前言¶

Agent 处理 JSON 时，经常要确认某个对象是否符合 schema，并且要能指出哪里不符合。只查询字段还不够，靠模型直接判断在复杂嵌套结构下也不稳定。dsh-tool-schema 把这件事做成一次工具调用：给定 schema 和 data，返回验证结论、失败路径、schema 约束解释，以及可选的 default 应用结果。

这是什么¶

dsh-tool-schema 是 DSH 插件，仓库位于 omdsh-dev/dsh-tool-schema，MIT 许可。它提供一个本地 JSON Schema 验证工具，核心定位是：验证数据、列出失败路径、解释 schema 约束、安全应用 default。插件强调零网络、零动态代码执行，并在固定资源限制内运行。

核心功能¶

validate¶

validate 用于验证一个 instance 是否符合给定 schema。

它会返回：

• 验证结论
• 使用 RFC 6901 instancePath / schemaPath 的错误定位
• schemaIssues
• checkedNodes
• truncated

这个动作适合需要完整验证结果和错误路径时使用。

paths¶

paths 只返回失败路径。

它会返回：

• 失败路径
• 关键字摘要
• errorCount
• truncated

如果只需要快速定位“哪里错了”，可以用这个动作，避免返回过多完整错误信息。

explain¶

explain 用于静态解释 schema 约束。

它会输出：

• 约束树节点序列
• schemaIssues
• truncated

这个动作不依赖具体 data，适合先理解 schema 本身会约束哪些字段和值。

normalize¶

normalize 会先深拷贝数据并应用显式 default，再进行验证。

它会返回：

• appliedDefaults
• warnings
• 完整 validate 结果

它适合需要在验证前补齐默认值的场景，但不会修改原始输入。

安全与限制¶

插件的验证内核是纯函数风格，目标是避免执行不可控代码。

主要约束如下：

• 零网络
• 零动态代码执行
• pattern 在可终止 worker 内执行
• pattern 共享 1,000ms 硬预算，用于防止 ReDoS
• 本地 $ref 支持 # 与 #/$defs/<token>，并使用 RFC 6901 转义
• 支持环检测
• 不支持的 schema 关键字会报告 unsupported-keyword
• strictSchema=true 时，遇到不支持关键字直接失败
• strictSchema=false 时，验证已支持子集，并返回 supportedSubsetValid

资源限制如下：

• data / schema 各不超过 256 KiB
• 嵌套深度不超过 64
• schema 节点数不超过 10,000
• 遍历节点数不超过 100,000
• 错误默认 100，上限 1,000
• $ref 链不超过 64
• canonical 输出不超过 1 MiB
• 超限后会截断并标记 truncated

安装与启用¶

下面给出 web profile 的安装方式。

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

安装完成后，可以检查 profile 配置中是否出现插件：

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

如果使用本地构建产物，也可以通过 tarball 路径安装：

npm pack
dsh plugin --profile web add <npm pack 产物 tarball 路径>

Windows 路径建议使用正斜杠，例如：

C:/path/to/xxx.tgz

兼容性方面，该插件已核实兼容 DSH 0.1.2-alpha.2。启动方式如下：

npx -p @deepseek-ai/dsh@next dsh web

不要使用 install -g 做全局安装。

需要注意，web 与 headless 是不同 profile。dsh run 默认使用 headless profile。如果要用 dsh run 触发该插件，需要确保插件已安装到对应 profile。

典型用法¶

安装到可用 profile 后，可以用下面命令让 DSH 调用 schema 工具做验证：

dsh run "用 schema 工具验证 {name: 'x', age: 3} 是否符合给定 JSON Schema"

工具参数方面：

• action 可选 validate、paths、explain、normalize
• schema 必填
• data 对 validate、paths、normalize 必需
• strictSchema 默认 true

适用场景与注意¶

适合以下场景：

• 验证 API 响应、插件 manifest、配置文件、会话事件等 JSON 数据
• 定位 schema 校验失败路径
• 静态解释 schema 约束
• 在验证前安全应用显式 default

使用注意：

• 插件会随当前 DSH 进程运行，请以当前 dsh 进程权限理解其行为
• 安装前应检查源码、依赖范围与 MIT 许可证
• 工具参数会记入会话日志，不要传入敏感数据
• 不要把不支持的关键字当作静默忽略；插件会报告 unsupported-keyword
• pattern 校验有独立 worker 预算，但仍应避免传入过大的 schema 和 data
• web 安装不会自动覆盖 headless profile

结尾¶

dsh-tool-schema 的价值在于把 JSON Schema 验证变成一次可检查、可定位、有边界的本地工具调用。它不访问网络，不动态执行代码，并且在错误路径、schema 问题、default 应用和资源限制上给出明确反馈。

GitHub 仓库：

• https://github.com/omdsh-dev/dsh-tool-schema

本文未列出社区目录页 URL，因为已核实资料中没有明确给出可引用地址。