GrepAI 高级搜索选项：JSON/TOON 输出、紧凑模式与 AI 代理集成指南

grepai-search-advanced by yoanbernabeu/grepai-skills

326 周安装量

15 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/yoanbernabeu/grepai-skills --skill grepai-search-advanced

AI/机器学习开发命令行工具

🇨🇳中文介绍

GrepAI 高级搜索选项

本技能涵盖高级搜索选项，包括 JSON 输出、紧凑模式以及与 AI 代理的集成。

何时使用此技能

将 GrepAI 与脚本或工具集成时
与 AI 代理（Claude、GPT）一起使用 GrepAI 时
以编程方式处理搜索结果时
在 AI 上下文中减少令牌使用量时

命令行选项

选项	描述
`--limit N`	结果数量（默认：10）
`--json` / `-j`	JSON 输出格式
`--toon` / `-t`	TOON 输出格式（比 JSON 少约 50% 的令牌）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

紧凑 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 代理节省约 80% 的令牌

TOON 输出（v0.26.0+）

TOON（面向令牌的对象表示法）是一种更紧凑的格式，专为 AI 代理优化。

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 对比

格式	令牌数（5 个结果）	最适合
JSON	~1,500	脚本、解析
JSON compact	~300	AI 代理
TOON	~250	AI 代理
TOON compact	~150	令牌受限的 AI

使用 TOON：当与支持它的 AI 代理集成时
使用 TOON compact：为了获得最高的令牌效率（比 JSON compact 小约 50%）
坚持使用 JSON：用于传统脚本编写（jq、编程语言）

