[Ideas / 文档] 插件开发的工具 schema 两个隐藏校验：object 节点必须显式声明 additionalProperties；type 不支持联合数组

[truelove-dreamer]

建议分类：Ideas 或 General（开发者体验 / 文档）
环境：@deepseek-ai/dsh 0.1.0-rc.6，harness.defineTool 与 tools.register
严重级别：minor，但每个首次写工具的插件作者都会撞上，且官方文档未说明

摘要

用 harness.defineTool（动态插件）或 ctx.tools.register（外部插件）注册模型工具时，工具参数的 JSON Schema 校验有两个硬性限制，违反即注册失败：

1. 每个 object 节点必须显式声明 additionalProperties（true 或 false 都行），省略报 unsupported JSON schema: schema.additionalProperties must be explicitly true or false；
2. type 不支持联合数组（如 ["string","null"]），报 schema.properties.xxx.type must be string/number/integer/boolean/null/array/object/json, or use oneOf。

两个限制都不在官方文档/类型定义里明确写出，只有运行时错误。本文给出最小复现、绕过方式，并建议把这两条写进 docs/cookbook/adding-a-package.md（或放宽校验）。

复现

坑 1：object 节点省略 additionalProperties

const tool = harness.defineTool({
  name: "demo",
  description: "demo",
  parameters: { type: "object", properties: {} },
  output: {
    schema: {
      type: "object",
      properties: {           // ← 缺 additionalProperties
        result: { type: "string" }
      }
    },
    render: (args, value) => [{ type: "text", text: "ok" }]
  },
  execute: async () => ({ result: "ok" })
});
harness.registerTool(ctx, tool);

报错：

unsupported JSON schema: schema.additionalProperties must be explicitly true or false

注意：嵌套的每个 object 节点（如 properties.result 里再套 object）也要各自显式声明，不是只补顶层。

坑 2：type 联合数组

// 想让字段"可为 null"而写：
ref: { type: ["string", "null"] }

报错：

unsupported JSON schema: schema.properties.checks.items.properties.ref.type
must be string/number/integer/boolean/null/array/object/json, or use oneOf

绕过方式

• 坑 1：给每个 object 节点补 additionalProperties: false（推荐，报告/参数结构更严格）或 true。
• 坑 2：把可选字段直接声明为单一类型（如 ref: { type: "string" }），用"字段缺失"表达 null，不要用联合数组；需要真正的多类型时改用 oneOf。

建议（供讨论）

1. 把这两条写进官方文档——最合适的位置是 docs/cookbook/adding-a-package.md（或 plugin 开发指南），加一节 "Tool schema gotchas"；
2. 或放宽校验：additionalProperties 缺省时按 true 处理、type 数组在运行时做值校验即可——当前报错信息对新手不友好（"unsupported JSON schema" 没指出是哪个节点、怎么改）；
3. 至少把错误信息补上具体节点路径（当前坑 1 的报错不说是哪个 object 节点缺了）。

附注

• 本发现来自实际开发 4 个 dsh 插件的踩坑过程（search-gate / credential-guard / pwsh-utf8 / security-audit）；
• 这是纯开发者体验问题，不涉及运行时安全；但错误的报错信息会让首次插件作者卡很久。