weaver-work-cli 0.1.1 → 0.1.4

package/docs/jiuchuanhui.md

@@ -0,0 +1,131 @@
+# 九氚汇营销管理 CLI
+
+来源目录：`weaver-e10-jiuchuanhui`，内容版本 `1.1.1`。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli jiuchuanhui` 命令，供 AI Agent 通过结构化 JSON 调用。
+
+源码位于 `src/shortcuts/jiuchuanhui`。命令注册、operation manifest 和业务执行逻辑分离；具体执行逻辑在 `src/shortcuts/jiuchuanhui/operations` 中按 operation class 维护。
+
+面向 Agent 的说明位于 `skills/weaver-e10-jiuchuanhui`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-e10-jiuchuanhui/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。
+
+## 公共前置
+
+先通过 E10 鉴权模块登录：
+
+```text
+weaver-work-cli auth login --base-url "https://jchdemo.e-cology.cn" --agent_type "<当前智能体名称>"
+weaver-work-cli auth status --no-check
+```
+
+每个九氚汇业务请求由 CLI 托管：
+
+1. 读取当前 `weaver-work-cli auth` Profile 的 E10 会话。
+2. 根据 operation 的 body mode 组装请求体（ESB 动作流 / eBuilder datajson）。
+3. 自动携带 Cookie、ETEAMSID、User-Agent，业务输入中禁止再传这些 key。
+
+Agent 不得在业务 JSON 中传 Cookie、ETEAMSID、Token 或内部控制字段；CLI 会拒绝这些 key。
+
+## Agent 入口
+
+优先使用 `jiuchuanhui run <operation>`：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli jiuchuanhui schema
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli jiuchuanhui schema
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.search --input-json '{"customer_name":"小康","mine":"","all":"-1","customerSea":"-1","pageNo":1,"pageSize":10}'
+```
+
+成功和失败都使用 JSON envelope。成功写 stdout；失败写 stderr，并设置非 0 退出码。
+
+当前输出层是完整 JSON 直接写 stdout，不提供飞书 CLI 的 `--jq`、`--format table/ndjson` 或通用 `--page-all`。Agent 使用时应默认小页读取和摘要渲染：列表先 `pageNo=1`、`pageSize=10`，按 `pageNo` 继续；回复只展示关键字段和数量，超长详情 JSON 落本地文件后给路径。
+
+## Operation 目录
+
+| Operation 组 | 风险 | 固定规则 |
+| --- | --- | --- |
+| `jiuchuanhui.app.discovery` / `form.discovery` / `ds.fields` / `field.options` / `rest.cfg.detail` / `config.id.by.pk` / `file.preview` / `get-rest-cfg-detail` | 只读 | 发现与配置；`file.preview` 需先确认文件内容 |
+| `jiuchuanhui.customer.create.prepare/apply` | 高风险写 | 创建前必须查重；`detail2` 同步创建联系人 |
+| `jiuchuanhui.customer.get` / `search` / `type/status/industry.search` / `open-sea.search` / `duplicate.check` | 只读 | 搜索必须显式传 `mine`/`all`/`customerSea`；`count:true` 并行取总数 |
+| `jiuchuanhui.customer.update/transfer/open-sea.release/open-sea.claim/contact-record.create/contact-record.batch` 的 prepare/apply | 高风险写 | 转移/释放/领取需确认唯一性与影响 |
+| `jiuchuanhui.contact.create/update` prepare/apply | 高风险写 | 联系人随客户创建时勿重复调用 |
+| `jiuchuanhui.contact.get` / `by-entity.search` | 只读 | 只给姓名先查候选再让用户选择 |
+| `jiuchuanhui.sale.create/update` prepare/apply | 高风险写 | 按配置 `data_key` 组装 |
+| `jiuchuanhui.sale.get` / `search` / `stage.search` / `process.search` / `lose-reason.search` / `rival.search` | 只读 | 阶段/原因选项供写操作取 ID |
+| `jiuchuanhui.sale.win/lose/invalid/pause/restart/manager-change/link-contacts/contact-record.create` 的 prepare/apply | 高风险写 | 赢单/输单/无效不可逆；输单先取原因；转移与负责人变更共用 |
+| `jiuchuanhui.clue.create/update/status-change/to-customer/contact-record.create` 的 prepare/apply | 高风险写 | 状态变更是覆盖型；转新客户走 `customer.create` 传 `source_module_id` |
+| `jiuchuanhui.clue.get` / `search` / `pool.search` | 只读 | 线索池列表 |
+| `jiuchuanhui.contact-plan.create/complete` prepare/apply | 高风险写 | `type` 与关联字段联动 |
+| `jiuchuanhui.entity.contact-records.list` / `contact-records.by-person-time.list` | 只读 | 联系记录查询 |
+| `jiuchuanhui.entity.id.by-name` / `user.id.by-name` / `user.current-profile` / `entity.permission.judge` / `company.business-profile.query` / `field.info.by-ids` / `browser-option.search` | 只读 | 通用辅助；行政区划也走 `entity.id.by-name` |
+
+缓存初始化（`cache.init`）与商机阶段推进（`stage-advance`）不暴露为 CLI operation：前者是 Agent 侧本地状态维护，后者依赖缓存阶段配置做映射，属于 Skill 编排层职责。
+
+## 常用命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.search --input-json '{"pageNo":1,"pageSize":10,"count":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"userName":"魏思雨"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"customerName":"示例科技有限公司"}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.get --input-json '{"id":"100001"}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.search --input-json '{"pageNo":1,"pageSize":10,"count":true}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.user.id.by-name --input-json '{"mainTable":{"userName":"魏思雨"}}'
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.duplicate.check --input-json '{"mainTable":{"customerName":"示例科技有限公司"}}'
+```
+
+写操作必须先 prepare，再 apply：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input .\customer-create.json
+
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.prepare --input-json '{"saleId":"200001"}'
+
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.prepare --input ./customer-create.json
+
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.customer.create.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.prepare --input-json '{"saleId":"200001"}'
+
+weaver-work-cli --json jiuchuanhui run jiuchuanhui.sale.win.apply --input-json '{"continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+## 写操作确认链
+
+- `prepare` 只预览和生成 continuation（HMAC 签名，绑定当前登录上下文与参数）。
+- 向用户摘要目标、差异、风险和 continuation 绑定含义。
+- 用户明确确认后才调用 `apply`（`confirm:true` + 有效 continuation）。
+- `apply` 不可盲目重试；遇到 `partial/write_uncertain` 先停止，再做一次只读回查（如 `customer.get`/`sale.get`/`clue.get`）。
+
+写操作出现网络中断、部分成功、缺少回执 ID 或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
+
+## 业务规则摘要
+
+- 选项字段（Select/RadioBox/CheckBox）必须先取选项 ID 再传值；`RelateBrowser` 字段通过 `browser-option.search` 查对应类型选项。
+- 行政区划传逗号分隔全路径 ID（`country,province,city,district`），传细粒度自动填充粗粒度。
+- 客户搜索必须显式传 `mine`/`all`/`customerSea` 三个 key（一个 `""` 其余 `-1`），没有 `scope` 快捷参数。
+- 列表、卡片及详情中的关联事项名称渲染为可点击链接 `https://{baseUrl}/sp/ebdfpage/card/0/{objId}/{dataId}`。
+- 新建客户前先查重；客户在公海时提醒可领取。
+- 线索转新客户走客户创建且传 `source_module_id=<clueId>`，成功后不再额外修改线索。

