okf-wiki

okf-wiki：搭建 Open Knowledge Format 知识库

OKF（Open Knowledge Format）将知识存储为简短的 Markdown 文件：每个文件包含一个概念，并在 YAML frontmatter 中记录其来源；目录中通过 index.md 文件进行导航，并使用验证器确保符合规范。它适用于由人和 Agent 共同阅读和编辑的知识库、新闻编辑室的机构记忆库、研究图谱、团队决策日志以及基础设施地图。

此技能用于搭建符合规范的 OKF 项目并对其进行验证。格式规范见此技能目录中的 spec/SPEC.md；更改结构前请先阅读。

适用场景

• 用户想要创建 OKF 知识库、图谱或 wiki。
• 用户希望文档按每个文件一个概念的方式组织，并记录来源，而非采用散文式页面。
• 用户想在代码库中“初始化 OKF”，也可以选择将其发布到该代码库的 GitHub wiki 中。

从这里开始：与用户一起确定 Wiki 的范围

在搭建任何内容之前，先与用户确定四件事。这些事项会影响创建的内容及其发布方式，而且概念建立后再调整会很麻烦。分两步使用 AskUserQuestion 提问，而不是用散文描述：第一次调用时询问前三个问题；只有受众选择公开或两者皆是时，才通过后续调用询问发布方式（仅限内部的 Wiki 不适用；相关选项取决于该答案，因此不能与第一批问题一起询问）。根据仓库或项目推断标题，并向用户确认。跳过用户已在请求中回答的问题，不要重复询问已告知你的内容。

1. 受众，谁会阅读此 Wiki？此答案决定其他事项：
   • **内部（Agent 和队友）：**引导机制能发挥作用，因此保留启用状态。资源包可能包含基础设施细节，因此通常放在私有仓库中。仓库内的 bundle/ 是事实来源。
   • **公开（浏览者）：**可读性和清除机密信息优先；引导机制没那么重要，因为人会阅读，而 Agent 不会。规划一个已发布的视图（见下文“发布”）。
   • **两者皆是：**仓库内的 bundle/ 是事实来源，并为 Agent 启用引导机制，同时为读者提供已发布的视图。用户不确定时，默认选择此项。
2. 标题和章节，知识库标题（推断后确认）以及初始章节。按使用场景预设提供章节，而不是让用户从空白提示开始：
   • 新闻编辑部机构记忆：people, orgs, sources, decisions, beats
   • 研究图谱：concepts, sources, methods, findings
   • 基础设施或车队地图：machines, services, networks, credentials, processes
   • 决策日志：decisions, context, events 选定的标题和列表将用于下文的 --title 和 --sections；用户可以编辑列表。
3. 现在填充还是稍后填充，现在根据现有材料（仓库、文档、笔记或 URL）撰写概念（收集材料并在搭建完成后进入撰写循环），还是搭建空目录结构供用户稍后填写。
4. 发布目标，只有受众选择公开或两者皆是时，才通过后续 AskUserQuestion 调用询问（仅限内部的 Wiki 则完全跳过）：
   • **仅仓库内资源包（默认）：**验证器和相对链接可直接使用，无需维护额外的发布界面。适用于大多数 Wiki。
   • **GitHub wiki：**可选的阅读界面。高级且需手动操作，详见下文“可选：发布到 GitHub wiki”，使用 scripts/gh-wiki-bootstrap.py 进行引导。
   • **GitHub Pages：**从资源包渲染而成的可浏览网站。目前尚未构建，应将其视为目标，并继续以仓库内的资源包为事实来源。

将这些答案带入搭建命令（标题和章节，以及用户选择在仅公开的 Wiki 中停用引导机制时使用的 --no-hooks），并带入填充步骤。受众答案也决定了“完成前”部分要求你审慎选择的可见性；现在就先做出选择，让它能够指导后续设置。

创建的内容

scripts/scaffold.py 会生成一个按设计即可通过自身验证器的项目：

<target>/
  SPEC.md                 the OKF format contract
  README.md               how to use and validate the bundle
  scripts/validate.py     the validator
  .claude/                Claude Code adapter: session-orientation hooks
    settings.json         registers the hooks (Claude Code approves them once)
    hooks/okf-anchor.py   SessionStart: load the index into context
    hooks/okf-orient.py   PreToolUse: gate the first action on orientation
  bundle/                 the OKF bundle (the validated tree)
    index.md              carries okf_version: "0.3" by default; "0.4" with --trust-signals
    <section>/
      index.md
      example-concept.md  a starter concept with full frontmatter

