文档总过期？LangChain OpenWiki：AI 自己写、自己更新

摘要：OpenWiki 让一个文档 Agent 读你的代码库，生成一份互联的 Markdown wiki，再通过 CI 随每次代码变更自动刷新——给 AI 编码 Agent 看的「项目说明书」，从此不用人维护。

结论先行

AI 编码 Agent 用得好不好，一半取决于它能不能看懂你的项目。现在主流做法是手写 CLAUDE.md / AGENTS.md 告诉它项目约定，但这玩意儿一写就过期——没人会天天更新它。LangChain 2026 年 6 月开源的 OpenWiki 换了条路：用一个文档 Agent 直接读代码库，生成一份互联的 Markdown wiki 存在仓库里，再通过 CI 定时任务随每次代码变更自动刷新。文档由 AI 写、给 AI 读，人类打开仓库也能当索引用。

这不是又一个「一键生成 README」的玩具。它背后是 LangChain 自家的 Deep Agents 框架，输出遵循 Google 的 Open Knowledge Format（OKF）标准，还能自动校验生成的 Mermaid 图——坏图就地降级成纯文本，下次更新再修复。写这篇文章前我把它的仓库翻了一遍：它用自己维护自己的文档，仓库里的 openwiki/ 目录就是它生成的 wiki，GitHub Actions 每天早上 8 点自动跑一次更新。这种「dogfooding」本身就是质量信号。

1. 先解决一个真实痛点：Agent 文档永远在过期

用 Claude Code、Codex 或 Cursor 的人都会遇到一个尴尬时刻：Agent 对一个成熟项目一无所知，反复问「这个模块是干嘛的」「测试跑哪个命令」。于是社区给出了两个答案，各有硬伤：

手写上下文文件（CLAUDE.md / AGENTS.md）。 Anthropic 的 CLAUDE.md、OpenAI 的 AGENTS.md 本质上是一份 Markdown 约定书。问题在于它是静态的：你写的时候是什么样，它就一直是什么样。功能加了、依赖换了、目录重构了，文档纹丝不动。而且它是「自我报告」——你声称的规范和代码实际的样子，常常是两回事。

一次性打包工具（repomix、code2prompt 之类）。 把整个仓库压成一个上下文文件喂给 Agent，当下很爽，但它是快照，没有记忆：下次会话还得重新跑一遍，代码变了也毫无感知。它解决的问题是「让 Agent 看见代码」，不是「让 Agent 理解项目」。

OpenWiki 的位置在两者之间：它读取代码库生成一份持续演化的 wiki，不只是一次性打包；文档由 AI 维护，不靠人写。 官方 README 对它自己的定义很直白："The self-maintaining wiki. Built for agents, explored by humans."（自我维护的 wiki，为 Agent 而生，供人类探索）。

2. 三步上手：安装、初始化、交给 CI

OpenWiki 是一个 npm 装的原生 CLI，不需要 Node 也没关系——它是全局命令：

npm install -g openwiki

# 在仓库根目录跑一次初始化
openwiki --init

第一次运行会引导你选模型提供商、填 API key、选模型，然后 Agent 开始读仓库，把文档写到 openwiki/ 目录。默认提供商是 OpenAI（gpt-5.6-terra），但内置 12 种模型通道：Anthropic、Gemini（AI Studio 和 Vertex 企业版）、AWS Bedrock、OpenRouter、GitHub Copilot（复用你已登录的 GitHub CLI 会话，不额外花 API 钱）、Nebius / Fireworks / Baseten / NVIDIA NIM，以及任何 OpenAI 兼容网关（LiteLLM、Ollama、LM Studio 都能接）。

保持文档新鲜靠的是 CI 自更新。官方给了三套现成模板：

官方仓库自己用的 workflow 是每天 8 点（UTC）跑 openwiki code --update --print，把更新后的 wiki 作为 PR 提出来——人看一眼合并即可。GitHub Actions 的 job 默认只在原仓库定时触发，fork 不会静默消耗你的模型额度，这点设计得挺细。

3. 核心机制：文档 Agent + 三份产出

OpenWiki 的引擎是 LangChain 自家的 Deep Agents 框架（deepagents 依赖，同目录下的 deepagentsjs 项目），搭配 LangGraph 的 SQLite 检查点做状态持久化，CLI 交互层用 Ink + React 来写。它在 src/agent/ 下有两份 prompt 模板：code.ts 管代码库文档、personal.ts 管个人知识库，中间还有 wiki_qa_subagents、wiki-link-validator、okf-middleware 这些环节。

一次运行结束，你得到三样东西：

① openwiki/ 目录——wiki 本体。 结构按概念分文件：index.md 总索引、每个概念一篇文档，带 OKF v0.2 标准 frontmatter（type 必填、generated: {by, at} 记录生成来源）。官方仓库里它给自己生成的 wiki 有 agent/、architecture/、cli/、integrations/、operations/ 这些子目录，每篇开头都是「这是 OpenWiki 的 TypeScript CLI，入口在 ./dist/cli/cli.js」这类精确到文件的描述。

