weaver-work-cli 0.1.2 → 0.1.5

package/docs/agent-skill-install.md

@@ -1,31 +1,113 @@
 # Agent Skill 安装与升级
 
-本文说明如何把 `weaver-work-cli` 随包 Agent Skill（以 `invoice` 为例）安装或升级到本机 Agent 的 skill 目录。适用两类读者：
+本文说明如何把 `weaver-work-cli` 随包 Agent Skill（以 `yepiaotong` 为例）安装或升级到本机 Agent 的 skill 目录。适用两类读者：
 
 - 首次让 Codex / WorkBuddy 等 Agent 识别发票业务的使用者；
 - 在本仓库修改 Skill 内容后，需要把最新版同步到本机 Agent 环境的开发者。
 
-Agent 运行期调用规则不在这里，见 `skills/weaver-work-cli-shared/SKILL.md` 与 `skills/weaver-work-cli-invoice/SKILL.md`。人类视角的安装总览见 `README.md`。
+Agent 运行期调用规则不在这里，见 `skills/weaver-e10-shared/SKILL.md` 与 `skills/weaver-e10-yepiaotong/SKILL.md`。人类视角的安装总览见 `README.md`。
+
+本文命令示例按平台选择执行。涉及用户目录、路径、文件删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 应先判断当前环境，Windows 或 PowerShell 用 Windows 示例，macOS/Linux、bash 或 zsh 用 macOS/Linux 示例；不确定时用 `node -p "process.platform"` 判断。
+
+## Agent 自动安装 CLI 运行时
+
+如果安装 Skill 前发现 `weaver-work-cli` 命令不可用，Agent 可以在用户明确同意后代装运行时。提示必须让用户选择安装来源：npm 源，或本地代码。选择本地代码时，用户必须提供 `weaver-work-cli` 仓库目录的绝对路径。
+
+建议提示词：
+
+```text
+未检测到可用的 weaver-work-cli。是否允许我为当前智能体安装运行时？
+
+请选择安装来源：
+1. npm 源安装：使用当前 npm registry；如需公司私有 registry，请同时提供 registry 地址。
+2. 本地代码安装：请提供 weaver-work-cli 仓库目录的绝对路径。
+
+我会先检查 node/npm 版本，安装后再运行 weaver-work-cli --version 和 weaver-work-cli skills list 验证。
+```
+
+npm 源安装命令；如用户指定公司 registry，把 `npm install -g weaver-work-cli` 替换为 `npm install -g weaver-work-cli --registry "<NPM_REGISTRY_URL>"`：
+
+```text
+node --version
+npm --version
+npm config get registry
+npm install -g weaver-work-cli
+weaver-work-cli --version
+weaver-work-cli skills list
+```
+
+本地代码安装命令：
+
+Windows PowerShell：
+
+```powershell
+$WeaverWorkCliRoot = "C:\path\to\weaver-work-cli"
+if (-not (Test-Path "$WeaverWorkCliRoot\package.json")) { throw "invalid weaver-work-cli path" }
+Set-Location $WeaverWorkCliRoot
+npm install
+npm run build
+npm link
+weaver-work-cli --version
+weaver-work-cli skills list
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+WEAVER_WORK_CLI_ROOT="/path/to/weaver-work-cli"
+test -f "$WEAVER_WORK_CLI_ROOT/package.json" || exit 1
+cd "$WEAVER_WORK_CLI_ROOT"
+npm install
+npm run build
+npm link
+weaver-work-cli --version
+weaver-work-cli skills list
+```
 
 ## 最短命令
 
+Windows PowerShell：
+
+```powershell
+$AgentSkillsRoot = "C:\path\to\agent-skills"
+if (-not (Test-Path "$AgentSkillsRoot\weaver-e10-shared\SKILL.md")) {
+  weaver-work-cli skills install shared --target-dir "$AgentSkillsRoot"
+}
+weaver-work-cli skills install yepiaotong --target-dir "$AgentSkillsRoot"
+```
+
+macOS/Linux（bash/zsh）：
+
 ```bash
-weaver-work-cli skills install invoice --target-dir <目标skills目录>
+AGENT_SKILLS_ROOT="/path/to/agent-skills"
+if [ ! -f "$AGENT_SKILLS_ROOT/weaver-e10-shared/SKILL.md" ]; then
+  weaver-work-cli skills install shared --target-dir "$AGENT_SKILLS_ROOT"
+fi
+weaver-work-cli skills install yepiaotong --target-dir "$AGENT_SKILLS_ROOT"
 ```
 
