Agent文档,为什么转向HTML

先看结论

当 Agent 的产物从短答复扩展为规格说明、实现计划、研究报告、代码评审和可交互原型，文档格式就不再只是保存文本的容器。它会影响人是否愿意打开、是否能快速理解、是否能继续审阅和修正模型产出。

Thariq 的核心判断是：在复杂产物上，HTML 比 Markdown 更适合作为人类阅读、评审和分享的界面。HTML 可以同时承载结构、图表、颜色、交互和导出动作，让 Agent 产物从“线性文本”变成可操作的工作界面。

这背后的重点是保持人在循环中。若计划和报告越来越长，而人不再认真阅读，Agent 实际上就获得了更大的隐性决策空间。更好的输出界面，可以让人重新参与判断、比较和取舍。

Thariq 的核心观察

Markdown 简单、可移植、便于编辑，因此很自然地成为 Agent 与人沟通的默认格式。Claude 甚至已经能在 Markdown 中用 ASCII 字符画出相当复杂的图示。

问题出现在产物复杂度上升之后。超过一百行的 Markdown 计划，很多人不会完整阅读；组织内的同事也未必愿意打开一个长 Markdown 附件。与此同时，用户越来越少直接手动编辑这些文件，更多时候是继续提示 Claude 修改。Markdown 原本“便于手改”的优势随之下降。

HTML 则提供了另一种工作表面。它可以用表格呈现数据，用 SVG 绘制图示，用 CSS 表达设计，用 JavaScript 加入交互，用图片和布局组织复杂上下文。对于规格说明、设计方案、PR 解释和研究报告，这些能力会直接提升可读性。

Markdown 开始受限的场景

Markdown 仍然适合保存原始文本、记录清单、维护 README、存放可搜索底稿。但在几类任务中，它会显得吃力。

在这些场景里，Markdown 依然能够表达信息，但表达成本更高，阅读者更容易放弃。

HTML 提供的增量

HTML 的价值首先是信息密度。表格、图示、代码片段、图片、时间线、流程图和说明文字，可以被组织到同一个页面中。读者不必在多个文件之间切换，也不必把 ASCII 图表重新想象成真实结构。

其次是视觉清晰度。Agent 可以为不同信息设置层级、颜色、间距和布局，也可以加入目录、标签页、折叠区和响应式设计。复杂内容因此更接近“可阅读产品”，减少纯文本输出带来的理解负担。

第三是双向交互。HTML 可以加入滑块、开关、拖拽、预览和复制按钮。用户可以在页面里调整参数，再把结果复制回 Agent。对于 prompt 调优、配置编辑、设计动效和任务分桶，这种一次性工具比纯文本描述更高效。

第四是分享。HTML 文件放到稳定地址后，可以像普通网页一样发送给同事。相比 Markdown 附件，打开和引用的门槛更低，团队实际阅读的概率更高。

实践侧的结论

后续处理 Agent 产物时，可以采用三层结构。

第一层是底稿层。Markdown、JSON、原始网页、原始 transcript、原始 PDF 等继续作为 source of truth。它们适合版本管理、搜索、复用，也适合再次喂给 Agent。

第二层是阅读与评审层。长文、双语阅读、研究报告、方案对比、代码解读、PR 说明、设计探索和交互式编辑界面，默认应提供 HTML 阅读入口。这里的目标是让人更容易进入内容，更容易发现结构和问题。

第三层是分发与兼容层。Markdown、PDF、笔记软件版本仍然保留，用于归档、同步、搜索和降级阅读。HTML-first 的含义是：Markdown 保留为可维护底稿和备选格式，HTML 承担主要阅读入口。

这个划分可以避免两个极端：一端是所有内容都停留在线性 Markdown，导致复杂产物难以审阅；另一端是把所有源文件都改成 HTML，导致 diff、搜索和长期维护成本上升。

适用边界

HTML 也有明确代价。它通常生成更慢，消耗更多 token；HTML diff 噪声较大，不如 Markdown 容易审阅；带脚本的 HTML 还需要注意安全边界，不能把不可信内容直接当成可执行页面分享。

因此，HTML 更适合“给人读、给人评审、给人操作”的最终阅读层。底稿、元数据、规则文档、索引和可长期维护的源文件，仍应优先使用 Markdown 或结构化数据。

对 Agent 工作流而言，真正值得保留的原则是：源文件要可维护，阅读入口要足够清晰。前者服务长期复用，后者服务当下判断。

一句话总结

Agent 时代的文档格式，正在从“写给机器和版本库看的文本”，扩展为“让人审阅 Agent 工作的界面”。HTML 的意义在于让复杂产物更可见、更可读、更可操作，同时保留 Markdown 的可维护价值。