weaver-work-cli 0.1.1 → 0.1.4

package/docs/ehr.md

@@ -0,0 +1,186 @@
+# 聚才林人事云（ehr）
+
+`ehr` 是 E10 聚才林人事云的聚合命令，覆盖**人事档案（hr）**、**出勤管理（attend）**、**薪酬管理（salary）**、**招聘（recruit，读 + 写）** 四个业务域。
+
+```text
+weaver-work-cli ehr --help
+weaver-work-cli ehr schema
+weaver-work-cli --json ehr run <operation> --input -
+```
+
+`schema` 是能力清单的唯一事实来源，包含每个 operation 的 `inputSchema`、`risk`、`requiresConfirmation`，以及固定数据源 `formId` 常量表 `dataSourceIds` 和禁用清单 `withheldOperations`。
+
+## 实现位置
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/shortcuts/ehr/index.ts` | 命令注册与 JSON envelope |
+| `src/shortcuts/ehr/manifest.ts` | `schema` 契约与禁用边界声明 |
+| `src/shortcuts/ehr/host.ts` | E10 会话桥接、认证头、form/JSON 请求、响应归一化 |
+| `src/shortcuts/ehr/continuation.ts` | 写操作确认链的 HMAC-SHA256 token |
+| `src/shortcuts/ehr/operations/` | 按业务域拆分的 operation 实现 |
+| `src/shortcuts/ehr/operations/registry.ts` | operation 注册表与去重校验 |
+
+## 认证
+
+复用 `src/internal/e10` 的 E10 会话（`requireE10Session`），请求自动携带 `Cookie`、`eteamsid` 与 `X-Requested-With: XMLHttpRequest`。业务代码不接触认证目录。
+
+请求路径强制以 `/api/` 开头，并拒绝绝对路径、跨域 URL 与路径逃逸。
+
+## 子系统差异归一化
+
+三个子系统由不同团队开发，契约不一致，`host.ts` 与 `operations/shared.ts` 负责归一化。
+
+**响应成功判定**
+
+| 子系统 | 契约 |
+| --- | --- |
+| 出勤 | `success` 布尔 |
+| 人事档案 | `code=200` |
+| 薪酬个人报表 | `status` 布尔 |
+
+**分页**：统一提取 `pageNo`/`current`/`pageSize`/`total`/`totalCount`/`totalPage`/`tableId`。
+- 表格类接口（出勤/人事/薪酬）总数用 **`total`**；数据源计数接口用 **`totalCount`**——两者都要提取，已在 `normalizePaged` 中覆盖。
+- 出勤统计接口不返回 page 对象（它是范围聚合，不是分页列表）。
+- `pageSize` **由服务端固定，传参无效**：通讯录 100，出勤与报表类 20。全量数据必须递增 `current` 翻页。
+
+**数据行位置（三种命名，均已在真实 E10 实测）**：
+
+| 接口 | 数据行字段 |
+|---|---|
+| `hr.contact.search` | `data` |
+| 出勤表格类（`abnormal`/`signrecord`/`orbit`/`worktime`/`leave`/`appeal`）+ hr 报表（`report.*`/`props.table`） | **`displayData`**（`data` 为空数组） |
+| `attend.report.get` | **`datas`** |
+
+注意 `birthday.list` 是例外——它的行在 `data`（同模块内也不统一）。
+
+CLI 原样透传整个响应对象，不做重命名；取用方按上表判断。
+
+**每页条数**：由服务端按接口独立配置，**`pageSize` 传参无效**（实测）：通讯录 100、出勤表格类 20、`worktime`/`leave.report` 10、hr 报表 20、薪酬 `bill.list`/`employee.list` 20、`empchange.list` 100。全量数据一律递增 `current` 翻页。
+
+**成功响应的 `data` 恒存在**：业务数据为 `undefined` 时（如社保福利、调薪记录为空）统一补为 `null`，避免 `JSON.stringify` 省略该键导致调用方需判断键是否存在。
+
+**二次身份验证 token**：工资单相关 4 个接口要求携带 `token`（与登录凭证无关，不由认证链路提供）。`bill.list` 走 body，其余三个走 query。用户未提供时 CLI 自动补固定协议值 `DONT_NEED`；用户主动提供时用原值。缺失会返回 `checkSecondFailNoToken`，验证失败返回 `checkSecondFail`，服务异常返回 `checkSecondError`（此时**不得绕过验证读取数据**）。见 `shared.ts` 的 `resolveSecondAuthToken`。
+
+**历史教训（2026-09-04）**：`bill.get` 曾持续返回 `code=500`，一度被判定为"服务端问题"（当时绕过 CLI 直接发 HTTP 也是 500，看似佐证）。真实原因是**未传 `token`**——直接 HTTP 对照时同样没传，所以对照组也失败，形成了误导性证据。补齐 `token` 后两个工资单 ID 均正常返回。结论：**构造对照实验时，必须确保对照组与实验组的差异只有唯一变量**。
+
+**语义差异（需调用方注意）**：通讯录默认只查在职（`personnelStatus=["normal"]`），人员状态变更台账默认包含离职人员。
+
+## 数据源接口
+
+HR 报表类接口走 `application/x-www-form-urlencoded`（`sourceType=LOGIC` + `queryDto` 为 JSON 字符串），不是 JSON body。`queryDto` 由 CLI 从结构化参数构造：
+
+```json
+{
+  "formId": "754217732232708651",
+  "conditions": [{ "field": "timePoint", "value": "2026-02-28", "compareType": "eq" }],
+  "pageNo": 1,
+  "pageSize": 100
+}
+```
+
+**日期范围条件必须拆成 `gte` + `lte` 两个条件**，这是 `hw.dutyDate` / `turn.dateRange` / `v2DeptEmpMove.month` / `dismiss.dismissDate` 的唯一正确传法。引擎取前 2 个 `conditionValue` 作为起止日期。
+
+```json
+"conditions": [
+  { "field": "dutyDate", "value": "2026-01-01", "compareType": "gte" },
+  { "field": "dutyDate", "value": "2026-12-31", "compareType": "lte" }
+]
+```
+
+只有 `tp.timePoint` 是单条件，用 `eq`。
+
+**不要用 `between`**（2026-09-04 修正，此前误判为可用）：实测 `_inner_params` 回显为 `paramTp: "2026-01-01,2026-12-31"`（服务端只收到单个字符串），返回条数与全量相同，即**退化为不过滤**；`hw` 等数据源传 `between` 则直接报 500。
+
+验证条件是否真生效：查返回记录的 `_inner_params`（如 `paramDutyDate: ["2026-01-01","2026-12-31"]`），它回显服务端实际收到的起止值；并用不同范围对比条数（实测 2026 全年 2535 vs 2026-06 单月 2534，证明过滤生效）。
+
+`COMPARE_TYPES` 白名单含 `eq`/`in`/`like`/`gtAndEq`/`ltAndEq`/`gte`/`lte`/`between`，具体以 `ds.fields` 返回的 `conditionType` 为准。
+
+`getListData` 走 `/api/bs/hr/ai/ds/getListData`，旧路径 `/api/bs/hr/ds/getListData` 已废弃。
+
+## 写操作确认链
+
+出勤域有 4 组写操作，全部采用 `prepare -> apply`：
+
+| 用途 | prepare | apply |
+| --- | --- | --- |
+| PC 端打卡 | `ehr.attend.card.check.prepare` | `ehr.attend.card.check.apply` |
+| 创建申诉 | `ehr.attend.appeal.save.prepare` | `ehr.attend.appeal.save.apply` |
+| 处理申诉 | `ehr.attend.appeal.result.prepare` | `ehr.attend.appeal.result.apply` |
+| 报表重算 | `ehr.attend.report.recalc.prepare` | `ehr.attend.report.recalc.apply` |
+
+协议：
+
+1. `prepare` 只预览并生成 continuation，不发送写请求。
+2. `apply` 必须带 `confirm=true` 与 `prepare` 返回的 continuation。
+3. continuation 绑定 `baseUrl`/`profile`/`userId`，10 分钟有效；租户或账号变化会触发 `context_mismatch`。
+4. 关键参数与 `prepare` 快照不一致时触发 `target_changed`，必须重新 `prepare`。
+5. 网络中断抛出 `partial/write_uncertain`（退出码 `partial`），**禁止自动重试**，先做只读回查。
+
+PC 打卡凭证 `sign` = `md5("wea" + "web" + empId + ETEAMSID + tenantKey 小写) + "ver"`，在 `apply` 阶段按当前会话实时构造，continuation 中不携带签名材料。
+
+## 调用示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json ehr run ehr.attend.summary.get --input-json '{"beginDate":"2026-03-01","endDate":"2026-03-31"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+printf '%s\n' '{"beginDate":"2026-03-01","endDate":"2026-03-31"}' | weaver-work-cli --json ehr run ehr.attend.summary.get --input -
+```
+
+## 招聘查询（recruit）
+
+招聘域第一期提供 4 个读 operation（`operations/recruit.ts`）：
+
+| operation | 用途 |
+| --- | --- |
+| `ehr.recruit.context.resolve` | 五层解析结果查看（调试/兜底用） |
+| `ehr.recruit.candidate.search` | 人才库姓名/手机号模糊搜索（无筛选 = 列出全部） |
+| `ehr.recruit.candidate.list` | demand/position/entry/offer 四类业务列表 |
+| `ehr.recruit.candidate.card` | 人才详情卡片（权限闸门 + 四卡片并行） |
+
+**五层运行时解析**：招聘接口不依赖固定路径，CLI 在业务调用前自动完成
+`getAppIds(tag=weaver-recruit-service) -> getObjsByTag -> allMenus -> ds/fields -> ds/options`，
+拿到 appId/objId/listId/cusMenuId/fieldId/optionId。菜单名按关键词匹配（跨版本菜单名不同，
+解析不到必须报错，禁止臆造）。解析产物缓存于进程内 + 磁盘双层，磁盘缓存根 = `E10_SKILL_CACHE_DIR`
+环境变量，未设置回退 CLI 数据目录 `WEAVER_WORK_CLI_HOME`（默认用户主目录下 `.weaver-work-cli`）的
+`env-cache/recruit-ops/<host>_<port>/<appId>.json`，与独立技能 `weaver-e10-jucailin` 同构（设同一
+`E10_SKILL_CACHE_DIR` 即可共享）；缓存目录内唯一 `<appId>.json`
+直接命中时跳过安装闸门（省 1 次 RTT），缺失时自动全量解析并回写缓存。
+
+**displayData 显示层策略**：EB 列表接口（`mapResult=1`）响应同时含 `data.data`（原始层，
+人员/字典字段为裸大 ID）与 `data.displayData`（显示层，服务端已内联姓名与字典中文）。
+列表 operation 优先取 displayData（零额外请求）；缺失时回退原始层——字典映射 + 纯 ID 创建人
+经 `/api/hrm/common/getEmployeeByIds`（`devtype: 5` 头，100 个一批）批量反查兜底。显示层行清理
+剔除 `DISPLAY_UI_KEYS`（operate/isToDo/todoPropSpan/flow_status 等）与 `xxxSpan`/`xxxAction` 动态后缀。
+
+**详情卡片**：`hasRights`（READ 闸门，严格前置）与 `getCandidateCardPrepareQuery` 并行
+（3RTT→2RTT），通过后四张卡片（BaseInfo/OtherInfo GET + InterviewInfo/Remark POST）并行；
+面试/沟通 `pageSize=100` 防默认 10 条静默截断。姓名内联解析兼容三种形态：数组 `name`、
+对象 `username`（备注创建人）、字符串 JSON。唯一仍需本地翻译的是 `baseInfo.recruitStatus`。
+每请求随机串：`tableuid` 32 位 hex、`randomkey_`/`v` 6 位 hex。
+
+招聘 EB 接口要求 `ebBusinessId: <listId>` 请求头，`ds/fields` 要求 multipart/form-data，
+两者由 `host.ts` 的 `headers`/`multipart` 通道支持（认证头仍由运行时统一注入并保护）。
+
+**招聘写操作**（`operations/recruit-write.ts`）：candidate.create / interview.arrange / offer.send / entry.process / interview.feedback.edit / interview.feedback.urge 六对 prepare→apply 已实现（迁移自 ehr 技能 recruit-* 写脚本），全部走确认链协议：prepare（只读定位/查重/枚举与人员解析 + 摘要 + continuation 10 分钟）→ 用户确认 → apply（confirm + 指纹校验 + 会话绑定校验 + 部分操作 apply 阶段二次查重）；多步写入（saveFormData → initTalentBatch / sendOffer / saveEstPreEntry / runEsb）中断报 `partial/write_uncertain` 禁止自动重试。Offer 邮件、面试通知（notify）、催评为 L3 外部通知。esbActionIds 全部运行时按钮解析（getFormButtons/getListButtons），解析不到阻断不编造。入职撤销（entry.cancel.change）暂缓实现。
+
+## 禁用边界
+
+`withheldOperations` 中声明的两类能力不实现，也不要绕过：
+
+- **招聘撤销类写操作**（`recruit.entry.cancel.change`）：撤销动作破坏性最强且依赖独立入口链路，暂缓迁移；招聘其余读/写操作已可用。
+- **移动端打卡**（`attend.card.sign.mobile`）：依赖真实定位、WiFi/蓝牙、设备凭证，Agent 无法获取，服务端必拒。严禁伪造参数重试。
+
+## 测试
+
+```text
+node --test --import tsx "test/business/ehr-recruit.test.ts" "test/business/ehr-recruit-write.test.ts" "test/business/ehr-operations.test.ts" "test/business/ehr-host.test.ts"
+```
+
+覆盖 manifest/registry 一致性、请求形状断言、写操作确认链、响应归一化、打卡签名算法与路径白名单，招聘域另覆盖 displayData 优先、原始层兜底反查、权限闸门前置、prepare/apply 全协议（指纹篡改拦截、二次查重、partial 报告、按钮解析失败阻断）与错误形状。

