返回探索
资讯VibeFix 内容整理更新于 2026年11月17日

Simon Willison 的新习惯:把 AI 写的 PR 描述藏进折叠块,只留一句人话

2026 年 11 月 9 日,Simon Willison 分享了一个小习惯:PR 描述顶部只留一段自己审过的人话开头,Agent 写的完整长文收进 GitHub 原生支持的 <details><summary> 折叠块,标题注明模型名与推理强度。信息一分没少,评审者却不用再被长文劝退。五个真实 PR 已经在用,模板可以直接抄。

Simon Willison 博客原文配图:GitHub PR 页面截图,上方是他亲手写的简短开头,下方是一行可点击展开的“Claude Opus 5.5”折叠标题,完整 AI 描述藏在折叠块里。

2026 年 11 月 9 日,Simon Willison 在自己的博客上分享了一个很小的工作习惯:他开始把 AI 生成的 PR 描述藏进 HTML 的

折叠块里,只在 PR 顶部留一段自己审过的人话开头。这个做法没有新工具、没有新流程、不用花一分钱,用的只是 GitHub Markdown 早就支持的原生功能。但它戳中了一个正在变大的痛点——AI 写 PR 描述已经写得太好了,好到没人愿意读。

Simon Willison 博客原文配图:GitHub PR 页面截图,上方是他亲手写的简短开头,下方是一行可点击展开的“Claude Opus 5.5”折叠标题,完整 AI 描述藏在折叠块里。

先说结论:问题不是 AI 写得差,是写得太多了

Willison 的处境很有代表性。他说,自己现在大部分改动都是以 PR 的形式来的,而且 PR 往往是由 Claude Code 或者 Codex 代他开出来的。PR 是他的工作单元:他用 PR 把一批提交打包在一起,反复迭代直到功能完成,顺带把决策过程记录下来,再合入主分支。而今天的编程 Agent 写 PR 描述写得相当出色:描述准确、内容全面,既讲清楚问题是什么,又讲清楚解决方案的细节,还会列出验证步骤。按理说,这应该是一件好事。

可 Willison 的判断很直接:问题恰恰出在它们写得太好了。一份 Agent 写的 PR 描述,动不动就是好几段结构工整的长文,标题、列表、代码引用一应俱全。内容没错,但读起来就是累。他的原话说得很坦白:这东西未必是 slop,但读起来像 slop。只要一眼认出这是 AI 写的,第一反应就是“我可读不完这个”。不管里面的信息多准确、多有用,读者在点开的那一瞬间就已经被篇幅吓退了——读它要花的时间,感觉比写它的作者花的时间还长,哪怕那个作者就是他自己。

这个判断值得认真对待。因为它点破了一个容易被忽略的真相:PR 描述的第一职责不是记录,而是说服。说服评审者花时间看下去。写得再全,如果开头就把人劝退了,后面写的一切都等于不存在。AI 写作的问题在这里不是质量问题,而是篇幅和节奏问题:它不知道什么时候该停,也不知道读者最需要先知道什么。它把所有信息平铺在你面前,等于把筛选的成本全部推给了读者。

Willison 想要的东西也很明确:人类编辑判断。他希望有人——哪怕只是花一点点时间想一想——先替他把 PR 的来龙去脉提炼成一句人话:这个 PR 是干什么的,值不值得你多花注意力。不是更长的总结,而是更短的判断。有了这个开头,读者才能决定:只看这一句就够了,还是值得点开展开看全文。

他的做法:三句话讲清这个套路

做法本身简单到可以一句话说完:PR 描述的开头,只留一段经过人工挑选的高层说明;Agent 写的完整长文,整个塞进一个

折叠块;折叠块的标题写上模型名和推理强度,比如“Claude Opus 5.5 Medium”。三句话,就是全部。

具体长什么样,Willison 在博客里给了代码示例。PR 顶部是他挑出来的一小段说明文字,有时候还会配一张截图,因为图片往往是展示新功能最快的方式。紧接着就是折叠块:

标签包住全部 Agent 原文, 标签里只写模型名。渲染出来之后,读者看到的首先是一段简短清晰的人话开头,下面跟着一行带小三角箭头的“Claude Opus 5.5”,点一下才展开全文。没点开之前,整个 PR 看起来清爽得像人手写的。

