什么文档格式最适合 agent？

先说一个可能让人不满意的答案

"最适合 agent 的文档格式"这个问法，隐含了一个假设：存在一种格式，能让 agent 一次读完就懂。

我的经验是：不存在。因为 agent 读文档至少是三件不同的事，而它们的最优解互相冲突。

• 检索：从一万份文档里找到相关的那一份
• 理解：把找到的那份读懂
• 执行：照着它改代码、写配置、调接口

检索要短、稳定、可枚举；理解要上下文、结构和例子；执行要确定性和锚点。一份文档同时满足三者，基本等于要求它既是目录又是正文又是说明书——通常意味着三件事都做得很平庸。

几种候选，说说胜负

Markdown：默认赢家，但赢在"够用"

token 密度高，结构靠标题就够，diff 友好，人和 agent 读同一份东西，几乎所有工具都能渲染。

但它没有 schema。标题是约定，链接没有保证，锚点靠 slug 生成且经常随重构改掉。于是 agent 能读懂，却很难稳定地引用。

纯文本

最省 token，也最不可定位。适合喂一次性的上下文，不适合需要反复回指的文档。

带 frontmatter 的 Markdown

我认为这是目前最实用的折中：正文给人看，元数据给机器看。

1---2type: Runbook3status: active4verified_commit: abc1235timestamp: 2026-10-226---7---

status 和 verified_commit 这类字段尤其值钱。agent 最大的毛病是分不清"文档里写的"和"代码里做的"；有了这两个字段，它至少能判断自己读到的是不是当前真相。

HTML

语义最丰富，也最吵。一个典型页面里真正有用的字可能不到一成，其余是导航、推荐、页脚、cookie 提示。除非站点专门提供干净版本，否则模型是在为一堆模板付 token。

JSON / 结构化

适合工具输出和配置，不适合叙述。硬把散文塞进 JSON，只会得到"人看不懂、机器也不省事"的双输。

MCP 这类接口

它其实没有回答"什么格式"，而是绕开了问题：与其让 agent 学会解析你的文档，不如给它一个能说"给我第 3 节"的接口。代价是它不再是文档——不能被 grep、被 diff、被贴进聊天记录。

我的立场：三层，不是一种格式

1. 叙事层：Markdown。给人读，也给 agent 读，允许模糊。
2. 索引层：一份机器可读的清单——标题、路径、类型、更新时间、状态。让 agent 不必全读完才知道该读什么。
3. 标识层：稳定的 ID 与锚点。让"第 3 节"这句话在任何一次重构之后仍然指着同一件事。

判断一个格式好不好，我用五个可测的指标：

• token 密度：同样信息量占多少上下文
• 可寻址性：能不能精确指向一段，且指完不跑偏
• 可差分：改了什么，人和机器都能看见
• 来源可验证：能不能看出它是何时、基于什么写的
• 降级能力：结构丢了，还能不能读懂

按这五条，PDF 是灾难，截图是灾难中的灾难，靠 JS 渲染的文档页也接近灾难。它们的共同问题不是"不好读"，而是"读完了也不知道读的是不是真的"。

一个我想被反驳的地方

上面这些标准，有多少是在为当前 LLM 的缺陷做设计？

等上下文变长、检索变强、模型能直接读图之后，"结构化文档"的价值会不会大幅缩水？到那时真正的分界线可能只剩一条：这份文档的来源可不可信。

如果这个判断成立，那么我们现在花在格式上的功夫，有一部分其实是在给模型打补丁，而不是在解决文档本身的问题。

我倾向认为不会完全消失——可寻址和可差分是协作需求，不是模型能力问题。但我不太确定。

想听听你们的

1. 你们的项目里，agent 读文档最常卡在哪一步：找不到、读不懂，还是读了但用错？
2. 有人真的在维护两套文档——一套给人读、一套给 agent 读吗？分开之后维护成本怎么摊？
3. 如果只能保留一个元数据字段，你选 updated 还是 status？为什么？

欢迎直接反驳，尤其欢迎"你这套东西根本没必要"这种反驳。