weaver-work-cli 0.1.2 → 0.1.5

package/skills/weaver-e10-jiuchuanhui/references/disabled-capabilities.md

@@ -0,0 +1,24 @@
+# 禁用能力边界（disabled-capabilities）
+
+## 何时使用
+
+用户表达九氚汇相关意图，但目标能力不在 `weaver-work-cli jiuchuanhui schema` 中，或源资料给出了接口但尚未安全封装为 CLI operation 时。
+
+## 未暴露为 CLI operation 的能力
+
+| 能力 | 原因 | 处理方式 |
+|---|---|---|
+| `jiuchuanhui.sale.stage-advance`（商机阶段推进） | 依赖缓存 `sale_stage` 配置做阶段 ID 映射与前置校验，属于 Skill 编排层职责 | 用 `sale.update` + `sale.stage.search` 组合实现；先查阶段选项，再按目标阶段映射 ID 走 `sale.update.prepare/apply` |
+| `jiuchuanhui.ds.fields`（表单字段发现） | 接口 `/api/ebuilder/common/ds/fields` 在当前 E10 版本返回 HTTP 400，无法使用 | 字段信息通过缓存初始化（`cache.init`）获取，不依赖此接口 |
+
+## 处理规则
+
+- 禁止绕过 CLI 直接 curl、fetch、浏览器自动化或拼 E10 原始接口。
+- 禁止加载原始 `weaver-e10-jiuchuanhui` 源 Skill 代替 CLI；禁止直接运行源目录 `scripts/*.mjs`。
+- 禁止读取或复制 CLI runtime 内部 Token、Cookie、ETEAMSID。
+- 源资料中有、但 CLI 未暴露的接口，先按 `weaver-e10-skill-maker` 流程评估是否补 operation；在补齐之前明确告知用户该能力暂不可用。
+
+## 注意
+
+- 缓存文件 `~/.weaver-e10-jiuchuanhui/{tenantKey}/{userId}/` 是 Agent 本地状态，不随 Skill 打包、不入库。
+- 不要编造不存在的 operation 或字段。

package/skills/weaver-e10-jiuchuanhui/references/discovery-config.md

@@ -0,0 +1,60 @@
+# 发现与配置（discovery-config）
+
+## 何时使用
+
+用户表达缓存/配置相关意图：初始化或刷新九氚汇配置缓存、应用发现、表单发现、字段发现、字段选项、接口配置详情、接口标识转配置 ID、文件预览。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.app.discovery` | 只读 | `tag`（默认 `jch-crm-project`） |
+| `jiuchuanhui.form.discovery` | 只读 | `tag`、`appId` |
+| `jiuchuanhui.field.options` | 只读 | `fieldName`、`sourceType`（必填，值为 `FORM`）；可选 `objId`、`groupId`（可省略自动发现，`groupId` 来自 `app.discovery` tag=`jch-crm-project`） |
+| `jiuchuanhui.rest.cfg.detail` | 只读 | `apid`、`id`（cfgId） |
+| `jiuchuanhui.config.id.by.pk` | 只读 | `mainTable.interface_pk` |
+| `jiuchuanhui.file.preview` | 只读（文件预览） | `fileId` 必填，可选 `fieldId`/`appId`/`customParam` |
+| `jiuchuanhui.get-rest-cfg-detail` | 只读 | `apid`、`id`（cfgId） |
+
+## 输入要点
+
+- 九氚汇配置缓存放 `~/.weaver-e10-jiuchuanhui/{tenantKey}/{userId}/`：主缓存 `weaver-e10-jiuchuanhui.json`（`discovery`/`ebuilder`/`options`/`region`），接口配置 `config/{pk}.json`。
+- 创建/更新类接口读 `config/{pk}.json.detail` 的 `mainFields`/`detailFields`；搜索类读 `searchParams`；选项字段优先读字段 `optionList`。
+- 缓存缺失或用户要求刷新时，调用 CLI operation `jiuchuanhui.cache.init`（应用发现 -> objId -> 版本校验 >= 1.5.11 -> cfgId -> 接口配置 -> 关联数据 -> 字段选项 -> 搜索参数 -> 行政区划），再继续业务调用。缓存初始化和刷新**已暴露为 CLI operation `jiuchuanhui.cache.init`**（risk: local-file-write，无需 prepare/apply 确认链）；也可在仓库根运行 `node src/shortcuts/jiuchuanhui/scripts/cache-init.mjs`（薄包装）。
+- 文件预览：`fileId` 为必填；涉及本地文件/远程 URL 解析时先提醒用户文件内容可能进入大模型上下文或发送到文件服务。
+- `file.preview` 返回的 `loadUrl`/`previewLink` 带临时签名（约 7 天），过期需重新调用获取，不要硬编码或长期缓存下载地址；附件 ID 从表单数据字段获取，字段无附件时返回空数组，无需调用本接口。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.app.discovery --input-json '{"tag":"jch-crm-project"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.form.discovery --input-json '{"tag":"uf_jch_customer","appId":"APP_ID"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.field.options --input-json '{"fieldName":"FIELD_ID","sourceType":"FORM","objId":"OBJ_ID","groupId":"APP_ID"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.file.preview --input-json '{"fileId":"FILE_ID"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.app.discovery --input-json '{"tag":"jch-crm-project"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.form.discovery --input-json '{"tag":"uf_jch_customer","appId":"APP_ID"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.field.options --input-json '{"fieldName":"FIELD_ID","sourceType":"FORM","objId":"OBJ_ID","groupId":"APP_ID"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.file.preview --input-json '{"fileId":"FILE_ID"}'
+```
+
+## 输出处理
+
+- `app.discovery` 返回 `data[0].appId`；`form.discovery` 优先取 `formId` 非空且非 `"0"` 的记录 `id` 为 `objId`；`field.options` 返回选项数组 `{lable, lableTitle, value}`。
+
+## 注意
+
+- 选项字段必须先取选项 ID 再传值（Select/RadioBox/CheckBox 传 `value`，不传 `lable` 中文名）。
+- `field.options` 的 `fieldName` 参数实际传字段元数据 ID（fieldid，纯数字），**不是** `data_key` 名称。传错会返回空数组。
+- `rest.cfg.detail` 与 `get-rest-cfg-detail` 都用于读取接口配置详情，Agent 按上下文选一个即可，不需要两个都调。
+
+## 失败处理
+
+- 版本校验 < `1.5.11`：停止业务调用并告知用户。
+- 缓存缺失：先执行初始化/单项刷新，再重试业务调用。

