v0.2.0 刚刚发布：信任等级、来源追溯、经认证计算 →

可由 AI Agent 驱动、用于管理知识图谱的 CLI

okf 是面向 Open Knowledge Format 的 Go CLI 工具包：智能体优先、JSON 原生、供应商中立。它是 Google 基于 Python 且绑定 Gemini 的参考实现的单二进制替代方案。

text $ okf schema validate { "name": "validate", "short": "Validate a bundle against the OKF spec", "stdout": "json", "exit_codes": [0, 1, 2, 4] }

$ okf validate ./my-bundle { "bundle": "./my-bundle", "command": "validate", "valid": true, "errors": 0, "warnings": 0, "findings": [] }

v0.2 新增内容

信任现已成为一等字段

okf v0.2.0 完整实现了新的 OKF v0.2 规范：来源追溯、信任、生命周期和经认证计算，均可被解析、验证，并以 Agent 可据此分支处理的 JSON 形式呈现。该版本已针对 Google knowledge-catalog 仓库中的每一个参考 bundle 完成验证，零错误通过。

信任等级

每个概念现在都会根据其 verified 事件获得派生等级：unverified、machine-confirmed 或 human-reviewed。okf list 和 okf show 会展示该等级，使 Agent 能够在采取行动前决定应信任哪些内容。

来源追溯

概念会携带 sources，其中包括每个来源的可信度信号：作者、使用次数和最后修改时间。正文脚注会关联至来源 ID，从而实现逐项主张的归因；okf validate 会双向检查这一关联关系。

生命周期

status（draft、stable、deprecated）和 stale_after 将内容新鲜度变为简单的日期比较。概念过期当天，验证就会将其标记为陈旧；没有内容会在无声无息中腐化。

经认证计算

一种新的概念类型可携带获认可的计算：包括 runtime、带类型的 parameters、executor 和确定性的 attester。okf 会验证完整契约，包括确保每个契约路径确实存在于 bundle 中。

text $ okf list ./bundles/finance { "concepts": [ {"id":"computations/revenue", "type":"Attested Computation", "status":"stable", "trust_tier":"human-reviewed"}, {"id":"metrics/margin-legacy", "type":"Metric", "status":"deprecated", "trust_tier":"machine-confirmed"} ] }

$ okf validate ./old-bundle { "valid": true, "warnings": 1, "findings": [{"severity":"WARN", "message":"frontmatter: legacy 'timestamp' is superseded by 'generated.at' in OKF v0.2 (§13.1)"}] }

okf 为何存在

适用于任意 AI Agent、任意提供商的供应商中立 OKF 工具

Google 的参考 OKF 实现采用 Python + Gemini + BigQuery，供应商锁定在 Google 云上。okf 是供应商中立的替代方案：一个可在任何地方运行、原生使用 JSON、设计为可由任何 AI Agent 驱动而非仅限 Gemini 的 Go 单一二进制文件。

问题

唯一的参考 OKF 工具要求 Python、Gemini API 密钥和 BigQuery。未运行在 Google 技术栈上的 Agent 无法参与。格式是开放的，但工具并不开放。

旧有变通方案

解析 --help 文本、猜测参数、抓取 stdout 输出。错误信息是无法可靠进行分支判断的英文句子。每个 Agent 集成都是定制化的提示词工程。

OKF 的方式

只需加载一次 okf schema：它提供包含每条命令、参数、输出格式和退出码的 JSON 清单。根据该规范驱动 CLI，并根据 .error.kind 进行分支处理。JSON 是默认方式，而不是需要额外开启的标志。

结果

Agent 可以发现、驱动并从 okf 错误中恢复，无需任何提示词工程。schema 就是提示词。错误封装就是分支逻辑。退出码就是重试策略。一个二进制文件，零依赖。

内部包含什么

11 条命令、一个二进制文件、零运行时依赖

采用测试优先方式构建（88 项测试），仅使用 Go 标准库，采用 Apache 2.0 许可证。每条命令默认都会向 stdout 输出结构化 JSON。没有 --json 标志，也无需抓取屏幕输出。

Schema 与发现

📐

okf schema

