你的AI智能体不需要更多上下文，它需要的是一个它能够信任的“大脑”。

想象一下，在凌晨2点14分，寻呼机突然响起。你打开操作手册，发现它看起来非常完善：有编号的步骤、图表，还有种种迹象表明有人用心编写了它。你按照第4步操作，却失败了。在页面底部，你看到了最后修改日期：14个月前。

这些文字在编写当天都是正确的。但却没有任何提示表明它们已经过时。

这才是真正的缺陷。问题不在于缺少文档或文档质量差，而在于那些即使在最糟糕的状态下也依然看起来可信的文档。四十年来，软件的发布一直遵循这样的原则：文档就是文字，由读者自行判断。后来，这些文档却被交给了那些无法判断任何事物、却对每一个字都充满绝对信心的工具。

发生了什么变化

人工智能代理没有自身的记忆能力。它是无状态的，每轮对话都会从开头重新发送整个对话内容。Anthropic的文档明确指出：每次都需要发送完整的对话历史。

因此，即使将一个包含4,000个标记的架构文档粘贴到代理始终会加载的文件中，它也只会被读取一次。在40轮的对话中，则会被读取40次。而加载这样的文档反而可能使代理的性能下降。

Chroma的上下文丢失研究测试了18种前沿模型，包括GPT、Claude、Gemini和Qwen，结果发现随着输入长度的增加，准确率会下降，某些情况下甚至从95%降至60%。需要改变人们习惯的是，这并非接近极限时的现象——在他们测量的每一个长度阶段都会出现性能下降。如果这些研究结果成立，那么即便在100万个标记的范围内，达到5万个标记时也会开始出现问题，因为问题根源在于噪声而非处理能力不足。

Anthropic将此称为注意力预算：上下文是一种有限的资源，其边际收益会逐渐递减，目标则是使用尽可能少的高信号标记。这就留下了两个糟糕的选择。

• 加载所有内容。智能体虽能理解系统，但在各项任务上的表现明显变差，且每次修改文档都会使整个提示缓存失效，需要重新生成。
• 不加载任何内容。智能体虽保持敏锐，但却一无所知，因此只能即兴应对，要么编造出某个部署步骤，要么运行早在3月就已废弃的命令。

各团队会在这两种方案间切换，承受相应弊端，这大致就是当前行业的现状。

已有简明的诊断结论

2026年4月，安德烈·卡帕西发布了一篇简短的摘要，他将其称为“想法文件”。那既不是产品也不是库，而只是概述了一种方法：模型将原始资料整理成结构清晰的Markdown维基文档，此后问题就会被发送到该维基而非原始资料。

其中关键的那句话与人工智能毫无关系：人们放弃使用维基是因为维护成本的增长速度超过了其带来的价值。

凡是见过 Confluence 页面逐渐废弃的人都会明白这一点。人们放弃使用它并非因为写作太困难，而是因为维护太麻烦，而维护工作大多都是些繁琐的文书工作：更新链接、修改摘要、标记某页面与另一页面内容矛盾、修正索引。这些工作之所以不再那么费力，正是因为大语言模型不会感到厌烦，不会忘记交叉引用，还能一次性处理十五个文件。它的分工非常简单：你负责阅读，大语言模型负责撰写。

这一理念迅速传播开来。两个月后，Google Cloud 发布了一项规范，根据其官方说明，该规范将基于大语言模型的维基模式转化为一种可移植、可互操作的格式。其背后的核心思路仍是 Karpathy 的观点，这也解释了为何这些方法在如今可行，而在2019年却行不通。

半分钟内了解 OKF

开放知识格式OKF由谷歌云的Data Cloud团队于2026年6月以草案版本（v0.2）形式发布，它实际上是对该格式的正式规范。从技术层面来看，它只是一个包含YAML前置信息的Markdown文件目录，仅此而已。

该规范的宣传语是：任何能够使用cat命令读取文件的工具都能解析OKF，而任何能够使用git clone命令克隆代码库的人都可以分发它。

