weaver-work-cli 0.1.8 → 0.1.21

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

@@ -4,12 +4,15 @@
 
 按名称/编号/上级组织查分部（subcompany）与部门（department）、按组织节点 id 取详情、按多级路径逐级收敛查询时使用。全部为只读操作。
 
+若用户给的是「**多维名称 + 部门/分部名称**」（例如「1号维度下的第一团队」），**不要**自己先查维度再查组织——直接用 `hrm.org.resolve` 一次调用（见本文末尾「多维解析」）。
+
 ## 输入要点
 
 | operation | 必填 | 说明 |
 | --- | --- | --- |
 | `hrm.org.query` | 至少一个收敛条件 | 按名称/编号/上级组织查询组织（`type` 区分分部/部门） |
-| `hrm.org.detail` | `id` | 按组织节点 id 取详情表单（类型由服务端自动判断，含全路径与人员统计） |
+| `hrm.org.detail` | `id` | 按组织节点 id 取组织详情（类型由服务端自动判断，含全路径 `fullPath`、上级部门名、所属分部名；**不含人员统计**） |
+| `hrm.org.resolve` | `virtual` + `name` | 多维名称 + 部门/分部名称 → 解析组织（精确优先/包含模糊兜底/近似只提示，歧义回候选） |
 
 ### `hrm.org.query` 关键字段
 
@@ -21,7 +24,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` 选用，不要混用。
 
@@ -65,6 +68,106 @@ weaver-work-cli --json hrm run hrm.org.query --input-json '{"subcompany":["10000
 weaver-work-cli --json hrm run hrm.org.detail --input-json '{"id":"1000000000000000101"}'
 ```
 