package/docs/esb.md

@@ -0,0 +1,64 @@
+# esb — E10 ESB 中心自定义触发动作流
+
+本模块为维护者说明。面向 Agent 的使用入口在 `skills/weaver-e10-esb/SKILL.md`，operation 合约以 `weaver-work-cli esb schema` 为准。
+
+## 模块来源
+
+- 源资料 Skill：`weaver-e10-customesb-execute`（ESB 中心动作流触发接口 Skill），本模块把它同步转换为 `weaver-work-cli esb` 命令面 + Agent Skill `skills/weaver-e10-esb`。
+- 源接口（去域名路径，域名与认证由 `src/internal/e10` 托管，业务 `host.ts` 不拼接域名、不处理凭证）：
+  - `POST /api/bs/esb/setting/customData/application/copyCustomData` — 取入参模板（只读）。
+  - `POST /api/esb/server/event/triggerActionFlow` — 执行自定义触发类型动作流（写操作）。
+
+## CLI 结构
+
+```text
+src/shortcuts/esb/
+  index.ts         Commander 注册（schema / run）、输入解析、输出 envelope
+  manifest.ts     operation 合约（WHAT：name/summary/risk/inputSchema/withheldOperations）
+  operations.ts   run 入口：白名单校验后分发 handler
+  host.ts         E10 请求适配：路径白名单、resultCode 归一化、写不确定性处理
+  errors.ts       模块结构化错误
+  continuation.ts prepare/apply 的 HMAC continuation 签发与校验
+  operations/
+    registry.ts   manifest 与 handler 强制一一对应
+    types.ts      handler 类型与 envelope
+    shared.ts     输入归一化、占位字段收集、resultCode 结果摘要
+    input-format.ts
+    trigger.ts
+```
+
+## operation 表
+
+| operation | 风险 | 用途 |
+| --- | --- | --- |
+| `esb.input-format` | `read` | 按 `applicationId` 取回 `customParams` 模板、`moduleSource` 与 `esbFlowId`；无副作用 |
+| `esb.trigger.prepare` | `read-before-write` | 只读回查目标动作流、组装触发请求体、签发 continuation（10 分钟）；不触发动作流 |
+| `esb.trigger.apply` | `high-risk-write` | 校验 continuation 与登录身份后调用触发接口，需 `confirm: true` |
+
+## 常见命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json esb run esb.input-format --input-json '{"applicationId":"900000000000000001"}'
+weaver-work-cli --json esb run esb.trigger.prepare --input-json '{"esbFlowId":"900000000000000001","employeeId":"10001","customParams":{"mainTable":{"dataId":"D1001"}}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json esb run esb.input-format --input-json '{"applicationId":"900000000000000001"}'
+weaver-work-cli --json esb run esb.trigger.prepare --input-json '{"esbFlowId":"900000000000000001","employeeId":"10001","customParams":{"mainTable":{"dataId":"D1001"}}}'
+```
+
+## 安全边界
+
+- **写操作强制确认链**：触发走 `prepare → apply`；`apply` 必须带 `confirm: true` 与有效 continuation，continuation 与签发时的 `userId`/`tenantKey` 绑定，过期或身份变化必须重新 prepare。
+- **写不确定性**：触发请求已发出但未取得结果（网络中断、超时）时返回 `partial/write_uncertain`，退出码为 `Partial`，禁止自动重试——重试可能造成重复执行。
+- **resultCode 归一化**：触发接口非 200 的 `resultCode` 全部在 `host.ts` 映射为结构化 subtype（如 507/508/511 → `throttled` 可重试，404 → `flow_not_found` 不可重试），`resultMsg` 原样带出。
+- **输入白名单**：顶层字段严格来自 `manifest.ts` 的 `inputSchema.properties`，未知字段直接报 `unknown_field`；`esbFlowId` 与 `uniqueIndent` 二选一，都传或多缺均报错，不做静默回退。
+
+## 已知限制（`withheldOperations`）
+
+- `esb.actionflow.resolve`：按动作流名称解析 ID 需要 ESB 中心查询接口，源资料未给出路径与字段契约，未实现；请用户直接提供 ID。
+- `esb.unique-indent.resolve`：唯一值触发所需的 `primary_key` 需直接查询 `esb_setting` 库（`SELECT primary_key FROM esb_application WHERE id = ?`），CLI 无数据库通道，只能由调用方查得后传入。

package/docs/fna.md

@@ -0,0 +1,72 @@
+# 齐业成费控中心（FNA）CLI
+
+对应 `src/shortcuts/fna`，把泛微齐业成 FNA 费控中心 11 个源接口固化为 13 个 operation（预算 2 / 费用中心 3 / 借款管理 4 / 发票核销 4，其中提醒还款与催票为 prepare/apply 写链）。源资料：`/Users/zhufangyuan/Desktop/weaver-e10-qiyecheng`（指纹见 `skills/weaver-e10-qiyecheng/references/source-manifest.json`）。
+
+## 公共前置
+
+- 认证、profile、HTTP client 由 `src/internal/e10` 托管；业务 host 只适配 `/api/fna/` 与 `/api/app/fna/` 路径（`src/shortcuts/fna/host.ts` 的 `assertPath` 白名单）。
+- 成功判定统一走 WeaResult（`success` 或 `status` 布尔 / `code==200`）；费用中心 AI 查询用 `success`，预算/借款/核销用 `status`。
+- JSON 输出与错误 envelope、退出码遵循共享规则；写操作不满足确认条件返回 `confirmation.required`（exit 10），请求发出后结果不确定返回 `partial/write_uncertain`（exit 11）。
+
+## Agent 入口
+
+面向 Agent 时先读 `skills/weaver-e10-qiyecheng/SKILL.md`，再按入口路由读取 `references/`（catalog/budget/expense-center/loan-management/invoice-writeoff）。
+
+## Operation 目录
+
+| Operation | 风险 | 固定规则与要点 |
+|---|---|---|
+| `fna.budget.application.detail` | read | GET `preApplication/getApplicationDetail`；`requestId` 必填 |
+| `fna.budget.execute.list` | read | POST `execute/getExecuteListByAi`；`current`/`pageSize` 必填；`templateId` 空仅返回表头 |
+| `fna.expense.reimbursed.sum` | read | POST `expense/center/getSumReimbursedAmountByAi`；body 可空 |
+| `fna.expense.loan.sum` | read | POST `expense/center/getSumLoanAmountByAi`；只认数字 ID；空 data 自动重试 2 次；已知仅统计首条记录缺陷 |
+| `fna.expense.prepay.writeoff.sum` | read | POST `expense/center/selectPrepayWriteOffAmountBySkill`；body 可空 |
+| `fna.loan.main.page` | read | POST `loanManagementMenu/mainPage` |
+| `fna.loan.main.list` | read | POST `loanManagementMenu/mainPageList`；`current`/`pageSize`/`menuCode`/`permissionSetCode` 必填 |
+| `fna.loan.remind.repay.prepare` | write | 校验 displayData 行并预览，不发送 |
+| `fna.loan.remind.repay.apply` | write | 需 `confirm:true` + continuation；行指纹与 prepare 一致 |
+| `fna.invoice.writeoff.summary` | read | POST `inv/financial/writeOffPageTab` |
+| `fna.invoice.writeoff.list` | read | POST `inv/financial/writeOffList`；`current`/`pageSize` 必填 |
+| `fna.invoice.writeoff.callticket.prepare` | write | 校验 requestids 并预览，不发送 |
+| `fna.invoice.writeoff.callticket.apply` | write | 需 `confirm:true` + continuation；指纹与 prepare 一致 |
+
+完整 schema（inputSchema/required/enum）以 `weaver-work-cli fna schema` 为准。`withheldOperations` 记录了未实现的按钮能力（确认已还、核销明细）与 ID 解析边界。
+
+## 常用命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json fna run fna.budget.application.detail --input-json '{"requestId":"1001"}'
+weaver-work-cli --json fna run fna.expense.reimbursed.sum --input-json '{"startDate":"2026-01-01","endDate":"2026-08-31"}'
+weaver-work-cli --json fna run fna.loan.main.list --input-json '{"current":1,"pageSize":20,"menuCode":"fesx_fna_borrowingManagement","permissionSetCode":"fesx_fna_borrowingManagement.default"}'
+weaver-work-cli --json fna run fna.invoice.writeoff.list --input-json '{"current":1,"pageSize":20,"invoiceStatus":"unarrivedTicket"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json fna run fna.budget.application.detail --input-json '{"requestId":"1001"}'
+weaver-work-cli --json fna run fna.expense.reimbursed.sum --input-json '{"startDate":"2026-01-01","endDate":"2026-08-31"}'
+weaver-work-cli --json fna run fna.loan.main.list --input-json '{"current":1,"pageSize":20,"menuCode":"fesx_fna_borrowingManagement","permissionSetCode":"fesx_fna_borrowingManagement.default"}'
+weaver-work-cli --json fna run fna.invoice.writeoff.list --input-json '{"current":1,"pageSize":20,"invoiceStatus":"unarrivedTicket"}'
+```
+
+写操作（提醒还款示例）：先用 `fna.loan.main.list` 取行 → 存 UTF-8 JSON 文件 → prepare → 向用户展示预览并取得明确确认 → apply（`--input` 传同一文件，apply 文件加 `confirm:true` 与 continuation）。Windows 用 `C:\path\to\loan-rows.json`、macOS/Linux 用 `/tmp/loan-rows.json`。
+
+## 口径与已知缺陷
+
+- 金额单位元：`data` 原始精度字符串、`displayData` 格式化；费用中心借款/预付核销接口金额实测可能返回字符串或数字。
+- 借款 `getSumLoanAmountByAi` 仅统计首条借款记录（for 循环内 return），汇报需注明口径。
+- 日期口径：报销按明细费用日期、借款按流程创建时间、预付核销按核销记录创建时间。
+- `menuCode`/`permissionSetCode` 环境相关，示例值需与环境核对。
+- 超 2^53 的 requestId 无法用 JS 数字精确表达，保留字符串并提示人工核验（真实环境 ID 一般在安全整数内，已按数字发送）。
+
+## 验证
+
+```text
+weaver-work-cli fna schema
+weaver-work-cli --json fna run fna.budget.application.detail --input-json '{"requestId":"<占位>"}'
+```
+
+对应测试：`test/business/fna-operations.test.ts`、`test/business/fna-host.test.ts`；layout 约束见 `test/skills/layout.test.ts`。

