OpenWiki：让 AI Agent 给代码库写一本带证据链的活维基

AI 编码 Agent 什么都不缺，唯独缺可靠的项目上下文。README 三个月没更新、核心模块的设计只存在于某位已离职工程师的脑子里、让 AI 现场读代码总结——写出来的东西没人敢信。文档的问题从来不是没人写，而是没人养。

OpenWiki 是 LangChain 今年 6 月底开源的一个 CLI，定位一句话："A living wiki for your code, your agents, and you"。它让 AI Agent 系统性地研究你的代码库，产出一份互相链接的 Markdown 维基——关键在于它不只生成，还持续维护：源码一变，它知道哪些"事实"过期了，下次更新只重写受影响的部分。

这个项目上线三个多月拿下 17k+ stars，底层由 LangChain 自家的 DeepAgents 驱动，而且仓库里的 openwiki/ 目录就是它自己给自己写的文档——一条彻底的吃狗粮路线。本文拆解它的核心设计。

本文大纲：

1. OpenWiki 是什么：从"生成文档"到"维护文档"
2. Grounded Claims：让文档的每句话都可溯源
3. 两种模式与两种驱动方式
4. MCP 生命周期：一场有状态的写作会话
5. 工程细节：断点续跑、并行 worker 与源码漂移
6. 上手：从 npm install 到 CI 定时更新

OpenWiki 是什么：从"生成文档"到"维护文档"

市面上"AI 生成文档"的工具不少，共同的问题是产出一次性的、无法验证的 Markdown。OpenWiki 把重心放在另外两件事上：

一是维护。 openwiki --update 从上次成功运行以来的代码变更和过期 Claims 出发做增量更新，而不是每次推倒重来。

二是可信。 维基每页的事实都以 Claims（带证据的陈述）形式持久化，每个 Claim 指向带版本号的源码证据，例如 repo://src/server.ts#L40-L82。证据变了或没了，OpenWiki 能定位到"哪些陈述需要确认、重写或废弃"。

分工也很清晰：在你的编码 Agent 驱动 OpenWiki 时，Agent 负责调查仓库、规划维基、用自己的原生工具写每一页；OpenWiki 负责"记账"——durable queue、Claims 校验与持久化、源码漂移处理、索引与溯源元数据的确定性收尾。智能和簿记分离，是整个项目最值得借鉴的架构决策。

Grounded Claims：让文档的每句话都可溯源

Grounded Claims 是 OpenWiki 的信任基石，覆盖未来 Agent 依赖的各类"真相"：行为、职责、架构、数据流、不变量、失败语义、配置和安全边界。三个设计点值得展开：

记录的是证据版本，不是文件时间。 每个 Claim 记下它建立时所观察到的源码版本，而不是仅凭 Markdown 文件的修改时间判断新旧。更新前，OpenWiki 会先核查每一条持久化的证据版本——这一步甚至发生在判断"这次是否 no-op"之前。某条 Claim 的证据过期了，它所属的页面就必须返工，哪怕规划器没把它列入计划。

更新是稀疏的，不是全量重写。 页面 worker 只会收到"需要处理的 Claims"，依然有效的 Claims 被确定性地保留，不反复占用模型上下文。worker 明确确认复核过的 Claims、只提交修订和新增、点名要废弃的 Claims——这套稀疏决策（确认/修订/新增/撤回）让增量更新既省 token 又不引入幻觉。

页面完成是一个持久化边界。 只有当页面的 Markdown、Claims、验证记录和 openwiki/.page-manifest.json 条目全部落盘，这一页才算完成。整个运行收尾前还要再做一次全量证明，然后才删除 openwiki/.run.json。

落盘格式也讲究：两种模式都输出 Google Open Knowledge Format (OKF) v0.2 bundle，Claims 证据被投影进 front matter 的 sources 字段，verified 戳只有在 Claims 全集通过最终证据复核并持久化后才会打上——所以维基可以被任何 OKF 兼容工具读取，信任元数据跟着文件走。

两种模式与两种驱动方式

OpenWiki 的使用面由两条正交的轴组成。第一条轴是 Mode：

