dsh-tool-schema

English

DSH JSON Schema 验证工具插件 —— 验证数据、列出失败路径、解释 schema 约束、安全应用 default。零网络、零动态代码执行。

动机

Agent 需要验证任意 JSON 数据是否符合 schema（API 响应结构、插件 manifest、配置文件、会话事件），并定位失败路径。现有路径没有这个能力：

1. defineTool 参数 DSL 是作者 DSL——面向插件作者声明工具参数，不是面向任意用户 schema 的通用验证服务
2. dsh-tool-json 只提供查询——能取路径、能筛选，但不验证结构、不给 RFC 6901 失败定位
3. 模型"目测"验证不可靠——复杂嵌套 schema（allOf/oneOf/$ref/pattern）组合下，手算通过/失败极易出错，且无法展示可验证的过程

本插件提供独立的纯函数 JSON Schema 验证内核：一次函数调用返回 verdict、路径化错误与 schema 问题。不执行任何代码、不访问网络，绝不静默忽略不支持的 schema 关键字。

安全模型

• 零动态执行：验证内核是纯数据遍历，不构造 RegExp（pattern 在独立 worker 内执行）、不 eval、不访问网络、不读文件
• 不支持关键字绝不静默忽略：报告 unsupported-keyword schema issue；strictSchema=true（默认）直接失败（valid:false / complete:false），strictSchema=false 验证已支持子集（valid:null / complete:false / supportedSubsetValid）
• ReDoS 防线：所有 pattern 校验在可终止的 worker 线程内共享 1,000ms 硬预算，超时 terminate() 并报错——灾难性回溯不能阻塞宿主进程；pattern ≤ 16 KiB、每 schema ≤ 100 个
• 原型污染防护：所有对象访问用 Object.hasOwn，__proto__ / constructor / prototype 只作为普通 JSON 键处理
• $ref 安全性：仅支持本地引用（# 与 #/$defs/，RFC 6901 转义）；目标必须存在；环检测（schema-check 静态报告 ref-cycle + 验证期 (schemaNode, instance) 栈动态兜底）
• 预算：
  • data / schema 各 ≤ 256 KiB（超限直接报错）
  • 嵌套深度 ≤ 64、schema 节点 ≤ 10,000、遍历节点 ≤ 100,000
  • 错误 100（默认）/ 1,000（上限）；$ref 链 ≤ 64
  • canonical 输出 ≤ 1 MiB（超限截断 errors/schemaIssues 等并置 truncated）
• 工具参数会记入会话日志，不要传入敏感数据

工具声明

注册 schema 工具（@deepseek-ai/dsh-tool-schema，row id tool-schema），统一输出 JSON 文本字符串。