这里有两个细节很见功力。第一,开头那段话不一定是他自己写的。有时候 Agent 在长篇大论里其实已经给出了他想要的那句话,只是埋在一大堆文字中间——他要做的只是把它挑出来、放到最前面。也就是说,他并没有增加多少工作量,只是把“写”这件事换成了“挑”这件事。判断的成本很低,但判断的价值很高。第二,折叠块的标题不是随便写的装饰,而是诚实的标注。读者一眼就能知道:下面这段是哪个模型写的、用了多大的推理强度。这是一种体面的透明:AI 写的东西没有被藏起来冒充人话,也没有被删掉假装不存在,它只是被放到了合适的位置。

Willison 说,用上这个办法之后,他的 PR“感觉没那么 sloppy 了”。信息一点没少,读者却可以先扫一眼人话开头,迅速抓住重点,不用一上来就被好几段 Agent 长文糊一脸。这种体验上的变化,靠的不是什么高深的技术,而是一个简单的版式决定:重要的先说,详细的后放,想看的人自己点开。

五个真实例子:这不是空想,是已经在用的工作流

Willison 不是只讲道理,他在博客里直接贴了五个已经用上这个套路的真实 PR,全部来自他自己的项目,读者可以逐个点开验证。这一点很重要:一个工作习惯值不值得学,首先要看提出它的人自己是不是真的在用。

第一个是 Datasette 的 PR #3052:把行详情页从单行表格改成纵向字段列表。开头只讲了一句人话——原来的行详情页把单行数据画成一张一行多列的表格,遇到 46 列的宽表就会横向滚出很远,页面大半是空白。下面配了一张截图。至于具体怎么改的、每个字段的复制按钮和空值样式怎么处理,全部收进折叠块里。这个 PR 在 2026 年 11 月 8 日已经合入,读者现在去 GitHub 上还能看到它当时的样子:顶部就是那两句人话开头。

第二个是 Datasette 的 PR #3043:给分页栏加上当前页位置提示。开头一句话:跨页的表格现在能一眼看出自己在哪一页,页面顶部和底部都有导航。第三个是 PR #3042:让 edit-tools.js 按需加载。原来这个约 220KB 的脚本会在每个表格页、行页和数据库页都加载,哪怕用户根本没有编辑权限;改完之后,只有当有编辑权限的用户第一次与编辑功能交互时才加载。开头把“原来怎么浪费、现在怎么省”讲清楚就够了,具体的触发条件和细节同样折起来。

第四个是 datasette-agent 的 PR #51:新增 register_agent_reference_types 插件钩子,让插件可以给聊天框里的井号标签增加自己的引用类型。第五个是 llm 的 PR #1838:给 llm openai endpoint 增加 add、list、remove、path 四个子命令,让 OpenAI 兼容端点的配置可以从命令行管理,不用再手改 YAML 文件。五个例子覆盖了界面改版、性能优化、插件机制和命令行工具,说明这个套路不是只适合某一类改动,而是通用的。

值得注意的是,这五个 PR 的改动本身都不小,有的还涉及架构层面的新钩子。但 Willison 给每个 PR 的开头都只留了一两句话。这种克制是有意的:开头不是摘要,而是判断——判断读者最需要先知道什么。摘要是把全文缩短,判断是替读者决定阅读顺序。两者看起来像,效果差很远。

为什么偏偏是 details 和 summary

这个套路能成立,有一个前提:GitHub 的 Markdown 原生支持

和 。你可以直接把这两个 HTML 标签写进 PR 描述或者 issue 评论里,GitHub 会把它渲染成一个默认折叠的区块,标题旁边带一个展开箭头,点一下就展开。区块里面可以放标题、文字、图片、代码块,什么都不缺。GitHub 官方文档里专门有一页讲这个功能,名字就叫“用折叠区块组织信息”,还说明了可以加 open 属性让区块默认展开。

也就是说,Willison 没有发明任何东西,他只是把一个早就存在、但很多人不知道或者想不起来用的功能,放到了一个正好需要它的地方。这个选择的聪明之处在于零成本:不用装插件、不用改工作流、不用等 GitHub 上线新功能,任何人打开 PR 编辑框就能用。今天就能用,明天团队里的每个人都能学会。

