OpenWiki：为代码库生成可持续更新的 Agent 文档
一次接口改名之后，旧文档仍把原函数列为入口，接手任务的人很难判断该信哪一份。OpenWiki 让文档 Agent 阅读仓库，生成带链接的 Markdown wiki；后续更新时再检查代码变化和已有事实的来源。生成物留在自己的仓库中，既能给编码 Agent 当上下文，也能在浏览器里按关系图探索。仓库说明将 OpenWiki 定位为 CLI，当前包版本为 0.5.2。
GitHub 仓库信息
| 信息 | 内容 |
|---|---|
| 项目标题 | OpenWiki |
| 项目描述 | 一个为代码库编写并维护 Agent 文档的命令行工具。 |
| GitHub 仓库 | langchain-ai/openwiki |
| 官网地址 | 项目官方 README（包清单指定的主页；未发现独立产品站） |
| 主要开发语言 | TypeScript 95.75%、Python 2.59%、JavaScript 1.35% |
| 开源许可证 | MIT |
| 最近代码更新 | 2026-09-20（GitHub pushed_at，核对日期：2026-09-20） |
文档怎样跟上代码
第一次生成的是仓库内的 openwiki/，不是托管在第三方平台上的只读页面。根目录的 AGENTS.md、CLAUDE.md 会得到指向 wiki 的 OpenWiki 管理区块；手写部分保留。你可以在 openwiki/INSTRUCTIONS.md 写明文档重点，正常运行不会改写这份人工说明。README 的所有权说明也列出了本地凭据目录与生成内容的界线。
持续更新的关键不是只比较 Markdown 文件日期。代码 wiki 的重要事实会以 Claims 记录对应的仓库证据与版本；--update 先检查证据是否失效，再决定哪些页面要重新确认、修订或撤回。没有变化的更新可跳过模型写作，但仍记录检查时间。来源核对降低了“源码已经改了，说明却看起来仍然完整”的风险，却不能代替人工审定生成结论。Claims 机制目前针对仓库代码证据，不覆盖连接器带来的事实。
生成过程还有页面级进度：仓库 wiki 的活动队列写在 openwiki/.run.json，每页的 Markdown、Claims 与清单持久化后才推进。持久工作区中断后可重新运行 --init 接续；CI 临时工作区若不保留文件，失败后只能重新开始。上游架构说明描述了这一边界。
在一个仓库里试用
准备 Node.js 22.22.0 或更新版本、一个可写的 Git 仓库，以及可用的模型服务或登录方式。在目标仓库根目录执行以下命令；安装命令是上游 Quick start给出的用法，本次没有安装或运行目标项目。
node --version
npm install -g openwiki
openwiki --init首次向导会选择模型提供方、凭据和模型，默认使用 OpenAI；模型调用可能产生费用。完成后，先打开 openwiki/index.md，找到一个描述自己熟悉模块的页面。从该页面挑出一条关于入口、配置或数据流的具体说法，按文中的源码路径在仓库中定位并逐项比对。成功信号是索引和关联页面已生成，且这条说法能在当前源码中找到依据；页面缺失或路径、行为对不上时，不要将生成内容直接交给团队使用，先检查生成过程输出和源文件是否被忽略。若缺少凭据或模型不可用，先按向导完成认证；不要把密钥提交到仓库。OpenWiki 将本地提供方配置放在 ~/.openwiki/.env。提供方列表包括 API 密钥、浏览器登录及自带模型会话的集成方式。
--init 是重建入口：再次执行会替换已有仓库 wiki 与 Claims，但保留人工编写的 openwiki/INSTRUCTIONS.md。已有 wiki 需要跟随代码变化时，改用 openwiki --update。首次尝试最好先用可回退的测试仓库或 Git 提交记录；运行前检查 .openwikiignore，把不希望工具读取的私密或生成目录排除。忽略规则限制读取，但不能保证其他允许来源不会间接提到某个主题。忽略规则说明
看结果，继续维护
第一次生成后，在同一仓库运行 openwiki visualize。CLI 会在本机回环地址启动关系图与 Markdown 阅读器，默认端口 4321，文件变化会实时反映；按终端提示打开页面，检查概念链接能否带你找到相关页面。若端口被占用，程序会尝试下一个端口；也可以指定 --port 4400 --no-open。页面从公共 CDN 加载前端依赖，离线环境不能假设可用。可视化说明
openwiki visualize修改仓库源码后，再运行 openwiki --update，检查 wiki 与 Claims 文件的 Git diff，并复核受影响的说明。没有变化时，更新检查可能只改动 .last-update.json。
团队想让文档变化进入代码审查，可从官方 GitHub Actions 示例开始，按自己的分支保护和密钥管理改造，让定时更新开 PR。不要直接启用自动合并：上游说明自动合并依赖单独的 PR token、必需检查和仓库规则，失败运行还可能留存部分文档供审阅。GitLab CI 与 Bitbucket Pipelines 也有官方示例。
已有 Codex、Claude Code 等编码 Agent 的团队还可以安装相应集成，例如 openwiki integrations install codex，重启 Agent 后在目标仓库请求初始化或更新。集成使用宿主 Agent 的模型会话和仓库工具，只支持代码 wiki，暂不支持个人知识库或连接器来源。集成说明给出了完整宿主列表、用户级默认安装与 --project 范围选项；安装会修改 Agent 配置，先确认目标范围。
适用边界
OpenWiki 适合已有 Git 工作流、愿意审阅 AI 生成说明，并希望文档与代码证据一起版本化的团队。仅需几页人工维护的稳定说明时，普通 Markdown 和代码审查可能更省模型成本；需要公开站点而不需要生成过程时，MkDocs 一类站点工具解决的是展示而非事实维护问题。OpenWiki 也有 personal 模式，输出到本地 ~/.openwiki/wiki 并接入外部知识源，但那是另一条含 OAuth 和数据摄取的路径，不应把代码 wiki 的 Claims 保证套用过去。
下一步可在小仓库完成一次 --init，阅读生成的一个模块页面，修改对应源码后运行 --update，在 Git diff 中审查实际变化。不要把生成文档当作无需核对的运行证据。