前言¶

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，因爲已覈實資料中沒有明確給出可引用地址。