Skip to main content
Glama

llmwiki-local

llmwiki-local 是独立运行的本地 stdio MCP 服务,让 Codex 等客户端查询 Markdown 知识库、生成预览、确认发布,以及复制已有库并更换向量模型。无需安装 dsh。

代码最初复制自 dsh-llmwiki 的 ff44903,共享建库、存储和查询代码按固定提交同步,独立安装、独立维护。当前预览版本为 0.3.0-preview.10,通过本仓 GitHub Release 独立分发。本版让来源定向补缺在牵涉主题时沿用原主题嵌入成果继续执行;补缺核对未形成可接受结果时保留上一版提取与原判定,在构建日志登记“补缺延后”,续跑时把旧版本留下的无接受来源补缺成果恢复后重新核对;自定义提取档位的未变来源续建时不再重复提取。主题定向恢复新增显式选项 renewReviewWindow,可为核对期限已过的选中主题再授予一次 20 分钟核对窗口,从首次实际续核起算并固定保存,不增加轮次,保留已有修复稿、接受成果与费用记录。更新包后重启 MCP 服务以加载新构建。正式 0.3.0、三库补建与 AC27 查询质量验收另行记录,预览包验证不替代这些验收。适配层负责配置、模型调用与 MCP;package.json 的 repository 记录本仓发布地址,source 记录同源插件的同步依据。许可与第三方声明见 THIRD_PARTY_NOTICES.md。

1. 安装与启动

需要 Node.js ^22.19.0 || >=24.0.0 和 pnpm。本机验证使用 Node.js 24。执行:

Set-Location '<个人资料目录>\ai-projects\llm-wiki\mcp-llmwiki-local'
pnpm install --frozen-lockfile
pnpm run build
node dist/cli.js library add 'E:\资料' --name '我的资料'
node dist/cli.js library list
node dist/cli.js mcp

安装为命令后同样可用 llmwiki-local mcp、llmwiki-local library add <资料目录> [--name <名称>]、library list、library remove <id>。remove 只删登记,不删文件。stdio 服务由客户端启动,stdout 只传协议,诊断日志写 stderr。

Related MCP server: KaaS

2. 配置与模型

首次启动自动生成 ~/.llmwiki-local/config.json;设置 LLMWIKI_LOCAL_HOME 可更换配置目录。文件包含 registry 与 runtime,registry 沿用上游非宿主配置字段;registry.libraries 保存库名、绝对路径、模型与 layered/queryUnderstanding 设置。停止写任务后修改配置,MCP 每次请求重新读取登记;修改 runtime 后重启服务。

配置

默认值与用途

runtime.codexExecutable

codex;Windows 自动查找 npm 安装的原生 codex.exe,也可填写绝对路径

runtime.codexContextWindowTokens

256000;沿用上游已跑通建库参考的保守预算,可按选用模型调整

runtime.deepseekBaseUrl

https://api.deepseek.com/v1,OpenAI 兼容接口

libraries[].models.unified

codex-cli / gpt-6.1-terra;五个建库阶段默认推理 high

libraries[].queryUnderstanding

默认 deepseek-official / deepseek-flash;无调用方变体时辅助理解,失败保留原话

libraries[].layered.localEmbeddingUrl

http://127.0.0.1:11434

libraries[].layered.localEmbeddingModel

qwen3-embedding:0.6b

libraries[].layered.embeddingMode

默认 auto,亦支持 ollama、cloud、none;none 为纯全文

首次生成后随库策略在 data/state/policy.json(旧布局路径保持原样);停止任务后可调整 pageGenerationConcurrency 和 concurrencyLimit,范围均为 1~1000,实际生成并发默认 3,不能超过上限;嵌入供应商闸门保持 50。模型路由和供应商重试、速率设置沿用核心配置校验。