package/docs/hrm.md

@@ -0,0 +1,89 @@
+# 组织管理（hrm）
+
+`hrm` 是 E10 组织管理的聚合命令，覆盖**员工（employee）**、**组织（org）**、**岗位（position）** 三个业务域，全部为只读查询。
+
+```text
+weaver-work-cli hrm --help
+weaver-work-cli hrm schema
+weaver-work-cli --json hrm run <operation> --input -
+```
+
+`schema` 是能力清单的唯一事实来源，包含每个 operation 的 `inputSchema`、`risk`，以及禁用清单 `withheldOperations`（代理商查询 `hrm.employee.dls`）。
+
+## 实现位置
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/shortcuts/hrm/index.ts` | 命令注册与 JSON envelope |
+| `src/shortcuts/hrm/manifest.ts` | `schema` 契约与禁用边界声明 |
+| `src/shortcuts/hrm/host.ts` | E10 会话桥接、HRM 页面上下文 Referer、JSON 请求、响应归一化 |
+| `src/shortcuts/hrm/operations/` | 按业务域拆分的 operation 实现（employee / org / position） |
+| `src/shortcuts/hrm/operations/registry.ts` | operation 注册表与去重校验 |
+
+## 认证
+
+复用 `src/internal/e10` 的 E10 会话（`requireE10Session`），请求自动携带 `Cookie`、`eteamsid` 与 `X-Requested-With: XMLHttpRequest`。业务代码不接触认证目录。
+
+请求路径强制以 `/api/` 开头，并拒绝绝对路径、跨域 URL 与路径逃逸。
+
+HRM 接口必须携带页面上下文 `Referer`（默认 `<baseUrl>/hrm/main`），否则网关长时间无响应；组织卡片与岗位卡片详情由 operation 覆盖为 `/sp/hrm/orgCard/{id}`、`/sp/hrm/positionCard/{id}`。
+
+## 跨模块约定
+
+三个业务域统一走 E10 HRM 内部浏览/详情接口，响应统一 `WeaResult` 契约，由 `host.ts` 与 `operations/shared.ts` 归一化：
+
+**响应成功判定**：统一 `code=200`。`403`（接口开关未开启）抛 `api/permission_denied`，其余业务失败抛 `api/business_error`。
+
+**数据行位置**：
+
+| 接口类型 | 行字段 | 总数 |
+| --- | --- | --- |
+| 员工浏览 `employee.query` | `data.data` | `count/resource` 的 `data.total`（`data/resource` 的 `data.count` 恒为 0） |
+| 下属查询 `subordinate.mine` | `data.data` | `count/resource` 的 `data.total` |
+| 组织浏览 `org.query` | `data.data` | `data.total` |
+| 岗位浏览 `position.query` | `data.data` | `data.total` |
+| 岗位批量 `position.list` | `data.data` | `data.total` |
+| 批量人员 `employee.batch` | `data.userList` | 行数 |
+| 下属按 id `subordinate.by-id` | `data.page.result` | `data.page.totalCount` |
+
+**详情接口**（`employee.detail`/`org.detail`/`position.detail`）返回单对象，CLI 附 `link`。
+
+**长整型 id 一律按字符串传递**；**手机号已脱敏**（3 位前缀 + `****` + 末 4 位）。
+
+## 详情页卡片链接
+
+查询命中后，回答中一律用 `[名称](link)` 形式输出每个命中实体（`link` 由 CLI 在每行提供）：
+
+| 卡片 | link 路径 | 来源 operation |
+| --- | --- | --- |
+| 人员卡片 | `/sp/hrm/profileInfo/{id}` | `employee.query`/`employee.batch`/`subordinate.*`/`employee.detail` |
+| 组织卡片 | `/sp/hrm/orgCard/{id}` | `org.query`/`org.detail` |
+| 岗位卡片 | `/sp/hrm/positionCard/{id}` | `position.query`/`position.detail`/`position.list` |
+
+## 调用示例
+
+Windows PowerShell：
+
+```powershell
+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 -
+```
+
+## 禁用边界
+
+`withheldOperations` 中声明的能力不实现，也不要绕过：
+
+- **代理商查询**（`hrm.employee.dls`）：`containsDls=true` 仅泛微自用系统域名支持（自用域名白名单），客户/其他环境禁止触发。
+
+## 测试
+
+```text
+node --test --import tsx "test/business/hrm-operations.test.ts" "test/business/hrm-host.test.ts" "test/business/hrm-command.test.ts"
+```
+
+覆盖 manifest/registry 一致性、请求形状断言、收敛条件与全量拉取拦截、响应归一化、Referer 注入与路径白名单、错误形状。

package/docs/invoice.md

@@ -1,17 +1,17 @@
 # 业票通发票管理 CLI
 
-来源目录：`weaver-e10-yepiaotong`，内容版本 `1.1.0`。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli invoice` 命令，供 AI Agent 通过结构化 JSON 调用。
+来源目录：`weaver-e10-yepiaotong`，内容版本 `3.0.0`。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli invoice` 命令，供 AI Agent 通过结构化 JSON 调用。
 
 源码位于 `src/shortcuts/invoice`。命令注册、operation manifest 和业务执行逻辑分离；具体执行逻辑在 `src/shortcuts/invoice/operations` 中按 operation class 维护。
 
-面向 Agent 的说明位于 `skills/weaver-work-cli-invoice`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-work-cli-invoice/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。
+面向 Agent 的说明位于 `skills/weaver-e10-yepiaotong`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-e10-yepiaotong/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。
 
 ## 公共前置
 
 先通过 E10 鉴权模块登录：
 
-```bash
-weaver-work-cli auth login --base-url "https://weapp.xxx.cn"
+```text
+weaver-work-cli auth login --base-url "https://weapp.xxx.cn" --agent_type "<当前智能体名称>"
 weaver-work-cli auth status --no-check
 ```
 
