Preface¶

DeepSeek Harness (command name dsh) is an intelligent agent runtime open-sourced by DeepSeek AI, currently in developer preview. The official repository deepseek-ai/deepseek-harness states its core philosophy as “Everything is a plugin”: models, tools, skills, sessions, sandboxes, and interfaces can all be replaced at the configuration layer without modifying the core source code. There is also an independent community plugin directory site deepseek-harness-plugin.com, which has no official affiliation with DeepSeek / Fangxin and should not be treated as an official app store.

Handling JSON is a frequent operation for intelligent agents. API return values, configuration files, and outputs from other tools are almost all in JSON format. The common practice is to spawn a bash process to run node -e or jq, which incurs process overhead every time and requires serializing objects into strings first. The built-in grep in DSH can perform regular expression matching, but it does not understand JSON structure. For data like {"items":[{"id":1}]} string searches easily mix up values, key names, and identically named keys in nested objects.

The community plugin dsh-tool-json does a focused job: it registers a tool named json for the current profile, uses a JMESPath-style path subset for structured queries. The parser is implemented with a handwritten recursive descent approach and does not rely on third-party query libraries. This article is organized after cross-checking the plugin directory page, GitHub repository README / package.json / source code, and the official DeepSeek Harness repository.

What It Is¶

dsh-tool-json is a “tool and capability” plugin for DeepSeek Harness, maintained by the GitHub organization omdsh-dev, with the repository address at omdsh-dev/dsh-tool-json. It was added to the community directory on 2026-08-14, licensed under MIT (the LICENSE copyright statement is 2026 whiteicey), and primarily written in TypeScript. As of 2026-08-18, both the directory page and GitHub repository show 3 stars. The version number in the repository’s package.json is 0.0.1, which requires Node.js ^22.19.0 || >=24.0.0, and the README states compatibility with DSH 0.1.0-rc.6 (npm channel).

One-sentence positioning: After installation, the model can call the json tool to perform path queries on JSON objects or JSON strings and return matched values.

You need to distinguish between package names and sources first. The Cordis plugin name and the name field in package.json are both @deepseek-ai/dsh-tool-json, but this is the package name used by the community repository itself, with the private field set to true, which does not mean it is released to npm by DeepSeek officially. Third-party listings occasionally show installation commands like dsh plugin add @deepseek-ai/dsh-tool-json using the package name; both the directory page and the repository README use the GitHub source, and this article uses those two as the reference.

The same maintenance organization also has a collection repository omdsh-dev/dsh-toolkit, which will create vendored snapshots of multiple tools including the json tool. The number of tests in the collection may not be synchronized with the standalone repository. If you only need JSON query functionality, you can install the standalone repository as described in this article.

Core Features¶

The plugin entry is in src/index.ts, which registers the tool via ctx.tools.register(); the query logic is in src/query.ts, divided into three parts: parsing, execution, and input normalization. The tool name exposed to the model is json, with two required parameters:
- input: The JSON value to query, or a JSON string
- query: The path expression, for example data.items[0].name

The output is returned in JSON format and converted to text using JSON.stringify during rendering. The timeoutMs in the tool declaration is 1000 milliseconds.

Dual Form Inputs¶

The input has two forms, which are uniformly validated by normalizeInput():
1. Direct object passing: The model directly generates JSON parameters, eliminating one layer of escaping.
2. String pass-through: The original text obtained from bash, read, etc., can be sent as-is, and it will be parsed with JSON.parse internally.

Both paths perform JSON compatibility checks. Only null, booleans, finite numbers, strings, arrays, and plain objects are accepted; undefined, BigInt, functions, Date, non-finite numbers, own properties with accessors or non-enumerable properties will be rejected. Circular references will also trigger an error.

Query Syntax¶

The syntax is a custom subset inspired by JMESPath, not full JMESPath. The expressions provided in the repository README are as follows:

Tests also show that: an empty query returns the entire input; Chinese key names like 数据.名称 can be accessed using dot notation; when items[*] has no subsequent path, all elements in the array are returned.

Semantics that are intentionally inconsistent with standard JMESPath and have been locked in include:
- Multi-level wildcards items[*].tags[*] return nested arrays, for example [['a','b'],['c']], without standard projection flattening.
- Wildcards only apply to arrays, and do not support enumerating object fields.
| During projection, non-object elements will be skipped; missing properties (MISSING_PROPERTY) will also be skipped; valid null results will be retained.
- Type errors, out-of-bounds access, and invalid queries will throw exceptions, and will not be swallowed during projection.
- Quoted properties support three escape types: \\, \', \"; invalid escapes will trigger an error.

Filters [?downloads > 1000], pipes |, and function calls are not supported. The README recommends using bash with node as a fallback for such low-frequency scenarios.

Security Boundaries¶

The parser is a handwritten recursive descent parser, and the source code comments explicitly state that eval / new Function are not used; when reading properties, Object.hasOwn is used, and accessing constructor / __proto__ will not follow the prototype chain. Tests treat both types of key names as “non-existent properties”.