文档和工具放在项目根目录；只有 bundle/ 会经过验证。请将它们分开存放：验证器会把资源包中所有非保留的 .md 文件都视为需要 frontmatter 的概念，因此若将 SPEC.md 随意放进 bundle/，验证就会失败。 .claude/ 钩子位于 bundle/ 之外，因此不会触发概念检查。

如何运行

下方的 ${CLAUDE_SKILL_DIR} 是此技能自身的目录（包含 SKILL.md 的文件夹）。Claude Code 会在运行命令前将其替换为实际的绝对路径，因此无论当前目录是什么，命令都能正常工作。在 Windows 上，请使用 python 而不是 python3（标准 Windows 未提供 python3）。--title 和 --sections 来自上述入门问题的回答，只有在用户选择退出时才使用 --no-hooks。请将脚手架生成到新目录中；操作结束时会自动进行验证：

python3 "${CLAUDE_SKILL_DIR}/scripts/scaffold.py" ./my-knowledge-base \
  --title "Team knowledge base" \
  --sections concepts,services,decisions

默认分区为 concepts。使用 --force 可写入非空目录，使用 --no-validate 可跳过验证，使用 --date YYYY-MM-DD 可设置示例 frontmatter 日期。默认会写入会话钩子；--no-hooks 可跳过它们，--hooks-os posix|windows 可覆盖自动检测到的启动命令（见下文）。

可随时从脚手架生成的项目根目录进行验证（Windows 上使用 python）：

python3 scripts/validate.py --bundle bundle    # must exit 0

填充知识包：根据现有材料编写概念

脚手架会生成一个空目录树，其中包含一个占位概念。通常接下来的请求是“这是我的文档 / 计划 / 笔记 / 代码库，帮我构建 Wiki”，但这没有导入脚本，也不可能有：判断什么算作一个独立概念、撰写它的一句话描述、选择其 type，以及将 source 指向真实来源，这些都需要判断，而非机械转换。因此，由你（Claude）直接编写概念，并按以下流程进行：

1. 收集来源。 阅读用户指定的内容，可以是文件、文件夹、仓库或 URL（先获取 URL 内容）。写作前先通读全文，以便了解自然的概念边界。
2. 确定概念边界。 一个文件对应一个概念：读者会单独查阅的一件事（服务、决策、路径、人物、事件）。如果一份文档涵盖五件事，就拆分为五个概念；如果几个片段只有放在一起才有意义，就合并为一个。标题只是提示，不是规则，不要盲目地把一个 ## 对应到一个文件。
3. 为每个概念 在 bundle/<section>/<slug>.md 中起草完整的 frontmatter。写入前先阅读 bundle 根目录中的 index.md，确保验证键与其声明的格式一致： 对于 okf_version 0.1 到 0.3，使用 verified；对于 okf_version 0.4，使用 verified_on。 按 type, title, description, source, timestamp, tags 的顺序输出这些键：
   • type 从词汇表中选择。基础设施类：Machine、Network、Service、Session、Project、 Repo、Credential、Path、Process。与领域无关类：Concept、Decision、Event、Person、 Org、Source。此外还有兜底类型 Reference。类型集合是封闭的；使用未列出的类型会导致失败。
   • description 为单行。source 中的每个元素都要加引号，指向事实的实际来源（源文件路径、URL、命令或事件），而不是此技能。
   • 将 timestamp 设为今天。verified/verified_on 是事实最近一次确认属实的日期，应根据你获知事实的方式设置，不要习惯性地设为今天：
     • 如果你现在重新对照实际情况核查过，或者用户是该事实的权威来源（他们在本次会话中陈述的决策、偏好或意图）：设为今天。
     • 如果用户是在回忆外部状态或系统状态（规范、路径、配置）：其记忆只是来源声明，并非重新核查；应使用该状态上次核查的日期，或回忆本身的日期，不要因为它在本次会话中被提起就设为今天。
     • 如果事实是从带日期的来源复制而来，且未重新核查：使用最后一次确认其属实的日期（来源自身的日期），而不是今天。
     • 如果事实来自无法重新确认的无日期记录（记忆文件、旧对话）：使用能够举证的最早日期、文件时间戳、引入该内容的提交记录日期，或陈述日期，绝不要使用今天。如果完全无法举证日期，该事实尚不可验证；请寻找有日期的来源，或省略该概念。 日期不确定时，向过去取整：较早的 verified 会准确传达“可能已过时，请重新核查”，而今天则表示“刚刚确认”。frontmatter 中的日期才是约定；正文中的限定说明无法抵消夸大的日期值，因为验证器和工具只读取日期。
   • 发现机密值时立即剔除：凭据概念应说明键名和获取路径，绝不包含其值。验证器会因泄露机密而导致构建失败。
