weaver-work-cli 0.1.1 → 0.1.4

package/skills/weaver-e10-jiuchuanhui/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: weaver-e10-jiuchuanhui
+display_name: 泛微九氚汇营销管理
+display_name_en: Weaver Jiuchuanhui Marketing Management
+description: "泛微 E10 九氚汇营销管理：客户、联系人、商机、线索的创建、查询、搜索、修改、转移、公海、联系计划、联系记录、商机推进、线索转客户等 CRM 操作。用户表达营销/CRM 相关业务意图时使用。"
+description_zh: "泛微 E10 九氚汇营销管理。覆盖客户、联系人、商机、线索全生命周期：创建、查询、搜索、修改、转移、公海领取/释放、查重、联系计划、联系记录、商机赢单/输单/无效/暂停/重启、线索转客户，并通过 prepare/apply 确认链处理全部高风险写操作。"
+description_en: "Full-lifecycle CRM operations for customers, contacts, opportunities and clues in Weaver E10 Jiuchuanhui marketing management, including confirmed writes for create, update, transfer, pool claim/release, stage changes and clue-to-customer conversion."
+version: 1.0.0
+author: 泛微网络科技股份有限公司
+agent_created: true
+requires:
+  bins: ["weaver-work-cli"]
+cliHelp: "weaver-work-cli jiuchuanhui --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --skills-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
+认证和登录态只能按共享规则通过 `weaver-work-cli auth ...` 命令判断；CLI 会自动携带完整 Cookie、`eteamsid` 与 `User-Agent: AgentType=<agentType>,IsAgent=true`，业务调用方不得覆盖这三条 header，也不得在业务 JSON 中传入这些 key。禁止直接读取、列出、打印或解析用户主目录下的 `.e10-cli`、auth、config 或 Keychain 数据。
+所有命令通过 `weaver-work-cli --json jiuchuanhui run <operation>` 执行：简单 JSON 传 `--input-json '<json>'`，复杂或多行 JSON 先写入 UTF-8 文件再传 `--input <path>`，只有确认当前 shell 能稳定传管道时才使用 `--input -`。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，`weaver-work-cli jiuchuanhui schema` 是 operation、字段和风险等级的合约来源。
+命令示例、提示词和临时说明必须同时兼容 Windows 和 macOS/Linux；涉及 JSON 输入、用户目录、路径分隔符、Python 启动器、文件删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。Windows/PowerShell 下不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。
+涉及附件、图片、本地文件、远程 URL 文件或文件解析的操作，执行前必须提醒用户：文件内容可能被上传到 E10 九氚汇、文件服务或解析服务，并可能进入当前大模型上下文用于理解和处理；必须等待用户明确确认后才继续。
+
+## 启动与缓存（MUST）
+
+**首次使用、缓存缺失、用户要求刷新、或需要版本/配置/选项/objId 时，必须先读取 [`references/cache.md`](references/cache.md) 并按其中规则处理，再继续业务调用。**
+
+- 优先使用 `~/.weaver-e10-jiuchuanhui/{tenantKey}/{userId}/` 下的缓存（主文件 `weaver-e10-jiuchuanhui.json` + `config/{pk}.json`）。
+- 缓存缺失或用户要求初始化/刷新时，调用 CLI operation `weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init`（7 步：应用发现 → 13 objId → 版本校验 >= 1.5.11 → cfgId → 配置详情+字段 data_key → ebuilder 关联数据 → 字段选项 → 搜索参数 → 行政区划），支持 `dryRun`/`verbose`；也可在仓库根运行 `node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs`（薄包装，转发同一 operation）。
+- 创建/更新接口读 `config/{pk}.json.detail.mainFields`（`data_key`）；搜索接口读 `searchParams`；选项字段优先读字段 `optionList`。缓存已覆盖的配置直接读缓存，不重复走动态配置链路。
+- 缓存初始化与刷新**已暴露为 CLI operation `jiuchuanhui.cache.init`**（risk: local-file-write，写本地缓存文件，无需 prepare/apply 确认链），Agent 直接调用即可。
+
+## 参数与字段处理（MUST）
+
+- **只使用用户明确提供或已确认的字段值**：录入或修改数据时，只使用用户明确提供或已确认的字段值；必填字段缺失时向用户追问，不编造默认值或占位值。
+- **写操作必须用户确认**：写操作（新建、修改、删除、转移、释放、领取、状态变更、完成计划等）一律走 `prepare` → 用户确认 → `apply`；查询类操作可直接执行，无需确认。
+- **不擅自追加动作**：只完成用户明确要求的业务动作，不自作主张追加查询、修改、创建、验证、推荐或其他操作；只有对应 reference 明确要求的前置步骤才可以执行。
+- **参数缺失/不支持立即停止**：操作类请求如果用户提供的参数缺失、不支持、无法映射或不符合接口文档，直接说明具体问题并停止；禁止猜测参数、替换参数或自动重试。
+- **选项字段传 ID 不传中文**：`Select`/`RadioBox`/`CheckBox` 优先使用字段 `optionList` 的选项 `value`；`Ebuilder`/关联字段通过对应搜索或查询接口取数据 ID；`RelateBrowser` 使用自定义浏览字段选项查询；均传 ID，不传中文名称。
+- **行政区划全路径 ID**：`country`/`province`/`city`/`district` 传逗号分隔的全路径 ID（格式 `country,province,city,district`）；传细粒度自动填充粗粒度。
+- **日期与金额**：日期类模糊表达（今天、本周、本月等）转换为明确起止范围；金额统一转换为数字，单位为元。
+
+## 路由优先级（先判断是不是九氚汇 CRM，再选 operation）
+
+九氚汇 CRM 不是通用 E10 对象。**只要用户的核心对象是九氚汇的客户、联系人、商机、线索、联系计划、联系记录、公海客户或相关辅助查询，就优先使用 `weaver-e10-jiuchuanhui`。**
+
+### 明确归 `weaver-e10-jiuchuanhui` 的高优先级语义
+
+出现以下任一语义时，优先走本 Skill：
+
+- 客户 / 新建客户 / 客户详情 / 搜索客户 / 修改客户 / 转移客户 / 客户查重 / 客户公海
+- 联系人 / 新建联系人 / 联系人详情 / 修改联系人 / 按客户或商机查联系人
+- 商机 / 新建商机 / 商机详情 / 搜索商机 / 修改商机 / 商机阶段 / 商机赢单 / 输单 / 无效 / 暂停 / 重启 / 商机转移 / 关联联系人
+- 线索 / 新建线索 / 线索详情 / 搜索线索 / 修改线索 / 线索状态变更 / 线索转客户 / 线索池
+- 联系计划 / 完成联系计划 / 联系记录 / 跟进记录 / 批量联系记录
+- 公海 / 领取公海客户 / 释放客户到公海 / 公海搜索
+- 客户经理 / 按姓名查人员 / 按名称查事项 ID / 事项权限校验 / 企业工商照面 / 字段选项 / 自定义浏览字段
+- `customerId` / `saleId` / `clueId` / `contactId` / `planId` / `managerid` 等九氚汇业务 ID
+
+**判定规则：** 只要最终动作是对九氚汇客户/联系人/商机/线索做查询、搜索、创建、修改、转移、公海、联系计划、联系记录、状态推进或辅助解析，就归 `weaver-e10-jiuchuanhui`。只有当用户处理的是非营销类 E10 业务、通用工作流或尚未封装的九氚汇能力时，才不使用本 Skill。
+
+## 选哪个命令
+| 想做什么 | 命令 | 按需读取 reference |
+|---|---|---|
+| 查看可用 operation、字段和风险等级 | `jiuchuanhui schema` | [`jiuchuanhui-entry.md`](references/jiuchuanhui-entry.md) |
+| 初始化/刷新表单配置缓存 | `jiuchuanhui run jiuchuanhui.cache.init`（risk: local-file-write）；或仓库根运行 `node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs` | [`cache.md`](references/cache.md) |
+| 客户创建/详情/搜索/修改/转移/公海/查重/联系记录 | `jiuchuanhui run jiuchuanhui.customer.*` | [`customer.md`](references/customer.md) |
+| 联系人创建/详情/修改/按事项查询 | `jiuchuanhui run jiuchuanhui.contact.*` | [`contact.md`](references/contact.md) |
+| 商机创建/详情/搜索/修改/阶段/赢单/输单/无效/暂停/重启/转移/关联/联系记录 | `jiuchuanhui run jiuchuanhui.sale.*` | [`sale.md`](references/sale.md) |
+| 线索创建/详情/搜索/修改/状态变更/转客户/线索池/跟进记录 | `jiuchuanhui run jiuchuanhui.clue.*` | [`clue.md`](references/clue.md) |
+| 创建/完成联系计划 | `jiuchuanhui run jiuchuanhui.contact-plan.*` | [`contact-plan.md`](references/contact-plan.md) |
+| 按事项或按人员+时间范围查询联系记录 | `jiuchuanhui run jiuchuanhui.entity.contact-records.list` / `jiuchuanhui.contact-records.by-person-time.list` | [`contact-records.md`](references/contact-records.md) |
+| 应用/表单/字段/选项/接口配置/文件预览等发现与配置 | `jiuchuanhui run jiuchuanhui.{app,form,ds,field,rest,config,file}.*` | [`discovery-config.md`](references/discovery-config.md)、[`cache.md`](references/cache.md) |
+| 按名称查事项/人员 ID、权限、工商照面、字段信息、自定义浏览选项 | `jiuchuanhui run jiuchuanhui.{entity,user,company,field,browser-option}.*` | [`general-helpers.md`](references/general-helpers.md) |
+| 商机阶段推进组合、其它 schema 未列出的能力 | 无可用命令 | [`disabled-capabilities.md`](references/disabled-capabilities.md) |
+
+处理链：
+
+- 客户：搜索/查重先于创建。新建客户前先 `jiuchuanhui.customer.duplicate.check`；有疑似重复时表格展示并让用户确认；若客户在公海提醒可领取。确认继续后才 `customer.create.prepare` -> 用户确认 -> `customer.create.apply`。
+- 客户修改/转移/释放/领取：先 `customer.search`/`customer.get` 确认唯一 -> `customer.update.prepare`（或 `transfer`/`open-sea.release`/`open-sea.claim`）-> 用户确认 -> `.apply`。
+- 联系人：只给姓名未指明所属事项时，先 `contact.by-entity.search` 或搜索候选并让用户选择；创建/修改走 `contact.create/update.prepare -> apply`。联系人随客户创建（`detail2`）时不要重复调用 `contact.create`。
+- 商机：赢单/输单/无效/暂停/重启/转移/关联联系人/联系记录，全部先确认商机唯一，再 `sale.*.prepare` -> 用户确认影响与不可逆性 -> `sale.*.apply`。输单必须先确定输单原因，暂停必须有暂停原因。
+- 线索：状态变更覆盖放弃/分配/转移/有效/无效，先确认线索唯一、目标状态/人员明确 -> `clue.status-change.prepare` -> 用户确认 -> `.apply`。线索转已有客户走 `clue.to-customer`；转新客户走 `customer.create` 且传 `source_module_id=<clueId>`，成功后不要再额外修改线索。
+- 联系计划：按客户/商机/线索关联时必须先确定唯一关联事项和 `type`，用户提到联系人时先用 `contact.by-entity.search` 查询候选 -> `contact-plan.create.prepare -> apply`；完成计划走 `contact-plan.complete.prepare -> apply`。
+- 通用辅助：先 `user.id.by-name` / `entity.id.by-name` 解析 ID，再进入业务调用；`user.current-profile` 每轮会话优先取一次并复用。
+
+## 执行原则（减少误路由、误重试和无效消耗）
+
+### 1) 先拿最小必要信息，再执行
+
+- 只是搜索时，优先直接用 `customer.search`/`sale.search`/`clue.search`
+- 列表默认先取小页，优先 `pageNo=1`、`pageSize=10`；用户没有要求全量时不要自动翻页
+- 客户搜索必须显式传 `mine`/`all`/`customerSea` 三个 key（其中一个为 `""`，其余两个为 `-1`），默认 `mine=""&all=-1&customerSea=-1`（我的客户）；本接口没有 `scope` 快捷参数
+- 用户已经给出 `customerId`/`saleId`/`clueId` 时，不要先查列表再过滤，直接用对应 get 或 prepare
+- 只有需要完整详情、可编辑状态或附件归属时才补 get
+
+### 1.5) 大结果只摘要给用户
+
+- 当前 CLI 会把完整 JSON envelope 写 stdout；Agent 回复时不要原样贴完整 JSON
+- 列表最多先展示最相关的前 10 条，包含 ID、名称、负责人、状态/阶段、金额、最近跟进时间和可点击链接
+- 需要全量统计时，按 `pageNo` 分页读取并累计必要字段；说明已读取页数、命中数和是否还有更多
+- 详情或调试用完整响应过长时，优先落本地文件并向用户提供摘要和文件路径
+- 列表、卡片及详情中的关联事项名称必须渲染为可点击链接 `https://{baseUrl}/sp/ebdfpage/card/0/{objId}/{dataId}`；`objId` 优先从缓存 `discovery["objId:{tag}"]` 获取
+- 返回类型为对象数组的字段必须展示全部对象及其完整有效值，不得只展示第一项或摘要；数组为空时按空值处理
+-客户列表默认展示客户名称、负责人、客户类型/状态、行业、最近跟进、创建时间；商机列表展示商机名称、客户、负责人、阶段、金额、预计成交/最近跟进；线索列表展示线索名称、客户/公司、处理人、状态、来源、最近跟进/创建时间。缺失字段用 `-`
+### 2) 已知对象时直达动作
+
+- 已拿到业务 ID、人员 ID、选项 ID 或完整 `form` 时，优先调用对应 operation
+- 同一轮里已有足够的新鲜查询结果时，不要重复查询同一事项
+- 不要默认走 `search -> get -> prepare -> apply` 全链路；对象已明确时应压缩步骤
+
+### 3) 错误语义驱动，而不是盲目重试
+
+- 失败后先看进程退出码、`error.type`、`error.subtype` 和 `error.message`
+- **除非错误明确提示可恢复或需要补充参数，否则不要重复刷同一个 operation**
+- 写请求已经发出后，遇到结果不确定必须停止；不要把 `.apply` 当成可重试读操作
+- **错误为 `authentication`（未登录，如 `E10 auth not found`）或 `session_expired`（登录态失效）时：立即停止当前操作，不要用示例占位域名或自行猜域名登录，也不要盲目重试**。先读取共享规则 `../weaver-e10-shared/references/e10-auth-and-session.md`，按其中流程用宿主提问/弹框让用户输入 E10 登录域名或选择已有 profile，完成登录后再继续原操作
+
+### 4) 文件处理确认
+
+- 执行文件预览（`file.preview`）或任何会读取本地文件、上传远程 URL 文件、解析图片/PDF/XML 的步骤前，必须先提醒用户文件内容可能进入大模型上下文，也可能发送到 E10 九氚汇或文件解析服务
+- 用户未明确确认前，不要运行文件预览或解析命令
+
+## 写操作失败处理：`partial/write_uncertain` 决策树
+
+当创建、修改、转移、释放、领取、状态变更、赢单/输单等写操作返回 `partial/write_uncertain`，或提示网络中断、部分成功、回查失败、回查字段不一致时，按下面规则处理：
+
+1. **先停止盲目重试**，不要连续重复提交相同 `.apply`
+2. 优先从以下角度解释：
+   - 写请求可能已经到达服务端，但连接在结果确认前中断
+   - 服务端可能只处理了部分事项（例如批量联系记录）
+   - 写接口已返回成功，但详情回查失败或与预期不一致
+   - continuation、目标事项或登录上下文可能已经变化
+3. 如需确认，只补 **一次** 只读查询（例如 `customer.get`/`sale.get`/`clue.get` 或列表查询），不要陷入 query/write 循环
+4. 最终给用户明确结论、已知 `status`/`resultCode`、成功/失败项和下一步人工确认建议，而不是继续无意义重试
+
+**特别注意：** 对转移、释放公海、赢单/输单/无效、状态变更场景更要严格执行上述规则；这些场景最容易因重复提交造成误转、误释放或覆盖用户刚确认的状态。
+
+**搜索约束：** 查询/搜索无结果时，直接原样说明查询条件并告知无结果，**不得修改条件（扩大范围/降低阈值/去除非核心条件）重试**——参数不支持的错误应反馈给用户后停止，而不是悄悄调整客户本意。
+
+## 快速命令示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli jiuchuanhui schema
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"name":"示例科技有限公司","simpleName":"示例科技"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input-json '{"form":{"mainTable":{"manager":"USER_ID","customer_name":"示例科技有限公司"}}}'
+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 '{"mainTable":{"saleId":"200001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"employeeName":"魏思雨"}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli jiuchuanhui schema
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"name":"示例科技有限公司","simpleName":"示例科技"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input-json '{"form":{"mainTable":{"manager":"USER_ID","customer_name":"示例科技有限公司"}}}'
+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 '{"mainTable":{"saleId":"200001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"employeeName":"魏思雨"}}'
+```
+
+## 不在本 skill 范围
+
+- 禁止加载原始 `weaver-e10-jiuchuanhui` 源 Skill 代替 CLI。
+- 禁止 curl、fetch、浏览器自动化或直接访问 E10 原始接口路径。
+- 禁止读取或复制 CLI runtime 内部 Token、Cookie、ETEAMSID。
+- 禁止读取、列出、打印或解析用户主目录下的 `.e10-cli`、auth、config 或 Keychain 数据。
+- `jiuchuanhui.sale.stage-advance` 未暴露为 CLI operation：商机阶段推进依赖缓存中的阶段配置做映射与前置校验，属于 Skill 编排层职责，CLI 的 `sale.update` 与 `sale.stage.search` 已覆盖基础能力。
+- 非九氚汇营销类 E10 能力、通用流程编排、非 CRM 表单/审批/组织等业务不由本 Skill 承载。

package/skills/weaver-e10-jiuchuanhui/product.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "product": "weaver-work-cli",
+  "productVersion": "0.1.2",
+  "packageName": "weaver-work-cli",
+  "command": "weaver-work-cli",
+  "nodeEngine": ">=18"
+}

package/skills/weaver-e10-jiuchuanhui/references/cache.md

@@ -0,0 +1,110 @@
+# 缓存说明（cache）
+
+缓存保存应用发现、接口配置、字段选项、关联数据和行政区划，按租户和人员隔离。缓存无 TTL：文件存在即命中，刷新时覆盖写入。
+
+## 何时使用
+
+首次使用、缓存缺失、用户要求刷新或重新加载、需要版本/配置/选项/objId 时，先读本文件，再按需运行初始化脚本。
+
+## 文件位置
+
+| 文件 | 内容 |
+|---|---|
+| `~/.weaver-e10-jiuchuanhui/{tenantKey}/{userId}/weaver-e10-jiuchuanhui.json` | 主缓存：`discovery`、`ebuilder`、`options`、`region` |
+| `~/.weaver-e10-jiuchuanhui/{tenantKey}/{userId}/config/{pk}.json` | 单接口配置：创建/更新类 `{cfgId,objId,detail}`，搜索类 `{cfgId,objId,searchParams}` |
+
+`tenantKey`、`userId`、`baseUrl` 和认证头均由 `weaver-work-cli auth` 提供。缓存文件是 Agent 本地状态，不随 Skill 打包、不入库。
+
+## 主缓存结构
+
+```json
+{
+  "discovery": {},
+  "ebuilder": {},
+  "options": {},
+  "region": {}
+}
+```
+
+| 命名空间 | 内容 | 典型 key |
+|---|---|---|
+| `discovery` | 应用、表单对象、版本校验 | `appId:jch-crm-project`、`objId:uf_jch_customer`、`spVersion:jch-crm-project` |
+| `ebuilder` | Ebuilder 关联数据 | `customer_type`、`customer_status`、`sale_stage` |
+| `options` | Select/RadioBox/CheckBox 选项 | `options:{fieldId}:*:1` |
+| `region` | 行政区划全路径 ID | `administrativeDivision:{name}` |
+
+接口配置的 `cfgId` 存在对应 `config/{pk}.json` 中，业务按 `pk` 读取；主缓存不保存单独的 cfgId 索引。
+
+## 初始化常量
+
+| 常量 | 值 |
+|---|---|
+| 应用标签 | `jch-crm-project` |
+| 模块表单标签 | `uf_jch_customer`、`uf_jch_sale`、`uf_jch_clue`、`uf_jch_contact`、`uf_jch_customer_open_sea`、`uf_jch_remind`、`uf_jch_rival`、`uf_jch_sale_process`、`uf_jch_sale_stage`、`uf_jch_clue_pool`、`uf_jch_lose_reason`、`uf_jch_customer_cmt`、`uf_jch_sale_cmt` |
+| 创建类 pk | `customer_create_api`、`sale_create_api`、`ebclue_ai_create_api`、`contact_create_api`、`ebcontact_plan_create_api` |
+| 搜索类 pk | `ebcustomer_search_api`、`ebsale_search_api`、`ebclue_ai_search_api` |
+| 更新类 pk | `customer_update_api`、`sale_update_api`、`ebclue_ai_update_api`、`contact_update_api` |
+| `interface_pk` 转 `cfgId` | `4F6E1A9702864666803CCA6B77B86227` |
+| 字段 ID 转 `data_key` | `10351A4DC8D4454A9F1957FBE647CD9F` |
+| 行政区划查询 | `7EC1639D5AC24B4DBCEE8D2CB85D4025` |
+| 行政区划预取城市 | 成都市 |
+| Ebuilder 分页大小 | `pageSize=500` |
+| 选项层级 | `optionLevel=1` |
+| 版本基线 | `>= 1.5.11` |
+
+## 初始化/刷新
+
+**调用 CLI operation `jiuchuanhui.cache.init` 执行完整初始化**（`weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init`），或在仓库根运行 `node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs`（薄包装，转发同一 operation）。依赖有效 E10 登录态。支持 `dryRun`（只拉取不写入）/ `verbose`。用户要求初始化、刷新或重新加载缓存时，覆盖旧缓存。返回摘要含各命名空间条目数、objId/cfgId 计数、版本校验结果（`spVersion`，version.passed=false 时应停止业务调用）。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init --input-json '{}'            # 完整初始化
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init --input-json '{"dryRun":true}'  # 只拉取不写入
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init --input-json '{"verbose":true}' # 打印步骤明细
+node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs            # 薄包装（等价完整初始化）
+node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs --dry-run  # 只拉取不写入
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init --input-json '{}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init --input-json '{"dryRun":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.cache.init --input-json '{"verbose":true}'
+node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs
+node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs --dry-run
+```
+
+初始化流程（operation 内 7 步，复用 CLI 的 E10 认证链直连接口）：
+
+1. **发现接口**：`jiuchuanhui.app.discovery`（`tag=jch-crm-project`）取 `data[0]` 为 `appId`；对 13 个模块表单标签调 `jiuchuanhui.form.discovery`，优先取 `formId` 非空且非 `"0"` 的记录 `id` 为 `objId`，否则回退 `data[0]`；读取 `spVersion`（`commitVersion`+`passed`），版本必须 `>= 1.5.11`，否则停止业务调用。
+2. **获取 cfgId**：对 12 个 pk 调 `jiuchuanhui.config.id.by.pk`（`mainTable.interface_pk`），取 `mainTable.cfgId`。**该接口走 ESB 动作流，必须 POST JSON body + `uniqueIndent=4F6E1A9702864666803CCA6B77B86227`**；若以 GET query 调用会返回 HTTP 405。
+3. **创建/更新接口配置**：对 5 个创建类 pk 和 4 个更新类 pk 调 `jiuchuanhui.rest.cfg.detail`（`apid={appId}&id={cfgId}`）；仅保留 `isInput=1` 的 `mainFields` 和 `detailFields[].fields`，空明细组丢弃；收集 `fieldid` 调 `jiuchuanhui.field.info.by-ids` 合并 `data_key`、`title`、`component_type`；注入对应表单 `objId`；精简存储（`detail` 顶层仅保留 `id`、`interfacePk`、`interfaceName`、`datasNumber`、`datasSize`、`mainFields`、`detailFields`、`interfaceType`、`relevanceForm`；字段元素仅保留 `fieldid`、`isRequired`、`isInput`、`data_key`、`title`、`component_type`）。写入 `config/{pk}.json`。
+4. **Ebuilder 关联数据**：对 8 类选项（客户公海、商机阶段、销售过程、线索池、输单原因、客户行业、客户类型、客户状态）调对应搜索 operation（`customer.open-sea.search` / `sale.stage.search` / `sale.process.search` / `clue.pool.search` / `sale.lose-reason.search` / `customer.industry.search` / `customer.type.search` / `customer.status.search`），归一化为 `{id,name}` 写入 `ebuilder`；商机阶段额外带 `sale_process`。
+5. **字段选项**：对 `config/{pk}.json` 中 `component_type` 为 `Select`/`RadioBox`/`CheckBox` 的字段调 `jiuchuanhui.field.options`（`fieldName`+`objId`+`groupId`），写入 `options.options:{fieldId}:*:1 = {lable,lableTitle,value}`，并按 `fieldid` 把 `value` 复制到相关 `config/{pk}.json` 字段的 `optionList`。失败不阻塞：保留旧缓存 `options`，业务侧可读字段 `optionList` 或主缓存 `options` 兜底。
+6. **搜索参数**：对 3 个搜索类 pk 调 `jiuchuanhui.rest.cfg.detail`，解析 `conditions.datas[]` 的 `{param}` 提取 URL 参数 key，组装 `{key,text,fieldType,compType,func,fieldid}` 写入 `config/{pk}.json.searchParams`。
+7. **行政区划**：预取 22 个常用城市（北京市、上海市、天津市、重庆市、成都市、广州市、深圳市、东莞市、杭州市、南京市、苏州市、武汉市、长沙市、西安市、郑州市、济南市、青岛市、厦门市、福州市、合肥市、沈阳市、大连市），通过 ESB 动作流（`uniqueIndent=7EC1639D5AC24B4DBCEE8D2CB85D4025`、`moduleType=administrativeDivision`、`name=城市名`、`fromType=agentSkill`）查询，`resultCode===200` 才写入 `region.administrativeDivision:{name}`；单城失败跳过，保留旧缓存 `region`。
+
+## 读取规则
+
+- 创建/更新接口直接读 `config/{pk}.json.detail`，用字段 `data_key` 组装 `mainTable` 和明细数组。
+- 搜索接口直接读 `config/{pk}.json.searchParams`，不得使用未定义的搜索 key。
+- Select/RadioBox/CheckBox 优先读字段 `optionList`（缺失时读主缓存 `options.options:{fieldId}:*:1`）。
+- Ebuilder 关联字段读 `ebuilder` 命名空间。
+- 行政区划读 `region`；运行时查询到的新行政区划可覆盖写入。
+- 缓存为空、主文件或接口级文件缺失时，执行初始化或单项刷新，再继续业务调用。
+
+## 刷新规则
+
+| 方式 | 场景 | 处理 |
+|---|---|---|
+| 全量刷新 | 用户要求初始化、刷新、重新加载缓存 | 重新调用 `jiuchuanhui.cache.init`（或 `node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs`），覆盖主缓存和接口级配置 |
+| 单项刷新 | 某接口、字段、选项或行政区划缺失/变更 | 只重新查询对应 CLI operation 并覆盖对应 key 或 `config/{pk}.json` |
+
+## 失败处理
+
+- 版本校验 `< 1.5.11`：停止业务调用并告知用户。
+- `jiuchuanhui.config.id.by.pk` 返回 HTTP 405：确认以 POST + JSON body 调用（EsbReadOperation），不要用 GET query 方式调用该 ESB 动作流。
+- `jiuchuanhui.field.options` 返回 HTTP 400：已知问题（GetQueryOperation 未注入 `sourceType=FORM` 时可能 400）；保留旧缓存 options，业务侧用字段 `optionList` / 主缓存 `options` 兜底。
+- 缓存缺失：先调用 `jiuchuanhui.cache.init` 完成初始化，再继续业务调用。

