beautiful-article 工程审阅型文章（review）实战指南：把 PR、方案、事故复盘写成证据驱动的网页长文
beautiful-article 工程审阅型文章（review）实战指南：把 PR、方案、事故复盘写成证据驱动的网页长文
导读
本文是 garden-skills 仓库中 beautiful-article Skill 的 review（工程审阅）文章类型完整写作指南。它面向把 PR 评审、方案设计、事故复盘、架构 / API / 安全审计这类具体产物审阅，转译为单文件 HTML 网页长文的场景。读完你将掌握 review 类型的骨架结构（Hero → Summary → 发现 → 影响 → 建议 → 行动项）、领域特例组件（RiskList、DiffReview、Incident 等）的取舍标准、Raw 自由层的边界，以及证据驱动的自检方法，并能在 SKILL.md 的八阶段工作流中找到它的准确落点。
1. review 是什么：起点是"一份具体产物"
在 article-types.md 的文章类型路由表中，review 被定位为 PR / 方案 / 事故 / 设计审阅，推荐信息保留 60-80%。它与其他类型的本质区别在于起点：
- 起点是审阅一份具体产物（一段代码改动、一份方案文档、一次线上事故、一个 API 设计、一轮安全审计）；
- 产出是意见与行动（通过 / 待修 / 否决 + 逐条发现 + 可执行行动项）。
这与 essay、briefing、full-report 有清晰的分界。原文档 review.md 给出了三条"何时不要用 review"的红线，这是判断类型的第一道闸门：
| 场景 | 应该用的类型 | 原因 |
|---|---|---|
| 评测产品 / 书 / 论文 / 电影 | essay |
观点驱动，没有"通过 / 否决"二元判断 |
| 给老板做"该不该做 X"的决策摘要 | briefing |
读者不读全文，只求快速判断 |
| 完整的事后调研报告 | full-report |
是研究报告而非对具体产物的审阅 |
判断口诀：如果读者看完这篇文章需要做出"通过 / 待修 / 否决"或"合并 / 返工 / 拒绝"的工程判断，用 review；如果读者要做的是业务决策或表达观点，立即改道
briefing/essay。
2. 信息保留比例：60-80%，删的是铺垫不是证据
review 的标配信息保留为 60-80%。结合 information-density.md 的密度等级表，这一档位的特征与 100% 的 longform 有明确分工：
- 保留：关键发现 + 证据（代码片段 / 截图 / 数据 / 日志）+ 行动；
- 删减：无关细节、上下文铺垫、历史背景、"之所以这样"的展开段落。
对应的正文 / 视觉比例是"中"：重点结构化、视觉辅助理解，但正文仍是主体。原文档反复强调一个原则——证据优先、不抢正文，这与 tufte 主题的"数据墨水比"气质天然同源（详见第 6 节）。
一个实操提示：密度不是"缩水摘要"，而是"被编辑过的审阅报告"。60-80% 的含义是每条发现都带证据、每项建议都可执行，但不保留评审过程中的来回沟通和冗余引用。
3. 典型结构：结论先行，证据后置
review 的典型结构在 review.md 中给出，核心是评审意见先于证据：
Hero 被评对象 + 评审范围 + 评审日期 / 评审人
Summary 结论 / 评审意见先行（通过 / 待修 / 否决）
Section 背景与目标 → 发现（逐条）→ 影响评估 → 建议 → 行动项
Conclusion 核心判断 + 通过 / 待修 / 否决
逐块拆解其写作要点：
- Hero（被评对象元信息）：必须在开篇就交代清楚"评的是什么"。原文档要求的字段是：被评对象（PR 编号 / 方案标题 / 事故时间窗）、评审范围、评审日期 / 评审人。这是审阅的可追溯性来源——评审意见必须能定位到具体产物。
- Summary（结论先行）：这是 review 与
longform最大的结构差异。读者（通常是决策者或合并方）应当只看 Hero + Summary 就能拿到最终判断。把"通过 / 待修 / 否决"以及最重要的 2-3 条发现直接放在开头。 - Section 主体：按"背景与目标 → 发现（逐条）→ 影响评估 → 建议 → 行动项"的顺序组织。发现是主体，每条都要能落到证据；影响评估回答"这条发现有多严重、影响谁"；建议与行动项回答"谁做 / 何时做 / 怎么验收"。
- Conclusion（收束判断）：给出核心判断并复述 通过 / 待修 / 否决 三元结论，与 Summary 首尾呼应。
4. 组件选择：prose-first，领域组件按需取用
原文档对 review 的组件策略有一条明确的纪律：仍是 prose-first——结论与发现先用正文 + Summary 讲清楚；领域特例组件只在内容确实是该结构时按需取用，"不要因为是 review 就全堆上"。
这与 component-policy.md 的全局规则一致：语义组件是点睛，只在内容确实"是"那个结构时才用（litmus test：若一句话 / 一个列表 / 一张表读起来更好，就用那个）。review 的领域特例组件及触发条件如下：
| 组件 | 触发条件 | 用法要点 |
|---|---|---|
RiskList |
确有一组需要分级的风险 | 只用于可分级风险，不是普通发现的陈列架 |
DiffReview |
确有代码改动要逐行评 | 代码一律用 CodeBlock，不裸写代码 |
Decision / Tradeoff |
确有 "X vs Y" 的取舍要展示 | 展示决策分叉与权衡，而非装饰 |
Incident |
事故复盘时的时间线 | 承载时间轴式的事故推进过程 |
ActionList / Checkpoint |
行动项 / 验收点确需结构化 | 对应"谁做 / 何时做 / 怎么验收" |
值得注意的约束来自 component-policy.md：领域特例组件"每多用一个，都要能回答'这块内容本质上就是它'"。一篇 review 如果发现都以平铺正文 + 证据呈现，就不需要 RiskList；只有确实存在多级风险时它才有意义。另外，写代码只能用 CodeBlock（HighlightedCode 是内部底层，不暴露给作者）。
5. Raw 边界：影响图、依赖关系、风险热度的自由层
review 类型对 Raw 自由层的定位在 review.md 中明确列出：
影响范围图、依赖关系、风险热度矩阵、调用链、监控曲线等用 Raw 自由层（HTML / CSS 矩阵 + 热度、轻交互、按需 SVG）；克制、证据优先、不抢正文。
结合 raw-policy.md 的心法，这块的自由层应该为 THIS 篇文章手写，而不是复用固定 widget：
- 影响范围图 / 依赖关系：用 HTML + CSS 的并排对比、卡片网格或分栏呈现模块受影响程度；
- 风险热度矩阵：CSS 矩阵 + 热度着色，让"哪些区域风险高"一眼可扫；
- 调用链 / 时序：按需用内联 SVG 画细线图，服务事故复盘的时间线或调用链追溯；
- 监控曲线：内联 SVG 折线，只在确实要展示趋势时用，不是默认手段。
Raw 的硬约束是用主题 token：颜色 / 字体 / 间距必须取自 var(--ra-color-accent)、var(--ra-font-body)、var(--ra-space-4) 这类 --ra-* 变量，禁止野生样式。Raw 自检四问：删掉后理解是否变差？服务哪一段落 / 论点？是否用 token、符合主题？是否让文章更像应用（若是则收敛）？
6. 配图与主题倾向：证据型审阅的四套气质
原文档为 review 给出了明确的配图与主题倾向：
- 配图倾向：
user-assets真实截图 / diff / 监控图 / dashboard 截图（tufte风）。这里的逻辑是"证据优先"——审阅的插图应当是评审现场的真实材料，而不是装饰性配图。 - 主题倾向：
tufte（证据型 review）、shannon（暗底工程 / 事故复盘）、fuller（系统设计 / RFC review）、vignelli（中性规格型）。
结合 theme-selection.md 的选型流程（先读 theme-profiles/index.json 拿 bestFor / mood，再读对应 <id>.md），这四套主题与 review 的匹配逻辑如下：
| 主题 | runtime id | 适合的 review 场景 | 关键气质 |
|---|---|---|---|
tufte |
tufte |
数据 / 证据型 review | 数据墨水比、发丝线、低装饰，证据型审阅的主场（见 tufte.md） |
shannon |
shannon |
暗底工程 / 事故复盘 | 温暖石墨暗底 + 琥珀信号色，Incident / RiskList / DiffReview / Decision 密集的内容尤其契合（见 shannon.md） |
fuller |
fuller |
系统设计 / RFC review | 蓝图底 + 制图青 + 方格网，适合规格表、拓扑示意、尺寸标注（见 fuller.md） |
vignelli |
vignelli |
中性规格型 | 瑞士国际主义、冷中性、强网格，适合可扫读的中性规格审阅（见 vignelli.md） |
配图在四种主题下都强调"截图裁掉浏览器 chrome、配清晰 caption / source / alt"，且 tufte / shannon / fuller 三个暗色系主题都明确禁止"营销落地页式"的装饰视觉。
7. 自检清单：让 review 站得住脚的四条铁律
原文档为 review 提供的自检是它区别于其他类型的质量底线，逐条展开：
- 评审意见在开头先行：读者只读 Hero + Summary 能否立刻得到"通过 / 待修 / 否决"？如果没有，结构就没做到"结论先行"。
- 每条发现都有证据支撑：代码片段 / 截图 / 数据 / 日志，而不是"凭感觉"。这条与
tufte的"每一滴墨水都承载信息"是同一条纪律的两个侧面。 - 建议与行动项可执行：必须回答"谁做 / 何时做 / 怎么验收"。无法执行的建议等于没有建议。
- 起点是审阅具体产物：如果起点是"读者要做决策"，应该用
briefing；如果起点是"读者要发表观点"，应该用essay。这是类型正确性的兜底检查。
8. 在 beautiful-article 工作流中的落点
review 不是孤立的写作模板，它嵌在 SKILL.md 的八阶段 harness 中。对 review 作者而言，关键节点有四处：
- Phase 2（Editorial Planning）：在 article-types.md 路由到
review后，读取本文所依据的 review.md，把"60-80% 保留"和上述结构写进plan/plan.md的 Brief / Outline 段。 - Phase 3（Checkpoint 1）：文章类型作为五项必确认决策之一，其语义化标签为"PR / 方案 / 事故审阅
review · ~70%"，与信息保留比例绑定。 - Phase 5（Full Article Build）：每个 Section 是独立组件文件（
article/sections/NN-*.tsx），由 Section Reviewer 以消息返回 pass / fail；正文是主体，Raw / 配图做增强。 - Phase 6（Final Review）：Editorial / Visual / Technical 三视角终审，写
review/final-review.md。其中 review-checklist.md 的 Technical Reviewer 清单要求章节序号全篇自洽（Section 序号连续单调、Subsection 前缀等于父 Section 编号）——对 review 这类多发现、多小节的结构尤其重要。
工作区由 scaffold.sh 在 Phase 4 创建（Vite + React + TS + reacticle 组件库），article/Article.tsx 是只做 import 与排序的 assembler，正文必须落在独立 Section 文件里；最终交付是 html-output.md 描述的自包含单文件 article/article.html。
9. 与相邻类型的辨析速查
最后把 review 与最容易被混淆的两个类型再对齐一次，方便在 Phase 2 快速路由：
- review vs essay：review 评的是工程产物，产出二元工程判断；essay 评的是产品 / 书 / 论文 / 电影，观点驱动、无二元判断。同样是"审阅"，起点和输出完全不同。
- review vs briefing：review 读者要做出工程决策（合并 / 返工 / 拒绝）；briefing 读者是忙人决策者，3-5 分钟读完，结论 + 关键证据 + 行动。若审阅对象是一份具体 PR，用 review；若是一份"该不该做 X"的摘要，用 briefing。
- review vs full-report：review 起点是具体产物；full-report 是消化后的研究报告（执行摘要 + 背景 + 证据 + 数据 + 风险 + 结论四件套），起点可以是开放议题。
把握好"具体产物 + 证据 + 二元判断 + 可执行行动"这四要素，你的 review 就能在 beautiful-article 的框架下成为一份既清晰又值得反复引用、复查的工程审阅记录。