weaver-work-cli 0.1.8 → 0.1.20

package/skills/weaver-e10-hrm/references/employee.md

@@ -2,18 +2,36 @@
 
 ## 何时使用
 
-按工号/姓名/手机/邮箱查员工、按人员 id 查当前登录人或任意员工的下属、查部门/分部下成员、按 id 列表批量查人员精简详情、按人员 id 取资料名片时使用。全部为只读操作。
+按工号/姓名/手机/邮箱查员工、按人员 id 查当前登录人或任意员工的下属、查部门/分部下成员、按 id 列表批量查人员精简详情、按人员 id 取人员卡片（默认精简、`full` 可回完整）时使用。全部为只读操作。
 
 ## 输入要点
 
 | operation | 必填 | 说明 |
 | --- | --- | --- |
-| `hrm.employee.query` | 至少一个收敛条件 | 按工号/姓名/手机/邮箱/状态分页查询员工 |
+| `hrm.employee.query` | 至少一个收敛条件 | 按工号/姓名/手机/邮箱/状态分页查询员工；**默认每行只回人员信息（6 键）**，`full: true` 回完整行 |
 | `hrm.employee.batch` | `ids` | 按人员 id 列表批量查精简详情（每批 ≤100 自动分批，不含部门/岗位/上级名称） |
-| `hrm.employee.detail` | `id` | 按人员 id 取资料名片（头像/是否管理员/在线状态，不含姓名/工号/部门/手机） |
-| `hrm.subordinate.mine` | `scope`（默认 all） | 查当前登录人的下属（direct/indirect/all），基于当前会话身份 |
-| `hrm.subordinate.by-id` | `id`（`scope` 默认 direct） | 按目标人员 id 查直接/间接下属（**无需切换会话**）；所有下属 = direct + indirect 两次并集 |
-| `hrm.dept.members` | `dept` | 按部门/分部名或 id 查其下直接成员（组织名需唯一） |
+| `hrm.employee.detail` | `id` | 按人员 id 取**人员卡片**：默认只回核心业务字段（组织/上级/助理/职称/职级/办公地点等）；`full: true` 才回完整卡片 |
+| `hrm.subordinate.mine` | `scope`（默认 all） | 查当前登录人的下属（direct/indirect/all），基于当前会话身份；**默认每行只回 `id`/`name`/`link`**（`full: true` 回完整行） |
+| `hrm.subordinate.by-id` | `id`（`scope` 默认 direct） | 按目标人员 id 查直接/间接下属（**无需切换会话**）；所有下属 = direct + indirect 两次并集；**默认每行只回 `id`/`name`/`link`**（`full: true` 回完整行） |
+| `hrm.dept.members` | `dept` | 按部门/分部名或 id 查其下直接成员（组织名需唯一）；**默认每行只回 `id`/`name`/`link`**（`full: true` 回完整行） |
+
+### 按组织反查人员（部门/岗位 → 有哪些人）
+
+需要"这个部门/岗位下有哪些人"时，先按下表判断，**不要默认认为 hrm 做不到**：
+
+| 起点 | 支持情况 | 走哪里 |
+| --- | --- | --- |
+| 部门 / 分部 | ✅ 支持 | `hrm.dept.members`（同模块，`dept` 传名称或 id） |
+| 岗位 | ❌ 本技能不支持 | `position.*` 只给 `userCount` 人数，`employee.query` 也不支持按岗位过滤；需跨到聚才林通讯录高级搜索 `ehr.hr.contact.search` + `saCondition` |
+
+⚠️ `hrm.dept.members` 只返回**直属**该组织的成员，**不含子部门人员**（实测：上级部门「基础服务研发部」→ 0 条，其子部门「组织权限组」→ 8 条）。需要连子部门一起取时，只能按组织树逐层调用。
+
+⚠️ 只有**岗位反查**才需要跨到聚才林 `saCondition`。该路径有两个反直觉点，执行前必须先读聚才林技能（`weaver-e10-jucailin`，连接器版为 `weaver-e10-jucailin-connector`）的通讯录高级搜索条件文档：
+
+1. `saCondition` 是完整条件对象，**不会继承便捷字段的"默认在职"**——不写 `personnel_status` 就是不限状态（含离职），与便捷字段默认在职相反；
+2. 条件元素漏写算子键/字段键会被服务端**静默忽略**，表现为"有结果但根本没过滤"（例如只给裸 id 不给字段键，会返回全量人员）。
+
+跨模块拿到结果后，**必须**按 [`../SKILL.md`](../SKILL.md) 的「反查人员的能力边界」执行结果自检：先取全量基线 N（`personnel_status: ["all"]`），`total` 等于或接近 N 即判定"条件被吞"，不得直接把该数字回复用户。
 
 ### `hrm.employee.query` 关键字段
 
@@ -25,10 +43,41 @@
 | `mobile` | 手机号（模糊匹配） |
 | `email` | 邮箱（模糊匹配） |
 | `status` | `["normal"]` 在职（默认）/ `["6"]` 离职。**不能单独使用**，必须搭配其它条件 |
-| `current`/`pageSize` | 分页（pageSize 默认 200） |
+| `current`/`pageSize` | 分页（**pageSize 默认 10、最大 100**，见 SKILL.md 分页统一约束；要更多数据用 `current` 翻页） |
 
 `keyword` 与 `username`/`job_num`/`mobile`/`email` 互斥，显式字段优先。
 
+## 返回字段
+
+### 🔴 三套 id 不要混用（最高频踩坑点）
+
+人员行里可能出现 3 个长得都像 id 的字段，**它们不是一回事**：
+
+| 字段 | 含义 | 用在哪 |
+| --- | --- | --- |
+| `id` | **人员 id**（驼峰 `userId` 与它同值） | ✅ 唯一该用的：拼卡片链接、`employee.detail`、`employee.batch` 的 `ids`、`subordinate.by-id` 的 `id`、IM 之外的所有人员定位 |
+| `userid` | **登录信息 id**（登录账号维度） | 登录账号场景；**不要当人员 id 用** |
+| `cid` | **IM 联系人 id**（`employee.batch` 里叫 `imCid`） | IM 聊天 / 在线状态；**不要当人员 id 用** |
+
+> `employee.query` 默认行**只保留人员 `id`**，另两套已被精简掉——正因如此，看到默认行时不存在混用风险；一旦传 `full: true` 就必须自己分清。
+
+### `employee.query` 的行字段
+
+**默认只回人员信息（6 键）**：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 人员 id（见上表） |
+| `name` | 姓名 |
+| `department` | 部门名称 |
+| `position` | 岗位名称 |
+| `statusCode` | 人员状态（`normal` 等） |
+| `link` | 人员卡片链接（派生） |
+
+**传 `full: true` 时额外回（+5 键）**：`userid`、`cid`、`mobile`（本接口**恒为空串**）、`departmentId`、`deptLink`。
+
+> 精简后单行约 186B（原 368B，省 49%）。**注意默认行没有工号和手机号**：工号要 `employee.batch`（`jobNum`）或 `full: true`，手机号只有 `employee.batch` 有脱敏值。
+
 ## 命令
 
 按姓名查员工：
