AI Agent 时代，为什么我放弃 Markdown 全面转向 HTML
原文作者：Thariq（@trq212），Claude Code 团队工程师
原文发布于 2026 年 5 月 9 日
背景
Markdown 已经成为 AI Agent 与我们沟通时的主流文件格式。它简洁、可移植，具备一定的富文本能力，并且便于编辑。Claude 甚至已经擅长在 Markdown 文件中用 ASCII 字符绘制图表。
但随着 Agent 能力越来越强，我开始觉得 Markdown 成了一种束缚。
Markdown 的局限性
信息密度低
超过 100 行的 Markdown 文件读起来就很吃力。当 Claude 需要表达：
- 表格数据
- 设计系统（颜色、组件）
- 图表和插图
- 交互效果
Markdown 只能：
- 画丑丑的 ASCII 图
- 用 unicode 字符近似呈现颜色（如 🟣🟢🔴）
- 贴截图或图片链接
视觉体验差
Markdown 扁平化了一切。代码 diff、流程图、模块关系——这些空间信息在 Markdown 里全部被压成一维文字。
当方案的复杂度超过一屏时，Markdown 从"文档"变成了"阅读障碍"。
分享不便
大多数浏览器不能原生渲染 Markdown 文件。你只能：
- 作为邮件附件发送
- 粘贴到 GitHub 评论里
- 上传到某个平台（Notion、飞书等）
而 HTML？上传到 S3 或任何静态托管，一个链接就能分享。
HTML 的优势
几乎能表达一切信息
| 信息类型 | Markdown 能做 | HTML 能做 |
|---|---|---|
| 表格 | ✅ 简单表格 | ✅ 复杂表格、排序、筛选 |
| 设计系统 | ❌ 只能贴色值 | ✅ 可点击的颜色面板、组件预览 |
| 图表 | ❌ ASCII 图 | ✅ SVG 矢量图、Canvas 交互图 |
| 代码 | ✅ 代码块 | ✅ 带语法高亮、行内注释、复制按钮 |
| 动画/交互 | ❌ 无法描述 | ✅ 真实动画、滑块、旋钮 |
| 地图/空间数据 | ❌ | ✅ Canvas 或集成地图服务 |
视觉清晰 + 易于导航
HTML 可以做到：
- 标签页切换
- 可折叠章节
- 侧边栏导航
- 响应式布局（手机/电脑都舒适）
- 彩色时间线和小节标题
一份 HTML 文档，读起来的体验完全不一样。
可交互
这是最关键的一点。Markdown 是只读的，而 HTML 可以是工具。
比如：
- 一个带滑块的动画原型，调到满意的效果后导出参数
- 一个可拖拽的工单看板，排序完成后导出 Markdown
- 一个 prompt 编辑器，左边写模板、右边实时预览渲染结果
诀窍永远是一个导出按钮：把你通过 UI 操作的结果，转换回可以粘贴给 AI 的格式。
Claude Code 的上下文优势
Claude Code 能接入的上下文非常丰富：
- 文件系统
- Git 历史
- Slack、Linear 等 MCP
- 浏览器（Claude in Chrome）
这些上下文让 Claude 可以生成真正个性化的 HTML：基于你的代码库、你的风格、你的数据。
典型使用场景
1. 需求探索与规划
不再是写一个 Markdown 方案文件，而是生成一组 HTML 的网络：
- 先头脑风暴，探索多个方向
- 挑一个深入展开，做原型和代码片段
- 最后输出实施方案
验证阶段，让验证 Agent 读取这些 HTML 文件，它能获得更丰富的上下文。
Prompt 示例：
我不确定该往哪个方向做引导界面。生成 6 种截然不同的方案，在布局、调性、信息密度上都要有差异——排成网格放在一个 HTML 文件里供我对比，每个都标注它在做什么取舍。
2. 代码评审
代码在 Markdown 里很难读，但 HTML 可以渲染：
- 带行内注释的 diff
- 模块关系图
- 流程图
这比 GitHub 默认的 diff 视图更好用。现在每个 PR 都附上一个 HTML 代码讲解。
Prompt 示例：
帮我评审这个 PR，做一个 HTML artifact 来描述它。我对其中的流式/背压逻辑不太熟悉，重点关注那部分。把 diff 渲染出来，在边栏加上行内注释，按严重程度给发现的问题着色。
3. 设计与原型
动画和交互不能被描述，只能被感受。一个 throwaway HTML 页面，用真实的缓动曲线、真实的点击效果，五秒钟就能验证一个想法。
Prompt 示例：
我想做一个新的结账按钮原型，点击时先播放动画然后变成紫色。做一个 HTML 文件，提供多个滑块让我尝试不同效果，加一个复制按钮导出参数。
4. 自定义编辑器
有时候很难用文字描述你想要什么。这种时候，让 Claude 做一个一次性的专用编辑器：
- 拖拽排序 30 个工单 → 导出 Markdown
- 编辑功能开关配置 → 导出 diff
- 调试 prompt 模板 → 实时预览 + 字符计数
核心原则： 永远以一个导出按钮结尾。
5. 研究报告
Claude Code 非常擅长综合多个数据源的信息：Slack、代码库、git 历史、互联网……生成可读性极强的报告。
- 长篇 HTML 文档（带图表、时间线、可折叠章节）
- 交互式讲解
- 幻灯片/演示稿
如何开始
你几乎不需要做任何特殊配置。直接说：
"做一个 HTML 文件" 或 "做一个 HTML artifact"
关键在于你知道自己想要这个 artifact 做什么，以及怎么用它。
常见问题
Q：HTML 不是更费 token 吗？
确实更费。但在 Opus 4.7 1MM 的上下文窗口下，多用一些 token 几乎感受不到。更重要的是，HTML 让我读它的可能性大大提高——整体收益更好。
Q：HTML 生成不是比 Markdown 更慢吗？
确实更慢，2-4 倍。但我觉得结果是值得的。
Q：版本控制怎么办？
这是 HTML 最大的缺点之一。diff 体验确实差。不过，如果你的使用场景是"AI 输出 → 人阅读/操作 → 导出结果"，版本控制本来就不重要。
Q：怎么让生成的 HTML 更好看？
可以用 frontend design 插件。如果想匹配公司风格，可以让 Claude 读你的代码库，生成一个统一的设计系统 HTML 文件，作为其他 HTML 的参考。
总结
Markdown 的简单性，在 AI 输出越来越复杂的时代，反而成了瓶颈。
当你发现自己在 Markdown 里画 ASCII 图、用 unicode 近似颜色、内容超过一屏时——就该换 HTML 了。
HTML 让 AI 生成的内容从**"读的文档"变成"用的工具"**。你不是在读一个方案，而是在使用一个为你定制的小工具。
最终，这一切都回归到一个核心：Stay in the Loop。
当 AI 越来越强，你越来越依赖它工作时，确保你仍然在环中，而不是放手让它自己做所有选择。HTML 做到了这一点——让我感觉自己和 AI 的协作更紧密、更高效、也更有趣。