weaver-work-cli 0.1.6 → 0.1.7

package/skills/weaver-e10-shijingran/references/write-operations.md

@@ -0,0 +1,90 @@
+# 事井然写操作确认链
+
+## 何时使用
+
+创建、修改、删除项目或任务时使用。所有写操作必须执行 `prepare -> apply`，不能直接提交。
+
+## 字段与默认值
+
+### 任务创建
+
+- 必填业务字段只有 `task_name`；`records` 至少 1 条、最多 100 条。
+- `manager` 未指定或传 `"@me"` 时，CLI 在 prepare 自动填当前登录人 ID，无需先查 userId；要指定他人时，先按 `field-resolution.md` 解析为 ID，并在 prepare 摘要中说明负责人。
+- `plan_start_time` / `plan_finish_time` 未指定时留空，业务接口不会注入默认值；在 prepare 摘要中如实说明「不设置计划时间」。
+- `project`、`parent_node`、人员、字典和自定义字段需要 ID 时，先按 `field-resolution.md` 解析。
+
+### 项目创建
+
+- 必填业务字段是 `proj_name`；`manager` 未指定或传 `"@me"` 时自动填当前登录人 ID（同任务创建）。
+- `plan_start_time` / `plan_finish_time` 未指定时留空，不要声称有默认值。
+- `progress` 为 0-100 的数字；不要把百分比符号写入值。
+
+### 通用格式
+
+- 日期时间：`yyyy-MM-dd HH:mm`，例如 `2026-09-14 18:00`。
+- 仅验收日期等纯日期字段使用 `yyyy-MM-dd`。
+- 多选字段用英文逗号拼接 ID 字符串且无空格，例如 `"id1,id2"`；不要传 JSON 数组。
+- 所有 ID 都按字符串传递。
+- `sys_status` 是系统维护字段，只能用于查询过滤，不能写入。
+- 附件字段只接受已上传文件 ID；本 Skill 不提供附件上传，处理文件前必须取得用户敏感数据确认。
+
+## 创建
+
+`prepare` 输入 `records`，每条记录是源接口 `mainTable` 字段对象。`prepare` 不触网写入，只生成请求预览和 continuation。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json project run project.task.create.prepare --input-json '{"records":[{"task_name":"需求评审"}]}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json project run project.task.create.prepare --input-json '{"records":[{"task_name":"需求评审"}]}'
+```
+
+向用户摘要记录数、用户提供的字段、准备使用的目标对象、解析后的 ID、接口默认值和不可逆性。用户明确确认后才执行 apply：
+
+```json
+{"continuation":"PREPARE_CONTINUATION","confirm":true}
+```
+
+## 修改
+
+- `project.task.update.prepare` / `project.project.update.prepare` 输入 `id` 和 `fields`。
+- 只传用户明确要求修改的字段；未提及字段保持原值。
+- `prepare` 会先回查当前数据并绑定指纹；向用户展示变更前/后差异。
+- 若用户用名称指定关联字段，先解析为 ID，再进入 prepare。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json project run project.task.update.prepare --input-json '{"id":"<taskId>","fields":{"progress":50}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json project run project.task.update.prepare --input-json '{"id":"<taskId>","fields":{"progress":50}}'
+```
+
+## 删除
+
+- `project.task.delete.prepare` / `project.project.delete.prepare` 仅输入 `id`。
+- 删除不可逆；prepare 摘要必须明确说明目标名称、类型和“不可恢复”。
+- 用户确认后才能 apply。
+
+## apply 约束
+
+- 必须 `confirm: true`。
+- `continuation` 必须原样传入，不得改写、截断或重新生成。
+- 修改/删除 apply 前会再次回查；`target_changed` 时必须重新 prepare。
+- continuation 与当前登录会话绑定，登录变化后不得复用。
+
+## 失败处理
+
+- `confirmation.required` 或缺少 `confirm`：停止，重新向用户确认。
+- `target_changed`：重新回查并重新 prepare。
+- `partial/write_uncertain`：禁止重试写入，先只读回查详情或列表。
+- 网络中断、登录失效、回查失败：停止写流程并如实告知用户。

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

@@ -10,24 +10,38 @@ author: 泛微网络科技股份有限公司
 agent_created: true
 requires:
   bins: ["weaver-work-cli"]
+dependencies:
+  - weaver-e10-login
 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`，安装或读取失败时必须停止执行。**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若不存在则必须先执行 `weaver-work-cli skills install shared --target-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。
+本 Skill 参考飞书 CLI 的 `lark-skill-maker`，但输出范围更完整：Agent 需要把已经给出的业务模块资料同步固化为 `weaver-e10-*` Agent Skill 和对应 `src/shortcuts/<module>` TypeScript CLI 能力。新业务模块一开始没有对应 `weaver-work-cli` 业务命令是正常输入，但不能只生成文档型 Skill；默认要把 CLI 一并设计、实现、测试并让 Skill 调用真实 operation。转换时以**业务语义保真**为第一目标：入口 `SKILL.md` 可以轻量，但 `references/`、schema、handler、测试和禁用边界必须承接源资料里的可执行业务细节，不能把多份源 MD 压缩成泛泛概述导致能力退化。
 
 生成或更新的 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 写法，不要把任一平台专属命令写成唯一默认步骤。
 
