2024 年底到 2025 年Coding Agent 成了 AI 开发工具赛道最拥挤的地方。从闭源的 Devin到开源的 OpenHands再到各家大模型厂商推出的 Codex、Claude Code几乎每个团队都在做“AI 程序员”。但如果你真的拿这些工具做过中型项目一定会发现一个扎心的事实模型本身都差不多真正拉开体验差距的是模型外面那层“壳”。这层壳在架构上有一个更准确的名字——Harness。它不负责写代码但它决定了 Agent 怎么拆任务、怎么调用工具、怎么判定成功、怎么回滚错误。这篇文章想拆解的不是某一个具体产品而是以 DeepSeek 为基座模型的 Coding Agent Harness 架构。我会从概念边界、分层架构、核心组件、最小可运行示例、生产环境工程化几个角度展开帮你建立对“Agent 控制系统”的判断力。读完你至少能回答一个问题如果让我来设计一个基于 DeepSeek 的 Coding Agent哪些组件决定成败。1. 这篇文章真正要解决的问题先说结论当大家都能调用 GPT、Claude 或 DeepSeek 时Coding Agent 的竞争力不在“模型聪明不聪明”而在“外部控制框架够不够稳”。“Harness”控制框架/测试框架原本是 LLM 评测领域的概念用于描述一套把模型包起来的输入管理、输出解析、结果验证机制。放到 Coding Agent 里它变成一个更复杂的系统模型只是大脑Harness 是运动神经、手脚、裁判和记忆系统。大多数用户对 Coding Agent 的抱怨其实是 Harness 的问题而不是模型的问题Agent 改一个 Bug结果把无关文件也改了——这是上下文管理和改动范围控制失败。Agent 反复尝试同一种错误方案浪费大量 token——这是规划器没有收敛机制。Agent 说“已完成”但测试根本没跑过——这是评测层缺失。Agent 改完代码后项目无法构建也没有任何回滚——这是执行沙箱和版本控制没做好。如果你正准备在企业项目里接入 Coding Agent或者在做 Agent 平台选型请把注意力从“哪个模型更强”转移到“这个 Harness 怎么控制模型”。这篇文章适合后端工程师、AI 应用开发者和技术负责人阅读。2. 先理清概念Coding Agent、Harness 与“套壳”的边界在拆架构之前必须先分清几个被混用的概念。2.1 Coding AgentCoding Agent 是一个能自主完成开发任务的 AI 系统。它通常具备四个能力理解用户意图自然语言或 issue。规划任务把需求拆成步骤。操作工具读文件、写文件、执行命令、调用 API。自我验证跑测试、看报错、修正。缺少任何一环严格意义上都不是 Agent而只是聊天机器人。2.2 Harness 的原始含义Harness 这个词来自 LLM 评测框架比如 OpenAI Evals、lm-evaluation-harness。它的核心作用是你把一个模型放进 Harness它能稳定地跑完评测数据给出可对比的分数。一个标准的评测 Harness 至少包含数据加载输入样例。模型调用封装。输出解析。评分器和标准答案对比。结果汇总。到 Coding Agent 这里Harness 的含义被扩展了它不只是“评测框架”而是“控制 Agent 运行的完整框架”。你可以把它理解为Agent 是一辆车Harness 是驾驶系统加赛道计时系统。2.3 容易混淆的产品形态形态典型产品核心能力与 Harness 的关系IDE 插件GitHub Copilot、Cursor代码补全、内联问答、多文件编辑最简单的 AI 辅助没有自主规划能力聊天型助手ChatGPT、DeepSeek 官方对话对话、代码生成、单轮推理无工具或仅有有限工具不做长期任务管理Coding AgentDevin、OpenHands、Claude Code自主规划、工具调用、文件修改、执行命令有 Agent 循环但控制强度参差不齐Agent Harness 平台企业自建居多在 Agent 之上增加评测、沙箱、权限、可观测、回滚能力本文讨论的架构主题有一个容易产生的误解认为 Harness 是一层“多余包装”模型足够强就不需要它。实际恰好相反。DeepSeek-R1 这种推理模型虽然擅长复杂逻辑但如果不加控制它可能输出大量调试思路却不真正落地不加沙箱地让它执行终端命令也存在风险。Harness 的存在意义就是既发挥模型能力又限制它的行为边界。3. DeepSeek Harness 整体架构分层一个设计良好的 Harness 通常采用分层架构。下面以 DeepSeek 为基座模型给出通用分层方式。3.1 分层概览从外到内可以分成六层接入与控制层处理用户请求、对话会话、任务队列、权限校验。规划与编排层把需求拆成可执行步骤维护任务状态机。模型网关层统一封装 DeepSeek API处理模型路由、重试、流式输出。工具与动作层文件操作、命令执行、信息检索、外部 API。执行沙箱层隔离代码运行环境限制网络和资源。评测与数据层验证 Agent 产出、保存执行轨迹、沉淀评测集。这六层之间是单向依赖上层只管下命令下层只对上层暴露接口。3.2 为什么以 DeepSeek 为底座值得关注从公开信息看DeepSeek 之所以适合作为 Harness 的基座主要有三点DeepSeek-V3 采用 MoE混合专家架构总参数量大但每次推理只激活部分参数配合公开可查的 API 定价长任务成本优势明显。DeepSeek-R1 是推理模型能把复杂编程任务拆解为推理链适合 Harness 里的“规划器”角色。API 兼容 OpenAI 协议接入成本极低不需要为每个 Agent 框架写单独适配。这里要做一个区分deepseek-chat指向 V3 系列适合快速代码生成、工具调用、多轮对话deepseek-reasoner指向 R1 系列适合复杂问题推理和长链路规划。后面会给出具体路由示例。3.3 一个 Harness 请求的完整链路假设用户提交了一个任务“修复 login 模块的竞态问题并补一个回归测试”。链路如下接入层接收任务创建任务 ID记录用户身份和权限。规划器把任务拆成定位代码、分析竞态、修改、写测试、运行测试。模型网关调用 deepseek-chat 生成具体修改方案调用 deepseek-reasoner 对竞态场景做推理分析。工具层执行文件读取、代码替换、git diff 对比。沙箱运行 pytest捕获输出。评测层判断测试是否通过若不通过则回到规划器带着失败信息生成下一次修复。全部完成后保存执行轨迹返回给用户 diff 和测试结果。这个链路里模型只是其中一环。每一层的设计都决定了 Agent 是“可靠的工具”还是“偶尔能用的玩具”。4. 从模型到 AgentDeepSeek 模型接入架构解析4.1 为什么选择 OpenAI 兼容接口DeepSeek 官方 API 提供 OpenAI 兼容格式这意味着所有基于 OpenAI SDK 的工具链都能直接使用。实际接入时只需要修改 base_url 和 api_key。这种方式给架构带来的好处很直接Harness 可以同时接入多个模型厂商做 A/B 对比或故障切换。已经存在的 LangChain、LlamaIndex、OpenAI Agents SDK 等框架无需大改。评测框架可以标准化输出格式。风险也很明显兼容并不意味着所有参数都生效比如某些 OpenAI 特有参数在 DeepSeek 端可能被忽略。架构上要注意抽象一层“模型参数映射”而不是把所有 OpenAI 参数直传。4.2 模型路由chat 模型与推理模型的分工在 Harness 设计中强烈建议不要把“规划”和“执行”捆在同一个模型调用里。更合理的方式是配置模型路由代码生成、文件修改、工具参数生成使用 deepseek-chat延迟低成本低。复杂问题推理、长期规划、错误根因分析使用 deepseek-reasoner推理质量高。from openai import OpenAI client OpenAI( api_keyyour-deepseek-api-key, base_urlhttps://api.deepseek.com ) def chat_completion(messages, modeldeepseek-chat, toolsNone, temperature0.3): payload {model: model, messages: messages, temperature: temperature} if tools: payload[tools] tools response client.chat.completions.create(**payload) return response.choices[0].message真实项目中建议配置项不要写在代码里而是放在环境变量或配置中心export DEEPSEEK_API_KEYsk-xxxxxxxx export DEEPSEEK_CHAT_MODELdeepseek-chat export DEEPSEEK_REASONER_MODELdeepseek-reasoner4.3 上下文管理与工具调用设计Harness 不比普通聊天它会持续产生文件内容、命令输出、报错堆栈如果不做上下文管理很快会撑爆模型上下文窗口。常用策略包括滑动窗口只保留最近的对话和工具结果早期中间步骤做摘要。关键信息压缩文件 diff 只保留变更部分不保留整份文件。检索增强把项目文档、历史 issue、测试报告向量化按需检索注入。工具调用这一层DeepSeek 支持 function calling。Harness 应该把“文件读取”“写入文件”“执行命令”“搜索代码”都定义为工具让模型决定何时调用而不是靠自己臆测项目内容。[ { type: function, function: { name: execute_command, description: 在项目沙箱内执行 shell 命令并返回输出, parameters: { type: object, properties: { command: { type: string, description: 要执行的 shell 命令 }, timeout: { type: integer, description: 超时时间秒, default: 30 } }, required: [command] } } } ]需要特别提醒工具调用权限是安全核心。不能让 Agent 无限制执行命令至少要做到命令白名单、路径限制、超时控制和人工审批机制。5. 一个最小可运行的 Harness 架构示例这部分我们做一个“最小 Harness”展示规划、调用模型、执行工具、评测四个核心环节。这个示例不追求生产级但足够说明架构骨架。5.1 环境准备Python 3.10 或更高版本。安装 openai SDKpip install openai pyyaml一个可用的 DeepSeek API Key。说明DeepSeek API 的具体版本和限制以官方文档为准本文重点是演示 Harness 的通用实现思路。pip install openai pyyaml5.2 项目结构deepseek-harness-demo/ ├── config.yaml ├── harness.py ├── tools.py └── evaluator.py5.3 配置文件# config.yaml model: chat: deepseek-chat reasoner: deepseek-reasoner temperature: 0.3 timeout: 120 sandbox: work_dir: ./workspace allowed_commands: [python, pytest, git] max_output_chars: 8000 evaluation: required_tests: [pytest]5.4 工具层实现第一步是让 Agent 具备操作项目的能力。这里我们只做两个最基础的工具执行命令、读取文件。# tools.py import os import subprocess class ToolExecutor: def __init__(self, config): self.work_dir config[sandbox][work_dir] self.allowed_commands config[sandbox][allowed_commands] self.max_output config[sandbox][max_output_chars] def execute_command(self, command: str, timeout: int 30) - dict: # 安全检查只允许白名单内的命令 cmd command.split()[0] if cmd not in self.allowed_commands: return {ok: False, error: fcommand not allowed: {cmd}} try: result subprocess.run( command, shellTrue, cwdself.work_dir, capture_outputTrue, textTrue, timeouttimeout, ) output (result.stdout result.stderr)[-self.max_output:] return {ok: True, output: output, returncode: result.returncode} except subprocess.TimeoutExpired: return {ok: False, error: timeout expired} def read_file(self, path: str) - dict: full_path os.path.join(self.work_dir, path) full_path os.path.abspath(full_path) if not full_path.startswith(os.path.abspath(self.work_dir)): return {ok: False, error: path outside workdir} try: with open(full_path, r, encodingutf-8) as f: content f.read() return {ok: True, content: content[-self.max_output:]} except Exception as e: return {ok: False, error: str(e)}关键点执行命令前做白名单校验避免 Agent 随意执行 rm、curl 之类的命令。读取文件时校验路径防止穿越工作目录。对输出做长度截断避免上下文膨胀。5.5 评测层实现Harness 和聊天机器人的最大区别在于它需要程序化判断“任务是否完成”。# evaluator.py class Evaluator: def __init__(self, config): self.required_tests config[evaluation][required_tests] def validate(self, tool_executor) - dict: results {} all_passed True for test_cmd in self.required_tests: res tool_executor.execute_command(test_cmd, timeout60) passed res.get(ok, False) and res.get(returncode) 0 results[test_cmd] { passed: passed, output: res.get(output, res.get(error, )), } if not passed: all_passed False return {all_passed: all_passed, results: results}这是一个非常简化的评估逻辑跑测试看退出码。真实项目还需要支持用例级断言、覆盖率阈值、静态检查等。5.6 Harness 主循环# harness.py import json from openai import OpenAI from tools import ToolExecutor from evaluator import Evaluator import yaml class DeepSeekHarness: def __init__(self, config_pathconfig.yaml): with open(config_path, r, encodingutf-8) as f: self.config yaml.safe_load(f) self.client OpenAI( api_keyself.config.get(api_key), base_urlhttps://api.deepseek.com, ) self.tools ToolExecutor(self.config) self.evaluator Evaluator(self.config) self.messages [] def run_task(self, task: str, max_iterations: int 5): system_prompt ( 你是项目里的编程助手。你可以执行命令和读取文件。 每次先分析任务再选择工具。 输出必须是对工具的调用 JSON不要额外解释。 ) self.messages [{role: system, content: system_prompt}] self.messages.append({role: user, content: task}) for iteration in range(max_iterations): print(f--- Iteration {iteration 1} ---) response self.client.chat.completions.create( modelself.config[model][chat], messagesself.messages, temperatureself.config[model][temperature], tools[{ type: function, function: { name: execute_command, description: 执行 shell 命令, parameters: { type: object, properties: { command: {type: string} }, required: [command] } } }], tool_choiceauto, ) message response.choices[0].message if not message.tool_calls: # 没有工具调用说明模型认为任务完成 print(Agent finished with message:, message.content) break for tool_call in message.tool_calls: args json.loads(tool_call.function.arguments) result self.tools.execute_command(args[command]) print(fCommand: {args[command]}) print(fResult: {result.get(output, result.get(error))}) self.messages.append({ role: assistant, tool_calls: [ { id: tool_call.id, type: function, function: { name: tool_call.function.name, arguments: tool_call.function.arguments, }, } ], }) self.messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) # 每次循环结束前做一次评测 validation self.evaluator.validate(self.tools) if validation[all_passed]: print(All tests passed. Task done.) return {ok: True, message: message.content} return {ok: False, error: max iterations reached} if __name__ __main__: harness DeepSeekHarness(config.yaml) result harness.run_task(运行测试并修改代码直到测试通过) print(result)这段代码有几点刻意简化需要说明它只支持 execute_command 一个工具真实场景还要加 read_file、write_file、search 等。没有把评测失败信息拼回 prompt严格来说需要把测试输出作为反馈继续驱动模型修正。没有做 token 预算和成本控制长任务会失控。但它的骨架是对的模型调用、工具执行、评估验证、循环回退四个要素都已经齐了。5.7 运行和验证在实际运行前需要先准备一个最小 Python 工程作为工作区。mkdir -p workspace cd workspace printf def add(a, b):\n return a b\n calc.py printf from calc import add\n\ndef test_add():\n assert add(2, 3) 5\n test_calc.py cd .. python harness.py预期行为Harness 启动后Agent 可能会先执行 pytest 看测试是否通过。如果测试通过评测层直接判定任务完成。如果测试失败Agent 会读取文件并修复再重新跑测试。如果运行失败第一件事看 API 返回的错误信息是鉴权失败还是模型参数不支持还是工具执行超时。不要盲目换 prompt。6. 拆解 Harness 的关键组件与选型建议上面是最小骨架下面从架构师视角深入几个关键组件。6.1 规划器任务分解与上下文管理Coding Agent 的规划器和传统任务调度不一样它本质上是“把模型输出变成可控状态机”。好的规划器应该做到将大任务拆成可验证的小步。维护一个任务队列而不是一次性把所有步骤塞给模型。失败时支持局部重试而不是从头开始。对长期上下文做摘要和中转。常见的实现有两种第一种是纯“提示驱动”让模型自己输出 plan然后 Harness 解析第二种是用代码强制流程比如先定位再修改再测试每一步都由代码校验。生产环境建议混合使用大方向由代码强制具体细节由模型规划。6.2 工具调用function calling 与安全边界DeepSeek 支持 function calling但这只是能力底座工具层的设计决定安全性。设计工具层时至少要有以下约束约束项建议命令白名单只允许 pytest、git、python 等必要命令文件路径限制Agent 只能操作工作区目录网络隔离默认禁止外网访问需要时显式开放资源限制单命令超时、内存上限、磁盘上限操作审批高危操作git push、删除分支、生产变更必须人工确认操作留痕所有工具调用都要有结构化日志6.3 评测循环Harness 最容易被忽略的一层很多 Coding Agent 失败不是因为代码写得不对而是因为它声称完成了实际没有。评测层就是用来解决这个信任问题的。评测不能只停留在“命令能跑通”建议分层冒烟级进程能启动、退出码为 0。功能级关键测试用例通过。回归级全部测试通过且覆盖率不下降。静态检查lint、类型检查通过。人类评审关键项目保留人工审核环节。在架构上评测层应该独立于模型层。这样即使未来换掉底层模型评测逻辑不需要变。6.4 记忆与知识库长期项目的关键每次任务都从零开始的 Agent在大型项目里会表现得很笨。它不记得上次为什么选某个方案也不了解项目的模块边界。建议 Harness 引入项目级记忆代码索引函数、类、模块的调用关系。任务历史之前修过哪些 Bug采用什么方案。决策记录架构选型和约束条件。常见错误库编译错误和对应修复策略。对中小项目可以先做成 Markdown 档案每次任务前注入模型对大型项目再引入向量检索。7. 常见问题与排查思路问题现象可能原因排查方式解决方案API 鉴权失败API Key 错误或未配置检查环境变量 DEEPSEEK_API_KEY调用官方接口测试重新生成 Key确认 base_url 正确工具执行超时命令本身阻塞或沙箱资源受限查看工具日志中的 time 字段手动执行同一条命令设置更短超时禁止交互式命令模型返回 JSON 解析失败function calling 参数格式不对或模型输出被截断打印原始 message 内容检查 tools 定义增加重试和格式化解析降低输出长度上限上下文窗口溢出工具输出过长历史消息累积查看 token 统计检查 messages 长度截断工具输出对历史消息做摘要滑动窗口裁剪Agent 反复试错不收敛评测反馈没有拼回 prompt检查评测失败信息是否作为新消息返回把 stdout/stderr 和退出码拼成用户消息反馈给模型修改了无关文件上下文里塞入了过多项目文件查看 Agent 实际读取了哪些文件引入代码检索按需注入工具层设置写文件白名单测试全部通过但结果仍然不对评测集覆盖不足检查测试用例是否覆盖需求补充回归用例增加人工审核环节排查时记住一个顺序先确认模型网关层有没有正确返回再确认工具层有没有正确执行最后才去怀疑规划逻辑。8. 工程化最佳实践8.1 安全先行Agent 是“主动执行者”不是“被动回答者”。所有工具调用都应当遵守最小权限原则。生产环境部署时强烈建议把 Agent 放进隔离容器或虚拟机限制文件系统、网络和系统调用。能通过 API 完成的操作用 API不要给终端 shell。8.2 评测先行在写 Agent 功能之前先定义“什么叫完成”。没有评测集的 Harness 无法保证质量。建议从第一天就把用户需求转成测试用例再让 Agent 去实现。8.3 可观测性与日志每个工具调用、每次模型请求、每个 token 消耗都应该有日志和链路追踪。我是建议保留完整的执行轨迹这一步既可以在 Agent 出错时回放排查也可以沉淀为后续训练或评测数据。8.4 版本控制与回滚Agent 修改文件前先创建 git commit 或快照任务失败时能一键回滚。生产环境不要直接让 Agent 操作主分支建议使用独立分支加 MR 评审流程。8.5 成本控制推理模型的成本高于普通对话模型。架构上应该区分轻量任务和重量任务不要所有请求都走 reasoner 模型。还可以为单任务设置 token 预算上限超了就暂停并请求人工确认。8.6 模型无关设计Harness 的每一层都应该尽量避免和具体模型绑定。把模型调用封装成接口把评测逻辑独立出来这样后续无论是换模型还是接本地部署的模型成本都可控。9. 总结与下一步学习方向DeepSeek Harness 的本质不是“用一个更强的模型写代码”而是“用一个可控的框架组织模型的推理和行动能力”。模型负责生成判断Harness 负责判断是否成立、操作是否安全、任务是否完成。这种架构思维适用于任何基座模型。如果你想继续深入建议按这个顺序学习把上面的最小示例跑通理解 Agent 循环和评测循环。研究 LangGraph 这类编排框架的状态机设计。看一下 OpenAI Agents SDK 和 open-source 的 Coding Agent 项目里工具层和沙箱是怎么设计的。学习 LLM 评测框架把“评测意识”应用到 Agent 开发中。最后提醒一句不要急于搭建复杂的多 Agent 架构。先把单 Agent 的 Harness 打磨到“稳定通过评测集、不越权操作、错误可回滚”再谈多机协作。架构的价值不在复杂而在可控。