如何在10分钟内安装 DeepSeek Harness（并将其指向任意模型）

安装 DeepSeek Harness 只需一条命令。三十秒后，你就能在 http://127.0.0.1:3080 看到一个漂亮但完全空白的界面，而且没人告诉你下一步该做什么。

README 内容很少，它链接的 Cordis 论文讨论的是时空组合性。你只是想让它读你的代码。

本指南就从那个空白界面开始。你会看到安装命令，没错，但真正耗费你一个下午的是配置模型提供商，而这一步中有三个默认值会悄悄破坏 DeepSeek 模型，并浪费掉你 75% 的上下文窗口。几乎没有人记录这些默认值。

关键要点

• npx @deepseek-ai/dsh web 就是完整的安装命令。唯一的前提条件是 Node.js ^22.19.0 或 >=24.0.0。
• DeepSeek Harness 是一个测试框架，不是模型。它不附带任何凭证，所以你必须连接一个提供商才能使用。
• 任何兼容 OpenAI 的端点都可以使用，包括 DeepSeek 自己的 API、网关或本地 Ollama 服务器。
• 当你添加自定义提供商时，框架会根据你的基础 URL 猜测推理方言。猜错了，reasoning_content 就会出问题。
• 手动声明的模型默认使用 262,144 的上下文窗口，所以 V4 完整的 1,048,576 窗口在你明确指定之前是关闭的。

终端显示绿色通过的测试和一个发光的模块化框架，展示了如何安装 DeepSeek Harness

你正在构建的内容的 60 秒版本

这是在讲理论之前先展示成果。一个空文件夹里的三个文件，一个粘贴进去的提示，然后代理读取代码，运行 pytest，看到两个测试失败，修改一个字符，重新运行直到测试套件全部通过。

DeepSeek Harness 读取 fizzbuzz.py，运行 pytest，修复 off-by-one 错误，重新运行，3 个测试通过

完整循环：读取、运行、诊断、修补、重新运行。每一步都会记录在一个只能追加的会话日志中，你可以稍后回放。

这就是我们将在第 6 步一起构建的演示。它特意设计得足够小，可以在一个临时目录中复现，并且不依赖任何可能在下周发生变化的外部仓库。

为什么大多数尝试安装 DeepSeek Harness 的人都在第二步卡住

安装确实很简单。卡住发生在安装之后，而且这是一个设计决策，不是 bug：DeepSeek Harness 不附带任何密钥、默认提供商和捆绑模型。

DeepSeek 于 2026 年 8 月 13 日以 MIT 许可证开源了这个项目，并迅速崛起。截至 2026 年 8 月 17 日，该仓库拥有 144,361 颗星和 14,689 个分支（GitHub，2026 年 8 月），这意味着同一周有很多人看到了同一个空白界面。

发布周的 Hacker News 讨论中反映了两种截然不同的反应。人们喜欢透明性：模型看到的所有内容都会被记录在一个只能追加的会话日志中，一位评论者指出“美国模型不会让你看到这些”。抱怨也同样一致。一位开发者写道：“除了安装说明，README 几乎没有内容”，而 Cordis 论文则被评价为“文字沙拉”（Hacker News，2026 年 8 月）。

所以，实际上阻碍人们的四个问题都发生在安装之后：

• Node 版本太旧，npx 在启动前就失败了。
• 端口 3080 已被另一个开发服务器占用。
• 自定义提供商返回 401，或者模型列表为空。
• 模型连接成功，但推理输出乱码，或者长文件过早超出上下文窗口。

下面第 1 到第 5 步正是针对这四个问题。

安装 DeepSeek Harness 之前：选择模型和密钥

首先回答：框架本身是免费且本地的，但在你提供兼容 OpenAI 的基础 URL、密钥以及至少一个模型 ID 之前，它不会做任何有用的事情。在安装前决定好这些，整个设置过程只需十分钟。

所有操作都在浏览器标签页 127.0.0.1:3080 中进行。你需要在三条路线中选择，它们都有效。

表 B：当前可与 DeepSeek Harness 配合使用的模型访问选项

在做出选择之前，有两件事值得了解。DeepSeek 的第一方 API 已改为高峰和非高峰计费，高峰时段为 01:00 至 04:00 和 06:00 至 10:00 UTC，非高峰时段价格正好是高峰时段的一半（DeepSeek API 文档，2026 年 8 月）。其缓存命中输入定价极低，因此重复读取相同上下文的负载在第一方 API 上可能非常便宜。

网关则以可预测性换取这种优势。Atlas Cloud 以固定费率提供相同的 DeepSeek 模型，没有高峰附加费，也没有订阅，我将在下面的设置中使用它作为示例，因为它不需要区域性付款方式。根据你的情况选择适合的路线；所有路线的配置形状都是相同的。

如何安装 DeepSeek Harness：一步步操作

