brief

Brief

生成一页内容丰富、视觉效果出众的摘要——一个独立的 HTML 文件，设计成信息密集的仪表盘，而不是文字文档，让时间紧迫的审阅者无需自己阅读差异内容，就能了解一组变更，并迅速决定是否批准或合并。

读者是一位日程繁忙的经理。他们可能只花 30 秒，也可能花 10 分钟；这份摘要必须让这两种阅读方式都各有收获。因此，内容严格按照优先级排序：最重要、最难撤销的变更放在最前面，日常编辑等次要内容放在最后。目标是在尽可能短的时间内传递最多有效信息，但绝不能为了简短而牺牲清晰度。内容要全面，只需把最重要的内容放在前面。

这不是一份报告，而应当像 PR 作者亲自坐下来向审阅者讲解工作一样——每个论断都要有真实代码作为依据，解释变更为何存在，而不仅仅是变更了什么。大多数读者不会打开差异内容。请直接展示关键代码。

两种模式 — 自动检测

根据工作的状态，同一项技能会生成两种风格的摘要：

• DRAFT — 存在工作树差异（未提交，或已提交但未推送），并且通常会在 proposed-pr-stack.md 中列出计划中的 PR 堆栈。目前还没有实际 PR，或 PR 堆栈尚未达到可供审阅的状态。这份摘要供用户在审批关口阅读，之后再将工作拆分为多个 PR。
• FINAL — 已有实际的 PR 堆栈（一个或多个开放或已合并的 PR），审阅已完成（PR 均无待处理审阅事项，或所有发现的问题都已处理），用户即将发出合并信号。这份摘要供用户在合并关口阅读。

**如何选择模式：**检查当前状态。

1. 此分支／堆栈上是否存在实际 PR？（运行 gh pr list --head <branch>；如果正在使用 Graphite，则运行 gt log。）
2. 如果存在，审阅是否已完成？（没有待处理的审阅评论，没有等待重新审阅的请求，所有发现的问题都已在后续提交中修复，或已明确标记为暂不处理。）
3. **两项均为是 → 选择 FINAL 模式。**否则 → 选择 DRAFT 模式。

如果用户明确指定某种模式（“draft brief”／“final brief”），请遵照执行。否则自动选择，并在回复顶部说明所选模式（“正在生成 FINAL 摘要——PR 堆栈已通过审阅。”）。

两种模式的区别在于内容，而非视觉结构。以下 HTML 框架适用于两种模式；特定模式的内容（每个 PR 卡片上的审阅状态标记、提交原因标签、跳过的问题行）仅在 FINAL 模式下显示，并置于两种模式共用的 PR Stack 部分中。

语气 — 写成循序引导的讲解

表格和提示框构成的页面便于快速浏览，却难以真正理解：审阅者虽然能看到事实，却看不到串联事实的脉络。因此，摘要除了结构清晰，还应当读起来流畅——像作者带着同事了解变更，而不是在提交一份报告。

• TL;DR 是一两句简洁的话——说明已交付（或计划提出）什么，以及唯一值得仔细关注的事项。开头不要写叙述性段落。保持精炼。
• 每个部分都以一句通俗易懂的引言开头，说明接下来会讲什么。随后再展示密集的表格、提示框或导览内容。
• Code Tour（第 5 步）是摘要的核心，天然具有叙事性——每一站都先简短说明这段代码为何重要，再展示实际代码。
• 尽量使用连贯、完整的句子，避免简短零散的片段。

让文字起到串联作用，而不是堆砌内容。快速浏览的读者仍能从结构中获取所有信息；从头读到尾的读者则能读出连贯的故事。

步骤 1 — 收集材料

确定主干分支（通常是 main）。然后全面了解相对于主干分支的所有变更：