package/skills/weaver-e10-jiuchuanhui/references/general-helpers.md

@@ -0,0 +1,59 @@
+# 通用辅助（general-helpers）
+
+## 何时使用
+
+用户表达辅助解析意图：按名称查事项 ID、按姓名查人员 ID、查询当前人员信息、校验事项权限、查询企业工商照面、按字段 ID 获取字段信息、自定义浏览字段选项查询。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.entity.id.by-name` | 只读 | `mainTable`: `{moduleType, name}` |
+| `jiuchuanhui.user.id.by-name` | 只读 | `mainTable.employeeName` |
+| `jiuchuanhui.user.current-profile` | 只读 | 无入参；每轮会话优先取一次并复用 |
+| `jiuchuanhui.entity.permission.judge` | 只读 | `mainTable`: `{moduleType, entityId, opType}` |
+| `jiuchuanhui.company.business-profile.query` | 只读 | `mainTable.companyName` |
+| `jiuchuanhui.field.info.by-ids` | 只读 | `mainTable.fieldids` |
+| `jiuchuanhui.browser-option.search` | 只读 | `pathParams.customBrowserType` 必填，`params.searchValue` 可选 |
+
+## 输入要点
+
+- `moduleType`：模块类型（如 `customer`/`sale`/`clue`/`contact` 等），`name` 为事项名称。
+- 行政区划也走按名称查事项 ID：`moduleType: "administrativeDivision"`、`name` 传城市名；返回全路径 ID，可写缓存。
+- `browser-option.search` 是 RelateBrowser 字段的选项查询入口：用 `customBrowserType` 指定浏览类型，返回自定义浏览选项供选择。需已知 `customBrowserType`（自定义浏览类型标识），通过「通过字段id获取字段信息」接口（`jiuchuanhui.field.info.by-ids`）获取 RelateBrowser 字段定义中的 `browser_type` 作为 `customBrowserType`。 常见类型：`customBrowser_industrybrowser`（行业）。
+- 选项字段（Select/RadioBox/CheckBox）传 ID；`RelateBrowser` 字段通过 `browser-option.search` 查询对应类型选项。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"employeeName":"魏思雨"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.entity.id.by-name --input-json '{"mainTable":{"moduleType":"customer","name":"示例科技有限公司"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.current-profile --input-json '{}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.browser-option.search --input-json '{"pathParams":{"customBrowserType":"customer_type"},"params":{"searchValue":"科技"}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"employeeName":"魏思雨"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.entity.id.by-name --input-json '{"mainTable":{"moduleType":"customer","name":"示例科技有限公司"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.current-profile --input-json '{}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.browser-option.search --input-json '{"pathParams":{"customBrowserType":"customer_type"},"params":{"searchValue":"科技"}}'
+```
+
+## 输出处理
+
+- `user.id.by-name` / `entity.id.by-name` 返回业务 ID，供后续写操作或关联使用。
+- `user.current-profile` 返回当前人员 ID，可作为默认 `manager`/负责人/操作人。
+
+## 注意
+
+- 查询无结果时说明实际条件并停止，不得放宽条件猜测重试。
+- `entity.permission.judge` 的 `moduleType` 仅确认支持 `customer`（转移）与 `contactPlan`（联系记录）；是否支持 `saleChance`/`clue` 等其它类型须以动作流实际返回为准，返回不支持/校验失败时应如实反馈用户，不得臆造支持范围。
+- `field.info.by-ids` 的 `fieldids` 传字段 ID（逗号分隔多个）。
+
+## 失败处理
+
+- 参数缺失/不支持：说明具体问题并停止。

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

