DeepSeek Harness 使用指南

本站推荐使用 npm 安装 DeepSeek Harness，方便管理与更新。下文将其简称为 dsh。

---

步骤一：安装

安装 Node.js

前往 Node.js 下载并安装 LTS 版本。安装时可以自定义路径，其余选项保持默认即可。

安装完成后，打开终端或 CMD 并验证：

node -v && npm -v

安装 dsh

使用 npm 全局安装：

npm install -g @deepseek-ai/dsh

PowerShell 注意

PowerShell 可能提示 npm.ps1 因系统禁止运行脚本而无法加载。建议改用 CMD 或终端；如必须使用 PowerShell，请自行调整执行策略。

安装耗时可能较长。如果需要通过本地代理加速下载，请先把 8080 替换为本机代理端口后执行：

npm config set proxy http://127.0.0.1:8080
npm config set https-proxy http://127.0.0.1:8080

步骤二：启动

先进入项目目录，dsh 会把当前调用目录作为默认文件系统位置：

cd path/to/your/project
dsh web

首次运行会初始化 Web 配置模板，并打印访问地址；默认地址是 http://127.0.0.1:3080。

验证安装：

1. 在浏览器打开终端显示的地址。
2. 看到 DeepSeek Harness 的 Web 界面即安装成功。
3. 新 Web UI 在添加工作区前不会选中任何工作区，这是正常现象。

保持终端开启

关闭终端后 dsh 会停止工作。

当前版本可能显示内测声明，点击继续即可。之后可以前往 DeepSeek 开放平台 充值并填入官方 Key 使用官方模型；也可以跳过这一步，直接使用本站模型。导入本站模型后，两类模型可以切换使用。

如果暂时不配置 DeepSeek 官方 Key，首次引导时可以点击「稍后配置」；之后仍可按下方步骤添加 Entropic Echo。

步骤三：配置 Entropic Echo

3.1 先确认 DSH 配置文件位置

DSH 的通用用户配置文件是：

$DSH_HOME/settings.yaml

如果没有设置 DSH_HOME，默认位置是：

系统	默认路径
Windows	%USERPROFILE%\.dsh\settings.yaml
macOS / Linux	~/.dsh/settings.yaml

Web UI 的 设置 → 模型、思考强度、图片输入和请求兼容性最终都对应这份设置。某些版本的设置页顶部提供 打开配置文件，也可以直接用文本编辑器打开。编辑前建议先备份；不要把 settings.yaml 整份替换成网上的示例，也不要删除原有供应商、模型或凭据字段。

配置文件错误

YAML 的缩进、冒号和列表层级必须正确。文件存在语法错误或字段类型错误时，DSH 可能拒绝加载配置，或在保存时返回 settings-rejected。遇到这类错误，先撤销最后一次修改，恢复备份，再逐项合并下面的字段。

3.2 在 Web UI 添加供应商

1. 在 Web UI 左下角打开 设置。
2. 进入 模型，点击 添加自定义提供方。
3. 填写供应商信息：

字段	填写内容
Provider ID	自定义一个小写、非空的标识，例如 entropicecho；后续在配置文件中要使用同一个 ID
API 地址	https://api.entropicecho.com/v1
API 协议	openai-responses
API Key	在 Entropic Echo 创建的 sk- 令牌

密钥分组

API Key 所在分组应为 Codex，才能使用 OpenAI 接口。如需同时使用 GPT 相关模型和国内模型，建议创建两个分组的密钥，并在 DeepSeek Harness 中分别添加供应商。

地址或协议错误

Entropic Echo 的 Codex / OpenAI 接入地址必须带 /v1，协议必须选择 openai-responses。不要把 /v1/responses、/responses 或 /chat/completions 继续追加到 API 地址。地址填错、协议不匹配或令牌无效时，常见结果是 401、403 或所有请求都失败；先回到 创建令牌 检查令牌、分组、余额和多余空格。

4. 在 模型目录 中点击 获取可用模型，选择要使用的模型。

获取模型失败

如果获取模型返回 401，检查令牌是否正确、是否已过期以及请求是否使用了 Codex 分组。如果返回空列表、提示响应没有 data 数组或 models 对象，说明网关的模型列表格式不在 DSH 的自动识别范围内；这不代表模型不能使用。直接手动添加模型，并从控制台模型广场复制完整模型 ID。

