设计Agent就像盖房子，你得先选对结构 —— 砖混、框架还是钢结构，再按图纸砌砖，而不是先乱堆一堆砖头，再想怎么让它不塌。Harness Engineering 的设计范式，就是经过 OpenAI、LangChain、Anthropic 这些大厂生产验证过的「Agent 架构图纸」，是让你的 Agent 从 Demo 走向生产的核心骨架。
今天这篇文章，我把5 大主流 Harness Engineering 设计范式全拆解透了，每个范式都讲透适用场景、核心架构、可直接复制的代码、避坑指南，看完你就能直接套用到自己的项目里，不管是个人提效还是团队生产，都能用。
前置认知：到底什么是 Harness 设计范式？
先给大家一个面试能直接说的标准答案，一句话拉开你和 90% 人的差距：Harness 设计范式，是经过生产验证的、可复用的 Harness 架构设计模式，它定义了模型如何与系统交互、任务如何流转、规则如何执行、反馈如何闭环，解决的是「Agent 输出不可控、长任务易失败、场景难扩展」的核心问题。
再直白点说：普通 ReAct 循环是 “给 AI 一把锤子，让它自己看着办”，而 Harness 范式是 “给 AI 搭了一条完整的生产线，每一步该干什么、不能干什么、干错了怎么办，全给它定死了，出来的结果稳定可控”。
范式一：单 Agent 全闭环范式 —— 新手入门必学，80% 的场景都能用
这是所有 Harness 范式的基础，也是个人开发者、小工具场景用得最多的范式，OpenAI 官方说的「人类掌舵，智能体执行」，最小闭环就是这个范式。
【适用场景】
个人提效工具、简单自动化任务、单一场景小 Agent、新手入门学习、面试 Demo 快速落地。比如：自动写周报、批量处理 Excel、简单接口测试、单功能代码生成。
【核心设计思想】
一个 Agent，一套 Harness，一个完整闭环。把「规则注入→任务执行→工具调用→结果校验→失败重试→结果输出」全链路封在一个 Harness 里，没有复杂的调度，极简、稳定、易维护，彻底解决普通 ReAct“输出不可控、干错了没人管” 的问题。
【可直接落地的代码示例】
Python 实现的完整单 Agent 闭环 Harness，复制就能改了用：
from openai import OpenAI
client = OpenAI()
class SingleAgentHarness:
"""单Agent全闭环Harness范式实现"""
def __init__(self, system_rules: str, max_retry: int = 3):
self.system_rules = system_rules # Harness核心：定死行为边界
self.max_retry = max_retry # 重试兜底机制
self.conversation_history = [] # 会话状态管理
def _tool_call_control(self, tool_name: str, params: dict) -> str:
"""Harness工具管控：白名单机制，防止AI乱调用工具"""
allowed_tools = ["read_file", "write_file", "run_bash", "excel_process"]
if tool_name not in allowed_tools:
return f"错误：禁止调用工具{tool_name}，仅允许调用{allowed_tools}"
# 此处可扩展具体工具实现
return f"工具{tool_name}执行完成，参数：{params}"
def _result_validate(self, result: str, task: str) -> tuple[bool, str]:
"""Harness闭环核心：后置结果校验，不合格直接打回"""
validate_prompt = f"""
核心任务：{task}
交付结果：{result}
校验规则：
1. 是否完整完成核心任务
2. 是否符合预设的系统规则
3. 是否有错误、遗漏、不符合要求的内容
只输出【PASS】或【FAIL】，并说明具体原因
"""
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": validate_prompt}],
temperature=0
)
validate_result = response.choices[0].message.content
return "PASS" in validate_result, validate_result
def run(self, task: str) -> str:
"""Harness全链路闭环执行入口"""
# 1. 前置规则注入，从源头管控行为
self.conversation_history = [
{"role": "system", "content": self.system_rules},
{"role": "user", "content": f"核心任务：{task}，严格遵守系统规则执行"}
]
retry_count = 0
while retry_count < self.max_retry:
# 2. 模型推理执行
response = client.chat.completions.create(
model="gpt-4o",
messages=self.conversation_history,
temperature=0.3
)
result = response.choices[0].message.content
self.conversation_history.append({"role": "assistant", "content": result})
# 3. 工具调用管控
if "调用工具" in result:
tool_result = self._tool_call_control("demo_tool", {"param": "demo"})
self.conversation_history.append({"role": "user", "content": f"工具执行结果：{tool_result}"})
continue
# 4. 后置结果校验，闭环核心
is_pass, validate_msg = self._result_validate(result, task)
if is_pass:
return f"任务执行完成：\n{result}\n校验结果：{validate_msg}"
# 5. 失败重试，注入错误信息
retry_count += 1
self.conversation_history.append({
"role": "user",
"content": f"结果不符合要求，失败原因：{validate_msg}，请重新修改，重试次数：{retry_count}/{self.max_retry}"
})
return f"任务执行失败，达到最大重试次数，最终结果：{result}"
# 直接使用示例
if __name__ == "__main__":
# 定义Harness核心规则，定死Agent的行为边界
system_rules = """
你是Java代码生成助手，必须严格遵守以下规则：
1. 所有代码符合SpringBoot 3.2规范，严格遵循分层架构
2. 所有入参必须做校验，禁止使用System.out.println，必须用SLF4J日志
3. 所有SQL必须防止注入，必须使用参数化查询
4. 生成的代码必须包含完整注释、单元测试
"""
# 初始化Harness
harness = SingleAgentHarness(system_rules=system_rules, max_retry=3)
# 执行任务
result = harness.run("生成用户管理CRUD接口，包含Controller、Service、Repository、Entity")
print(result)
【避坑指南】
- 工具白名单越短越稳定，80% 的场景只需要 3-5 个核心工具就够了，别堆一堆没用的工具
- 规则只抓核心红线，别写几百条无效规则，比如你只需要定分层架构，不用管变量名怎么起
- 校验逻辑要可量化，别用 “写得好一点” 这种模糊要求，要明确 “必须包含单元测试” 这种可校验的规则
- 重试次数别超过 3 次，重试多了只会让 AI 在错误的方向上越走越远
范式二：多 Agent 分工协同范式 —— 复杂项目的终极解法
这是 LangChain 官方主推的范式，也是中大型团队、复杂项目的首选。OpenAI 3 人团队 5 个月写 100 万行代码，核心用的就是这个范式的变种。
【适用场景】
中大型复杂项目、多角色分工的任务、团队级生产应用、跨领域复杂任务。比如：完整的 Web 应用全栈开发、复杂的数据分析系统、多模块的业务自动化流程。
【核心设计思想】
分角色、定边界、专事专办。把一个复杂任务，拆成多个专业子角色，每个角色对应一个专属的 Agent，每个 Agent 有自己独立的 Harness（自己的规则、工具、校验逻辑），再通过一个总控 Harness做任务调度、进度同步、结果汇总。
就像一个成熟的开发团队，有产品经理、前端开发、后端开发、测试工程师，每个人只干自己专业的事，比一个人全干效果好 10 倍。普通单 Agent 干复杂活，就像让一个人既当产品又当开发还当测试，必然顾此失彼，干出来的东西全是漏洞。
【可直接落地的代码示例】
Java 实现的多 Agent 总控 Harness 核心调度逻辑，适配后端团队场景：
package com.harness.multiagent;
import java.util.*;
/**
* 多Agent协同分工范式 总控Harness核心实现
*/
public class MultiAgentMasterHarness {
// 角色Agent注册中心，每个Agent有独立的Harness
private final Map<String, AgentHarness> agentRegistry = new HashMap<>();
private final int maxRetry = 3;
public MultiAgentMasterHarness() {
// 注册各角色Agent，每个Agent有独立的规则和Harness
agentRegistry.put("PRODUCT", new AgentHarness(
"产品经理Agent",
"""
你是专业产品经理，输出PRD必须包含：
1. 需求背景、核心目标、用户场景
2. 功能详情、业务规则、异常流程
3. 验收标准、非功能需求
输出必须清晰可落地，开发能直接照着做
"""
));
agentRegistry.put("BACKEND", new AgentHarness(
"后端开发Agent",
"""
你是专业Java后端开发，基于PRD开发必须遵守：
1. SpringBoot 3.2规范，分层架构Controller→Service→Repository→Entity
2. 入参校验、异常处理、日志规范、防SQL注入
3. 代码必须包含完整注释、单元测试
"""
));
agentRegistry.put("TEST", new AgentHarness(
"测试工程师Agent",
"""
你是专业测试工程师，输出测试用例必须包含：
1. 功能测试、边界测试、异常测试用例
2. 接口测试、性能测试要求
3. 验收标准对应的测试点
"""
));
}
/**
* 总控Harness核心执行入口
*/
public Map<String, String> run(String task) {
Map<String, String> resultMap = new HashMap<>();
int retryCount = 0;
while (retryCount < maxRetry) {
try {
// 1. 产品Agent输出PRD
AgentHarness productAgent = agentRegistry.get("PRODUCT");
String prd = productAgent.run("基于以下需求，输出完整PRD：" + task);
resultMap.put("PRD", prd);
// 2. 后端Agent基于PRD开发代码
AgentHarness backendAgent = agentRegistry.get("BACKEND");
String code = backendAgent.run("基于以下PRD，输出完整Java后端代码：" + prd);
resultMap.put("BACKEND_CODE", code);
// 3. 测试Agent输出测试用例
AgentHarness testAgent = agentRegistry.get("TEST");
String testCase = testAgent.run("基于以下PRD，输出完整测试用例：" + prd);
resultMap.put("TEST_CASE", testCase);
// 4. 总控Harness最终校验
boolean isPass = finalValidate(resultMap);
if (isPass) {
resultMap.put("STATUS", "SUCCESS");
return resultMap;
}
retryCount++;
} catch (Exception e) {
retryCount++;
resultMap.put("ERROR", e.getMessage());
}
}
resultMap.put("STATUS", "FAIL");
return resultMap;
}
/**
* 总控Harness最终校验逻辑
*/
private boolean finalValidate(Map<String, String> resultMap) {
return resultMap.containsKey("PRD")
&& resultMap.containsKey("BACKEND_CODE")
&& resultMap.containsKey("TEST_CASE");
}
/**
* 子Agent独立Harness实现
*/
static class AgentHarness {
private final String roleName;
private final String systemRules;
public AgentHarness(String roleName, String systemRules) {
this.roleName = roleName;
this.systemRules = systemRules;
}
public String run(String task) {
// 实际实现调用大模型+独立校验闭环，参考范式一
return "【" + roleName + "】执行结果：\n" + task;
}
}
}
【避坑指南】
- 角色边界必须清晰，绝对不能让一个 Agent 干多个角色的活，比如让后端 Agent 改 PRD，必然逻辑混乱
- 总控 Harness 只做调度和最终校验，绝对不插手具体角色的执行，否则会破坏分工逻辑
- 角色数量别超过 6 个，太多会导致调度混乱、沟通成本过高，反而不如单 Agent
- 必须有统一的信息同步标准，比如 PRD 格式、代码目录结构，所有 Agent 必须遵守，否则各干各的合不起来
范式三：渐进式技能解锁范式 —— 长周期大项目的防崩神器
这是 OpenAI Codex 百万行代码项目的核心范式，专门解决长周期大项目里的「上下文腐烂」「AI 失忆」问题。
【适用场景】
超大型长周期项目、持续迭代的产品开发、多阶段复杂任务、需要避免上下文腐烂的场景。比如：百万行代码级的产品开发、持续数月的自动化项目、多阶段的业务系统搭建。
【核心设计思想】
地图式导航，渐进式披露，用多少给多少。不是一上来把所有规则、工具、技能、文档全塞给 Agent，而是通过 Harness 做一个「导航地图」（也就是 OpenAI 用的 AGENTS.md），把项目拆成多个阶段，Agent 当前阶段需要什么技能、什么规则、什么文档，Harness 就只注入什么内容，用不到的绝对不塞到上下文里。
同时用文件系统做持久化，每一步的进度、决策、成果全存在代码仓库里，Agent 跨会话、跨阶段也不会失忆，彻底解决上下文溢出、干着干着就忘了目标的问题。
【可直接落地的代码示例】
Python 实现的渐进式技能管理 Harness 核心：
import os
from typing import Dict, List
class ProgressiveSkillHarness:
"""渐进式技能解锁范式Harness实现"""
def __init__(self, project_root: str = "./agent_project"):
self.project_root = project_root
self.nav_map_path = os.path.join(project_root, "AGENTS.md")
self.skill_library = {} # 按阶段分类的技能库
self.phase_progress = {} # 阶段进度持久化
self._init_project()
def _init_project(self):
"""初始化项目目录和导航地图"""
os.makedirs(self.project_root, exist_ok=True)
# 初始化导航地图，核心是阶段拆分和技能索引
if not os.path.exists(self.nav_map_path):
default_nav_map = """
# AGENT 项目导航地图
## 项目阶段拆分
1. 阶段1：项目初始化 - 技能：环境搭建、仓库初始化、规范定义
2. 阶段2：架构设计 - 技能：分层架构设计、数据库设计、接口设计
3. 阶段3：核心功能开发 - 技能：业务代码开发、单元测试
4. 阶段4：测试与优化 - 技能：集成测试、性能优化、bug修复
5. 阶段5：上线交付 - 技能：部署配置、上线文档、验收交付
## 技能索引
所有技能文档在 ./docs/skills/ 目录下，仅当前阶段的技能会被注入
"""
with open(self.nav_map_path, "w", encoding="utf-8") as f:
f.write(default_nav_map)
# 加载技能库
self._load_skill_library()
def _load_skill_library(self):
"""加载技能库，按阶段分类"""
skill_dir = os.path.join(self.project_root, "docs", "skills")
os.makedirs(skill_dir, exist_ok=True)
# 遍历技能文件，按阶段分类
for phase in ["phase1", "phase2", "phase3", "phase4", "phase5"]:
phase_skill_path = os.path.join(skill_dir, phase)
os.makedirs(phase_skill_path, exist_ok=True)
self.skill_library[phase] = []
for file in os.listdir(phase_skill_path):
if file.endswith(".md"):
with open(os.path.join(phase_skill_path, file), "r", encoding="utf-8") as f:
self.skill_library[phase].append(f.read())
def get_current_phase_skills(self, current_phase: str) -> str:
"""Harness核心：仅获取当前阶段的技能，渐进式披露"""
return "\n\n".join(self.skill_library.get(current_phase, []))
def update_phase_progress(self, phase: str, progress: str, result: str):
"""持久化阶段进度到文件系统，跨会话不会丢失"""
self.phase_progress[phase] = progress
progress_path = os.path.join(self.project_root, "docs", "progress", f"{phase}_progress.md")
os.makedirs(os.path.dirname(progress_path), exist_ok=True)
with open(progress_path, "w", encoding="utf-8") as f:
f.write(f"# {phase} 进度记录\n\n进度：{progress}\n\n成果：{result}")
def run_phase(self, phase: str, phase_task: str) -> str:
"""执行指定阶段的任务，仅注入当前阶段的技能和规则"""
# 1. 仅注入导航地图和当前阶段的技能，避免上下文溢出
system_prompt = f"""
项目导航地图：{open(self.nav_map_path, "r", encoding="utf-8").read()}
当前阶段：{phase}
当前阶段专属技能和规则：{self.get_current_phase_skills(phase)}
历史阶段进度：{self.phase_progress}
你只需要完成当前阶段的任务，不要涉及后续阶段的内容
"""
# 2. 执行任务（实际调用大模型）
print(f"===== 执行{phase}任务 =====")
print(f"注入上下文长度：{len(system_prompt)} 字符")
result = f"{phase}任务执行完成，成果：{phase_task}"
# 3. 持久化进度
self.update_phase_progress(phase, "已完成", result)
return result
# 使用示例
if __name__ == "__main__":
harness = ProgressiveSkillHarness(project_root="./user_management_project")
# 分阶段执行，每个阶段仅注入对应的技能，上下文不会爆炸
print(harness.run_phase("phase1", "初始化SpringBoot项目，搭建仓库结构，定义编码规范"))
print(harness.run_phase("phase2", "设计用户管理系统的分层架构、数据库表结构、接口规范"))
【避坑指南】
- 导航地图必须清晰，阶段拆分要合理，每个阶段的目标必须可量化、可验收，不能模糊
- 技能必须和阶段强绑定，绝对不能提前注入后续阶段的内容，否则就失去了渐进式披露的意义
- 所有进度、决策、成果必须持久化到文件系统，绝对不能只存在会话历史里，否则重启就全没了
- 必须完成上一个阶段的验收，才能解锁下一个阶段，避免跳步导致的逻辑混乱
范式四：事件驱动流式范式 —— 高并发实时场景的首选
这是企业级高并发 Agent 服务的主流范式，专门解决实时交互、高并发、7*24 小时在线的场景需求。
【适用场景】
高并发实时交互场景、流式对话应用、实时数据处理、7*24 小时在线的 Agent 服务。比如：AI 客服系统、实时监控告警 Agent、流式对话机器人、高并发的 API 服务。
【核心设计思想】
事件触发，流式响应，无状态闭环。Harness 基于事件驱动架构设计，把用户输入、工具返回、系统回调、超时告警都定义为标准事件，Harness 通过事件总线监听事件，触发对应的处理逻辑，流式输出结果。同时每个会话的状态完全隔离，高并发下也能稳定运行，不会出现会话串扰、状态混乱的问题。
普通的循环式 Agent，在高并发场景下会出现阻塞、内存溢出、会话串扰的问题，而事件驱动范式，天生适配高并发、异步化的场景，是企业级生产服务的首选。
【避坑指南】
- 事件必须有标准格式，唯一 ID、类型、时间戳、会话 ID、payload 缺一不可，必须保证幂等性
- 会话状态必须完全隔离，每个会话的状态只能由自己的事件修改，绝对不能出现跨会话的状态共享
- 事件处理必须异步非阻塞，绝对不能在事件处理器里加阻塞逻辑，否则高并发下会直接崩
- 必须有超时、重试、死信队列机制，避免某个事件处理失败导致整个链路阻塞
范式五：反馈自进化范式 —— 长期运营系统的终极形态
这是 Harness Engineering 的高阶范式，专门解决「Agent 越用越难用，需要不停手动改规则」的问题，让你的 Agent 越用越好用。
【适用场景】
长期迭代的产品、持续优化的自动化系统、需要自主学习优化的 Agent、团队级长期使用的工具。比如：团队内部长期使用的研发效能 Agent、持续运营的 AI 产品、长期维护的自动化系统。
【核心设计思想】
反馈闭环，自动迭代，规则自进化。Harness 不仅执行任务，还会自动收集每一次的执行结果、人工反馈、错误信息、成功案例，自动分析优化规则、更新记忆、调整执行策略，把优化后的内容更新到 Harness 里，下一次执行直接生效，越用越好用，不用你每次手动改 prompt、改规则。
普通的 Agent，用的时间越长，需求变化越多，规则越乱，效果越差；而自进化范式的 Harness，用的时间越长，数据越多，优化得越好，效果越稳定。
【避坑指南】
- 必须有人工审核节点，核心规则的修改必须经过人工确认，绝对不能让 Agent 无限制修改核心规则
- 进化逻辑必须可控，只能优化规则、更新记忆、调整策略，绝对不能修改 Harness 的核心执行逻辑
- 反馈数据必须结构化，成功案例、失败原因、优化点必须清晰，不能用模糊的反馈做优化
- 必须有版本回滚机制，优化后的规则如果效果变差，必须能一键回滚到上一个稳定版本
核心选型指南：你的场景该选哪个范式？
很多人看完会问，这么多范式，我该选哪个？给大家做了一个清晰的选型表，一眼就能找到适合自己的范式：
表格
| 范式 | 适用人群 | 核心场景 | 落地难度 | 稳定性 | 扩展性 |
|---|---|---|---|---|---|
| 单 Agent 全闭环范式 | 个人开发者、新手 | 简单工具、小任务、提效脚本 | ★☆☆☆☆ | ★★★★★ | ★☆☆☆☆ |
| 多 Agent 协同范式 | 团队、中大型项目 | 复杂项目、全栈开发、跨领域任务 | ★★★☆☆ | ★★★★☆ | ★★★★☆ |
| 渐进式技能解锁范式 | 长周期项目开发者 | 大项目、持续迭代产品、防上下文腐烂 | ★★★☆☆ | ★★★★☆ | ★★★☆☆ |
| 事件驱动流式范式 | 企业级服务开发者 | 高并发实时服务、7*24 在线 Agent | ★★★★☆ | ★★★☆☆ | ★★★★★ |
| 反馈自进化范式 | 长期运营产品团队 | 持续优化的系统、长期使用的工具 | ★★★★☆ | ★★★☆☆ | ★★★★★ |
核心选型铁则：
- 场景优先，不炫技：80% 的场景，单 Agent 闭环范式就足够用了，别为了装 X 搞复杂的多 Agent，反而不稳定
- 先闭环，再扩展：先把最小闭环跑通，能稳定落地，再扩展更复杂的范式，别一上来就搞大而全的系统
- 范式可组合，不固定：大项目里可以组合多个范式，比如总控用多 Agent 协同，每个子 Agent 用单 Agent 闭环，长周期任务用渐进式技能解锁，灵活适配自己的场景
结尾总结
最后，跟大家说句掏心窝子的话：AI 时代，程序员的核心竞争力，早就不是手写代码的速度了，而是设计系统、定义规则、驾驭 AI 的能力。Harness Engineering 的本质，就是把你的工程能力、业务理解、团队规则，编码成一套 AI 能稳定执行的系统。
你不用再卷模型、卷 prompt，选对了适合自己场景的 Harness 范式，你的 Agent 就能从 Demo 走向生产，真正实现 10 倍、100 倍的提效。
