weaver-work-cli 0.1.1 → 0.1.4

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

@@ -0,0 +1,86 @@
+---
+name: weaver-e10-shared
+display_name: 泛微CLI共享规则
+display_name_en: Weaver CLI Shared Rules
+description: weaver-work-cli 共享规则：安装检查、E10 认证、JSON 输出、高风险写入、安全边界和引用路由。
+description_zh: weaver-work-cli 共享规则：安装检查、E10 认证、JSON 输出、高风险写入、安全边界和引用路由。
+description_en: Shared rules for weaver-work-cli, including installation checks, E10 authentication, JSON output, high-risk writes, safety boundaries, and reference routing.
+version: 1.0.0
+author: 泛微网络科技股份有限公司
+agent_created: true
+requires:
+  bins: ["weaver-work-cli"]
+---
+
+# weaver-work-cli 共享规则
+
+所有 `weaver-e10-*` Skill 共享的底座：命令可用性、E10 认证、JSON 输出契约、大结果渲染与高风险操作。
+
+## 最高优先级：小 E 统一登录
+
+如果当前运行在小 E 宿主环境，或任务上下文/环境变量显示存在 `XIAOE_*`，登录处理必须优先走小 E 统一登录：
+
+1. 未登录、登录失效、准备执行业务命令前需要确认 E10 会话，或 `auth status --no-check` 显示未登录时，先运行：
+   ```text
+   weaver-work-cli auth xiaoe
+   ```
+2. 不得因为本地存在旧 profile、`auth profile current` 指向旧环境，或 `auth profile list` 里只有旧环境，就跳过小 E 统一登录；也不得先要求用户选择旧 profile 或输入域名。
+3. 小 E 统一登录由 CLI 消费宿主注入的 `XIAOE_*` 域名/凭证映射。Agent 不要打印、转述、索取或要求用户手动设置 `XIAOE_*`、Cookie、ETEAMSID、业务 Token。
+4. 统一登录走不通、CLI 仍缺少真实域名或需要用户决策时，才进入旧版“让用户确认 E10 登录域名或选择已有 profile”的流程；具体细节读取 [`e10-auth-and-session.md`](references/e10-auth-and-session.md)。
+5. `auth status --no-check` 只是本地诊断，不会主动触发小 E 统一登录；业务命令和 `auth xiaoe` 才会尝试写入统一登录态。
+
+## 通用准则
+
+1. 执行业务命令前先确认用法：优先读当前业务 Skill 和被路由到的 reference，必要时跑对应命令的 `--help` 或 `schema`，不要猜参数。
+
+2. 首次使用先确认 CLI 可用：
+
+```text
+weaver-work-cli --version
+weaver-work-cli doctor --e10
+```
+
+如果命令不可用，先读 [`weaver-e10-installation.md`](references/weaver-e10-installation.md)，让用户选择 npm 源安装或本地代码安装；本地代码必须提供仓库目录。用户明确同意后才执行 `npm install -g weaver-work-cli`、`npm install`、`npm run build` 或 `npm link`。
+
+3. 业务输入只描述业务对象和意图。认证、Cookie、ETEAMSID、业务 Token、接口地址和回查细节都由 CLI 托管。调用业务 operation 时，简单 JSON 优先使用 `--input-json '<json>'`；复杂或多行 JSON 先写入 UTF-8 `.json` 文件再传 `--input <path>`；只有确认当前 shell 能稳定传管道时才使用 `--input -`。生成或改写 docs、reference、提示词和命令示例时，必须同时兼容 Windows 和 macOS/Linux；涉及 JSON 输入、用户目录、路径分隔符、Python 启动器、文件删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。Windows/PowerShell 下不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。
+
+4. 认证诊断只能通过 `weaver-work-cli auth root/status/profile list/profile current`、`weaver-work-cli doctor --e10` 和业务命令 JSON 错误完成。禁止直接列目录、打印、复制或解析用户态认证目录和认证文件。
+
+5. 涉及附件、图片、本地文件、远程 URL 文件或文件内容解析的操作，执行前必须先向用户说明：文件内容可能会被上传到业务系统、OCR/解析服务，并可能进入当前大模型上下文用于理解和处理。必须等待用户明确确认后，才继续上传、读取、解析、OCR、导入或复用已上传文件对象；用户未确认时只说明风险和所需确认，不执行相关命令。
+
+## 输出契约
+
+Agent 调用业务能力时优先加 `--json`。成功看进程退出码 0 和 JSON envelope 的 `ok=true`；失败看非 0 退出码和 stderr JSON 的 `error.type/subtype/message`。不要用老式 `code == 0` 判断成功。
+
+返回 `partial`、`write_uncertain`、登录失效、回查失败或网络中断时，立即停止当前写流程，不自动重试写入或删除。
+
+当前 CLI 的 JSON 输出是完整 envelope 直接写 stdout；没有飞书 CLI 那种通用 `--jq`、`--format table/ndjson` 或 `--page-all`。列表、详情、OCR、导出等可能产生大响应时，必须先读 [`json-output-contract.md`](references/json-output-contract.md) 的“大结果渲染与提效规则”：默认小页读取、只保留任务所需字段、分页有预算，回复用户时给摘要和路径，不要原样粘贴超长 JSON。
+
+## Reference 强触发索引
+
+命中任一触发条件时，执行下一步前读取对应 reference。命中多条时按表中顺序读取，同一 reference 只读取一次。
+
+| 强触发条件 | Reference |
+| --- | --- |
+| 命令不可用、Agent 自动安装 CLI、安装、构建、全局 link、检查可用 skill | [`weaver-e10-installation.md`](references/weaver-e10-installation.md) |
+| 登录、profile、E10 会话、baseUrl、auth 文件、`WEAVER_*` / `XIAOE_*` 环境变量；**未登录或登录失效（小 E 先自动尝试，其它场景需要用户提供登录域名）** | [`e10-auth-and-session.md`](references/e10-auth-and-session.md) |
+| 判断 stdout/stderr、JSON envelope、退出码、脚本封装、自动化调用、大结果渲染/分页控量 | [`json-output-contract.md`](references/json-output-contract.md) |
+| 准备执行写入/删除/导入/更新、遇到 `confirmation.required`、`partial.write_uncertain`、网络中断或回查失败 | [`high-risk-write.md`](references/high-risk-write.md) |
+
+## 安全规则
+
+1. 禁止输出或索取 Cookie、ETEAMSID、业务 Token、access token、app key、app secret。
+
+2. 禁止读取、列出、打印、复制或解析任何 `e10-login` / `e10-cli` 历史认证目录，例如用户主目录下的旧 `.e10-cli`；也禁止直接读取 `auth`、`config.json` 或 Keychain 项来推断登录态。
+
+3. 禁止绕过 `weaver-work-cli` 直接 `curl`、`fetch`、浏览器自动化或访问 E10 业务接口。
+
+4. 写入、删除、导入、更新等高风险操作必须使用 CLI 提供的确认流程；业务 Skill 要求 `prepare -> apply` 时，必须把 prepare 返回的 continuation 原样传给 apply，并在 apply 前取得用户明确确认。
+
+5. 不能猜测 CLI 未暴露的内部字段、接口路径、ID 解析逻辑或回查语义。
+
+6. 未登录或登录失效（`authentication` / `session_expired` / `auth status` 未登录）时，小 E 宿主环境必须先运行 `weaver-work-cli auth xiaoe` 尝试统一登录；统一登录不可用时，再通过宿主提问或弹框向用户确认 E10 登录域名，或用 `auth profile list` 让用户选择已有 profile。执行浏览器登录时必须传入 `--agent_type "<当前智能体名称>"`，让授权确认页展示发起登录验证的智能体；**禁止**使用示例占位域名登录，也禁止在拿到域名前反复重试业务命令。具体流程读取 [`e10-auth-and-session.md`](references/e10-auth-and-session.md)。
+
+7. 附件、图片上传或文件解析属于敏感数据处理。即便 operation 风险等级不是高风险写入，也必须先取得用户对“文件内容可能进入大模型/外部解析服务”的明确确认；不能把用户仅提供文件路径或文件名视为同意解析或上传。
+
+8. 在小 E 宿主环境中，CLI 可以从宿主注入的 `XIAOE_*` 环境变量读取支持统一登录的域名与对应凭证；未显式传域名时优先使用小 E 环境支持域名，其次才使用当前 profile，最后兜底默认域名 `https://www.e-cology.com.cn`。业务命令会在未显式指定 `--auth` / `--profile` 时自动优先尝试小 E 统一登录；Agent 也可以显式调用 `weaver-work-cli auth xiaoe`。不要要求用户提供、展示或手动设置这些凭证。小 E 统一登录失败、当前域名不在支持范围内或用户切换访问域名时，CLI 会自动降级到原浏览器 OAuth 登录。

