weaver-work-cli 0.1.8 → 0.1.21

package/skills/weaver-e10-caizhilian/references/withheld.md

@@ -0,0 +1,93 @@
+# 采知连：明确不提供的能力（withheld）与源 Skill 范围外模块
+
+## 何时使用
+
+- 用户要求「列一下有哪些环境 / 看看当前配置 / 重新加载配置 / 切换到测试环境」这类源 Skill 的系统管理能力。
+- 用户拿着源 Skill（`weaver-e10-caizhilian` 1.1.17）的 operation 名来调用，但 CLI 里没有对应 operation。
+- `caizhilian operations` 的 `withheldOperations` 里给出了名称与理由，需要向用户解释替代方案。
+
+## 输入要点
+
+### 4 个 withheld 系统操作
+
+源 `scripts/system_plugins.py` 的这 4 个插件**没有**转换成 CLI operation。原因都是同一个：它们操作的是源 Skill 自带的 `assets/config.json` 多环境配置与本地登录态缓存，而在 weaver-work-cli 里，环境、配置与登录态由框架统一管理，业务模块不得自建一套。
+
+| 源 operation |  withheld 名称 | 不提供的原因 | 替代命令 |
+| --- | --- | --- | --- |
+| `list_systems` | `caizhilian.system.list-systems` | 读取 Skill 自带 config.json 的多环境列表与登录态 | `weaver-work-cli config list`、`weaver-work-cli e10 auth status`；连通性自检用 `weaver-work-cli --json caizhilian health` |
+| `get_loaded_config` | `caizhilian.system.get-loaded-config` | 输出 Skill 本地配置生效内容（含 cookies 掩码、下载目录） | `weaver-work-cli config list`；不在业务模块内暴露配置快照 |
+| `reload_config` | `caizhilian.system.reload-config` | 重新加载 Skill 本地 config.json | 无需替代：CLI 每次进程启动即读取框架配置，没有进程内缓存需要刷新 |
+| `switch_config` | `caizhilian.system.switch-config` | 在 Skill 本地多套环境配置间切换 | `weaver-work-cli config set ...`、`weaver-work-cli e10 auth login --base-url <域名>` |
+
+只保留了 `caizhilian.system.health`（源 `check_system_health`）：探测 `/api/doc/config/getUserConfiguration?configKeys`，返回 `{ environment, healthy, base_url, url, status_code, business_code, diagnosis, elapsed_ms }`，其中 `environment.provider` 固定为 `weaver-work-cli:e10-auth`；本地无登录态时抛 `authentication/session_unavailable`。
+
+### 源 Skill 目录内的已补充模块
+
+以下模块已补充到 caizhilian CLI 中：
+
+| 源模块 | CLI 操作 | 说明 |
+| --- | --- | --- |
+| 系统设置-附件 | `caizhilian.setting-attach.get` / `.set.prepare` / `.set.apply` | 附件全局设置（上传最大、格式控制、批量下载等 11 项） |
+| 系统设置-备份 | `caizhilian.setting-backup.get` / `.set.prepare` / `.set.apply` / `.rule.*` | 备份设置（开关、规则 CRUD、启停） |
+| 系统设置-加密 | `caizhilian.setting-encrypt.get` / `.set.prepare` / `.set.apply` | 加解密设置（8 项配置） |
+| 系统设置-存储 | `caizhilian.setting-storage.instance.*` / `.rule.*` | 存储实例与规则管理 |
+| 文件收集 | `caizhilian.file-collection.task.*` / `.scan.*` / `.run.*` / `.cancel.*` / `.delete.*` | FTP/SFTP 文件采集任务管理 |
+| 文件上传 | `caizhilian.file-upload.contract` / `.prepare` / `.upload.prepare` / `.upload.apply` | 本地文件上传到文件服务 |
+
+### 源基础设施脚本的处理方式
+
+源的通用基础设施不是业务 operation，已按 weaver-work-cli 的框架能力**等价替换**，不单独暴露：
+
+| 源文件 | 处理方式 |
+| --- | --- |
+| `scripts/cli.py`、`scripts/engine.py`、`scripts/plugin_base.py` | 由 `src/shortcuts/caizhilian/index.ts` + `operations/registry.ts` 承担（命令注册、operation 分派、prepare/apply 展开） |
+| `scripts/http_client.py` | 由 `src/shortcuts/caizhilian/host.ts` + 框架 E10 HTTP client 承担（Cookie/ETEAMSID/User-Agent 注入、超时、重试、下载流处理） |
+| `scripts/_session_helper.py`、`scripts/environment_provider.py`、`scripts/cache_manager.py`、`.cache/` | 由框架登录态管理承担（`weaver-work-cli e10 auth ...`）；业务模块不读写登录缓存 |
+| `scripts/_utils.py`、`scripts/_plugin_helpers.py` | 直译进 `operations/shared.ts`、`operations/files.ts`、`operations/api.ts`（文件元数据、上传下载、Python 语义小工具） |
+| `scripts/response_templates.py` | 输出归一逻辑直译进各 handler（`users[]` / `departments[]` / `documents[]` 等键名与字段） |
+| `scripts/reply_lint.py`、`scripts/collection_lint_skill.py` | 属于源 Skill 的回复与 Skill 自检工具，不在业务 CLI 范围 |
+| `doc-business-orchestrations/*.json` | 编排建议已落进各 reference 的「典型链路」，不作为可执行 operation 暴露 |
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli caizhilian operations
+weaver-work-cli --json caizhilian health
+weaver-work-cli config list
+weaver-work-cli e10 auth status
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli caizhilian operations
+weaver-work-cli --json caizhilian health
+weaver-work-cli config list
+weaver-work-cli e10 auth status
+```
+
+`caizhilian operations` 的返回里带 `withheldOperations`，每项是 `{ name, reason }`，可以直接把 `reason` 转述给用户。
+
+## 输出处理
+
+- 用户点名要 withheld 能力时：**不要报「做不到」就结束**，要给出上表里的替代命令，并说明「环境与登录态由 weaver-work-cli 框架统一管理」。
+- 用户拿源 operation 名（如 `create_html_document`、`search_documents`）来调用时，用 `caizhilian operations` 的 `sourceOperation` 字段反查 CLI operation 名（如 `caizhilian.document.create-html.prepare` / `.apply`），再按 `write-protocol.md` 走确认链。
+- `caizhilian health` 的 `diagnosis` 字段是逗号分隔的判定项：`ok`、`network_error`、`http_error`、`http_status_mismatch`、`business_code_mismatch`、`request_failed`。非 `ok` 时把 `status_code`、`business_code`、`elapsed_ms` 一起给用户。
+
+## 注意
+
+- 不要为了让用户满意而**临时补出** withheld 操作，也不要用 curl / 脚本绕过 CLI 去读框架配置或登录态。
+- 不要读取、列出、打印或解析 CLI runtime 内部的登录凭据文件；认证相关一律通过 `weaver-work-cli auth` / `weaver-work-cli e10 auth` 命令。
+- 源 Skill 范围外模块的能力**不要**用 caizhilian 的 operation 去近似模拟（例如用附件上传去替代「附件全局设置」）。
+- 如果用户确实需要范围外模块，回复「需要按 skill-maker 单独生成对应模块 CLI 与 Skill」，不要在本模块里扩权。
+
+## 失败处理
+
+| error.type / subtype | 触发场景 | 处理 |
+| --- | --- | --- |
+| `validation/operation_unknown` | 调用了 withheld 或范围外的 operation 名 | 用 `caizhilian operations` 校对，按本文件的替代命令回复用户 |
+| `authentication/session_unavailable` | `caizhilian health` 时本地无登录态 | 引导用户执行 `weaver-work-cli e10 auth login`，不要猜域名 |
+| `api/http_error` / `api/business_error` | health 探测返回非成功码 | 把 `diagnosis`、`status_code`、`business_code` 交给用户 |
+| `network/*` | health 探测网络失败 | `retryable=true` 时最多重试一次 |

package/skills/weaver-e10-caizhilian/references/write-protocol.md

@@ -0,0 +1,120 @@
+# 采知连写操作确认协议（prepare → apply）
+
+## 何时使用
+
+- 要执行任何**会产生服务端副作用**的操作：创建/修改文档、替换正文、改作者、文件夹创建、权限与默认共享增删改、标签增删、参与人增删、共享增删、附件上传替换、封面设置移除、比对文件上传与提交。
+- 收到 `confirmation/required` 或任何 `continuation_*` / `plan_changed` 报错，需要判断下一步。
+- 写操作结果不确定（超时、连接中断、返回结构异常），需要决定「查一次还是重放」。
+
+## 输入要点
+
+### 四步链路
+
+1. **只读定位**：先用查询类操作拿到真实 ID 与合法枚举值（`document.search` / `document.get` / `folder.query-by-name` / `*.form` / `*.list` / `org.search-*`）。ID 一律不要猜。
+2. **prepare**：`weaver-work-cli --json caizhilian run <name>.prepare --input-json '<json>'`。这一步**不产生副作用**，只做只读回查、组装请求体、计算指纹，并签发 `continuation`。
+3. **向用户摘要并取得明确确认**：必须写清「对哪个对象（名称 + ID）、做什么、影响范围、是否可撤销」。涉及本地文件时还要写清文件路径、文件名、大小。用户没有明确同意，不得进入第 4 步。
+4. **apply**：`weaver-work-cli --json caizhilian run <name>.apply --input-json '<与 prepare 完全相同的 json>' --continuation TOKEN --yes`。`--yes` 会注入 `confirm: true`，`--continuation` 注入票据。
+
+### 票据（continuation）约束
+
+- 有效期 **10 分钟**（`expires_in_ms`），过期报 `continuation_expired`，必须重新 prepare。
+- 票据里绑定了 **baseUrl + 登录账号**：换环境或换账号后复用会报 `continuation_context_mismatch`。
+- 票据绑定 **目标 apply 操作名**：把 A 操作的票据用于 B 操作报 `continuation_mismatch`。
+- 票据里存了 prepare 时的**入参指纹**（排除 `confirm` / `continuation`）：apply 入参与 prepare 不一致报 `continuation_args_changed`；关键字段（如 `doc_id`）单独漂移报 `continuation_target_changed`。
+- 票据里还存了**请求体指纹**与（文件类）**文件 MD5 + 大小**：表单级联结果变化报 `plan_changed`，本地文件被改动报 `file_changed`。
+- 票据签名校验失败或无法解析报 `continuation_invalid`；缺失报 `continuation_required`；apply 未带 `--yes` 报 `confirmation/required`（`error.type = "confirmation"`）。
+- 结论：**apply 的 `--input-json` 必须与 prepare 逐字一致**。要改任何参数，就重新走一遍 prepare，不要「改一个字段再 apply」。
+
+### prepare 返回体
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "operation": "caizhilian.folder.create.prepare",
+  "data": {
+    "request": { "method": "POST", "path": "/api/doc/folder/create", "body": {} },
+    "continuation": "TOKEN",
+    "expires_in_ms": 600000,
+    "hint": "确认无误后调用 caizhilian.folder.create.apply（必须回传本次 continuation 且 confirm=true，CLI 加 --yes）"
+  },
+  "meta": { "status": "PREPARED", "requiresConfirmation": true, "expires_in_ms": 600000 },
+  "warnings": []
+}
+```
+
+`warnings` 是 prepare 阶段的非阻断提醒（例如共享兜底覆盖了文件夹兜底、参与人已在列表中、待删条目已消失），**必须原样转述给用户**，不要静默丢弃。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.prepare --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"C:\data\weekly.md"}'
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.apply --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"C:\data\weekly.md"}' --continuation TOKEN --yes
+weaver-work-cli --json caizhilian run caizhilian.share.add.prepare --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}'
+weaver-work-cli --json caizhilian run caizhilian.share.add.apply --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}' --continuation TOKEN --yes
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.prepare --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"/tmp/data/weekly.md"}'
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.apply --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"/tmp/data/weekly.md"}' --continuation TOKEN --yes
+weaver-work-cli --json caizhilian run caizhilian.share.add.prepare --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}'
+weaver-work-cli --json caizhilian run caizhilian.share.add.apply --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}' --continuation TOKEN --yes
+```
+
+## 输出处理
+
+- prepare 成功：把 `data` 里的请求预览翻译成**人话摘要**（对象、动作、范围、可撤销性），连同 `warnings` 一起给用户，然后等确认。不要把 `continuation` 当业务结果展示，也不要截断或改写它。
+- apply 成功：`data` 是服务端返回的业务结果（新文档 ID、新文件夹 ID、上传后的 `file_id`、共享列表等）。摘要关键 ID 与名称，并说明「已生效」。
+- apply 失败：按 `error.type` / `error.subtype` 判断。**只要错误发生在请求已发出之后，一律不得自动重放**。
+- 多步写入（`cover.set` = 上传 + 改字段、`document.replace-content` = 上传 + 替换 + 通知、`document.create-by-upload` = 批量上传）失败时，先看 `data.summary` 与 `warnings` 判断已完成到哪一步，再决定是否需要人工在 E10 页面复核。
+
+## 写结果不确定的决策树
+
+出现「请求已发出但结果未知」的情形（网络超时、连接被重置、`response_shape` / `empty_response`、进程被中断），按顺序执行：
+
+1. **立即停止**，不要重试同一个 apply，也不要用同一个 `continuation` 再跑一次。
+2. **最多做一次只读回查**确认实际状态：
+   - 文档创建 → `caizhilian.document.search`（按名称 + `folder_id` + 创建时间）
+   - 文档字段/正文/作者 → `caizhilian.document.get`
+   - 文件夹 → `caizhilian.folder.query-by-name`
+   - 权限/默认共享 → `caizhilian.folder.permission.list` / `caizhilian.folder.default-share.list`
+   - 标签/参与人/共享 → `caizhilian.tag.list` / `caizhilian.participant.list` / `caizhilian.share.list`
+   - 附件/比对文件 → `caizhilian.compare.list-file-objects`
+3. **回查结果二选一**：
+   - 已生效 → 告知用户「操作已成功」，不再重放。
+   - 未生效 → 告知用户失败原因，**重新 prepare**（拿新票据）后再由用户确认执行；不要复用旧票据。
+4. 回查本身也失败 → 停止，把原始错误交给用户，建议在 E10 页面人工核对。
+
+> 说明：`partial/write_uncertain` 是错误分类里保留的「写结果不确定」类型；采知连模块当前把批量与多步写入的部分失败通过 `warnings` + `data.summary` 表达，遇到上述网络类不确定情形时按本节决策树处理。
+
+## 注意
+
+- **绝不允许跳过 prepare 直接 apply**，也不允许由 Agent 自行编造 `continuation`。没有票据就没有写权限。
+- `--yes` 只能在**用户已经明确同意**之后使用。用户说「先看看」或没有回应，都等于未确认。
+- 删除类操作（`folder.default-share.delete`、`folder.permission.delete`、`share.delete`、`participant.remove`、`tag.remove`、`cover.remove`）**不可撤销**，确认摘要必须列出被删对象的名称与 ID，并明示不可恢复。
+- 扩大可见范围的操作（`share.add`、`folder.permission.set-auth` 从 `user` 改成 `true`、`folder.permission.add` 给 `all`）属于**信息暴露面扩大**，必须在摘要里写明「谁会因此看到什么」。
+- 一次确认只对一次 apply 有效：票据用过即失效语义上不应复用，重复 apply 同一票据属于误用，需重新 prepare。
+- 不要把票据、Cookie、ETEAMSID、Token 写进回复、日志或提交到仓库。
+
+## 失败处理
+
+| error.type / subtype | 含义 | 处理 |
+| --- | --- | --- |
+| `confirmation/required` | apply 缺 `confirm: true` | 先向用户摘要并取得确认，再加 `--yes` 重跑 apply |
+| `validation/continuation_required` | apply 缺 `continuation` | 先跑 prepare 拿票据 |
+| `validation/continuation_invalid` | 票据签名校验失败或无法解析 | 重新 prepare；不要修改票据字符串 |
+| `validation/continuation_expired` | 超过 10 分钟有效期 | 重新 prepare |
+| `validation/continuation_mismatch` | 票据被用于别的 apply 操作 | 用对应操作的 prepare 重新签发 |
+| `validation/continuation_context_mismatch` | 环境（baseUrl）或登录账号已变 | 确认目标环境后重新 prepare |
+| `validation/continuation_target_changed` | 关键字段（如 `doc_id`）与 prepare 不一致 | 重新 prepare |
+| `validation/continuation_args_changed` | 整体入参指纹与 prepare 不一致 | 用与 prepare 完全相同的入参，或重新 prepare |
+| `validation/plan_changed` | 组装出的请求体指纹与 prepare 不一致（表单级联结果或服务端状态已变） | 重新 prepare，并把变化告知用户 |
+| `validation/file_changed` | prepare 后本地文件 MD5/大小变化 | 与用户确认文件后重新 prepare |
+| `authentication/session_expired` | 登录态失效 | 停止，引导重新登录，然后从 prepare 重新开始 |
+| `api/business_error` | 服务端业务拒绝 | 原样转述 message；写操作不要重复提交 |
+| `network/*`（retryable） | 请求未确认送达 | 按上文决策树：停止 → 一次只读回查 → 必要时重新 prepare |
+| `partial/write_uncertain` | 写结果不确定 | 同上决策树，禁止自动重放 |

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

@@ -15,8 +15,8 @@ cliHelp: "weaver-work-cli calendar --help"
 
 # 泛微E10日程管理
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --target-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
-
+**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)。
 
 本技能覆盖日程管理业务域：**创建日程**、**查询列表**、**查询详情**、**查询总数**、**更新日程**、**删除日程**、**查询类型/紧急程度字典**、**应用版本检测**。写操作（创建/更新/删除）全部走 prepare→apply 确认协议。
 
@@ -102,5 +102,6 @@ weaver-work-cli --json calendar run calendar.list --input-json '{"page_no":1,"pa
 macOS/Linux（bash/zsh）：
 
 ```bash
-printf '%s\n' '{"page_no":1,"page_size":10}' | weaver-work-cli --json calendar run calendar.list --input -
+printf '%s
+' '{"page_no":1,"page_size":10}' | weaver-work-cli --json calendar run calendar.list --input -
 ```

package/skills/weaver-e10-ebuilder-form/SKILL.md

@@ -11,23 +11,18 @@ agent_created: true
 requires:
   bins: ["weaver-work-cli"]
 dependencies:
-  - weaver-e10-login
+  - weaver-e10-shared
 cliHelp: "weaver-work-cli ebuilder-form --help"
 ---
 
 # 泛微E10 eBuilder表单
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --target-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
+**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)。
 
 本技能覆盖 eBuilder 表单菜单定位、List/NList 页面查询、字段/选项/浏览字段解析，以及 OpenAPI 和已发布自定义接口的表单数据读写。所有业务调用必须通过 `weaver-work-cli ebuilder-form`，禁止绕过 CLI 直接拼 E10 接口、Cookie、ETEAMSID 或 `/api/bs/` 路径。
 
-认证由 `weaver-work-cli` 共享登录能力和 `weaver-e10-login` 兼容依赖托管。底层请求头由 CLI 自动设置，Agent 不得在对话或命令输入中索取、粘贴或输出这些凭证：
-
-```text
-Cookie: <e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
-eteamsid: <e10-login 返回的 ETEAMSID>
-User-Agent: AgentType=<agentType>,IsAgent=true
-```
+认证由 `weaver-e10-shared` 共享规则和 `weaver-work-cli auth ...` 命令体系托管。底层请求头三件套由 CLI 统一注入，Agent 不得在对话或命令输入中索取、粘贴或输出这些凭证；唯一权威声明见 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md) 的「请求头契约」章节。
 
 ## 命令入口
 

package/skills/weaver-e10-ebuilder-form/references/context-routing.md

@@ -4,15 +4,6 @@
 
 用户给了菜单名、页面 URL，或需要拿到 `appId` / `apiPrefix` / `objId` / `listId` / 页面地址时使用。这是几乎所有其它 operation 的前置步骤。
 
-## 请求头契约（CLI 注入，Agent 不手写）
-
-CLI 发往 E10 的每个请求都自动携带以下三项用户信息参数，缺一不可（业务入参里不要传这些字段，也不要手工拼装请求头）：
-
-```text
-Cookie: <e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
-eteamsid: <e10-login 返回的 ETEAMSID>
-User-Agent: AgentType=<agentType>,IsAgent=true
-```
 
 ## operation
 

package/skills/weaver-e10-ebuilder-form/references/custom-api.md

@@ -8,11 +8,7 @@
 
 ## 请求头契约（CLI 注入，Agent 不手写）
 
-```text
-Cookie: <e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
-eteamsid: <e10-login 返回的 ETEAMSID>
-User-Agent: AgentType=<agentType>,IsAgent=true
-```
+请求头三件套由 `weaver-work-cli` 统一注入，Agent 不手写、不覆盖；唯一权威声明见 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md) 的「请求头契约」章节。
 
 ## operation
 

package/skills/weaver-e10-ebuilder-form/references/fields-browser.md

@@ -8,11 +8,7 @@
 
 ## 请求头契约（CLI 注入，Agent 不手写）
 
-```text
-Cookie: <e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
-eteamsid: <e10-login 返回的 ETEAMSID>
-User-Agent: AgentType=<agentType>,IsAgent=true
-```
+请求头三件套由 `weaver-work-cli` 统一注入，Agent 不手写、不覆盖；唯一权威声明见 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md) 的「请求头契约」章节。
 
 ## operation
 

package/skills/weaver-e10-ebuilder-form/references/list-nlist.md

@@ -8,11 +8,7 @@
 
 ## 请求头契约（CLI 注入，Agent 不手写）
 
-```text
-Cookie: <e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
-eteamsid: <e10-login 返回的 ETEAMSID>
-User-Agent: AgentType=<agentType>,IsAgent=true
-```
+请求头三件套由 `weaver-work-cli` 统一注入，Agent 不手写、不覆盖；唯一权威声明见 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md) 的「请求头契约」章节。
 
 ## operation
 

package/skills/weaver-e10-ebuilder-form/references/openapi-read.md

@@ -8,11 +8,7 @@
 
 ## 请求头契约（CLI 注入，Agent 不手写）
 
-```text
-Cookie: <e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
-eteamsid: <e10-login 返回的 ETEAMSID>
-User-Agent: AgentType=<agentType>,IsAgent=true
-```
+请求头三件套由 `weaver-work-cli` 统一注入，Agent 不手写、不覆盖；唯一权威声明见 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md) 的「请求头契约」章节。
 
 ## operation
 

package/skills/weaver-e10-ebuilder-form/references/openapi-write.md

@@ -8,11 +8,7 @@
 
 ## 请求头契约（CLI 注入，Agent 不手写）
 
-```text
-Cookie: <e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
-eteamsid: <e10-login 返回的 ETEAMSID>
-User-Agent: AgentType=<agentType>,IsAgent=true
-```
+请求头三件套由 `weaver-work-cli` 统一注入，Agent 不手写、不覆盖；唯一权威声明见 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md) 的「请求头契约」章节。
 
 ## operation
 

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

@@ -15,8 +15,8 @@ cliHelp: "weaver-work-cli esb --help"
 
 # 泛微E10 ESB动作流执行
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --target-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
-
+**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)。
 
 本技能覆盖 ESB 中心的**自定义触发类型动作流**：取入参模板（只读）与执行动作流（写操作，需确认）。按动作流名称解析 ID、唯一值对应的 `primary_key` SQL 查询都不在本技能范围内，见「不在范围」。
 

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

@@ -104,12 +104,12 @@
     }
   },
   "artifactBaseline": {
-    "aggregateSha256": "9867d4f6de7aa27f37e6bad3702e22b3d2f3fe5b62157642e32861a1847c22f9",
+    "aggregateSha256": "13a4b9b7beec15e4377ab86dc220dde327c9b398dacd88d8f691b9e21cf7f30f",
     "files": [
       {
         "path": "docs/_catalog.md",
-        "size": 4580,
-        "sha256": "7ec48267965b4ccd35dcc463ed0a73dd71c3f4d2fc3d978165f508261945d4b3"
+        "size": 5332,
+        "sha256": "a81903939aea5bf1196d1e3243709d2facf50d9bdcf74d8a6ca731061310dbbe"
       },
       {
         "path": "docs/esb.md",
@@ -123,8 +123,8 @@
       },
       {
         "path": "skill-template/business-info.json",
-        "size": 6294,
-        "sha256": "7af8cc1b35564b11a4c33cf566b22919d75c8a4daeec488d6ff8979c098c8ff7"
+        "size": 8216,
+        "sha256": "370a45e86c6b7e33869c5df1bf08d9f22bd98fa8b157b49716e13bca0e7b63c3"
       },
       {
         "path": "skill-template/domains/esb.md",
@@ -149,8 +149,8 @@
       },
       {
         "path": "skills/weaver-e10-esb/SKILL.md",
-        "size": 6841,
-        "sha256": "b6b1bb5c629ef627267de04922e0f5a9504fe7eafe52f8406924f2981a14198d"
+        "size": 8073,
+        "sha256": "a12d79807348cdb3be2e17bfdca1fc783f5be004eb4b76906db73b81ea203d00"
       },
       {
         "path": "src/shortcuts/esb/continuation.ts",
@@ -209,8 +209,8 @@
       },
       {
         "path": "src/shortcuts/index.ts",
-        "size": 1274,
-        "sha256": "54df058151b6f3602a2d112a49396b4ad4121cdba06d31c4c368ebd3235192c4"
+        "size": 1420,
+        "sha256": "569bef374df2d86b511150a0c609ce1abee63f8317994513bce6241276b5be40"
       },
       {
         "path": "test/business/esb-command.test.ts",

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

@@ -5,7 +5,7 @@ display_name_en: Weaver E10 Organization Management
 description: 泛微E10组织管理（员工/组织/岗位查询）的 E10 查询能力，通过 weaver-work-cli hrm 命令执行。
 description_zh: 泛微E10组织管理（员工/组织/岗位查询）的 E10 查询能力，通过 weaver-work-cli hrm 命令执行。
 description_en: Weaver E10 Organization Management capabilities for E10, covering employee, organization and position queries, delivered through the weaver-work-cli hrm command.
-version: 1.0.0
+version: 1.0.28
 author: 泛微网络科技股份有限公司
 agent_created: true
 requires:
@@ -15,10 +15,10 @@ cliHelp: "weaver-work-cli hrm --help"
 
 # 泛微E10组织管理
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --target-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
+**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)。
 
-
-本技能覆盖组织管理三大业务域：**员工（employee）**、**组织（org）**、**岗位（position）**，全部为只读查询，无写操作。代理商查询（`containsDls=true`）属于禁用边界，见 [`references/employee.md`](references/employee.md)。
+本技能覆盖组织管理三大业务域：**员工（employee）**、**组织（org）**、**岗位（position）**，全部为只读查询，无写操作。代理商查询（`containsDls=true`）属于禁用边界，见 [`references/employee.md`](references/employee.md)。组织域额外提供**多维（虚拟组织维度）解析** `hrm.org.resolve`，见下方「多维解析」。
 
 ## 命令入口
 
@@ -42,24 +42,117 @@ weaver-work-cli --json hrm run <operation> --input -
 | --- | --- |
 | 查员工、工号/手机/邮箱、查下属、部门成员、批量人员、人员详情 | [`references/employee.md`](references/employee.md) |
 | 查分部、查部门、组织架构、层级路径、组织详情 | [`references/org.md`](references/org.md) |
+| **按「多维名称 + 部门/分部名称」找组织**（多维 / 虚拟组织 / 维度） | [`references/org.md`](references/org.md) 的「多维解析」 |
 | 查岗位、岗位详情、批量岗位 | [`references/position.md`](references/position.md) |
+| **按部门/分部反查人员**（某部门下有哪些人） | [`references/employee.md`](references/employee.md) 的「按组织反查人员」 |
+| **按岗位反查人员**（某岗位下有哪些人） | 本技能不支持，需跨到 `weaver-e10-jucailin`；先读下方「反查人员的能力边界」 |
+
+## 多维解析（`hrm.org.resolve`）：一次调用，禁止自己分两步推理
+
+E10 组织树按**多维**（虚拟组织维度，如「行政组织」「1号维度」「备份维度」）切分，同名部门/分部在不同维度下是**不同节点**；组织浏览接口不传 `companyId` 会**默认落到「行政组织」维度**。所以「按名称找部门/分部」需要先定位多维 id，再带 `companyId` 查组织。
+
+**这段编排已在 CLI 内实现，Agent 只调一次 `hrm.org.resolve`，不要自己先查维度、再查组织。**
+
+```text
+weaver-work-cli --json hrm run hrm.org.resolve --input-json '{"virtual":"1号维度","name":"第一团队"}'
+```
+
+- 入参：`virtual`（多维名称）+ `name`（部门/分部名称）；`type` 可选（`department`/`subcompany`，**不传时同时检索两者、按部门优先定位**）；歧义候选**默认最多回 20 条**，要一次性看全时传 `maxCandidates`（1~200）。
+- 匹配分**三级**，"能不能自动往下走"完全不同，别混为一谈：
+
+| 级别 | 判定 | CLI 行为 |
+| --- | --- | --- |
+| ① 精确 | 忽略大小写/空白的全等 | 唯一 → 继续；多个 → `ambiguous` |
+| ② 包含（模糊） | 名称是关键字子串 | 唯一 → 继续；多个 → `ambiguous` |
+| ③ **近似（打字级差异，如「客服维度」→「客户维度」）** | 编辑距离阈值内 | **只回 `suggestions`，`status = not_found`，绝不继续** |
+
+### 🔴 不要替用户做主（三条硬边界，违反即算答错）
+
+1. **禁止自行替换/纠正名称**。用户说「客服维度」，就只能在「客服维度」不存在时**如实告知**；不许把「客户维度」当成用户的意思直接用（这是最典型的越权：看着像就替用户认了）。
+2. **禁止在 `ambiguous` 里替用户选**。不许取第一条、不许取「看起来最像的」、不许取「唯一直属根节点的」——一律列表让用户挑。
+3. **`not_found` ≠ 换个名字再试**。必须把 `data.message` + `data.suggestions`（近似名称）+ `data.availableVirtuals`（该租户全部多维）原样交给用户，等用户确认；**用户确认后**才用 `virtualId`（维度）/ `orgId`（组织）复调，不要再用名称猜。
+
+> 实例：`{"virtual":"客服维度","name":"云桥测试"}` → `not_found`（`suggestions: [客户维度]`）。正确回复是「本租户没有『客服维度』，最接近的是『客户维度』（id …），要用它继续查『云桥测试』吗？」——**不是**直接返回客户维度下的结果。
+> 反过来，③ 之外的 ①② 是 CLI 既定行为（属于系统收敛，不属于你改名），命中了就正常往下走。
+
+- **结果判定只看 `data.status`，不要只看 `ok`**（本操作三种结果都是 `ok: true`）：
+
+| `data.status` | 含义 | Agent 必须做什么 |
+| --- | --- | --- |
+| `resolved` | 已定位唯一组织 | 用 `data.org`（`id`/`name`/`type`/`fullPath`/`link`）直接回答，用 `[名称](link)` 呈现；**若同时回 `data.alsoMatched`（同名但另一类型的节点，如既有同名部门又有同名分部），必须一并告知用户**，不要只报 `org` |
+| `ambiguous` | 精确或包含命中多个 | **停下来问用户**：把 `data.candidates` 以表格（名称 / `fullPath` / link）列出让用户选，不要自行挑一个；候选被截断（`truncated: true`）时先告知总数，用户要全量就用 `maxCandidates` 复调 |
+| `not_found` | 名称不存在（含"只有近似名称"的情况） | 原样转述 `data.message`，并把 `data.suggestions`/`data.availableVirtuals` 一并给用户确认；**禁止自行替换名称后重试** |
+
+- 用户确认候选后**复调同一个操作**：把候选的 `id` 作为 `orgId` 传回（若是维度歧义，把维度 `id` 作为 `virtualId` 传回），一次即可定位；**不要再用名称重试猜**。
+- **🔴「这个租户有哪些多维」暂不支持**（`hrm.org.virtuals` 已下线，`hrm schema --full` 的 `withheldOperations` 里有声明）：
+  - 没有列维度的 operation，**也不许绕**——不要故意传一个不存在的维度名去套 `not_found.availableVirtuals` 来"列清单"，那属于构造假查询。
+  - `availableVirtuals` 只用于**纠错**（用户给的名字对不上时，顺手告诉他本租户有哪些维度可参考），维度 id 也只从 `not_found.availableVirtuals` / 维度歧义的 `candidates` 里取。
+  - 用户明确问"有哪些多维"时 → 直接回答**该能力暂不支持**，并请其改用「维度名 + 组织名」的方式查询。
+- 完整契约、匹配规则与示例见 [`references/org.md`](references/org.md) 的「多维解析」。
+
+## 反查人员的能力边界
+
+"这个部门/岗位下有哪些人"是高频误判点，先按下表判断，**不要默认认为 hrm 整个模块都做不到**：
+
+| 起点 | 支持情况 | 走哪里 |
+| --- | --- | --- |
+| 部门 / 分部 | ✅ 支持 | `hrm.dept.members`（同模块，**只返回直属成员，不含子部门**） |
+| 岗位 | ❌ 不支持反查 | `position.*` 只给 `userCount` 人数，`employee.query` 不支持按岗位过滤；需跨到聚才林通讯录高级搜索 `ehr.hr.contact.search` + `saCondition` |
+
+只有**岗位反查**才需要跨模块。以下护栏**自包含**，跨模块前读完；聚才林技能（`weaver-e10-jucailin`，连接器版 `weaver-e10-jucailin-connector`）的通讯录高级搜索条件文档是补充，不是前置依赖（读不到也必须按本节执行）。
+
+**陷阱 1 · 条件元素漏字段键 → 整个条件被静默丢弃**
+
+`saCondition` 的每个字段值是「条件对象数组」，**元素内部必须再带一个服务端认识的键**（字段同名键，或 `xxx_condition` 算子键）：
+
+| 字段类型 | 正确写法 |
+| --- | --- |
+| BROWSER（岗位/部门/分部/上级） | `"position": [{ "position": [{ "id": "<id>", "includeSub": true }] }]` |
+| SELECT（状态/性别） | `"personnel_status": [{ "personnel_status": ["normal"] }]` |
+| INPUT（姓名/工号） | `"username": [{ "username_condition": "in", "username": "杰" }]` |
+
+写成 `"position": [{ "id": "<id>" }]`（元素里只有裸 id）时**不报错、不返回错误码**，服务端直接忽略该条件——看起来"有结果"，其实完全没过滤。
+
+**陷阱 2 · `saCondition` 不继承"默认在职"**
+
+便捷字段路径默认在职；一旦改用 `saCondition` 且不写 `personnel_status`，就是**不限状态（含离职）**。两者叠加就是"无过滤 + 不限状态"。
+
+**结果自检（必做，不得跳过）**
+
+跨模块反查后必须核对 `total`，再决定是否回复用户：
+
+1. 先取该租户的**全量基线 N**：用 `personnel_status: ["all"]`（或空条件）查一次，得到"不限状态总人数"；
+2. 条件生效时 `total` 必须**明显小于 N**；
+3. **一旦 `total` 等于或接近 N，就判定为"条件被吞"**——不要回复"有这么多结果"，回到上面两条检查条件结构后重查；
+4. 岗位反查的合理量级通常是**个位数到几十**（单个岗位不会等于全公司人数）。
+
+> 量级示例（本次实测，随租户不同，**不可当常量**）：全量含离职 N=44853、在职=11976、离职=32692，而 `{"position":[…正确…]}` 得到的真实岗位人数=1。写下这些数字只为说明"条件生效后 total 会掉几个数量级"。
 
 ## 跨模块约定（必须先知道）
 
 三个业务域统一走 E10 HRM 内部浏览/详情接口，响应统一 `WeaResult` 契约，已在 CLI 内归一化，但语义差异仍会影响结果解读：
 
 - **响应成功判定**：统一 `code=200`（WeaResult）。业务失败码即使 HTTP 200 也会抛 `api/business_error`；`403` 会抛 `api/permission_denied`（提示联系管理员开启接口开关，不盲目重试）。
-- **数据行位置**：列表接口行在 `data.data`（浏览按钮 `browser/data/*` 与岗位批量 `queryListByOrgTree`），总数在 `data.total`；员工浏览/下属查询因 `data/resource` 的 `data.count` 恒为 0，CLI 额外请求 `count/resource` 取真实 `data.total`。下属按 id 查询（`myDirectSubordinates`/`myIndirectSubordinates`）的行在 `data.page.result`、总数在 `data.page.totalCount`。
-- **详情接口**：员工名片（`profile/get`）、组织详情（`organization/getForm`）、岗位详情（`getEditOrAddPostForm`）返回单对象（`data` 直接承载），CLI 附 `link`。
+- **数据行位置（描述的是上游原始响应，不是 CLI 输出）**：上游列表接口行在 `data.data`（浏览按钮 `browser/data/*` 与岗位批量 `queryListByOrgTree`）；下属按 id 查询（`myDirectSubordinates`/`myIndirectSubordinates`）的行在 `data.page.result`、总数在 `data.page.totalCount`。
+  - CLI 已把上述差异归一化：**列表类统一读 envelope 的 `data.rows` + `data.total`，分页参数在 `meta`（current/pageSize）**。不要把上游的 `data.data` / `data.page.result` 当成 CLI 输出路径。
+  - ⚠️ **CLI 不会去请求 count 接口**（员工浏览上游的 `data.count` 恒为 0，调 count 也拿不到可靠总数）：除 `subordinate.by-id` 外，`employee.query`/`subordinate.mine`/`dept.members` 的 `data.total` **就是本页行数**，不是真实总数。要真实总数只能按 `current` 逐页翻到 `rows.length < pageSize`；`subordinate.by-id` 的 `total` 来自上游 `page.totalCount`，是真值（并附 `data.page.hasNext/totalPages`）。
+- **详情接口**：员工卡片（`card/get`）、组织详情（`organization/getForm`）、岗位详情（`getEditOrAddPostForm`）底层都是 `WeaForm` 单对象。**上游响应**里业务字段在 `data.data`；CLI 会把它**展平上移一层**，因此**最终输出中业务字段直接挂在 envelope 的 `data` 下，不存在 `data.data` 嵌套**（`items`/`groups`/`layout` 等前端表单元数据已丢弃），并附 `link`。
+  - **`hrm.employee.detail` 默认只回核心业务字段**（26 键，约完整卡片体积的 1/5；实体数组只留 `{id,name}`、人员数组只留 `{id,name,statusCode,avatar}`、`avatar` 只留 1 个 `url`）。**只有确实要完整卡片时才传 `full: true`** —— 默认别传，它会带回 `password`/`last_android`/`hideFieldList`/`setting`/各类 `*_admin` 等无用元数据，显著撑大上下文。
+- **「人员列表」默认只回精简行**：`hrm.subordinate.mine` / `hrm.subordinate.by-id` / `hrm.dept.members` 每行只有 `id`/`name`/`link`（原始行 366B（`mine`/`dept.members`）/ 960B（`by-id`，其中上游 `superior` 对象一项就占 485B），精简后约 116~120B）；`hrm.employee.query` 保留人员信息、每行 6 键（`id`/`name`/`department`/`position`/`statusCode`/`link`，368B → 186B）。需要部门/岗位/电话/上级等完整列时显式传 `full: true`；缺部门岗位信息时，优先对个别人再调 `hrm.employee.detail`（其精简卡片已含 `department`/`position` 的 `{id,name}`），**不要为列表好看就默认开 `full`**。
+- **🔴 三套 id 不要混用**：人员行可能出现 `id`（**人员 id**，驼峰 `userId` 与它同值）、`userid`（登录信息 id）、`cid`（`employee.batch` 里叫 `imCid`，IM 联系人 id）。**只有人员 `id` 能用于**卡片链接、`employee.detail`、`employee.batch.ids`、`subordinate.by-id.id`；`userid`/`cid` 分别只用于登录账号与 IM 场景。`employee.query` 默认行只留人员 `id`，另两套仅在 `full: true` 时出现。
 - **长整型 id 一律按字符串传递**：人员 id、组织节点 id、岗位 id 都是长整型，避免精度丢失。
 - **手机号脱敏**：员工/批量/下属列表返回的 `mobile` 已由 CLI 脱敏（3 位前缀 + `****` + 末 4 位），Agent 直接呈现，不做二次处理。
 
 ## 安全边界
 
 - **🔴 无条件禁止全量拉取**：`employee.query`/`org.query`/`position.query` 必须携带至少一个收敛条件，无条件时先询问用户，禁止空条件调用。`position.list` 无 `org`/`name`/`code` 过滤时必须显式 `all=true`。
+- **🔴 分页统一约束：`pageSize` 默认 `10`、最大 `100`**。支持 `pageSize` 的操作只有 `employee.query`/`subordinate.mine`/`subordinate.by-id`/`dept.members`/`org.query`/`position.list`；`position.query` 不接受该参数（传入被忽略，固定按 200 返回）。需要更多数据时用 `current` 递增翻页，**禁止靠放大 `pageSize` 一次取回大结果**——大结果会整段进入上下文。`position.list` 自带自动翻页，通常无需显式传 `pageSize`。
+  - 说明：服务端**不校验**该上限（实测 `pageSize=500` 会原样返回 500 行，不传 `pageSize` 时服务端按 20 返回），所以这条是**本技能为控制上下文体积定下的自觉约束**。Agent 必须遵守，不得因为"服务端没拦"就放大取值。
 - **🔴 `status` 不能单独使用**：`employee.query` 的 `status`（`["normal"]` 在职 / `["6"]` 离职）必须搭配其它条件（keyword/工号/姓名/手机/邮箱）。
 - **批量禁止循环单查**：批量查询一律走 `batch`（每批 ≤100，CLI 自动分批）；岗位批量走 `position.list` 一次性返回，禁止按 id 逐个调详情。
-- **姓名/工号/名称模糊匹配**：多人命中时必须列出候选让用户选择，不得自动取第一条；`dept.members` 部门重名时报 `dept_ambiguous`，需改用组织 id。
+- **姓名/工号/名称模糊匹配**：多人命中时必须列出候选让用户选择，不得自动取第一条；`dept.members` 部门重名时报 `dept_ambiguous`，需改用组织 id。`hrm.org.resolve` 不抛歧义错误，而是回 `data.status = ambiguous` + `data.candidates`，同样必须问用户、不得自动取第一条。
+- **🔴 禁止自主任意解读名称**：`hrm.org.resolve` 报 `not_found` 时，`data.suggestions`（近似名称）**只是给用户看的提示，不是给你用的参数**——不得据此改名重试、也不得省略「不存在」这一事实直接给结果。凡「名称对不上」一律先回用户，用户确认后再用 `virtualId`/`orgId` 复调。
+- **🔴 禁止绕取未暴露能力**：`hrm.employee.dls`（代理商查询）与 `hrm.org.virtuals`（列多维）都在 `hrm schema --full` 的 `withheldOperations` 里声明为不可用；**不得构造假查询（如故意传不存在的维度名）去套内部字段**、也不得编造或绕过。用户问到就如实回答暂不支持。
 - **人员 id、组织 id、岗位 id 都是长整型**，一律按字符串传递。
 - **代理商查询禁用**：`hrm.employee.dls`（`containsDls=true`）仅泛微自用系统支持，已列为禁用边界，不得编造或绕过。
 
@@ -67,7 +160,8 @@ weaver-work-cli --json hrm run <operation> --input -
 
 - `code=302` 或认证类错误：引导用户执行 `weaver-work-cli auth login`，不要用其他方式排查。
 - 业务失败看 stderr JSON 的 `error.type` / `error.subtype` / `error.message`，不要用退出码 `0` 判断成功。
-- 常见业务错误：`empty_condition`（空条件拉取被拦截）、`full_pull_blocked`（岗位全量需 `all=true`）、`dept_not_found`/`dept_ambiguous`（组织未找到或重名，改用 id）、`enum_invalid`（枚举取值非法）、`permission_denied`（接口开关未开启）。
+- 常见业务错误：`empty_condition`（空条件拉取被拦截）、`full_pull_blocked`（岗位全量需 `all=true`）、`dept_not_found`/`dept_ambiguous`（组织未找到或重名，改用 id）、`enum_invalid`（枚举取值非法）、`permission_denied`（接口开关未开启）、`virtual_required`/`name_required`（`hrm.org.resolve` 缺多维或多维名称参数）。
+- `hrm.org.resolve` 的「没找到 / 命中多个」**不是错误**：命令仍退出 0、`ok: true`，判定以 `data.status` 为准，不要把 `not_found` 当异常重试。
 
 ## 平台兼容
 
@@ -82,7 +176,8 @@ weaver-work-cli --json hrm run hrm.employee.query --input-json '{"keyword":"张
 macOS/Linux（bash/zsh）：
 
 ```bash
-printf '%s\n' '{"keyword":"张三"}' | weaver-work-cli --json hrm run hrm.employee.query --input -
+printf '%s
+' '{"keyword":"张三"}' | weaver-work-cli --json hrm run hrm.employee.query --input -
 ```
 
 复杂 JSON 建议保存为 UTF-8 文件后按平台传给 `--input <file>`。