本文是「LLM Wiki 实战」系列第 3 篇。
上一篇用一批火电报告跑了完整实战。本篇拆解四个最有工程含金量的功能,讲清楚它们背后到底怎么运作——算法、依赖、配置、代码组织,而不只是「点这个按钮」。

如果你只看 UI,LLM Wiki 像是个「导入 PDF → 聊天」的普通应用。但底下有四个模块决定了它的上限,也是本文要拆的:

1. 知识图谱 + Louvain 社区检测 —— 四信号关联度模型
2. MCP Server —— 把 Claude Code / Codex 接进你的知识库
3. 深度研究 —— 自我发现知识空白并联网补全
4. 两步思维链摄入 —— 质量和可维护性的秘密

---

亮点一:知识图谱与四信号关联度模型

问题: wikilink 之外,怎么衡量「两个页面有多相关」?

原始 Karpathy 方法论只有 [[wikilink]] 一种关联。但现实中两个页面可能没有直接链接,却共享同一份原始资料(来源重叠),或共享很多共同邻居(Adamic-Adar)。LLM Wiki 设计了一个四信号加权模型:

信号	权重	含义
来源重叠	×4.0	两页共享同一原始资料(靠 frontmatter sources[] 匹配)
直接链接	×3.0	通过 [[wikilink]] 相连
Adamic-Adar	×1.5	共享共同邻居,且按邻居度数倒数加权
类型亲和	×1.0	同类型页面加分(实体↔实体、概念↔概念)

最终关联度 = Σ(信号命中 × 权重)。这个分数同时用在三个地方:图谱边的粗细/颜色(绿=强、灰=弱)、查询时的图谱扩展(第 4 篇详述)、知识空白的桥接节点识别。

注意权重的设计哲学:来源重叠(×4.0)权重最高,因为「同源」是最强的语义证据——它来自结构化数据(frontmatter),不是 LLM 猜的链接。直接链接(×3.0)次之。Adamic-Adar 和类型亲和是补充信号。这种「结构化证据优先于推断」的排序,是工程上很稳的选择。

可视化技术栈

前端用 sigma.js + graphology 做图渲染,ForceAtlas2(graphology-layout-forceatlas2)做力导向布局。几个工程细节:

• 节点大小按度数 √ 缩放(不是线性,避免枢纽节点过大撑爆画布)
• 边按关联度分数映射粗细和颜色
• 位置缓存:数据更新时不重跑布局,防止节点「跳来跳去」
• 悬停时邻居保持可见、非邻居变暗,是 sigma 的典型交互模式

对应前端代码在 src/components/graph/。

Louvain 社区检测

光有节点和边还不够,你需要知道「这些页面自然分成几簇」。LLM Wiki 用 Louvain 算法(graphology-communities-louvain)做社区检测——它只看链接拓扑,独立于预定义的页面类型,所以能发现「按类型看不出来,但确实是一组」的知识聚类。

切换「类型 / 社区」两种着色模式,你能对比两种视角:按类型看是人为分类,按社区看是知识实际连成的样子。两者不一致的地方,往往就是值得审视的边界。

内聚度评分给每个社区打分:

内聚度 = 社区内实际边数 / 社区内可能边数(= n(n-1)/2)

低于 0.15 的社区(且 ≥ 3 个页面)会被标警告——意思是这几页虽然被算法归到一起,但彼此交叉引用很薄弱,知识还没真正串联起来。12 色调色板保证不同社区视觉上可区分。

图谱洞察:惊奇连接与知识空白

在图谱结构之上,系统自动产出可操作的洞察:

• 惊奇连接:跨社区边、跨类型链接、边缘↔核心耦合,按复合惊奇度排序。这是「你以为没关系、其实关系很强」的发现。
• 知识空白:
  • 孤立页面(度 ≤ 1)—— 被提取出来却没展开的实体
  • 稀疏社区(内聚度 < 0.15)—— 串联薄弱的领域
  • 桥接节点(连 3+ 集群)—— 维系多个领域的关键枢纽

每个洞察卡片都能点击在图谱里高亮对应节点和边;知识空白和桥接节点还带 Deep Research 按钮,这就引出下一个亮点。

---

亮点二:MCP Server —— 把 Claude Code 接进你的知识库

一句话理解 MCP

