> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# DeepSeek Harness 接入指南
DeepSeek Harness（`dsh`）是 DeepSeek 开源的 Agent Harness。本文介绍如何通过自定义 Provider 接入 Step 5 Preview，包括 Web UI 配置、配置文件、验证与常见问题。
dsh 目前处于开发者预览阶段，界面和配置可能随版本变化。本文按当前官方模型配置文档整理；运行前请阅读项目的[安全说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md)，只在可信工作目录中使用，并谨慎授权文件操作和命令执行。
## 配置速查
| 配置项 | 值 |
| ------------------ | ----------------------------------------------------- |
| Provider ID | `stepfun` |
| API protocol | `openai-completions` |
| Step Plan Base URL | `https://api.stepfun.com/step_plan/v1` |
| 按量付费 API Base URL | `https://api.stepfun.com/v1` |
| 模型 ID | `step-5-preview` |
| 上下文窗口 | 1,000,000 tokens |
| API Key | [控制台密钥管理](https://platform.stepfun.com/interface-key) |
## 前置条件
### 安装并启动 dsh
准备 Node.js 22.19+（22.x）或 24+ 和 npm，建议使用当前 LTS，并以 dsh 官方要求为准。然后在可信工作目录中运行：
```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
npx -y @deepseek-ai/dsh web
```
首次运行会下载所需包。本机启动时默认打开 `http://127.0.0.1:3080`；通过 SSH 启动时可能只打印地址。具体启动选项见 [dsh 官方仓库](https://github.com/deepseek-ai/deepseek-harness)。
### 准备 API Key
在[控制台](https://platform.stepfun.com/interface-key)创建 API Key。使用 Step Plan 前请确认[订阅](https://platform.stepfun.com/plan-subscribe)和模型权限；使用按量付费 API 时请确认账户余额及权限。不要将真实密钥提交到代码仓库或分享在截图中。
## 方式一：通过 Web UI 配置
使用 Step Plan 订阅额度时，必须选择 `/step_plan/v1`，并确认订阅有效、具备对应模型权限。普通 `/v1` 是按量付费 API，不会因为已有 Step Plan 订阅而自动使用订阅额度。下文示例默认使用 Step Plan；按量付费用户请统一替换 Base URL。
在 dsh Web UI 中进入 **Settings → Models**，选择 **Add a custom provider**。
| 字段 | 填写内容 |
| ------------ | -------------------------------------- |
| Provider ID | `stepfun`，这是提供方标识，不是模型名 |
| Display name | `StepFun` |
| Base URL | `https://api.stepfun.com/step_plan/v1` |
| API protocol | `openai-completions` |
| API key | 您的 StepFun API Key |
Provider ID 保存后不能直接重命名；要使用新标识，请创建新的 Provider。
在模型列表中点击 **Add model**，将模型 ID 和显示名称都填为 `step-5-preview`。在 **Model options** 中将上下文窗口设为 `1000000`（1,000,000 tokens，输入时不加逗号）；需要图片输入时，在 **Input types** 中保留 **Text** 并选中 **Image**。
可选添加 `step-3.7-flash`，上下文窗口为 256,000 tokens（填写 `256000`）。模型规格分别见 [Step 5 Preview](/docs/zh/guides/models/step-5-preview) 和 [Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)，可用模型以当前账户权限为准。
模型 ID 不能为空。仅点击 Add model 而不填写 ID 会导致保存失败；Provider ID 应为 `stepfun`，模型 ID 是 `step-5-preview`。
点击 **Create provider**，新建会话，在模型选择器中选择 StepFun 下的 `step-5-preview`，发送一条简单消息验证。已有会话可能保留之前使用的模型。
Web UI 保存的密钥存储在运行 dsh 的机器上的 `$DSH_HOME/.credentials.yaml` 中，配置只保留凭据引用；如果 dsh 部署在远程服务器上，密钥也保存在服务器上。调用模型时仍会将密钥作为认证信息发送给配置的 API 服务，请核对 Base URL。
## 方式二：通过配置文件
使用 Step Plan 订阅额度时，必须选择 `/step_plan/v1`，并确认订阅有效、具备对应模型权限。普通 `/v1` 是按量付费 API，不会因为已有 Step Plan 订阅而自动使用订阅额度。下文示例默认使用 Step Plan；按量付费用户请统一替换 Base URL。
编辑 `~/.dsh/settings.yaml`。如果设置了 `DSH_HOME`，请使用该目录下的 `settings.yaml`。将以下配置合并到现有 `llm-pi-ai.providers` 中，不要覆盖其他 Provider 或重复创建同名 YAML 键。
```yaml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
llm-pi-ai:
providers:
stepfun:
apiKeyEnv: STEPFUN_API_KEY
api: openai-completions
baseURL: https://api.stepfun.com/step_plan/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: step-5-preview
name: step-5-preview
contextWindow: 1000000
input: [text, image]
- id: step-3.7-flash
name: step-3.7-flash
contextWindow: 256000
input: [text, image]
```
`compat` 将系统指令按兼容的角色发送，并使用 `max_tokens` 指定输出限制；这些选项见 [dsh 请求兼容性文档](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md#request-compatibility)。`input` 声明 dsh 可发送的输入类型，不代表模型的全部模态能力。
### 设置凭据
选择以下一种方式：
* **Web UI（推荐）**：启动 dsh，进入 **Settings → Models**，编辑 `stepfun`，填入 API Key 并保存。
* **环境变量**：将 `YOUR_STEP_API_KEY` 替换为您的 API Key，在启动 dsh 的同一个终端中设置变量，再启动进程。以下命令适用于 macOS / Linux / WSL 的 Bash 或 Zsh：
```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEPFUN_API_KEY="YOUR_STEP_API_KEY"
npx -y @deepseek-ai/dsh web
```
`settings.yaml` 和通过 Web UI 保存的凭据通常在下一次请求生效，无需重启。终端中的新环境变量不会自动传入已经运行的进程；使用环境变量方式时，需要从已设置变量的终端重新启动 dsh。
## 验证配置
先确认 **dsh 新会话**选中了 `stepfun` 下的 `step-5-preview`，发送简单消息并检查返回。
如需单独排查 API 连通性，在终端设置 `STEPFUN_API_KEY` 后运行以下命令。仅在 Web UI 中保存密钥不会自动设置终端变量。
```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
curl --silent --show-error --fail-with-body \
--write-out '\nHTTP %{http_code}\n' \
https://api.stepfun.com/step_plan/v1/chat/completions \
-H "Authorization: Bearer $STEPFUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "step-5-preview",
"messages": [{"role": "user", "content": "Say hello briefly."}],
"max_tokens": 1024
}'
```
返回 HTTP 200 且 JSON 中包含正常的 `choices` 表示这次 API 请求成功；它不能单独证明 dsh 的 Provider、凭据或会话选择正确。若输出被截断，可提高 `max_tokens` 后重试。测试调用会使用对应账户的额度。
## 常见问题
| 现象 | 排查方式 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `MISSING_CREDENTIAL` | 确认 `apiKeyEnv` 与 `STEPFUN_API_KEY` 一致，变量已传入 dsh 进程；或在 Web UI 中补填密钥。若旧环境变量仍存在，更新或移除它后重启，避免遮蔽 UI 保存的新密钥。 |
| 模型 ID 不能为空 | 模型 ID 是 API 调用时使用的模型标识：Step 5 Preview 填写 `step-5-preview`，Step 3.7 Flash 填写 `step-3.7-flash`。为每个新增模型填写对应 ID，或删除多余的空模型行。Provider ID 填写 `stepfun`，不要与模型 ID 混淆。 |
| `401 Unauthorized` | 检查密钥是否正确、有效，且属于当前 API 地址对应的平台账户。 |
| `404` / model not found | 检查 Base URL、`step-5-preview` 拼写以及账户模型权限；不要把完整 `/chat/completions` 路径填入 Base URL。 |
| 密钥和地址正确，但请求字段被拒绝 | 检查 YAML 的 `compat.supportsDeveloperRole: false` 和 `compat.maxTokensField: max_tokens`，然后新建会话重试。 |
| 新配置没有生效 | 检查 `DSH_HOME`、YAML 缩进及重复键；重新选择模型并新建会话。使用新环境变量时重启 dsh。 |
| 模型列表获取失败 | 模型发现依赖服务端列表接口；可以直接手动添加模型 ID，不必等待自动发现。 |
## 相关文档
* [Step 5 Preview](/docs/zh/guides/models/step-5-preview)
* [Step 3.7 Flash](/docs/zh/guides/models/step-3.7-flash)
* [Step Plan 快速开始](/docs/zh/step-plan/quick-start)