-- `skills install invoice` 会同时安装 `weaver-work-cli-shared` 与 `weaver-work-cli-invoice`，无需分别安装。
-- 默认目标为 `$CODEX_HOME/skills`（未设置时 `~/.codex/skills`）；其它目录必须用 `--target-dir <path>` 显式指定。
+- Agent 代装业务 Skill 时，必须先判断目标目录里的 `weaver-e10-shared/SKILL.md` 是否存在；未安装时先执行 `weaver-work-cli skills install shared --target-dir "<agent-skills-root>"`，再安装业务 Skill。
+- `skills install yepiaotong` 的 CLI 层会同时安装 `weaver-e10-shared` 与 `weaver-e10-yepiaotong`，用于命令兜底；但提示词和自动安装流程仍需显式展示 shared 前置检查。
+- 默认目标优先使用环境变量 `CODEX_HOME` 下的 `skills` 子目录；未设置时使用用户主目录下的 `.codex/skills`。其它目录必须用 `--target-dir` 显式指定。
 - 安装是文件拷贝，不需要 E10 登录；登录只在执行业务命令（`invoice run ...`）前需要。
+- 名称支持短名（如 `skill-maker`）、全名 `weaver-e10-skill-maker` 和旧前缀 `weaver-work-cli-skill-maker`；旧前缀会转换为当前名称。建议使用短名，避免不同版本的前缀差异。
+- Skill 生成器拼写为 `maker`，不是 `marker`。名称不存在时会提示相近名称和查询命令，不会自动安装猜测的 Skill。
+
+安装 Skill 生成器到 WorkBuddy（macOS/Linux）：
+
+```bash
+weaver-work-cli skills install skill-maker --target-dir "$HOME/.workbuddy/skills"
+```
 
 ## 各 Agent 环境的 skill 目录
 
 | Agent 环境 | skill 根目录 | 安装方式 |
 | --- | --- | --- |
-| Codex CLI | `$CODEX_HOME/skills`，默认 `~/.codex/skills` | `skills install invoice`（默认目标） |
-| WorkBuddy（桌面端） | `~/.workbuddy/skills`（用户级） | `skills install invoice --target-dir ~/.workbuddy/skills` |
-| 其它 Agent | 由 Agent 配置决定 | `skills install invoice --target-dir <path>` |
+| Codex CLI | `CODEX_HOME` 下的 `skills`；默认用户主目录下的 `.codex/skills` | `skills install yepiaotong`（默认目标） |
+| WorkBuddy（桌面端） | 用户主目录下的 `.workbuddy/skills`（用户级） | Windows：`skills install yepiaotong --target-dir "$env:USERPROFILE\.workbuddy\skills"`；macOS/Linux：`skills install yepiaotong --target-dir "$HOME/.workbuddy/skills"` |
+| 其它 Agent | 由 Agent 配置决定 | `skills install yepiaotong --target-dir <path>` |
 
-不确定 Agent 读哪个目录时先问用户，不要盲目同时安装到多个目录。装到 `~/.workbuddy/skills` 不会同步 `~/.codex/skills`，反之亦然。
+不确定 Agent 读哪个目录时先问用户，不要盲目同时安装到多个目录。装到用户主目录下的 `.workbuddy/skills` 不会同步 `.codex/skills`，反之亦然。
 
 ## 核心事实（先读，避免误操作）
 
@@ -37,37 +119,74 @@ weaver-work-cli skills install invoice --target-dir <目标skills目录>
 
 ## 首次安装
 
+Windows PowerShell：
+
+```powershell
+# 1. 确认命令可用且能看到随包 Skill
+weaver-work-cli --version
+weaver-work-cli skills list
+
+# 2. 安装到目标目录（示例：WorkBuddy）
+weaver-work-cli skills install yepiaotong --target-dir "$env:USERPROFILE\.workbuddy\skills"
+
+# 3. 验证：结果是真实目录，不是软链
+Get-ChildItem -Force "$env:USERPROFILE\.workbuddy\skills"
+```
+
+macOS/Linux（bash/zsh）：
+
 ```bash
 # 1. 确认命令可用且能看到随包 Skill
 weaver-work-cli --version
 weaver-work-cli skills list
 
 # 2. 安装到目标目录（示例：WorkBuddy）
-weaver-work-cli skills install invoice --target-dir ~/.workbuddy/skills
+weaver-work-cli skills install yepiaotong --target-dir "$HOME/.workbuddy/skills"
 
 # 3. 验证：结果是真实目录，不是软链
-ls -la ~/.workbuddy/skills/
+ls -la "$HOME/.workbuddy/skills"
 ```
 
 ## 从本地开发仓库升级到最新
 
 在仓库根目录执行：
 
