grepai-trace-callers

GrepAI 跟踪调用方

本技能介绍如何使用 grepai trace callers 查找调用特定函数或方法的所有代码位置。

何时使用本技能

• 重构前查找函数的所有用法
• 了解函数依赖关系
• 变更前进行影响分析
• 浏览和探索代码

什么是跟踪调用方？

grepai trace callers 可以回答：“哪些地方调用了这个函数？”

func Login(user, pass) {...}
        ↑
        │
┌───────┴───────────────────┐
│   Who calls Login()?      │
├───────────────────────────┤
│ • HandleAuth (auth.go:42) │
│ • TestLogin (test.go:15)  │
│ • CLI (main.go:88)        │
└───────────────────────────┘

基本用法

grepai trace callers "FunctionName"

示例

grepai trace callers "Login"

输出：

🔍 Callers of "Login"

Found 3 callers:

1. HandleAuth
   File: handlers/auth.go:42
   Context: user.Login(ctx, credentials)

2. TestLoginSuccess
   File: handlers/auth_test.go:15
   Context: result := Login(testUser, testPass)

3. RunCLI
   File: cmd/main.go:88
   Context: err := auth.Login(username, password)

JSON 输出

用于程序化处理：

grepai trace callers "Login" --json

输出：

{
  "query": "Login",
  "mode": "callers",
  "count": 3,
  "results": [
    {
      "file": "handlers/auth.go",
      "line": 42,
      "caller": "HandleAuth",
      "context": "user.Login(ctx, credentials)"
    },
    {
      "file": "handlers/auth_test.go",
      "line": 15,
      "caller": "TestLoginSuccess",
      "context": "result := Login(testUser, testPass)"
    },
    {
      "file": "cmd/main.go",
      "line": 88,
      "caller": "RunCLI",
      "context": "err := auth.Login(username, password)"
    }
  ]
}

紧凑 JSON（针对 AI 优化）

grepai trace callers "Login" --json --compact

输出：

{
  "q": "Login",
  "m": "callers",
  "c": 3,
  "r": [
    {"f": "handlers/auth.go", "l": 42, "fn": "HandleAuth"},
    {"f": "handlers/auth_test.go", "l": 15, "fn": "TestLoginSuccess"},
    {"f": "cmd/main.go", "l": 88, "fn": "RunCLI"}
  ]
}

TOON 输出（v0.26.0+）

TOON 格式比 JSON 减少约 50% 的令牌：

grepai trace callers "Login" --toon

输出：

callers[3]:
  - call_site:
      context: "user.Login(ctx, credentials)"
      file: handlers/auth.go
      line: 42
    symbol:
      name: HandleAuth
      ...

注意： --json 和 --toon 不能同时使用。

提取模式

GrepAI 提供两种提取模式：

快速模式（默认）

使用正则表达式模式。速度快且不依赖其他组件。

grepai trace callers "Login" --mode fast

精确模式

使用 tree-sitter AST 解析。准确度更高，但需要 tree-sitter。

grepai trace callers "Login" --mode precise

对比

模式	速度	准确度	依赖项
fast	⚡⚡⚡	良好	无
precise	⚡⚡	极佳	tree-sitter

配置

在 .grepai/config.yaml 中配置跟踪功能：

trace:
  mode: fast  # fast or precise

  enabled_languages:
    - .go
    - .js
    - .ts
    - .py
    - .php
    - .rs

  exclude_patterns:
    - "*_test.go"
    - "*.spec.ts"

支持的语言

语言	扩展名
Go	.go
JavaScript	.js、.jsx
TypeScript	.ts、.tsx
Python	.py
PHP	.php
C/C++	.c、.h、.cpp、.hpp、.cc、.cxx
Rust	.rs
Zig	.zig
C#	.cs
Java	.java
Pascal/Delphi	.pas、.dpr

使用场景

重构前

# Find all usages before renaming
grepai trace callers "getUserById"

# Check impact of changing signature
grepai trace callers "processPayment"

了解代码库

# Who uses this core function?
grepai trace callers "validateToken"

# Find entry points to a module
grepai trace callers "initialize"

调试

# Where is this function called from?
grepai trace callers "problematicFunction"

代码审查

# Verify function usage before approving changes
grepai trace callers "deprecatedMethod"

处理常见名称

如果函数名称很常见，结果中可能会包含无关代码：

问题

grepai trace callers "get"  # Too common, many false positives

解决方案

1. 使用更具体的名称：

grepai trace callers "getUserProfile"

2. 按路径筛选结果：

grepai trace callers "get" --json | jq '.results[] | select(.file | contains("auth"))'

与语义搜索结合使用

结合使用，全面了解代码：

# Find what Login does (semantic)
grepai search "user login authentication"

# Find who uses Login (trace)
grepai trace callers "Login"

脚本示例

Bash

# Count callers
grepai trace callers "MyFunction" --json | jq '.count'

# Get caller function names
grepai trace callers "MyFunction" --json | jq -r '.results[].caller'

# Get file paths only
grepai trace callers "MyFunction" --json | jq -r '.results[].file' | sort -u

Python

import subprocess
import json

result = subprocess.run(
    ['grepai', 'trace', 'callers', 'Login', '--json'],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)
print(f"Found {data['count']} callers of Login:")
for r in data['results']:
    print(f"  - {r['caller']} in {r['file']}:{r['line']}")

常见问题

❌ 问题： 未找到调用方 ✅ 解决方案：

• 检查函数名称拼写（区分大小写）
• 确保文件类型已列入 enabled_languages
• 运行 grepai watch 更新符号索引

❌ 问题： 误报太多 ✅ 解决方案：

• 使用更具体的函数名称
• 在配置中添加排除模式
• 使用 jq 筛选结果

❌ 问题： 遗漏了部分调用方 ✅ 解决方案：

• 尝试使用 --mode precise 提高准确度
• 检查文件是否匹配忽略模式

最佳实践

1. 使用准确的函数名称： 大小写有影响
2. 检查符号索引： 先运行 grepai watch
3. 脚本中使用 JSON： 更易解析
4. 结合搜索： 语义搜索 + 跟踪 = 全面了解
5. 筛选大量结果： 使用 jq 或 grep

输出格式

跟踪调用方的结果：

🔍 Callers of "Login"

Mode: fast
Language files scanned: 245

Found 3 callers:

1. HandleAuth
   File: handlers/auth.go:42
   Context: user.Login(ctx, credentials)

2. TestLoginSuccess
   File: handlers/auth_test.go:15
   Context: result := Login(testUser, testPass)

3. RunCLI
   File: cmd/main.go:88
   Context: err := auth.Login(username, password)

Tip: Use --json for machine-readable output
     Use --mode precise for more accurate results