package/skills/weaver-e10-shared/references/e10-auth-and-session.md

@@ -0,0 +1,127 @@
+# E10 认证与会话
+
+## 什么时候读取
+
+用户需要登录、切换 profile、诊断 E10 连接、处理登录失效，或任务涉及 `base-url`、auth 文件、Keychain、`WEAVER_*` 环境变量时读取本文件。
+小 E 宿主环境涉及 `XIAOE_*` 环境变量时也读取本文件。
+
+## 基本检查
+
+```text
+weaver-work-cli auth status --no-check
+weaver-work-cli auth whoami
+```
+
+`--no-check` 只读取本地登录态；需要实际验证服务端可用性时使用业务命令或明确带 live 校验的命令。
+
+## 认证隔离与禁止探查旧目录
+
+`weaver-work-cli auth root` 是唯一用于确认本 CLI 认证根目录的命令；默认根目录位于用户主目录下的 `.weaver-work-cli/e10`（Windows PowerShell：`$env:USERPROFILE\.weaver-work-cli\e10`；macOS/Linux：`$HOME/.weaver-work-cli/e10`）。Agent 不得因为历史兼容信息去读取、列出、打印或解析用户主目录下的旧 `.e10-cli`，也不得探查 `e10-login` / `e10-cli` 的 auth、config 或 Keychain 数据。
+
+登录态判断只允许通过 `weaver-work-cli auth status --no-check`、`weaver-work-cli auth profile list/current`、`weaver-work-cli doctor --e10` 和业务命令返回的 JSON 错误完成。只有用户明确提供外部 auth 文件路径时，才可按用户要求使用 `--auth <path>` 或 `E10_AUTH_PATH`；不能主动搜索旧认证目录。
+
+## 未登录 / 登录失效：小 E 先自动尝试，其它场景先问域名
+
+业务命令依赖 E10 登录态。出现以下任一情况即判定为未登录或登录失效：
+
+- `weaver-work-cli auth status` 输出 `loggedIn: false`，或本地不存在 auth 文件
+- `weaver-work-cli doctor --e10` 的 `e10AuthFile` 检查为 `ok: false`
+- 业务命令失败，stderr JSON 中 `error.type === "authentication"`（如 `E10 auth not found`）
+- 业务命令返回 `error.subtype === "session_expired"`（E10 登录态 401/302 失效）
+
+此时**禁止**：
+
+- 使用示例占位域名（如 `https://weapp.xxx.cn`）或自行猜测域名执行登录
+- 未向用户确认登录域名前，反复重试业务命令
+- 要求用户提供 Cookie、ETEAMSID、业务 Token（见安全边界）
+- 读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、`e10-login` / `e10-cli` 的历史 auth、config 或 Keychain 数据
+
+**正确流程（按序执行，缺一不可）：**
+
+0. **小 E 宿主环境优先自动尝试统一登录**：如果当前宿主/环境提供 `XIAOE_*` 变量，先运行：
+   ```text
+   weaver-work-cli auth xiaoe
+   ```
+   CLI 会按“显式 `--base-url` / 小 E 环境变量中的首个支持域名 / 当前 profile `config.baseUrl` / 资料包默认域名 `https://www.e-cology.com.cn`”解析登录域名。业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试这一步。若该域名在小 E 支持范围内且凭证有效，会直接保存登录态，`agentType` 固定为 `Xiao.E`，然后继续原业务操作。若当前域名不在小 E 支持范围内、客户切换了访问域名，或小 E 凭证校验失败，CLI 会自动降级到原浏览器 OAuth；只有 CLI 仍然缺少真实域名或需要用户决策时，才进入下面的提问流程。Agent 不得因为本地存在旧 profile 就跳过这一步，也不得要求用户提供或展示 `XIAOE_*` / ETEAMSID。
+
+1. **先调用宿主提供的提问 / 弹框能力询问用户**，让用户二选一：
+   - 输入本次要登录的 E10 登录域名（base URL），形如 `https://<企业域名>`；或
+   - 从已有 profile 中选择一个已登录环境：先运行 `weaver-work-cli auth profile list` 列出候选，让用户选择。
+2. 用户提供了**新域名**时，用真实域名执行浏览器 OAuth 登录：
+   ```text
+   weaver-work-cli auth login --base-url "<用户输入的域名>" --agent_type "<当前智能体名称>"
+   ```
+   端口冲突时加 `--port 19801`。
+3. 用户选择了**已有 profile** 时，切换后验证登录态：
+   ```text
+   weaver-work-cli auth profile use PROFILE_NAME
+   weaver-work-cli auth status
+   ```
+4. 登录成功后再继续原业务操作。仍失败时，把 `error.type/subtype/message` 原样反馈给用户并停止，不要自动重试。
+
+登录域名一律以用户实际提供为准；拿不到域名前，不要执行任何依赖登录态的业务命令。
+
+## 登录
+
+先取得用户确认的登录域名（见上节流程），再让用户通过浏览器 OAuth 登录：
+
+```text
+weaver-work-cli auth login --base-url "<用户确认的登录域名>" --agent_type "<当前智能体名称>"
+```
+
+在小 E 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 会先读取宿主注入的 `XIAOE_*` 环境变量，查找“当前登录域名 -> ETEAMSID”的统一登录映射。只有当前 `--base-url` 或小 E 默认域名与小 E 环境变量中的域名匹配时，CLI 才会尝试用该凭证登录，并且保存的 `agentType` 固定为 `Xiao.E`。如果命令没有显式传入域名，CLI 会优先使用小 E 环境变量里的首个支持域名，其次才使用当前 profile 配置；仍没有支持域名时，保留资料包默认域名 `https://www.e-cology.com.cn`。如果小 E 凭证校验失败、当前域名不在支持范围内，或用户切换了访问域名，CLI 会自动降级到下面的浏览器 OAuth 流程，Agent 不需要也不应要求用户提供 ETEAMSID。
+
+需要显式表达“小 E 优先”的场景也可以使用等价入口：
+
+```text
+weaver-work-cli auth xiaoe
+```
+
+该命令同样会在小 E 统一登录不可用时降级到浏览器 OAuth；用户明确切换域名时再追加 `--base-url "<用户确认的登录域名>"`。
+
+如果端口冲突：
+
+```text
+weaver-work-cli auth login --base-url "<用户确认的登录域名>" --agent_type "<当前智能体名称>" --port 19801
+```
+
+`<当前智能体名称>` 使用发起登录验证的宿主标识，例如 WorkBuddy 传 `workbuddy`，Codex 传 `codex`。CLI 会把该值同时写入 E10 授权 URL 的 `agent_type` 和 `from` 参数，其中 `from` 用于授权确认页的客户端名称展示。如果宿主无法确认名称，才允许省略 `--agent_type`；CLI 会尝试从 `WEAVER_AGENT_TYPE`、`WORKBUDDY_AGENT_TYPE`、`CODEX_AGENT_TYPE` 以及 `WORKBUDDY_*` / `CODEX_*` 环境变量推断，最后回落为 `weaver-work-cli`。
+
+保底方式是让用户手动写入浏览器中的 `ETEAMSID`：
+
+```text
+weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx" --base-url "<用户确认的登录域名>" --agent_type "<当前智能体名称>"
+```
+
+## Profile 与环境
+
+```text
+weaver-work-cli auth profile list
+weaver-work-cli auth profile current
+weaver-work-cli auth profile use PROFILE_NAME
+weaver-work-cli --profile PROFILE_NAME auth status --no-check
+```
+
+通过 `weaver-work-cli run` 执行外部命令时，CLI 会按当前 profile 注入 `WEAVER_BASE_URL`、`WEAVER_ETEAMSID`、`WEAVER_COOKIE`、`WEAVER_USER_AGENT` 和 `WEAVER_AGENT_TYPE`。这些值只给子进程使用，不应在回复或日志中明文展示。
+
+小 E 的 `XIAOE_*` 环境变量只由宿主/客户端注入给 CLI 消费；Agent 不要打印、转述、要求用户手动填写或将其导出到当前 shell。CLI 当前支持 JSON 域名映射和单域名变量两类宿主格式，但这些格式属于宿主集成细节，不作为用户操作步骤。
+
+如必须导出到当前 shell，按环境选择：
+
+Windows PowerShell：
+
+```powershell
+Invoke-Expression (weaver-work-cli auth export-weaver-env --shell powershell)
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+eval "$(weaver-work-cli auth export-weaver-env --shell posix)"
+```
+
+`auth export-weaver-env` 默认 `--shell auto` 会在 Windows 输出 PowerShell 语法，在 macOS/Linux 输出 POSIX shell 语法；不确定时先用 `node -p "process.platform"` 判断。
+
+## 安全边界
+
+Agent 不要要求用户贴 Cookie、ETEAMSID、业务 Token、app key 或 app secret，也不要直接读取用户机器上的 auth、config 或 Keychain 数据。业务 Skill 只负责调用 CLI；登录态读取、Cookie 拼接、业务 Token 获取和 HTTP header 注入都由 `weaver-work-cli` 内部完成。