有三种安装方式。选择一种，然后按照步骤操作。

表 A：安装方法对比

第 1 步：安装前检查前提条件

最常见的失败原因是 Node 版本看起来足够新但实际上不够。仓库要求 ^22.19.0 || >=24.0.0。23.x 系列的任何一个版本都不符合要求，无论补丁级别如何。

bashCopy
1node -v      # 必须在 22.x 上 >= 22.19.0，或在 >= 24.0.0 上
2npm -v
3

如果 node -v 输出 22.14 或 20.x，请先升级。只有当你计划从源码构建或编写插件时，才需要 pnpm：

bashCopy
1npm install -g pnpm
2

第 2 步：用一条命令安装 DeepSeek Harness

这就是完整的安装命令。它会下载并一次性启动 Web 配置文件。

bashCopy
1npx @deepseek-ai/dsh web
2

打开 http://127.0.0.1:3080。如果该端口已被占用，启动器会将所有不认识的标志直接传递给配置文件，因此你可以更改端口：

bashCopy
1npx @deepseek-ai/dsh web --port 8080
2

你得到的是一个空壳。没有提供商，没有模型，没有密钥。这是正常的，而且大多数指南到这里就结束了。

安装后立即显示的 DeepSeek Harness Web UI（127.0.0.1:3080），未配置提供商或模型

安装完成，但完全无响应。从这里开始，一切都是连接配置。

第 3 步：为 DeepSeek Harness 获取 API 密钥

无论你从表 B 中选择哪条路线，你都需要一个密钥和一个基础 URL。对于第一方路线，在 platform.deepseek.com 注册并创建一个密钥。计费选项因地区而异，因此请在承诺使用前检查你的付款方式是否支持。

对于本指南中使用的网关路线，在 Atlas Cloud 仪表板 的 API 密钥下创建一个密钥，然后导出，以便框架可以读取它，而无需将其存储在设置文件中：

bashCopy
1export ATLASCLOUD_API_KEY="sk-your-key-here"
2

Atlas Cloud 仪表板的 API 密钥页面，显示一个新建的密钥，部分已遮盖

复制密钥一次。离开页面后，它将不再显示。

第 4 步：将模型提供商添加到 DeepSeek Harness

在 UI 中，进入设置，然后模型，然后点击 添加自定义提供商。表单需要提供商 ID、显示名称、基础 URL、API 协议、凭证以及至少一个模型。

一个文档中反复强调的警告：提供商 ID 是永久性的。 它会被写入请求、保存的会话、模型默认值和凭证引用中。如果你以后不喜欢它，唯一的选择是创建一个新的提供商并删除旧的。

如果获取模型返回 401，说明密钥错误。如果返回空列表，说明端点根本没有暴露模型索引，这无害：手动输入模型 ID 即可。

填写好的“添加自定义提供商”表单，标记了基础 URL、API 协议和获取模型控制

三个决定下一步是否成功的字段：基础 URL、协议和模型列表。

第 5 步：三个会悄悄破坏 DeepSeek 模型的 DeepSeek Harness 默认值

这是其他安装指南没有涵盖的部分，也是你的设置看起来已连接但行为异常的原因。

框架的 LLM 层会根据你的端点 URL 推断要使用的推理方言。内部文档对其后果直言不讳：“pi-ai 通过端点 URL 猜测；私有网关的 URL 不提供任何信息，因此 DeepSeek 方言的网关会被用 OpenAI 方言与之通信，且无法纠正。” 简单来说，任何不是明显 DeepSeek 的基础 URL 都会被当作 OpenAI 处理，而 DeepSeek 的 reasoning_content 处理就会出错。

第二个和第三个陷阱是容量。手动声明的模型会回退到 defaultContextWindow 为 262,144 和 defaultMaxTokens 为 32,768。V4 支持 1,048,576 token 的上下文，因此接受默认值会浪费掉四分之三。

将这些内容写入你的设置文件：

yamlCopy
1# $DSH_HOME/settings.yaml   （默认路径 ~/.dsh/settings.yaml）
2llm-pi-ai:
3  providers:
4    atlas:
5      displayName: Atlas Cloud
6      api: openai-completions
7      baseURL: https://api.atlascloud.ai/v1
8      apiKeyEnv: ATLASCLOUD_API_KEY
9      compat:
10        thinkingFormat: deepseek   # 1. 停止基于 URL 的猜测
11      defaultContextWindow: 1048576  # 2. 默认仅为 262144
12      defaultMaxTokens: 32768        # 3. 为长输出任务提高此值
13      models:
14        - id: deepseek-ai/deepseek-v4-flash
15          contextWindow: 1048576
16        - id: deepseek-ai/deepseek-v4-pro
17          contextWindow: 1048576
18

