Investigation Toolkit

代码排查工具包

Debug issues through systematic search and AI-powered analysis.

通过系统化搜索和AI驱动的分析来调试问题。

Prerequisites

前置依赖

bash

undefined

bash

undefined

ripgrep for fast search

brew install ripgrep

Gemini for analysis

pip install google-generativeai export GEMINI_API_KEY=your_api_key

undefined

pip install google-generativeai export GEMINI_API_KEY=your_api_key

undefined

Search Commands

搜索命令

ripgrep Basics

ripgrep基础用法

bash

undefined

bash

undefined

Search for pattern

rg "pattern" src/

Case insensitive

rg -i "error" src/

Whole word

rg -w "user" src/

File types

rg -t ts "function" src/ rg -t py "def " src/

Exclude patterns

rg "TODO" --glob "!node_modules"

Show context

rg -C 3 "error" src/ # 3 lines before and after rg -B 5 "crash" src/ # 5 lines before rg -A 5 "crash" src/ # 5 lines after

Just filenames

rg -l "pattern" src/

Count matches

rg -c "pattern" src/

undefined

rg -c "pattern" src/

undefined

Finding Definitions

查找定义

bash

undefined

bash

undefined

Function definitions (TypeScript)

rg "function\s+functionName" src/ rg "(const|let|var)\s+functionName\s*=" src/ rg "export\s+(async\s+)?function\s+\w+" src/

Class definitions

rg "class\s+ClassName" src/

Interface/Type definitions

rg "(interface|type)\s+TypeName" src/

undefined

rg "(interface|type)\s+TypeName" src/

undefined

Tracing Usage

追踪调用

bash

undefined

bash

undefined

Where is this function called?

rg "functionName(" src/

Where is this imported?

rg "import.*functionName" src/

Where is this exported?

rg "export.*functionName" src/

undefined

rg "export.*functionName" src/

undefined

Investigation Patterns

排查模式

Bug Investigation

Bug排查

bash

undefined

bash

undefined

1. Search for error message

rg "exact error message" .

2. Find where error is thrown

rg "throw.*Error" src/ -C 3

3. Trace the function

rg "functionThatFails" src/ -C 5

4. Check recent changes

git log --oneline -20 --all -- src/problematic-file.ts git diff HEAD~5 -- src/problematic-file.ts

undefined

git log --oneline -20 --all -- src/problematic-file.ts git diff HEAD~5 -- src/problematic-file.ts

undefined

Trace Execution Flow

追踪执行流程

bash

#!/bin/bash
ENTRY_POINT=$1

echo "=== Entry Point ==="
rg -A 10 "export.*$ENTRY_POINT" src/

echo "=== Called Functions ==="
rg -o "\w+\(" src/$ENTRY_POINT*.ts | sort -u

echo "=== Dependencies ==="
rg "^import" src/$ENTRY_POINT*.ts

bash

#!/bin/bash
ENTRY_POINT=$1

echo "=== Entry Point ==="
rg -A 10 "export.*$ENTRY_POINT" src/

echo "=== Called Functions ==="
rg -o "\w+\(" src/$ENTRY_POINT*.ts | sort -u

echo "=== Dependencies ==="
rg "^import" src/$ENTRY_POINT*.ts

AI-Assisted Debugging

AI辅助调试

bash

undefined

bash

undefined

Analyze error with context

ERROR="Your error message here" CODE=$(cat problematic-file.ts)

gemini -m pro -o text -e "" "Debug this error:

ERROR: $ERROR

CODE: $CODE

Provide:

Most likely cause
How to verify
How to fix
How to prevent in future"

undefined

ERROR="Your error message here" CODE=$(cat problematic-file.ts)

gemini -m pro -o text -e "" "Debug this error:

ERROR: $ERROR

CODE: $CODE

Provide:

Most likely cause
How to verify
How to fix
How to prevent in future"

undefined

Hypothesis Testing

假设验证

bash

undefined

bash

undefined

Generate hypotheses

gemini -m pro -o text -e "" "Given this bug symptom:

