gitnexus-debugging

使用 GitNexus 调试

适用场景

• “为什么这个函数会失败？”
• “追踪此错误的来源”
• “谁调用了这个方法？”
• “这个端点返回 500”
• 调查 Bug、错误或意外行为

先绑定仓库

如果在错误的仓库中追踪根因，得到的根因就是错的。

使用已确认的注册名称／路径或已配置的 MCP 默认值绑定一次。如果尚未确定目标，请调用 list_repos {}；后续调用均复用该绑定。只有一个已索引仓库时，请按下方示例操作。多个仓库时，每次调用都传入 repo：省略 repo 通常会报错，但如果 MCP 策略配置了默认值，则会静默地解析为该默认值。如果无法判断 指的是哪个仓库，请停止并询问。这一点对 cypher 尤其重要，因为它的语句本身不包含任何关于所查询数据库的提示。

list_repos 会分页，因此请使用 offset: pagination.nextOffset 获取后续页面，直到 hasMore 为 false，再断定某个仓库不存在。

过期索引描述的是 Bug 出现之前的代码，因此在信任追踪结果前请先刷新索引，并在诊断中说明仓库及索引的新鲜度。

工作流

0. Bind the repo once (list_repos only if not already known)
1. If the suspect is unknown, query for the error/symptom with small result limits
2. context({name: "<suspect>"})                    → See callers/callees/processes
3. Read a process resource only if its trace resolves an open question
4. cypher({statement: "MATCH path..."})                 → Custom traces if needed

如果显示“Index is stale”，请在终端中运行 node .gitnexus/run.cjs analyze。 热工具的 staleness 会指出响应所用的索引（branch／lastCommit）及其新鲜度（status）。仅在状态为 behind 或 diverged 时重新分析；current 表示索引身份，unknown 表示无法测量。

检查清单

- [ ] Once per session: bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
- [ ] State the repository and index freshness with the diagnosis

保持调查范围聚焦

从已知符号的 context 开始，或使用较小的 query（limit: 3、 max_symbols: 3、include_content: false、chain_depth: 0）来发现一个符号。 当服务支持这些单仓库过滤器时，只请求所需的证据：

context({uid: "<suspect id>", repo: "my-app", include_content: true,
         response_sections: ["outgoing"], relationTypes: ["CALLS"]})
trace({from_uid: "<suspect id>", to_uid: "<failure id>", repo: "my-app"})

经过过滤的上下文中仍会包含 symbol 以及完整性／过期状态诊断。 relationTypes 只过滤返回的入向／出向类别；它不会扩展这些类别现有的有限范围，也不会过滤显式请求的调用链。 对于回调注册，请包含 USES；对于导入或继承，请请求相应的关系类型，或省略过滤器。未返回的引用不代表引用不存在。只有在假设需要时才扩大调查范围，并保留 UNKNOWN／部分结果警告。确认源码和测试后，再断定根因。将 2–3 次调用完成调查作为目标，而不是跳过验证或编辑前影响分析的理由。

调试模式

症状	GitNexus 方法
错误消息	对错误文本使用 query → 对抛出错误的位置使用 context
返回值错误	对函数使用 context → 追踪被调用函数以分析数据流
间歇性故障	context → 查找外部调用、异步依赖
性能问题	context → 查找调用者较多的符号（热点路径）
最近的回归	使用 detect_changes 查看更改影响的内容——链接工作树请传入 worktree
“A 如何到达 B？”	对两个符号之间使用 trace——一次调用即可获得最短调用链

工具

query — 查找与错误相关的代码：

query({search_query: "payment validation error", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException

context — 获取可疑对象的完整上下文：

context({name: "validatePayment", repo: "my-app"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)

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 — 获取两个符号之间的最短调用链（“A 如何到达 B？”），一次调用即可完成，无需串联多个 context 跳转：

trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)

如果不存在路径，trace 会报告最远的可达节点——也就是调用链中断的确切位置（动态分派、反射或外部边界）。

示例：“支付端点间歇性返回 500”

0. list_repos {}
   → total: 2 (my-app, billing-api) — bind my-app explicitly on every call

1. query({search_query: "payment error handling", repo: "my-app"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

2. context({name: "validatePayment", repo: "my-app"})
   → Outgoing calls: verifyCard, fetchRates (external API!)

3. READ gitnexus://repo/my-app/process/CheckoutFlow
   → Step 3: validatePayment → calls fetchRates (external)

4. Root cause: fetchRates calls external API without proper timeout
   Repository: my-app  Index: current

只有一个已索引仓库时，步骤 0 会返回 total: 1，上面所有调用都可以省略 repo 参数。