okf-kit 完全指南 — 总结与资源

okf-kit 完全指南 — 总结与资源#

一句话摘要：本章节回顾 okf-kit 的核心知识点，提供 CLI 命令速查表和典型使用场景模板，汇总官方资源和生态项目链接。

1. 核心知识点回顾#

1.1 本质理解#

okf-kit 做的事情可以用一句话概括：将网站转化为 Agent 可直接读取的可移植 Markdown 知识包。

关键设计理念：

零 Key 启动：核心爬取无需 API Key，LLM 是可选增强
渐进式导航：目录索引让 Agent 像人浏览文件一样查找信息
增量同步：内容 hash 确保只更新变更页面，git diff 干净
可移植性：bundle 是纯文本目录，可以 git、zip、离线使用

1.2 核心流程#

网站 URL → [BFS爬取] → [Markdown提取] → [URL映射] → [写入Bundle]
                                                          ↓
                                              [index.md索引] → [validate] → [zip]
                                                          ↓
                                              [.okf-kit/state.json]
                                                          ↓
                                              chat / MCP / serve / visualize

1.3 五大核心能力#

能力	命令	关键特性
构建	`okf build`	BFS爬取、HttpFetcher/BrowserFetcher、自动prefix
同步	`okf sync`	content hash增量、安全阈值、git友好
对话	`okf chat`	Agent导航、零Key检索、多Provider支持
服务	`okf serve-mcp` / `okf serve`	stdio MCP、HTTP API + SSE
生态	`okf get` / `okf visualize`	Registry发现、知识图谱

2. CLI 命令速查表#

2.1 构建与维护#

命令	说明	典型用法
`okf build <URL>`	爬取网站生成bundle	`okf build https://docs.example.com -o docs -d 3 -p 200`
`okf build <URL> --js`	JS渲染站点爬取	`okf build https://spa.example.com -o spa --js`
`okf build <URL> --enrich`	LLM富化frontmatter	`okf build https://docs.example.com -o docs --enrich`
`okf build <URL> --all-paths`	爬取同域所有路径	`okf build https://example.com -o full --all-paths -p 500`
`okf sync <DIR>`	增量同步（重新爬取，hash判断变更）	`okf sync docs`
`okf sync <DIR> --force`	忽略删除阈值强制同步	`okf sync docs --force`
`okf validate <DIR>`	验证OKF规范	`okf validate docs`
`okf zip <DIR>`	打包zip	`okf zip docs -o docs.okf.zip`

2.2 知识消费#

命令	说明	典型用法
`okf list`	列出已注册bundle	`okf list`
`okf get <NAME>`	从Registry获取	`okf get <name>`
`okf chat <DIR>`	零Key检索问答（交互模式）	`okf chat docs`
`okf chat <DIR> --provider ollama`	Ollama离线对话	`okf chat docs --provider ollama -m llama3.1`
`okf chat <DIR> --provider openai`	OpenAI对话	`okf chat docs --provider openai -m gpt-4o-mini`
`okf chat <DIR> --trace`	显示导航轨迹	`okf chat docs --provider ollama --trace`
`okf visualize <DIR>`	生成知识图谱HTML	`okf visualize docs -o graph.html`

2.3 服务暴露#

命令	说明	典型用法
`okf serve-mcp <DIR>`	启动MCP服务	`okf serve-mcp docs`
`okf serve`	启动HTTP API	`okf serve --port 8000 --token mytoken`

2.4 常用选项速查#