+## 认证与请求头契约
+
+登录与会话由 E10 登录能力统一提供：文档型约定为 `weaver-e10-login` 技能，本 CLI 场景下等价入口是 `weaver-work-cli auth ...` 命令体系。业务 Skill 不自建登录流程，不索取、打印或转存任何凭证。
+
+CLI 发往 E10 的每个请求都自动携带以下三项用户信息参数，**缺一不可**（业务入参里不要传这些字段，也不要手工拼装请求头）：
+
+```text
+Cookie: <登录返回的完整原始 Cookie 串，原样透传，禁止裁剪/去重/改写>
+eteamsid: <登录返回的 ETEAMSID>
+User-Agent: AgentType=<agentType>,IsAgent=true
+```
+
 ## 适用范围
 
 使用本 Skill 处理以下请求：
 
 - 把新的 E10 / 泛微业务模块文档、接口说明、现有代码或示例同步转换成 `weaver-work-cli` 业务 CLI 与 Skill。
-- 为已有 `src/shortcuts/<module>` 和 `skills/weaver-e10-<module>` 补 operation、reference、路由语义、禁用边界、文件处理确认或写操作确认链。
+- 为已有 `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 拆分和安装约定。
@@ -37,6 +51,8 @@ cliHelp: "weaver-work-cli skills --help"
 推进规则：
 
 - 用户已明确作为输入提供的业务文档、代码目录、接口说明或样例，视为本次转换的源资料；先读取与当前模块直接相关的原文和现有 reference，再判断是否缺口。不要只因为“需要读取 reference 原文”就停止。
+- 转换不得以摘要替代业务规则。源 MD 中的字段表、枚举/状态、默认值、固定参数、权限前置、分页/排序口径、ID 解析规则、流程分支、写入确认条件、错误码、返回结构、示例和禁用能力，必须分别落到 `manifest.ts` / handler / reference / 测试 / 禁用边界之一；确实不能迁移的细节要在待确认清单或禁用边界说明原因。
+- 源资料给出结构化 JSON 请求体字段表时，`inputSchema.properties` 必须逐字段转换字段名、类型、必填、数组元素和嵌套对象；禁止只暴露 `payload`、`body`、`requestPayload` 或 `object` 这类通用包裹字段来替代字段转换。确需兼容旧 `payload` 输入时，只能在 handler 归一化层保留兼容，schema/reference 仍以逐字段 canonical 入参为准。
 - 缺口只阻断受影响的 operation；已能从源资料确认的只读、预览、准备或文档索引部分要继续实现。不能实现的能力写入待确认清单或禁用边界，不要生成假 operation。
 - 如果确实必须等用户补充，回复必须列出具体缺口并提出明确问题，例如缺少哪个 operation 的接口路径、请求方法、关键字段、权限边界、幂等键、回查接口或写入确认条件。不能只说“需要确认细节”，也不要以“实现前需要确认几个细节”“随后开始实现”这类状态句作为最终回复。
 
@@ -45,11 +61,12 @@ cliHelp: "weaver-work-cli skills --help"
 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。
+4. 读取 [`weaver-skill-style.md`](references/weaver-skill-style.md)，确保入口 `SKILL.md`、`references/`、`skill-template/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 命令示例。
+6. 若用户要求扫描单个已有业务模块是否转全，或要求补齐缺少的业务逻辑/参数，读取 [`module-gap-audit-and-repair.md`](references/module-gap-audit-and-repair.md)，先做缺口审计和分级，再对可由源资料证明的缺口实施修复；资料不足的缺口只登记为待确认，不编造业务逻辑或入参。
+7. 读取 [`detector-validation.md`](references/detector-validation.md)，每次创建或更新 Skill 后都必须先询问用户是否现在进行 Skill 质检；用户同意后用泛微技能检测工具校验生成结果。用户拒绝、未回复或检测器不可用时，只能停在待质检状态，不能安装、发布或把未过检的 Skill 当作完成；检测失败时先修复。
+8. 检测通过后读取 [`post-generation-install.md`](references/post-generation-install.md)，用宿主支持的弹框或确认 UI 询问用户是否安装；用户确认后再打包并安装到当前智能体可识别的 skills 目录。
+9. 完成后至少验证 `weaver-work-cli <module> schema`、`weaver-work-cli skills list` 和 `weaver-work-cli skills read weaver-e10-<module>`；在仓库内改动时再跑相关测试，并确认新生成 Markdown 中没有 Unix-only 命令示例。
 
 ## 命名约定
 
@@ -65,7 +82,7 @@ cliHelp: "weaver-work-cli skills --help"
 生成或更新业务 CLI 与 Skill 时，默认只改这些位置：
 
 - `skills/weaver-e10-<module>/SKILL.md`
-- `skills/weaver-e10-<module>/product.json`
+- `skill-template/product.json`
 - `skills/weaver-e10-<module>/references/*.md`
 - `skills/weaver-e10-<module>/references/source-manifest.json`
 - `src/shortcuts/<module>/` 和 `src/shortcuts/index.ts`
@@ -75,4 +92,4 @@ cliHelp: "weaver-work-cli skills --help"
 - `skill-template/domains/<module>.md`
 - 必要时更新仓库级文档索引或说明文件；这些不是发布包内 reference，入口文件里不要把它们写成可点击引用
 
-不要把用户源文档全文复制进 Skill；只提炼稳定的业务规则、operation 使用方式、字段约束、风险确认和禁用边界。超长接口手册应拆成按需读取的 reference，或继续留在用户指定的源资料位置并在 manifest 中记录来源。
+不要把用户源文档全文塞进入口 `SKILL.md`，也不要复制无关叙述、截图说明或敏感内容；但所有会影响 Agent 正确执行的业务契约都要保真迁移。超长接口手册应按业务对象、operation 或源文档标题拆成多个按需读取的 reference，并在 manifest 中记录 `sourceChunks` / `operationImpact` / `sourceCoverage`；如果某段源资料只保留在外部位置，必须说明它不参与已生成能力，或列入待确认/禁用边界。

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

