先讲事实，再开火：Repo-Roast 的证据驱动审查设计

本文更新于 2026-07-26，内容对应 Repo-Roast v0.4.0。

代码仓库锐评最容易走向两个极端：要么只剩规则列表，没有对项目整体的判断；要么为了“有节目效果”而放大措辞，最后连事实都变形。

Repo-Roast 选择先解决可信度，再处理表达方式。它是一个证据驱动的仓库审查 Skill：先从架构、安全、性能、可读性、工程化五个维度形成中性 finding，再由 Editor 验证证据、计算评分，最后按照指定风格组织成有观点的报告。

Scout：建立项目画像并确定唯一 review_scope
  ↓
Deep Dive：五维并行审查，只输出中性、可验证的 JSON finding
  ↓
Editor：验证证据与状态 → 计算评分 → 按 Flavor 排序 → 按 Tone 表达
  ↓
REPO_ROAST_REPORT.md

一句话概括 v0.4.0 的原则：

先完成技术审查，再选择怎么把事实说出来。

为什么不是再做一个 lint

ESLint、SonarQube、CodeScene 等工具分别擅长格式规则、静态检查或代码热点。Repo-Roast 并不替代它们，而是试图回答另一类问题：

  • 模块边界是否清楚，未来扩展会不会牵一发动全身？
  • 安全问题有没有落到真实文件和具体行号？
  • 性能风险是理论猜测，还是能从实现中找到证据？
  • 可读性问题是否影响维护，而不只是违反某条风格规则？
  • 测试、配置、文档和贡献流程能否支撑长期开发？

这些问题需要跨文件、跨配置理解仓库，也需要把“判断”和“证据”绑定在一起。

三阶段证据链

第一阶段：Scout

Scout 在不超过 10 次工具调用的约束内读取 README、目录结构、构建配置、CI 配置和 Git 历史，建立项目画像，并生成唯一的 review_scope。

这个范围不是随手列一批文件。后续五个审查 Agent 必须共享同一份范围，避免架构 Agent 看完整仓库、安全 Agent 只看两个入口，最后却把结果放在同一张评分表中。

第二阶段：五维 Deep Dive

五个独立 Agent 并行审查：

维度 重点
architecture 模块边界、依赖方向、分层、耦合与扩展性
security 硬编码凭据、输入边界、注入风险与敏感信息处理
performance 重复查询、复杂度、资源释放、缓存与热路径
readability 命名、函数职责、控制流、注释与一致性
engineering 测试、错误处理、配置、文档与协作流程

每个 Agent 只输出中性 JSON finding。正式问题必须包含仓库内真实相对路径、有效行号、严重度、影响和修改建议，并通过对应 JSON Schema。

第三阶段：Editor

Editor 不只是“把五份结果拼起来”，而是负责：

  1. 验证文件、行号和引用是否位于本次审查范围。
  2. 删除证据验证失败的问题。
  3. 汇总各维度状态，只让已完成的维度参与评分。
  4. 按 Flavor 调整问题权重和优先级。
  5. 在不改变技术事实的前提下，按 Tone 加入表达。

锐评可以更锋利，但 severity、file、line、事实描述、影响和修复建议不能跟着变化。

五条铁律

铁律 含义
有据可依 正式批评必须带真实文件和行号
有褒有贬 亮点如实承认，问题同样直说
拒绝模糊 只写已经确认的事实，不拿猜测凑问题
对事不对人 评价代码、设计和工程结果，不攻击作者
给出路 每个问题都附带可执行的修改方向

Flavor 和 Tone 不再混用

v0.4.0 最关键的变化，是把“审查立场”和“表达锐度”拆开。

Flavor：决定怎么看

Flavor 控制五维权重、审查立场和问题优先级：

Flavor 主要关注点
default 维护成本、边界与长期工程质量
google 可读性、测试、清晰接口与一致性
startup 交付速度、风险敞口与可控技术债
oss-maintainer 文档、贡献体验、兼容性与社区维护

