dsh-capability-facade：为 DSH 插件作者提供窄工具面

前言¶

在 DeepSeek Harness (DSH) 插件开发中，常见的做法是将内部操作直接注册为模型可见的工具。这会导致模型面对一个巨大的工具清单，频繁发起多次独立的 root 调用，增加成本并降低确定性。

dsh-capability-facade 提供了一个 seam：插件作者声明一个语义明确的 capability，插件内部将这些 capability 映射为若干个模型可见的工具。这些工具在执行时，会按声明的顺序、确定性地运行已注册的底层工具。

它是什么¶

这是一个由 goatliamia 维护的参考实现与实验证据，许可证为 MIT。

核心价值：解决“插件工具面过宽”的问题。它通过声明语义能力，将原本分散的底层工具组合成一个确定性的管线，让模型只需进行一次调用即可完成原本需要多次往返的任务。

核心功能¶

声明语义能力：通过 ctx.capabilities.register 定义 capability 及其包含的 operations。
生成确定管线工具：将 operation 转换为模型可见的工具，内部通过 steps 数组编排底层工具的执行。
一次调用执行：模型只需调用一次 facade 工具，harness 内部完成嵌套 dispatch，跑完整个管线。
继承约束：facade 生成的工具会继承底层实现工具的守卫和审批约束。
窄工具面：帮助插件作者在设计之初就控制模型可见的工具数量。

安装与启用¶

安装命令如下，请将 <profile> 替换为你的实际 profile 名称：

dsh plugin --profile <profile> add dsh-capability-facade-<version>.tgz

安装后，可以通过 --dump-config 检查配置中是否包含该插件：

dsh --profile <profile> --dump-config

典型用法¶

插件需要注入 capabilities 服务。关键点：底层实现工具必须先于 facade 注册，否则注册会直接报错（fail-loud）。

export const inject = ['tools', 'capabilities']

export function apply(ctx) {
  // 1. 先注册底层实现工具
  ctx.tools.register(extractTool)
  ctx.tools.register(layoutTool)

  // 2. 声明 capability
  ctx.capabilities.register({
    id: 'pdf',
    description: 'Read a PDF document: text, layout and OCR in one deterministic sequence.',
    operations: [
      {
        name: 'analyze',
        description: 'Extract text and layout from a PDF in one call.',
        parameters: {
          path: { type: 'string', required: true }
        },
        steps: [
          { tool: 'pdf_extract' },
          // from 指定从上一步的输出中获取参数
          { tool: 'pdf_layout', from: 'layout' }
        ],
      },
    ],
  })
}

执行后，模型看到的工具名为 pdf_analyze，描述中包含管线步骤说明。Harness 会确保这些步骤在同一个 root call 下执行。

适用场景与约束¶

适用场景¶

适合希望将多个底层工具组合成一个高语义操作的插件。对于能够稳定组合回答同一问题的工具集，使用 facade 可以显著减少模型调用轮次。

关键约束¶

不能隐藏已暴露的工具：DSH 的工具注册表使用同一个 visibility resolver 决定展示、查找和分发。因此，如果一个底层工具已经被注册为模型可见，facade 无法将其“藏”起来。它只能帮作者一开始就写窄。
实现工具必须先注册：facade 注册依赖于底层工具的存在，顺序错误会导致注册失败。
当前状态：这是一个“参考实现 + 实验证据”，并非用户可直接安装的成品产品。

总结¶

dsh-capability-facade 的核心在于将“工具编排”从模型的决策中移除，交由插件作者通过代码声明。它通过确定性的管线执行，将多次 root 调用合并为一次，同时保留了底层工具的守卫和审批机制。

项目主页：https://github.com/goatliamia/dsh-capability-facade
插件目录：https://www.skillhub.cn/plugins/goatliamia/dsh-capability-facade