package/docs/operation-manual.md

@@ -0,0 +1,443 @@
+# weaver-work-cli 操作手册
+
+本文面向普通使用者和业务模块建设者，说明如何快速安装 `weaver-work-cli`，以及如何使用随包能力生成、验证、打包和安装业务模块 Agent Skill。
+
+## 1. 适用范围
+
+`weaver-work-cli` 是面向泛微工作工具链的 TypeScript CLI。框架层保持业务无关，E10 登录、profile 和 HTTP client 由 `src/internal/e10` 托管，具体业务能力放在 `src/shortcuts/<module>`，对应的 Agent Skill 放在 `skills/weaver-e10-<module>`。
+
+当前随包内置业务模块：
+
+| 模块 | CLI 命令 | Agent Skill | 说明 |
+| --- | --- | --- | --- |
+| 业票通 | `weaver-work-cli invoice` | `weaver-e10-yepiaotong` | 发票查询、详情、OCR/查验、下载、导入/新增/编辑/删除确认链 |
+| 文书定 | `weaver-work-cli wenshuding` | `weaver-e10-wenshuding` | 全宗、档案检索、借阅车、借阅单、发起借阅、预归档上传 |
+| Skill Maker | `weaver-work-cli skills ...` + Agent 生成流程 | `weaver-e10-skill-maker` | 把新业务模块资料转换成业务 CLI 与 Skill，并做检测和安装确认 |
+
+注意：当前 CLI 不提供独立的 `skills generate` 子命令。新业务模块的生成由 `weaver-e10-skill-maker` 这个 Agent Skill 编排完成；CLI 提供运行时、`schema/run` 合约、随包 Skill 读写安装能力和打包脚本。
+
+## 2. 环境要求
+
+- Node.js 18 或更高版本。
+- npm。
+- 可访问组织 npm registry 或本地源码包。
+- 执行业务 operation 前需要 E10 登录；仅安装 Agent Skill 不需要登录。
+
+本手册的命令示例按平台选择执行。完全相同的 `node`、`npm`、`git` 和 `weaver-work-cli` 命令可作为通用示例；涉及 JSON 输入、用户目录、路径分隔符、Python 启动器、文件删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 应先判断当前环境，Windows 或 PowerShell 用 Windows 示例，macOS/Linux、bash 或 zsh 用 macOS/Linux 示例；不确定时用 `node -p "process.platform"` 判断。Windows/PowerShell 下不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。
+
+## 3. 快速安装 CLI
+
+### 3.1 从 npm 或公司 registry 安装
+
+```text
+npm install -g weaver-work-cli
+weaver-work-cli --version
+weaver-work-cli --help
+weaver-work-cli commands list
+weaver-work-cli skills list
+```
+
+`skills list` 能输出 `weaver-e10-shared`、`weaver-e10-yepiaotong`、`weaver-e10-wenshuding`、`weaver-e10-skill-maker` 等条目，说明发布包中的 Skill 内容可读。
+
+### 3.2 从源码安装到本机全局命令
+
+```text
+git clone GIT_REPO_URL weaver-work-cli
+cd weaver-work-cli
+npm install
+npm run build
+npm link
+weaver-work-cli --version
+```
+
+如果怀疑全局命令指向旧版本，可在仓库根目录直接调用当前构建产物：
+
+```text
+node dist/index.js --version
+node dist/index.js commands list
+node dist/index.js skills list
+```
+
+### 3.3 从本地 tgz 包安装
+
+Windows PowerShell：
+
+```powershell
+cd C:\path\to\weaver-work-cli
+npm install
+npm run build
+npm pack
+npm install -g .\weaver-work-cli-VERSION.tgz
+weaver-work-cli --version
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+cd /path/to/weaver-work-cli
+npm install
+npm run build
+npm pack
+npm install -g ./weaver-work-cli-VERSION.tgz
+weaver-work-cli --version
+```
+
+## 4. 登录和可用性检查
+
+执行业务接口前先登录 E10：
+
+```text
+weaver-work-cli auth login --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"
+weaver-work-cli auth status
+weaver-work-cli doctor --e10
+```
+
+如果不能打开浏览器登录，也可以手动写入当前浏览器中的 `ETEAMSID`：
+
+```text
+weaver-work-cli auth set --eteamsid "<PCACCOUNT_xxx>" --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"
+weaver-work-cli auth whoami --live
+```
+
+`<当前智能体名称>` 使用发起登录验证的宿主标识，例如 WorkBuddy 用 `workbuddy`，Codex 用 `codex`。CLI 会把该值同时写入授权 URL 的 `agent_type` 和 `from` 参数；未显式传入时，CLI 会尝试从环境变量推断。
+
+多环境可用 profile 隔离：
+
+```text
+weaver-work-cli auth profile list
+weaver-work-cli auth profile use PROFILE_NAME
+weaver-work-cli --profile PROFILE_NAME auth status
+```
+
+认证、Cookie、Token 只应通过 `weaver-work-cli auth ...` 管理。不要让 Agent 直接读取、复制或展示本机认证文件、Keychain、Cookie、`ETEAMSID` 或业务 Token。
+
+## 5. 安装已有业务模块 Skill
+
+### 5.1 安装到 Codex 默认目录
+
+```text
+weaver-work-cli skills install yepiaotong
+weaver-work-cli skills install wenshuding
+```
+
+默认目标目录优先使用环境变量 `CODEX_HOME` 下的 `skills` 子目录；未设置 `CODEX_HOME` 时使用用户主目录下的 `.codex/skills`（Windows PowerShell 示例：`$env:USERPROFILE\.codex\skills`）。安装非 shared 业务 Skill 时，CLI 会自动带上 `weaver-e10-shared`。
+
+### 5.2 安装到 WorkBuddy 或其它 Agent
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli skills install yepiaotong --target-dir "$env:USERPROFILE\.workbuddy\skills"
+weaver-work-cli skills install wenshuding --target-dir "$env:USERPROFILE\.workbuddy\skills"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli skills install yepiaotong --target-dir "$HOME/.workbuddy/skills"
+weaver-work-cli skills install wenshuding --target-dir "$HOME/.workbuddy/skills"
+```
+
+其它 Agent 使用自己的 skills 根目录：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli skills install MODULE_NAME --target-dir "C:\path\to\agent-skills"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli skills install MODULE_NAME --target-dir "/path/to/agent-skills"
+```
+
+`<module>` 可以传短名，例如 `yepiaotong`、`wenshuding`、`skill-maker`，也可以传完整名，例如 `weaver-e10-yepiaotong`。传 `all` 会安装包内全部 Skill。
+
+### 5.3 验证安装结果
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli skills list
+weaver-work-cli skills read weaver-e10-yepiaotong
+weaver-work-cli skills list weaver-e10-yepiaotong/references
+Get-ChildItem -Force "C:\path\to\agent-skills"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli skills list
+weaver-work-cli skills read weaver-e10-yepiaotong
+weaver-work-cli skills list weaver-e10-yepiaotong/references
+ls -la "/path/to/agent-skills"
+```
+
+Agent 需要新建会话或按宿主规则重载 Skill 后才会读取新内容。
+
+### 5.4 安装语义
+
+- `skills install` 是文件拷贝，不是软链；源目录后续修改不会自动同步到已安装目录。
+- 覆盖安装只覆盖同名文件，不会清理目标目录里源端已删除的旧文件；需要干净升级时先移除目标 Skill 目录再安装。
+- 拷贝会过滤 dotfile、`scripts/`、`assets/`、`node_modules/`，保留 `SKILL.md`、`product.json`、`references/` 等文本内容。
+- 目标已有软链时可能报 `ERR_FS_CP_DIR_TO_NON_DIR`，先删除目标软链或旧副本再重装。
+
+## 6. 使用业务 CLI
+
+Agent 和自动化脚本优先使用统一 JSON operation 入口：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli MODULE_NAME schema
+weaver-work-cli --json MODULE_NAME run MODULE_NAME.operation --input-json '{"key":"value"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli MODULE_NAME schema
+weaver-work-cli --json MODULE_NAME run MODULE_NAME.operation --input-json '{"key":"value"}'
+```
+
+示例：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli invoice schema
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
+
+weaver-work-cli wenshuding schema
+weaver-work-cli --json wenshuding run wenshuding.search --input-json '{"key":"合同","page":0,"page_size":10}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli invoice schema
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
+
+weaver-work-cli wenshuding schema
+weaver-work-cli --json wenshuding run wenshuding.search --input-json '{"key":"合同","page":0,"page_size":10}'
+```
+
+成功输出统一 JSON envelope：
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "operation": "<module>.<action>",
+  "data": {},
+  "meta": { "status": "COMPLETE" },
+  "warnings": []
+}
+```
+
+失败也会输出结构化 envelope，重点看 `error.type`、`error.subtype`、`error.message` 和退出码。写入类 operation 采用 `prepare -> apply`，`apply` 必须携带 `confirm: true` 和 prepare 返回的 continuation；写请求已发出后如出现 `partial/write_uncertain`，不要自动重试，先做只读回查。
+
+## 7. 启用业务模块 Skill 生成能力
+
+先把 Skill Maker 安装到当前 Agent 的 skills 目录：
+
+```text
+weaver-work-cli skills install skill-maker
+```
+
+WorkBuddy 示例：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli skills install skill-maker --target-dir "$env:USERPROFILE\.workbuddy\skills"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli skills install skill-maker --target-dir "$HOME/.workbuddy/skills"
+```
+
+安装后新建 Agent 会话，并用类似提示触发生成流程：
+
+```text
+请使用 weaver-e10-skill-maker，把 <源资料路径或文档列表> 转换为 <module> 业务模块。
+
+要求：
+- 模块短名：<module>
+- 输出到当前 weaver-work-cli 仓库
+- 同步生成或更新 src/shortcuts/<module> 与 skills/weaver-e10-<module>
+- 生成的 docs、Skill reference、提示词和 CLI 示例必须同时兼容 Windows 和 macOS/Linux；涉及 JSON 输入、用户目录、路径、Python、删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例，并让 Agent 根据当前环境选择；Windows/PowerShell 简单 JSON 优先使用 `--input-json`，复杂 JSON 使用临时 UTF-8 文件和 `--input <path>`，不要使用 `printf`
+- 只实现源资料能确认的 operation；资料不足的能力写入禁用边界或待确认清单
+- 生成后运行 schema、测试和泛微技能检测工具
+- 检测通过后询问我是否安装到 <agent-skills-root>
+```
+
+源资料至少应提供：
+
+- 业务模块短名，例如 `contract`、`expense-claim`。
+- 接口文档、现有代码、样例 JSON、业务说明或已有 Skill。
+- 每个 operation 的接口路径、请求方法、关键字段、分页语义和返回结构。
+- 写入、删除、导入、上传等高风险操作的确认条件、幂等要求和写后回查方式。
+- 权限、租户、scope、固定参数和不可自动化边界。
+
+如果这些事实不足，Skill Maker 会只生成已能确认的能力，并把缺口列出来让用户确认；它不应编造接口、字段或写入确认链。
+
+## 8. 生成后的产物结构
+
+一个新业务模块生成后，默认会同步维护这些文件：
+
+```text
+src/shortcuts/<module>/
+  index.ts
+  manifest.ts
+  operations.ts
+  errors.ts
+  host.ts
+  continuation.ts
+  operations/
+    registry.ts
+    types.ts
+    shared.ts
+    <operation>.ts
+
+skills/weaver-e10-<module>/
+  SKILL.md
+  product.json
+  references/
+    <operation-or-topic>.md
+    source-manifest.json
+
+docs/<module>.md
+skill-template/business-info.json
+skill-template/domains/<module>.md
+test/business/<module>-*.test.ts
+```
+
+分工规则：
+
+- `manifest.ts` 和 `<module> schema` 拥有 operation、字段、风险、权限、固定参数等 WHAT 合约。
+- `docs/<module>.md` 说明维护者视角的 WHEN：模块来源、命令结构、operation 表和安全边界。
+- `skills/weaver-e10-<module>/SKILL.md` 只做 Agent 路由、共享规则入口、工作流和禁用边界。
+- `references/*.md` 写具体 HOW：命令示例、输入要点、输出处理、失败处理和回查策略。
+- `source-manifest.json` 记录源资料路径、大小、sha256 和聚合指纹，后续源资料更新时先比较差异，再确认是否覆盖生成结果。
+
+## 9. 验证、检测和打包
+
+在仓库根目录验证生成结果：
+
+```text
+npm run build
+npm test -- test/skills/layout.test.ts
+npm test -- "test/business/MODULE_NAME-*.test.ts"
+weaver-work-cli MODULE_NAME schema
+weaver-work-cli skills read weaver-e10-MODULE_NAME
+```
+
+使用泛微技能检测工具做静态质检：
+
+Windows PowerShell：
+
+```powershell
+py -3 ..\weaver-skill-detector-1.0.13\scripts\validate_skill.py skills\weaver-e10-MODULE_NAME --json --no-html
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+python3 ../weaver-skill-detector-1.0.13/scripts/validate_skill.py skills/weaver-e10-MODULE_NAME --json --no-html
+```
+
+检测通过后打包：
+
+```text
+node scripts/package-skill.mjs MODULE_NAME
+```
+
+该脚本使用纯 Node 生成 ZIP，不依赖系统 `zip`/`unzip` 命令，Windows、macOS 和 Linux 下命令一致。
+
+默认输出：
+
+```text
+dist/weaver-e10-<module>-skill.zip
+```
+
+打包单个业务模块时会自动包含 `weaver-e10-shared`。zip 用于平台导入、离线分发或版本归档；本机日常安装优先使用 `weaver-work-cli skills install <module>`。
+
+## 10. 安装新生成的业务模块 Skill
+
+检测通过并得到用户确认后安装：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli skills install MODULE_NAME --target-dir "C:\path\to\agent-skills"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli skills install MODULE_NAME --target-dir "/path/to/agent-skills"
+```
+
+如果全局命令还没更新，但当前仓库已构建，可用当前构建产物安装：
+
+Windows PowerShell：
+
+```powershell
+node dist/index.js skills install MODULE_NAME --target-dir "C:\path\to\agent-skills"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+node dist/index.js skills install MODULE_NAME --target-dir "/path/to/agent-skills"
+```
+
+安装后验证：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli skills list
+weaver-work-cli skills read weaver-e10-MODULE_NAME
+Get-ChildItem -Force "C:\path\to\agent-skills\weaver-e10-shared"
+Get-ChildItem -Force "C:\path\to\agent-skills\weaver-e10-MODULE_NAME"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli skills list
+weaver-work-cli skills read weaver-e10-MODULE_NAME
+ls -la "/path/to/agent-skills/weaver-e10-shared"
+ls -la "/path/to/agent-skills/weaver-e10-MODULE_NAME"
+```
+
+## 11. 升级已有业务模块
+
+源文档或代码更新后，用下面的提示让 Agent 先做差异检测：
+
+```text
+请使用 weaver-e10-skill-maker，检查 <module> 的源资料 <路径> 是否相对
+skills/weaver-e10-<module>/references/source-manifest.json 发生变化。
+先给出新增、删除、sha256 变化；如果 manifest 有 sourceChunks/operationImpact，
+再列出变化 chunk、锚点、可能影响的 operation、schema、reference、测试和写入确认链，
+然后问我是否同步转换。
+```
+
+确认转换后，Agent 才应更新 `src/shortcuts/<module>`、`skills/weaver-e10-<module>`、测试、docs、`business-info.json`、domain 文件和 manifest。无变化时不要重写 Skill；只有文件级变化但 chunk 未变时，也要先说明差异并等待确认。
+
+## 12. 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| `weaver-work-cli: command not found` | 先执行 `npm install -g weaver-work-cli` 或在源码仓库 `npm link` |
+| `unknown packaged skill` | 先运行 `weaver-work-cli skills list`，确认传入的是短名或完整 Skill 名 |
+| Agent 安装后没识别新 Skill | 新建会话或按 Agent 规则重载 Skill；确认安装到了该 Agent 实际读取的 skills 目录 |
+| 安装后内容不是最新 | `skills install` 是拷贝语义，重新安装；需要干净升级时先删除旧目标目录 |
+| 目标目录已有软链导致安装失败 | 删除该目标条目后重试，例如删除 `<agent-skills-root>/weaver-e10-<module>` |
+| `schema` 能看见但业务执行失败 | 先 `weaver-work-cli auth status` 和 `doctor --e10`，再看失败 envelope 的 `error.type/subtype` |
+| 生成器要求补资料 | 按 `operation -> 缺少事实 -> 为什么阻断` 补接口路径、字段、权限、幂等或回查契约 |

package/docs/plan.md

@@ -0,0 +1,82 @@
+# plan — 泛微E10计划报告
+
+`plan` 模块把 E10「计划报告」的两套报告侧接口链路（e10 标准版 / e10-ebuilder 版）收敛成一组业务 operation，供人和 Agent 统一调用。源资料为「E10 标准报告和 eb 报告整合 skill」目录下的标准版接口说明、ebuilder 其他接口说明、ebuilder 自定义接口说明与补充说明规则。
+
+## 模块来源
+
+- `e10标准版本计划报告接口说明文档.docx`：新建报告、修改报告、发布报告、撤回报告、按报告 id 或按周期查询单个报告详情、分页查询共享我的报告、发送报告提交提醒、获取某个报告的评论。
+- `e10-ebuilder版本计划报告其他接口说明文档.docx`：eb 链路发布报告（secondev 二开接口）、撤回报告（ESB 动作流）。
+- `e10-ebuilder版本计划报告自定义接口说明文档.zip`：创建报告、编辑报告、按周期查询单个报告详情、分页查询报告、查询报告版本信息。
+- `补充说明规则.txt`：意图判定、版本路由、作业步骤链、eb/标准版专属规则、通用基础规则。
+
+## CLI 结构
+
+```text
+weaver-work-cli plan --help
+weaver-work-cli plan schema
+weaver-work-cli --json plan run <operation> --input-json '<json>'
+weaver-work-cli --json plan run <operation> --input <path>
+```
+
+便捷子命令（均为薄包装，最终调用同一 operation）：
+
+- `plan route` → `plan.version.check`
+- `plan get` → `plan.report.get`
+- `plan list` → `plan.report.page`
+
+源码结构：
+
+```text
+src/shortcuts/plan/
+  index.ts            Commander 命令注册、schema/run、便捷子命令
+  manifest.ts         operation 合约清单、链路路由元信息、禁用边界
+  operations.ts       run 入口：选择 handler、校验输入、统一执行
+  errors.ts           结构化错误（validation/authentication/network/api/policy/confirmation/partial）
+  host.ts             E10 请求适配 + 租户级缓存读写
+  continuation.ts     prepare/apply 写入链的确认凭据签发与校验
+  operations/
+    registry.ts       manifest 与 handler 一一对应校验
+    types.ts          operation 类型、统一 JSON Schema 片段、报告枚举与标签
+    shared.ts         输入校验、字段归一化、报告结构归一化、默认提醒文案
+    link.ts           版本路由与租户缓存、eb 表单 id 解析、报告详情查询
+    version.ts        plan.version.check、plan.eb.form.resolve
+    read.ts           plan.report.get、plan.report.page、plan.comment.list
+    write.ts          新建/修改/发布/撤回/提交提醒的 prepare 与 apply
+```
+
+## operation 表
+
+| operation | 风险 | 说明 |
+| --- | --- | --- |
+| `plan.version.check` | read | 判定租户报告链路（缓存 1 天；`ver_name=V2` → eb） |
+| `plan.eb.form.resolve` | read | 解析 eb 报告详情表单 id（idobjId），按租户长期缓存 |
+| `plan.report.get` | read | 按 id 或按周期查询单份报告详情，附带评论总条数（标准版） |
+| `plan.report.page` | read | 分页查询报告列表 |
+| `plan.comment.list` | read | 报告评论内容（标准版） |
+| `plan.report.create.prepare` / `.apply` | read-before-write / high-risk-write | 新建报告（含周期查重） |
+| `plan.report.update.prepare` / `.apply` | read-before-write / high-risk-write | 修改报告 |
+| `plan.report.publish.prepare` / `.apply` | read-before-write / high-risk-write | 发布报告 |
+| `plan.report.withdraw.prepare` / `.apply` | read-before-write / high-risk-write | 撤回报告（标准版） |
+| `plan.report.remind.prepare` / `.apply` | read-before-write / high-risk-write | 发送提交提醒（标准版） |
+
+## 关键设计
+
+- **链路路由由 CLI 负责**：`plan_searchAppver` 读到 `ver_name = V2` 走 eb 链路，其它走标准版；结果按租户缓存 1 天。Agent 只传业务字段，不选接口。
+- **输出归一化**：eb 链路的 `f_*` 字段统一归一化为业务键（`reportId` / `title` / `content` / `summary` / `plans` / `year` / `type` / `serialNumber` / `postStatus` / `postTime` / `creator` / `detailUrl`），避免把数据库字段名暴露给 Agent 与用户。
+- **详情页链接**：标准版 `/sp/plan/detail/{id}`；eb 版 `/sp/ebdfpage/card/0/{表单id}/{id}`，表单 id 由 `plan.eb.form.resolve` 解析并长期缓存，租户 `tt1pa2w2i3` 使用固定值。
+- **写入链**：`prepare` 只读回查 + 预览 + 签发 continuation；`apply` 强制 `confirm=true` 与有效 continuation，并校验登录上下文与链路未变化。写请求发出后网络中断返回 `partial/write_uncertain`，禁止自动重试。
+- **查重**：`create.prepare` 与 `create.apply` 都会按周期查重；已存在时 `prepare` 返回 `ALREADY_EXISTS`，`apply` 直接报 `report_exists`，杜绝重复创建。
+
+## 已知限制
+
+- eb 链路「撤回报告」是 ESB 动作流，源资料未提供动作流唯一标识（uniqueIndent），本模块不实现；改用 weaver-e10-customesb-execute skill 执行同名动作流。对应 `plan.report.withdraw.*` 在 eb 链路返回 `policy/link_unsupported`。
+- eb 链路未提供报告提交提醒、报告评论接口，`plan.report.remind.*`、`plan.comment.list` 在 eb 链路返回 `policy/link_unsupported`。
+- eb 链路没有「按报告 id 查询详情」的接口，只有按周期查询；`prepare` 阶段若缺少 `year`/`type`/`serialNumber` 会跳过写入前校验并在 `warnings` 中说明。
+- 标准版分页接口语义为「共享给我的报告」，不支持按创建人筛选，传入 `creatorUserId` 会被忽略并返回警告。
+
+## 安全边界
+
+- 只调用 `/api/` 前缀路径，拒绝跨域、路径逃逸与协议外地址。
+- 认证、Cookie、ETEAMSID、User-Agent 由 `src/internal/e10` 统一托管；业务输入不接收凭证。
+- 不读取、不打印认证目录与认证文件。
+- 租户缓存只落地版本判定结果与 eb 表单 id，不缓存任何凭证或报告正文。