给代码库写文档这件事，OpenWiki 让 Agent 自己干

大家好，我是若风。

每个项目的 README 都是开荒时写的。项目活久了，README 就开始骗人。代码已经改了三轮，文档还停留在 v0.1 的架构描述。新来的人照着 README 跑环境，报错，翻 issues，发现文档和代码早就不一致了。

这不是哪个团队的问题，是整个行业的问题。文档维护的 ROI 太低，写代码是产出，写文档是负债。于是文档永远滞后于代码，直到彻底失去可信度。

LangChain 团队做了一个工具试图解决这件事。openwiki，一个 CLI，自动给代码库生成和维护文档。2026 年 6 月 22 日上传，三周后 10,651 个 Star。

一句话定位

OpenWiki 是一个 CLI 工具，用 AI Agent 自动为代码库或个人知识源生成和维护 wiki 文档。它有两种模式，personal mode 做个人知识大脑，code mode 做代码库文档。基于 LangChain 的 deepagents 框架构建，TypeScript 实现，MIT 协议。

两种模式，一个引擎

OpenWiki 的设计分叉点很早，你装完后要选模式。

openwiki personal --init 启动 personal mode。它把你的 Gmail、Notion、X/Twitter、Hacker News、Slack、Web Search、本地 git 仓库等数据源，综合成一个本地知识库，存在 ~/.openwiki/wiki。你问它「上周那条关于 RAG 的推文链接是什么」，它从你连接的数据源里找答案。

openwiki code --init 启动 code mode。它分析当前代码库，在 openwiki/ 目录下生成技术文档。这是更实用的模式，因为它解决的是「文档滞后于代码」这个普遍痛点。

两个模式共享同一个 Agent 引擎，区别在于数据源和输出位置。这个设计很聪明，因为「理解代码并写文档」和「理解多个信息源并综合知识」本质上是同一个能力，信息检索 + 理解 + 结构化输出。

Agent 怎么读代码库

src/agent/prompt.ts 里的 system prompt 是理解 OpenWiki 工作方式的关键。这个 prompt 很长，但里面的「Run discipline」部分暴露了核心设计。

「Do not exhaustively read every file. Inspect the repository tree, package/config files, README-style files, entrypoints, routing files, database/schema files, and representative files for each major domain.」

它不是把整个代码库读一遍。它做的是选择性读取，先看项目结构和配置文件，再看入口文件和路由，再看数据库 schema，最后挑每个核心领域的代表性文件。

这个策略和人类工程师熟悉一个新代码库的方式几乎一样。你也不会逐行读，你会先看 package.json 了解依赖，看入口文件了解启动流程，看路由文件了解 API 结构，然后挑核心模块深入。

