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

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

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

这组示例服务的是工作中间态，而不是最终发布页。过去这类东西当然也能手写，只是成本太高，通常没人愿意为了"一次评审"或"一次讲解"专门做一页界面。agent 把这个门槛压低以后，浏览器重新变成了一个足够便宜、足够通用的工作容器。标题里的"又"也不是修辞：早期 web 文档本来就直接写在 HTML 里，后来 Markdown 和 docs-as-code 把写作、diff、协作都做得更轻，很多原本可以做成小界面的中间材料也跟着退回纯文本；现在 agent 能顺手生成一页可运行的界面，HTML 才重新回到这些场景里。

两点口径先说清。其一，仓库 README 明确写着 “Sample code. Not maintained and not accepting contributions”——这是一次性示例集，不持续维护；本文事实核对基于 2026 年 9 月的仓库状态。其二，README 同时声明所有示例中的产品名、数据和场景均为虚构（占位品牌 Acme），正文引用的页面数字都是演示设定，不是真实测量值。这 20 个示例分别在替代什么，第一节先给地图；要不要把这套思路引入你的工作流，第六、七节给判断和落地约束。

目录

• 一、这 20 个示例在替代什么
• 二、为什么这些任务用 HTML 会更顺手
• 三、五个典型示例拆解
• 四、AI 把这件事的成本打下来了
• 五、别把这个结论说过头
• 六、什么时候该让 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，给后台任务文档当头图，每张图下面都带独立导出按钮。更细一点看，作者把配色、描边粗细（中性框 1.5px、强调容器 2px）、圆角半径（rx="10"）、标签字号（框内 11px 等宽、框外 12px 无衬线）这些规则单独列成了 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 通常就会比一篇泛泛而谈的说明文更有工作价值。

八、自测题

先想再看答案，每题的参考答案折叠在题面下方。

1. 单文件 HTML 的 9 组应用场景分别是什么？每组在替代什么传统文档？

2. 为什么空间信息、交互体验、分层入口是 HTML 比 Markdown 更适合某些中间产物的原因？

3. 5 个典型示例各自的设计思路是什么？

4. 如何判断你的团队工作中哪些场景适合用 HTML 中间产物？

5. 让 agent 生成 HTML 的约束条件应该怎么写？

九、动手练习

练习 1：为你的团队设计一个 HTML 中间产物

从团队真实工作流里挑一个低效文档场景（方案比较、PR 审查、概念讲解均可），按第七节的提示词骨架写一份约束：任务、使用者、要做的判断、必须包含的交互、导出目标。让 agent 生成页面后，拿原来那份 Markdown 对照：哪些判断变快了，哪些信息丢了。

练习 2：用 agent 生成一个代码审查页

找一个真实 PR（或模拟一个），让 agent 生成带改动说明、风险地图、文件导航、阻塞级评论和导出按钮的单文件审查页。在浏览器里打开，按页面排好的顺序走一遍评审，再回到 GitHub 上走一遍：两遍里哪一遍先发现风险？

练习 3：评估你现有的文档工作流

列出团队常用的文档类型，逐个问四个问题：是否带空间关系？是否只能靠体验判断？是否需要分层入口？是否是一次性的？四问里命中两条以上的，值得先做成 HTML 中间产物试用一轮；一条都不中的，留在 Markdown 里。

十、进阶路径

• 逐个读 20 个示例的源码：每个文件都是一个自包含页面，看它如何用内联 CSS/JS 实现交互与导出
• 沉淀团队模板：把团队最常用的 2-3 个场景（比如 PR 审查页、方案比较页）固化成可复用的提示词模板
• 接入现有工作流：在 Claude Code / Cursor 里配置自定义命令或 prompt 模板，让"生成工作面板"成为一条命令
• 小范围试用再推广：先在 1-2 个迭代里试用，收集"页面是否真的加快了判断"的反馈，再决定是否扩大
• 探索更复杂的交互场景：在单文件约束内尝试过滤、拖拽、实时重渲染等更重的交互，观察文件大小与可维护性的边界

十一、结语

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

仓库是一次性示例集，README 明确标注不维护、不接受贡献；示例里的公司、数据和场景均为虚构。把这里的思路搬进自己团队时，值得照搬的是"把判断顺序和导出出口做进页面"的设计方法，而不是任何一页的具体实现。

参考资料

• 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

仓库：ThariqS/html-effectiveness | 许可证：Apache License 2.0