HTML 对 Agent 的不合理有效：从文字墙到可操作工件的输出格式革命

原文：The unreasonable effectiveness of HTML — examples · Thariq Shihipar

引言：Agent 的输出，正在悄悄换一种形状

过去两年，几乎所有 Coding Agent 的默认输出格式都是 Markdown——它结构简单、流式友好、所有渲染器都认得。Cursor、Claude Code、CodeBuddy、Devin 全都默认吐 Markdown，开发者们也已经习惯了在终端或聊天窗里翻一堵又一堵的"文字墙"。

但越来越多迹象表明：Markdown 是 Agent 输出的"够用解"，不是"好解"。

Thariq 的这篇 The unreasonable effectiveness of HTML 用 9 大类别 × 20 个 demo 把这件事摆得相当直白——HTML 不是网页的呈现层，它是 Agent 与人类协作的天然媒介。当 Agent 开始用 HTML 输出时，同一份信息的可消费性、可决策性、可回灌性，会出现一个明显的跃迁。

这篇文章把原文的 20 个 demo 收敛成 5 类可复用范式，回答三个问题：

1. 为什么 Markdown 把空间信息压扁了？
2. HTML 的结构 / 交互 / SVG / 一次性编辑器，分别让 Agent 多做了什么？
3. “导出按钮收紧反馈循环"为什么是关键设计原则？

最后给出一份可落地的 Agent 输出格式选型决策树，以及它对 Claude Code、CodeBuddy、Cursor、Devin 等主流 Coding Agent 形态的影响推断。

一、Markdown 的"扁平诅咒”：把空间信息压成线

Markdown 的本质是 线性结构——它擅长表达"先 A 后 B 再 C"，但极不擅长表达"A、B、C 同时存在并需要被对照"。

来看一组真实对照。同一份"部署流水线"信息，Markdown 输出长这样：

## 部署流水线
1. 拉取代码（约 12s）
2. 单元测试（约 95s，可能失败：超时）
3. 构建镜像（约 180s）
4. 安全扫描（约 40s，可能失败：CVE）
...

读者要在脑子里完成四件事：把 8 个步骤排成时间轴、心算总耗时、判断"哪一步失败概率最高"、想象"第 4 步失败时怎么走"——所有这些"二维信息"都被压成了一行行的一维文字。

而 HTML 工件长这样：一条横向时间线，节点用色标（绿色=正常，橙色=偶发失败，红色=高失败率），点击节点 4 立刻弹出运行命令、耗时分布图、失败路径、最近 7 天统计、以及一个"复制为 prompt"按钮。

运动与交互无法被描述，只能被感受。
——Thariq

这句话不只是给动效说的。Diff 是空间信息（旧→新的对位）、调用图是空间信息（A 调 B 调 C 的结构）、设计 token 是空间信息（颜色与值的视觉绑定）——Markdown 把它们全压扁了，读者要再用脑力把它们拉回二维。

这个"脑力税"是 Markdown 默认输出的隐形代价。它在 Agent 输出语境下被 N 倍放大，因为 Agent 一次给你的信息密度，远远大于一个同事写文档的速度。

二、HTML 让 Agent 多做了什么：4 件 Markdown 做不到的事

要看清 HTML 的"不合理有效"在哪儿，得把它解构成 4 项具体能力——它们组合起来，构成了 Markdown 与 HTML 工件之间真正的鸿沟。

1. 结构化空间布局 — 卡片、网格、时间线、看板，能让信息在二维上同时呈现。Markdown 只能给你顺序。

2. 内联 SVG 这支真正的笔 — Agent 可以现场画 diff、调用图、状态机、流程图、色卡，而不是写一段"想象一下…“的描述。原文称之为 Inline SVG gives the agent a real pen。

3. 微交互 — 折叠、Tab、悬浮提示、滑块、拖拽。它们让单个工件能容纳多个视角，而不是把每个视角各写一段。

4. 一次性编辑器 — 当用户的诉求"用文字说不清"时，Agent 可以即兴造一个一次性 UI（看板、开关墙、参数滑块），让用户用手表达，最后用导出按钮把操作序列化回 prompt。

