跳到主内容

dsh-tool-json/packages/dsh-tool-json

24Star1Fork1Issue0Watching

DSH JSON 结构化查询工具，用 JMESPath 子集路径表达式替代 grep/jq 解析 JSON

分类⇄ 集成与服务
机审证据5/5方法论数据来源安装命令持续维护DSH 版本风险扫描
机审证据安装命令仓库已核验dsh-plugin Topic许可证READMEAI 百科

ⓘ 此插件是大仓库 omdsh-dev/dsh-toolkit 的子包，星数与活跃度统计的是整个仓库。

omdsh-devomdsh-dev
·omdsh-dev/dsh-toolkit
语言
TypeScript
License
MIT
分支
main
collectiondshdsh-plugintoolkitzero-dependency

安装

命令web profile
$ dsh plugin --profile web add github:omdsh-dev/dsh-toolkit#path:packages/dsh-tool-json

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

对话式安装

帮我安装 DeepSeek Harness 插件 omdsh-dev/dsh-toolkit/packages/dsh-tool-json：先查看仓库 https://github.com/omdsh-dev/dsh-toolkit 确认安全性，然后执行安装命令并验证插件加载成功。

把这段指令粘贴给 DSH Web GUI 里的助手，由它代你完成安装与验证。

一句话定位

DSH 的 JSON 结构化查询工具，让 AI 用 JMESPath 风格的路径表达式（foo.bar、items[0]、items[*].name）从 JSON 数据中精确提取指定字段，免去起 bash 进程跑 jq 或用 grep 做字符串级匹配。

核心能力

  • 注册名为 json 的工具，让 AI 用路径表达式查询 JSON 数据（API 响应、配置文件、工具输出）
  • 支持点号访问（foo.bar）、数组下标（items[0]）、方括号属性（items['complex-key']）、数组通配符投影（items[*].name）
  • 接受双形态输入：JSON 对象直传（零转义）或 JSON 字符串（bash/read 原文透传），由 normalizeInput 统一归一化与校验
  • 每次查询前对输入做全量校验：类型、深度、字节、循环引用、不可枚举属性、accessor 都会被拦截
  • 资源硬上限：输入 ≤ 1,000,000 字节、嵌套深度 ≤ 100、查询表达式 ≤ 200 字符、解析深度 ≤ 20 层、单次 wildcard 投影 ≤ 100,000 元素
  • 错误分类精细：MISSING_PROPERTY（投影内跳过）/ TYPE_MISMATCH / INDEX_OUT_OF_BOUNDS / INVALID_QUERY，统一 json: 错误前缀

技术实现

  • 语言: TypeScript（ESM，tsc 编译输出到 lib/）
  • 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-invariants
  • 架构模式: Cordis 插件模型（name + inject: ['tools'] + apply(ctx)），在 apply 中通过 ctx.tools.register(defineTool(...)) 注册名为 json 的工具；安装时由 cordis.patch.yml 以 - insert: 列表把 tool-json 条目插入目标 profile 的 layer 栈
  • 入口文件: src/index.ts（Cordis 插件入口 + 工具声明）/ src/query.ts（手写递归下降解析器 + 执行器 + 输入归一化）/ src/invariant.ts（包级 invariant companion）/ tests/query.spec.ts（功能、错误、攻击载荷、资源边界 54 个用例）

适用场景

AI 频繁处理 JSON 数据（HTTP API 响应、配置文件、JSON 日志、其他工具输出）时，用结构化路径精准取出指定字段，比 grep 字符串匹配更准确，比 jq + bash 更轻量、零进程开销；尤其在 Windows 上替代 jq 能省去 shell 启动成本。配合 Agent 工具栈可在多步骤 JSON 处理中作为只读取数器使用。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.8+peerDependencies 要求 @deepseek-ai/dsh-tools 与 @deepseek-ai/dsh-invariants 在 [0.0.1-rc.1, 0.2.0)，@deepseek-ai/cordis ^4.0.1；README 明确在 @deepseek-ai/[email protected] 隔离 consumer 完成全链路验证
Node.js>=22.19.0package.json#engines 声明 ^22.19.0 || >=24.0.0
平台macOS / Windows / Linux纯 TypeScript 实现，未声明任何原生模块
原生模块无零运行时 JS 依赖（解析器、执行器、归一化器均为手写），不引入 node-pty、node:sqlite 等

安装方式

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

配置项

本插件无需外部配置。json 工具的入参完全由单次调用决定，源码中没有读取 config、process.env、options 等任何外部配置。

配置类型说明默认值
inputjson待查询的 JSON 值或 JSON 字符串；对象直传走零转义路径，字符串走原文透传（每次调用必填，无默认值）
querystring路径表达式，例如 "data.items[0].name"、"users[*].email"（每次调用必填，无默认值）

常见问题

