LLMWIKI--个人知识库的本地化使用-拓冰网站定制

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 24+

node -v :: 必须输出 v24.x.x

不是 24 的话，用 nvm-windows 或 volta 装一个：

nvm install 24 nvm use 24

1.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 Karpathy's 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 packages

3.1 忽略无关提示

以下都是提示，不是错误：

N vulnerabilities→ 间接依赖安全提示，不要跑npm audit fix --force
New 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_KEY`	`sk-xxxxxx`	你的 API key
`ANTHROPIC_BASE_URL`	`https://api.deepseek.com/anthropic`	中转地址
`LLMWIKI_MODEL`	`deepseek-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_MODEL=deepseek-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`	提问并把答案存回 wiki
`llmwiki 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 常用选项

--json：status、next等支持 JSON 输出
--lang Chinese：指定输出语言
--concurrency <n>：并行数
--review：启用审查模式

十、开始建第一个知识库

⚠️知识库要建在源码目录之外。

10.1 建目录

cd /d D:\ mkdir knowledge cd knowledge mkdir kb-myfirst cd kb-myfirst

10.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 全局目录	见第六章；改后重开 CMD
`No sources found`	`sources/`为空或资料放错位置	用`ingest`，或放对`sources/`子目录
`400 ... model names`	模型名不匹配	设`LLMWIKI_MODEL=deepseek-flash`
`401 / 403`	key 无效或环境变量未生效	重开 CMD；`echo %ANTHROPIC_API_KEY%`
`unknown option '--root'`	`view`不支持指定 root	先`cd`到项目目录再`view`
`Cannot find module`	依赖没装全	`npm install`重跑
`esbuild command failed`	脚本被拦	`npm approve-scripts esbuild`
`Assertion failed ... async.c`	Node 异常退出连带崩溃	通常是 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 对比（精简版）

核心差异

传统 RAG	llmwiki
思路	查询时现找现答	编译时造知识，再查
检索对象	原始文本 chunk	结构化 wiki 页面
建库方式	切分→embedding→向量库（自己搭）	放资料→`compile`（一条命令）
产物	向量库（不可读）	Markdown（可读、可 Git）
知识积累	答完即丢	`--save`存回，越用越厚
增量更新	每次重检索	SHA-256 哈希，只编变动源
引用溯源	弱，靠 LLM 编	强，可校验 broken
适合规模	大到百万级	个人/小团队（百篇级）
权限/治理	✅ 支持 RBAC	❌ 整库模式
时效性	✅ 实时	⚠️ 需重新 compile

一句话区分

RAG：每次现找现答，适合海量、高频变动、需权限控制的工业场景。
llmwiki：先编译成书再查，适合个人知识沉淀、需要溯源和积累的场景。

llmwiki 四个关键命令

命令	作用	何时用
`query "问题" --save`	沉淀答案到`wiki/queries/`	得到有复用价值的结论时
`lint`	检查断链、坏引用、孤儿页	每次`compile`后、接入 CI
`refresh --stale`	只重编译过期页面	`lint`报告 stale 时
`export --target okf`	导出为开放知识格式	分享、迁移、备份

这四个命令是 RAG 体系里没有对应物的能力，也是 llmwiki "越用越值钱" 的核心。

结论

RAG 解决"百万文档如何安全准确地找到答案"；llmwiki 解决"个人知识如何越用越厚"。前者是工业级检索基础设施，后者是知识管理哲学，目标不同，可以互补。

资讯详情

LLMWIKI--个人知识库的本地化使用