前言¶

在 DSH 插件开发中，Agent 经常需要读取 API 返回值、配置文件或工具输出里的 JSON。如果只用字符串搜索，容易把 key、value 和嵌套对象中的同名 key 混在一起；如果引入完整 JSON 查询引擎，成本又不一定适合轻量工具。

omdsh-dev/dsh-tool-json 是一个 DSH 工具插件：它注册一个名为 json 的工具，接受 JSON value 或 JSON string 作为输入，并用一条 JMESPath-inspired 路径查询（自定义子集）取字段。下面介绍它的定位、能力、安装方式和注意事项。

这是什么¶

这是一个只读 JSON 查询插件。

• 仓库：omdsh-dev/dsh-tool-json
• 包名：@deepseek-ai/dsh-tool-json
• 维护者：omdsh-dev
• 许可证：MIT
• 当前 package.json 版本：0.0.1
• 适配 DSH：0.1.2-alpha.2（npm）
• 安装方式：支持 Profile Bundle，也支持 npm pack tarball 安装

它提供 DSH 工具 json。调用时传入 input 和 query：input 是要查询的 JSON value 或 JSON string，query 是路径表达式。插件执行查询后返回对应字段值。

核心功能¶

提供 json 工具¶

工具声明中的参数包括：

input: {
  type: 'json',
  required: true,
  description: 'JSON value or JSON string to query.'
}

query: {
  type: 'string',
  required: true,
  description: 'Path expression, e.g. "data.items[0].name".'
}

input 支持两种形态：对象直传，或 JSON string 传入。插件通过 normalizeInput 做统一归一化与校验。工具声明中的超时时间为：

timeoutMs: 1000

查询子集¶

该插件支持 JMESPath-inspired 路径查询的子集，不实现完整 JMESPath。

常见表达式包括：

它只作用于查询取值，不修改 JSON 字段。

错误模型¶

查询错误统一归类为 JsonQueryError，并带 json: 前缀。

已核实的错误类型包括：

• MISSING_PROPERTY
• TYPE_MISMATCH
• INDEX_OUT_OF_BOUNDS
• INVALID_QUERY

其中，MISSING_PROPERTY 在投影内跳过；TYPE_MISMATCH、INDEX_OUT_OF_BOUNDS、INVALID_QUERY 会如实抛出。

查询语法¶

下面介绍几个典型路径表达式。

单值查询¶

json { input: <JSON>, query: "items[0].name" }

示例返回：

"hello"

数组投影¶

json { input: <JSON>, query: "items[*].name" }

示例返回：

["a", "b"]

合法 null 会保留。

特殊 key 查询¶

json { input: <JSON>, query: "items['complex-key']" }

示例返回：

"ok"

多级通配符¶

items[*].tags[*] 这类多级通配符会返回嵌套数组，不做标准 JMESPath 投影扁平化。

例如标准 JMESPath 可能期望扁平数组，但该插件返回的是嵌套结构。

语义边界¶

这个插件有意不兼容完整 JMESPath。

已核实的限制包括：

• 通配符仅作用于数组
• 不支持对象字段枚举
• 多级通配符返回嵌套数组
• 不做标准 JMESPath 投影扁平化
• 不支持过滤器表达式，例如 [?downloads > 1000]
• 不支持管道 |
• 不支持函数调用

如果你的需求是修改 JSON 字段，这个插件不适合，因为它只读，不能修改 JSON 字段。

安全与资源限制¶

插件使用手写递归下降解析器，不使用 eval 或 new Function。在对象属性访问时使用 Object.hasOwn，避免触发原型链。

已核实的资源上限如下：

• 查询表达式长度：≤ 200 字符
• 解析深度：≤ 20 层
• 字符串输入：≤ 1,000,000 bytes
• 输入嵌套深度：≤ 100
• 单次 wildcard 投影：≤ 100,000 元素

输入只接受 JSON-compatible 值：

• null
• boolean
• 有限 number
• string
• array
• plain object

需要注意：输入在每次查询前会执行全量校验。由于校验是同步过程，timeoutMs 无法中断同步校验。

安装与启用¶

确认依赖¶

该插件适配 DSH 0.1.2-alpha.2（npm）。

package.json 中的 engines 要求：

"node": "^22.19.0 || >=24.0.0"

peerDependencies 要求：

{
  "@deepseek-ai/cordis": "^4.0.1",
  "@deepseek-ai/dsh-invariants": ">=0.0.1-rc.1 <0.2.0",
  "@deepseek-ai/dsh-tools": ">=0.0.1-rc.1 <0.2.0"
}

按 profile 安装¶

web 与 headless 是不同 profile。web 安装不会自动覆盖 headless；dsh run 默认使用 headless profile。

如果要安装到 web profile：

dsh plugin --profile web add github:omdsh-dev/dsh-tool-json

如果要安装到 headless profile：

dsh plugin --profile headless add github:omdsh-dev/dsh-tool-json

选择哪个 profile，取决于你后续用 web 还是 dsh run。

Profile Bundle 机制¶

包内 package.json 的 dsh.bundle.patch 指向：

./cordis.patch.yml

安装后，插件会进入 profile 的 layer stack。插件的 cordis.patch.yml 使用 - insert: 列表插入条目。

如果使用裸 - id: 条目，会报 entry not found。正确写法应使用 - insert: 列表包裹。

验证安装¶

可以检查配置中是否出现该插件条目：

dsh --profile web --dump-config | grep tool-json

npm pack tarball 安装¶

也可以本地打包后安装：

npm pack
dsh plugin --profile web add ./dsh-tool-json-*.tgz
dsh plugin --profile headless add ./dsh-tool-json-*.tgz

发布 tarball 包含：

lib/
src/
cordis.patch.yml

典型用法¶

下面是插件文档中给出的查询示例。

查询单个字段¶

json { input: <JSON>, query: "items[0].name" }

返回：

"hello"

查询数组中多个字段¶

json { input: <JSON>, query: "items[*].name" }

返回：

["a", "b"]

合法 null 会保留。

查询带特殊字符的 key¶

json { input: <JSON>, query: "items['complex-key']" }

返回：

"ok"

通过 dsh run 调用¶

可以要求 DSH 使用 json 工具完成查询：

dsh run "使用 json 工具查询 {"a":{"b":1}} 的 a.b"

适用场景与注意¶

适合的场景¶

• 从 JSON 中按明确路径取值
• 查询数组中固定结构字段
• 查询含特殊字符的属性名
• 在 DSH Agent 中替代临时脚本做只读 JSON 取值

不适合的场景¶

• 需要修改 JSON 字段
• 需要过滤器表达式
• 需要管道 |
• 需要函数调用
• 需要对象字段枚举
• 需要标准 JMESPath 的投影扁平化行为

安全注意¶

插件会在当前 dsh 进程权限下执行查询。安装前应先检查源码与许可证，确认其行为符合你的安全要求。

该插件是 MIT 许可，公开仓库地址为：

https://github.com/omdsh-dev/dsh-tool-json

结尾¶

omdsh-dev/dsh-tool-json 解决的是一个具体问题：在 DSH 中用结构化路径从 JSON 里取值。它不替代完整 JMESPath，而是提供一个零依赖、只读、有明确资源上限的查询子集。

如果你需要在 web 或 headless profile 中让 Agent 稳定读取 JSON 字段，可以先按目标 profile 安装，再用 dsh --profile <profile> --dump-config 验证插件是否进入配置。

源码地址：

https://github.com/omdsh-dev/dsh-tool-json