把 AI 生成的冗长 PR 描述藏进 `<details><summary>` 标签

2026年11月9日

如今我对项目所做的大部分改动，都是以 Claude Code 或 Codex 为我提交的 PR 形式出现的。PR 是我的工作单元——我用它把提交打包在一起，反复迭代直到功能完成，记录决策，然后合并最终结果。如今的编码智能体非常擅长撰写 PR 描述。

它们太擅长描述工作了

问题在于它们太擅长了。智能体撰写的 PR 描述准确而全面。它描述了问题、详细的解决方案以及为验证所采取的步骤。要吸收的信息太多了。

它未必是垃圾内容，但读起来像垃圾内容！

AI 撰写的 PR 很容易辨认，和其他形式的 AI 写作一样，我的第一反应可以概括为“我才不会把那些全读完”。无论信息多么准确或有用都无所谓，一想到我读它花的时间会比驱动它的作者写它花的时间还长，我就立刻没了兴致……即使那个驱动作者就是我自己！

我想要人类的编辑判断。我希望有人对 PR 思考了足够长的时间，给我一个经人类认可的引言，帮助我从高层次理解这个 PR 是做什么的，以及它是否值得我投入更多注意力。

我想我找到了一种省力又感觉合适的方法。

把大部分内容藏在 details/summary 里

HTML 的 <details><summary> 元素会渲染成一个折叠的标题（即 summary），展开后可以查看更长的文本。代码如下：

<details>
  <summary>Claude Opus 5.5</summary>
  <h2>The hook</h2>
  Plugins implement <code>register_agent_reference_types(datasette)</code>...
</details>

渲染后，它看起来像这样：

Screenshot of a GitHub PR. The text "Claude Opus 5.5" sits next to a little black arrow. Clicking on that text expands a full description inside the PR body.

关键在于，<details><summary> 在 GitHub Markdown 中受支持。你可以把这些标签直接放进 issue 评论或 PR 描述中，GitHub 会隐藏详情，只显示 summary 和一个展开箭头。

我已经开始在我由 AI 生成的 pull request 中使用这一做法。

我的 PR 开头段落会经过精心挑选，作为对整体情况的高层次说明——这是人类能读到的最短文本，能帮助他们快速了解情况。

我有时还会附上一张截图，因为图片通常是快速展示新功能的最佳方式。

随后，完整的智能体撰写的长文会放在一个 <details><summary> 中。我用模型名称、通常还有 effort 级别作为 summary，让人一眼就能看清情况——例如“Claude Opus 5.5 Medium”。

我的 PR 现在感觉没那么潦草了！信息仍然都在，但读者可以扫一眼就获得顶部的、由人类筛选过的信息，而不会因为好几段智能体撰写的细节而眼神呆滞。

引言并不总是我自己写的——有时智能体已经给了我需要的内容，只是藏在大量其他文本之中。我对读者的承诺是，简短的开头将代表我作为人类的判断，说明什么才真正值得他们花时间。

以下是我最近使用这一模式的一些例子，包括我使用的开头：

datasette PR #3052：将行页面重新设计为字段的垂直列表——“行页面将其单行显示为单行表格。对于宽表格，比如一个 46 列的 GitHub repos 表格，它会向右滚动很远，导致页面大部分空白。”（然后是一张截图）
datasette PR #3043：显示当前页包含哪些行的分页栏——“跨越多页的表格页面现在能清楚地显示你所在的位置，并在页面顶部和底部都提供导航。”（外加截图）
datasette PR #3042：通过一个小型加载器按需加载 edit-tools.js——"edit-tools.js（约 220KB）此前会在每个表、行和数据库页面上加载，即使是对那些无法编辑任何内容的用户也是如此。现在只对有权编辑的用户加载，并且是在他们首次与编辑功能交互时（包括鼠标悬停在编辑链接上）才加载。"
datasette-agent PR #51：register_agent_reference_types 插件钩子——"让插件可以通过一个新的 register_agent_reference_types(datasette) 插件钩子，在聊天编辑器的 # 标记中添加它们自己的条目类型。"——如上图所示。
llm PR #1838：添加 llm openai endpoint add/list/remove/path 命令——"添加了用于管理 extra-openai-models.yaml 中记录的命令，这样 OpenAI 兼容端点就可以从命令行保存，而不必手动编辑 YAML。"——随后复制了 --help 的输出。

这个助记法

我以前总是记不住这两个标签的顺序——到底是 <details><summary> 还是 <summary><details>？

有两个技巧帮到了我。

首先，也是最明显的一点，<summary> 显然就是用来概括细节的那部分。那是你那段可点击展开的文字所用的标签——那么 <details> 元素就必须包裹其他所有内容。

一个更好的技巧是，始终把这两个标签称作“details-summary”。

“details-summary”是两个音节加三个音节。它比“summary-details”那种三加二的节奏更顺口。

把“details-summary”大声念上几遍，你就再也不会忘记这两个标签的顺序了。

（我仍然希望 GitHub 能在他们的 Markdown 编辑器里为此加一个按钮——一部分是为了省去我在手机键盘上费劲地输入，一部分也是为了帮助向更多 GitHub 用户传播这个功能的存在。）