企业官网建设流程全解析

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 Agent

Coding 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 是一层“多余包装”，模型足够强就不需要它。实际恰好相反。DeepSeek-R1 这种推理模型虽然擅长复杂逻辑，但如果不加控制，它可能输出大量调试思路却不真正落地；不加沙箱地让它执行终端命令，也存在风险。Harness 的存在意义，就是既发挥模型能力，又限制它的行为边界。

3. DeepSeek Harness 整体架构分层

一个设计良好的 Harness 通常采用分层架构。下面以 DeepSeek 为基座模型，给出通用分层方式。

3.1 分层概览

从外到内，可以分成六层：

1. 接入与控制层：处理用户请求、对话会话、任务队列、权限校验。
2. 规划与编排层：把需求拆成可执行步骤，维护任务状态机。
3. 模型网关层：统一封装 DeepSeek API，处理模型路由、重试、流式输出。
4. 工具与动作层：文件操作、命令执行、信息检索、外部 API。
5. 执行沙箱层：隔离代码运行环境，限制网络和资源。
6. 评测与数据层：验证 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 模块的竞态问题，并补一个回归测试”。

链路如下：

1. 接入层接收任务，创建任务 ID，记录用户身份和权限。
2. 规划器把任务拆成：定位代码、分析竞态、修改、写测试、运行测试。
3. 模型网关调用 deepseek-chat 生成具体修改方案，调用 deepseek-reasoner 对竞态场景做推理分析。
4. 工具层执行文件读取、代码替换、git diff 对比。
5. 沙箱运行 pytest，捕获输出。
6. 评测层判断测试是否通过，若不通过则回到规划器，带着失败信息生成下一次修复。
7. 全部完成后，保存执行轨迹，返回给用户 diff 和测试结果。

这个链路里，模型只是其中一环。每一层的设计，都决定了 Agent 是“可靠的工具”还是“偶尔能用的玩具”。

4. 从模型到 Agent：DeepSeek 模型接入架构解析

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_key="your-deepseek-api-key", base_url="https://api.deepseek.com" ) def chat_completion(messages, model="deepseek-chat", tools=None, temperature=0.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_KEY="sk-xxxxxxxx" export DEEPSEEK_CHAT_MODEL="deepseek-chat" export DEEPSEEK_REASONER_MODEL="deepseek-reasoner"

4.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 SDK：pip install openai pyyaml
• 一个可用的 DeepSeek API Key。

说明：DeepSeek API 的具体版本和限制以官方文档为准，本文重点是演示 Harness 的通用实现思路。

pip install openai pyyaml

5.2 项目结构

deepseek-harness-demo/ ├── config.yaml ├── harness.py ├── tools.py └── evaluator.py

5.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": f"command not allowed: {cmd}"} try: result = subprocess.run( command, shell=True, cwd=self.work_dir, capture_output=True, text=True, timeout=timeout, ) 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", encoding="utf-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, timeout=60) 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_path="config.yaml"): with open(config_path, "r", encoding="utf-8") as f: self.config = yaml.safe_load(f) self.client = OpenAI( api_key=self.config.get("api_key"), base_url="https://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( model=self.config["model"]["chat"], messages=self.messages, temperature=self.config["model"]["temperature"], tools=[{ "type": "function", "function": { "name": "execute_command", "description": "执行 shell 命令", "parameters": { "type": "object", "properties": { "command": {"type": "string"} }, "required": ["command"] } } }], tool_choice="auto", ) 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(f"Command: {args['command']}") print(f"Result: {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_ascii=False), }) # 每次循环结束前做一次评测 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，但这只是能力底座，工具层的设计决定安全性。

设计工具层时，至少要有以下约束：

6.3 评测循环：Harness 最容易被忽略的一层

很多 Coding Agent 失败，不是因为代码写得不对，而是因为它声称完成了，实际没有。评测层就是用来解决这个信任问题的。

评测不能只停留在“命令能跑通”，建议分层：

• 冒烟级：进程能启动、退出码为 0。
• 功能级：关键测试用例通过。
• 回归级：全部测试通过，且覆盖率不下降。
• 静态检查：lint、类型检查通过。
• 人类评审：关键项目保留人工审核环节。

在架构上，评测层应该独立于模型层。这样即使未来换掉底层模型，评测逻辑不需要变。

6.4 记忆与知识库：长期项目的关键

每次任务都从零开始的 Agent，在大型项目里会表现得很笨。它不记得上次为什么选某个方案，也不了解项目的模块边界。

建议 Harness 引入项目级记忆：

• 代码索引：函数、类、模块的调用关系。
• 任务历史：之前修过哪些 Bug，采用什么方案。
• 决策记录：架构选型和约束条件。
• 常见错误库：编译错误和对应修复策略。

对中小项目，可以先做成 Markdown 档案，每次任务前注入模型；对大型项目，再引入向量检索。

7. 常见问题与排查思路

排查时记住一个顺序：先确认模型网关层有没有正确返回，再确认工具层有没有正确执行，最后才去怀疑规划逻辑。

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 负责判断是否成立、操作是否安全、任务是否完成。这种架构思维，适用于任何基座模型。

如果你想继续深入，建议按这个顺序学习：

1. 把上面的最小示例跑通，理解 Agent 循环和评测循环。
2. 研究 LangGraph 这类编排框架的状态机设计。
3. 看一下 OpenAI Agents SDK 和 open-source 的 Coding Agent 项目里工具层和沙箱是怎么设计的。
4. 学习 LLM 评测框架，把“评测意识”应用到 Agent 开发中。

最后提醒一句：不要急于搭建复杂的多 Agent 架构。先把单 Agent 的 Harness 打磨到“稳定通过评测集、不越权操作、错误可回滚”，再谈多机协作。架构的价值不在复杂，而在可控。