OpenWiki：为代码库养一座活维基

每个仓库里都埋着一座文档的废墟。README 写于某个雄心勃勃的午后，此后代码迁徙了数十个版本，它仍停在原地，像一块无人认领的碑。后来者路过，读到的全是前朝的地名。

OpenWiki 想治的就是这个病。它由语言链（LangChain）团队开源，底层是深度智能体（DeepAgents）框架，做的事可以概括成一句：把代码仓库编译成一座活着的维基，让文档跟随代码一起迁徙。

把结论钉在证据上

传统文档工具每次运行都全量重写，像每逢换季就把整部史书烧掉重抄，成本高昂，人工批注也随之殉葬。

OpenWiki 的治法接近史学的考据：生成页面时记录每条结论对应的源文件哈希与提交点，称为断言（Claims）。增量刷新时读取 Git 历史，比对代码变动与断言的证据版本，证据失效的页面才交给模型重写，未受波及的页面保持原样。Token 消耗降下来了，人工修订也保住了。

生成过程被建模为可持久化的页面作业（PageJob）队列：规划、逐页生成、断言校验、最终定稿，各有明确的状态边界。中途断电断网，从上次完成的页面继续，前功不弃。

产物是普通 Markdown 文件，存放在仓库的 openwiki/ 目录，符合开放知识格式（OKF，Open Knowledge Format），页面之间以标准链接互联。维基的所有权归使用者，任何编辑器、静态站点或智能体都能直接消费。

给智能体一双按图索骥的眼睛

编码智能体读仓库的常规姿势是全文正则匹配，动辄遍历数百文件，上下文窗口被垃圾信息淹没。

OpenWiki 通过模型上下文协议（MCP）暴露一组本地只读工具，全程不发起模型调用：

• openwiki_search：输入问题，返回紧凑的页面与三级标题锚点，例如 openwiki/methods/ach.md#操作步骤。
• openwiki_read：按页面与锚点读取完整小节切片，滤掉无关段落。
• openwiki_list_workspaces 与 openwiki_list_wikis：跨仓库工作区的发现入口。

先拿锚点，再读切片，命中即停。整个调阅只消耗几百个字符的上下文，考古队换成了精确制导。

其余几件家什

• 交互式图谱：openwiki visualize 在本地回环地址启动节点网状图与 Markdown 阅读器，--export 可导出静态站点，挂到任何静态托管。
• 跨仓库工作区：openwiki link 把多个仓库的维基编入命名工作区，支持跨库联合检索，适合控制面、数据面、基础设施分仓存放的系统。
• 持续集成：官方提供 GitHub Actions 模板，定时比对增量、生成 Pull Request，文档更新进入人工审签流程，与代码评审同轨。
• 多供应商：支持 OpenAI、Anthropic、Gemini、OpenRouter，以及任何 OpenAI 兼容端点，包括月之暗面的 Kimi Code。

与 llm-wiki-agent 的楚河汉界

安德烈·卡帕西（Andrej Karpathy）提出过一种个人维基编译范式，llm-wiki-agent 是它的实现：服务于自由生长的网状笔记库，产出概念页、实体页与综述，深度绑定 Obsidian 双链生态，消费者是人。

OpenWiki 面向契约明确的 Git 仓库与规范化知识：方法库、接口文档、架构基线。它以 Git 差异为更新信号，以断言为质量闸门，消费者是编码智能体与持续集成流水线。

两套系统按仓库属性划界，互不争夺：个人知识库走 llm-wiki-agent 的定时编译链路，代码仓库与方法库交给 OpenWiki。各守其土，各安其位。

一次完整的接入实录

手头一个舆情治理研究仓库刚刚走完全链路：

1. 工作流改配：.github/workflows/openwiki-update.yml 的供应商切换为 openai-compatible，端点 https://api.kimi.com/coding/v1，模型 kimi-for-coding，密钥经 llm-vault 写入仓库 Secret KIMI_API_KEY。
2. 云端验证：手动调度运行 5 分 25 秒，全部步骤通过，自动提交 PR #1，为知识库各分类目录补充索引导航，并准确标注专著页码缺口，已合并入主分支。
3. 本地检索：全局安装 [email protected]，MCP 配置写入 ~/.omp/agent/mcp.json，技能包落位 ~/.omp/agent/skills/openwiki/。实测检索「竞争性假设分析 操作步骤」，返回精确锚点 openwiki/methods/ach.md#操作步骤，stderr 干净。

使用纪律

工具再好，也怕滥用。几条约定：

• 任务启动时不枚举、不预载维基目录。仅在遇到未知架构、依赖行为不明、源码研读存在不确定性时启用检索。
• 检索遵循两阶段协议：先 openwiki_search 拿锚点，再 openwiki_read 读切片，信息对齐后立刻停止。
• 维基内容是辅助上下文，最终结论以源码与测试为准。
• 生成页面遵循 openwiki/INSTRUCTIONS.md 划定的学术边界：页码缺失标注「页码待补」，缺口写入 Backlog，不用推测补齐。

结语

《汉书·艺文志》著录的典籍，传到今天的十不存一。文档与代码的相依为命，历来比人们愿意承认的更难。

OpenWiki 的思路朴素：把每条结论钉在证据上，让证据替文档记得自己从何而来。代码迁徙时，维基随之迁徙；证据失效时，页面自动显形。文档由此摆脱了写成即腐烂的宿命，成为仓库里另一株活着的东西。

养一座活维基，大约就是养一份对后来者的体恤。