+## 多维解析（`hrm.org.resolve`）
+
+> 多维清单（维度名 + id）**不单独暴露成 operation**，全部由 `hrm.org.resolve` 内部获取与处理：匹配时用它、不存在时把 `availableVirtuals` 随结果回给用户。
+
+### 为什么需要它
+
+E10 组织树按**多维**（虚拟组织维度）切分：「行政组织」是真实组织树，其余是各业务维度（「1号维度」「备份维度」…）。**同名部门/分部在不同维度下是不同节点**，浏览接口 `department`/`subcompany` 不带 `companyId` 时会**默认落到「行政组织」维度**（实测：按名称查到的 `virtualid` 全是 `1`）。所以「按名称找部门」必须先定位多维 id，再以 `companyId` 收敛。
+
+这段编排（取维度 → 匹配维度名 → 取多维 id → 带 `companyId` 查组织 → 匹配组织名）**已全部实现在 CLI 内**，Agent **只调一次 `hrm.org.resolve`**，不需要自己分两步推理（也不存在"先列维度再查组织"的第二步可用）。
+
+### 入参
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `virtual` | 首调必填 | 多维名称（如 `行政组织` / `1号维度`）；精确优先，未命中按**包含**模糊匹配 |
+| `name` | 首调必填 | 部门或分部名称；精确优先，未命中按**包含**模糊匹配 |
+| `type` | 否 | `department` 部门 / `subcompany` 分部；**不传时同时检索两者、按部门优先定位**，并把同名另一类型节点回在 `alsoMatched` |
+| `virtualId` | 复调用 | 多维 id（长整型字符串）；用户确认后复调直接传，跳过维度名称匹配 |
+| `orgId` | 复调用 | 组织节点 id（长整型字符串）；用户确认后复调直接传，跳过名称匹配（改走组织详情） |
+| `maxCandidates` | 否 | 歧义时最多回传的候选条数，**1~200，默认 20**；超限抛 `number_invalid` |
+
+首调至少要有 `virtual` + `name`；只给 `virtualId` + `orgId` 也可以（纯 id 定位）。缺 `virtual`/`virtualId` 抛 `virtual_required`，缺 `name`/`orgId` 抛 `name_required`。
+
+### 匹配规则（两级同名匹配，三级判定）
+
+名称匹配分**三级**，它们的「能否自动往下走」完全不同：
+
+| 级别 | 判定方式 | CLI 行为 |
+| --- | --- | --- |
+| ① 精确 | 忽略大小写与多余空白的**全等**（服务端条件 `eq`/等于） | 唯一 → 继续；多个 → `ambiguous` |
+| ② 包含（模糊） | 名称是关键字**子串**（服务端条件 `in`/包含）；返回行再做一次客户端「忽略大小写全等」优先，兜住服务端 `eq` 漏判（全角/空格差异） | 唯一 → 继续；多个 → `ambiguous` |
+| ③ **近似** | 编辑距离阈值内（`相似度 ≥ 0.6`，只认**打字/口误级**差异，如「客服维度」→「客户维度」） | **只回 `suggestions` + `status: not_found`，绝不自动继续** |
+
+- ①② 属于系统收敛，命中即可往下走；③ **绝不参与解析**，只能作为「是不是指这个？」的提示交回用户。
+- 维度级：③ 在**本地全量维度清单**上算相似度（`listCompanyVirtual` 一次返回全部）。
+- 组织级：③ 用「关键字**末 2 字 / 首 2 字**」各做一次包含查询（≤2 次，中文名后缀信息量最大：经理/部/科/中心…），命中即作为 `suggestions` 回传。
+- 未命中且无近似项时，组织级回 `availableVirtuals`（仅维度级）或提示补充关键字。
+
+### 结果契约（🔴 只看 `data.status`，不要只看 `ok`）
+
+三种结果都是 `ok: true`、退出码 `0`：
+
+| `data.status` | 附带字段 | Agent 该做什么 |
+| --- | --- | --- |
+| `resolved` | `org`（`id`/`name`/`type`/`fullPath`/`parentPath`/`parentId`/`subcompanyId`/`virtualId`/`virtualName`/`link` 等）、`virtual`、`matchType`（`exact`/`fuzzy`/`id`）；不传 `type` 且存在**同名另一类型**节点时另回 `alsoMatched[]` | 直接用 `org` 回答，按 `[名称](link)` 呈现；**有 `alsoMatched` 时必须一并告知用户**（如同一客户下既有同名部门又有同名分部） |
+| `ambiguous` | `stage`（`virtual`=多维歧义 / `org`=组织歧义）、`virtual`、`candidates[]`、`candidateTotal`、`truncated`、`message` | **停下问用户**：把 `candidates` 列表（名称 / `fullPath` / link）给用户选，**禁止自动取第一条** |
+| `not_found` | `stage`、`virtual`、`suggestions[]`/`suggestionTotal`（近似名称）、`availableVirtuals`（`stage=virtual` 时）、`message` | **原样转述给用户**（含"不存在"这一事实 + 近似名称 + 可用多维），**禁止自行替换名称后重试**；用户确认后再用 `virtualId`/`orgId` 复调 |
+
+- `candidates` 每项为 `{id, name, type, fullPath, code?, link}`；**默认最多 20 条**，`truncated: true` 表示还有更多。`candidateTotal` 是服务端匹配总数（模糊时可能大于所列条数）。
+  - 要把候选一次列全：用 `maxCandidates` 复调（1~200），如 `{"virtual":"客户维度","name":"客户经理","maxCandidates":100}` → `candidateTotal: 29, truncated: false`。上游浏览分页会同步放宽到 `max(100, maxCandidates)`，因此上限 200 内都能取全。
+- **`suggestions`（`not_found` 才可能出现）**：近似名称，**最多 5 条**；维度级每项 `{id, name}`，组织级每项与 `candidates` 同结构。`suggestionTotal` 为该级近似匹配总数（组织级来自宽松探测）。
+  - 🔴 **它只是给用户看的提示，不是给 Agent 用的参数**：不得据此改名重试，也不得因此省略「用户给的名称不存在」这一事实。
+  - 实测：`{"virtual":"客服维度","name":"云桥测试"}` → `not_found` + `suggestions: [{id:"100001569000010000", name:"客户维度"}]` + 5 个可用多维；正确回复是「本租户没有『客服维度』，最接近的是『客户维度』，要用它继续查吗？」，而**不是**直接返回客户维度下的结果。
+- `fullPath` 含多维名并逐级到本节点（如 `1号维度/超级组织66/第一团队`），同名不同层级靠它区分。
+  - ⚠️ **不同租户上游的层级分隔符不一致**（实测：木林泉用 `/`、泛微网络租户的 `supDepartment` 用 `|`）；CLI 已统一归一化为 `/`，所以 `fullPath`/`parentPath` 跨环境格式一致。需要精确定位时用 `id`/`parentId`，不要反解析字符串。
+  - 直属多维根节点的候选 `fullPath` 就是名称本身（无上级路径），可用于识别「标准节点 vs 各客户下的同名子节点」。
+- **`alsoMatched`（resolved 才可能出现）**：不传 `type` 时，若同一多维下**既有一个同名部门、又有一个同名分部**，本操作不会静默二选一 —— 按部门优先给出 `org`，同时把另一类型节点放进 `alsoMatched`（结构与 `candidates` 相同，含 `id`/`type`/`fullPath`/`link`），并在 `message` 里提示。**Agent 必须把两者都告诉用户**，用户要另一个就用它的 `id` 当 `orgId` 复调（或显式传对应 `type`）。要避免这种双命中，直接在首调传 `type`。
+
+### 用户确认后的复调
+
+把候选的 `id` 作为 `orgId` 传回；若是**多维**歧义（`stage: "virtual"`），把维度的 `id` 作为 `virtualId` 传回：
+
+```powershell
+weaver-work-cli --json hrm run hrm.org.resolve --input-json '{"virtual":"1号维度","name":"第一团队","orgId":"9163142909607938"}'
+```
+
+`not_found` 时若用户**确认**了 `suggestions` 里的近似名称，同样复调：维度近似 → 传 `virtualId`；组织近似 → 传 `orgId`（或按用户确认后的准确名称重查一次）。**但确认之前绝不能自己走这一步。**
+
+复调一次即定位，**不要再用名称反复重试**。
+
+### 命令示例
+
+首调（多维名称 + 部门名称；分部同理，传 `"type":"subcompany"` 或省略让它自动识别）：
+
+```powershell
+weaver-work-cli --json hrm run hrm.org.resolve --input-json '{"virtual":"1号维度","name":"第一团队"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+printf '%s\n' '{"virtual":"1号维度","name":"第一团队"}' | weaver-work-cli --json hrm run hrm.org.resolve --input -
+```
+
+多维名不存在时（自动给出近似名称 + 该租户全部多维，不自动继续）：
+
+```powershell
+weaver-work-cli --json hrm run hrm.org.resolve --input-json '{"virtual":"客服维度","name":"云桥测试"}'
+```
+
+### 注意
+
+- 覆盖关系：`hrm.org.resolve` 是「多维 + 名称」的**一步到位**入口；已有明确收敛条件（编号 `code`、上级组织 id 等）或已知组织 id 时，仍用 `hrm.org.query` / `hrm.org.detail`。
+- 多维清单来自 `/api/bs/hrm/companyVirtual/listCompanyVirtual`（一次返回全量，无分页）；`行政组织` 也在清单里（id 为 `1`）。
+- 🔴 **「列多维」暂不支持，且不暴露入口**：`hrm.org.virtuals` 已下线（`hrm schema --full` 的 `withheldOperations` 中有声明），Agent 拿不到独立的维度清单接口。
+  - `not_found.availableVirtuals` 是**纠错辅助**（用户给的名字对不上时，顺手告知本租户有哪些维度），不是列维度能力——**不要故意构造一个不存在的维度名去套它**。
+  - 用户明确问「这个租户有哪些多维」→ 直接回答**暂不支持**，请其改用「维度名 + 组织名」查询。
+  - 维度 id 的唯一来源：`not_found.availableVirtuals`（全量）或维度歧义时的 `candidates`。
+- 名称匹配不做拼音/别名/简称展开（`shortname` 只回显不参与匹配）。
+
 ## 多级路径查询（drill-down 编排）
 
 路径形如 `总部/研发部/产品组`，逐级用「父节点 id 作为上级条件 + 下一段名称」调用 `org.query`：