模式	记录什么	写到哪里	启动方式
code（默认）	当前仓库	仓库内的 openwiki/	openwiki --init
personal	你连接的外部知识源	~/.openwiki/wiki	openwiki personal --init

code 模式的维基随代码一起提交，团队共享、CI 可用；personal 模式更像你的私人知识库，把连接的外部源整理成跨项目笔记。

第二条轴是 Driver——谁来驾驶生成过程：

• Host-driven：把 OpenWiki 装进你已有的编码 Agent。集成覆盖 10 种主流工具：Codex、Claude Code、OpenCode、Cursor、IBM Bob / Bob Shell、Kiro、Oh My Pi、Antigravity、GitHub Copilot CLI 和 Pi。这种方式直接复用 Agent 已认证的模型会话和仓库工具，不需要再配置任何模型 provider。
• Native：OpenWiki 自带基于 DeepAgents 的文档 Agent，openwiki --init 首次运行时引导你选择 provider、凭证和模型，支持 13 家模型 provider，包括托管网关和 Ollama、LM Studio 这类本地 OpenAI 兼容端点。

MCP 生命周期：一场有状态的写作会话

Host-driven 模式下，OpenWiki 以 MCP server 的身份暴露一套生命周期工具，把"写维基"变成一场有状态、可审计的会话：

sequenceDiagram
    participant A as Coding Agent
    participant W as OpenWiki
    A->>W: openwiki_begin
    W-->>A: repo context + writing rules
    A->>W: openwiki_submit_plan
    loop each page
        A->>W: openwiki_next_page
        W-->>A: page spec + source baseline
        Note over A: research code and draft page
        A->>W: openwiki_submit_page
        W->>W: persist markdown + claims durably
    end
    A->>W: openwiki_finish
    W->>W: final proof, delete .run.json

几个细节值得注意：

• OpenWiki 有权"拒收"：在最终状态落盘之前，它拒绝 finish。宿主 Agent 每页只提交稀疏的 Claim 决策，未受影响的 Claims 由 OpenWiki 保留，显式的确认、修订、新增、撤回被逐条应用。
• 按需审查：openwiki_inspect_page_claims 可以随时查看某页的完整 Claims 状态，适合大范围重写前的尽职调查。
• 检索工具是本地、只读、零模型的：openwiki_search 返回紧凑的排序结果，openwiki_read 取回完整章节，openwiki_list_workspaces 和 openwiki_list_wikis 负责跨仓库发现。它们不会触发生成运行，也不自己调用模型——查询维基和写维基在成本上是两回事。

开启了 LangSmith tracing 时，规划器和每个页面 worker 是独立的 trace，按 run 归入同一条 thread；从 CI 触发的运行还可以用 OPENWIKI_TRACE_THREAD_ID 把 thread 和触发提交关联起来，排查质量问题时能直接定位到那次运行。

工程细节：断点续跑、并行 worker 与源码漂移

OpenWiki 的仓库生成是一条"有序队列里独立持久化的页面任务"，这带来三个工程性质：

可恢复。 活跃运行和进度被 openwiki/.run.json 检查点化，中断后重跑同一命令会从 durable page queue 续跑，已完成的页面是恢复单元。setup 阶段就失败的话，旧维基原样保留——不会出现"跑一半把文档弄坏了"的状态。

可并行。 原生模式支持 1 到 8 个页面 worker（OPENWIKI_PAGE_CONCURRENCY，默认 1，建议从 2-4 起步）：

OPENWIKI_PAGE_CONCURRENCY=4 openwiki --update

每个 worker 恰好拥有一个页面；quickstart 页面被刻意排到最后写，因为它要链接到它路由的所有页面。更有意思的是限速自适应：某个 worker 撞上 provider 限流，整个运行的并发度自动减一，正在写的页面被还原、留给下次更新——而不是盲目重试把限流烧成封号。

可自愈。 源码漂移的处理循环如下：

flowchart TD
    A[openwiki --update] --> B{recheck every claim evidence}
    B -->|all evidence current| C[no-op run, refresh .last-update.json]
    B -->|stale or missing evidence| D[invalidate owning pages]
    D --> E[workers rewrite affected pages only]
    E --> F{markdown + claims + manifest durable?}
    F -->|crash| G[resume queue from .run.json]
    G --> E
    F -->|yes| H[whole-run proof, delete .run.json]