Resource limits are enforced uniformly on both the object input and string input paths, consistent between the repository README and src/query.ts:
- Query expression length must not exceed 200 characters, and parsing depth must not exceed 20 levels
- String input must not exceed 1,000,000 bytes (UTF-8); input nesting depth must not exceed 100
- A single wildcard projection must not exceed 100,000 elements
- There is also a 4 MB fuse for output (UTF-8 bytes after JSON.stringify)

A full validation of the input (type, depth, byte count, cycles, enumerability) is performed before each query. This is an intentional security cost: even if only a small field is fetched, the entire input will be scanned first. The README specifically notes that the timeoutMs cannot interrupt this synchronous validation.

The error type is JsonQueryError, with a unified json: prefix, categorized as MISSING_PROPERTY, TYPE_MISMATCH, INDEX_OUT_OF_BOUNDS, INVALID_QUERY.

Installation and Activation¶

The installation command provided on the directory page is as follows, run it in the DeepSeek Harness terminal:

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

The dsh CLI will parse the plugin from GitHub and load it into the current configuration. For reproducible installations, the directory page requires fixing the commit hash, with the syntax:

dsh plugin add github:omdsh-dev/dsh-tool-json#<commit>

As of 2026-08-18, the latest commit on the repository’s main branch is 902bdf60da4d85bc014e46d32070970a62bb5532 (2026-08-14). Pinning to this commit can be written as:

dsh plugin add github:omdsh-dev/dsh-tool-json#902bdf60da4d85bc014e46d32070970a62bb5532

The repository README recommends installing per profile. Under DSH 0.1.0-rc.6, web and headless have two different configurations:

# Interactive (web) profile
dsh plugin --profile web add github:omdsh-dev/dsh-tool-json

# One-off task (headless) profile; dsh run defaults to headless
dsh plugin --profile headless add github:omdsh-dev/dsh-tool-json

The package’s dsh.bundle.patch points to cordis.patch.yml, which will insert a tool-json entry into the profile’s layer stack after installation. The patch must be wrapped in a - insert: list; writing it as a bare - id: will trigger an entry not found error.

Verify that the web profile is installed:

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

The README also provides paths for local npm pack and installation via tarball, as well as old snapshot debugging steps by copying source code into the DSH monorepo. For daily use, the GitHub source method above is sufficient. When starting DSH, the official repository recommends using version-specified commands like npx -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web, and avoiding global installation with install -g.

Typical Usage¶

The calling forms provided in the repository README are:

json { input: <JSON>, query: "items[0].name" }        → "hello"
json { input: <JSON>, query: "items[*].name" }         → ["a", "b"] (valid nulls are retained)
json { input: <JSON>, query: "items['complex-key']" }  → "ok"

After installing to the headless profile, you can use a one-off task for smoke testing:

dsh run "Use the json tool to query a.b from {"a":{"b":1}}"

The following examples are from the repository tests, which help align with the semantics rather than being made-up business stories.

Dot notation and array indexing:

input:  {"foo":{"bar":42},"items":[{"name":"a"},{"name":"b"}]}
query:  foo.bar              → 42
query:  items[0].name        → "a"
query:  items[1].meta.version  (if the element has meta.version)

Array projection. If there are numbers or null mixed in items, these non-object elements will be skipped; objects missing the name property will also be skipped; a name value of null will be retained:

query:  items[*].name

Special key names use brackets:

query:  ['complex-key']

String input also works:

input:  "{\"a\":1}"
query:  a                    → 1

The plugin is read-only and cannot modify JSON fields. The README states that in-place modifications should continue to use str_replace_editor / write; the repository lists set mode as a possible future consideration, and it is not available in the current version.

Applicable Scenarios and Notes¶

It is suitable for these situations:
- The intelligent agent retrieves a field or a set of fields via path after obtaining JSON from APIs, configurations, or upstream tools
- You want to use structured path queries instead of using grep to search for identically named keys in plain text
- You do not want to spawn jq or node -e for a single value lookup

Situations where it is not suitable, or where you need to implement fallback logic yourself:
- You need conditional filtering ([?...]), pipes, or JMESPath functions
- You expect multi-level wildcards to automatically flatten arrays
- You need to modify JSON data
- The input may exceed 1 MB, have a nesting depth over 100, or a single array projection with over 100,000 elements

There are several items you need to verify on your own before installation:
1. The plugin runs with the permissions of the current dsh process and may execute code during installation. Please review the directory page, GitHub source code, and MIT license before installing.
2. The package name has the @deepseek-ai/ prefix, which only means that it follows the official tool package naming convention to integrate with Cordis, and does not represent official maintenance.
3. Installing the plugin to the web profile will not automatically make it available in the headless profile; dsh run uses the headless profile by default. Install it on both sides if you need to use it on both.
4. DeepSeek Harness is still in developer preview, and the official README notes that there will be breaking changes. This plugin explicitly aligns with version 0.1.0-rc.6 on the npm channel.

Summary¶

dsh-tool-json adds a very specific capability to DSH: reading JSON via in-process path queries, with a small syntax footprint, zero dependencies, and clear limits on length, depth, prototype chain access, and input forms. It is not a general-purpose JMESPath engine, nor does it modify data. If you just need the intelligent agent to extract items[0].name or items[*].id from tool outputs on a daily basis, this plugin matches the scope and installation commands on the directory page.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-tool-json/

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