llm-wiki：把零散研究编译成可查询知识库的 agent 插件
LLM-compiled knowledge bases for any AI agent. Parallel multi-agent research, thesis-driven investigation, source ingestion, wiki compilation, querying, and artifact generation.
秒懂
- 它是什么？
- 它把「收集资料、写成条目、按项目审计」这套流程交给 agent 执行，用 Markdown 目录存结果。适合已经在用 Claude Code 或 Codex 做长期研究的人，不适合只想做一次性问答的人。
- 适合谁用？
- 如果你已经在 Claude Code、Codex 或 OpenCode 里做跨周的选题研究，并且愿意让知识以 Markdown 目录的形式落在本地，llm-wiki 的采集、编译、审计链路值得装一次试试，从 `claude plugin install wiki@llm-wiki` 或 `codex plugin marketplace add nvk/llm-wiki` 开始。如果你的需求只是对几篇文档做一次问答，或者你的团队不允许 agent 直接写本地目录，这个项目就是错的工具，用普通的检索增强流程更省事。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它要解决的是研究散落在会话里这个问题
用 agent 做研究的人大多遇到过同一种损耗：上周让它查过的东西，这周要重新讲一遍背景。对话历史不会变成可检索的资产，换一个 agent 运行时更是从零开始。llm-wiki 的定位就是把这段工作外化成文件，README 的措辞是「LLM-compiled knowledge bases for any AI agent」，编译结果放在 wiki 目录里，由 agent 反复读写。
它面向的不是通用问答用户。README 描述的流程是采集原始资料、编译成条目、按主题查询、再生成交付物，中间还有审计环节。这套流程默认你会围绕某个主题持续投入几周，主题本身有边界，比如硬件钱包威胁模型这类可以不断加料的题目。如果你只是想知道某个 API 怎么用，装它属于杀鸡用牛刀。
项目用 Python 写成，MIT 许可，默认分支 master。发布节奏值得注意：v0.24.4 与 v0.24.3、v0.24.2 之间分别只隔了四天和一天，说明当前仍在快速调整接口和契约，而不是进入稳定期。
从想法到项目：两级结构是它的核心设计
README 里有一句容易被略过的描述：先捕获粗略的想法，研究并打磨，然后显式地把获批的 brief 提升为交付项目。这句话决定了整个数据模型的形状，也解释了 v0.18.0 引入 `/wiki:portfolio` 的动机。
也就是说，wiki 里的东西不是平铺的笔记，而是分成 Idea、Project、Concept 三类记录。Idea 是还没成型的东西，Project 是明确立项、有交付目标的，Concept 作为支撑性知识存在。README 特别强调 portfolio 视图会区分「显式提升的项目」和「直接创建的项目」，并且刻意避免推断血缘关系。这个取舍很清楚：它宁可让用户手动声明一条记录属于哪个项目，也不让 agent 猜。代价是你要多做一步提升动作，收益是你不会在某天发现 agent 把两条无关的笔记合并成了一个主题。
同一段说明里还提到避免「catch-all topics」和重复记录。这反过来是它的一个隐含约束：主题划分得太粗，wiki 的价值会迅速下降，因为所有东西都往一个筐里扔。
多运行时适配是靠技能文件而不是靠抽象层
README 的架构小节标题是「Claude-first, multi-runtime」，这个顺序不是随便写的。Claude Code 走原生插件，一条 `claude plugin install wiki@llm-wiki` 就装完。Codex 走插件市场，需要先 `codex plugin marketplace add nvk/llm-wiki`，再 `codex plugin add wiki@llm-wiki`，并且要开新线程才能用 `@wiki` 或 `$wiki-query`。OpenCode 更轻，只是在 `opencode.json` 的 `instructions` 数组里指向一个远程 SKILL.md 的 URL。
三种接入方式的差异不只是命令不同。OpenCode 每次会话开始都会重新拉取那个 URL，所以技能定义永远是最新的，代价是你依赖 GitHub 的可用性，并且权限要自己配：README 给出的示例是给 `~/.config/llm-wiki/**` 和 iCloud 下的 wiki 路径加 `permission.external_directory` 的 allow 规则。Claude Code 和 Codex 则是把插件缓存到本地，升级要靠 `codex plugin marketplace upgrade llm-wiki` 这类命令手动触发。
Codex 这边还有一个容易踩的点，README 的 troubleshooting 明确写了：`codex plugin marketplace add` 只是注册目录，真正安装并启用的是 `codex plugin add wiki@llm-wiki`。另外，如果你想让会话自动捕获生效，需要去 `/hooks` 里审阅并信任随插件附带的 hook；不信任也不影响 `@wiki` 技能本身使用。
查询和研究会走两条不同的技能
README 把入口分成 `$wiki-query` 和 `@wiki` 两个技能，这个划分比表面看起来重要。`$wiki-query` 被描述为「small, explicit, read-only」，它不会隐式激活，也不会修改 wiki 文件，你必须显式输入 `$` 再选它。`@wiki` 则是完整的研究与维护入口，README 说自然语言提出的 wiki 请求仍然可能自动激活它。
这个设计实际上是在用技能边界替代权限系统。只读查询走一个永远不会写盘的通道，研究、采集、审计走另一个可能改文件的通道。对多人共享一个 wiki 目录的场景，这个区分比配置文件里的开关更可靠，因为它不依赖模型判断该不该动手。
命令面上，README 列出的动作包括 `research`、`collect`、`ingest`、`audit`、`session status`、`feedback list --unpromoted` 以及 `ll`。其中 `@wiki collect "bitcoin memes" --wiki memes-bitcoin` 这一条显示了 `--wiki` 参数用于指定目标主题，`@wiki audit --project coldcard-threat-model` 则说明审计是按项目粒度执行的。`@wiki feedback list --unpromoted` 对应前面提到的提升机制，用来查看还没被提升的反馈或想法。
v0.19 到 v0.22 的私有适配器协议说明了它的边界在哪
连续四个版本的 changelog 都在讲同一件事：把供应商相关的东西从公开插件里挪出去。v0.19.0 引入一个机器本地的、需要显式信任的适配器注册表和 `llm-wiki-adapter/v1` JSON 契约，带清单握手、路径范围、净化过的环境变量和哈希校验的产物。v0.20.0 加上远程写入的治理，包括精确的远程资源白名单、绑定了计划哈希的显式批准、幂等键和私有回执。v0.21.3 是边界过渡。v0.22.0 让适配器自己声明意图和精确 URL 路由，公开插件只负责在采集前发现路由。
这条演化线透露出一个明确的产品判断：认证、浏览器操作、恢复流程、编辑工作流这些东西不放进公开仓库。README 在 v0.23.0 的说明里也写了，公开版本只包含个人专家框架，个人专家包和 wiki 派生的候选报告都不随版本发布。
对使用者的含义是，如果你需要接入某个需要登录态的站点，公开插件本身不会替你完成认证。你得自己承担适配器那一层。这是它有意留下的边界，不是待补的缺口。
几个需要提前知道的限制
第一，README 明确写 OpenCode 配置「sync- and budget-tested, but not tied to one model」，也就是说它没有针对特定模型调优过。不同模型驱动同一套技能，产出质量的波动要你自己承担。
第二，会话记忆依赖 hook 信任。在 Codex 下如果你不去 `/hooks` 里确认，自动捕获就不会发生，而 `@wiki session status` 之类命令反映的是捕获状态。想关掉的话 README 给了 `@wiki session disable`。
第三，v0.24.0 引入的项目知识检查点导出有一个很强的约束：README 原文写 checkpoint 写入「never authorize commit, publication, or import」。这意味着导出动作不会顺带把东西提交或发布出去，你需要另走一步。导出路径是 `docs/knowledge/<slug>/`，并且是先 dry-run 再创建或刷新，带只读校验和有界导入。这个设计偏保守，对自动化流水线来说会显得啰嗦。
第四，版本迭代速度快本身就是成本。v0.24.2 的标题是「Safe Index Contract Repair」，v0.24.3 是「Privacy-Sensitive Log Retraction」，这类修复说明索引契约和日志内容在这之前出过问题。跟着升级意味着偶尔要处理这类变更。
和直接往 Obsidian 里写笔记的差别
最接近的替代方案不是另一个 agent 插件，而是你自己维护一个 Obsidian vault，再让 agent 直接读写它。llm-wiki 声称 Obsidian-compatible，说明它没有把用户锁在专有格式里，产物就是 Markdown。
差别在于流程由谁保证。自己维护 vault 时，采集、去重、按项目归档、审计这些动作靠你的习惯；llm-wiki 把它们写成技能和命令，由 agent 按固定入口执行，并且用 Idea、Project、Concept 的分类和显式提升动作来约束结构。代价是你接受它的分类模型和目录约定，而不是自己那套。
如果你的笔记结构已经稳定运行了几年，换成 llm-wiki 的分类法不一定划算。它的价值主要体现在「结构还没定，但研究量已经在涨」的阶段。
谁该装，装之前先确认什么
已经在 Claude Code、Codex 或 OpenCode 里做跨周主题研究，并且希望知识以本地 Markdown 形式沉淀的人，是这套东西的目标用户。反过来，只做一次性问答、或者团队政策不允许 agent 写本地目录的人，不该引入它，因为它的核心动作就是让 agent 往 wiki 目录里写编译结果。
动手前确认三件事：运行时是否在 README 列出的范围内；wiki 目录放在哪里，OpenCode 下要在 `permission.external_directory` 里显式放行；是否接受会话自动捕获，不接受就在 Codex 里执行 `@wiki session disable`。
许可方面，仓库标注 MIT，插件本身可以自由使用和修改。但要注意 v0.23.0 之后公开版本只包含框架，个人专家包不随版本发布，如果你依赖的是适配器那一层，需要自己评估那部分代码的来源和授权，这不是 MIT 标签能覆盖的范围。
编辑结论
如果你已经在 Claude Code、Codex 或 OpenCode 里做跨周的选题研究，并且愿意让知识以 Markdown 目录的形式落在本地，llm-wiki 的采集、编译、审计链路值得装一次试试，从 `claude plugin install wiki@llm-wiki` 或 `codex plugin marketplace add nvk/llm-wiki` 开始。如果你的需求只是对几篇文档做一次问答，或者你的团队不允许 agent 直接写本地目录，这个项目就是错的工具，用普通的检索增强流程更省事。上手前先确认三件事：你的 agent 运行时是否在 README 列出的四个之内，wiki 目录打算放在哪里（OpenCode 的 `permission.external_directory` 需要显式放行路径），以及你是否接受每次会话自动捕获（不接受就在 Codex 里执行 `@wiki session disable`）。
社区笔记