OpenWiki 评测：用 CLI 维护一份给 AI 读的代码库维基

它解决什么问题：文档滞后于代码

代码库文档最常见的死法是写完就过期。OpenWiki 的定位是让文档跟着代码走，而不是等人去改。它不是一个文档生成器，而是一个持续维护工具。README 明确说，它由 Deep Agents 文档代理驱动，能读取源码，生成链接的 Markdown 维基，并在每次变更后更新。目标读者有两个：AI 代理把维基当记忆，人类用可视化界面浏览。所以这不是给 README 加个自动补全，而是一套完整的文档生命周期管理。适用人群是维护大型仓库的团队，或者想把自己的知识库系统化的个人。

两种模式与十三家模型提供商

OpenWiki 提供两种运行模式。code 模式针对仓库，personal 模式针对个人知识。两种模式共用同一套 CLI，但底层生成逻辑不同。模型提供商内置了十三种，从 OpenAI、Anthropic 到 Bedrock、Gemini，以及任何兼容 OpenAI 接口的网关。这意味着你不需要绑定某一家云服务。实际使用时，第一次运行 openwiki --init 会引导你选择提供商、密钥和模型。这个设计降低了上手门槛，但也意味着生成质量高度依赖你选的模型。文档没有说明不同模型间的输出差异，但可以推测，模型能力直接决定 wiki 的准确性。

核心机制：可恢复的页面任务队列

OpenWiki 的架构亮点是它的页面任务队列。README 描述了完整的流程：begin → submit_plan → next_page → submit_page → … → finish。每个页面是一个独立的任务，有持久化的顺序队列。openwiki/.run.json 文件记录当前运行的进度。页面只有在 Markdown、Claims、验证结果和 .page-manifest.json 条目都持久化后，才算完成。这意味着中断后可以恢复，不会丢掉已完成的部分。对于持续集成环境，这个设计很关键，因为 CI 任务经常超时或被取消。它还支持部分进度的 PR，让文档更新可以分批次合并。这种设计比一次性生成整个文档更健壮。

Grounded Claims：追踪事实来源

文档容易出错，因为事实会过时。OpenWiki 用 Grounded Claims 机制来缓解。每个 material fact 都带有版本化的源码证据。当证据文件变化或消失时，系统能定位到哪些命题需要确认、重写或退役。这相当于给文档加了一层溯源。实现上，Claims 在页面生成时持久化，并在更新时比对。这个机制的价值在于，它不只是重新生成文档，而是精确知道哪些内容失效。代价是额外的存储和校验开销。对于小型仓库，这个机制可能显得重，但对于大型项目，它能显著减少人工审查的工作量。

与编码代理集成：换个工作方式

OpenWiki 不一定要自己调用模型。它可以跑在现有的编码代理里，比如 Codex、Claude Code、OpenCode 和 Cursor。安装命令很简单：openwiki integrations install codex，其他同理。安装后，代理用自身的模型和仓库工具来研究代码、规划维基、逐页编写。OpenWiki 负责持久化队列、Claims 验证、来源漂移处理和最终确定。这种模式下不需要 OpenWiki 的提供商凭据，因为用的是代理的认证会话。注意，host-driven 模式只支持 code 维基，不支持 personal 模式。这意味着个人知识库没法享受这种集成。另外，所有集成默认安装在用户级别，所以一次安装，任何仓库都能用。

快速上手：从安装到自动更新

安装要求 Node.js 22 或更新版本。全局安装用 npm install -g openwiki。然后进入仓库目录运行 openwiki --init，它会引导你配置提供商和模型，并生成 openwiki/ 目录。再次运行 --init 会重新生成，但保留你手写的 openwiki/INSTRUCTIONS.md 文件。日常更新用 openwiki --update，它会根据仓库变化和过期的 Claims 来更新文档。要自动化，可以复制 examples/openwiki-update.yml 到 GitHub Actions，或使用 GitLab CI 和 Bitbucket Pipelines 的示例文件。这些 CI 任务会定时运行并打开文档 PR。Windows 用户注意，不要用 bun 安装，因为 better-sqlite3 原生依赖需要 Visual Studio Build Tools。

局限与失败模式

OpenWiki 不是万能的。首先，它依赖模型生成内容，模型可能产生幻觉，所以文档准确性需要抽查。Grounded Claims 能追踪事实，但不能保证事实本身正确。其次，Windows 安装有坑，bun 会触发原生编译，需要额外工具链。第三，CI 环境下的中断恢复有限制：临时 CI 运行器在失败后不会保留工作区，除非你显式保存。这意味着在无状态 CI 上，长时间生成任务可能反复从头开始。第四，personal 模式不支持编码代理集成，功能不对称。最后，生成质量取决于你选的模型，免费或弱模型可能产出低质量文档。

替代方案与选型建议

与 OpenWiki 最接近的替代方案是传统的文档生成器，比如 Docusaurus 或 MkDocs，但它们不自动更新内容，只负责渲染。另一类是 AI 文档工具，比如 Mintlify，它也有自动生成功能，但通常绑定自家平台。OpenWiki 的差异在于它输出 Open Knowledge Format（OKF v0.2），这是一个可移植的格式，带有验证过的 Mermaid 图和确定性生成 provenance。这意味着你可以把 wiki 导出到任何静态托管，不锁定在某个服务。另一个差异是它的双读者设计：AI 代理和人类都通过同一份 Markdown 交互。如果你只需要人类可读的文档，传统工具可能更简单。如果你需要 AI 可读的记忆，OpenWiki 的架构更对口。

编辑结论

OpenWiki 适合那些文档更新频繁、希望让 AI 代理直接读取代码库记忆的工程团队，尤其是已经使用 LangChain 生态或需要自动化文档流水线的项目。个人知识管理场景也可用，但个人模式不支持编码代理集成。不适合对文档生成成本敏感、或无法接受第三方模型读取代码内容的团队。采用前应先验证：Node.js 22 环境是否就绪，Windows 下避免用 bun 安装，以及确认你选择的模型提供商是否支持所需的上下文长度。另外，检查 CI 集成示例中的权限设置，确保定时任务能创建 PR。最后，由于生成内容依赖模型，务必抽查 wiki 中关键 Claims 的准确性，不要完全信任自动生成的文档。

官方来源

1. Official README
2. Project repository
3. Release notes