用途
Codebase Navigator 是一个语义代码搜索技能，由 osgrep 驱动，用于理解代码库、查找实现和导航大型项目。当用户询问“某功能在哪里实现？”“某组件如何工作？”“找到处理某任务的代码”或需要理解代码库架构、搜索实现模式时，可调用此技能。
主要能力
- 语义搜索：根据代码含义而非仅关键词查找代码，支持自然语言描述查询。
- 索引管理：检查索引新鲜度，自动刷新过期索引（超过4小时），支持首次设置和完整重新索引。
- 多种输出模式：默认模式显示带行号的代码片段预览；内容模式（--content）显示完整块内容；紧凑模式（--compact）仅显示文件路径；JSON 模式（--json）提供机器可读输出；评分模式（--scores）显示相关性分数（0-1）。
- 高级功能：后台服务器（osgrep serve，默认端口4444）、多存储支持（--store）、查询优化与迭代。
- 与其他工具结合：可与 Glob（按文件类型过滤）、grep（精确字符串匹配）、Read（深入理解）配合使用。
使用方式
首次设置
如果当前仓库没有存储，运行：
osgrep list # 查看可用存储
osgrep doctor # 验证设置健康
osgrep index # 索引当前目录（约30秒-2分钟）
检查索引新鲜度（自动刷新）
搜索前检查索引是否过期（>4小时）：
# 查找当前仓库的存储
osgrep list
# 检查相关存储的年龄（macOS）
STORE=~/.osgrep/data/YOUR-STORE.lance
STORE_AGE=$(( $(date +%s) - $(stat -f %m "$STORE") ))
# 如果超过4小时（14400秒），刷新
if [ $STORE_AGE -gt 14400 ]; then
echo "Index is $(( STORE_AGE / 3600 )) hours old - refreshing..."
osgrep index
fi
快速方式：如果不确定，直接使用 --sync：
osgrep search "query" --sync # 始终安全，搜索前更新
语义搜索
基本搜索：
osgrep search "natural language description of what you're looking for"
调整搜索：
osgrep search "query" --max-count 10 # 限制总结果数
osgrep search "query" --per-file 3 # 每个文件多个匹配
osgrep search "query" --content # 显示完整块内容
osgrep search "query" --compact # 仅文件路径
osgrep search "query" --scores # 显示相关性分数
osgrep search "query" --json # 机器可读输出
综合结果
不要直接输出原始 osgrep 结果。应阅读相关文件片段，理解上下文中的代码，用平实语言向用户解释，并引用具体文件和行号。
查询构建
语义查询效果最佳。将用户问题转化为描述性短语：
- “Where's the auth?” → “authentication logic and user login”
- “How do we handle errors?” → “error handling and exception management”
- “Find the API endpoints” → “HTTP routes and API endpoint definitions”
- “Database queries” → “database queries and SQL execution”
- “Config loading” → “configuration loading and environment variables”
技巧：使用描述性短语而非关键词；包含同义词；描述目的；具体说明所需内容。
高级用法
- 保持索引新鲜：拉取新代码、创建/删除文件、重大重构后定期刷新。使用
osgrep search "query" --sync或osgrep index。 - 后台服务器：大型代码库频繁变更时，运行
osgrep serve（端口4444）或osgrep serve --port 8080。 - 多存储：
osgrep --store myproject.lance search "query"。 - 查询优化：检查结果质量（--scores，低分<0.15表示匹配差）；用领域术语缩小范围；增加具体性；尝试同义词。
osgrep 与 grep 的选择
- 使用 osgrep：按概念搜索、未知函数名、架构问题、理解代码目的。
- 使用 grep/rg：搜索精确字符串、已知函数名、错误消息查找、特定标识符。
- 经验法则：如果能输入精确字符串，用 grep；如果描述代码功能，用 osgrep。
结合工具
- osgrep + Glob：osgrep 找到提及 Python 的代码，不限于 .py 文件；然后用 Glob 过滤实际脚本。
- osgrep + grep：先用 osgrep 找到相关区域，再用 grep 搜索特定术语。
- osgrep + Read：先用 osgrep 找到文件，再用 Read 理解。
反模式
不要：用 osgrep 做精确字符串匹配；直接输出原始结果而不综合；跳过索引；使用单个关键词；期望找到技术字面量如“sha256”“TODO:”。 要：用自然语言描述构建查询；搜索无结果时检查 osgrep list；需要更多上下文时用 --content；结合文件阅读；用 --scores 评估匹配质量；结果不佳时迭代优化查询。
适用场景
- 回答“某功能在哪里实现？”
- 回答“某组件如何工作？”
- 查找处理特定任务的代码
- 理解代码库架构
- 搜索实现模式
- 导航大型项目
限制
- 需要预先安装 osgrep 并建立索引。
- 不适合精确字符串匹配（应使用 grep/rg）。
- 无法找到技术字面量如“sha256”“TODO:”、错误代码。
- 索引可能过期，需要定期刷新。
- 查询需要自然语言描述，单个关键词效果差。
- 首次索引可能需要30秒到2分钟。
- 官方资料未提供收费、价格、平台支持等具体信息。