@@ -27,13 +27,24 @@ Agent 不得在业务 JSON 中传 `access_token`、`app_key`、`app_secret`、Co
 
 优先使用 `invoice run <operation>`：
 
+Windows PowerShell：
+
+```powershell
+weaver-work-cli invoice schema
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
+```
+
+macOS/Linux（bash/zsh）：
+
 ```bash
 weaver-work-cli invoice schema
-echo '{"page_size":10,"start_pos":0}' | weaver-work-cli --json invoice run invoice.list --input -
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
 ```
 
 成功和失败都使用 JSON envelope。成功写 stdout；失败写 stderr，并设置非 0 退出码。
 
+当前输出层是完整 JSON 直接写 stdout，不提供飞书 CLI 的 `--jq`、`--format table/ndjson` 或通用 `--page-all`。Agent 使用时应默认小页读取和摘要渲染：列表先 `page_size=10`，按 `start_pos` 继续；回复只展示关键字段和数量，超长详情/OCR/调试 JSON 落本地文件后给路径。
+
 ## Operation 目录
 
 | Operation | 风险 | 固定规则 |
@@ -41,40 +52,75 @@ echo '{"page_size":10,"start_pos":0}' | weaver-work-cli --json invoice run invoi
 | `invoice.list` | 只读 | 个人票夹固定 `flag=0` |
 | `invoice.enterprise.list` | 只读 | 企业票夹固定 `flag=6`，权限失败不降级个人票夹 |
 | `invoice.get` | 只读 | `fid` 优先，或按 `number` 查询 |
