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