• 相对于主干分支的累计差异和统计信息 — 使用 git diff <trunk>..HEAD --stat，并查看重要文件的完整差异。
• 分支 / 堆栈上的提交 — 使用 git log <trunk>..HEAD --oneline，并查看完整提交消息（git log <trunk>..HEAD --format=fuller 或 git log <trunk>..HEAD --format=%B），以提取作者撰写的说明性正文。许多提交只有主题行——没关系，正文是可选的。但如果某个提交确实包含有意义的正文（例如 Why: 段落、理由说明、权衡说明），那就是作者对该部分工作的亲自解释，应纳入简报。
• 未跟踪文件（尤其是 DRAFT 模式）——新文件往往包含最重要的代码，也很容易被遗漏。运行 git status --porcelain，然后直接阅读这些文件。
• 拟议的 PR 堆栈（如果存在） — 可能位于当前对话上下文中，也可能在 proposed-pr-stack.md 中（检查仓库根目录和 .briefs/）。如果不存在，则省略堆栈部分。不要凭空编造。
• 实际的 PR 堆栈（如果存在）（FINAL 模式）— 使用 gh pr list --head <branch>，并通过 gh pr view <num> --json title,body,state,commits,reviews,reviewDecision 查看每个 PR。如果使用 Graphite，也要运行 gt log short。
• 评审讨论串（FINAL 模式）— 使用 gh pr view <num> --comments 和 gh api repos/{owner}/{repo}/pulls/{num}/comments 查看行内评审评论。将提交消息与评审发现交叉对照，建立「发现 → 提交」的对应关系。

挑选代码导览内容时，跳过生成的文件。 这些文件会增加干扰，却无法为讲解提供信息。常见示例（请根据仓库调整）：

• **/*.api.md、**/api-report* — 生成的 API 面报告
• apps/docs/content/reference/**、生成的参考文档
• yarn.lock、package-lock.json、pnpm-lock.yaml
• 自动生成的 **/CHANGELOG.md
• 快照文件、架构转储、打包资源——任何带有「DO NOT EDIT」标头或仓库中标明重新生成命令的文件

这些文件仍可出现在精简文件索引中，但不应作为导览点或重点说明。

忽略所有已有的简报文件。 .briefs/ 中可能已有先前运行或其他工作的简报。它们绝不能作为输入——可能已经过时或不再适用。不要读取它们。

步骤 2 — 按风险级别对每项变更分类

开始撰写之前，先将发现的内容分级。页面的组织顺序由此决定。

第 1 级 — 高风险（优先说明，并确保不被忽略）：

• 新增或变更的服务端点 / API 路由 / 路由处理程序 / 服务端操作 — 任何会扩大功能表面的变更。
• 身份验证、授权、访问控制、会话、机密信息、CORS — 任何涉及谁可以执行哪些操作的变更。
• 数据库架构变更 — 新增表 / 列、类型变更、约束、索引、删除。
• 新增外部依赖项、变更配置 / 环境变量，以及任何破坏性或不可逆变更。

**第 2 级 — 承载功能的核心逻辑：**业务逻辑、数据流、API 响应结构、状态机，以及评审者必须真正理解的函数。

**第 3 级 — 常规变更：**UI 调整、重构、测试、文档、格式调整。

如果某一级没有内容，请明确说明（例如「没有身份验证或架构变更」）——没有高风险变更本身也是有价值的信息。

第 3 步 — 逐行处理 Schema 变更

在大多数差异中，Schema 变更最危险，也最容易被轻率放过。如果 Schema 源文件发生了变化（schema.prisma、db/schema.ts、迁移文件、模型定义），不要概述，要逐项检查。

每项变更占一行：表／模型、确切字段、变更前 → 变更后、是否可为空、默认值、索引／约束的影响，以及实际后果（“现有行需要回填”“删除会导致数据丢失”“在已有数据的表中，不带默认值的非空字段会导致操作失败”）。审阅者应该能够从本节审查完整的 Schema 差异。

第 4 步 — 规划代码导览

这是简报的核心，也是最重要、最需要准确完成的部分。代码导览是一系列带编号的“站点”，逐步讲解这次变更，就像作者向同事介绍代码一样。核心理念借鉴了 Graphite Code Tours：不再要求审阅者在 PR 描述、评论和零散的差异之间来回滚动，叙述应与实际代码并列呈现，形成一条连续路径。每个站点都将简短的文字说明与所讨论的具体代码块配对，让审阅者无需切换上下文即可理解变更。

规划规则：

