前言¶
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
