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