@@ -17,7 +17,7 @@
 
 当用户要求“根据源码仓库提交记录更新业务模块 Skill/CLI”时，把 Git 范围视为源资料的一部分。开始差异分析前，主动确认以下信息；用户没有提供时先提问，不能用网页 URL、目录名或最近提交自行补齐：
 
-- **源码仓库本地路径**：本地 clone 下来的仓库根目录，例如 `C:\work\weaver-interface` 或 `/Users/me/work/weaver-interface`。线上 GitLab/GitHub URL 只能作为来源说明；除非用户明确允许 clone/fetch 并提供访问能力，否则不要把远程 URL 当作可直接执行的仓库路径。
+- **源码仓库本地路径**：本地 clone 下来的仓库根目录，例如 `<本地仓库根目录>`（如 Windows 的 `C:\work\weaver-interface`、macOS/Linux 的 `~/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、路由注册、公共枚举、鉴权或全局配置，让用户补充这些仓库相对路径；没有提供时先用模块路径过滤，并在影响报告中说明可能漏掉公共依赖。
@@ -35,12 +35,31 @@
 - `sha256`
 - 可选的 `role`：`api-doc`、`code`、`sample`、`existing-skill`、`requirement`
 
-用户本轮明确提供为输入的业务文档、代码目录、接口说明和样例，可以直接读取用于转换；读取后只把稳定规则、字段和约束写入生成产物，不复制整份源文档。源资料是附件、图片、远程 URL、二进制文件，或需要上传到外部解析/OCR 服务时，先按 shared 规则提示风险并等待用户确认。仅拿文件路径做 manifest 指纹通常不需要读取正文。
+用户本轮明确提供为输入的业务文档、代码目录、接口说明和样例，可以直接读取用于转换；转换阶段必须阅读与业务模块相关的正文并抽取可执行契约，不能只拿文件名或摘要生成能力。读取后不要复制整份源文档、无关叙述或敏感内容，但必须把稳定规则、字段、约束和流程细节保真迁移到生成产物。源资料是附件、图片、远程 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 标记弱检测。
 
+同时写入或更新 `sourceCoverage`：逐个源文件记录 `converted`、`withheld`、`external-only`、`not-applicable` 或 `needs-confirmation` 状态，以及对应 operation/reference/原因。任何 `api-doc`、`existing-skill` 或 `code` 源文件如果没有映射到 `sourceChunks` 或 `sourceCoverage`，都必须在最终回复中说明原因并视为待确认风险。
+
+还要为每个 operation 写入或更新参数覆盖矩阵，至少记录在 `source-manifest.json` 的 `operationImpact[operation].parameterCoverage` 或等价结构中。矩阵必须以源资料参数为起点，逐项记录参数名、源位置、类型/必填/枚举/默认值等已知事实、落到的 `inputSchema` 字段，以及状态：
+
+- `converted`：已进入 `inputSchema`，并由 handler/host 使用。
+- `fixed`：源接口要求但不暴露给 Agent 的固定参数，写入 manifest 的 `fixed` 或 handler 常量。
+- `derived`：由 CLI 内部查询、解析或 continuation 绑定得到，例如名称转 ID、当前用户、prepare 输出。
+- `deprecatedAlias`：兼容旧字段，写入 `deprecatedInputAliases` 并测试冲突规则。
+- `withheld`：源资料有该参数或能力，但当前 CLI 不支持，写清原因。
+- `needs-confirmation`：源资料只出现字段名或片段，缺少类型、是否必填、来源、枚举、权限、回查或绑定规则，等待用户补充。
+- `not-applicable`：接口内部字段、展示字段或返回字段，不应暴露为 Agent 入参。
+
+入参 example 采用分级规则，不能因源资料没有 example 就阻断整个生成：
+
+- 源资料已有请求样例、历史 Skill 样例或可运行脚本入参时，必须原样抽取业务含义并写入 manifest 的 `inputExamples`（或等价字段），标明 `source`；未迁移视为生成失败。
+- 源资料没有 example，但字段表、必填、枚举和默认值足够完整时，可以生成 `source: "synthetic"` 的推导样例，必须只用明显假值或占位值，并标明“由 schema 推导，需业务复核”。
+- 源资料没有 example 且参数事实不完整时，不得编造样例；在 manifest/source-manifest 中记录 `missingExamples`，并在最终回复列出需要用户后续补充的 operation 和缺少事实。
+- 测试应失败的情况是：源资料有 example 但 manifest 缺失、example JSON 不可解析、example 字段不在 schema 中、最小 example 缺少 required 字段，或 reference 命令示例与 manifest/schema 不一致。仅“源资料未提供 example”只能作为 WARN/needs-confirmation。
+
 ## 3. 抽取业务语义
 
 从源资料中提炼这些稳定信息：
@@ -52,6 +71,18 @@
 - 已知禁用能力：文档中存在但 CLI 未暴露、缺少稳定 ID、缺少回查或风险不可自动化的能力。
 - 认证边界：业务 Skill 只调用 CLI，不复制 Cookie、ETEAMSID、Token 或内部登录逻辑。
 
+### 业务语义保真清单
+
+不要把多份源 MD 压缩成一个“能力概述”。对每个业务对象或 operation，至少检查并迁移以下可执行细节：
+
+- 字段表：字段名、类型、必填、默认值、枚举/状态、单位、时间格式、ID 精度、别名、互斥/二选一/至少一个、固定参数和废弃字段兼容策略。
+- 请求与响应：接口路径、请求方法、query/body/form/file 位置、分页/排序/筛选口径、返回结构、成功判定、错误码、空结果语义和大结果展示规则。
+- 业务流程：前置查询、版本门禁、权限/scope、对象状态流转、跨链路差异、ID/名称解析、缓存或字典依赖、写前回查、写后回查和不确定结果处理。
+- 示例与边界：源资料已有入参 example 时必须迁移到 manifest 和 reference；源资料没有 example 时按参数完整度生成 `synthetic` 样例或登记 `missingExamples`，并在最终报告中列出待补充项；如果源资料区分成功、失败、不同链路或不同对象类型，要分别保留能影响执行的差异。
+- 禁用与缺口：源资料出现但未生成 CLI operation 的能力，必须进入 schema 的 withheld/disabled 信息或 reference 的禁用边界，并写清缺少的事实和为什么阻断。
+
+迁移方式要按所有权落点分配：`manifest.ts` / `schema` 承载 WHAT，handler 和 host 承载请求形状与校验，`references/` 承载条件化 HOW，测试承载关键语义回归。不能只把细节写在自然语言里，也不能只在代码里实现而不让 Skill/reference 指到对应用法。若源资料给出 JSON 请求体字段表，`inputSchema.properties` 必须逐项暴露这些业务字段；不能把整段请求体塌缩成 `payload`/`body`/`requestPayload` 一个 object 后宣称已转换。
+
 如果源资料描述的是底层接口，但仓库还没有对应 operation，按 [`module-cli-generation.md`](module-cli-generation.md) 先实现 CLI，再让 Skill 调用该 operation。确实缺少实现依据时，把缺口列入待确认清单并问用户，不能生成假 operation；缺口只阻断对应 operation，已确认的能力继续生成 CLI、测试、docs 和 Skill reference。
 
 ## 4. 同步实现 CLI
@@ -86,14 +117,14 @@ weaver-work-cli --json MODULE_COMMAND run MODULE_NAME.operation --input-json '{"
 
 - 入口 `SKILL.md`：只放共享前置、路由优先级、operation 表、处理链、执行原则和不在范围。
 - `references/`：每类意图或每个 operation 一个 reference，写具体输入、命令示例、输出摘要、注意事项和失败处理。
-- `product.json`：声明 `weaver-work-cli` 运行时。
+- `skill-template/product.json`：统一声明 `weaver-work-cli` 运行时；打包或安装时为每个 Skill 产物注入 `product.json`。
 - `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 项。
