Simon Willison 分享用 details/summary 折叠 AI 生成的 PR 描述

Simon Willison 博客·2026-11-09 12:25· 1 小时前AI 评分72

把那些垃圾 PR 描述藏到 <details><summary> 后面

AI 导读

Simon Willison 介绍自己用 GitHub Markdown 支持的 <details><summary> 标签折叠 Claude Code 或 Codex 写的冗长 PR 描述的做法。折叠区标题写明模型名和档位（如 Claude Opus 5.5 Medium），开头保留一段人工撰写的高层摘要，并给出多个 datasette 和 llm 仓库的 PR 实例。

正文 · 原文

如今我对项目所做的大部分改动，都是以 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>

渲染出来像这样：

关键在于，<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 用户传播这个功能的存在。）

标签：github、html、markdown、ai、generative-ai、llms、ai-assisted-programming、coding-agents

来源：Simon Willison 博客 · simonwillison.net