weaver-work-cli 0.1.1 → 0.1.4

package/dist/shortcuts/plan/operations.js

@@ -0,0 +1,8 @@
+import { getPlanOperation } from './operations/registry.js';
+import { asObject, assertNoForbiddenKeys } from './operations/shared.js';
+export async function executePlanOperation(operation, rawInput, context) {
+    const definition = getPlanOperation(operation);
+    const input = asObject(rawInput);
+    assertNoForbiddenKeys(input);
+    return definition.handler(input, context);
+}

package/docs/SKILL.md

@@ -6,22 +6,22 @@
 
 - `src/cmd`：框架内置命令、平台命令和 `skills list/read`。
 - `src/internal/e10`：E10 session、profile、auth 文件和 API client。
-- `src/shortcuts`：面向人和 Agent 的高层业务 CLI 能力，按业务模块分目录；模块内每个业务 operation 用相对独立的 class 封装。
-- `skills`：随包发布的 Agent Skill，按业务模块分目录；每个模块对应一个独立 Skill，入口 `SKILL.md` 只做路由，具体操作细节放到 `references/`，公共约束通过 `weaver-work-cli-shared` 复用。
+- `src/shortcuts`：面向人和 Agent 的高层业务 CLI 能力，按业务模块分目录；模块内每个业务 operation 用相对独立的 class 封装。使用 Skill Maker 新增业务模块时，默认同步生成或更新对应 shortcut。
+- `skills`：随包发布的 Agent Skill，按业务模块分目录；每个模块对应一个独立 Skill，入口 `SKILL.md` 只做路由，具体操作细节放到 `references/`，公共约束通过 `weaver-e10-shared` 复用。
 - `skill-template`：新增或重写业务 Skill 的模板来源；结构参考飞书 CLI 的 `skill-template`，用于保持入口、路由关键词、业务域说明和 reference 拆分方式一致。
 
 使用内置 docs 命令可以把当前文档目录复制到业务工作区：
 
-```bash
+```text
 weaver-work-cli docs copy
 ```
 
-后续业务 shortcut 应在 `src/shortcuts/<name>` 下维护源码，在 `skills/weaver-work-cli-<name>` 下维护对应 Agent Skill，在 `_catalog.md` 和 `skill-template/business-info.json` 中补充对应的加载规则。业务 Skill 直接声明并调用 `weaver-work-cli` bin，不为每个业务模块复制 bootstrap 脚本。
+后续业务模块应在 `src/shortcuts/<name>` 下维护源码，在 `skills/weaver-e10-<name>` 下维护对应 Agent Skill，在 `_catalog.md` 和 `skill-template/business-info.json` 中补充对应的加载规则。新增或更新模块时，先按 `skills/weaver-e10-skill-maker/references/module-cli-generation.md` 定正确实现面、operation 合约、测试断言和 Skill/CLI 一致性。业务 Skill 直接声明并调用 `weaver-work-cli` bin，不为每个业务模块复制 bootstrap 脚本。
 
 业务 Skill 目录约定：
 
 ```text
-skills/weaver-work-cli-<name>/
+skills/weaver-e10-<name>/
   SKILL.md                  入口路由：共享规则、schema、reference 索引、禁用边界。
   product.json              可选：Skill 包元信息。
   references/               具体业务 reference，按用户意图和 operation 分文件。
@@ -31,6 +31,10 @@ skills/weaver-work-cli-<name>/
 
 ## 已内置业务模块
 
