# https://github.com/VectifyAI/OpenKB 项目说明书 生成时间：2026-06-24 19:36:59 UTC ## 目录 - [OpenKB 概览与系统架构](#page-1) - [Wiki 编译管道与知识管理](#page-2) - [生成器层：查询、聊天、技能工厂与可视化](#page-3) - [配置、LLM 集成与生态集成](#page-4) ## OpenKB 概览与系统架构 ### 相关页面 相关主题：[Wiki 编译管道与知识管理](#page-2), [生成器层：查询、聊天、技能工厂与可视化](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md) - [openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) - [openkb/agent/query.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/query.py) - [openkb/agent/linter.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/linter.py) - [openkb/agent/skill_runner.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/skill_runner.py) - [openkb/agent/tools.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/tools.py)
# OpenKB 概览与系统架构 ## 一、项目定位与核心思想 **OpenKB（Open Knowledge Base）** 是一个基于 LLM 的开源命令行工具，能够将多种格式的原始文档（PDF、Word、Markdown、PowerPoint、HTML、Excel、CSV、文本、URL 等）编译成结构化、可互相链接的 wiki 式知识库。其底层检索由 [PageIndex](https://github.com/VectifyAI/PageIndex) 提供，支持长文档的"无向量、基于推理"的检索方式。资料来源：[README.md:1-15]() OpenKB 的设计灵感来自 Andrej Karpathy 关于"LLM 驱动知识库"的概念——知识被一次性编译、持续累积，而不是像传统 RAG 那样在每次查询时重新发现。资料来源：[README.md:17-19]() 相较于传统 RAG，OpenKB 的核心差异在于：知识被沉淀为持久的 wiki 结构，跨页引用、矛盾标记、综合分析都基于已经"消费过"的内容。系统分为两层——**wiki 基础层**负责编译与维护，**生成器层**（query / chat / Skill Factory）将 wiki 转化为可用输出。资料来源：[README.md:21-25]() ## 二、双层架构总览 OpenKB 的运行时由两层组成：基础层把原始文档变成可检索的 wiki；生成器层消费 wiki 产出最终结果。 ```mermaid flowchart TB A[raw/ 原始文档] --> B[基础层: 编译与索引] B --> B1[PageIndex 树索引
长文档] B --> B2[Summary / Concept / Entity 页面] B --> B3[wiki/ 目录] B3 --> C{生成器层} C --> D[query: 引用式问答] C --> E[chat: 多轮会话] C --> F[skill new: 技能包] C --> G[deck new: 演示稿] C --> H[visualize: 知识图谱] ``` 基础层关键能力包括： - **多模态文档解析**：自动识别 PDF、Office、HTML、URL 等格式并提取文本与图像。资料来源：[README.md:29-33]() - **PageIndex 长文档索引**：当 PDF 超过 `pageindex_threshold`（默认 20 页）时启用树形索引，实现 context-aware 的精确检索。资料来源：[README.md:35-39]() - **结构化编译**：通过 LLM 流水线生成 `summaries/`、`concepts/`、`entities/` 三个子目录，页面之间通过 `[[wikilinks]]` 形成双向引用。资料来源：[openkb/agent/compiler.py:10-30]() ## 三、编译流水线（Compiler Pipeline） 编译流程位于 `openkb/agent/compiler.py`，分为四个主要阶段，并利用 LLM 的 prompt cache 优化成本。资料来源：[openkb/agent/compiler.py:1-15]() | 阶段 | 动作 | 关键产物 | |---|---|---| | Step 1 | 构造基础上下文 A：schema + 文档内容 | 缓存断点 1 | | Step 2 | A → 生成 summary 页面 | `summaries/.md` | | Step 3 | A + summary → 制定 concepts 计划（create/update/related） | 缓存断点 2 | | Step 4 | 并发调用 LLM 生成新概念页、改写旧概念页；代码补齐交叉引用并更新 `index.md` | `concepts/*.md` + 反向链接 | Anthropic 系列的 prompt cache 通过 `cache_control` 标记启用：第一个标记在文档消息末尾（跨 N+M+2 次调用共享 system+doc），第二个标记在 summary 消息末尾（跨 N+M 次概念生成调用共享额外前缀）。对不支持 `cache_control` 的提供方，标准化为 list-of-blocks 形式以保持兼容。资料来源：[openkb/agent/compiler.py:30-55]() 代码部分负责确定性任务：把 summary 中提到但未链接的概念补全 `## Related Documents` 段、生成 `[[concepts/...]]` 反向链接、更新 `index.md`。资料来源：[openkb/agent/compiler.py:60-110]() > 社区关注：在 issue #41 中，用户希望显式删除已过时或被替代的文档——`openkb remove ` 命令会清理对应的 summary、concept、entity、图像、PageIndex 状态，并通过 `--dry-run` 预览或 `--keep-raw/--keep-empty` 保留产物。资料来源：[README.md:64-72]() ## 四、生成器层（Generators） 生成器消费已编译的 wiki 产出最终结果。当前官方支持的生成器包括： - **query**：单次引用式问答，工具集包括 `read_file`、`get_page_content`（按页号拉取 PageIndex 文档）、`get_image`（查看图表）。资料来源：[openkb/agent/query.py:1-35]() - **chat**：多轮会话，支持 `--resume/--list/--delete` 管理历史 session。资料来源：[README.md:88-90]() - **skill new**：从 wiki 蒸馏出可分发的 agent skill（Claude Code、Codex 等可加载），产物结构为 `SKILL.md + references/ + (scripts/)`，同时自动生成 `.claude-plugin/marketplace.json`。资料来源：[openkb/agent/skill_runner.py:1-30]()、[README.md:165-185]() - **deck new**（v0.4.1 新增）：把 wiki 编成单文件 HTML 演示稿，输出至 `output/decks//index.html`，支持全屏与 ←/→/F/P 导航。资料来源：[README.md:8-14]() - **visualize**：将 wiki 渲染为单文件离线 HTML，提供 3D 力导向图、mind-map、径向树三种视图。资料来源：[README.md:150-155]() ## 五、知识健康检查（Lint） `openkb lint` 启动一个语义审计 Agent（`openkb/agent/linter.py`），对 wiki 内的矛盾、缺口、过时、冗余、概念/实体覆盖、孤立实体等问题生成结构化 Markdown 报告。资料来源：[openkb/agent/linter.py:1-30]() Agent 暴露两个 `function_tool`：`list_files(directory)` 列出指定子目录的 Markdown 文件；`read_file(path)` 读取任意 wiki 文件（路径必须位于 wiki root 之内以防止越权）。资料来源：[openkb/agent/tools.py:1-25]() > 社区关注：issue #28 提出"反馈与修正机制"——目前 lint 报告是最接近的官方纠错通道；用户可以借助 `openkb feedback` 提交带类型的 GitHub issue（`--type bug/feature/question`）来推动知识库修正。资料来源：[README.md:74-76]() ## 六、配置与运行时限制 OpenKB 的配置位于 `.openkb/config.yaml`，关键字段为 `model`（使用 LiteLLM 的 `provider/model` 格式）、`language`、`pageindex_threshold`（PDF 页数阈值）。资料来源：[README.md:125-140]() > 社区关注：issue #132 和 #137 都涉及 LiteLLM 的兼容问题—— > - 在使用 Ollama 等本地模型时，10 分钟默认超时可能不足，需要在配置中传入 timeout 参数； > - 某些 provider（如 Ollama）不支持部分 LiteLLM 参数（`UnsupportedParamsError`），需要过滤或换用 OpenAI 兼容协议。 > 资料来源：[README.md:142-156]() > 社区关注：issue #61 反映企业场景下需要 S3 / MinIO 等对象存储支持——目前 OpenKB 仅支持本地文件系统，需要用户在外部把对象下载到 `raw/` 临时目录、生成后再上传产物。资料来源：[README.md:64-66]() ## 七、与其他 Agent 的集成 OpenKB 内置 `SKILL.md`（位于 `skills/openkb/SKILL.md`），使 Claude Code、Codex CLI、Gemini CLI 等 agent 可以直接以"只读"方式读取已编译的 wiki。Skill 默认不执行 `openkb add/remove/lint --fix` 等写操作，必须由用户显式触发。资料来源：[README.md:200-235]() --- ## See Also - OpenKB 编译流水线详解（`openkb/agent/compiler.py`） - PageIndex 长文档索引（[VectifyAI/PageIndex](https://github.com/VectifyAI/PageIndex)） - Agent Skill 格式（[Claude Skills 文档](https://docs.claude.com/en/docs/build-with-claude/skills)） --- ## Wiki 编译管道与知识管理 ### 相关页面 相关主题：[OpenKB 概览与系统架构](#page-1), [生成器层：查询、聊天、技能工厂与可视化](#page-3), [配置、LLM 集成与生态集成](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) - [openkb/agent/query.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/query.py) - [openkb/agent/linter.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/linter.py) - [openkb/agent/skill_runner.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/skill_runner.py) - [openkb/agent/tools.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/tools.py) - [README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md)
# Wiki 编译管道与知识管理 ## 概述与定位 OpenKB 的核心能力是将原始文档（PDF、Word、Markdown、HTML 等）通过 LLM 编译成一个持续累积、可链接检索的 Wiki 知识库。与传统 RAG 不同，OpenKB 不在每次查询时重新检索切片，而是把文档"编译"成结构化的 Markdown Wiki 页面（summaries、concepts、entities），让知识随时间沉淀 [README.md:1-40](README.md)。 Wiki 编译管道（`openkb/agent/compiler.py`）是这条主线的核心组件，负责把单个文档转成可被检索、引用和维护的页面。配套的知识管理操作包括：增删文档（`openkb remove`）、重编译（`openkb recompile`）、健康检查（`openkb lint`）、以及查询/会话/可视化等"生成器"输出 [README.md:50-90](README.md)。 ## 编译管道架构 `compile_short_doc` 与长文档变体 `compile_pageindex_doc` 共享一条五步流水线 [openkb/agent/compiler.py:120-200](openkb/agent/compiler.py)： 1. **Step 1 — 构建基础上下文 A**：把 schema（`get_agents_md`）和文档内容拼装成 system + doc 两条消息，作为后续所有 LLM 调用的共享前缀。 2. **Step 2 — 生成摘要**：A → LLM → 输出单页 summary，写入 `wiki/summaries/{doc_name}.md`。 3. **Step 3 — 概念/实体规划**：A + summary → LLM JSON，规划需要新建/更新/关联的 concept 列表。 4. **Step 4 — 并发生成**：以 A + summary 为缓存前缀，并发调用 N+M 次 LLM（`max_concurrency=DEFAULT_COMPILE_CONCURRENCY`），分别生成或重写 concept、entity 页面；写入前调用 `strip_ghost_wikilinks` 清理未在白名单中的 `[[wikilink]]` [openkb/agent/compiler.py:300-360](openkb/agent/compiler.py)。 5. **Step 5 — 反向链接与索引更新**：纯代码阶段。`_backlink_summary` / `_backlink_concepts` 在 summary 页和 concept 页之间插入双向 `[[wikilinks]]`；`_update_index` 刷新 `wiki/index.md` [openkb/agent/compiler.py:380-460](openkb/agent/compiler.py)。 ```mermaid flowchart TD A[文档 raw/*] --> B[Step1: 拼装 schema + 文档上下文 A] B --> C[Step2: 生成 summary] C --> D[Step3: 规划 concepts/entities 计划] D --> E[Step4: 并发 LLM 调用
基于 A + summary 缓存] E --> F[strip_ghost_wikilinks 清洗] F --> G[Step5: 反向链接 + index 更新] G --> H[wiki/summaries, concepts, entities, index.md] ``` 为降低成本，管道在两个断点启用 Anthropic prompt caching：通过 `_cached_text` 在文档消息末尾和 summary 消息末尾插入 `cache_control: ephemeral`；不支持缓存的厂商会收到规范的 list-of-blocks 内容，LiteLLM 直接透传 [openkb/agent/compiler.py:50-110](openkb/agent/compiler.py)。 ### 长文档分支（PageIndex） 当 `pageindex_threshold` 触发且文档带 `doc_type: pageindex` 时，`compile_pageindex_doc` 会先用 `get_wiki_page_content`（`openkb/agent/tools.py`）按需检索页内容，再喂入相同的概念/实体规划与生成流程 [openkb/agent/query.py:30-70](openkb/agent/query.py)。 ## 知识维护操作 ### 文档移除（`openkb remove`） 社区反复提出"如何清理过时文档"的需求（Issue #41）。`_remove_doc_from_pages` 会扫描所有 `concepts/*.md`、`entities/*.md`，把 `sources:` 中包含该文档的页面： - 从 frontmatter `sources` 列表移除该来源； - 删除 `## Related Documents` 下对应的 `[[summaries/{doc_name}]]` 条目； - 没有任何剩余来源时，可选删除整页（`--keep-empty` 关闭此行为）[openkb/agent/compiler.py:240-330](openkb/agent/compiler.py)。 ### 重编译（`openkb recompile`） 不重新索引 PDF，直接走 Step 2–5 重新生成 summary 与 concept 页面；带 `--refresh-schema` 时同步刷新 `wiki/AGENTS.md`。需要注意：**手动编辑会被覆盖**，这一点是设计取舍 [README.md:30-50](README.md)。 ### 语义质量检查（`openkb lint`） `openkb/agent/linter.py` 定义了一个独立 Agent，工具集仅包含 `list_files` 与 `read_file`，授权它浏览 wiki 并产出结构化报告，覆盖：矛盾、缺失、陈旧、冗余、概念覆盖、实体覆盖六大类问题 [openkb/agent/linter.py:1-80](openkb/agent/linter.py)。这是 OpenKB 对"反馈修正机制"（Issue #28）的工程化回应——它不给终端用户提供 UI，但提供可被人工或上层代理消费的 Markdown 审计结果。 ### 查询与会话 `openkb/agent/query.py` 中的 `build_query_agent` 暴露三个 function tool：`read_file`、`get_page_content`、`get_image`，分别对应普通 markdown 读取、PageIndex 长文档按页读取、图片直接返回给多模态模型 [openkb/agent/query.py:10-60](openkb/agent/query.py)。`openkb/agent/skill_runner.py` 在此基础上克隆出 `skill::{name}` Agent，并授予 `write_file`（仅允许写入 `wiki/explorations/**` 与 `output/**`）以及 `read_output_or_skill_file`，实现"Skill Factory"的可执行后端 [openkb/agent/skill_runner.py:1-80](openkb/agent/skill_runner.py)。 ## 配置与社区关注点 配置入口在 `.openkb/config.yaml`，核心字段为 `model`、`language`、`pageindex_threshold` [README.md:260-310](README.md)。围绕 LiteLLM 配置，社区有两个高关注问题： - **超时参数（Issue #132）**：默认 10 分钟对 Ollama 等本地后端不足；可通过 `get_timeout` / `get_timeout_extra_args`（`openkb/config.py`）由环境变量或配置文件注入，编译管道在 `acompletion` 调用时已透传 `extra_args`。 - **不支持的参数（Issue #137）**：Ollama 等后端会拒绝部分 LiteLLM 参数，抛出 `UnsupportedParamsError`。建议在配置中显式声明轻量子集，或在调用前通过 `extra_headers` / `extra_args` 过滤。 - **对象存储（Issue #61）**：当前仅本地文件系统；要支持 S3/MinIO，需要在 `openkb/converter.py`、`openkb/indexer.py`、`openkb/url_ingest.py` 的输入输出路径上接入 `s3fs`，属于尚未实现的企业特性 [README.md:1-30](README.md)。 ## See Also - [README.md](README.md) — 项目总览与命令清单 - `openkb/agent/compiler.py` — 编译管道实现 - `openkb/agent/linter.py` — 语义健康检查 Agent - `openkb/agent/query.py` — 查询与多模态检索 Agent - `openkb/agent/skill_runner.py` — Skill Factory 执行后端 - `openkb/agent/tools.py` — Wiki 读取/页面解析工具集 --- ## 生成器层：查询、聊天、技能工厂与可视化 ### 相关页面 相关主题：[OpenKB 概览与系统架构](#page-1), [Wiki 编译管道与知识管理](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [openkb/agent/query.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/query.py) - [openkb/agent/chat.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/chat.py) - [openkb/agent/chat_session.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/chat_session.py) - [openkb/agent/tools.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/tools.py) - [openkb/agent/skill_runner.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/skill_runner.py) - [openkb/agent/linter.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/linter.py) - [openkb/skill/creator.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/skill/creator.py) - [openkb/skill/generator.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/skill/generator.py) - [README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md)
# 生成器层：查询、聊天、技能工厂与可视化 ## 概述 OpenKB 采用两层架构：底层"维基基础"把原始文档编译成交互链接的 Wiki 页面，上层"生成器层"再把已编译的知识转化为可分享、可重用的产物。两个层共享同一份 `wiki/` 目录作为读取基底，并通过 LiteLLM 兼容接口统一调用大语言模型。生成器层目前包含查询（`openkb query`）、聊天（`openkb chat`）、技能工厂（`openkb skill`）、可视化（`openkb visualize`）四个核心入口，并在 v0.4.1 中新增了 `openkb deck` 演示稿生成器。资料来源：[README.md](README.md) ```mermaid flowchart LR A[wiki/
summaries · concepts · entities] --> Q[query] A --> C[chat] A --> S[skill factory] A --> V[visualize] A --> D[deck
v0.4.1] Q -->|--save| E[wiki/explorations/] S -->|distill| SK[skills//] V --> G[output/visualize/
graph.html] D --> DK[output/decks/
index.html] ``` ## 查询与聊天 查询和聊天是日常使用频率最高的入口。`openkb query` 通过 `build_query_agent()` 在 `agents` 库的 `Agent` 上注册三个 `function_tool`：`read_file` 读取 Wiki 中任意 Markdown；`get_page_content` 按页码片段（如 `"3-5,7,10-12"`）从 PageIndex 树拉取长文档节点；`get_image` 把 Wiki 内的图片以 `ToolOutputImage` 直接喂给多模态模型。模型字符串以 `litellm//` 形式传入，底层由 LiteLLM 适配多家厂商。资料来源：[openkb/agent/query.py](openkb/agent/query.py) 聊天入口在查询代理之上叠加会话管理：`chat_session.py` 维护对话历史，配合 `--resume`、`--list`、`--delete` 三个 CLI 子命令切换、列举和删除会话；查询结果通过 `--save` 持久化到 `wiki/explorations/` 目录，供后续阅读与回溯。两者运行时均通过 `Runner.run()` 驱动，并对异步 LiteLLM 客户端在循环结束时调用 `_close_async_llm_clients()`，避免长任务中的 FD 泄漏。资料来源：[README.md](README.md)、[openkb/agent/compiler.py](openkb/agent/compiler.py) ## 技能工厂 技能工厂（Skill Factory）把整份 Wiki 提炼成可分发的 Agent 技能包，命令链为 `openkb skill new ""` → `validate` → `eval` → `history` / `rollback`。编译阶段由 `openkb/skill/creator.py` 与 `openkb/skill/generator.py` 协作生成技能主体；运行时由 `openkb/agent/skill_runner.py` 提供 `skill_runner` 代理：它以 `base.clone()` 复制查询代理的指令集与工具，再附加 `write_file`（仅允许 `wiki/explorations/**` 与 `output/**` 路径）与 `read_output_or_skill_file`（可读取 `output/`、`skills/` 下的既有产物），最后把技能主体 `body` 与用户意图 `intent` 拼接到系统提示末尾。资料来源：[openkb/agent/skill_runner.py](openkb/agent/skill_runner.py) 辅助子命令覆盖完整生命周期：`skill validate` 检查 YAML frontmatter、文件大小、wikilink 合法性与脚本；`skill eval` 评估质量；`skill history` 与 `skill rollback --to ` 提供版本回滚。资料来源：[README.md](README.md) ## 可视化、健康检查与社区反馈 `openkb visualize` 扫描 `wiki/` 中所有 Markdown 与 `[[wikilinks]]`，生成单文件离线 HTML 图谱 `output/visualize/graph.html`，同时提供 3D 力导向图、根节点思维导图与径向树三种视图。资料来源：[README.md](README.md) 健康检查由 `openkb/agent/linter.py` 中的 `build_lint_agent()` 提供：代理从 `index.md` 出发，依次阅读 summaries、concepts、entities，最终产出涵盖六类问题的结构化 Markdown 报告——矛盾（contradictions）、缺口（gaps）、过时（staleness）、冗余（redundancy）、概念覆盖度（concept coverage）和实体覆盖度（entity coverage）。该报告落地于 `wiki/reports/`，可作为迭代维基的诊断输入。资料来源：[openkb/agent/linter.py](openkb/agent/linter.py) 社区反馈指出了几条与生成器层直接相关的痛点：#28 建议在查询与 Wiki 页面增加用户反馈与纠错通道；#132 与 #137 报告在使用本地 Ollama 等后端时，会因 LiteLLM 默认 10 分钟超时或 `UnsupportedParamsError` 而失败。OpenKB 已通过 `openkb/config.py` 中的 `get_timeout` / `get_timeout_extra_args` 暴露超时参数，并支持 `extra_headers` 透传，叠加订阅型 OAuth 厂商免 Key 的提示跳过逻辑可缓解大多数兼容性问题。资料来源：[README.md](README.md)、社区议题 #28、#132、#137 ## 参见 - 知识编译流水线：[openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) - 工具与文件读写接口：[openkb/agent/tools.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/tools.py) - 项目总览与命令清单：[README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md) --- ## 配置、LLM 集成与生态集成 ### 相关页面 相关主题：[OpenKB 概览与系统架构](#page-1), [Wiki 编译管道与知识管理](#page-2), [生成器层：查询、聊天、技能工厂与可视化](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) - [openkb/agent/query.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/query.py) - [openkb/agent/linter.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/linter.py) - [openkb/agent/skill_runner.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/skill_runner.py) - [README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md) - [config.yaml.example](https://github.com/VectifyAI/OpenKB/blob/main/config.yaml.example) - [skills/openkb/SKILL.md](https://github.com/VectifyAI/OpenKB/blob/main/skills/openkb/SKILL.md)
# 配置、LLM 集成与生态集成 OpenKB 通过三层结构将"配置"与"生态"统一在同一入口：本地 YAML 配置文件负责运行参数、LiteLLM 负责屏蔽多供应商差异、`SKILL.md` 负责把编译好的知识库暴露给外部 Agent。本页聚焦这三层如何协同工作，并标注社区频繁反馈的痛点与现有缓解方式。 ## 配置系统结构 `openkb init` 会在知识库根目录生成 `.openkb/config.yaml`，所有运行期可调参数都集中在此。基础字段包含三组： - **输出控制**：`language` 控制 Wiki 文本语言（默认 `en`），`pageindex_threshold` 决定 PDF 何时切换为长文档树索引（默认 20 页）。 - **模型选择**：`model` 采用 LiteLLM 的 `provider/model` 命名规范，OpenAI 系列可省略前缀，例如 `gpt-5.4`、`anthropic/claude-sonnet-4-6`、`gemini/gemini-3.1-pro-preview`。 - **实体类型**：`entity_types` 是可选 YAML 列表；省略时使用 [openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) 中声明的默认值 `person / organization / place / product / work / event / other`（参见 `DEFAULT_ENTITY_TYPES`）。 下表汇总主要配置项及其在源码中的读取位置： | 字段 | 默认值 | 作用 | 读取位置 | |---|---|---|---| | `language` | `en` | Wiki 输出语言 | [openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py), [openkb/agent/linter.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/linter.py) | | `model` | 必填 | LiteLLM 模型标识 | [openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) | | `pageindex_threshold` | `20` | 触发 PageIndex 的页数阈值 | [README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md) | | `entity_types` | 默认七类 | 实体页分类 | [openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) | | `extra_headers` | 空 | 透传至 LiteLLM 的自定义 HTTP 头 | [openkb/agent/query.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/query.py), [openkb/agent/linter.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/linter.py) | ## LLM 集成与请求通道 所有 Agent（编译、查询、Lint、技能执行）都通过 LiteLLM 统一调用模型，并由 `ModelSettings` 注入通用参数： ```python model_settings=ModelSettings( extra_headers=get_extra_headers() or None, extra_args=get_timeout_extra_args(), ) ``` 资料来源：[openkb/agent/linter.py:18-58]()、[openkb/agent/query.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/query.py)。 `extra_headers` 用于供应商需要自定义头信息的场景，例如 GitHub Copilot 的 IDE 鉴权头（`Editor-Version`、`Copilot-Integration-Id`）。订阅型供应商（`chatgpt/*`、`github_copilot/*`）走 OAuth 设备流，OpenKB 会在缺省 API Key 时跳过告警。资料来源：[README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md)。 在编译长文档时，[openkb/agent/compiler.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) 通过 `_cached_text()` 在文档末尾插入 Anthropic 风格的 `cache_control: ephemeral` 标记。LiteLLM 会把标记透传给 Anthropic / OpenRouter→Anthropic；对于忽略该字段的供应商，列表式 content 载荷仍可作为合法的 OpenAI 兼容消息体，从而在多供应商间保持一致。 ## 生态集成：SKILL.md 与外部 Agent OpenKB 把编译完成的 Wiki 暴露为只读技能，外部 Agent 加载后即可阅读与探索，无需任何运行时依赖。`skills/openkb/SKILL.md` 描述了完整的指令集，三种主流 CLI 的安装方式如下： ```mermaid flowchart LR A[OpenKB 仓库] --> B[skills/openkb/SKILL.md] B --> C[Claude Code
/plugin install] B --> D[OpenAI Codex CLI
ln -s] B --> E[Gemini CLI
gemini skills install] ``` - **Claude Code**：通过官方市场 `VectifyAI/OpenKB` 一键安装。 - **OpenAI Codex CLI**：尚无 marketplace 命令，需手动克隆并软链至 `~/.agents/skills/openkb`。 - **Gemini CLI**：执行 `gemini skills install --path skills/openkb --consent`。 技能默认只读，仅在你明确授权时才执行 `add` / `remove` / `lint --fix` 等写操作。资料来源：[README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md)、[skills/openkb/SKILL.md](https://github.com/VectifyAI/OpenKB/blob/main/skills/openkb/SKILL.md)。 技能运行时由 [openkb/agent/skill_runner.py](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/skill_runner.py) 负责，它在基础查询 Agent 上克隆出一个 `skill::` 实例，注入 `write_file` / `read_output_or_skill_file` 工具，并把写入路径限制在 `wiki/explorations/**` 与 `output/**` 两棵子树，避免越权。 ## 社区反馈与已知边界 | 议题 | 现状 | 相关代码 | |---|---|---| | LiteLLM 超时（默认 600s）对 Ollama 等本地模型不足 | 通过 `extra_args` 透传超时参数；社区建议将超时写入 `.openkb/config.yaml` | [openkb/agent/linter.py:58](), [#132](), [#137]() | | 不支持 S3 / MinIO 等对象存储 | 仅本地文件系统；需手动下载/上传绕行 | [#61]() | | 文档版本更新需移除旧条目 | `openkb remove ` 支持清理 | [README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md), [#41]() | | 缺少反馈与修正闭环 | `openkb feedback` 仅打开预填好的 GitHub Issue | [README.md](https://github.com/VectifyAI/OpenKB/blob/main/README.md), [#28]() | 整体来看，OpenKB 的"配置 + LLM 抽象 + 生态技能"三层既覆盖了从本地 Ollama 到云端 Claude 的多模型场景，也通过 `SKILL.md` 把知识库无缝接入主流 Agent CLI。 ## See Also - [openkb 知识编译流水线](https://github.com/VectifyAI/OpenKB/blob/main/openkb/agent/compiler.py) - [OpenKB Wiki 主页](https://github.com/VectifyAI/OpenKB) --- --- ## Doramagic 踩坑日志 项目：VectifyAI/OpenKB 摘要：发现 11 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature] Support passing timeout parameter to LiteLLM。 ## 1. 安装坑 · 来源证据：[Feature] Support passing timeout parameter to LiteLLM - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Support passing timeout parameter to LiteLLM - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/VectifyAI/OpenKB/issues/132 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 安装坑 · 来源证据：uv tool install openkb fails - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：uv tool install openkb fails - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/VectifyAI/OpenKB/issues/130 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 配置坑 · 来源证据：[Feature] Share PDF page extraction across short PDFs and long PDF page JSON - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature] Share PDF page extraction across short PDFs and long PDF page JSON - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/VectifyAI/OpenKB/issues/135 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 安装坑 · 来源证据：Suggestion: replacing the default PDF parser with a more capable alternative - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Suggestion: replacing the default PDF parser with a more capable alternative - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/VectifyAI/OpenKB/issues/77 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 配置坑 · 来源证据：[Feature] Plans to support litellm config in .openkb/config.yaml? (Encountered UnsupportedParamsError with Ollama) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature] Plans to support litellm config in .openkb/config.yaml? (Encountered UnsupportedParamsError with Ollama) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/VectifyAI/OpenKB/issues/137 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/VectifyAI/OpenKB | README/documentation is current enough for a first validation pass. ## 7. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/VectifyAI/OpenKB | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/VectifyAI/OpenKB | no_demo; severity=medium ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/VectifyAI/OpenKB | no_demo; severity=medium ## 10. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/VectifyAI/OpenKB | issue_or_pr_quality=unknown ## 11. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/VectifyAI/OpenKB | release_recency=unknown