DeepSeek Harness：通过 JoinGonka Gateway 连接自有提供商

Harness 就是 Agent 工作中围绕在模型周围的一切：那个「请求 → 工具调用 → 结果 → 下一步」的循环，文件与终端工具，权限与确认，会话日志，上下文压缩。DeepSeek Harness 用插件把这些拼装起来：它的「一切皆插件」架构建立在 Cordis 框架之上，从工具到模型适配器，任何节点都能在不改核心的前提下替换。代码以 MIT 许可开源。

无需安装——只要有 Node.js 就行（22 系列需 22.19 及以上，或 24 及更新版本）：

npx @deepseek-ai/dsh web

该命令会在 http://127.0.0.1:3080 上拉起 Web UI 并在浏览器中打开；通过 SSH 启动时，地址只会打印到终端。--no-open 参数让服务器启动但不打开浏览器，--port 用于改端口。启动 dsh 时所在的目录会成为默认工作目录，但界面只有在你明确选择工作区之后才会开始会话。

模型层由两个适配器构成。直连适配器走厂商官方 API。多服务商适配器 dsh-llm-pi-ai 构建在 pi-ai 库之上——正是终端 Agent Pi 底层所用的同一个库；通过它既能接入内置目录里的服务商，也能接任何自有 endpoint。因此配置文件里的字段名——api、contextWindow、maxTokens——与你在 Pi 上熟悉的那套完全一致。

关于成熟度。 项目 README 开头就是一句警告：developer preview、快速迭代、破坏性变更。另有一份 SAFETY.md 明确指出：尚未进行安全审计，而 Agent 会执行由模型生成的命令。务实结论很简单：把 dsh 跑在容器、虚拟机或独立账号下，并对它能触及的一切做好备份。

第 1 步：密钥。前往 gate.joingonka.ai/register 注册：确认邮箱后，账户会收到 3M 个免费代币。进入控制台，打开「API 密钥」板块，创建一个带 jg- 前缀的密钥。不妨为 harness 单独建一个密钥——这样它的流量就会在统计里独占一行。

第 2 步：首个界面。在测试状态提示（Continue 按钮）之后，dsh 会要求你填入官方 API 密钥（「Add an API key to get started」）。这一步并非必须：点击 Configure later 即可跳过。

第 3 步：服务商。打开 Settings → Models，选择 Add a custom provider。表单字段如下：

第 4 步：模型。在 Models 区块中点击 Fetch available models：dsh 会向网关拉取列表，并弹出「Choose models to add」窗口。在我们的实测中，窗口里列出了网络上的全部三个模型——MiniMaxAI/MiniMax-M2.7、deepseek-ai/DeepSeek-V4-Flash-0731 和 zai-org/GLM-5.3-Flash——点击 Add selected 后，harness 会根据网关数据自动为每个模型填好上下文窗口和回复上限。接下来只需点击 Create provider。

第 5 步：选择模型。关闭设置，点击 Choose workspace 并添加项目目录。新服务商的模型会出现在选择器中；所选模型将成为新会话的默认模型。

dsh 将密钥与设置分开存放：保存在 ~/.dsh/.credentials.yaml 文件中，仅所有者可读。settings.yaml 里只保留对它的引用名称——在我们的实测中是 JOINGONKA_API_KEY，取自服务商标识符。

该选哪种协议。网关三种协议都支持，区别在于基础地址和附带的便利功能：

dsh 中一个服务商只使用一种协议，因此要用第二种协议就需再建一个服务商，使用不同的 Provider ID。日常使用第一种足矣；在我们的实测中，带工具调用的智能体循环在三种协议下都正常运行。

Models 表单写入的是普通的 YAML 文档——$DSH_HOME/settings.yaml，默认路径为 ~/.dsh/settings.yaml。你可以直接编辑它：设置顶部的 Open configuration file 按钮会打开该文件，适配器会在下一次请求时重新读取——无需重启。以下是针对 Gonka 网络的完整配置：

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    joingonka:
      displayName: JoinGonka Gateway
      apiKeyEnv: JOINGONKA_API_KEY
      api: openai-completions
      baseURL: https://gate.joingonka.ai/v1
      models:
        - id: deepseek-ai/DeepSeek-V4-Flash-0731
          name: DeepSeek V4 Flash
          contextWindow: 380000
          maxTokens: 32768
        - id: zai-org/GLM-5.3-Flash
          name: GLM-5.3 Flash
          contextWindow: 390000
          maxTokens: 8192
          reasoningEfforts:
            off: low
            high: high
        - id: MiniMaxAI/MiniMax-M2.7
          name: MiniMax M2.7
          contextWindow: 200000
          maxTokens: 8192
agent-default-model:
  provider: joingonka
  model: deepseek-ai/DeepSeek-V4-Flash-0731

以下几点很重要：

