内容
# okf-kit
[](https://github.com/vinodborole/okf-kit/actions/workflows/ci.yml)
[](https://pypi.org/project/okf-kit/)
[](https://pypi.org/project/okf-kit/)
[](LICENSE)
[](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
**将任何网站转化为可移植、代理就绪的知识包 — 无需大型语言模型即可开始。**
<p align="center"><img src="docs/assets/demo.svg" alt="okf-kit: build a docs site into an OKF bundle, chat with it, and serve it to a coding agent — no API key" width="760"></p>
`okf-kit` 将网站爬取成
[谷歌开放知识格式（OKF）](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
知识包：一个包含 markdown 概念文件和 YAML 前置信息的目录，以及每个目录的 `index.md` 列表，任何代理都可以通过纯文件读取来导航。构建它，保持同步发布它，并与它聊天 — 本地、通过自己的密钥或完全离线通过 Ollama。
```bash
pip install okf-kit
okf build https://docs.example.com -o docs-okf # 爬取 → OKF 知识包（无需密钥，无需浏览器）
okf chat docs-okf --provider ollama # 离线聊天，无需密钥
```
或使用 [`uv`](https://docs.astral.sh/uv/) 零安装：
```bash
uvx --from okf-kit okf build https://docs.example.com -o docs-okf
```
**calknowledge** 生态系统的一部分 — okf-kit 是轻量级、开源的库；calknowledge 是在此基础上构建的完整平台（LLM 增强、RAG 导出、检索评估、GUI）。
---
## 为什么
每个人都重新爬取和重新索引相同的文档，效果不佳。okf-kit 使网站的知识成为一个**可移植的产物**：
- **代理可以读取 OKF 知识包；它们无法读取您的网站。** 知识包是可导航的 markdown — 无需爬取，无需 SDK，无需运行时。
- **忠实的 markdown，而不是文本混合。** 真实的提取（标题、代码、表格）、模板过滤、需要时渲染 JavaScript。
- **自我维护。** `okf sync` 仅更新更改的内容，因此发布的知识包在 git 中产生小的增量提交，并且永远不会过时。
- **与任何 LLM 合作，或无需 LLM。** 通过 OpenAI、Ollama、vLLM、OpenRouter 或 Claude 进行聊天 — 或使用零密钥检索答案和引用。
## 安装
```bash
pip install okf-kit # 核心：构建 / 同步 / 验证 / 打包 / 列表 / 获取 / 可视化
pip install "okf-kit[chat]" # okf 聊天，通过 OpenAI 兼容的提供商（OpenAI、Ollama、…）
pip install "okf-kit[anthropic]" # Claude 作为聊天提供商
pip install "okf-kit[js]" # 爬取 JavaScript 渲染的网站（拉取 Playwright Chromium）
pip install "okf-kit[mcp]" # 通过 MCP 向 Claude Code / Cursor 提供知识包
pip install "okf-kit[enrich]" # okf build --enrich（LLM 描述 + 标签）
```
默认安装**无需浏览器和 LLM SDK** — 它在几秒钟内安装完成。
> **提示：** 安装到一个专用的虚拟环境中，以便 okf-kit 的依赖项不会与其他项目混淆：
> ```bash
> python3 -m venv ~/okf && ~/okf/bin/pip install okf-kit
> ```
> 这也避免了冲突，如果现有环境已经固定了诸如 `lxml` 之类的包（例如，先前的 `crawl4ai` 安装）— 普通安装否则会升级它们。
## 命令
### 构建
```bash
okf build https://docs.example.com -o docs-okf --max-depth 3 --max-pages 200
```
域名限制的 BFS 爬取 → OKF 知识包：`pages/` 镜像包含前置信息的概念、用于同步的 `.okf-kit/state.json` 和用于代理导航的每个目录的 `index.md`。退出时验证。无需 API 密钥。
默认情况下，爬取**限定在种子路径部分** — `okf build https://doc.rust-lang.org/book/` 停留在 `/book/` 下，不会漫游到主机其他部分。覆盖 `--path-prefix PATH`（更窄/不同的范围）或 `--all-paths`（整个主机）。其他标志：`--js`（JavaScript 渲染的网站 — 构建提示，当网站需要它时）、`--no-robots`、`--enrich`（添加 LLM 描述/标签 — 需要 `[enrich]` + `OPENAI_API_KEY`）。
### 同步
```bash
okf sync docs-okf
```
重新爬取相同的网站并更新**仅有变化的部分** — 添加的页面写入、更改的页面重写、删除的页面删除、不变的页面字节对字节保留（稳定的 git diffs）。一个安全阀在可疑的空重新爬取时中止（`--force` 覆盖）。
### 聊天
```bash
okf chat docs-okf --provider ollama # 离线，无需密钥
okf chat docs-okf --provider openai --trace # 任意提供商，附带引用 + 导航跟踪
okf chat docs-okf # 无提供商 → 零密钥检索答案
okf chat docs-okf --resume # 继续上次会话（历史记录本地存储）
```
代理导航知识包（`list_directory` / `read_concept`）到最具体的概念，并**仅根据阅读内容**回答，引用路径。
| `--provider` | 端点 | 密钥 |
|---|---|---|
| `openai` | OpenAI | `OPENAI_API_KEY` |
| `ollama` | `localhost:11434`（本地） | 无 |
| `openrouter` | OpenRouter | `OPENROUTER_API_KEY` |
| `anthropic` | Claude | `ANTHROPIC_API_KEY` |
| `custom` | `--base-url` | 按配置 |
聊天历史记录存储在 `~/.okf/chats/<bundle>/`。
### 可视化
```bash
okf visualize docs-okf # -> docs-okf/graph.html
```
自包含的交互式图（节点 = 概念，边 = 内部链接）；无需后端，无需 CDN — 直接从 `file://` 打开 HTML。
### 通过 MCP 提供服务
```bash
okf serve-mcp docs-okf # 或 --all 获取每个下载的知识包
```
通过 stdio MCP 向 Claude Code/Desktop、Cursor 和任何 MCP 客户端公开 `list_bundles` / `list_directory` / `read_concept` / `search_bundle`。
**或作为容器运行**（包含的 `Dockerfile` 嵌入了 `rust-book` 知识包）：
```bash
docker build -t okf-kit-mcp .
docker run -i --rm okf-kit-mcp # 通过 stdio 提供 MCP 服务；提供另一个知识包：… okf-kit-mcp okf serve-mcp <name>
```
### 注册表
```bash
okf list --remote # 浏览已发布知识包
okf get backstage-docs # 下载、验证、安装到 ~/.okf/bundles/
okf list # 您的本地知识包
```
### 打包用于交付
```bash
okf zip docs-okf # -> docs-okf.zip，准备发布或分享
```
## 发布
参见 [docs/PUBLISHING.md](docs/PUBLISHING.md) — 构建知识包，将其作为发布 zip 文件发送，并每周添加一个自我同步操作，然后将其添加到 [awesome-okf-kit](https://github.com/vinodborole/awesome-okf-kit) 注册表中。仅发布您可以重新分发的内容。
## 知识包布局
```
docs-okf/
index.md 根目录列表（保留，无前置信息）
log.md 构建/同步历史记录
pages/ 每个概念一个页面（前置信息 + 正文 + 引用）
index.md 目录列表（每个目录都有）
home.md
docs/…
.okf-kit/state.json 爬取配置，每页内容哈希，链接边
```
## 开发
`pip install -e ".[dev]"`，然后 `pytest -q`（37 个测试，完全离线）和 `ruff check okf_kit tests`。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CHANGELOG](CHANGELOG.md)。
## 许可证
Apache-2.0。
