# 单模块缺口审计与修复

本流程用于用户指定一个已有业务模块，要求检查 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`、`outputSchema`、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`。
- 输出缺口：源资料响应字段、出参或返回示例没有进入 `outputSchema`，也没有在 `operationImpact` 的 `outputFields` / `outputSchemaCoverage` / `missingOutputSchema` 中说明；只用 `result`、`data`、`raw` 或通用 `object` 包裹返回值视为未逐字段转换。
- 示例缺口：源资料已有 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`、`outputSchema`、required、enum、默认值、oneOf/anyOf、fixed、权限、`inputExamples`、`missingExamples`、`missingOutputSchema`。
3. 更新执行逻辑：补 handler 输入归一化、host 请求形状、固定参数、派生参数、错误映射、分页和写入确认链。
4. 更新 Skill/reference：命令示例优先引用 manifest `inputExamples`；缺 example 时写 `missingExamples` 和待补事实，不伪装成源样例。
5. 更新 source-manifest：补 `sourceChunks`、`operationImpact`、`sourceCoverage`、`parameterCoverage`、`outputFields` / `outputSchemaCoverage`、`artifactBaseline` 和 notes。
6. 更新测试：至少覆盖 schema 字段、输出字段 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`。

## 输出修复规则

补返回值时逐项判断归属：

- CLI 成功 envelope 外层字段固定为 `{schemaVersion, ok, operation, data, meta, warnings}`，`outputSchema` 只描述其中的 `data`。
- handler 已经归一化的字段，以 CLI 实际返回字段为准，并把源接口字段来源写入 description、reference 或 `operationImpact.outputFields`。
- 服务端原始响应需要保留时，可暴露 `result`、`raw` 等字段，但这只能作为附加调试/追溯字段；仍要逐项声明已知稳定的业务字段。
- 源资料响应字段表中的数组必须声明 `items`；嵌套对象必须声明 `properties`；确定必返字段必须进入 `required`；枚举、状态码、分页结束标记和金额/时间格式能确认时要写入 schema。
- 源资料只有响应示例时，从示例抽取稳定字段并标注示例来源；缺少类型、必填或嵌套结构时，在 `missingOutputSchema` 或 `outputSchemaCoverage` 中标记 `needs-confirmation`。
- 不要为了规避不确定性把整个输出写成 `additionalProperties: true`。只有明确的原始服务端透传字段可以 `additionalProperties: true`，且必须和稳定业务字段分开。

## 审计报告格式

单模块扫描完成后，先输出或保留一份结构化报告，再动手修复。报告至少包含：

- `module` / `skill` / 源资料边界。
- 基线状态：schemaVersion、detectionStrength、sources、sourceChunks、operationImpact、sourceCoverage、artifactBaseline。
- 缺口列表：`operation -> gapType -> severity -> evidence -> proposedAction`。
- 可自动修复项：源事实位置、要改的 schema/handler/reference/test/manifest。
- 待用户补充项：缺少哪个 operation 的哪个事实，以及为什么阻断。
- 暂缓/禁用项：源资料有但不暴露的能力和原因。
- 验证计划：要跑的测试和 detector 状态。

最终回复必须区分“已修复”和“仍待补充”。不要把已登记 `needs-confirmation` 的 operation 当成完成；也不要因为存在待补项，就忽略已经能修复的其它缺口。