gitnexus-debugging

使用 GitNexus 调试

适用场景

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

工作流

1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed

如果提示“索引已过期”，请在终端中运行 npx gitnexus analyze。

检查清单

- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] gitnexus_query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] gitnexus_context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] gitnexus_cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause

调试模式

症状	GitNexus 方法
错误消息	使用 gitnexus_query 搜索错误文本 → 对抛出错误的位置使用 context
返回值错误	对函数使用 context → 追踪被调用函数以了解数据流
间歇性失败	使用 context → 查找外部调用、异步依赖
性能问题	使用 context → 找出调用方较多的符号（热点路径）
最近出现的回归	使用 detect_changes 查看你的更改会影响哪些内容

工具

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

gitnexus_query({query: "payment validation error"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException

gitnexus_context — 获取可疑代码的完整上下文：

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

gitnexus_cypher — 自定义调用链追踪：

MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain

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

1. gitnexus_query({query: "payment error handling"})
   → Processes: CheckoutFlow, ErrorHandling
   → Symbols: validatePayment, handlePaymentError

2. gitnexus_context({name: "validatePayment"})
   → 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