需要记住三件事。设置解析顺序是：模型第一，然后路由，然后已安装的目录条目，最后是基于 URL 的猜测，因此每个模型的值总是获胜。compat 开关 thinkingFormat 和 supportsReasoningEffort 仅存在于 openai-completions 下；将其放在其他协议上会导致解析失败。并且此适配器特意不涵盖 Bedrock、Vertex、Azure 或 Codex，它们的认证流程需要的不仅仅是密钥、端点和标头。

第 6 步：在 DeepSeek Harness 中运行你的第一个真实任务

现在，运行本文开头提到的演示。创建一个空文件夹并添加三个文件。

fizzbuzz.py，包含一个 off-by-one 错误：

pythonCopy
1def fizzbuzz(n):
2    out = []
3    for i in range(1, n):
4        if i % 15 == 0:
5            out.append("FizzBuzz")
6        elif i % 3 == 0:
7            out.append("Fizz")
8        elif i % 5 == 0:
9            out.append("Buzz")
10        else:
11            out.append(str(i))
12    return out
13

test_fizzbuzz.py，其中三个测试中两个失败：

pythonCopy
1from fizzbuzz import fizzbuzz
2
3def test_starts_correctly():
4    assert fizzbuzz(5)[:3] == ["1", "2", "Fizz"]
5
6def test_covers_every_number():
7    assert len(fizzbuzz(15)) == 15
8
9def test_fifteen_is_fizzbuzz():
10    assert fizzbuzz(15)[-1] == "FizzBuzz"
11

以及 requirements.txt：

textCopy
1pytest>=8.0
2

先手动运行测试套件是值得的，这样你就知道代理将要面对什么：

textCopy
1.FF                                                                      [100%]
2=================================== FAILURES ===================================
3___________________________ test_covers_every_number ___________________________
4E       AssertionError: assert 14 == 15
5___________________________ test_fifteen_is_fizzbuzz ___________________________
6E       AssertionError: assert '14' == 'FizzBuzz'
7=========================== short test summary info ============================
82 failed, 1 passed in 0.01s
9

将代理模式设置为标准，模型设置为 deepseek-ai/deepseek-v4-flash，然后粘贴这个提示：

在此工作区中运行 pytest。两个测试失败。在 fizzbuzz.py 中找到根本原因，用最小的改动修复它，然后重新运行 pytest 并显示最终输出。不要编辑测试文件。

正确的修复是一个字符：range(1, n) 变成 range(1, n + 1)，然后测试套件报告 3 passed。

现在，这是框架与聊天窗口的不同之处。每次运行都会记录在一个只能追加的会话日志中，并且你可以进行分叉。回到代理首次读取 fizzbuzz.py 的点，并分支第二次尝试：

从你第一次读取 fizzbuzz.py 的步骤分叉此会话。这次将其重写为基于字典的查找，而不是修补 if 分支，然后再次运行 pytest。

分叉 DeepSeek Harness 会话日志，从同一起点生成第二个基于字典的实现

一个起点，两个分支。这是发布周期间人们真正关心的功能。

第 7 步：为脚本和 CI 使用无头模式

两个配置文件在首次使用时初始化：web 和 headless。你一直在使用 web，dsh web 只是 dsh --profile web 的别名。

无头模式运行一个全新的持久化会话，打印最终答案，然后退出，这正是 CI 任务想要的形态：

bashCopy
1dsh --profile headless "运行测试并修复任何失败。报告差异。"
2

任何其他配置文件都必须通过 dsh plugin 创建。配置文件位于 $DSH_HOME/profiles/<name>，默认路径为 ~/.dsh/profiles/<name>。

无头 DeepSeek Harness 运行的终端输出，打印最终答案并退出

无头模式：一个会话，一个答案，你可以根据退出码进行分支。

安装 DeepSeek Harness 的其他方法

npx 路线覆盖了大多数人。以下三种方法也值得了解。

使用 pnpm 从源码安装 DeepSeek Harness

如果你想阅读代码、修补它或编写针对它的插件：

bashCopy
1git clone https://github.com/deepseek-ai/deepseek-harness
2cd deepseek-harness
3pnpm install
4pnpm run build
5pnpm dsh web
6

5 MB 的桌面版构建

一个社区项目 hairyf/deepseek-harness-desktop 将框架封装在 Tauri 中，并提供大约 5 MB 的 Windows、macOS 和 Linux 安装程序，无需任何 Node 设置。这不是 DeepSeek 的官方发布版，因此请相应对待：在撰写本文时，它大约有 400 颗星，并且是在框架本身发布后一天创建的。

使用 Ollama 完全本地运行 DeepSeek Harness

Ollama 提供了一个第一方集成。简短版本是一条命令：

bashCopy
1ollama launch dsh
2