选项	默认值	适用命令	说明
`-o, --output`	自动派生	build, zip	输出路径
`-d, --max-depth`	3	build, sync	BFS爬取深度
`-p, --max-pages`	200	build, sync	最大页面数
`--js`	off	build	使用浏览器渲染JS（需`[js]` extra）
`--all-paths`	off	build	爬取同域所有路径（不限前缀）
`--path-prefix`	自动推导	build	URL路径前缀限制
`--no-robots`	off	build	忽略robots.txt
`--enrich`	off	build	LLM富化frontmatter（需`[enrich]` extra）
`--enrich-model`	gpt-4o-mini	build	富化使用的模型
`--force`	off	build, sync	build:覆盖已有目录; sync:忽略删除阈值
`--verbose` / `-v`	off	build	详细输出
`--provider`	zero-key	chat	LLM提供商（zero-key/openai/ollama等）
`--model` / `-m`	提供商默认	chat	模型名称
`--base-url`	提供商默认	chat	OpenAI兼容API端点
`--trace`	off	chat	显示导航轨迹
`--host`	127.0.0.1	serve	绑定地址
`--port`	0(自动)	serve	监听端口
`--token`	auto	serve	Bearer token（auto=随机生成）

3. 典型使用场景模板#

场景1：快速构建文档知识库#

# 1. 安装
pip install okf-kit

# 2. 爬取文档站（首次构建）
okf build https://docs.python.org/3/ -o python3-docs --max-depth 4 --max-pages 300

# 3. 验证
okf validate python3-docs

# 4. 查看生成结果
ls python3-docs/
cat python3-docs/index.md

# 5. 零Key检索（进入交互模式后直接输入问题）
okf chat python3-docs
# 在交互提示后输入：如何定义一个类？

# 6. 后续更新（每周一次）
okf sync python3-docs

场景2：MCP 集成到 Claude Code#

# 1. 安装MCP支持
pip install 'okf-kit[mcp]'

# 2. 构建bundle
okf build https://api-docs.example.com -o api-docs

# 3. 添加到Claude Code
claude mcp add okf-api-docs -- okf serve-mcp api-docs

# 4. 在Claude Code中直接使用
# 提问："如何调用用户创建API？"
# Claude会自动通过MCP读取文档回答

场景3：完全离线知识库（Ollama）#

# 1. 安装chat支持
pip install 'okf-kit[chat]'

# 2. 确保Ollama运行并拉取模型
ollama serve &
ollama pull llama3.1:8b

# 3. 构建bundle
okf build https://internal-docs.example.com -o internal-docs

# 4. 离线对话
okf chat internal-docs --provider ollama --model llama3.1:8b

场景4：Bundle 发布到社区#

# 1. 构建高质量bundle（react.dev是SPA，需要--js）
okf build https://react.dev -o react-docs -d 5 -p 500 --js

# 2. 验证通过
okf validate react-docs

# 3. 打包
okf zip react-docs

# 4. 上传到GitHub Releases

# 5. Fork awesome-okf-kit，添加到registry.yaml，提交PR

4. 核心数据位置速查#

内容	路径	说明
用户主目录	`~/.okf/`	okf-kit 数据根目录
Bundles	`~/.okf/bundles/`	所有已安装的bundle
聊天历史	`~/.okf/chats/<bundle>/`	JSONL格式会话记录
设置	`~/.okf/settings.json`	Provider配置（不含Key）
API密钥	OS Keychain / `~/.okf/.secrets.json`	安全存储
Bundle状态	`<bundle>/.okf-kit/state.json`	爬取元数据（增量同步用）
构建日志	`<bundle>/log.md`	爬取过程日志
目录索引	`<bundle>/index.md` 等	Agent导航入口

5. 官方资源链接#

资源	URL
GitHub 仓库	github.com/vinodborole/okf-kit
PyPI 包	pypi.org/project/okf-kit
OKF 规范	GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md
awesome-okf-kit	github.com/vinodborole/awesome-okf-kit（社区Bundle Registry）
calknowledge 平台	github.com/vinodborole/calknowledge（基于okf-kit的完整平台）
okf-desktop	github.com/vinodborole/okf-desktop（桌面GUI客户端）
MCP 协议	modelcontextprotocol.io

6. 相关项目对比#

