weaver-work-cli 0.1.1 → 0.1.4

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 对齐问题。检测通过后，进入安装确认流程；用户未确认前不要安装。

package/skills/weaver-e10-skill-maker/references/detector-validation.md

@@ -0,0 +1,101 @@
+# 泛微技能检测工具集成
+
+生成或更新业务模块 Skill 后，必须用泛微技能检测工具做静态质检。目标是让产物同时符合 WorkBuddy 平台规范、泛微专项安全合规要求和通用质量规则。
+
+## 检测工具来源
+
+检测工具不是生成出的业务 Skill 的一部分。运行时按以下顺序定位：
+
+1. 用户本轮明确提供的检测工具目录。
+2. 当前工作区中与 `weaver-work-cli` 同级的 `weaver-skill-detector-1.0.13` 目录。
+3. 如果以上都不可用，向用户询问检测工具目录，不要自行联网下载或改用其它检测器。
+
+不要把本机个人绝对路径写入生成出的 Skill 或 `source-manifest.json`；需要记录检测器时只写工具名、版本号或用户提供的相对位置。
+
+检测器的 zip 输入分支使用新版 Python 标准库参数。目录检测可作为本地保底；需要检测 zip 时，优先使用 WorkBuddy 托管 Python 或 Python 3.11+。如果当前环境只有旧版 Python 且 zip 检测报运行时错误，先向用户确认可用解释器路径，不要把 zip 检测失败误判为 Skill 内容不合格。
+
+检测命令必须同时给出 Windows PowerShell 与 macOS/Linux（bash/zsh）示例。Windows 优先使用 `py -3` 或 `py -3.11`；macOS/Linux 使用 `python3` 或用户确认的 Python 路径。Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。不要把个人绝对路径写入生成产物。
+
+## 必须满足的 frontmatter
+
+默认 `weaver` 模式下，生成的 `SKILL.md` frontmatter 必须使用顶层字段，不得使用 `metadata:` 嵌套。至少包含：
+
+```yaml
+name: weaver-e10-<module>
+display_name: 泛微<中文展示名>
+display_name_en: Weaver <English Name>
+description: "<200 字内的一句话中文概述，说明能力和触发场景>"
+description_zh: "<中文简介>"
+description_en: "<English summary>"
+version: 1.0.0
+author: 泛微网络科技股份有限公司
+agent_created: true
+requires:
+  bins: ["weaver-work-cli"]
+cliHelp: "weaver-work-cli <command> --help"
+```
+
+`name` 只能使用小写字母、数字和连字符，必须以 `weaver` 开头，目录名必须与 `name` 一致。`display_name` 必须以「泛微」开头，建议不超过 20 字。`description` 保持短句，详细介绍放入 `description_zh` 和 `description_en`。
+
+## 打包与内容约束
+
+生成的 Skill 需要满足这些硬约束：
+
+- 入口文件名精确为 `SKILL.md`。
+- 目录层级不超过两级：根目录文件、二级目录文件；不要出现 `references/topic/file.md`。
+- 文件总数不超过 300。
+- 只包含纯文本文件；不要把图片、PDF、压缩包或构建产物放进 Skill。
+- 所有 JSON、YAML、TOML 文件必须可解析。
+- `SKILL.md` 中写成 Markdown 链接或反引号路径的 `references/...` 文件必须真实存在于包内。
+- 不写默认登录地址、真实 IP、凭证、个人路径、IDE 配置目录或平台虚假技术承诺。
+- 默认按 `weaver` 模式检测；只有用户明确说要上架千问办公或 QwenWork，才加 `--platform qwenwork`。
+
+## 检测命令
+
+优先检测生成出的 Skill 目录：
+
+Windows PowerShell：
+
+```powershell
+py -3 DETECTOR_DIR\scripts\validate_skill.py GENERATED_SKILL_DIR --json --no-html
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+python3 DETECTOR_DIR/scripts/validate_skill.py GENERATED_SKILL_DIR --json --no-html
+```
+
+如果还生成了发布 zip，再用 Python 3.11+ 检测 zip：
+
+Windows PowerShell：
+
+```powershell
+py -3.11 DETECTOR_DIR\scripts\validate_skill.py GENERATED_SKILL_ZIP --json --no-html
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+python3.11 DETECTOR_DIR/scripts/validate_skill.py GENERATED_SKILL_ZIP --json --no-html
+```
+
+退出码含义：
+
+- `0`：通过或仅有警告。若有 WARN，发布前尽量修复；无法修复时向用户说明剩余风险。
+- `1`：不通过。必须先修复 BLOCK/FAIL 项，再重新检测。
+- `2`：输入非法。先修正路径或包结构。
+
+不要主动使用 `--market-live`，除非用户明确要求联网核查市场可达性。
+
+## 失败处理
+
+检测失败时，按报告中的规则编号修复：
+
+- frontmatter 缺字段或存在 `metadata:`：提升为顶层字段并补齐展示名、版本、作者、英文描述。
+- 引用文件不存在：把 reference 补进包内，或移除入口里的包外 Markdown 链接。
+- 目录层级过深：拍平 `references/` 下的子目录。
+- 二进制或隐藏文件：从 Skill 包移除。
+- 默认地址、凭证或真实 IP：改为用户显式提供、命名凭据或占位说明。
+
+修复后必须重新运行检测。最终回复中说明检测结果、是否还有 WARN，以及使用的检测器版本。

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