@@ -76,8 +179,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` 已转多语言，直接呈现。
 
 ## 注意
 
@@ -85,11 +191,14 @@ weaver-work-cli --json hrm run hrm.org.detail --input-json '{"id":"1000000000000
 - 分部与部门是两个不同接口（`browser/data/subcompany` 与 `browser/data/department`），CLI 用 `type` 区分；不传 `type` 默认查部门。
 - `org.detail` 详情查询**只需传 `id`**，服务端按记录自动判断分部/部门，无需传 `type`。
 - 组织节点 id 是长整型，按字符串传递。
-- 浏览按钮行含 `title`（`名称|全路径`），可直接用于路径确认/重建。
+- 浏览按钮行含 `title`（`名称|上级路径`），行上另有 `supDepartment`（部门）/ `supSubDepartment`（分部）给同一信息；本节点全路径由 CLI 合成在 `fullPath`（`上级路径/名称`）。
+- `hrm.org.resolve` 的行内字段还含 `virtualid`（所属多维 id）、`subcompanyid`（所属分部 id）、`hasSub`（是否有下级），已投影进 `org`。
 
 ## 失败处理
 
 - `empty_condition`：空条件拉取被拦截，先询问用户补条件。
 - `enum_invalid`：`type` 取值非法（仅 `subcompany`/`department`）。
 - `permission_denied`（`code=403`）：HRM 读接口开关未开启，提示用户联系管理员开启。
+- `virtual_required`/`name_required`：`hrm.org.resolve` 少传了多维（`virtual`/`virtualId`）或名称（`name`/`orgId`）。
+- **「未找到 / 命中多个」不是错误**：`hrm.org.resolve` 仍 `ok: true`、退出 0，按 `data.status` 分派（`not_found` / `ambiguous`），不要当异常重试。
 - 认证类错误：引导用户执行 `weaver-work-cli auth login`。

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,167 @@
+---
+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 不能在未确认时自行安装。用户明确确认后，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`——省略会装进默认目录，导致本技能依然读不到共享规则。命令均成功后重新读取共享规则；仍读不到就停止并把结果报告用户，不得凭猜测继续。**
+**`--is-connector` 判据**：用户明确使用连接器、或上下文要求用连接器完成任务 → 传 `true`；本次任务或上下文直接选择单独技能 → 不传；用户没有明确说明时，按**正在运行的这份 Skill 是哪一级**定——**用户级（条目标 `(user)`）不传，连接器级（标 `(connector)`）传**（同名 Skill 只会运行用户级那一份）。传 `true` 时不要再写 `--profile` / `--base-url`。完整规则见 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)。
+认证和登录态只能按共享规则通过 `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）、企业变更、企业监控：源资料只有索引，子文档缺失，未实现。
+- 撤回/退回流程：源资料只提及接口存在，未给出路径与参数，未实现。