colbymchenry/codegraph
一句话理解
CodeGraph 在本地预先记录函数、类、方法等代码元素,以及调用、导入、继承等关系。编程助手可以沿着这份关系图取回相关源码,把查询落到具体定义和调用位置。
它解决什么问题
当你问编程助手某段逻辑从哪里进入,或者改一个函数会影响哪些地方,助手往往要先逐个搜索和打开文件,再拼出调用链。CodeGraph 把这段查找工作提前到项目建索引时。输入是项目源码和一个关于代码结构的问题,输出是相关源码、调用路径和可能受影响的范围。试用时可以先用一道自己知道答案的跨文件问题验收,看助手能否指出正确的入口、调用顺序和对应源码,再看它为此翻了多少文件。
从输入到输出
流程分五步。第一步,接入编程助手并为每个项目单独初始化。接入让助手能调用查询服务,初始化才会创建项目索引。第二步,解析识别到的源码,提取函数、类、方法以及它们引用的名称。第三步,把调用对到定义、把导入对到文件,并将解析得到的关系存入本地 SQLite 数据库。缺少某条跨文件关系时,沿图追踪就可能漏掉后续代码。第四步,助手通过 MCP 这个工具接口发出查询,拿回按文件归组的源码、调用链和影响范围摘要。如果目标项目还没有索引,查询会提示改用助手自带的工具。第五步,服务监听源码变动,等短时间内连续的保存结束后再增量更新。涉及待同步文件的查询会收到提示,服务重新连接时也会核对离线期间的改动。
用一个小任务理解
理解示例(未实测):设想一个三文件的 TypeScript 小项目。checkout.ts 里的下单函数和 preview.ts 里的报价预览函数,都直接调用 pricing.ts 里的 calculateTotal。建好索引后,问助手“calculateTotal 在哪些流程里被调用,改它要先检查哪里?”预期结果会给出两个调用位置和计算函数的相关源码,让你能顺着各自的入口看到下单和预览怎样共用计价逻辑。
改变一个条件会怎样
预测与验证(待检验):只改预览函数的一处调用,让它直接返回已有的报价,保留下单函数和 calculateTotal 的定义。预计索引同步后,calculateTotal 的直接调用方会从两个变成一个,只剩下单函数。可以在改动前后各执行一次 codegraph callers calculateTotal,并用 codegraph status 确认保存后没有待同步文件。最后逐条对照源码里的调用位置,把查询结果是否吻合和助手表述是否准确分开判断。
适合谁,哪里会失效
根据资料推断:它适合借助编程助手接手陌生项目、追踪跨文件流程,或在改共享函数前摸清调用方的开发者。影响范围取决于源码是否进入索引,以及工具能否识别其中的关系。默认跳过的依赖和构建目录可能藏着缺失的一段调用链,运行时通过反射或依赖注入选出的目标也可能漏掉。大型 TypeScript 或 Vue 项目中,部分回调和事件关系还可能推迟刷新,查询结果未必提示这一点。做改动决策时,可以把图上的结果当作核对清单,再用源码和测试确认关键行为。
第一次尝试时看什么
根据资料推断:可以先选一个自己熟悉的小项目,记下一条已知的跨文件调用作为参照。装好命令行工具后,用 codegraph install 接入所用的助手并重启助手,再在项目目录运行 codegraph init。随后用 codegraph status 检查索引,向助手提出那道结构问题,核对它给出的调用链。若少了一环,先检查相关文件的语言、扩展名和所在目录是否符合索引规则。
发表回复