HTML 的不讲道理:AI 时代文档的新范式

围绕 thariq 的 20 个单文件 HTML 示例，讨论为什么 HTML 在代码审查、交互原型、概念讲解和临时工具上，比 Markdown 更适合承担中间工作产物。

thariq 的 The unreasonable effectiveness of HTML 其实在说一件很简单的事：很多协作任务需要的是能直接拿来比较、点击、调参的界面，说明文字只能起辅助作用。AI 编码助手一旦能直接交付这种界面，文档和工具之间的边界就会松动。

项目主页的定义也很直接：20 个由 agent 生成的、自包含的单文件 HTML，用来替代冗长的 Markdown。关键在使用方式：单文件、浏览器直接打开、围绕具体任务组织内容。这些文件服务的都是中间工作环节，比如方案比较、代码审查、概念讲解、配置调整，定位更接近工作面板。

项目到底在演示什么

只看标题，很容易把它理解成一组“AI 生成网页”的展示页。主页的 9 组分类表明，HTML 在这里直接被拿来做工作界面。20 个示例分别落在探索与计划、代码审查与理解、设计、原型、插图与图表、演示、研究与学习、报告、自定义编辑界面这些工作类型上，几乎都对应团队里真实存在的沟通瓶颈。

这些示例有三个共同特征：

1. 每个产物都围绕一个具体任务服务，不把重点放在“做一篇网页文章”。
2. 每个产物都尽量单文件、自包含，省掉构建、部署和外部依赖。
3. 每个产物都能直接参与下一步协作，不只停留在阅读层。

更重要的是，这类 HTML 更像一次性的工作台，适合缩短“理解问题、做出判断、回写结果”这条链路。Markdown 依然适合沉淀稳定内容。

HTML 多出来的四种能力

放到协作场景里看，HTML 比 Markdown 多出四种很实用的能力。

空间关系可以直接呈现

代码差异、模块结构、流程分支本来就带有空间信息。Markdown 能记录这些信息，只是默认仍按线性阅读展开，读者经常要自己在脑中重建上下文。HTML 可以把风险、结构、导航和正文放到同一屏里，减少来回切换。

状态和交互可以直接体验

动效、点击流程、参数调整都属于“看说明不如上手试”的内容。对这类任务来说，滑块、切换和局部预览比一段精确描述更有用，因为判断本来就依赖体验，不靠复述。

渐进式披露更容易实现

解释型文档的常见问题，在于所有信息被一次性铺开。HTML 很容易做出 TL;DR、可展开步骤、标签切换、侧边注释这类分层入口，让不同背景的读者按需要下钻，不必从头读到尾。

产物可以被回写回流程

这组示例最有意思的地方，是很多页面都留了“出口”。用户在页面里完成选择或调节之后，可以把结果复制成 Markdown、配置 diff、SVG 或 prompt 模板。这样 HTML 就会直接接上后面的流程，不会停在展示这一层。

五个代表性示例

代码审查：把审查顺序做成界面

03-code-review-pr.html 把审稿人真正关心的信息排成了顺手的顺序：先看这次改动解决什么，再看风险分布和文件列表，最后落到具体行级评论。对审稿人来说，真正的价值来自更少的上下文切换，不必在 PR 描述、diff 和评论区之间来回折返。

研究说明：把导航做进正文结构

14-research-feature-explainer.html 讲的是仓库里的 rate limiting 机制。页面先用 TL;DR 交代结论，再把请求路径拆成可展开的步骤，随后才给配置示例、注意事项和 FAQ。这样的结构更适合读者进入：可以先抓结论，也可以沿着理解路径逐层展开。

概念讲解：把抽象原理重新变成可观察对象

15-research-concept-explainer.html 用一致性哈希说明了 HTML 最适合哪类难点：读者不仅要知道结论，还要看到系统在变化时怎么工作。页面中的环形图可以增删节点，并实时显示哪些 key 发生迁移；再配上一张与 mod N 的对照表，抽象概念就从“定义”变成了“现象”。

插图与图表：把图变成可编辑资产

