开源项目第199期：OpenWiki — LangChain 出品的代码库自维护文档 CLI，为 Agent 而生，15k Stars

引言

"The self-maintaining wiki. Built for agents, explored by humans."

这是「每日一个开源项目」系列的第 199 篇。今天的项目是 OpenWiki —— LangChain AI 出品的代码库文档自动生成与维护 CLI，15,600 颗 Star，MIT 许可证。

OpenWiki 解决一个每个工程团队都有的问题：文档写了就过时，不写 AI Agent 找不到路。OpenWiki 的解法是：让 Agent 来写、让 Agent 来维护，产出的 Markdown wiki 是你的（存在仓库里），Agent 随时能读，人也能通过可视化图探索。

你会学到什么

• 两种模式：代码库 wiki（code）和个人知识库（personal）的区别
• Grounded Claims：追踪关键事实到精确代码行的机制
• 与 Claude Code / Codex / OpenCode 的编程 Agent 集成方式
• 13 个模型提供商支持和 9 个知识源连接器
• 交互式节点图可视化与静态站点导出
• CI 自动更新（GitHub Actions / GitLab CI / Bitbucket）

前提知识

• 基本命令行使用经验
• 了解大语言模型 API 的基本概念（API Key、模型名称）
• 了解 Git 工作流会有帮助

项目背景

概述

OpenWiki 基于 Deep Agents（LangChain 的深度 Agent 框架）构建。它不是一个"写一次就完事"的文档工具，而是一个文档生命周期管理系统：

1. 初始化：Agent 读取源码，生成结构化的 Markdown wiki
2. 追踪：把每个关键事实（Grounded Claims）绑定到具体的代码行
3. 更新：代码变更时，检查哪些事实的"证据"发生了变化，只重写受影响的页面
4. 集成：在仓库根目录维护 AGENTS.md 和 CLAUDE.md，让编程 Agent 能找到并读取 wiki

项目信息

• 组织: LangChain AI
• 主要语言: TypeScript
• 许可证: MIT
• 创建时间: 2026-06-22

项目数据

• ⭐ GitHub Stars: 15,600+
• 🍴 Forks: 1,133+
• 📄 许可证: MIT
• 📅 创建时间: 2026-06-22

快速上手

安装

# 需要 Node.js 22 或更新版本
npm install -g openwiki

为当前仓库生成 Wiki

cd your-project
openwiki --init

首次运行时，会引导你选择模型提供商（默认 OpenAI + gpt-5.6-terra）、填写 API Key、选择模型，然后写出文档到 openwiki/ 目录。

更新已有 Wiki

# 检测代码变更，只更新受影响的页面
openwiki --update

启动可视化界面

# 在浏览器里看交互式节点图
openwiki visualize

两种模式

code 模式适合团队：wiki 跟代码一起提交，CI 自动维护，AGENTS.md 和 CLAUDE.md 让编程 Agent 直接找到文档入口。

personal 模式适合个人：把你散落在各处的知识（Notion 笔记、邮件、X/Twitter、Hacker News……）整合成一个本地 wiki，AI 帮你做成结构化的知识图谱。

核心机制：Grounded Claims

这是 OpenWiki 区别于普通文档生成工具的核心设计。

普通文档工具只知道"这个页面上次是什么时候生成的"。OpenWiki 更进一步：它追踪文档里每一个关键事实，精确到源码的哪一行。

// Claims 的结构（存在 openwiki/.claims/ 下）
{
  id: "claim-abc123",
  proposition: "AuthMiddleware 在失败时返回 401，不向上抛出异常",
  evidence: "repo://src/middleware/auth.ts#L40-L82",
  evidence_version: "git-sha-of-that-commit"
}

Claims 覆盖的内容类型：

• 函数/模块的行为和职责
• 架构关系和数据流
• 不变量（invariants）和失败语义
• 配置要求和安全边界

更新时，OpenWiki 在决定"是否需要重新生成"之前，先检查所有 Claims 的 evidence：

openwiki --update 的执行顺序：
1. 检查每个 Claim 的 evidence（精确到行号）是否变化
2. 如果 evidence 变化 → 该页面需要重写，无论代码量改变多少
3. 如果 evidence 未变化 → 页面内容可能不需要更新
4. 页面工作完成后，Claims 原子性地持久化（不能部分更新）

这解决了一个微妙问题：代码量改变了但文档还对，或者代码量没变但关键事实变了。行号级别的 evidence 跟踪让更新决策更精确。

可恢复的页面作业架构

OpenWiki 的生成流程不是一个大批处理，而是有状态的页面队列：

begin → submit_plan → next_page → submit_page → ... → finish

• begin：开始新的生成运行，记录运行状态到 openwiki/.run.json
• submit_plan：提交要生成的页面计划（哪些主题需要文档）
• next_page / submit_page：逐页工作，每页完成后原子性持久化 Claims
• finish：最终验证，删除 .run.json，标记运行完成

