如何构建面向真实代码库的 DeepSeek Coding Harness

构建一个 DeepSeek Coding Harness，重点不在于写出一个聪明的 Prompt，而在于设计一套可靠的执行系统。模型需要用一种可控的方式检查代码库、选择动作、运行工具、观察结果，再决定下一步。

本文聚焦这条系统边界，并假设你已经能够向 DeepSeek 兼容端点发送请求并接收模型响应。

从明确的 Agent 循环开始

让编排循环保持足够小，开发者可以直接理解。简化后大致如下：

while (!task.done) {
  const context = await buildContext(task, session);
  const response = await model.respond(context, tools);
  const result = await execute(response.toolCall, policy);
  await session.append({ response, result });
  task = evaluate(task, response, result);
}

生产代码还需要取消、重试、非法工具调用处理、Token 限制和审批状态，但核心关系应该始终清晰：模型决策 → 受控执行 → 真实结果。

如果工具执行被藏在很多无关抽象之后，排查一次失败的 Agent 任务会非常困难。

定义窄而明确的工具契约

可以从最小工具集开始：

• search：搜索路径和符号。
• read：读取有限的文件范围。
• patch：应用可审查的修改。
• shell：运行项目命令。
• status：查看 Git 状态和 diff。

每个工具都应验证输入，并返回结构化结果。限制文件大小、命令时长、结果长度和可写路径。即使任务本身可信，也应把模型生成的参数当作不可信输入处理。

不要把每个操作都变成 Shell 命令。专用的读取或补丁工具比一个什么都能做的自由命令更容易验证、记录和解释。

渐进式构建上下文

上下文构建器是 DeepSeek Harness 最重要的部分之一。它的任务不是加载所有内容，而是为下一次正确决策提供最少但足够的状态。

一个实用顺序是：

1. 用户任务与当前计划。
2. AGENTS.md 等代码库指令。
3. 通过搜索发现的相关文件片段。
4. 当前 diff 与最近的工具结果。
5. 简洁的用量摘要。

把长期事实和临时输出分开。项目规则可能影响整个会话；一段 500 行编译日志，在当前错误解决后通常只需要保留摘要。

上下文压缩应该保留决策、未解决问题、改动文件和验证状态，而不是简单删除最早的消息。

把权限写进策略代码

Prompt 指令不是安全边界。执行策略应该决定：

• 哪些代码库目录可读、可写。
• 命令是否可以联网。
• 可以访问哪些环境变量。
• 哪些命令必须由人确认。
• 如何解析并验证破坏性操作的目标。

在可能时，把普通开发命令放进操作系统沙箱。权限升级应该明确、范围有限，并记录在会话轨迹中。

还要按请求类型区分授权。用户要求诊断故障，意味着可以检查；它并不会自动授权修改生产状态。

把测试当作一等工具结果

Harness 应该让模型能够方便地运行小范围检查、读取失败信息并继续。测试结果需要稳定格式和长度限制，避免一个噪声很大的命令占满整个上下文窗口。

至少记录：

• 命令与工作目录。
• 退出码与耗时。
• 相关的 stdout 和 stderr。
• 输出是否被截断。
• 与上次检查相比改动了哪些文件。

验证应该从小到大。一个专注的单元测试通常比反复运行整个构建更快地提供反馈。

保存可重放的会话

保存消息、可用的推理元数据、工具调用、工具结果、审批、补丁和用量。追加式 JSONL 会话简单、可检查，也能抵抗部分写入失败。

为每条记录分配稳定 ID 和时间戳。记录足够的信息来还原工具为什么运行，但不要把环境返回的密钥持久化。

可重放会话支持继续任务、调试、审计，以及未来使用 Stub 模型进行确定性的 Harness 测试。

隔离之后再增加并行 Agent

并行 Agent 适合独立探索、实现、审查和测试，同时也会带来新问题：编辑冲突、上下文重复和所有权不清。

增加并发之前，需要定义：

• 最大活跃 Agent 数。
• 哪些任务只读。
• 什么时候实现任务进入独立 Git worktree。
• 子 Agent 如何把发现返回父 Agent。
• 谁负责最终集成与验证。

并行的目标应该是缩短关键路径，而不是让会话变得更难理解。

测量上下文、缓存、Token 与成本

记录每次模型调用的用量，并在会话级聚合。展示输入 Token、输出 Token、可用时的缓存 Token、推理、上下文容量和预估费用。

然后把指标与行为联系起来。反复加载同一个大文件，说明上下文管理可能有问题；子 Agent 消耗大量 Token 却没有带回新证据，说明委派策略可能有问题。

Harness 应该让低效行为可以被调试。

用证据定义完成

Agent 不应该只因为模型说“完成了”就停止。完成条件应该来自任务和代码库：

• 请求的行为已经实现。
• 相关测试通过。
• 项目要求时，生产构建或类型检查通过。
• diff 中没有无关改动。
• 剩余限制被清楚说明。

最终回复是一份简洁交接：结果、改动文件、验证，以及仍需开发者决定的事项。

自己构建，还是直接采用

当你需要特殊工具、权限策略或部署约束时，自己构建 Harness 很合理；同时你也需要承担会话存储、工具安全、模型重放、上下文管理、测试和界面设计。

DSCode 是已经实现核心代码库循环的开源 DeepSeek Coding Harness。你可以直接使用，也可以在设计自己的系统之前研究它的实现方式。

想理解基础概念，可以阅读《什么是 DeepSeek Harness？》；想了解开发者实际工作流，可以阅读《DeepSeek Code Agent：从 Prompt 到通过测试的代码改动》。