10-svg-illustrations.html 的价值不在“图够不够好看”，而在“图还能不能继续用”。三张后台任务文档头图都是内联 SVG，自带样式，可以单独导出，也可以继续修改、复制到别的页面或设计工具里。对 AI 工作流来说，这比贴一张静态图片更实用，因为它保留了继续加工的空间。

临时编辑器：让模糊需求先变成可操作界面

最像真实团队工具的，是 18-editor-triage-board.html、19-editor-feature-flags.html 和 20-editor-prompt-tuner.html 这一组。它们分别对应工单分诊、特性开关调整和 prompt 调参。共同原则很清楚：页面必须允许操作，也必须允许导出。没有导出按钮，它只是 demo；能把结果复制回 Markdown、配置或 prompt，它才真正接入现有流程。

20 个示例分别在替代什么

这张表也给出一个很清楚的边界：HTML 更适合推进当前工作，Markdown 更适合沉淀稳定知识。两者各管一段。

为什么这件事在 AI 时代突然变得实用

过去也可以手写这类 HTML，只是成本高，很难成为团队习惯。agent 把 HTML、CSS、少量 JavaScript 和示例数据一次性交付出来，浏览器又天然是通用运行时，于是“临时做个工作面板”的成本第一次接近“先写一份说明文档”。

变化主要有两点。第一，交付物从说明文本变成可运行文件，页面能不能打开、交互能不能工作，会形成最低限度的质量约束。第二，反馈从延迟理解变成即时判断，人可以直接在界面里拖、点、调，再把结果带回主流程。HTML 在这里显得“不讲道理”，说到底是因为浏览器刚好是最便宜的可交互容器。

什么时候该让 agent 生成 HTML，什么时候继续写 Markdown

判断标准很简单：先看当前任务最需要什么。

实际工作里，最有价值的往往是混合做法：Markdown 负责沉淀长期知识，HTML 负责解决当前这轮决策和沟通。二者各有分工。

如果你也想让 agent 产出这种 HTML，约束要怎么下

这组示例还有一个很实用的启发：高质量 HTML 往往来自贴近任务的约束，不来自“请做一个漂亮页面”这种泛泛要求。先把下面几件事说清，结果通常会好很多：

1. 只做一个单文件 HTML，内联 CSS 和 JavaScript，无外部依赖。
2. 围绕一个具体工作对象设计界面，例如 PR 审查、特性开关、工单分诊、概念讲解。
3. 用真实或拟真的示例数据，不要只放占位文本。
4. 提供一个明确的导出出口，例如复制成 Markdown、复制 diff、导出 SVG、复制 prompt。
5. 用渐进式披露组织页面，避免把所有信息一次性铺满。

下面这个提示词骨架就比“帮我写一份说明文档”更容易得到有用结果：

请基于下面的任务生成一个单文件 HTML 原型，浏览器可直接打开。

任务对象：<这里写具体任务，例如 PR 审查页 / 工单分诊板 / 概念讲解页>
目标读者：<谁会使用它>
必须包含：<风险摘要 / 可展开步骤 / 示例数据 / 导出按钮等>
约束：内联 CSS 与 JavaScript；无外部依赖；桌面端优先，同时保证窄屏可读；不要写成宣传页。
输出目标：让使用者在 3 分钟内完成判断，并能把结果复制回 Markdown、配置文件或下一轮 prompt。

这种写法的关键在于先把交付物说清：你要的是一个工作面板，不是一篇介绍文章。

结语

The unreasonable effectiveness of HTML 给出的启发，其实就是把不同产物放回合适的位置。需要长期维护、可 diff、可协作编辑的内容，Markdown 依然更稳；需要比对、体验、调参、导出的中间产物，单文件 HTML 往往更顺手。

当 agent 可以低成本生成这类页面之后，团队其实只是多了一种沟通手段：浏览器可以直接承担轻量、通用、可回写的工作面板角色。

参考资料

• The unreasonable effectiveness of HTML^[1]
• 03. Annotated pull request^[2]
• 10. SVG figure sheet^[3]
• 14. Feature explainer^[4]
• 15. Concept explainer^[5]
• 18. Ticket triage board^[6]

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

引用链接