GitNexus 调试技能用于在调试 bug、追踪错误或分析某处为何失败时，基于已索引的代码仓库进行根因定位。
一、适用场景 该技能适用于以下提问或任务：为什么某个函数失败、追踪某个错误的来源、谁调用了某个方法、某接口返回 500，以及调查 bug、错误或非预期行为。
二、使用前提：先绑定仓库 在错误仓库中追踪到的根因是错误根因。首次调用工具前需调用 list_repos {}。若只有一个已索引仓库，可直接使用下述示例；若有多个仓库，则每次调用都需传入 repo。省略 repo 通常会报错，但在配置了默认值的 MCP 策略下会静默解析为该默认值。若无法判断指向哪个仓库，应停止并询问。这对 cypher 尤为重要，因为其语句本身不携带在哪个数据库上运行的提示。list_repos 是分页的，应通过 offset 即 pagination.nextOffset 翻页，直到 hasMore 为 false，才能断定某仓库不存在。索引过期意味着它描述的是 bug 之前的代码，因此应在信任追踪结果前刷新，并在诊断中说明仓库与索引新鲜度。
三、工作流程 0. list_repos {} 绑定仓库
- query({search_query: "<错误或症状>"}) 查找相关执行流程
- context({name: "<可疑对象>"}) 查看调用者、被调用者与流程
- READ gitnexus://repo/{name}/process/{name} 追踪执行流程
- cypher({statement: "MATCH path..."}) 需要时进行自定义追踪 若提示 “Index is stale”，在终端运行 node .gitnexus/run.cjs analyze。热工具过期状态会指出哪个索引作答（branch/lastCommit）以及新鲜程度（status）。仅在 behind 或 diverged 时重新分析；current 表示一致，unknown 表示无法测量。
四、检查清单
- list_repos {} 绑定仓库；已索引仓库多于一个时显式指定 repo，模糊时询问
- 理解症状（错误信息、非预期行为）
- 用 query 检索错误文本或相关代码
- 从返回的流程中识别可疑函数
- 用 context 查看调用者与被调用者
- 如适用，通过 process 资源追踪执行流程
- 如需要，用 cypher 做自定义调用链追踪
- 阅读源文件确认根因
- 在诊断中说明仓库与索引新鲜度
五、调试模式 错误信息：query 检索错误文本，再对抛出位置执行 context。 返回值错误：对函数执行 context，追踪被调用者以分析数据流。 间歇性失败：context，查找外部调用与异步依赖。 性能问题：context，查找调用者众多的符号（热点路径）。 近期回归：detect_changes 查看改动影响，若为链接工作树则传入 worktree。 “A 如何到达 B？”：在两个符号之间 trace，一次调用得到最短调用链。
六、工具说明 query 用于查找与错误相关的代码，例如 query({search_query: "payment validation error", repo: "my-app"})，会返回流程与符号。 context 用于查看可疑对象的完整上下文，例如 context({name: "validatePayment", repo: "my-app"})，会返回入向调用、出向调用与所处流程。 cypher 用于自定义调用链追踪。需在语句旁传入 repo，因为 Cypher 文本本身不指明仓库，缺少它将无法归属结果。示例语句：MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"}) RETURN [n IN nodes(path) | n.name] AS chain。 trace 用于追踪两个符号之间的最短调用链，一次调用即可，无需串联多次 context。例如 trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })，返回 status、hopCount、hops 与 edges。当不存在路径时，trace 会报告最远可达节点，即调用链断裂的位置（动态分发、反射或外部边界）。
七、示例：支付接口间歇性返回 500 0. list_repos {} 返回 total: 2（my-app、billing-api），因此每次调用显式绑定 my-app。
- query({search_query: "payment error handling", repo: "my-app"}) 返回流程 CheckoutFlow、ErrorHandling，以及符号 validatePayment、handlePaymentError。
- context({name: "validatePayment", repo: "my-app"}) 返回出向调用 verifyCard、fetchRates（外部 API）。
- READ gitnexus://repo/my-app/process/CheckoutFlow，显示第 3 步 validatePayment 调用 fetchRates（外部）。
- 根因：fetchRates 调用外部 API 时缺少适当超时。仓库：my-app 索引：current。 若只有一个已索引仓库，步骤 0 返回 total: 1，上述每次调用中的 repo 参数可省略。