@@ -0,0 +1,230 @@
+# 业务模块 CLI 生成规范
+
+使用 Skill Maker 生成或更新业务模块时，默认同步实现 `src/shortcuts/<module>`。Agent Skill 只引用已经在 CLI 中注册并通过 `schema` 暴露的 operation。
+
+本规范借鉴飞书 CLI 的 shortcut 纪律，但按 `weaver-work-cli` 当前 TypeScript 架构落地：飞书的 `shortcuts/<domain>` 对应这里的 `src/shortcuts/<module>`；飞书的 command-level affordance 对应这里的 `docs/<module>.md` 和 Skill references；飞书的 `--dry-run` 预览在这里优先映射为 `*.preview`、`*.prepare` 或只读回查 operation，除非本模块显式实现人类友好的 dry-run 子命令。
+
+## 生成前先定正确实现面
+
+开始写代码前，先建立当前合约和 owner：
+
+- 已有模块：先读 `src/shortcuts/<module>`、`docs/<module>.md`、`skills/weaver-e10-<module>`、相关 `test/business/<module>-*.test.ts`，确认现有 command、operation、schema、输出 envelope、错误 subtype 和安全边界。
+- 新模块：先从源资料划分“业务友好的高层 operation”和“底层接口细节”。只有能为 Agent 或人类提供稳定流程、智能默认值、安全确认、字段收敛或结果归一化时，才新增 operation。
+- 不重复命令面：同一业务动作只能有一个 canonical operation。可选的人类友好子命令只是薄包装，最终必须调用同一个 operation 执行器。
+- 不绕过 owner：E10 认证、profile、HTTP client 和请求拦截链归 `src/internal/e10`；业务 API 适配归本模块 `host.ts`；operation 只组织业务输入、校验、确认链和结果。
+- 不补推测能力：缺少接口路径、请求方法、关键字段、权限/认证边界、幂等键、回查方式或写入确认条件时，先确认是否只影响局部 operation；能实现的 operation 继续实现，不能实现的列入待确认清单或禁用边界。
+- 不空停：如果必须暂停等用户，最终回复必须列出 `operation -> 缺少事实 -> 为什么阻断`，并提出一个明确问题。不要以“实现前需确认几个高风险接口细节”“读取关键 reference 原文”作为最终回复；仓库内已经存在的 reference 应先直接读取。
+
+## 入口与注册
+
+CLI 命令后缀 `<command>` 使用小写字母、数字和连字符，命令名就是 `<command>`；它独立于 Skill 后缀 `<skill>`，两者可不同。operation 前缀统一用 `<command>.<action>`：
+
+```text
+weaver-work-cli <command>
+weaver-work-cli <command> schema
+weaver-work-cli --json <command> run <command>.<action> --input-json '{"key":"value"}'
+```
+
+新增模块时必须更新 `src/shortcuts/index.ts`，把 `<command>Shortcut` 加入 `builtinShortcuts`。命令对象实现 `CliCommand`，`category` 使用 `shortcut`，注册方式参考 `src/shortcuts/invoice/index.ts`。命名分工：`src/shortcuts/<command>`、`docs/<command>.md`、`test/business/<command>-*.test.ts` 用 `<command>`；`skills/weaver-e10-<skill>`、`skill-template/domains/<skill>.md`、`skill-template/business-info.json` 的 key 用 `<skill>`。本规范下文的 `<module>` 均指 CLI 命令后缀 `<command>`。
+
+## 文件结构
+
+推荐结构：
+
+```text
+src/shortcuts/<module>/
+  index.ts                  Commander 命令注册、schema/run、可选人类友好子命令。
+  manifest.ts               operation 合约清单。
+  operations.ts             run 入口：选择 handler、校验输入、统一执行。
+  errors.ts                 模块结构化错误。
+  host.ts                   业务 API 适配，复用 E10 request runtime/session。
+  continuation.ts           只有 prepare/apply 写入链需要。
+  operations/
+    registry.ts             manifest 和 handler 一一对应校验。
+    types.ts                operation handler 类型。
+    shared.ts               通用输入校验、响应归一化、文件限制。
+    <operation>.ts          具体 operation。
+```
+
+小模块可以合并少量文件，但不能省略 `schema`、`run`、manifest 与 registry 对齐校验。
+
+## operation 合约
+
+`manifest.ts` 是 Agent 和测试的 WHAT 合约，至少暴露：
+
+```ts
+export interface <Module>OperationContract {
+  name: string;
+  risk: string;
+  scope?: string;
+  auth?: string[];
+  permissions?: string[];
+  conditionalAuth?: Record<string, string[]>;
+  conditionalPermissions?: Record<string, string[]>;
+  deprecatedInputAliases?: Record<string, string[]>;
+  fixed?: Record<string, unknown>;
+  inputSchema: Record<string, unknown>;
+}
+
+export const <module>Operations: <Module>OperationContract[] = [
+  {
+    name: '<module>.<action>',
+    risk: 'read',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {}
+    }
+  }
+];
+```
+
+operation 名称使用 `<module>.<action>`，多级动作可用 `<module>.<object>.<action>`。`inputSchema` 必须禁止额外字段；需要二选一、至少一个、互斥、固定值或默认值时用 JSON Schema 表达，不把规则只写在说明里。源资料给出权限、scope、角色、身份或接口前置条件时，记录到 `auth`、`permissions`、`scope` 或 `fixed` 中；如果当前模块不需要这些字段，可以省略，但不能把已知权限事实只放在正文里。
+
+如果某些权限、身份或接口只在特定执行路径需要，例如“勾选同步才需要写权限”“上传附件才需要文件接口”，用 `conditionalAuth` 或 `conditionalPermissions` 在 manifest 中声明触发条件，并在 handler 中按同一个条件校验。不要把条件权限只写进 `references/` 或错误提示里。
+
+常用风险等级：
+
+- `read`：只读查询。
+- `external-read`：向外部服务查询但不写业务数据。
+- `external-artifact`：上传或生成外部制品，但不落业务对象。
+- `read-with-upload`：上传后只读解析或预览。
+- `read-before-write`：写入前准备、预览、生成 continuation。
+- `high-risk-write`：新增、编辑、删除、导入、同步等真实写入。
+- `local-file-write`：写本地文件。
+
+## 命令行为
+
+每个业务命令必须提供：
+
+- `schema`：输出 manifest，供 Agent 判断 operation、字段和风险等级。
+- `run <operation> --input-json <json>`：从命令参数读取简单 JSON 对象并执行 operation，优先用于 Agent 示例和 Windows PowerShell。
+- `run <operation> --input <path>`：从 JSON 文件读取对象；传 `-` 时从标准输入读取，只在当前 shell 能稳定传管道时使用。
+- 可选的人类友好子命令：只作为薄包装，最终仍调用同一个 operation 执行器。
+- 可选本地 introspection：复杂 JSON 输入可以提供 schema 示例或 reference，但不能为了查看 schema 要求填写业务参数。
+
+命令示例和生成出的 Markdown 必须同时兼容 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 写法，不要把任一平台专属命令写成唯一默认步骤。
+
+`--json` 成功输出统一 envelope：
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "operation": "<module>.<action>",
+  "data": {},
+  "meta": { "status": "COMPLETE" },
+  "warnings": []
+}
+```
+
+失败输出统一 envelope：
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": false,
+  "error": {
+    "type": "validation",
+    "subtype": "input_invalid",
+    "message": "输入不合法",
+    "retryable": false
+  }
+}
+```
+
+结构化错误要能被 `toErrorEnvelope` 转换。校验失败用 usage exit code；认证、网络、策略、需要确认、写入不确定分别使用现有 `ExitCode` 语义。
+
+把这些视为公共兼容合约：operation 名称、字段名、默认值、固定业务参数、输出 envelope、错误 type/subtype、exit code、文件落点和覆盖策略。修改时必须同步更新测试、Skill reference 和 docs；不要为了兼容旧输入静默替换语义。确需兼容别名或旧字段时，在输入归一化阶段显式处理，并测试“新旧同时出现”的冲突规则。
+
+## 输入兼容与归一化
+
+字段名以 `manifest.ts` 的 `inputSchema` 为准。源资料、历史脚本或旧 Skill 里出现多个同义字段时，先选一个 canonical 字段；只有用户明确要求兼容旧输入，或已发布版本已经接受旧字段，才在 manifest 中记录 `deprecatedInputAliases`。
+
+归一化只能发生在 `operations/shared.ts` 或清晰命名的 `normalizeInput()` 阶段，且必须早于业务 host 调用。不要在 `host.ts`、HTTP body 拼装或结果处理里偷偷接受旧字段。旧字段和新字段同时出现时必须报结构化校验错误，不能让任一方静默覆盖另一方。
+
+归一化测试至少断言：旧字段能映射到 canonical 字段；canonical 字段保持原样；新旧字段同时出现会失败；错误的别名值不会绕过 `inputSchema` 的枚举、格式、互斥或固定值约束。
+
+## E10 与业务 API
+
+E10 业务模块必须复用 `src/internal/e10` 的 session、profile 和 request runtime，不直接读取认证文件、Cookie、Keychain 或 legacy auth 目录，也不在业务 `host.ts` 中直接调用 `fetch`。业务 host 只封装本模块需要的请求方法，负责：
+
+- 统一 base URL、headers 和 session 失效处理。
+- 把源资料里的接口路径映射为明确方法。
+- 归一化业务成功、业务错误、登录超时和网络异常。
+- 对上传、下载、本地文件读取设置大小、类型和覆盖保护。
+
+公共 E10 request runtime 提供统一拦截能力：`beforeRequest` 可在安全校验内调整 query、body、form、普通 header 和 timeout；不得修改 path，不得写入 Cookie、ETEAMSID、token、Authorization 等保留凭据头。`afterResponse` 默认只用于观察、记录和抛出结构化错误，不作为业务成功语义的任意改写入口。模块特有 token、业务成功码、重试和响应归一化仍留在模块 `host.ts`，不要放进全局 runtime。
+
+如果源资料没有说明接口路径、请求方法、必要字段、分页语义、返回结构或错误码，不要猜；先把已确认 operation 继续落地，再向用户列出剩余缺口并等待补充。
+
+用户或工作区文件访问必须在模块内集中校验。读取、上传、下载和写本地文件前，operation 要限制文件类型、大小、父目录存在性、路径逃逸和覆盖行为；Skill 层的风险提醒不能替代 CLI 层校验。
+
+## guidance 分工
+
+参考飞书 CLI 的 affordance/Skill 分层，weaver 中按以下边界维护：
+
+- `manifest.ts` / `schema` 拥有 WHAT：operation、字段、风险、固定参数、权限或身份事实。
+- `docs/<module>.md` 拥有维护者和命令级 WHEN：模块来源、命令结构、operation 表、何时用哪个 operation、已知限制。
+- `skills/weaver-e10-<module>/SKILL.md` 拥有领域路由、共享规则入口、跨 operation 工作流和安全边界。
+- `references/*.md` 拥有条件化 HOW：具体命令示例、输入摘要、输出处理、失败处理和回查策略。
+
+不要在 docs 或 Skill 中重复整份 schema；需要字段细节时让 Agent 读取 `weaver-work-cli <module> schema` 或对应 reference。所有 shipped reference 路径必须真实存在，入口里不要链接不会随包发布的源码文件。
+
+## 高风险写入
+
+新增、编辑、删除、导入、同步等写操作必须优先设计为 `prepare -> apply`。这相当于飞书 shortcut 的 high-risk `--yes` 与 `--dry-run` 纪律，但 weaver 的确认必须沉到 CLI operation 中：
+
+1. `prepare` 做只读回查、输入归一化、差异摘要和 continuation 签发，不真实写入。
+2. Agent 把目标、差异、风险和确认条件摘要给用户。
+3. 用户明确确认后，`apply` 必须要求 `confirm: true` 和有效 continuation。
+4. `apply` 校验 session、目标 ID、文件 sha256 或业务对象指纹没有变化。
+5. 写请求已发送后，如遇网络中断、部分成功或回查失败，返回 `partial/write_uncertain`，禁止自动重复提交。
+
+写操作不能只有 Skill 层确认；CLI 必须强制确认链。
+
+只读预览、外部查询、上传后解析等非写入风险，优先命名为 `*.preview` 或 `*.validate.preview`，并在 `risk` 中标明 `external-read`、`external-artifact` 或 `read-with-upload`。能本地预览请求形状但不触网的模块，可额外提供 dry-run，但它不能替代 `prepare -> apply`。
+
+## 测试与文档
+
+新增或更新业务 CLI 时同步维护：
+
+- `test/business/<module>-*.test.ts`：覆盖 manifest、固定字段、输入校验、核心 operation、写入确认和不确定结果。
+- `docs/<module>.md`：说明模块来源、CLI 结构、operation 表、常见命令和安全边界。
+- `skills/weaver-e10-<module>`：只引用已实现 operation，并与 `weaver-work-cli <module> schema` 保持一致。
+
+测试断言至少覆盖：
+
+- manifest 和 registry 一一对应：每个 operation 有 handler，每个 handler 在 schema 中暴露。
+- schema 合约：operation 名称、risk、scope/auth/permissions、`additionalProperties: false`、required/oneOf/const/default 等关键字段。
+- 请求形状：用 fake host 断言 method、path、query、body、固定业务参数和分页默认值，避免只测返回文本。
+- 错误形状：校验失败、认证失败、业务失败、网络失败、结果不确定都返回稳定 type/subtype 和 exit code。
+- 高风险写入：`prepare` 不写入；`apply` 缺少 `confirm: true` 或 continuation 必失败；目标、session、文件 sha256 或业务指纹变化必须失败；写请求发出后的不确定结果不能自动重试。
+- 文件操作：本地输入文件存在、类型、大小、路径逃逸；下载或导出拒绝覆盖已存在文件。
+- 命令输入：`--input-json`、`--input <path>` 和 `--input -` 的解析行为一致；`--input-json` 与 `--input` 同时出现时报结构化校验错误；UTF-8 BOM 文件能正常读取。
+- Skill/CLI 一致性：抽取 Skill 和 reference 中的 `run <operation>` 示例，断言 operation 在 manifest 中存在；示例使用的字段必须在 schema 中存在。
+- 示例安全：docs、tips、reference 示例只用 `PLACEHOLDER_VALUE`、`example.test` 或明显假 ID，不出现真实 IP、内网域名、Cookie、Token、手机号、邮箱或个人路径；PowerShell 命令块里不要使用会被解释为重定向的裸尖括号占位符。
+- 更新路径：源资料变化时，测试或文档要证明 CLI、Skill、manifest、business-info 和 domain 同步更新；如果 manifest 存在 `operationImpact`，要优先覆盖受影响 operation、schema 字段、reference 和写入确认链。
+- Git 更新语义回归：基于 `OLD_REF..NEW_REF` 更新时，不只检查生成产物存在；还要为受影响 operation 补充或更新 golden tests，断言用户意图会路由到正确 operation、字段 canonical 化与旧字段兼容策略、固定参数/默认值/枚举、写入确认链和错误 envelope。`major` 兼容性变化必须有测试覆盖迁移或拒绝策略。
+
+验证命令：
+
+Windows PowerShell：
+
+```powershell
+npm test -- "test/business/MODULE_NAME-*.test.ts"
+npm test -- test/skills/layout.test.ts
+npm run build
+weaver-work-cli MODULE_NAME schema
+py -3 DETECTOR_DIR\scripts\validate_skill.py skills\weaver-e10-MODULE_NAME --json --no-html
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+npm test -- "test/business/MODULE_NAME-*.test.ts"
+npm test -- test/skills/layout.test.ts
+npm run build
+weaver-work-cli MODULE_NAME schema
+python3 DETECTOR_DIR/scripts/validate_skill.py skills/weaver-e10-MODULE_NAME --json --no-html
+```

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

