osgrep-reference

osgrep：语义代码搜索

在进行概念性代码探索时，优先使用 osgrep，而非 grep/rg——它按含义查找代码，而不只是匹配字符串。对于精确标识符或字面字符串搜索，grep/rg 仍然合适。

概述

osgrep 是一款自然语言语义代码搜索工具，按概念而非关键词匹配来查找代码。与匹配字面字符串的 grep 不同，osgrep 使用本地 AI 嵌入理解代码语义。

版本 0.5.16（2025 年 12 月）亮点：

• skeleton 命令：将文件压缩为函数/类签名（减少约 85% 的令牌）
• trace 命令：显示任意符号的调用者/被调用者（调用图）
• symbols 命令：列出所有已索引符号及其定义
• doctor 命令：健康状况/完整性验证
• list 命令：显示所有已索引仓库
• 每个项目使用独立的 .osgrep/ 目录（不再使用全局 ~/.osgrep/data）
• 采用 V2 架构，性能有所提升（令牌用量减少约 20%，速度提升约 30%）
• 支持 Go 语言
• --reset 标志，可从头重新索引
• 使用 ColBERT 重新排序，提高结果相关性
• 角色检测：区分编排逻辑与类型定义
• 分开搜索：“代码”和“文档”索引独立

适用场景：

• 探索不熟悉的代码库（“认证逻辑在哪里？”）
• 查找概念模式（“展示错误处理”）
• 定位横切关注点（“所有数据库迁移”）
• 用户明确要求进行语义代码搜索

适用传统工具的场景：

• 搜索精确字符串或标识符（使用 Grep）
• 按名称模式查找文件（使用 Glob）
• 已知确切位置（使用 Read）

快速开始

请在项目目录中运行 osgrep，因为它使用每个项目独立的 .osgrep/ 索引。

cd /path/to/project      # REQUIRED: cd into the project first
osgrep "your query"      # Now search works

基本搜索

osgrep "your semantic query"
osgrep search "your query" path/to/scope    # Scope to subdirectory
osgrep skeleton src/file.py                 # Compress file to signatures
osgrep trace functionName                   # Show call graph
osgrep symbols                              # List all symbols

示例：

osgrep "user registration flow"
osgrep "webhook signature validation"
osgrep "database transaction handling"
osgrep "how are plugins loaded" packages/src

输出格式

返回结果的格式如下：

IMPLEMENTATION path/to/file:line
Score: 0.95

Preamble:
[code snippet or content preview]
...

• IMPLEMENTATION：表示匹配类型的标签
• Score：相关性分数（0-1，越高越好）
• ...：截断标记——代码片段不完整，请使用 Read 获取完整上下文

搜索策略

针对架构/系统级问题

适用于：认证、集成、文件监视、横切关注点

1. 先进行广泛搜索，了解整体情况：

   osgrep "authentication authorization checks"
   

2. 查看搜索结果——寻找多个文件中的模式：

   • 检查是在中间件、装饰器还是多个服务中？
   • 文件路径是否暗示了不同层级（网关、处理程序、工具）？

3. 有策略地阅读——选择 2-4 个能代表不同方面的文件：

   • 阅读主入口点
   • 阅读有代表性的中间件/工具文件
   • 如果架构不清晰，沿导入关系继续查看

4. 如果某个方面不清楚，就通过具体搜索进一步缩小范围：

   osgrep "session validation logic"
   osgrep "API authentication middleware"
   

针对特定实现细节

适用于：特定函数、算法、单项功能

1. 针对精确逻辑进行具体搜索：

   osgrep "logic for merging user and default configuration"
   

2. 评估语义匹配结果：

   • 代码片段看起来相关吗？
   • 如果以 ... 结尾或在逻辑中途截断，请阅读文件

3. 一次搜索，一次阅读：使用 osgrep 定位最合适的文件，然后完整阅读。

CLI 参考

搜索选项

控制结果数量：

osgrep "validation logic" -m 20           # Max 20 results total (default: 10)
osgrep "validation logic" --per-file 3    # Up to 3 matches per file (default: 1)

输出格式：

osgrep "API endpoints" --compact           # File paths only
osgrep "API endpoints" --content           # Full chunk content (not just snippets)
osgrep "API endpoints" --scores            # Show relevance scores
osgrep "API endpoints" --plain             # Disable ANSI colors

搜索前同步：

osgrep "validation logic" -s               # Sync files to index before searching
osgrep "validation logic" -d               # Dry run (show what would sync)

索引管理

osgrep index                    # Incremental update
osgrep index -r                 # Full re-index from scratch (--reset)
osgrep index -p /path/to/repo   # Index a specific directory
osgrep index -d                 # Preview what would be indexed (--dry-run)

