dsh-json-flat-plugin

August 17, 2026 · View on GitHub

English | 中文

本插件属于 dsh-plugins 合集，完整的自研插件索引见该仓库。

Persistent DeepSeek Harness bundle wrapping the jstool.py JSON flat view / edit tool as model-facing Cordis tools. Plain-JS reimplementation of the json-flat-tool skill (flat view, schema inference, search, and path-based editing), so the agent can inspect and modify JSON directly instead of shelling out to a Python script.

What it provides

Tool	What it does
`json_flat_view`	Flatten a JSON value into `path / type / value` rows. Supports schema mode (collapse `[N]→[*]`, dedupe, hide values), a `filter` path (element-aware), and row/element-level pagination (`limit` / `offset` / `elemOffset` / `elemLimit`).
`json_flat_schema`	Infer a JSON Schema Draft-7 structure (array sampling up to 20 items, `required` = non-empty fields).
`json_flat_find`	Search flattened paths and/or values by regex (default) or glob (`*` matches any string), case-insensitive optionally.
`json_flat_edit`	Path-based editing: `set` / `del` / `set-null` / `before` / `after` / `copy` / `merge`. Defaults to a dry-run preview with a compact per-path diff; pass `apply: true` to write back through the `fs` service.

Inputs

read-only tools accept source (inline JSON text or @file) and/or file (a path resolved through the fs service). Inline JSON works even without fs.
json_flat_edit requires the fs service and always works on file. A dry-run returns changes but never writes; apply: true atomically writes the result back.
@ prefix and @@ escape: a string argument (source or value) starting with a single @ reads JSON from that file. To write a literal string that starts with @ (e.g. an npm scoped package name like @scope/name), escape it with @@: @@pkg writes the literal @pkg (no file read, no JSON parsing).

Path syntax

count             root-level key
users[0]          array element
users[0].name     nested key
root[0].key       root-array element key
root              the root node itself

Design notes

Pure algorithmics live in json-flat-core.js (deterministic, no runtime dependencies) so they can be unit-tested standalone and reused without the DSH runtime.
Mutating edits capture a deep clone before applying so the returned diff compares against the pre-mutation state (the apply* helpers mutate in place).
The Loader entry (index.js) is failure-isolated: the optional fs service and all heavy imports are resolved inside apply(), so a missing service or a load error degrades to a diagnostic instead of taking down the profile.
Read-only tools never write; editing is apply: true-opt-in so accidental mutation is avoided.

Development

node --test test.mjs   # core algorithmics
node smoke.mjs         # tool registration + end-to-end via mock ctx + fs

Installation

复制下面的指令块给你的 DSH agent，它会自动完成安装：

请安装 json-flat 插件（@doiiarx/dsh-json-flat-plugin）：

1. 前置：本机已有 deepseek-harness 源码（本插件 link 依赖其中的 dsh-tools 包，
   位于 <deepseek-harness>/packages/core/tools）。
2. 克隆仓库：
   git clone https://github.com/DoiiarX/dsh-json-flat-plugin
   cd dsh-json-flat-plugin
3. 安装依赖：pnpm install
   （如果 package.json 里 dsh-tools 的 link 路径与你机器不符，改成你的
   deepseek-harness 实际路径后再装。）
4. 挂进 web profile：编辑 $HOME/.dsh/profiles/web/package.json，
   在 dependencies 加 "@doiiarx/dsh-json-flat-plugin": "link:<本插件目录绝对路径>"，
   在 dsh.profile.bundles 加 "@doiiarx/dsh-json-flat-plugin"。
5. 在 profile 目录执行 pnpm install。
6. 重启 web 进程，验证工具列表出现 json_flat_view / json_flat_find /
   json_flat_edit 等工具。

本插件无设置页，不需要改 WEB_SETTINGS_NAMESPACES 白名单。