📦 llm-wiki — AI知识库

# CLI 参考 ## 协议模式（推荐） 使用自然语言与您的 agent 交互： `` "请摄入 sources/paper.pdf 到 wiki" "查询 wiki: Transformer 和 RNN 有什么区别？" "检查 wiki 健康状况" ` ## CLI 模式（可选） 安装依赖后： `bash # 显示 wiki 状态概览 python -m src.llm_wiki status # 运行健康检查 python -m src.llm_wiki lint # 显示帮助 python -m src.llm_wiki --help ` 注意：CLI 中的 ingest 和 query 命令仅提供辅助功能（如列出页面）。实际内容处理需通过与 agent 的自然语言交互完成。 # LLM-Wiki Karpathy 的 llm-wiki 模式实现 —— 面向 AI agent 的累积式知识管理。 > 核心哲学：LLM 即程序员，Wiki 即代码库，用户即产品经理。 ## 为何采用 SKILL 形态？ | 维度 | 独立应用（如 Sage-Wiki） | 本 SKILL 实现 | |-----------|----------------------------------|---------------------------| | 架构 | Go + SQLite + 嵌入式前端 | 纯 Markdown | | 部署 | 需运行服务 | 零部署 | | 集成 | 通过 MCP 间接 | 原生命令 | | 代码量 | ~1 万行 | ~500 行 | | 数据格式 | 专有 | 纯文本 Markdown | | 编辑器 | 锁定在应用内 | Obsidian/VSCode/任意 | ## 功能 - 📚 协议驱动：自然语言即可，无需安装 - 📝 纯 Markdown：无数据库、无锁定、原生 git - 🔗 Wiki 式链接：[[PageName]] 格式，兼容 Obsidian - 🧠 累积学习：每次查询都可创建新知识 - 🔍 健康检查：孤儿页面、死链、过期内容检测 - 🖥️ 可选 CLI：Python 脚本，支持自动化与批处理 ## 快速开始 `bash # 1. 克隆 git clone https://github.com/Nemo4110/llm-wiki.git cd llm-wiki # 2. 添加源材料 cp ~/Downloads/paper.pdf sources/ # 3. 告诉你的 agent "请摄入 sources/paper.pdf 到 wiki" ` ## 安装 ### 协议模式（推荐） 无需安装。Agent 直接读取 CLAUDE.md 并执行。 ### CLI 模式（可选） #### 使用 uv（最快） `bash # 创建虚拟环境并安装依赖 uv venv uv pip install -r src/requirements.txt --python .venv/Scripts/python.exe # 激活环境（Windows） .venv\Scripts\activate # 或 Linux/macOS source .venv/bin/activate ` #### 使用 conda `bash # 创建环境 conda create -n llm-wiki python=3.11 # 激活环境 conda activate llm-wiki # 安装依赖 pip install -r src/requirements.txt ` #### 使用 pip `bash # 创建虚拟环境 python -m venv .venv # 激活环境 source .venv/bin/activate # Linux/macOS .venv\Scripts\activate # Windows # 安装依赖 pip install -r src/requirements.txt ` #### 验证安装 `bash python -c "from src.llm_wiki.core import WikiManager; print('✓ Installation successful')" ` 重要依赖说明： | 依赖 | 版本 | 用途 | 备注 | |------------|---------|---------|-------| | click | >=8.0.0 | CLI 框架 | - | | pyyaml | >=6.0 | YAML 解析 | - | | pymupdf | >=1.25.0 | PDF 处理 | 主 PDF 引擎，CJK 最佳 | 可选依赖（增强功能）： - numpy >=1.24.0 — 向量运算，用于 embedding 检索 - httpx >=0.27.0 — HTTP 客户端，用于 Ollama/本地服务 - openai >=1.0.0 — OpenAI embedding API - mcp >=1.0.0 — MCP SDK，用于远程 embedding 提供商 PDF 降级依赖： - pdfplumber >=0.11.8 — 表格提取降级（需安全版本，修复 CVE-2025-64512） - pdfminer.six >=20251107 — PDF 底层库降级 ## 项目结构 ` llm-wiki/ ├── CLAUDE.md # ⭐ 核心协议：Agent 行为准则 ├── AGENTS.md # Agent 实现指南（CLI 用法） ├── SKILL.md # 本文件 ├── log.md # 时间线日志（仅追加） ├── sources/ # 原始材料（用户管理，Agent 只读） │ └── README.md ├── wiki/ # 生成的知识页面（Agent 管理） │ ├── index.md # 入口索引 │ └── .md # 主题页面 ├── assets/ # 模板与配置 │ ├── page_template.md │ └── ingest_rules.md ├── src/ # SKILL 实现（可选，CLI 用） │ ├── llm_wiki/ │ └── requirements.txt ├── scripts/ # 辅助脚本 ├── hooks/ # 平台钩子（可选） └── examples/ # 示例 wiki ` 关于 sources/：默认 git 排除，避免仓库膨胀。Wiki 仅保留提炼知识；原始文件另行管理（云盘、Zotero 等）。详见 sources/README.md 追踪具体文件。 ## 工作原理 ### 数据流 ` +----------+ +--------------------+ +--------------+ | sources/ |---->| LLM Processing |---->| wiki/ | | (Raw) | | (Extract + Link) | | (Structured) | +----------+ +--------------------+ +--------------+ | v +----------+ | log.md | | (Record) | +----------+ ` ### 关键设计 1. CLAUDE.md 作为协议：定义 Agent 行为标准，任何人/任何 Agent 均可遵循 2. 纯 Markdown：无数据库、无锁定、原生 git 版本控制 3. 双向链接：[[PageName]] 格式，兼容 Obsidian 4. 累积学习：每次查询都可生成新 wiki 页面，知识持续累加 ## 查询机制 ### 当前实现：符号导航 + LLM 合成（默认） 默认情况下，本 SKILL 无需 Embedding/向量检索。查询通过以下方式完成： ` 用户提问 | v +-------------------------------+ | 1. 读取 index.md | <-- 人工/Agent 维护的分类索引 | 定位相关主题 | +-------------------------------+ | v +-------------------------------+ | 2. 读取相关页面 | <-- 通过 [[链接]] 发现关联 | 及其链接邻居 | +-------------------------------+ | v +-------------------------------+ | 3. LLM 合成 | <-- 基于已读内容生成答案 | 带引用生成 | 引用格式：[[PageName]] +-------------------------------+ ` 可选增强：启用 config.yaml 中的 embedding 设置后，CLI query --semantic 会增加混合搜索（关键词匹配 + 向量搜索 + 链接遍历），更快更准。 示例流程：用户问：“什么是 LoRA？” 1. Agent 读取 wiki/index.md，在“AI/ML”主题下找到 [[LoRA]] 2. Agent 读取 wiki/LoRA.md，发现链接到 [[Fine-tuning]]、[[Adapter]] 3. Agent 合成 答案： > LoRA（Low-Rank Adaptation）是一种参数高效微调方法——见 [[LoRA]]。 > 相比传统 [[Fine-tuning]]，它仅训练低秩矩阵…… ### 为何 Embedding 可选？ | 考量 | 当前方案 | Embedding 方案 | |---------------|------------------|-------------------| | 依赖 | 零外部依赖 | 需 Embedding API 或本地模型 | | 成本 | 无额外费用 | 按 token/请求计费 | | 隐私 | 数据不上传 | 必须发送内容到外部服务 | | 准确性 | 精确链接，可解释 | 近似相似，可能召回无关内容 | | 规模 | 适合 0-500 页 | 大规模（1000+ 页）必备 | 结论：个人/小团队知识库，维护好 index.md 与页面链接，比引入 Embedding 更简单有效。Embedding 作为 CLI 可选增强，在规模需要时启用。 ### 何时启用 Embedding？ 当 wiki 出现以下特征时，可考虑启用 config.yaml 中的 embedding 设置： - [ ] 页面数 > 500，人工索引难以维护 - [ ] 查询多为模糊语义（“那篇关于优化的论文……”） - [ ] 需跨主题关联（用户未提关键词，但语义相关） 详见 ROADMAP.md。 ## 使用示例 ### 场景 1：研究新领域 `bash # 第 1 天：添加材料 sources/ ├── 2026-04-10-transformer-paper.pdf └── 2026-04-10-lora-blog.md ` ` 用户：请摄入新材料 Claude：已处理 2 份材料 - 创建 [[Transformer]] —— 注意力机制架构 - 创建 [[LoRA]] —— 低秩适配 - 创建 [[Self-Attention]] —— 自注意力细节 - 更新 wiki/index.md ` ### 场景 2：深度探索 ` 用户：LoRA 和全参数微调有什么区别？ Claude（读取 wiki/index.md → 找到 [[LoRA]] → 合成答案）：基于我们的 wiki： LoRA —— [[LoRA]] - 冻结预训练权重，仅训练低秩矩阵 - 参数量减少约 1 万倍 全参数微调 - 更新全部参数 - 计算成本高 关键区别： 1. 参数量：LoRA 仅训练 0.1%~1% 参数 [[Parameter Efficiency]] 2. 存储：LoRA 仅保存适配器，而非完整模型 3. 组合：可叠加多个 LoRA [[LoRA Composition]] 以上是否有帮助？是否将该回答归档到 wiki？ ` ### 场景 3：知识累积 ` 用户：是的，归档此回答 Claude：已创建 [[LoRA vs Full Fine-tuning]] - 从对话中提取对比要点 - 链接到 [[LoRA]] 与 [[Fine-tuning]] - 添加到 wiki/index.md 的 FAQ 部分 ` ## 与 Obsidian 配合使用 1. 在 Obsidian 中打开 wiki/` 目录 2. 享受图谱视图、快速导航、精美渲染 3. Claude Code 负责维护，Obsidian 负责阅读与思考 ## 与替代品对比 | 方案 | 特点 | 最适合 | |----------|----------------|----------| | 本 SKILL | 零依赖、纯文本、Claude Code 原生 | 个人知识管理、研究笔记 | | Sage-Wiki | 功能完整、多模态、独立应用 | 团队知识库、企业部署 | | Obsidian + 插件 | 可视化强、社区丰富 | 已有 Obsidian 工作流 | | Notion/Logseq | 协作、实时同步 | 多人协作、移动端访问 | ## 文档 - CLAUDE.md —— 用户面向的协议（先读） - AGENTS.md —— 面向 agent 开发者的实现指南 - SKILL.md —— 本文件，机器可读规范 - ROADMAP.md —— 未来计划 ## 贡献 欢迎提 Issue 与 PR！ ### 当前 TODO - [ ] MCP server 包装（供其他 Agent 使用） - [ ] Obsidian 插件（一键同步） - [x] 增量 embedding，更快检索 - [ ] 多语言支持 ## 许可证 MIT —— 自由使用、修改、分发。 --- 灵感源自 Karpathy's llm-wiki*