-| `invoice.upload` | 外部制品 | 固定上传 `ocr=1` |
+| `invoice.upload` | 外部制品 | 固定上传 `ocr=0`，只取上传文件 ID，不做上传阶段解析 |
 | `invoice.ocr.preview` | 上传+只读 | 固定 `flag=13`、`is_sync=1`、`is_save=1`，不保存票夹 |
 | `invoice.validate.preview` | 外部查询 | 先取详情，固定 `flag=100`、`is_save=1`，不回写查验结果 |
-| `invoice.import.prepare/apply` | 高风险写 | continuation 绑定本地文件 SHA-256；显式声明 `validate` 和 `syncToOa` |
+| `invoice.import.prepare/apply` | 高风险写 | continuation 绑定本地文件 SHA-256；导入默认推荐 `validate=true`、`syncToOa=true` |
 | `invoice.add.prepare/apply` | 高风险写 | 单张票面校验、重复检查、确认后新增并回查 |
 | `invoice.update.prepare/apply` | 高风险写 | 基于完整详情修改白名单字段，保留附件并回查 |
 | `invoice.download` | 本地文件写 | 先校验 `fileId` 属于目标 `fid`，拒绝覆盖 |
 | `invoice.delete.prepare/apply` | 高风险写 | 固定软删除 `flag=0`，确认后执行并回查 |