package/skills/weaver-e10-shared/references/json-output-contract.md

@@ -0,0 +1,120 @@
+# JSON 输出契约
+
+## 什么时候读取
+
+需要判断命令成功或失败、编写脚本封装、处理 stdout/stderr，或连续执行多个 Agent operation 时读取本文件。
+
+## 成功 envelope
+
+成功写入 stdout，退出码为 0：
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "operation": "invoice.list",
+  "data": {},
+  "meta": { "status": "COMPLETE" },
+  "warnings": []
+}
+```
+
+判断成功使用退出码 0 和 `ok === true`。不要用 `code === 0`，成功 envelope 没有顶层 `code/msg`。
+
+## 失败 envelope
+
+失败写入 stderr，退出码非 0：
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": false,
+  "error": {
+    "type": "validation",
+    "subtype": "input_invalid",
+    "message": "必须提供 fid 或 number",
+    "retryable": false
+  }
+}
+```
+
+错误判断优先看：
+
+- `error.type`
+- `error.subtype`
+- `error.message`
+- `error.retryable`
+- `error.stage`
+- 进程退出码
+
+## 退出码
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 成功 |
+| `2` | 参数或业务输入错误 |
+| `3` | 认证错误 |
+| `4` | 网络错误 |
+| `10` | 需要明确确认 |
+| `11` | 部分完成或结果不确定 |
+
+`retryable=true` 只表示读操作或准备阶段可能可以重试；写入请求已经发出后，遇到 `partial/write_uncertain` 必须停止并交给用户判断。
+
+## JSON 输入兼容
+
+简单 JSON 优先使用 `--input-json`，两端都可用，能避开 Windows PowerShell 对 `printf`、管道、转义和续行的差异：
+
+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 invoice.list --input-json '{"page_size":10,"start_pos":0}'
+```
+
+复杂或多行 JSON 使用临时 UTF-8 文件。Windows PowerShell 示例：
+
+```powershell
+$inputFile = Join-Path $env:TEMP "weaver-work-cli-input.json"
+@{ page_size = 10; start_pos = 0 } | ConvertTo-Json -Depth 20 -Compress | Set-Content -Encoding UTF8 -NoNewline $inputFile
+weaver-work-cli --json invoice run invoice.list --input $inputFile
+```
+
+macOS/Linux（bash/zsh）示例：
+
+```bash
+input_file="$(mktemp)"
+printf '%s\n' '{"page_size":10,"start_pos":0}' > "$input_file"
+weaver-work-cli --json invoice run invoice.list --input "$input_file"
+```
+
+Windows/PowerShell 下不要使用 `printf`、bash 反斜杠续行、`$HOME/...` 或 `~/...` 路径、`rm/ls/diff/python3` 等 Unix-only 写法；目录查看用 `Get-ChildItem`，删除用 `Remove-Item`，文件比对用 `Get-FileHash`，Python 启动器优先用 `py -3`。
+
+## 大结果渲染与提效规则
+
+当前 `weaver-work-cli` 输出层是轻量封装：JSON 模式把完整结果写 stdout，文本模式写人类可读文本；不像飞书 CLI 已内置 `--format table/pretty/ndjson`、`--jq` 或通用 `--page-all`。Agent 因此必须在调用和回复阶段主动控量，避免把超长接口响应原样渲染给用户。
+
+### 调用前控量
+
+- 列表类 operation 默认先取小页：优先 `page_size=10`，需要更多结果时再按用户目标递增，通常不要超过 `20`。
+- 用户只想定位一个对象时，用筛选字段缩小范围；已有 `fid`、`number`、文件路径或 continuation 时直达对应 operation，不要先拉全量列表。
+- 用户说“全部 / 全量 / 统计”时，先说明会分页读取；每页读取后只保留任务所需字段和去重键，避免在上下文里累计完整原始响应。
+- 有 `hasMore`、`start_pos`、`page_token`、`next_page_token` 等分页字段时，用它们继续翻页；没有明确分页信号时不要无界循环。
+
+### 回复时渲染
+
+- 不要把完整 stdout JSON 直接粘给用户。优先输出结论、命中数量、关键字段、下一页/剩余数据提示和必要的文件路径。
+- 列表结果只展示最相关的前 `10` 条；如果用户要求更多，分批展示并说明还可以继续读取。
+- 详情结果只展示与用户问题相关的字段。发票类详情通常优先展示 `fid`、号码/代码、购销方、金额、日期、查验/报销状态和附件摘要。
+- 超长文本、大数组、OCR 原文、逐项明细或调试需要的完整 JSON，优先写入本地文件再给路径；不要在对话里展开。可用 shell 重定向保存完整 stdout，或业务 operation 暴露 `output` 参数时使用其文件输出。
+- 如果为了调试必须引用原始 envelope，只截取必要字段：`ok`、`operation`、`meta`、`warnings`、`error` 或 `data` 的相关子树。
+
+### 参考飞书 CLI 的实践
+
+- 飞书 CLI 用 `--format json` 保留机器可读 envelope，用 `pretty/table/ndjson/csv` 降低人读成本；本 CLI 目前主要依赖 `--json` envelope，因此 Agent 回复时承担 pretty/table 摘要职责。
+- 飞书 CLI 的分页实践是显式页预算（如 `--page-limit`）和页间延迟；本 CLI 业务 operation 应使用自身 schema 中的 `page_size/start_pos` 等字段模拟同样的预算控制。
+- 飞书 CLI 对大产物倾向返回 artifact 文件路径；本 CLI 遇到下载、导出、OCR 或超长 JSON 时也应优先落盘并只向用户展示路径和摘要。

package/skills/weaver-e10-shared/references/weaver-e10-installation.md

@@ -0,0 +1,110 @@
+# 安装与可用性检查
+
+## 什么时候读取
+
+命令不可用、版本不确定、用户刚安装、全局命令可能指向旧版本，或需要确认当前安装包含哪些 Agent Skill 时读取本文件。
+
+## 检查命令
+
+```text
+weaver-work-cli --version
+weaver-work-cli setup invoice
+weaver-work-cli doctor --e10
+weaver-work-cli skills list
+```
+
+`weaver-work-cli skills list` 只证明包内 Skill 文件可读，不证明业务 API 可用；E10 登录态和 live API 仍需按业务命令实际验证。
+
+## Agent 自动安装运行时
+
+当 `weaver-work-cli --version` 失败或用户要求代装时，Agent 先让用户选择来源；未同意前不改全局 npm 环境。
+
+建议提示词：
+
+```text
+未检测到 weaver-work-cli。是否安装运行时？
+请选择：1. npm 源安装（可填 registry）；2. 本地代码安装（需仓库绝对路径）。
+```
+
+用户选 npm 源安装后执行；如提供 registry，把安装命令换成 `npm install -g weaver-work-cli --registry "<NPM_REGISTRY_URL>"`：
+
+```text
+node --version
+npm --version
+npm install -g weaver-work-cli
+weaver-work-cli --version
+```
+
+用户选本地代码安装时，先取得仓库绝对路径并确认有 `package.json`；路径缺失或错误时先追问。
+
+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
+```
+
+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
+```
+
+权限错误时停止并报告，不自动加 `sudo`。
+
+## 本地构建验证
+
+如果怀疑全局 `weaver-work-cli` 仍是旧版本，在仓库内直接调用当前构建产物：
+
+```text
+node dist/index.js --version
+node dist/index.js commands list
+node dist/index.js skills list
+```
+
+## 推荐交付模式
+
+`weaver-work-cli` 发布包是唯一必须安装的运行时，包含 CLI 命令、E10 鉴权、
+发票业务 operation 和随包 Agent Skill 文档。普通用户通过组织认可的包管理器来源安装后即可使用：
+
+```text
+weaver-work-cli setup invoice
+weaver-work-cli auth login --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"
+weaver-work-cli invoice schema
+```
+
+如果当前环境需要让 Codex/Agent 直接加载发票 Skill，优先使用随包一键安装：
+
+```text
+weaver-work-cli skills install yepiaotong
+```
+
+该命令会同时安装 `weaver-e10-shared` 和 `weaver-e10-yepiaotong` 到
+环境变量 `CODEX_HOME` 下的 `skills` 子目录；未设置 `CODEX_HOME` 时使用用户主目录下的 `.codex/skills`
+（Windows PowerShell：`$env:USERPROFILE\.codex\skills`；macOS/Linux：`$HOME/.codex/skills`）。默认目标
+面向 Codex CLI；WorkBuddy 等桌面 Agent 的用户级 Skill 目录不是默认目标，需
+显式指定后再安装（目标目录位置以对应 Agent 的官方文档为准）：
+
+```bash
+weaver-work-cli skills install yepiaotong --target-dir "<目标 Agent 的用户级技能目录>"
+```
+
+`skills install` 是拷贝语义，装出的是真实副本，不与源目录联动。目标目录里
+已有旧条目（旧副本或软链）时不能直接覆盖：目标是软链会报
+`ERR_FS_CP_DIR_TO_NON_DIR`，Windows 用 `Remove-Item -Recurse -Force`、macOS/Linux 用 `rm -rf` 断链再安装；覆盖安装不会清理目标里已
+不存在的旧文件。安装只是文件拷贝，不需要 E10 登录；Agent 需新会话或重载
+Skill 后才读取新内容。完整安装/升级流程见仓库 `docs/agent-skill-install.md`。
+
+交付给 Agent 的 Skill ZIP 不内置运行时，只声明依赖本机可用的 `weaver-work-cli`
+bin。ZIP 主要用于平台导入、离线分发或版本归档，不应作为普通用户的必经安装步骤。

package/skills/weaver-e10-skill-maker/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: weaver-e10-skill-maker
+display_name: 泛微Skill生成器
+display_name_en: Weaver Skill Maker
+description: "将泛微/E10 业务模块文档或代码同步转换成 weaver-work-cli 业务 CLI 与 Skill，并用检测工具校验。"
+description_zh: "泛微/E10 业务模块 CLI 与 Skill 生成器。把用户提供的业务文档、接口说明或代码同步转换成 weaver-work-cli 业务命令和 Agent Skill，并在源资料更新时先检测差异、再确认是否重新转换。"
+description_en: "Convert Weaver or E10 business module documents and code into synchronized weaver-work-cli business CLI commands and Agent Skills, validate them with the Weaver detector, and confirm before applying source updates."
+version: 1.0.0
+author: 泛微网络科技股份有限公司
+agent_created: true
+requires:
+  bins: ["weaver-work-cli"]
+cliHelp: "weaver-work-cli skills --help"
+---
+
+# weaver-work-cli Skill Maker
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --skills-dir <当前Agent的Skills目录>`，若 CLI 未安装则先执行 `npm install -g weaver-work-cli`，安装或读取失败时必须停止执行。**
+
+本 Skill 参考飞书 CLI 的 `lark-skill-maker`，但输出范围更完整：Agent 需要把已经给出的业务模块资料同步固化为 `weaver-e10-*` Agent Skill 和对应 `src/shortcuts/<module>` TypeScript CLI 能力。新业务模块一开始没有对应 `weaver-work-cli` 业务命令是正常输入，但不能只生成文档型 Skill；默认要把 CLI 一并设计、实现、测试并让 Skill 调用真实 operation。
+
+生成或更新的 docs、Skill reference、模板提示词和 CLI 示例必须同时兼容 Windows 和 macOS/Linux。凡涉及 JSON 输入、用户目录、路径分隔符、Python 启动器、文件删除、目录查看或文件比对，必须同时给出 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例；Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。简单 JSON 优先生成 `--input-json '<json>'` 示例；复杂或多行 JSON 使用临时 UTF-8 文件和 `--input <path>`。Windows/PowerShell 下不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法，不要把任一平台专属命令写成唯一默认步骤。
+
+## 适用范围
+
+使用本 Skill 处理以下请求：
+
+- 把新的 E10 / 泛微业务模块文档、接口说明、现有代码或示例同步转换成 `weaver-work-cli` 业务 CLI 与 Skill。
+- 为已有 `src/shortcuts/<module>` 和 `skills/weaver-e10-<module>` 补 operation、reference、路由语义、禁用边界、文件处理确认或写操作确认链。
+- 用户提供的业务模块资料更新后，先用文件级指纹或 Git ref 范围检测源资料是否变化；若 manifest 记录了 `sourceChunks` 与 `operationImpact`，再定位可能受影响的 operation、reference、schema、测试和写入确认链，并询问是否需要重新转换。
+- 用户希望按源码仓库提交记录更新业务模块时，主动收集本地源码仓库路径、仓库下模块资料相对路径、旧版本 ref、新版本 ref、参考内容或补充说明、目标 CLI 命令后缀、目标 Skill 后缀和特殊要求；信息不完整时先提问，不要自行搜索整个磁盘或猜测版本范围。
+- 审查某个业务 CLI 与 Skill 是否符合 `weaver-work-cli` 的 operation、共享规则、reference 拆分和安装约定。
+
+使用本 Skill 时默认要实现或更新新的 TypeScript shortcut、E10 HTTP 适配和对应 operation；如果源资料不足以安全实现某个 operation，先把缺口列清楚并向用户确认，不能编造接口、字段、写入确认链或 operation。
+
+推进规则：
+
+- 用户已明确作为输入提供的业务文档、代码目录、接口说明或样例，视为本次转换的源资料；先读取与当前模块直接相关的原文和现有 reference，再判断是否缺口。不要只因为“需要读取 reference 原文”就停止。
+- 缺口只阻断受影响的 operation；已能从源资料确认的只读、预览、准备或文档索引部分要继续实现。不能实现的能力写入待确认清单或禁用边界，不要生成假 operation。
+- 如果确实必须等用户补充，回复必须列出具体缺口并提出明确问题，例如缺少哪个 operation 的接口路径、请求方法、关键字段、权限边界、幂等键、回查接口或写入确认条件。不能只说“需要确认细节”，也不要以“实现前需要确认几个细节”“随后开始实现”这类状态句作为最终回复。
+
+## 处理流程
+
+1. 先确认两个独立命名，两者可以不同、不要默认同名：**CLI 命令后缀 `<command>`**（`weaver-work-cli <command>` 的命令名，通常用英文动作名，如 `invoice`）和 **Skill 后缀 `<skill>`**（`skills/weaver-e10-<skill>` 的目录名与 frontmatter `name`，通常用业务系统名/拼音，如 `yepiaotong`）。任一不明确都先问用户，不要猜；源文档/代码路径、源码仓库路径、仓库下模块资料相对路径、旧版本 ref、新版本 ref 或输出位置不明确时同样先问。CLI 同步生成/更新是默认范围。
+2. 读取 [`business-skill-generation.md`](references/business-skill-generation.md)，按流程盘点源资料、抽取业务语义和生成 artifact。
+3. 读取 [`module-cli-generation.md`](references/module-cli-generation.md)，按 CLI 规范同步实现或更新 `src/shortcuts/<module>`、operation manifest、registry、错误 envelope、测试和命令注册。
+4. 读取 [`weaver-skill-style.md`](references/weaver-skill-style.md)，确保入口 `SKILL.md`、`references/`、`product.json`、`skill-template/` 和文档索引保持 weaver 风格，并且 Skill 只调用已实现的 CLI operation。
+5. 若目标 Skill 或目标 CLI 已存在，或用户说源文档/代码有更新，必须先读取 [`source-update-detection.md`](references/source-update-detection.md)，比较源资料文件指纹或 Git ref 范围；若存在 `sourceChunks` / `operationImpact`，同步列出小范围变更和可能影响。只有用户确认需要转换后，才更新已有 Skill 和 CLI。
+6. 读取 [`detector-validation.md`](references/detector-validation.md)，用泛微技能检测工具校验生成结果；检测失败时先修复，不要把未过检的 Skill 当作完成。
+7. 检测通过后读取 [`post-generation-install.md`](references/post-generation-install.md)，用宿主支持的弹框或确认 UI 询问用户是否安装；用户确认后再打包并安装到当前智能体可识别的 skills 目录。
+8. 完成后至少验证 `weaver-work-cli <module> schema`、`weaver-work-cli skills list` 和 `weaver-work-cli skills read weaver-e10-<module>`；在仓库内改动时再跑相关测试，并确认新生成 Markdown 中没有 Unix-only 命令示例。
+
+## 命名约定
+
+每个业务模块有两个独立命名，生成时必须分别向用户确认，不要默认相同：
+
+- **CLI 命令后缀 `<command>`**：决定命令面 `weaver-work-cli <command> schema/run ...`，也决定 operation 前缀 `<command>.<action>` 和 `src/shortcuts/<command>` 目录。通常用英文动作名，如 `invoice`。
+- **Skill 后缀 `<skill>`**：决定 Skill 目录 `skills/weaver-e10-<skill>`、frontmatter `name: weaver-e10-<skill>`、`skill-template/business-info.json` 的 key、`skill-template/domains/<skill>.md`。通常用业务系统名或拼音，如 `yepiaotong`、`wenshuding`。
+
+两者通过 Skill 的 `cliHelp: "weaver-work-cli <command> --help"` 关联：Skill 名用 `<skill>`，但 Skill 内部所有命令示例仍走 `weaver-work-cli <command>`。例如发票模块 CLI 命令后缀是 `invoice`、Skill 后缀是 `yepiaotong`，则目录为 `skills/weaver-e10-yepiaotong`，命令为 `weaver-work-cli invoice run invoice.list`。下面产物边界里的 `<module>` 按位置分别指 `<command>`（`src/shortcuts/`、`test/business/`、`docs/`）或 `<skill>`（`skills/`、`skill-template/`）。
+
+## 产物边界
+
+生成或更新业务 CLI 与 Skill 时，默认只改这些位置：
+
+- `skills/weaver-e10-<module>/SKILL.md`
+- `skills/weaver-e10-<module>/product.json`
+- `skills/weaver-e10-<module>/references/*.md`
+- `skills/weaver-e10-<module>/references/source-manifest.json`
+- `src/shortcuts/<module>/` 和 `src/shortcuts/index.ts`
+- `test/business/<module>-*.test.ts`
+- `docs/<module>.md`
+- `skill-template/business-info.json`
+- `skill-template/domains/<module>.md`
+- 必要时更新仓库级文档索引或说明文件；这些不是发布包内 reference，入口文件里不要把它们写成可点击引用
+
+不要把用户源文档全文复制进 Skill；只提炼稳定的业务规则、operation 使用方式、字段约束、风险确认和禁用边界。超长接口手册应拆成按需读取的 reference，或继续留在用户指定的源资料位置并在 manifest 中记录来源。

package/skills/weaver-e10-skill-maker/product.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "product": "weaver-work-cli",
+  "productVersion": "0.1.2",
+  "packageName": "weaver-work-cli",
+  "command": "weaver-work-cli",
+  "nodeEngine": ">=18"
+}