Q: 这个工具和 DSH 内置的 grep 比有什么差别？

A: grep 只做字符串级正则匹配，遇到嵌套 JSON 时容易把同名 key、value、或子对象里的同名 key 混在一起。json 走结构化路径表达式，只匹配你指定位置的字段，不混淆 key 和 value，也不怕序列化后跨行的字段。

Q: 为什么不直接用 jq？

A: 调用 jq 要起一个 bash 进程跑命令，每次都要付 shell 启动 + 字符串序列化成本，且把 JSON 字符串拼到命令行里有 shell 注入风险需要手动转义。本工具是毫秒级纯函数调用，JSON 解析和转义都在插件内部消化。

Q: 支持哪些路径语法？

A: 点号访问 foo.bar、数组下标 items[0]、方括号属性 items['key'] 或 items["key"]（支持 \\ \' \" 转义，非法转义直接报错）、数组通配符投影 items[*].name；以上可自由组合（如 a.b[0].c.d）。底层是手写的递归下降解析器，没有依赖任何 JMESPath 标准库。

Q: 不支持哪些 JMESPath 功能？

A: 不支持过滤器表达式 [?downloads > 1000]、管道 |、函数调用（to_string / sort 等）；多级通配符 items[*].tags[*] 返回嵌套数组而非标准 JMESPath 的扁平化结果；通配符只能作用于数组，无法枚举对象字段。需要这些场景可以走 bash + node 兜底。

Q: 输入是 JSON 对象还是 JSON 字符串？

A: 两种都接受。input 字段类型是 json，模型可以直接传 JSON 对象（走零转义路径），也可以传字符串（bash/read 拿到的原文）。normalizeInput() 会统一走 JSON.parse 或直接对对象做兼容性校验（assertJsonCompatible），拒绝循环引用、不可枚举属性、accessor、symbol key、BigInt、Date 等非 JSON 值。

Q: 查询会超时吗？输入太大怎么办？

A: 工具调用超时 1 秒（timeoutMs: 1000，src/index.ts:48）。输入侧对 JSON 字符串的 UTF-8 字节数、对象路径累计字节数、嵌套深度、wildcard 投影元素数都有硬上限：字符串输入 ≤ 1 MB、嵌套深度 ≤ 100 层、wildcard 投影元素 ≤ 10 万；输出 JSON 字符串 ≤ 4 MB。任意一项超出都会抛 JsonQueryError(INVALID_QUERY)。

Q: 能修改 JSON 字段吗？

A: 不能。这是只读工具。需要原地修改字段请用 str_replace_editor、write 等文本编辑工具，或者直接重写整个 JSON。

Q: 装到 web profile 后 dsh run 能用到吗？

A: 不能。web 与 headless 是两个独立的 profile，dsh run 默认走 headless，所以 headless profile 也需要单独装一次，或者用集合仓库自带的批量脚本一次性同时装到两边。

上手难度

入门 — 安装一行命令即生效，AI 在对话里按需调用 json 工具并传入 JSON 与路径表达式即可；理解支持的 4 种路径语法和通配符仅作用于数组这两个边界，足以避免常见踩坑。

已知问题与限制

  • 只读：不能修改 JSON 字段，需要修改请用文本编辑工具（README.md:165）
  • 不支持 JMESPath 过滤器 [?...]、管道 |、函数调用；多级通配符返回嵌套数组而非扁平化（README.md:73-80）
  • 通配符 [*] 仅作用于数组，无法枚举对象字段；非对象元素按投影语义跳过，合法 null 结果保留（README.md:76、src/query.ts:174-188）
  • 工具调用超时 timeoutMs: 1000（src/index.ts:48），单次查询超过 1 秒会被宿主中断；且因为输入校验是同步全量扫描，超大输入可能在到达超时前就抛 INVALID_QUERY
  • 输入在每次查询前执行全量校验（类型 / 深度 / 字节 / 循环 / 不可枚举 / accessor），即便只查一个小字段也会完整扫描整个输入（README.md:29）
  • 资源上限：查询表达式 ≤ 200 字符、解析深度 ≤ 20 层、字符串输入 ≤ 1 MB（UTF-8）、对象嵌套 ≤ 100 层、wildcard 投影 ≤ 10w 元素、输出 JSON ≤ 4 MB（src/query.ts:15-18、src/query.ts:223、src/query.ts:307）
  • 仓库内未发现 TODO / FIXME / HACK / XXX 注释

查看使用指南 →

该插件的安装步骤、关键要点、FAQ 与兼容性说明（基于已收录字段派生）。

收录徽章

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/omdsh-dev/dsh-toolkit/packages/dsh-tool-json)

把这段 markdown 粘贴到你的 GitHub README，链接回本插件详情页。徽章只声明已被本站收录，不代表安全认证。

返回插件目录