gunduziba/dsh-tool-zg

dsh-tool-zg

DeepSeek Harness (DSH) 原生 zg (zvec-grep) 代码语义与架构搜索工具插件。

让大模型智能体能够像资深架构师一样，使用自然语言理解工程宏观设计、探查业务概念，并沿着跨文件调用链路精准定位代码。

license
dsh

什么是 zg (zvec-grep)？

zvec-grep (zg) 是专门为 AI Coding Agent 与开发者打造的下一代混合代码检索引擎：
- 混合多路召回：融合了本地轻量向量模型（如 16M 参数的 potion-code-16m-v2）、BM25 关键词相关度算法与底层的 ripgrep 正则搜索。
- RRF 倒数排名融合：通过倒数排名融合（Reciprocal Rank Fusion）算法，将语义相似性与字面精确匹配完美结合。
- 解决核心痛点：当面对陌生巨型项目、业务词有错别字（如“称”与“秤”）、跨文件接口实现解耦或仅有自然语言概念描述时，传统的 ripgrep 极易漏查或查无所获，而 zg 能秒级直达核心实现。

特性亮点

1. 极致节省 Token (下降 90%)：
- 相比官方 MCP 协议臃肿冗余的 Tools Schema 定义（每轮对话消耗约 800+ tokens），本插件采用 DSH 原生 defineTool 精简定义，单次提示词占用仅约 80 tokens。
2. 按 Agent 预设（Preset）动态控制：
- 支持按 DSH 预设隔离工具。默认在 minimal（极简模式）中自动屏蔽，保证极简模式的双工具（bash + editor）纯粹性，避免上下文污染。
3. 原生进程毫秒级直连：
- 绕过 HTTP / SSE 等多层网络协议序列化开销，直接以 Node.js 异步进程调用本机预热好的 zg 引擎，响应时间在毫秒级别。
4. 上下文安全与自动截断落盘：
- 内置 2000 行 / 50KB 安全头截断保护，超限结果自动保存至 /tmp/dsh-zg-.../output.txt，并在返回内容末尾附带提示，防止长文本撑爆上下文窗口。

前置条件

在使用本插件之前，请确保系统中已正确安装并配置好 zvec-grep 环境：

1. 安装 zg 命令行工具
需要 Node.js >= 22：
npm install -g @zvec/zvec-grep

2. 下载并配置本地 Embedding 模型
配置使用本地轻量级代码嵌入模型（完全本地离线运行，支持 GPU/Metal 硬件加速，无需额外 API Key）：
设置默认模型为 potion-code-16m-v2，在 Apple Silicon 上开启 metal 加速（Linux/Windows 可指定 cpu 或 cuda）
zg config model set local/potion-code-16m-v2 --default --device metal

3. 启动常驻守护服务（推荐）
启动后台守护进程以提供即时索引与极速查询响应：
zg server on

4. 为目标工程建立索引
首次在某个项目工作区使用前，可快速建立语义索引（支持增量更新）：
zg index /path/to/your/project

安装与配置

步骤 1：部署插件
将本插件放入 DSH Web Profile 插件目录中：
cp -r dsh-tool-zg ~/.dsh/profiles/web/node_modules/

步骤 2：在 cordis.patch.yml 中挂载
编辑 ~/.dsh/profiles/web/cordis.patch.yml，插入如下配置：
- insert:
- id: tool-zg
name: 'dsh-tool-zg'
config:
disabledPresets:
- minimal    # 在极简模式下严格禁用 zg 工具

步骤 3：重启 DSH 进程
pm2 restart dsh-web

工具参数说明

大模型在调用 zg 工具时支持以下参数：

| 参数 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| query | string | 是 | 语义检索词、自然语言描述、跨文件调用流或架构设计概念 |
| fts | string | 否 | 精确关键词或代码标识符（与语义搜索融合以锁定特定函数/类/字段） |
| path | string | 否 | 限制搜索的目标目录或文件路径（默认为当前工作区根目录） |
| glob | string | 否 | 文件匹配模式，如 '*.ts'、'src/' 或排除 '!node_modules/' |
| limit | integer | 否 | 返回的最大匹配条数（默认为 10，上限 30） |

开源协议

本项目采用 MIT License 协议。