Semble 代码搜索
为编程智能体快速定位相关代码片段，减少上下文消耗。
项目说明检索在本机 CPU 上运行，无需 API 密钥或外部推理服务，并清楚披露首次模型下载、远程仓库克隆、索引与节省统计缓存、安装器对代理配置的修改以及清理位置。交互式安装允许用户选择集成，非交互模式必须显式使用 --yes；卸载和分项清缓存提供了充分的恢复路径。MIT 文件、项目作者及引用信息使来源归属明确。扣分点是没有专门说明密钥、私有源码或其他敏感文件的处理策略；.gitignore/.sembleignore 只能提供间接保护。多数运行时依赖仅设下限且未提供锁文件或漏洞审计证据，发布工作流中的部分第三方 Action 也只按标签固定。远程克隆、模型下载及配置写入虽有披露，但缺少更细的网络目标、保存周期和安装改动清单。
README、包元数据、CI 配置和所示 BM25 测试形成基本一致的实现叙述；测试覆盖公式、空查询、删除状态、持久化往返以及损坏状态拒绝。CI 声明跨三种操作系统和多个 Python 版本运行，依赖也集中列出。扣分点是静态材料不能证明完整搜索链路或安装器的可靠性；“零设置”与需要安装 uv、首次联网下载模型之间存在轻微表述张力。模型和依赖的可用性仍受 PyPI、Hugging Face及网络影响。失败消息证据主要限于 BM25 的 ValueError 测试，未展示下载、克隆、权限、配置写入或 MCP 故障的用户提示。
材料清楚覆盖代理用户、CLI 脚本、MCP、Python 库、子代理、本地及远程仓库等场景，并提供代码、文档、配置和全内容模式、结果数量与片段长度控制以及自定义模型入口，因此受众与环境适配较强。Python 3.10–3.14 和 Linux、macOS、Windows 的 CI 矩阵进一步支持环境适配。扣分点是能力边界未系统说明，例如二进制文件、超大仓库、子模块、离线首次使用和不支持语言的行为。MCP 工具参数较明确，但实际 AGENTS.md 指令、子代理触发规则和安装文档未包含在证据中，无法确认触发精度及避免无关调用的机制。
README 结构清晰，包含快速开始、CLI、MCP、存储、库接口、原理、基准、更新和许可；命令、包名、入口点及环境变量命名一致。示例覆盖主要操作和返回字段，MIT 许可正文与元数据一致，满足完整许可要求。扣分点是详细安装页未提供，FAQ 也不完整；已知限制没有独立、系统的说明。版本由 setuptools_scm 动态管理，并提供版本查看与升级路径，但没有所示变更日志、兼容性政策或迁移说明。作者、问题跟踪地址和发布工作流提供维护入口，但未说明支持承诺、负责人分工或安全报告渠道；发布者身份仍是未知而非可疑。
输出设计直接面向代理消费，能够返回文件路径、行范围和精确代码片段，并允许控制 top-k、内容类型和最大片段行数；find_related 和自然语言混合检索相对于单纯 grep 具有明确的增量价值。文档还说明 BM25、静态嵌入、RRF 与代码感知重排如何产生结果。扣分点是约 99% token 节省、毫秒级速度和质量对齐等收益主要来自 README 的项目方基准陈述，所给材料没有基准数据或方法文件可供逐项核查。首次模型下载、磁盘缓存、索引开销和远程克隆也意味着成本并非完全为零。
主要性能数字指向基准章节和外部方法说明，节省统计的计算公式也被明确给出；BM25 测试为若干底层行为提供了可追踪证据。扣分点是本次材料没有包含 benchmarks/README.md、原始结果、完整测试清单或覆盖率报告，无法从供应文件复核 99%、220 倍、17 倍、NDCG@10 0.854 等核心主张。跨来源印证较弱：README 和 pyproject 主要是同一发布方陈述，所示测试仅验证 BM25 的局部性质。文档通常区分实现说明、估算公式和基准结果，但部分营销措辞将项目方测量概括为普遍效果，未充分陈述适用条件与不确定性。
- 首次使用会从 Hugging Face 下载模型；离线或受限网络环境应预先提供兼容的本地模型并设置 SEMBLE_MODEL_NAME。
- 索引可能包含私有源码或凭据。使用前应配置 .gitignore/.sembleignore，并核查缓存目录的访问权限、保留策略及清理流程。
- 不要把约 99% token 节省、220 倍索引速度、17 倍查询速度或 NDCG@10 0.854 视为已独立验证；本次证据未包含原始基准材料。
- semble install 会修改代理集成配置；建议先审查安装选择及目标文件，并保留配置备份，尽管项目提供 semble uninstall。
- 依赖未由所示锁文件完全固定；部署方应自行锁定版本、生成软件物料清单并执行漏洞扫描。
这个 Agent 能做什么，适合哪些场景？
Semble 是面向编程智能体的本地代码搜索库，也提供 CLI、Python API、MCP 服务器和专用搜索子智能体等接入方式。它读取本地目录或按需克隆远程 Git 仓库，通过 tree-sitter 将文件切成代码感知片段，再结合 Model2Vec 静态嵌入、BM25 和倒数排名融合进行检索。查询可以使用自然语言或代码，输出相关文件路径、行号范围和代码片段，而不是整份文件。索引和查询在 CPU 上运行，无需 API 密钥、GPU或外部推理服务；首次使用仍需从 Hugging Face 下载嵌入模型，除非配置本地兼容模型。项目宣称在其约 1,250 个查询、63 个仓库和19种语言的基准中达到 0.854 NDCG@10，并比 grep+read 平均少用约 99% 的令牌。
SembleIndex.from_path() 读取本地代码库，SembleIndex.from_git() 获取远程 Git 仓库；content 可限定为 code、docs、config 或它们的组合。系统用 tree-sitter 分块，以 potion-code-16M-v2 的 Model2Vec 静态嵌入计算语义相似度，同时用 BM25 匹配标识符和 API 名称，再通过 Reciprocal Rank Fusion 合并分数。融合后的结果还会应用查询自适应权重、定义提升、标识符词干匹配、文件一致性提升，以及对测试、兼容层、旧代码、示例和 .d.ts 声明的降权。search 返回匹配片段及其 file_path、start_line、end_line 和 content；find_related 根据文件与行号寻找相似代码。索引首次构建后写入缓存，后续通过文件修改时间增量更新；CLI 的 savings 命令还会估算并汇总相对于读取完整匹配文件所节省的令牌。
- 使用 Codex、Claude Code、Cursor 或其他 MCP 客户端的开发者，希望智能体用自然语言问题直接找到实现位置，而不必反复 grep 并读取完整文件。
- 维护大型或陌生代码库的工程师，需要查询认证流程、模型持久化等概念，并获得带路径和行号的短代码片段。
- 编写自动化开发脚本的团队，需要通过 semble search 在没有 MCP 会话的环境中搜索本地或远程仓库。
- 构建自定义 Python 开发工具的作者，希望使用 SembleIndex API 搜索代码、文档和配置，并继续检索与已知位置相似的实现。
- 网络受限或不允许调用外部推理 API 的团队，可预先准备兼容的本地 Model2Vec 模型，在 CPU 上完成索引和查询。
这个 Agent 有哪些优点和局限？
- 同一核心能力同时提供 CLI、Python API、MCP 服务器和专用子智能体，便于接入不同编程工作流。
- 混合使用 Model2Vec 语义嵌入和 BM25 标识符匹配，并加入定义提升与代码噪声降权，兼顾概念查询和精确符号查询。
- 索引与查询均在 CPU 本地执行，无需 API 密钥、GPU或外部推理服务。
- 索引会缓存并按文件变化增量刷新，本地 MCP 会话不必每次完整重建。
- 项目基准报告平均仓库约 500 毫秒完成索引、查询约 1 毫秒，并宣称相对 grep+read 平均减少约 99% 的令牌。
- 默认配置首次使用必须联网从 Hugging Face 下载模型；完全离线部署需要提前准备 Model2Vec 兼容模型并设置 SEMBLE_MODEL_NAME。
- 安装流程依赖 uv，MCP、指令文件和子智能体等集成还需要在各编程客户端中完成配置。
- 搜索结果依赖分块、混合排序和降权规则；测试、示例、legacy/compat 路径或 .d.ts 文件可能被排在较后位置，即使它们对某次调查很重要。
- README 中的速度、质量和令牌节省数字来自项目自己的基准与估算方法，未提供独立生产环境验证。
- 缓存索引、统计数据和 Hugging Face 模型会占用本地磁盘；远程仓库搜索还需要网络并会按需克隆仓库。
如何安装或部署这个 Agent？
运行环境需要 shell 和 uv。安装并启动交互式集成配置：
uv tool install semble
semble install安装器会检测 Codex、Claude Code、OpenCode 等已安装的编程智能体，并允许选择 MCP、写入 AGENTS.md/CLAUDE.md 的 CLI 指引或 semble-search 子智能体。无人值守示例：
semble install --agent codex --type mcp subagent --yes首次使用默认模型时需要网络，以便从 Hugging Face 下载并缓存嵌入模型；也可以将 SEMBLE_MODEL_NAME 设置为本地的 Model2Vec 兼容模型路径。卸载集成使用 semble uninstall。
如何使用这个 Agent？
搜索本地仓库：
semble search "authentication flow" ./my-project搜索远程仓库：
semble search "save model to disk" https://github.com/MinishLab/model2vec限制结果或调整内容范围：
semble search "save model to disk" ./my-project --top-k 10
semble search "deployment guide" ./my-project --content docs
semble search "authentication flow" ./my-project --max-snippet-lines 10寻找与已知代码位置相似的片段：
semble find-related src/auth.py 42 ./my-project作为 Python 库使用时，可通过 SembleIndex.from_path("./my-project") 建立索引，再调用 index.search("save model to disk", top_k=3)；结果提供文件路径、起止行号和片段正文。MCP 客户端可调用 search 和 find_related，并将 repo 指定为本地路径或 HTTPS Git URL。
这个 Agent 与同类方案有什么区别？
与 grep+read 相比，Semble 返回选定片段而非读取完整匹配文件；项目基准声称其平均少用约 99% 的令牌，在约 2,000 令牌时达到 97% 召回率，而 grep+read 在 100,000 令牌上下文中达到 85%。与 1.37 亿参数的 CodeRankEmbed 相比，项目报告 Semble 的检索质量相当，但索引快约 220 倍、查询快约 17 倍。这些数字均来自项目描述的内部基准。