前言¶

在 DSH 插件開發中，Agent 經常需要讀取 API 返回值、配置文件或工具輸出裏的 JSON。如果只用字符串搜索，容易把 key、value 和嵌套對象中的同名 key 混在一起；如果引入完整 JSON 查詢引擎，成本又不一定適合輕量工具。

omdsh-dev/dsh-tool-json 是一個 DSH 工具插件：它註冊一個名爲 json 的工具，接受 JSON value 或 JSON string 作爲輸入，並用一條 JMESPath-inspired 路徑查詢（自定義子集）取字段。下面介紹它的定位、能力、安裝方式和注意事項。

這是什麼¶

這是一個只讀 JSON 查詢插件。

倉庫：omdsh-dev/dsh-tool-json
包名：@deepseek-ai/dsh-tool-json
維護者：omdsh-dev
許可證：MIT
當前 package.json 版本：0.0.1
適配 DSH：0.1.2-alpha.2（npm）
安裝方式：支持 Profile Bundle，也支持 npm pack tarball 安裝

它提供 DSH 工具 json。調用時傳入 input 和 query：input 是要查詢的 JSON value 或 JSON string，query 是路徑表達式。插件執行查詢後返回對應字段值。

核心功能¶

提供 json 工具¶

工具聲明中的參數包括：

input: {
  type: 'json',
  required: true,
  description: 'JSON value or JSON string to query.'
}

query: {
  type: 'string',
  required: true,
  description: 'Path expression, e.g. "data.items[0].name".'
}

input 支持兩種形態：對象直傳，或 JSON string 傳入。插件通過 normalizeInput 做統一歸一化與校驗。工具聲明中的超時時間爲：

timeoutMs: 1000

查詢子集¶

該插件支持 JMESPath-inspired 路徑查詢的子集，不實現完整 JMESPath。

常見表達式包括：

表達式	示例	說明
點號訪問	`a.b`	訪問嵌套對象屬性
方括號數組索引	`items[0]`	訪問數組元素
方括號引號屬性	`items['complex-key']`	訪問含特殊字符的屬性名
數組通配符投影	`items[*].name`	對數組元素提取指定屬性
組合嵌套	`a.b[0].c.d`	以上形式自由組合

它只作用於查詢取值，不修改 JSON 字段。

錯誤模型¶

查詢錯誤統一歸類爲 JsonQueryError，並帶 json: 前綴。

已覈實的錯誤類型包括：

MISSING_PROPERTY
TYPE_MISMATCH
INDEX_OUT_OF_BOUNDS
INVALID_QUERY

其中，MISSING_PROPERTY 在投影內跳過；TYPE_MISMATCH、INDEX_OUT_OF_BOUNDS、INVALID_QUERY 會如實拋出。

查詢語法¶

下面介紹幾個典型路徑表達式。

單值查詢¶

json { input: <JSON>, query: "items[0].name" }

示例返回：

"hello"

數組投影¶

json { input: <JSON>, query: "items[*].name" }

示例返回：

["a", "b"]

合法 null 會保留。

特殊 key 查詢¶

json { input: <JSON>, query: "items['complex-key']" }

示例返回：

"ok"

多級通配符¶

items[*].tags[*] 這類多級通配符會返回嵌套數組，不做標準 JMESPath 投影扁平化。

例如標準 JMESPath 可能期望扁平數組，但該插件返回的是嵌套結構。

語義邊界¶

這個插件有意不兼容完整 JMESPath。

已覈實的限制包括：

通配符僅作用於數組
不支持對象字段枚舉
多級通配符返回嵌套數組
不做標準 JMESPath 投影扁平化
不支持過濾器表達式，例如 [?downloads > 1000]
不支持管道 |
不支持函數調用

如果你的需求是修改 JSON 字段，這個插件不適合，因爲它只讀，不能修改 JSON 字段。

安全與資源限制¶

插件使用手寫遞歸下降解析器，不使用 eval 或 new Function。在對象屬性訪問時使用 Object.hasOwn，避免觸發原型鏈。

已覈實的資源上限如下：

查詢表達式長度：≤ 200 字符
解析深度：≤ 20 層
字符串輸入：≤ 1,000,000 bytes
輸入嵌套深度：≤ 100
單次 wildcard 投影：≤ 100,000 元素

輸入只接受 JSON-compatible 值：

null
boolean
有限 number
string
array
plain object

需要注意：輸入在每次查詢前會執行全量校驗。由於校驗是同步過程，timeoutMs 無法中斷同步校驗。

安裝與啓用¶

確認依賴¶

該插件適配 DSH 0.1.2-alpha.2（npm）。

package.json 中的 engines 要求：