-
-共享、转让和标签暂不暴露给 Agent：原始文档未给出稳定的接收人 `appid/cid/uid` 解析来源、标签关系查询和写后回查契约。
+| `invoice.browse-field.data` | 只读 | 基于详情接口生成流程表单发票浏览按钮 JSON |
+| `invoice.reim.file-ocr.preview` | 文件识别预览 | 对 E10 fileId 调用报销场景的发票识别接口，只保留成功项 |
+| `invoice.reim.requests.list` | 只读 | 查询事前申请流程列表，默认 `pageNo=1`、`pageSize=20` |
+| `invoice.reim.workflow.resolve` | 只读 | 根据事前申请 ID 获取报销工作流；无事前申请时传空数组 |
+| `invoice.reim.form.structure` | 只读 | 获取报销流程表单字段结构 |
+| `invoice.reim.row-info` | 只读 | 使用 urlencoded 请求获取单张发票明细行预填信息 |
+| `invoice.reim.employee-superiors` | 只读 | 获取当前人员和上级信息 |
+| `invoice.reim.field.search` | 只读 | 搜索表单关联字段值，用于用户修正或出差客户确认 |
+| `invoice.reim.flow.create.prepare/apply` | 高风险写 | continuation 绑定已组装报销单 payload；确认后调用 `createFlowNew` |
+| `invoice.reim.flow.update.prepare/apply` | 高风险写 | continuation 绑定更新 payload；确认后调用 `updateFlow` |
+| `invoice.issuing.make.prepare/apply` | 高风险写 | 固定销方信息，确认后调用 `makeInvoice` 开票或存台账 |
+
+共享、转让和标签仍暂不暴露给 Agent：新版源资料给出了提交接口，但还缺少稳定的接收人 `appid/cid/uid` 解析来源、标签关系查询和写后回查契约。
 
 ## 常用命令
 
