> ## 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`        |

完成后，Models 页面会显示已配置的 AIHubMix 提供方。

<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` 的网络环境

检查 Node.js 和 npm：

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

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

直接安装 npm 发布版，无需克隆源码：

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

确认安装结果：

```bash theme={null}
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
```

浏览器打开：

```text theme={null}
http://127.0.0.1:3080
```

首次进入时选择或添加工作区，Harness 才能在该目录中运行 Agent 请求。

<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 将其保存为凭据，不会在设置页回显明文       |

Harness 会在 Base URL 后请求 `/chat/completions`，最终请求地址为：

```text theme={null}
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`。`auto` 是 AIHubMix 的自动模型选择入口，适合先验证连接。

需要使用指定模型时，在获取到的列表中勾选对应模型，或点击 **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="DeepSeek Harness 手动添加 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>

开发机和 CI 环境可让 Harness 配置引用环境变量。编辑 `$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
```

启动 Harness 前设置密钥：

```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>

无需 Web UI 时，可运行：

```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：

```bash theme={null}
test -n "$AIHUBMIX_API_KEY" && echo configured
```

<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、公司网络和本地代理。如果浏览器使用系统代理而终端没有使用，请为启动 `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