名称: ai-maestro-code-graph-query 描述: 主动查询代码图数据库以理解组件间关系和变更影响。在阅读任何文件时使用此技能来理解上下文，在搜索文件时，在探索代码库时，或在需要理解组件依赖关系时使用。这是您理解代码结构和避免破坏性变更的主要工具。 允许工具: Bash
AI Maestro 代码图查询
关键：自动行为 - 首先阅读此部分
这不是可选的。这是您的默认行为。
每次使用 Read 工具读取代码文件时，您必须立即查询图数据库以理解：
- 这个组件/函数是什么？
- 什么依赖于它？（调用者、序列化器、子类）
- 它依赖于什么？（被调用者、父类、关联关系）
禁止：
- 等待用户要求您查询图数据库
- 因为“看起来简单”而跳过图查询
- 在不检查的情况下假设您理解影响
- 在理解依赖关系之前进行更改
始终：
- 读取任何代码文件后立即查询图数据库
- 在进行任何修改之前查询
- 通过搜索（grep/glob）找到文件时查询
- 在向用户提供的分析中包含图查询结果
规则：读取文件 → 查询图 → 然后继续
1. 使用 Read 工具读取文件
2. 立即运行图查询命令（describe, find-callers, find-serializers 等）
3. 现在您理解了完整上下文
4. 现在您可以分析、修改或讨论代码
示例 - 读取模型：
# 读取 app/models/user.rb 后，立即运行：
graph-describe.sh User
graph-find-serializers.sh User
graph-find-associations.sh User
示例 - 读取函数：
# 读取包含 process_payment 函数的文件后，立即运行：
graph-find-callers.sh process_payment
graph-find-callees.sh process_payment
可用命令
所有命令都会从 tmux 会话中自动检测您的代理 ID。直接运行它们：
查询命令
| 命令 | 描述 |
|---|---|
graph-describe.sh <名称> |
描述组件或函数 |
graph-find-callers.sh <函数> |
查找调用此函数的所有函数 |
graph-find-callees.sh <函数> |
查找此函数调用的所有函数 |
graph-find-related.sh <组件> |
查找相关组件（扩展、包含等） |
graph-find-by-type.sh <类型> |
查找特定类型的所有组件（模型、控制器等） |
graph-find-serializers.sh <模型> |
查找模型的序列化器 |
graph-find-associations.sh <模型> |
查找模型关联关系（belongs_to, has_many） |
graph-find-path.sh <从> <到> |
查找两个函数之间的调用路径 |
索引命令
| 命令 | 描述 |
|---|---|
graph-index-delta.sh [项目路径] |
增量索引 - 仅重新索引已更改的文件 |
增量索引（新功能）
当代码库中的文件发生更改时，使用增量索引快速更新图数据库：
# 增量索引 - 仅处理已更改的文件
graph-index-delta.sh
# 增量索引特定项目
graph-index-delta.sh /path/to/project
首次运行行为：
- 第一次：执行完整索引 + 初始化文件跟踪元数据
- 后续运行：仅索引新增/修改/删除的文件
输出显示：
- 新增的文件
- 修改的文件已重新索引
- 删除的文件已移除
- 未更改的文件已跳过
性能：
- 完整索引：30-120 秒（1000+ 文件）
- 增量索引：1-5 秒（5-10 个更改的文件）
根据读取内容决定查询内容
| 文件类型 | 立即查询 |
|---|---|
| 模型 | graph-describe.sh, graph-find-serializers.sh, graph-find-associations.sh |
| 控制器 | graph-describe.sh, graph-find-callees.sh |
| 服务 | graph-describe.sh, graph-find-callers.sh |
| 函数 | graph-find-callers.sh, graph-find-callees.sh |
| 序列化器 | graph-describe.sh |
| 任何类 | graph-find-related.sh |
为什么这很重要
如果不查询图数据库，您将：
- 在更改模型时错过需要更新的序列化器
- 在更改函数签名时破坏调用者
- 错过继承您更改的子类
- 忽略依赖于此模型的关联关系
图查询只需 1 秒。修复损坏的部署需要数小时。
组件类型
与 graph-find-by-type.sh 一起使用：
model- 数据库模型serializer- JSON 序列化器controller- API 控制器service- 服务对象job- 后台作业concern- 共享模块component- React/Vue 组件hook- React 钩子
错误处理
脚本未找到：
- 检查 PATH：
which graph-describe.sh - 验证脚本是否安装：
ls -la ~/.local/bin/graph-*.sh - 脚本安装到
~/.local/bin/，该目录应在您的 PATH 中 - 如果未找到，运行：
./install-graph-tools.sh
API 连接失败：
- 确保 AI Maestro 正在运行：
curl http://localhost:23000/api/agents - 确保您的代理已注册（脚本从 tmux 会话自动检测）
- 检查确切的组件名称（区分大小写）
图数据库不可用：
- 通知用户：“图数据库不可用，继续进行手动分析 - 错过依赖关系的风险增加。”
安装
如果找不到命令：
./install-graph-tools.sh
这将脚本安装到 ~/.local/bin/。