个人知识库管理系统

一个轻量级的 Python CLI 工具，使用 LLM 作为"图书管理员"，自动整理、关联和管理个人知识库。

🌟 特性

✅ 完全自动化：用户只需采集素材和提问，其他由 AI 完成
✅ 多种 LLM 后端：支持 OpenAI, Anthropic Claude, 本地 Ollama, 离线 Mock
✅ 智能搜索：倒排索引快速定位相关内容
✅ 状态与自检：支持 status 和 doctor 做本地状态查看与配置预检
✅ 健康检查：自动检测 wiki 中的问题（断链、孤立页面等）
✅ 备份恢复：支持从 wiki_backup/ 恢复历史 wiki 页面并重建索引
✅ 闭环知识流：采集 → 整理 → 问答 → 演化
✅ 可视化：所有文件使用 Markdown，支持 Obsidian/VS Code

📦 项目结构

知识库/
├── config/
│   ├── KNOWLEDGE_BASE.md      # 知识库配置和规则（用户编辑）
│   ├── llm_config.json        # LLM 后端配置（可选）
│   ├── llm_config.example.json # LLM 配置模板（init 自动生成）
│   ├── .last_update           # 最近一次 build/update 时间戳（自动维护）
│   └── .raw_manifest.json     # raw 快照（自动维护）
├── raw/                       # 原始素材（LLM 只读）
│   ├── article1.md
│   ├── paper2.txt
│   └── ...
├── wiki/                      # AI 维护的知识网络
│   ├── INDEX.md              # 总目录（自动生成）
│   ├── INDEX.json            # 索引数据（自动生成）
│   ├── 概念1.md
│   ├── 概念2.md
│   └── ...
├── outputs/                   # 问答与分析结果
│   ├── 20250218_1432_问题.md
│   └── ...
├── logs/                      # 系统日志
└── wiki_backup/               # Wiki 备份

补充文档位于 help/QUICKSTART.md 和 help/ARCHITECTURE.md。

🚀 快速开始

1. 初始化知识库

python kb.py init ~/my_knowledge --name "我的知识库"
cd ~/my_knowledge

2. 添加原始素材

将你的文章、笔记等 Markdown / 纯文本素材放入 raw/ 目录：

raw/
├── Python异步编程.md
├── 设计模式.txt
└── ...

3. 配置 LLM

初始化后会生成 config/llm_config.example.json。复制其内容到 config/llm_config.json 后再填写真实参数：

{
  "openai": {
    "api_key": "your-openai-api-key-here",
    "model": "gpt-5.4",
    "base_url": "https://api.openai.com/v1"
  },
  "anthropic": {
    "api_key": "your-anthropic-api-key-here",
    "model": "claude-opus-4.6"
  },
  "ollama": {
    "model": "llama4",
    "base_url": "http://localhost:11434"
  }
}

💡 自定义 API 地址：如果使用代理服务或兼容 OpenAI 的本地部署，可以修改 base_url 字段。

或者设置环境变量（向后兼容）：

export OPENAI_API_KEY="sk-..."

PowerShell:

$env:OPENAI_API_KEY="sk-..."

4. 构建 Wiki

使用 LLM 将原始素材组织成结构化知识网络：

python kb.py build --backend openai
# 或离线校验
python kb.py build --backend mock

如果 wiki/ 中已经有页面，build 会先二次确认，并提供 3 个选项：

全部重新构建
降级为 update 做增量更新
取消本次构建

日常新增或修改素材时，优先使用 update。只有在你明确要重做知识网络，或者 raw/ 发生删除、重命名、大范围重组时，再使用全量构建。

4. 提问与搜索

# 提问
python kb.py ask "如何在 Python 中使用异步编程?"

# 搜索
python kb.py search "异步编程 Coroutine"

5. 健康检查

检查 wiki 的质量和一致性：

python kb.py health --backend openai --fix

6. 查看状态与环境

# 查看知识库状态
python kb.py status

# 检查目录结构、配置文件和后端本地预检
python kb.py doctor
python kb.py doctor --backend openai

📖 完整命令参考

init - 初始化知识库