• 按理解顺序排列，而不是按文件排列。 如果在一个文件中定义新类型，并在另一个文件中使用它，应先讲定义，再讲使用者。沿着功能的流程展开。
• 较大的变更应按章节标题对站点分组。 平铺的 12 个站点很难浏览；将同样的 12 个站点分成 3 个章节标题（“后端服务”“工作流连接”“管理界面”），则一目了然。Graphite Code Tours 的 UI 采用这种层级结构——章节父项包含嵌套的子站点——简报也应与之保持一致。对于较小的变更（总计 ≤6 个站点），可以使用单一的平铺列表。
• 不要逐个讲解所有文件。 只讲解重要的文件——高风险范围、核心逻辑和任何细微之处。典型变更以 5–10 个站点为宜；如有帮助，可进行分组；微小变更可以更少，大范围变更可以更多（并分组）。如果你发现自己列出了 20 个未分组的站点，那就是把导览变成了文件索引——请重新确定优先级或进行分组。
• 一个站点 = 一个聚焦的想法。 一个站点通常围绕一个文件或函数展开，但如果三个小变更属于同一个想法，也可以合并讲解（“index.ts、types.ts、public.ts 中的类型重新导出——只是为新类型 Foo 添加连接代码”）。
• 每个站点都必须展示实际代码，而不只是谈论代码。选取承载含义的代码块（通常为 5–30 行），并删去周边无关内容。对于全新文件，展示有意义的片段，而不是整个文件。
• 解释原因，而不只是内容。 页面上的代码展示了变更内容，文字说明则补充其背后的理由——解决的问题、处理的边界情况，以及被否决的替代方案。如果说明除了重述差异之外毫无内容，那么这个站点就没有必要存在。
• 跳过样板代码，但要提及。 不要为每项导入变更都单独设置一个站点。在总结站点中顺带提及：“其余变更是类型重新导出和测试夹具。”

第 5 步 — 构建 HTML 单页文档

编写一个独立的 .html 文件——所有 CSS 都内联在 <style> 块中，不发起外部请求，不使用 JS 框架，也不获取字体。文件必须能够直接从磁盘打开。

结构优先级

页面内容虽多，但顺序必须严格固定——不得更改，即使你认为某项变更换一种顺序会更容易阅读。过去，重新调整顺序的简报（PR 堆栈被放到代码导览之后，以及单个 PR 的简报把 PR 编号藏在元数据网格中）都一再未能通过审阅。**只阅读首屏内容的审阅者必须看到：标题、模式、TL;DR、PR 堆栈，以及任何高风险提示。**其余内容向下滚动查看。

请严格按以下顺序排列各部分：

1. 主视觉区 — 精简扼要。 不超过首屏视口的约 1/4。
   • 标题行：分支 / 技术栈名称 + 醒目显示的模式标签 — 使用纯色背景、白色文字，字号大于正文（例如，DRAFT 用琥珀色，FINAL · review clean 用绿色，FINAL · 2 findings open 用红色）。读者隔着房间也应该能看出当前模式。低调的标签式标记不够醒目。
   • 一到两句话的 TL;DR。 这里不要写冗长的叙述段落，只写审阅者最需要了解的一件事。
   • 精简的水平元信息栏：主干、变更文件数、+/-、提交数、生成时间戳。
