# knowledge

**Repository Path**: gitdogcat_admin/knowledge

## Basic Information

- **Project Name**: knowledge
- **Description**: # KB - 极简知识库系统

一个基于文件系统的轻量级知识库，用 Go 编写，单二进制部署。没有数据库锁死，没有花里胡哨的功能，就是简单可靠的文档管理。

## 为什么做这个

思源笔记太难用了。BUG 没人修，文档管理混乱，数据格式私有。找了一圈替代品，要么太重（Outline 要 Postgres+Redis），要么太 g
eek（纯命令行），要么往"块编辑器/双链图谱"这些花里胡哨的方向卷
- **Primary Language**: TeX/LaTeX
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-24
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KB - 极简知识库系统

一个基于文件系统的轻量级知识库，用 Go 编写，单二进制部署。没有数据库锁死，没有花里胡哨的功能，就是简单可靠的文档管理。

## 为什么做这个

思源笔记太难用了。BUG 没人修，文档管理混乱，数据格式私有。找了一圈替代品，要么太重（Outline 要 Postgres+Redis），要么太 geek（纯命令行），要么往"块编辑器/双链图谱"这些花里胡哨的方向卷。

我们的需求很朴素：
- 树状目录 + Markdown 文档
- 全文搜索（中文要能用）
- API 给 Hermes 读写
- 数据就是 `.md` 文件，不锁死在数据库里

找不到，就自己写了一个。

## 特性

- **文件系统即真相**：文档就是目录里的 `.md` 文件，系统挂了数据还在，scp 就能搬走
- **双链 + 反向链接**：`[[文档名]]` 语法，文档互链自动索引，阅读页显示"谁引用了我"
- **链接图谱**：d3 力导向图可视化整个知识网络，一眼看清文档之间的关系
- **业务实体图谱**（v1.3.0）：规则抽取 IP/主机名/服务:端口，实体成为图谱节点，文档挂在实体上
- **LLM 问答**（v1.4.0）：基于知识库的 RAG 问答，接任意 OpenAI 兼容 endpoint（本地 Ollama/vLLM/LM Studio 或云端 API），流式输出
- **悬停预览**（v1.4.0）：鼠标悬停双链显示文档预览，不用跳转就能瞟一眼内容
- **LLM 业务关系抽取**（v1.5.0）：从文档提炼业务级三元组（部署在/管理/依赖/运行…），关系入图谱、可语义检索
- **自动双链建议**（v1.5.2）：独立 link_llm（可指本地 Ollama）分析语义关联，建议 + 一键应用 `[[双链]]`
- **文档富化**（v1.6.0）：LLM 生成摘要/主题标签/文档类型/关联文档，异步批量，进度可查
- **MCP server**（v1.7.0）：内置 `POST /mcp`（Streamable HTTP），AI Agent 直连知识库——搜索/读写/目录/RAG 问答五个工具
- **融合检索 RAG**（v1.7.0）：关键词（停用词过滤 + CJK bigram）+ 语义向量 RRF 融合，命中位置 passage 级上下文
- **附件管道**（v1.8.0）：图片等二进制安全存储，`GET /attachments/{path}` 读取，Web UI 拖图自动插入文档
- **写入自动 AI**（v1.8.0）：可选 `auto_ai_enabled`，文档写入后防抖异步触发关系抽取 + 富化，图谱自愈式更新
- **摘要栏可收起**（v1.8.1）：预览页文档信息栏支持折叠（状态记忆），摘要文本限高滚动，不再遮挡正文
- **问答页长答案可滚动**（v1.8.2）：修复答案过长撑出视口、无滚动条的问题
- **多轮问答**（v1.9.0）：`/api/ask` 支持 history，前端会话气泡 + 追问自动携带上下文
- **块级 RAG 检索**（v1.9.0）：长文档按标题/段落切块独立算向量，命中块原文作上下文，长文后半段语义不再丢失
- **实体关系面板**（v1.9.0）：实体详情显示其参与的全部业务关系三元组
- **跨平台发行**（v1.9.1）：新增 Windows (amd64/arm64) 与 macOS (Intel/Apple Silicon) 构建；配置路径按平台落位（%AppData%\kb / ~/Library/Application Support/kb / ~/.config/kb），兼容旧路径；scripts/release.sh 一键六平台打包
- **SQLite WAL 并发修复**（v1.9.3）：修复 DSN pragma 语法错误导致 journal 一直是 delete 模式的问题；WAL + busy_timeout 15s，批量写入/reindex 不再 SQLITE_BUSY
- **业务实体规范化**（v1.9.2）：实体类型持久化（reindex 不丢）、别名自动合并（"ES 集群"≡"ES集群"）、IP/主机名不再误入业务实体、实体页按业务类型筛选
- **版本历史**：每次修改自动存档（每文档最多 50 版），支持 diff 对比和一键回滚
- **SQLite FTS5 搜索**：trigram 分词支持中文，索引坏了随时重建
- **单二进制部署**：Go 编译，前端 embed，15MB 搞定一切
- **REST API**：Bearer token 认证，Hermes 直接读写
- **Git 自动提交**：可选开启，文档变更自动 commit
- **回收站**：删除不真删，移入 trash 目录防手滑
- **零外部依赖**：前端 JS/CSS 全部本地化（含 d3），不依赖 CDN

