weaver-work-cli 0.1.2 → 0.1.5

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

@@ -0,0 +1,90 @@
+---
+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 输出契约、大结果渲染与高风险操作。
+
+## 业务 Skill 安装前版本检查
+
+用户要求安装任一业务模块 Skill 时，必须先执行 `weaver-work-cli --version` 与 `npm view weaver-work-cli version` 比对本地版本和 npm 源版本。若本地版本低于 npm 源版本，先询问用户是否使用（推荐）最新版 `weaver-work-cli`；用户确认后先执行 `npm install -g weaver-work-cli` 更新 CLI，再继续安装业务模块 Skill。用户拒绝时，说明将沿用本地版本后再继续。
+
+## 最高优先级：小 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-work-cli-shared → weaver-e10-shared}/references/json-output-contract.md

@@ -60,6 +60,40 @@
 
 `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 因此必须在调用和回复阶段主动控量，避免把超长接口响应原样渲染给用户。

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,78 @@
+---
+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"
+}

package/skills/weaver-e10-skill-maker/references/business-skill-generation.md

@@ -0,0 +1,124 @@
+# 业务模块 Skill 生成流程
+
+本流程用于把用户提供的新业务模块文档或代码转换成 `weaver-e10-*` Agent Skill，并同步生成或更新对应 `src/shortcuts/<module>` CLI。目标是让其它 Agent 先读业务 Skill，再通过 `weaver-work-cli --json <module> run <operation> --input-json '<json>'` 或 `--input <path>` 调用真实 operation，而不是绕过 CLI 猜接口。
+
+生成出的 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`。Windows/PowerShell 示例不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。
+
+## 1. 明确输入和输出
+
+开始前确认这些事，其中两个命名必须分别确认、可以不同：
+
+- **CLI 命令后缀 `<command>`**：只用小写字母、数字和连字符，例如 `invoice`、`contract`、`expense-claim`。决定 `weaver-work-cli <command>`、operation 前缀 `<command>.<action>` 和 `src/shortcuts/<command>`。
+- **Skill 后缀 `<skill>`**：同样只用小写字母、数字和连字符，但通常用业务系统名或拼音，例如 `yepiaotong`、`wenshuding`。决定 `skills/weaver-e10-<skill>` 目录名与 frontmatter `name`。
+- 源资料：用户提供的文档、代码目录、接口说明、样例 JSON、已有 Skill 或需求说明。
+- 输出位置：默认是当前仓库的 `skills/weaver-e10-<skill>`；如果用户指定外部 Agent skill 目录，以用户指定为准。
+
+两个命名任一不清楚时都不要从文件夹名硬猜；候选名可以给出，但要等用户确认。尤其不要把 CLI 命令后缀直接当成 Skill 后缀：例如发票模块 CLI 命令是 `invoice`、Skill 名是 `yepiaotong`，目录应是 `weaver-e10-yepiaotong` 而不是 `weaver-e10-invoice`。不要因为当前没有 `weaver-work-cli <command>` 命令就追问是否补 CLI；CLI 同步生成/更新是默认范围。只有源资料缺少实现 CLI 所需的接口路径、请求方式、关键字段、认证边界、幂等/回查或写入确认信息时，才停下来向用户确认缺口。停下前必须已经读取用户提供的相关源资料和仓库内现有 reference；最终回复必须列出具体缺口和一个明确问题，不能只说“需要确认细节”。
+
+当用户要求“根据源码仓库提交记录更新业务模块 Skill/CLI”时，把 Git 范围视为源资料的一部分。开始差异分析前，主动确认以下信息；用户没有提供时先提问，不能用网页 URL、目录名或最近提交自行补齐：
+
+- **源码仓库本地路径**：本地 clone 下来的仓库根目录，例如 `C:\work\weaver-interface` 或 `/Users/me/work/weaver-interface`。线上 GitLab/GitHub URL 只能作为来源说明；除非用户明确允许 clone/fetch 并提供访问能力，否则不要把远程 URL 当作可直接执行的仓库路径。
+- **仓库下模块资料相对路径**：相对于仓库根目录的路径，例如 `backend/business-apis/inc/weaver-e10-yepiaotong`。如果用户给的是完整浏览器地址，去掉 `/-/tree/<branch>/` 之前的部分并向用户确认相对路径。
+- **旧版本 ref** 与 **新版本 ref**：可以是完整 commit SHA、唯一短 SHA、tag 或 branch/ref。多次提交通常只需要最开始旧 ref 和最后新 ref；中间 ref 只作为阶段说明或需求来源记录。
+- **关联公共路径**：可选。若业务模块依赖共享 DTO、路由注册、公共枚举、鉴权或全局配置，让用户补充这些仓库相对路径；没有提供时先用模块路径过滤，并在影响报告中说明可能漏掉公共依赖。
+- **参考内容**：可选。用户对需求单、截图、接口说明、历史 Skill、人工总结或特殊业务语义的补充；这些内容用于解释 diff，不能替代 Git ref 事实。
+- **特殊要求**：可选。包括不要改某些 operation、兼容旧字段、按需求号分阶段输出、只生成报告不 apply、检测工具路径或额外测试命令等。
+
+缺少源码仓库本地路径、模块相对路径、旧版本 ref、新版本 ref、CLI 命令后缀或 Skill 后缀时，不要进入写入阶段；先一次性向用户索取缺失项。目标产物路径通常可按 `<command>` / `<skill>` 在当前 `weaver-work-cli` 仓库中推断，不必要求用户提供全路径。
+
+## 2. 盘点源资料
+
+只读取用户明确提供或与模块直接相关的资料。对每个源文件记录：
+
+- `path`
+- `size`
+- `sha256`
+- 可选的 `role`：`api-doc`、`code`、`sample`、`existing-skill`、`requirement`
+
+用户本轮明确提供为输入的业务文档、代码目录、接口说明和样例，可以直接读取用于转换；读取后只把稳定规则、字段和约束写入生成产物，不复制整份源文档。源资料是附件、图片、远程 URL、二进制文件，或需要上传到外部解析/OCR 服务时，先按 shared 规则提示风险并等待用户确认。仅拿文件路径做 manifest 指纹通常不需要读取正文。
+
+如果源资料中存在机器可读契约，例如 `business-module.json`、OpenAPI/JSON Schema、导出的 operation manifest、接口路由表或字段枚举表，优先把这些契约作为 WHAT 的权威来源；源码 diff、需求说明和截图用于解释 WHY 与 WHEN。契约与源码实现冲突时，在影响报告中列为阻断或待确认项，不要让 Agent 从源码自由猜测字段语义。
+
+如果源资料有稳定锚点，还要写入 `sourceChunks` 和 `operationImpact`：用 operation 名、HTTP 方法加路径、Markdown 标题或导出的 operation class 作为 chunk id，并把 chunk 映射到可能受影响的 CLI operation、schema 字段、reference、测试和风险确认链。不要用行号、段落顺序或模型摘要当 chunk id。源资料无法稳定切块时，只保留文件级指纹，并在 manifest 标记弱检测。
+
+## 3. 抽取业务语义
+
+从源资料中提炼这些稳定信息：
+
+- 业务对象和高优先级触发词。
+- operation 清单、命令名、输入字段、输出字段、分页字段和风险等级。
+- 写入、删除、导入、更新等高风险操作的确认链；能做 `prepare -> apply` 的必须写清。
+- 文件上传、OCR、导入、下载、远程 URL 读取等数据处理风险。
+- 已知禁用能力：文档中存在但 CLI 未暴露、缺少稳定 ID、缺少回查或风险不可自动化的能力。
+- 认证边界：业务 Skill 只调用 CLI，不复制 Cookie、ETEAMSID、Token 或内部登录逻辑。
+
+如果源资料描述的是底层接口，但仓库还没有对应 operation，按 [`module-cli-generation.md`](module-cli-generation.md) 先实现 CLI，再让 Skill 调用该 operation。确实缺少实现依据时，把缺口列入待确认清单并问用户，不能生成假 operation；缺口只阻断对应 operation，已确认的能力继续生成 CLI、测试、docs 和 Skill reference。
+
+## 4. 同步实现 CLI
+
+生成 Skill 前先读取 [`module-cli-generation.md`](module-cli-generation.md)，用飞书 CLI 的 contract-first 思路完成对应业务 shortcut：先定正确实现面，再实现 operation、schema、测试和文档。实现后确认 CLI 暴露的真实能力：
+
+```text
+weaver-work-cli MODULE_COMMAND --help
+weaver-work-cli MODULE_COMMAND schema
+weaver-work-cli skills list
+```
+
+Skill 必须以 `schema` 为准；源文档和 schema 冲突时，先修正 CLI 或记录冲突并向用户确认。新增或更新 operation 后，Skill 里的命令统一写成：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json MODULE_COMMAND run MODULE_NAME.operation --input-json '{"key":"value"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json MODULE_COMMAND run MODULE_NAME.operation --input-json '{"key":"value"}'
+```
+
+不要在 Skill 中要求 Agent 直接 `curl`、`fetch`、浏览器自动化或拼 E10 原始接口。
+
+## 5. 生成 artifact
+
+按 `weaver-skill-style.md` 生成：
+
+- 入口 `SKILL.md`：只放共享前置、路由优先级、operation 表、处理链、执行原则和不在范围。
+- `references/`：每类意图或每个 operation 一个 reference，写具体输入、命令示例、输出摘要、注意事项和失败处理。
+- `product.json`：声明 `weaver-work-cli` 运行时。
+- `references/source-manifest.json`：记录源资料指纹、可选的 `sourceChunks` / `operationImpact` 和生成产物基线，用于后续更新检测。
+- `src/shortcuts/<module>`：注册命令、schema/run、operation manifest、执行逻辑、错误 envelope 和测试。
+- `skill-template/business-info.json` 与 `skill-template/domains/<module>.md`：让聚合模板知道如何路由。
+- 泛微技能检测结果：按 `detector-validation.md` 运行检测，确保生成出的 Skill 至少无 BLOCK/FAIL 项。
+- 安装确认：检测通过后按 `post-generation-install.md` 询问用户是否安装，确认后再打包并安装到当前智能体。
+
+写 reference 时只保留执行所需的事实和约束，不复制整份接口手册。复杂字段以小而完整的 JSON 示例展示，避免超长响应或敏感字段。
+
+## 6. 验证
+
+在仓库内生成时至少运行：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli skills list
+weaver-work-cli skills read weaver-e10-MODULE_NAME
+weaver-work-cli MODULE_NAME schema
+npm test -- test/skills/layout.test.ts
+npm test -- "test/business/MODULE_NAME-*.test.ts"
+py -3 DETECTOR_DIR\scripts\validate_skill.py skills\weaver-e10-MODULE_NAME --json --no-html
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli skills list
+weaver-work-cli skills read weaver-e10-MODULE_NAME
+weaver-work-cli MODULE_NAME schema
+npm test -- test/skills/layout.test.ts
+npm test -- "test/business/MODULE_NAME-*.test.ts"
+python3 DETECTOR_DIR/scripts/validate_skill.py skills/weaver-e10-MODULE_NAME --json --no-html
+```
+
+如果新增或修改了 TypeScript CLI 代码，再运行构建和相关业务测试。若验证失败，优先修正 CLI 合约、artifact 结构、frontmatter、reference 链接和 business-info 对齐问题。检测通过后，进入安装确认流程；用户未确认前不要安装。