> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek Harness

> 在 DeepSeek Harness 中接入 AIHubMix：安裝 npm 發布版、設定 OpenAI 相容提供方、加入 auto 或指定模型並驗證 Agent 請求。

DeepSeek Harness（指令名稱 `dsh`）是 DeepSeek 開源的程式設計 Agent Harness，提供工作區、終端機、檔案編輯、Skills、計畫和 Web UI。它可透過 OpenAI Chat Completions 相容介面連接 AIHubMix。

<Info>
  本文於 2026 年 8 月 14 日使用 DeepSeek Harness `0.1.0-rc.6` 實測。Harness 仍處於開發者預覽階段，後續版本的欄位或介面可能變更。
</Info>

<h2 id="summary">
  快速結論
</h2>

接入需要四項設定：

| 設定                           | 值                         |
| ---------------------------- | ------------------------- |
| Provider ID                  | `aihubmix`                |
| Base URL                     | `https://aihubmix.com/v1` |
| API protocol                 | `openai-completions`      |
| API key environment variable | `AIHUBMIX_API_KEY`        |

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/01-models-aihubmix-configured.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=9a11531222d056d05d6ee6030eddb595" alt="DeepSeek Harness Models 頁面顯示 AIHubMix 已設定" width="1280" height="720" data-path="public/en/deepseek-harness/01-models-aihubmix-configured.png" />
</Frame>

<h2 id="requirements">
  需要準備什麼？
</h2>

