# 今承达合同管理 CLI

来源目录：`泛微E10今承达合同管理`（源 Skill `weaver-e10-jinchengda`）。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli contract` 命令，供 AI Agent 通过结构化 JSON 调用。

源码位于 `src/shortcuts/contract`。命令注册、operation manifest 和业务执行逻辑分离；具体执行逻辑在 `src/shortcuts/contract/operations` 中按 operation class 维护。

面向 Agent 的说明位于 `skills/weaver-e10-jinchengda`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-work-cli-jinchengda/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。

## 公共前置

先通过 E10 鉴权模块登录，并用 CLI 判断登录态：

```text
weaver-work-cli auth login --base-url "https://weapp.xxx.cn"
weaver-work-cli auth status --no-check
```

每个合同业务请求由 CLI 托管：

1. 读取当前 `weaver-work-cli auth` Profile 的 E10 会话。
2. 请求只使用相对 `/api/...` 路径，完整地址和认证由会话提供。
3. `userid` / `userId`（催办接口）由 CLI 从会话注入。

Agent 不得在业务 JSON 中传 `userid`、`userId`、Cookie、ETEAMSID、Token 或内部控制字段（`sedit`、`dubboFlag`、`dubboToken`、`skipFlag`）。

## Agent 入口

优先使用 `contract run <operation>`：

Windows PowerShell：

```powershell
weaver-work-cli contract schema
weaver-work-cli --json contract run contract.type.tree
weaver-work-cli --json contract run contract.workflow.query --input-json '{"workflowName":"销售合同起草","status":"1"}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli contract schema
weaver-work-cli --json contract run contract.type.tree
weaver-work-cli --json contract run contract.workflow.query --input-json '{"workflowName":"销售合同起草","status":"1"}'
```

## operation 分组

| 分组 | operation |
|---|---|
| 合同类型与模板 | `contract.type.tree`、`contract.template.tree`、`contract.template.list`、`contract.template.detail` |
| 条款查询 | `contract.clause.tree`、`contract.clause.list`、`contract.clause.group.list`、`contract.clause.search`、`contract.clause.tags` |
| 条款引用 | `contract.clause.reference.get`、`contract.clause.reference.save.prepare/apply` |
| 签约主体 | `contract.subject.app`、`contract.subject.form`、`contract.subject.fields`、`contract.subject.options`、`contract.subject.query`、`contract.subject.create.prepare/apply` |
| 流程解析 | `contract.workflow.query`、`contract.workflow.list`、`contract.workflow.form.info`（三段式：loadBaseParam → loadFrameParam → getFormLayout）、`contract.workflow.field.options` |
| 流程写操作 | `contract.request.create.prepare/apply`、`contract.request.save.prepare/apply`、`contract.request.submit.prepare/apply`、`contract.request.supervise.prepare/apply` |
| 流程状态 | `contract.request.status`、`contract.request.log` |

完整字段与风险等级以 `weaver-work-cli contract schema` 为准。

## 业务成功码适配

源资料中各接口的成功码字段并不统一，适配层按路径分组判定，不凭 HTTP 200 判定业务成功：

| 路径 | 成功判定 |
|---|---|
| `/api/ebd/**` | 顶层 `code = 0` |
| `/api/ebuilder/form/obj/getObjsByTag`、`/api/bs/ebuilder/app/tags/getAppIds`、`/api/ebuilder/common/ds/fields`、`/api/ebuilder/common/ds/options` | 顶层 `code = 200` 且 `status` 不为 false |
| `/api/ebuilder/form/dataset/v2/**` | `message.code = "0"` |
| `/api/workflow/**` | `message.errcode = "0"`（`getFieldOption` 上游示例为 `200`，同样视为成功） |

## 环境与 ID 约束

- `appId`、`objId`、`formId`、`workflowId`、`nodeId`、人员/选项/业务数据 ID 均视为环境相关字符串，必须运行时解析。
- 未找到就停止并提示用户配置 Tag 或确认名称，不使用标准环境 ID 兜底。
- 同名多结果时展示候选请用户选择，不默认取第一条。

## 写操作确认链

- 写操作一律 `prepare -> apply`：`prepare` 返回脱敏 `preview` 与 `continuation`（有效期 10 分钟），`apply` 必须带 `continuation` 与 `confirm: true`。
- 提交审批与催办需要与“创建并保存”分开的第二次确认。
- 提交后回读 `contract.request.status`，`flowStatus.code` 为 1（审批中）或 3（已归档）才算生效。
- 写请求超时或断线返回 `partial/write_uncertain`（退出码 11），禁止自动重放。
- `submitRequest` 返回 `1200306` 时解析缺失字段补全后重试（最多 3 轮）；返回 `1200301` 时停止并诊断会话状态。

## 暂未实现

企业资信查询、企业变更、企业监控和撤回/退回流程在源资料中缺少接口路径、参数或确认契约，已列入 `withheldOperations`，详见 `skills/weaver-work-cli-jinchengda/references/contract-disabled-capabilities.md`。

## 源资料指纹

`skills/weaver-work-cli-jinchengda/references/source-manifest.json` 记录了源资料的 `sha256` 与聚合指纹，用于后续检测源资料更新；更新检测确认前不要覆盖已生成的 CLI 与 Skill。