只看其中任何一条都还不够刺激。但当 Agent 把这 4 条一起用上时，它的输出会从"读完关掉"变成"读完去操作再回来”——这就是 Thariq 想说的工件（artifact），而不是文档。

三、5 类可复用范式：从 9 类 20 demo 收敛到可上手的清单

原文给了 9 大类别 × 20 个 demo，但作为读者你不需要记 20 个——它们其实可以收敛成 5 类范式，每类回答同一个问题：“如果用 Markdown 会怎样？”

① 探索 & 规划：横向铺开，而不是顺序读墙

场景：用户还没想清楚要什么，让 Agent 给几个方向。
HTML 怎么做：三种代码方案并排成三张卡片，每张内联标注权衡（性能、可读性、依赖）；多种视觉设计的 mockup 实时渲染并排；实施计划画成"时间轴里程碑 + 数据流图 + 风险代码 + 风险表"四件套。
Markdown 反例：用户读完 A 已经忘了 B 的对应字段，要往回滚屏对照。

这里的关键是横向——人脑天生擅长扫视而不是滚动。当三个方案并排时，差异会"跳出来"；当顺序展开时，差异要靠工作记忆维持。

② 代码评审 & 模块理解：把结构画出来

场景：评审 PR，或者让 Agent 帮你看懂一个陌生包。
HTML 怎么做：Diff 不再是终端滚动条，而是带边注的可扫描画面——红色严重度、黄色提醒、点开跳到上下文；陌生包的结构画成框图，热路径高亮，入口点显式标出。
Markdown 反例：你滚动一千行 diff，看到第 400 行时已经忘了第 50 行。模块结构靠文字描述根本拼不出心智模型。

Diffs and call-graphs are spatial information; markdown flattens them.

这一类是"HTML 收益最稳定"的场景——任何带"结构"或"对位"的信息，Markdown 都不擅长。

③ 设计 & 原型：动效与色彩必须被感受

场景：让 Agent 帮你提取仓库的设计 token，或者尝试一个组件的视觉变体。
HTML 怎么做：从代码里扫出颜色、字号、间距，渲染成可点击复制的色卡墙；动效装在 sandbox 里，配上时长和缓动滑块，按下去就能看到弹性回弹的真实曲线；四屏可点击 mockup，用方向键就能感受跳转节奏。
Markdown 反例：用文字描述"轻微的弹性回弹，缓动曲线类似 ease-out-back"——写得再细，读者也只能在脑子里失真地脑补一遍。

这就是原文那句"运动与交互无法被描述，只能被感受"的具体落地——有些信息的最低损耗呈现就是 HTML 本身。

④ 一次性编辑器：当用户"用文字说不清"时

场景：30 个工单要分到 Now / Next / Later / Cut；feature flag 要按区域开开关关；prompt 模板要换 3 个变量看一眼输出。
HTML 怎么做：Agent 即兴造一个看板让你拖、一面开关墙让你点、一个 prompt 调参面板让你改。最后必须以导出按钮结尾——把你的拖拽 / 切换 / 修改序列化为 Markdown / JSON / Diff，回灌到下一轮 prompt 里。
Markdown 反例：你来回打字描述"把第 3 张工单移到 Next，第 7 张工单 Cut 掉，第 12 张……" Agent 猜歪一半，你再纠正，反复 N 轮。

这一类是 HTML 工件最"不合理有效"的地方——它把"用户表达"这件事，从自然语言切到了直接操作。沟通带宽直接打开。

⑤ 教学 & 解释：在空间中建立直觉

场景：解释一致性哈希、解释限流算法、解释一个新的 protocol。
HTML 怎么做：一致性哈希画成可增删节点的实时环，让你直觉地看懂"加一个节点谁会被影响"；限流的请求路径画成可折叠的调用链 + 配置 Tab + FAQ；术语用 hover 弹层即点即看。
Markdown 反例：线性段落写满"假设有 N 个节点……"——读者抓不到那个环的形状。

教学是关于"建立直觉"，而直觉天然就是空间的。

共享底层模式：5 类殊途同归