相比之下,市面上很多“解决 AI 写作泛滥”的方案都要重得多:有人提议用检测工具给 AI 内容打分,有人主张在流程里加一道人工重写关卡,有人干脆规定 PR 描述不许用 AI 写。这些方案要么增加工具成本,要么增加人力成本,要么在和现实对着干——Agent 已经在写了,而且越写越好,拦是拦不住的。Willison 的做法绕开了所有这些对抗:不拦、不删、不重写,只是换个位置放。AI 继续写它擅长的长文,人类只负责在最前面加一句判断。分工没变,阅读体验变了。

还有一个容易被忽略的优点:这个做法对读者是诚实的。折叠块的标题直接写明模型名,等于在 PR 里留了一个清晰的 provenance:上面是人审过的判断,下面是 AI 写的全文。读者不会被误导,也不会在读到一半才发现“原来这段是 AI 写的”。在 AI 生成内容越来越多的今天,这种标注本身就是一种信用建设。

这招好在哪:信息一分没少,负担少了一大半

最容易误解这个做法的一点,是以为它在“藏”东西。不是的。折叠起来的内容没有消失,也没有降级,任何人点一下就能看到全文,搜索也能搜到。对于真正需要了解细节的评审者——比如要接手这块代码的人、要复核验证步骤的人——信息完整地保留在原地。这个做法压缩的不是信息量,而是第一眼的信息量。

这正是它高明的地方。它承认了一个现实:不同读者对同一份 PR 描述的需求是不一样的。路过的同事只需要知道“这个 PR 是干什么的”;负责合入的维护者需要知道“改动安不安全”;未来的自己需要知道“当时为什么这么改”。一份平铺直叙的长文试图同时满足所有人,结果是谁都读得累。Willison 的分层做法让每个人各取所需:只想了解大概的人看开头就走,想深挖的人点开展开看全文。

更深一层看,这个做法其实是在修复 AI 写作和人类阅读之间的节奏错位。AI 写东西没有边际成本,一口气能写几千字;人类读东西的注意力却是稀缺品,打开一个页面先扫一眼,觉得值得才继续。以前是人写人读,篇幅天然受限于作者的体力;现在是 AI 写人读,篇幅失去了天然的刹车。Willison 的折叠块,就是给 AI 的篇幅重新装了一个刹车——不是限制它写,而是限制它第一时间展示。

对 vibe coding 的实践者来说,这一点尤其值得琢磨。很多人现在的工作流和 Willison 很像:让 Claude Code 或者 Codex 去改代码、开 PR,自己负责审和合。PR 描述是这条流水线里最容易被忽视的一环——代码审得很细,描述却直接放行。结果就是仓库里的 PR 描述越来越长、越来越像,评审者越来越不想点开。Willison 的做法等于给这条流水线补上了一个轻量的人工关卡:合入之前,先想清楚一句话——这个 PR 到底是干什么的。想不清楚这一句,就说明自己对这次改动的理解还不够,折叠也救不了。

别急着照搬:四条边界要先想清楚

这个套路虽好,但它不是万能的。照搬之前,有四条边界值得先想清楚,否则很容易把它用歪。

第一,折叠不是遮丑。如果 Agent 写的描述本身质量差——事实有错、逻辑混乱、验证步骤是编的——把它折起来并不能解决问题,只是把问题藏到了一个需要点一下才能看到的地方。Willison 的做法成立的前提,是 Agent 的描述本身准确全面,只差一个人类判断的开头。如果你的 Agent 经常写错东西,先修提示词和工作流,别指望折叠块来兜底。折叠只能解决“太长”,解决不了“太错”。

第二,折叠起来的内容会“过期”。PR 在评审过程中会反复修改,代码变了,描述却不一定跟着变。平铺的长文至少一眼能看到哪里对不上,折起来的长文更容易被人忽略,最后变成一份和最终代码不符的存档。Willison 的五个例子都是很快合入的小步 PR,漂移的风险比较小。如果你的 PR 要经历多轮评审、改动幅度大,最好在合入前把折叠块里的内容也过一遍,或者干脆在开头那句人话里写清楚“描述以最新提交为准”。

