Skip to content
  • Home
  • Plugin manual
  • dsh-tool-json

omdsh-dev/dsh-tool-json

30Last commit Aug 14, 2026

dsh-tool-json DSH plugin

This plugin provides a `json` tool that allows DSH agents to query JSON structures using a path expression syntax similar to JMESPath. It is designed to be a lightweight, secure alternative to spawning bash processes for JSON manipulation. It features a hand-written recursive descent parser without eval, prototype pollution protection, and resource limits.

developer-tools

How to install the dsh-tool-json DSH plugin

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

Copying does not run this command. Review the repository and version before installing the dsh-tool-json DSH plugin.

dsh-tool-json DSH plugin data source

dsh-tool-json DSH plugin snapshot date: Aug 16, 2026

discovered

What the dsh-tool-json DSH plugin can do

  • Query JSON using dot notation, bracket indexing, bracket property access, and wildcard projection on arrays.
  • Supports nested combinations like `a.b[0].c.d`.
  • Accepts input as a JSON object (direct from model) or a JSON string (for bash/read passthrough).
  • Enforces resource limits: query length ≤200 chars, depth ≤20, input ≤1MB, nesting ≤100, wildcard projection ≤100,000 elements.
  • Error classification with specific error types (missing property, type mismatch, index out of bounds, invalid query).

Where the dsh-tool-json DSH plugin fits

  • Extract specific fields from API responses without invoking external tools like jq or node.
  • Query configuration files in JSON format to retrieve settings for downstream tasks.
  • Validate or inspect tool outputs that are JSON-encoded, using structured path queries instead of regex.
  • Extract items from arrays using wildcard projections, e.g., `items[*].name`.
  • Debug complex nested JSON structures by navigating with path expressions.

Who the dsh-tool-json DSH plugin is for

  • DSH agent developers who need to process JSON data in tool calls.
  • Users who want a safe, low-overhead JSON query tool inside the DSH environment.

dsh-tool-json DSH plugin limitations

  • Read-only: cannot modify JSON fields; use other tools like `str_replace_editor` or `write` for mutations.
  • No support for filter expressions like `[?downloads > 1000]`, pipes, or function calls.
  • Wildcard only works on arrays, not object fields; nested wildcards return nested arrays without flattening.
  • Object-form input relies on the DSH parameter pipeline to guarantee lossless JSON serialization.

dsh-tool-json DSH plugin: from the repository README

Quoted from the omdsh-dev/dsh-tool-json README, the upstream source of the dsh-tool-json DSH plugin. Copyright remains with the original authors.

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() — 执行器（错误分类 + 投影上限）

Read the full READMERepository license: MIT

dsh-tool-json DSH plugin questions

How do I install the dsh-tool-json plugin?

You can install it via the DSH CLI using the command `dsh plugin --profile web add github:omdsh-dev/dsh-tool-json` for the web profile, or `dsh plugin --profile headless add github:omdsh-dev/dsh-tool-json` for the headless profile. After installation, verify with `dsh --profile web --dump-config | grep tool-json`.

What syntax does the json tool use for querying?

The tool supports a custom JMESPath-inspired subset. You can use dot notation for nested objects (e.g., `foo.bar`), bracket indexing for arrays (e.g., `items[0]`), bracket property access for keys with special characters (e.g., `items['key']`), and wildcard projection on arrays (e.g., `items[*].name`). It does not support filters, pipes, or function calls.

Can the json tool modify JSON data?

No, the tool is read-only. It cannot modify JSON fields. If you need to modify JSON, use other DSH tools such as `str_replace_editor` or `write`. A future version might add a `set` mode.

What are the input limits for the json tool?

The query expression must be ≤200 characters and ≤20 layers deep. The input string must be ≤1,000,000 bytes (UTF-8) and nesting depth ≤100. Wildcard projections are limited to 100,000 elements. The tool performs a full validation scan of the input before each query, which may be a security cost.

How does the json tool handle errors?

Errors are classified into specific types: `MISSING_PROPERTY` (skipped in projections), `TYPE_MISMATCH`, `INDEX_OUT_OF_BOUNDS`, and `INVALID_QUERY` (thrown as errors). All errors are prefixed with `json:`. The tool uses a hand-written parser without eval, and protects against prototype pollution via `Object.hasOwn`.