gitnexus-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debugging with GitNexus

使用GitNexus进行调试

When to Use

适用场景

"Why is this function failing?"
"Trace where this error comes from"
"Who calls this method?"
"This endpoint returns 500"
Investigating bugs, errors, or unexpected behavior

"这个函数为什么执行失败？"
"追踪这个错误的来源"
"谁调用了这个方法？"
"该接口返回500错误"
排查Bug、错误或异常行为

Workflow

工作流程

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

If "Index is stale" → run
npx gitnexus analyze
in terminal.

1. gitnexus_query({query: "<错误或症状>"})            → 查找相关执行流程
2. gitnexus_context({name: "<可疑对象>"})                    → 查看调用方/被调用方/流程
3. 读取 gitnexus://repo/{name}/process/{name}                → 追踪执行流程
4. gitnexus_cypher({query: "MATCH path..."})                 → 如有需要可自定义追踪

如果提示"Index is stale"（索引已过期）→ 在终端运行
npx gitnexus analyze
。

Checklist

检查清单

- [ ] 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_query查询错误文本或相关代码
- [ ] 从返回的流程中识别可疑函数
- [ ] 使用gitnexus_context查看调用方和被调用方
- [ ] 如有必要，通过流程资源追踪执行流程
- [ ] 如有需要，使用gitnexus_cypher进行自定义调用链追踪
- [ ] 阅读源文件确认根本原因

Debugging Patterns

调试模式

Symptom	GitNexus Approach
Error message	`gitnexus_query` for error text → `context` on throw sites
Wrong return value	`context` on the function → trace callees for data flow
Intermittent failure	`context` → look for external calls, async deps
Performance issue	`context` → find symbols with many callers (hot paths)
Recent regression	`detect_changes` to see what your changes affect

症状	GitNexus处理方法
错误信息	使用 `gitnexus_query` 查询错误文本 → 在抛出点使用 `context`
返回值异常	对目标函数使用 `context` → 追踪被调用方的数据流向
间歇性故障	使用 `context` → 检查外部调用、异步依赖
性能问题	使用 `context` → 找出被大量调用的符号（热点路径）
近期回归问题	使用 `detect_changes` 查看你的变更影响范围

Tools

工具

gitnexus_query — find code related to error:

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

gitnexus_context — full context for a suspect:

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

gitnexus_cypher — custom call chain traces:

cypher

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

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

gitnexus_query({query: "payment validation error"})
→ 流程：CheckoutFlow、ErrorHandling
→ 符号：validatePayment、handlePaymentError、PaymentException

gitnexus_context — 查看可疑对象的完整上下文：

gitnexus_context({name: "validatePayment"})
→ 传入调用：processCheckout、webhookHandler
→ 传出调用：verifyCard、fetchRates（外部API！）
→ 流程：CheckoutFlow（第3/7步）

gitnexus_cypher — 自定义调用链追踪：

cypher

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

Example: "Payment endpoint returns 500 intermittently"

示例："支付接口间歇性返回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

1. gitnexus_query({query: "payment error handling"})
   → 流程：CheckoutFlow、ErrorHandling
   → 符号：validatePayment、handlePaymentError

2. gitnexus_context({name: "validatePayment"})
   → 传出调用：verifyCard、fetchRates（外部API！）

3. 读取 gitnexus://repo/my-app/process/CheckoutFlow
   → 第3步：validatePayment → 调用fetchRates（外部服务）

4. 根本原因：fetchRates调用外部API时未设置合理超时时间