云端向量需显式选择 cloud,并设置 cloudEmbeddingUrl、cloudEmbeddingModel、cloudEmbeddingKeyEnv;最后一项填写环境变量名。查询向量默认冷态等待 10 秒、就绪后等待 2 秒,可在登记的 layered 配置中设置 queryEmbeddingColdTimeoutMs 和 queryEmbeddingTimeoutMs;超时降级不写入一分钟失败缓存,Ollama 查询超时可触发共享后台预热。已有库的向量身份绑定在库内,更换模型使用复制工具。纯全文库仍可生成来源与索引,不调用嵌入;主题组织行为沿用上游全文模式。

历史库若遗漏要点的向量引用,查询会按当前要点正文哈希查找本地缓存,并核对向量对象和完整模型身份后复用;首次查询自动刷新旧检索索引。查询只嵌入查询词,不重新计算资料向量。确实缺失或身份不符的向量仍保留覆盖提示,对应内容可通过全文检索查阅。

可用内存

Ollama 模型建议

8GB 以下

qwen3-embedding:0.6b

16GB 左右

qwen3-embedding:4b

32GB 以上

qwen3-embedding:8b

2.1 环境变量

名称

用途

LLMWIKI_LOCAL_HOME

配置和本地作业回执目录,默认 ~/.llmwiki-local

DEEPSEEK_API_KEY

DeepSeek 官方查询理解密钥;缺失时返回降级标注

LLMWIKI_EMBEDDING_API_KEY

默认云端嵌入密钥变量;也可通过 cloudEmbeddingKeyEnv 指定其他变量

CODEX_HOME

由已安装 Codex CLI 读取其既有配置和登录状态;本服务不修改

兼容模型与嵌入服务支持在本机配置中填写 apiKey,或用 apiKeyEnv 引用进程环境变量,两者互斥。凭据不随库复制或导出,不写入工具参数、作业回执、模型提示词或日志。Codex CLI 沿用本机登录;自动化测试使用假模型,真实库只读联验单独记在项目进度。

2.2 多模型与接受恢复

registry.compatibleProviders 可登记 compatible:<名称>,指定 baseUrl、model、api(openai-completions 或 openai-responses),凭据按上节选择一种方式;registry.embeddingService 使用同一凭据约定。配置文件仍使用原有 { registry, runtime } 外层。两种协议沿用相同的模型路由和日志脱敏规则。

建库阶段策略、线路和并发配额分别来自库策略的 buildModels 与登记的 modelExecution。已接受成果、实际模型、生产记录和升级备份沿用共用核心;暂停后换模型续跑先复用已有成果。旧模型路由和 runtime 配置继续有效。

2.3 首次建库选择颗粒度

这项引导从 0.3.0-preview.2 提供。需求见FR-10,实现与验证状态见项目进度。

首次调用 wiki_generate,尚无成果或恢复任务的新库会返回 selection_required 和档位说明。客户端应先解释差异、询问用户,再携选择调用;收到待选择结果时,生成作业尚未启动。

档位

基础要点上限

覆盖深度

默认核对强度

极简 minimal

5

最关键内容

不做额外提取、主题及矛盾核对

粗放 coarse

10

核心内容

不做额外提取、主题及矛盾核对

适中 balanced

25

重要内容,略去一般细节

关键提取核对、主题核对

标准 standard

50

重要及较重要内容

关键提取核对、主题核对

细致 detailed

75

重要内容和主要细节

全量提取、主题及矛盾核对

精细 fine

100

尽量覆盖全部有据内容

全量提取、主题及矛盾核对

自定义 custom

1~500

用户指定固定上限

联动不超过该上限的最高预设档位

上限不是必须凑足的数量;预设随长文篇幅扩为基础值的 1~4 倍,短文单包请求可能进一步收缩,自定义不扩额。越细通常调用量和耗时越高,实际取决于原文、缺口与复用结果;所有档位都不得编造原文没有的知识。表中核对强度是档位默认值,库中显式设置优先。

用户选择精细后,传入 extractionGranularity: "fine";选择自定义则同时传 extractionGranularity: "custom" 和整数 customPointLimit。已有成果或可恢复任务继续使用原颗粒度,无需重新选择;这两个首次建库参数不能用于修改已有库的档位。扫描不要求选择,登记和只读查阅也不会启动建库。

3. 在 Codex 登记 MCP