python kb.py init [路径] \
  --name "知识库名称" \
  --description "知识库描述" \
  --topics "主题1" "主题2" "主题3"

选项：

path: 目标目录（默认：当前目录）
--name: 知识库标题
--description: 知识库描述
--topics: 关注的子方向（多个）

输出：

config/KNOWLEDGE_BASE.md - 知识库配置文件
config/llm_config.example.json - LLM 配置模板
config/.last_update - 最近一次同步时间戳
config/.raw_manifest.json - raw 快照，用于增量更新保护
wiki/INDEX.md - 空索引
config/, raw/, wiki/, outputs/, logs/, wiki_backup/ 目录

status - 查看当前状态

查看素材数、wiki 页面数、待同步文件、备份数量和关键索引文件状态。

python kb.py status --path .

doctor - 本地自检

检查目录结构、知识库说明书、LLM 配置文件和指定后端的本地可用性。

python kb.py doctor --path .
python kb.py doctor --path . --backend openai

build - 全量构建 Wiki

从原始素材构建完整的知识网络。

python kb.py build \
  --path . \
  --backend openai \
  --clean \
  --dry-run

选项：

--path: 知识库路径（默认：当前目录）
--backend: LLM 后端：openai（默认）、anthropic、ollama、mock
--clean: 构建前清空现有 wiki（会自动备份）
--dry-run: 只预览动作，不写入 wiki、索引、备份或时间戳

行为说明：

如果 wiki/ 已有页面，交互环境下会先询问： 1 全部重新构建、2 降级为 update、3 取消。
全量构建把本轮 LLM 产出的页面集合作为最终结果，未保留的旧页面会被清理。
当 raw/ 为空且选择重新构建时，会清空旧 wiki 页面并写出空索引。

输出：

wiki/ 下的 .md 文件（每个概念一个）
wiki/INDEX.md - 更新的总目录
wiki/INDEX.json - 索引元数据

update - 增量更新 Wiki

扫描原始文件变化，增量更新 wiki（节省 token）。

python kb.py update --path . --backend openai --dry-run

选项：

--path: 知识库路径
--backend: LLM 后端：openai、anthropic、ollama、mock
--dry-run: 只预览动作，不写入 wiki、索引或时间戳

行为说明：

update 依据 config/.last_update 和 config/.raw_manifest.json 判断哪些 raw 文件发生了新增或修改。
如果检测到 raw 文件被删除或重命名，update 会直接拒绝继续，并提示改用 python kb.py build --clean。
对于与现有 wiki 页面明显对应的增量内容，系统会优先更新原页面，而不是新建一个同主题页面。

ask - 提问与问答

使用知识库回答问题。

python kb.py ask "你的问题" \
  --path . \
  --backend openai \
  --output markdown \
  --no-save

选项：

question: 问题内容（必需）
--path: 知识库路径
--backend: LLM 后端：openai、anthropic、ollama、mock
-o, --output: 输出格式：markdown（默认）、marp、json
--no-save: 不保存到 outputs/ 目录

工作流程：

搜索相关页面（使用倒排索引）
LLM 精选最相关的 3-5 个页面
读取精选页面全文生成答案
保存到 outputs/

降级行为：

如果 LLM 调用失败，ask 会退化为返回本地搜索摘要，不会修改 wiki/。

search - 快速搜索

在 wiki 中搜索关键词（不调用 LLM，速度快）。

python kb.py search "Python 异步编程"

输出：

匹配的页面列表
每个页面的摘要和相关性评分

health - 健康检查

检查 wiki 的质量问题。

python kb.py health \
  --path . \
  --backend openai \
  --fix

检查项：

💔 断链检测 - 引用了不存在的页面或素材
🏚️ 孤立页面 - 没有被其他页面引用
📝 缺少摘要 - 页面缺少开头的摘要段落
🔄 重复内容 - 相似或重复的页面内容
📎 未引用素材 - raw/ 中的素材没有被任何 wiki 页面引用
⏰ 过时页面 - 来源素材已更新但 wiki 页面未同步
⚠️ 矛盾检测 - 通过 LLM 检查页面间潜在冲突（失败时自动降级跳过）

