字数 3181，阅读大约需 16 分钟

给Agent用的文档格式，为什么Markdown不够用了——ObjectGraph格式解析

做过Agent开发的同学大概率都踩过同一个坑：不管是技能文件、运维手册还是执行计划，只要是给Agent读的文档，基本都是整份丢进上下文窗口。一份上千行的部署手册，真正和当前任务相关的可能就几十行，剩下的全是无效token。多轮对话走下来，历史记录里堆着好几份读过的文档，token消耗翻着倍涨，模型注意力还容易被无关内容稀释。

很多人会想办法优化：做上下文压缩、接RAG检索、拆小块……但这些都是在“怎么读文档”上做文章，没有碰最底层的问题：文档本身的格式，从一开始就是给人设计的，不是给Agent设计的。最近有篇论文提出了一个叫 ObjectGraph（.og后缀） 的新文档格式，直接从格式层面解决Agent消费文档的效率问题。它把文档从“线性字符串”重新定义成“带类型的有向知识图谱”，Agent可以像遍历图一样按需取内容，不用整份加载。实测下来最多能减少95%的token，同时任务准确率没有明显下降。

一、Markdown的三个先天问题

Markdown是2004年为人类创作网页内容设计的，它的底层假设很简单：人从上到下线性阅读，靠眼睛判断哪里重要。这些假设放到Agent身上全不成立。论文里把问题总结成三种失效模式：

第一，Token通胀。一份文档n个token，真正和任务相关的只有很小一部分。论文统计了1247次真实Agent任务执行，平均内容利用率只有6.3%——也就是说，塞进上下文的文档里，93.7%的内容都是纯浪费。

第二，上下文累积放大。LLM接口是无状态的，每一轮调用都要传完整对话历史。一个5轮的工作流，如果中间读了3份文档，每份1800token，累积下来的传输开销能到一万五千token以上，是文档本身成本的好几倍。这不是文档本身的问题，是全量读取模式在多轮场景下的必然结果。

第三，角色盲视。多Agent系统里，编排Agent、执行Agent、监控Agent需要的文档内容不一样。比如密钥配置只需要编排Agent看到，执行Agent只要知道调用方式就行。但现有格式做不到按角色分发内容，要么全给，要么靠外部中间件做权限控制。

从这三个问题出发，论文推导出了Agent原生文档格式必须满足的6个属性：可查询索引、分层压缩、类型化依赖图、角色权限、可执行断言、人类可读。我们可以看下现有格式的满足情况：

表1 各文档格式的属性满足情况对比

可以看到，没有一个现有格式能同时满足这六点。这也是论文认为必须设计新格式的核心原因。

二、ObjectGraph的核心设计

ObjectGraph的核心想法很直接：把文档拆成一个个独立的语义节点，节点之间用带类型的边连起来，形成一张知识图。Agent不用整份读，先看索引，再按需取节点内容。

1. 文件结构：三个头部 + 节点主体

每份.og文件开头都有三个必选的头部块，是给Agent快速索引用的：

• • ::meta：文件元数据，包含标题、版本、领域、校验和
• • ::schema：声明节点类型、边类型、权限级别
• • ::index：核心路由表，记录每个节点的ID、类型、权限、置信度、关键词，一份普通技能文件的索引大概只需要30token

真正的内容以节点为单位存储。每个节点有稳定ID、类型、权限、置信度，内部再分成不同粒度的内容块。比如一个安装步骤节点，会有密集关键词版、完整说明版、步骤列表版、代码版、警告提示版，对应不同的读取深度。

2. 渐进式披露：三层读取，按需拿取

这是ObjectGraph节省token的核心机制，叫渐进式披露模型（PDM）。读取分三档逐层深入：

• • 索引层：只读meta和index，约30token，用来判断哪些节点和当前任务相关
• • 密集层：读取匹配节点的::dense块，每个节点约10-15token，足够用来做路由和规划
• • 完整层：真正执行任务时，才读取::full、::code、::steps这些完整内容，每个节点约100-300token

算一笔账：一份1800token的文档，传统方式全读要1800token。用ObjectGraph的话，索引30 + 2个节点密集层24 + 1个节点完整层180 = 234token，直接减少87%的token消耗。

3. 类型化边：自动遍历依赖

节点之间的依赖关系用边声明，比如:requires（前置依赖）、:precedes（后续步骤）、:see-also（参考延伸）。当你查询一个节点的时候，协议会自动顺着:requires边把所有前置依赖节点也取回来。比如查询“生产部署”节点，会自动带上“环境配置”和“密钥获取”的依赖，不用Agent自己再发起一次查询。

4. 原生角色权限与可执行断言