SYMPTOM: [describe what's happening] CONTEXT: [relevant code/system info]

Generate 5 hypotheses ranked by likelihood, with a test for each."

gemini -m pro -o text -e "" "Given this bug symptom:

SYMPTOM: [describe what's happening] CONTEXT: [relevant code/system info]

Generate 5 hypotheses ranked by likelihood, with a test for each."

Then test each hypothesis

rg "hypothesis-related-pattern" src/

undefined

rg "hypothesis-related-pattern" src/

undefined

Common Investigations

常见排查场景

Find All Error Handling

查找所有错误处理逻辑

bash

rg "catch|\.catch|try\s*{" src/ -t ts
rg "throw\s+new" src/ -t ts

bash

rg "catch|\.catch|try\s*{" src/ -t ts
rg "throw\s+new" src/ -t ts

Find API Endpoints

查找API端点

bash

rg "(get|post|put|delete|patch)\s*\(" src/ -i
rg "router\.(get|post|put|delete)" src/
rg "@(Get|Post|Put|Delete)" src/

bash

rg "(get|post|put|delete|patch)\s*\(" src/ -i
rg "router\.(get|post|put|delete)" src/
rg "@(Get|Post|Put|Delete)" src/

Find Database Queries

查找数据库查询

bash

rg "(SELECT|INSERT|UPDATE|DELETE)" src/ -i
rg "\.query\(|\.execute\(" src/
rg "prisma\.\w+\.(find|create|update|delete)" src/

bash

rg "(SELECT|INSERT|UPDATE|DELETE)" src/ -i
rg "\.query\(|\.execute\(" src/
rg "prisma\.\w+\.(find|create|update|delete)" src/

Find Configuration

查找配置信息

bash

rg "process\.env\." src/
rg "(config|settings)\[" src/
rg "getenv|os\.environ" src/ -t py

bash

rg "process\.env\." src/
rg "(config|settings)\[" src/
rg "getenv|os\.environ" src/ -t py

Find Security Issues

查找安全问题

bash

undefined

bash

undefined

SQL injection potential

rg "query.+."|'.*+" src/

Hardcoded secrets

rg "(password|secret|key|token)\s*=\s*['"]" src/ -i

Unsafe eval

rg "eval(" src/

undefined

rg "eval(" src/

undefined

Deep Investigation Script

深度排查脚本

bash

#!/bin/bash

bash

#!/bin/bash

investigate.sh - Comprehensive code investigation

TERM=$1 echo "=== Investigating: $TERM ==="

echo "" echo "### Definitions ###" rg "^(export\s+)?(function|const|class|interface|type)\s+$TERM" src/

echo "" echo "### Usage ###" rg "$TERM" src/ --stats | head -50

echo "" echo "### Recent Changes ###" git log --oneline -10 -S "$TERM"

echo "" echo "### Blame ###" for f in $(rg -l "$TERM" src/); do echo "--- $f ---" git blame -L "/$TERM/,+5" "$f" 2>/dev/null | head -10 done

undefined

TERM=$1 echo "=== Investigating: $TERM ==="

echo "" echo "### Definitions ###" rg "^(export\s+)?(function|const|class|interface|type)\s+$TERM" src/

echo "" echo "### Usage ###" rg "$TERM" src/ --stats | head -50

echo "" echo "### Recent Changes ###" git log --oneline -10 -S "$TERM"

echo "" echo "### Blame ###" for f in $(rg -l "$TERM" src/); do echo "--- $f ---" git blame -L "/$TERM/,+5" "$f" 2>/dev/null | head -10 done

undefined

Best Practices

最佳实践

Start with the error - Search for exact message first
Expand context - Use
```
-C
```
,
```
-B
```
,
```
-A
```
for surrounding code
Check history -
```
git log -S
```
finds when code was introduced
Use AI for complex - When pattern matching isn't enough
Document findings - Note what you discover
Test hypotheses - Verify before assuming

从错误入手 - 首先搜索确切的错误信息
扩展上下文 - 使用
```
-C
```
、
```
-B
```
、
```
-A
```
参数查看周边代码
查看历史记录 -
```
git log -S
```
可以查找代码的引入时间
复杂场景用AI - 当模式匹配无法解决时使用AI
记录排查结果 - 记录你的发现
验证假设 - 先验证再下结论

investigate

Original

Translation

Investigation Toolkit

代码排查工具包

Prerequisites

前置依赖

ripgrep for fast search

ripgrep for fast search

Gemini for analysis

Gemini for analysis

Search Commands

搜索命令

ripgrep Basics

ripgrep基础用法

Search for pattern

Search for pattern

Case insensitive

Case insensitive

Whole word

Whole word

File types

File types

Exclude patterns

Exclude patterns

Show context

Show context

Just filenames

Just filenames

Count matches

Count matches

Finding Definitions

查找定义

Function definitions (TypeScript)

Function definitions (TypeScript)

Class definitions

Class definitions

Interface/Type definitions

Interface/Type definitions

Tracing Usage

追踪调用

Where is this function called?

Where is this function called?

Where is this imported?

Where is this imported?

Where is this exported?

Where is this exported?

Investigation Patterns

排查模式

Bug Investigation

Bug排查

1. Search for error message

1. Search for error message

2. Find where error is thrown

2. Find where error is thrown

3. Trace the function

3. Trace the function

4. Check recent changes

4. Check recent changes

Trace Execution Flow

追踪执行流程

AI-Assisted Debugging

AI辅助调试

Analyze error with context

Analyze error with context

Hypothesis Testing

假设验证

Generate hypotheses

Generate hypotheses

Then test each hypothesis

Then test each hypothesis

Common Investigations

常见排查场景

Find All Error Handling

查找所有错误处理逻辑

Find API Endpoints

查找API端点

Find Database Queries

查找数据库查询

Find Configuration