+Windows PowerShell：
+
+```powershell
+# 1. 前置检查：确认全局 CLI 来源与待发布的工作区状态
+Get-Command weaver-work-cli
+git status --short
+
+# 2. 重新构建，通过构建期 TS 校验（clean + tsc）
+npm run build
+
+# 3. 移除目标目录旧条目（软链/旧副本），再安装
+Remove-Item -Recurse -Force "$env:USERPROFILE\.workbuddy\skills\weaver-e10-yepiaotong", "$env:USERPROFILE\.workbuddy\skills\weaver-e10-shared"
+weaver-work-cli skills install yepiaotong --target-dir "$env:USERPROFILE\.workbuddy\skills"
+
+# 4. 验证安装的是最新内容（与仓库工作区一致）
+if ((Get-FileHash "skills\weaver-e10-yepiaotong\SKILL.md").Hash -ne (Get-FileHash "$env:USERPROFILE\.workbuddy\skills\weaver-e10-yepiaotong\SKILL.md").Hash) { throw "yepiaotong skill differs" }
+if ((Get-FileHash "skills\weaver-e10-shared\SKILL.md").Hash -ne (Get-FileHash "$env:USERPROFILE\.workbuddy\skills\weaver-e10-shared\SKILL.md").Hash) { throw "shared skill differs" }
+```
+
+macOS/Linux（bash/zsh）：
+
 ```bash
 # 1. 前置检查：确认全局 CLI 来源与待发布的工作区状态
-which weaver-work-cli
+command -v weaver-work-cli
 git status --short
 
 # 2. 重新构建，通过构建期 TS 校验（clean + tsc）
 npm run build
 
 # 3. 移除目标目录旧条目（软链/旧副本），再安装
-rm ~/.workbuddy/skills/weaver-work-cli-invoice ~/.workbuddy/skills/weaver-work-cli-shared
-weaver-work-cli skills install invoice --target-dir ~/.workbuddy/skills
+rm -rf "$HOME/.workbuddy/skills/weaver-e10-yepiaotong" "$HOME/.workbuddy/skills/weaver-e10-shared"
+weaver-work-cli skills install yepiaotong --target-dir "$HOME/.workbuddy/skills"
 
 # 4. 验证安装的是最新内容（与仓库工作区一致）
-diff -q skills/weaver-work-cli-invoice/SKILL.md ~/.workbuddy/skills/weaver-work-cli-invoice/SKILL.md
-diff -q skills/weaver-work-cli-shared/SKILL.md ~/.workbuddy/skills/weaver-work-cli-shared/SKILL.md
+diff -q skills/weaver-e10-yepiaotong/SKILL.md "$HOME/.workbuddy/skills/weaver-e10-yepiaotong/SKILL.md"
+diff -q skills/weaver-e10-shared/SKILL.md "$HOME/.workbuddy/skills/weaver-e10-shared/SKILL.md"
 ```
 
 构建失败（tsc 报错）时先修复 TS 错误再安装；`skills install` 的内容源不依赖 `dist/`，但发布前应保证仓库可构建。
@@ -76,17 +195,17 @@ diff -q skills/weaver-work-cli-shared/SKILL.md ~/.workbuddy/skills/weaver-work-c
 
 安装本身不校验业务 API。要确认对 Agent 生效：
 
-- 目录结构正确：`~/.workbuddy/skills/weaver-work-cli-invoice/{SKILL.md,product.json,references/}` 与 `weaver-work-cli-shared/{SKILL.md,references/}`。
-- 内容一致：上述 `diff` 无差异，或 `weaver-work-cli skills read weaver-work-cli-invoice` 与仓库一致。
+- 目录结构正确：用户主目录下的 `.workbuddy/skills/weaver-e10-yepiaotong` 包含 `SKILL.md`、`product.json`、`references/`，且 `weaver-e10-shared` 包含 `SKILL.md`、`references/`。
+- 内容一致：Windows 使用上述 `Get-FileHash`，macOS/Linux 使用上述 `diff -q`；或用 `weaver-work-cli skills read weaver-e10-yepiaotong` 与仓库内容比对。
 - **Agent 需重新加载**：新建会话或按 Agent 规则重载 Skill 后才读取新内容；已打开的会话不会热更新。
