DeepSeek Harness 配合 OpenAI 兼容 API

DeepSeek Harness 可以使用 OpenAI 兼容的模型端点，需要提供四个值：基础 URL、API 密钥、模型 id 和 Chat Completions 路径。 对于 reAPI，基础 URL 是 https://api.reapi.ai/v1，当前模型 id 为 deepseek-v4-flash 和 deepseek-v4-pro。^[1][2]

Harness 项目仍被标记为开发者预览版，其命令名称和配置文件可能会更改。稳定的部分是提供者契约。先配置契约，然后验证一条普通消息和一个工具调用，再安装其他插件。

需要映射的四个值

不要将密钥粘贴到仓库文件中。提供者插件应从环境变量或当前 Harness 版本支持的密钥存储中读取密钥。

在 HTTP 层，请求应该解析为：

POST https://api.reapi.ai/v1/chat/completions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

这个最小请求体足以在调试代理行为前测试模型访问权限：

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "Reply with exactly: provider ok" }
  ],
  "stream": false,
  "max_tokens": 64
}

如果直接请求失败，问题不在 Harness。先修复 URL、密钥、模型 id、账户余额或网络访问。

从 Flash 开始，将困难任务升级到 Pro

两个当前 DeepSeek V4 变体都提供 100 万令牌上下文窗口、最多 384K 输出、工具使用、思考模式、视觉输入，以及 reAPI 路由上的上下文缓存。^[2] 它们的价格和预期工作负载差异很大。

代理循环重复指令、仓库上下文和工具模式。这使缓存行为特别重要。Flash 缓存命中输入比缓存未命中便宜 50 倍；Pro 缓存命中输入比未命中便宜 120 倍。

在接线代理时使用 Flash 作为默认值。仅当推理要求大约是缓存未命中输入和输出率的 12.4 倍时，才将步骤路由到 Pro。

保持稳定前缀不变

上下文缓存在连续请求的开头保持相同时最有用。在编码代理中，该前缀通常包含：

• 系统指令；
• 仓库策略；
• 工具定义和 JSON 模式；
• 不变的架构文档；
• 最新工具结果前的先前对话。

重新排列工具、在顶部附近添加时间戳或用略有不同的措辞重新生成相同的指令可能会阻止前缀重用。在稳定块之后放置易变状态。

例如，一个包含 200,000 个稳定输入令牌、10,000 个新输入令牌和 8,000 个输出令牌的 Pro 循环成本大约为：

200,000 cached input × $0.0145 / 1,000,000 = $0.0029
 10,000 new input    × $1.74   / 1,000,000 = $0.0174
  8,000 output       × $3.48   / 1,000,000 = $0.02784
                                                -------
                                                $0.04814

没有缓存命中，相同的 210,000 输入令牌在输出前的成本将是 $0.3654。代理的上下文布局可能比修剪最新消息中的几百个令牌更重要。

在添加插件前验证工具调用

成功的聊天响应不能证明代理可以行动。接下来运行一个无害的工具调用测试：

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "What files are in the current directory?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "list_files",
        "description": "List files in the current working directory",
        "parameters": { "type": "object", "properties": {} }
      }
    }
  ],
  "tool_choice": "auto"
}

模型应该返回一个结构化的工具调用。Harness 执行本地函数并在下一轮提供结果。如果模型以散文形式打印"我会列出文件"，检查提供者插件是否转发了 tools 并完整返回助手工具调用字段。

五个看起来像模型问题的失败点

当前 DeepSeek V4 路由默认启用思考。推理令牌计入输出使用，所以输出上限小可能在工具计划前结束用户可见的答案。^[2]

使用一次性仓库测试完整代理循环

在消息和工具调用探测通过后，为 Harness 提供一个为集成测试创建的小仓库。它应包含一个可读文件、一个失败的测试、一个受保护的路径和一个无害的命令。要求代理诊断测试、提议补丁、运行窄检查，并在任何提交或外部操作前停止。

这揭示了 JSON 工具调用测试无法发现的四个集成故障：

• 相对路径解析超出预期工作目录；
• 命令输出在模型看到错误前被截断；
• 补丁工具改变行尾或文件编码；
• 批准边界在 UI 中强制但在插件中不强制。

重启 Harness 后重复相同的任务。会话恢复在编码代理中很重要，因为长时间运行在普通边界失败：笔记本睡眠、进程重启、提供者超时或格式错误的工具输出。第一轮工作是不够的。

记录足够的日志以区分运行时和模型故障

至少保留请求 id、选定的模型、令牌使用、缓存命中令牌、完成原因、工具名称、工具持续时间和已编辑的错误。不要记录 API 密钥或无限制的文件内容。

当代理停止时，这些字段回答不同的问题：

没有这种分离，团队经常切换模型来修复缺失的环境变量或重写提示来修复丢弃的工具结果。

不要将隐藏推理作为对话历史转发

DeepSeek V4 响应可以将推理内容与最终答案分开。API 文档建议在下一轮前删除先前的推理内容。^[2] 在产品的策略下存储计费和调试所需的内容，但不要将隐藏推理追加到下一个用户/助手历史作为普通内容。

对话应保留可见的助手响应、结构化的工具调用和协议所需的工具结果。这保持下一个请求有效，并防止上下文使用端点不期望接收的材料增长。

插件安全应在设置中考虑，之后不行

Harness 预览支持插件，这也意味着第三方代码可能会接收提示、文件、工具输出或网络访问。启用前：

1. 阅读插件源代码和权限表面；
2. 在一次性仓库或沙盒中运行 Harness；
3. 以只读文件系统工具开始；
4. 阻止密钥文件和父目录；
5. 要求对 shell、包安装、git 推送和外部消息进行确认。

模型端点无法纠正过度许可的本地插件。该边界属于代理运行时。

当前的模型契约和 SDK 示例在 DeepSeek V4 API 文档 中，实时价格在 DeepSeek V4 模型页面。

参考文献

1. DeepSeek, "deepseek-harness" official repository, developer preview, accessed August 23, 2026.
2. reAPI DeepSeek V4 API documentation, accessed August 23, 2026.
3. DeepSeek Harness official product page, accessed August 23, 2026.