Simon Willison 用 <details><summary> 折叠 AI 生成的 PR 描述

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 会隐藏 details 内容，只显示 summary 和一个展开箭头。

我已经开始把它用在我那些 AI 生成的 pull request 上了。

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

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

随后，智能体写的完整长文会放在一个 <details><summary> 里。我用模型名称（通常还有努力程度）作为 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 用户知道这个功能的存在。）