4. 归档并链接。 将每个概念放入合适的章节（必要时新建章节），在该章节的 index.md 中为其添加项目符号，并使用相对 [text](path.md) 链接交叉链接相关概念，不要使用 [[slug]] 双链。[[slug]] 是自动记忆的惯用写法；OKF 验证器会拒绝这种写法，也无法解析它，因此拼写错误或已删除的引用会被静默放过。新建章节时，还要在 bundle 根目录的 index.md 中添加链接；会话锚点会加载该根目录文件作为导航地图，因此即使验证通过，未在其中列出的章节也无法用于定位。
5. 清除占位内容。 如果是从新脚手架开始，真实概念创建后请删除初始的 example-concept.md（以及章节 index.md 中对应的项目符号），否则示例会留在最终知识库中，且仍能通过验证。
6. 循环验证。 运行 python3 scripts/validate.py --bundle bundle，修复报告的问题后重复运行，直到退出码为 0。source 元素未加引号和 frontmatter 键缺失是最常见的问题。分批编写，并在每批之间进行验证，不要一口气写五十个文件后再排查所有问题。

当源内容已经是 OKF

如果用户指定的是一个现有的 OKF 捆绑包（例如上游示例：一个带有 okf_version 的 index.md，以及带有 frontmatter 的概念文件），你是在采用它，而不是导入它。将目录树复制或克隆进来，把验证器指向新的根目录，并修复移动后失效的链接。若要将其作为独立区域，与其他内容并列放置，请为它指定一个唯一命名的顶层目录，然后创建一个包含 okf_version 的合并根目录 index.md，并移除每个已采用捆绑包自身根目录 index.md 中的 frontmatter，将其改为普通的章节索引（验证器只允许一个合并根目录包含 okf_version；仍包含该字段的嵌套 index.md 会导致验证失败）。使用相对路径编写交叉链接，并验证合并后的根目录。将一个已经符合规范的捆绑包重新编写成你自己的概念纯属浪费精力；只有在这确实是目标时才对其进行改造。

格式简介

完整规范见 spec/SPEC.md。此规范是 Google 上游 OKF 的严格分支：它要求全部七个 frontmatter 键，使用 source 列表替代上游的 resource 和 # Citations，新增一个验证日期键，限制类型词汇，并强制解析链接。spec/SPEC.md 中的「与上游 OKF 的关系」列出了所有差异。关键规则：

• 每个概念都必须有 frontmatter：type, title, description, source、上文所述的特定版本验证键、timestamp, tags。type 可选值为：Machine、Network、Service、Session、Project、Repo、Credential、Path、Process（基础设施）；Concept、Decision、Event、Person、Org、Source（领域中立）；或 Reference（兜底类型）。
• 每个 source 元素都必须加引号，源指针包含 # 和 : ，不加引号会破坏 YAML。source: ["README.md", "issue #445"]。
• verified/verified_on 是事实最近一次被确认为属实的日期，可以是重新对照现实核查，也可以是用户声明其有权确认的事实（例如决策、偏好）；用户只是回忆起的外部状态事实属于来源声明，不算重新核查。timestamp 是概念撰写或更新的时间。在 0.3 和 0.4 中，验证日期必须采用 ISO 格式 YYYY-MM-DD；timestamp 也可以是完整的 ISO 8601 日期时间。完整日期规则见上文的编写流程。
• 绝不能包含秘密值。 凭据概念记录密钥名称和获取路径，绝不记录密钥值。若检测到泄露的秘密，验证器会导致构建失败。
• index.md 和 log.md 为保留文件，不得包含 frontmatter（捆绑包根目录的 index.md 除外，它只包含 okf_version）。

可选：上游 v0.2 信任／来源信号

上游 Google OKF v0.2（2026 年 7 月）新增了一组可选词汇，供使用者在阅读概念前对其进行判断：generated（由谁／什么生成）、verified（独立确认的列表，而非此分支自身的单一日期字段）、sources（带有结构化可信度信号的逐指针信息）、status（draft/stable/deprecated）、stale_after（绝对到期日期），以及一种用于经认可且可检查计算的 Attested Computation 类型。这些都不是必需项，不采用其中任何项的捆绑包不会受到影响。