输出每条命令的完整 JSON 清单：名称、描述、标志、参数、stdout 格式和退出码。一次调用，Agent 就能了解完整的 CLI 接口。这就是护城河。

🔢

okf version

以 JSON 形式输出版本信息。Agent 可在驱动其余 CLI 功能前检查兼容性。

创建与结构

🚀

okf init

使用标准子目录（tables、datasets、playbooks）、根 index.md 及 .gitignore 搭建新的空 OKF bundle。它是 AI 驱动文档流水线的起点。

📇

okf index

为每个目录生成 index.md 文件，以实现 OKF 规范 §8 所定义的渐进式披露，同时保留 bundle 的 okf_version 声明。Agent 可逐层导航，而不是加载整个 bundle。

验证与质量

✅

okf validate

检查每个概念是否符合 OKF v0.2：必需的 frontmatter、交叉链接、来源追溯/信任/生命周期字段族、经认证计算契约，以及旧版 v0.1 构造。如发现任何错误则以退出码 1 退出。这是 CI 质量门禁。

🧹

okf lint

执行与 validate 相同的检查，但只输出警告。错误会被抑制，因此即使存在警告也会以退出码 0 退出。可用于标记缺失的推荐字段，而不导致构建失败。

探索与查询

📋

okf list

以 JSON 列出每个概念文档的 ID、类型、标题、生命周期状态和信任等级。这是库存查询：这个 bundle 中有什么，以及我应在多大程度上信任它？

🔍

okf search

按 --tag、--type 或 --text 过滤概念。可以查找陈旧概念、按类别筛选，或定位所有带有 auth 标签的内容，全部以结构化 JSON 输出。

📄

okf show

以 JSON 返回单个概念的完整内容：frontmatter、Markdown 正文、信任等级、陈旧状态、来源追溯信息，以及在存在时返回经认证计算契约。这是深度阅读命令。

图谱与关系

🕸️

okf graph

根据 Markdown 链接以及 v0.2 派生边（sources、computations、executors、attesters）构建有向交叉链接图，并输出节点、边、密度和汇总统计数据。可用于发现孤立概念并验证结构。

🔗

okf backlinks

列出链接到指定概念的每个概念，即反向链接查询。无需 grep 整个 bundle，即可回答“谁依赖于此？”

智能体优先原则

四项原语，零歧义

“智能体优先”意味着外部 AI 能通过 okf schema 发现并驱动 CLI，而不是指 CLI 在内部调用 LLM。Agent 所需的一切都内置于二进制文件本身。

text $ okf schema { "name": "okf", "description": "Go CLI toolkit for the Open Knowledge Format (OKF)", "commands": [ {"name":"schema", "stdout":"json", "exit_codes":[0,4]}, {"name":"validate", "stdout":"json", "exit_codes":[0,1,2,4]}, {"name":"graph", "stdout":"json", "exit_codes":[0,2,4]} ] }

$ okf graph ./my-bundle { "command": "graph", "node_count": 3, "edge_count": 3, "density_pct": 50, "isolated": 0, "nodes": [{"id":"tables/events_","type":"BigQuery Table"}], "edges": [{"from":"datasets/ga4","to":"tables/events_"}] }

$ okf validate ./broken-bundle { "error": { "kind": "validation", "code": 400, "reason": "validationError", "message": "broken link: [Users] -> users.md (concept tables/users not found)" } }

代码	类型	Agent 策略
0	success	解析 stdout JSON，继续执行
1	validation	解析 findings，修复 bundle，然后重新运行
2	io	检查文件系统 / 路径，并呈现给调用方
3	internal	升级给用户处理，属于意外错误
4	usage	根据 schema 修正标志/参数，然后重试

开始使用

30 秒内安装

v0.2.0 已发布，使用 cosign 签名，并包含 SBOM。一个二进制文件，没有运行时依赖。

Homebrew（macOS / Linux）

brew install okfcli/okf/okf

Go install

go install github.com/okfcli/okf/cmd/okf@latest

从源码构建

git clone https://github.com/okfcli/okf.git cd okf && make build ./okf --help

然后创建一个 bundle、添加概念并验证：

