Vibe review

Vibe Review

接收项目代码 + .vibe/doc/ 下全部 spec 文档，对构建产出做全面审计。发现 bug、检测偏离 spec、安全性漏洞、假代码残留：修复后重审，直到收敛。

核心铁律：

1. Agent 分离：build 的 agent 永不参与 review。每个审查者是独立子 agent，fresh context
2. 预设代码有罪：对抗性审查，证明不了清白就记录失败报告
3. 收敛式修复：修→审→修→审，直到没有新发现

---

三个强度级别

你在 Phase 4 REPORT 看到发现后选择，或在启动时预设：

级别	触发	审查范围	修复方式
Quick	你说"快速检查"	假代码扫描 + 安全 CRITICAL + spec drift 检测	只报告不修复。~30s
Standard	默认	八路并行 + 辩论 + 收敛循环	你选修 → 收敛修复。~10-15min
Deep	涉及认证/支付/数据删除/用户敏感数据	Standard + 全量回归测试 + E2E	全量收敛修复。~30-60min

---

七阶段

门禁总览

#	Phase	门禁条件	你参与
1	SCAN	必入	零
2	RESEARCH	必入	零
3	AUDIT	必入	零
4	DEBATE	必入	零
5	REPORT	必入	选择修哪些 + 确认强度级别
6	CONVERGE	REPORT 确认通过	仅在达上限时介入
7	SATISFACTION GATE	必入	确认
8	HANDOFF	满意度门禁通过	确认

---

Phase 1：SCAN

门禁：无（必入）

流程：

1. 显式 Read .vibe/doc/REQUIREMENTS.md、.vibe/doc/ARCHITECTURE.md、.vibe/doc/BUILD_LOG.md
2. 扫描代码库全量文件
3. 生成代码地图：

维度	内容
文件清单	所有源码文件（排除 node_modules / .git / dist）
路由清单	每个路由 + 对应文件 + 是否有认证中间件
组件清单	每个组件 + 文件路径 + 行数
依赖清单	package.json 依赖 + 是否在 ARCHITECTURE.md 技术选型表中
BUILD_LOG 遗留	上次构建留下的已知问题和偏离记录

4. 交叉对照：spec 声明的 vs 实际存在的：

ARCHITECTURE.md §4 声明了 5 个路由 → 实际找到 6 个
  → 多出来的 /api/debug 未在 spec 中出现
  → 标记为 uncovered（DevSpec 四维检测）

输出：代码地图（内部，供审查者使用）

---

Phase 2：RESEARCH（避免造轮子）

门禁：无（必入）

流程：理解了审查范围之后，搜索社区是否已有现成的审查/扫描工具。

搜索方向：

搜索内容	方法
现成扫描工具	rlsgate、DoneCheck、Groundtruth、AI-SLOP Detector 是否可直接用
OWASP 安全扫描	npm audit、安全扫描 skill
假代码检测工具	grep 正则、pre-commit hook 模板
任何 vibe-review 能直接调用的 DevOps/QA skill	npx skills add 搜索相关 skill

纪律：

• 有现成工具 → 优先调用而非在 skill 里重写检测逻辑
• rlsgate 能覆盖 RLS 检查 → 直接跑 rlsgate scan，不在 AUDIT 中重复实现
• DoneCheck 能扫假代码 → 直接跑，结果并入 AUDIT
• 搜不到 → 记录，审查者自己实现检测逻辑

输出：搜索结论 + 被纳入使用的工具清单 + 工具运行结果

---

Phase 3：AUDIT（八路并行审查）

每个审查者是独立子 agent，context: fork（fresh context），只读权限。

Quick 级别：只运行审查者 D（代码质检员）的假代码扫描 + C（安全审计员）的 CRITICAL 项。 Standard/Deep 级别：八路全开。

审查者 A：Spec 对齐官

角色：建设性审查：代码有没有实现 spec 说要做的事？

检查清单：

#	检查项	方法
A1	P0 功能覆盖	逐条对照 REQUIREMENTS.md §2，grep 搜索关键词确认有对应实现
A2	路由匹配	逐条对照 ARCHITECTURE.md §4 路由表，确认每个路由文件存在且路径正确
A3	组件匹配	逐条对照 ARCHITECTURE.md §4 组件树，确认每个组件文件存在
A4	数据模型对齐	逐表对照 ARCHITECTURE.md §3，确认数据库 schema 字段匹配
A5	技术选型对齐	ARCHITECTURE.md §2 选型表 → 实际 package.json / 配置文件
A6	Spec drift	gap（改代码没改 spec）/ stale（spec 指向已删除文件）/ uncovered（新文件无 spec）/ orphaned（spec 声明不存在的文件）
A7	不多做	检查是否有 REQUIREMENTS.md 和 ARCHITECTURE.md 都没提到的功能/路由/组件/依赖

