---
name: delivery
displayName: 交付物格式化与汇总
description: 对编码阶段增量积累的变更记录、代码审查阶段产出的技术参考文档和评审报告进行最终格式化、完整性校验和交付展示。
triggers: ["生成交付物", "交付", "/deliver", "格式化变更清单"]
autoTrigger: true
version: '1.0.2'
---

# 交付物格式化与汇总

## 技能目标

对编码过程中增量维护的变更记录文档、代码审查阶段产出的技术参考文档和质量结论文档进行最终格式化和完整性校验，形成正式的交付包。

**本技能不从零生成文档**——变更记录在编码阶段逐条积累，技术参考文档和代码评审报告在 B3 产出/定稿。本技能负责"最后一公里"的格式化和校验。

## 核心原则

1. **格式化而非重建**：基于已有的增量记录做格式整理，不重新阅读全部代码
2. **完整性校验**：将变更记录与 `git diff main...HEAD` 对账，确保无遗漏
3. **高风险标注**：确认所有高风险变更已在"需关注"中列出
4. **需求关联**：所有交付物必须关联需求编号
5. **齐套后交付**：三类正式交付文档齐套且通过检查后，才允许展示“交付物已就绪”
6. **分工明确，避免复述**：每份交付文档只记录自己的职责内容，不复制其他文档的大段信息

## 正式交付文档清单

| 交付物 | 路径 | 产出阶段 |
|--------|------|---------|
| 变更清单 | `docs/delivery/SV-xxxxx-changelist.md` | B1 初始化，B2 增量维护，B3 定稿 |
| 技术参考文档 | `docs/delivery/SV-xxxxx-tech-ref.md` | B3 代码审查与对齐阶段产出 |
| 代码评审报告 | `docs/delivery/SV-xxxxx-review-report.md` | B3 代码审查、验证循环和安全审计收口后定稿 |

> `docs/delivery/.state/SV-xxxxx-verification.json` 是 B3 验证循环的**机器状态文件**，用于断点续验和重验计划，不属于正式交付文档，不在 B4 交付展示中列为交付物。

## 文档分工边界

| 文档 | 只记录 | 不记录 |
|------|--------|--------|
| 变更清单 | 文件级事实、变更类型、接口变更、高风险项 | 业务背景长文、测试步骤、评审过程 |
| 技术参考文档 | 面向测试的验证路径、接口/数据流、配置和注意事项 | 完整 diff、完整变更文件列表、评审问题清单 |
| 代码评审报告 | 问题、风险、对齐结论、V1-V5 最终验证摘要、安全审计结论、Critical 闭环状态、交付判定 | 大段功能说明、重复的文件级变更清单、完整命令输出、完整测试日志、完整 diff |

机器状态文件只保存结构化字段（当前迭代、维度状态、失败摘要、日志引用、重验计划），不写叙述性长文；如果需要引用，只写路径，不复制内容。

如果需要引用其他文档，只写路径和章节，不复制正文。

## 工作流程

### 第一步：变更清单定稿

输入：编码阶段积累的 `docs/delivery/SV-xxxxx-changelist.md`

1. 读取变更记录文档中的所有条目
2. 执行 `git diff main...HEAD --name-status` 获取实际变更文件列表
3. 对账校验：
   - 记录中的文件是否与 diff 完全匹配
   - 遗漏的文件 → 补充记录
   - 多余的记录 → 确认后移除
4. 按层级重新分组（新增/修改/删除），统一格式
5. 确认"需关注：高风险变更"部分完整

定稿格式：

```markdown
# 变更清单 SV-xxxxx

## 新增
- [文件路径] — [功能说明]

## 修改
- [文件路径] — [变更说明]

## 删除
- [文件路径] — [删除原因]

## 需关注：高风险变更
- [文件#方法名] — [说明：被什么替代，或为什么移除/注释]
```

### 第二步：技术参考文档校验

输入：代码审查阶段产出的 `docs/delivery/SV-xxxxx-tech-ref.md`

1. 检查文档结构是否完整（6 个标准章节）
2. 检查接口清单是否与变更清单中的接口变更一致
3. 补齐缺失章节（如无配置变更则标注"无"）

### 第三步：交付文档齐套检查

检查三类正式交付文档是否全部存在，并验证需求编号一致：

1. 缺少 `changelist.md`：回到 B2/B3，基于已有任务记录或 diff 补齐变更清单，并重新对账
2. 缺少 `tech-ref.md`：回到 B3，从变更清单和评审结果生成技术参考文档
3. 缺少 `review-report.md`：回到 B3，重新汇总代码评审、V1-V5 验证摘要、安全审计结论与交付判定
4. 若 `review-report.md` 中缺少验证摘要：读取 `docs/delivery/.state/SV-xxxxx-verification.json` 生成最终摘要；若状态文件不存在或状态不完整，回到 B3 重新执行验证循环

缺失项补齐前，不得进入交付展示。

### 第四步：交付展示

展示所有交付物摘要，让用户选择后续操作：
1. **提交 PR**：自动填写 PR 标题和描述，附变更清单和技术参考文档
2. **本地合并**：将 feature 分支合并到主分支
3. **保留分支**：不做合并操作

## 文件保存位置

- 变更清单：`docs/delivery/SV-xxxxx-changelist.md`
- 技术参考文档：`docs/delivery/SV-xxxxx-tech-ref.md`
- 代码评审报告：`docs/delivery/SV-xxxxx-review-report.md`
- 机器状态（非交付物）：`docs/delivery/.state/SV-xxxxx-verification.json`

## 补救场景

当通过 `/deliver` 独立触发时（未经 `/code` 正常流程），本技能回退到从 git diff 重新生成模式：
1. 从 `git diff main...HEAD` 提取所有变更，生成变更清单
2. 读取变更文件内容，生成技术参考文档
3. 基于 diff、变更清单和可用技术方案生成补救版代码评审报告；无法实际确认的构建/测试/性能/规范/安全状态，必须在报告中标注"未验证/需人工执行"，不得写成 PASS
4. 提示用户：此模式下文档精度可能低于正常流程中的增量记录