Introduction

In DeepSeek Harness (DSH) plugin development, a common approach is to register internal operations directly as model-visible tools. This can lead to models facing a large tool inventory, frequently issuing multiple independent root calls, increasing cost and reducing determinism.

dsh-capability-facade provides a seam: plugin authors declare a semantically clear capability, and the plugin internally maps that capability to model-visible tools. When executed, these tools run the registered underlying tools deterministically in the declared order.

What It Is

This is a reference implementation and experimental evidence maintained by goatliamia, licensed under MIT.

Core value: solves the “plugin tool surface is too broad” problem. By declaring semantic capabilities, it combines previously scattered underlying tools into a deterministic pipeline, allowing the model to complete tasks that previously required multiple round trips with a single call.

Core Features

  1. Declare semantic capabilities: define a capability and its operations via ctx.capabilities.register.
  2. Generate deterministic pipeline tools: convert operations into model-visible tools, internally orchestrating underlying tool execution through a steps array.
  3. Execute with a single call: the model only needs to call the facade tool once, and the harness completes the nested dispatch internally, running the entire pipeline.
  4. Inherit constraints: tools generated by the facade inherit the guard and approval constraints of the underlying implementation tools.
  5. Narrow tool surface: helps plugin authors control the number of model-visible tools from the design stage.

Installation and Activation

The installation command is as follows. Replace <profile> with your actual profile name:

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

After installation, you can use --dump-config to check whether the plugin is included in the configuration:

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

Typical Usage

Plugins need to inject the capabilities service. Key point: underlying implementation tools must be registered before the facade; otherwise, registration will fail loudly (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' }
        ],
      },
    ],
  })
}

After execution, the tool name visible to the model is pdf_analyze, and its description includes an explanation of the pipeline steps. The harness ensures that these steps are executed within the same root call.

Use Cases and Constraints

Use Cases

Suitable for plugins that want to combine multiple underlying tools into a highly semantic operation. For tool sets that can be stably combined to answer the same problem, using a facade can significantly reduce the number of model call round trips.

Key Constraints

  1. Cannot hide already exposed tools: the DSH tool registry uses the same visibility resolver to determine display, lookup, and dispatch. Therefore, if an underlying tool has already been registered as model-visible, the facade cannot “hide” it. It can only help authors write narrow from the beginning.
  2. Implementation tools must be registered first: facade registration depends on the existence of underlying tools; incorrect order will cause registration failure.
  3. Current status: this is a “reference implementation + experimental evidence,” not a finished product that users can install directly.

Summary

The core of dsh-capability-facade is to remove “tool orchestration” from model decision-making and delegate it to plugin authors who declare it in code. Through deterministic pipeline execution, it merges multiple root calls into one while preserving the guard and approval mechanisms of the underlying tools.

  • Project homepage: https://github.com/goatliamia/dsh-capability-facade
  • Plugin directory: https://www.skillhub.cn/plugins/goatliamia/dsh-capability-facade