输出：

wiki/HEALTH_REPORT.md - 可读格式的报告
wiki/HEALTH_REPORT.json - 结构化数据

选项：

--fix: 尝试自动修复检测到的问题

补充说明：

--fix 真正修改 wiki 页面后，会同步重建 INDEX.md / INDEX.json。
页面矛盾检测依赖 LLM；如果调用失败，会自动跳过该检查项并继续生成报告。

archive - 归档输出

将 outputs/ 中的优质回答合并到 wiki，对已归档内容保持幂等跳过。

python kb.py archive --path .
# 或启用 LLM 精选目标页面
python kb.py archive --path . --backend openai

系统会优先使用显式 [[页面]] 链接匹配目标页面；若提供 --backend，会先调用 LLM 在候选页面中精选目标；否则回退到本地规则匹配。最终会把内容追加到对应 wiki 页面的 ## 讨论与疑问，并同步重建索引。

restore - 恢复历史 wiki 备份

先列出备份，再按目录名恢复。恢复前会先把当前 wiki 页面备份到新的 *_before_restore 目录；随后覆盖当前 wiki 页面、重建 INDEX.md / INDEX.json，并清除上次更新时间戳。

python kb.py restore --path . --list
python kb.py restore 20260415_120000 --path . --yes

🔌 LLM 后端配置

OpenAI

export OPENAI_API_KEY="sk-..."
python kb.py build --backend openai

$env:OPENAI_API_KEY="sk-..."
python kb.py build --backend openai

Anthropic Claude

export ANTHROPIC_API_KEY="sk-ant-..."
python kb.py build --backend anthropic

$env:ANTHROPIC_API_KEY="sk-ant-..."
python kb.py build --backend anthropic

本地 Ollama

# 启动 Ollama 服务（默认: http://localhost:11434）
ollama serve

# 在另一个终端运行
python kb.py build --backend ollama

离线 Mock

python kb.py build --backend mock
python kb.py ask "根据知识库总结核心观点" --backend mock

适合在没有 API Key 的环境里做命令链路自测。

📊 Wiki 页面格式

系统生成的 wiki 页面遵循以下格式：

# 概念名称

> 摘要：2-3 句话概括核心内容。

## 来源
- [[原始文件名]]
- [外部链接](url)

## 核心内容

### 小标题

页面内容...

## 相关概念

- [[相关页面1]]
- [[相关页面2]]

## 讨论与疑问

（问答结果可能被添加到这里）

🧪 演示

运行演示脚本查看系统完整功能：

python demo.py

这将：

创建临时知识库
添加示例文件
构建 wiki
执行搜索
运行健康检查
演示问答功能

🏗️ 系统架构

模块	职责
`kb.py`	CLI 入口和命令路由
`sparrow_kar_knowledge/constants.py`	全局配置和常数
`sparrow_kar_knowledge/file_ops.py`	文件系统操作
`sparrow_kar_knowledge/llm_client.py`	LLM 后端抽象（OpenAI, Anthropic, Ollama, Mock）
`sparrow_kar_knowledge/wiki_manager.py`	Wiki 页面管理和模板
`sparrow_kar_knowledge/builder.py`	Build/Update 逻辑
`sparrow_kar_knowledge/qa.py`	问答系统
`sparrow_kar_knowledge/search_engine.py`	倒排索引搜索
`sparrow_kar_knowledge/health.py`	健康检查
`sparrow_kar_knowledge/archive.py`	输出归档回流到 wiki
`sparrow_kar_knowledge/output_formatter.py`	输出格式化（Markdown, MARP, JSON）
`sparrow_kar_knowledge/cli.py`	CLI 命令、状态自检、备份恢复

📝 工作流程示例

全量构建流程