项目	类型	与okf-kit的关系
Firecrawl	云爬虫API	类似的爬取→Markdown功能，但需要API Key且输出非OKF格式
Crawl4AI	开源爬虫库	okf-kit的BrowserFetcher底层使用Crawl4AI
trafilatura	正文提取库	okf-kit的HttpFetcher底层使用trafilatura做正文提取
MkDocs	文档站点生成器	okf-kit可以爬取MkDocs生成的站点制作离线bundle
Docusaurus	React文档框架	SSR版本可直接用HttpFetcher，SPA版本需用BrowserFetcher
LangChain	LLM应用框架	okf-kit的bundle可作为LangChain的Document Loader来源
LlamaIndex	RAG框架	bundle可作为LlamaIndex的知识源
Ollama	本地LLM运行时	okf-kit chat推荐搭配实现完全离线
Claude Code	AI编程助手	通过MCP集成okf-kit bundle
Cursor	AI编辑器	通过MCP集成okf-kit bundle

7. Extras 安装速查#

想做什么	安装命令
核心功能（build/sync/validate/zip/list/chat零Key/visualize）	`pip install okf-kit`
爬取JS渲染站点（SPA）	`pip install 'okf-kit[js]'`
LLM对话（OpenAI/Ollama/OpenRouter/Custom）	`pip install 'okf-kit[chat]'`
Claude/Anthropic对话	`pip install 'okf-kit[anthropic]'`
MCP服务（Claude Code/Cursor）	`pip install 'okf-kit[mcp]'`
HTTP API服务（GUI客户端用）	`pip install 'okf-kit[serve]'`
所有功能	`pip install 'okf-kit[all]'`
开发（测试+类型检查）	`pip install -e '.[dev]'`

8. 学习检查清单#

完成本教程学习后，你应该能够：

[ ] 解释 OKF 格式与传统 RAG 方案的区别
[ ] 使用 okf build 爬取静态文档站点
[ ] 使用 --js 爬取 JS 渲染站点
[ ] 理解 BFS 爬取和路径前缀的作用
[ ] 使用 okf sync 进行增量更新
[ ] 解释 content hash 如何工作以及安全阈值的意义
[ ] 在零 Key 模式下检索 bundle 内容
[ ] 配置 Ollama 进行完全离线对话
[ ] 解释 Agent 导航模式与传统 RAG 的区别
[ ] 配置 MCP 让 Claude Code/Cursor 读取 bundle
[ ] 使用 okf serve 启动 HTTP API
[ ] 使用 okf visualize 生成知识图谱
[ ] 从 Registry 安装社区 bundle
[ ] 排查常见的爬取和对话问题

9. 进一步学习路径#

深入 OKF 规范：阅读 Google OKF SPEC 文档，理解格式设计哲学
calknowledge 平台：体验 LLM 富化、RAG 导出等增强功能
okf-desktop：使用桌面 GUI 进行可视化知识库管理
自定义 Fetcher：参考第9章实现 PDF/Notion/Confluence 等自定义抓取器
MCP 生态：探索更多 MCP 服务器，构建完整的 AI 辅助开发工作流
Bundle 贡献：爬取优质文档站点发布到 awesome-okf-kit 社区

← 上一章：FAQ 与排错
返回概述

okf-kit 完全指南 — 总结与资源

目录

okf-kit 完全指南 — 总结与资源#

1. 核心知识点回顾#

1.1 本质理解#

1.2 核心流程#

1.3 五大核心能力#

2. CLI 命令速查表#

2.1 构建与维护#

2.2 知识消费#

2.3 服务暴露#

2.4 常用选项速查#

3. 典型使用场景模板#

场景1：快速构建文档知识库#

场景2：MCP 集成到 Claude Code#

场景3：完全离线知识库（Ollama）#

场景4：Bundle 发布到社区#

4. 核心数据位置速查#

5. 官方资源链接#

6. 相关项目对比#

7. Extras 安装速查#

8. 学习检查清单#

9. 进一步学习路径#