CodeGraph 索引指南init 一步建图、增量 sync 与 MCP 会话中的三层自动保鲜机制【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraphCodeGraph 把项目预先索引为一张本地代码知识图谱存储于项目根的.codegraph/目录供 Claude Code、Codex、Gemini、Cursor、OpenCode、Antigravity、Kiro、CoPilot 等 AI Agent 通过 MCP 调用。本文围绕 官方索引指南 展开先讲清init/index/sync三类命令的分工再深入文件监听器、防抖同步、按文件陈旧度横幅与连接时追赶这三层自动保鲜机制的源码实现最后说明如何验证索引是否跟手、以及极少数的手动同步场景。读完你可以掌握如何一步初始化索引、如何让图谱在 Agent 会话期间与磁盘代码保持同步、以及当 Agent 询问索引是否已追上时该看哪个输出块。一步完成初始化与全量索引cd your-project codegraph init # 创建 .codegraph/ 并构建全量图谱 —— 一步到位codegraph init在同一个步骤内完成两件事创建本地.codegraph/数据目录并构建全量图谱。不存在init 之后再单独跑 index的环节——建图完成后图谱的保鲜就交给后文所述的自动机制。三个索引命令的分工codegraph index # 全项目全量索引 codegraph index --force # 从头重建丢弃既有索引 codegraph sync # 增量同步 —— 只重新解析发生变化的文件sync之所以快是因为它只重新解析变化过的文件——文件监听器在每次编辑后替你跑的就是它日常几乎不需要手动执行。从源码结构看sync内部有一条作用域快速路径当待处理文件集合是监听事件直接给出的精确文件列表、且规模不超过阈值watcher.ts 中SCOPED_SYNC_MAX_PENDING 500时直接把这些路径交给同步流程、跳过 O(仓库规模) 的扫描比对只有当事件无法完整描述变化如目录删除、事件风暴超过 500 个文件时才回退到全量扫描比对作为地面真值。三层自动保鲜编辑到下一次查询之间Agent 不会拿到静默的错答案在 Agent 会话中你不需要手动跑codegraph sync。当你的 Agent 通过codegraph serve --mcp启动 MCP 服务时三层机制协同保证索引与代码同步并且在编辑发生到下一次同步完成之间那个小窗口里绝不让 Agent 拿到一个静默的错误答案。第一层文件监听器 防抖自动同步始终开启MCP 引擎在打开项目后会启动一个原生文件监听器macOS 上走 FSEventsLinux 上走 inotifyWindows 上走 ReadDirectoryChangesW监听范围是整个项目根目录。每个源文件的创建 / 修改 / 删除事件都会被捕获一个防抖定时器把成串的编辑合并为一次同步。事件流的典型时序agent writes src/Widget.ts → watcher fires (event delivery: typically 100ms) → 2000ms debounce → sync runs; Widget.tss nodes edges are in the index → next agent query sees it可调参数环境变量CODEGRAPH_WATCH_DEBOUNCE_MS可覆盖默认 2000ms 的防抖窗口取值被钳制在[100ms, 60s]。当构建步骤或格式化工具在短时间内密集写大量文件时把它调大到5000或10000让监听器把这些写入合并成一次同步。源码层面这个参数在 engine.ts 的parseDebounceEnv()中解析非数字、非整数或越界值一律视为忽略这个错误配置回退到FileWatcher的默认 2000ms——设计上选择不悄悄钳位因为把 0 或笔误值静默封顶会掩盖真实的配置错误生效值会打印到 stderrFile watcher debounce: msms (CODEGRAPH_WATCH_DEBOUNCE_MS)以便排查。watcher.ts 中的实现还有两个超出文档细节的要点解释了为什么这套监听器既快又省资源平台策略是有界的macOS/Windows 使用单个递归fs.watchlibuv 映射为一条 FSEvents 流 / 一个 ReadDirectoryChangesW 句柄无论树多大都只占 O(1) 描述符Linux 不支持递归监听因此对每个非忽略的目录各挂一个 inotify watch代价是 O(目录数) 而非 O(文件数)。目录数上限默认 5 万可用CODEGRAPH_MAX_DIR_WATCHES调整触发fs.inotify.max_user_watches内核上限表现为ENOSPC时只告警并停止新增监听已装的 watch 继续工作警告信息会直接给出调高上限的sysctl命令。自适应防抖快速路径待处理文件数不超过 2 个时一次单独的保存或编辑器文件 对应测试文件这种成对出现防抖窗口缩短为 300ms 的快速静默窗下限 100ms图谱几乎即时更新更大的批量变更仍走完整防抖窗口行为与之前完全一致。防抖语义始终是尾沿trailing-edge——每次新事件都会重置计时器。同步失败的处理同样有界写锁竞争另一个进程持有数据库写锁连续 5 次、或一般性同步失败解析器崩溃、DB 损坏等确定性错误连续 5 次后监听器会永久降级degrade而不是无限重试刷日志并通过回调把自动同步已禁用请手动跑codegraph sync这类可执行的原因报告给宿主进程指数退避重试的封顶值为 30 秒。第二层按文件陈旧度横幅 —— 覆盖防抖窗口防抖引入了一个约 2 秒的窗口刚编辑过的文件已在磁盘上、但还没进索引。CodeGraph 用一个按文件的陈旧度横幅封住这个窗口——如果任何 MCP 工具响应引用了当前待重新索引的文件响应开头就会追加一个⚠️横幅点名这些陈旧文件⚠️ Some files referenced below were edited since the last index sync — their codegraph entries may be stale: - src/Widget.ts (edited 800ms ago, pending sync) For accurate content of those specific files, Read them directly. The rest of this response is fresh. ## Code Context …Agent 读到后会直接对点名的文件发起Read跟进——官方文档说这一点已经用 Claude Code 端到端验证过Agent 会字面地说出 Reading the file directly for the live content 再去打开文件。也就是说即使在 2 秒的防抖窗口内Agent 也绝不会拿到静默的错误答案。未被响应引用的待处理文件则改以一个小尾注形式呈现Note: N file(s) elsewhere in this project are pending index sync but were not referenced above: …保证新鲜度信号始终是显式的不会悄悄丢失。源码上横幅与尾注的文案都由 tools.ts 中的两个纯函数生成formatStaleBanner()横幅逐文件列出edited msms ago与pending sync/indexing in progress状态和formatStaleFooter()尾注最多列 5 个文件超出部分折叠为一行…and N more。而哪些文件是待处理的来自FileWatcher.getPendingFiles()每个待处理文件记录首次/最近一次事件时间且条目只在同步成功提交后、且其最近事件早于同步开始时间时才被清除——同步过程中到达的新事件会继续挂起留给下一轮同步。注释里写明了取舍偏好宁可误报陈旧代价至多是 Agent 多 Read 一次不可误报新鲜会让 Agent 基于过期索引给出错误答案。另有一个整索引级别的横幅值得知道当实时监听永久停止资源耗尽、锁竞争超过预算等getPendingFiles()为空、按文件横幅不会触发此时读取类工具会改发⚠️ CodeGraph auto-sync is DISABLED横幅告知 Agent 整个索引已冻结、应直接 Read 文件确认——同样是绝不静默原则的延伸。第三层连接时追赶同步 —— 覆盖 MCP 服务未运行的空窗当你的编辑器 / Agent 与 MCP 服务重新连接时CodeGraph 会在回答第一个查询之前先跑一次快速的基于文件系统的对账先用(size, mtime)stat 预筛再对其余文件做内容哈希比对。于是那些在没有 MCP 服务运行期间发生的变化——终端里的一次git pull、从另一个编辑器进来的编辑、一个已经跑完退出的 Agent——都会在下一个会话的第一个工具调用中被自动追上。源码上这个动作是 engine.ts 的catchUpSync()在open()之后立即在后台执行cg.sync()并把返回的 Promise 交给工具处理层作为一个一次性门闸——第一个工具调用必须等它完成才返回。这一步的必要性在于追赶同步不经过监听器getPendingFiles()里不会有它的影子陈旧度横幅帮不上忙没有门闸的话抢先于同步完成的查询会返回文件在磁盘上已不存在的旧行。同步完成后若有变化stderr 会打印Caught up N file(s) changed since last run。验证监听器看到了什么codegraph_status工具把待处理集合作为一等公民暴露出来——Agent 问索引追上了吗只需一次调用codegraph_status → ## CodeGraph Status … ### Pending sync: - src/Widget.ts (edited 1200ms ago)如果响应里没有Pending sync:段就说明当前没有任何同步在途。对应实现见 tools.ts 的handleStatus()它除了逐文件列出待处理项含edited ms ago与pending sync/indexing in progress状态还会报告文件 / 节点 / 边计数、数据库大小、当前 SQLite 后端与日志模式journal mode 非wal时会警告读取可能被并发写入阻塞、被中断的解析残留Pending resolution以及自动同步已禁用段若监听器永久降级这里会明确说索引已冻结请直接 Read 文件。CLI 侧codegraph status报告节点 / 边 / 文件计数、活动 SQLite 后端与日志模式Agent 会话中的 MCP 侧codegraph_status额外给出上面描述的Pending sync:块。什么时候才需要手动codegraph sync答案几乎从不需要。只有两个边缘场景监听器被禁用时。沙箱环境会阻止本地文件监听或者你设置了CODEGRAPH_NO_DAEMON1退出共享守护进程模式——这两种情况下codegraph sync是手动兜底。监听禁用原因由 watch-policy.ts 统一判定例如 WSL2 下/mnt/挂载盘上的fs.watch会长时间阻塞会被主动跳过并提示手动同步或 git 钩子。CI 跑之前的预检。如果你是在 Agent 会话之外、通过脚本直接消费索引在脚本开头跑一次codegraph sync可以保证索引反映当前工作树。除此之外直接用就行。监听器 横幅 连接时同步已经端到端覆盖了 AI 辅助工作流。如果你在防抖窗口早已过去之后仍看到文件被真正漏掉那是一个 bug——请带着复现步骤提 issue。哪些文件会被索引所有扩展名映射到支持语言的源码文件减去以下排除项默认排除的依赖 / 构建目录node_modules、vendor、dist等你.gitignore排除的一切超过 1 MB 的文件。监听器与索引器共用同一套作用域匹配器内置默认排除 项目.gitignorecodegraph.json的 include/exclude 规则两者作用域永远一致.codegraph/数据目录与.git/无论如何都会忽略。完整的排除 / 包含配置与语言清单见官方文档站中的 Configuration 与 Supported Languages 页面。小结CodeGraph 的索引模型可以概括为一句话init一步建图sync只管增量保鲜交给自动机制。三层机制各管一段窗口——监听器 防抖覆盖正常编辑流按文件陈旧度横幅覆盖防抖窗口内的查询连接时追赶同步覆盖服务未运行的空窗codegraph_status的Pending sync:块则是验证一切是否跟手的单一入口。若需进一步阅读源码建议从 watcher.ts监听与防抖、engine.tsMCP 侧启动、防抖参数解析、追赶同步门闸与 tools.ts状态输出与三类陈旧度横幅文案三个文件切入配套测试可参考 watcher.test.ts 与 mcp-staleness-banner.test.ts。【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考