OWASP Cheat Sheet Series 的 Cheat Sheet PR 评审工作流：五维审查与单一裁决实战指南

本文面向 OWASP Cheat Sheet Series（CheatSheetSeries）仓库的维护者、贡献者以及任何希望以自动化 Agent 形式落地"高质量文档 PR 评审"的团队，完整讲解仓库自带的 /review-cheatsheet-pr 评审工作流：从上下文收集、机械预检、五个评审维度，到最终输出 MERGE / REQUEST_CHANGES / CLOSE 单一裁决。读完本文，你将掌握这套"激进且严谨、一切结论基于证据"的 PR 评审方法论，以及它在当前仓库中的全部配套实现（五个评审 Agent、CI 检查、技能文件镜像）。

背景：为什么需要"激进而严谨"的 PR 评审

OWASP Cheat Sheet Series 是一个面向全球开发者、被当作权威参考阅读的文档项目，其 AGENTS.md 明确规定受众是"开发者而非安全专家"。正因如此，项目长期积累了大量低质量投稿——尤其是 AI 生成的、引用了不存在或不支持其论断的页面的内容。

仓库自带的评审工作流 .claude/commands/review-cheatsheet-pr.md 正是为处理这一局面而设计。它的核心立场是：

• 评审必须激进（rigorous and aggressive），但每个结论都必须建立在证据之上，绝不能靠猜测；
• "错误的 looks fine（看起来没问题）"比"误报"更糟——放过一条错误建议会让全世界的开发者引入真实漏洞；
• 评审覆盖安全、实用性、链接/来源、重复、语言五个维度，最终收敛为一个明确的裁决。

这套工作流被 AGENTS.md 描述为维护者"triage backlog 和大规模核查来源"的标准工具，并与 GitHub-native 的 .github/skills/code-review/SKILL.md 形成镜像契约。

输入与三种运行模式

工作流通过 slash 命令 /review-cheatsheet-pr 触发，参数取自 $ARGUMENTS（见 .claude/commands/review-cheatsheet-pr.md 的 frontmatter 说明），有三种模式：

参数	行为
PR 编号或 GitHub PR URL	PR 模式（默认）：评审指定 PR
空	本地模式：评审相对 master 的本地工作差异（git diff master...HEAD 加未提交改动）
追加 --post	在产出报告后，主动提议将报告作为 PR 评论发布（仅 PR 模式有效）

运行时兼容性：跨 Agent 运行时可用

工作流明确要求能在"支持或不支持 Claude 风格 slash 命令、自定义子 Agent 或共享跨 Agent 上下文"的运行时中工作：

• 优先使用 平台原生 GitHub 工具/API；不可用时回退到 gh 命令行和本地 git；
• 如果运行时无法启动独立评审 Agent，则必须在当前会话内自行完成同样五个评审维度，不能因为子 Agent 不可用就跳过或失败；
• 绝不假设其他 Agent 能看到本会话上下文；委派任务时必须重新发送全部所需输入（PR 标题与正文、统一 diff、每个变更文件的完整当前内容、文件路径）。

Step 1 — 收集评审上下文

PR 模式

首选使用平台原生 GitHub PR 工具/API 获取：

• PR 元数据：编号、标题、作者、正文、增删行数、变更文件、状态、URL；
• 统一 diff（unified diff）；
• 变更文件列表；
• CI/检查状态。

gh 回退方案：

gh auth status          # 若未认证，提示用户运行 `gh auth login` 并停止
gh pr view <N> --json number,title,author,body,additions,deletions,changedFiles,files,state,url
gh pr diff <N>

关键约束：如果 gh pr view 失败（未认证、PR 编号无效或仓库错误），必须明确说明并提议回退到本地模式，而不是猜测。