prompt 里还有一条硬约束。「Do not call glob with **/* from the root. Use targeted discovery by directory and extension.」禁止从根目录递归搜索所有文件。这是对 Agent 行为的预判，因为 LLM Agent 天然倾向于「全读一遍以防遗漏」，但这会爆 context window。

connector 架构

src/connectors/ 目录是 OpenWiki 的数据源系统。7 个 connector 各自独立。

• git-repo.ts，本地 git 仓库
• gmail.ts，Gmail 邮件
• hackernews.ts，Hacker News
• slack.ts，Slack 消息
• web-search.ts，网络搜索
• x.ts，X/Twitter
• mcp.ts，通用 MCP 协议连接器

每个 connector 做两件事。第一，用各自的 API/协议把原始数据拉下来，存到 ~/.openwiki/connectors/<connector>/raw 目录。第二，把原始数据的元信息返回给 Agent。

registry.ts 管理所有 connector 的注册和发现。tools.ts 把 connector 包装成 Agent 可调用的工具。write-connector-skill.ts 动态生成 connector 使用说明，帮 Agent 理解每个 connector 能做什么。

这个架构的关键在于，数据拉取和文档生成是分离的。connector 只负责拉原始数据，Agent 负责理解数据并生成文档。这意味着加一个新数据源只需要写一个新 connector，不需要改 Agent 逻辑。

deepagents 和多模型支持

src/agent/index.ts 的 import 揭示了技术栈。OpenWiki 用了 deepagents 库（来自 LangChain 生态），配合 @langchain/langgraph-checkpoint-sqlite 做状态持久化。

SqliteSaver 把 Agent 的执行状态存在 SQLite 里，这意味着如果 Agent 中途崩溃或被中断，它可以从上次的状态恢复。对于处理大型代码库这种可能跑几十分钟的任务，这个设计是必要的。

多模型支持是另一个亮点。import 里有 ChatAnthropic、ChatOpenAI、ChatOpenRouter，还支持 Codex（ChatGPT OAuth）。src/constants.ts 定义了 provider 解析逻辑，支持 Anthropic、OpenAI、OpenRouter 三家，以及任何 OpenAI 兼容的 API endpoint。

issue #256 报了一个有意思的 bug，OpenAI 兼容的 thinking 模型（Qwen3.7）会导致静默挂起，原因是 ChatOpenAI 需要在 modelKwargs 里设 enable_thinking: false。这说明 OpenWiki 在兼容多种模型 provider 时遇到了真实世界的兼容性碎片化问题。

code mode 的 CI/CD 集成

code mode 最实用的地方是 CI/CD 集成。src/code-mode.ts 实现了自动化的文档更新机制。

ensureCodeModeRepoSetup() 做两件事。第一，在 .github/workflows/ 下生成 openwiki-update.yml，一个 GitHub Actions 定时任务，默认每天早上 8 点跑一次。第二，在项目根目录的 AGENTS.md 和 CLAUDE.md 里注入 OpenWiki 指引片段，用 <!-- OPENWIKI:START --> 和 <!-- OPENWIKI:END --> 标记包裹。

支持三个 CI 平台，GitHub Actions、GitLab CI、Bitbucket Pipelines，各有独立的 example YAML 文件。

这个设计的价值在于，文档不再是「写一次就完」的静态产物，而是跟代码同步更新的活文档。每次 CI 跑的时候，OpenWiki 分析最新的代码变更，自动更新 openwiki/ 里的文档，然后开一个 PR 让你 review。你不需要写文档，只需要审文档。

issue #47 的标题很有代表性，「Restrict agent filesystem writes to openwiki directory via declarative permissions」。社区要求限制 Agent 的文件写入范围，只允许写 openwiki/ 目录。这说明用户对 Agent 自动改文件有合理的警惕。code-mode 的 OpenWikiLocalShellBackend 已经做了 docs-only 的后端限制，但社区希望更细粒度的权限控制。

这比传统文档生成工具强在哪

市面上已经有不少文档生成工具。JSDoc、Sphinx、MkDocs，它们做的是从代码注释提取 API 文档。TypeDoc、docusaurus 做的是结构化文档站点。

OpenWiki 的差异在于，它不是从注释提取，是理解代码后重新表达。传统工具的输出是代码的镜像，代码里有什么 API 就列什么 API。OpenWiki 的输出是代码的解释，它会写「这个模块负责用户认证流程，依赖 OAuth2 协议，入口在 auth.ts 的 login 函数」。

这种差异的价值在于，镜像式文档你能自己从代码读出来，解释式文档帮你省了理解代码的时间。对于新人 onboarding，后者价值大得多。

但代价是，解释式文档可能解释错。LLM 理解代码不总是对的，尤其面对复杂业务逻辑或非直觉的设计模式。prompt.ts 里那句「Ground every important claim in source files」就是在对抗这个问题，要求每个重要论断都要有源码证据。但「有证据」不等于「理解正确」。

issue 区的真实痛点

翻 issue 区能看到这个项目面临的真问题。

issue #128 请求支持本地 LLM（Ollama、LM Studio）。这意味着有用户不想把代码库发给 OpenAI 或 Anthropic，想在本地跑。对于私有代码库，这个需求很合理。

issue #123 请求 .openwikiignore 文件，排除特定目录和文件模式。类似 .gitignore 的机制，让用户控制哪些文件不被 Agent 读取。这是隐私和精度兼顾的需求。

issue #178 请求 OpenTelemetry trace 导出。这是生产级可观测性的需求，说明有人在认真考虑把 OpenWiki 用到真实项目里。

从 0.0.3 到 0.1.0（2026-07-09）的迭代速度很快，三周四个版本。但版本号还在 0.1 说明团队自己也认为这还是早期产品。

给你什么启发

拆完 OpenWiki，我觉得最值得带走的是一个产品设计决策，把文档维护从人的责任变成 CI 的责任。

大多数文档工具的假设是，人写了代码就顺手写文档。这个假设在现实中不成立，因为写文档的 ROI 对个人是负的。OpenWiki 的假设是，Agent 读代码写文档，人只负责 review。这把人的角色从「作者」降级为「审稿人」，大大降低了维护成本。

这个思路可以迁移到很多「大家该做但没人做」的维护性工作。

• API 变更日志，changelog 可以从 commit history + diff 自动生成
• 依赖安全审计，定时跑 Agent 分析依赖链里的已知漏洞
• 测试覆盖报告，不只是数字，而是 Agent 分析哪些路径没被覆盖、风险多大
• 架构决策记录(ADR),Agent 分析代码变更，自动生成「为什么这么改」的决策文档

核心都是同一个模式，把需要人类持续投入的维护性工作，变成 CI 里定时跑的 Agent 任务。人类从执行者变成审批者。

如果你在考虑用 OpenWiki，code mode 适合任何 5 人以上、文档已经开始骗人的团队。personal mode 更适合信息源多、需要跨源检索的重度知识工作者。但做好心理准备，它是 0.1 版本，准备好踩坑。