输出：对齐报告（每个 P0 ✅/❌ + drift 清单 + 多做项清单）

审查者 B：Bug 猎手

角色：建设性审查：代码里有什么逻辑漏洞？

检查清单：

#	检查项	方法
B1	空状态	每个数据展示组件，数据为空的场景处理了吗？
B2	加载态	每个异步操作有 loading 状态吗？
B3	错误态	每个可能失败的操作有错误处理吗？catch 块不是空的？
B4	边界条件	输入为 0、负数、超长字符串、特殊字符 → 会发生什么？
B5	null/undefined	链式访问 data.xxx.yyy 前有 null check 吗？
B6	N+1 查询	循环内有数据库调用吗？
B7	资源泄漏	文件句柄、事件监听器、定时器有没有清理？
B8	竞态条件	快速连续点击提交按钮会创建重复数据吗？
B9	类型安全	npx tsc --noEmit 通过吗？有 any 类型吗？

输出：Bug 清单（每个 bug: file:line + 触发条件 + 预期 vs 实际 + 严重度）

审查者 C：安全审计员

角色：建设性审查：代码有没有安全漏洞？

检查清单：

#	检查项	方法
C1	认证覆盖	每个路由是否被认证中间件覆盖？有没有漏网的路由？
C2	授权隔离	A 用户能否访问 B 用户的数据？Row Level Security 启用了吗？
C3	注入检测	SQL 拼接？命令拼接？eval()？ dangerouslySetInnerHTML？
C4	输入校验	每个 API 接口对输入做了类型+范围+格式校验吗？
C5	密钥硬编码	grep sk-|api_key|secret|password\s*= → 0 结果
C6	敏感文件	.env 在 .gitignore 里吗？有没有 .env 文件被 git track？
C7	依赖漏洞	npm audit 或同等检查
C8	文件上传安全	有文件类型白名单吗？有文件大小限制吗？文件名有 sanitize 吗？
C9	HTTPS/HSTS	生产环境是否强制 HTTPS？

输出：安全报告（每个漏洞: file:line + 攻击路径 + CVSS 严重度 + 修复建议）

审查者 D：代码质检员

角色：建设性审查：代码质量达标吗？

检查清单：

#	检查项	方法
D1	假代码扫描（8 种模式）	占位者/空函数/幻觉 import/拖延语言/吞错/缩水/承诺者/绕行安全
D2	TypeScript strict	tsconfig.json strict: true 且编译无错误
D3	命名一致性	组件 PascalCase？函数 camelCase？文件命名统一？
D4	文件大小	单文件是否过大？一眼看去能在同一个文件里找到你要找的东西吗？→ 建议拆分
D5	重复代码	跨文件搜索：有没有明显重复的代码块？复制粘贴超过一次就值得提取
D6	注释质量	grep TODO|FIXME|HACK → 0 结果（除非 BUILD_LOG 明确记录）
D7	BUILD_LOG 遗留追踪	BUILD_LOG 里标记的遗留问题，解决了吗？偏离记录，代码最终收敛了吗？

输出：质量报告（每个问题: file:line + 规则引用 + 建议）

审查者 E：架构守卫

角色：建设性审查：代码架构是否偏离了 ARCHITECTURE.md 的设计？

检查清单：

#	检查项	方法
E1	依赖合规	每个 package.json 依赖能追溯到 ARCHITECTURE.md §2 选型表吗？
E2	目录结构	实际目录树 vs ARCHITECTURE.md §5 声明
E3	数据流	数据从 DB → API → 组件的流向是否和架构图一致？
E4	抽象层级	有没有跨层调用（如组件直接访问数据库而不通过 API）？
E5	未授权模式	有没有引入 spec 里没提到的设计模式或框架特性？

输出：架构合规报告

审查者 F：对抗审查者（Adversarial Auditor）

角色：预设代码有罪，直到证明清白。和其他五路审查者不同：对抗审查者不参照 spec，不假定代码"应该是对的"。它主动寻找代码会在什么条件下崩溃、被绕过、产生错误结果。

