用途:当编码智能体需要了解符号关系、调用者、被调用者或变更影响时,按本指南使用 CodeGraph 命令行工具。CodeGraph 为本项目提供预索引的 AST 代码图;本技能只使用 CLI,不运行 codegraph install(该命令单独配置 MCP/智能体规则)。
命令解析(优先顺序):1) ~/.terrain/bin/codegraph(Terrain 环境集成);2) bunx codegraph(无 Terrain 安装,需一次联网);3) npx codegraph。仅使用常规路径,不要用 /Users/… 或 C:\Users\… 这类机器专属绝对路径。Windows 下包装器可能是 ~/.terrain/bin/ 下的 codegraph.cmd 或 codegraph.exe。可选清单 .terrain/env/agent-tools.json(本地、被 gitignore)沿用相同约定。
存在性检查:bash/zsh/Git Bash 用 [ -x ~/.terrain/bin/codegraph ] || [ -f ~/.terrain/bin/codegraph.exe ] || [ -f ~/.terrain/bin/codegraph.cmd ];PowerShell 用 Test-Path "$HOME.terrain\bin\codegraph*"。示例中 <cg> 表示解析出的前缀。
前置条件:索引按仓库存放于 .codegraph/。若缺失,在仓库根目录初始化,例如 bunx codegraph init -i;编辑后执行 <cg> sync 刷新;用 <cg> status 做健康检查。注意 status 可能失真(例如索引 10 天未更新却仍报告最新,对新符号查询无结果),不可单独作为权威判断。
主要命令:<cg> query <name> 按名查找符号;<cg> callers <symbol> 查调用者;<cg> callees <symbol> 查被调用;<cg> impact <symbol> 评估变更影响面;<cg> affected <files…> 查受文件变更影响的测试;<cg> files 列出项目文件树;<cg> status 查看索引健康;<cg> sync 编辑后刷新。
推荐流程:先读 .terrain/agent/context.md;始终先 <cg> sync(廉价、增量,且不必依赖 status 的自我声明);用 query 定位定义;用 callers/callees/impact 回答关系问题;需要某文件完整源码时用 repomix-context-skill;后续 shell 命令(测试、git)使用 rtk-skill。
强制的新旧度交叉校验:在信任 impact/callers/callees 结果做安全相关判断前(如“能否安全删除某函数”),运行 ~/.terrain/bin/terrain tools codegraph-drift --project <slug>(或 bunx @terrain-ai/cli tools codegraph-drift --project <slug>),它把 .codegraph/codegraph.db 的修改时间与 git log --since 对比,独立于 CodeGraph 自身记账。若 likely_stale: true,先 <cg> sync 再复核。
不应当:运行 codegraph install;盲目全仓库 grep 复核 AST 结果;在 impact 已能回答问题时串行查询加手工读文件。
限制:资料只描述上述 CLI 用法与注意事项,未提供收费、价格、平台覆盖或效果数据;status 结果不可单独采信。