完整键名	紧凑键名	描述
`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

用于 Claude/GPT 提示

使用紧凑模式以最小化令牌使用：

# 代理请求上下文
grepai search "payment processing" --json --compact --limit 5

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

搜索相关代码：

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

  "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 进行脚本编写

# 仅获取文件路径
grepai search "config" --json | jq -r '.results[].file'

# 按分数过滤
grepai search "config" --json | jq '.results[] | select(.score > 0.8)'

# 统计结果数量
grepai search "config" --json | jq '.total'

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']}")

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}`);
});

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`

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

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

对于一个包含 5 个结果的典型搜索：

格式	大约令牌数
Human-readable	~2,000
JSON full	~1,500
JSON compact	~300

何时使用每种格式

格式	使用场景
Human-readable	手动检查
JSON full	需要内容的脚本
JSON compact	AI 代理、令牌受限的上下文

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

当搜索失败时：

{
  "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

对 AI 代理使用紧凑格式： 节省 80% 的令牌
对脚本使用完整 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
}

令牌估算： ~80 个令牌（对比完整内容的 ~800 个令牌）

🇺🇸English

GrepAI Advanced Search Options

This skill covers advanced search options including JSON output, compact mode, and integration with AI agents.

When to Use This Skill

Integrating GrepAI with scripts or tools
Using GrepAI with AI agents (Claude, GPT)
Processing search results programmatically
Reducing token usage in AI contexts

Command-Line Options

Option	Description
`--limit N`	Number of results (default: 10)
`--json` / `-j`	JSON output format
`--toon` / `-t`	TOON output format (~50% fewer tokens than JSON)
`--compact` / `-c`	Compact output (no content, works with --json or --toon)

Note: --json and --toon are mutually exclusive.

JSON Output

Standard JSON

grepai search "authentication" --json

Output:

{
  "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
}

Compact JSON (AI Optimized)

grepai search "authentication" --json --compact

Output:

{
  "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
}

Key differences:

Abbreviated keys (s vs score, f vs file)
No content (just file locations)
~80% fewer tokens for AI agents

TOON Output (v0.26.0+)

TOON (Token-Oriented Object Notation) is an even more compact format, optimized for AI agents.

Standard TOON

grepai search "authentication" --toon

Output:

[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

Compact TOON (Best for AI)

grepai search "authentication" --toon --compact

Output:

[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 vs JSON Comparison

Format	Tokens (5 results)	Best For
JSON	~1,500	Scripts, parsing
JSON compact	~300	AI agents
TOON	~250	AI agents
TOON compact	~150	Token-constrained AI

When to Use TOON

Use TOON when integrating with AI agents that support it
Use TOON compact for maximum token efficiency (~50% smaller than JSON compact)
Stick with JSON for traditional scripting (jq, programming languages)

Compact Format Reference

Full Key	Compact Key	Description
`query`	`q`	Search query
`results`	`r`	Results array
`score`	`s`	Similarity score
`file`

Combining Options

# 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 Integration

For Claude/GPT Prompts

Use compact mode to minimize tokens:

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

Then provide results to the AI with file read tool for details.

Workflow Example

Search for relevant code:

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

Get response:

  "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. Read specific files: AI reads src/auth/middleware.go:15-45 for full context.

Scripting with 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 Integration

GrepAI provides MCP tools with format selection (v0.26.0+):

# Start MCP server
grepai mcp-serve

MCP tools support JSON (default) or TOON format:

MCP Tool	Parameters
`grepai_search`	`query`, `limit`, `compact`, `format`
`grepai_trace_callers`	`symbol`, `compact`, `format`

Format Parameter

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

Valid values: "json" (default) or "toon"

Token Optimization

Token Comparison

For a typical search with 5 results:

Format	Approximate Tokens
Human-readable	~2,000
JSON full	~1,500
JSON compact	~300

When to Use Each Format

Format	Use Case
Human-readable	Manual inspection
JSON full	Scripts needing content
JSON compact	AI agents, token-limited contexts

Piping Results

To File

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

To Another Tool

# 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

Batch Searches

Run multiple searches:

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

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

Error Handling

JSON Error Response

When search fails:

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

Checking for Errors in Scripts

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

Best Practices

Use compact for AI agents: 80% token savings
Use full JSON for scripts: When you need content
Use human-readable for debugging: Easier to read
Limit results appropriately: Don't fetch more than needed
Check for errors: Parse JSON response properly

Output Format

Advanced search output (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 estimate: ~80 tokens (vs ~800 for full content)

Weekly Installs

326

Repository

yoanbernabeu/gr…i-skills

GitHub Stars

First Seen

Jan 28, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode264

codex254

gemini-cli235

github-copilot235

kimi-cli214

amp212

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

105,000 周安装

GrepAI 高级搜索选项：JSON/TOON 输出、紧凑模式与 AI 代理集成指南

🇨🇳中文介绍

GrepAI 高级搜索选项

何时使用此技能

命令行选项

相关 Skills

JSON 输出

标准 JSON

紧凑 JSON（AI 优化）

TOON 输出（v0.26.0+）

标准 TOON

紧凑 TOON（最适合 AI）

TOON 与 JSON 对比

何时使用 TOON

紧凑格式参考

组合选项

AI 代理集成

用于 Claude/GPT 提示

工作流程示例

使用 JSON 进行脚本编写

Bash + jq

Python

Node.js

MCP 集成

格式参数

令牌优化

令牌对比

何时使用每种格式

管道传输结果

输出到文件

输出到其他工具

批量搜索

错误处理

JSON 错误响应

在脚本中检查错误

最佳实践

输出格式

🇺🇸English

GrepAI Advanced Search Options

When to Use This Skill

Command-Line Options

JSON Output

Standard JSON

Compact JSON (AI Optimized)

TOON Output (v0.26.0+)

Standard TOON

Compact TOON (Best for AI)

TOON vs JSON Comparison

When to Use TOON

Compact Format Reference

Combining Options

AI Agent Integration

For Claude/GPT Prompts

Workflow Example

Scripting with JSON

Bash + jq

Python

Node.js

MCP Integration

Format Parameter

Token Optimization

Token Comparison

When to Use Each Format

Piping Results

To File

To Another Tool

Batch Searches

Error Handling

JSON Error Response

Checking for Errors in Scripts

Best Practices

Output Format

最新 Skills