内容
<div align="center">
<img src="docs/readme/logo.png" width="128" alt="WikiLoop"><br>
<h1>WikiLoop</h1>
<p>Agent-native LLM Wiki (Karpathy-style) RAG: distill raw docs → structured Markdown wiki → hybrid search via MCP</p>
<p><a href="docs/readme/README.zh-CN.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/jasen215/wikiloop/releases"><img src="https://img.shields.io/github/v/release/jasen215/wikiloop" 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-blue" alt="Platform">
</p>
</div>
WikiLoop 是一个本地优先的 LLM Wiki 知识库，适用于代理。它旨在帮助代理和人类维护来源于本地原始资料的可引用的、审查的知识，以 Markdown 为基础。
## 核心思想
```text
wikiloop-kb/
raw/ 真相来源；原始资料和转换后的近全文本衍生品
wiki/ 由代理和人类维护的结构化 Markdown 知识
schema/ 知识库本地规则、模板、引用规则和工作流程
index/ 生成的搜索/索引产物
```
WikiLoop 不是一个长期记忆系统。用户偏好、项目习惯和跨会话记忆应保留在外部记忆提供者中。WikiLoop 管理外部知识源和从中派生的 Wiki 层。
## WikiLoop 与 RAG
传统的 RAG 直接将原始文档导入向量存储——知识是隐含的，隐藏在嵌入中，且不可供人类审查。WikiLoop 增加了一个明确的蒸馏步骤：
```text
RAG: 原始文档 → 嵌入 → 向量存储 → LLM 检索
WikiLoop: 原始文档 → Wiki（人类/代理）→ FTS + 图 + 嵌入（可选）
```
| | RAG | WikiLoop |
|---|---|---|
| 知识形式 | 隐含（向量） | 显式（Markdown） |
| 可审计 | 否 | 是 - git diff, lint, 冲突链接 |
| 冷启动成本 | 低 | 较高（需要 Wiki 创作） |
| 知识衰减 | 难以检测 | 易于检测 - lint + 引用 |
| 多步推理 | 取决于 LLM | 图扩展（显式） |
| 嵌入 | 需要 | 可选增强 |
权衡：WikiLoop 需要蒸馏步骤（人类或代理），但产生可控、可追溯和增量维护的知识。
WikiLoop Wiki 包与 [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) 兼容。
## 安装
为您的平台下载最新的发行版：
| 平台 | 文件 |
|---|---|
| macOS Apple Silicon | `WikiLoop-<version>-darwin-arm64.dmg` |
| macOS Intel | `WikiLoop-<version>-darwin-amd64.dmg` |
| Linux x86_64 | `wikiloop-<version>-linux-amd64.tar.gz` |
| Linux ARM64 | `wikiloop-<version>-linux-arm64.tar.gz` |
| Windows x86_64 | `wikiloop-<version>-windows-amd64.zip` |
> **Windows 注意：** Windows 版本完全支持 FTS 关键字搜索。向量搜索需要嵌入模型 - 从 [models-v1](https://github.com/jasen215/wikiloop/releases/tag/models-v1) 下载并解压到 `<WIKILOOP_KB>/models/`。`embed` 子命令在 Windows 上运行。
**macOS:** 打开 DMG 并将 WikiLoop 拖到应用程序。应用程序作为菜单栏图标运行。
**Linux:**
```bash
tar -xzf wikiloop-<version>-linux-amd64.tar.gz -C /path/to/install/
sudo ln -sf /path/to/install/wikiloop /usr/local/bin/wikiloop
```
### 下载嵌入模型
向量搜索需要 `bge-small-zh` ONNX 模型（53 MB），需要单独下载：
**[⬇ 下载 bge-small-zh.tar.gz](https://github.com/jasen215/wikiloop/releases/tag/models-v1)**
```bash
# 解压到您的 KB 的模型目录
tar -xzf bge-small-zh.tar.gz -C $WIKILOOP_KB/models/
```
解压后： `$WIKILOOP_KB/models/bge-small-zh/model.onnx` 应存在。
FTS 搜索无需模型即可工作；向量搜索需要它。
## 从源代码构建
需要启用 CGO 的 Go 1.25+。
```bash
./scripts/build.sh [version] [target...]
```
| 目标 | 输出 | 平台 |
|---|---|---|
| `darwin-arm64` | `dist/WikiLoop-<version>-darwin-arm64.dmg` | macOS Apple Silicon |
| `linux-amd64` | `dist/wikiloop-<version>-linux-amd64.tar.gz` | Linux x86_64 |
| `linux-arm64` | `dist/wikiloop-<version>-linux-arm64.tar.gz` | Linux ARM64 |
```bash
./scripts/build.sh 1.2.0 # 所有平台
./scripts/build.sh 1.2.0 linux-amd64 # 单个目标
```
**依赖：**
- Linux 目标： `brew install FiloSottile/musl-cross/musl-cross`
- macOS DMG： `brew install create-dmg` （可选，跳过如果不存在）
每个 tar.gz 仅包含二进制文件。DMG 是一个可拖拽安装的 macOS 应用程序包，支持系统托盘。嵌入模型单独下载（见上文）。
## 仓库结构
```text
wikiloop/
cmd/wikiloop/ # 主入口
internal/
kb/ # 索引、FTS、向量搜索
mcp/ # MCP 服务器（stdio + HTTP）
embed/ # ONNX 嵌入（bge-small-zh）
watcher/ # 文件监视器，用于自动重新索引
distill/ # LLM 蒸馏管道
convert/ # 原始文件转换
service/ # 操作系统服务管理器（launchd / systemd）
webui/ # Web UI
tray/ # macOS 系统托盘（仅限 darwin）
config/ # 知识库配置（config.yaml）
scripts/
build.sh # 多平台构建脚本
Info.plist # macOS 应用程序包元数据
wikiloop.icns # 应用程序图标
docs/
```
## 模式和模板
`wikiloop init` 将知识库的 `schema/` 目录填充为捆绑的创作规则和页面模板（源自 `internal/kbinit/schema/`）：
- `schema/templates/`：Markdown 模板，用于源笔记/概念/比较/决策页面。
- `schema/references/`：创作规则 - 页面类型、引用规则、冲突规则、目录结构、维护循环。
蒸馏/合成提示读取这些模板，因此编辑它们会自定义每个知识库的 Wiki 格式。
## 知识库实例
默认知识库实例名称为：
```text
wikiloop-kb/
```
这只是一个约定。用户可以将知识库放在任何地方并命名为不同的名称。
最小结构：
```text
wikiloop-kb/
raw/
wiki/
schema/
```
推荐的完整结构在 `schema/references/kb-directory-structure.md` 中有记录（由 `wikiloop init` 创建）。
## 快速入门
```bash
export WIKILOOP_KB=/path/to/your-kb
wikiloop index # 构建/更新索引
wikiloop embed # 生成嵌入（可选）
wikiloop status # 索引统计
wikiloop search "查询"
wikiloop context "问题"
wikiloop lint
```
完整选项： `wikiloop --help`.
## 命令参考
所有命令都接受全局 `--kb <path>` 标志（默认为 `$WIKILOOP_KB`，然后是 `~/wikiloop-kb`）：
| 命令 | 描述 |
|---|---|
| `wikiloop init [--force]` | 搭建知识库目录并复制捆绑的模式/模板。 `--force` 覆盖现有的模式文件。 |
| `wikiloop serve` | 启动长时间运行的服务器：HTTP MCP (`/mcp`) + Web UI + 文件监视器。默认情况下，当没有子命令时。 |
| `wikiloop index` | 从 `wiki/` 和 `raw/` Markdown 构建/更新 FTS 索引。 |
| `wikiloop embed [--full]` | 为文档生成向量嵌入。 `--full` 删除并重建向量存储。需要 ONNX 运行时。 |
| `wikiloop search <查询>` | FTS 关键字搜索；打印带有路径和摘要的排名结果。 |
| `wikiloop context <问题>` | 为问题构建上下文包（相关页面 + 源）。 |
| `wikiloop distill` | （在 `serve`/监视器内运行）将新的 `raw/` 文件通过 LLM 转换为 `wiki/source-notes/`。不是独立的子命令 - 自动触发。 |
| `wikiloop synthesize [--topic X] [--full]` | 从源笔记生成概念/比较/决策页面。默认增量； `--full` 重新处理所有内容； `--topic` 限制为标签/标题匹配。 |
| `wikiloop synthesize --gaps --topic X` | 话题知识差距分析；写入报告到 `index/gaps/<slug>.md`。 |
| `wikiloop lint` | 健康检查 Wiki 页面：缺少 frontmatter 字段、损坏的源链接。 |
| `wikiloop status` | 打印索引统计（文档/嵌入计数、索引大小）。 |
| `wikiloop service <install\|uninstall\|start\|stop\|status\|logs>` | 管理操作系统服务（launchd / systemd）。 |
**LLM 配置**（知识库根目录下的 `config.yaml`，`distill` 部分）对于 `distill` 和 `synthesize` 是必需的。请参阅 MCP 服务器部分的格式； `api_type` 选择 `openai`（默认）或 `anthropic`。
### 合成工作流：从原始源到主题摘要
典型流程：代理收集或生成内容 → 自动蒸馏 → 按需综合每个主题。
原始源可以是任何内容：
- 代理获取的文章（网页、微信、RSS）
- 用户丢弃的文档（转换后的 PDF、本地笔记）
- 代理生成的报告或分析文件
- 任意 Markdown 文件
**步骤 1 — 内容进入知识库（自动）**
将 Markdown 放入 `raw/`（按来源组织，例如 `raw/articles/`、`raw/papers/`、`raw/reports/`）；
`wikiloop serve` 监视器自动运行蒸馏 + 索引 + 嵌入。
**步骤 2 — 按主题综合（按需，代理触发）
```bash
# 总结所有标记/标题为“芯片产业”的源笔记
wikiloop synthesize --topic "芯片产业"
# 强制完整重新运行（忽略增量缓存）
wikiloop synthesize --topic "芯片产业" --full
# 无主题：处理所有新的/更改的源笔记，跨主题
wikiloop synthesize
# 知识差距分析：主题有什么缺失？
wikiloop synthesize --gaps --topic "芯片产业"
# → index/gaps/zhi-pian-chan-ye.md
```
** `--topic` 匹配**：源笔记 `title` 或 `tags` 的不区分大小写的子字符串匹配。
**输出类型**:
| 类型 | 目录 | 阈值 |
|---|---|---|
| 概念 | `wiki/concepts/` | ≥3 源笔记共享一个概念/模式 |
| 比较 | `wiki/comparisons/` | ≥2 源笔记值得对比 |
| 决策 | `wiki/decisions/` | ≥2 源笔记支持技术判断 |
## 自动索引服务
监视知识库目录中的更改并自动触发 `index + embed`。支持 macOS（launchd）和 Linux（systemd）。
```bash
# 安装并启动系统服务
wikiloop service install --kb /path/to/your-kb
# 检查状态 / 卸载
wikiloop service status
wikiloop service uninstall
```
日志写入 `{WIKILOOP_KB}/index/watcher.log`。
## MCP 服务器
WikiLoop 通过 MCP 协议公开知识库工具。支持两种部署场景。
可用工具： `kb_search`, `kb_context`, `kb_status`, `kb_reindex`, `kb_lint`
---
### 场景 1：本地多代理共享
适用于共享单个知识库实例的多个本地代理（Claude Code、Cursor 等）。
推荐 HTTP 模式：一个 WikiLoop 进程由所有代理共享，避免索引冲突，每个代理都启动自己的_stdio 进程时可能发生冲突。
**步骤 1：设置知识库路径并启动 WikiLoop**
默认知识库目录为 `~/wikiloop-kb`。使用环境变量覆盖：
```bash
export WIKILOOP_KB=/path/to/wikiloop-kb
```
安装后，为 CLI 访问创建符号链接：
```bash
# macOS
sudo ln -sf /Applications/WikiLoop.app/Contents/MacOS/wikiloop /usr/local/bin/wikiloop
# Linux
sudo ln -sf /path/to/wikiloop /usr/local/bin/wikiloop
```
启动服务：
```bash
wikiloop serve
```
> 在 macOS 上，您也可以双击 WikiLoop.app 以将其启动为菜单栏图标。
> 应用程序自动从 `~/.zshenv`、`~/.bashrc` 等 shell rc 文件中读取 `WIKILOOP_*` 变量，因此其行为与 CLI 调用相同。
`serve` 提供 HTTP MCP (`/mcp`) 和 Web UI。端口在 `config.yaml` 下的 `server` 中配置（默认为 8766）。
**步骤 2：在每个代理中配置 HTTP MCP**
添加到 `~/.claude.json` 下的 `mcpServers`:
```json
{
"mcpServers": {
"wikiloop": {
"type": "http",
"url": "http://127.0.0.1:8766/mcp",
"headers": {
"x-api-key": "${WIKILOOP_API_KEY}"
}
}
}
}
```
`x-api-key` 对应于 `config.yaml` 中的 `server.api_key`。如果未设置 api_key，请省略 `headers`。
---
### 场景 2：托管代理环境（Hermes / OpenClaw 等）
在托管环境中，容器无法访问用户本地进程。将 WikiLoop 安装在代理环境 **的持久卷** 上，并通过 stdio 在本地调用。
Alibaba Cloud NAS 安装的 OpenClaw/Hermes 示例（安装点 `/root/.openclaw`）：
**1. 安装到持久卷（一次性）：**
```bash
tar -xzf wikiloop-linux-amd64.tar.gz -C /root/.openclaw/wikiloop/
chmod +x /root/.openclaw/wikiloop/wikiloop
# 将模型复制到知识库目录
mkdir -p /root/.openclaw/wikiloop-kb/models
cp -r /root/.openclaw/wikiloop/models/* /root/.openclaw/wikiloop-kb/models/
```
容器重新构建后，NAS 卷重新挂载，二进制和知识库数据都保留 - 无需重新安装。
**2. MCP 配置：
Claude Code（`~/.claude.json`）：
```json
{
"mcpServers": {
"wikiloop": {
"command": "/root/.openclaw/wikiloop/wikiloop",
"args": ["serve"],
"env": {
"WIKILOOP_KB": "/root/.openclaw/wikiloop-kb"
}
}
}
}
```
Hermes（代理配置中的 `mcp_servers`）：
```yaml
mcp_servers:
wikiloop:
command: /root/.openclaw/wikiloop/wikiloop
args: [serve]
env:
WIKILOOP_KB: /root/.openclaw/wikiloop-kb
```
OpenClaw 使用与 Hermes 相同的格式 - 请参阅平台文档。