其中只有type字段是必填的。只要一个文件包含type字段，即视为符合规范。整个过程无需任何模式注册表、数据库、嵌入流程、供应商锁定机制或SDK。

okf/
  index.md                  ← table of contents
  billing/
    index.md
    invoice-retries.md      ← one file, one answerable question
  flows/
    customer-offboarding.md

如果你的反应是“原来是个 Markdown 文件夹”，那确实没错。格式并非关键所在，有人会合理地指出文件夹本就不需要规范。谷歌的声明给出了答案：Karpathy 的维基、团队的维基以及供应商的目录导出虽然都包含 Markdown、前置信息及交叉链接，但它们并非为相互协作而设计。这正是需要制定规范的理由——大家各自独立地形成了相同的格式，而这通常意味着该格式是正确的，随后各个实现又各自创造了不同的字段名称。格式的作用就是将多种私有的约定规范整合为一种任何工具都能读取的内容。

核心理念：文档即状态

以下是一份示例文档：

---
type: Playbook
title: Invoice retry policy
status: stable                      # draft | stable | deprecated
stale_after: 2026-11-01             # stale when today >= this date
generated: { by: "human:dana", at: 2026-08-10 }
verified:  [{ by: "human:sam",  at: 2026-08-11 }]
sources:
  - resource: services/billing/retry.go
    last_modified: 2026-07-15
not:
  - term: "restart the worker to clear the queue"
    why: "in-flight jobs are lost, they are not re-queued"
    instead: "drain first, then restart"
---

所示的字段中有五个来自规范要求。第六个最为重要，稍后会再次出现。

文件柜仅用于存储文档。大脑同样知道自己存储了什么、对信息的置信度如何，以及哪些错误让自己获得了教训。下表对应了这些功能：

现在就以机器的方式来解读那些前置信息吧。stale_after代表的是过期日期，而非需要人们自行解读的“最后更新时间”标记。它是一个绝对日期，因此可以将文档过时问题简化为简单的比较——today >= stale_after。任何程序都可以执行这项检查：读取文件的脚本、定时任务，或是你的持续集成系统。

仔细想想这一点。自从维基出现以来，文档过时问题就一直是个普遍存在的文化问题。各种催促、定期的文档检查、季度审计，再加上那页本身也已经过时的“文档标准”说明。所有这些措施都依赖于社会压力，而且根本无法强制执行。而有了stale_after之后，文档过时问题就变成了一个测试失败的情况，与构建失败属于同一类别。它要么通过测试，要么失败，这样就没人需要为此感到内疚了。

其他字段的运作方式相同。sources列出了文档所描述的代码路径，这样脚本就能回答维基系统永远无法解答的问题：这个拉取请求修改了三份文档都声称要解释的文件，那么有人更新过这些文档吗？verified记录的是确认文档的人，与撰写文档的人是分开的，因为按照规范的说法，撰写某个概念的人不一定是确认它的人。由代理人提交的草稿与高级工程师的最终确认是两件不同的事情，而大多数文档工具从未对这种区别进行记录。信任等级是根据执行者前缀确定的，并不会被存储下来，因为存储的评分具有主观性，无法在不同使用方之间通用，而且会过时。

status: deprecated 允许你保留旧的定义而不删除它。当两个控制面板对“收入”这一数据的数值存在差异时，原因往往并非数据有问题，而是存在两种不同的定义，其中一种被悄悄替换了，却没有任何标记。只要保留两种定义并给其中一种加上标记，上个季度的数值依然可以准确呈现。

这就是变化所在：不再是单纯的文本格式，而是加入了可查询的状态。文档可以被查询、测试，也可能会出现错误。

令牌运算

这些数值是根据谷歌公布的示例数据集测得的，因此可以对其进行验证：

当智能体决定查找时 2 一份文档 约656个标记 当智能体选择其中一份时

从头到尾处理一条事实大约需要950个标记，仅在对此有需求的提示中才会收费。始终开启的功能属于0级：60个标记，一句话。

