本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-tool-json

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add github:omdsh-dev/dsh-toolkit#path:packages/dsh-tool-json

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

常见问题

这个工具和 DSH 内置的 grep 比有什么差别？

grep 只做字符串级正则匹配，容易把同名 key、值或嵌套子对象混在一起；json 走结构化路径，只匹配指定位置的字段，行为更精准，也省掉 grep 误匹配的麻烦。

为什么不直接用 jq？

调用 jq 要起一个 bash 进程跑命令，DSH 每次都付进程启动 + 字符串序列化成本，且 shell 注入风险需要 shell escaping 兜底；本工具是毫秒级纯函数调用，输入解析与转义全部由插件内部消化。

支持哪些路径语法？

点号访问（foo.bar）、方括号数组索引（items[0]）、方括号属性（items['key'] 或 items["key"]，支持 \ ' " 转义）、数组通配符投影（items[*].name）；以上可自由组合。底层是手写的递归下降解析器，没有依赖任何 JMESPath 标准库。

不支持哪些 JMESPath 功能？

不支持过滤器表达式（[?downloads > 1000]）、管道（|）、函数调用（to_string/sort 等）；多级通配符 items[].tags[] 返回嵌套数组而非标准 JMESPath 的扁平化结果；通配符只能作用数组，不能枚举对象字段。

输入是 JSON 对象还是 JSON 字符串？

两种都接受。input 字段声明为 json 类型，模型可以直接传 JSON 对象（零转义），也可以传字符串（bash/read 拿到的原文）；normalizeInput() 会统一走 JSON 解析与兼容性校验。

查询有超时吗？输入太大怎么办？

工具调用超时 1 秒（src/index.ts:48 timeoutMs: 1000）；输入侧对 JSON 字符串 UTF-8 字节数、对象累计字节数、嵌套深度、wildcard 投影元素数都有硬上限（字符串 1MB、嵌套 100 层、投影 10w 元素），超出直接抛 JsonQueryError(INVALID_QUERY)。

能修改 JSON 字段吗？

不能，这是只读工具。需要原地修改字段请用 str_replace_editor/write 等文本编辑工具。

装到 web profile 后 dsh run 能用到吗？

不能。web 与 headless 是两个独立 profile，dsh run 默认走 headless，所以 headless profile 也需要单独装一次。

— 源: plugin_wiki.faq_json

兼容性

• DSH: 0.1.0-rc.8+
• Node: >=22.19.0
• Platforms: macOS, Windows, Linux

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则