Jaylor-Wang/dsh-tool-ast-grep

English | 中文

专为 DeepSeek Harness (DSH) 打造的语法级 AST 代码检索与大纲提取插件，基于 Rust 高性能语法解析工具 ast-grep 驱动。

为 Coding Agent 提供精准的代码语法树（AST）检索能力与文件架构提取能力，在语义精度和 Token 消耗控制上彻底超越传统的纯文本正则搜索（grep）。

---

核心特性

• ast_search（AST 结构化检索）：
  • 使用 AST 模式语法与元变量（如 $NAME 匹配单节点，$$$ 匹配任意多节点/参数）精准定位目标代码。
  • 语法无关排版：不论是单行书写、换行还是空格格式差异，均能准确匹配。
  • 支持节点类型（Kind）检索（如 class_declaration, interface_declaration, method_definition）。
  • 支持严格度模式（smart, relaxed, ast, cst）及文件 Glob 过滤。
• ast_outline（极速代码大纲提取）：
  • 一键提取源码文件的结构化大纲（顶层函数、类、接口、类型别名、导出语句）。
  • 相比把整个长文件塞进大模型上下文，可节省 80%–95% 的 Token 消耗。
  • 支持深度控制：默认只看顶层接口，可展开类内部方法与构造函数。
• 消灭 Shell 引号与转义地狱：
  • 采用 Node.js 原生参数列表调用，彻底规避 Windows Shell 下特殊字符（如 $VAR 被吞、引号被截断）引发的运行报错。

---

前置要求

使用本插件需要在系统中安装 ast-grep 命令行工具（二选一即可）：

• 通过 npm 全局安装：

  npm install -g @ast-grep/cli
  

• 通过 Python pip 安装：

  pip install ast-grep-cli
  

• 通过 Cargo 安装 (Rust)：

  cargo install ast-grep --locked
  

• macOS / Homebrew：

  brew install ast-grep
  

验证安装：

ast-grep --version

自定义路径提示：若二进制安装在非标准路径或自定义 npm prefix，插件会自动探测系统 PATH 目录。你也可以直接设置环境变量 AST_GREP_PATH（指向 ast-grep 或 ast-grep.exe 的完整路径）。

---

在 DeepSeek Harness 中安装

方式 1：通过插件市场一键安装（推荐）

在 Web UI 导航至 设置 → 插件市场，搜索 dsh-tool-ast-grep，点击安装即可。

或在终端中运行：

dsh plugin --profile web add dsh-tool-ast-grep

方式 2：在智能体预设（Preset）中引入

在你的预设文件（如 ~/.dsh/.agent-presets/my-agent/agent.cordis.yml）中挂载：

id: my-agent
name: My Agent
tools:
  - id: tool-ast-grep
    name: dsh-tool-ast-grep
    config:
      maxResults: 50
      timeoutMs: 60000

---

工具参数说明

1. ast_search

参数	类型	说明
pattern	string	AST 匹配模式，如 function $NAME($$$) { $$$ } 或 $OBJ.push($ITEM)
kind	string	AST 语法节点类型，如 class_declaration, function_declaration
path	string	搜索的目标目录或文件路径（默认为工作区根目录）
lang	string	指定语言（ts, tsx, js, jsx, python, rust, go 等）
globs	string	文件过滤规则（如 src/**/*.ts 或 !**/*.test.ts）
limit	integer	最大返回条数（默认 50）

2. ast_outline

参数	类型	说明
file_path	string	目标源码文件路径（相对路径或绝对路径）
lang	string	指定语言（如省略则根据文件后缀自动推断）
depth	integer	大纲深度：1 仅展示顶层定义（默认），2 展开类方法与构造器

---

支持的语言

TypeScript (ts, tsx), JavaScript (js, jsx), Python (py), Rust (rs), Go (go), Java (java), C (c, h), C++ (cpp, hpp, cc)。

---

许可证

MIT © Jaylor Wang (Jaylor-Wang)