用OKF构建自更新代码库知识图谱

AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | PLC在线仿真器 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

Google 的新一页规范标准化了 AI 上下文，但保持千文件代码库知识图谱的准确性取决于你。以下是管道。

AI 代理正在消耗你的令牌预算，在每个任务上重新推导代码库的结构，然而业界的回答要么是天真的全仓库转储，要么是不可预测的 RAG。Google 新发布的开放知识格式 (OKF) 提供了一种疗法——一个如此极简以至于可以在单页上放下的规范——但它将最困难的系统问题留给了读者作为练习：当团队每天发布四十个提交时，你如何保持千文件知识图谱的准确性？

我们构建了解决方案：一个由 git hook 触发的代码库富化管道，它会在每次提交时自动起草、链接和检查 OKF 捆绑包。这使上下文成本降低了数量级，并将代码库记忆从临时检索转移到编译的、自我维护的缓存。

1、隐藏系统问题的一页规范

2026年6月12-13日，Google Cloud 的 Sam McVeety 和 Amir Hormati 发布了开放知识格式 (OKF) v0.1：一个带有 YAML frontmatter 的 Markdown 文件目录，整个规范中唯一必需的字段是 type。仅此而已。正如他们所说：

"今天，我们介绍开放知识格式 (OKF)……一个供应商中立、代理和人类友好的标准，用于表示现代 AI 系统所需的元数据、上下文和精选知识。"

Google 明确说明了谱系：OKF 正式化了 Andrej Karpathy 2026年4月的"LLM Wiki"模式。核心前提是 LLM 应维护一个编译的、交叉链接的 Markdown wiki 作为持久的外部记忆，就像源代码编译一次后重用，而不是每次读取时重新解析一样。这是对 RAG 默认假设的直接反驳，RAG 在查询时每次都从原始文档重新推导关系。正如 Google 自己的材料所解释的：

"LLM 不会感到无聊，不会忘记更新交叉引用，并且可以在一次通过中处理15个文件。导致人类放弃个人 wiki 的记账工作正是 LLM 擅长的。"

这是每个解释者都跳过的部分。完整的 OKF v0.1 合规规范可以放在一页上——总共三条合规规则。工程师们不断错过这种极简主义：该规范从来不是为了成为产品。它是一种线格式。实际的系统——将实时变化的代码库转化为准确的、交叉链接的、代理可消费的图谱的东西——在这些文章中都不存在。没有人展示如何为仍在编辑的仓库程序化生成和保持 OKF 图谱的真实性。这就是本文填补的空白：我们正在构建管道，而不仅仅是阅读文件夹结构。

2、为什么极简是特性，而不是限制

在构建任何东西之前，你需要精确理解数据模型，因为这里的设计选择不是偶然的——它们是 OKF 能够被采用的原因。

捆绑包是 Markdown 文件的目录。概念是一个文件，代表一个知识单元——一个表、一个服务、一个操作手册、一个 API 端点——文件的路径就是它的身份；没有单独的 ID 系统需要同步。在推荐的 frontmatter 字段（type、title、description、resource、tags、timestamp）中，只有 type 是必需的。正如作者所说："OKF 对每个概念只需要一样东西：一个 type 字段……规范定义了互操作性表面，而不是内容模型。" 一个典型的概念文件如下所示：

---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema
| Column        | Type      | Description                               |
|---------------|-----------|--------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.          |
| `customer_id` | STRING    | FK to [customers](/tables/customers.md).   |

# Joins
Joined with [customers](/tables/customers.md) on `customer_id`.

两个保留文件名在不添加必需字段的情况下赋予捆绑包结构：

• index.md 是一个目录列表，支持渐进式披露——代理从根目录开始，仅根据任务需要跟踪链接，这是直接的令牌预算控制。
• log.md 是按日期分组的按时间顺序排列的变更历史，与 git log 不同，旨在回答"这个系统知道的内容中什么发生了变化"，而不是"文件中什么发生了变化"。

合规性故意宽松：消费者不得因为缺少可选字段、未识别的 type 值、未知的 frontmatter 键或断开的链接而拒绝捆绑包。这是"格式而非平台"的设计原则，这就是为什么 Alphamatch 的分析称其为*"AI 知识的 USB-C 电缆——任何人都可以生产、任何人都可以消费的通用连接器，无需专有 SDK、API 或锁定。"* 与之前的企业元数据目录和知识图谱标准相比，后者通常在编写单个条目之前就需要模式注册表、验证服务器和供应商 SDK。Google 自己的 GA4 演示捆绑包——17个 markdown 文件，涵盖索引、引用、数据集和表——证明了这种克制可以扩展到真实的东西，而不仅仅是玩具示例。