把以下示例手动合并到 ~/.codex/config.toml。示例使用当前电脑 Node.js 与构建入口的绝对路径;换电脑时替换这两个路径。本仓库不会修改用户的 Codex 配置。

[mcp_servers.llmwiki-local]
command = 'C:\Program Files\nodejs\node.exe'
args = ['<个人资料目录>\ai-projects\llm-wiki\mcp-llmwiki-local\dist\cli.js', 'mcp']
env_vars = ['DEEPSEEK_API_KEY', 'LLMWIKI_EMBEDDING_API_KEY', 'LLMWIKI_LOCAL_HOME']
startup_timeout_sec = 30
tool_timeout_sec = 120

配置字段参考 Codex MCP 文档。修改后让客户端重新加载 MCP 服务。

4. 工具与操作

工具

用途

wiki_list_libraries

列出启用库与当前卡片、版本

wiki_search

query、library、types、variants、limit、include、excerpt_budget、excerpt_pages 沿用上游

wiki_browse

按 root、主题、来源、章节下钻;cursor 分页

wiki_read

按路径或 ID 阅读,支持来源与已登记分节的 #^块ID,offset/maxChars 分页

wiki_generate

libraryId,可选 action=scan/generate、retrySources、legacyLibraryAction=backup、reextract=all/gaps/来源 ID 数组;立即返回 jobId

wiki_status

jobId;返回进度、缺口、模型调用与 token 成本;includePreview=true 返回逐页变更和 digest

wiki_commit

携带 jobId 与已读预览的 digest,核对版本、策略和资料后发布

wiki_cancel

按 jobId 取消后台任务或预览,已发布版本不回滚

wiki_copy_with_embedding

libraryId、confirm=true、target;复制后只重算向量,立即返回 jobId

wiki_find_library、wiki_library_card

按问题选库、读取库卡片;wiki_list_libraries 传 cursor/limit/groupId 时返回分页短目录

wiki_register_library、wiki_update_library、wiki_unregister_library

按 expectedRegistryRevision 登记、修改或移除库;移除保留文件,运行中禁止更改路径或移除登记

wiki_answer、wiki_source_read

按库或发现结果回答,按来源及定位读取原文;思源返回外部回源提示

wiki_changes、wiki_pause、wiki_retry_topic_gaps

按库检查预览批次、暂停运行和显式重试主题缺口

MCP 共 19 个工具。旧 wiki_status(jobId)、wiki_commit、wiki_cancel 和带 target 的异步复制接口保留;wiki_status(libraryId) 可读取生产记录,复制省略 target 时使用 embeddingService。库卡片还可通过 llmwiki://libraries/{libraryId}/card 资源读取和订阅。

wiki_list_libraries 返回的 libraryId 可直接作为 wiki_search、wiki_browse、wiki_read 和 wiki_source_read 的 library;库名输入继续可用,同名库建议使用 ID。页头格式损坏的页面会从搜索和浏览中隔离,并返回降级提示或 warning;其他来源页与原文仍可读取,直接读取坏页返回格式错误。

原 library add/list/remove 命令保持。新增 libraries list/find/show/register/update/unregister、libraries groups list/save、libraries summary refresh/unlock;请求使用 --json <UTF-8 文件> 或 --json -。命令沿用原配置目录、外层和写锁,修订冲突返回退出码 3。

生成流程:登记资料 → wiki_generate → 轮询 wiki_status → includePreview=true 阅读变更 → 携带 digest 调用 wiki_commit。取消运行任务后应轮询到终态。服务重启会把失去运行进程的任务标为 interrupted;再次生成复用核心持久检查点。完成预览的 jobId 和 digest 可在重启后继续使用。

提取调用因连接、超时、上游流中断、HTTP 429 或 5xx 耗尽重试时,组级缺口标为可重试,普通建库及续跑会自动重提。其他 4xx 按状态码判为永久缺口;内容校验失败的组级缺口保留,可用 reextract=gaps 显式重试。旧缺口没有标记时按原因文本识别。

只补指定已发布来源的摘要或核对缺口时,向 wiki_generate 传 retrySources:

