文档老过时?OpenWiki 让 Agent 替你写,代码改了它自己跟着改

代码改了一版又一版，文档还停在第一版。新来的人问接口怎么调，没人说得清，最后只能去翻源码。OpenWiki 的解法：Agent 读仓库源码→生成结构化 wiki→代码变了只重写受影响的页面→人只管审。

OpenWiki 做了什么

OpenWiki 是 LangChain 出品的 Node.js CLI（MIT 开源，GitHub 1.58 万星），基于 LangChain 的 Deep Agents（多步骤 Agent 编排，https://github.com/langchain-ai/deepagentsjs）。它做的事情用一句话讲：读取仓库源码，Agent^[1] 自动生成并维护 Markdown wiki，代码变了文档跟着变。

两种模式：

本文重点讲 code 模式——团队场景下用得最多。

首次 openwiki --init 后，仓库里多出这些文件：

和"手动写文档 + AI 润色"的本质区别：代码是事实的来源，文档是代码的忠实映射。wiki 正文不需要人写，Agent 自己读代码、自己生成、自己维护。

国内可用路径：OpenWiki 默认用 OpenAI API（gpt-5.6-terra），但支持 13 个模型提供商。国内开发者可以在 --init 时选对应提供商：

选好提供商后配置一次，后续运行自动复用。

Grounded Claims：行号级追踪，替代页面粒度的"最后更新时间"

传统文档工具只记录"这个页面上次是什么时候生成的"。OpenWiki 追踪的是文档里每一条关键事实——函数的行为、模块的职责、数据流的走向——精确到源码的哪一行。这个机制叫 Grounded Claims。

每个 Claim 的结构：

Claims 覆盖的内容：函数/模块的行为和职责、架构关系和数据流、不变量（系统必须始终满足的约束）和失败语义（出错时的行为）、配置要求和安全边界。只有"未来的 Agent 可能依赖的关键事实"才会被追踪，普通描述不会变成 Claim。

openwiki --update 的执行顺序：

这解决了一个实际问题：代码量改变了但文档还对，或者代码量没变但关键事实变了。行号级别的 evidence 追踪让更新决策更精确，避免每次全量重新生成。

页面完成是持久化边界。OpenWiki 在持久化 Claims、同步页面版本、完成整体验证之后才标记该页完成。最终确认（即所有页面完成后的整仓验证）还需要再跑一轮全量验证，验证通过后才删除运行状态文件。

编程 Agent 集成：让 Claude Code 来写文档

OpenWiki 支持在 Claude Code、Codex、OpenCode、Cursor 内部直接运行。此时编程 Agent 做仓库研究和写作，OpenWiki 管理 Claims 生命周期和持久化。

一行安装：

安装后重启编程 Agent，在仓库里直接说：

更新已有 wiki：

分工明确：编程 Agent 有完整的仓库访问权，负责研究源码、规划页面、逐页写作；OpenWiki 负责管理 Claims 的创建、更新、保留和撤销，以及页面持久化和验证。底层五步操作——openwiki_begin、submit_plan、next_page、submit_page、openwiki_finish——由 OpenWiki 暴露给编程 Agent，两端的职责完全分开。

免去额外配置：不需要单独配 OpenWiki 的 API Key。编程 Agent 用自己已认证的模型 session，OpenWiki 只管文档生命周期。

实际效果：v0.3 重写 prompt 后成功率从 35% 提升到 45%（+28.57%，n=2，样本量小仅反映趋势方向），编程 Agent 集成写出的文档与原生生成质量对齐。

CI 自动更新：文档 PR 自动开，人只管审

OpenWiki 提供三套 CI 模板，都在仓库 examples/ 目录下：

具体文件名以仓库 examples/ 目录为准。

自动化流程：定时检测变更 → 更新 wiki → 自动开文档 PR → 人审完合并。不直接合并，保留人工审查。

两个重要细节：

no-op 运行零开销。代码没变时只更新 .last-update.json，不碰页面，不发 PR。

可恢复架构。生成过程按有状态的页面队列推进，每页完成后独立持久化。openwiki/.run.json 记录运行断点，中断后重跑从断点续跑，不重复已完成页面。但要注意：CI 临时环境（每次全新 checkout）失败后必须从头开始，除非 workspace 做了持久化。

国内 CI 适配：官方模板覆盖 GitHub/GitLab/Bitbucket；国内其他 CI 平台需自行编写 workflow，核心命令仍是 openwiki --update。

竞品对比：Agent 写 vs 人写 vs AI 辅写

先按核心思路分类，再同类对比。

同类对阵（Agent 主导 vs AI 辅写）：

异类互补说明：Mintlify 做 API 文档站的阅读体验和交互式 playground 比较好，OpenWiki 做代码仓库文档自动化比较好，两个互相补充而非互相替代。已有 Mintlify 做 API 文档站的团队，可以用 OpenWiki 补上代码仓库内部文档这块短板。

可视化：节点图 + Markdown 阅读器

本地启动一个服务（127.0.0.1，默认 4321 端口），浏览器打开交互式节点图 + Markdown 阅读器并排。节点是 wiki 页面，边是页面间的链接，点击节点在右侧读对应内容。编辑 wiki 文件后自动刷新。

导出静态站点：

产出 index.html + client.js + graph.json，直接部署到 GitHub Pages、MkDocs 或任何静态托管。

现在的边界