5 类场景表面上各做各的事，但底层共享同一个三段式模式：

空间呈现 → 在空间中决策 → 导出回 prompt

这个模式之所以重要，因为它解释了为什么 HTML 的 ROI 在不同场景里都成立——它不是"每个场景给个新方案"，而是把同一种交互范式套到不同信息形状上。

四、方法论核心：导出按钮才是工件的灵魂

如果上面 4 节你只能记住一句话，那就是这句：

自定义编辑界面应始终以"导出按钮"结尾——把 UI 操作产物转回可粘贴 / 可提交的内容。
“You stay in the loop. The loop gets tighter.”

这句话很容易被当成"细节"忽略，但它其实是 HTML 工件能不能成立的单点决定因素。

来对比两个反馈循环：

没有导出按钮的工件——用户看到漂亮的看板，把工单拖来拖去；想完之后又得回到聊天框打字：“好的，我把工单 #1234 放到 Now，#5678 放到 Next，剩下的……”
→ Agent 拿到的还是文字描述，还得猜，还得再来一轮。反馈循环：分钟级，信息有损。

有导出按钮的工件——用户拖完一键导出 Markdown 表格 / JSON Patch / Git Diff，直接粘回 prompt，Agent 拿到的是结构化的、无歧义的、零脑力转化成本的输入。
→ 反馈循环：秒级，信息无损。

差别看起来只是一个按钮，但从信息论角度看，这一步是"把模拟信号还原成数字信号"。没有它，再漂亮的工件都只是单向输出；有了它，工件就成了双向通道。

这也是原文里反复强调的方法论——HTML 工件不是为了好看，是为了把"人在循环中"这件事做实。

五、Agent 输出格式选型决策树

讲了这么多 HTML 的好，是不是该把所有 Agent 输出都换成 HTML？
不是。Markdown 在它该发光的地方依然不可替代。问题不是"哪个更好"，而是**“这次输出的信息形状是什么”**。

可以按一个简单的判据来选：

一句话原则：线性 → Markdown ・ 空间 → HTML 工件 ・ 难以描述 → 一次性编辑器 + 导出。

这条选型逻辑的隐含前提是：Agent 自己得能判断信息形状。这是个新的能力维度——以前我们只让它判断"答什么"，现在还要让它判断"用什么形状答"。这一层判断质量，会逐渐变成 Coding Agent 的核心差异化。

六、对主流 Coding Agent 形态的影响推断

Thariq 的文章其实已经把方向指明了，剩下的是看哪些产品先把它落到主线交互里。我们来逐个推断当前主流形态的可能演化路径。

Claude Code · Artifacts 已迈出半步

Claude.ai 的 Artifacts 早在 2024 年就已经在用 HTML 容器装代码、画图、做交互，这其实就是 HTML 工件思路的产品化。但 Claude Code（CLI 形态）目前还在 Markdown 的世界里——终端是它的主战场，HTML 工件的渲染要么靠跳转浏览器、要么靠 IDE 插件代理。

可预见的演化：Claude Code 会以配套的轻量本地 web view 形式承接复杂输出（比如 claude code review 时弹一个 diff 工件），主线对话仍然是 Markdown，但关键节点会"分流"到工件。

CodeBuddy · IDE 内置 web view 是天然优势

CodeBuddy 这类深度嵌入 IDE 的 Agent，比 CLI 形态多一张牌：WebView 容器现成可用。从 Skill 元数据 + Hook 触发渲染一个 HTML 工件，工程上几乎是平的。

可预见的演化：Skill 体系里会出现一类"工件型 Skill"——它的 SKILL.md 不输出文本而输出渲染器和导出契约，配合 hub-and-spoke 的目录结构，把"模型生成 HTML 工件"和"工件回灌为 prompt"变成 Skill 调用栈的一部分。

Cursor · 编辑器里的 Agent 还在文字流

Cursor 把 Agent 紧贴编辑器，这是它的优势，也是它的束缚——编辑器界面已经被代码占满了。HTML 工件要往哪儿放？一种思路是侧边栏专属面板；另一种是把工件直接嵌成"内联区块"，类似 Notion 的 mention 卡片。

