# 意见整理 Skill 设计

## 1. 背景与目标

本设计用于新增一个“意见整理”Skill，将 `gitea-pr-review fetch` 产出的 PR Review Markdown 中的非结构化评论，整理为结构化的 `Organized Feedback` 列表，供后续开发决策使用。

目标：
- 对混杂的审阅意见做统一分类与归并。
- 允许“拆分或合并”策略由 agent 自主决定。
- 强制执行覆盖审计，保证不遗漏任何原始 `Comment/Reply`。
- 最终输出写入用户指定路径。

## 2. 范围

本 Skill 仅负责：
- 读取单份 PR Review Markdown。
- 产出单份 Organized Feedback Markdown 文档。
- 在交互中展示覆盖审计信息。

本 Skill 不负责：
- 直接修改代码。
- 自动发起二次请求获取更多 PR 数据。

## 3. 输入与输出

### 3.1 输入

必需输入：
- 一份符合 `gitea-pr-review` 输出结构的 Markdown（含 `Review/Comment/Reply`）。
- 用户指定的输出文件路径（用于写入 Organized Feedback 文档）。

若用户未提供输出路径，Skill 必须先询问并暂停。

### 3.2 输出

最终输出文档（写入用户指定路径）包含：
- `## Organized Feedback`
- `## Unknown Items`（仅存在 unknown 时出现）

最终输出文档不包含：
- `Coverage Audit`（仅在交互过程展示，不落盘）。

## 4. 分类体系

### 4.1 主类型

- `question`：请求解释/澄清，不直接要求修改。
- `supplement`：补充背景信息，不构成明确修改请求。
- `request-for-change`：要求实现发生改变。
- `unknown`：证据不足或语义冲突，且无法通过上下文消歧。

默认倾向：尽量避免 `unknown`，仅在迫不得已时使用。

### 4.2 RFC 二级分类

仅当 `Type=request-for-change` 时填写：

`Change-Scope`：
- `local`
- `implement`
- `api-change`
- `requirement-change`

`Necessity`：
- `nice-to-have`
- `should-fix`
- `must-fix`

## 5. 处理流程

### 5.1 阶段 A：预处理

- 扫描输入文档中的全部 `Comment/Reply`。
- 为每条原始意见建立唯一引用键（例如 `R1.C2`、`R1.C2.P1`）。
- 建立 `All-Source-Refs` 集合。

### 5.2 阶段 B：归类与归并

- agent 可自主选择粒度：
  - 拆分：一条原始意见拆成多条整理意见。
  - 合并：多条原始意见合并成一条整理意见。
- 允许一条原始意见被多条整理意见引用（多对多）。
- 若同一原始意见同时包含提问与改动请求，优先拆分为独立条目。

### 5.3 阶段 C：覆盖审计（交互展示）

- 计算 `Covered-Source-Refs`（被至少一个整理意见引用）。
- 计算差集 `Missing-Source-Refs = All - Covered`。
- 若差集非空，强制补洞并重复审计，直至差集为空。
- 审计信息在交互中展示，不写入输出文档。

### 5.4 阶段 D：unknown 反思机制

- 只要存在 `unknown`（>=1），必须执行一次反思复判。
- 复判后仍无法归类，方可保留为 `unknown`。
- 若 `unknown` 绝对数量 `> 3`：
  - 必须在交互中明确提示“审阅质量或上下文完整性存在风险”。
  - 必须请求用户许可；未获许可不得写最终输出文件。

## 6. 输出格式

### 6.1 Organized Feedback 条目格式

每条意见包含：
- `Type`
- `Change-Scope`（RFC 必填）
- `Necessity`（RFC 必填）
- `Summary`（1-2 句）
- `Rationale`（分类依据；unknown 时写阻塞原因）
- `Source-Refs`（引用的原始键）
- `Raw-Excerpts`（精简原文摘录）

### 6.2 Unknown Items

当存在 unknown 时，文档追加 `## Unknown Items`，每条写明：
- 无法归类的原因。
- 解除不确定性所需的最小补充信息。

## 7. 错误处理

- 输入结构不可识别：报错并停止；提示已识别段落数与示例片段。
- 输出路径缺失：询问用户并暂停。
- 输出目录不存在：请求确认后创建，或要求用户更换路径。
- 输出不可写：报错并给出替代路径建议。
- 覆盖审计始终无法闭合：停止写文件并在交互中报告未覆盖键。

## 8. 组件边界与职责

- Parser：提取 Review/Comment/Reply 与引用键。
- Classifier：完成类型判定、RFC 细分与必要性判定。
- Grouper：执行拆分/合并并维持 `Source-Refs` 映射。
- Auditor：执行覆盖审计与补洞循环。
- Writer：按固定模板写入输出 Markdown。

各组件通过显式结构化中间数据通信，避免隐式状态耦合。

## 9. 测试与验收标准

最小验收标准：
- 所有原始 `Comment/Reply` 均被至少一条输出意见覆盖。
- 输出文档不包含 Coverage Audit 区块。
- 当出现 unknown 时，必有反思复判步骤。
- 当 unknown 数量 > 3 时，无用户许可不得落盘。
- RFC 条目完整填写 `Change-Scope` 与 `Necessity`。

建议测试集：
- 纯 question 样例。
- question + RFC 混合样例（验证拆分）。
- 多线程同主题样例（验证合并）。
- 高歧义样例（触发 unknown 与用户许可门禁）。

## 10. 决策记录

- 采用纯 Prompt Skill（不引入脚本）。
- 采用“两阶段归类 + 覆盖审计补洞”策略。
- Coverage Audit 仅用于交互，不写最终文件。
- 必须由用户指定输出路径。