内容
<div align="center">
# 📚 okf — 开放知识格式工具包，适用于 Claude Code
**教会你的编码代理编写、维护、验证和 *可视化* 便携式知识包 — 使用 Markdown 让你的团队和代理都能阅读。**
[](LICENSE)
[](skills/okf/reference/SPEC.md)
[](https://code.claude.com/docs/en/plugins)
[](https://skills.sh/scaccogatto/okf-skills)
[](#contributing)
### ▶ [**打开实时演示**](https://scaccogatto.github.io/okf-skills/) — 一个真正的 OKF 包作为交互式图
[](https://scaccogatto.github.io/okf-skills/)
*点击任意节点 → 渲染的 Markdown、类型化的元数据和“链接到 / 引用”回链。无需后端，页面内无数据交换。*
</div>
---
> [**OKF**](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
> 是开放的、厂商中立的格式（由 Google Cloud 于 2026 年 6 月宣布），它将知识 — 系统周围的上下文和精选的洞察 — 表示为
> Markdown 文件目录，带有 YAML 前言。无需模式注册。无需运行时。无需 SDK。如果你可以 `cat` 一个文件，你就可以读取它；如果你可以 `git clone`
> 一个仓库，你就可以分发它。
这是 **Claude Code 原生** 的 OKF 工具链。它教会 Claude **生成**、
**维护**、**消费**、**验证** 和 **可视化** OKF 包，作为其正常工作的一部分 —
由逐字规范驱动，支持确定性一致性检查器，带有自包含的图形渲染器。作为
**Claude Code 插件** 和 **代理技能** （Cursor、Codex 和 20+ 代理）分发。
## 为什么是知识即代码（以及 OKF 的位置）
项目知识分散在 wiki、代码注释和人员脑海中；代理每次会话都从头开始重新发现。OKF 为其提供一个持久的、
可差异化、可移植的家园 — 与其描述的代码版本控制在一起。它是
**互补** 的，而不是替代现有的上下文栈：
| | **OKF 包** （此） | `CLAUDE.md` | Claude 自动记忆 | Wiki / Notion |
|---|:---:|:---:|:---:|:---:|
| 目的 | 精选的 **知识** | 持续的 **指令** | 隐含的笔记 | 人类文档 |
| 跨代理/工具的可移植性 | ✅ 普通 Markdown + YAML | ⚠️ Claude 特定 | ❌ 每代理存储 | ⚠️ 需要导出 |
| 与代码一起版本控制在 git 中 | ✅ | ✅ | ❌ | ❌ |
| 类型化和可查询 | ✅ 前言 | ❌ 正文 | ❌ | ⚠️ |
| 链接概念图 | ✅ | ❌ | ❌ | ⚠️ |
| 在 PR 中精选和审查 | ✅ | ✅ | ❌ 隐含 | ⚠️ |
| 超出上下文窗口的扩展 | ✅ 进步披露 | ❌ 整体加载 | ⚠️ | n/a |
将 `CLAUDE.md` 用于 *行为方式*，自动记忆用于 *代理拾取的内容*，
而 OKF 包用于 *团队所知* — 共享、结构化和可分发的。
> 🪞 **此仓库通过 OKF 文档自身。** 架构、技能和决策
> 背后 okf-skills 位于 [`.okf/`](.okf/) — 在 [**实时自图**](https://scaccogatto.github.io/okf-skills/self.html) 中探索它们。CI
> 在每次推送时验证该包（使用一致性检查器进行自测试）。
## 内部结构
| 组件 | 功能 |
|-----------|--------------|
| `/okf:okf` 技能 | 生成/维护/消费包，应用规范和模板。在检测到 OKF 包的仓库中自动触发。 |
| `/okf:validate` 技能 | 确定性 §9 一致性检查（不是人工检查）。 |
| `/okf:visualize` 技能 | 将包渲染为自包含的交互式 HTML 图（`viz.html`）。 |
| `skills/validate/scripts/okf_validate.py` | 独立的、零配置的验证器（`uv run`，PyYAML 通过 PEP 723）。 |
| `skills/visualize/scripts/okf_visualize.py` | 独立的包 → `viz.html` 渲染器（Cytoscape + marked 通过 CDN）。 |
| `skills/okf/reference/SPEC.md` | OKF v0.1 规范，直接从来源引用 — 真相来源。 |
| `templates/CLAUDE-okf.md` | 启用项目中自动消费/维护的片段。 |
| `examples/sample-bundle/` | [实时演示](https://scaccogatto.github.io/okf-skills/) 背后的合规包 — 代码、数据、决策、运行手册、指标。 |
## 安装
**作为 Claude Code 插件** （一个插件市场）：
```shell
/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto
```
**作为 skills.sh 代理技能** （Claude Code、Cursor、Codex 和 20+ 代理）：
```shell
npx skills add scaccogatto/okf-skills # 安装 okf、validate 和 visualize 技能
```
**本地开发** （无市场）：
```shell
claude --plugin-dir /path/to/okf-skills
```
这两个布局共存于单个仓库中：`.claude-plugin/` 使其成为插件市场；而 `skills/<name>/SKILL.md` 使其可被 skills.sh 发现。脚本
位于其技能内部，并通过 `${CLAUDE_SKILL_DIR}` 引用，因此在任一安装路径下都能正常工作。
需要 [`uv`](https://docs.astral.sh/uv/) 用于脚本（或 `python3` + `pyyaml`）。
## 使用
**捕获知识** — 要求 Claude “用 OKF 记录身份验证服务”，或运行：
```shell
/okf:okf produce .okf
```
**验证** 提交前：
```shell
/okf:validate .okf --strict
# 或直接：
uv run skills/validate/scripts/okf_validate.py .okf --strict
```
**可视化** 知识图 — 一个自包含的 `viz.html`，可在任何
浏览器中打开（[实时示例](https://scaccogatto.github.io/okf-skills/)）：
```shell
/okf:visualize .okf
# 或直接，带标题和回链到您的仓库：
uv run skills/visualize/scripts/okf_visualize.py .okf \
-o viz.html --title "我的项目" --link "https://github.com/me/project"
```
每个概念都有一个可分享的深层链接 — 打开 `viz.html#services/auth-api`，图会加载并选中该概念。
**启用自动维护（软模式）。** 此插件设计上 **不带钩子**。要让 Claude 在任务前咨询 `.okf/` 并在更改后写入知识，
请将 [`templates/CLAUDE-okf.md`](templates/CLAUDE-okf.md) 粘贴到您的项目的
`CLAUDE.md`（或 `~/.claude/CLAUDE.md` 以适用于所有项目）中。
## 一个包的样子
```
.okf/
├── index.md # 进步披露（根目录携带 okf_version）
├── log.md # ISO 日期变更历史，新旧顺序
├── services/
│ ├── index.md
│ └── auth-api.md # 一个概念 = 一个文件；路径是其 ID
├── datasets/orders-db.md
├── decisions/use-okf.md
├── runbooks/payment-failures.md
└── metrics/checkout-conversion.md
```
每个概念只需要一个条件即可符合：带有非空 `type` 的 YAML 前言。缺少的部分是可选的，当缺少时会被容忍。
```markdown
---
type: 服务
title: 身份验证 API
description: 发布和验证短期访问令牌。
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---
# 端点
| 方法 | 路径 | 描述 |
|--------|----------|----------------------------|
| `POST` | `/token` | 交换凭证为 JWT。 |
```
## 仓库布局
```
okf-skills/
├── .claude-plugin/{plugin.json, marketplace.json}
├── skills/okf/{SKILL.md, reference/SPEC.md, templates/}
├── skills/validate/{SKILL.md, scripts/okf_validate.py}
├── skills/visualize/{SKILL.md, scripts/okf_visualize.py}
├── examples/sample-bundle/ # 实时演示包
├── docs/ # GitHub Pages：实时交互演示
├── templates/CLAUDE-okf.md
└── .github/workflows/ci.yml
```
## 贡献
欢迎提出问题和 PR — 新模板、更多来源的生产者、验证器和
可视化器改进。CI 在每次推送时验证插件清单和示例包。
## 致谢与许可
- **开放知识格式** 规范由 Google Cloud Data Cloud 团队提供，遵循 Apache-2.0 许可。`skills/okf/reference/SPEC.md` 直接从 [参考仓库](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) 引用，并附有署名。
- 本插件的自身代码和内容：**MIT** © Marco Boffo ([@scaccogatto](https://github.com/scaccogatto))。
MCP 市场