+- Skill 质检确认与泛微技能检测结果：每次创建或更新 Skill 后，先按 `detector-validation.md` 询问用户是否现在进行 Skill 质检；用户同意后运行检测，确保生成出的 Skill 至少无 BLOCK/FAIL 项。未得到确认、未运行检测或检测失败时，只能报告待质检状态，不能安装、发布或宣布完成。
 - 安装确认：检测通过后按 `post-generation-install.md` 询问用户是否安装，确认后再打包并安装到当前智能体。
 
-写 reference 时只保留执行所需的事实和约束，不复制整份接口手册。复杂字段以小而完整的 JSON 示例展示，避免超长响应或敏感字段。
+写 reference 时保留执行所需的全部事实和约束，不复制整份接口手册里的无关叙述。复杂字段优先使用 manifest 中的 `inputExamples` 展示小而完整的 JSON 示例；没有源 example 时，reference 必须说明该示例是 `synthetic` 或该 operation 缺少样例，不能伪装成源资料事实。字段表、枚举、流程分支、错误处理和禁用边界过长时，按 operation、业务对象或源文档标题拆成多个 reference，而不是删减成摘要。reference 应做到：对已生成的 operation，Agent 只依赖当前 Skill 包和 `weaver-work-cli <command> schema` 就能正确执行，不需要再回源资料包补读业务规则。
 
 ## 6. 验证
 
@@ -107,7 +138,7 @@ 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
+weaver-work-cli skills validate skills\weaver-e10-MODULE_NAME --json --no-html
 ```
 
 macOS/Linux（bash/zsh）：
@@ -118,7 +149,7 @@ 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
+weaver-work-cli skills validate skills/weaver-e10-MODULE_NAME --json --no-html
 ```
 
-如果新增或修改了 TypeScript CLI 代码，再运行构建和相关业务测试。若验证失败，优先修正 CLI 合约、artifact 结构、frontmatter、reference 链接和 business-info 对齐问题。检测通过后，进入安装确认流程；用户未确认前不要安装。
+如果新增或修改了 TypeScript CLI 代码，再运行构建和相关业务测试。运行泛微技能检测工具前必须先询问用户是否现在进行 Skill 质检；用户同意后再执行 detector 命令。若验证失败，优先修正 CLI 合约、artifact 结构、frontmatter、reference 链接和 business-info 对齐问题。检测通过后，进入安装确认流程；用户未确认前不要安装。

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

@@ -4,14 +4,31 @@
 
 ## 检测工具来源
 
-检测工具不是生成出的业务 Skill 的一部分。运行时按以下顺序定位：
+检测工具不是生成出的业务 Skill 的一部分，但它是 `weaver-work-cli` 的随包依赖。优先使用稳定入口：
 