Tone：决定怎么说

Tone 只控制措辞和修辞密度：

Tone 表达特点
professional 克制、正式，适合审计或团队报告
sharp 直接、有观点，是默认选项
savage 更强的技术讽刺，但仍不攻击个人

假设已经确认 src/auth.ts:42 将访问令牌写进源码，同一个 finding 可以有不同表达：

professional：src/auth.ts:42 存在硬编码访问令牌，请移除并立即轮换。

sharp：版本库在这里兼职保险箱，而且还是透明的；请移除并立即轮换。

savage：把访问令牌焊进源码，不叫配置管理，叫给泄露事故预填工单。

三种说法共享同一文件、行号、严重度和修复建议。Tone 不能制造新问题，也不能把普通问题渲染成严重漏洞。

不把“没检查”写成“没问题”

每个维度都有明确状态：

  • requested：用户本次要求审查的维度全集。
  • completed：结果通过 Schema 和证据验证，参与评分。
  • failed：请求过，但因超时、解析或验证失败而没有完成。
  • skipped：用户没有请求，不参与评分。

S/A/B/C/D 只评价已经完成的维度。这样可以避免某个 Agent 超时后，报告仍给出一个看似完整但实际缺项的总分。

使用方式

# 默认 Flavor 为 default，默认 Tone 为 sharp
review https://github.com/xxx/yyy

# 调整表达锐度
review https://github.com/xxx/yyy --tone professional
review https://github.com/xxx/yyy --tone savage

# 调整审查立场
review /absolute/path/to/repo --flavor startup

# 只审查指定维度
review /absolute/path/to/repo --dimensions security,performance

# 控制范围和深度
review /absolute/path/to/repo --depth deep --focus src/core/

这些命令由安装 Repo-Roast Skill 的 Agent 客户端解释，不是独立的系统 CLI。

安装到 Claude Code

仓库中真正可安装的 Skill 是内部的 repo-roast/ 目录。不要把整个仓库直接放进同名 Skill 目录，否则入口会多嵌套一层。

git clone --depth 1 https://github.com/haodehaode378/ruiping-skill.git ruiping-skill-source
mkdir -p .claude/skills
cp -R ruiping-skill-source/repo-roast .claude/skills/repo-roast

安装结果应为：

.claude/skills/repo-roast/SKILL.md

安装到 Codex

仓库级 Skill 可以放进 .agents/skills：

git clone --depth 1 https://github.com/haodehaode378/ruiping-skill.git ruiping-skill-source
mkdir -p .agents/skills
cp -R ruiping-skill-source/repo-roast .agents/skills/repo-roast

PowerShell 对应写法：

New-Item -ItemType Directory -Force .agents\skills | Out-Null
Copy-Item -Recurse .\ruiping-skill-source\repo-roast .\.agents\skills\repo-roast

最终入口应为 .agents/skills/repo-roast/SKILL.md。

v0.4.0 的实现边界

Repo-Roast 由 Markdown 指令、JSON Schema、五维评分规则、Flavor 配置、修辞规则和报告模板组成。当前版本还提供：

  • 90 条按维度、问题模式、严重度和 Tone 分类的结构化修辞语料。
  • 六组回归 fixture，用于验证 Schema、状态和报告行为。
  • 对文件、行号、范围及引用事实的证据校验。
  • 对歧视、羞辱、威胁、人身攻击等表达的明确禁止规则。

仓库内的 Schema、语料和 fixture 已有自动验收，但这不等于所有 Claude Code、Codex 版本和真实仓库都完成了端到端验证。实际报告仍需要开发者复核。

仓库地址：https://github.com/haodehaode378/ruiping-skill

Repo-Roast 的价值不在于“骂得狠”，而在于把事实、判断和表达分成三层：事实必须可验证，判断必须有尺度，表达才可以有锋芒。