[控场AI]
· 6 分钟阅读· 3,292 字

用details/summary折叠AI生成的PR描述

用details/summary折叠AI生成的PR描述

用 details/summary 折叠 AI 生成的长 PR 描述,只留人类判断的短引言。

Simon Willison 发现,Claude Code、Codex 等代理自动生成的 PR 描述虽然准确完整,却因结构工整、面面俱到而触发读者的「AI 味」防御心理,让人不愿读完。他的解法是利用 GitHub Markdown 原生支持的 `<details><summary>` 标签,把 AI 生成的长描述整体折叠,只在最外层保留一段简短引言,传达人类编辑的判断:这个 PR 做什么、值不值得细看。引言可以摘自代理文本,但必须代表人类筛选。summary 中标注模型与 effort 等级以标明来源。文章还给出记忆标签顺序的技巧,并将此概括为一种可迁移的分层信息披露协作模式。

当AI写的PR描述好到让人不想读

Simon Willison 最近分享了一个小技巧:把 AI 生成的冗长 PR 描述塞进 HTML 的 <details><summary> 标签里,只保留一段人类撰写的简短引言。这看似是个排版小花招,背后却触及了人机协作中一个微妙的心理边界——AI 写得太完整,反而让人失去阅读欲望。

据他在博客中的描述,如今项目里的大部分代码变更都由 Claude Code 或 Codex 直接开 PR。这些代理在撰写 PR 描述上表现相当出色:问题背景、解决方案、验证步骤一应俱全。但问题恰恰出在「太出色」上。

"It's not necessarily slop, but it reads like slop!"

这段评论点出了一个关键区别:内容未必是低质量的(slop 通常指粗制滥造的内容),但它的呈现方式——结构化的长段落、面面俱到的论证、滴水不漏的标题层级——会立刻触发读者「这是 AI 写的,我不想读完」的防御心理。Willison 说,哪怕驱动这个 PR 的人是他自己,他也会本能地抗拒阅读。

读者想要的是编辑判断,不是信息堆砌

Willison 的诉求很明确:他想要的是人类编辑的判断力。具体来说,他需要的是一段经过人脑压缩的引言,在高层次上解释这个 PR 是干什么的、值不值得投入更多注意力。

这其实揭示了一个容易被忽略的协作断层:AI 擅长生成完整信息,但人类读者需要的往往不是完整,而是优先级。哪些是重点、哪些可以跳过、哪些需要仔细看——这些判断目前仍然依赖人类来完成。

PR 即 Pull Request(拉取请求),是 GitHub 等代码托管平台的核心协作机制:开发者在一个分支上完成修改后,通过 PR 请求将改动合并进主分支,同时附上描述说明改了什么、为什么改、如何验证。PR 描述因此既是代码审查的入口,也是团队沟通的载体。在 AI 编程代理普及之前,PR 描述通常由提交者手写,篇幅偏短、重点突出;而当 Claude Code、Codex 这类代理自动开 PR 后,描述文本量显著膨胀,这也正是文中「阅读防御心理」问题的直接来源。

details/summary 折叠方案的具体做法

解决思路很直接:利用 GitHub Markdown 支持的 <details><summary> 标签,把 AI 生成的长篇描述折叠起来。

details/summary标签折叠效果示意

HTML 结构是这样的:

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

关键点在于:GitHub Markdown 原生支持这个标签。你可以直接把它写进 PR 描述或 issue 评论,GitHub 会自动把 <details> 里的内容折叠,只显示 <summary> 中放的那行文字和一个展开箭头。

Willison 的实际用法是:

  1. PR 开头放一段精心挑选的引言,作为高层次解释——用最短的文字帮读者快速进入状态。
  2. 有时附上一张截图,因为图片往往是快速展示新功能的最佳方式。
  3. 把完整的 AI 生成描述整体塞进 <details><summary>。
  4. <summary> 里放模型名称和 effort 等级,比如 "Claude Opus 5.5 Medium",让读者一眼看清这段折叠内容的来源。