raw/*.md → 扫描所有文件
    ↓
    → LLM 聚类分析
    ↓
    → 生成 wiki 页面
    ↓
    → 更新 INDEX.md 和 INDEX.json
    ↓
    → 完成！

问答流程

用户问题 → 搜索引擎（关键词匹配）
    ↓
    → LLM 精选相关页面（3-5 个）
    ↓
    → 读取完整页面内容
    ↓
    → LLM 生成答案
    ↓
    → 保存到 outputs/

🛡️ 安全与限制

✅ 自动备份 wiki 到 wiki_backup/
✅ 支持 restore 从备份恢复 wiki 页面
✅ LLM 写操作前自动备份
✅ 操作日志记录到 logs/
✅ 基础重试和调用统计
✅ LLM 对 raw/ 只读，无法修改原始文件

🤝 集成 Obsidian

本项目的 wiki 完全兼容 Obsidian，可以：

在 Obsidian 中打开 wiki 目录
使用 [[链接]] 进行笔记链接
查看自动生成的关系图
在 Obsidian 中编辑和扩展 wiki

📦 依赖

核心依赖：

Python 3.10+
pathlib, argparse, logging, json（标准库）

可选依赖（取决于使用的 LLM 后端）：

openai - 用于 OpenAI API
anthropic - 用于 Anthropic API
requests - 用于 Ollama

安装依赖：

pip install -r requirements.txt

🐛 故障排除

找不到 API Key

❌ 缺少 OPENAI_API_KEY 环境变量

解决：

export OPENAI_API_KEY="sk-..."

PowerShell:

$env:OPENAI_API_KEY="sk-..."

Build 失败

检查：

raw/ 目录是否有文件
LLM API 是否可用
日志文件：logs/ 目录

如果 wiki/ 已有页面，build 还会先要求你选择：

重新构建
降级为 update
取消操作

搜索结果为空

确保已运行 build 或 update
检查 wiki/ 目录是否有 .md 文件
尝试使用不同的关键词

update 提示需要改用 build --clean

这通常表示 raw/ 中有文件被删除或重命名
update 不会自动处理这类结构性变化
运行 python kb.py build --clean 重新收敛 wiki 与索引

📚 更多示例

创建学习笔记库

python kb.py init ~/study --name "学习笔记"
# 添加各课程笔记到 raw/
python kb.py build --backend openai
python kb.py ask "总结本周学习内容"

构建研究资料库

python kb.py init ~/research --name "研究资料库"
# 将 Markdown / 纯文本资料放入 raw/
python kb.py build --backend anthropic
python kb.py health --fix  # 检查一致性

团队知识管理

# 在共享驱动器上初始化
python kb.py init /shared/team_kb --name "团队知识库"
# 团队成员各自提交资料
# 定期运行 health 检查质量
python kb.py health --backend openai

📄 许可证

MIT License

🙏 致谢

项目灵感来自 Andrej Karpathy 的 LLM Knowledge Bases 思想。以及linux.do用户zanezhou的把一堆乱七八糟的笔记，变成一个会自己生长的知识库-Karpathy

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
config		config
help		help
sparrow_kar_knowledge		sparrow_kar_knowledge
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
demo.py		demo.py
kb.py		kb.py

Folders and files

Latest commit

History

Repository files navigation

个人知识库管理系统

🌟 特性

📦 项目结构

🚀 快速开始

1. 初始化知识库

2. 添加原始素材

3. 配置 LLM

4. 构建 Wiki

4. 提问与搜索

5. 健康检查

6. 查看状态与环境

📖 完整命令参考

init - 初始化知识库

status - 查看当前状态

doctor - 本地自检

build - 全量构建 Wiki

update - 增量更新 Wiki

ask - 提问与问答

search - 快速搜索

health - 健康检查

archive - 归档输出

restore - 恢复历史 wiki 备份

🔌 LLM 后端配置

OpenAI

Anthropic Claude

本地 Ollama

离线 Mock

📊 Wiki 页面格式

🧪 演示

🏗️ 系统架构

📝 工作流程示例

全量构建流程

问答流程

🛡️ 安全与限制

🤝 集成 Obsidian

📦 依赖

🐛 故障排除

找不到 API Key

Build 失败

搜索结果为空

update 提示需要改用 build --clean

📚 更多示例

创建学习笔记库

构建研究资料库

团队知识管理

📄 许可证

🙏 致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages