symdex-code-search

SymDex 代码搜索

广泛浏览文件前，请先使用 SymDex。 通过检索 Agent 所需的确切代码，而不是扫描整个文件，来节省 token。 SymDex 目前覆盖 21 种语言，包括 Python、Go、Kotlin、Dart、Swift、HTML、CSS、Shell、Vue/Svelte 脚本块，以及 Markdown 标题和受支持的围栏代码块。

当前 SymDex 快照

• 软件包版本：0.1.26
• 最新公开标签：v0.1.26
• MCP 工具数量：21
• 语言覆盖范围：21 种语言，包括 Android/Kotlin、Flutter/Dart、iOS/Swift、HTML、CSS 系样式表、Shell、Vue/Svelte 脚本块、Markdown 标题和受支持的围栏代码块
• 路由提取：Python、JavaScript/TypeScript、Spring/Kotlin、Laravel、Gin 风格的 Go、ASP.NET、Rails/Sinatra、Phoenix 和 Actix
• 搜索输出：单行 CLI token 节省摘要，以及 MCP roi、roi_summary 和 roi_agent_hint
• 质量输出：MCP 结果和 CLI JSON 中包含 quality，其中提供置信度、新鲜度、解析器模式、语言、生成文件提示和嵌入可用性
• 上下文包：CLI symdex pack 和 MCP build_context_pack 可组装受 token 预算限制的证据包，用于回答范围较广的功能问题
• 语义后端：本地 sentence-transformers、Voyage、兼容 OpenAI 的 /embeddings、Gemini 和兼容代理
• 托管嵌入支持：使用 SYMDEX_EMBED_RPM，并通过 symdex index --lazy 在前台进行结构索引，同时在后台填充嵌入
• 无嵌入模式：symdex index --no-embed 会完全跳过语义嵌入工作
• 监视行为：默认执行低内存结构刷新；只有在必须持续刷新语义嵌入时才使用 symdex watch --embed
• 状态模型：默认使用全局 ~/.symdex，也可选用包含 registry.json 的工作区本地 ./.symdex
• Markdown 支持：.md、.markdown 和 .mdx 标题及受支持的围栏代码块会与源文件一同建立索引

从这里开始

1. 如果 SymDex CLI 提示有更新版本，请优先升级，再开始长时间会话。
2. 确认仓库 ID。
3. 如果已知仓库 ID，每次调用范围受限的工具时都传入 repo。
4. 如果未知仓库 ID，请调用 list_repos 并匹配当前工作树。
5. 使用 get_index_status(repo) 检查索引的新鲜度。
6. 如果当前工作树尚未建立索引，请调用 index_folder(path=".")。
7. 如果工作区已有 .symdex，请将其视为预期的本地 SymDex 状态并重复使用。
8. 在任务的其余部分重复使用返回的 repo ID。

如果 SymDex 不可用或索引失败，请明确说明，并仅在必要时回退到常规文件读取。

核心规则

• 先搜索。
• 只要知道 repo，就传入它。
• 对于“此功能如何运作？”这类范围较广的问题、文档、API 或 Bug 调查问题，在进行许多分散的窄范围搜索前，先使用 build_context_pack。
• 优先使用 get_symbol 或 get_file_outline，而不是读取完整文件。
• 手动追踪前，先使用调用图和路由工具。
• 重大编辑或切换工作树后，重新检查 get_index_status。
• 只有在编辑、审查不受支持或生成的内容，或 SymDex 无法回答时，才读取完整文件。
• 优先降低检索所需的 token，而不是加载大量上下文。
• 如果搜索工具返回 roi、roi_summary 或 roi_agent_hint，请在回复中简要说明大致节省的 token 数。
• 在基于结果进行推理前，先检查 quality。优先采用新鲜、由解析器支持且置信度高的证据；如果证据过期、由工具生成、属于回退文本或缺少嵌入，请提醒用户。
• 如果仓库使用工作区本地 SymDex 状态（./.symdex），请留在该工作区内，以便自动发现同一索引。
• 将 symdex watch 视为默认低内存模式；只有在文件变更时必须刷新语义嵌入，才请求 --embed。
• 对请求限制严格的远程嵌入提供商，优先使用 symdex index --lazy 并设置 SYMDEX_EMBED_RPM，而不是让 Agent 会话阻塞在耗时的前台嵌入任务上。

工具选择