-1. 用户本轮明确提供的检测工具目录。
-2. 当前工作区中与 `weaver-work-cli` 同级的 `weaver-skill-detector-1.0.13` 目录。
-3. 如果以上都不可用，向用户询问检测工具目录，不要自行联网下载或改用其它检测器。
+```text
+weaver-work-cli skills validate <skill-dir-or-zip> --json --no-html
+```
+
+运行时按以下顺序定位：
+
+1. `weaver-work-cli` 包内的 `tools/weaver-skill-detector-1.0.13`。
+2. 用户本轮明确提供的检测工具目录，通过 `weaver-work-cli skills validate --detector-dir DETECTOR_DIR ...` 使用。
+3. 当前工作区中与 `weaver-work-cli` 同级的 `weaver-skill-detector-1.0.13` 目录仅作为旧版本地开发兜底；正常拉取或安装 `weaver-work-cli` 后不应依赖它。
+4. 如果以上都不可用，说明当前安装包不完整或向用户询问检测工具目录，不要自行联网下载或改用其它检测器。
 
 不要把本机个人绝对路径写入生成出的 Skill 或 `source-manifest.json`；需要记录检测器时只写工具名、版本号或用户提供的相对位置。
 
+## 质检确认门槛
+
+每次 Skill Maker 创建或更新 `skills/weaver-e10-<module>` 后，在安装、打包发布或最终宣布完成前，必须明确询问用户是否现在进行 Skill 质检。推荐提问：
+
+```text
+业务模块 Skill 已生成/更新。Skill 质检是必需步骤，是否现在使用泛微技能检测工具进行质检？
+```
+
+用户明确同意后，按上面的检测工具来源定位 detector 并运行检测。用户拒绝、未回复、要求稍后再做，或当前环境没有可用检测器且用户未提供目录时，停止在“待质检”状态：可以报告生成目录、待运行命令和缺少的检测器信息，但不得安装、发布、声明完成、或把该 Skill 标记为通过检测。
+
 检测器的 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"` 判断。不要把个人绝对路径写入生成产物。
@@ -57,13 +74,13 @@ cliHelp: "weaver-work-cli <command> --help"
 Windows PowerShell：
 
 ```powershell
-py -3 DETECTOR_DIR\scripts\validate_skill.py GENERATED_SKILL_DIR --json --no-html
+weaver-work-cli skills validate GENERATED_SKILL_DIR --json --no-html
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-python3 DETECTOR_DIR/scripts/validate_skill.py GENERATED_SKILL_DIR --json --no-html
+weaver-work-cli skills validate GENERATED_SKILL_DIR --json --no-html
 ```
 
 如果还生成了发布 zip，再用 Python 3.11+ 检测 zip：
@@ -71,13 +88,13 @@ python3 DETECTOR_DIR/scripts/validate_skill.py GENERATED_SKILL_DIR --json --no-h
 Windows PowerShell：
 
 ```powershell
-py -3.11 DETECTOR_DIR\scripts\validate_skill.py GENERATED_SKILL_ZIP --json --no-html
+weaver-work-cli skills validate GENERATED_SKILL_ZIP --json --no-html --python "C:\Path\To\Python311\python.exe"
 ```
 
 macOS/Linux（bash/zsh）：
 
 ```bash
-python3.11 DETECTOR_DIR/scripts/validate_skill.py GENERATED_SKILL_ZIP --json --no-html
+weaver-work-cli skills validate GENERATED_SKILL_ZIP --json --no-html --python python3.11
 ```
 
 退出码含义：

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

@@ -63,6 +63,18 @@ export interface <Module>OperationContract {
   conditionalPermissions?: Record<string, string[]>;
   deprecatedInputAliases?: Record<string, string[]>;
   fixed?: Record<string, unknown>;
+  inputExamples?: Array<{
+    name: string;
+    input: Record<string, unknown>;
+    source: string;
+    sourceType: 'source-provided' | 'synthetic';
+    notes?: string;
+  }>;
+  missingExamples?: Array<{
+    reason: string;
+    missingFacts?: string[];
+    source?: string;
+  }>;
   inputSchema: Record<string, unknown>;
 }
 