引言由谁写?

有意思的是,Willison 并不总是自己写引言。有时候代理在大量文本中已经产出了他需要的内容,他只是把它挑出来放到折叠区外面。但他对读者的承诺是:这段短引言代表的是他作为人类的判断——确保这里的信息值得读者花时间。

这种模式在他最近的几个 PR 里都有体现:

  • datasette PR #3052 的引言解释了为什么把行页面从单行表格改成垂直字段列表——宽表(比如 46 列的 GitHub repos 表)会横向滚动出屏幕,导致页面大片空白。
  • datasette PR #3042 的引言直截了当:edit-tools.js(约 220KB)原先在每个表格、行和数据库页面都会加载,现在改成仅在用户与编辑功能交互时才加载。
  • llm PR #1838 的引言用一句话说明了命令的用途,随后附上 --help 输出。

这些引言的共同特征是:短、具体、有判断。它们不是对 AI 描述的摘要,而是人类重新组织的切入点。

<details> 与 <summary> 是 HTML5 原生的交互式披露元素,并非 GitHub 专有扩展。浏览器默认将 <summary> 渲染为始终可见的标题行(带展开/折叠三角),其余子内容在折叠状态下隐藏,点击即展开,无需任何 JavaScript。GitHub 的 Markdown 渲染器允许内联原始 HTML,因而这一元素可以直接写在 PR 描述、issue 和评论里。需要注意的是,<details> 内部嵌套的 Markdown 通常需要在 HTML 块前后留空行才能被正确解析,且折叠状态不会影响搜索引擎或页内查找的可见性逻辑。

记忆标签顺序的小技巧

Willison 坦言自己之前总记不住这两个标签的顺序——到底是 <details><summary> 还是 <summary><details>。他分享了两个办法:

第一个是语义上的:<summary> 明显是用来概括内容的那一行,所以它应该在里面;<details> 则包裹其余所有内容。

第二个办法更实用:始终把这组标签念作 "details-summary"。两个音节加三个音节的节奏比 "summary-details" 的三加二更顺口。多念几遍就不会再搞混。

他还提到一个遗憾:希望 GitHub 能在 Markdown 编辑器里加个按钮,一键插入这组标签。一来省去在手机键盘上手动敲的痛苦,二来也让更多 GitHub 用户知道这个功能的存在。

一个可迁移的协作模式

这个技巧的价值不限于 PR 描述。它本质上是一种分层信息披露策略:把机器生成的海量细节收进可展开的容器,把人类判断的精华留在最外层。

在 AI 代理越来越多地承担内容生成任务的今天,读者对「AI 味」的敏感度也在上升。Willison 的做法提示了一个方向:与其让 AI 写得更像人,不如让人类保留最后的编辑权,把 AI 的输出降级为「可选的深入阅读材料」。这样既保留了信息的完整性,又尊重了读者的注意力预算。

他在博客结尾写道:"My PRs don't feel nearly as sloppy now!"——信息全都还在,但读者可以扫一眼就获得人类筛选过的核心内容,不必对着好几段代理生成的细节眼神放空。

「分层信息披露」(progressive disclosure)是交互设计与技术写作中的经典原则:先呈现最关键的信息,把细节按需展开,以降低认知负荷。它常见于设置面板的高级选项、API 文档的示例折叠、以及 Nielsen Norman Group 提出的可用性准则中。Willison 的做法把这一原则从界面设计迁移到了协作文本:AI 负责生成完整细节层,人类负责提炼摘要层,读者按注意力预算自行决定下探深度。相较于单纯压缩 AI 输出长度,分层保留了信息完整性,同时把「读多深」的控制权交还给读者。

#details summary 标签#GitHub PR 描述#AI 生成代码#coding agents#AI 编程协作#Markdown 折叠#PR 描述优化
分享:

相关推荐