可预见的演化：Cursor 短期内大概率仍以 Markdown chat 为主，但会引入"工件区块"（如 PR Review 工件、Refactor Plan 工件）作为 chat 内的可交互内嵌，给关键场景定向开 HTML 通路。

Devin / 自主型 Agent · 工件是天然产物

像 Devin 这类长程自主 Agent，每个任务跨度可能是小时甚至天。Markdown 流水账式日志对人类监督来说几乎是噩梦——你根本扫不过来。

可预见的演化：自主型 Agent 会默认产出阶段性工件——任务规划工件、变更总览工件、风险评审工件——人类只需"指着工件说话"，而不是阅读流水账。这一类形态对 HTML 工件的需求最为刚性。

一个共同方向：从"对话"到"协作工件"

把上面四种形态合起来看，一条共同趋势已经很清晰：

Coding Agent 的 UI 范式正在从"对话窗口"过渡到"协作工件"——对话仍然是入口，但重要的输出会以工件形式具象化，并以"导出回 prompt"的方式形成闭环。

这意味着评价一个 Coding Agent 的指标也会跟着变：以前看"它能不能写对代码"，未来还要看"它能不能在合适的时机给出合适形状的工件"。

七、给一线 Agent 开发者的 5 条带走清单

如果你正在设计或维护一个 Coding Agent / Tooling 产品，下面 5 条可以直接抄走：

1. 不要默认 Markdown — 在 Agent 系统提示里明确声明输出形态决策权（“如果用户输出涉及对比 / 结构 / 操作，输出 HTML 工件而非 Markdown”），让模型主动判断信息形状。

2. 关键场景预制工件模板 — 不要指望模型每次现造一个像样的 HTML，把 PR Review、Plan、Module Map、Design Token、Incident Timeline 这类高频场景做成可填充的工件模板，模型只负责填空。

3. 强制内联 SVG 不依赖前端 CDN — Mermaid 之类的 CDN 渲染存在加载与可访问性风险，让 Agent 直接吐内联 SVG——配色与样式自包含，离线也能看，截图分享也保真。

4. 每个交互工件配导出按钮 — 没有导出按钮的工件就是单向广播。导出格式建议默认 Markdown / JSON Patch / Diff 三选一——它们都能直接拼回 prompt。

5. 建立工件可用性的 Eval 指标 — 除了"代码对不对"、“答案准不准”，引入新指标：“工件被用户操作并导出"的占比——这是工件是否真的进入用户工作流的硬证据。

八、总结：HTML 不是新东西，但它的"权重"被重估了

HTML 当然不是什么新技术——它和 Markdown 都已经存在了二十年。变的是 Agent 的角色：当 Agent 从"偶尔回答一个问题"变成"持续协作完成任务”，输出格式的"信息密度"和"反馈循环紧度"就成了核心瓶颈。

Markdown 在 Agent 早期靠简单胜出。但简单是有代价的——它把空间信息压扁、把交互信息删除、把人类决策的反馈通道压窄。

HTML 工件没那么"简单"，但它换来了三件事：

同一份信息可以以 N 个视角同时呈现
用户可以用手表达而不是用文字描述
决策可以一键回灌为下一轮 prompt 输入

这就是 Thariq 标题里那个 unreasonable effectiveness 想说的——HTML 这个"老媒介"，在 Agent 协作时代被无意中做对了一件事：它天生是为"人在循环中"设计的。

下一阶段 Coding Agent 之间的差异化，不会只来自"模型谁更聪明"，还会来自"谁更会选输出形状"。这是 Agent 产品设计的新维度，也是这篇博文里最值得记下的一句结论。

延伸阅读

• The unreasonable effectiveness of HTML — examples · Thariq Shihipar
• Designing, Refining, and Maintaining Agent Skills at Perplexity（与本文「工件型 Skill」推断互补）
• Anthropic Artifacts（HTML 工件的早期产品化样本）

× 爱折腾的工程师

真诚赞赏，手留余香

2元 5元 10元 50元 100元 任意金额

2元

使用微信扫描二维码完成支付

• ← Previous Post
• Next Post →