@@ -79,7 +91,16 @@ export const <module>Operations: <Module>OperationContract[] = [
 ];
 ```
 
-operation 名称使用 `<module>.<action>`，多级动作可用 `<module>.<object>.<action>`。`inputSchema` 必须禁止额外字段；需要二选一、至少一个、互斥、固定值或默认值时用 JSON Schema 表达，不把规则只写在说明里。源资料给出权限、scope、角色、身份或接口前置条件时，记录到 `auth`、`permissions`、`scope` 或 `fixed` 中；如果当前模块不需要这些字段，可以省略，但不能把已知权限事实只放在正文里。
+operation 名称使用 `<module>.<action>`，多级动作可用 `<module>.<object>.<action>`。`inputSchema` 必须禁止额外字段；需要二选一、至少一个、互斥、固定值或默认值时用 JSON Schema 表达，不把规则只写在说明里。源资料给出结构化 JSON 请求体字段表时，必须把字段逐项转换进 `inputSchema.properties`，包括必填、数组元素、嵌套对象、枚举和默认值；不得只写 `{ payload: { type: "object" } }`、`requestPayload`、`body` 或 `additionalProperties: true` 来代替参数转换。若为了兼容旧版本继续接受 `payload`，只能在 handler 归一化中处理，并用测试证明 canonical 顶层字段仍是 schema/reference 的唯一推荐输入。源资料给出权限、scope、角色、身份或接口前置条件时，记录到 `auth`、`permissions`、`scope` 或 `fixed` 中；如果当前模块不需要这些字段，可以省略，但不能把已知权限事实只放在正文里。
+
+`inputExamples` 是 Agent 入参格式的优先参考，按以下规则生成：
+
+- 源资料、历史 Skill、测试脚本或接口文档已有入参样例时，必须迁移到 `inputExamples`，`sourceType` 为 `source-provided`，`source` 指到源文件、标题、脚本或稳定 chunk；这类样例缺失时测试失败。
+- 源资料没有样例但参数事实完整时，可以生成 `sourceType: "synthetic"` 的最小样例，字段值只能用明显假值、`example.test` 或安全占位，并在 `notes` 标明由 schema 推导、需业务复核。
+- 源资料没有样例且参数事实不足时，不要生成伪样例；写入 `missingExamples`，列出缺少的类型、必填、枚举、来源、绑定规则、回查或确认链事实。生成完成时必须把这些缺口报告给用户。
+- 只读无入参 operation 可以省略 `inputExamples`，但要保证 `inputSchema.properties` 为空且 reference 不制造多余入参。
+
+`inputExamples` 中每个字段必须出现在 `inputSchema.properties` 或 `deprecatedInputAliases` 中，最小样例必须覆盖 required 字段；涉及 `oneOf`/`anyOf` 时，每条样例必须能解释覆盖的是哪条输入分支。reference 里的 `--input-json` 示例应优先来自 `inputExamples`，不能与 schema 漂移。
 
 如果某些权限、身份或接口只在特定执行路径需要，例如“勾选同步才需要写权限”“上传附件才需要文件接口”，用 `conditionalAuth` 或 `conditionalPermissions` 在 manifest 中声明触发条件，并在 handler 中按同一个条件校验。不要把条件权限只写进 `references/` 或错误提示里。
 
@@ -139,7 +160,9 @@ operation 名称使用 `<module>.<action>`，多级动作可用 `<module>.<objec
 
 ## 输入兼容与归一化
 
-字段名以 `manifest.ts` 的 `inputSchema` 为准。源资料、历史脚本或旧 Skill 里出现多个同义字段时，先选一个 canonical 字段；只有用户明确要求兼容旧输入，或已发布版本已经接受旧字段，才在 manifest 中记录 `deprecatedInputAliases`。
+字段名以 `manifest.ts` 的 `inputSchema` 为准。源资料、历史脚本或旧 Skill 里出现多个同义字段时，先选一个 canonical 字段；只有用户明确要求兼容旧输入，或已发布版本已经接受旧字段，才在 manifest 中记录 `deprecatedInputAliases`。源接口请求体本身是 JSON 对象时，canonical 输入通常就是该请求体的业务字段；不要为了实现方便新增通用 `payload` 层。
+
+缺少参数事实必须结构化登记，不要散落在自然语言里。为每个 operation 维护参数覆盖矩阵（通常写入 `source-manifest.json` 的 `operationImpact[operation].parameterCoverage`），逐项记录源参数到 manifest/schema/handler 的落点和状态：`converted`、`fixed`、`derived`、`deprecatedAlias`、`withheld`、`needs-confirmation`、`not-applicable`。凡是源资料出现但没有进入 `inputSchema` 的参数，都必须有 `fixed`、`derived`、`withheld`、`needs-confirmation` 或 `not-applicable` 原因；不得静默丢弃。最终报告需要单独列出 `needs-confirmation` 参数，例如 `operation.field -> 缺少事实 -> 为什么影响调用`。
 
 归一化只能发生在 `operations/shared.ts` 或清晰命名的 `normalizeInput()` 阶段，且必须早于业务 host 调用。不要在 `host.ts`、HTTP body 拼装或结果处理里偷偷接受旧字段。旧字段和新字段同时出现时必须报结构化校验错误，不能让任一方静默覆盖另一方。
 
@@ -147,6 +170,38 @@ operation 名称使用 `<module>.<action>`，多级动作可用 `<module>.<objec
 
 ## E10 与业务 API
 
+### 登录与凭证契约（生成产物必须遵循）
+
+生成的 E10 业务 Skill 必须遵守登录与凭证红线：
+
+- 登录与会话统一由 `weaver-e10-login` 提供；CLI 场景下的等价入口是 `weaver-work-cli auth ...`，业务 Skill 不得自行实现任何登录流程。
+- 生成的 SKILL.md frontmatter 必须声明 `dependencies:\n  - weaver-e10-login`。
+- 每个请求必须携带 `weaver-e10-login` 返回的三项用户信息参数，缺一不可：
+
+```text
+Cookie: <weaver-e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
+eteamsid: <weaver-e10-login 返回的 ETEAMSID>
+User-Agent: AgentType=<agentType>,IsAgent=true
+```
+
+- Skill 与 reference 文档中若描述了接口请求，必须同时写明上述请求头契约，否则发布门禁会阻断。
+
+### 登录与凭证契约（生成产物必须遵循）
+
+生成的 E10 业务 Skill 必须遵守登录与凭证红线：
+
+- 登录与会话统一由 `weaver-e10-login` 提供；CLI 场景下的等价入口是 `weaver-work-cli auth ...`，业务 Skill 不得自行实现任何登录流程。
+- 生成的 SKILL.md frontmatter 必须声明 `dependencies:\n  - weaver-e10-login`。
+- 每个请求必须携带 `weaver-e10-login` 返回的三项用户信息参数，缺一不可：
+
+```text
+Cookie: <weaver-e10-login 返回的完整原始 Cookie 串>（禁止裁剪/去重/改写）
+eteamsid: <weaver-e10-login 返回的 ETEAMSID>
+User-Agent: AgentType=<agentType>,IsAgent=true
+```
+
+- Skill 与 reference 文档中若描述了接口请求，必须同时写明上述请求头契约，否则发布门禁会阻断。
+
 E10 业务模块必须复用 `src/internal/e10` 的 session、profile 和 request runtime，不直接读取认证文件、Cookie、Keychain 或 legacy auth 目录，也不在业务 `host.ts` 中直接调用 `fetch`。业务 host 只封装本模块需要的请求方法，负责：
 
 - 统一 base URL、headers 和 session 失效处理。
@@ -202,13 +257,19 @@ E10 业务模块必须复用 `src/internal/e10` 的 session、profile 和 reques
 - 高风险写入：`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 中存在。
