前言¶
在 DSH 裏做代碼相關任務時，模型往往先用 grep 或 ripgrep 掃字面匹配。大倉庫裏關鍵詞對不上、或問題本身是「這段邏輯在哪」時，純詞法檢索容易漏掉語義上相關但措辭不同的文件。自建向量索引再寫檢索腳本，又要單獨維護 CLI、embedding 和索引目錄，和會話裏的工具鏈也接不上。
下面介紹社區插件 @jayyuen66/dsh-zvec-grep（維護者 JayYuen666）。它把 zg CLI 的 BM25、向量與 RRF 混合檢索掛進 dsh，向模型暴露 zg_search、zg_index、zg_status，並附帶 systemPrompt 路由、grep/rg 的 search-first 門禁，以及 web 端設置卡。插件當前版本爲 0.1.6（MIT），GitHub 星標爲 0。
這是什麼¶
一句話：@jayyuen66/dsh-zvec-grep 是 zg（@zvec/zvec-grep）之上的 dsh 適配層，經宿主 shell 調用 zg，不在包內分發上游二進制。
底層檢索由獨立安裝的 zg 完成；本插件負責註冊模型工具、注入規則與 guard、提供 embedding 與重建相關的設置界面，並在已建索引的工作區裏要求「先語義搜、再 grep/rg」（可配置關閉門禁，安全兜底仍在）。
核心功能¶
三個模型工具¶
-
zg_search：至少提供
query、queries、fts、vector之一（合計最多 32 組，單條最多 4000 字符）。支持 globs、fileTypes、limit、preview、refresh、device 等參數。工作區無索引時，缺省會自動改走 zg 的--rg窮舉詞法通道；有索引時走混合語義檢索。傳輸模式缺省--mode auto：守護進程就緒走 server，否則 zg 靜默落回 direct。 -
zg_index：
confirm必須爲true纔會執行。可建索引、重建、切換 embedding（切換 embedding 須rebuild=true）。支持background=true在模型側後臺跑索引，與設置卡「工作區重建」共用同一套作業登記邏輯。 -
zg_status：查看索引狀態；
checkReady=true時按 zg 契約用退出碼錶達是否就緒，報告仍在 stdout。
三者 root 可省略（缺省爲當前會話工作區）。超時與 stdout 上限有部署默認值（檢索 5 分鐘、索引 10 分鐘、status 60 秒、stdout 400000 字節）。
規則與門禁¶
- 注入 systemPrompt 段
zvec-grep-routing（order 1550），引導模型優先用語義檢索。 - search-first：在判定「已含索引」的工作區裏，bash/pwsh 命令串或原生 grep 工具裏的 grep/rg 須先有一次成功的
zg_search（配額與窗口可在設置裏調：grepBudgetPerSearch、unlockWindowMin）。enforceSearchFirst=false只關門禁，不削弱 zg_* 的 root、confirm 等安全兜底。 - zg_* 安全兜底：例如
zg_index無 confirm 會被拒絕；root 須爲以/開頭的絕對路徑（POSIX）。
Web 設置卡¶
命名空間 zvec-grep 由宿主隱式註冊。卡片上可調默認 embedding、defaultLimit、HF 鏡像基址 hfEndpoint、search-first 開關與配額等；另有一行守護進程就緒態和「工作區重建」按鈕。重建狀態由客戶端每 2 秒輪詢 Remote 接口 zvecGrepRebuild（REBUILD_POLL_MS = 2000）。
平臺與支持面¶
- Linux / macOS：root 與命令形態按 POSIX 設計（
bash -c、路徑以/分隔）。 - Windows 不在支持面：工作區形如
C:\Users\…時三個 zg 工具會在rootOf階段 fail-fast，並說明 root 必須以/開頭。
安裝與啓用¶
安裝 dsh 插件¶
包在公共 npm，無需憑據。官方安裝命令如下：
dsh plugin --profile web add @jayyuen66/dsh-zvec-grep
add/remove 會維護包內 cordis.patch.yml 的註冊行 - id: zvec-grep。bundle 安裝走 pnpm（>= 12.3.0），且 dsh.client.platform 爲 web 時設置卡 client 半由宿主下發。
宿主兼容性按 peer 聲明比對 @deepseek-ai/dsh 與各 @deepseek-ai/dsh-* 版本。本包對 dsh-* 精確釘版本；若宿主高於插件聲明的 0.2.1-rc.2 區間，需按宿主提示使用：
dsh plugin --profile web allow-version @jayyuen66/dsh-zvec-grep@<版本> --dsh-version <確切版本> --accept-risk
apply 需要 settings、shell、tools、systemPrompt、timer 五個 inject 面齊備，缺一則 cordis 不激活該條目。
安裝 zg CLI¶
插件不捆綁 zg。須在 PATH 中安裝上游 CLI，版本不低於 0.2.2：
npm install -g @zvec/zvec-grep
未安裝或不在 PATH 時，工具會區分 exit 127（zg 缺失）與其他 runner 失敗。上游倉庫：https://github.com/zvec-ai/zvec-grep，許可 Apache-2.0。
可選：守護進程（server 模式）¶
refresh=background、索引 watcher 與常駐 embedding 模型池僅在 server 模式可用。插件不代爲執行 zg server on；需要時在終端自行啓動，本包只緩存約 60 秒內 zg server status --check-ready 的退出碼並在設置卡展示就緒態。
典型用法¶
1. 爲當前工作區建索引¶
模型調用 zg_index，且 confirm=true。大倉庫可加 globs/fileTypes 縮小範圍；長時間索引可用 background=true，再通過官方 job_list / job_output 或設置卡查看進度。
2. 語義查找代碼¶
建索引後使用 zg_search，傳入自然語言或關鍵詞 query。默認 preview=short 會附帶有限上下文；默認 refresh=wait 會等索引刷到最新再查。
3. 無索引時的字面檢索¶
從未建索引的根上，zg_search 缺省會自動走 --rg 窮舉通道，並在結果前聲明這是逐行字面匹配而非語義排序。若要語義結果，須先 zg_index。
4. 在已索引工作區裏繼續用 grep/rg¶
開啓 search-first 時，須先完成一次成功的 zg_search，再在配額與時間窗口內使用 grep/rg。若被拒並提示「尚未執行過 zg_search」，先補一次語義檢索即可，不必關閉整個插件。
5. 在設置卡里改 embedding 或重建¶
在 web 設置中修改 defaultEmbedding 等 volatile 項；切換 embedding 後須通過重建（卡片按鈕或 zg_index 且 rebuild=true）才生效。遠程 embedding 默認關閉，須在部署 config 中顯式打開相關項，且 zg 側還需用戶自行 zg auth grant 授權。
適用場景與注意¶
適合誰：在 DSH（web profile）裏經常讓模型查代碼、且願意在 Linux/macOS 上維護本地 zg 索引與 embedding 的開發者。
依賴與版本：若 profile 用 pnpm overrides 釘 @jayyuen66/dsh-plugin-shared，版本不得低於本包聲明的版本，否則可能出現「包裝得上、條目不激活」的導出缺失錯誤。
數據與隱私：索引寫在各檢索 root 下的 .zvec-grep/，由 zg 寫入；本插件自身不向 $DSH_HOME 落盤。默認排除常見密鑰擴展名；無擴展名密鑰文件需用 ignoreFiles 自行聲明。顯式 embedding 默認只允許本地候選清單中的模型，避免模型隨意指定會把工作區送到外部的遠程端點。
權限與安全：插件以當前 dsh 進程權限經 shell 調用 zg，能讀寫的範圍與會話工作區及 zg 行爲一致。安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證；zg 上游爲 Apache-2.0，一併分發時需分別保留許可聲明。
DSH 生態強調「一切皆插件」；社區目錄 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係，僅作發現與鏈接用途。
結尾¶
@jayyuen66/dsh-zvec-grep 把 zg 的混合檢索、索引管理與 search-first 紀律收進 dsh 工具面，減少「只會 grep 掃關鍵詞」和「另起一套索引腳本」之間的斷層。按上文安裝插件與 zg、在 POSIX 宿主上建索引後，模型即可在會話內用語義檢索定位代碼，並在規則允許範圍內繼續使用 grep/rg。
- 社區目錄：https://www.skillhub.cn/plugins/JayYuen666/dsh-zvec-grep
- 源碼與文檔：https://github.com/JayYuen666/dsh-zvec-grep
