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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址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你的Key3.2 settings.jsonMCP 客户端注册{ 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 Servercd 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 APIhttp://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.mdpurpose.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 更合适。链路跑通后你会发现知识库开始自我生长而不是每次手动复制粘贴。