随后必须读取每个变更的 cheatsheets/*.md（及 cheatsheets_draft/*）文件的完整当前内容——评审者需要看到变更所在的整节内容，而不仅仅是 diff 的 hunk；新文件则读取整个文件。

本地模式

git diff --stat master...HEAD   # 查看变更统计
git diff master...HEAD          # 查看完整差异
git status / git diff           # 查看未提交改动

然后同样读取变更文件。

Step 2 — 机械预检（快速、自行完成）

在进入深度评审前，先完成四项可快速核对的机械检查：

1. 范围（Scope）：统计变更的 cheatsheets(_draft)?/*.md 文件数与净增行数。CI 硬性限制为 3 个文件与 1500 行净增（无关联 issue 时），超出即记录违规——此限制由 .github/workflows/pr-scope-check.yml 强制执行，且仅统计 cheatsheets/ 与 cheatsheets_draft/ 下的 Markdown。
2. Issue 链接 / AI 披露：PR 正文是否按要求关联跟踪 issue，是否完成 AI Tool Usage 披露（模板见 .github/pull_request_template.md）。空白的 AI 披露区是关闭 PR 的理由。
3. 单一主题聚焦：这是否是一个连贯的变更，还是把无关编辑捆绑在一起？
4. CI 状态（PR 模式）：使用平台原生检查工具，或 gh pr checks <N>；记录失败的 markdownlint / textlint / link-check / scope / citation 检查——不要重复做 CI 的机械工作，而是建立在它之上。

Step 3 — 五个评审维度

当运行时支持独立评审 Agent 时，并行启动全部五个评审器，并在每个 Agent 的提示中内联传入：PR 标题与正文（意图）、统一 diff、每个变更 cheat sheet 的完整当前内容、文件路径。不支持独立 Agent 时，在同一会话内明确地、分别地完成五个维度的评审后再合并。

每个维度都有独立的 Agent 契约文件，位于 .claude/agents/ 目录。

维度 1：安全评审（cheatsheet-security-reviewer）

由资深应用安全工程师角色把关"安全正确性"。核心检查项（见 .claude/agents/cheatsheet-security-reviewer.md）：

• 建议正确性：每条安全建议是否真的正确？是否存在被过度简化到错误、或"正确但危险地不完整"的情况；
• 时效性：建议是否仍符合当下标准？警惕废弃算法、过时参数（弱迭代次数、密码用 MD5/SHA-1、旧 TLS 版本）、被取代的标准，或与当前 OWASP/NIST 立场相矛盾的内容；
• 危险模式：任何不安全、可利用、会 fail-open 的代码或配置？任何开发者可能直接粘贴进生产的"示例"（如禁用证书校验、把弱正则当作安全控制、手写加密）；
• 威胁模型健全性：建议是否真的防御了它声称防御的威胁？是否制造虚假安全感（如把客户端校验当作安全边界、该用允许列表却用黑名单）；
• 具体性："校验所有输入""使用加密"这类没有具体、正确机制的表述不是可执行的建议——要标记那些用模糊掩盖错误的表述；
• 论断 vs 来源：对带引用的安全论断做抽查，确认论断与权威来源的实际表述一致。

输出格式固定为：**Verdict:** PASS | CONCERNS | BLOCK + 按 [BLOCKER|MAJOR|MINOR] 文件:行号/节 — 问题 · 证据 · 修复 列出的 findings。严重级别语义：BLOCKER = 错误/危险建议，绝不能合并；MAJOR = 误导或实质过时；MINOR = 不精确但无害。存在任一 BLOCKER 即 BLOCK，存在 MAJOR/MINOR 即 CONCERNS，否则 PASS。

维度 2：实用性评审（cheatsheet-practicality-reviewer）

由"资深软件开发者（非安全专家）"角色评判建议对开发者是否可落地（见 .claude/agents/cheatsheet-practicality-reviewer.md）。该维度有时不适用——例如纯错别字/链接修复，或没有实现面的政策/治理类 cheat sheet，此时应明确说明并快速 PASS，而不是编造问题。

核心检查项：

• 可执行性：开发者读完后是否知道下一步做什么？还是"确保健壮安全""遵循最佳实践"这类空洞表述？
• 可行性：建议对大多数团队是否现实？是否在未说明的前提下假设了专用工具、大型基础设施或深度专家？按项目准则：可执行的"好实践"优于做不到的"最佳实践"——标记缺乏简单回退方案的不可行建议；
• 对非专家的清晰度：受众是没有深度安全知识的开发者。标记难懂的行话、未定义的缩写、会劝退读者的学术化表述；
• 架构 vs 代码平衡：按项目规则，建议应尽量架构化、语言无关。标记不必要的代码堆砌、不必要的单语言绑定、被当作生产就绪的示例代码；
• 信噪比：是否简洁、有观点？还是被填充词、重复背景和冗长的 AI 风格序言注水？
• 会咬人的完整性缺口：缺失的错误处理、被忽略的边界情况、会破坏常见真实工作流的建议。

维度 3：链接与来源审计（cheatsheet-link-auditor）

由事实核查编辑角色审计 diff 中新增/变更的链接与来源，其职责远超"链接是否 404"（CI 已能检测死链），核心是判断每个来源是否真实、权威、且确实支撑其挂载的那条论断（见 .claude/agents/cheatsheet-link-auditor.md）。幻觉、无关或弱引用是这些 PR 被回滚的头号原因。

对每个新增/变更链接逐项检查：

1. 可达性与重定向：能否解析到真实相关内容？还是 404、停放的 SEO 页面、登录墙、重定向到无关首页？注意某些站点只在伪装 User-Agent 时可用；
2. 支撑论断：页面是否真的佐证了它所引用的那一条具体建议？——真实且相关但不支撑论断的链接仍是 findings，这是最重要的检查；
3. 权威性与质量：RFC、NIST、OWASP、官方厂商/项目文档、MDN、信誉良好的工具文档、权威源码仓库（如 GitHub）都是有效权威来源，不应标记；要标记的是 SEO/营销内容农场、低质量博客转载、以及"存在主来源却用随机论坛帖"的情况；厂商营销博客不能用来支撑厂商中立的论断；
4. 时效性：页面是否过时/存档/被取代（旧版规范、已废弃建议、带"本文已过时"横幅）？
5. 内部链接：指向其他 cheat sheet 或锚点的链接，必须用 Glob/Grep/Read 确认目标文件存在于 cheatsheets/ 且锚点对应真实标题。

审计结论按类型区分：BROKEN、WRONG-PAGE、UNSUPPORTED 均视为 BLOCK；LOW-AUTHORITY 或 STALE 视为 CONCERNS；全部 OK 为 PASS。

维度 4：重复与定位检查（cheatsheet-duplication-checker）

由"脑海中装着整个系列地图"的编辑角色检查重复与错位（见 .claude/agents/cheatsheet-duplication-checker.md）。系列规则是"一个主题讲透；链接到其他 cheat sheet 而不是重复它们"。

• 跨表重复：新增内容是否大幅重复了另一张 cheat sheet 已有的指导？应在 cheatsheets/ 全系列搜索 diff 引入的关键主题/术语，若已覆盖则应链接而非复述；
• 表内重复：新内容是否重复了同一文件内已有的内容；
• 定位正确性：内容是否真的属于被编辑的这张 cheat sheet？如果是另一主题，应放到该主题的 cheat sheet（或新表）；
• 是否该开新表 / 先开 issue：若 PR 向无关的表添加了大型自洽主题，应按贡献流程标记其可能需要单独（经 issue 批准）的 cheat sheet；
• 缺失交叉链接：存在紧密相关的 cheat sheet 却未链接时记录之——良好的链接能预防未来的重复。

重要说明：Index.md 是站点构建时由 scripts/Update_CheatSheets_Index.py 自动生成的，只用于查找，绝不能把"缺少 Index.md 条目"标记为作者需要修复的问题。此外，XSS、注入、授权这类协调的多表家族采用 hub-and-spoke 模式互相链接是有意为之的正确做法，只有"复述另一张表的指导而非链接"才算重复。

维度 5：语言与编辑评审（cheatsheet-language-reviewer）

由文案编辑角色审查语言与编辑质量（见 .claude/agents/cheatsheet-language-reviewer.md）。机械的 markdownlint/textlint 规则由 CI 运行，本维度聚焦 lint 检查不到的部分：

• 语法与拼写：新增文本中的真实错误（错字、一致性、时态、标点、run-on）;
• 美式英语：American 拼写与用法；
• 面向非母语读者的清晰度：按项目准则保持语言相对简单，标记无谓复杂的句子、含混措辞、绕弯的句式；
• 缩写：非通用缩写首次出现时必须给出全称（HTTP/URL 这类可免）;
• 语气与简洁：标记啰嗦、冗余、注水的文字和 AI 式填充句（"在当今瞬息万变的格局中……"）。Cheat sheet 是参考材料，应紧凑直接；
• 结构惯例（lint 无法评判的部分）：H1 = cheat sheet 标题；以 ## Introduction 开头；标题后空一行；不手工添加目录；列表用 -。## References 一节为惯常做法但可选——约半数系列采用内联引用，仅在来源缺失时才提示其缺席。通常 3–6 个 H2 小节，但宽泛主题更多也无妨，不要仅因小节数量就标记。

本地可先运行项目自带 lint 暴露具体问题：

npm run lint-markdown      # markdownlint
npm run lint-terminology   # textlint（美式英语 / 术语）

Step 4 — 汇总与裁决

将五个维度报告与预检结果综合为一个决策，注意：

• 不得简单拼接——必须去重（若多个评审器标记同一问题，如某含混句同时被语言与实用性评审器标记，则合并为一条、同时呈现两个角度）、解决重叠、按严重性排序并权衡；
• 不可合并（Not mergeable）的情况：存在任何安全 BLOCKER；论断错误或超出该主题威胁模型（即使有引用）；任何损坏/不支持/伪造的链接；实质性重复；缺失 AI 披露；或范围违规；
• citation-check 失败本身不是阻塞项：它只是维护者可以对内容健全但触发门槛的内容进行覆盖的下限。按整体健全性判断；反过来，也不要放行引用充分但内容错误的内容。

最终映射到三级裁决：

• MERGE — 内容健全、有来源、在范围内、有用；至多有琐碎瑕疵；
• REQUEST_CHANGES — 存在可修复的问题；明确列出作者必须修改的内容；
• CLOSE — 根本性不健全、超出范围/流程、AI 垃圾内容，或重复到难以修复；说明原因并保持尊重。

Step 5 — 输出评审报告

工作流规定了固定的报告模板，评审结束后按此打印：

# Cheat Sheet PR Review — <PR #N: title | local diff>

**Verdict: MERGE | REQUEST_CHANGES | CLOSE**
<2-4 sentence rationale>

## Scope & process
- Files: <n> · Net additions: <n> · Issue linked: <y/n> · AI disclosed: <y/n> · CI: <summary>

## Dimension verdicts
| Dimension | Verdict | Headline |
|-----------|---------|----------|
| Security | PASS/CONCERNS/BLOCK | … |
| Practicality | PASS/CONCERNS/BLOCK/N-A | … |
| Links & sources | PASS/CONCERNS/BLOCK | … |
| Duplication & placement | PASS/CONCERNS/BLOCK | … |
| Language | PASS/CONCERNS/BLOCK | … |

## Must-fix before merge
1. <blocker/major, with file:line and concrete fix>

## Should-fix
- <major/minor>

## Nits
- <optional>

## Suggested reply to author
> <ready-to-paste, respectful, specific comment summarizing the decision and required changes>

模板要素：裁决句 + 2–4 句理由；范围与流程摘要（文件数、净增行、issue 链接、AI 披露、CI 摘要）；五维裁决表（含"N/A"选项）；"合并前必须修复"清单（带 file:line 与具体修复建议）；"应该修复"；"小瑕疵"；以及一段可直接粘贴、尊重且具体的"回复作者"评论。

Step 6 — 可选发布（仅 --post 且 PR 模式）

• 展示"Suggested reply to author"并请求明确的确认，之后才可发布；
• 仅在明确同意后，使用平台原生 PR 评论工具；否则：

gh pr comment <N> --body-file <file>

两条硬性约束：

• 未经本会话维护者明确同意，绝不发布关闭/批评某个贡献的裁决；
• 不执行 gh pr close / merge——最终动作留给维护者。

配套实现：五个评审 Agent 的职责契约

工作流的三级裁决（BLOCKER/MAJOR/MINOR、BLOCK/CONCERNS/PASS）并非凭空设计，而是与 .claude/agents/ 下五个 Agent 文件的输出契约严格对齐的，每个 Agent 都要求"返回完全固定的结构，除此之外什么也不返回"：

Agent 文件	角色	输出契约要点
cheatsheet-security-reviewer.md	资深应用安全工程师	## Security review / Verdict / 按严重级别的 findings / Notes
cheatsheet-practicality-reviewer.md	资深开发者（非安全专家）	Applicable: YES/NO / Verdict / findings / Notes
cheatsheet-link-auditor.md	事实核查编辑	逐链接的 OK/BROKEN/WRONG-PAGE/UNSUPPORTED/LOW-AUTHORITY/STALE 判定
cheatsheet-duplication-checker.md	全系列编辑	重叠对象、修复建议（链接/移动/拆分）
cheatsheet-language-reviewer.md	文案编辑	引用原文 → 给出修正 → 说明原因

这些 Agent 的职责边界清晰：安全评审不碰链接可达性与语法（那是链接审计与语言评审的领地）；实用性评审不做安全正确性判断（那是安全评审的领地）；重复检查器可以跨整个 cheatsheets/ 与 Index.md 搜索。Agent 被要求"不要为了显得周全而编造问题"——如果某个维度内容健全，就直说 PASS。

与仓库规则、CI 与贡献流程的联动

评审工作流不是孤立的，它引用了仓库的三份规则文件，并依托 CI 的机械检查：

• AGENTS.md —— 面向仓库内所有 AI 工具的强制规则，定义"不可协商规则"：来源必须真实、已读、且支撑论断；论断必须正确且落在威胁模型内；单一主题、单 PR、单分支；不重复而链接；架构优先于代码；拒绝 AI 垃圾内容；必须披露 AI 使用。它明确将 /review-cheatsheet-pr 描述为维护者的标准评审工具；
• CONTRIBUTING.md —— 贡献流程：次要修复直接提 PR；更新/新建 cheat sheet 需先经 issue 批准；PR 聚焦单一文件；AI 使用必须披露，否则贡献可能被关闭或删除；
• GUIDELINE.md —— 写作指南：为开发者而非安全专家写作、务实优于理论、简洁、有观点、用表格对比、用权威引用支撑论断。

评审工作流中"不重复 CI 的机械工作"的立场，与仓库实际部署的 CI 检查一一对应（.github/workflows/）：

CI 检查	作用
pr-scope-check.yml	3 文件 / 1500 净增行的范围硬限制
citation-check.yml	每个新增 H2 至少一条内联 [text](https://...) 引用
md-link-check.yml	死链检测
md_lint_check.yml	markdownlint 格式检查
index-drift-check.yml	验证 Index.md 与目录实际内容一致（自动生成，非手改）

此外，AGENTS.md 明确指出：同一评审契约已镜像到 GitHub-native 的 .github/skills/code-review/SKILL.md（供 Copilot code review 拾取），创作规范见 .github/instructions/cheatsheets.instructions.md；一条规则在三处改动时必须同步。贡献者环境搭建与 lint/链接自检流程见 CONTRIBUTING.md 与 Project.code-workspace。

快速参考

事项	位置
PR 评审工作流主命令	.claude/commands/review-cheatsheet-pr.md
五个评审 Agent 契约	.claude/agents/ 目录
全仓库 AI 强制规则	AGENTS.md
写作指南	GUIDELINE.md
贡献流程与 AI 披露政策	CONTRIBUTING.md
GitHub-native 镜像评审技能	.github/skills/code-review/SKILL.md
CI 检查工作流	.github/workflows/ 目录
PR 模板（含 AI 披露区）	.github/pull_request_template.md
全部 cheat sheet 目录	cheatsheets/ 目录
草稿目录	cheatsheets_draft/ 目录

一句话总结这套方法论：用五个视角各司其职的评审者交叉审视每一个变更，用证据（而非印象）支撑每一个结论，把五份报告去重、排序、加权后收敛成一个可执行的裁决——MERGE、REQUEST_CHANGES 或 CLOSE。这既是对抗 AI 生成垃圾投稿的过滤器，也是保证"全世界开发者当作权威参考"的 cheat sheet 内容安全、准确、可落地的最后一道人工质检线。