-- `invoice`：E10 业票通发票管理。源码说明先读 `docs/invoice.md`；面向 Agent 时先读 `skills/weaver-work-cli-invoice/SKILL.md`，再按入口路由读取对应 reference。
+- `invoice`：E10 业票通发票管理。源码说明先读 `docs/invoice.md`；面向 Agent 时先读 `skills/weaver-e10-yepiaotong/SKILL.md`，再按入口路由读取对应 reference。
+- `fna`：E10 齐业成费控中心（预算查询/费用中心/借款管理/发票核销）。源码说明先读 `docs/fna.md`；面向 Agent 时先读 `skills/weaver-e10-qiyecheng/SKILL.md`，再按入口路由读取对应 reference。写操作（提醒还款/催票）走 prepare/apply 确认链。
+- `plan`：E10 计划报告（报告查询/新建/修改/发布/撤回/提交提醒/评论），自动适配标准版与 e10-ebuilder 两套报告接口链路。源码说明先读 `docs/plan.md`；面向 Agent 时先读 `skills/weaver-e10-plan/SKILL.md`，再按入口路由读取对应 reference。写操作走 prepare/apply 确认链。
+- `esb`：E10 ESB 中心自定义触发动作流（入参模板查询 + 触发）。源码说明先读 `docs/esb.md`；面向 Agent 时先读 `skills/weaver-e10-esb/SKILL.md`，再按入口路由读取对应 reference。触发动作流是写操作，走 prepare/apply 确认链。
+- `skill-maker`：把用户提供的新业务模块文档或代码转换成 `weaver-e10-*` Agent Skill，通过源资料指纹检测更新，用泛微技能检测工具做发布前静态质检，并在检测通过后询问是否安装到当前智能体。面向 Agent 时先读 `skills/weaver-e10-skill-maker/SKILL.md`。
 
-Agent 调用业务能力时优先使用 `weaver-work-cli --json invoice run <operation> --input -`，不要绕过 CLI 直接拼业务 HTTP。
+Agent 调用业务能力时优先使用 `weaver-work-cli --json <command> run <operation> --input-json '<json>'`；复杂或多行 JSON 用 UTF-8 文件和 `--input <path>`，只有确认当前 shell 能稳定传管道时才使用 `--input -`。不要绕过 CLI 直接拼业务 HTTP。新增业务模块时，如果源资料不足以实现 CLI，先向用户列出缺口并确认，不生成假 operation。

package/docs/_catalog.md

@@ -5,8 +5,26 @@
 | CLI 框架、钩子、system/platform/business 分层、新增模块 | `docs/SKILL.md` |
 | E10 鉴权、profile、共享 API client | `docs/e10-auth.md` |
 | Agent Skill 模板、业务域关键词、入口和 reference 拆分方式 | `skill-template/` |
-| Agent 共享规则、安装检查、JSON 输出、高风险写入 | `skills/weaver-work-cli-shared/SKILL.md` |
-| Agent 共享规则细节：安装、E10 登录、JSON 输出、写入协议 | `skills/weaver-work-cli-shared/references/` |
-| 业票通发票管理、invoice operation、写操作 prepare/apply | `docs/invoice.md` |
-| Agent 调用业票通 CLI 的入口路由 | `skills/weaver-work-cli-invoice/SKILL.md` |
-| Agent 调用业票通 CLI 的具体 reference | `skills/weaver-work-cli-invoice/references/` |
+| Agent 共享规则、安装检查、JSON 输出、高风险写入 | `skills/weaver-e10-shared/SKILL.md` |
+| Agent 共享规则细节：安装、E10 登录、JSON 输出、写入协议 | `skills/weaver-e10-shared/references/` |
+| 业票通发票管理、报销填单、智能开票、invoice operation、写操作 prepare/apply | `docs/invoice.md` |
+| 聚才林人事云（人事档案/出勤/薪酬）、ehr operation、写操作 prepare/apply | `docs/ehr.md` |
+| 齐业成费控中心（预算/费用中心/借款管理/发票核销）、fna operation、提醒还款与催票 prepare/apply | `docs/fna.md` |
+| 文书定档案管理（全宗/检索/借阅车/借阅单/发起借阅/预归档上传）、wenshuding operation | `docs/wenshuding.md` |
+| 计划报告管理（报告查询/新建/修改/发布/撤回/提交提醒/评论）、plan operation、写操作 prepare/apply | `docs/plan.md` |
+| E10 ESB 中心自定义触发动作流（入参模板查询 / prepare-apply 触发）、esb operation | `docs/esb.md` |
+| 快速安装 CLI，并使用 CLI/Skill Maker 生成、验证、打包和安装业务模块 Skill | `docs/operation-manual.md` |
+| 把随包 Agent Skill 安装/升级到本机 Agent（Codex/WorkBuddy 目录、从本地仓库发布最新版） | `docs/agent-skill-install.md` |
+| Agent 调用业票通 CLI 的入口路由 | `skills/weaver-e10-yepiaotong/SKILL.md` |
+| Agent 调用业票通 CLI 的具体 reference | `skills/weaver-e10-yepiaotong/references/` |
+| Agent 调用聚才林 CLI 的入口路由 | `skills/weaver-e10-jucailin/SKILL.md` |
+| Agent 调用聚才林 CLI 的具体 reference | `skills/weaver-e10-jucailin/references/` |
+| Agent 调用文书定 CLI 的入口路由 | `skills/weaver-e10-wenshuding/SKILL.md` |
+| Agent 调用文书定 CLI 的具体 reference | `skills/weaver-e10-wenshuding/references/` |
+| Agent 调用齐业成费控 CLI 的入口路由 | `skills/weaver-e10-qiyecheng/SKILL.md` |
+| Agent 调用齐业成费控 CLI 的具体 reference | `skills/weaver-e10-qiyecheng/references/` |
+| Agent 调用计划报告 CLI 的入口路由 | `skills/weaver-e10-plan/SKILL.md` |
+| Agent 调用计划报告 CLI 的具体 reference | `skills/weaver-e10-plan/references/` |
+| Agent 调用 ESB 动作流 CLI 的入口路由 | `skills/weaver-e10-esb/SKILL.md` |
+| Agent 调用 ESB 动作流 CLI 的具体 reference | `skills/weaver-e10-esb/references/` |
+| 将新业务模块文档或代码同步转换为 weaver-work-cli 业务 CLI 与 Skill、检测源资料更新 | `skills/weaver-e10-skill-maker/SKILL.md` |

