dsh-tool-zg

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

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

---

什么是 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 协议。