dsh-semble

dsh plugin --profile web add dsh-semble

<p align="center">

<img src="https://raw.githubusercontent.com/CodeIntegrity/dsh-semble/main/dsh-semble.png" alt="dsh-semble" width="760">

</p>

<h1 align="center">dsh-semble</h1>

<p align="center">

<a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>

<a href="https://dsh-plugin.org/plugins/codeintegrity/dsh-semble"><img src="https://dsh-plugin.org/badges/listed.svg" alt="Listed on dsh-plugin.org"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="许可证：MIT"></a>

<a href="https://www.npmjs.com/package/dsh-semble"><img src="https://img.shields.io/npm/v/dsh-semble.svg?style=flat-square" alt="npm 版本"></a>

<a href="https://github.com/CodeIntegrity/dsh-semble/actions/workflows/ci.yml"><img src="https://github.com/CodeIntegrity/dsh-semble/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI 状态"></a>

<a href="https://github.com/CodeIntegrity/dsh-semble/stargazers"><img src="https://img.shields.io/github/stars/CodeIntegrity/dsh-semble.svg?style=flat-square" alt="GitHub stars"></a>

<a href="https://github.com/CodeIntegrity/dsh-semble/commits/main"><img src="https://img.shields.io/github/last-commit/CodeIntegrity/dsh-semble.svg?style=flat-square" alt="最近提交"></a>

<a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/topic-dsh--plugin-0e7490.svg?style=flat-square" alt="topic: dsh-plugin"></a>

<a href="#平台差异"><img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue.svg?style=flat-square" alt="平台：Windows / macOS / Linux"></a>

<a href="https://github.com/CodeIntegrity/dsh-semble/blob/main/package.json"><img src="https://img.shields.io/badge/node-%E2%89%A522-43853d.svg?style=flat-square&logo=node.js&logoColor=white" alt="node: >=22"></a>

<a href="#兼容性"><img src="https://img.shields.io/badge/dsh-%E2%89%A50.2.1--rc.2-4B32C3.svg?style=flat-square" alt="dsh: >=0.2.1-rc.2"></a>

</p>

<p align="center"><a href="README.md">English</a> | 简体中文</p>

dsh-semble 把 Semble ——一个专为 agent 打造的代码检索引擎

——接进 DSH 会话，以两个原生工具的形式出现：semble_search 与 semble_find_related。从 3.0.0 起

不再经过 MCP 层：插件直接向宿主工具注册表注册，每次调用经 uvx 拉起 Semble CLI。grep 要求你手里已经

有了一个字符串；它要的是一句行为描述——「请求失败时重试策略在哪生效」「哪个模块决定了打分权重」。

而这种时刻，agent 通常正好开始猜文件名。而且它只返回命中的片段而不是整个文件，单次检索的 token

开销远低于「先 grep 再整读文件」的路径——按上游 benchmark，比 grep+read 平均省约 99% 的 token，

检索质量与代码专用的 transformer 检索模型持平。

怎么实现的。 Semble 先用 tree-sitter 把每个文件切成代码感知的分块，检索时叠加两套互补信号：

静态 Model2Vec 嵌入（代码专用模型 potion-code-16M-v2）负责语义相似度，BM25 负责标识符与 API 名

的词法命中；两份结果用 Reciprocal Rank Fusion（RRF）融合，再按代码感知的规则重排——定义了查询符号

的分块排在只提到它的前面，查询词在分块内以标识符词干出现（parse config → parseConfig /

config_parser）会被加分，同一文件多个分块命中会提升整个文件，而测试文件、示例与兼容垫片被降权，

让正式的实现先冒出来。嵌入模型是静态的，查询时没有 transformer 前向计算，所以给普通仓库建索引

不到一秒、每次查询只需毫秒，全程 CPU，不需要 API key、GPU 或外部服务。索引首次使用时写入磁盘缓存，

之后随文件改动增量刷新；https:// 仓库按需 clone 进同一份缓存。

开始前须知。 本插件运行时依赖 PATH 上的 uvx；首次调用需要联网——它会从 PyPI 安装

semble[mcp]，再从 huggingface.co 下载 potion-code-16M-v2 模型，之后索引与查询都在本地完成。

无法访问 huggingface.co 的内网环境，请先把 HF_ENDPOINT 指向可用的镜像站。

你会得到什么

工具 · 交给它 · 拿回来

