前言¶
DeepSeek Harness (DSH) 側重於插件化架構。在進行智能體開發或代碼調試時，快速定位源碼中的具體邏輯往往比簡單的文本匹配更高效。傳統的搜索工具依賴關鍵詞匹配，難以理解代碼語義。semantic-search 插件解決了這一問題，它將代碼庫片段轉化爲向量索引，支持自然語言查詢。
是什麼¶
這是一個爲 DeepSeek Harness (DSH) 提供的本地語義代碼搜索插件，由開發者 JohnXu22786 維護。插件的核心價值在於無需聯網即可完成代碼的語義理解與檢索，支持片段級索引與混合檢索策略。
核心功能¶
該插件包含以下主要能力：
- 代碼索引：支持片段級、符號感知的索引構建。它能夠識別函數、類等邊界，並支持 16 種以上的編程語言（包括 TypeScript、Python、Go、Rust、Java、C/C++、Ruby、PHP、Swift、Bash、Markdown、JSON、YAML 等）。
- 離線嵌入：默認使用離線詞法嵌入，無需網絡或 API Key。同時也支持配置 OpenAI 兼容的端點。
- 混合檢索：結合向量餘弦相似度與 BM25 算法，並通過倒數排名融合 (RRF) 策略合併結果。
- 工具集：提供三個 DSH 工具 (
sema_search、sema_reindex、sema_stats) 和一個獨立的sema命令行工具。 - 增量更新：支持增量刷新與文件監聽，並持久化索引到
<root>/.sema目錄。
安裝與啓用¶
安裝前請確保環境滿足要求：Node.js 版本需在 ^22.19.0 或 >=24.0.0 範圍內。
- 執行安裝命令：
dsh plugin --profile demo add github:JohnXu22786/semantic-search
- 安裝完成後，插件會註冊相應的工具到 DSH 的工具鏈中。
典型用法¶
安裝後，可以使用 sema 命令進行索引構建、更新與搜索。
- 構建索引：從工作區構建完整索引。
sema index
- 增量更新：根據文件變更進行增量重建，或使用
--full進行完全重建。
sema reindex [--full]
- 語義搜索：混合向量與 BM25 檢索，輸出排名靠前的結果。
sema search <query...>
- 索引統計：查看索引健康狀態、提供者信息及數據大小。
sema stats [--]
常用全局選項包括：
* --root <dir>：指定工作區根目錄（默認爲當前目錄）。
* --provider <kind>：指定嵌入提供者類型（默認爲 lexical）。
* --dim <n>：指定嵌入維度。
適用場景與注意¶
- 離線優先：插件默認離線工作，內置的詞法提供者不依賴網絡。如果配置了遠程提供者且連接失敗，會優雅降級回退到離線模式。
- 確定性：相同的源碼和配置會產生確定的索引和排序結果。
- 權限與安全：插件以 DSH 進程的權限運行，安裝前建議檢查源碼與許可證（MIT）。
- 生態說明：該插件爲社區維護項目，通過 SkillHub 等目錄發佈，與 DeepSeek 或幻方官方無從屬關係。
短結尾¶
semantic-search 爲 DSH 生態提供了一個輕量、本地化的語義代碼搜索方案。通過片段級索引和混合檢索，它能夠顯著提升代碼定位的準確性。更多細節可參考插件目錄或 GitHub 倉庫。