MCP(Model Context Protocol)是让 AI 客户端(如 Claude Code、Cursor、Codex)调用外部工具的标准协议。LLM Wiki 内置了一个 MCP Server(mcp-server/),装上之后,你的 AI Agent 就能直接读写、检索你的知识库——而不是每次把文件复制粘贴进对话。

关键架构决策:不重复造轮子

MCP Server 的 README 里有一句很关键的话:

It does not scan project folders directly and does not copy the app’s search or graph logic. Every tool calls the local desktop API at http://127.0.0.1:19828/api/v1.

也就是说,MCP Server 是个薄封装——它自己不实现搜索、不实现图谱遍历、不直接碰文件系统,所有操作都转发给桌面应用内置的 HTTP API。好处很明显:MCP 客户端用的项目和 app 用的是同一套项目注册表、文件权限、搜索后端、图谱后端、Source Watch 规则。不会出现「Agent 看到的和 App 看到的不一致」。

数据流是这样的:

Claude Code ──MCP协议──▶ mcp-server(node)──HTTP──▶ 桌面App API(127.0.0.1:19828)──▶ Rust后端
                                                                                 (search / graph / fs)

八个工具

工具	作用
llm_wiki_status	健康检查 + 当前项目概要
llm_wiki_projects	项目列表 + 活跃项目
llm_wiki_files	列出项目文件(project_id 可传 UUID、路径或 current)
llm_wiki_read_file	读允许的文本文件(如 wiki/index.md)
llm_wiki_reviews	列出审核项(默认未处理,支持状态/类型/数量过滤)
llm_wiki_search	复用 app 的关键词+向量混合检索
llm_wiki_graph	查询知识图谱
llm_wiki_rescan_sources	触发 Source Watch 重新扫描

注意 llm_wiki_search 和 llm_wiki_graph 直接复用 app 后端——Agent 拿到的检索结果和你手动搜的完全一致。

三步接入

1. 在 App 里开启 API + MCP(设置 → API + MCP):勾选「Enable local HTTP API」和「Enable MCP access」,生成一个 Token(或选允许本机无鉴权)。

2. 构建 MCP Server:

cd mcp-server && npm install && npm run build
# 产物:mcp-server/dist/src/index.js

3. 在 MCP 客户端配置里注册。Claude Code 的配置(路径换成你机器上的绝对路径):

{
  "mcpServers": {
    "llm-wiki": {
      "command": "node",
      "args": ["/absolute/path/to/llm_wiki/mcp-server/dist/src/index.js"],
      "env": {
        "LLM_WIKI_API_TOKEN": "your-token"
      }
    }
  }
}

开启无鉴权模式时,省掉 LLM_WIKI_API_TOKEN。App 的「设置 → API + MCP」会自动填好你当前机器的真实入口路径,直接复制即可。

安全模型

技术博主会关心安全。这个 MCP Server 继承了桌面 API 的安全模型,有几条硬约束:

• 只监听 127.0.0.1 —— 只本机可达,不暴露到网络
• Token 鉴权(或显式开启无鉴权)
• 文件读走 allow-list —— 内部应用状态文件不暴露
• Token 用环境变量传,不要走命令行参数(避免出现在 shell history)

还有一条更省事的路径:Agent Skill

如果你不想手写 MCP 配置,LLM Wiki 还配套了一个 agent skill,一行命令装进 Claude Code / Codex:

npx skills add https://github.com/nashsu/llm_wiki_skill.git --skill llm_wiki_skill

装完就能对 Agent 说「我的 wiki 里关于 X 是怎么说的」「在我的知识库里搜 Y」「展示图谱里 Z 的邻居」,它默认只读,并引用 wiki 页面路径方便你核对。

顺带一提,Rust 后端(src-tauri/src/commands/)里还有 claude_cli.rs 和 codex_cli.rs——App 自己也能把 claude / codex CLI 当子进程拉起(tokio + which 定位二进制),流式回传 stdout。也就是说接入是双向的:既能让 Agent 查 App,也能让 App 调 Agent。

---

亮点三:深度研究 —— 自我发现并补全知识空白

触发点

深度研究不是无脑联网,它有明确的触发场景:

1. 图谱洞察 —— 点知识空白/桥接节点上的 Deep Research 按钮
2. 审核队列 —— 处理 LLM 标记的「需要补资料」项
3. 手动 —— 你主动想研究某个主题

主题生成:为什么不是泛泛关键词