使用这些选项来搭建项目：scaffold.py <target> --trust-signals。捆绑包会声明 okf_version: "0.4"，并在必需字段中将 verified 改名为 verified_on（从而让 verified 可用于新的字段格式；完整的字段约定和更名原因见 spec/SPEC.md 的「信任与来源」章节）。Attested Computation 同样是仅限 0.4 的类型。不加此标志时，搭建方式与引入这组词汇之前相同。

会话钩子

脚手架生成的项目会附带一个 .claude/，其中包含两个钩子，确保在其中开启的 Claude 会话从知识包开始，而不是依赖记忆：

• okf-anchor.py（SessionStart）会将知识包的根索引输出到会话上下文中。
• okf-orient.py（PreToolUse，无匹配器）会阻止会话的第一次操作，直到 Claude 确认已阅读索引，然后在本次会话的其余时间解除阻止。它在 OKF 知识包之外不会生效，发生任何错误时都会放行，因此绝不会卡住会话。

两个钩子都是跨平台的 python3 脚本。在所有操作系统上，脚本都相同；只有 .claude/settings.json 中的解释器会变化：macOS/Linux 上为 python3，Windows 上为 python。scaffold.py 会自动检测操作系统；--hooks-os posix|windows 可强制指定。

Claude Code 会将已提交到代码库的 .claude/settings.json 视为不可信，因此首次打开项目时会要求用户批准这些钩子；此后它们会自动运行。如需关闭钩子，可在搭建脚手架时使用 --no-hooks，或在现有项目中删除 .claude/（或设置 disableAllHooks）。

客户端边界

可移植的 OKF 部分包括 SPEC.md、requirements.txt、scripts/validate.py 和 bundle/ 目录树。生成的 README.md 会说明这部分共享内容，以及任何已启用的客户端适配器。生成的三个 .claude/ 文件是 Claude Code 适配器，不属于 OKF 格式，也不代表 Codex 共有行为。Codex 不会将它们作为项目配置读取，本技能也不得声称其中的 SessionStart 或 PreToolUse 生命周期钩子会在 Codex 中运行。

上文介绍的常规入门流程仍会用到 Claude Code 的 AskUserQuestion 和 ${CLAUDE_SKILL_DIR} 接口。记录在案的 Codex 试点预先设置了所有入门选项，并使用了明确的项目相对安装路径；这并不能证明未经适配的常规流程具有可移植性。

对于同时使用 Claude Code 和 Codex 的项目，请保留 .claude/，以便 Claude Code 请求信任授权并使用钩子；Codex 会将其置于不生效状态。对于仅使用 Codex 的项目，请在搭建脚手架时传入 --no-hooks，或之后删除 .claude/。无论选择哪种方式，可移植的知识包和验证器都不会改变。

可选：发布到 GitHub wiki

OKF 最适合以仓库内文件的形式存在（验证器和相对链接可直接使用）。仓库的 GitHub wiki 是可选的阅读界面；配置它是高级手动操作，大多数用户可以跳过，并将知识包保留在仓库内。

没有任何页面的 wiki 没有可供推送的 git 仓库，也没有 API，因此必须通过网页界面创建第一页。scripts/gh-wiki-bootstrap.py 可以自动完成这一步，但它会操作一个已登录的真实浏览器，因此需要你自行提供两项内容（GitHub PAT 不适用，因为 wiki 页面只能通过网页界面操作）：

• 已安装 Chromium 的 Playwright： pip install playwright && playwright install chromium。
• 已保存的 GitHub 网页会话： 一个 Playwright storageState JSON 文件，需从已登录 GitHub 的浏览器中获取。脚本会复用该会话，不会替你登录。使用 --state 指定文件路径（默认值：~/.cache/gh_state.json）。

python3 "${CLAUDE_SKILL_DIR}/scripts/gh-wiki-bootstrap.py" owner/repo --state path/to/gh_state.json
# then: git clone https://github.com/owner/repo.wiki.git and push your pages

请注意两者之间的差异：GitHub wiki 的结构比 OKF 树更扁平，并使用 [[WikiLinks]]，因此需要调整 OKF 的嵌套目录和相对链接，以适配 wiki 界面。请将 wiki 视为已发布的视图，而非事实来源。（v0.1 提供了初始化步骤；目前尚未实现知识包到 wiki 的自动同步。）

完成前

• 运行验证器并确认其退出码为 0。
• 确认入门时设置的可见性仍适用于已编写的内容：最终记录了真实基础设施的知识包通常应设为内部可见。OKF 不持立场；你必须作出决定。