Codegraph

CodeGraph

启动方式

先把本 SKILL.md 所在目录的绝对路径保存为 Skill 目录。不得假设当前工作目录就是 Skill 目录，也不要直接运行相对路径 scripts/codegraph.*。

macOS、Linux、WSL 或 Git Bash：

CODEGRAPH_SKILL_DIR="/absolute/path/to/installed/codegraph"
cg() { bash "$CODEGRAPH_SKILL_DIR/scripts/codegraph.sh" "$@"; }

Windows PowerShell：

$CodeGraphSkillDir = "C:\absolute\path\to\installed\codegraph"
function cg { & (Join-Path $CodeGraphSkillDir "scripts/codegraph.ps1") @args }

cg 只在当前 shell 会话有效。若宿主无法执行对应 wrapper，可使用相同参数直接调用 codegraph CLI。

前置检查

先阅读 [CLI 兼容性契约](references/cli-compatibility.md)，再检查当前版本和关键能力：

cg check

如果找不到 CLI，先说明安装会修改用户环境，并让用户选择官方 standalone installer 或 npm 全局安装；未经明确同意不要安装、升级或执行远程脚本。安装方式和平台说明见 [工作流参考](references/workflows.md)。

首次使用 explore 或 node 时，可用 cg raw explore --help 和 cg raw node --help 做能力检查。旧版 CLI 不支持时，先使用结构化查询降级；只有用户同意后才升级。

首次在项目中初始化前：

1. 确认目标项目和索引写入范围。
2. 如果是 Git 项目，使用 git check-ignore 确认 .codegraph/ 已被忽略。
3. 未忽略时，先取得用户同意，再在适用的 .gitignore 中加入 .codegraph/ 或 **/.codegraph/。
4. 运行 cg init .；wrapper 会拒绝在未忽略索引目录的 Git 项目中初始化。
5. 用 cg status . 确认索引状态。

不要因为分析结束就自动删除索引。只有用户明确要求清理时才运行 cg uninit . --force，随后检查工作区状态。

默认检索顺序

1. cg status .：确认项目是否已初始化。
2. cg explore . "问题、流程或目标符号"：默认入口，一次获取相关源码、调用路径和影响摘要。
3. cg node . TargetSymbol：读取单个符号及其调用关系。
4. cg node . --file path/to/file --offset 1 --limit 200：按行读取文件并查看依赖。
5. 需要结构化细查时再使用 files、query、callers、callees、impact 和 affected。

cg files . --format tree --max-depth 2 --no-json
cg query . TargetSymbol --limit 5
cg callers . TargetSymbol --limit 20
cg callees . TargetSymbol --limit 20
cg impact . TargetSymbol --depth 2
cg affected . path/to/changed_file.ext

status、files、query、callers、callees、impact 和 affected 默认输出 JSON；需要原始可读输出时加 --no-json。explore 和 node 使用 CLI 原生文本输出。

索引维护

当前 CodeGraph 初始化后会自动同步文件变化。只有状态异常、文件大量移动或结果明显过期时才手工执行：

cg sync .
cg index . --force
cg unlock .

解读 status 时区分增量同步与提取器版本：

• pendingChanges 为 0 只表示工作区没有等待增量同步的文件，不表示索引由当前提取器完整构建。
• index.builtWithExtractionVersion 为 null 或低于 currentExtractionVersion 时，当前 CLI 会设置 reindexRecommended: true；builtWithVersion 只记录完整建索引时的 CLI 版本。
• sync 只处理文件增删改，不能替代完整重建。出现上述组合时，先说明原因；获得用户同意后运行 cg index . --force，再用 cg status . 复核。

升级会修改全局或 standalone 安装。只有用户明确要求时才运行 cg upgrade --check 或 cg upgrade。

使用边界

• 精确字符串、错误消息、配置项、环境变量和非代码文件优先用 rg 或宿主等价工具。
• CodeGraph 结果是索引视角；运行时注册、反射、生成代码、外部依赖和初始化副作用仍需源码与测试确认。
• 框架路由识别是尽力而为。受支持框架的路由缺失且状态建议重建时，先完整重建再复测，不要直接归因于静态分析能力。
• HTTP 路径字符串、动态 URL 拼接、前后端跨语言消费者、ORM 字段和业务状态关系不保证形成图边；结合 rg、源码、迁移和测试补齐影响面。
• affected 为空不等于没有回归风险；检查测试命名、过滤条件、语言支持和索引覆盖。
• CLI 不存在、语言不支持、索引损坏或 wrapper 不兼容时，退回常规文件检索，不要阻塞任务。
• init、.gitignore 编辑、安装、升级和 uninit 都会改变状态，执行前遵循用户授权边界。

更多安装、跨平台命令、降级和评估场景见 [工作流参考](references/workflows.md)；版本漂移和能力探测见 [CLI 兼容性契约](references/cli-compatibility.md)。

本 Skill 及其分发包使用 [MIT License](LICENSE)。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: betterlmy
• Source: betterlmy/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.