1. 从「导入 PDF 就能聊」到四个工程模块：LLM Wiki 到底强在哪
LLM Wiki 表面看是个「导入 PDF → 聊天」的普通应用，但真正决定它上限的是底下四个模块：知识图谱构建、MCP 接入、深度研究流程、两步思维链摄入。这篇不聊 UI 按钮，直接拆工程实现路径，并给出 TaoToken 统一 Key/API 通道在config.toml与settings.json中的可复制配置骨架，最后附上 MCP 服务连通性验证动作，让你在本地把 Wiki 增强链路跑通。
适合谁看：已经在用 Claude Code / Codex 做知识管理、想把自己的 Wiki 变成 Agent 一等工具、或者单纯想搞清楚「知识图谱 + MCP + 深度研究 + 两步摄入」这四个词背后到底怎么落地的人。我试过把一批火电报告丢进去跑完整链路，踩过的坑基本都集中在配置和连通性上，所以这篇会把配置骨架写全，你照着改路径就能复现。
核心检索词先对齐：知识图谱负责把页面关系量化成可计算的边权；MCP 负责让外部 Agent 读写你的知识库；深度研究负责自动发现知识空白并联网补全；两步摄入负责把「边读边写」拆成「先分析、再生成」，保证质量和可维护性。四个模块不是并列功能，而是一条从摄入到检索再到自我补全的链路。
2. TaoToken 前置：统一 Key/API 通道为什么先配
在拆四个模块之前，先把模型通道配好。LLM Wiki 的两步摄入、深度研究综合、主题生成都要调 LLM，如果每个环节各配一套 Key，后面排障会非常痛苦。TaoToken 提供统一 Key/API 通道，一个 Key 走完所有模型调用，配置集中在一处，出问题只看一个地方。
官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
API 基址：https://taotoken.net/api （不加 UTM）
你需要先拿到 Key，再去控制台确认模型可用性。拿 Key 的入口在 API Keys 页面，模型可用性可以在模型对话里先手动验证一次，确认通道通了再写进配置文件。这一步别省，很多人后面报 401 或模型不存在，其实都是 Key 或模型名没对齐。
注意：Key 用环境变量传，不要写死在会进版本控制的文件里，也不要走命令行参数，避免出现在 shell history。
3. 可复制配置：config.toml 与 settings.json 骨架
LLM Wiki 的配置分两处：config.toml管模型通道和摄入管线参数，settings.json管 MCP 客户端注册。下面给的是骨架，路径和 Key 换成你自己的。
3.1 config.toml：模型通道与摄入参数
# config.toml [llm] # TaoToken 统一通道 base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" # 从环境变量读取，不写明文 model = "claude-sonnet-4-20250514" # 换成你控制台确认可用的模型名 timeout_seconds = 900 # 两步摄入长 PDF 可能几分钟，超时设宽 [ingest] two_step = true # 开启两步思维链摄入 sha256_cache = true # 增量缓存，源文件没变就跳过 serial_queue = true # 持久化串行队列，防并发覆盖 max_retries = 3 # 失败重试 ensure_summary = true # 兜底：强制生成资料摘要页 language = "zh" # 语言感知，按此生成 wiki 内容 [research] provider = "tavily" # tavily / serpapi / searxng max_concurrency = 3 # 任务队列最多 3 并发 confirm_before_search = true # 主题和查询先人工确认再花钱搜 [graph] louvain = true # 社区检测 cohesion_warn_threshold = 0.15 # 内聚度低于此值且页面≥3 标警告环境变量这样设：
export TAOTOKEN_API_KEY="你的Key"3.2 settings.json：MCP 客户端注册
{ "mcpServers": { "llm-wiki": { "command": "node", "args": ["/absolute/path/to/llm_wiki/mcp-server/dist/src/index.js"], "env": { "LLM_WIKI_API_TOKEN": "your-token", "TAOTOKEN_API_KEY": "your-key" } } } }args里的路径换成你机器上的绝对路径。开启无鉴权模式时，省掉LLM_WIKI_API_TOKEN。App 的「设置 → API + MCP」会自动填好当前机器的真实入口路径，直接复制更省事。
3.3 构建 MCP Server
cd mcp-server npm install npm run build # 产物：mcp-server/dist/src/index.js构建完确认产物存在，再往 settings.json 里填路径。路径写错是 MCP 连不上的头号原因。
4. 四个模块的工程实现拆解
4.1 知识图谱：四信号关联度模型
wikilink 之外怎么衡量「两个页面有多相关」？LLM Wiki 用四信号加权：
| 信号 | 权重 | 含义 |
|---|---|---|
| 来源重叠 | ×4.0 | 两页共享同一原始资料（frontmatter sources[] 匹配） |
| 直接链接 | ×3.0 | 通过 [[wikilink]] 相连 |
| Adamic-Adar | ×1.5 | 共享共同邻居，按邻居度数倒数加权 |
| 类型亲和 | ×1.0 | 同类型页面加分（实体↔实体、概念↔概念） |
最终关联度 = Σ(信号命中 × 权重)。这个分数同时用在三处：图谱边的粗细/颜色、查询时的图谱扩展、知识空白的桥接节点识别。
权重设计哲学值得记一下：来源重叠权重最高，因为「同源」来自结构化数据（frontmatter），不是 LLM 猜的链接；直接链接次之；Adamic-Adar 和类型亲和是补充。结构化证据优先于推断，工程上很稳。
可视化用 sigma.js + graphology 渲染，ForceAtlas2 做力导向布局。节点大小按度数 √ 缩放，避免枢纽节点撑爆画布；边按关联度映射粗细和颜色；数据更新时不重跑布局，防止节点跳来跳去。
Louvain 社区检测只看链接拓扑，独立于预定义页面类型，能发现「按类型看不出来、但确实是一组」的聚类。内聚度 = 社区内实际边数 / 社区内可能边数（n(n-1)/2），低于 0.15 且页面 ≥3 的社区会被标警告，意思是这几页虽被归到一起，但交叉引用薄弱，知识还没真正串联。
4.2 MCP 接入：薄封装 + 复用后端
MCP Server 的关键架构决策是不重复造轮子：它自己不实现搜索、不实现图谱遍历、不直接碰文件系统，所有操作转发给桌面应用内置的 HTTP API（http://127.0.0.1:19828/api/v1）。好处是 MCP 客户端和 App 用同一套项目注册表、文件权限、搜索后端、图谱后端，不会出现「Agent 看到的和 App 看到的不一致」。
数据流：
Claude Code ──MCP协议──▶ mcp-server(node) ──HTTP──▶ 桌面App API(127.0.0.1:19828) ──▶ Rust后端(search/graph/fs)八个工具覆盖状态检查、项目列表、文件列表、读文件、审核项、搜索、图谱查询、重新扫描。其中llm_wiki_search和llm_wiki_graph直接复用 app 后端，Agent 拿到的检索结果和你手动搜的完全一致。
安全模型几条硬约束：只监听 127.0.0.1，只本机可达；Token 鉴权或显式无鉴权；文件读走 allow-list，内部应用状态文件不暴露；Token 用环境变量传。
不想手写 MCP 配置的话，还有 Agent Skill 路径：
npx skills add https://github.com/nashsu/llm_wiki_skill.git --skill llm_wiki_skill装完就能对 Agent 说「我的 wiki 里关于 X 是怎么说的」，默认只读并引用页面路径方便核对。
4.3 深度研究：先确认再花钱
深度研究不是无脑联网，触发场景有三类：图谱洞察里的知识空白/桥接节点按钮、审核队列里 LLM 标记的「需要补资料」项、你主动研究某主题。
主题生成不是泛泛关键词。普通联网搜索通病是查询太泛，噪音大。LLM Wiki 让 LLM 先读overview.md+purpose.md获取领域上下文，再生成研究主题和针对搜索引擎优化的多条查询：
[overview.md + purpose.md] │ LLM 读取领域上下文 ▼ 研究主题(领域精准) + 多条搜索查询(SEO 友好) │ 可编辑确认框(你可改主题和查询) ▼ Tavily / SerpApi / SearXNG 多查询并发搜索，返回完整内容 │ LLM 综合 ▼ Wiki 研究页 + 交叉引用现有 wiki │ 自动走两步摄入 ▼ 新实体/概念吸进知识网络那个可编辑确认框是关键设计：LLM 生成的主题和查询你先过目、可修改，确认后才花钱去搜。把确认权留给人类，避免 Agent 跑偏烧额度。
三个 Provider 独立配置：Tavily 自己的 Key，专为 AI 优化；SerpApi 自己的 Key，可选搜索引擎，抓完整内容而非截断摘要；SearXNG 自建实例 URL + 搜索分类，完全自托管无 Key。任务队列最多 3 并发，侧边面板实时流式进度，综合过程中的<think>块显示为可折叠区域。
4.4 两步摄入：关注点分离
原始方法论是「LLM 同时阅读和写入」的单步摄入，一边理解一边生成，质量不稳定。LLM Wiki 拆成两次顺序 LLM 调用：
第一步分析（只读不写）：LLM 阅读资料，产出关键实体、概念、论点；与现有 Wiki 内容的关联（能链到哪些已有页面）；与现有知识的矛盾和张力；Wiki 结构建议。
第二步生成（基于分析写）：带 frontmatter 的资料摘要页（type / title / sources[]）；实体页、概念页及[[wikilink]]交叉引用；更新index.md、log.md、overview.md；审核项和深度研究搜索查询。
拆两步的好处是关注点分离：第一步专注「理解 + 找关联 + 找矛盾」，第二步专注「按 schema 规范落地」。比让模型一次性边读边写质量高得多，也更容易符合 schema 约束。
配套工程保障：SHA256 增量缓存（源文件没变就跳过，省 token 也避免重复覆盖）；持久化串行队列（严格串行防并发改文件覆盖，队列落盘崩溃自动恢复，失败重试最多 3 次）；15 分钟超时（长 PDF 两步摄入可能几分钟，超时设宽不误判）；保证资料摘要生成（兜底强制创建）；语言感知；overview.md每次摄入后自动重生成。
5. 验证请求与成功结果
配置写完别急着跑全量，先做连通性验证。
5.1 验证 TaoToken 通道
curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: $TAOTOKEN_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'返回里有content字段且无error，说明通道通了。如果报 401，检查 Key；报模型不存在，去模型对话里确认模型名。
5.2 验证 MCP 服务连通性
先确认桌面 App 的本地 API 在监听：
curl -s http://127.0.0.1:19828/api/v1/status \ -H "Authorization: Bearer $LLM_WIKI_API_TOKEN"返回健康状态和当前项目概要，说明 App API 正常。再验证 MCP Server 能起来：
node /absolute/path/to/llm_wiki/mcp-server/dist/src/index.js进程能启动不报错，说明产物和依赖没问题。最后在 Claude Code 里发一句「llm_wiki_status」，能返回项目概要，整条链路就通了。
5.3 验证两步摄入
丢一个小 PDF 进项目，观察日志：第一步分析产出实体和关联，第二步生成摘要页和交叉引用，overview.md自动刷新。源文件再摄入一次，SHA256 缓存命中直接跳过，说明增量缓存生效。
6. 本篇常见错排查
MCP 连不上：九成是args路径写错。确认mcp-server/dist/src/index.js存在，用绝对路径。其次是 Token 没传或传错，检查LLM_WIKI_API_TOKEN环境变量。
401 / 模型不存在：Key 没设或设错，或者config.toml里的模型名和控制台确认的不一致。先去模型对话里手动验证一次。
摄入卡住不动：长 PDF 两步摄入可能几分钟，先等。超过 15 分钟看队列日志，可能是串行队列里前一个任务失败重试。检查max_retries和网络。
图谱边全是灰的：关联度分数低，说明页面间来源重叠和直接链接少。检查 frontmatter 的sources[]是否填了，wikilink 是否真的链上了。
社区内聚度警告刷屏：低于 0.15 的社区被标警告是正常的，意思是这些页面交叉引用薄弱。用深度研究补全，或者手动加 wikilink 串联。
深度研究搜出来一堆噪音：检查overview.md和purpose.md是否填了领域上下文，主题生成依赖它们。确认框里手动改查询再搜。
Token 出现在 shell history：别用命令行参数传 Token，改用环境变量或配置文件读取。
7. 把链路跑起来之后
四个模块合在一起，构成 LLM Wiki 区别于「又一个 RAG 套壳」的工程含金量：四信号关联度 + Louvain 让知识结构可视化可分析；MCP 让知识库成为 AI Agent 的一等工具，融入 Claude Code 工作流；深度研究让知识库自我补全，而不是被动等投喂；两步摄入用关注点分离 + 工程保障，把自动构建做得可靠。
配置骨架已经给全，接下来就是改路径、设环境变量、跑连通性验证。排障和接入相关的入口在 API Keys 和接入文档；想先验证模型可用性，去模型对话手动发一次请求；长期编码和 Agent 场景，Coding Plan 更合适。链路跑通后，你会发现知识库开始自我生长，而不是每次手动复制粘贴。