-- 业务可用性：安装后仍需完成 E10 登录（`weaver-work-cli auth login --base-url "<E10_BASE_URL>"`），并可按 `weaver-work-cli invoice schema` 验证 operation 契约。
+- 业务可用性：安装后仍需完成 E10 登录（`weaver-work-cli auth login --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"`），并可按 `weaver-work-cli invoice schema` 验证 operation 契约。
 
 ## 常见问题
 
 | 现象 | 处理 |
 | --- | --- |
 | `weaver-work-cli: command not found` | 先安装运行时：`npm install -g weaver-work-cli`，再 `setup invoice` |
-| 安装报 `ERR_FS_CP_DIR_TO_NON_DIR` | 目标目录对应条目是软链，先 `rm <target>/weaver-work-cli-*` 断链再安装 |
-| `unknown packaged skill` | 确认 `weaver-work-cli skills list` 输出的包内 Skill 名称；目标是全名或 `invoice` 等短名 |
+| 安装报 `ERR_FS_CP_DIR_TO_NON_DIR` | 目标目录对应条目是软链；Windows 用 `Remove-Item -Recurse -Force "C:\path\to\skills\weaver-e10-*"`，macOS/Linux 用 `rm -rf "/path/to/skills"/weaver-e10-*` 断链再安装 |
+| `unknown packaged skill` | 确认 `weaver-work-cli skills list` 输出的包内 Skill 名称；目标是全名或 `yepiaotong` 等短名 |
 | 改了仓库 Skill 但 Agent 看不到 | 已安装目录是拷贝，需重跑安装；且 Agent 需新会话重载 |
-| 需要离线/平台导入的独立归档 | 用 `npm run build:invoice-skill`，产物 `dist/weaver-work-cli-invoice-skill.zip`；日常本机安装优先用 `skills install` |
+| 需要离线/平台导入的独立归档 | 用 `npm run build:yepiaotong-skill`，产物 `dist/weaver-e10-yepiaotong-skill.zip`；日常本机安装优先用 `skills install` |

package/docs/calendar.md

