# AI Review 工作流路线图 · 2026-05-11

> 基于 [`ai-review-stats-20260511.md`](./ai-review-stats-20260511.md) 真实数据，对 issue [#259](http://43.130.59.228/FFAIWorkspace/workspace/issues/259) 原始三层方案做的精炼 + 子工单拆分。
> 工单 TODO 第 5、6 项「基于报告 refine 方案 + 立项实施」的产出物。

## 1. 盘点数据 5 条关键事实

| # | 事实 | 决策影响 |
|---|---|---|
| 1 | 109/222 PR (49%) 跑过 AI Review，共 212 条评论 | 影响面够大，值得系统性优化 |
| 2 | **47% 跑 ≥2 次 review**，单 PR 最高 10 次（#247） | 触发收敛 + state 去重收益面证实 |
| 3 | verdict 分布：67% pass / 30% pass_with_risk / **2% block** | 硬阻断极少 → review **指出真问题的能力被分级稀释**，绝大多数 finding 被归入 risk（无强制反馈通道） |
| 4 | DRY RUN 期 100%，verdict=block 出现 3 次但未实际阻断合并 | #171 转正前必须做人工抽样验证这 3 次 block 的准确率 |
| 5 | 重复指控只检出 2 组（远低于 PR #247 复查时的"4 项 × 5 次"印象） | **finding 文本指纹失效**：60 字 hash 无法稳定识别"同一问题"，AI 换措辞就算两条 |

## 2. 数据驱动的优先级重排

工单原方案 11 项，按真实数据重新打分（**优先级 = 数据信号强度 × 实现难度倒数**）：

| Tier | 项 | 工单原优先级 | 数据后优先级 | 重排理由 |
|---|---|---|---|---|
| 3 | D1 触发收敛 | 高 | ✅ **本 PR 已做** | 47% PR 跑 ≥2 次直接验证 |
| 3 | D2 State header 去重 | 高 | ✅ **本 PR 已做** | PR #247 跑 10 次实证 |
| 3 | D3 hard/soft finding 分级 | 中 | ✅ 历史已做 | PR #297 schema 化 |
| 3 | D4 退出 DRY RUN | 中 | **中** | 等 D1+D2 上线 2-3 天 + 人工抽样 20 条 |
| 2 | C1 contract-check pre-push | 中 | ✅ 历史已做 | `.githooks/pre-push:23` |
| 2 | C2 simplify 接 pre-push | 中 | **不做** | simplify 是交互式 skill，硬塞 pre-push 体验差；其功能被 C3 覆盖（ai-review-local 含 quality 维度）|
| 2 | C3 ai-review-local 接 pre-push | 中 | **高** | 本 PR 触发收敛把"PR 前自检"变刚需；脚本（#301）已存在 |
| 2 | C4 `push.ai_check_sha` 防重跑 | 低 | **中** | 配合 C3，避免同 HEAD 重复跑 AI |
| 1 | B1 API-doc drift detector | 低 | **高** | 盘点里 "contract 文档漂移" 是高频 risk（如 PR #247 五次 review 都包含 07-api.md 缺端点） |
| 1 | B4 Migration count hook | 低 | **待验证** | CLAUDE.md 已规定但 `.githooks/pre-commit` 没看到实装，需先确认现状再决定补不补 |
| 1 | B2 Enum-extension consumer check | 低 | **低** | 盘点里没出现这类 finding；保留待未来 |
| 1 | B3 PR-topic 跨模块告警 | 低 | **低** | 盘点里 sugg 偶尔提（PR #247 1 次），频次不足以做 hook |

## 3. 数据带出的新发现（不在工单原方案里）

### 新发现 1：finding 文本指纹失效 → 需要 stable_finding_id

**症状**：盘点用 (category, message 前 60 字) 模糊去重，重复指控只检出 2 组，但 PR #247 复查讨论提到"反复指出同 4 项"——说明 AI **换措辞**就让 fingerprint 失效。

**根因**：schema 里 finding 没有稳定 ID，每次 review 都是"新写"。

**新工单建议**：
- 标题：`[ai-review] finding 加 stable_id 让 state 去重真正生效`
- 方案：schema 加 `stable_id` 字段，prompt 要求 claude 对"同类问题"复用上轮 ID（state context 里给历史 ID 列表）
- 价值：解锁 state header 真正去重 + 后续盘点重复率统计准确

### 新发现 2：verdict 区分度低 → hard/should-fix/risk/suggestion 四级

**症状**：97% verdict 是 pass / pass_with_risk，2% block —— **现实中绝大部分 PR 没有"硬阻断"问题**，但仍有不少 risk 需要修。

**根因**：hard-rules-block 模式 prompt 把门槛设得太严（只算契约缺失、SQL 注入等），让 verdict 失去区分度。risk 没有强制反馈通道，等同于"提了等于没提"。

**新工单建议**：
- 标题：`[ai-review] verdict 加 should_fix 级别 + risk 进 check status`
- 方案：四级 verdict（pass / should_fix / needs_fix / block），`should_fix` 进 PR check status 但不 block 合并
- 价值：让 AI Review 的 risk 真正能产生压力（作者会主动响应）

## 4. 衍生工单（merge 后按顺序执行）

#259 本 PR merge 后剩余事项已拆为 3 个独立工单，每个 ≤ 3 件，符合 weekly-retro 闭环节奏：

| 工单 | 标题 | 前置 | 时间 |
|---|---|---|---|
| **#315** | [ai-review] 观察期验证 + auto-eval 复跑 | #259 merge | merge 后 3-5 天 |
| **#316** | [ai-review] D4 退出 DRY RUN 转正 → required check | #315 决策启动 | 跟 #315 间隔 1-2 天 |
| **#317** | [ai-review] Tier 1 hooks warn → block 渐进升级 | #316 完成 + 1-2 周累积数据 | merge 后 2-4 周 |

### 已在本 PR 中完成

- A1 盘点脚本 + 报告 / A2 路线图文档（本文）
- D1 触发收敛 / D2 State header / D3 hard/soft 分级（PR #297 历史）
- B1 / B2 / B3 / B4 全部 Tier 1 hooks 落地（warn 模式 + B4 block）
- C3 + C4 pre-push 自检闭环
- 新发现 1 finding stable_id（schema + prompt + state）
- 新发现 2 verdict should_fix（schema + 5 处同步）
- D4-prep auto-eval 脚本（替代人工抽样，综合分 72.5% 达标）

### 关联

- #171 `[ai-review] dry-run 转正评估` — 由 #316 收尾

## 5. 完成度跟踪

| Tier | 总数 | 本 PR 后 | 剩余 |
|---|---|---|---|
| Tier 3 PR-time | 4 | 3 ✅ + D4 自动评估已落 / 综合分 72.5% 已达标 | D4 收尾（去 DRY RUN + Gitea required check）|
| Tier 2 Pre-push | 4 | 3 ✅ + C2 不做（理由见上） | 0 |
| Tier 1 Pre-commit | 4 | 4 ✅（B1 / B2 / B3 / B4） | 0 |
| 数据盘点 | 6 项 TODO | 6 ✅ | 0 |
| 新发现 1 (finding stable_id) | 1 | ✅ schema + prompt + runner state | 0 |
| 新发现 2 (verdict should_fix 四级) | 1 | ✅ schema + prompt + runner emoji + stats buckets | 0 |
| **总计** | **20** | **20 (100%)** | **D4 收尾（脚本 + 1 次手工 Gitea 设置）**|

> **D4-prep 路径换装**：原方案"人工抽样 20 条 CSV 标注"违反 AI-first 原则，
> 改为 `scripts/ops/ai-review-auto-eval.py` 自动评估，0 人工。当前综合分 **72.5%**
> 已达 70% 门槛（采纳率 99.5% / 自洽率 100% / block 合理性 50% / 漏检率 proxy 高估）。
>
> **D4 收尾的剩余操作**（AI 都能做，等 PR merge 后再启动）：
> 1. `.gitea/workflows/ai-review.yml` 删 `AI_REVIEW_DRY_RUN: '1'` 那行 — AI 改
> 2. Gitea web → 仓库 Settings → Branches → develop 保护规则 → 必需检查加 `ai-review` — **必须 web UI 手工点（API 走 Gitea 也行但繁琐），AI 不做**
> 3. 同步 `docs/ops/02-gitea-config.md` + `docs/standards/05-development-workflow.md` 去 DRY RUN 备注 — AI 改
> 4. 关闭 #259 + #171
>
> 建议先把 D4 收尾留到 **本 PR merge 后 2-3 天**，跑增量 auto-eval 看新触发策略 + state header 的真实效果再启动；如果指标稳定就直接收尾。

## 6. 后续路径

1. **本 PR merge → 2-3 天观测窗口**：用 ai-review-stats.py `--since-days 3` 跑增量盘点，看 review 次数分布是否显著左移（≥3 次 review 的 PR 应该 ≈0）
2. **P1 启动**：把上述 3 个子工单创建到 Gitea，按盘点周期推
3. **#171 转正评估**：依赖 P1.3 抽样标注；达标后 workflow YAML 去掉 `AI_REVIEW_DRY_RUN: '1'` + Gitea 必需检查里加 `ai-review`
4. **退役 #259**：本工单作为"系统盘点"任务，P1 全部完成后可关闭；P2 衍生为独立 issue 长期跟踪

---

_Generated as part of #259 deliverable. 跟踪 [#259](http://43.130.59.228/FFAIWorkspace/workspace/issues/259) / [#171](http://43.130.59.228/FFAIWorkspace/workspace/issues/171)._