前言¶
DeepSeek Harness（DSH）插件生态采用「一切皆插件」的架构，智能体在会话中通过注册的工具访问外部能力。现有的 grep 等工具需要已知字符串才能检索，而智能体在代码库中往往只有行为描述，例如「哪里处理请求失败时的重试策略」或「哪个模块决定评分权重」。这种时候，智能体通常开始猜测文件名，检索效率低且容易偏离目标。
dsh-semble 将 Semble 引入 DSH 会话，以两个原生工具提供语义代码搜索：semble_search 与 semble_find_related。插件从 3.0.0 版本起不再依赖 MCP 层，直接将工具注册到宿主的工具注册表，每次调用通过 uvx 启动 Semble CLI。检索时返回匹配片段而非整文件，一次查询的 token 数量约为 grep+read 的 1%，上游基准测试显示检索质量与专用 transformer 检索器相当。
核心能力¶
插件提供两个工具与一个斜杠命令：
semble_search：输入对代码行为的描述或位置说明，返回按相似度排序的file:line位置与代码片段。semble_find_related：输入已知位置，返回其邻居：其他实现、调用方、测试等。/semble：报告子命令，包括/semble savings、/semble file-types、/semble version与/semble clear <index|savings|orphans|all>。
工具参数包括：
- repo：仓库的绝对路径或 https:// Git URL。可一次搜索多个仓库。
- top_k：默认 5，检索数量。首次命中不足时可提升到 10–20。
- max_snippet_lines：默认 10，片段最大行数；设为 0 仅返回位置。
- content：默认 code，可选 docs、config 或 all，控制索引内容类型。
第一次查询会构建索引（较慢，一次性）；后续查询复用磁盘缓存。命中结果按相似度排序，分数为 RRF 值（约 0.0x），可视为相对排序，空结果表示未找到相关代码。
安装与启用¶
桌面应用¶
- 打开 DSH 桌面应用。
- 进入 Settings → Plugins → Install。
- 输入插件名：
dsh-semble
- 若需锁定版本，可在插件行配置中输入
dsh-semble@3.0.0。
桌面应用仅支持通过设置页安装 desktop 配置文件，CLI 会拒绝直接安装到该配置文件。
命令行¶
dsh plugin --profile web add dsh-semble
该命令在 web 配置文件中运行 pnpm add，并协调 dsh.profile.bundles，使插件在下一次启动时挂载。无构建步骤，无需额外豁免配置。
从仓库安装¶
若需跟踪 main 分支、fork 或未发布提交，使用：
dsh plugin --profile web add github:CodeIntegrity/dsh-semble
支持 github:owner/repo、git+https://…、https://github.com/owner/repo 以及 .tgz URL，需要 git 在 PATH。
本地检出安装¶
dsh plugin --profile web add link:/absolute/path/to/dsh-semble # macOS / Linux
dsh plugin --profile web add link:D:\path\to\dsh-semble # Windows
安装后配置文件指向工作副本，修改 cordis.patch.yml 后重启即可生效，无需重新安装。
前置依赖¶
插件依赖 uv，通过 uvx 从 PyPI 启动 Semble：
- Windows：
winget install astral-sh.uv
- macOS：
brew install uv
- macOS / Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
首次启动时会下载 Semble 包与嵌入模型（约 1–2 分钟），之后索引与查询在本地运行，无需 API 密钥、GPU 或外部服务。安装后重启 DSH，设置行可能显示「待重启」。
配置与调优¶
在 Settings → Plugins 编辑插件行，配置项为加载器行的 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 移动索引位置 |
修改配置会重新注册工具，磁盘索引缓存保留。
环境变量¶
工具通过进程环境读取配置，将变量放在插件 config 的 env 字段。/semble 命令启动独立进程并继承宿主环境，若报告与搜索需一致，建议同时在两者导出相关变量。
| 变量 | 默认值 | 作用 |
|---|---|---|
SEMBLE_INDEX_WORKERS |
4 |
首次索引时分片仓库的工作进程数，设为 0 在进程内分片。多核机器可提升，避免后台搜索占用过多 CPU |
SEMBLE_MCP_IDLE_TIMEOUT |
0（永不） |
MCP 模式下空闲索引在内存缓存中停留的秒数；CLI 每次调用退出，该变量对该模式无影响 |
SEMBLE_MODEL_NAME |
minishlab/potion-code-16M-v2 |
替换为本地路径或 Hugging Face 仓库的嵌入模型 |
SEMBLE_MAX_FILE_BYTES |
1000000 |
超过该大小的文件将被跳过，生成代码需索引时可调高 |
SEMBLE_CLONE_TIMEOUT |
60 |
克隆 https:// 仓库允许的最长时间（秒） |
HF_ENDPOINT |
https://huggingface.co |
模型下载时的镜像地址 |
适用场景与注意¶
- 适合需要根据行为描述而非文件名检索代码的智能体场景，如代码理解、迁移与重构辅助。
- 插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。
- 依赖
uv与网络（首次下载模型），网络受限时可配置镜像。 - 首次索引较慢，后续查询在毫秒级完成，索引增量更新。
小结¶
dsh-semble 为 DSH 提供了基于语义的代码检索能力，通过 semble_search 与 semble_find_related 让智能体根据行为描述而非猜测文件名定位代码，显著降低 token 消耗并提升检索精度。插件在本地完成索引与查询，无需外部服务，适合需要深度代码理解的智能体开发场景。
- 插件目录：https://www.skillhub.cn/plugins/CodeIntegrity/dsh-semble
- GitHub：https://github.com/CodeIntegrity/dsh-semble