text $ okf init ./my-bundle {"command":"init","bundle":"./my-bundle","created":true}

$ okf validate ./my-bundle {"bundle":"./my-bundle","command":"validate","valid":true,"errors":0,"warnings":0,"findings":[]}

$ okf index ./my-bundle $ okf graph ./my-bundle $ okf search ./my-bundle --type Table --tag revenue

为你的 Agent 配备一套真正可驱动的 CLI

可通过 Schema 发现。JSON 原生。供应商中立。一个 Go 二进制文件。

New v0.2.0 just shipped: trust tiers, provenance, attested computations →

The CLI your AI agent drives to manage your knowledge graph

okf is a Go CLI toolkit for the Open Knowledge Format: agentic-first, JSON-native, vendor-neutral. A single binary alternative to Google's Python/Gemini-locked reference implementation.

$ okf schema validate { "name": "validate", "short": "Validate a bundle against the OKF spec", "stdout": "json", "exit_codes": [0, 1, 2, 4] } $ okf validate ./my-bundle { "bundle": "./my-bundle", "command": "validate", "valid": true, "errors": 0, "warnings": 0, "findings": [] }

New in v0.2

Trust is now a first-class field

okf v0.2.0 implements the new OKF v0.2 spec end to end: provenance, trust, lifecycle, and attested computations, all parsed, validated, and surfaced as JSON your agent can branch on. Verified against every reference bundle in Google's knowledge-catalog repository with zero errors.

TRUST TIERS

Every concept now gets a derived tier from its verified events: unverified, machine-confirmed, or human-reviewed. okf list and okf show expose it, so an agent can decide what to trust before it acts.

PROVENANCE

Concepts carry sources with per-source credibility signals: author, usage count, last modified. Body footnotes join into source ids for per-claim attribution, and okf validate checks the join both ways.

LIFECYCLE

status (draft, stable, deprecated) and stale_after make freshness a plain date comparison. Validation flags a stale concept the day it expires; nothing silently rots.

ATTESTED COMPUTATIONS

A new concept type carries a sanctioned computation: runtime, typed parameters, an executor, and a deterministic attester. okf validates the full contract, including that every contract path actually exists in the bundle.

$ okf list ./bundles/finance { "concepts": [ {"id":"computations/revenue", "type":"Attested Computation", "status":"stable", "trust_tier":"human-reviewed"}, {"id":"metrics/margin-legacy", "type":"Metric", "status":"deprecated", "trust_tier":"machine-confirmed"} ] } $ okf validate ./old-bundle { "valid": true, "warnings": 1, "findings": [{"severity":"WARN", "message":"frontmatter: legacy 'timestamp' is superseded by 'generated.at' in OKF v0.2 (§13.1)"}] }

Why okf exists

Vendor-neutral OKF tooling for any AI agent on any provider

Google's reference OKF implementation is Python + Gemini + BigQuery, vendor-locked to Google's cloud. okf is the vendor-neutral alternative: a single Go binary that works anywhere, speaks JSON natively, and is designed to be driven by any AI agent, not just Gemini.

THE PROBLEM

The only reference OKF tooling requires Python, a Gemini API key, and BigQuery. Agents that don't run on Google's stack can't participate. The format is open, but the tooling isn't.

THE OLD WORKAROUND

Parse --help text, guess at flags, screen-scrape stdout. Errors are English sentences you can't reliably branch on. Every agent integration is bespoke prompt engineering.

THE OKF WAY

Load okf schema once: a JSON manifest of every command, its args, output format, and exit codes. Drive the CLI from that spec. Branch on .error.kind. JSON is the default, not an opt-in flag.

THE RESULT

An agent that can discover, drive, and recover from okf without any prompt engineering. The schema IS the prompt. The error envelope IS the branching logic. The exit code IS the retry strategy. One binary, zero dependencies.

What's inside

11 commands, one binary, zero runtime dependencies

Built test-first (88 tests), Go stdlib-only, Apache 2.0. Every command outputs structured JSON on stdout by default. No --json flag, no screen-scraping.

Schema & Discovery

📐

okf schema

