Simon Willison：把智能体写的冗长 PR 描述折叠进 details/summary 折叠块，开头只留一段人写的导语

如今我对自己项目做的大多数改动，都是由 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>

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

我已经开始在 AI 生成的 PR 上这么用了。

我的 PR 开头一段会精心挑选，作为对整体情况的高层说明：一个人能读完、又能帮他快速了解情况的最短文字。

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

接下来，智能体写的完整长文放进一个 <details> 里。我用模型名，通常还加上推理强度作为 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> 元素必须把其余所有内容包起来。

更好的技巧是，永远把这两个标签叫作「details-summary」。

「details-summary」是两个音节接三个音节，念起来比「summary-details」那种三加二的节奏顺口得多。

把「details-summary」大声念几遍，你就再也不会忘记标签的顺序了。

（我仍然希望 GitHub 能在 Markdown 编辑器里为此加一个按钮：一方面省得我在手机键盘上费力地敲，另一方面也能让更多 GitHub 用户知道有这个功能。）