01
安装一次
用 npm 或 bun 安装，后续命令统一都是 okf。
指南
先跑通第一个 bundle。
先安装 CLI，再用固定示例完成 convert、validate、search 和 viewer。这里的 search 是给 agent 工作流用的渐进式检索步骤；跑通之后，再把同一套流程换到你自己的本地目录。
02
先跑固定示例
首次体验直接用固定仓库和固定提交，结果更可复现；再用 metadata search 先筛出适合进入 agent 上下文的 wiki 概念。
03
再换本地目录
整体流程不变，只替换 source path、profile，以及 agent 要使用的检索查询词。
步骤 1
安装 CLI
先把已发布的 CLI 装好。npm 和 bun 二选一，不要两条都执行。后面的所有命令都直接使用 okf。
命令
npm 安装
如果你平时用 npm，就执行这一条。它和下面的 bun 安装命令二选一，不需要两个都跑。
npm i -g @fastrag/okf或 bun 安装
如果你已经在用 bun，就改用这一条。只需要保留一种全局安装路径即可。
bun install -g @fastrag/okf步骤 2
运行固定 GitHub 示例
首次建议直接用固定仓库和固定提交。先 convert、再 validate、再把 search 当成渐进式检索步骤，最后 generate 并本地 serve workbench。
命令
convert
读取固定仓库 mattpocock/dictionary-of-ai-coding 的固定提交，并把第一个 OKF bundle 写到 ./out/okf。
okf convert mattpocock/dictionary-of-ai-coding ./out/okf --profile ./starter-profile.zh-CN.yaml --ref 251fec7ec3b08059e4203863024e6123090a54e3validate
在继续生成浏览器工作台之前，先检查 ./out/okf 的 bundle 结构。
okf validate ./out/okfsearch
先对 ./out/okf 做一次 metadata 搜索，把它当成 agent 工作流里的轻量检索步骤，再决定要把哪些概念加载进更完整的上下文。
okf search --bundle ./out/okf agentviewer generate
把浏览器工作台静态文件生成到 ./out/workbench，供后续本地预览使用。
okf viewer generate --bundle ./out/okf --out ./out/workbenchviewer serve
从 ./out/workbench 启动本地预览服务，直接在浏览器里查看生成后的 workbench。
okf viewer serve --dir ./out/workbench步骤 3
切换到本地目录
当固定示例跑通后，只替换 source path、profile 和检索查询词，剩余命令顺序保持不变。
命令
convert
把示例仓库替换成你自己的本地目录 ./local-docs，bundle 仍然输出到 ./out/okf。
okf convert ./local-docs ./out/okf --profile ./starter-profile.zh-CN.yamlvalidate
继续沿用同样的校验步骤，先确认本地 bundle 的结构有效。
okf validate ./out/okfsearch
把 <query> 替换成 agent 在渐进式检索里会使用的标题、路径、类型、描述关键词或标签，再决定要把哪些概念进一步加载进上下文。
okf search --bundle ./out/okf <query>viewer generate
把本地 bundle 的浏览器工作台静态文件生成到 ./out/workbench。
okf viewer generate --bundle ./out/okf --out ./out/workbenchviewer serve
像示例流程一样启动本地预览，直接检查你自己的 workbench。
okf viewer serve --dir ./out/workbench