每个节点都有scope属性，标记哪些角色可以查看。索引层就会暴露权限信息，没有权限的Agent连这个节点的存在都感知不到。比如同样是“API密钥”节点，编排Agent看到的是真实的Vault读取命令，执行Agent看到的只有调用接口说明。这件事是格式原生支持的，不用额外搭建权限中间件。

另外还有断言节点，把校验逻辑直接写在文档里：触发条件、检查项、成功路径、失败重试次数、重试失败后的升级流程。相当于把校验逻辑从Agent提示词里挪进了文档本身，步骤完成后自动触发校验，不用额外写判断逻辑。

下图展示了两种典型的部署架构，分别对应小文件和大文件场景：

图1 ObjectGraph的两种查询架构

• • 架构A（小文件）：把索引块直接注入系统提示，Agent直接调用解析接口取节点，没有额外工具调用开销
• • 架构B（大文件）：用轻量模型做路由Agent，负责搜索索引筛选节点，执行Agent只拿到解析后的内容，完全没有工具调用历史，从根源上避免上下文累积

三、查询协议：两个原语就够

整个查询协议设计得非常克制，只有两个核心原语：

1. 1. search_index(f, q, r)：给定文件路径、查询语句、角色，返回匹配的节点ID列表
2. 2. resolve_context(f, N)：给定节点ID集合，返回节点完整内容 + 自动遍历依赖节点

简单说就是“先搜索引找节点，再取节点内容”。而且索引匹配不是简单的关键词匹配，是LLM自己读取索引用语义判断，比传统BM25或者向量匹配更适合领域内的技能文档。

还有个很实用的设计：会话级别的“已读跳过”。标记了skip-if-known的节点（比如基础概念说明），一个会话里只会加载一次，后面再遇到依赖也不会重复加载，进一步节省token。

四、实测效果：省token，还不降准确率

论文用240份文档、8类任务做了完整测试，对比全量Markdown、RAG、SkillReducer几个基线方案。

1. Token消耗：平均减少92%

图2 各类文档的单次查询平均token消耗

在所有文档类别上，ObjectGraph的token消耗都远低于全量Markdown和RAG。尤其是体积较大的运维手册，Architecture B架构能做到接近99%的缩减。平均下来，单次查询token数从2340降到187，减少92%。

2. 多轮累积：差距越拉越大

图3 5轮工作流的累积token消耗

第5轮的时候，全量Markdown累积了46000token，而ObjectGraph Architecture B只有1260token，相差36.5倍。原因很直观：Markdown每读一次文档就往历史里堆一次，越往后负担越重；而ObjectGraph的执行Agent每轮只拿当次需要的内容，没有历史包袱，token增长接近线性。

3. 任务准确率：多数任务反而更好

表4 各类任务的准确率对比

这个结果有点反直觉：少读了那么多内容，准确率怎么还更高？论文给出两个解释：一是去掉无关内容减少了注意力稀释，模型不容易被干扰；二是明确的内容类型标签（比如::warning、::steps）帮模型更准确地解析结构。只有跨节点推理这一项，全量Markdown因为上下文完整，略有优势。但加上边声明的自动依赖遍历之后，差距已经缩小到1.8%，基本可以忽略。另外像角色权限、更新检测、断言校验这几项，Markdown本身没有对应能力，所以ObjectGraph优势特别明显。

4. 转译保真度

现有Markdown文档不用手动改造，论文提供了一个三阶段转译器：规则引擎拆分结构，LLM只生成索引和密集关键词，最后做保真校验。在180份留出集文档上，平均保真度达到98.7%，所有文档都能通过95%的部署阈值。而且LLM完全不触碰正文内容，只生成导航元数据，幻觉风险被控制在路由层面。

五、一点总结和思考

ObjectGraph这套思路最有价值的地方，是把“Agent怎么读文档”这件事从检索优化、提示词优化，下沉到了文档格式本身。它的适用场景很明确：Agent技能库、运维手册、执行计划、技术文档、多Agent共享知识库这些场景，只要现在在用Markdown编写、Agent全量读取的，换成.og格式都能拿到很可观的token收益，同时还能获得角色权限、自动校验这些额外能力。而且它是Markdown的严格超集——任何一份.md文件都是合法的.og文件，可以渐进式迁移，不用一次性全量改造。

当然目前也有局限。比如还不支持跨文件的边引用，只能单文件内部遍历；没有统一标准，容易出现不兼容的方言；也没测试过恶意构造的误导性索引。论文自己也提到，下一步最值得做的是跨文件联邦的标准协议，让.og文档能组成跨仓库、跨组织的分布式知识图谱。

总的来说，这是一个很务实的技术方向：Agent生态发展到今天，我们需要的不只是更强的模型，也需要更适合机器消费的信息载体。从“给人看的文档”到“给Agent用的文档”，格式层面的进化可能是下一个很落地的增长点。

https://arxiv.org/pdf/2604.27820