@@ -57,36 +106,61 @@ weaver-work-cli --json hrm run hrm.employee.query --input-json '{"keyword":"李
 weaver-work-cli --json hrm run hrm.employee.batch --input-json '{"ids":["1000000000000000001","1000000000000000002"]}'
 ```
 
-按 id 取资料名片（头像/管理员/在线）：
+按 id 取人员卡片（**默认精简**，体积约为完整卡片的 1/5）：
 
 ```powershell
 weaver-work-cli --json hrm run hrm.employee.detail --input-json '{"id":"1000000000000000001"}'
 ```
 
-查当前登录人的所有下属：
+仅在确实需要完整卡片（`password`/`last_android`/`hideFieldList`/`setting`/各类 `*_admin` 等登录与管理元数据）时才加 `full`：
+
+```powershell
+weaver-work-cli --json hrm run hrm.employee.detail --input-json '{"id":"1000000000000000001","full":true}'
+```
+
+查当前登录人的所有下属（默认每行只回 `id`/`name`/`link`）：
 
 ```powershell
 weaver-work-cli --json hrm run hrm.subordinate.mine --input-json '{"scope":"all"}'
 ```
 
-查某人的直接下属（无需切换会话）：
+查某人的直接下属（无需切换会话；默认每行只回 `id`/`name`/`link`）：
 
 ```powershell
 weaver-work-cli --json hrm run hrm.subordinate.by-id --input-json '{"id":"1000000000000000001","scope":"direct"}'
 ```
 
-查部门下成员：
+需要下属的部门/岗位/电话等完整行时加 `full`（**仅当确实要展示这些列时才加**）：
+
+```powershell
+weaver-work-cli --json hrm run hrm.subordinate.mine --input-json '{"scope":"all","full":true}'
+weaver-work-cli --json hrm run hrm.subordinate.by-id --input-json '{"id":"1000000000000000001","scope":"direct","full":true}'
+```
+
+查部门下成员（默认每行只回 `id`/`name`/`link`；要部门/岗位/手机等列时加 `full: true`）：
 
 ```powershell
 weaver-work-cli --json hrm run hrm.dept.members --input-json '{"dept":"示例部门"}'