高级命令（v0.5+）

Skeleton - 将文件压缩为签名：

osgrep skeleton src/server.py              # Show function/class signatures only
osgrep skeleton src/server.py --no-summary # Omit call/complexity summaries
osgrep skeleton "auth logic" -l 5          # Query mode: skeleton of top 5 matching files

输出显示：函数签名，以及函数体内的 # → calls | C:N | ORCH 摘要。

Trace - 显示调用图：

osgrep trace handleRequest                 # Who calls this? What does it call?

Symbols - 列出所有已索引符号：

osgrep symbols                             # All symbols (default limit: 20)
osgrep symbols "Request"                   # Filter by pattern
osgrep symbols -p src/api/ -l 50           # Filter by path, increase limit

其他命令

osgrep list                     # Show all indexed repositories
osgrep doctor                   # Check health and configuration
osgrep setup                    # Pre-download models (~150MB)
osgrep serve                    # Run background daemon (port 4444)
osgrep serve -p 8080            # Custom port (or OSGREP_PORT=8080)
osgrep serve -b                 # Run in background (--background)
osgrep serve status             # Check if daemon is running
osgrep serve stop               # Stop daemon
osgrep serve stop --all         # Stop all daemons

服务端点：

• GET /health - 健康检查
• POST /search - 使用 { query, limit, path, rerank } 进行搜索
• 锁文件：.osgrep/server.json，包含 port/pid

Claude Code 集成

osgrep install-claude-code      # Install as Claude Code plugin
osgrep install-opencode         # Install for Opencode

两个插件都会在会话期间自动管理后台服务的生命周期。

常见搜索模式

架构探索

# Mental processes (Open Souls / Daimonic)
osgrep "mental processes that orchestrate conversation flow"
osgrep "subprocesses that learn about the user"
osgrep "cognitive steps using structured output"

# React/Next.js
osgrep "where do we fetch data in components?"
osgrep "custom hooks for API calls"
osgrep "protected route implementation"

# Backend
osgrep "request validation middleware"
osgrep "authentication flow"
osgrep "rate limiting logic"

业务逻辑

osgrep "payment processing"
osgrep "notification sending"
osgrep "user permission checks"
osgrep "order fulfillment workflow"

跨领域关注点

osgrep "error handling patterns"
osgrep "logging configuration"
osgrep "database migrations"
osgrep "environment variable usage"

高效查询技巧

信任语义

无需使用精确名称。概念性查询效果更好：

# Good - conceptual
osgrep "how does the server start"
osgrep "component state management"

# Less effective - too literal
osgrep "server.init"
osgrep "useState"

具体明确

# Too vague
osgrep "code"

# Clear intent
osgrep "user registration validation logic"

使用自然语言

osgrep "how do we handle payment failures?"
osgrep "what happens when a webhook arrives?"
osgrep "where is user input sanitized?"

留意分布式模式

如果结果涉及不同目录中的 5 个或更多文件，该功能很可能涉及架构层面——深入研究前先全面了解。

不要过度依赖代码片段

对于架构问题，代码片段只是线索，而不是答案。请阅读关键文件。

技术细节

• 完全本地运行：使用 transformers.js 嵌入（不调用远程 API）
• 自动隔离：每个仓库在各自的 .osgrep/ 目录中建立索引（v0.5+）
• 自适应性能：有界并发可保持系统响应能力
• 索引位置：项目根目录中的 .osgrep/（v0.4.x 中为 ~/.osgrep/data/）
• 模型下载：首次运行时约 150MB（使用 osgrep setup 预先下载）
• 分块策略：Tree-sitter 按函数／类边界解析代码
• 去重：对相同代码块去重
• 双通道：使用 ColBERT 重排序，分别建立“代码”和“文档”索引
• 结构增强：函数／类的优先级高于测试文件
• 骨架压缩：查看文件结构时可减少约 85% 的令牌数

故障排除

显示“仍在建立索引……”消息：

• 索引仍在进行中。完成前，结果可能不完整。
• 提醒用户，并询问他们是否希望继续。

首次搜索较慢：

• 这是预期情况——中型仓库建立索引需要 30–60 秒
• 使用 osgrep setup 预先下载模型

索引已过时：

• 运行 osgrep index 刷新索引
• 运行 osgrep index --reset 完全重新建立索引
• osgrep 通常会自动检测更改

安装问题：

osgrep doctor              # Diagnose problems
npm install -g osgrep      # Reinstall if needed

未找到结果：

• 尝试更宽泛的查询（“身份验证”而不是“JWT 中间件”）
• 确保索引是最新的（osgrep index）
• 确认你位于正确的仓库目录中