DeepSeek Harness 插件挂载成功却注册 0 个工具？output schema 静默失败排查

插件显示已挂载、状态正常，但工具列表是空的，console.warn 一次都没触发 —— 先检查手写 register() 的 output.schema 是不是写了 { type: 'json' }。 据讨论 #9875，json 不在输出白名单 SCHEMA_TYPES 里，注册期校验会抛错，而抛错被 cordis fiber 接住送进 context.logger.error，部署没有对应日志出口时就表现为「零工具、零提示」。这不是插件没加载，而是工具被拒绝注册。

DeepSeek Harness 插件挂载成功却注册 0 个工具的三个事实

同时满足这三条，才说明你遇到的是注册被拒，而不是插件根本没启用。 逐条确认，避免和「插件未加载」混为一谈：

1. 插件在已加载列表里可见，profile 没有报加载失败，预期 apply 已经被调用。
2. 调用 ctx.tools.schemas() 或查看工具列表，预期返回数量为 0，说明注册没有留下任何工具。
3. 统计 console.warn 调用次数为 0，界面上也没有红色报错，预期失败被日志层吞掉了。
4. 如果插件注册了 4 个工具却全部消失，预期更像是整批注册在第一个坏 schema 处中断，而不是单个工具被跳过。

DeepSeek Harness 零工具时模型侧看到什么

工具没有进注册表，模型连「有这个工具」都不会知道，所以不会报错、只会绕开。 这解释了为什么用户感知是「功能没生效」而不是「插件坏了」：

1. 系统提示里的工具清单为空，预期模型没有可调用的目标。
2. 用户要求执行对应操作时，预期模型只能用文本回答或改用其他工具。
3. 插件详情页仍显示已加载，预期排查方向会被带到权限或网络。
4. 因为没有异常抛出，预期的重装插件也不会改变结果，除非改掉 schema。
5. 只有把 logger.error 接到可见出口，预期启动时才会看到「工具被拒绝」而不是一片安静。

DeepSeek Harness 调用链：register 在哪一步抛错，错误被谁吞掉

据讨论中社区核对源码，失败发生在注册期的 schema 断言，而不是工具执行期。 工具注册的完整契约可以对照 工具插件开发说明 看，这里只留五步：

1. register() 先检查 output.render 是否存在，预期缺失时直接拒绝。
2. 随后调用 assertSupportedJsonSchema(output.schema)，预期对输出 schema 做白名单校验。
3. SCHEMA_TYPES 只列了 object、array、string、number、integer、boolean、null，预期 json 不在其中，校验抛出违规。
4. 抛错向上冒泡到插件的 apply，预期被 cordis fiber 捕获并交给 context.logger.error。
5. 部署没有配置该级别日志出口时，预期插件挂载完成、注册表为空、控制台安静，三者同时成立。

DSH插件修法：defineTool、空 schema 还是提升错误

三条路都能让工具重新注册，差别在改的是作者写法、单个 schema，还是整个错误的可见性。 先改写法，再补错误出口，避免下一次又静默。

路径一：改用 defineTool，让 json 走编译

这是作者侧最省心的修法：把「编译 schema」这一步交回给 DSH，而不是手写 wire schema。 据讨论，defineTool 的 valueSchemaSpec 路径本来就接受 json，并把它编译成 {}。

1. 找到插件里手写的 ctx.tools.register({...}) 调用，预期能定位到工具定义处。
2. 改用 defineTool 包装，把工具名、描述、参数与输出 spec 传进去，预期工具通过包装器定义。
3. 输出仍可写 { type: 'json' }，预期 defineTool 在编译阶段转成无约束 schema。
4. 重新加载插件并调用 ctx.tools.schemas()，预期工具数量恢复，输出不再触发 SCHEMA_TYPES 违规。

const tool = defineTool({
  name: "read_meta",
  description: "读取插件元数据",
  parameters: { type: "object", properties: {} },
  output: { type: "json" },
})

路径二：手写 register 时用 {} 作无约束输出

如果必须保留手写 register()，就把 { type: 'json' } 换成 {}，这是编译后的等价形式。 空对象表示「任意 JSON 值」，也是校验器接受的形态。

1. 定位 output.schema 字段，预期能看到当前的输出契约。
2. 删除 type: 'json'，改成空对象 {}，预期 schema 变成空对象。
3. 如果原本靠 json 表达嵌套结构，改用 type: 'object' 加 properties，或保留 {} 并在 render 里自行收窄，预期 schema 要么表达结构、要么不带约束。
4. 重新加载并确认 ctx.tools.schemas() 数量正确，预期注册通过，模型侧收到的是不带类型约束的合法 schema。

ctx.tools.register({
  name: "read_meta",
  render: renderMeta,
  parameters: { type: "object", properties: {} },
  output: { schema: {} },
})

路径三：把注册拒绝提升到 UI 或启动日志

前两条修的是单个插件，这一条修的是「以后还会静默」的问题。 据讨论回复，注册期已经把契约违规当成 throw 处理，调用点能区分「被拒绝」和「本来就没有工具」。

1. 在 register() 的调用侧统计被拒绝的次数，预期能拿到「N 个工具在注册期被拒」。
2. 在插件启动完成时输出一行汇总，预期启动日志里出现这个计数。
3. 把该计数接到 DSH 插件市场 的详情页或系统日志面板，预期用户能看到插件「已加载但零工具」。
4. 在抛错信息里补一句可用替代：无约束输出写 {}，预期错误文本直接告诉作者该写什么。
5. 预期结果：同类错误不再需要翻源码才能定位，插件市场页也能提示异常状态。

DeepSeek Harness 插件注册的自检清单

用真实注册路径测一遍，比给 stub 写 282 个绿测试更有用。 讨论里提到，stub 版 register 什么都接受，正是「测试全绿、插件零工具」能共存的原因。

1. 测试里创建真实的 cordis Context 与 ToolRuntime，预期走的是生产注册路径。
2. 走 defineTool 或 register() 的真实路径注册工具，预期 stub 不挡在工具与运行时之间。
3. 断言 ctx.tools.schemas() 的数量与预期一致，预期数量不符时测试失败。
4. 单独构造一个 { type: 'json' } 的用例，预期它要么被编译、要么给出可读错误。
5. 把注册拒绝的计数与错误文本一起断言，预期同类问题在 CI 里失败，而不是等用户装上插件才发现。

来源：Discussion #9875。