3、从规范到代码库：OKF 概念在代码中的样子

Google 的参考用例是 BigQuery 表。对软件团队来说重要的转折是认识到相同的形状可以直接映射到服务、模块和 API——你只是将 resource 从控制台 URL 交换到仓库路径，将 # Schema 交换为 # Responsibilities 和 # Dependencies：

---
type: Service
title: billing-service
description: Handles subscription billing, invoicing, and payment webhooks.
resource: https://github.com/acme/monorepo/tree/main/services/billing
tags: [billing, payments, python]
timestamp: 2026-06-30T09:12:00Z
---
# Responsibilities
Owns the `Invoice` and `PaymentEvent` domain models. Consumes Stripe webhooks via
[stripe-webhook-handler](/services/billing/stripe-webhook-handler.md).

# Dependencies
- Calls [customer-service](/services/customer-service.md) to resolve account state.
- Publishes events consumed by [notifications-service](/services/notifications-service.md).

# Citations
[1] [Billing runbook](https://wiki.internal/billing-runbook)

交叉链接不是装饰。捆绑包相对的 Markdown 链接（/services/customer-service.md）将扁平目录变成依赖图，比文件系统的父/子层次结构更丰富——billing-service 现在正式指向它调用的所有内容以及它发出的所有内容，与这些服务在仓库树中的物理位置无关。

根 index.md 是编码代理在接触任何文件之前读取的入口点：

# Billing Domain

* [billing-service](services/billing-service.md) - subscription billing, invoicing, webhooks
* [customer-service](services/customer-service.md) - account and subscription state
* [Runbooks](runbooks/) - on-call playbooks for billing incidents

单个文件取代了全仓库重新扫描或重新嵌入。编码代理可以在接触仓库之前读取 OKF 捆绑包，数据助手可以在生成 SQL 之前查阅 OKF 文档。捆绑包充当预检上下文加载，而不是你查询的搜索索引。

4、没有人填补的空白：构建富化代理

这是本文的核心主张：采用 OKF 是微不足道的——一个必需字段、一个文件夹约定、纯 Markdown 链接。真正的工程工作是完全不同的事情：

"真正的工程工作……不是采用 OKF，而是构建富化代理管道，使代码库的 OKF 图谱随着代码变化保持准确和最新。"

OKF 对如何生成捆绑包或保持真实性没有意见——这完全由采用者决定。

Google 自己的 BigQuery 参考实现是模板。它是一个两遍代理：第一遍遍历数据集中的每个表/视图，并根据其架构为每个资产起草一个 OKF 概念文档；第二遍通过交叉引用现有文档添加引用。直接翻译到代码：第一遍遍历仓库中的每个模块/服务/API，并根据其接口和调用图起草一个概念文件；第二遍添加回操作手册、ADR 和 PR 的引用。

你不必从零开始构建这个。独立的 okf CLI（Go, Apache-2.0, superops-team）已经证明了这种形状是有效的——包括"自动保持最新"的部分：

# 扫描当前仓库并构建 .okf/knowledge 捆绑包
okf init

# 安装 git hook，以便捆绑包在每次提交时自动更新
okf hook install

# 按关键字查询概念
okf search -q "database"

# 强制执行 13 个内置规范合规规则
okf lint

hook install 步骤就是全部要点：在每次提交时，该工具重新扫描仓库并刷新受影响的概念文件，因此图谱永远不会在某些东西强制其同步之前偏离代码太远。综合起来，你实际构建的管道如下所示：

提交推送
     |
     v
差异范围模块扫描（哪些服务/文件发生了变化？）
     |
     v
起草/更新概念文档（两遍富化代理，按照 Google 的 BigQuery 模式）
     |
     v
重新链接交叉引用（更新 Dependencies/Responsibilities 链接）
     |
     v
检查（okf lint — 13 个规范合规规则）
     |
     v
发布（提交捆绑包 / 推送到 CI / 注册到目录）

将扫描范围限制为 git diff（而不是整个仓库）是使其足够便宜以在每次提交上运行而不是每晚运行的关键。

5、将其接入多代理工作流

除非代理实际消费捆绑包，否则这些都不重要，这就是渐进式披露不再只是规范细节而成为预算杠杆的地方。协调器代理首先读取 index.md，根据子任务决定哪些子代理需要哪些概念文件，并相应地路由——没有人会为接触一个服务的任务加载整个捆绑包。

可编程的连接点很简单。基于 Go 的 CLI 工具暴露了你可以连接到编译层的加载/搜索原语：

bundle, err := okf.LoadBundle(".okf/knowledge", nil)
if err != nil {
    log.Fatal(err)
}
results := bundle.Search("database")
result := lint.LintBundle(concepts, lint.DefaultConfig())

bundle.Search 是你的协调器在调度子代理之前调用的钩子；lint.LintBundle 是你的 CI 在信任捆绑包足以让代理在其上操作之前调用的钩子。

对于希望捆绑包在其自身工具之外可消费的团队，第三方 Kiso 引擎将 OKF 捆绑包编译成静态站点——为人类提供 HTML，为爬虫式代理提供自动生成的 llms.txt 和 sitemap.xml——设计为在每次合并时在 CI 中运行，因此发布的捆绑包永远不会落后于真实来源。

一个工作流级别的决策比任何工具选择都重要：OKF 在哪里停止，RAG 在哪里开始。OKF 用于代码库知识中稳定的、精选的部分——服务、所有权边界、依赖图、你费心编写的操作手册。RAG 仍然是你处理长尾内容的方式：非结构化的票证、Slack 线程和一次性设计文档。将 OKF 视为 RAG 的替代品是错误的框架；将其视为 RAG 不需要重新推导的编译缓存是正确的框架。在这个框架下，早期分析师评论声称，对于专注的、稳定的知识域，与天真的文档加载相比，令牌消耗减少了大约95%。虽然这个数字是轶事性的，需要在大规模生产中验证，但它突出了预编译代理上下文的潜在节省。

6、哪里会出问题：诚实的局限性

如果你跳过故障模式，上述所有内容都不起作用，所以这里不加掩饰地列出：

• 没有内置搜索或检索：OKF 是一种文件格式，而不是平台。你拥有索引器、搜索层和服务层；okf search 和 Kiso 是填补这一空白的早期、非官方尝试，而不是成熟的基础设施。
• 没有类型注册表和模式强制执行：唯一必需的字段 type 由生产者定义，未针对任何规范列表进行验证。多个团队对同一个捆绑包做出贡献将会发生偏差——这里的"API Endpoint"，那里的"Endpoint"，其他地方的"Route"——没有外部治理和 lint 来坚守阵地。
• 无类型、未强制的链接：交叉引用只是一个带有隐含关系语义的 Markdown 链接，消费者必须容忍断开的链接（按规范）。这限制了代理可以安全自动化的形式图推理（依赖遍历、影响分析）与实际的 RDF/OWL 知识图谱相比。
• Markdown 不会修复知识质量：如果你的源文档和注释过时或相互矛盾，OKF 会在更好的文件夹结构中忠实地保留这一点。它本身没有机制来检测或解决冲突的概念——这仍然是你的富化代理的工作，或者是没有人做。
• 生态系统极早期：规范 v0.1 于2026年6月发布，Google 之外的工具分散且未获认可，并且没有大型、活跃变化代码库的长期生产案例研究来验证随时间变化的维护开销。正如作者自己指出的："OKF v0.1 是一个起点，而不是一个完成的标准。"

7、你应该构建这个吗？决策框架

考虑到这些局限性，以下是 ROI 计算，而不是"取决于"的手势。

如果你已经在对自己的仓库或知识库运行多个代理，就构建它。在那个世界里，富化代理管道直接收回成本：每个任务花费更少的令牌重新推导上下文，以及更少的过时上下文错误（代理基于代码库的过时心智模型操作）。

如果你还没有针对代码运行代理工作流，就跳过它——暂时。OKF 的整个价值主张是代理消费；如果没有代理消费它，你就是在维护一个没人阅读的 wiki。

如果你决定构建，最小可行管道可以在一个下午内完成：okf init 加上一个 git hook，对你变化最多的服务（不是整个仓库）进行一次富化遍历，以及 index.md 作为每个代理首先读取的单个入口点。成本方面，格式本身几乎可以免费原型化——一个必需字段、六个推荐字段、没有 SDK、没有锁定、没有需要建立的模式注册表。持续成本是富化代理自身的计算以及你围绕它构建的漂移监控，而不是规范。正如 FAQ 所说："如果你能 cat 一个文件，你就能读取 OKF；如果你能 git clone 一个仓库，你就能发布它。"

8、结束语

停止将 OKF 作为格式决策进行评估，开始将其作为管道决策进行原型化。本周将一个 git hook 和一个两遍富化代理指向你最活跃的服务，测量你下一个多代理任务上的令牌增量，并从数据（而不是规范的极简主义）来决定维护成本是否值得你的仓库。

原文链接：Stop Wasting LLM Tokens: Building a Self-Updating Codebase Knowledge Graph with OKF

汇智网翻译整理，转载请标明出处