grepai-search-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GrepAI Search Basics

GrepAI 基础搜索

This skill covers the fundamentals of semantic code search with GrepAI.

此技能涵盖使用GrepAI进行语义代码搜索的基础知识。

When to Use This Skill

何时使用此技能

Learning GrepAI search
Performing basic code searches
Understanding semantic vs. text search
Interpreting search results

学习GrepAI搜索
执行基础代码搜索
理解语义搜索与文本搜索的区别
解读搜索结果

Prerequisites

前提条件

GrepAI initialized (
```
grepai init
```
)
Index created (
```
grepai watch
```
)
Embedding provider running (Ollama, etc.)

已初始化GrepAI（
```
grepai init
```
）
已创建索引（
```
grepai watch
```
）
嵌入服务已运行（Ollama等）

What is Semantic Search?

什么是语义搜索？

Unlike traditional text search (grep, ripgrep), GrepAI searches by meaning:

Type	How it Works	Example
Text search	Exact string match	"login" → finds "login"
Semantic search	Meaning similarity	"authenticate user" → finds login, auth, signin code

与传统文本搜索（grep、ripgrep）不同，GrepAI通过语义进行搜索：

类型	工作原理	示例
文本搜索	精确字符串匹配	"login" → 找到包含"login"的内容
语义搜索	语义相似度匹配	"authenticate user" → 找到登录、认证、登录相关代码

Basic Search Command

基础搜索命令

bash

grepai search "your query here"

bash

grepai search "your query here"

Example

示例

bash

grepai search "user authentication flow"

Output:

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatus(401)
            return
        }
        claims, err := ValidateToken(token)
        if err != nil {
            c.AbortWithStatus(401)
            return
        }
        c.Set("user", claims.UserID)
        c.Next()
    }
}

Score: 0.82 | src/auth/jwt.go:23-55
──────────────────────────────────────────
func ValidateToken(tokenString string) (*Claims, error) {
    token, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
        return []byte(secretKey), nil
    })
    if err != nil {
        return nil, err
    }
    if claims, ok := token.Claims.(*Claims); ok && token.Valid {
        return claims, nil
    }
    return nil, errors.New("invalid token")
}

Score: 0.76 | src/handlers/login.go:10-35
──────────────────────────────────────────
func HandleLogin(c *gin.Context) {
    var req LoginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": "invalid request"})
        return
    }
    user, err := userService.Authenticate(req.Email, req.Password)
    // ...
}

bash

grepai search "user authentication flow"

输出：

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatus(401)
            return
        }
        claims, err := ValidateToken(token)
        if err != nil {
            c.AbortWithStatus(401)
            return
        }
        c.Set("user", claims.UserID)
        c.Next()
    }
}

Score: 0.82 | src/auth/jwt.go:23-55
──────────────────────────────────────────
func ValidateToken(tokenString string) (*Claims, error) {
    token, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
        return []byte(secretKey), nil
    })
    if err != nil {
        return nil, err
    }
    if claims, ok := token.Claims.(*Claims); ok && token.Valid {
        return claims, nil
    }
    return nil, errors.New("invalid token")
}

Score: 0.76 | src/handlers/login.go:10-35
──────────────────────────────────────────
func HandleLogin(c *gin.Context) {
    var req LoginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": "invalid request"})
        return
    }
    user, err := userService.Authenticate(req.Email, req.Password)
    // ...
}

Understanding Results

解读搜索结果

Result Format

结果格式

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
[code content]

Component	Meaning
Score	Similarity (0.0 to 1.0, higher = more relevant)
File path	Location of the code
Line numbers	Start-end lines of the chunk
Content	The actual code

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
[code content]

组成部分	含义
分数	相似度（0.0到1.0，分数越高相关性越强）
文件路径	代码所在位置
行号	代码片段的起始-结束行
内容	实际代码

Score Interpretation

分数解读

Score	Meaning
0.90+	Excellent match
0.80-0.89	Good match
0.70-0.79	Related
0.60-0.69	Loosely related
<0.60	Weak match

分数	含义
0.90+	极佳匹配
0.80-0.89	良好匹配
0.70-0.79	相关
0.60-0.69	松散相关
<0.60	弱匹配

Limiting Results

限制结果数量

By default, GrepAI returns 10 results. Adjust with

--limit

bash

undefined

默认情况下，GrepAI返回10条结果。可通过

--limit

参数调整：

bash

undefined

Get only top 3 results

仅获取前3条结果

grepai search "database queries" --limit 3

Get more results

获取更多结果

grepai search "error handling" --limit 20

undefined

grepai search "error handling" --limit 20

undefined

Checking Index Status

检查索引状态

Before searching, verify your index:

bash

grepai status

Output:

✅ GrepAI Status

   Index:
   - Files: 245
   - Chunks: 1,234
   - Last updated: 2 minutes ago

   Ready for search.

搜索前，请验证索引状态：

bash

grepai status

输出：

✅ GrepAI Status

   Index:
   - Files: 245
   - Chunks: 1,234
   - Last updated: 2 minutes ago

   Ready for search.

Search vs Grep Comparison

搜索与Grep对比

Traditional grep

传统grep

bash

grep -r "authenticate" .

Finds exact text "authenticate"
Misses synonyms (login, signin, auth)
Returns all matches, unranked

bash

grep -r "authenticate" .