## 快速开始

### 二进制运行

```bash
# 生成 token
export KB_TOKEN=$(openssl rand -hex 32)

# 启动（默认端口 6806）
./kb

# 访问 http://localhost:6806
```

### 配置

程序启动时自动读取平台配置目录下的 `kb/config.json`（Linux `~/.config/kb/`、macOS `~/Library/Application Support/kb/`、Windows `%AppData%\kb\`，也可用 `-config` 指定其他路径），环境变量优先级更高、会覆盖文件里的同名项。

```json
{
  "addr": ":6806",
  "docs_dir": "./docs",
  "data_dir": "./data",
  "token": "your-secret-token",
  "git_enabled": false,
  "log_level": "info"
}
```

推荐把配置写进配置文件（`chmod 600`），改 token 只动这一个文件 + `systemctl --user restart kb` 即可。

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `KB_ADDR` | 监听地址 | `:6806` |
| `KB_DOCS_DIR` | 文档根目录 | `./docs` |
| `KB_DATA_DIR` | 数据目录（索引+回收站） | `./data` |
| `KB_TOKEN` | API Token（必填） | - |
| `KB_GIT_ENABLED` | Git 自动提交 | `false` |
| `KB_LOG_LEVEL` | 日志级别 | `info` |

### AI 功能配置（可选，需要外部大模型）

**不配置 AI 也完全可用**：文档管理、全文搜索、规则实体图谱开箱即用。语义搜索、RAG 问答、业务关系抽取需要一个 **OpenAI 兼容** 的模型服务——本地跑（Ollama / vLLM / LM Studio）或任意云端 API 均可。以本地 Ollama 为例：

```json
{
  "semantic_enabled": true,
  "embedding_api": "http://localhost:11434/v1",
  "embedding_model": "bge-m3",
  "embedding_api_key": "",
  "llm_enabled": true,
  "llm_api": "http://localhost:11434/v1",
  "llm_model": "qwen2.5:7b",
  "llm_api_key": "",
  "auto_ai_enabled": false
}
```

> Ollama 需先 `ollama pull bge-m3 qwen2.5:7b`。换云端服务时把 api 地址/模型/key 换成对应服务商的即可。

| 配置项 | 作用 | 依赖 |
|---|---|---|
| `semantic_enabled` + `embedding_*` | 语义搜索（关键词+向量混合召回） | embedding 服务 |
| `llm_enabled` + `llm_*` | RAG 问答（多轮）、业务关系/实体抽取 | 聊天大模型 |
| `auto_ai_enabled` | 写入文档后自动触发语义索引+实体抽取 | 上面两者至少开一个 |

完整字段说明见仓库根目录 `config.example.json`（带注释）与 `docs/api.md`。

### API 示例

```bash
# 列出所有文档
curl -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/docs?recursive=true"

# 读取文档
curl -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/docs/项目/README.md"

# 创建/更新文档
curl -X PUT -H "Authorization: Bearer $KB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "# 标题\n\n正文"}' \
  "http://localhost:6806/api/docs/项目/新文档.md"

# 搜索
curl -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/search?q=关键词"

# 删除（进回收站）
curl -X DELETE -H "Authorization: Bearer $KB_TOKEN" \
  "http://localhost:6806/api/docs/旧文档.md"
```

完整 API 文档见 [docs/api.md](docs/api.md)。

### MCP Server（AI Agent 直连）

内置 Streamable HTTP MCP 端点 `POST /mcp`（与 REST API 同一个 Bearer token 鉴权），
AI Agent（Hermes / Claude 等任何 MCP 客户端）可把知识库直接当工具用：

| 工具 | 说明 |
|------|------|
| `kb_search` | 融合检索（FTS5 + 语义向量 RRF），返回命中片段 |
| `kb_read` | 读取文档全文（Markdown） |
| `kb_write` | 创建/更新文档（自动存版本历史 + 更新索引） |
| `kb_list` | 列出文档目录结构 |
| `kb_ask` | RAG 问答（需 `llm_enabled`），带出处回答 |

Hermes 配置示例（`~/.hermes/config.yaml`）：

```yaml
mcp_servers:
  kb:
    url: http://192.0.2.197:6806/mcp
    headers:
      Authorization: Bearer <token>
    timeout: 180
