# 九氚汇营销管理 CLI

来源目录：`weaver-e10-jiuchuanhui`，内容版本 `1.1.1`。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli jiuchuanhui` 命令，供 AI Agent 通过结构化 JSON 调用。

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

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

## 公共前置

先通过 E10 鉴权模块登录：

```text
weaver-work-cli auth login --base-url "https://jchdemo.e-cology.cn" --agent_type "<当前智能体名称>"
weaver-work-cli auth status --no-check
```

每个九氚汇业务请求由 CLI 托管：

1. 读取当前 `weaver-work-cli auth` Profile 的 E10 会话。
2. 根据 operation 的 body mode 组装请求体（ESB 动作流 / eBuilder datajson）。
3. 自动携带 Cookie、ETEAMSID、User-Agent，业务输入中禁止再传这些 key。

Agent 不得在业务 JSON 中传 Cookie、ETEAMSID、Token 或内部控制字段；CLI 会拒绝这些 key。

## Agent 入口

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

Windows PowerShell：

```powershell
weaver-work-cli jiuchuanhui schema
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli jiuchuanhui schema
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10}'
```

成功和失败都使用 JSON envelope。成功写 stdout；失败写 stderr，并设置非 0 退出码。

当前输出层是完整 JSON 直接写 stdout，不提供飞书 CLI 的 `--jq`、`--format table/ndjson` 或通用 `--page-all`。Agent 使用时应默认小页读取和摘要渲染：列表先 `pageNo=1`、`pageSize=10`，按 `pageNo` 继续；回复只展示关键字段和数量，超长详情 JSON 落本地文件后给路径。

## Operation 目录

| Operation 组 | 风险 | 固定规则 |
| --- | --- | --- |
| `jiuchuanhui.app.discovery` / `form.discovery` / `ds.fields` / `field.options` / `rest.cfg.detail` / `config.id.by.pk` / `file.preview` / `get-rest-cfg-detail` | 只读 | 发现与配置；`file.preview` 需先确认文件内容 |
| `jiuchuanhui.customer.create.prepare/apply` | 高风险写 | 创建前必须查重；`detail2` 同步创建联系人 |
| `jiuchuanhui.customer.get` / `search` / `type/status/industry.search` / `open-sea.search` / `duplicate.check` | 只读 | 搜索必须显式传 `mine`/`all`/`customerSea`；`count:true` 并行取总数 |
| `jiuchuanhui.customer.update/transfer/open-sea.release/open-sea.claim/contact-record.create/contact-record.batch` 的 prepare/apply | 高风险写 | 转移/释放/领取需确认唯一性与影响 |
| `jiuchuanhui.contact.create/update` prepare/apply | 高风险写 | 联系人随客户创建时勿重复调用 |
| `jiuchuanhui.contact.get` / `by-entity.search` | 只读 | 只给姓名先查候选再让用户选择 |
| `jiuchuanhui.sale.create/update` prepare/apply | 高风险写 | 按配置 `data_key` 组装 |
| `jiuchuanhui.sale.get` / `search` / `stage.search` / `process.search` / `lose-reason.search` / `rival.search` | 只读 | 阶段/原因选项供写操作取 ID |
| `jiuchuanhui.sale.win/lose/invalid/pause/restart/manager-change/link-contacts/contact-record.create` 的 prepare/apply | 高风险写 | 赢单/输单/无效不可逆；输单先取原因；转移与负责人变更共用 |
| `jiuchuanhui.clue.create/update/status-change/to-customer/contact-record.create` 的 prepare/apply | 高风险写 | 状态变更是覆盖型；转新客户走 `customer.create` 传 `source_module_id` |
| `jiuchuanhui.clue.get` / `search` / `pool.search` | 只读 | 线索池列表 |
| `jiuchuanhui.contact-plan.create/complete` prepare/apply | 高风险写 | `type` 与关联字段联动 |
| `jiuchuanhui.entity.contact-records.list` / `contact-records.by-person-time.list` | 只读 | 联系记录查询 |
| `jiuchuanhui.entity.id.by-name` / `user.id.by-name` / `user.current-profile` / `entity.permission.judge` / `company.business-profile.query` / `field.info.by-ids` / `browser-option.search` | 只读 | 通用辅助；行政区划也走 `entity.id.by-name` |

缓存初始化（`cache.init`）与商机阶段推进（`stage-advance`）不暴露为 CLI operation：前者是 Agent 侧本地状态维护，后者依赖缓存阶段配置做映射，属于 Skill 编排层职责。

## 常用命令

Windows PowerShell：

```powershell
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.search --input-json '{"pageNo":1,"pageSize":10,"count":true}'
weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"userName":"魏思雨"}}'
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"customerName":"示例科技有限公司"}}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.search --input-json '{"pageNo":1,"pageSize":10,"count":true}'
weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"userName":"魏思雨"}}'
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"customerName":"示例科技有限公司"}}'
```

写操作必须先 prepare，再 apply：

Windows PowerShell：

```powershell
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input .\customer-create.json

weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'

weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.prepare --input-json '{"saleId":"200001"}'

weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input ./customer-create.json

weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'

weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.prepare --input-json '{"saleId":"200001"}'

weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
```

## 写操作确认链

- `prepare` 只预览和生成 continuation（HMAC 签名，绑定当前登录上下文与参数）。
- 向用户摘要目标、差异、风险和 continuation 绑定含义。
- 用户明确确认后才调用 `apply`（`confirm:true` + 有效 continuation）。
- `apply` 不可盲目重试；遇到 `partial/write_uncertain` 先停止，再做一次只读回查（如 `customer.get`/`sale.get`/`clue.get`）。

写操作出现网络中断、部分成功、缺少回执 ID 或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。

## 业务规则摘要

- 选项字段（Select/RadioBox/CheckBox）必须先取选项 ID 再传值；`RelateBrowser` 字段通过 `browser-option.search` 查对应类型选项。
- 行政区划传逗号分隔全路径 ID（`country,province,city,district`），传细粒度自动填充粗粒度。
- 客户搜索必须显式传 `mine`/`all`/`customerSea` 三个 key（一个 `""` 其余 `-1`），没有 `scope` 快捷参数。
- 列表、卡片及详情中的关联事项名称渲染为可点击链接 `https://{baseUrl}/sp/ebdfpage/card/0/{objId}/{dataId}`。
- 新建客户前先查重；客户在公海时提醒可领取。
- 线索转新客户走客户创建且传 `source_module_id=<clueId>`，成功后不再额外修改线索。