Sym Dex

SymDex 的

代理AI系统的符号索引。

*SymDex将签出的存储库转换为代码结构、路由、关系、文档、测试和上下文的本地符号索引，因此AI编码代理可以在不首先读取整个文件的情况下进行推理、检索和操作。*

 ](https://pypi.org/project/symdex/)   

      

From whole-file browsing to exact repo retrieval

Exact symbols, routes, callers, callees, file outlines, semantic matches, and token-budgeted context packs for coding agents.

# Install the lean core
pip install symdex

# Add local semantic search when you want the sentence-transformers backend
pip install "symdex[local]"

# Or install the local semantic backend as an isolated CLI tool
uv tool install "symdex[local]"

# Or run without installing
uvx symdex --help

# Upgrade an existing install
py -m pip install -U symdex
uv tool upgrade symdex
uvx symdex@latest --help

# Install the SymDex agent skill globally for supported agents
npx skills add https://github.com/husnainpk/SymDex --skill symdex-code-search --yes --global

______________________________________________________________________

SymDex做什么

SymDex是一个用于AI编码代理的repo本地符号索引引擎。它将项目映射到精确的符号、文件、路由、关系、文档、测试和检索上下文中，然后通过CLI命令和MCP工具公开该映射。

AI编码代理是有用的，直到他们不得不从头开始重新发现你的仓库。他们打开整个文件，grep宽模式，错过路由处理程序，两次读取相同的实用程序，并花费数千个令牌来进行定向。

SymDex在代理开始读取代码之前为其提供了一个repo本地检索层。您将索引保留在计算机上，仅在语义搜索有用时选择嵌入后端，并通过CLI命令和MCP工具公开相同的项目映射。

它将您的项目索引到一个小型的本地SQLite知识库中，包括：

• 精确的符号和字节偏移
• 文件大纲和回购摘要
• 文字文本搜索
• 可选语义搜索
• 调用者、被调用者和循环依赖性检查
• 提取的HTTP路由
• 查询驱动的上下文包，从符号、路线、文档、测试、文本、图邻居和可选的语义匹配中组装小证据包
• 用于新鲜度、置信度、解析器模式、生成路径和嵌入可用性的检索质量元数据
• 一个repo、多个repo或多个工作树的注册表

然后，代理可以要求他们需要的窄切片：函数、路由、调用链、文件大纲、意图匹配，或者更广泛的功能问题的令牌预算上下文包。这意味着更少的盲目浏览，更少的上下文浪费，以及可以解释SymDex节省了多少代币预算的响应。

SymDex是本地第一。基础 symdex 保持符号、文本、路线、图形和MCP特征的精简。安装 symdex[local] 只有当你想要本地语义嵌入时，或者当你想要远程嵌入时，将托管后端指向Voyage、OpenAI兼容服务、Gemini或兼容的代理。

此结账中的当前产品功能：

• 当前版本 0.1.26；最新公共标签 v0.1.26
• 21个MCP工具，涵盖索引、搜索、上下文包、大纲、路由、统计、图形、缓存失效和过时索引清理
• 21种语言界面，包括HTML、CSS、Shell、Svelte、Markdown标题和支持的围栏代码块
• 通过Kotlin、Dart和Swift解析器目标覆盖Android、Flutter和iOS
• 跨Python、JavaScript/TypeScript、Spring/Kotlin、Laravel、Gin-style Go、ASP的路由提取。NET、Rails/Sinatra、Phoenix和Actix
• 成功搜索命令后的一行CLI令牌节省脚注
• 主控程序 roi, roi_summary，以及 roi_agent_hint 字段，以便代理在最终响应中提及节省
• MCP和CLI JSON quality 字段，以便代理在从结果推理之前判断置信度、索引新鲜度、解析器模式、生成的路径和嵌入可用性
• symdex pack 和MCP build_context_pack 用于查询形状、令牌预算的证据包
• 局部语义后端 sentence-transformers，Voyage，兼容OpenAI /embeddings，以及Gemini嵌入
• SYMDEX_EMBED_RPM 托管嵌入提供程序的请求速度
• symdex index --lazy 在后台观察器中构建嵌入时快速进行前台结构索引
• 低的 symdex watch 默认情况下：结构刷新，不加载嵌入模型，除非 --embed 已通过
• 重复观察程序保护、空闲自动退出和状态感知观察程序元数据
• 本地工作区 ./.symdex Docker、可移植工作区和不希望索引隐藏在主目录中的团队的状态
• 带有确切信息的升级通知 pip, uv tool，以及 uvx 存在较新版本时的命令

______________________________________________________________________

SymDex代理技能

当您希望受支持的代理在广泛浏览文件之前使用SymDex时，请安装SymDex代码搜索技能：

npx skills add https://github.com/husnainpk/SymDex --skill symdex-code-search --yes --global

如果您希望使用交互式安装程序，请省略 --yes --global.

技能告诉特工：

• 首先检查回购和索引准备情况
• 在广泛的Read/Grep/Glob发现之前使用SymDex进行搜索
• 与完整文件读取相比，更喜欢符号级和轮廓级检索
• 当调用者、被调用者、路由、仓库统计和语义搜索更适合时，使用它们
• 在多次单独搜索之前，使用上下文包回答更广泛的“此功能如何工作？”问题
• 当SymDex不可用或语义嵌入尚未构建时，可以明显回退
• 保持工作流程以较低令牌代码检索为中心，而不是广泛的文件读取

该技能存在于以下仓库中 skills/symdex-code-search/SKILL.md 并遵循标准 skills//SKILL.md 布局。

通过安装 skills CLI使用与skills.sh索引相同的公共路径。

______________________________________________________________________

60秒快速入门

# Install the lean core
pip install symdex
# or
uv tool install symdex

# Index a project
symdex index ./myproject --repo myproject

# Search by symbol name
symdex search "validate_email" --repo myproject

# Search by literal text
symdex text "JWT" --repo myproject

# Add local semantic search only when you want embeddings
pip install "symdex[local]"

# Search by intent
symdex semantic "check email format" --repo myproject

# Build a token-budgeted context pack for an agent
symdex pack "how checkout auth works" --repo myproject --budget 6000

# Show HTTP routes
symdex routes myproject -m POST

# Start the MCP server
symdex serve

笔记：

• 如果你忽略了 --repo 上 symdex index 或 symdex watch，SymDex会自动从当前的git分支和工作树路径哈希生成一个稳定的repo id。
• 索引后，SymDex会打印一个代码摘要。
• 成功执行搜索命令后，SymDex会打印一行ROI页脚，其中包含大致的令牌节省。
• MCP搜索工具也返回 roi_agent_hint，因此代理可以将节省的资金折叠到面向用户的响应中，而不是将其埋在日志中。
• 当存在较新的PyPI版本时，正常的CLI命令会打印精确的升级命令 pip, uv tool，以及 uvx.
• 集 SYMDEX_STATE_DIR=.symdex 关于保存回购数据库的第一个索引， registry.db，以及 registry.json 在当前工作空间内。之后，从工作区运行的命令会自动发现本地状态。
• --state-dir 可以全局传递，也可以在子命令之后传递，例如 symdex --state-dir .symdex repos 或 symdex repos --state-dir .symdex.
• 规范CLI命令包括 index 和 repos.Shell兼容性别名也接受MCP形状的名称，如 index-folder, index-repo，以及 list-repos.
• 语义搜索需要存储嵌入。如果在启用所需的后端之前对仓库进行了索引，请使用重新索引 symdex index, symdex index --lazy，或 symdex watch --embed.

添加到您的代理配置中：

{
  "mcpServers": {
    "symdex": {
      "command": "uvx",
      "args": ["symdex", "serve"]
    }
  }
}

HTTP模式：

{
  "mcpServers": {
    "symdex": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

______________________________________________________________________

工作区本地状态和Docker

SymDex默认为 ~/.symdex 并且还支持用于可移植和容器化工作流的工作区本地状态目录。

在第一次设置时这样使用它：

SYMDEX_STATE_DIR=.symdex symdex index ./myproject --repo myproject

这会产生：

• ./.symdex/.db
• ./.symdex/registry.db
• ./.symdex/registry.json

registry.json 是人类可读的清单。在工作区本地模式下，它存储相对 root_path 和 db_path 值，因此您可以在不打开SQLite的情况下检查索引的内容。

本地状态存在后，SymDex会自动从当前工作区或任何嵌套子目录中发现它。

______________________________________________________________________

你得到了什么

______________________________________________________________________

SymDex适合哪里

人工智能代码库工具现在分为几个强大的类别：企业代码搜索、IDE原生助手、LSP支持的代理工具包、仓库映射系统和整个仓库提示打包器。SymDex位于一个更窄但有用的位置：一个本地第一检索层，它结合了精确的符号、文本搜索、可选的语义搜索、查询驱动的上下文包、HTTP路由、调用者、被调用者、文件大纲、仓库大纲、Markdown/围栏代码索引、仓库统计、令牌节省提示、检索质量元数据、CLI访问和MCP访问，而不需要编辑器会话或托管索引。

这使得当代理需要一个可移植的代码库映射时，SymDex最强大，它可以在读取文件之前查询。

当你需要深度类型系统推理或编辑器原生重构时，使用语言服务器。当您需要组织范围内的搜索、权限和代码监控时，请使用企业代码搜索平台。当您想将整个仓库快照交给模型时，使用提示打包器。当您希望AI编码代理在使用令牌读取文件之前询问精确的仓库本地问题时，请使用SymDex。

______________________________________________________________________

CLI参考

# Indexing and maintenance
symdex index ./myproject --repo myproject       # Index with an explicit repo id
symdex index ./myproject                        # Auto-name from git branch + path hash
symdex index ./myproject --repo myproject --no-embed  # Skip semantic embedding work
symdex index ./myproject --repo myproject --lazy      # Index code now, embed in a background watcher
symdex watch ./myproject --repo myproject       # Keep an index fresh without loading embedding models
symdex watch ./myproject --repo myproject --embed  # Also refresh semantic embeddings on change
symdex invalidate --repo myproject              # Force re-index of a repo
symdex invalidate --repo myproject --file app.py
symdex gc                                       # Remove stale index databases
symdex repos                                    # List indexed repos

# Search
symdex search "validate_email" --repo myproject
symdex search "validate_email"                 # Search across all indexed repos
symdex find validate_email --repo myproject     # Exact lookup
symdex text "JWT" --repo myproject
symdex semantic "check auth token" --repo myproject
symdex pack "how auth token refresh works" --repo myproject --budget 6000
symdex pack "document checkout API" --repo myproject --include routes,docs,tests --format json

# Navigation
symdex outline auth/utils.py --repo myproject
symdex callers validate_email --repo myproject
symdex callees validate_email --repo myproject
symdex routes myproject
symdex routes myproject --method POST
symdex routes myproject --path /api

# Server
symdex serve
symdex serve --port 8080

MCP目前公开了其他未作为专用CLI命令显示的repo树和repo统计视图： get_file_tree, get_repo_outline, get_index_status，以及 get_repo_stats.

______________________________________________________________________

MCP工具

SymDex目前公开了21个MCP工具：

______________________________________________________________________

支持的语言

由...驱动 树保姆 用于代码，语言包语法回退，以及用于标题和围栏代码示例的本地Markdown扫描器。

______________________________________________________________________

支持的平台

SymDex适用于任何支持stdio或流式HTTP的MCP客户端。

______________________________________________________________________

语义嵌入后端

基础 symdex 仅安装贫芯。选择与语义搜索工作方式相匹配的嵌入额外内容：

• symdex[local] 用于本地 sentence-transformers
• symdex[voyage] 用于Voyage文本嵌入
• symdex[voyage-multimodal] 适用于Voyage文本、图像和PDF

远程OpenAI兼容和Gemini后端使用Python标准库HTTP客户端，因此它们不添加所需的依赖关系。

本地模式

pip install "symdex[local]"

SYMDEX_EMBED_BACKEND=local \
SYMDEX_EMBED_MODEL=all-MiniLM-L6-v2 \
symdex index . --repo myrepo

航行文本模式

pip install "symdex[voyage]"

SYMDEX_EMBED_BACKEND=voyage \
VOYAGE_API_KEY=... \
SYMDEX_VOYAGE_MODEL=voyage-code-3 \
symdex index . --repo myrepo

SYMDEX_EMBED_BACKEND=voyage \
VOYAGE_API_KEY=... \
symdex semantic "parse source code" --repo myrepo

OpenAI兼容模式

将其用于OpenAI、本地OpenAI兼容服务器和暴露 POST /embeddings.

SYMDEX_EMBED_BACKEND=openai \
SYMDEX_EMBED_BASE_URL=https://api.openai.com/v1 \
SYMDEX_EMBED_MODEL=text-embedding-3-small \
SYMDEX_EMBED_API_KEY=... \
SYMDEX_EMBED_RPM=60 \
symdex index . --repo myrepo --lazy

对于本地或代理提供程序，设置 SYMDEX_EMBED_BACKEND=custom，点 SYMDEX_EMBED_BASE_URL 在其 /v1 基本URL，并设置它所期望的模型名称。如果提供程序不需要API密钥，则忽略 SYMDEX_EMBED_API_KEY.

Gemini模式

Gemini使用 RETRIEVAL_DOCUMENT 当索引和 RETRIEVAL_QUERY 搜索时。

SYMDEX_EMBED_BACKEND=gemini \
GEMINI_API_KEY=... \
SYMDEX_EMBED_MODEL=text-embedding-004 \
SYMDEX_EMBED_RPM=60 \
symdex index . --repo myrepo --lazy

航行多式联运模式

pip install "symdex[voyage-multimodal]"

SYMDEX_EMBED_BACKEND=voyage
SYMDEX_VOYAGE_MULTIMODAL=1
VOYAGE_API_KEY=...
SYMDEX_VOYAGE_MULTIMODAL_MODEL=voyage-multimodal-3.5
symdex index . --repo myrepo

多模式模式允许SymDex将支持的图像、屏幕截图和PDF作为可搜索的资产条目进行索引。

笔记：

• 基础 symdex 保留符号、文本、路由和调用图特征，而无需拉入本地嵌入堆栈。
• 如果 SYMDEX_EMBED_BACKEND 如果未设置，SymDex在以下情况下使用本地后端 symdex[local] 已安装。
• 本地语义搜索需要 symdex[local] 并在首次使用时下载该模型。
• 航行文本模式需要 symdex[voyage].
• 航行多式联运模式需要 symdex[voyage-multimodal].
• OpenAI兼容模式读取 SYMDEX_EMBED_BASE_URL, SYMDEX_EMBED_MODEL，可选 SYMDEX_EMBED_API_KEY 或 OPENAI_API_KEY.
• Gemini模式读取 SYMDEX_EMBED_MODEL, SYMDEX_EMBED_BASE_URL，以及 SYMDEX_EMBED_API_KEY, GEMINI_API_KEY，或 GOOGLE_API_KEY.
• SYMDEX_EMBED_RPM 将请求定步应用于远程后端。当免费层或代理强制执行每分钟请求限制时，请使用它。
• symdex index --lazy 首先执行快速结构索引，然后启动后台 symdex watch --embed 这样嵌入就可以在不阻塞前台命令的情况下填充。
• symdex index --no-embed 完全跳过语义嵌入工作。
• 如果缺少所选的后端额外功能，SymDex会打印一个可操作的安装提示。
• 多模态索引仅在以下情况下处于活动状态 SYMDEX_VOYAGE_MULTIMODAL=1.

______________________________________________________________________

常见问题

什么是SymDex？

SymDex是一个用于AI编码代理的repo本地符号索引引擎。它将项目索引到本地SQLite知识库中，这样代理就可以检索精确的符号、文件大纲、HTTP路由、调用者、被调用者、文本匹配、语义匹配、令牌预算上下文包和仓库摘要，而无需先读取整个文件。

SymDex为AI编码代理解决了什么问题？

SymDex减少了盲目的回购浏览。代理可以向SymDex询问当前任务所需的特定函数、路由处理程序、调用图边缘、Markdown标题或文件大纲，而不是打开宽泛的文件并在方向上花费数千个令牌。

SymDex可以帮助代理查找错误或检查代码逻辑吗？

是的，作为代码理解和证据层。SymDex本身并不能证明错误，也不是一个完整的静态分析器。它通过检索精确的定义、调用者、被调用者、路由、文件大纲、文本匹配、语义匹配、文档锚和查询驱动的上下文包来帮助代理调查逻辑，然后附加高质量的元数据，以便代理在提出索赔之前可以查看证据是否新鲜、解析器支持、生成或缺少嵌入。

SymDex是MCP服务器吗？

对。SymDex包括一个MCP服务器，其中有21个工具，用于索引、符号搜索、语义搜索、文本搜索、上下文包、文件大纲、存储库大纲、路由搜索、调用图遍历、存储库统计、缓存失效和过时索引清理。它还为同一仓库本地检索工作流提供CLI命令。

哪些AI编码代理可以使用SymDex？

任何支持stdio或流式HTTP的MCP客户端都可以使用SymDex。典型的设置包括Codex CLI、Gemini CLI、Cursor、Windsurf、GitHub Copilot、Roo、Continue.dev、Cline、Kilo Code、Zed、OpenCode和其他MCP兼容客户端。

SymDex与grep、ripgrep、嵌入或LSP有何不同？

SymDex将精确的结构搜索与可选的语义搜索和令牌预算上下文包相结合。Grep和ripgrep查找文本；语言服务器提供编辑器本机类型的导航；只嵌入系统可以找到近似意义；整个repo打包器会产生大量的提示工件。SymDex为代理提供了一个预先索引的本地映射，在一个工作流中包含符号、字节偏移、路由、调用图、文本搜索、语义搜索、质量元数据、上下文包和MCP工具。

SymDex会取代语言服务器吗？

不。SymDex不是一个完整的类型检查器或自动重构引擎。当编辑器本机类型推理或重构很重要时，使用语言服务器。当代理需要快速的仓库本地检索、路由发现、代码大纲、语义搜索、上下文包和跨一个或多个仓库的低令牌导航时，请使用SymDex。

SymDex索引哪些语言和文件？

SymDex目前涵盖了21种语言：Python、JavaScript、TypeScript、Go、Rust、Java、Kotlin、Dart、Swift、PHP、C#、C、C++、HTML、CSS家族样式表、Shell、Elixir、Ruby、Vue脚本块、Svelte脚本块和Markdown。Markdown支持包括 .md, .markdown，以及 .mdx 标题加上支持的围栏代码块。

SymDex可以提取HTTP路由吗？

对。SymDex提取跨Python、JavaScript/TypeScript、Spring/Kotlin、Laravel、Gin-style Go、ASP的HTTP路由。NET、Rails/Sinatra、Phoenix和Actix。代理可以直接查询路由，而不是手动扫描路由器、装饰器、控制器或框架入口点。

SymDex是否帮助文档、SEO或生成引擎优化团队？

是的，当技术内容依赖于代码库时。文档、SEO和生成引擎优化（GEO）团队可以使用SymDex-powered代理构建源代码支持的上下文包，查找SDK示例、API路由、Markdown标题、功能实现和源代码支持答案，然后再更新开发人员文档、变更日志、比较页面或AI搜索友好的技术内容。SymDex是一个代码检索层，而不是关键字研究或排名跟踪工具。

语义搜索需要互联网吗？

不，默认情况下不是。安装 symdex[local] 用于本地 sentence-transformers 语义搜索；模型下载一次，然后脱机运行。Voyage、OpenAI兼容和Gemini嵌入模式需要网络访问，除非配置的基本URL指向本地服务器或私有代理。

SymDex可以在没有语义嵌入的情况下运行吗？

对。 pip install symdex 保持核心符号、文本、路由、文件大纲、仓库大纲、调用图和MCP功能的精简。使用 symdex index --no-embed 完全跳过嵌入工作，或稍后添加嵌入 symdex[local]、Voyage、OpenAI兼容、Gemini、， symdex index --lazy，或 symdex watch --embed.

为什么 symdex semantic 假设一个repo没有语义嵌入？

该仓库在没有嵌入后端的情况下进行了索引，并使用 --no-embed，或通过默认的低内存监视模式保持新鲜。启用所需的后端，然后运行 symdex index, symdex index --lazy，或 symdex watch --embed 因此，语义向量被写入索引中。

意志 symdex watch 在内存中保留一个大的嵌入模型？

不，默认情况下不是。 symdex watch 刷新结构索引而不加载本地嵌入模型，除非 --embed 已通过。监视模式还拒绝同一repo/root的重复监视程序，可以在空闲时间后自动退出，并将监视程序元数据存储在活动状态目录中。

SymDex索引存储在哪里？

默认情况下，每个仓库都有自己的SQLite数据库 ~/.symdex，以及一个中央注册数据库。集 SYMDEX_STATE_DIR=.symdex 或使用 symdex --state-dir .symdex ... 为了保持仓库数据库， registry.db, registry.json，以及当前工作区内的观察者元数据。

SymDex可以跨多个仓库和工作树工作吗？

对。SymDex维护一个索引仓库的注册表，支持显式 --repo 名称，并且可以在以下情况下从当前分支和工作树路径自动生成稳定的仓库id --repo 省略。使用 symdex repos 列出索引和 symdex gc 在删除工作树后清理过时的条目。

SymDex如何报告代币节省？

成功的CLI搜索命令会打印一行ROI页脚，其中包含大约节省的令牌。MCP搜索工具返回结构化 roi, roi_summary，以及 roi_agent_hint 字段，以便代理可以在面向用户的响应中提及检索节省。

什么是SymDex检索质量信号？

MCP结果和CLI JSON输出包括 quality 具有以下字段的对象 confidence, confidence_reason, index_fresh, last_indexed, parser_mode, language_surface, is_generated, has_embeddings，以及 route_confidence。代理可以使用这些字段来避免过度信任过时的索引、回退文本匹配、生成的文件或来自存储库的语义搜索，而无需嵌入。

索引打印什么？

索引后，SymDex会打印一个代码摘要，其中包含文件计数、代码行数、符号计数、路由计数、跳过的文件、错误和语言细分。这有助于团队在依赖搜索结果之前确认索引内容。

可以排除生成的文件吗？

对。添加a .symdexignore 使用gitignore样式模式在repo根目录下创建文件。默认情况下，SymDex还会跳过常见的生成、依赖和构建路径。

为什么有些日志说 index_folder 或 list_repos 而CLI文档说 index 和 repos?

index_folder 和 list_repos 是MCP工具名称。规范的shell命令是 symdex index 和 symdex repos，以及兼容性别名，例如 symdex index-folder 和 symdex list-repos 也被接受。

现有用户是否收到更新通知？

对。交互式CLI命令可以打印简短的升级通知，其中包含以下确切命令 pip, uv tool，以及 uvxJSON输出保持安静，因此结构化消费者不会被破坏。

SymDex可以在没有AI代理的情况下使用吗？

对。所有核心搜索和导航功能都可以通过CLI使用，包括符号搜索、精确查找、文本搜索、语义搜索、上下文包、路由搜索、调用者、被调用者、大纲、仓库列表和过时索引清理。

______________________________________________________________________

贡献

欢迎发布问题和PR .

如果SymDex为你保存了代币，那么一颗星星会帮助其他人找到它。