dsh-tool-json DSH 插件

本插件提供 `json` 工具，让 DSH Agent 可以用路径表达式查询 JSON 结构，语法类似 JMESPath。它旨在替代启动 bash 进程执行 `node -e` 或 `jq` 的方式，更加轻量安全。采用手写递归下降解析器，无 eval，防止原型链污染，并设有资源上限。

developer-tools

如何安装 dsh-tool-json DSH 插件

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

复制不会执行命令。安装 dsh-tool-json DSH 插件前请核对仓库和版本。

dsh-tool-json DSH 插件数据来源

dsh-tool-json DSH 插件快照日期：2026年8月16日

discovered

dsh-tool-json DSH 插件能做什么

使用点号、方括号索引、方括号属性、数组通配符投影等方式查询 JSON。
支持嵌套组合，例如 `a.b[0].c.d`。
接受对象（模型直接生成）或字符串（bash/read 透传）两种输入形态。
资源上限限制：查询表达式长度 ≤200 字符、深度 ≤20 层、输入 ≤1MB、嵌套深度 ≤100、通配符投影 ≤100,000 元素。
错误分类清晰：缺失属性、类型不匹配、索引越界、查询语法错误等。

dsh-tool-json DSH 插件适合哪些场景

从 API 返回的 JSON 中提取特定字段，无需调用外部工具如 jq 或 node。
查询 JSON 格式的配置文件，获取下游任务所需的设置项。
验证或检查工具输出的 JSON 内容，使用结构化路径而非正则匹配。
通过通配符投影提取数组元素属性，例如 `items[*].name`。
调试复杂嵌套 JSON 结构，使用路径表达式导航。

dsh-tool-json DSH 插件适合谁

需要处理 JSON 数据的 DSH Agent 开发者。
希望在 DSH 环境内安全、高效地查询 JSON 的用户。

dsh-tool-json DSH 插件的限制

只读：不能修改 JSON 字段，修改请使用 `str_replace_editor` 或 `write` 等其他工具。
不支持过滤器表达式（如 `[?downloads > 1000]`）、管道符或函数调用。
通配符仅作用于数组，不作用于对象字段；嵌套通配符返回嵌套数组，不做扁平化。
对象形态输入依赖 DSH 参数管线保证 JSON 无损传递。

dsh-tool-json DSH 插件的仓库 README 摘录

以下文字摘自 dsh-tool-json DSH 插件的上游仓库 omdsh-dev/dsh-tool-json 的 README，版权归原作者，仅作引用。

DSH JSON 查询工具插件 —— JMESPath-inspired 路径查询（自定义子集），零依赖递归下降解析器。 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ## 为什么需要 Agent 处理 JSON 是高频操作——API 返回值、配置文件、工具输出到处都是 JSON。当前做法是起 bash 进程跑 `node -e` 或 `jq`，每次都有进程开销和字符串序列化成本。 DSH 内置 `grep` 可以做正则匹配，但无法理解 JSON 结构。对于 `{"items":[{"id":1}]}`： - `grep` 只能做字符串级搜索，容易误匹配值、key、或嵌套子对象中的同名 key - `json` 走结构化路径，只匹配指定路径，不混淆 key 和 value ## 安全模型手写递归下降解析器，无 `eval`/`new Function`；`Object.hasOwn` 防原型链污染（`constructor`/`__proto__` 读取不触发原型链）。资源上限（**对象与字符串两条输入路径统一执行**）： - 查询表达式长度 ≤ 200 字符、解析深度 ≤ 20 层、数组索引必须是安全整数 - 字符串输入 ≤ 1,000,000 bytes（UTF-8）；输入嵌套深度 ≤ 100 - 单次 wildcard 投影 ≤ 100,000 元素 - 只接受 JSON-compatible 值（null/boolean/有限 number/string/array/plain object；拒绝 undefined/BigInt/函数/Date/非有限数）错误分类（`JsonQueryError`）：`MISSING_PROPERTY`（投影内跳过）、`TYPE_MISMATCH`/`INDEX_OUT_OF_BOUNDS`/`INVALID_QUERY`（如实抛错），统一 `json:` 前缀。 > 成本模型（AUDIT-JSON-03）：输入在每次查询前执行**全量校验**（类型/深度/字节/循环/枚举性）——这是有意的安全成本，查询小字段也会完整扫描输入；`timeoutMs` 无法中断同步校验。 ## 架构 ``` DSH Agent │ ctx.tools.register() ▼ src/index.ts（Cordis 插件入口 + action 分发） │ ▼ src/query.ts ├── parseQuery() — 递归下降解析器（strict 语法 + 转义 + 上限） ├── executeQuery() — 执行器（错误分类 + 投影上限）

阅读完整 README仓库许可: MIT

dsh-tool-json DSH 插件常见问题

如何安装 dsh-tool-json 插件？

通过 DSH 命令行安装：`dsh plugin --profile web add github:omdsh-dev/dsh-tool-json`（web 配置）或 `dsh plugin --profile headless add github:omdsh-dev/dsh-tool-json`（headless 配置）。安装后运行 `dsh --profile web --dump-config | grep tool-json` 验证。

json 工具支持什么查询语法？

支持自定义的 JMESPath 子集语法：点号访问嵌套对象（如 `foo.bar`）、方括号数组索引（如 `items[0]`）、方括号属性访问特殊字符键（如 `items['key']`）、数组通配符投影（如 `items[*].name`）。不支持过滤器、管道符或函数调用。

json 工具能修改 JSON 数据吗？

不能，工具是只读的。如果需要修改 JSON，请使用其他 DSH 工具如 `str_replace_editor` 或 `write`。未来版本可能增加 `set` 模式。

json 工具有哪些输入限制？

查询表达式长度 ≤200 字符，深度 ≤20 层。输入字符串 ≤1,000,000 字节（UTF-8），嵌套深度 ≤100。通配符投影最多 100,000 个元素。每次查询前会完整扫描输入，这是有意为之的安全开销。

json 工具如何处理错误？

错误分为几类：`MISSING_PROPERTY`（在投影内跳过）、`TYPE_MISMATCH`、`INDEX_OUT_OF_BOUNDS`、`INVALID_QUERY`（这些会抛出）。所有错误带 `json:` 前缀。解析器手写，无 eval，通过 `Object.hasOwn` 防止原型链污染。