第三,别把真正重要的东西也折进去。开头那句人话应该包含评审者必须知道的关键信息:如果这次改动有破坏性变更、有安全影响、有迁移成本,这些话必须放在折叠块外面。折叠块里放的是“想了解更多的人再看”的细节,不是“不希望别人看到”的内容。拿折叠来藏风险提示、藏已知问题,是对评审者的不诚实,也是对自己仓库的不负责。Willison 的开头之所以可信,恰恰是因为他承诺:短开头代表他的人类判断,是“一定值得你花时间”的部分。这个承诺一旦被滥用,整个套路就失效了。

第四,操作上还有一点小摩擦。Willison 自己也在博客结尾许愿:希望 GitHub 能在 Markdown 编辑器里加一个一键插入折叠块的按钮。一方面是他经常在手机键盘上一个个字母敲出这些标签很麻烦,另一方面也是希望更多 GitHub 用户知道这个功能存在。也就是说,这个套路目前还依赖人手写 HTML 标签,没有顺手的工具支持。团队如果要推广,最好把它写进 PR 模板或者贡献指南里,再配一段可以直接复制的代码片段,降低每个人的上手成本。顺带一提,评论区里还有人提醒了一个技术细节:</summary> 后面要空一行,否则折叠块里的 Markdown 可能渲染不出来——照抄模板时别漏了这一行。

落到你的仓库:一个可以直接抄的模板

如果你也想在自己的项目里试试,这个套路的落地成本几乎为零。不需要改任何配置,只需要约定一个格式。下面是一个可以直接放进 PR 模板或者团队文档里的写法:

最上面写一到三句话的人话开头:这次改动是干什么的、为什么要做、有没有需要评审者特别注意的地方。能配截图就配一张截图,尤其是界面类改动,一张图顶得上三段话。然后空一行,写折叠块:<details> 开头,<summary> 里写模型名和强度,比如“Claude Opus 5.5 Medium”或者“Codex High”,空一行,再把 Agent 生成的完整描述原样贴进去,最后以 </details> 收尾。

更进一步,还可以在 Agent 的提示词里加一条规则:让它在输出 PR 描述的时候,主动把“给人看的一句话开头”和“完整版”分开写。这样人类挑选开头的成本更低,基本上就是从它给的候选里挑一句、微调一下就能用。Willison 的做法里已经有这个意思——他有时候直接用 Agent 长文里现成的一句话当开头。把这条写进提示词,等于把“挑”这个动作也半自动化了。

团队推广的时候,建议先从维护者自己的 PR 开始。Willison 本人就是这么做的:他先在自己的 Datasette 和 llm 项目里用起来,贴出真实例子,再写博客讲清楚为什么。维护者先示范,贡献者跟着学,比在贡献指南里写十条规定都管用。等大家习惯了,再考虑把它写进 PR 模板,让新来的贡献者第一次提 PR 就知道这个格式。

还有一个值得参考的对照:就在 Willison 写这篇博客的同一年,另一位工程师 Kenton Varda 选择了相反的做法——直接禁止团队在 PR、提交信息和工单里使用 AI 生成的描述。他的理由是,AI 描述重复的都是代码里已经能看到的细节,却漏掉了更高层次的背景和意图。Willison 没有反驳这个判断,他只是给出了一个更温和的答案:AI 的长文可以留着,但要先过一道人类判断。禁令适合对描述质量要求极高的团队,折叠适合大多数想在效率和可读性之间找平衡的团队。两条路没有对错,只有适不适合你的团队。

一个口诀,和一个更值得琢磨的判断

Willison 在博客结尾还分享了一个记忆口诀。他以前总记不住两个标签的顺序,是 <details><summary> 还是 <summary><details>。后来他想明白了两个诀窍:第一,summary 的意思就是“总结细节”,所以 summary 是那行可以点击的标题文字,details 是包住其余所有内容的外层;第二,两个词连起来念“details-summary”,是两个音节加三个音节,比反过来念要顺口。多念几遍,就再也不会记错顺序了。

这个口诀本身很小,但它透露出 Willison 写这篇博客的态度:他不是在发布一个宏大的方法论,只是在分享一个让自己每天工作更顺手的小习惯。这种“小习惯体”的写作,恰恰是他的博客多年来受欢迎的原因——不贩卖焦虑,不堆砌概念,只讲自己真的在用的做法,附上真实的例子,让读者自己判断要不要学。