package/skills/weaver-e10-jiuchuanhui/references/clue.md

@@ -0,0 +1,61 @@
+# 线索管理（clue）
+
+## 何时使用
+
+用户表达线索相关意图：新建线索、线索详情、搜索线索、修改线索、线索状态变更（放弃/分配/转移/有效/无效）、新建线索跟进记录、线索转已有客户、线索池搜索。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.clue.create.prepare/apply` | 高风险写 | `form`: `{mainTable, detail1?, ...}` |
+| `jiuchuanhui.clue.get` | 只读 | `id` |
+| `jiuchuanhui.clue.search` | 只读 | 搜索条件走 query，`count:true` 并行取总数 |
+| `jiuchuanhui.clue.pool.search` | 只读 | 线索池列表 |
+| `jiuchuanhui.clue.update.prepare/apply` | 高风险写 | `form`：主表修改 |
+| `jiuchuanhui.clue.status-change.prepare/apply` | 高风险写 | `clueid`（注意小写）、`type`（必须传数字 1/2/3/4，不可中文）；`type=1`放弃时必填 `desc`，`type=2`分配/转移时必填 `newmanager`，`type=4`无效时必填 `desc`；`type=2` 靠线索有无负责人区分意图 |
+| `jiuchuanhui.clue.to-customer.prepare/apply` | 高风险写 | `clueId`、`customerId`（转已有客户） |
+| `jiuchuanhui.clue.contact-record.create.prepare/apply` | 高风险写 | `clueId`、`content`、`clueStatus_MappingId`（必填，驱动状态流转：`3`=跟进中、`4`=无效） |
+
+## 输入要点
+
+- 创建/修改前读缓存 `config/ebclue_ai_create_api.json`（或 `ebclue_ai_update_api.json`）的 `detail`，按 `data_key` 组装，`isRequired:"1"` 缺失时追问。
+- 状态变更 `type` **必须用数字 1/2/3/4**（不可中文，非缓存选项）：`1`=放弃（必填 `desc`）| `2`=分配或转移（必填 `newmanager`，有无负责人区分意图）| `3`=恢复有效 | `4`=无效（必填 `desc`）。先确认线索唯一、目标状态/人员明确，再 prepare -> 用户确认 -> apply。
+- 线索转客户：用户指定转已有客户 -> `clue.to-customer`；转新客户 -> 走 `customer.create` 且传 `source_module_id=<clueId>`，成功后不要额外修改线索。
+- 创建类型记录时根据联系记录内容自动判断线索状态（有效或无效）。
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.search --input-json '{"clue_name":"示例","pageNo":1,"pageSize":10,"count":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.get --input-json '{"id":"500001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.status-change.prepare --input-json '{"mainTable":{"clueid":"500001","type":"2","newmanager":"USER_ID"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.status-change.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.to-customer.prepare --input-json '{"mainTable":{"clueId":"500001","customerId":"100001"}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.search --input-json '{"clue_name":"示例","pageNo":1,"pageSize":10,"count":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.get --input-json '{"id":"500001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.status-change.prepare --input-json '{"mainTable":{"clueid":"500001","type":"2","newmanager":"USER_ID"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.status-change.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.clue.to-customer.prepare --input-json '{"mainTable":{"clueId":"500001","customerId":"100001"}}'
+```
+
+## 输出处理
+
+- 创建成功返回 `datajson.dataIds`；状态变更成功以 `resultCode===200` 为标志，不额外验证。
+- 线索名称渲染为可点击链接，`objId` 取缓存 `discovery["objId:uf_jch_clue"]`。
+
+## 注意
+
+- 线索状态变更覆盖放弃、分配、转移、有效、无效等动作；写入前必须让用户确认目标状态与人员。
+- 转新客户成功后不要再调用线索修改接口。
+
+## 失败处理
+
+- 参数缺失/不支持：说明具体问题并停止。
+- `partial/write_uncertain`：停止重试，补一次 `clue.get` 回查。