+- Skill/CLI 一致性：抽取 Skill 和 reference 中的 `run <operation>` 示例，断言 operation 在 manifest 中存在；示例使用的字段必须在 schema 中存在，并优先与 manifest `inputExamples` 对齐。
+- 入参 example 回归：源资料已有 example 时，断言对应 operation manifest 存在 `source-provided` 样例；`inputExamples` 必须是可解析 JSON，对应字段在 `inputSchema.properties` 或 `deprecatedInputAliases` 中，最小样例覆盖 required 字段；仅源资料没有 example 不失败，但必须在 `missingExamples` 或参数覆盖矩阵中形成 WARN/needs-confirmation。
+- 源资料保真：从源 MD 或机器契约中抽取关键字段表、枚举/状态、固定参数、分页口径、错误码、写入确认条件和禁用能力，断言它们分别出现在 `manifest.ts`、handler 请求形状、reference、withheld/disabled 清单或 golden tests 中；不要只测生成产物存在。
+- sourceCoverage 回归：`source-manifest.json` 中业务源文件不能全部落成一条笼统说明；每个 `api-doc`、`existing-skill` 或 `code` 源文件应有 `converted`、`withheld`、`external-only`、`not-applicable` 或 `needs-confirmation` 状态，并能追到 operation/reference 或明确原因。
+- 参数覆盖回归：每个源资料参数都要映射到 `converted`、`fixed`、`derived`、`deprecatedAlias`、`withheld`、`needs-confirmation` 或 `not-applicable`；源资料中存在但产物中没有解释的参数视为失败，参数事实不完整但已登记为 `needs-confirmation` 只作为待用户补充项。
 - 示例安全：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` 兼容性变化必须有测试覆盖迁移或拒绝策略。
 
 验证命令：
 
+每次创建或更新 Skill 后，泛微技能检测是必需步骤；运行 detector 前必须先询问用户是否现在进行 Skill 质检。用户拒绝、未回复或检测器不可用时，不得安装、发布或把生成结果声明为完成。
+
 Windows PowerShell：
 
 ```powershell
@@ -216,7 +277,7 @@ 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
+weaver-work-cli skills validate skills\weaver-e10-MODULE_NAME --json --no-html
 ```
 
 macOS/Linux（bash/zsh）：
@@ -226,5 +287,5 @@ 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
+weaver-work-cli skills validate skills/weaver-e10-MODULE_NAME --json --no-html
 ```

package/skills/weaver-e10-skill-maker/references/module-gap-audit-and-repair.md