@@ -0,0 +1,87 @@
+# 日程管理（calendar）
+
+`calendar` 是 E10 日程管理的聚合命令，覆盖**创建日程、查询列表、查询详情、查询总数、更新日程、删除日程、查询类型/紧急程度字典、应用版本检测** 8 类能力。
+
+```text
+weaver-work-cli calendar --help
+weaver-work-cli calendar schema
+weaver-work-cli --json calendar run <operation> --input-json '{"key":"value"}'
+```
+
+`schema` 是能力清单的唯一事实来源，包含每个 operation 的 `inputSchema`、`risk`、`requiresConfirmation`。
+
+## 实现位置
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/shortcuts/calendar/index.ts` | 命令注册与 JSON envelope |
+| `src/shortcuts/calendar/manifest.ts` | `schema` 契约 |
+| `src/shortcuts/calendar/host.ts` | E10 会话桥接、datajson/ESB 两类请求、响应归一化 |
+| `src/shortcuts/calendar/continuation.ts` | 写操作确认链的 HMAC-SHA256 token |
+| `src/shortcuts/calendar/operations/read.ts` | 读 operation（list/get/count/priority/type/app.check） |
+| `src/shortcuts/calendar/operations/write.ts` | 写 operation（create/update/delete prepare→apply） |
+| `src/shortcuts/calendar/operations/registry.ts` | operation 注册表与去重校验 |
+
+## 认证
+
+复用 `src/internal/e10` 的 E10 会话（`requireE10Session`），请求自动携带 `Cookie`、`eteamsid`、`User-Agent`。业务代码不接触认证目录。所有 `datajson` 结构接口的 `header.operator` 由 CLI 自动填充为当前登录用户。
+
+## operation 清单
+
+| operation | 类型 | 用途 |
+| --- | --- | --- |
+| `calendar.list` | read | 分页查询日程列表（ESB 流程触发，`uniqueIndent` 固定） |
+| `calendar.get` | read | 按 ID 查询单条日程详情 |
+| `calendar.count` | read | 查询日程总数 |
+| `calendar.priority.list` | read | 查询紧急程度选项 |
+| `calendar.type.list` | read | 查询日程类型选项 |
+| `calendar.app.check` | read | 应用版本检测（要求 >= 4.1.4） |
+| `calendar.create.prepare` / `.apply` | high-risk-write | 创建日程 |
+| `calendar.update.prepare` / `.apply` | high-risk-write | 更新日程（全量覆盖） |
+| `calendar.delete.prepare` / `.apply` | high-risk-write | 删除日程（不可逆） |
+
+## 两类请求结构
+
+- **datajson 结构**（创建/查询详情/总数/更新/删除/类型/紧急程度）：请求体 `{datajson: {...}}`，业务成功判定 `datajson.status === true`。
+- **ESB 直接 JSON**（列表查询）：请求体 `{customParams, moduleSource, uniqueIndent}`，业务成功判定 `resultCode === 200`。
+
+`host.ts` 的 `isBusinessSuccess` 统一判定，operation 层无需关心差异。
+
+## 写操作确认链
+
+创建、更新、删除全部走 `prepare -> apply`：
+
+1. `prepare` 只归一化、补默认值、查当前数据（更新/删除）、生成预览和 continuation，不写入。
+2. `apply` 必须带 `confirm=true` 与 prepare 返回的 continuation。
+3. continuation 绑定 `baseUrl`/`profile`/`userId`，10 分钟有效；变化触发 `context_mismatch`，字段指纹变化触发 `target_changed`。
+4. 网络中断抛 `partial/write_uncertain`，禁止自动重试，先做只读回查。
+
+## 关键业务规则
+
+- **参与人默认带当前人**：未传 `participants` 自动用当前用户；指定他人时当前人仍默认包含。
+- **时长默认 1 小时**：只传 `start_time` 时自动补 `end_time`。
+- **更新为全量覆盖**：`update.prepare` 先查当前详情，把 `[{name,id}]` 数组字段转标量 ID 再合并用户修改。
+- **Switch 字段**（`all_day`/`remind`/`part_receipt`）传数字 `0`/`1`，禁止布尔值。
+- **`agn_type`/`priority` 传选项 ID**，`participants` 传人员 ID，均非语义字符串/姓名。
+
+## 调用示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json calendar run calendar.list --input-json '{"page_no":1,"page_size":10}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+printf '%s\n' '{"page_no":1,"page_size":10}' | weaver-work-cli --json calendar run calendar.list --input -
+```
+
+## 测试
+
+```text
+node --test --import tsx "test/business/calendar-*.test.ts"
+```
+
+覆盖 manifest/registry 一致性、请求形状断言、写操作确认链、响应归一化与错误形状。

package/docs/e10-auth.md

@@ -4,35 +4,41 @@ E10 适配模块刻意与核心 CLI 框架隔离，避免平台逻辑污染通
 
 存储路径与密钥：
 
-- 鉴权根目录：`~/.weaver-work-cli/e10`
-- Profile 目录：`~/.weaver-work-cli/e10/profiles/<profile>`
-- 当前激活 profile：`~/.weaver-work-cli/e10/profile`
+- 鉴权根目录：通过 `weaver-work-cli auth root` 查看；默认位于用户主目录下的 `.weaver-work-cli/e10`（Windows PowerShell：`$env:USERPROFILE\.weaver-work-cli\e10`；macOS/Linux：`$HOME/.weaver-work-cli/e10`）
+- Profile 目录：`profiles/<profile>`（位于鉴权根目录下）
+- 当前激活 profile：`profile`（位于鉴权根目录下）
 - Keychain service/account：`weaver-work-cli` / `auth-key`
 - 发票业务 Token Keychain service：`cn.weaver.weaver-work-cli.invoice-token`
 
-`weaver-work-cli` 默认不读取、不迁移 `e10-login` / `e10-cli` 的 `~/.e10-cli`
+`weaver-work-cli` 默认不读取、不迁移 `e10-login` / `e10-cli` 的旧 `.e10-cli`
 登录态，避免用户安装本插件后因为历史登录状态被自动授权。确需复用外部 auth
 文件时，可以显式传 `--auth <path>` 或设置 `E10_AUTH_PATH`。
 
 主要命令：
 
