内容
<div align="center">
<img src="docs/readme/logo.png" width="128" alt="PieKBS"><br>
<h1>PieKBS</h1>
<p>适用于代理的本地知识搜索引擎 - 将原始文档提炼成结构化的Markdown wiki，通过MCP进行搜索和阅读</p>
<p>
<a href="docs/readme/README.zh-CN.md">简体中文</a> |
<a href="docs/readme/README.zh-TW.md">繁體中文</a> |
<a href="docs/readme/README.ru.md">Русский</a> |
<a href="docs/readme/README.de.md">Deutsch</a> |
<a href="docs/readme/README.fr.md">Français</a> |
<a href="docs/readme/README.es.md">Español</a> |
<a href="docs/readme/README.ko.md">한국어</a>
</p>
<p>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
<a href="https://github.com/pieteams/piekbs/releases"><img src="https://img.shields.io/github/v/release/pieteams/piekbs" alt="Release"></a>
<img src="https://img.shields.io/badge/go-1.25+-00ADD8.svg" alt="Go Version">
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue" alt="Platform">
</p>
</div>
PieKBS是一款适用于代理的本地知识搜索引擎。它将原始文档提炼成结构化的、可审查的Markdown wiki，然后通过MCP暴露两个工具 - `kb_search`和`kb_page` - 允许代理按自己的节奏搜索和深入阅读。
## 设计理念
PieKBS围绕一个观察结果构建：**代理使用外部知识工具的方式与人类使用搜索引擎的方式相同** - 他们从不同的角度发出多个查询，跟随链接，并综合自己的结论。他们不想要预包装的答案；他们想要原始材料来形成自己的答案。
这意味着PieKBS的工作不是回答问题。而是确保当代理搜索某些内容时，他们能找到正确的文件 - 并能完整阅读。
```text
piekbs-kb/
raw/ 知识的源头 - 任意格式的原始材料。
将文件放在此处；观察者会自动提炼它们。
wiki/ 结构化的Markdown知识层（LLM维护）。
source-notes/ 一个提炼的笔记，每个原始文档一个。全文搜索目标。
concepts/ 跨文档的综合：概念和方法论。
comparisons/ 跨文档的综合：并排比较。
decisions/ 跨文档的综合：技术决策。
_draft/ 综合页面，少于2个来源（尚未索引）。
schema/ 知识库本地创作规则和页面模板。
编辑这些以自定义提炼的页面格式。
index/ 生成的工件（SQLite全文搜索索引，查询日志）。
自动管理 - 请勿手动编辑。
```
## 代理如何使用PieKBS
代理通过三个MCP工具与PieKBS交互：
**`kb_search(query, limit?)`** - 使用关键词或短语搜索。每次调用返回最多5个源笔记和3个概念/比较/决策页面。每个结果都包含一个`related`字段，列出链接文档以便于导航。使用多个搜索和不同的关键词来从多个角度覆盖一个主题。
**`kb_page(ids, full?)`** - 通过ID获取一个或多个页面的完整内容（来自`kb_search`结果）。最多传递5个ID来扫描多个文档，或传递`full=true`和单个ID来获取完整的未截断文本。
**`kb_add(filename, content, source_url?)`** - 将文本文档添加到知识库。写入内容到`raw/<filename>`并触发增量索引。提炼在后台异步运行。使用`converted/`前缀表示代理提取的PDF/Word/Excel/EPUB内容。
推荐的代理工作流程：
```text
kb_search("keyword A") → 发现相关文档
kb_search("keyword B") → 覆盖不同的角度
kb_page(["id1", "id2", "id3"]) → 深入阅读最相关的文档
代理从中找到的内容中综合自己的答案
```
代理被期望迭代搜索，跟随`related`链接，跨来源验证并形成自己的结论。PieKBS不生成答案。
## PieKBS vs RAG
传统的RAG检索上下文并将其交给LLM来回答。PieKBS将原始材料交给代理，让代理进行推理。
```text
RAG: 用户问题 → 检索上下文 → LLM答案
PieKBS: 代理搜索 → 代理阅读 → 代理综合
```
| | RAG | PieKBS |
|---|---|---|
| 知识形式 | 隐含（向量或块） | 显式（Markdown，可审计） |
| 代理角色 | 被动接收上下文 | 主动搜索者和阅读者 |
| 答案来源 | 系统生成 | 代理综合 |
| 可审计 | 否 | 是 - git diff，lint，冲突链接 |
| 多步推理 | 取决于LLM | 通过`related`链接的图扩展 |
| 嵌入 | 需要 | 不需要（纯全文搜索） |
PieKBS包与[OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)兼容。
## 知识管道
原始文档通过提炼管道流转，然后代理才能搜索它们：
**步骤1 - 提炼（自动）**
将任意Markdown文件放入`raw/`。`piekbs serve`观察者自动运行提炼 + 索引。LLM从结构化的源笔记中提取到`wiki/source-notes/`，包括：
- 带有内联别名和跨语言等价的`key_claims`（ALIAS规则） - 确保全文搜索匹配所有查询变体
- `【entity|type】`格式的命名实体注释
- `related_to`，`supports`，`contradicts`链接 - 为搜索结果中的`related`字段提供支持
- `authority`（1-5）和`doc_type`元数据
**步骤2 - 综合（按需）
```bash
piekbs synthesize --topic "RAG"
```
从源笔记中生成概念/比较/决策页面，当一个主题上积累足够的来源时。少于2个来源引用的页面进入`wiki/<type>/_draft/`，在添加更多来源之前不会被索引。
**步骤3 - 搜索**
代理通过MCP使用`kb_search` + `kb_page`。搜索是纯全文搜索（SQLite FTS5，BM25评分）。不需要向量模型。
## 安装
下载最新版本：
| 平台 | 文件 |
|---|---|
| macOS Apple Silicon（ARM64） | `PieKBS-<version>-macos-arm64.dmg` |
| Linux x86_64 | `piekbs-<version>-linux-amd64.tar.gz` |
| Linux ARM64 | `piekbs-<version>-linux-arm64.tar.gz` |
| Windows x86_64 | `piekbs-<version>-windows-amd64.zip` |
> **macOS Intel（x86_64）：** 无预构建版本。GitHub Actions于2025年4月停止了Intel macOS运行器。在Intel Mac上从源代码构建：`CGO_ENABLED=1 go build -tags fts5 -o piekbs ./cmd/piekbs/`
**macOS:** 打开DMG并将PieKBS拖到应用程序。应用程序以菜单栏图标运行。
**Linux：**
```bash
tar -xzf piekbs-<version>-linux-amd64.tar.gz -C /path/to/install/
sudo ln -sf /path/to/install/piekbs /usr/local/bin/piekbs
```
**Windows:** 解压zip并运行`piekbs.exe serve`（或`piekbs.exe stdio`用于MCP）。将目录添加到`PATH`以便使用。无需CGO - 纯Go二进制文件。
**HarmonyOS PC（社区，实验性）：** PieKBS未正式发布HarmonyOS PC。但是，由于核心二进制文件不需要CGO（纯Go + SQLite），因此可以使用社区[Harmonybrew](https://harmonybrew.dev)包管理器在HarmonyOS上本地构建。参见[ohos_go_cgo](https://github.com/ohos-go/ohos_go_cgo)以获取在HarmonyOS PC上设置Go + CGO的指南。
```bash
# 在HarmonyOS PC上（安装Go后使用Harmonybrew）
CGO_ENABLED=0 go build -tags fts5 -o piekbs ./cmd/piekbs/
piekbs serve
```
## 从源代码构建
需要Go 1.25+。无需CGO。
```bash
# macOS / Linux
go build -tags fts5 -o piekbs ./cmd/piekbs/
# Windows
go build -tags fts5 -o piekbs.exe ./cmd/piekbs/
```
或使用多平台构建脚本：
```bash
./scripts/build.sh [version] [target...]
```
| 目标 | 输出 | 平台 |
|---|---|---|
| `darwin-arm64` | `dist/PieKBS-<version>-macos-arm64.dmg` | macOS Apple Silicon |
| `linux-amd64` | `dist/piekbs-<version>-linux-amd64.tar.gz` | Linux x86_64 |
| `linux-arm64` | `dist/piekbs-<version>-linux-arm64.tar.gz` | Linux ARM64 |
| `windows-amd64` | `dist/piekbs-<version>-windows-amd64.zip` | Windows x86_64 |
## 仓库结构
```text
piekbs/
cmd/piekbs/ # 主入口
internal/
kb/ # 全文索引，搜索，图扩展，页面获取
mcp/ # MCP服务器（stdio + HTTP）
watcher/ # 文件观察者，用于自动提炼 + 索引
distill/ # LLM提炼管道
synthesize/ # 概念/比较/决策页面生成
convert/ # 原始文件转换
service/ # 操作系统服务管理器（launchd / systemd）
webui/ # 网页界面
tray/ # macOS系统托盘（仅darwin）
config/ # 知识库配置（config.yaml）
scripts/
build.sh # 多平台构建脚本
```
## 模式和模板
`piekbs init`将知识库的`schema/`目录填充为捆绑的创作规则和页面模板：
- `schema/templates/`：Markdown模板，用于源笔记/概念/比较/决策页面。
- `schema/references/`：创作规则 - 页面类型，引用规则，冲突规则，目录结构。
提炼/综合提示读取这些模板，因此编辑它们可以自定义每个知识库的wiki格式。
## 快速开始
```bash
export PIEKBS_KB=/path/to/your-kb
piekbs init # 搭建知识库目录并复制模式/模板
piekbs serve # 启动服务器：MCP + 网页界面 + 文件观察者
piekbs index # 构建/更新全文索引
piekbs status # 索引统计
piekbs lint # 健康检查wiki页面
```
## 命令参考
所有命令都接受全局`--kb <path>`标志（默认为`$PIEKBS_KB`，然后是`~/piekbs-kb`）。
| 命令 | 描述 |
|---|---|
| `piekbs init [--force]` | 搭建知识库目录并复制捆绑的模式/模板。 |
| `piekbs serve` | 启动长时间运行的服务器：HTTP MCP（`/mcp`）+ 网页界面 + 文件观察者。 |
| `piekbs index` | 从`wiki/`和`raw/` markdown构建/更新全文索引。 |
| `piekbs search <query>` | 全文关键词搜索；打印带有路径和摘要的排名结果。 |
| `piekbs synthesize [--topic X] [--full]` | 从源笔记中生成概念/比较/决策页面。 |
| `piekbs synthesize --gaps --topic X` | 某个主题的知识差距分析。 |
| `piekbs import-lark <URL>` | 将Lark/Feishu Wiki页面及其嵌入的表格导入`raw/lark/`。 |
| `piekbs lint` | 健康检查wiki页面：缺少前置字段，损坏的源链接。 |
| `piekbs status` | 打印索引统计（文档数量，索引大小）。 |
| `piekbs service <install\|uninstall\|start\|stop\|status\|logs>` | 管理操作系统服务（launchd / systemd）。 |
**LLM配置**（知识库根目录下的`config.yaml`，`distill`部分）对于`distill`和`synthesize`是必需的。
## MCP服务器
PieKBS通过MCP协议公开知识库工具。
**可用工具：** `kb_search`，`kb_page`，`kb_add`
管理员操作（`status`，`reindex`，`lint`）可通过网页界面或CLI（`piekbs status`，`piekbs index`，`piekbs lint`）访问。
---
### 场景1：本地多代理共享
HTTP模式推荐：一个PieKBS进程由所有代理共享 - Claude Code，Cursor，VS Code（Copilot），Windsurf，Trae，Codex，Hermes，OpenClaw等。
**步骤1：启动PieKBS**
```bash
export PIEKBS_KB=/path/to/piekbs-kb
piekbs serve
```
> 在macOS上，双击PieKBS.app以启动为菜单栏图标。
**步骤2：在每个代理中配置HTTP MCP**
添加到`~/.claude.json`下的`mcpServers`：
```json
{
"mcpServers": {
"piekbs": {
"type": "http",
"url": "http://127.0.0.1:8766/mcp",
"headers": {
"x-api-key": "${PIEKBS_API_KEY}"
}
}
}
}
```
`x-api-key`对应于`config.yaml`中的`server.api_key`。如果未设置api_key，请省略`headers`。
---
### 场景2：托管代理环境
在托管环境中（Hermes，OpenClaw等），在持久卷上安装PieKBS，并通过**stdio**调用 - PieKBS作为代理主进程的子进程启动，观察者自动在后台运行。
示例（NAS-mounted OpenClaw/Hermes，安装点`/root/.openclaw`）：
**1. 安装到持久卷（一次性）：**
```bash
tar -xzf piekbs-linux-amd64.tar.gz -C /root/.openclaw/piekbs/
chmod +x /root/.openclaw/piekbs/piekbs
```
**2. 安装markitdown（推荐）：**
markitdown启用PDF，Word，Excel，PPT和HTML文件转换为Markdown之前进行提炼。 如果没有它，只支持`.md`和`.txt`文件进行提炼；二进制文件仅按文件名索引。
```bash
pip install markitdown
# verify
markitdown --version
```
> 在OpenClaw/Hermes上验证工作（路径：`/root/.openclaw/workspace/bin/markitdown`）。 将`workspace/bin`添加到PATH或在环境中设置完整路径。
如果markitdown不可用，代理可以自己提取文本（使用LLM视觉或其他工具），并直接写入 `$PIEKBS_KB/raw/converted/<slug>.md` - 观察者自动拾取。
**3. MCP配置：
Hermes（代理配置中的`mcp_servers`）：
```yaml
mcp_servers:
piekbs:
command: /root/.openclaw/piekbs/piekbs
args: [stdio]
env:
PIEKBS_KB: /root/.openclaw/piekbs-kb
PATH: /root/.openclaw/workspace/bin:/usr/local/bin:/usr/bin:/bin`
```
知识库目录将自动在首次启动时创建。不需要手动`init`。
**4. 将内容添加到知识库：
具有`write_file`访问权限的代理可以直接写入知识库 - 观察者检测到更改并自动触发索引和提炼。
| 内容类型 | 写到 |
|---|---|
| 文章，笔记，参考文献（Markdown/文本） | `$PIEKBS_KB/raw/<your-category>/<slug>.md` |
| 代理转换的PDF / Word / Excel / EPUB内容 | `$PIEKBS_KB/raw/converted/<slug>.md` |
`raw/converted/`中的文件被视为已转换，直接进入提炼，跳过markitdown步骤。所有其他`raw/`下的路径都通过完整管道处理（转换 → 索引 → 提炼）。
在`raw/`下组织子目录以适合您的内容结构 - PieKBS不强制执行固定结构。
## 系统服务（可选）
`piekbs serve`包含一个内置的观察者，自动监控知识库目录，触发提炼并重建索引。无需额外设置。
要使PieKBS **在启动时启动并在后台运行**，请将其安装为系统服务（macOS launchd / Linux systemd）：
```bash
piekbs service install --kb /path/to/your-kb
piekbs service status
piekbs service uninstall
```
日志： `{PIEKBS_KB}/index/watcher.log`