参考：完整对手攻击模式清单见 references/adversary-playbook.md，安全审查清单见 references/security-checklist.md，假代码模式清单见 references/fake-code-patterns.md。

方法论：

对于代码库的每个模块，依次攻击：

1. 输入攻击
   "如果我把 null / undefined / 空字符串 / 超长字符串 / emoji / SQL片段 /
    -1 / 0 / Infinity / NaN 传给这个函数，会发生什么？"

2. 状态攻击
   "如果用户快速连续点 3 次提交按钮？"
   "如果用户在登录过期后继续操作？"
   "如果用户在操作中途切换账号？"

3. 顺序攻击
   "如果先调 B 再调 A（而不是 spec 规定的 A → B）？"
   "如果跳过第一步直接进第二步？"

4. 并发攻击
   "如果两个请求同时修改同一条数据？"
   "如果一个请求在读、另一个在写？"

5. 权限攻击
   "如果普通用户尝试访问管理接口？"
   "如果未登录用户直接访问 API？"
   "如果能猜到另一个用户的 ID？"

失败报告格式（每条必须带可复现的攻击路径）：

## 失败报告 #F03: 空状态处理存在崩溃风险

**声称**: SPEC §2 P0 "数据为空时显示占位符"
**攻击**: 
  1. 清空数据库中的 shipments 表
  2. 访问 /dashboard 页面
  3. API 返回 `{ data: null }` 而非 `{ data: [] }`
**证据**: `app/dashboard/page.tsx:23`：`data.map(...)` 未做 null check
**崩溃**: `TypeError: Cannot read property 'map' of null` → 页面白屏
**影响**: CRITICAL：用户首次使用时必然触发（新用户数据为空）
**结论**: 空状态处理不完整。需要防御性编程：`data?.map(...) ?? <EmptyState />`

纪律：

• 每条失败报告必须带实际可复现的攻击步骤：不接受"可能""也许""理论上"
• 必须实际尝试攻击（运行代码、发送请求、检查响应），不靠推测
• 找不到漏洞就坦白"未发现可利用漏洞"：不为凑数编造
• 不仅找代码漏洞，也找 spec 矛盾（"spec 说 X 但代码里隐含假设了 Y"）

输出：失败报告（每条带攻击路径 + 证据 + 影响的严重度）

审查者 G：性能审查者

角色：建设性审查：代码加载和运行是否高效？

Quick 级别跳过。Standard 和 Deep 级别执行。

检查清单：

#	检查项	方法
G1	Bundle 大小	npm run build → 检查 .next/ 或 dist/ 中 JS 文件大小。首次加载 JS 总量 > 500KB → WARNING；> 1MB → CRITICAL
G2	图片优化	扫描 public/ 和 import 的图片：是否有 > 500KB 的原始图片直接使用？是否有未压缩的 PNG/JPEG？
G3	Code splitting	Next.js 项目：动态 import (dynamic()) 是否用于非首屏组件？非关键第三方库是否懒加载？
G4	Render-blocking	是否有同步加载的第三方脚本阻塞首屏渲染？字体加载是否使用了 font-display: swap？
G5	Lighthouse 估算	基于代码特征估算：未优化图片 → Perf 扣 10-20；大 bundle → 扣 10-20；无 code splitting → 扣 5-10

输出：性能报告（每条: file:line + 指标 + 严重度 + 优化建议）

审查者 H：可访问性审查者

角色：建设性审查：代码是否对所有用户可用？

Quick 级别跳过。Standard 和 Deep 级别执行。

检查清单：

#	检查项	方法
H1	图片 alt 属性	扫描所有 <img> 标签：是否有有意义的 alt 文本？装饰性图片是否有 alt=""？
H2	颜色对比度	检查主要文本颜色 vs 背景色：正文 ≥ 4.5:1，大文字(≥18px bold) ≥ 3:1
H3	键盘可达	所有交互元素（按钮、链接、表单输入）是否可通过 Tab 键到达？tabindex 是否合理？
H4	focus 可见	grep "outline:\s*none" + grep "outline-none" → 检查是否同时提供了替代的 focus 样式
H5	表单 label	所有 <input> / <select> / <textarea> 是否有关联的 <label>（htmlFor 或嵌套）？
H6	ARIA 合理性	如有 aria-* 属性：是否使用了正确的 role？是否避免了冗余（如 <button role="button">）？
H7	状态传达	错误/成功/警告消息是否配合了图标或文字（而非仅靠颜色传达）？

