为什么单文件 HTML 又变得实用了

如果把 thariq 的 The unreasonable effectiveness of HTML 只看成一组“AI 生成网页”的展示页，很容易错过它真正有价值的部分。这个项目讨论的是一种被低估的中间产物：有些工作天然带着空间关系、交互状态和回写动作，硬塞进线性文本之后，信息虽然还在，判断链路却被拉长了。

项目主页给出的定义很克制：20 个由 agent 生成的、自包含的单文件 HTML，用来替代一堵 Markdown 文字墙。它们可以直接在浏览器里打开，围绕一项具体任务组织内容，更像临时但可工作的面板：打开就能看，能点，能拖，能展开，做完判断之后还能把结果复制回 PR、配置文件、设计稿或下一轮 prompt。主页对这组产物的总括也很传神：把原本会被匆匆扫过的文档，换成更愿意真正读完的界面。

这组示例服务的是工作中间态，而不是最终发布页。过去这类东西当然也能手写，只是成本太高，通常没人愿意为了“一次评审”或“一次讲解”专门做一页界面。agent 把这个门槛压低以后，浏览器重新变成了一个足够便宜、足够通用的工作容器。

标题里的“又”，也不是修辞。早期 web 文档本来就直接写在 HTML 里，后来 Markdown 和 docs-as-code 把写作、diff、协作都做得更轻，很多原本可以做成小界面的中间材料也跟着退回纯文本。现在 agent 能顺手生成一页可运行的界面，HTML 才重新回到这些场景里。

这 20 个示例在替代什么

项目首页把 20 个示例分成 9 组，几乎每一组都能对上团队里常见的一类低效文档。

这张分类表能说明一个关键边界：这些 HTML 主要在替代那些本来就不太适合纯文字承担的工作载体，而不是去抢 README、API 参考或长期维护教程的位置。它们更像工作台，而不是档案柜。

为什么这些任务用 HTML 会更顺手

项目首页其实已经把理由说得很明白了。换成中文重新整理后，更容易看出这不是排版偏好，而是任务匹配。

1. 空间信息不该被压扁

主页在 Code Review & Understanding 一栏里写得很直接：diff 和 call graph 本来就是空间信息，Markdown 会把它们压平成一条线。这个判断很准确。线性文档并不是不能描述代码结构，而是读者必须自己在脑中重建结构图；一旦牵涉风险分布、模块边界、导航跳转和评论上下文，认知成本会迅速上升。

HTML 可以把风险图、文件列表、正文批注和跳转入口放在同一屏里。读者不用先记住一段说明，再切去另一段内容求证，判断顺序直接被界面编码出来了。

2. 有些东西只能体验，不能靠转述

Prototyping 一栏的原话也很到位：motion and interaction can’t be described, only felt。动效曲线、点击路径、参数调节都属于这种情况。你当然可以写一段精确描述，但真正的判断通常发生在“点一下试试”“拖一下看看”之后，而不是读完说明之后。

这类任务里，浏览器的价值很直接：它本来就是交互运行时。一个带滑块的单文件页面，往往比三段说明文字更接近真实问题。

3. 解释型文档需要分层入口

Research & Learning 这一组说明了 HTML 另一个很实用的能力：它不仅能展示信息，还能把信息组织成适合下钻的入口。TL;DR、可展开步骤、标签切换、边栏术语表，这些都是为了让读者先抓住结论，再根据需要往下钻，而不是被迫从第一行读到最后一行。

线性 Markdown 也能做到分节，但做到“分层阅读”通常要靠读者自觉跳转。HTML 则可以把这个阅读路径做进界面本身。

4. 最像工具的页面，都会留下出口

导出能力在最像工具的那几页里尤其关键。项目首页在 Custom Editing Interfaces 一栏里反复强调：最好总是以一个 export button 结尾，把用户刚才在界面里做的操作，重新变成可以粘贴回 agent 或直接提交的结果。

这一步决定了它是 demo 还是工具。只能展示的页面，价值停在“看过”；能把结果复制成 Markdown、配置 diff、SVG 或 prompt 的页面，才算真正进入工作流。

五个示例，为什么比“写得更详细”更有效

真正说服人的不是概念，而是这些页面到底做了什么。下面挑 5 组最能代表项目思路的示例来看。

代码审查页：把审查顺序编码进界面

03 号示例是一个带批注的 PR 页面。打开后先看到的是本次改动说明（What this PR does），再往下是风险地图（risk map）、文件列表，最后才进入具体行级评论。它不是把 diff 生硬搬进浏览器，而是把评审动作重新排了一遍顺序。

