内容
# 知情者
[简体中文](README.zh-CN.md)
知情者是一款面向代理的本地优先知识聚合工具。它提供了一个统一的核心服务，带有CLI、Web仪表盘和面向MCP的适配器，允许代理和人类从多个知识库中添加、浏览和检索知识。
## 功能特点
- **多后端**: 支持SQLite和文本文件知识库。
- **本地默认存储**: 无需配置文件即可运行，使用`~/.knowledger/db`。
- **词典搜索**: 可用SQLite FTS5，适用于文件存储的文本搜索。
- **语义搜索**: SQLite知识库可使用Chroma进行语义或混合检索。
- **嵌入式持久化Chroma**: 默认设置无需外部Chroma服务器。
- **CLI工作流**: 从终端添加、搜索、获取和列出知识库。
- **Web仪表盘**: 管理运行时知识库、检查项目和测试搜索行为。
- **MCP适配器基础**: 面向代理集成的工具定义。
## 系统要求
- Go 1.25+
## 安装
**macOS / Linux** — 一行命令:
```bash
curl -fsSL https://raw.githubusercontent.com/sunshine0523/claude-knowledger/main/install.sh | sh
```
**Windows** (PowerShell):
```powershell
irm https://raw.githubusercontent.com/sunshine0523/claude-knowledger/main/install.ps1 | iex
```
该脚本检测您的操作系统和架构，从[最新版本](https://github.com/sunshine0523/claude-knowledger/releases/latest)下载正确的二进制文件，并将其安装到`/usr/local/bin`（或`~/.local/bin`如果`/usr/local/bin`不可写入）。
**从源代码构建** （需要Go 1.25+，无需CGO）：
```bash
git clone https://github.com/sunshine0523/claude-knowledger.git
cd claude-knowledger
go build -o knowledger ./cmd/knowledger
```
## 快速入门
知情者可以在没有`knowledger.yaml`的情况下运行。如果没有配置文件，它会创建一个默认的SQLite知识库：
- ID: `default`
- SQLite路径: `~/.knowledger/db`
- 嵌入式Chroma路径: `~/.knowledger/chroma/default`
- Chroma集合: `default`
添加一个知识项:
```bash
knowledger add \
--kb default \
--title "SQLite笔记" \
--content "知情者将本地知识存储在SQLite中。"
```
搜索知识:
```bash
knowledger search --query SQLite --limit 10
```
按ID获取项目:
```bash
knowledger get --kb default --id 1
```
列出知识库:
```bash
knowledger list-kbs
```
## Web仪表盘
启动仪表盘:
```bash
knowledger serve
```
默认地址:
```text
http://127.0.0.1:34125/
```
页面:
- `/` — 仪表盘概览
- `/kbs` — 知识库管理
- `/knowledge` — 知识项目浏览
- `/search-lab` — 搜索测试UI
- `/debug` — 诊断
从Web仪表盘创建的运行时知识库默认存储在`~/.knowledger/registry.json`中。`knowledger.yaml`中定义的静态知识库在仪表盘中为只读。删除运行时知识库仅删除其注册条目；它不会删除SQLite数据库、文本目录或Markdown文件。
## MCP服务器
```bash
knowledger install --claude
```
这会自动将知情者配置为Claude代码中的MCP服务器。
## 配置
复制示例配置文件:
```bash
cp knowledger.example.yaml knowledger.yaml
```
使用显式配置文件启动:
```bash
knowledger --config knowledger.yaml serve
```
最小SQLite配置:
```yaml
default_search_mode: auto
runtime_registry_path: ~/.knowledger/registry.json
server:
address: ":34125"
knowledge_bases:
- id: default
name: 默认
store_type: sqlite
enabled: true
store_config:
path: ~/.knowledger/db
indexing:
lexical:
enabled: true
semantic:
enabled: true
provider: chroma
mode: persistent
path: ~/.knowledger/chroma/default
collection: default
auto_download: true
sync_mode: async
```
文本知识库配置:
```yaml
knowledge_bases:
- id: docs
name: 文档
store_type: text
enabled: true
store_config:
path: ./data/docs
```
文本知识库读写`.md`和`.txt`文件。
## 搜索模式
支持的搜索模式:
- `auto` — 使用知识库的默认行为。
- `lexical` — 关键词/全文搜索。
- `semantic` — 通过Chroma进行向量搜索，适用于支持的SQLite知识库。
- `hybrid` — 当支持时，结合语义和词典检索。
示例:
```bash
knowledger search --query "代理内存" --search-mode hybrid --limit 5
```
如果在查询时语义搜索不可用，则支持的路径会回退到词典搜索，并带有警告。
## 开发
运行测试:
```bash
go test ./...
```
运行SQLite/FTS5测试:
```bash
go test -tags fts5 ./...
```
## 项目状态
知情者处于早期开发阶段。CLI和Web仪表盘可用于本地实验。MCP适配器目前为未来的代理集成提供基础工具注册。