package/skills/weaver-e10-jiuchuanhui/references/contact-plan.md

@@ -0,0 +1,56 @@
+# 联系计划（contact-plan）
+
+## 何时使用
+
+用户表达联系计划相关意图：创建联系计划、完成联系计划。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.contact-plan.create.prepare/apply` | 高风险写 | `form`: `{mainTable, ...}`；`type` 必填且与关联字段一一对应（见下） |
+| `jiuchuanhui.contact-plan.complete.prepare/apply` | 高风险写 | `planId` |
+
+## 输入要点
+
+- **`type` 联动规则（必填，传数字 1/2/3）**：`type=1`（客户）→ 必填 `customer`（客户 ID）；`type=2`（商机）→ 必填 `sale_chance`（商机 ID）；`type=3`（线索）→ 必填 `clue`（线索 ID）。三选一、一 一对应，不可混搭。字段 key 是 `customer`/`sale_chance`/`clue`，不是 `customer_id`/`sale_id`/`clue_id`。
+- `status` 必填，默认"进行中"（ID=1）。
+- `remind_time`（联系时间）必填，格式 `yyyy-MM-dd HH:mm`；字段 key 是 `remind_time`（非 `plan_time`）。
+- `manager`（负责人）必填，默认当前操作人。
+- `visit_type`（联系类型）与 `type`（关联对象类型）**无关**——`type` 分模块，`visit_type` 分方式（上门/电话等），可独立选择。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+# 为客户创建联系计划 (type=1 → customer)
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.create.prepare --input-json '{"form":{"mainTable":{"type":"1","customer":"100001","remind_time":"2026-09-10 14:00"}}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.complete.prepare --input-json '{"mainTable":{"planId":"600001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.complete.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+# 为客户创建联系计划 (type=1 → customer)
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.create.prepare --input-json '{"form":{"mainTable":{"type":"1","customer":"100001","remind_time":"2026-09-10 14:00"}}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.complete.prepare --input-json '{"mainTable":{"planId":"600001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-plan.complete.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+## 输出处理
+
+- 创建成功返回 `datajson.dataIds`；完成计划成功以 `resultCode===200` 为标志。
+
+## 注意
+
+- `type` 与关联字段必须联动：客户、商机、线索分别传对应事项 ID。
+- 写操作执行前必须展示摘要并取得用户确认。
+
+## 失败处理
+
+- 关联事项不唯一：先搜索候选并让用户选择。
+- `partial/write_uncertain`：停止重试，补一次只读回查。

package/skills/weaver-e10-jiuchuanhui/references/contact-records.md

@@ -0,0 +1,48 @@
+# 联系记录（contact-records）
+
+## 何时使用
+
+用户表达联系记录/跟进记录相关意图：查询某客户/商机/线索/联系人的联系记录，或按人员+时间范围查询联系记录。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.entity.contact-records.list` | 只读 | `mainTable.moduleType`（`customer`/`clue`/`saleChance`）、`mainTable.entityId` |
+| `jiuchuanhui.contact-records.by-person-time.list` | 只读 | `mainTable`: `{employeeId, startData, endData}` |
+
+（新建联系记录/跟进走各业务模块的 `*.contact-record.create.prepare/apply`：客户/商机/线索分别见对应 reference。）
+
+## 输入要点
+
+- `moduleType`：要查询的对象类型（客户/商机/线索），`entityId` 为对应数据 ID。
+- 按人员+时间范围查询时，`employeeId` 用人员 ID（可先用 `user.id.by-name` 解析姓名），`startData`/`endData` 用 `yyyy-MM-dd HH:mm:ss`。
+- 日期类模糊表达需转换为明确范围，例如今天、本周、本月分别补齐开始和结束时间。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.entity.contact-records.list --input-json '{"mainTable":{"moduleType":"customer","entityId":"100001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-records.by-person-time.list --input-json '{"mainTable":{"employeeId":"USER_ID","startData":"2026-09-01 00:00:00","endData":"2026-09-09 23:59:59"}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.entity.contact-records.list --input-json '{"mainTable":{"moduleType":"customer","entityId":"100001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact-records.by-person-time.list --input-json '{"mainTable":{"employeeId":"USER_ID","startData":"2026-09-01 00:00:00","endData":"2026-09-09 23:59:59"}}'
+```
+
+## 输出处理
+
+- 联系记录列表按时间倒序展示；超过 10 条先展示最相关的前 10 条并提示可继续翻页/缩小范围。
+
+## 注意
+
+- 记录内的关联事项名称渲染为可点击链接。
+
+## 失败处理
+
+- 参数缺失/不支持：说明具体问题并停止。

package/skills/weaver-e10-jiuchuanhui/references/contact.md

@@ -0,0 +1,56 @@
+# 联系人管理（contact）
+
+## 何时使用
+
+用户表达联系人相关意图：新建联系人、联系人详情、修改联系人、按客户或商机查询联系人。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.contact.create.prepare/apply` | 高风险写 | `form`: `{mainTable, detail1?, ...}`；联系人随客户创建（客户 `detail2`）时勿重复调用 |
+| `jiuchuanhui.contact.get` | 只读 | `id` |
+| `jiuchuanhui.contact.update.prepare/apply` | 高风险写 | `form`：主表修改，按配置 `data_key` 组装 |
+| `jiuchuanhui.contact.by-entity.search` | 只读 | 按 `customerId` 或 `saleChanceId`（URL Query 传递，至少传一个），支持分页；body 的 `mainTable` 必传空对象 `{}` |
+
+## 输入要点
+
+- 创建/修改前读缓存 `config/contact_create_api.json`（或 `contact_update_api.json`）的 `detail`；只使用 `isInput:"1"` 字段，按 `data_key` 组装。
+- `contact_name`（姓名）必填；`customer`（所属客户）与 `salechance`（所属商机）**二选一必填**（至少传一个归属），`rel_sales` 可多选（逗号分隔）。
+- 只给联系人姓名未指明所属事项时，先 `contact.by-entity.search` 或搜索候选并让用户选择，不要猜归属。
+- 关联字段传选项/事项 ID（RelateBrowser 通过 `browser-option.search` 查自定义浏览选项）。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.by-entity.search --input-json '{"customerId":"100001","pageNo":1,"pageSize":10}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.get --input-json '{"id":"300001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.create.prepare --input-json '{"form":{"mainTable":{"contact_name":"王五","position":"采购经理"}}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.by-entity.search --input-json '{"customerId":"100001","pageNo":1,"pageSize":10}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.get --input-json '{"id":"300001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.create.prepare --input-json '{"form":{"mainTable":{"contact_name":"王五","position":"采购经理"}}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.contact.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+## 输出处理
+
+- 创建成功返回 `datajson.dataIds`；`by-entity.search` 返回联系人列表。
+- 联系人名称渲染为可点击链接，`objId` 取缓存 `discovery["objId:uf_jch_contact"]`。
+
+## 注意
+
+- 客户创建时通过 `detail2` 提交的联系人会同步写入联系人模块，不要再调用 `contact.create`。
+- 写操作必须展示摘要并取得用户确认。
+
+## 失败处理
+
+- 参数缺失/不支持：说明具体问题并停止。
+- `partial/write_uncertain`：停止重试，补一次 `contact.get` 回查。

package/skills/weaver-e10-jiuchuanhui/references/customer.md

@@ -0,0 +1,69 @@
+# 客户管理（customer）
+
+## 何时使用
+
+用户表达客户相关意图：新建客户、客户详情、搜索客户、修改客户、转移客户、客户查重、公海搜索/领取/释放、客户联系记录、批量联系记录、客户状态/类型/行业查询。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.customer.create.prepare/apply` | 高风险写 | `form`: `{mainTable, detail1?, detail2?, ...}`；`detail2` 提交后同步创建联系人，勿再调 `contact.create` |
+| `jiuchuanhui.customer.get` | 只读 | `id` |
+| `jiuchuanhui.customer.search` | 只读 | 搜索条件走 query；**必须显式传 `mine`/`all`/`customerSea`**（一个 `""` 其余 `-1`，默认 `mine=""`）；分页 `pageNo`/`pageSize`；`count:true` 并行取总数 |
+| `jiuchuanhui.customer.type/status/industry.search` | 只读 | 分页字段，用于取选项 ID |
+| `jiuchuanhui.customer.open-sea.search` | 只读 | 公海客户列表，条件走 query |
+| `jiuchuanhui.customer.update.prepare/apply` | 高风险写 | `form`：主表+明细修改，按配置 `data_key` 组装 |
+| `jiuchuanhui.customer.transfer.prepare/apply` | 高风险写 | `customerId`、`toUserId`、可选 `remark` |
+| `jiuchuanhui.customer.open-sea.release.prepare/apply` | 高风险写 | `customerId`、`openSeaId`（均必填）、可选 `remark`；释放影响需用户确认 |
+| `jiuchuanhui.customer.open-sea.claim.prepare/apply` | 高风险写 | `customer_id`（注意下划线命名） |
+| `jiuchuanhui.customer.duplicate.check` | 只读 | `mainTable.name`（原始名称）、`mainTable.simpleName`（归一化简称，均必填），动作流 `uniqueIndent=D5D0A1C30E7B404B842987C0AD3B749D` |
+| `jiuchuanhui.customer.contact-record.create.prepare/apply` | 高风险写 | `customerId`、`comment_content`（必填）；可选 `type`/`rating`/`contact_information`/`contacts`/`next_time`/`next_content`/`next_contact_information`/`next_contacts`/`sync_salechance`/`rel_remind`。`type` 为**评论类型**（销售记录/外勤记录/系统记录/客服记录等），与商机联系记录的 `type`（联系类型）**取值体系不同，勿混用** |
+| `jiuchuanhui.customer.contact-record.batch.prepare/apply` | 高风险写 | `customerIds`（一次最多 20 个客户 ID）、`content`；批量部分成功需人工核对 |
+
+## 输入要点
+
+- 创建/修改前先读缓存 `config/customer_create_api.json`（或 `customer_update_api.json`）的 `detail.mainFields`/`detail.detailFields`；只使用 `isInput:"1"` 字段，按 `data_key` 组装，`isRequired:"1"` 缺失时追问，禁止占位值。
+- `manager`（客户经理）必填，默认当前操作人；`id` 由系统生成，**请求体不携带 `id`**。
+- **修改（update）局部更新**：只传需要修改的字段（含 `id` 定位记录），未传入字段保持原值。以下系统字段**不可更新**（传了会被忽略）：`id`、`operator`、`creator`、`create_time`、`update_time`、`updater`、`data_status`、`customer_number`。
+- **转移/释放公海权限不足返回 HTTP 204**：提示用户无对应权限，联系管理员；不可误报为"操作失败"。
+- Select/RadioBox/CheckBox 字段传选项 ID（读字段 `optionList`）；Employee/RelateBrowser 字段传人员/事项 ID。
+- 行政区划 `country`/`province`/`city`/`district` 传逗号分隔全路径 ID；传细粒度自动填充粗粒度。
+- 搜索无 `scope` 快捷参数，`mine`/`all`/`customerSea` 三选一置空；日期范围用 `*_gt`/`*_lt` 字段；人员字段传人员 ID（如 `managerid`）。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"name":"示例科技有限公司","simpleName":"示例科技"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input-json '{"form":{"mainTable":{"manager":"USER_ID","customer_name":"示例科技有限公司"}}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10,"count":true}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"name":"示例科技有限公司","simpleName":"示例科技"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input-json '{"form":{"mainTable":{"manager":"USER_ID","customer_name":"示例科技有限公司"}}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10,"count":true}'
+```
+
+## 输出处理
+
+- 创建成功返回 `datajson.dataIds`（ID 列表）与 `status`；搜索返回 `datajson.datas` 数组。
+- 列表默认只取第一页 `pageNo=1`、`pageSize=10`；只有用户要求翻页才继续。
+- 客户名称渲染为可点击链接 `https://{baseUrl}/sp/ebdfpage/card/0/{objId}/{dataId}`，`objId` 取缓存 `discovery["objId:uf_jch_customer"]`。
+
+## 注意
+
+- 新建客户前**必须先查重**；存在疑似重复时表格展示让用户确认；若客户在公海，提醒可领取并让用户确认。
+- `detail2` 会同步创建联系人，不要重复调用 `contact.create`。
+- 释放公海、转移客户前必须确认客户唯一并提示影响。
+
+## 失败处理
+
+- 参数缺失/不支持：说明具体问题并停止，不猜测、不替换、不重试。
+- `partial/write_uncertain`：停止重试，补一次 `customer.get` 只读回查，给用户明确结论。