grepai-search-basics

GrepAI 搜索基础

本技能介绍使用 GrepAI 进行语义代码搜索的基础知识。

何时使用此技能

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

前置条件

1. 已初始化 GrepAI（grepai init）
2. 已创建索引（grepai watch）
3. 嵌入提供程序正在运行（Ollama 等）

什么是语义搜索？

与传统文本搜索（grep、ripgrep）不同，GrepAI 根据含义进行搜索：

类型	工作方式	示例
文本搜索	精确字符串匹配	“login” → 查找 “login”
语义搜索	含义相似度	“authenticate user” → 查找 login、auth、signin 代码

基本搜索命令

grepai search "your query here"

示例

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)
    // ...
}

理解搜索结果

结果格式

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

组成部分	含义
分数	相似度（0.0 到 1.0，越高 = 越相关）
文件路径	代码所在位置
行号	代码块的起止行
内容	实际代码

分数解读

分数	含义
0.90+	极佳匹配
0.80-0.89	良好匹配
0.70-0.79	相关
0.60-0.69	关联较弱
<0.60	匹配度较低

限制结果数量

GrepAI 默认返回 10 条结果。使用 --limit 调整：

# Get only top 3 results
grepai search "database queries" --limit 3

# Get more results
grepai search "error handling" --limit 20

检查索引状态

搜索前，请确认索引状态：

grepai status

输出：

✅ GrepAI Status

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

   Ready for search.

搜索与 Grep 对比

传统 grep

grep -r "authenticate" .

• 查找完全匹配的文本 “authenticate”
• 找不到同义词（login、signin、auth）
• 返回所有匹配项，不进行排序

GrepAI 搜索

grepai search "authenticate user credentials"

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

如何编写好的查询

好的查询 ✅

描述意图或行为：

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"

效果较差的查询 ❌

太短或太笼统：

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

自然语言查询

GrepAI 能理解自然语言：

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

多个单词与短语

两者都可用，但短语通常能获得更好的结果：

# Multiple words (OR-like behavior)
grepai search "login password validation"

# Phrase (describes specific intent)
grepai search "validate user login credentials"

快速提示

1. 使用英语： 模型基于英语训练
2. 具体明确： 使用 “JWT token validation”，而不是 “validation”
3. 描述意图： 描述代码的作用，而不是它的名称
4. 使用 3-7 个词： 提供足够的上下文，同时避免过于冗长
5. 反复尝试： 根据结果优化查询

常见搜索模式

查找入口点

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

查找错误处理

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

查找数据访问

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

查找业务逻辑

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

故障排除

❌ 问题： 没有结果
✅ 解决方案：

• 检查索引是否存在：grepai status
• 如果索引为空，运行 grepai watch
• 简化查询

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

• 提供更具体的描述
• 尝试使用不同的词
• 检查代码库中是否存在相关代码

❌ 问题： 未找到预期代码
✅ 解决方案：

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

输出格式

基本搜索成功时：

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