使用说明
代理知识库
用于跨项目管理markdown知识库的CLI工具和MCP服务器。将项目上下文（CLAUDE.md/AGENT.md）和共享文档（API文档、规范、工作流）外部化到中心版本目录中，然后通过MCP将其公开给AI编码代理。
支持 克劳德代码, OpenAI Codex，以及 开源代码.
为什么
- 上下文文件分散 跨仓库，无法在项目之间共享文档
- API文档重复 -将相同的API文档复制到3个以上的repo中
- 无版本历史记录 -更新项目上下文时，旧版本将消失
- 大型参考文档浪费上下文 -9000行API文档不应加载到每个会话中
kb 通过将知识集中到 ~/knowledge-base/ 与：
- 替换存储库中CLAUDE.md文件的每个项目上下文
- 多个项目引用的共享文档，没有重复
- 自动对所有项目可用的全局共享文档
- 内联模式，将共享文档内容直接嵌入context.md（在会话开始时加载，无需MCP调用）
- 每次更改时的Git版本控制（自动提交）
- MCP服务器，以便代理可以按需搜索、读取和写入文档
- TUI浏览器，用于交互式导航和为知识库分配参考
设置
1.安装
go install github.com/leona/kb@latest
或者从以下网址下载预构建的二进制文件 最新版本:
curl -Lo kb https://github.com/leona/kb/releases/latest/download/kb-linux-amd64
chmod +x kb
sudo mv kb /usr/local/bin/kb
替换 kb-linux-amd64 使用您的平台： kb-darwin-arm64 （macOS苹果硅）， kb-darwin-amd64 （macOS英特尔）， kb-windows-amd64.exe.
2.初始化知识库
kb init
这创造了 ~/knowledge-base/ 与：
kb.yml--配置文件shared/--共享文档目录projects/--每个项目知识目录.git/--版本历史记录（自动管理）
要使用其他目录，请执行以下操作：
kb init --dir ~/my-knowledge-base
然后设置 KB_ROOT 在shell配置中：
export KB_ROOT="$HOME/my-knowledge-base"
3.为项目配置MCP
在项目目录中：
kb setup
或者指定项目名称：
kb setup my-project
此功能会自动检测已安装的代理，并：
- 在项目目录中创建MCP配置(
.mcp.json对于克劳德代码，.codex/config.toml对于Codex，opencode.json对于OpenCode） - 写
@importCLAUDE.md（以及AGENTS.md/AGENT.md（如果存在））中指向KB上下文的指针
显示要写的内容并要求确认(-y 跳过）。
安装后重新启动代理以连接到MCP服务器。
Claude Code对此进行了扩展 @import 自动加载——完整上下文将像以前一样加载。当Claude修改上下文时，它编辑的是KB文件（因为指令头），而不是仓库的Claude.md。
浏览
用于浏览知识库的交互式TUI：
kb
- 在项目外部启动→ 在双窗格视图中显示所有项目和共享文档
- 在注册项目内启动→ 跳转到该项目的详细视图
- 使用箭头键导航或
h/l,tab切换窗格，/要筛选，请按Enter键打开，按Esc键返回 - 用于切换引用/内联模式（项目详细信息）或循环全局状态（主视图）的空间
q或Ctrl+C退出
代理使用
代理通过MCP使用知识库工具按需搜索、阅读和创建文档。
搜索知识库：
正在阅读共享的API文档：
创建新的共享文档：
版本控制
每个CLI写入操作都会自动提交到KB的git仓库，并显示一条描述性消息：
$ kb log
a1b2c3d 2026-03-04 02:26 ref: link my-project → rest-api-docs
e4f5a6b 2026-03-04 02:26 shared: add rest-api-docs (1 file(s), 500 lines)
c7d8e9f 2026-03-04 02:18 import: my-project from ~/repos/my-project/CLAUDE.md
0a6b0f2 2026-03-04 02:07 init: knowledge base
自动推送
kb init 提供设置git远程并启用自动推送。启用时(auto_push: true 在 kb.yml)，每次提交都会在后台自动推送到远程。
MCP服务器工具
配置后，代理将获得16个工具：
| 工具 | 说明 |
|---|---|
kb_context |
读取项目context.md（相当于CLAUDE.md）。自动检测cwd中的项目。 |
kb_list |
列出项目文档、链接的共享文档、全局变量和其他可用的共享文档。 |
kb_read |
按路径读取特定文档。支持 offset/limit 对于大文件。 |
kb_search |
跨KB的全文搜索。按项目、共享文档或全部范围。 |
kb_draft |
编写前预览内容--返回格式化的预览而不保留。 |
kb_write |
在以下位置创建或更新文件 shared/ 或 projects/。自动提交。 |
kb_delete |
删除共享文档（清除引用/全局变量）或特定文件。 |
kb_log |
显示版本历史记录。适用于项目或共享文档。 |
kb_diff |
显示知识库中未提交的更改。 |
kb_show |
在特定提交时读取文件内容。 |
kb_revert |
将文件还原为特定提交。自动提交更改。 |
kb_ref_add |
将共享文档链接到项目。支持 inline 在context.md中嵌入内容 |
kb_ref_remove |
从项目中取消共享文档的链接。 |
kb_global_add |
将共享文档标记为对所有项目全局可用。支持 inline. |
kb_global_remove |
从全局中删除共享文档。 |
kb_commit |
提交待处理的更改。突变后使用 no_commit=true. |
这 kb_draft → kb_write 工作流确保代理在持久化更改之前预览更改。
代理可以创建共享文档，链接它们，并完全通过MCP管理全局变量——不需要CLI。
知识库结构
~/knowledge-base/
.git/ # Auto-managed version history
kb.yml # Config + project path mappings + globals
shared/ # Cross-project shared docs
rest-api-docs/
api-reference.md # The actual documentation
meta.yml # Optional: title, description, source, tags
design-patterns/
reactivity.md
projects/ # Per-project knowledge
my-project/
context.md # Project context (the "real" CLAUDE.md)
refs.yml # Links to shared docs: [rest-api-docs]
notes/ # Additional project-specific docs
architecture.md
配置文件
kb.yml --带有项目路径映射和全局变量的全局配置：
version: 1
editor: hx # Fallback: $EDITOR, then vi
globals: # Shared docs available to all projects (referenced)
- style-guide
inline_globals: # Shared docs embedded into all projects' context.md
- coding-standards
projects:
my-project: ~/repos/my-project
other-project: ~/documents/other-project
work-api: /opt/work/api-server
项目可以在磁盘上的任何地方——它们不需要在公共目录下。
refs.yml --每个项目共享文档引用：
refs:
- rest-api-docs
- design-patterns
inline: # Embedded directly into context.md
- commit-conventions
meta.yml --可选共享文档元数据：
title: REST API Reference
description: API endpoints, authentication, and usage examples
source: https://docs.example.com/api
tags: [api, rest, reference]
CLAUDE.md集成的工作原理
之前 kb
~/repos/my-project/CLAUDE.md ← 300 lines of context, edited in-repo
~/repos/other-project/CLAUDE.md ← Duplicate API docs, diverges over time
之后 kb
~/repos/my-project/CLAUDE.md ← One line: @~/knowledge-base/projects/my-project/context.md
~/knowledge-base/
projects/my-project/context.md ← The actual 300 lines, versioned, with edit directive
shared/rest-api-docs/ ← API docs, shared by both projects
回购的CLAUDE.md变为单个 @import 指针。Claude Code在会话开始时对此进行了扩展，并看到了完整的内容。知识库 context.md 开始于：
<!-- KB managed: ~/knowledge-base/projects/my-project/context.md -->
<!-- Always edit THIS file for project context. Do NOT edit the repo's CLAUDE.md. -->
此指令确保代理编辑KB文件（版本化、集中式），而不是仓库的指针文件。
上下文备份
当context.md被更新时， kb 复制到 .kb-context.md 在项目目录中。这会在代码旁边保留项目上下文的版本副本。
参考与内联
共享文档可以通过两种方式链接：
- 参考 （默认）--列在
<!-- KB:REFS -->以行数作为摘要进行评论。代理通过以下方式按需获取内容kb_read/kb_search。最适合大型参考文档。 - 内联 (
--inline)--直接嵌入的内容context.md里面<!-- KB:INLINE -->块，在会话开始时加载。最适合应该始终可用的小文档（提交约定、样式指南）。
命令行命令
| 命令 | 描述 |
|---|---|
kb |
启动TUI浏览器（默认命令） |
kb init [--dir PATH] |
初始化新的知识库 |
kb setup [PROJECT] [-y] |
配置MCP+ @import 项目指针 |
kb project init <NAME> --path <DIR> |
在知识库中创建新项目 |
kb project import <NAME> --from <DIR> |
将现有的CLAUDE.md/AGENTS.md导入知识库 |
kb project list |
列出所有项目 |
kb project show <NAME> |
显示项目详细信息和上下文 |
kb shared add <SLUG> <FILES...> |
将共享文档添加到知识库 |
kb shared list |
列出共享文档的使用情况和行数 |
kb ref add <PROJECT> <SLUG> [--inline] |
将共享文档链接到项目 |
kb ref remove <PROJECT> <SLUG> |
从项目中取消共享文档的链接 |
kb global add <SLUG> [--inline] |
为所有项目提供共享文档 |
kb global remove <SLUG> |
从全局中删除共享文档 |
kb global list |
列出全局共享文档 |
kb search <QUERY> [--project NAME] |
跨KB的全文搜索 |
kb edit <PROJECT> |
在中打开项目context.md $EDITOR |
kb detect |
从工作目录中自动检测当前项目 |
kb log [SCOPE] |
显示版本历史记录 |
kb diff [SCOPE] |
显示未提交的更改 |
kb revert <REF> <PATH> |
将文件还原到以前的版本 |
kb commit |
手动提交待处理的KB更改 |
kb graph |
显示项目和共享文档的ASCII参考图 |
kb version |
打印版本信息 |
kb mcp |
启动MCP服务器（stdio传输） |