package/docs/agent-invoice.md

@@ -4,13 +4,13 @@
 
 安装后的 Agent Skill 已拆为入口和 references：
 
-- `skills/weaver-work-cli-shared/SKILL.md`：安装检查、E10 认证、JSON 输出、高风险写入和安全边界。
-- `skills/weaver-work-cli-invoice/SKILL.md`：业票通入口路由。
-- `skills/weaver-work-cli-invoice/references/`：按 schema、查询、文件预览、写入、暂缓能力拆分的具体说明。
+- `skills/weaver-e10-shared/SKILL.md`：安装检查、E10 认证、JSON 输出、高风险写入和安全边界。
+- `skills/weaver-e10-yepiaotong/SKILL.md`：业票通入口路由。
+- `skills/weaver-e10-yepiaotong/references/`：按 schema、查询、文件预览、流程发票字段、报销、开票、写入和暂缓能力拆分的具体说明。
 
 ## 准备
 
-```bash
+```text
 weaver-work-cli --version
 weaver-work-cli doctor --e10
 weaver-work-cli invoice schema
@@ -18,35 +18,56 @@ weaver-work-cli invoice schema
 
 如未登录，先让用户完成：
 
-```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 "<当前智能体名称>"
 ```
 
 ## 固定入口
 
-Agent 优先使用：
+Agent 优先使用统一 operation 入口。简单 JSON 用 `--input-json`，复杂 JSON 用临时文件和 `--input <path>`；只有确认当前 shell 能稳定传管道时才使用 `--input -`。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
+```
+
+macOS/Linux（bash/zsh）：
 
 ```bash