与之相比的是传统方法：尽管可能每十条提示中只有一条需要，但仍然会在每条提示中加入1,600个标记的指南。虽然知识内容相同，平均费用仅为前者的十分之一，而且文档可以无限扩展，因为额外的长度不会再影响仓库中其他无关的对话。该规范正是基于这一目标创建了index.md，并将其命名为“渐进式披露”：先查看已有的内容，然后再打开文档。

OKF并非什么

OKF并不能起到防护作用。Markdown文件无法阻止智能体执行破坏性操作，真正的约束必须通过代码实现，比如黑名单和预执行钩子，无论模型做出何种选择都能阻止相应操作。无论你还记得什么，都不要以为把风险写下来就意味着自己得到了保护。

OKF真正带给你的是一个知晓规则的智能体。该规范还定义了一种“经验证的计算”类型，在这种类型中，智能体可以传递参数，但绝不能编写或修改计算逻辑本身，这已经是尽可能接近禁止重写安全检查措施的做法了。可以关注这一机制，但目前还不宜基于它进行开发：规范明确指出该接口将推迟到后续版本中实现。

请记住这只是一个草案。从 v0.1 到 v0.2 的升级已经修改了两个构件的名称，因此只需使用您需要的那八个字段。之后如需重新命名，只需进行查找替换即可。

从小处着手，必要时再增加约束

这并非一个项目，而只是一个文件。

1. 针对最近让某人耗费了半天时间处理的任务，编写一份包含 type、title、description 和 stale_after 字段的文档。
2. 编写一个 index.md 文件来列出这些文档，添加“何时阅读”一列，并写入 okf_version: "0.2"。该字段应放在根级索引中，根据规范，索引也只能包含这一项前置信息。

将指针添加到您的常驻文件中。这大约需要六十个令牌，其中包含路径和触发条件，绝不会包含摘要，因为摘要既会增加常驻文件的成本，还会促使智能体去打开该文件。

这样就可以开始使用了。由于 today >= stale_after 只是一种比较操作，智能体可以在文件一被打开时就对其进行评估。对于过期的文档应如何处理则由您决定，规范也刻意留下了这一灵活性。

当有第二个人能够在不阅读文档的情况下使其失效时，就需要加入自动化机制。这才是真正的临界点，它更多关乎团队规模而非准确性。如果只有五份文档，你自己就能察觉问题，此时代理端的过期检查就足够了。但在团队环境中，任何破坏文档的人按定义都是从未打开过它的人，因此良好的意愿无法传达给他们，就必须通过拉取请求流程中的机制来解决。较为简单的方案是设置定时任务来报告过期的文档；更为严格的方案则是设置拉取请求关卡，在检测到文档过期时予以阻止，并在文档所描述的代码被修改时发出警告。建议从较简单的方案开始。

简版

智能体所需要的并非更大的上下文窗口，而是知道该去何处查找信息，而且它打开的任何文件都必须如实显示其更新时间。初始提供60个标记，其余内容按需获取；同时，一旦文件内容不再准确，就会导致构建失败，而这在以往是无法实现的。

延伸阅读：OKF v0.2规范及示例包、Google Cloud关于该格式的文章、Anthropic关于上下文工程、智能体技能及提示词缓存的论述，以及Chroma关于上下文过时问题的研究。

相关阅读

• 实用笔记：你的编程助手不需要更多上下文，它需要的是一张地图。 — 《实用笔记：你的编程助手不需要更多上下文，它需要一张地图》的实操指南：适用于采用该模式的团队的契约、检查项以及可直接插入的代码片段。
• 实用笔记：你的编程助手不需要更优的提示词 — 《实用笔记：你的编程助手不需要更优的提示词》的实操指南：适用于采用该模式的团队的契约、检查项以及可直接插入的代码片段。

实用指南：2026-27年以色列科技雷达：智能体时代的工程实践 — 该实用指南的详细操作指南，涵盖合同、检查项以及适用于采用该模式的团队的可直接插入的代码片段。