而这篇博客更值得琢磨的地方,其实不在技巧本身,而在它背后的判断:AI 写作的泛滥,最终会倒逼人类重新重视“编辑”这件事。写东西的成本塌了,读东西的成本没塌,于是筛选、提炼、判断这些编辑动作反而变得更值钱。Willison 的折叠块,本质上是把编辑判断放到了最显眼的位置——先给结论,再给全文。PR 描述是这样,AI 生成的文档、报告、总结又何尝不是这样。以后我们要学的,可能不是怎么写得更多,而是怎么在前面加一句值得别人读下去的人话。

写在最后:AI 时代的 PR 礼仪正在成形

把视野放宽一点看,Willison 这个小习惯出现的时间点很有意思。2026 年,Claude Code、Codex 这样的编程 Agent 已经成了很多开发者的日常工具,PR 描述由 AI 代笔正在从新鲜事变成常态。随之而来的问题也很现实:评审者每天要面对的 AI 长文越来越多,耐心却没有跟着变多。有人选择禁止,有人选择放任,Willison 选择了第三条路——承认 AI 长文的价值,但用人类的判断给它加一个入口。

这条路的意义不止于 PR 描述。它其实在回答一个更大的问题:当 AI 能替我们写出所有“正确而全面”的文字时,人类在协作里还剩下什么不可替代的价值?Willison 的答案是:判断。判断什么值得读、什么值得注意、什么可以先放一放。一句话的开头,就是这种判断最轻量的形式。它不需要你写得比 AI 好,只需要你想得比 AI 清楚。

所以,这篇博客值得读,不是因为它教了一个 HTML 小技巧,而是因为它示范了一种 AI 时代的工作姿态:不抗拒 AI,也不把一切都交给 AI。在 AI 写得越来越多的世界里,愿意花三十秒想一句人话、再把它放在最前面的人,反而成了最稀缺的协作者。下次你的 Agent 开完 PR、写好长文,别急着点合入,先问自己一句:如果只能留一句话,我会留哪一句?想清楚了,就把它放在最前面,剩下的交给折叠块。

阅读 10评论 0

评论 (0)

ME
0/1000
评论加载中...

原始来源

浏览项目广场发布你的项目

相关文章

一名戴眼镜的开发者坐在木桌前敲笔记本电脑,左边外接显示器上是深色背景的 C 语言代码,桌上有绿植
资讯
微软的编程模型终于不当配角了:MAI Code 2 拿 96% 的分数、只收 5% 的钱,但先看清三处“但是”

2026 年 11 月 17 日,微软发布 MAI Code 2 和 Code 2 Flash:大模型 770 亿激活参数、100 万上下文,四项基准平均通过率 63.2%,与 GPT-6.1 Sol、Claude Opus 5.5 咬得很紧,但每任务成本只有 0.309 美元。先看清三处“但是”:价格是推广价、分数是三者最低、长周期任务不在舒适区。

开发工作流产品发布模型动态
一名开发者坐在双显示器工位前敲键盘,左屏是深色代码编辑器,右屏是带绿色对勾与柱状图的测试仪表盘,桌上有台灯和马克杯
资讯
你的智能体到底变好还是变坏了:AWS 开源 UAEF,给所有框架的智能体用同一把尺子量

2026 年 11 月 11 日,AWS 开源 UAEF:先把 LangGraph、LangChain、Strands、Bedrock AgentCore 等框架的运行记录翻成统一格式,再用 36 个指标、7 个维度打分,回归超过 5% 就亮灯。评审模型本身也被防了一手:打分要引原文作证,分数不能用来决定安全放行。

开发工作流产品发布测试与质量
黑色背景上,一名指挥家背对镜头高举指挥棒,脚下环绕着旋转的光轨,像一支乐队正在被指挥
资讯
一个接口接 45 个模型,坏了自动换一家接着跑:Perplexity 的 Orchestrator 想当模型界的‘总机’

2026 年 11 月 17 日,Perplexity 推出 Orchestrator API:一个接口接通 OpenAI、Anthropic、Google、xAI 与 GLM、Kimi、DeepSeek 等开源权重模型,按回答模型的公开价计费、不收平台费。同一模型挂了就换一家部署接着跑,路由功能还能按任务把请求分给不同的模型。

开发工作流产品发布模型动态