更关键的是，页面里的评论并不空泛。示例里有一条阻塞级评论（blocking comment）指出 onMutate 前没有先执行 qc.cancelQueries(key)，后台 refetch 可能把乐观更新冲掉；另一条阻塞级评论则指出把 idempotency key 生成为默认参数，会让重试请求拿到不同 key，从而失去幂等意义。也就是说，这个页面不是“更漂亮的 diff 查看器”，而是把审稿人真正会看的东西提到了前面：风险、关注点、跳转入口和后续动作。

功能说明页：把代码路径变成可走的路线

14 号示例讲的是一个仓库里的 rate limiting 机制。页首不是长导语，而是一个 TL;DR：所有请求先经过 rateLimit()，再根据 bucket key 去 Redis 里的 token bucket 扣 token，没 token 就返回 429。这段总结后面，才是按步骤展开的请求路径（request path）。

它的好处在于，解释不再停留在“这个功能是什么”，而是直接回答“请求进来之后，代码到底怎么走”。页面里甚至补上了很具体的细节：整个路径大约 40 行代码，p50 额外开销约 0.4 ms；配置靠 config/limits.yaml；本地开发没配 REDIS_URL 时会退回内存 map；burst 表示桶容量，不等于速率；30 秒的 SSE 流也只扣 1 个 token。这些信息如果只写成长段文字，不难读懂，但很难让人快速定位。

概念讲解页：把抽象原理重新变成现象

15 号示例用一致性哈希解释了 HTML 特别适合哪类知识。页面中间是一个可以增删节点的交互式哈希环（live ring），旁边直接显示本次变化导致多少 key 迁移；下面再配一张和 mod N 的对照表，把“新增一台机器后会发生什么”从抽象定义变成眼前现象。

这个页面里还有一组可悬停联动的术语表，解释 ring、node、arc、virtual node、successor。于是读者不是在一堆定义之间来回跳，而是在“看到变化”“对比变化”“补术语”这三步之间自然切换。对概念教学来说，这比多写几段解释更有效，因为很多误解并不是出在字不够多，而是读者从来没真正看到系统如何变化。

SVG 资产页：把插图留在可编辑状态

10 号示例是一页 SVG 资产页（SVG figure sheet）。页面里放了 3 张 720 × 320 的内联 SVG，给后台任务文档当头图，每张图下面都带独立导出按钮。更细一点看，作者还把配色、描边粗细、圆角半径、标签字号这些规则单独列成了 Palette & rules，并明确每个 SVG 自带自己的 style，导出后不依赖外部资源。

这类页面的价值不在“帮你画完了图”，而在“图依然是活的”。你可以复制单张 SVG，继续改样式，直接贴回文档，或者拿进设计工具继续加工。相比一张静态 PNG，它保留了后续编辑权；相比一段“请设计师照着做”的说明，它又已经把大部分决策落成了资产。

临时编辑器：让模糊需求先落到手上

18、19、20 号示例是一组非常像真实团队内部工具的页面。18 号是工单分诊板（ticket triage board），预先放了 24 个 Linear 工单，支持在 Now、Next、Later、Cut 之间拖动，点标签筛选，最后一键复制成 Markdown。19 号是特性开关编辑器（feature flag editor），按区域组织开关，依赖条件不满足时会直接给出提示，并且只复制变更的 key。20 号是 prompt 调优器（prompt tuner），左边编辑模板，变量槽位高亮，右边用 3 组示例输入实时重渲染。

这组页面说明了一个经常被忽略的事实：很多需求之所以难写清，往往是因为对象本身更适合先操作一遍。先拖一遍工单，再导出排序；先开关几组 feature flag，再复制 diff；先改 prompt，再看样例输出。HTML 在这里承担的是操作界面，把模糊判断缩短成几次可见操作。

AI 把这件事的成本打下来了

如果把这件事理解成“HTML 赢了 Markdown”，重点就看偏了。更贴近现实的变化是，AI 把一次性工作面板的制作成本压到了可以接受的范围，原本不值得专门实现的界面，开始值得做了。

过去当然也能手写一个 PR 审查页、一个参数调优页、一个交互原型页，只是投入产出比太低，团队通常会退回 Markdown。现在 agent 能一次性生成 HTML、CSS、少量 JavaScript 和示例数据，浏览器又是现成运行时，于是“先做一个能用的单文件面板，再决定要不要沉淀成正式文档”，成了很多场景里的现实选项。