• apiKeyEnv 不是密钥本身，而是对密钥的引用名。dsh 会按顺序查找其值：启动时的环境变量，然后是 .credentials.yaml（表单会写入这里），然后是启动目录下的 .env，最后是 ~/.dsh/.env。如果你要在无浏览器环境下配置 harness，只需在 ~/.dsh/.env 中写入一行 JOINGONKA_API_KEY=jg-your-key，权限设为 600 即可。启动之后导出的变量，已经运行的进程是看不到的。
• 请显式设置 contextWindow 和 maxTokens。对于 dsh 一无所知的模型，它会默认按 262,144 和 32,768 个 token 处理——这与实际限制并不相符。你设置的 maxTokens 同时会成为每个请求的默认响应上限。
• reasoningEfforts 是 Effort 菜单中的推理等级。手动添加的模型没有等级，因此不会为它显示该菜单。GLM-5.3 Flash 的开关是二元的：low 会关闭推理，其他任何值都会让它保持完整推理。因此 off 等级被映射为 low，而 high 则原样传递。在我们的测试中，使用 off 时完全没有推理块，使用 high 时推理块又回来了。
• agent-default-model 是新 agent（包括 headless 模式）使用的模型。界面中的模型选择效果相同；你也可以在这里添加 reasoningEffort。

dsh 文档针对严格网关建议的 compat 开关（supportsDeveloperRole: false、maxTokensField: max_tokens）在这里并不需要：JoinGonka Gateway 同时接受 developer 角色和 max_completion_tokens 字段。

安装器 npx @joingonka/setup 不会配置这个 harness：整个接入过程只需上一节的表单或上面的 YAML 片段。

验证整套集成最快的方法，就是在代码目录里跑一次单次运行。把一个带有明显 bug 的小文件放在旁边，让 agent 去找出来：

cd /path/to/project
npx @deepseek-ai/dsh --profile headless "Read calc.py and tell me in one sentence whether it has a bug."

最终答案输出到 stdout，推理过程输出到 stderr，并带有 dsh: reasoning: 前缀。agent 应该自行调用读文件工具并给出实质性的回答：在我们的运行中，网络上的三个模型都指出了出错的那一行。这说明「请求 → 工具调用 → 结果 → 回答」这一完整链路经由网关已经正确打通。

验证的另一半在网关侧。进入控制台的「使用情况」，可以看到按小时和按天统计的请求、按模型和按密钥的拆分。一旦出现带有 harness 密钥和最新请求时间的那一行，就说明流量确实在走网关。

如果出了问题，通常直接从报错信息里就能读出诊断结论：

网络中所有模型的价格都是相同的，因此选择主要取决于行为而非预算。以下是限制条件以及模型在我们 dsh 运行中针对同一任务（读取文件并找出其中的错误）的表现：

默认推荐为 DeepSeek V4 Flash：代理工作很容易达到上下文容量和编辑长度的瓶颈，而该模型在这两个参数上都有充足的余量。当任务需要深入思考复杂的逻辑时，请切换到 GLM-5.3 Flash 并将推理级别保持在 high；对于快速编辑，同一提供商提供的该模型级别设为 off。MiniMax M2.7 是处理短任务的稳健选择，此时可见的推理过程不会造成干扰。可在界面选择器中或通过 agent-default-model 块中的 model 字符串更改模型。

网络构成由参与者投票决定，并随时间变化；最新的列表及限制条件始终可通过 GET https://gate.joingonka.ai/v1/models 获取——“获取可用模型”按钮使用的也是该端点。

智能体工具消耗 token 的方式与聊天不同：对于你的每一句话，harness 都会添加一个系统提示词和所有工具的描述，然后与模型进行多轮对话。在我们的测试运行中，“读取文件并查找错误”的任务耗时两到三轮，使用了 14,000 到 22,000 个 token，其中几乎全部是输入：即使在你提问之前，每轮都会消耗约 7,000 个 token。这是为自主性支付的正常代价，这也是为什么按 token 计费至关重要的原因。

通过 JoinGonka Gateway，输入端 token 每百万个仅需 $0.0069，输出端每百万个仅需 $0.021——此价格适用于网络中的所有模型，并从此页面的实时源中自动获取。2026 年 9 月的价格量级如下：

按实际消耗付费，无订阅，无请求配额限制；余额和每日消耗量可在后台查看。

版本。 项目目前处于 developer preview 状态，每次更新后请检查提供商是否正常，为了可复现性，请直接在命令中固定版本：npx @deepseek-ai/[email protected] web。

权限。 新会话默认在 Workspace Write 模式下运行——写入权限仅限于工作目录；超过策略的操作，界面会要求确认。可在 Settings → General 中更改模式。

重试。 如果发生单次网络错误，dsh 会自动重试请求——根据文档最多重试五次——因此短时的网络负载峰值通常不会被察觉。

隐私。 网关不存储提示词和响应的内容：统计数据中仅保留消耗总量。智能体在你的本地机器上读取项目文件。

如果需要处理图像——界面截图、照片中的图表——请在旁边配置第二个具有视觉能力模型的提供商：dsh 支持同时使用多个提供商，而 Gonka 网络模型是基于文本的。

DeepSeek Harness 并不是模型开发实验室自身发布的唯一智能体：GLM 的作者 Z.ai 有 ZCode 环境，MiniMax 有终端版的 MiniMax Code。两者都使用相同的密钥连接到同一个网关。