@@ -0,0 +1,86 @@
+# 单模块缺口审计与修复
+
+本流程用于用户指定一个已有业务模块，要求检查 Skill/CLI 是否从源资料完整转换，或要求补齐缺少的业务逻辑、参数、示例、reference、测试和 source-manifest 映射。目标是把“看起来能用”的文档型补丁升级为可验证的 contract-first 修复。
+
+## 适用输入
+
+用户至少需要明确目标模块的两个命名之一：
+
+- CLI 命令后缀 `<command>`，例如 `invoice`、`asset`、`meeting`。
+- Skill 后缀 `<skill>`，例如 `yepiaotong`、`ziguanjia`、`huiyi`。
+
+如果只能从现有仓库唯一反查到另一侧命名，可以继续审计并在报告中说明推断依据；如果存在多个候选，先问用户确认。已有 `source-manifest.json`、`docs/<command>.md`、`src/shortcuts/<command>`、`skills/weaver-e10-<skill>` 和用户本轮提供的源资料都视为本次审计输入。
+
+不要自行搜索整个磁盘找源资料。manifest 缺失、`schemaVersion < 2`、`detectionStrength=weak`、`sources` 为空或源路径不可访问时，先标记为“基线不足”；能从现有 CLI/Skill 判定的问题继续审计，涉及源事实的修复必须等用户提供或确认源资料。
+
+## 审计清单
+
+先构建单模块现状清单：
+
+- CLI manifest：`weaver-work-cli <command> schema` 或 `src/shortcuts/<command>/manifest.ts` 中的 operation、`inputSchema`、risk、fixed、权限、`inputExamples`、`missingExamples`。
+- handler/host：registry 是否一一对应，handler 是否使用 schema 字段，host 请求 method/path/query/body/form/file 是否可被测试断言。
+- Skill：`SKILL.md` 路由表、reference 文件、命令示例、禁用边界、写操作确认链说明。
+- Source manifest：`sources`、`sourceChunks`、`operationImpact`、`sourceCoverage`、`artifactBaseline`、参数覆盖矩阵和 notes。
+- 测试：业务测试、source-manifest 基线测试、reference 示例字段测试、写操作 prepare/apply 测试。
+
+然后按这些信号找缺口：
+
+- 基线缺口：manifest 旧版、弱检测、源文件为空、artifactBaseline 缺失或聚合 hash 不一致。
+- 映射缺口：CLI operation 没有 `operationImpact`；`operationImpact` 指向不存在的 operation；sourceChunk 没有映射 operation/reference；业务源文件没有 `sourceCoverage`。
+- 参数缺口：源资料参数没有进入 `inputSchema`，也没有标记为 `fixed`、`derived`、`deprecatedAlias`、`withheld`、`needs-confirmation` 或 `not-applicable`。
+- 示例缺口：源资料已有 example 但 manifest/reference 没迁移；源资料没有 example 但未记录 `missingExamples` 或 `synthetic` 样例。
+- 业务逻辑缺口：源资料里的接口路径、请求方法、固定参数、枚举、默认值、分页、状态流转、权限、ID 解析、写前/写后回查、错误码或返回结构没有落到 schema/handler/reference/test。
+- 写入安全缺口：新增、编辑、删除、导入、同步等真实写入缺少 `prepare -> apply`、`confirm: true`、continuation、指纹校验或 `partial/write_uncertain` 处理。
+- 文档漂移：reference 命令中的 operation 不存在，示例字段不在 schema 中，入口路由指向未实现能力，禁用能力未写清原因。
+
+## 分级规则
+
+把每个缺口分成四类，避免一边修一边猜：
+
+- `repairable`：源资料事实已存在，只是没有迁移或迁移不完整。直接修复，不需要用户重复确认。
+- `needs-confirmation`：缺少接口路径、请求方法、关键字段、类型/必填/枚举、权限边界、幂等键、回查接口、写入确认条件或 example 来源。登记缺口并向用户索取具体事实，不编造实现。
+- `withheld`：源资料有能力，但缺少安全自动化条件、稳定 ID、权限边界或写后回查，不应暴露为 CLI operation。写入 withheld/禁用边界。
+- `baseline-only`：业务能力看不出缺失，但源基线弱、陈旧或不可访问。只修 source-manifest、artifactBaseline、测试和报告，不改业务语义。
+
+同一轮中只要存在 `repairable` 缺口，就先修这些；`needs-confirmation` 只阻断对应 operation，不阻断其它已能证明的修复。遇到 `major` 语义变化，例如删除字段、改变必填、改变写入对象、改变权限或确认链，先给迁移/兼容策略并向用户确认。
+
+## 修复顺序
+
+修复必须按 contract-first 顺序推进：
+
+1. 锁定源事实：读对应 source chunk、源文档标题、接口定义、历史脚本或用户补充说明；记录来源锚点。
+2. 更新 schema：补 `inputSchema`、required、enum、默认值、oneOf/anyOf、fixed、权限、`inputExamples` 或 `missingExamples`。
+3. 更新执行逻辑：补 handler 输入归一化、host 请求形状、固定参数、派生参数、错误映射、分页和写入确认链。
+4. 更新 Skill/reference：命令示例优先引用 manifest `inputExamples`；缺 example 时写 `missingExamples` 和待补事实，不伪装成源样例。
+5. 更新 source-manifest：补 `sourceChunks`、`operationImpact`、`sourceCoverage`、`parameterCoverage`、`artifactBaseline` 和 notes。
+6. 更新测试：至少覆盖 schema 字段、请求形状、reference 示例字段、source-manifest 映射、高风险写入确认链和缺口登记。
+7. 运行验证：业务测试、`weaver-work-cli <command> schema`、`weaver-work-cli skills read weaver-e10-<skill>`、layout 测试；创建或更新 Skill 后按 detector 规则询问是否质检。
+
+如果发现源资料中有底层接口但当前没有 operation，先判断是否能形成稳定、业务友好的高层 operation。能实现时补 CLI operation、reference 和测试；不能实现时写入 withheld，不要把原始接口路径直接暴露给 Agent。
+
+## 参数修复规则
+
+补参数时逐项判断归属：
+
+- 用户必须提供或 Agent 可从用户意图取得的字段，进入 `inputSchema`。
+- 源接口固定值，进入 `fixed` 或 handler 常量，不暴露给 Agent。
+- 可由当前用户、前置查询、名称解析、prepare continuation 或上下文推导的字段，标为 `derived` 并测试解析失败路径。
+- 旧 Skill/历史脚本字段需要兼容时，进入 `deprecatedInputAliases`，并测试新旧字段冲突。
+- 源资料提到但缺少类型、必填、枚举或来源时，标为 `needs-confirmation`，最终报告列出具体问题。
+- 接口内部字段、返回字段或展示字段，标为 `not-applicable`。
+
+严禁为了让业务逻辑“跑起来”把不确定字段放进 `additionalProperties: true`。除非已有模块明确是通用 datajson 透传能力，否则业务 operation 的顶层 `inputSchema.additionalProperties` 必须为 `false`。
+
+## 审计报告格式
+
+单模块扫描完成后，先输出或保留一份结构化报告，再动手修复。报告至少包含：
+
+- `module` / `skill` / 源资料边界。
+- 基线状态：schemaVersion、detectionStrength、sources、sourceChunks、operationImpact、sourceCoverage、artifactBaseline。
+- 缺口列表：`operation -> gapType -> severity -> evidence -> proposedAction`。
+- 可自动修复项：源事实位置、要改的 schema/handler/reference/test/manifest。
+- 待用户补充项：缺少哪个 operation 的哪个事实，以及为什么阻断。
+- 暂缓/禁用项：源资料有但不暴露的能力和原因。
+- 验证计划：要跑的测试和 detector 状态。
+
+最终回复必须区分“已修复”和“仍待补充”。不要把已登记 `needs-confirmation` 的 operation 当成完成；也不要因为存在待补项，就忽略已经能修复的其它缺口。