这会带来两个变化。第一，交付物从纯文本变成可运行文件，页面能不能打开、交互有没有坏、导出是否可用，都会形成最低限度的质量约束。第二，反馈从延迟理解变成即时判断，团队成员不需要先读完说明再想象结果，而是可以直接点开页面确认：这个方案是否顺手，这个解释是否能看懂，这个参数是否调对了。

所以这里“不讲道理”的，其实是浏览器这个容器足够便宜、足够通用。只要任务需要一点空间布局、少量状态和一个导出出口，浏览器就会显得很顺手。

别把这个结论说过头

项目很有启发，但如果顺着它一路推到“以后都让 agent 产 HTML”，很快就会踩坑。边界至少有四条。

长期知识仍然更适合 Markdown

README、API 参考、版本记录、团队规范这类内容，核心需求是版本化、可 diff、易搜索、多人协作和长期维护。单文件 HTML 在这些维度上并不占优，甚至更难维护。项目里的 demo 也没有宣称自己要替代这一层。

一次性页面很容易腐烂

throwaway interface 的优势在于快，代价也在于快。示例数据、内联脚本、硬编码逻辑如果不及时回写到正式系统，很快就会过时。它适合服务当前这轮判断，不适合悄悄冒充系统真相。

交互页面照样有可用性成本

单文件 HTML 不等于天然好用。窄屏可读性、键盘操作、颜色对比、信息层次、导出结果是否干净，这些都需要明确约束。否则 agent 很容易给出一个“看起来像成品”的页面，却没有真正解决任务。

不可信来源的 HTML 不能随手打开

这一点常被忽略。自包含 HTML 往往带脚本，打开来源不明的文件，其风险性质和运行来历不明的脚本很接近。把 HTML 当工作介质，并不意味着可以放弃基本的安全判断。

什么时候该让 agent 生成 HTML

落地时，用一个简单分法就够了：先看下一步动作是什么。如果下一步动作主要是读、查、比、点、拖、调、导出，HTML 通常更合适；如果下一步动作主要是存档、协作编辑、版本对比、长期检索，Markdown 通常更稳。

多数团队真正值得采用的，并不是二选一，而是分层：Markdown 管长期知识，HTML 管当前这轮决策和沟通。

如果要复用这套思路，约束要写到任务层

如果要复用这套做法，提示词应该写到任务层，而不是审美层。如果目标是拿到能用的工作面板，至少要把任务对象、关键判断、必须出现的交互和最终导出目标交代明白；单文件、自包含、真实示例数据、窄屏可读这些约束，也应该一开始就写进去。只说“做个漂亮页面”，最后往往会得到一张宣传页，而不是一个工作面板。

下面这个提示词骨架，比“做一个介绍页”更容易得到有用结果：

请生成一个单文件 HTML 工作面板，浏览器可直接打开。

任务：<具体任务>
使用者：<谁使用这页>
要做的判断：<几分钟内必须完成的决策>
必须包含：<风险摘要 / 可展开步骤 / 示例数据 / 过滤器 / 导出按钮>
导出目标：<Markdown / diff / SVG / prompt / JSON>
约束：内联 CSS 与 JavaScript；无外部依赖；不要做成宣传页；窄屏可读。

如果把前面的 PR 审查页落成提示词，最小可用版本可以写成下面这样：

请把下面这次代码改动整理成一个单文件 HTML 审查页，浏览器可直接打开。

使用者：负责 review 的工程师
要做的判断：在 3 分钟内判断这次改动是否可以合并，以及优先该看哪些风险点
必须包含：改动摘要、风险地图、文件导航、阻塞级评论、建议后续动作
导出目标：复制评审摘要为 Markdown
约束：内联 CSS 与 JavaScript；无外部依赖；不要做成营销页面。

这里最重要的是任务闭环。只要把“页面里要做什么”与“做完之后结果去哪里”说清，agent 给出的 HTML 通常就会比一篇泛泛而谈的说明文更有工作价值。

结语

thariq 这组示例真正提醒人的，是文档是否有效，最终要看它能不能承接下一步动作。浏览器适合当前这轮比对、解释和导出；Markdown 适合长期沉淀、协作和检索。AI 没有发明什么新媒介，它只是把两者之间切换的成本降下来了，于是很多原本写成“说明文”的工作，又重新长回了更适合它们的形状。

参考资料

• The unreasonable effectiveness of HTML
• 03. Annotated pull request
• 10. SVG figure sheet
• 14. Feature explainer
• 15. Concept explainer
• 18. Ticket triage board
• 19. Feature flag editor
• 20. Prompt tuner

文档信息 难度：⭐⭐⭐⭐ | 类型：技术笔记 | 更新日期：2026-05-10 | 预计阅读时间：22 分钟