这将安装并运行框架，并集成 Ollama，将其设置保存在 ~/.ollama/launch/dsh/settings.yaml（Ollama 文档，2026 年 8 月）。在假设一切都在离线之前，有一个注意事项值得阅读：内置的 Web 搜索会自动启用，需要 Ollama 云访问以及支持工具的模型。真正的本地模型给你零 token 成本，但代价是速度和通常较弱的工具调用能力。

DeepSeek Harness 连接到本地 Ollama 服务器，运行相同的失败测试任务

相同任务，无网络往返，无按 token 计费。

DeepSeek Harness 是免费的吗？实际运行成本是多少？

首先回答：该软件是免费的，采用 MIT 许可证，包括商业用途。模型 token 不是免费的，除非你本地运行模型。框架本身没有计量、限制或与 DeepSeek 账户绑定。

表 C：什么是真正免费的，什么不是

一个实际例子，使用四舍五入的数字而非特定运行。假设一个像第 6 步那样的调试会话消耗 200,000 个输入 token 和 20,000 个输出 token，这在代理读取了几个文件并迭代后是合理的。按网关固定费率输入 $0.14 和输出 $0.28 计算，该会话成本约为 3.4 美分。在第一方 API 上，按非高峰缓存未命中率计算约为 5.7 美分，高峰时段约为 11 美分。如果你的大部分输入是缓存命中，第一方 API 在输入侧会变得非常便宜，因为缓存命中输入低至每百万 token $0.007。

实际杠杆，按影响排序：保持会话简短，以免上下文膨胀；将常规工作放在 Flash 上，将 Pro 留给真正困难的任务；对于基准测试风格运行使用最小模式，因为它只给模型两个工具，没有上下文压缩。

部署前：DeepSeek Harness 许可证和预览风险

三件简短的事情，然后是常见问题。

许可证是 MIT，因此商业使用没问题。但该项目将自己标记为开发者预览版，并明确警告将会有不兼容的更改。固定一个版本，暂时不要将其集成到生产发布管道中。

你的凭证以明文形式存储在你的机器上，位于 $DSH_HOME/.credentials.yaml，设置文件位于 $DSH_HOME/settings.yaml，两者默认路径为 ~/.dsh。如果你的框架主目录最终位于仓库中，请将其添加到 .gitignore：

textCopy
1.dsh/
2

还有一个容易忘记的明显事项：你的代码会发送到你在第 4 步配置的任何端点。在将代理指向私有代码库之前，请阅读该提供商的数据条款。

常见问题

DeepSeek Harness 是免费的吗？

该框架是免费的，采用 MIT 许可证，无需账户或订阅，你可以将其用于商业用途。模型 token 由你连接的提供商单独计费。将其指向本地 Ollama 模型可以给你一个真正零 token 成本的设置，但用硬件和速度来换取。

安装 DeepSeek Harness 需要 DeepSeek API 密钥吗？

不需要。安装和 DeepSeek 密钥无关。npx @deepseek-ai/dsh web 无需任何凭证即可运行。只有当你希望代理实际调用模型时才需要密钥，而且它可以是任何兼容 OpenAI 的端点的密钥，包括本地服务器。

DeepSeek Harness 可以运行 DeepSeek 以外的模型吗？

可以。自定义提供商接受 openai-completions，适配器涵盖可以用密钥、端点和标头描述的协议。通过在 settings.yaml 中的 providers: 下添加另一个块，使用其自己的 ID、基础 URL 和模型，即可添加第二个提供商。Bedrock、Vertex、Azure 和 Codex 被故意排除在外，因为它们的认证需要的不仅仅是这些。

为什么我的自定义提供商返回 401 或“未知模型”？

401 几乎总是意味着密钥错误，或者没有从 apiKeyEnv 命名的环境变量中读取。未知模型通常意味着端点没有暴露模型索引，因此没有获取到任何内容：改用手动输入模型 ID。另外，检查提供商 ID 的拼写，因为它不能重命名，只能替换。

DeepSeek Harness 将我的 API 密钥和设置存储在哪里？

密钥存储在 $DSH_HOME/.credentials.yaml，手动编写的模型设置存储在 $DSH_HOME/settings.yaml，两者默认位于 ~/.dsh，除非你覆盖了 DSH_HOME。会话位于 $DSH_HOME/storages，配置文件位于 $DSH_HOME/profiles/<name>。将整个目录排除在版本控制之外。

DeepSeek Harness 可以用于生产环境吗？

根据其自身说明，还不能。该项目作为开发者预览版发布，并明确警告会存在不兼容的更改，这对于只有几天历史的软件来说是合理的。将其用于本地开发和 CI 辅助，固定你测试过的版本，并在升级后重新阅读提供商文档。

---

于 2026 年 8 月 17 日针对 DeepSeek Harness 开发者预览版验证。该项目有意进行破坏性更改，因此如果你的构建中的字段名与上述 YAML 不同，请先检查官方提供商文档，再假设配置错误。