gitnexus-debugging

用途

GitNexus Debugging 用于在调试代码缺陷、追踪错误来源或排查异常行为时，借助 GitNexus 的代码图谱能力定位问题。典型触发场景包括：询问“为什么 X 失败”“这个错误来自哪里”“谁调用了这个方法”“这个接口返回 500”，以及调查 bug、错误或非预期行为。

主要能力

该技能围绕四个工具与资源展开：

• gitnexus_query：根据错误文本或症状查找相关执行流程与符号。例如 gitnexus_query({query: "payment validation error"}) 会返回相关流程（如 CheckoutFlow、ErrorHandling）和符号（如 validatePayment、handlePaymentError、PaymentException）。
• gitnexus_context：查看某个可疑函数的完整上下文，包括入向调用（callers）、出向调用（callees）以及所属流程。例如 gitnexus_context({name: "validatePayment"}) 会显示入向调用 processCheckout、webhookHandler，出向调用 verifyCard、fetchRates（外部 API），以及流程 CheckoutFlow（第 3/7 步）。
• process 资源：通过 READ gitnexus://repo/{name}/process/{name} 追踪执行流程。
• gitnexus_cypher：在需要时编写自定义调用链查询，例如：

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

使用方式

推荐工作流如下：

1. gitnexus_query({query: "<error or symptom>"}) → 查找相关执行流程
2. gitnexus_context({name: "<suspect>"}) → 查看调用方、被调用方与流程
3. READ gitnexus://repo/{name}/process/{name} → 追踪执行流
4. gitnexus_cypher({query: "MATCH path..."}) → 需要时进行自定义追踪

若提示“Index is stale”，需在终端运行 npx gitnexus analyze。

调试检查清单：

• 理解症状（错误信息、非预期行为）
• 用 gitnexus_query 搜索错误文本或相关代码
• 从返回的流程中识别可疑函数
• 用 gitnexus_context 查看调用方与被调用方
• 如适用，通过 process 资源追踪执行流
• 如需要，用 gitnexus_cypher 做自定义调用链追踪
• 阅读源文件确认根因

适用场景

针对不同症状的调试模式：

• 错误信息：用 gitnexus_query 搜索错误文本 → 对抛出点做 context
• 返回值错误：对函数做 context → 追踪被调用方以分析数据流
• 间歇性失败：做 context → 查找外部调用、异步依赖
• 性能问题：做 context → 找出被大量调用的符号（热点路径）
• 近期回归：用 detect_changes 查看改动影响范围

示例：“支付接口间歇性返回 500”

1. gitnexus_query({query: "payment error handling"}) → 流程 CheckoutFlow、ErrorHandling；符号 validatePayment、handlePaymentError
2. gitnexus_context({name: "validatePayment"}) → 出向调用 verifyCard、fetchRates（外部 API）
3. READ gitnexus://repo/my-app/process/CheckoutFlow → 第 3 步：validatePayment → 调用 fetchRates（外部）
4. 根因：fetchRates 调用外部 API 时缺少合适的超时设置

限制

资料未提供该技能的收费、价格、支持平台、性能指标或效果保证等信息。使用前需确保代码索引为最新，否则需运行 npx gitnexus analyze 重新分析。