可恢复性：如果生成中途被中断（比如 CI 超时），下次在同一个 checkout 上重跑会从断点继续，不会重复已完成的页面。

CI 注意事项：Ephemeral CI runner（每次都是全新环境）在失败后不会保留 .run.json，所以失败后会从头开始。只有在 checkout 持久化的情况下才有续跑能力。

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

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

# 安装集成（选择你的编程 Agent）
openwiki integrations install claude
openwiki integrations install codex
openwiki integrations install opencode

安装后，重启编程 Agent，在仓库里问：

Initialize this repository's OpenWiki from the current source and tests.

或者更新已有 wiki：

Update this repository's OpenWiki for changes since its last successful run.

集成暴露了与原生生成相同的五个操作：openwiki_begin、openwiki_submit_plan、openwiki_next_page、openwiki_submit_page、openwiki_finish。编程 Agent 在提交每个页面时附带完整的 Claim 集，OpenWiki 内部处理 Claims 的创建、更新、保留和撤销——OpenWiki 不允许 finish，直到最终状态完全持久化。

这种集成的优势：使用编程 Agent 自身已认证的模型 session，不需要单独配置 OpenWiki 的提供商凭据。

9 个知识源连接器（personal 模式）

LangSmith 连接器比较特殊：它用于 code 模式，而不是 personal 模式。它把 LangSmith 里的实际运行 traces（工具调用、结果、延迟）注入到代码库文档里，让文档反映代码在运行时的实际行为，而不只是源码里写的内容。

同一个连接器可以配置多个实例（例如两个 Web Search 实例，一个搜 AI 资讯、一个搜 NBA 新闻），以 web-search-1、web-search-2 形式分开存储。

13 个模型提供商

本地模型示例（Ollama）：

OPENWIKI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=ollama
OPENAI_COMPATIBLE_BASE_URL=http://localhost:11434/v1
OPENWIKI_MODEL_ID=llama3.2

交互式可视化

# 在本地浏览器打开交互式节点图
openwiki visualize
 
# 导出为静态站点（GitHub Pages / MkDocs 等）
openwiki visualize openwiki --export docs/openwiki-visualizer

可视化界面是一个实时节点图 + Markdown 阅读器并排布局：节点是 wiki 页面，边是页面间的链接关系，点击节点在右侧阅读对应页面。

静态导出包含 index.html、client.js、styles.css、graph.json，可以直接部署到任何静态托管平台。

CI 自动更新

把以下 workflow 文件复制到仓库即可：

# .github/workflows/openwiki-update.yml
# 每天检查一次代码变更，如果 wiki 需要更新就开 PR

官方提供了 GitHub Actions、GitLab CI、Bitbucket Pipelines 三套示例，都在 examples/ 目录下。自动更新流程：检测变更 → 更新 wiki → 开一个文档 PR，不直接合并，保留人工 review。

文档归你所有

OpenWiki 的一个设计原则：你的文档是你的。

• wiki 是普通 Markdown 文件，存在仓库里，不依赖任何外部服务
• openwiki/INSTRUCTIONS.md 是用户自己写的文档 brief，正常更新运行不会覆盖
• OpenWiki 维护 AGENTS.md 和 CLAUDE.md 里自己的 block（<!-- OPENWIKI:START -->…<!-- OPENWIKI:END -->），其余内容不动
• Claims 文件在 openwiki/.claims/ 下，和 Markdown 一起可以做 git 历史追踪
• 无变更时不重写内容（no-op 只更新 .last-update.json，不动页面）

参考资源

• 🌟 GitHub: langchain-ai/openwiki
• 📦 npm: openwiki
• 🔧 Deep Agents: langchain-ai/deepagentsjs
• 📋 OKF 规范: Open Knowledge Format v0.2

总结

OpenWiki 代表了一种新的文档工程思路：文档的质量问题不是写得不好，而是写了不维护。

三点值得注意：

Grounded Claims 是关键创新。 传统文档工具的"最后更新时间"是页面粒度的。OpenWiki 把粒度降到了"命题 + 代码行"级别：每个事实知道自己的证据在哪一行，证据变了就知道要重写。这让更新决策从"整个文件重新生成"变成"只有证据变了的命题才需要重写"，精准度高得多。

把编程 Agent 当写作工具，而不是问答工具。 OpenWiki 的 Claude Code/Codex 集成让编程 Agent 承担的是"仓库研究员 + 文档作者"的角色，而不是"根据 prompt 生成文档"的一次性工具。Agent 有完整的仓库访问权，按页面队列逐步工作，每步结果都持久化，整个过程可恢复。

OKF 格式是一个可互操作的赌注。 产出符合 Google Open Knowledge Format v0.2 标准意味着 wiki 不只是给这个工具用的，任何支持 OKF 的工具都能读取。这是一个防止厂商锁定的设计选择。

如果你在构建 AI 原生的工程团队，需要一套代码变更时自动跟进的活文档，OpenWiki 是目前最完整的开源解决方案。

探索 PrimeSkills —— 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。