{
  "libraryId": "<libraryId>",
  "retrySources": { "sourceIds": ["S-0001"], "kinds": ["summary"] }
}

sourceIds 和 kinds 均须显式非空;kinds 可选 summary、review,也可同时选择。此操作要求可写的本地 Markdown 分层库,与扫描、重提和旧库备份互斥。摘要补缺复用原分组、配额和要点;没有有效匹配成员的组留下可审计的排除原因。核对只处理尚未核实的要点,沿用有界纠正;证据或可用状态真正改变时才更新已有依赖主题及必要父页。该生成范围不启动补标、术语、标签归并、旧待办聚类或嵌入;新核实但缺少主题归属或缓存向量的点继续保留待办及覆盖缺口。

暂停后再次生成可省略 retrySources,核心继续已保存的来源和种类;传入不同范围会被拒绝。补缺期间原资料集合须保持不变,新增、修改、删除或改名会在模型派发前暂停。完成后仍按上述作业流程阅读预览并提交。未在本轮重建的主题、术语等已有页面继续保留;同一范围没有剩余缺口时再次生成不会产生模型请求或新版本。

问答允许明确返回“本次证据不足”:模型引用数组和正文引用编号都为空时,服务端只返回固定提示,不交付模型的无引用正文。有依据的部分答案仍可返回,并说明其余缺口;引用编号一致不代表事实已被自动核实。引用 Wiki 页优先使用路径和块锚点,原文定位使用来源版本与 #L;搜索正文与补读全文的页头处理不同,不能直接把摘录的 locator 当作文件物理行号。

主题核对只有在正文、成员证据和协议均未变化,且已经取得明确完成结论时复用结果;协议或传输未完成会保留检查点,按有界额度续核或暂停。

复制 target 选择 embeddingMode=ollama 并提供 localEmbeddingModel(可选 localEmbeddingUrl),或选择 cloud 并提供 cloudEmbeddingModel、cloudEmbeddingUrl、cloudEmbeddingKeyEnv。目标目录存在时拒绝覆盖,完成后自动登记副本;该工具不走预览提交。

5. 库布局与兼容

新库默认写在资料目录下 .llmwiki-qwen3-06b,其他模型形如 .llmwiki-qwen3-8b。根目录保留 wiki/、library.yaml、README.md,内部数据存放 data/ 并由 data/layout.json 标记。旧 .llmwiki/ 布局沿用;遇到旧式 Wiki 需要转换时,只在显式 legacyLibraryAction=backup 后备份处理。

资料目录内只有一个模型库时自动登记它;多个模型库时直接传入目标库目录。dsh 与本服务使用相同设备身份、写锁和版本协议:后来的写操作返回正在被占用;并发读写、撤权过滤及人工修改冲突检查沿用核心。

独立 MCP 的异步生成入口开放本地 Markdown 建库,新增来源读取、库管理与批次操作使用共用服务。思源导出、Obsidian 共管、旧式生成与维护代码保留;宿主附件注入、自动维护、keeper 和 dsh 设置页不进入本服务。依赖 dsh 客户端产物与 HTTP 模块的本地网页工作区暂不同步,管理操作使用 CLI/MCP。错误中可能保留上游“设置页/宿主”等文字。

6. 验证与同步

pnpm run typecheck
pnpm run build
pnpm test

测试入口每批最多运行五个实际用例,日志与统计写入系统临时目录。当前验收结果见 项目进度,首次迁移验证保留历史基线;固定提交对照见 源仓库文件对照。同步规则见 AGENTS.md。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes a compiled Markdown knowledge base to MCP-capable coding agents through a single ask tool that returns cited answers grounded in whole wiki articles rather than embedded fragments. Supports local stdio and remote streamable-HTTP transports, with optional bearer-token authentication on the network transport.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents and tools to read and write a repo-local graph datastore over stdio, query it with datalog, and manage nodes such as todos, gaps, rules, and notes.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search and manage a local Markdown memory vault over stdio, including hybrid search, note retrieval and addition, session handoff claiming, and status checks without holding a model in memory.
      MIT