semble_search · 一句话描述代码做什么、或者它在哪儿 · 按相关度排序的 file:line 命中 + 片段

semble_find_related · 一个你已经知道的位置 · 它的邻居：其他实现、调用方、测试

另外还注册了一个 slash command：/semble savings、/semble file-types、/semble version 和

/semble clear <index|savings|orphans|all>，用来跑

工具没有暴露的 CLI 报表，见[命令](#命令)。

一次典型对话：

你： DSH 判断「插件已加载」是在哪儿决定的？

agent： 调 semble_search，拿到插件清单模块的一条命中，用 read 打开，找到 isEntryLoaded

把 loader 条目名和包名做比对，然后基于源码回答，而不是基于猜测。

工具怎么用

• repo —— 必填。仓库绝对路径，或 https:// git 地址；传数组可同时检索多个仓库。
• top_k —— 默认 5，首轮没命中时提到 10–20。
• max_snippet_lines —— 默认 10，0 只返回位置。
• content —— code（默认）、docs、config、all。

某个仓库的首次查询要建索引（慢，一次性），之后复用。命中按相似度排序；检索分数是排名融合值，

即使命中的正是相关代码也只有 0.0x 量级——把它当相对排序看，不要当绝对置信度。空结果才是

「没检索到相关内容」的信号。

安装

桌面端

设置 → 插件 → 安装，粘贴：

dsh-semble

钉住版本写 dsh-semble@3.0.0。desktop profile 只支持从设置页安装——CLI 会拒绝，

因为这个 profile 的 node_modules 与 lockfile 由 Electron 应用独占。

命令行

dsh plugin --profile web add dsh-semble

该子命令在 profile 目录里跑 pnpm add，随后 reconcile dsh.profile.bundles，所以下次启动即挂载。

没有构建步骤，pnpm 不需要 allowBuilds 例外。

从源码安装

要跟 main、装某个 fork 或装还没发版的提交，走仓库安装：

dsh plugin --profile web add github:CodeIntegrity/dsh-semble

支持 github:owner/repo、git+https://…、https://github.com/owner/repo 和 .tgz 链接；

这些需要 PATH 上有 git。

本地目录

dsh plugin --profile web add link:/绝对路径/dsh-semble   # macOS / Linux
dsh plugin --profile web add link:D:\path\to\dsh-semble  # Windows

之后 profile 指向你的工作副本，改完 cordis.patch.yml 下次启动即生效，无需重装。

前置条件

PATH 上要有 uv——uvx 负责从 PyPI 拉起 Semble：

winget install astral-sh.uv                      # Windows

brew install uv                                  # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS / Linux

首次启动会下载包与嵌入模型（约 1–2 分钟，一次性，之后离线可用）。装完重启一次 DSH；在那之前设置页那行

可能显示「待重启」。

设置

在 设置 → 插件 里编辑本插件的行（loader 行的 config，由插件在每次调用时读取）：

字段 · 默认值 · 什么时候改

command · uvx · 如果只装了 .cmd 包装，改指向 uvx.exe

args · --from 'semble[mcp]' semble · 追加 --content all 让文档和配置也进索引

args（版本） · 浮动 · 改成 semble[mcp]==X.Y.Z 钉版本

toolTimeoutMs · 300000 · 首次调用要建索引并下载模型；想更快失败就调小

env · 空 · 受限网络加 HF_ENDPOINT；搬索引加 SEMBLE_CACHE_LOCATION

改设置会重新应用插件（重注册两个工具）；磁盘上的索引缓存不受影响。

调优

Semble 从运行它的进程的环境变量读配置。检索工具的环境变量写在插件 config 的 env 里；

/semble 是另起进程、继承宿主环境，所以要让报表和检索看到同一份配置时，两处都要设——真正会出问题的

只有 SEMBLE_CACHE_LOCATION。

变量 · 默认值 · 作用

SEMBLE_INDEX_WORKERS · 4 · 首次建索引时切块用的工作进程数；0 表示在主进程里做。多核机器可调大，不想让后台检索吃满 CPU 就调小

SEMBLE_MCP_IDLE_TIMEOUT · 0（永不过期） · MCP server 模式下空闲索引在内存缓存里保留多少秒；CLI 每调用即退出，此变量对它无效

SEMBLE_MODEL_NAME · minishlab/potion-code-16M-v2 · 换一个 Model2Ve

…(truncated)