-```bash
-weaver-work-cli --json invoice list --input -
-weaver-work-cli --json invoice enterprise list --input -
-weaver-work-cli --json invoice get --fid <fid>
+```text
+weaver-work-cli --json invoice list --input-json '{"page_size":10,"start_pos":0}'
+weaver-work-cli --json invoice enterprise list --input-json '{"page_size":10,"start_pos":0}'
+weaver-work-cli --json invoice get --fid INVOICE_FID
 weaver-work-cli --json invoice upload --file ./invoice.pdf
 weaver-work-cli --json invoice ocr preview --file ./invoice.pdf
-weaver-work-cli --json invoice validate preview --fid <fid> --scope personal
-weaver-work-cli --json invoice download --fid <fid> --file-id <fileId> --output ./invoice.pdf
+weaver-work-cli --json invoice validate preview --fid INVOICE_FID --scope personal
+weaver-work-cli --json invoice download --fid INVOICE_FID --file-id FILE_ID --output ./invoice.pdf
+weaver-work-cli --json invoice run invoice.browse-field.data --input-json '{"fid":"INVOICE_FID"}'
+weaver-work-cli --json invoice run invoice.reim.requests.list --input-json '{"pageNo":1,"pageSize":20}'
 ```
 
 写操作必须先 prepare，再 apply：
 
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"file":"./invoice.pdf"}'
+
+weaver-work-cli --json invoice import prepare --input-json '{"file":"./invoice.pdf","validate":true,"syncToOa":true}'
+
+weaver-work-cli --json invoice import apply --input-json '{"file":"./invoice.pdf","continuation":"PREPARE_CONTINUATION","confirm":true}'
+
+weaver-work-cli --json invoice run invoice.reim.flow.create.prepare --input .\reim-create.json
+
+weaver-work-cli --json invoice run invoice.issuing.make.prepare --input .\issuing.json
+```
+
+macOS/Linux（bash/zsh）：
+
 ```bash
-echo '{"file":"./invoice.pdf","validate":false,"syncToOa":false}' \
-  | weaver-work-cli --json invoice import prepare --input -
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"file":"./invoice.pdf"}'
+
+weaver-work-cli --json invoice import prepare --input-json '{"file":"./invoice.pdf","validate":true,"syncToOa":true}'
+
+weaver-work-cli --json invoice import apply --input-json '{"file":"./invoice.pdf","continuation":"PREPARE_CONTINUATION","confirm":true}'
 
-echo '{"file":"./invoice.pdf","continuation":"<prepare返回值>","confirm":true}' \
-  | weaver-work-cli --json invoice import apply --input -
+weaver-work-cli --json invoice run invoice.reim.flow.create.prepare --input ./reim-create.json
+
+weaver-work-cli --json invoice run invoice.issuing.make.prepare --input ./issuing.json
 ```
 
-`validate=false` 表示跳过查验，不能描述为“查验通过”。写操作出现网络中断、部分成功或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
+导入本地发票文件时，面向 Agent 的正常链路是先 `invoice.ocr.preview`，再 `invoice.import.prepare` 使用 `validate=true`、`syncToOa=true`。只有用户明确要求跳过查验或离线导入时才传 `validate=false`；`validate=false` 表示跳过查验，不能描述为“查验通过”。
+
+报销单创建和开票/存台账只接受 Agent 已组装好的 payload。CLI 不负责猜测事前申请匹配、出差客户或税率；这些规则在 Skill reference 中指导 Agent 组装和展示预览。写操作出现网络中断、部分成功、缺少回执 ID 或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
 
 ## 编辑白名单