内容
# OKF-go — 开放知识格式工具
**开放知识格式（OKF）** 是一种与供应商无关的、轻量级的规范，用于将组织知识（文档、运行手册、指标、数据库模式和 API 定义）结构化为机器可读、人类友好的 Markdown 文件。
通过将知识表示为带有结构化 YAML 前置信息的 Markdown 文件目录，OKF 弥合了结构化元数据仓库和非结构化文本文档之间的差距，作为 **AI 代理**、**检索增强生成（RAG）** 管道和 **模型上下文协议（MCP）** 的理想基底。
## 📄 知识格式规范
**开放知识格式（OKF）** 是由 Google Cloud 开发的开放的、与供应商无关的规范，用于将结构化元数据表示为带有 YAML 前置信息的普通 Markdown 文件。有关完整的格式规范、约定、模式详细信息和参考示例，请参阅官方 [Google Cloud OKF 规范](https://github.com/GoogleCloudPlatform/knowledge-catalog)。
**OKF-go** 提供了一套高性能的实用程序，用于验证捆绑包、从数据库和 API 收集元数据、为大型语言模型组装上下文以及运行 MCP 服务器。
## 🚀 主要功能
* **一致性引擎和校验工具（`okf lint`）：** 验证知识捆绑包的 YAML 前置信息正确性、必填属性和损坏的内部/外部 Markdown 链接。
* **元数据收集器（`okf harvest`）：** 自动从数据库（PostgreSQL、MySQL、Cloud Spanner、BigQuery）、OpenAPI 规范、Protobuf 文件、Git 仓库和网页中提取和转换模式为 OKF 概念文档。
* **上下文组装器（`okf assemble`）：** 从核心概念开始执行基于图的广度优先搜索（BFS），在指定的字符/标记预算内解析相关概念，以构建精简的高质量提示上下文。
* **模型上下文协议服务器（`okf mcp`）：** 通过 Stdio 或 SSE 传输将您的知识库直接暴露给与 MCP 兼容的 AI 客户端（例如 Claude Desktop、Cursor、Antigravity）。
* **捆绑包操作（`okf diff` / `okf merge`）：** 比较两个 OKF 捆绑包的结构和内容差异，或合并它们以统一分布式知识库。
* **AI curator（`--ai-enrich` 标志）：** 在元数据收集过程中使用 AI 驱动的概念管理，自动生成业务描述并使用 Gemini 模型对概念进行分类。
* **JSON-LD 导出（`okf export`）：** 将您的 OKF 图导出为 JSON-LD 格式，以用于语义网。
* **交互式 HTML 门户编译器（`okf doc`）：** 将 OKF 捆绑包编译为具有搜索、标签和链接关系图的交互式静态 Web 应用程序。
* **语言服务器协议守护进程（`okf lsp`）& VS Code 扩展：** 在 IDE 中运行 LSP 服务器，以实时发布诊断错误/警告。还提供专用的 VS Code 扩展。
* **双向同步守护进程（`okf sync`）：** 自动将本地概念与 Notion、Confluence、Jira 和 Google Drive 中的远程文档节点同步。
* **极快的性能：** 高度优化的 Go 架构，解析约 97k 概念/秒，完成 200 个节点的图 BFS 遍历 < 40µs，并验证 100 概念捆绑包约 125µs。
## 📦 安装和分发
本节详细介绍如何安装和运行预建的 `okf` CLI 二进制文件，开发人员如何自动化发布，以及如何构建和捆绑 OKF 仓库。
### 1. 安装预建的 CLI
您可以使用以下选项在不从源代码构建的情况下安装 `okf` CLI：
#### 选项 A：单行 Shell 安装程序（macOS 和 Linux）
运行自动化安装脚本，下载、验证并安装适合您的 OS 和 CPU 架构的正确二进制文件：
```bash
curl -sSfL https://okfgo.dev/install.sh | sh
```
* 默认情况下，这会安装到 `/usr/local/bin`（如果可写）、`~/.local/bin` 或 `./bin`（后备）。
#### 选项 B：GitHub 发布（手动下载）
前往 GitHub 发布页面，下载适合您操作系统的存档：
* **macOS（Apple Silicon / M 系列）：** `okf_<version>_darwin_arm64.tar.gz`
* **macOS（Intel）：** `okf_<version>_darwin_amd64.tar.gz`
* **Linux（64 位 AMD64）：** `okf_<version>_linux_amd64.tar.gz`
* **Linux（ARM64 / Graviton）：** `okf_<version>_linux_arm64.tar.gz`
* **Windows（64 位）：** `okf_<version>_windows_amd64.zip`
提取二进制文件并将其添加到系统的 `PATH` 中。
#### 选项 C：Go 安装（从源代码构建）
如果您已安装 Go，您可以直接从 GitHub 仓库编译并安装 CLI：
```bash
go install github.com/abcubed3/okf@latest
```
确保您的 `GOBIN` 目录（通常为 `$HOME/go/bin` 或 `$GOPATH/bin`）位于系统的 `PATH` 中。
## 💻 CLI 命令和详细文档
### 1. 校验工具和验证器（`lint`）
确保知识捆绑包符合规范。它验证 YAML 语法，确保设置了必填字段，并检查内部 Markdown 链接是否损坏。
```bash
# 校验当前目录中的捆绑包
./okf lint
# 校验特定目录中的捆绑包
./okf lint /path/to/my-bundle
```
* **硬性规则（失败并报错）：**
* 语法有效的 YAML 前置信息。
* 前置信息中存在 `type` 字段。
* **软性规则（发出警告）：**
* 推荐字段（`title`、`description`）存在。
* 解析和验证所有相对 Markdown 链接（例如 `[Users](users.md)`），以保证图完全连接且无孤立链接。
### 2. 模式收集器（`harvest`）
从数据库、API 规范、protobuf 文件、git 仓库和网页中提取元数据，自动生成结构化的 OKF 概念。
#### A. 数据库模式收集（`harvest db`）
支持 **PostgreSQL**、**MySQL**、**Cloud Spanner** 和 **BigQuery**。连接到数据库，查询信息模式，并生成表、列、约束和关系作为 OKF 概念。
```bash
# PostgreSQL 示例
./okf harvest db \
--driver postgres \
--conn "postgresql://postgres:password@localhost:5432/my_db?sslmode=disable" \
--schema public \
--output ./my-bundle/tables
# MySQL 示例
./okf harvest db \
--driver mysql \
--conn "user:password@tcp(localhost:3306)/my_db" \
--output ./my-bundle/tables
# Cloud Spanner 示例
./okf harvest db \
--driver spanner \
--conn "projects/my-project/instances/my-instance/databases/my-db" \
--output ./my-bundle/tables
# BigQuery 示例
./okf harvest db \
--driver bigquery \
--conn "projects/my-project" \
--dataset "my_dataset" \
--output ./my-bundle/tables
```
#### B. OpenAPI 规范收集（`harvest openapi`）
解析 OpenAPI 规范文档（JSON/YAML）并生成表示 API 端点的 OKF 概念。
```bash
# 收集 OpenAPI 规范并输出到捆绑包
okf harvest openapi
--spec ../openapi-sample.yaml
--output harvested-endpoints
```
#### C. Protobuf 模式收集（`harvest proto`）
从 `.proto` 模式中提取消息、RPC 服务和字段定义。
```bash
okf harvest proto \
--path ./protos/user_service.proto \
--output ./my-bundle/protobufs
```
#### D. Git 仓库收集（`harvest git`）
从 Git 仓库中提取元数据，将提交、文件结构和架构文档转换为 OKF 概念。
```bash
./okf harvest git \
--repo https://github.com/abcubed3/okf.git \
--output ./my-bundle/git
```
#### E. 网页收集（`harvest web`）
爬取目标 URL 以抓取文档，并将其结构化为 OKF 概念。可选地由 **AI 管理员**（`--ai-enrich` 标志）提供支持，以自动生成业务描述并使用 Gemini 模型丰富概念。
```bash
./okf harvest web \
--url https://example.com/docs \
--output ./my-bundle/web \
--ai-enrich
```
## 🤝 贡献
欢迎贡献！请阅读我们的 [贡献指南](CONTRIBUTING.md)，了解如何设置开发环境、运行校验工具、执行单元测试和提交拉取请求。
## 👥 作者
* **abcubed3** — *创建者 & 维护者* — [GitHub 个人资料](https://github.com/abcubed3)
## 📄 许可证
该项目根据 Apache License 2.0 许可。有关完整文本，请参阅 [LICENSE](LICENSE) 文件。