需求	工具
为当前工作树建立索引	index_folder
显式注册并为仓库建立索引	index_repo
按名称查找函数、类或方法	search_symbols
按意图或行为查找代码	semantic_search
查找字面文本或正则表达式匹配项	search_text
构建符合查询需求的证据包	build_context_pack
读取单个符号的确切源码	get_symbol
阅读文件前获取文件大纲	get_file_outline
获取仓库地图或摘要	get_repo_outline 或 get_file_tree
追踪谁调用了某个符号	get_callers
追踪某个符号调用了什么	get_callees
查找 HTTP 路由	search_routes
检查仓库索引的新鲜度	get_index_status
获取代码指标和语言分布	get_repo_stats
列出索引	list_repos
清理已删除工作树的索引	gc_stale_indexes

典型流程

1. 确认仓库 ID 和索引新鲜度。
2. 如有需要，使用 index_folder 建立索引。
3. 对于涉及广泛功能、API、文档或 Bug 调查的问题，从 build_context_pack 开始。
4. 对于范围较窄的查询，从 search_symbols、semantic_search 或 search_text 开始。
5. 缩小范围，使用 get_symbol 或 get_file_outline。
6. 在基于返回结果做出代码理解方面的判断前，先检查其中的 quality 字段。
7. 使用 get_callers、get_callees、search_routes 或 get_repo_stats 进行更深入的分析。
8. 只有在 SymDex 无法足够准确地回答时，才直接读取文件。

决策指南

• “X 定义在哪里？” → search_symbols
• “这段代码做什么？” → semantic_search，然后使用 get_symbol
• “这个功能是如何工作的？” → build_context_pack
• “记录此 API 前收集证据” → 使用 include=["routes", "docs", "tests"] 调用 build_context_pack
• “谁在使用它？” → get_callers
• “它调用了什么？” → get_callees
• “端点在哪里？” → search_routes
• “先给我看看文件结构” → get_file_outline
• “概述一下仓库” → get_repo_outline 或 get_repo_stats
• “索引是最新的吗？” → get_index_status

适用的触发语句

• “查找验证 JWT 的函数”
• “谁调用了这个路由处理程序？”
• “给我看看这个文件的大纲”
• “搜索解析 webhook 负载的代码”
• “查找 /api/checkout 对应的 HTTP 路由”
• “在我编辑任何内容之前，给我一份仓库摘要”
• “查找可能解释这个 Bug 的代码路径”
• “检查此逻辑在调用方和被调用方之间是否一致”
• “为这个功能构建一个上下文包”

Bug 和逻辑调查

将 SymDex 用作证据检索工具，而不是单凭它作为证明。

1. 从症状、路由、函数或文本线索入手。
2. 如果 Bug 涉及多个符号、路由、文档或测试，请使用 build_context_pack。
3. 获取确切符号、路由、调用链、被调用链和相关文档。
4. 检查 quality.index_fresh、quality.confidence、quality.parser_mode、quality.is_generated 和 quality.has_embeddings。
5. 如果证据质量较弱，请先说明缺少什么，再声称存在 Bug。
6. 针对任何 Bug 假设，引用具体的符号、文件、路由或调用边作为依据。

编辑

需要编辑代码时：

1. 使用 SymDex 查找确切的符号或文件位置。
2. 只读取该文件或符号片段。
3. 只做必要的最小改动。

监控与语义搜索

• 默认情况下，symdex watch 会刷新结构索引，而不加载本地嵌入模型。
• 只有在任务需要持续更新语义搜索时，才使用 symdex watch --embed。
• 如果 semantic_search 没有嵌入向量，请改用 search_symbols 或 search_text，或者启用 symdex[local]、Voyage、OpenAI-compatible、Gemini 或其他托管嵌入后端后重新建立索引。
• 如果托管模型延迟或 RPM 限制可能导致嵌入耗时，请使用 symdex index --lazy。
• 工作区本地状态会将监控器元数据保存在 ./.symdex 下，因此应从该工作区运行命令，或传入匹配的 --state-dir。

仅在需要时使用常规浏览

• SymDex 不可用。
• 仓库尚未建立索引，且当前环境无法为其建立索引。
• 目标文件类型不受支持或由工具生成。
• 你需要符号级响应未提供的周边上下文。

输出检查清单

• 已确认或推导出仓库 ID
• 已检查索引的新鲜度
• 在广泛读取文件之前已选择 SymDex 工具
• 针对涉及多个文件的宽泛问题，已使用上下文包
• 在可能的情况下，读取整个文件前已查看确切的符号或文件大纲
• 在提出逻辑或 Bug 相关说法之前，已检查质量元数据
• 仅在 SymDex 无法给出清晰答案时才直接读取文件