2. PR 堆栈 — 放在靠上位置，醒目且内容完整。 如果存在堆栈（已提议或实际存在），就放在这里，视觉上与其他内容区分开来，不要埋在四列元信息网格中。本节还应包含各 PR 的提交 / 发现历史 — 页面下方不再单独设置“PR 演变”一节。审阅者了解某个 PR 所需的所有信息 — 它是什么、包含什么、如何演变而来 — 都应放在其卡片上。采用纵向排列的 PR 卡片视觉堆栈效果很好，每张卡片都是一个小型复合内容块：
   • 标题行。 位置（1/3）、PR 编号 / 标识、单行摘要、变更规模（例如 +312 / −44 · 8 files）、状态标签（open / merged / draft）。在 FINAL 模式下，还要显示审阅状态标签（review-clean / 2 findings / 1 skipped）。
   • 提交时间线 — 卡片正文。 按时间顺序列出 PR 上的每个提交。每行显示：简短 SHA、等宽字体的主题，以及（FINAL 模式下）原因标签 — 基线提交标为 initial，后续提交标为 review finding / user steering / other（CI 修复、重新叠放导致的后续改动、润色）。对照审阅讨论串核对提交消息，以判定后续提交的原因；每个后续提交都必须标明原因。
   • 提交说明（如果作者写了）。 在提交主题行下方，以较小字号、弱化样式的正文显示提交消息正文（主题行之后的内容）。保留换行，但不要将其显示为代码。这是作者对该部分改动的说明，往往能传达仅看差异无法了解的原因。如果正文为空或只是套话，则省略 — 例如，重复主题内容的单行 Why:、AI 署名尾注、Co-Authored-By 行。默认应保持精简：仅展开能提供有用信息的正文，其余提交只显示主题。对于提交很多但有意义正文很少的 PR，这样自然会形成紧凑列表，只展开少数几行。
   • 跳过的审阅发现（FINAL 模式）。在卡片内以独立且视觉上鲜明的行显示 — 使用警告色，并附上发现摘要和跳过原因。这些发现属于 PR 历史，应放在其卡片上，而不是单独列在附录中。
   • 单个 PR 的简报仍需包含本节 — 显示一张包含完整时间线的 PR 卡片，而不是在元信息栏中隐藏一个数字。审阅者需要一目了然地知道“这是 PR #22，状态为 open，review-clean，共有三个提交，其中一个后续提交处理了发现 X”，而不必四处寻找。
   • 只有在确实还没有 PR 且没有已提议的堆栈时，才省略本节，并在 TL;DR 中说明一次（“仅工作树 — 尚未提议堆栈。”）。此时，在 TL;DR 下方以单个时间线块列出工作分支上的提交，使用相同的行格式，以免丢失提交正文。
3. 高风险提示。 使用小型彩色提示网格 — 端点、身份验证、架构、依赖项、配置、破坏性操作。每条提示用一到两行说明：涉及的范围、变更内容、需要留意之处。如果没有高风险变更，则显示一条中性提示说明这一点 — 没有变更也是一种信息。
4. 端点审计（当变更新增或修改了多个路由 / 服务端操作 / API 范围时）。使用专门的表格，而不是提示块；列为：Route / Inputs / Success behavior / Failure behavior / Side effect / Auth。每个端点占一行。此节应放在架构梳理之前，因为新增的接口范围通常是后端变更中风险最高的部分。如果变更涉及零个或一个端点，则跳过本节 — (3) 中的提示已足够。
5. 架构梳理（如有）。使用第 3 步中的逐行表格。
6. 代码导览。 使用第 4 步中的各个讲解点。这是页面的主要内容。讲解点超过约 6 个时，应按小节标题分组（见第 4 步）。每个讲解点都是一个小型复合内容块：
   • 讲解点编号 + 简短描述性标题（例如，3. 为删除路径添加行锁）。编号便于审阅者引用具体讲解点；描述性标题则便于浏览目录。
   • 等宽字体显示文件路径，另可添加“依赖于 / 调用方”标签。
   • 用 1–3 句话说明这段代码的作用及其重要性。
   • 内嵌代码或差异片段 — 见下方的呈现规则。没有代码的讲解点没有存在的必要；应补充代码，或将其并入其他位置的说明。
   • 可选：生命周期 / 流程图，用于引入多步骤状态机的变更（购买 → 授予 → 消耗；排队 → 丰富内容 → 发布；草稿 → 审阅 → 批准）。使用内联 CSS 将其呈现为带箭头的水平方框序列 — 不使用 SVG，也不使用 JS。每份简报最多一张流程图；它应放在相关讲解点内，而不是作为单独章节。
   • 对于包含 8 个或更多导览点的简报，添加粘性导览目录。 在左侧放置 position: sticky 栏（或在较窄视口中放置顶部锚定的小型导航），列出每个导览点标题，并添加 #anchor 链接。通过缩进子项，使其归属的小节一目了然。不使用 JS — 只用粘性 CSS 和命名锚点。这样才能方便地浏览 Graphite 的代码导览；如果没有它，较长的简报就只能线性滚动阅读。
7. 文件索引。 精简，放在底部。每个文件一行，并附上一句描述。生成的文件也可以列在这里。

渲染行内代码和差异（无 JS、无字体）

导览步骤必须展示真实代码，而非伪代码或意译。采用简单的手工实现方式——不使用语法高亮库：