② 仓库根目录的 AGENTS.md / CLAUDE.md 指针。 这是给编码 Agent 看的入口。OpenWiki 在每次 code 模式运行后更新这两个文件，用 <!-- OPENWIKI:START --> / <!-- OPENWIKI:END --> 包裹它写的块，只改自己圈的地盘，其余内容不动——你手写的部分保留。官方仓库的 AGENTS.md 现在是这样的：

## OpenWiki

This repository has a generated `openwiki/` evidence index. It is optional
just-in-time context, not required startup reading.

- Treat source code and tests as authoritative. A brief's unknowns and review
  items are verification gaps, not automatic requirements.
- ...

<!-- OPENWIKI:START -->
...

<!-- OPENWIKI:END -->

它甚至告诉后来的 Agent：「不要手改生成的 wiki 页面，去改源码，让 OpenWiki 重新生成。」——维护关系反过来了。

③ openwiki/INSTRUCTIONS.md——你的私货。 这是唯一一个用户手写、Agent 永不重写的文件，用来指定文档范围和优先级。想让它多写架构少写测试？在这里说。这是整个设计里我最欣赏的一点：AI 保持文档新鲜，但「文档的立场」始终由人决定。

4. 闭环是怎么转起来的

用一张图概括整个运行闭环：

流程是：Agent 读代码（遵守 .openwikiignore 的读取边界）→ 生成/更新 openwiki/ wiki → 刷新 AGENTS.md/CLAUDE.md 指针 → CI 定时任务收到新 commit → 再跑一轮 --update → 提 PR 给人合并。文档和代码从此绑在一起演进。

三个细节值得展开：

Mermaid 图自动校验。 OpenWiki 会在合适的地方自动嵌 Mermaid 图（时序图、ER 图、状态图），每次运行后校验所有 mermaid fence：坏图直接降级成纯文本并加注释说明原因，下次 --update 读到注释就尝试修复——质量随运行次数收敛。想要 GitHub 级别的高保真校验，CI 里装个 mermaid + jsdom 即可。

no-op 运行不花钱。 每次运行后对 openwiki/ 做快照，只有内容真正变了才更新元数据。仓库没动的话，定时任务跑完就是空转，不会制造一堆「文档没变化但 PR 刷屏」的噪音。

可视化器。 openwiki visualize 把 wiki 变成一个交互式节点图，旁边同步显示 Markdown 正文；--export 还能导出静态目录扔到 GitHub Pages 上。

5. 和主流方案摆在一起看

它跟上一轮我写过的「Personal Model」（AI 从你的行为生成 HUMAN.md 个人画像）是互补的两端：OpenWiki 管代码库侧，Personal Model 管用户侧。 一个让 Agent 懂项目，一个让 Agent 懂你。

6. 诚实评估：边界与代价

说清楚了能力，也得说代价。

第一，它本质是"Agent 跑一天"的活，贵且挑模型。 文档质量直接取决于用的模型；用弱模型生成的 wiki 可能是套话。单仓库首次生成要消耗不少 token，这是隐性的。开源项目 CI 里定时白嫖你的 API key——注意 workflow 只在原仓库自动触发，fork 不会，但你自己配的 job 还是要掂量下额度。

第二，有噪音风险。 想让一个 agent 理解大仓库的每个角落，必然会产生大量页面。INSTRUCTIONS.md 划范围、.openwikiignore 划边界，控制不好会得到一个「文档很多但没人看」的 wiki。官方也承认 .openwikiignore 只是读取边界：忽略的路径不会被读，但 Agent 仍可能从代码、提交信息里推断出被忽略区域的存在。

第三，还在快速迭代期。 我从 changelog 里看到 0.3.3 刚加入 LEDGER 基准测试（重放仓库 git 检查点、逐条评测文档事实是 grounded/stale/hallucinated），说明团队已经在认真对付「AI 文档幻觉」这个命题；但同时 open issues 也有上百个，覆盖了 OpenAI 兼容网关的流式怪癖、Windows 原生依赖编译等各种边角——生产化程度还谈不上成熟。

第四，有遥测，默认开。 官方声明只收集匿名聚合的运行事件（命令、成败），不收集文件内容、路径、凭据、提示词，且可用 OPENWIKI_TEAMETRY_DISABLED=1 或 DO_NOT_TRACK=1 关掉。介意的团队部署前记得关。

7. 项目信息

• 仓库：langchain-ai/openwiki（GitHub）
• 创建：2026 年 6 月 22 日；两个月内发布 10 个版本（0.2.0 → 0.3.3）
• 语言/协议：TypeScript / MIT
• 运行要求：Node.js ≥ 22
• 安装：npm install -g openwiki
• 同类生态：Deep Agents（deepagentsjs，文档 Agent 的底层框架）、OKF（Google Open Knowledge Format，输出标准）

一句话判断：如果你的团队重度使用 AI 编码 Agent、又苦于项目文档没人写，OpenWiki 值得在一个中型仓库上试跑一轮——先本地生成看看 wiki 质量，再决定要不要接 CI 让它自维护。而如果项目小、成员少、文档靠口口相传，它对你的价值就有限，省下 token 买咖啡更实在。

有什么想法可以随时留言沟通。