普通联网搜索的通病是查询太泛(比如直接拿「调峰 环保」去搜),结果噪音大。LLM Wiki 的做法是让 LLM 先读 overview.md + purpose.md 获取领域上下文,再生成研究主题和针对搜索引擎优化的多条查询。

[overview.md + purpose.md]
        │ LLM 读取领域上下文
        ▼
研究主题(领域精准) + 多条搜索查询(SEO 友好)
        │ 可编辑确认框(你可改主题和查询)
        ▼
Tavily / SerpApi / SearXNG 多查询并发搜索,返回完整内容
        │ LLM 综合
        ▼
Wiki 研究页 + 交叉引用现有 wiki
        │ 自动走两步摄入
        ▼
新实体/概念吸进知识网络

那个可编辑确认框是关键设计——LLM 生成的主题和查询你先过目、可修改,确认后才花钱去搜。把「确认权」留给人类,避免 Agent 跑偏烧 API 额度。

Provider 各自配置

三个搜索 Provider 独立配置,各有适配:

• Tavily —— 自己的 API Key,专为 AI 优化的搜索
• SerpApi —— 自己的 API Key,可选搜索引擎(Google/Bing/…),抓完整内容而非截断摘要
• SearXNG —— 自建实例 URL + 搜索分类,完全自托管、无 Key

任务队列最多 3 个并发,专用侧边面板实时流式进度,综合过程中的 <think> 块(针对 DeepSeek、QwQ 等会输出思维链的模型)显示为可折叠区域。

闭环价值

深度研究把「发现空白 → 补全」自动化了。结合上一篇火电案例:报告偏安全/寿命,对「调峰环保影响」着墨少 → 图谱标为稀疏 → 一键研究 → 联网补全 → 自动入库 → 知识网络更完整。知识库开始自我生长。

---

亮点四:两步思维链摄入 —— 质量的秘密

为什么拆成两步

原始方法论是「LLM 同时阅读和写入」的单步摄入——一边理解一边生成,质量不稳定。LLM Wiki 把它拆成两次顺序 LLM 调用:

第一步:分析(只读不写)

LLM 阅读资料,产出结构化分析:

• 关键实体、概念、论点
• 与现有 Wiki 内容的关联(能链到哪些已有页面)
• 与现有知识的矛盾和张力(主动发现冲突)
• Wiki 结构建议(该建/更新哪些页)

第二步:生成(基于分析写)

LLM 基于第一步的分析,产出:

• 带 frontmatter 的资料摘要页(type / title / sources[])
• 实体页、概念页及 [[wikilink]] 交叉引用
• 更新 index.md、log.md、overview.md
• 审核项(需人工判断的)和深度研究搜索查询

拆两步的好处是关注点分离:第一步专注「理解 + 找关联 + 找矛盾」,第二步专注「按 schema 规范落地」。这比让模型一次性「边读边写」质量高得多,也更容易让生成结果符合 schema 约束。

配套的工程保障

光拆两步还不够,摄入管线还有几个保障可靠性的机制:

• SHA256 增量缓存 —— 摄入前算源文件哈希,没变就跳过。省 token,也避免重复覆盖。
• 持久化串行队列 —— 严格串行,防止并发 LLM 调用同时改 wiki 文件导致覆盖;队列落盘,崩溃/重启自动恢复;失败重试最多 3 次。
• 15 分钟超时 —— 长 PDF 的两步摄入可能要几分钟,超时设宽,不误判失败。
• 保证资料摘要生成 —— 兜底机制,即使第二步 LLM 漏了摘要页,也强制创建。
• 语言感知 —— 按你配置的语言(中文/英文)生成 wiki 内容。
• overview.md 自动重生成 —— 每次摄入后刷新全局概要,反映最新状态。

---

小结

这四个亮点合在一起,构成了 LLM Wiki 区别于「又一个 RAG 套壳」的工程含金量:

• 四信号关联度 + Louvain 让知识结构可视化、可分析,而不只是存起来
• MCP 让你的知识库成为 AI Agent 的一等工具,融入 Claude Code 工作流
• 深度研究 让知识库能自我补全,而不是被动等投喂
• 两步摄入 用关注点分离 + 工程保障,把「自动构建」这件事做得可靠

下一篇也是最后一篇,我们再往底层挖一层:三层架构的职责边界、四阶段检索管线的数据流、关联度算法的具体计算、缓存与队列的实现——把整个系统的运作原理讲透。

---

系列下一篇:技术原理剖析 —— 三层架构与四阶段检索管线