注意 no-op 路径：证据全部有效时，这次运行完全不调用模型，只刷新 .last-update.json——文档不会因为例行更新而抖动。

连维基里的 Mermaid 图都有自愈机制：每次运行后验证所有 mermaid 代码块，验证失败的图会被原地降级为带注释的 text 块（而不是渲染出一个坏图），下一次 --update 发现注释后自动修复——质量随着运行次数单调回升。

文档主权的边界设计

"AI 帮你写文档"最让人担心的是失控：它会不会覆盖你手写的内容？会不会把私有代码写进文档？OpenWiki 在这几处都画了清晰的线：

• 只管理自己的地盘。每次 code 运行维护仓库根部的 AGENTS.md（若仓库已有 CLAUDE.md 则刷新它），但只改写 <!-- OPENWIKI:START -->…<!-- OPENWIKI:END --> 标记块，其余内容原封不动。
• 你的 brief 说了算。openwiki/INSTRUCTIONS.md 是用户手写的范围与优先级说明，正常运行时只读不写；重新 --init 会重建生成的维基，但这份文件会被保留。
• 读取有边界。仓库根部的 .openwikiignore 语法与 gitignore 同源（支持 */** glob 和 ! 反选），被忽略的路径不会被读取、扫描或复述进文档——当然作者也诚实标注了边界：Agent 仍可能从测试、README 等允许的证据推断出被忽略区域的存在。
• 配置留在本地。provider 选择、密钥、LangSmith 开关保存在本机 ~/.openwiki/.env。

上手：从 npm install 到 CI 定时更新

完整走一遍 host-driven 路线只需要三步：

npm install -g openwiki
openwiki integrations install claude   # 或 codex / cursor / opencode ...

重启你的编码 Agent，打开仓库，说一句 "Initialize this repository's OpenWiki from the current source and tests"，Agent 就会研究仓库并写出第一版维基。之后日常是这样用的：

• 查询：直接让 Agent "Search this repository's OpenWiki for how retry handling works"，它通过 openwiki_search/openwiki_read 检索后回答。
• 跨仓库：openwiki link 把多个仓库的维基编成一个命名 workspace（比如 Payments = 控制面 + 数据面 + 基础设施），Agent 可以跨整个服务搜索并精确读取某个成员 wiki 的章节。
• 可视化：openwiki visualize 起一个仅监听 loopback 的本地服务，交互式节点图谱加实时 Markdown 阅读器，编辑维基时图谱同步更新；--export 还能导出静态目录挂到 GitHub Pages。
• 持续保鲜：把官方提供的 workflow 模板放进 .github/workflows/openwiki-update.yml，定时跑 openwiki --update 产出 docs-only PR；成功后才启用 auto-merge，失败的运行会把部分成果留在 PR 里并撤销待合并状态。GitLab CI 和 Bitbucket Pipelines 也有现成模板。

一个印证设计的细节：OpenWiki 仓库自己的 openwiki/ 目录就是它生成的——concepts/、architecture/、workflows/、operations/ 分类下躺着 grounded-claims、two-modes、agent-runtime、source-map 等页面，外加 .claims/ 和 .page-manifest.json 两份机器可读的元数据。文档即代码库的一部分，跟代码一起评审、一起演进。

适用场景与边界

OpenWiki 最适合这几类场景：接手陌生的大型代码库（先让 Agent 写维基再干活）、多仓库服务的统一上下文（workspace 跨库检索）、团队知识随代码演进（CI 定时更新替代"文档周会"）。

也要认清边界：Claims 机制目前只覆盖仓库代码证据，来自 LangSmith 等连接器的事实暂不带 Claim；host-driven 模式还不支持 personal 模式；生成和更新都要消耗真实的模型 token，维基质量的上限取决于你选的模型。它不打算取代 README 和 ADR——架构决策记录依然该由人写，OpenWiki 养的是"这个系统现在是什么样"的那部分事实。

---

作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。