docs: add organized feedback skill design spec
This commit is contained in:
@@ -0,0 +1,160 @@
|
||||
# 意见整理 Skill 设计（v1）
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
本设计用于新增一个“意见整理”Skill，将 `gitea-pr-review fetch` 产出的 PR Review Markdown 中的非结构化评论，整理为结构化的 `Organized Feedback` 列表，供后续开发决策使用。
|
||||
|
||||
目标：
|
||||
- 对混杂的审阅意见做统一分类与归并。
|
||||
- 允许“拆分或合并”策略由 agent 自主决定。
|
||||
- 强制执行覆盖审计，保证不遗漏任何原始 `Comment/Reply`。
|
||||
- 最终输出写入用户指定路径。
|
||||
|
||||
约束：
|
||||
- 当前文档版本规则固定为 `v1`，不做版本 bump。
|
||||
|
||||
## 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 仅用于交互，不写最终文件。
|
||||
- 必须由用户指定输出路径。
|
||||
Reference in New Issue
Block a user