5. 对每个模型点击右数第二个图标，展开详细设置。
6. 填写正确的上下文窗口和最大输出 Token。模型能力不确定时，以模型广场或供应商说明为准，不要因为模型名称相似就套用另一个模型的参数。

模型不存在或能力参数错误

模型 ID 拼写错误、模型不在令牌分组中或仍选中了已下线模型时，常见错误是 UNKNOWN_MODEL、model not found 或请求返回 400。上下文窗口填得过大可能导致上游拒绝请求，填得过小则会过早触发上下文超限；最大输出 Token 也必须不超过模型和网关的实际限制。

最大输出 Token

使用场景	推荐 max_tokens / max_output_tokens
普通聊天、问答	8K–16K
长文、论文分析、复杂推理	32K
Agent、深度推理、长任务	64K
Max Thinking、非常复杂任务	128K

200K / 384K / 1M 通常没必要常驻设置。日常建议保持 128K；如果网关限制更小，以网关限制为准。

3.3 为每个模型配置思考强度

自定义供应商的模型通常不在 DSH 内置模型目录中。即使点击了“获取可用模型”，DSH 也通常只能拿到模型 ID、名称和上下文信息，不会自动知道每个模型支持哪些思考强度，因此模型选择器可能没有“推理等级 / 思考强度”选项。

思考强度要写在具体模型的 reasoningEfforts 下，而不是只在供应商上写一个开关：

• 左侧键名是 DSH 界面显示的档位。
• 右侧值是实际发送给上游网关的值。
• off: null 表示不发送推理参数。
• reasoningEfforts: false 表示该模型不支持思考强度。
• 供应商级 reasoning 只是没有单独选择时的默认档位，不能代替每个模型的 reasoningEfforts。

强烈建议让 AI 自行核对并生成配置

模型 ID 多、不同模型支持的档位不一致时，建议先让 AI 读取当前 DSH 配置中的模型列表，再让 AI 按模型逐一生成 reasoningEfforts，由你检查后粘贴。可以直接使用下面的提示词：

请你了解 DSH 的 config 如何填写第三方供应商模型思考强度，帮我为当前模型列表中的每一模型填写正确的思考强度档位。
请根据当前 DSH 配置中该供应商 models 列表里的每一个模型，按照每个模型实际支持的档位生成 llm-pi-ai.providers.<我的Provider ID>.models[].reasoningEfforts 映射：左侧使用 DSH 档位，右侧填写供应商实际接收的 wire 值；不支持思考的模型写 reasoningEfforts: false；off 使用 null 表示不发送推理参数。请保留我现有的 API 地址、协议、令牌引用和其他模型配置，只输出可合并的 YAML，并逐项解释判断依据。修改前先提醒我备份 settings.yaml。

AI 生成的结果也必须经过核对。AI 不应修改 API Key，不应为了“让菜单显示”给所有模型盲目添加相同档位，也不应把供应商级 reasoning 当成所有模型都支持。

将下面内容合并到已有的 $DSH_HOME/settings.yaml 中。把 entropicecho 换成你在 Web UI 中实际填写的 Provider ID，把每个 MODEL_ID_* 换成当前模型列表中的完整模型 ID；不要直接覆盖已有的 apiKeyEnv、baseURL、models 或其他配置。

llm-pi-ai:
  providers:
    entropicecho: # 替换为实际 Provider ID
      reasoning: medium # 可选；必须是目标模型共同支持的档位
      models:
        - id: MODEL_ID_A
          reasoningEfforts:
            off: null
            low: low
            medium: medium
            high: high
        - id: MODEL_ID_B
          reasoningEfforts:
            off: null
            high: high
            max: max
        - id: MODEL_ID_C
          reasoningEfforts: false

如果上游网关使用的值不是 DSH 的标准名称，只修改右侧的值。例如供应商把最高档位叫 ultra，可以写成：

reasoningEfforts:
  off: null
  low: light
  medium: standard
  high: strong
  max: ultra

保存后刷新 Web UI，最好新建一个会话，在模型选择器中确认该模型出现了预期档位。选择一个档位发送最小验证请求，再到 轨迹 或请求详情中确认实际的 reasoningEffort。模型选择器没有档位时，通常是模型条目的 reasoningEfforts 没有写入、Provider ID 不一致或 YAML 缩进错误。

选择档位后返回 400

