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 生态进行部署和交互的场景。