-```bash
+```text
 weaver-work-cli auth status
 weaver-work-cli auth login --base-url "https://weapp.xxx.cn"
 weaver-work-cli auth oidc --base-url "https://weapp.xxx.cn"
+weaver-work-cli auth xiaoe
 weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx" --base-url "https://weapp.xxx.cn"
 weaver-work-cli auth whoami
 weaver-work-cli auth whoami --live
 weaver-work-cli auth logout
 weaver-work-cli auth profile list
-weaver-work-cli auth profile use <name>
+weaver-work-cli auth profile use PROFILE_NAME
 weaver-work-cli auth export-weaver-env
 ```
 
 `auth login` 和 `auth oidc` 都走 E10 OAuth2.0 浏览器授权登录，本地默认监听
 `http://127.0.0.1:19800/callback`。如端口被占用，可以使用
 `--port 19801` 指定其他端口；如需要区分客户端来源，可以使用
-`--agent_type <value>`，默认值为 `weaver-work-cli`。
+`--agent_type <value>`。未显式传入时，CLI 会依次读取 `WEAVER_AGENT_TYPE`、
+`WORKBUDDY_AGENT_TYPE`、`CODEX_AGENT_TYPE`，再根据 `WORKBUDDY_*` / `CODEX_*`
+环境变量推断当前宿主，最后回落为 `weaver-work-cli`。浏览器授权地址会同时携带
+`agent_type=<value>` 和 `from=<value>`，其中 `from` 用于 E10 授权确认页展示客户端名称。
+
+小 E 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 会先尝试从 `XIAOE_*` 环境变量读取当前域名对应的统一登录凭证。域名匹配且凭证可用时，CLI 直接保存登录态，保存的 `agentType` 固定为 `Xiao.E`；未显式传域名时，会优先使用小 E 环境变量里的首个支持域名，其次才使用当前 profile 配置，仍没有支持域名时保留资料包默认域名 `https://www.e-cology.com.cn`。业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试小 E 统一登录。小 E 凭证校验失败、当前域名不在支持范围内，或用户切换了访问域名时，会自动降级到原浏览器 OAuth2.0 登录。
 
 无法使用浏览器回调时，可以用 `auth set` 直接写入浏览器中复制到的
 `ETEAMSID`。命令会调用 `teamsCheck` 解析当前用户、租户和组织信息，并写入
@@ -41,7 +47,10 @@ E10 兼容的 auth 文件。
 `auth whoami` 默认读取本地缓存，不发网络请求；`auth whoami --live` 会调用
 `teamsCheck` 获取实时信息。`auth export-weaver-env` 会输出
 `WEAVER_BASE_URL`、`WEAVER_ETEAMSID`、`WEAVER_COOKIE`、`WEAVER_USER_AGENT` 和
-`WEAVER_AGENT_TYPE`，可通过下面方式注入到当前 shell：
+`WEAVER_AGENT_TYPE`。默认 `--shell auto` 会在 Windows 输出 PowerShell 语法，在
+macOS/Linux 输出 POSIX shell 语法；也可显式使用 `--shell powershell` 或
+`--shell posix`。Agent 给子进程使用登录态时，仍优先通过 `weaver-work-cli run ...`
+自动注入，避免在回复或日志中展示敏感值。
 
 `auth login`、`auth oidc` 和 `auth set` 保存新登录态前，会清理同一
 profile/baseUrl/userId 下缓存的发票业务 Token，避免重登后继续复用旧 Token。
@@ -50,6 +59,16 @@ profile/baseUrl/userId 下缓存的发票业务 Token，避免重登后继续复
 `--profile <name>` 清理指定 profile。该命令不删除 profile 配置和登录加密用
 keychain 密钥。
 
+Windows PowerShell：
+
+```powershell
+Invoke-Expression (weaver-work-cli auth export-weaver-env --shell powershell)
+weaver-work-cli run node -e "console.log(process.env.WEAVER_BASE_URL || 'no e10 auth')"
+```
+
+macOS/Linux（bash/zsh）：
+
 ```bash
-eval "$(weaver-work-cli auth export-weaver-env)"
+eval "$(weaver-work-cli auth export-weaver-env --shell posix)"
+weaver-work-cli run node -e "console.log(process.env.WEAVER_BASE_URL || 'no e10 auth')"
 ```

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 无数据库通道，只能由调用方查得后传入。