DeepSeek Harness 插件：dsh-plugin-slashx-gateway

前言¶

DeepSeek Harness (DSH) 採用了插件化的架構。當需要將 DSH 實例對接到遵循 slashx.request.v1 和 slashx.response.v1 協議的第三方平臺（如 SlashX）時，通常需要編寫適配器。dsh-plugin-slashx-gateway 插件直接實現了這套協議，使得 DSH 實例能夠作爲一個符合規範的網關服務運行，並提供安全可靠的媒體入口與製品出口。

插件簡介¶

這是一個 DeepSeek Harness Host Bundle。它將 Harness 實例暴露爲遵循 slashx.cn 協議的 SlashX 服務端點，並提供文本、圖片、文件、音視頻、引用、卡片和按鈕所需的安全媒體入口與製品出口。

基本信息
* 插件名稱: dsh-plugin-slashx-gateway
* 維護者: superslash-rico
* 版本: 0.1.0
* 許可證: MIT
* 兼容性: DeepSeek Harness >=0.1.0-rc.6 <0.2.0

核心功能¶

插件實現了以下能力：

請求處理: 接收文本、圖片、文件（PDF/Office/文本/代碼）、音視頻。
響應處理: 支持引用與按鈕點擊、Markdown 響應、富媒體響應。
異步回調: 支持 extensions.slashxAsync、一次性 callback token、輪詢和取消入口。
安全機制: 對 URL 進行 DNS/重定向 SSRF 檢查，對 Base64 媒體進行校驗，防止安全漏洞。

安裝與啓用¶

環境要求¶

Node.js 22.19+
需使用官方 Harness web profile（提供 ctx.apiProxy）。不要裝入不含 ApiProxy 的 headless profile。

安裝步驟¶

確保已安裝 DeepSeek Harness 官方包。
使用 web profile 安裝插件：

    dsh plugin --profile web add dsh-plugin-slashx-gateway

確認插件已加載：

    dsh web --dump-config

配置¶

設置環境變量以啓動網關。至少需要 32 字符的隨機訪問令牌：

export SLASHX_GATEWAY_TOKEN="$(openssl rand -base64 32)"
export SLASHX_GATEWAY_STATE_ROOT="/srv/deepseek-harness/slashx-gateway"
export SLASHX_GATEWAY_PUBLIC_BASE_URL="https://harness.example.com"
dsh web

默認網關監聽 127.0.0.1:3090。

典型用法¶

反向代理配置¶

生產環境建議在 Caddy 或 Nginx 上終止 TLS，僅暴露網關端口，避免直接暴露 Harness 原生 API。

harness.example.com {
  reverse_proxy /slashx-provider/* 127.0.0.1:3090
  reverse_proxy /healthz 127.0.0.1:3090
}

SlashX 連接配置¶

在 SlashX 平臺創建“自建 HTTP 服務”連接，指向網關地址：
* Endpoint: https://harness.example.com/slashx-provider/v1/run
* Auth: Bearer Token (與 SLASHX_GATEWAY_TOKEN 相同)
* Async callback: 建議開啓，用於長任務或大文件處理
* Timeout: 同步任務應不小於 Gateway 的預期執行時長

富媒體響應工具¶

插件向 Harness 註冊 slashx_deliver 工具。Agent 調用該工具可返回富媒體內容。

參數示例:

{
  "runId": "11111111-1111-4111-8111-111111111111",
  "text": "## 分析完成\n報告和預覽如下。",
  "images": [
    {
      "localPath": "output/preview.png",
      "mimeType": "image/png",
      "fileName": "preview.png"
    }
  ],
  "attachments": [
    {
      "localPath": "output/report.pdf",
      "mimeType": "application/pdf",
      "fileName": "report.pdf",
      "attachmentType": "document"
    }
  ],
  "citations": [
    {
      "index": 1,
      "title": "數據來源",
      "url": "https://example.com/source"
    }
  ],
  "cards": [
    {
      "type": "summary",
      "title": "處理結果",
      "fields": [{ "label": "狀態", "value": "已完成" }]
    }
  ],
  "actions": [
    { "label": "繼續處理", "kind": "send_message", "value": "繼續處理" },
    { "label": "打開來源", "kind": "open_url", "value": "https://example.com/source" }
  ],
  "conversationUpdate": { "title": "文件分析結果", "modeTag": "done" }
}

適用場景與注意¶

Profile 限制: 必須使用 web profile，因爲插件依賴 ctx.apiProxy。
SSE 限制: 當前版本 (0.1.0) 不支持文本逐 token SSE，長任務使用異步回調。
模型依賴: 媒體生成與理解能力取決於實際裝入 Harness 的模型和工具。
客戶端能力: 插件會遵守客戶端聲明的 stream、markdown 等能力，若客戶端不支持富組件，會降級爲附件或 Markdown。
重啓行爲: 網關重啓後，若發現某個 run 只有 running 記錄，會返回 RUN_OUTCOME_UNCERTAIN，不會自動重複執行。
計費歸集: 支持按次 (flat_per_run) 和按 Token (pass_through) 計費。按 Token 計費時，reasoningTokens 不會疊加到輸出 Token 以避免重複計費。

結語¶

該插件爲 DeepSeek Harness 提供了標準的 SlashX 協議接入能力，適合需要通過 SlashX 生態進行部署和交互的場景。