okf

Open Knowledge Format（OKF）技能

OKF 将知识表示为由带有 YAML frontmatter 的 Markdown 文件组成的目录。 它在设计上力求精简：没有架构注册表、运行时或 SDK。你的任务是生成、 维护和使用符合规范的 OKF bundle，而不是依赖你对规范的记忆。

在开展非简单工作前，务必先阅读规范原文： reference/SPEC.md。这是 OKF v0.2 规范的逐字原文， 也是下列所有规则的权威依据。

唯一硬性规则

当且仅当满足以下条件时，bundle 才符合规范（§11）：每个非保留的 .md 文件都有可解析的 YAML frontmatter 块，且每个这样的块都包含非空的 type 字段。其他内容都只是建议。使用方 MUST 容忍缺失的可选字段、未知类型和损坏的链接——绝不能因此拒绝 bundle。

应遵循的约定

• 一个概念对应一个文件。 文件路径（去掉 .md）就是概念 ID。
• Frontmatter： type 为必填项。添加 title、description、tags 有助于使用时，再添加这些字段；仅当概念绑定到真实资源时，才添加 resource（规范 URI）——抽象概念应省略该字段。
• 正文： 优先使用结构化 Markdown（标题、表格、列表、围栏代码块）。 常用标题：# Schema、# Examples、# Computation。
• 交叉链接： 使用标准 Markdown 链接；优先采用相对于 bundle 的绝对路径（/services/auth-api.md）。链接表示一种关系；关系的类型应写在周围的正文中，而不是链接里。
• 保留文件： index.md（目录列表，不带 frontmatter；bundle 根目录下的索引除外，它可以包含 okf_version 和此插件的 upkeep: enforced 自选启用标记，以及 recursive: true（或深度 n：根目录以下的层级数，true 表示 6），以便让钩子监视嵌套的 git 仓库）和 log.md（按 ISO 日期记录历史，最新的在前）。切勿将这些名称用于概念。
• log.md 中记录的内容： 仅记录生命周期事件，写入 bundle 根目录的 log.md：bundle 创建、概念弃用或退役、一个概念取代另一个概念、概念在其来源变更后重新生成，以及一次验证。对概念的常规编辑不应记录：generated 和 git 已经记录了这些变更。日志只能追加，因此切勿改写或删除已有条目。

v0.2 系列（均为可选项，但都值得填写）

• 信任 (§5.2)： generated: { by, at } — 谁生成了当前内容，以及何时生成。verified: [{ by, at }] — 此后由谁确认过（单独的映射项视为一条记录）。by 按照 参与者约定 (§7) 填写：Agent 使用 <producer>/<version>，个人使用 human:<id>，自动化任务使用 process:<id>。只要内容由个人撰写或签字确认，就使用 human:——消费者会根据此前缀划分信任等级。
• 生命周期 (§5.4–5.5)： status: draft|stable|deprecated（缺省表示 stable）和 stale_after，即绝对 ISO 8601 日期时间（可使用单独的日期），而非 TTL。
• 溯源 (§5.1)： sources: [{ id, resource, title, author, usage_count, last_modified }]，以及与 sources 同级的 usage_window: { from, to }，用于界定每个 usage_count 的统计范围（条目可包含自己的统计范围以覆盖它）；没有统计范围的 usage_count 会触发警告。每个条目都必须包含 resource，其值可以是 URL、捆绑包路径或范围描述符。使用 Markdown 脚注标注特定声明，脚注标签使用来源的 id：…sharded daily.[^ga4-schema]，并添加 [^ga4-schema]: … 定义。该标签是关联键，必须与 sources[].id 相匹配。
• 认证 (§10)： 经认可的计算是独立概念，类型为 type: Attested Computation，须包含 runtime（必填）、parameters、executor、attester，并将计算本身放在 # Computation 下（或 computation: 路径中）。需要该值的概念应链接到它。切勿将某个数字对应的 SQL 内联到描述该数字的概念中。

读取 v0.1 捆绑包？ 两种结构已被取代 (§13.1)：timestamp 现在是 generated.at，正文中的 # Citations 列表现在是 sources。读取时兼容二者，写入时使用 v0.2；并且在 maintain 模式下编辑旧版概念时，将其 frontmatter 一并迁移。验证器会对二者发出警告。

可复制的模板：概念、索引、日志。

默认捆绑包位置

除非项目已使用其他位置，否则在仓库根目录使用 .okf/。将其与所描述的代码一起提交——知识即代码。

模式

produce — 创建或扩展捆绑包

要从头创建捆绑包？ 使用 init 快速路径，而不是手动编写首批文件——它会一次性生成符合规范的 index.md、log.md 和 getting-started.md 概念，并填入完整的推荐 frontmatter：

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_init.py" <target-dir> [--title "..."]

除非提供 --force，否则如果目录中已有 .md 文件，它将拒绝进行修改。然后扩展捆绑包：

1. 阅读 reference/SPEC.md。
2. 选择来源：code（从源代码、README、文档字符串和配置中提炼概念）、docs/wiki（将页面提炼为概念，并在 sources 中记录原始资料）、manual（决策、操作手册、指标）。
3. 按领域选择目录布局（例如 services/、datasets/、decisions/）。每个文件对应一个概念。
4. 根据 templates/concept.md 编写每个概念：设置描述性 type，填写推荐字段，记录 generated 和实际阅读过的 sources，并交叉链接相关概念。
5. 为每个目录添加或更新 index.md（并在根索引中设置 okf_version: "0.2"）。新建的捆绑包要在 log.md 中添加带日期的 Creation 条目。扩展已有捆绑包则不需要。
6. 验证（见下文）。完成前修复所有错误。

维护 — 让知识包与实际情况保持同步

1. 确定此次更改影响哪些概念（按 resource、路径或主题搜索）。这类整理工作正是 Agent 擅长的——一次性更新所有受影响的文件。
2. 更新正文和 generated.at（在 generated.by 中填写你自己的操作者）；修复或添加交叉链接；为新资产创建概念；将已移除资产标记为 status: deprecated，并在 log.md 中注明弃用情况，不要悄悄删除上下文。要处理的是整个 v0.1 知识包，而不是某个零散字段？不要手动编辑——运行一次验证器的 --migrate。
3. 更新相关的 index.md 文件。只有当更改属于生命周期事件时，才在 log.md 中追加带日期的条目（参见 log.md 中应记录的内容）。
4. 验证。

使用 — 将知识包用作上下文

1. 首先阅读知识包根目录的 index.md，以渐进式披露信息；然后只沿链接查看与任务相关的概念。
2. 审慎评估所读内容：status: draft／deprecated、已经过期的 stale_after，或缺少 verified 条目，都表示“依赖前请先核实”。将失效链接视为尚未编写的知识，而不是错误。
3. 需要一个由 Attested Computation 覆盖的数值？使用绑定到已声明 parameters 的值来运行其计算——绝不要自行编写查询。
4. 如果工作过程中了解到某些持久有用的信息，请切换到维护并将其写回。

验证（宣布完成前执行）

不要凭目测判断是否符合要求——运行确定性检查器。调用配套的 validate 技能（/okf:validate <bundle-dir> --strict），该技能会提供检查器。如果未安装该技能，请直接运行：

uv run "${CLAUDE_SKILL_DIR}/../validate/scripts/okf_validate.py" <bundle-dir> --strict

解决所有 ERROR（§11 中的硬性失败项）。在 --strict 模式下，警告也会导致运行失败（退出码为 1），因此也要清除警告；如果只想检查是否符合 §11 的要求，可移除 --strict（或使用 --max-warnings N）。