"node": "^22.19.0 || >=24.0.0"

peerDependencies 要求：

{
  "@deepseek-ai/cordis": "^4.0.1",
  "@deepseek-ai/dsh-invariants": ">=0.0.1-rc.1 <0.2.0",
  "@deepseek-ai/dsh-tools": ">=0.0.1-rc.1 <0.2.0"
}

按 profile 安裝¶

web 與 headless 是不同 profile。web 安裝不會自動覆蓋 headless；dsh run 默認使用 headless profile。

如果要安裝到 web profile：

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

如果要安裝到 headless profile：

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

選擇哪個 profile，取決於你後續用 web 還是 dsh run。

Profile Bundle 機制¶

包內 package.json 的 dsh.bundle.patch 指向：

./cordis.patch.yml

安裝後，插件會進入 profile 的 layer stack。插件的 cordis.patch.yml 使用 - insert: 列表插入條目。

如果使用裸 - id: 條目，會報 entry not found。正確寫法應使用 - insert: 列表包裹。

驗證安裝¶

可以檢查配置中是否出現該插件條目：

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

npm pack tarball 安裝¶

也可以本地打包後安裝：

npm pack
dsh plugin --profile web add ./dsh-tool-json-*.tgz
dsh plugin --profile headless add ./dsh-tool-json-*.tgz

發佈 tarball 包含：

lib/
src/
cordis.patch.yml

典型用法¶

下面是插件文檔中給出的查詢示例。

查詢單個字段¶

json { input: <JSON>, query: "items[0].name" }

"hello"

查詢數組中多個字段¶

json { input: <JSON>, query: "items[*].name" }

["a", "b"]

合法 null 會保留。

查詢帶特殊字符的 key¶

json { input: <JSON>, query: "items['complex-key']" }

"ok"

通過 dsh run 調用¶

可以要求 DSH 使用 json 工具完成查詢：

dsh run "使用 json 工具查詢 {"a":{"b":1}} 的 a.b"

適用場景與注意¶

適合的場景¶

從 JSON 中按明確路徑取值
查詢數組中固定結構字段
查詢含特殊字符的屬性名
在 DSH Agent 中替代臨時腳本做只讀 JSON 取值

不適合的場景¶

需要修改 JSON 字段
需要過濾器表達式
需要管道 |
需要函數調用
需要對象字段枚舉
需要標準 JMESPath 的投影扁平化行爲

安全注意¶

插件會在當前 dsh 進程權限下執行查詢。安裝前應先檢查源碼與許可證，確認其行爲符合你的安全要求。

該插件是 MIT 許可，公開倉庫地址爲：

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

結尾¶

omdsh-dev/dsh-tool-json 解決的是一個具體問題：在 DSH 中用結構化路徑從 JSON 裏取值。它不替代完整 JMESPath，而是提供一個零依賴、只讀、有明確資源上限的查詢子集。

如果你需要在 web 或 headless profile 中讓 Agent 穩定讀取 JSON 字段，可以先按目標 profile 安裝，再用 dsh --profile <profile> --dump-config 驗證插件是否進入配置。

源碼地址：

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

omdsh-dev/dsh-tool-json：DSH JSON 查詢工具插件

前言¶

這是什麼¶

核心功能¶

提供 json 工具¶

查詢子集¶

錯誤模型¶

查詢語法¶

單值查詢¶

數組投影¶

特殊 key 查詢¶

多級通配符¶

語義邊界¶

安全與資源限制¶

安裝與啓用¶

確認依賴¶

按 profile 安裝¶

Profile Bundle 機制¶

驗證安裝¶

npm pack tarball 安裝¶

典型用法¶

查詢單個字段¶

查詢數組中多個字段¶

查詢帶特殊字符的 key¶

通過 dsh run 調用¶

適用場景與注意¶

適合的場景¶

不適合的場景¶

安全注意¶

結尾¶

精选优惠券

omdsh-dev/dsh-tool-json：DSH JSON 查詢工具插件

前言¶

這是什麼¶

核心功能¶

提供 json 工具¶

查詢子集¶

錯誤模型¶

查詢語法¶

單值查詢¶

數組投影¶

特殊 key 查詢¶

多級通配符¶

語義邊界¶

安全與資源限制¶

安裝與啓用¶

確認依賴¶

按 profile 安裝¶

Profile Bundle 機制¶

驗證安裝¶

npm pack tarball 安裝¶

典型用法¶

查詢單個字段¶

查詢數組中多個字段¶

查詢帶特殊字符的 key¶

通過 dsh run 調用¶

適用場景與注意¶

適合的場景¶

不適合的場景¶

安全注意¶

結尾¶

精选优惠券

相關文章