输出：可访问性报告（每条: file:line + WCAG 标准引用 + 修复建议）

---

Phase 4：DEBATE（审查辩论）

八路审查者互相读取对方的产出，进行交叉验证和辩论。

流程：

Step 1：合并去重
  同一 file:line 被多个审查者标记 → 合并为一个发现，
  记录"被 A、C、E 三方独立发现"

Step 2：严重度仲裁
  对抗审查者的失败报告 #F03 → Spec 对齐官读后说：
  "F03 对应的是 spec 的 P0 功能验收不通过，升级为 CRITICAL"
  
  安全审计员读了代码质检员的发现 D07 → 说：
  "D07 标记的 TODO 在 /api/upload 旁边，说'加文件类型校验'。
   这不是代码质量问题，是已知安全漏洞。升级为 CRITICAL。"

  完整严重度矩阵见 `references/severity-matrix.md`。

Step 3：关联发现
  架构守卫读了 Spec 对齐官和安全审计员的发现 → 说：
  "A04 和 C03 都指向 /api/upload 路由。
   A04 说这个路由不在 spec 里，C03 说这个路由缺认证。
   建议合并为一个发现：未授权的新路由 + 缺乏安全控制。"

辩论纪律：

• 不引入全新发现：只处理已有发现之间的关系
• 升级（WARNING → CRITICAL）需要至少两个审查者共识
• 降级不需要共识，任何审查者都可以提出降级建议：由你最终裁决
• 辩论结束后产出的是"合并后的发现清单"，每个发现标注：原始来源 + 辩论决定 + 最终严重度

输出：合并后的发现清单（去重 + 严重度仲裁 + 关联标注）

---

Phase 5：REPORT（分级呈现）

门禁：DEBATE 完成

流程：展示审查报告，让你选择修哪些和强度级别。

# Review Report：[项目名]

> 审查时间: 2026-07-15 | 审查范围: 32 文件, 14 组件, 6 路由
> 审查者: Spec对齐官 + Bug猎手 + 安全审计员 + 代码质检员 + 架构守卫 + 对抗审查者 + 性能审查者 + 可访问性审查者
> 辩论: 8 个审查者交叉验证完成

## 🔴 CRITICAL：必须修，否则不可上线（阻塞项）

### C01：/api/upload 无文件类型校验 + 无认证中间件
**来源**: 安全审计员 (C1, C8) + 架构守卫 (E4) + 对抗审查者 (F07)： 三方独立发现
**位置**: `app/api/upload/route.ts:12`
**攻击路径**: 未登录 → POST /api/upload → 上传 .php 文件 → 成功写入服务器
**影响**: 任意文件上传 → RCE 风险
**修复**: 1. 加认证中间件 2. 加文件类型白名单 (image/png, image/jpeg, application/pdf) 3. 加文件大小限制 5MB

### C02：空数据导致页面白屏
**来源**: Bug猎手 (B1) + 对抗审查者 (F03)： 两方独立发现
**位置**: `app/dashboard/page.tsx:23`
**攻击路径**: 清空数据库 → 访问 /dashboard → TypeError → 白屏
**影响**: 新用户首次使用必然触发
**修复**: `data?.map(...) ?? <EmptyState />`

## 🟡 WARNING：应该修，条件性失败或技术债积累

### W01：仪表盘空数据时无空状态占位符
...

### W02：三个组件有重复的日期格式化逻辑
...

## 🔵 SUGGESTION：建议，修了更好

### S01：DashboardPage 320 行，建议拆分
...

## 📊 统计
- CRITICAL: 2 | WARNING: 3 | SUGGESTION: 4
- Spec 对齐: 28/28 P0 覆盖 ✅ | 2 处 drift 检测
- 安全: 2 CRITICAL | 其他通过 ✅
- 假代码: 0 残留 ✅
- 对抗: 5 次攻击尝试 → 2 次成功穿透
- 性能: bundle 180KB ✅ | 首屏估算 2.1s 🟡
- 可访问性: 3 个 WARNING (alt 缺失 / focus 样式 / 对比度不足)

## 🎯 审查强度
当前默认: Standard
- Quick: 只报告不修复，~30s
- Standard: 选中的问题收敛修复，~10-15min ← 推荐
- Deep: 全量回归 + E2E，涉及认证/支付建议选这个