@@ -0,0 +1,60 @@
+# 入口：schema 与统一调用方式
+
+## 何时使用
+
+首次接触九氚汇模块、不确定某个 operation 是否存在、需要核对字段与风险等级，或想确认写操作是否走 prepare/apply 时。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli jiuchuanhui schema
+weaver-work-cli --json jiuchuanhui schema
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli jiuchuanhui schema
+weaver-work-cli --json jiuchuanhui schema
+```
+
+## 输出处理
+
+`schema` 输出全部 operation 的 name、risk 和 inputSchema。`weaver-work-cli jiuchuanhui schema` 是 operation、字段和风险等级的合约来源，任何调用都以它为最终依据；references 是第一信息源，`schema` 是契约校验。
+
+## 调用方式
+
+统一入口 `weaver-work-cli --json jiuchuanhui run <operation>`。输入支持两种方式：`--input-json '<json>'` 内联 JSON、`--input <path>` 从文件读取：
+
+Windows PowerShell：
+
+```powershell
+# 内联 JSON（复杂/嵌套结构）
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
+# 从文件读取 JSON
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input .\customer-create.json
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+# 内联 JSON（复杂/嵌套结构）
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
+# 从文件读取 JSON
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input ./customer-create.json
+```
+
+简单 JSON 传 `--input-json '<json>'`；复杂或多行 JSON 先写入 UTF-8 文件再传 `--input <path>`。
+
+## 注意
+
+- 业务输入不得包含 Cookie、ETEAMSID、Token 或内部控制字段；CLI 会拒绝这些 key。
+- 写 operation 都带 `.prepare` / `.apply` 后缀；`.apply` 只接受 prepare 返回的 continuation 且 `confirm:true`。
+- 不要在对话中手写 E10 原始接口路径或拼 HTTP 鉴权细节。
+
+## 失败处理
+
+- operation 不存在或字段不符：检查 `jiuchuanhui schema`，按合约修正，不猜字段。
+- `authentication`/`session_expired`：按共享规则完成登录后再继续。

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

@@ -0,0 +1,72 @@
+# 商机管理（sale）
+
+## 何时使用
+
+用户表达商机相关意图：新建商机、商机详情、搜索商机、修改商机、销售阶段/销售过程查询、商机转移/负责人变更、暂停、重启、赢单、输单、无效、关联联系人、商机联系记录、对手/友商查询、输单原因查询。
+
+## 可用 operation
+
+| Operation | 风险 | 输入要点 |
+|---|---|---|
+| `jiuchuanhui.sale.create.prepare/apply` | 高风险写 | `form`: `{mainTable, detail1?, ...}` |
+| `jiuchuanhui.sale.get` | 只读 | `id` |
+| `jiuchuanhui.sale.search` | 只读 | 搜索条件走 query，`count:true` 并行取总数 |
+| `jiuchuanhui.sale.update.prepare/apply` | 高风险写 | `form`：主表修改 |
+| `jiuchuanhui.sale.stage.search` / `sale.process.search` / `sale.lose-reason.search` | 只读 | 阶段/销售过程/输单原因选项，分页字段 |
+| `jiuchuanhui.rival.search` | 只读 | 对手/友商列表 |
+| `jiuchuanhui.sale.win.prepare/apply` | 高风险写 | `saleId`；赢单不可逆 |
+| `jiuchuanhui.sale.lose.prepare/apply` | 高风险写 | `saleid`、`reasonids`（输单原因，**单选**，传一个原因 ID）；可选 `money`（单位为**元**）、`rivals`（对手 ID，**多选**逗号分隔）、`desc`；输单必须先确定原因 |
+| `jiuchuanhui.sale.invalid.prepare/apply` | 高风险写 | `saleid`；无效不可逆 |
+| `jiuchuanhui.sale.pause.prepare/apply` | 高风险写 | `saleid`、`pauseReason`（必填，暂停原因描述）；可选 `restartDate`（**预计重启日期**，格式 `yyyy-MM-dd`） |
+| `jiuchuanhui.sale.restart.prepare/apply` | 高风险写 | `saleChanceId`（**仅可重启已暂停的商机**）；确认商机已暂停再操作 |
+| `jiuchuanhui.sale.manager-change.prepare/apply` | 高风险写 | `saleChanceId`、`managerId`（目标负责人）；转移/负责人变更共用；**仅本人或本人下级商机可操作**，权限不足返回 HTTP 204 |
+| `jiuchuanhui.sale.link-contacts.prepare/apply` | 高风险写 | `salechanceId`（注意小写 c）、`contactIds`；确认联系人与商机关联关系 |
+| `jiuchuanhui.sale.contact-record.create.prepare/apply` | 高风险写 | `saleid`、`comment_content`（必填）；可选 `type`/`rating`/`contact_information`/`contacts`/`next_time`/`next_content`/`next_contact_information`/`next_contacts`/`rel_remind`。`type` 为**联系类型**（例行联系等），与客户联系记录的 `type`（评论类型）**取值体系不同，勿混用** |
+
+## 输入要点
+
+- 创建/修改前读缓存 `config/sale_create_api.json`（或 `sale_update_api.json`）的 `detail`，按 `data_key` 组装，`isRequired:"1"` 缺失时追问。
+- Select/RadioBox/CheckBox 传选项 ID；关联客户传 `customerId`；负责人传人员 ID。
+- 搜索商机：默认小页；需要总数时 `count:true` 与列表**并行**发起。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.search --input-json '{"sale_name":"示例","pageNo":1,"pageSize":10,"count":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.get --input-json '{"id":"200001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.prepare --input-json '{"mainTable":{"saleId":"200001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.lose.prepare --input-json '{"mainTable":{"saleId":"200001","reasonids":"400001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.link-contacts.prepare --input-json '{"mainTable":{"salechanceId":"200001","contactIds":"300001,300002"}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.search --input-json '{"sale_name":"示例","pageNo":1,"pageSize":10,"count":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.get --input-json '{"id":"200001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.prepare --input-json '{"mainTable":{"saleId":"200001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.lose.prepare --input-json '{"mainTable":{"saleId":"200001","reasonids":"400001"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.link-contacts.prepare --input-json '{"mainTable":{"salechanceId":"200001","contactIds":"300001,300002"}}'
+```
+
+## 输出处理
+
+- 赢单/输单/无效等 ESB 操作以 `resultCode===200` 为成功标志，不额外发起查询验证。
+- 商机名称渲染为可点击链接，`objId` 取缓存 `discovery["objId:uf_jch_sale"]`。
+
+## 注意
+
+- 赢单、输单、无效是高影响状态变更，执行前必须提示不可逆或关键影响。
+- 输单要先确定输单原因（`sale.lose-reason.search` 取 ID）；暂停必须有暂停原因；重启需确认目标商机处于可重启状态。
+- 商机转移和负责人变更共用 `sale.manager-change`。
+- 关联联系人前要确认商机和联系人均唯一，且联系人属于该客户/商机关系链。
+- 商机阶段推进（stage-advance）属于 Skill 编排层组合逻辑，不暴露为 CLI operation；可用 `sale.update` + `sale.stage.search` 组合实现。
+
+## 失败处理
+
+- 参数缺失/不支持：说明具体问题并停止。
+- `partial/write_uncertain`：停止重试，补一次 `sale.get` 回查。