Emits a complete JSON manifest of every command: name, description, flags, args, stdout format, exit codes. One call and an agent knows the full CLI surface. This is the moat.

🔢

okf version

Prints version info as JSON. Agents can check compatibility before driving the rest of the CLI.

Create & Structure

🚀

okf init

Scaffolds a new empty OKF bundle with standard subdirectories (tables, datasets, playbooks), a root index.md, and a .gitignore. The starting point for an AI-driven documentation pipeline.

📇

okf index

Generates index.md files into every directory for progressive disclosure per OKF spec §8, preserving the bundle's okf_version declaration. Agents navigate level by level instead of loading the entire bundle.

Validate & Quality

✅

okf validate

Checks every concept against OKF v0.2: required frontmatter, cross-links, the provenance, trust, and lifecycle families, attested-computation contracts, and legacy v0.1 constructs. Exits 1 if any errors are found. The CI quality gate.

🧹

okf lint

Same checks as validate but only emits warnings. Errors are suppressed, so it exits 0 even with warnings. Use it to flag missing recommended fields without failing a build.

Explore & Query

📋

okf list

Lists every concept document with its ID, type, title, lifecycle status, and trust tier as JSON. The inventory query: what's in this bundle, and how much should I trust it?

🔍

okf search

Filters concepts by --tag, --type, or --text. Find stale concepts, filter by category, or locate everything tagged auth, all as structured JSON.

📄

okf show

Returns a single concept's full content: frontmatter, markdown body, trust tier, staleness, provenance sources, and the attested-computation contract when present, all as JSON. The deep-read command.

Graph & Relationships

🕸️

okf graph

Builds the directed cross-link graph from markdown links plus v0.2 derivation edges (sources, computations, executors, attesters) and prints nodes, edges, density, and summary statistics. Find orphan concepts and verify structure.

🔗

okf backlinks

Lists every concept that links to a given concept: reverse-link lookup. Answer "who depends on this?" without grepping the entire bundle.

The agentic-first principle

Four primitives. Zero ambiguity.

"Agentic first" means an external AI can discover and drive the CLI via okf schema, not that the CLI calls an LLM internally. Everything an agent needs is built into the binary itself.

$ okf schema { "name": "okf", "description": "Go CLI toolkit for the Open Knowledge Format (OKF)", "commands": [ {"name":"schema", "stdout":"json", "exit_codes":[0,4]}, {"name":"validate", "stdout":"json", "exit_codes":[0,1,2,4]}, {"name":"graph", "stdout":"json", "exit_codes":[0,2,4]} ] } $ okf graph ./my-bundle { "command": "graph", "node_count": 3, "edge_count": 3, "density_pct": 50, "isolated": 0, "nodes": [{"id":"tables/events_","type":"BigQuery Table"}], "edges": [{"from":"datasets/ga4","to":"tables/events_"}] } $ okf validate ./broken-bundle { "error": { "kind": "validation", "code": 400, "reason": "validationError", "message": "broken link: [Users] -> users.md (concept tables/users not found)" } }

Code	Kind	Agent Strategy
0	success	Parse stdout JSON, continue
1	validation	Parse findings, fix the bundle, re-run
2	io	Check filesystem / paths, surface to caller
3	internal	Escalate to user, unexpected error
4	usage	Fix flags/args from schema, retry

Get started

Install in 30 seconds

v0.2.0 released, cosign-signed, SBOM-included. One binary, no runtime dependencies.

Homebrew (macOS / Linux)

brew install okfcli/okf/okf

Go install

go install github.com/okfcli/okf/cmd/okf@latest

Build from source

git clone https://github.com/okfcli/okf.git cd okf && make build ./okf --help

Then scaffold a bundle, add concepts, and validate:

$ okf init ./my-bundle {"command":"init","bundle":"./my-bundle","created":true} $ okf validate ./my-bundle {"bundle":"./my-bundle","command":"validate","valid":true,"errors":0,"warnings":0,"findings":[]} $ okf index ./my-bundle $ okf graph ./my-bundle $ okf search ./my-bundle --type Table --tag revenue

Give your agent a CLI it can actually drive

Schema-discoverable. JSON-native. Vendor-neutral. One Go binary.