查找精确文本"authenticate"
会遗漏同义词（login、signin、auth）
返回所有匹配结果，无排序

GrepAI search

GrepAI搜索

bash

grepai search "authenticate user credentials"

Finds semantically similar code
Includes related concepts
Results ranked by relevance

bash

grepai search "authenticate user credentials"

查找语义相似的代码
包含相关概念
结果按相关性排序

What Makes a Good Query

如何编写优质查询

Good Queries ✅

优质查询 ✅

Describe the intent or behavior:

bash

grepai search "validate user credentials"
grepai search "handle HTTP request errors"
grepai search "connect to the database"
grepai search "send email notification"
grepai search "parse JSON configuration"

描述意图或行为：

bash

grepai search "validate user credentials"
grepai search "handle HTTP request errors"
grepai search "connect to the database"
grepai search "send email notification"
grepai search "parse JSON configuration"

Less Effective Queries ❌

效果较差的查询 ❌

Too short or generic:

bash

grepai search "auth"           # Too vague
grepai search "function"       # Too generic
grepai search "getUserById"    # Exact name (use grep)

过于简短或宽泛：

bash

grepai search "auth"           # 过于模糊
grepai search "function"       # 过于宽泛
grepai search "getUserById"    # 精确名称（建议使用grep）

Natural Language Queries

自然语言查询

GrepAI understands natural language:

bash

undefined

GrepAI支持自然语言查询：

bash

undefined

Ask questions

提问

grepai search "how are users authenticated" grepai search "where is the database connection configured"

Describe behavior

描述行为

grepai search "code that sends emails to users" grepai search "functions that validate input data"

undefined

grepai search "code that sends emails to users" grepai search "functions that validate input data"

undefined

Multiple Words vs Phrases

多词查询与短语查询

Both work, but phrases often get better results:

bash

undefined

两种方式都可行，但短语查询通常能获得更优结果：

bash

undefined

Multiple words (OR-like behavior)

多词查询（类似OR逻辑）

grepai search "login password validation"

Phrase (describes specific intent)

短语查询（描述特定意图）

grepai search "validate user login credentials"

undefined

grepai search "validate user login credentials"

undefined

Quick Tips

快速提示

Use English: Models are trained on English
Be specific: "JWT token validation" vs "validation"
Describe intent: What the code DOES, not what it's called
Use 3-7 words: Enough context, not too verbose
Iterate: Refine query based on results

使用英文： 模型基于英文训练
具体化： 例如使用"JWT token validation"而非"validation"
描述意图： 说明代码的功能，而非名称
使用3-7个词： 提供足够上下文，避免过于冗长
迭代优化： 根据搜索结果调整查询语句

Common Search Patterns

常见搜索模式

Finding Entry Points

查找入口点

bash

grepai search "main entry point"
grepai search "application startup"
grepai search "HTTP server initialization"

bash

grepai search "main entry point"
grepai search "application startup"
grepai search "HTTP server initialization"

Finding Error Handling

查找错误处理

bash

grepai search "error handling and logging"
grepai search "exception handling"
grepai search "error response to client"

bash

grepai search "error handling and logging"
grepai search "exception handling"
grepai search "error response to client"

Finding Data Access

查找数据访问

bash

grepai search "database query execution"
grepai search "fetch user from database"
grepai search "save data to storage"

bash

grepai search "database query execution"
grepai search "fetch user from database"
grepai search "save data to storage"

Finding Business Logic

查找业务逻辑

bash

grepai search "calculate order total"
grepai search "process payment transaction"
grepai search "validate business rules"

bash

grepai search "calculate order total"
grepai search "process payment transaction"
grepai search "validate business rules"

Troubleshooting

故障排除

❌ Problem: No results ✅ Solutions:

Check index exists:
```
grepai status
```
Run
```
grepai watch
```
if index is empty
Simplify query

❌ Problem: Irrelevant results ✅ Solutions:

Be more specific
Use different words
Check if code exists in the codebase

❌ Problem: Missing expected code ✅ Solutions:

Check if file is ignored in config
Ensure file extension is supported
Re-index:
```
rm .grepai/index.gob && grepai watch
```

❌ 问题：无搜索结果 ✅ 解决方案：

检查索引是否存在：
```
grepai status
```
若索引为空，执行
```
grepai watch
```
简化查询语句

❌ 问题：结果不相关 ✅ 解决方案：

更具体化查询
使用不同的表述
检查代码库中是否存在目标代码

❌ 问题：缺失预期代码 ✅ 解决方案：

检查配置中是否忽略了该文件
确保文件扩展名受支持
重新索引：
```
rm .grepai/index.gob && grepai watch
```

Output Format

输出格式

Successful basic search:

Query: "user authentication flow"
Results: 5 matches

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
[relevant code...]

Score: 0.82 | src/auth/jwt.go:23-55
──────────────────────────────────────────
[relevant code...]

[additional results...]

Tip: Use --limit to adjust number of results
     Use --json for machine-readable output

基础搜索成功时的输出：

Query: "user authentication flow"
Results: 5 matches

Score: 0.89 | src/auth/middleware.go:15-45
──────────────────────────────────────────
[relevant code...]

Score: 0.82 | src/auth/jwt.go:23-55
──────────────────────────────────────────
[relevant code...]

[additional results...]

Tip: Use --limit to adjust number of results
     Use --json for machine-readable output