reasoningEfforts 只是告诉 DSH“可以选择哪些档位”，最终是否生效取决于网关。如果某个档位返回参数不支持、invalid_request_error 或 400，请删除该档位，或把右侧 wire 值改成供应商文档要求的值。不要继续重试一个网关明确不接受的参数。

off 仍然在思考

off: null 的含义是“不发送推理参数”。如果上游默认开启思考，仅仅不发送参数不会主动关闭它。只有供应商明确要求 DeepSeek 风格的关闭字段时，才在对应模型或路由下补充当前 DSH 版本支持的 compat.thinkingFormat；不要把 supportsReasoningEffort 当成显示思考菜单的开关。

3.4 配置图片输入和网关兼容性

dsh 默认把添加的模型识别为文本模型。如果使用多模态模型，需要在同一个模型条目中单独开启对应能力，并注意保持缩进：

input: [text, image]

图片相关错误

发送图片前被拒绝，通常是模型没有声明 input: [text, image]；如果声明后网关返回“不支持图片”，则说明模型实际不是视觉模型，应移除 image 并新建会话。不要为了消除前置错误给所有模型添加图片能力。

某些 OpenAI 兼容网关虽然地址、协议和密钥都正确，仍可能因为请求格式不同返回 400，例如拒绝 developer 角色，或只接受 max_tokens 而不接受 max_completion_tokens。只有网关明确报出对应错误时，才在当前 DSH 版本支持的 compat 字段中修正；这不是思考强度的配置开关：

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

compat 字段校验失败

compat 字段与协议有关。若 DSH 保存时提示字段不支持、值为空或 settings-rejected，删除不适用于当前协议的字段，不要留空冒号；然后根据当前 DSH 版本的配置目录和网关错误重新添加。对于 openai-responses，优先保持官方推荐的协议和地址，不要为了显示思考菜单随意改成其他协议。

步骤四：选择工作区与权限

每次开始任务前，依次选择工作区、模式、权限和模型。

权限	说明	适用
Read Only	只能读取工作区文件，不能修改文件或执行终端命令	安全性最高
Workspace Write	可读写当前工作目录，可在该目录执行命令，不能访问目录外文件	日常开发推荐
Full Access	可读写任意路径文件，可执行各类终端指令	风险较高，按需使用

配置完成后输入需求即可开始对话。

执行流程

从启动 Web UI 到任务完成，Agent 会按当前权限策略执行读写和命令操作；需要确认的操作会先在 Web UI 中发起审批。

使用技巧

• 在 轨迹 中可以查看每轮对话的详细过程。
• 对话栏下方会显示每次调用的相关数据。
• 轨迹页还会展示轮次、耗时、吞吐、缓存命中和输入输出 Token。

插件安装

可以在 dsh 插件目录 查找并安装插件。推荐安装 dsh-web-ui 的多插件集成美化包。

1. 在运行 dsh web 的终端按 Ctrl+C 停止进程。
2. 安装集成插件：

dsh plugin --profile web add @linxin666/dsh-web-all@latest

插件安装报错

安装插件时如果提示 'pnpm' 不是内部或外部命令，先全局安装 pnpm，再重新执行安装命令：

npm install -g pnpm
dsh plugin --profile web add @linxin666/dsh-web-all@latest

如果出现 ERR_PNPM_IGNORED_BUILDS：

1. 进入 web profile，Windows 路径一般是 C:\Users\xxx\.dsh\profiles\web。
2. 在该目录打开终端，执行 pnpm approve-builds。
3. 信任插件及其依赖，并全部选中。
4. 重新执行上方的插件安装命令。

3. 执行 dsh web 重新进入 Web 界面。

插件安装成功但界面没有变化

插件需要在 dsh web 启动时加载。安装前已经运行的进程必须先按 Ctrl+C 停止，再重新执行 dsh web；若浏览器仍显示旧界面，按 Ctrl+R 强制刷新。若安装命令本身失败，先检查网络、GitHub/npm 访问权限和当前用户对 $DSH_HOME/profiles/web 的写入权限。

4. 如果界面没有立即变化，按 Ctrl+R 刷新浏览器页面。

桌面快捷方式

安装成功后，在设置的 Web 插件 列表中配置桌面启动器，之后无需命令行即可启动 dsh。

相关页面

页面	说明
创建令牌	创建分组正确的 API Key
快速开始	确认地址、令牌与验证方式
第三方客户端	其他 OpenAI 兼容客户端接入
报错档案	排查请求失败和权限问题