• 使用 <pre><code> 包裹代码片段，并设置等宽字体栈。
• 对于差异片段，根据每行开头的 +、- 或空格字符，使用 <span class="add">、<span class="del"> 或 <span class="ctx"> 包裹每一行；CSS 会为每个类设置柔和的绿色、红色或中性色背景，并铺满整行。
• 可以选择将 @@ 块头行包裹为 <span class="hunk">（使用弱化颜色）。
• 对于非差异的源代码（用于说明上下文的函数或类），使用单个 <pre><code> 块，不添加逐行类；只需采用等宽字体和中性面板背景。
• 在代码片段上方显示文件路径，不要将它放在代码片段内。每个导览步骤中的代码片段应保持适度简短——5–30 行。如果函数较长，则展示有意义的代码块，并用文字说明省略的部分（“……省略参数验证……”）。
• 在代码块之间使用未更改区域标记，就像 Graphite Code Tours 那样。当同一文件中两个不连续的代码块都属于一个导览步骤时，请使用类似 ↕ 12 lines unchanged 的样式化标记将它们分隔开，单独占一行（弱化颜色、虚线边框、较小字号）。这样，一个导览步骤就能展示长文件中的两处代码，而不会伪装成连续内容，也能明确告知评审者省略了多少行代码。
• 长词元换行：在代码块上使用 white-space: pre-wrap; word-break: break-word;，避免过长的行撑破布局。

视觉设计

这会展示给经理看，因此要有明确的设计感，而不是千篇一律：清晰的字体层级、有目的地使用颜色（优先级、严重程度、评审状态、添加/删除）、代码和路径使用等宽字体，并保持舒适的留白节奏。页面最大宽度控制在 1100–1200px 左右。如果有 frontend-design 技能，请参考其原则。

主视觉区域必须保持精简——不要忍不住塞满卡片。大部分视觉重点应放在 PR 堆栈 和 代码导览 上。

步骤 6 — 保存、打开并自检

将文件保存到仓库根目录下的 .briefs/ 目录中。命名方式：

• DRAFT 模式使用 draft-brief-<slug>.html。
• FINAL 模式使用 final-brief-<slug>.html。

<slug> 为分支名称或简短描述此次变更内容的标识，确保文件不会与其他工作的简报重名。确保 .briefs/ 已添加到版本控制忽略规则中，避免提交简报——优先使用本地、未提交的忽略规则，而不是修改已跟踪的 .gitignore。然后在用户的浏览器中打开简报。

交付前，请根据简报的用途进行检查：

• 只阅读首屏内容的审阅者，能否说出所有高风险变更，并看出 PR 堆栈？
• 模式标记在视觉上是否足够醒目，让人一眼就能分辨 DRAFT 和 FINAL？
• TL;DR 是否只有一到两句话，而不是一整段？
• 是否包含 PR Stack 部分（即使只有一个 PR），且位于高风险提示之前？
• 每张 PR 卡片中，是否呈现了作者所写的提交消息正文；如果没有正文，是否没有显示空的正文块？
• 是否严格遵循章节顺序（Hero → PR Stack → High-stakes → Endpoint Audit → Schema → Code Tour → File Index）？
• Code Tour 中的每个讲解点是否都展示了实际代码（差异或源代码），而不只是描述？
• 讲解顺序是否按理解逻辑排列，而非按文件名排列？
• 是否逐行说明了每项 Schema 变更？
• （FINAL）每张 PR 卡片中，是否都为每个后续提交标明了原因，并将每条跳过的发现放在单独的警告色行中——全部放在卡片内，而不是单独放进演进章节？
• 是否声称存在实际不存在的堆栈／审阅章节，或遗漏了实际存在的章节？
• 检查整个堆栈中的孤立项。 对每张 PR 卡片，列出其引入的顶层新函数／组件／导出，然后确认每项都至少有一个调用方位于同一 PR 的差异中。将任何孤立项（在 PR N 中引入、首次在 PR N+1 中使用）作为警告色行列在引入它的 PR 卡片上——这意味着该 PR 提前添加了代码，应将该符号移到首次使用它的 PR 中。如果渲染了 mermaid／依赖图来展示堆栈，孤立节点会表现为没有来自堆栈中其他内容的入边；请明确指出这些节点。
• 是否有内容冗长？精简它。

然后告知用户简报已准备就绪、保存位置以及所选模式。