-weaver-work-cli --json invoice run <operation> --input -
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
 ```
 
 不要直接 `curl`、`fetch` 或浏览器自动化访问 E10 `/api/inc/*`。不要输出或索取 Cookie、ETEAMSID、发票 Token。
 
+## 输出与大数据处理
+
+当前项目的输出方式是 JSON envelope 直接写 stdout，失败 envelope 写 stderr；不像飞书 CLI 已内置 `--format table/pretty/ndjson`、`--jq` 和通用翻页参数。因此 Agent 调用时要主动控量：
+
+- 列表默认 `page_size=10`，需要更多时再按 `start_pos` 分页。
+- 回复用户时只展示结论、数量、关键字段和下一步，不要原样粘完整 stdout JSON。
+- 发票列表/详情优先展示 `fid`、代码/号码、购销方、金额、日期、查验/报销状态和附件摘要。
+- 全量统计按页读取并只累计必要字段；超长 OCR、详情或调试 JSON 需要保留时落本地文件，再返回路径和摘要。
+
 ## 推荐工作流
 
 处理“把这张发票录入业票通”的典型流程：
 
 1. 查询个人票夹和企业票夹，确认目标不存在。
 2. `invoice.ocr.preview` 预览文件识别结果，预览阶段固定不保存。
-3. 用户确认后执行 `invoice.import.prepare`，输入必须显式包含 `validate` 和 `syncToOa`。
+3. 用户确认后执行 `invoice.import.prepare`，输入必须显式包含 `validate` 和 `syncToOa`；默认传 `validate=true`、`syncToOa=true`，表示导入时请求服务端查验并按服务端要求同步 OA。
 4. 把 prepare 返回的 `continuation` 原样交给 `invoice.import.apply`，并传 `confirm=true`。
 5. 使用返回的 `fid` 回查详情，按实际结果报告查验状态、写入状态和附件信息。
 
+只有用户明确要求跳过发票查验或离线导入时，Agent 才能传 `validate=false`。这种结果必须报告为“跳过查验”，不能写成“查验通过”。
+
 删除、编辑、新增同样必须使用 `prepare -> apply`。出现 `partial/write_uncertain` 时停止，不能自动重试写操作。
 
+处理“把发票填进流程表单”的场景，使用 `invoice.browse-field.data` 生成浏览按钮控件所需 JSON。处理“报销发票/自动填单”时，先读取 `invoice-reim.md`，用报销相关只读 operation 获取事前申请、工作流、表单结构、预填信息和人员上级；Agent 组装 payload 后，必须通过 `invoice.reim.flow.create.prepare/apply` 或 `invoice.reim.flow.update.prepare/apply` 写入。处理“开票/存台账”时，先读取 `invoice-issuing.md`，字段提取、税率确认和金额校验完成后，再走 `invoice.issuing.make.prepare/apply`。
+
 ## 暂缓能力
 
-以下原始接口文档存在，但当前不暴露为 Agent 操作：
+以下新版源资料已有提交接口，但当前仍不暴露为 Agent 操作：
 
 - 共享发票：缺接收人的稳定 `appid/cid/uid` 解析和共享关系回查契约。
 - 转让发票：会改变持有人，缺接收人侧归属回查契约。

package/docs/agent-skill-install.md

@@ -0,0 +1,211 @@
+# Agent Skill 安装与升级
+
+本文说明如何把 `weaver-work-cli` 随包 Agent Skill（以 `yepiaotong` 为例）安装或升级到本机 Agent 的 skill 目录。适用两类读者：
+
+- 首次让 Codex / WorkBuddy 等 Agent 识别发票业务的使用者；
+- 在本仓库修改 Skill 内容后，需要把最新版同步到本机 Agent 环境的开发者。
+
+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
+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"
+```
+
+- 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 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`，反之亦然。
+
+## 核心事实（先读，避免误操作）
+
+1. **内容源是包内 `skills/` 目录**，不经过编译；`npm run build` 只保证 CLI 代码通过构建期 TS 校验，不产出 Skill。
+2. **`skills install` 是拷贝语义**：装出的是真实副本，不与源目录联动。之后源里改动 Skill，已安装目录不会自动更新，需重跑安装；覆盖安装只写入与覆盖同名文件，**不会清理目标里已不存在的旧文件**，需要干净结果时先整目录移除再安装。
+3. **目标目录已有旧条目（旧副本或软链）时不能直接覆盖**：命令内部是递归拷贝，目标为软链时会报 `ERR_FS_CP_DIR_TO_NON_DIR` 失败；先移除该条目再安装（移除软链只断链，不影响其指向的目录）。
+4. **本机 CLI 若为 `npm link` 指向本地仓库**，`skills list/install` 反映的是仓库当前工作区内容，包含未提交改动——开发期可直接发布最新工作区。
+5. 拷贝会过滤 dotfiles、`scripts/`、`assets/`、`node_modules/`；`SKILL.md`、`references/`、`product.json` 会完整拷贝。
+
+## 首次安装
+
+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 yepiaotong --target-dir "$HOME/.workbuddy/skills"
+
+# 3. 验证：结果是真实目录，不是软链
+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 来源与待发布的工作区状态
+command -v weaver-work-cli
+git status --short
+
+# 2. 重新构建，通过构建期 TS 校验（clean + tsc）
+npm run build
+
+# 3. 移除目标目录旧条目（软链/旧副本），再安装
+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-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/`，但发布前应保证仓库可构建。
+
+## 验证清单与生效
+
+安装本身不校验业务 API。要确认对 Agent 生效：
+
+- 目录结构正确：用户主目录下的 `.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>" --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` | 目标目录对应条目是软链；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: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')"
 ```