```

手动验证：

```bash
curl -X POST http://localhost:6806/mcp \
  -H "Authorization: Bearer ***" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## 部署

### 直接二进制（推荐）

```bash
# 下载或编译
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o kb ./cmd/kb

# 上传到服务器
scp kb user@server:/opt/kb/

# 写配置文件（程序启动时自动读取）
sudo mkdir -p /root/.config/kb
sudo tee /root/.config/kb/config.json << 'EOF'
{
  "addr": ":6806",
  "docs_dir": "/opt/kb/docs",
  "data_dir": "/opt/kb/data",
  "token": "your-token-here",
  "git_enabled": false,
  "log_level": "info"
}
EOF
sudo chmod 600 /root/.config/kb/config.json

# 创建 systemd 服务（无需 EnvironmentFile）
sudo tee /etc/systemd/system/kb.service << 'EOF'
[Unit]
Description=KB Knowledge Base
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/kb
ExecStart=/opt/kb/kb
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now kb
```

### 普通用户部署（无 sudo）

适合共享服务器或没有 root 权限的环境（如 Oracle Cloud 的 opc 用户）。配置写 `~/.config/kb/config.json`，服务用 `systemctl --user` 管理：

```bash
# 安装到 home 目录
mkdir -p ~/kb/{docs,data}
cp kb ~/kb/

# 1. 配置文件（程序启动自动读取）
mkdir -p ~/.config/kb
cat > ~/.config/kb/config.json << EOF
{
  "addr": ":6806",
  "docs_dir": "$HOME/kb/docs",
  "data_dir": "$HOME/kb/data",
  "token": "$(openssl rand -hex 32)",
  "git_enabled": false,
  "log_level": "info"
}
EOF
chmod 600 ~/.config/kb/config.json

# 2. 用户级 unit（%h 自动展开为 home，无需改路径）
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/kb.service << 'EOF'
[Unit]
Description=KB Knowledge Base
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/kb
ExecStart=%h/kb/kb
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
EOF

# 3. 启动（顺序不能反：先写 unit 文件，再 daemon-reload）
systemctl --user daemon-reload
systemctl --user enable --now kb

# 4. 常驻：注销登录后服务不被回收（需一次性 sudo）
sudo loginctl enable-linger $USER

# 验证
curl http://localhost:6806/api/health
```

常见报错 `Failed to enable unit: Unit file kb.service does not exist.` 不是权限问题，是第 2 步的 unit 文件没创建（或没 daemon-reload）。改 token 只需编辑 `~/.config/kb/config.json` 后 `systemctl --user restart kb`。

### 容器部署

```bash
# 构建镜像
podman build -t kb:latest -f Containerfile .

# 运行
podman run -d \
  --name kb \
  --restart unless-stopped \
  -p 6806:6806 \
  -v /data/kb/docs:/data/docs:Z \
  -v /data/kb/db:/data/db:Z \
  -e KB_TOKEN=your-token \
  kb:latest
```

更多部署选项见 [docs/deployment.md](docs/deployment.md)。

## 从思源迁移

```bash
# 导出思源文档
python3 scripts/export-from-siyuan.py

# 复制到 KB 文档目录
cp -r scripts/siyuan-export/* docs/

# 重建索引
curl -X POST -H "Authorization: Bearer $KB_TOKEN" \
  http://localhost:6806/api/reindex
```

## 项目结构

```
kb/
├── cmd/kb/           # 主程序入口
├── internal/
│   ├── api/          # REST API 处理器
│   ├── config/       # 配置加载
│   ├── search/       # SQLite FTS5 搜索
│   └── store/        # 文件系统存储 + Git
├── web/              # 前端（Alpine.js 单页）
├── scripts/          # 部署和迁移脚本
└── docs/             # 项目文档
```

## 技术栈

- **后端**：Go 1.24+，标准库优先，唯一外部依赖是 `modernc.org/sqlite`（纯 Go SQLite）
- **前端**：Alpine.js + Marked.js + github-markdown-css（全部本地化，无 CDN）
- **存储**：文件系统 + SQLite FTS5（仅索引）
- **部署**：systemd 或 Podman

##  License

MIT License - 详见 [LICENSE](LICENSE)

## 致谢

- [思源笔记](https://github.com/siyuan-note/siyuan) — 虽然难用，但导出的 markdown 格式帮了大忙
- [SQLite FTS5](https://www.sqlite.org/fts5.html) — trigram 分词让中文搜索变得简单