+weaver-work-cli --json hrm run hrm.dept.members --input-json '{"dept":"示例部门","full":true}'
 ```
 
 ## 输出处理
 
-- 查询类返回 `data.rows`（行数组）+ `data.total`（总数）+ `meta`（current/pageSize）；批量/下属返回 `data.rows` + `data.total`。
-- 每行含派生字段 `link`（人员卡片链接 `/sp/hrm/profileInfo/{id}`）与 `deptLink`（部门卡片链接），Agent 输出用 `[姓名](link)` 形式呈现；列表行自带 `departmentId`，可同时输出 `[部门名](deptLink)`。
-- `employee.detail` 返回 `data`（含 `avatar`/`isAdmin`/`managerType`/`online`）+ `data.link`。这是轻量名片，**不含**姓名/工号/部门/手机。
+- 查询类返回 `data.rows`（行数组）+ `data.total` + `meta`（current/pageSize）；批量/下属返回 `data.rows` + `data.total`。
+  - ⚠️ **`data.total` 是「本页行数」，不是真实总数**（源码用返回行数当 total）。实测同一个 `job_num:"WS"`：`pageSize=5` → `total=5`、`pageSize=50` → `total=50`、不传 → `total=20`。要真实总数只能按 `current` 逐页翻到 `rows.length < pageSize` 为止。**例外**：`subordinate.by-id` 的 `total` 是真实总数（另有 `data.page.hasNext/totalPages`）。
+  - ⚠️ **不传 `pageSize` 时 `meta.pageSize` 会显示 200，但服务端实际只回 20 行**；别用 meta 判断"拿到了多少条"。
+- 列表行分两种形态：**默认精简行只有 `link`**（人员卡片链接 `/sp/hrm/profileInfo/{id}`）；**完整行（`employee.query` 传 `full: true`、`dept.members`/下属传 `full: true`）额外有 `deptLink`（部门卡片链接）与 `departmentId`**，这时可同时输出 `[部门名](deptLink)`。两种形态都用 `[姓名](link)` 呈现人名。
+- `employee.detail` 的 `data` **本身就是**人员卡片业务字段，并附 `data.id` + `data.link`。**默认只回核心字段**（26 键：`id`/`name`/`username`/`job_num`/`sex`/`avatar`/`personnel_status`/`status`/`type`/`department`/`subcompany`/`organization`/`position`/`jobsetid`/`jobset_level`/`superior`/`other_superior`/`only_superior`/`subordinate`/`assistant`/`mobile`/`email`/`telephone`/`office`/`location`/`active_date`），实测体积 5.3KB → 1.2KB。
+  - 精简规则：实体数组（`department`/`subcompany`/`position`/`personnel_status`/`jobsetid`/`jobset_level`/`location`）只留 `{id, name}`；人员数组（`superior`/`other_superior`/`assistant`）只留 `{id, name, statusCode, avatar}`；`avatar` 只留 1 个 `url`（原响应重复给了 7 个等价 URL + `p1..p5`）。
+  - 完整卡片（85 个顶层键，含 `password`/`last_android`/`hideFieldList`/`setting`/`formdata`/各类 `*_admin`）需显式传 `full: true`。**默认不要传**：那些是登录/管理元数据，回答业务问题时无用，且会显著撑大上下文。
+  - ⚠️ **没有 `data.data` 这一层**：上游 `card/get` 响应里的业务字段位于其 `data.data`，CLI 已把它**展平上移一层**，所以最终 CLI 输出里业务字段**直接挂在 envelope 的 `data` 下**。按 `j.data.data` 取值会得到 `undefined`。
+  - CLI envelope 统一为 `{ schemaVersion, ok, operation, data, meta?, warnings }`；判断成功看 `ok=true`（不是 `code`），业务数据只看 `data`。`items`/`groups`/`layout` 等前端表单元数据已丢弃（传 `full: true` 也不会回）。
+  - 若要从卡片里取上级：`data.superior` 是数组（元素含 `id`/`name`/`avatar`/`statusCode`），另有 `data.other_superior`、`data.only_superior`、`data.assistant`、`data.subordinate`（布尔，是否带下属）。
 - `subordinate.by-id` 返回 `data.rows` + `data.total` + `data.page`（hasNext/totalPages）。
+- **三个「人员列表」接口默认精简**：`subordinate.mine` / `subordinate.by-id` / `dept.members` 的每行默认只回 `id` / `name` / `link`（对比原始行：`dept.members` 与 `subordinate.mine` 走 `formatMember` 单行 366B、`by-id` 原始行 960B——其中上游 `superior` 对象一项独占 485B；精简后约 116~120B/行）。要部门/岗位/电话/上级等列时传 `full: true`。
+  - 默认行的 `id` 就是人员 id，可直接喂给 `employee.detail`；`link` 用来渲染 `[姓名](link)`。
+  - 若回答里确实要展示"某人属于哪个部门/什么岗位"，要么传 `full: true`，要么对感兴趣的人再调 `employee.detail`（默认精简卡片里含 `department`/`position` 的 `{id,name}`）。**不要为了列表好看就默认传 `full: true`**。
+  - `employee.query` 默认行也精简了，但**保留人员信息**（`id`/`name`/`department`/`position`/`statusCode`/`link` 6 键，单行 368B → 186B）；它裁掉的是另两套 id（`userid`/`cid`）、恒空的 `mobile`、以及 `departmentId`+`deptLink`。要看这两套 id 或部门卡片链接时传 `full: true`。
 - `mobile` 已由 CLI 脱敏（3 位前缀 + `****` + 末 4 位），直接呈现。
 
 ## 注意
@@ -94,7 +168,7 @@ weaver-work-cli --json hrm run hrm.dept.members --input-json '{"dept":"示例部
 - **🔴 无条件禁止全量拉取**：`employee.query` 必须带至少一个收敛条件。
 - **🔴 `status` 不能单独使用**：必须搭配其它条件，否则 `empty_condition`。
 - 在职查询未命中时，CLI 会在 `data.hint` 提示"可能已离职"，Agent 应据此询问用户是否要查离职人员，不要直接答复"查无此人"。
-- `employee.batch` 不含部门/岗位/上级**名称**，需要名称时用列表接口或 `employee.detail`（但 detail 也不含这些，需走 `employee.query` 或 `subordinate.by-id`）。
+- `employee.batch` 不含部门/岗位/上级**名称**（返回纯字符串），需要这些信息时改用 `employee.query`（列表行）或 `employee.detail`（人员卡片，含组织/上级/助理等；完整卡片需加 `full: true`）。
 - `subordinate.by-id` 的 `scope` 两值：`direct`（直接）/`indirect`（间接）；"所有下属"需两次调用并集（无 `all` 接口，实测 404）。
 - `subordinate.mine` 返回的是**当前登录人**的下属，查"某人的下属"请用 `subordinate.by-id`。
 - 人员 id 是长整型，按字符串传递。

package/skills/weaver-e10-hrm/references/org.md

@@ -9,7 +9,7 @@
 | operation | 必填 | 说明 |
 | --- | --- | --- |
 | `hrm.org.query` | 至少一个收敛条件 | 按名称/编号/上级组织查询组织（`type` 区分分部/部门） |
-| `hrm.org.detail` | `id` | 按组织节点 id 取详情表单（类型由服务端自动判断，含全路径与人员统计） |
+| `hrm.org.detail` | `id` | 按组织节点 id 取组织详情（类型由服务端自动判断，含全路径 `fullPath`、上级部门名、所属分部名；**不含人员统计**） |
 
 ### `hrm.org.query` 关键字段
 
@@ -21,7 +21,7 @@
 | `parent` | 上级**部门** id 数组（查挂在某部门下的子部门，`department`） |
 | `subcompany` | 上级**分部** id 数组（查挂在某分部下的组织，`department`） |
 | `supSubDepartment` | 上级**分部** id 数组（查挂在某分部下的分部，`subcompany`） |
-| `current`/`pageSize` | 分页（pageSize 默认 200） |
+| `current`/`pageSize` | 分页（**pageSize 默认 10、最大 100**，见 SKILL.md 分页统一约束；要更多数据用 `current` 翻页） |
 
 > **parent vs subcompany vs supSubDepartment**：`parent` 限定上级部门、`subcompany` 限定上级分部（部门挂在分部下）、`supSubDepartment` 限定上级分部（分部挂在分部下）。三者键名不同，按 `type` 选用，不要混用。
 
@@ -76,8 +76,11 @@ weaver-work-cli --json hrm run hrm.org.detail --input-json '{"id":"1000000000000
 ## 输出处理
 
 - `org.query` 返回 `data.rows`（组织数组）+ `data.total` + `meta`（current/pageSize）；每行含派生字段 `link`（组织卡片链接 `/sp/hrm/orgCard/{id}`），Agent 输出用 `[组织名](link)` 呈现。
-- `org.detail` 返回 `data`（含 `name`/`code`/`type`/`fullPath`/`employee_count`/`parent`/`subcompany` 等）+ `data.link`。`employee_count` 格式为 `"直接人数/总人数"`（`includeSub=true` 时总数含下级）。
-- 名称/全称已转多语言，直接呈现。
+- `org.detail` 返回 `data`，业务字段**直接挂在 envelope 的 `data` 下，没有 `data.data` 嵌套**（上游 `organization/getForm` 的 `data.data` 已被 CLI 展平上移）。CLI **只透出这些字段**：
+  `id` / `name` / `type` / `code` / `fullPath`（全路径）/ `status` / `parentName`（上级部门名，无则省略）/ `subcompanyName`（所属分部名，无则省略）/ `description` / `remark`（有值才回）/ `link`。
+  - ⚠️ **`parent` / `subcompany` 已由「对象数组」改为 `parentName` / `subcompanyName` 字符串**（只要名字，不要 id/元数据）。
+  - 🔴 **`employee_count`（人员统计）不再返回**，本接口也**没有 `full` 开关**。要看某组织有多少人、有哪些人，只能用 `hrm.dept.members`（注意其 `data.total` 是本页行数，且只算直属成员）。
+- 名称/全路径 `fullPath` 已转多语言，直接呈现。
 
 ## 注意
 

package/skills/weaver-e10-hrm/references/position.md

@@ -9,28 +9,32 @@
 | operation | 必填 | 说明 |
 | --- | --- | --- |
 | `hrm.position.query` | 至少一个收敛条件 | 按名称/编号查岗位（快捷搜索名称编号合一；显式 name/code 走高级条件） |
-| `hrm.position.detail` | `id` | 按岗位 id 取详情表单（只读，含职务/职级） |
+| `hrm.position.detail` | `id` | 按岗位 id 取详情（只读 `type=info`；含**上级岗位名 / 职务序列 / 职务类型 / 职级**；不含全称与所属部门） |
 | `hrm.position.list` | 至少一个过滤或 `all=true` | 按组织/名称/编号批量查岗位（岗位地址簿，一次性 + 自动翻页） |
 
 ### `hrm.position.query` 关键字段
 
 | 字段 | 说明 |
 | --- | --- |
-| `keyword` | 快捷搜索关键词，名称与编号合一匹配 |
-| `name` | 岗位名称（包含匹配） |
+| `keyword` | 快捷搜索关键词，名称与编号合一匹配，**包含**匹配（模糊找岗位只能用这个字段） |
+| `name` | 岗位名称（**精确匹配**，不支持模糊） |
 | `code` | 岗位编号（精确匹配） |
 
 `keyword` 与 `name`/`code` 互斥：传 `name`/`code` 时走高级条件，否则走快捷搜索。
 
+⚠️ **`name` 是精确匹配，不是包含匹配**（实测：`name:"测试"` → 0 条；`name:"测试组长"` → 命中多条同名岗位）。要模糊找岗位必须先知道完整岗位名，或改用 `keyword`（实测 `keyword:"EBU"` → 1334 条）。
+
 ### `hrm.position.list` 关键字段
 
 | 字段 | 说明 |
 | --- | --- |
 | `org` | 组织 id（限定该组织下岗位） |
-| `name` | 岗位名称过滤（与 `code` 二选一） |
+| `name` | 岗位名称过滤（**包含**匹配，与 `code` 二选一） |
 | `code` | 岗位编号过滤（与 `name` 二选一） |
 | `all` | 显式确认全量拉取（无 `org`/`name`/`code` 过滤时必填 `true`） |
-| `pageSize` | 分页大小（默认 100，自动翻页到 total） |
+| `pageSize` | 分页大小（**上限 100**，见 SKILL.md 分页统一约束；本接口自带自动翻页取全 total，通常无需显式传） |
+
+> `hrm.position.query` **不接受 `pageSize`**（schema 里没有该参数，传了会被忽略，固定按 200 返回）；只有 `hrm.position.list` 支持分页。
 
 ## 命令
 
@@ -76,14 +80,17 @@ weaver-work-cli --json hrm run hrm.position.list --input-json '{"name":"行政"}
 
 - `position.query` 返回 `data.rows`（轻量行：`id`/`name`/`code`/`title`/`leaf`）+ `data.total`；每行含派生字段 `link`（岗位卡片链接 `/sp/hrm/positionCard/{id}`），Agent 输出用 `[岗位名](link)` 呈现。
 - `position.list` 返回 `data.rows`（结构化行：`id`/`name`/`fullName`/`code`/`parent`/`department`/`userCount`/`partTimeCount`/`cancelStatus`/`jobsetid`）+ `data.total`；每行含 `link`。
-- `position.detail` 返回 `data`（含岗位名称/全称/编号/上级岗位/所属部门/职务/职级）+ `data.link`。
-- 岗位名/全称/职务/职级名已转多语言，直接呈现。
+- `position.detail` 返回 `data`，业务字段**直接挂在 envelope 的 `data` 下，没有 `data.data` 嵌套**（上游 `getEditOrAddPostForm` 的 `data.data` 已被 CLI 展平上移）。CLI **只透出这些字段**：
+  `id` / `name` / `code` / `parentName`（上级岗位名，无则省略）/ `jobsetName`（职务序列名，无则省略）/ `jobsetTypeName`（职务类型名，无则省略）/ `grade`（职级名称数组，无则省略）/ `link`。
+  - ⚠️ **不返回 `fullName`（全称）与 `department`（所属部门）**。要看岗位所属部门，改用 `hrm.position.list` 的行字段 `department`；要看全称同样走 `position.list` 的 `fullName`。
+- 岗位名/上级岗位名/职务序列名/职务类型名/职级名已转多语言，直接呈现（**全称与所属部门不在 `position.detail` 里**，见上）。
 
 ## 注意
 
 - **🔴 无条件禁止全量拉取**：`position.query` 必须带至少一个收敛条件；`position.list` 无 `org`/`name`/`code` 过滤时必须显式 `all=true`，否则 `full_pull_blocked`。
 - **批量禁止循环单查**：批量一律走 `position.list` 一次性返回，禁止按 id 逐个调 `position.detail`。
 - 两个列表接口返回字段不同：`position.query`（浏览按钮）返回轻量行，`position.list`（岗位地址簿）返回结构化行（含全名/上级/人员数）。
+- **`name` 匹配语义两处不同，别混用**：`position.query` 的 `name` 是**精确匹配**，`position.list` 的 `name` 是**包含匹配**。需要模糊查岗位时，`position.query` 走 `keyword`，或改用 `position.list` 的 `name`。
 - 岗位 id 是长整型，按字符串传递。
 - `cancelStatus`：1=封存 / 0=未封存。
 

package/skills/weaver-e10-hrm/references/source-manifest.json

@@ -433,7 +433,7 @@
   },
   "notes": [
     "源资料为用户提供的 weaver-interface 仓库 hrm 模块（原始 document-skill 形态，含 SKILL.md + employee/org/position 模块文档 + scripts/*.mjs 参考 CLI）。",
-    "本次转换将原始「weaver-e10-login 会话 + 去域名内部路径 + 脚本」形态改写为 weaver-work-cli 的 hrm shortcut + weaver-e10-hrm Skill，接口路径与请求体以源资料 scripts/*.mjs 与模块文档为唯一依据，未编造接口。",
+    "本次转换将原始「旧登录会话 + 去域名内部路径 + 脚本」形态改写为 weaver-work-cli 的 hrm shortcut + weaver-e10-hrm Skill，接口路径与请求体以源资料 scripts/*.mjs 与模块文档为唯一依据，未编造接口。",
     "代理商查询（containsDls=true）仅自用系统支持，列为禁用边界 hrm.employee.dls，未实现。",
     "manifest 只记录路径、hash、影响映射和转换摘要，不保存 Cookie、Token、个人主目录绝对路径或大段源正文。"
   ]

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

@@ -0,0 +1,166 @@
+---
+name: weaver-e10-jinchengda
+display_name: 泛微今承达合同管理
+display_name_en: Weaver Jinchengda Contract Management
+description: "泛微 E10 今承达合同管理：查询合同类型/模板/条款、引用条款、管理签约主体，并通过确认链发起、保存、提交和催办 12 类合同审批流程。"
+description_zh: "泛微今承达合同管理。触发场景：找合同模板或合同条款、查或新建签约主体、发起/保存/提交/催办合同审批、查审批进度与意见。所有能力通过 weaver-work-cli contract 命令执行。"
+description_en: "Weaver E10 Jinchengda contract management skill for contract types, templates and clause discovery, clause reference writes, signing subject management, and prepare/apply confirmation chains across 12 contract approval workflows, driven by weaver-work-cli contract."
+version: 1.1.1
+author: 泛微网络科技股份有限公司
+agent_created: true
+requires:
+  bins: ["weaver-work-cli"]
+dependencies:
+  - weaver-e10-shared
+cliHelp: "weaver-work-cli contract --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若共享规则不存在、CLI 未安装或读取失败，说明本技能的必需依赖缺失，必须先提示用户先补齐 `weaver-work-cli` 与共享 skill `weaver-e10-shared`（不补齐本技能无法执行），并把下面两条待执行命令原样完整展示给用户；Agent 不能自行安装——必须先取得用户明确确认后再执行。用户确认后按顺序执行且仅执行一次：① 缺 CLI 时执行 `npm install -g weaver-work-cli`；② 再执行 `weaver-work-cli skills install shared --target-dir <SKILLS_ROOT>` 装回共享 skill，`<SKILLS_ROOT>` 取本 SKILL.md 所在目录的上一级绝对目录（即与本技能同级的 skills 根目录），不要省略 `--target-dir`——省略会装进默认目录，导致本技能依然读不到共享规则。命令均成功后重新读取共享规则；仍读不到就停止并把结果报告用户，不得凭猜测继续。**
+认证和登录态只能按共享规则通过 `weaver-work-cli auth ...` 命令判断；禁止直接读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。
+所有命令通过 `weaver-work-cli --json contract run <operation>` 执行：简单 JSON 优先传 `--input-json '<json>'`，复杂或多行 JSON 先写入 UTF-8 文件再传 `--input <path>`，只有确认当前 shell 能稳定传管道时才使用 `--input -`。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，`weaver-work-cli contract 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 今承达，并可能进入当前大模型上下文用于理解和处理；必须等待用户明确确认后才继续。
+
+## 请求头 / 认证
+
+本技能发起的 API 请求通过 `weaver-work-cli` 执行，CLI 从 E10 登录会话自动注入以下凭证头：
+
+| 请求头 | 值 |
+|--------|-----|
+| `Cookie` | `<e10-login 返回的完整原始 Cookie 串>`（禁止裁剪/去重/改写） |
+| `eteamsid` | `<e10-login 返回的 ETEAMSID>` |
+| `User-Agent` | `AgentType=<agentType>,IsAgent=true` |
+
+上述凭证由 `weaver-work-cli auth login --agent_type WorkBuddy` 建立会话后自动注入，业务输入（`--input-json` / `--input`）**不得包含** `userid`、`userId`、`token`、`cookie`、`eteamsid` 等字段，用户 ID 由 CLI 从会话注入。
+
+## 适用场景与触发条件
+
+当用户表达命中以下任一类意图时，优先加载本 skill 并路由到 `weaver-work-cli contract`：
+
+- 关键词：合同类型、合同模板、模板推荐、条款、条款分类、条款标签、条款推荐、条款引用、签约主体、我方签约主体、客户签约主体、供应商签约主体
+- 合同审批场景：销售合同、采购合同、协议合同、合同变更、合同解除、合同关闭、合同开票、合同收款、合同付款、履约计划、进度提报、供应商准入
+- 动作词：查条款 / 推荐条款 / 引用条款、查或新建签约主体、发起合同、保存合同表单、提交审批、催办、查审批进度、查审批意见
+
+使用时机：最终动作落在今承达合同对象上，且必须通过 CLI 完成查询或写入时。仅查询企业工商资信或做通用 E10 对象操作时不要路由到这里（见 [`contract-disabled-capabilities.md`](references/contract-disabled-capabilities.md)）。
+
+## 路由优先级（先判断是不是今承达合同，再选 operation）
+
+今承达合同管理不是通用 E10 对象。**只要用户的核心对象是合同类型、合同模板、合同条款、条款引用、签约主体，或 12 类合同审批流程，就优先使用 `weaver-e10-jinchengda`。**
+
+### 明确归 `weaver-e10-jinchengda` 的高优先级语义
+
+- 合同类型 / 合同模板 / 模板分类 / 模板详情
+- 条款 / 条款分类 / 条款标签 / 条款搜索 / 条款推荐 / 条款引用
+- 我方签约主体 / 客户签约主体 / 供应商主体 / 签约主体库
+- 销售合同、采购合同、协议、变更、解除、关闭、开票、收款、付款、履约计划、进度提报、供应商准入的合同审批流程
+- 发起合同 / 保存合同表单 / 提交合同审批 / 催办 / 审批进度 / 审批意见
+
+**判定规则：** 只要最终动作是对今承达合同做模板条款查询、主体查询、主体新建、条款引用写入、流程发起、表单保存、提交审批或催办，就归 `weaver-e10-jinchengda`。企业资信查询、撤回/退回流程等源资料未给出接口的能力不在范围内（见 [`contract-disabled-capabilities.md`](references/contract-disabled-capabilities.md)）。
+
+## 选哪个命令
+
+| 想做什么 | 命令 | 按需读取 reference |
+|---|---|---|
+| 查看可用 operation、字段和风险等级 | `contract schema` | [`contract-agent-entry.md`](references/contract-agent-entry.md) |
+| 查合同类型树 | `contract run contract.type.tree` | [`contract-template-selector.md`](references/contract-template-selector.md) |
+| 查模板分类树 / 模板列表 / 模板详情 | `contract run contract.template.tree/list/detail` | [`contract-template-selector.md`](references/contract-template-selector.md) |
+| 查条款分类 / 条款列表 / 条款组 / 条款搜索 / 条款标签 | `contract run contract.clause.tree/list/group.list/search/tags` | [`contract-clause-recommender.md`](references/contract-clause-recommender.md) |
+| 查合同文档已引用条款 | `contract run contract.clause.reference.get` | [`contract-clause-reference-save.md`](references/contract-clause-reference-save.md) |
+| 准备/确认把条款写入合同文档 | `contract run contract.clause.reference.save.prepare/apply` | [`contract-clause-reference-save.md`](references/contract-clause-reference-save.md) |
+| 解析 appId / objId / 字段 / 选项 | `contract run contract.subject.app/form/fields/options` | [`contract-signing-subjects.md`](references/contract-signing-subjects.md) |
+| 查询签约主体 | `contract run contract.subject.query` | [`contract-signing-subjects.md`](references/contract-signing-subjects.md) |
+| 准备/确认新建签约主体 | `contract run contract.subject.create.prepare/apply` | [`contract-subject-create.md`](references/contract-subject-create.md) |
+| 解析 workflowId / 表单字段 / 字段选项 | `contract run contract.workflow.query/list/form.info/field.options` | [`contract-workflow-discovery.md`](references/contract-workflow-discovery.md) |
+| 准备/确认创建合同流程实例 | `contract run contract.request.create.prepare/apply` | [`contract-request-write.md`](references/contract-request-write.md) |
+| 准备/确认保存合同表单 | `contract run contract.request.save.prepare/apply` | [`contract-request-write.md`](references/contract-request-write.md) |
+| 准备/确认提交合同审批 | `contract run contract.request.submit.prepare/apply` | [`contract-request-write.md`](references/contract-request-write.md) |
+| 准备/确认催办 | `contract run contract.request.supervise.prepare/apply` | [`contract-request-write.md`](references/contract-request-write.md) |
+| 查审批状态 / 签字意见 | `contract run contract.request.status/log` | [`contract-request-status.md`](references/contract-request-status.md) |
+| 企业资信、撤回/退回等未实现能力 | 无可用命令 | [`contract-disabled-capabilities.md`](references/contract-disabled-capabilities.md) |
+
+处理链：
+
+- 选模板：`contract.type.tree` -> `contract.template.tree`（取 `belongId`）-> `contract.template.list` -> 必要时 `contract.template.detail`
+- 推荐条款：`contract.clause.tags`（取 `tagId`）-> `contract.clause.tree`（取 `belongId`）-> `contract.clause.search` -> 展示候选名称、状态与推荐理由，**不伪造"智能评分"**
+- 引用条款：`contract.clause.reference.get` 查已引用 -> 用户确认具体条款、合同和文件 -> `contract.clause.reference.save.prepare` -> 用户确认 -> `contract.clause.reference.save.apply` -> 回查 `contract.clause.reference.get`
+- 签约主体：`contract.subject.app`（应用 Tag 固定 `合同管理`）-> `contract.subject.form`（按意图选 `我方签约主体库` / `客户签约主体库` / `供应商签约主体库`）-> `contract.subject.fields` / `contract.subject.options` -> `contract.subject.query` 或 `contract.subject.create.prepare/apply`
+- 发起合同审批：`contract.workflow.query` 或 `contract.workflow.list` 解析 `workflowId`（无需预先获取活动版本）-> `contract.workflow.form.info` 读字段 -> `contract.workflow.field.options` 把业务名称转成选项 ID -> `contract.request.create.prepare/apply` 取 `requestId` -> `contract.request.save.prepare/apply` -> **第二次确认** -> `contract.request.submit.prepare/apply` -> `contract.request.status` 回读 `flowStatus.code`
+
+## 执行原则（减少误路由、误重试和无效消耗）
+
+### 1) 环境相关 ID 必须运行时解析
+
+- `appId`、`objId`、`formId`、`workflowId`、`nodeId`、人员/选项/业务数据 ID 均为环境相关字符串，必须运行时解析
+- 未找到就停止并提示用户配置 Tag 或确认名称；**不使用标准环境 ID 兜底**
+- 同名流程返回多条时展示候选请用户选择或加 `status=1` 收敛，**不默认取第一条**
+- 名称匹配不到选项时展示候选请用户确认，**不得猜测 optionId**
+
+### 2) HTTP 200 不是业务成功的充分条件
+
+- 本组接口的成功码字段不统一：
+  - `/api/ebd/**`：顶层 `code = 0` 或 `code = 200` 均视为成功（实测 E10 10.0.9807.01 返回 `200` 且 `msg = "接口返回成功"`），同时要求 `status` 不为 false、`fail` 不为 true
+  - `/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`，同样视为成功）
+  - `/api/workflow/core/flowPage/**`、`/api/workflow/core/form/**`、`/api/ebuilder/flow/form/**`（表单三段式）：**没有 `message` 节点**，只有出现非 0/200 的 `errcode`、或 `fail=true` / `status=false` 才算失败；载荷包在 `data` 里
+- CLI 已按路径分组判定；Agent 仍需把"请求成功"与"业务生效"分开报告
+
+### 3) 写操作必须走 prepare -> apply 两段确认
+
+- 创建签约主体、引用条款、开启企业监控、创建/保存合同审批流程前，必须展示目标、关键字段和影响的脱敏摘要并获得明确确认
+- **提交合同审批和催办需要与"创建并保存"分开的第二次确认**
+- 提交后必须回读 `contract.request.status` 的 `flowStatus.code`（1 审批中 / 3 已归档）才算生效，不能只凭第一步返回就宣称"提交成功"
+- 创建流程 ≠ 保存表单 ≠ 提交审批，必须分别报告每一步结果，不得概括为"成功"
+
+### 4) 错误语义驱动，而不是盲目重试
+
+- 失败后先看退出码、`error.type`、`error.subtype` 和 `error.message`
+- 写请求超时或断线时不得盲目重试，先用查询接口确认是否已生效
+- `submitRequest` 返回 `1200301`（当前 userid 为空）：停止并诊断会话状态，不自动切换接口
+- `submitRequest` 返回 `1200306`（服务端必填校验）：解析缺失字段列表，逐字段补全后重试（最多 3 轮），不切换接口
+- 错误为 `authentication` 或 `session_expired` 时立即停止，先读取共享规则 `../weaver-e10-shared/references/e10-auth-and-session.md` 让用户完成登录
+
+### 5) 附件、图片和文件解析确认
+
+- 执行涉及合同正文、附件、本地文件或远程 URL 文件的步骤前，必须先提醒用户文件内容可能进入大模型上下文，也可能发送到 E10 今承达；用户未明确确认前不要运行。
+
+## 写操作失败处理：`partial/write_uncertain` 决策树
+
+当引用条款、新建签约主体、创建/保存/提交/催办返回 `partial/write_uncertain`，或提示网络中断、回查失败、回查状态不符时：
+
+1. **先停止盲目重试**，不要连续重复提交相同 `.apply`
+2. 优先从以下角度解释：写请求可能已到达服务端但连接在结果确认前中断；写接口已返回成功但回查失败或与预期不一致；continuation、目标对象或登录上下文可能已变化
+3. 如需确认，只补 **一次** 只读查询（`contract.request.status`、`contract.clause.reference.get`、`contract.subject.query`），不要陷入 query/write 循环
+4. 最终给用户明确结论、已知 `workflow.status`、成功/失败项和下一步人工确认建议
+5. 提交审批场景最容易因重复提交造成重复流转，必须严格执行上述规则
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli contract schema
+weaver-work-cli --json contract run contract.type.tree
+weaver-work-cli --json contract run contract.subject.app --input-json '{"tag":"合同管理"}'
+weaver-work-cli --json contract run contract.workflow.query --input-json '{"workflowName":"销售合同起草","status":"1"}'
+weaver-work-cli --json contract run contract.request.create.prepare --input-json '{"workflowId":"12345","requestname":"WB-SKILL-TEST 销售合同"}'
+weaver-work-cli --json contract run contract.request.create.apply --input-json '{"workflowId":"12345","requestname":"WB-SKILL-TEST 销售合同","continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+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.subject.app --input-json '{"tag":"合同管理"}'
+weaver-work-cli --json contract run contract.workflow.query --input-json '{"workflowName":"销售合同起草","status":"1"}'
+weaver-work-cli --json contract run contract.request.create.prepare --input-json '{"workflowId":"12345","requestname":"WB-SKILL-TEST 销售合同"}'
+weaver-work-cli --json contract run contract.request.create.apply --input-json '{"workflowId":"12345","requestname":"WB-SKILL-TEST 销售合同","continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+## 不在本 skill 范围
+
+- 禁止绕过本 skill 的命令面自行复刻旧版「今承达」接口文档里的裸调用，所有能力必须走 `weaver-work-cli contract`。
+- 禁止 curl、fetch、浏览器自动化或直接访问 E10 `/api/ebd/**`、`/api/ebuilder/**`、`/api/workflow/**`。
+- 禁止读取或复制 CLI runtime 内部 Token、Cookie、ETEAMSID；业务输入不得携带 `userid`、`token`、`cookie`、`eteamsid` 等字段，用户 ID 由 CLI 从会话注入。
+- 禁止读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。
+- 企业资信查询（CM-018）、企业变更、企业监控：源资料只有索引，子文档缺失，未实现。
+- 撤回/退回流程：源资料只提及接口存在，未给出路径与参数，未实现。