## 🎯 你想修哪些？
  A) 全部修 (Standard)
  B) 只修 🔴 CRITICAL
  C) 修 🔴 + 🟡
  D) 我来手选

你选择 → 进入 Phase 6 CONVERGE

---

Phase 6：CONVERGE（收敛循环）

门禁：你确认修哪些 + 确认强度级别

流程：

converged = false
round = 0
pending = [你选择的修复项]
all_fixed = []

while (not converged 且 round < 5):

  round += 1

  // 6.1 FIX
  round_fixed = []
  for each issue in pending:
    启动独立子 agent
      上下文: 问题描述 + 相关文件 + spec 段落
      约束: 只修这个问题，不动其他代码
    修复 → 运行验收命令 → 通过？
      通过 → git commit "Fix [C01]: ..." → round_fixed += issue
      失败 → 再试一次（最多 2 次）
      2 次后仍失败 → 标记 STUCK，记录原因

  // 6.2 RE-AUDIT（轻量版）
  六路审查者只审本轮修改涉及的文件（非全量）
  产出: 本轮新发现清单

  // 6.3 记录本轮结果
  all_fixed += round_fixed
  new_issues = 本轮新发现的 CRITICAL + WARNING
  stuck_issues = 本轮 STUCK 的项

  // 6.4 收敛判断
  if new_issues 数量 == 0 且 stuck_issues 数量 == 0:
    converged = true  ✅
  elif new_issues 数量 > 0:
    pending = new_issues  // 下一轮修这些新发现
    if 本轮是第五轮 (round == 5):
      已达上限，暂停 ⏸️
  elif stuck_issues 数量 > 0:
    // 有修不了的，继续但标记
    if 本轮是第五轮 (round == 5):
      已达上限，暂停 ⏸️

// 收敛出口
if converged:
  → 进入 Phase 8 HANDOFF

收敛日志（每轮记录，最终写入 REVIEW.md）：

Round 1: 修复 5 个 → 重审 → 消除 4 个 ✅ | 新发现 2 个 🔍 | 卡住 0 个
  - 消除: C01, C02, W01, W03
  - 新发现: W05 (修复 C01 引入的对 /api/upload 的认证中间件，
    但没有同步更新测试文件中的 mock)
  - 卡住: W02 (涉及跨模块重构，需要你决定方案)
  - 剩余: W05, W02

Round 2: 修复 2 个 → 重审 → 消除 2 个 ✅ | 新发现 0 个 🔍 | 卡住 0 个
  - 消除: W05
  - 卡住: W02 (你决定延后处理)

✅ 收敛。2 轮完成。

遗留: W02：日期格式化重复代码，你选择延后，记录到技术债。

第五轮达上限时的处理：

⚠️ 已达 5 轮，仍有未收敛项：

- W05 (第 3 轮发现): 修复 2 次仍不通过。原因：[...]
- W06 (第 5 轮新发现): [...]

你想怎么做？
  A) 再来一轮
  B) 这俩记下来以后再说，先完成审查
  C) 我来决定怎么处理

纪律：

• 轻量重审只审变更文件：不全量扫，控制每轮耗时
• 修复不引入新 CRITICAL 是硬性要求：如果连续两轮都引入新 CRITICAL，暂停，可能是修复方案本身有问题
• STUCK 项必须记录：卡在哪、尝试了什么、为什么修不了、建议的替代方案
• 每轮 commit 必须标注 round 编号，方便追溯

---

Phase 7：SATISFACTION GATE（满意度门禁）

门禁：必入

→ 执行满意度门禁（详见 hlvibes/references/satisfaction-gate.md）。当前阶段名称：「代码审查」。

---

Phase 8：HANDOFF

门禁：CONVERGE 收敛成功，或你确认达上限后退出

→ 执行交付（详见 hlvibes/references/handoff.md）。产出 .vibe/doc/REVIEW.md。下一步：vibe-deploy。

REVIEW.md 格式要点

• 审查结果（原始发现数 / 修复数 / 遗留数）
• 收敛日志（每轮修复/消除/新发现/卡住/剩余）
• 修复记录（每条: 问题ID + commit）
• 对抗审查失败报告（已修复项）
• 安全基线 / Spec 对齐
• 遗留问题

---

通用纪律（所有 Phase 共享）

→ 完整通用纪律见 hlvibes/references/common-rules.md。