grepai-search-advanced

GrepAI 高级搜索选项

本技能介绍高级搜索选项，包括 JSON 输出、精简模式以及与 AI Agent 的集成。

何时使用此技能

• 将 GrepAI 集成到脚本或工具中
• 在 AI Agent（Claude、GPT）中使用 GrepAI
• 以编程方式处理搜索结果
• 减少 AI 场景中的 Token 用量

命令行选项

选项	说明
--limit N	结果数量（默认值：10）
--json / -j	JSON 输出格式
--toon / -t	TOON 输出格式（比 JSON 少约 50% 的 Token）
--compact / -c	精简输出（不含内容，可与 --json 或 --toon 配合使用）

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

JSON 输出

标准 JSON

grepai search "authentication" --json

输出：

{
  "query": "authentication",
  "results": [
    {
      "score": 0.89,
      "file": "src/auth/middleware.go",
      "start_line": 15,
      "end_line": 45,
      "content": "func AuthMiddleware() gin.HandlerFunc {\n    return func(c *gin.Context) {\n        token := c.GetHeader(\"Authorization\")\n        if token == \"\" {\n            c.AbortWithStatus(401)\n            return\n        }\n        claims, err := ValidateToken(token)\n        ...\n    }\n}"
    },
    {
      "score": 0.82,
      "file": "src/auth/jwt.go",
      "start_line": 23,
      "end_line": 55,
      "content": "func ValidateToken(tokenString string) (*Claims, error) {\n    ..."
    }
  ],
  "total": 2
}

精简 JSON（针对 AI 优化）

grepai search "authentication" --json --compact

输出：

{
  "q": "authentication",
  "r": [
    {
      "s": 0.89,
      "f": "src/auth/middleware.go",
      "l": "15-45"
    },
    {
      "s": 0.82,
      "f": "src/auth/jwt.go",
      "l": "23-55"
    }
  ],
  "t": 2
}

主要区别：

• 使用缩写键（s 代替 score，f 代替 file）
• 不含内容（仅包含文件位置）
• AI Agent 的 Token 用量减少约 80%

TOON 输出（v0.26.0+）

TOON（面向 Token 的对象表示法）是一种更加精简的格式，专为 AI Agent 优化。

标准 TOON

grepai search "authentication" --toon

输出：

[2]{content,end_line,file_path,score,start_line}:
  "func AuthMiddleware()...",45,src/auth/middleware.go,0.89,15
  "func ValidateToken()...",55,src/auth/jwt.go,0.82,23

精简 TOON（最适合 AI）

grepai search "authentication" --toon --compact

输出：

[2]{end_line,file_path,score,start_line}:
  45,src/auth/middleware.go,0.89,15
  55,src/auth/jwt.go,0.82,23

TOON 与 JSON 对比

格式	Token 数量（5 条结果）	最适用于
JSON	~1,500	脚本、解析
JSON 精简	~300	AI Agent
TOON	~250	AI Agent
TOON 精简	~150	Token 受限的 AI 场景

何时使用 TOON

• 集成支持 TOON 的 AI Agent 时，使用 TOON
• 要最大限度提高 Token 效率时，使用 TOON 精简（比 JSON 精简小约 50%）
• 用于传统脚本（jq、编程语言）时，继续使用 JSON

精简格式参考

完整键	精简键	说明
query	q	搜索查询
results	r	结果数组
score	s	相似度分数
file	f	文件路径
start_line/end_line	l	行范围（"15-45"）
total	t	结果总数

组合使用选项

# 5 results in compact JSON
grepai search "error handling" --limit 5 --json --compact

# 20 results in full JSON
grepai search "database" --limit 20 --json

AI Agent 集成

用于 Claude/GPT 提示词

使用精简模式以尽可能减少 Token 用量：

# Agent asks for context
grepai search "payment processing" --json --compact --limit 5

然后将结果提供给 AI，并使用文件读取工具获取详细信息。

工作流示例

1. 搜索相关代码：

grepai search "authentication middleware" --json --compact --limit 3

2. 获取响应：

{
  "q": "authentication middleware",
  "r": [
    {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},
    {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"},
    {"s": 0.78, "f": "src/handlers/auth.go", "l": "10-40"}
  ],
  "t": 3
}

3. 读取特定文件： AI 读取 src/auth/middleware.go:15-45 以获取完整上下文。

使用 JSON 编写脚本

Bash + jq

# Get just file paths
grepai search "config" --json | jq -r '.results[].file'

# Filter by score
grepai search "config" --json | jq '.results[] | select(.score > 0.8)'

# Count results
grepai search "config" --json | jq '.total'

Python

import subprocess
import json

result = subprocess.run(
    ['grepai', 'search', 'authentication', '--json'],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)
for r in data['results']:
    print(f"{r['score']:.2f} | {r['file']}:{r['start_line']}")

Node.js

const { execSync } = require('child_process');

const output = execSync('grepai search "authentication" --json');
const data = JSON.parse(output);

data.results.forEach(r => {
    console.log(`${r.score.toFixed(2)} | ${r.file}:${r.start_line}`);
});

MCP 集成

GrepAI 提供支持格式选择的 MCP 工具（v0.26.0+）：

# Start MCP server
grepai mcp-serve

MCP 工具支持 JSON（默认）或 TOON 格式：

MCP 工具	参数
grepai_search	query、limit、compact、format
grepai_trace_callers	symbol、compact、format
grepai_trace_callees	symbol、compact、format
grepai_trace_graph	symbol、depth、format
grepai_index_status	format

Format 参数

{
  "name": "grepai_search",
  "arguments": {
    "query": "authentication",
    "format": "toon",
    "compact": true
  }
}

有效值："json"（默认）或 "toon"

Token 优化

Token 数量对比

一次典型搜索包含 5 条结果时：

格式	约计 Token 数量
人类可读	~2,000
JSON 完整	~1,500
JSON 精简	~300

何时使用各格式

格式	使用场景
人类可读	手动检查
JSON 完整	需要内容的脚本
JSON 精简	AI Agent、Token 受限场景

管道传递结果

写入文件

grepai search "authentication" --json > results.json

传递给其他工具

# Open results in VS Code
grepai search "config" --json | jq -r '.results[0].file' | xargs code

# Copy first result path to clipboard (macOS)
grepai search "config" --json | jq -r '.results[0].file' | pbcopy

批量搜索

运行多次搜索：

#!/bin/bash
queries=("authentication" "database" "logging" "error handling")

for q in "${queries[@]}"; do
    echo "=== $q ==="
    grepai search "$q" --json --compact --limit 3
    echo
done

错误处理

JSON 错误响应

搜索失败时：

{
  "error": "Index not found. Run 'grepai watch' first.",
  "code": "INDEX_NOT_FOUND"
}

在脚本中检查错误

result=$(grepai search "query" --json)
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
    echo "Error: $(echo "$result" | jq -r '.error')"
    exit 1
fi

最佳实践

1. 供 AI Agent 使用时选择精简格式： 节省 80% 的 token
2. 脚本需要内容时使用完整 JSON： 确保内容齐全
3. 调试时使用便于人阅读的格式： 更易阅读
4. 适当限制结果： 不要获取超出所需的内容
5. 检查错误： 正确解析 JSON 响应

输出格式

高级搜索输出（精简 JSON）：

{
  "q": "authentication middleware",
  "r": [
    {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},
    {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"},
    {"s": 0.78, "f": "src/handlers/auth.go", "l": "10-40"}
  ],
  "t": 3
}

Token 估算： 约 80 个 token（完整内容约需 800 个）