@@ -0,0 +1,105 @@
+# 检测通过后的安装确认
+
+业务模块 Skill 生成并通过泛微技能检测工具后，必须询问用户是否把它安装到当前使用的智能体。安装会改变用户本机 Agent 的 skills 目录，因此不能跳过确认。
+
+## 触发条件
+
+只有同时满足以下条件，才进入安装确认：
+
+- `skills/weaver-e10-<module>` 已生成或更新完成。
+- 泛微技能检测工具默认 `weaver` 模式结果为 `PASS`，或仅有用户明确接受的 WARN。
+- `weaver-work-cli skills list` 能读到生成后的 Skill。
+
+检测失败、检测未运行、当前 Skill 不在 `weaver-work-cli/skills` 下、或用户尚未确认安装时，不要执行安装。
+
+## 弹框确认
+
+优先使用当前宿主支持的弹框、确认 UI 或用户输入工具询问：
+
+```text
+业务模块 Skill 已生成并通过检测。是否安装到当前智能体？
+
+将安装：
+- weaver-e10-shared
+- weaver-e10-<module>
+
+目标目录：<detected-agent-skills-root>
+```
+
+如果当前智能体没有弹框或确认 UI，退化为普通对话提问。无论使用哪种方式，必须得到用户明确同意后才安装；用户没有回复、关闭弹框或选择取消时，只报告生成目录和检测结果。
+
+## 当前智能体目录
+
+按当前宿主识别目标目录：
+
+- Codex：优先环境变量 `CODEX_HOME` 下的 `skills` 子目录；未设置时使用用户主目录下的 `.codex/skills`（Windows PowerShell：`$env:USERPROFILE\.codex\skills`；macOS/Linux：`$HOME/.codex/skills`）。
+- WorkBuddy：使用用户主目录下的 `.workbuddy/skills`（Windows PowerShell：`$env:USERPROFILE\.workbuddy\skills`；macOS/Linux：`$HOME/.workbuddy/skills`）。
+- 用户显式指定目录：以用户指定为准。
+- 其它智能体：只有当宿主暴露明确的本地 skills 根目录且当前进程可写时才自动安装；否则说明当前智能体不支持自动安装。
+
+不要同时安装到多个 Agent 目录，除非用户明确要求。不要猜测隐藏目录或扫描用户主目录寻找其它 Agent。
+
+## 打包
+
+用户确认安装后，先生成归档，再执行安装。`scripts/package-skill.mjs` 使用纯 Node 生成 ZIP，不依赖系统 `zip`/`unzip` 命令；仓库内生成的 Skill 使用：
+
+Windows PowerShell：
+
+```powershell
+node scripts/package-skill.mjs MODULE_NAME "C:\path\to\weaver-e10-MODULE_NAME-skill.zip"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+node scripts/package-skill.mjs MODULE_NAME "/path/to/weaver-e10-MODULE_NAME-skill.zip"
+```
+
+归档路径建议放在临时目录或仓库 `dist/`，最终回复说明 zip 路径和 sha256。若脚本不可用或写入目标失败，先说明无法打包；不要继续自动安装未打包产物，除非用户明确接受只做目录安装。
+
+## 安装
+
+用户确认后，使用 `weaver-work-cli` 自带安装命令安装当前模块。它会自动带上 shared：
+
+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"
+```
+
+如果 `weaver-work-cli` 全局命令不可用，但当前仓库已构建，可以用当前构建产物执行同等命令：
+
+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"
+```
+
+安装后验证目标目录中存在：
+
+- `weaver-e10-shared/SKILL.md`
+- `weaver-e10-<module>/SKILL.md`
+
+若目标目录不可写、当前智能体不支持本地 Skill、或安装命令失败，停止并报告原因、zip 路径和手动安装命令；不要改装到其它目录。
+
+## 完成回复
+
+最终回复要包含：
+
+- Skill 目录。
+- 检测器结果和版本。
+- 是否已打包、zip 路径和 sha256。
+- 用户是否选择安装。
+- 如果已安装，说明目标智能体和 skills 目录；如果未安装，说明未安装原因。