* 可用的 [AIHubMix API Key](https://console.aihubmix.com/token)
* Node.js `22.19.0` 或更新版本，也可使用 Node.js 24+
* 可存取 npm Registry 與 `https://aihubmix.com` 的網路環境

```bash theme={null}
node --version
npm --version
```

<h2 id="install">
  如何安裝 DeepSeek Harness？
</h2>

直接安裝 npm 發布版，無需複製原始碼倉庫：

```bash theme={null}
npm install -g @deepseek-ai/dsh
dsh --version
```

若顯示 `dsh: command not found`，執行 `npm config get prefix`，並確認該目錄下的 `bin` 已加入 `PATH`。

<h2 id="start-web-ui">
  如何啟動 Web UI？
</h2>

在要作為工作區的專案目錄中執行：

```bash theme={null}
dsh web --port 3080
```

開啟 `http://127.0.0.1:3080`，首次使用時選擇或加入工作區。

<h2 id="configure-provider">
  如何設定 AIHubMix 提供方？
</h2>

開啟 **Settings > Models > Add a custom provider**：

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/03-add-custom-provider.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=e5f609447d3c979a65235ecc1b0382d0" alt="DeepSeek Harness 自訂提供方設定表單" width="1280" height="720" data-path="public/en/deepseek-harness/03-add-custom-provider.png" />
</Frame>

| 欄位           | 建議值                       | 說明                              |
| ------------ | ------------------------- | ------------------------------- |
| Provider ID  | `aihubmix`                | 小寫識別碼；若已使用可填 `aihubmix-gateway` |
| Display name | `AIHubMix`                | 模型選擇器顯示名稱                       |
| Base URL     | `https://aihubmix.com/v1` | 必須包含 `/v1`                      |
| API protocol | `openai-completions`      | OpenAI Chat Completions 相容協定    |
| API key      | 你的 AIHubMix API Key       | Harness 會保存為憑證，不會再次顯示明文         |

最終請求端點為 `https://aihubmix.com/v1/chat/completions`。

<Warning>
  Base URL 欄位不要填入完整的 `/chat/completions` 路徑。
</Warning>

<h2 id="add-models">
  加入 auto 或其他模型
</h2>

填入 Base URL 與 API Key 後，選擇 **Fetch available models**。Harness 會請求 `GET https://aihubmix.com/v1/models` 並顯示目前可用的模型 ID。

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/07-discover-models.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=7fdeeb8c4ba8400910bcabe1e7b50a78" alt="DeepSeek Harness 取得 AIHubMix 可用模型" width="1280" height="720" data-path="public/en/deepseek-harness/07-discover-models.png" />
</Frame>

首次連線測試可只加入 `auto`，顯示名稱填寫 `Auto`。若要使用指定模型，可從取得的清單勾選，或選擇 **Add model** 手動填入正確的模型 ID。圖形介面的模型選擇器只會顯示已註冊在目前 Provider 目錄中的模型。

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/04-add-auto-model.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=0c1e93d53cf9840d5c5885dc192b0d80" alt="手動加入 AIHubMix auto 模型" width="1280" height="720" data-path="public/en/deepseek-harness/04-add-auto-model.png" />
</Frame>

選擇 **Create provider** 儲存設定。

<h2 id="auto-vs-specific-models">
  auto 與指定模型比較
</h2>

| 選擇      | 適用情況                      |
| ------- | ------------------------- |
| `auto`  | 首次連線測試，或由 AIHubMix 自動選擇模型 |
| 指定模型 ID | 需要固定模型能力、版本或可重現結果         |

兩種方式使用相同的 Provider、Base URL 和 API Key。切換模型不需要重新建立提供方。

<h2 id="environment-variables">
  使用環境變數保存 API Key
</h2>

編輯 `$HOME/.dsh/settings.yaml`：

```yaml theme={null}
llm-pi-ai:
  providers:
    aihubmix:
      displayName: AIHubMix
      apiKeyEnv: AIHUBMIX_API_KEY
      api: openai-completions
      baseURL: https://aihubmix.com/v1
      models:
        - id: auto
          name: Auto
          contextWindow: 1000000
          maxTokens: 32768

agent-default-model:
  provider: aihubmix
  model: auto
```

```bash theme={null}
export AIHUBMIX_API_KEY='sk-***'
dsh web --port 3080
```

密鑰來自啟動環境時，設定頁會顯示唯讀提示，不會顯示實際值。

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/02-aihubmix-provider-details.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=a18af7f6409268331dcb4ddfa7d78568" alt="DeepSeek Harness 中的 AIHubMix 提供方詳細設定" width="1280" height="720" data-path="public/en/deepseek-harness/02-aihubmix-provider-details.png" />
</Frame>

變更環境變數後需要重新啟動 Harness。

<h2 id="verify-chat">
  選擇模型並驗證對話
</h2>

關閉設定視窗，開啟輸入框右下角的模型選擇器，選擇 **Auto** 或已加入的指定模型。

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/05-select-auto-model.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=82577ac5295eebc0ef6e4945f75f5ffe" alt="DeepSeek Harness 模型選擇器中的 Auto" width="1280" height="720" data-path="public/en/deepseek-harness/05-select-auto-model.png" />
</Frame>

```text theme={null}
Reply with exactly: AIHubMix connection successful
```

收到預期回覆代表 Harness、OpenAI Chat Completions 相容端點與 AIHubMix 之間的連線正常。

<Frame>
  <img src="https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/06-live-chat-success.png?fit=max&auto=format&n=pPBGbuf_Qo9bMEMd&q=85&s=f5fe3902c1c2f57b84b34b739b258394" alt="DeepSeek Harness 透過 AIHubMix 成功回覆" width="1280" height="720" data-path="public/en/deepseek-harness/06-live-chat-success.png" />
</Frame>

<h2 id="headless-test">
  執行 headless 測試
</h2>

```bash theme={null}
export AIHUBMIX_API_KEY='sk-***'
dsh --profile headless \
  'Reply with exactly DSH_AIHUBMIX_OK and do not use tools.'
```

成功時會輸出 `DSH_AIHUBMIX_OK`。

<h2 id="troubleshooting">
  常見問題
</h2>

<h3 id="missing-credential">
  為什麼顯示 MISSING\_CREDENTIAL？
</h3>

Harness 未從啟動環境取得 `AIHUBMIX_API_KEY`。設定變數後，從同一個終端機啟動 Harness。

<h3 id="models-401">
  為什麼取得模型時回傳 401？
</h3>

檢查 API Key 是否有效，以及是否包含多餘的空格或換行。模型探索請求使用 Bearer 驗證。

<h3 id="only-auto">
  為什麼模型選擇器只有 Auto？
</h3>

選擇器只顯示目前 Provider 目錄中已註冊的模型。前往 **Settings > Models > AIHubMix > Edit**，使用 **Fetch available models** 或手動加入正確的模型 ID。

<h3 id="unknown-model">
  為什麼顯示 UNKNOWN\_MODEL？
</h3>

目前 Provider 目錄中沒有該模型 ID。模型 ID 會區分大小寫，請使用模型探索回傳的正確值。

<h3 id="connection-timeout">
  為什麼連線逾時？
</h3>

檢查 DNS、組織網路與本機 Proxy。若瀏覽器使用系統 Proxy 而終端機沒有使用，請在啟動 `dsh` 的終端機設定 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NODE_USE_ENV_PROXY=1`。

<h2 id="security">
  安全建議
</h2>

* 不要將 API Key 提交到 Git，或放入截圖與共用指令碼
* 優先使用 Harness 憑證儲存或 `AIHUBMIX_API_KEY`
* 疑難排解時不要列印完整 API Key
* 在 CI 中使用 Secret 管理功能注入環境變數

***

更新日期：2026-08-14