package/skills/weaver-e10-jinchengda/references/contract-agent-entry.md

@@ -0,0 +1,82 @@
+# 今承达合同管理 CLI 入口
+
+## 请求头 / 认证
+
+所有 `weaver-work-cli contract run <operation>` 发起的 API 请求均自动携带以下凭证头，值来自 E10 登录会话（由 `weaver-work-cli auth login` 建立），禁止业务输入携带：
+
+| 头 | 值来源 | 说明 |
+|---|---|---|
+| `Cookie` | E10 登录返回的完整原始 Cookie 串 | CLI 从会话注入，禁止裁剪/去重/改写 |
+| `eteamsid` | E10 登录返回的 ETEAMSID | CLI 从会话注入 |
+| `User-Agent` | `AgentType=<agentType>,IsAgent=true` | CLI 自动拼接，`agentType` 来自登录时的 `--agent_type` 参数 |
+
+业务输入（`--input-json` / `--input`）**不得包含** `userid`、`userId`、`token`、`cookie`、`eteamsid` 等字段，用户 ID 由 CLI 从会话注入。
+
+## operation 合约第一信息源
+
+`weaver-work-cli contract schema` 输出 operation 名称、`risk`、`fixed`（固定的方法与路径）、`inputSchema` 和 `withheldOperations`。调用前先读它，不要凭记忆拼 operation 名和字段名。
+
+- operation 名称统一为 `contract.<domain>.<action>`。
+- 写操作一律是 `*.prepare` -> `*.apply` 两段：`prepare` 返回脱敏 `preview` 和 `continuation`，`apply` 必须带 `continuation` 与 `confirm: true`。
+- `inputSchema` 的 `additionalProperties` 为 `false`，未声明的字段会被拒绝。
+- `withheldOperations` 列出源资料不足、暂未实现的能力，遇到对应意图直接说明不可用，不要尝试用其它接口替代。
+
+## 统一调用方式
+
+所有 operation 都通过 `contract run <operation>` 调用。三种输入方式：
+
+1. `--input-json '<json>'`：简单 JSON，推荐。
+2. `--input <path>`：复杂或多行 JSON，先写入 UTF-8（无 BOM 也可，CLI 会自动剥离 BOM）文件。
+3. `--input -`：stdin，只有确认当前 shell 能稳定传管道时才使用。
+
+`--input` 与 `--input-json` 不能同时传，同时传会返回 `validation/input_conflict`。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli contract schema
+weaver-work-cli --json contract run contract.template.list --input-json '{"templateName":"采购合同","pageNo":1,"pageSize":10}'
+weaver-work-cli --json contract run contract.request.status --input-json '{"requestId":"12345"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli contract schema
+weaver-work-cli --json contract run contract.template.list --input-json '{"templateName":"采购合同","pageNo":1,"pageSize":10}'
+weaver-work-cli --json contract run contract.request.status --input-json '{"requestId":"12345"}'
+```
+
+## 人类友好子命令
+
+除了 `run`，CLI 也提供分组子命令（参数会转成对应的 operation 输入），可用于排查和手工操作：
+
+- `contract type tree`
+- `contract template tree|list|detail`
+- `contract clause tree|list|groups|search|tags`
+- `contract clause reference get|save-prepare|save-apply`
+- `contract subject app|form|fields|options|query|create-prepare|create-apply`
+- `contract workflow query|list|form-info|field-options`
+- `contract request create-prepare|create-apply|save-prepare|save-apply|submit-prepare|submit-apply|supervise-prepare|supervise-apply|status|log`
+
+Agent 侧优先用 `run <operation>`，保证输入与 manifest 完全一致。
+
+## 退出码
+
+| 退出码 | 含义 |
+|---|---|
+| 0 | 成功 |
+| 1 | 业务/服务错误 |
+| 2 | 输入用法错误（含 ID 非法、字段非法） |
+| 3 | 认证失败或登录态失效 |
+| 4 | 网络错误 |
+| 5 | 内部错误 |
+| 6 | 策略拒绝（重复引用、流程状态不允许等） |
+| 10 | 需要确认（缺少 `confirm` 或 continuation） |
+| 11 | `partial/write_uncertain`，结果不确定，禁止自动重试 |
+
+## 注意
+
+- 业务输入不得包含 `userid`、`userId`、`token`、`cookie`、`eteamsid` 等字段；用户 ID 由 CLI 从会话注入。
+- 环境相关 ID（`appId`、`objId`、`formId`、`workflowId`、`nodeId`）只能运行时解析，禁止使用文档示例值或标准环境 ID 兜底。
+- 涉及合同正文或附件的操作，文件内容可能进入大模型上下文，执行前必须获得用户明确确认。

package/skills/weaver-e10-jinchengda/references/contract-clause-recommender.md

@@ -0,0 +1,69 @@
+# 条款查询与推荐
+
+## 请求头 / 认证
+
+本文件描述的 API 请求通过 `weaver-work-cli` 执行，CLI 从 E10 登录会话自动注入以下凭证头（禁止业务输入携带）：
+
+| 请求头 | 值 |
+|--------|-----|
+| `Cookie` | `<e10-login 返回的完整原始 Cookie 串>`（禁止裁剪/去重/改写） |
+| `eteamsid` | `<e10-login 返回的 ETEAMSID>` |
+| `User-Agent` | `AgentType=<agentType>,IsAgent=true` |
+
+业务输入（`--input-json` / `--input`）**不得包含** `userid`、`userId`、`token`、`cookie`、`eteamsid` 等字段，用户 ID 由 CLI 从会话注入。
+
+
+用途：按标签、分类或关键词查找合同条款，供用户挑选。五个 operation 全部为 `read`。
+
+## operation 与接口
+
+| operation | 方法 | 路径 | 关键输入 |
+|---|---|---|---|
+| `contract.clause.tags` | GET | `/api/ebd/contract/clauseinfo/getClausesConfig` | `label`、`value`、`pageNum`、`pageSize` |
+| `contract.clause.tree` | GET | `/api/ebd/contract/tree/queryList` | 无（无需传参） |
+| `contract.clause.search` | GET | `/api/ebd/contract/clauseinfo/getClauses` | `id`、`title`、`tagId`、`content`、`group`、`mark`、`pageNum`、`pageSize` |
+| `contract.clause.list` | GET | `/api/ebd/contract/clauseinfo/getListPage` | `belongId`、`clauseName`、`clauseNum`、`clauseStatus`、`clauseGroup`、`contractType`、`pageNo`、`pageSize` |
+| `contract.clause.group.list` | GET | `/api/ebd/contract/clausegroup/getListPage` | `belongId`、`clauseName`、`clauseNum`、`clauseStatus`、`contractType`、`pageNo`、`pageSize` |
+
+分页参数命名差异（源资料原文，不要统一）：
+- `contract.clause.list` / `contract.clause.group.list` 用 `pageNo`（默认 1）+ `pageSize`（默认 10）。
+- `contract.clause.search` / `contract.clause.tags` 用 `pageNum`（默认 **0**）+ `pageSize`（默认 10）。
+
+## 处理链
+
+1. `contract.clause.tags` 是**语义匹配的关键前置接口**，先拿 `tagId`。
+2. `contract.clause.tree` 拿条款分类树，取 `belongId`。
+3. `contract.clause.search` 是核心查询接口，传 `tagId`、`title` 或 `content`。
+4. 需要按分类浏览时用 `contract.clause.list`；需要按条款组浏览时用 `contract.clause.group.list`。
+
+## 调用示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json contract run contract.clause.tags --input-json '{"pageNum":0,"pageSize":10}'
+weaver-work-cli --json contract run contract.clause.tree
+weaver-work-cli --json contract run contract.clause.search --input-json '{"tagId":"12345","title":"违约金","pageNum":0,"pageSize":10}'
+weaver-work-cli --json contract run contract.clause.list --input-json '{"belongId":"12345","pageNo":1,"pageSize":10}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json contract run contract.clause.tags --input-json '{"pageNum":0,"pageSize":10}'
+weaver-work-cli --json contract run contract.clause.tree
+weaver-work-cli --json contract run contract.clause.search --input-json '{"tagId":"12345","title":"违约金","pageNum":0,"pageSize":10}'
+weaver-work-cli --json contract run contract.clause.list --input-json '{"belongId":"12345","pageNo":1,"pageSize":10}'
+```
+
+## 结果解读
+
+- 成功码为顶层 `code = 0`。
+- 展示候选时给条款名称、状态和推荐理由；**不伪造"智能评分"**。
+- 命中多条时先展示候选请用户选择，不要把第一条当成唯一答案。
+- 标签 ID、分类 ID、条款 ID 均为环境相关字符串，必须运行时解析。
+
+## 注意
+
+- 只做查询和推荐，不写入。要把条款真正插入合同文档，必须先走 [`contract-clause-reference-save.md`](contract-clause-reference-save.md) 的确认链。
+- 推荐前先用 `contract.clause.reference.get` 查已引用条款，避免推荐用户已经插入过的条款。