LangChain 开源的 OpenWiki，盯的就是这道缝：用文档智能体生成并维护一本面向智能体的本地百科，再把「需要仓库上下文时先读这儿」写进 AGENTS.md / CLAUDE.md。
你大概碰过这种事：换个仓库，Cursor 或 Claude Code 一上来很自信，改完才发现鉴权入口不在它以为的地方，接口约定也读歪了。模型未必突然变笨，多半是缺一份已经整理好、还能跟着代码变的仓库上下文。
README 写于开荒期，活久了就会骗人。代码改了三轮，架构描述还停在 v0.1。写代码算产出，写文档像负债，文档先死，智能体再跟着猜。把整仓背景塞进AGENTS.md也不行——短说明还好，真塞成上百页，每次任务的固定上下文会被撑爆。
LangChain 开源的 OpenWiki，盯的就是这道缝：用文档智能体生成并维护一本面向智能体的本地百科，再把「需要仓库上下文时先读这儿」写进AGENTS.md/CLAUDE.md。
读完你能分清三件事：它生产的是哪种知识、Agent 怎么用这本百科，以及你怎么用几条命令把它跑进日常。想先上手的，可以直接跳到「怎么用」；想搞清原理的，按顺序读也行。
OpenWiki 分层：命令行、智能体运行时、工具沙箱、主机裁定、编程智能体消费
命令行、智能体运行时、工具沙箱、主机裁定、编程智能体消费
一、它解决的不是「再生成一份文档」
编程智能体不缺单文件理解力。缺的是稳定、能复用、能顺着点的仓库地图。没有地图，它每次重新扫目录、猜入口、从对话里拼背景；对话一长，早先的结论还可能被冲掉。你以为它「熟悉项目了」，其实只是这一轮上下文碰巧还记得。
传统工具也救不了这个场景。JSDoc、Sphinx、MkDocs 更擅长从注释抽出 API 列表，出来的多半是代码镜像。智能体缺的常常是解释：这模块管哪条链路，入口在哪，和谁耦合，改它先跑什么测试。
OpenWiki 默认也不做给人慢慢翻的漂亮文档站。它给智能体准备本地百科：架构、领域概念、主流程、运维注意点，外加能跳回去的源码锚点。生成完不会把全书塞进指令文件，只插一段短引用：需要上下文时，先从openwiki/quickstart.md往下读，再按链接取细节。
有个产品判断容易被忽略：百科的第一读者是智能体，第二才是人。所以它在意可导航、能增量、能审，不太在意视觉站点。同一套引擎还有个人模式，把 Notion、邮件、本地仓库等综合进~/.openwiki/wiki；天天写代码的人通常更需要代码模式。
它和 DeepWiki 也不打架。DeepWiki 更像「打开陌生公开仓的导览站」；OpenWiki 更像「在自己仓里养一本给 Cursor / Claude Code 用的活地图」，还能挂进指令文件、跟 git 增量更新。查函数位置仍用搜索；问「链路为什么这样串、改它先看谁」，优先走openwiki/。
二、它在生产什么：编译知识，按概念成页
OpenWiki 站在 DeepWiki、AutoWiki，以及 Karpathy「LLM Wiki」那条线上。共享直觉很朴素：给人和智能体一本结构化百科，比把所有上下文塞进一个巨型文件更能撑住。
常见 RAG、聊天上传文件，本质是查询时再从碎片里检索、拼装、回答。能用，但几乎每次都在重新发现知识——问完，综合过程常留在聊天记录里蒸发。Wiki 反过来：新材料进来时读完、抽取、写进已有结构，标矛盾、改交叉引用。知识先编译，再保鲜，而不是每次提问都重导一遍。百科会越用越厚，不是每次归零。
系统可以看成三层。原材料（代码、git、邮件等）不可变，模型只读。百科层是模型维护的 Markdown，人读模型写。协议层是AGENTS.md/CLAUDE.md/INSTRUCTIONS.md，规定怎么组织、先读什么、维护守什么。没有协议，模型只是健谈；有了协议，才像有纪律的图书管理员。OpenWiki 把这三层钉进仓库：源码和 git 是原材料，openwiki/是百科，指令文件是协议。
落到「知识生产」，几条最要紧。
综合被前移。贵的工作发生在入库和更新，查询时优先吃已经编译好的页。成本从「每次对话付一次」变成「有变更时付一次，之后多次复用」。这是节奏变了，不只是换个文件夹。
人、模型、主机分工。人策展、定范围、问好问题、审 PR、否决胡说；模型编译、记账、小范围修订——像图书管理员兼初稿作者，不是真理机关；主机裁定源有没有变、产物有没有变、能不能写源码、密钥能不能外泄。少任何一方都会歪：只靠模型会飘，只靠人会荒，只靠主机又综合不出来。
产物是解释性概念图，不是文件镜像。源码是证据，百科页是解释，页间链接是关系，指令文件里的短引用是消费协议。页面被收成概念节点：题头说明类型，正文链接表达「依赖于 / 调度到」这类语义。它承认自己可错：重要论断要有源码或 git 证据，人在文档 PR 上签字。下一次源码变更，这份稳定又可以被正当打破。
消费侧也会反过来塑形生产。第一读者是编程智能体，产物就该是短协议加可按需展开的地图，而不是完整叙事站点。所以初始化控制页数，宁可进待办也不堆薄页；更新禁止为排版空转。标准不是「写全」，而是「下次任务能不能更快读到对的上下文」。组织账本也换了：记账挪给模型和 CI，人改成审稿——动的是生产制度，不只是又一个写作工具。
粒度也不按「一个源文件一页」。阅读做领域采样（树、配置、入口、代表文件），禁止根目录穷举。落盘按认证、订单状态机、发布流水线这类可行动概念成页；薄页合并，小仓甚至快速开始加一两页就够。首次生成常见预算大约最多八页，装不下的进待办。更新按 diff 冲击面动刀：变更很少时通常只改一两页。上游粗采样，中游按概念成页，下游按任务展开。
知识生产：原材料经综合变成概念图，经审稿进入可复用百科，再被编程智能体按需消费
原材料经综合变成概念图，经审稿进入可复用百科，再被编程智能体按需消费
内核其实就一句：在源码之上，持续生产可错、可审、可导航、可增量修订的解释性知识，专供智能体低成本复用。
三、怎么跑起来的：主机定边界，模型做综合
实现不是「解析 AST → 填模板」。它是受约束的智能体运行时：主机准备证据和边界，DeepAgents 会话用工具综合与写盘，主机再做一致性裁定。init建底稿，update按变更窗口小改，chat回答问题且默认不乱改文档。
命令行层管体验和密钥（进~/.openwiki/.env，不进仓库）。运行时在src/agent/index.ts：收集 git 证据、给百科做内容快照，再拉起会话。会话挂虚拟文件系统、连接器工具、SQLite 检查点，以及很长的系统提示词——提示词才是控制面，不是说明书附件。
沙箱决定写得进哪里。代码模式下，写入被限制在openwiki/；虚拟路径让/README.md映射到仓库根，避免宿主机绝对路径写歪。连接器涉及外部凭证时，先确定性拉到本地 raw，再让模型读文件。个人模式同样：ingest拉数，综合会话再写~/.openwiki/wiki，拉数与写百科拆开，降低密钥乱飞和提示注入风险。
提示词里几条纪律决定它像不像文档系统：别全仓穷举；先写后删临时计划页；更新要手术刀式；重要论断要接地；init/update/chat三种任务语义分开。大仓可用子智能体只读调研，但写盘仍归主会话。口头禅会漂，所以还有沙箱、快照、确定性生成的index.md托底。
模型供应商集中配置。选定一个后，瞬时失败可以重试；最终失败就停，而不是悄悄换更弱的模型凑合写完——静默降级会让你误以为百科已经可靠。
增量靠两套锚点卡住。主机注入 git 变更窗口，模型不是凭感觉猜「最近好像改了认证」。任务前后对百科做内容哈希，只有真改了才推进.last-update.json；没改动却推进锚点，后面会误以为已经同步。没有实质源码变更时，更新可以直接短路跳过，省钱也防空转。
更新闭环：空跑检测、证据注入、手术刀改写、内容快照、指令文件指针
空跑检测、证据注入、手术刀改写、内容快照、指令文件指针
串起来：要不要跑 → 注入变更窗口 → 定向阅读并改页 → 沙箱拦越界 → 哈希决定是否更新锚点 → CI 有 diff 再开 PR。智能体负责综合，流水线负责节奏，人负责签字。
四、怎么用：装上、让 Agent 读、再养起来
环境需要 Node 22+：
npm install -g openwiki cd your-repo openwiki --init按提示选供应商和密钥。成功后出现openwiki/，根目录AGENTS.md/CLAUDE.md会插入或刷新 OpenWiki 引用块（只改自己的标记区间）。也可以openwiki code --init；个人模式是openwiki personal --init。
想写清范围，可先放openwiki/INSTRUCTIONS.md（人写的简报，普通更新不会擅自重写），再带诉求跑更新，往往比盲目重跑 init 稳。
下面三条路径，覆盖大多数人真正会用到的部分。
示例一：中型业务仓做首轮百科
假设仓库带登录、订单、后台任务。在仓库根执行上面的--init。跑完后结构大致是：
openwiki/ quickstart.md architecture/ auth/ orders/ operations/ AGENTS.md CLAUDE.md先打开openwiki/quickstart.md：它能不能回答「这仓库干什么、从哪进、下一步读哪」？再看待办区，有没有把真实领域悄悄丢掉。写飘了就先改INSTRUCTIONS.md，例如：
# 仓库文档简报 优先讲清：HTTP 入口、认证会话、订单状态机、异步出账任务。 不要展开：第三方 SDK 内部实现、生成代码目录。 读者是编程智能体：每页保留入口文件与改动时该跑的检查。然后再：
openwiki --update 「按 INSTRUCTIONS.md 收紧范围，补订单与出账，薄页合并进快速开始或待办」示例二：编程智能体怎么消费（你几乎不用改习惯）
百科生成后，照常在 Cursor / Claude Code / Codex 里提需求：
给订单服务加「超时自动取消」。先对齐现有状态机和定时任务入口，再改代码。
比较靠谱的路径：读AGENTS.md看到指针 → 打开openwiki/quickstart.md→ 跟链接进订单/运维页 → 核对源码锚点 → 回真实代码改，并按页里提示跑测试。
你不必把 wiki 贴进对话。引用块还在、quickstart 能带路，就够了。若它仍盲扫全仓，任务里加一句：「先读openwiki/quickstart.md和订单相关页，再改代码。」
示例三：改完代码后更新，CI 养文档
合并「登录从 JWT 改成服务端 Session」之后：
openwiki --update 「登录已改为服务端 Session；请更新认证相关页，并检查快速开始是否仍写 JWT」理想 diff 只动认证页和 quickstart 里过时的两三句。审的时候盯三件事：旧术语清没清；入口文件对不对；有没有把无关页顺便润色一遍。
要让百科活着，把示例工作流拷进仓库，CI secrets 配好密钥，定时跑：
openwiki code --update --print有变更就开文档 PR。人只审：有没有虚构模块、该改的页改了没有、有没有无故重写。合并后，所有编程智能体自动读到新地图。
交互追问用openwiki；脚本里用openwiki -p 「...」。个人模式（openwiki personal）和仓内openwiki/分开：编程任务读仓内百科，跨项目个人上下文走 personal，别揉成一个目录。
五、可能翻车的地方，以及能搬走的东西
OpenWiki 仍是早期产品。本地模型、忽略规则、更细写权限、可观测性，都是真实张力：既要读够证据，又不能泄露秘密；既要自动维护，又不能制造文档噪音；既要解释，又要防幻觉。
弱模型容易写出结构整齐、细节发飘的页。把它当自动作者，你会很快失去信任；当自动记账员加初稿作者，人做抽检，才比较符合设计假设。私有代码会经过你配置的模型供应商，合规上按团队要求选网关或暂缓上传。
即便不用这个 CLI，也值得搬走这套分工：综合发生在入库与更新，而不是每次聊天归零；人策展审稿，模型编译记账，主机守边界；产物按概念成页，指针进指令文件；增量同时盯「源变了没有」和「产物变了没有」。
今天就能做的最小闭环：
npm install -g openwiki cd your-repo openwiki --init然后在 Cursor 里提一个真实小需求，看它会不会先读openwiki/quickstart.md。会，这套消费链路就通了；不会，先检查AGENTS.md里的 OpenWiki 引用块还在不在。
