知识库cli
edit | blame | history | raw

kb-cli

知识库 CLI 工具，支持 Obsidian 风格 Markdown 文件的图谱搜索。

功能特性

  • ✅ Vault 解析器：解析 Obsidian frontmatter、标签、实体、wikilinks
  • ✅ 知识图谱构建：文件 → 节点，标签/实体/wikilinks → 边
  • ✅ SQLite 存储：高效持久化，支持增量更新
  • ✅ FTS5 全文搜索：基于 SQLite FTS5 的快速搜索（ASCII 走 FTS5、CJK 走 LIKE 双通道）
  • ✅ 图谱评分算法：文本位置分 + RWR 随机游走图质量双信号加权
  • ✅ 长中文词召回：>3 字符 CJK 词自动 bigram 展开
  • ✅ explore 命令：按字节预算直出原文段落（agent 一次性上下文）
  • ✅ 多种输出格式：表格、JSON
  • ✅ 内容返回：--with-content 返回完整文件内容
  • ✅ 关联链接：--with-links 返回 wikilink 关联文档

安装

# 编译
make build

# 安装到 ~/go/bin
make install

# 运行测试
make test

注意：需要 CGO 和 FTS5 支持。

构建要求

go-sqlite3 需要系统 SQLite 开启 FTS5，构建时必须显式传入 CGO 标志（make build 已内置）：

CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go build
# 或
make build

使用方法

搜索

# 基础搜索
kb-cli search 充装规格

# 带扩展词
kb-cli search 充装 --expanded 重量,规格

# 带症状词
kb-cli search 充装失败 --symptom 报错,无法启动

# 返回完整文件内容
kb-cli search 充装规格 --with-content

# 返回关联文档链接
kb-cli search 充装规格 --with-links

# 同时返回内容和链接
kb-cli search 充装规格 --with-content --with-links

# JSON 输出
kb-cli search 充装 --json

# 限制结果数
kb-cli search 充装 --top 5

双通道检索：ASCII 词走 FTS5，CJK 词走 LIKE（title/aliases/content/tags 四列）。FTS5 unicode61 把连续中文当整串单 token，多字符中文词 MATCH 匹配不到，必须走 LIKE。长中文词（>3 字符）自动做 bigram 滑动展开（如「电子秤补气失败」→ 电子/子秤/秤补/补气/气失/失败），bigram 命中按扩展词档计权。

排序双信号：最终分 = 文本位置分 × TextWeight + RWR 随机游走图质量 × (1-TextWeight)（TextWeight 缺省 0.5，可配 config.yaml）；草稿态/待审阅板块降权 0.6。

探索（explore）

面向 agent 的一次性上下文获取：按字节预算直出相关文档的**原文段落**（整段不截半句），并附关联清单（wikilinks）与悬空链接提示，agent 无需再读文件。

# 默认预算 16000 字节、Top 5 篇（均可配 config.yaml explore 节）
kb-cli explore "电子秤补气失败"

# 自定义预算与文档数
kb-cli explore "补气失败" --budget 8000 --top 3

# JSON 输出
kb-cli explore "补气失败" --json

与 search 的分工：search 返回文档列表（路径/标题/板块/得分，供浏览定位）；explore 直接按预算返回命中文档的原文段落（供 agent 一次性获取上下文）。

索引管理

# 构建索引：默认增量对账同步（按 mtime/size 比对，只处理新增/修改/删除的文件），
# --force 全量重建
kb-cli index build
kb-cli index build --force

# 查看索引状态
kb-cli index status

# 清理孤立节点
kb-cli index gc

Git 同步

# 同步知识库到 Git 仓库
kb-cli git sync

知识图谱

# 图谱统计（节点数、边数、关系类型分布）
kb-cli graph stats

# 查询节点的关联关系
kb-cli graph query 补气

# 查找与关键词相关的节点
kb-cli graph related 补气 --top 10

provenance 标注：每条边带 provenance 字段标注关系来源类型：tag（frontmatter 标签）、entity（正文实体）、exact/fuzzy（wikilink 精确/模糊匹配）。graph query 的边数据（含 --json 输出）携带该字段；悬空补全的 wikilink 边按匹配方式标注 exact/fuzzy。graph related 只输出节点级信息（路径/板块/标签/关联度），不含边 provenance。

全局选项

--vault    知识库路径（默认：~/aisim/note/001/笔记001）
--db       索引数据库路径（默认：~/.cache/kb-cli/kb.db）

项目结构

kb-cli/
├── cmd/              # CLI 命令
│   ├── root.go       # 根命令
│   ├── search.go     # search 命令
│   ├── explore.go    # explore 命令
│   ├── index.go      # index 命令
│   ├── graph.go      # graph 命令
│   └── rebuild.go    # 索引构建逻辑
├── internal/
│   ├── vault/        # Vault 解析器
│   │   ├── parser.go
│   │   ├── scanner.go
│   │   └── sections.go
│   ├── graph/        # 知识图谱
│   │   ├── model.go
│   │   ├── builder.go
│   │   └── rwr.go    # RWR 随机游走图质量
│   ├── index/        # SQLite 存储
│   │   ├── sqlite.go
│   │   ├── fts.go    # 双通道检索（FTS5 + LIKE）
│   │   ├── reconcile.go  # 增量对账
│   │   ├── migrations.go # schema 迁移
│   │   └── graphload.go  # RWR 邻接加载
│   ├── search/       # 搜索引擎
│   │   ├── engine.go
│   │   ├── explore.go    # explore 段落直出
│   │   ├── expand.go     # CJK bigram 展开（search/explore 共享）
│   │   └── scorer.go
│   ├── llm/          # LLM 配置
│   ├── classify/     # 实体/标签分类
│   ├── draft/        # 草稿入库
│   ├── review/       # 草稿预览
│   └── output/       # 输出格式化
│       └── formatter.go
├── scripts/
│   └── e2e-verify.sh # 端到端验证脚本
└── main.go

评分算法

搜索结果按**双信号加权**排序：

  • 文本位置分：路径/标题/板块/别名/内容命中计权（位置权重不同，别名按 title 档；实体词降权 1/5，通用词降权 1/3）
  • RWR 图质量：随机游走（Personalized PageRank），种子 = 检索候选前 20，体现节点在知识图谱中的中心性
  • 合并：最终分 = 归一化文本分 × TextWeight + RWR × (1-TextWeight)，TextWeight 缺省 0.5（config.yaml 可配）
  • 降权：草稿态（草稿/待确认/跟进中）与「待审阅」板块 ×0.6

开发

# 运行所有测试
make test

# 详细测试输出
make test-v

# 构建并运行
make build
./bin/kb search 充装

依赖

  • Go 1.21+
  • SQLite3（带 FTS5 支持）
  • github.com/mattn/go-sqlite3
  • github.com/spf13/cobra
  • gopkg.in/yaml.v3

许可证

MIT