用途
本技能介绍 GrepAI 的高级搜索选项，主要面向需要将 GrepAI 集成到脚本、工具或 AI 智能体中的场景。适用情况包括：将 GrepAI 与脚本或工具集成、在 AI 智能体（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、results（每项含 score、file、start_line、end_line、content）以及 total 字段。
紧凑 JSON（面向 AI 优化）：
grepai search "authentication" --json --compact
输出使用缩写键（q、r、s、f、l、t），不含 content，仅保留文件位置，可为 AI 智能体减少约 80% token。
TOON 输出（v0.26.0+）
TOON（Token-Oriented Object Notation）是更紧凑的格式，专为 AI 智能体优化。
标准 TOON：
grepai search "authentication" --toon
紧凑 TOON（最适合 AI）：
grepai search "authentication" --toon --compact
TOON 与 JSON 对比
| 格式 | Token（5 条结果） | 最适合 |
|---|---|---|
| JSON | ~1,500 | 脚本、解析 |
| JSON compact | ~300 | AI 智能体 |
| TOON | ~250 | AI 智能体 |
| TOON compact | ~150 | token 受限的 AI |
使用 TOON 的时机：与支持 TOON 的 AI 智能体集成时使用；需要最大 token 效率时使用 TOON compact（比 JSON compact 小约 50%）；传统脚本（jq、编程语言）仍使用 JSON。
紧凑格式键名对照
| 完整键 | 紧凑键 | 说明 |
|---|---|---|
| query | q | 搜索查询 |
| results | r | 结果数组 |
| score | s | 相似度分数 |
| file | f | 文件路径 |
| start_line/end_line | l | 行范围（"15-45"） |
| total | t | 结果总数 |
组合选项示例
5 条结果，紧凑 JSON
grepai search "error handling" --limit 5 --json --compact
20 条结果，完整 JSON
grepai search "database" --limit 20 --json
使用方式
AI 智能体集成
面向 Claude/GPT 提示词时，使用紧凑模式以最小化 token：
grepai search "payment processing" --json --compact --limit 5
然后将结果提供给 AI，并配合文件读取工具获取细节。
工作流示例：先搜索相关代码（--json --compact --limit 3），再让 AI 读取具体文件（如 src/auth/middleware.go:15-45）获取完整上下文。
脚本化处理
Bash + jq：
仅获取文件路径
grepai search "config" --json | jq -r '.results[].file'
按分数过滤
grepai search "config" --json | jq '.results[] | select(.score > 0.8)'
统计结果数
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+）：
启动 MCP 服务器
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"。
结果管道传递
输出到文件：
grepai search "authentication" --json > results.json
传递给其他工具：
在 VS Code 中打开结果
grepai search "config" --json | jq -r '.results[0].file' | xargs code
将首个结果路径复制到剪贴板（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
适用场景
- 将 GrepAI 搜索结果接入脚本或自动化工具链
- 在 Claude、GPT 等 AI 智能体中提供代码上下文
- 以编程方式解析、过滤、统计搜索结果
- 在 token 受限的 AI 上下文中降低消耗
- 通过 MCP 服务器向智能体暴露搜索与调用链追踪工具
限制与注意事项
- --json 与 --toon 互斥，不能同时使用。
- --compact 需与 --json 或 --toon 配合使用。
- TOON 格式需要 v0.26.0 及以上版本。
- 紧凑模式不包含 content 字段，仅提供文件位置，需要细节时须另行读取文件。
- 使用前需先建立索引（如运行 grepai watch），否则会返回 INDEX_NOT_FOUND 错误。
最佳实践
- AI 智能体使用 compact：节省约 80% token。
- 脚本需要内容时使用完整 JSON。
- 调试时使用人类可读格式，更易阅读。
- 合理限制结果数量，不要获取超出需要的结果。
- 正确解析 JSON 响应并检查错误。
输出格式
高级搜索输出（JSON compact）示例：
{ "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 token）。