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 22npm 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 引用块还在不在。