代码智能体MCP 服务搜索引擎人工智能【免费下载链接】sembleFast and Accurate Code Search for Agents. Uses 99% fewer tokens than grepread项目地址https://gitcode.com/gh_mirrors/se/semble点击查看免费下载本指南以仓库中为 Qwen Code 准备的子代理配置文档 qwen.md 为核心完整讲解如何让 Qwen Code 通过semble search按语义意图或符号名检索代码、按--content过滤代码/文档/配置、用find-related挖掘相关实现并跨多个仓库一次性搜索。读完本文你将掌握 Qwen Code 子代理中这套命令的每一个参数与底层行为并理解其索引缓存、混合检索与重排原理。为什么让 Qwen Code 用 semble 而非 grep在探索陌生代码库时Agent 的传统做法是grep加全文read_file先猜测关键字再整文件读入上下文。semble 的思路相反——它把每个文件按代码结构切分成语义块chunk查询时只返回命中的小块及其精确行号Agent 直接跳到对应位置即可不必重复搜索或整文件阅读。从源码看这一目标的实现方式是双路混合检索semble.search.search()同时跑语义检索基于 Model2Vec 静态嵌入模型与 BM25 词法检索再用 Reciprocal Rank FusionRRF融合两份分数见 search.py。README 报告其相较 grepread 可节省约 99% 的 token 用量且整个检索过程在 CPU 上毫秒级完成。对 Qwen Code 这类需要频繁找实现、找调用方、理解机制的编码 Agent 而言这是比 grep 更省 token、更快、更精准的探索手段。事实边界说明上述 ~99% token 节省、约 500ms 建索引、NDCG10 0.854 等数据均出自 README.md 的官方说明与 benchmarks 基准本文不作引申。子代理配置frontmatter 逐字段解读qwen.md 是安装器写给 Qwen Code 的专用子代理文件其目标位置为~/.qwen/agents/semble-search.md对应关系见 docs/installation.md 中的表格。文件开头有一段 YAML frontmatter逐字段拆解如下--- name: semble-search description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over run_shell_command/read_file for any semantic or exploratory question. tools: - run_shell_command - read_file ---name: semble-search子代理标识Qwen Code 会在需要代码探索时调用它。description触发条件与能力边界。注意它明确写着Prefer over run_shell_command/read_file for any semantic or exploratory question——即凡属按意图找代码、定位实现、理解机制、发现相关代码这类语义性或探索性问题都应优先交给该子代理而不是直接跑 shell 命令或读文件。tools该子代理可用的工具集。run_shell_command用于执行sembleCLIread_file用于跳转到搜索结果指向的文件位置精读。从 installer/agents.py 可以看到 Qwen Code 的安装目标定义MCP 配置写入~/.qwen/settings.json的mcpServers指令写入~/.qwen/QWEN.md子代理即本文件。也就是说这套配置既可以通过 CLI 子代理方式使用也可以作为 MCP 工具mcp__semble__search/mcp__semble__find_related被直接调用。基础用法semble search的三个典型姿势文档给出的三条核心命令如下它们对应检索的三个常见诉求semble search authentication flow ./my-project --max-snippet-lines 10 # first 10 lines only, concise semble search save_pretrained ./my-project # full chunk content semble search save model to disk ./my-project --top-k 10 # more results第一条用自然语言描述功能意图authentication flow并用--max-snippet-lines 10只取每个结果的前 10 行——正好覆盖函数/类签名加少量函数体足以确认位置又不浪费上下文。第二条直接按符号/标识符save_pretrained检索不带--max-snippet-lines时返回完整 chunk 内容。符号名查询会走符号偏向的排名逻辑见下文自适应加权。第三条--top-k 10增加返回结果数适合需要全面盘点候选实现如接口的所有实现的场景。从 cli.py 可以看到这些参数的默认值path默认[.]当前目录、--top-k默认 5、--max-snippet-lines默认None完整 chunk、--format默认json。--max-snippet-lines 0则只输出文件路径与行号区间、不带任何代码内容适合只要定位不要正文的场合。输出为 JSON 时每个结果包含file_path、start_line、end_line、score以及除非设为 0content字段字段拼装逻辑见 utils.py。文档随后强调Results are cached automatically on first run and invalidated when files change. 这与 cache.py 的实现一致首次检索会构建索引并缓存到系统缓存目录macOS 为~/Library/Caches/semble/、Linux 为~/.cache/semble/可用SEMBLE_CACHE_LOCATION覆盖后续运行通过get_validated_cache()比对文件的mtime_ns清单文件有增删改时缓存失效再次构建时则通过load_previous_for_incremental()复用旧索引只对变化文件做增量重索引见 cache.py而非全量重建。内容类型过滤--content docs / config / all默认只检索代码但当目标内容在文档或配置文件里时就需要显式切换semble search deployment guide ./my-project --content docs semble search database host port ./my-project --content config semble search authentication ./my-project --content all--content docs检索文档与散文markdown、rst 等。--content config检索配置文件yaml、toml 等。--content all同时检索代码、文档与配置。底层由ContentType枚举code/docs/config驱动见 types.py。CLI 层面--content可接受空格分隔的多个值如--content code docs默认code具体解析见 cli.py。不同的内容选择会生成不同的索引变体并分开缓存——cache.py 中缓存目录名会带上内容作用域后缀如index-docs-configMCP 模式下同样按内容选择分别缓存。另有已被弃用的--include-text-files等价于--content all新代码请直接使用--content。相关代码发现semble find-related当一条搜索结果看起来有希望时可把它的file_path和line来自结果中的start_line/end_line区间交给find-related寻找与该位置代码语义相似的其他 chunksemble find-related src/auth.py 42 ./my-project其用途包括找某个接口的全部实现、某函数的全部调用点、某类的全部测试。实现上find-related先用resolve_chunk()把(file_path, line)还原为索引中的 chunk见 utils.py再以该 chunk 的内容作为查询向量在语义索引中检索最相似的 chunk并自动排除种子自身、限定同语言范围见 index/index.py。注意line是 1 起始的行号若该行不在任何已索引 chunk 内命令会报 No chunk found at ... 并退出见 cli.py。多仓库联合搜索把依赖项目一起索引path省略时默认为当前目录同时接受 git URL。当本项目调用了兄弟仓库里定义的服务时可以把多个路径或 URL 一次传给semble search让它们作为一个整体语料被检索semble search invoice endpoint ./service-a ../service-b此时每个索引各自构建、在查询时合并SembleIndex.merge见 index/index.py返回结果的file_path会带上仓库名前缀如service-b/api/invoices.py输出里附带一张repos映射表把前缀对应回原始路径或 URL把带前缀的路径回传给find-related即可从已知位置跨所有仓库继续挖掘相关代码。若path是 git URL以https://、http://、ssh://等开头判定见 utils.pysemble 会按需浅克隆--depth 1默认 60 秒超时可用SEMBLE_CLONE_TIMEOUT调整到临时目录完成索引见 index/index.py。未加入 PATH 时的回退uvx如果semble不在$PATH上用 uvx 按需拉起并附带 MCP 依赖即可所有命令参数保持一致uvx --from semble[mcp] semble search authentication flow ./my-project安装器写入的 MCP 配置与子代理指令同样使用uvx --from semble[mcp]X.Y.Z形式固定版本见 installer/agents.py保证 Agent 调用的是安装时所写指令对应的版本。推荐工作流六步探索法文档末尾给出了 Qwen Code 子代理应该遵循的完整工作流逐条展开如下先用semble search定位相关 chunk。索引首次自动构建并缓存无需手动准备。按内容类型切换检索范围文档用--content docs配置文件用--content config全部内容用--content all。直接跳到返回的文件与行号。不要对同一内容再次搜索或 grep——这正是 token 节省的关键来源。可选用find-related顺藤摸瓜。以某条有希望结果的file_path与line为种子发现相关实现。答案可能在被依赖项目或兄弟仓库时把相关仓库路径一次性传给同一次semble search跨仓库联合检索。仅在确需整仓字面匹配时用 grep。例如重命名函数后要找出全部调用点这类精确字面量全量枚举需求才回归 grep。这套流程的核心理念与 installer/agents.py 中写入的SEMBLE_START/SEMBLE_END指令完全一致搜索返回文件与行号后直接导航精读绝不为同一内容重复 grep。底层原理补充缓存、混合检索与代码感知重排三个值得展开的实现细节帮助你判断命令参数的真实影响1索引缓存与自动失效。semble search每次运行先经 cache.py 的校验路径命中且model_path、content类型、chunk 大小、缓存格式版本都匹配的缓存直接加载本地目录还会逐文件比对mtime_ns任何文件变化都会触发增量重索引而非全量重建。所以文档所说的首次自动缓存、文件变化自动失效并非夸大而是由文件清单比对机制保证的。2混合检索的融合与权重。search.py 中语义与 BM25 两路各取top_k * 5的候选分数分别转为 RRF 分数1/(krank)k60后按alpha加权合并。alpha默认不固定符号型查询如Foo::bar、_private、getUserById自动偏向 BM25alpha0.3自然语言查询则语义与词法均衡alpha0.5判定逻辑见 ranking/boosting.py。这也解释了为什么save_pretrained这种符号查询与save model to disk这种自然语言查询会有不同表现。3代码感知重排rerank。合并分数后若索引包含代码内容还会应用四类信号见 ranking/boosting.py 与 ranking/penalties.py定义符号的 chunk 获得最高约 3 倍的加成NL 查询中嵌入的 camelCase 符号按半强度加成同一文件多个 chunk 命中时提升文件级分数测试文件、compat/、legacy/、示例目录、.d.ts声明桩等按路径模式降权强降权系数 0.3、.d.ts为 0.7同文件多 chunk 还会触发饱和衰减避免结果被单个文件刷屏。检索词与文件名的词干匹配如查parse config能命中parseConfig、ConfigParser、config_parser则由 tokens.py 的 camelCase/snake_case 拆分逻辑支撑。这些行为均有对应测试覆盖例如 tests/test_search.py 验证了 BM25 的选择器过滤、混合检索的跨文件去重、以及默认与自定义模型的加载路径tests/test_ranking.py 则覆盖符号查询加权与路径惩罚逻辑。安装与更多参考资料安装执行uv tool install semble后运行semble install交互式选择 MCP / 指令AGENTS.md/ 子代理三种集成Qwen Code 的子代理文件即本文讲解的 qwen.md完整安装说明见 docs/installation.md。沙箱环境可无人值守安装semble install --agent qwen --type mcp subagent --yes。常用维护命令semble clear index清索引缓存、semble clear savings清 token 节省统计、semble savings查看累计节省检索结果默认 JSON 输出--format text可切换为人类可读格式。若想在 Python 中以库方式调用同样的检索能力SembleIndex.from_path/from_git/merge/search/find_related可参考 index/index.py 与 README.md 的 Library usage 一节SEMBLE_MODEL_NAME环境变量可切换为本地路径或 Hugging Face 仓库中任意 Model2Vec 兼容模型。把以上命令与工作流写进 Qwen Code 的指令后Agent 探索任何代码库的方式将从猜测关键字 整文件读取升级为语义定位 精确跳转这正是该子代理存在的意义。赞分享代码智能体MCP 服务搜索引擎人工智能【免费下载链接】sembleFast and Accurate Code Search for Agents. Uses 99% fewer tokens than grepread项目地址https://gitcode.com/gh_mirrors/se/semble点击查看免费下载相关推荐如何用一句自然语言精准定位代码gortex 语义搜索实战指南如何用一句自然语言精准定位代码gortex 语义搜索实战指南 gortex 是一款面向 AI 编程代理与 IDE 的高性能代码智能引擎支持 257 种语言、mac-setup 指南用 ack 取代 grep 的 macOS 代码搜索实战mac setup 指南用 ack 取代 grep 的 macOS 代码搜索实战 ack 是一款专为程序员设计的代码搜索工具定位为 grep 的高效替代品文档教程开发工具Onyx生态系统概览包管理、文档生成与第三方库推荐Onyx生态系统概览包管理、文档生成与第三方库推荐 Onyx作为一款现代化的编译器和开发者工具链其生态系统围绕包管理、文档生成和丰富的标准库构建为开发者提上一篇Spring项目快速启动终极指南5分钟完成项目初始化下一篇终极指南掌握Antares SQL客户端的10个高效数据库管理技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考