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

学习目标：理解单文件 HTML 在现代 AI 工作流中的重新定位；掌握 20 个示例分别替代哪些低效文档场景；能够判断何时应该让 Agent 生成 HTML 页面而非 Markdown 文档；能够设计适合你团队工作的 HTML 中间产物 核心问题：为什么有些工作天然带着空间关系、交互状态和回写动作，硬塞进线性文本之后，判断链路会被拉长？HTML 如何成为比 Markdown 更有效的工作介质？ 难度：⭐⭐⭐（中级，需要理解文档工程和工作流设计） 预计阅读时间：25 分钟

学习目标

读完本文后，你应该能够：

1. 列举单文件 HTML 的 9 个应用场景（Exploration & Planning、Code Review、Design、Prototyping 等）及每个场景替代什么传统文档
2. 解释为什么空间信息、交互体验、分层入口、导出能力是 HTML 比 Markdown 更适合某些中间产物的原因
3. 分析 5 个典型示例（代码审查页、功能说明页、概念讲解页、SVG 资产页、临时编辑器）的设计思路
4. 判断你的团队工作中哪些场景适合用 HTML 中间产物（方案比较、PR 审查、概念讲解、SVG 资产、临时编辑器）
5. 设计让 Agent 生成 HTML 的约束条件，避免把结论说过头或产生不可维护的产物

目录

1. 这 20 个示例在替代什么
2. 为什么这些任务用 HTML 会更顺手
   • 1. 空间信息不该被压扁
   • 2. 有些东西只能体验，不能靠转述
   • 3. 解释型文档需要分层入口
   • 4. 最像工具的页面，都会留下出口
3. 五个示例，为什么比"写得更详细"更有效
   • 代码审查页：把审查顺序编码进界面
   • 功能说明页：把代码路径变成可走的路线
   • 概念讲解页：把抽象原理重新变成现象
   • SVG 资产页：把插图留在可编辑状态
   • 临时编辑器：让模糊需求先落到手上
4. AI 把这件事的成本打下来了
5. 别把这个结论说过头
6. 什么时候该让 Agent 生成 HTML
7. 如果要复用这套思路，约束要写到任务层
8. 结语
9. 参考资料
10. 自测题
11. 练习
12. 进阶路径
13. 资料口径说明

如果把 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 通常就会比一篇泛泛而谈的说明文更有工作价值。

自测题

读完本文后，请自测以下问题：

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

   点击查看参考答案

   • Exploration & Planning（3个）：方案比较、实现计划 → 替代选型说明、规划文档
   • Code Review（3个）：带批注的 diff、PR 写作 → 替代 PR 描述、架构导读
   • Prototyping（2个）：动效沙盒、可点击流程 → 替代交互动效说明、流程原型
   • Research & Learning（2个）：功能说明页、概念讲解页 → 替代研究笔记、技术讲解
   • Custom Editing Interfaces（3个）：分诊板、prompt 调优器 → 替代临时操作台、手工清单

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

   点击查看参考答案

   • 空间信息：diff 和 call graph 本来就是空间信息，HTML 可以把风险图、文件列表、正文批注放在同一屏
   • 交互体验：动效曲线、点击路径只能体验不能靠转述，HTML 页面比三段说明文字更接近真实问题
   • 分层入口：TL;DR、可展开步骤、标签切换可以把阅读路径做进界面本身

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

   点击查看参考答案

   • 代码审查页：把审查顺序编码进界面（改动说明 → 风险地图 → 文件列表 → 行级评论）
   • 功能说明页：把代码路径变成可走的路线（TL;DR → 按步骤展开的请求路径）
   • 概念讲解页：把抽象原理重新变成现象（可交互的示意图）
   • SVG 资产页：把插图留在可编辑状态（SVG 源码可直接复制修改）
   • 临时编辑器：让模糊需求先落到手上（可交互的分诊板、开关编辑器）

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

   点击查看参考答案

   判断标准：是否带着空间关系、是否需要交互体验、是否需要分层入口、是否是一次性的（是 → HTML；长期 → Markdown）

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

   点击查看参考答案

   约束条件要写到任务层：要做的判断、必须包含的元素、导出目标、技术约束（内联 CSS/JS、无外部依赖）

练习

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

目标：根据团队实际工作流，设计一个适合用 Agent 生成 HTML 的场景。

步骤：

1. 明确团队的常见低效文档场景（方案比较？PR 审查？概念讲解？）
2. 设计 HTML 页面的核心功能（空间信息、交互体验、分层入口、导出能力）
3. 写 prompt 让 Agent 生成这个 HTML 页面（包含任务闭环约束）
4. 测试生成的页面是否比原 Markdown 更有效

验证：生成的 HTML 页面能有效承接下一步动作吗？

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

目标：实践让 Agent 生成带批注的 PR 页面。

步骤：

1. 找一个真实 PR（或模拟一个）
2. 写 prompt 让 Agent 生成代码审查页（包含改动说明、风险地图、文件列表、行级评论、导出按钮）
3. 在浏览器中打开测试，对照原 PR 的 Markdown 描述评估

验证：生成的代码审查页能有效提升审查效率吗？

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

目标：系统评估团队目前的文档工作流，找出适合换成 HTML 的场景。

步骤：

1. 列出团队常用的文档类型
2. 对每个文档类型评估是否适合 HTML（空间关系？交互体验？分层入口？一次性？）
3. 选择 1-2 个最高优先级的场景，设计 HTML 页面原型
4. 用 Agent 生成这些页面，在团队内部试用

验证：引入 HTML 中间产物后，团队工作流有显著提升吗？

进阶路径

1. 系统研究 html-effectiveness 项目的 20 个示例：理解每个示例的设计思路和实现细节
2. 为团队设计 HTML 中间产物模板：创建 2-3 个可复用的 HTML 模板
3. 把 Agent 生成 HTML 集成到工作流：在 Claude Code / Cursor 中配置自定义命令或 prompt 模板
4. 评估 HTML 中间产物的实际效果：在团队内部 A/B 测试，收集反馈并迭代优化
5. 探索更复杂的交互场景：研究如何用 HTML + JavaScript 实现更复杂的交互
6. 写一篇总结文章：把团队的实践经验和教训写成文章，分享给社区

资料口径说明

1. 信息来源：基于 thariq 的 The unreasonable effectiveness of HTML 项目和 20 个示例。项目仍在维护中，部分细节可能已更新。
2. 功能验证：20 个示例已在项目主页验证，但未逐一用 Agent 重新生成并测试。
3. 应用场景的判断边界：9 个应用场景基于 thariq 的项目分类。你的团队工作流可能不同，部分场景可能需要调整。
4. 技术细节：HTML 技术（内联 CSS/JS、无外部依赖）已验证可行，但复杂交互可能影响文件大小。
5. Agent 生成质量的依赖性：HTML 质量严重依赖 Agent 能力和 prompt 设计。写得不好的 prompt 可能生成无效页面。
6. 更新记录：本文撰写于 2026-06-30。如果项目在之后有重大更新，本文可能需要补充。

结语

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 分钟