llmwiki 本地化部署与知识库使用指南本文档面向第一次接触 llmwiki 的用户从拉取源码到建成自己的知识库一步步照做即可。 环境Windows其他系统路径格式自行替换。 已验证Node 24 npm 11 DeepSeek Anthropic 兼容端点。官方说明文档llmwiki将原始源代码编译成互联维基 - llmwiki〇、先理解三件事1. 这是 Node.js/TypeScript 项目不是 Python 项目不需要创建虚拟环境不需要requirements.txt。需要的是Node.js 24。2. 工具和数据是分开的位置示例作用工具源码D:\llm-wiki-compiler-main装一次别删知识库数据D:\knowledge\kb-xxx你的资料和编译结果可以有多个日常使用是在知识库目录里敲llmwiki xxx不是在源码目录。3. 工作流是三步ingest → compile → 使用把资料放进 sources/ → 编译成 wiki 页面 → 提问 / 浏览 / 导出关键放完资料必须compile否则query什么也查不到。一、环境准备1.1 安装 Node.js 24node -v :: 必须输出 v24.x.x不是 24 的话用 nvm-windows 或 volta 装一个nvm install 24 nvm use 241.2 确认 npm 全局目录npm config list找到这一行示例; user config from C:\Users\用户名\.npmrc prefix D:\nodejs\node_global⚠️记下这个prefix路径第 6 步配置 PATH 要用。 如果没配置过默认是C:\Users\用户名\AppData\Roaming\npm。1.3 配置 npm 国内镜像npm config set registry https://registry.npmmirror.com npm config get registry :: 应输出 https://registry.npmmirror.com二、拉取源码git地址atomicstrata/llm-wiki-compiler: The knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathys LLM Wiki pattern.cd /d D:\ git clone https://github.com/atomicstrata/llm-wiki-compiler.git llm-wiki-compiler-main cd /d D:\llm-wiki-compiler-main用 ZIP 下载解压也可以目录名保持llm-wiki-compiler-main即可。三、安装依赖cd /d D:\llm-wiki-compiler-main npm install预期输出added XXX packages, and audited XXX packages3.1 忽略无关提示以下都是提示不是错误N vulnerabilities→ 间接依赖安全提示不要跑npm audit fix --forceNew major version of npm available→ 忽略不要升级3.2 批准被拦的 esbuild 脚本关键npm 11.17 默认拦截依赖的 postinstall 脚本esbuild 需要执行它npm approve-scripts esbuild不处理的话构建时可能报 esbuild 相关错误。四、构建项目cd /d D:\llm-wiki-compiler-main npm run build预期生成dist/目录看到Build success。验证dir .\dist\cli.js两种构建方式命令用途npm run build一次性构建日常用这个npm run dev监听模式改源码自动重建只在改代码时用五、链接为全局命令cd /d D:\llm-wiki-compiler-main npm link预期输出added 1 package验证全局文件已生成dir 第一步记下的 prefix 路径\llmwiki*本文档环境示例dir D:\nodejs\node_global\llmwiki*应看到三个文件llmwiki llmwiki.cmd llmwiki.ps1六、配置 PATH可以忽略这是npm配置混乱的报错解决问题npm link成功后敲llmwiki仍报「不是内部或外部命令」。原因npm 全局 bin 目录prefix指向的位置不在系统 PATH 里。6.1 把 npm 全局目录加入 PATH本文档环境需加入D:\nodejs\node_global操作图形界面Win R→ 输入sysdm.cpl→ 回车「高级」→「环境变量」用户变量里找到Path→ 编辑新建 → 粘贴D:\nodejs\node_global→ 一路确定关闭所有 CMD 窗口关键PATH 只对新进程生效新开 CMD 验证where llmwiki :: 应输出 prefix\llmwiki.cmd llmwiki --help :: 应打印帮助信息⚠️ 其他环境把D:\nodejs\node_global换成你第 1.2 步prefix的实际值。七、配置 LLM 环境变量llmwiki 调 LLM 需要凭据。本文档以 DeepSeek 的 Anthropic 兼容端点为示例。7.1 必需变量在「系统变量」或「用户变量」里新增变量名值示例说明ANTHROPIC_API_KEYsk-xxxxxx你的 API keyANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic中转地址LLMWIKI_MODELdeepseek-flash关键模型名必须匹配中转支持的⚠️模型名用LLMWIKI_MODEL不是ANTHROPIC_MODEL。llmwiki 只认前者。7.2 为什么模型名必须匹配如果模型名不对会报Error: 400 The supported API model names are deepseek-flash, deepseek-v4-pro, but you passed DeepSeek-V4.1-Flash.原因llmwiki 内置默认名与中转支持的不一致。解法用LLMWIKI_MODEL显式覆盖。先临时验证不改系统变量set LLMWIKI_MODELdeepseek-flash llmwiki --help确认可行后再永久写进系统环境变量并重开 CMD。7.3 验证echo %ANTHROPIC_API_KEY% echo %ANTHROPIC_BASE_URL% echo %LLMWIKI_MODEL%八、验证工具可用cd /d C:\ llmwiki --help看到完整命令列表 部署成功。九、llmwiki 完整命令速查9.1 数据摄入命令说明llmwiki ingest 文件或URL把资料放进sources/llmwiki ingest-session path导入 Claude/Codex/Cursor 会话记录llmwiki quickstart source一步完成 ingest compile 打开界面9.2 编译与构建命令说明llmwiki compile增量编译源文件成 wiki 页面llmwiki compile --review生成页面暂存待审llmwiki watch监听 sources/ 自动重编译9.3 查询与使用命令说明llmwiki query 问题提问获取带引用的答案llmwiki query 问题 --save提问并把答案存回 wikillmwiki view --open打开浏览器界面先 cd 到项目目录llmwiki context prompt --json为 Agent 构建证据包llmwiki serve启动 MCP 服务器9.4 导出与导入命令说明llmwiki export --target format导出 json / llms.txt / GraphML / Marp 等llmwiki import --okf dir导入 OKF 知识包9.5 项目维护命令说明llmwiki status看项目状态页面数、源数、过期页面等llmwiki lint质量检查断链、孤页、低置信度llmwiki review list查看待审候选llmwiki refresh --stale修复过期页面llmwiki next只读提示下一步推荐操作llmwiki rm source删除源及其派生页面9.6 常用选项--jsonstatus、next等支持 JSON 输出--lang Chinese指定输出语言--concurrency n并行数--review启用审查模式十、开始建第一个知识库⚠️知识库要建在源码目录之外。10.1 建目录cd /d D:\ mkdir knowledge cd knowledge mkdir kb-myfirst cd kb-myfirst10.2 加资料两种方式任选方式 A用ingest推荐会自动建sources/llmwiki ingest D:\某资料.md :: 或 llmwiki ingest https://en.wikipedia.org/wiki/某条目方式 B手动放mkdir sources copy D:\某资料\*.md sources\ :: 或手动建一个 notepad sources\test.md⚠️ 资料必须放在sources/子目录里不能直接放知识库根目录。10.3 确认资料进来了llmwiki status应看到Sources: 1 ← 大于 0 才对10.4 编译llmwiki compile预期看到Extracting: xxx.md等日志最后Build success。如果报No sources found→ 说明资料没放对位置见 10.2。 如果报400 ... model names→ 见第七章设置LLMWIKI_MODEL。10.5 再确认llmwiki status应看到Pages: N concept(s), M quer(y/ies) — X total ← X 0 Sources: 1 Last compiled: 日期10.6 使用llmwiki query 资料的核心内容是什么 llmwiki view --open十一、日常使用流程11.1 平时在知识库目录里cd /d D:\knowledge\kb-myfirst llmwiki status :: 看状态 llmwiki query 问题 :: 提问消耗 API llmwiki view --open :: 打开浏览器界面 llmwiki lint :: 质量检查11.2 加新资料时cd /d D:\knowledge\kb-myfirst llmwiki ingest D:\新资料.md llmwiki compile :: 增量编译只处理变动的源11.3 工具维护极少用cd /d D:\llm-wiki-compiler-main npm run build :: 重新构建 npm run dev :: 改源码时开监听 npm link :: 换目录后重新链接十二、多知识库管理推荐结构D:\knowledge\ ← 总文件夹 ├── kb-work\ ← 知识库1 │ ├── sources\ │ │ ├── a.md │ │ └── b.md │ ├── wiki\ │ └── .llmwiki\ ├── kb-study\ ← 知识库2 │ ├── sources\ │ └── ... └── kb-research\ ← 知识库3 └── ...使用规则cd到哪个库llmwiki就操作哪个库各库完全独立互不干扰没有跨库查询要分开查新建一个库cd /d D:\knowledge mkdir kb-new cd kb-new llmwiki ingest D:\资料.md llmwiki compile十三、常见问题速查现象原因解法llmwiki不是内部或外部命令PATH 未包含 npm 全局目录见第六章改后重开 CMDNo sources foundsources/为空或资料放错位置用ingest或放对sources/子目录400 ... model names模型名不匹配设LLMWIKI_MODELdeepseek-flash401 / 403key 无效或环境变量未生效重开 CMDecho %ANTHROPIC_API_KEY%unknown option --rootview不支持指定 root先cd到项目目录再viewCannot find module依赖没装全npm install重跑esbuild command failed脚本被拦npm approve-scripts esbuildAssertion failed ... async.cNode 异常退出连带崩溃通常是 400 的果修好模型名即消失关掉 dev 窗口命令还能用吗能dist 已生成只有改源码才需 dev重启电脑后还能用吗能环境变量和全局命令都持久化十四、必须保留的东西删了命令就废保留项位置dist/目录D:\llm-wiki-compiler-main\dist\node_modules/D:\llm-wiki-compiler-main\node_modules\全局命令入口prefix\llmwiki*如D:\nodejs\node_global\llmwiki*环境变量ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、LLMWIKI_MODEL你的知识库D:\knowledge\kb-xxx\真正的数据记得备份十五、完整流程图① 安装 Node 24 ② npm 换国内镜像 ③ git clone 源码到 D:\llm-wiki-compiler-main ④ npm install ⑤ npm approve-scripts esbuild ⑥ npm run build ⑦ npm link ⑧ 把 npm 全局目录加入 PATH重开 CMD ⑨ 配置 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL / LLMWIKI_MODEL重开 CMD ⑩ llmwiki --help 验证 ──────────────────────────────── ⑪ 建知识库目录 D:\knowledge\kb-xxx ⑫ cd 进去用 llmwiki ingest 放资料或复制到 sources/ ⑬ llmwiki compile ⑭ llmwiki query 问题 / llmwiki view --open十六、核心概念小结概念含义ingest把资料放入sources/compile调 LLM 把源编译成结构化 wiki 页面query从编译好的 wiki 检索 LLM 生成带引用的答案view本地只读浏览器界面增量编译用 SHA-256 哈希只重编译变动的源省 API 成本引用溯源答案里每句带[[引用]]可校验有效性一句话工作流ingest→compile→query/view加新资料重复前两步。文档结束。按 ①→⑭ 顺序执行任何人即可完成 llmwiki 的本地部署并建成自己的知识库。RAG 与 llmwiki 对比精简版核心差异传统 RAGllmwiki思路查询时现找现答编译时造知识再查检索对象原始文本 chunk结构化 wiki 页面建库方式切分→embedding→向量库自己搭放资料→compile一条命令产物向量库不可读Markdown可读、可 Git知识积累答完即丢--save存回越用越厚增量更新每次重检索SHA-256 哈希只编变动源引用溯源弱靠 LLM 编强可校验 broken适合规模大到百万级个人/小团队百篇级权限/治理✅ 支持 RBAC❌ 整库模式时效性✅ 实时⚠️ 需重新 compile一句话区分RAG每次现找现答适合海量、高频变动、需权限控制的工业场景。llmwiki先编译成书再查适合个人知识沉淀、需要溯源和积累的场景。llmwiki 四个关键命令命令作用何时用query 问题 --save沉淀答案到wiki/queries/得到有复用价值的结论时lint检查断链、坏引用、孤儿页每次compile后、接入 CIrefresh --stale只重编译过期页面lint报告 stale 时export --target okf导出为开放知识格式分享、迁移、备份这四个命令是 RAG 体系里没有对应物的能力也是 llmwiki 越用越值钱 的核心。结论RAG 解决百万文档如何安全准确地找到答案llmwiki 解决个人知识如何越用越厚。前者是工业级检索基础设施后者是知识管理哲学目标不同可以互补。