第18章 Agent-Harness 协作模式 —— 推理与执行的完美配合

2026-05-23 约 2400 字预计阅读 11 分钟

上一篇我们用类比深化理解。本章我们看 Agent 与 Harness 如何协作——推理与执行的完美配合。

Agent-Harness 协作是什么

一句话定义：Agent 推理决策，Harness 执行落地——两者配合完成任务。

Agent-Harness Collaboration = 推理 + 执行定位：理解 Agent 与 Harness 的协作关系

图表代码

graph LR
    Agent[Agent
推理决策] -->|tool_use| Harness[Harness
执行落地]
    Harness -->|结果反馈| Agent
    Agent -->|调整策略| Harness
    
    Agent[思考者]
    Harness[执行者]graph LR
    Agent[Agent
推理决策] -->|tool_use| Harness[Harness
执行落地]
    Harness -->|结果反馈| Agent
    Agent -->|调整策略| Harness
    
    Agent[思考者]
    Harness[执行者]graph LR
    Agent[Agent
推理决策] -->|tool_use| Harness[Harness
执行落地]
    Harness -->|结果反馈| Agent
    Agent -->|调整策略| Harness
    
    Agent[思考者]
    Harness[执行者]

graph LR
    Agent[Agent<br/>推理决策] -->|tool_use| Harness[Harness<br/>执行落地]
    Harness -->|结果反馈| Agent
    Agent -->|调整策略| Harness
    
    Agent[思考者]
    Harness[执行者]

协作本质：

Agent 是思考者：推理、决策、规划
Harness 是执行者：调用工具、管理状态、执行操作
双向反馈：结果反馈、策略调整、状态同步

协作模式的核心流程

Agent → Harness → Agent 循环

图表代码

sequenceDiagram
    participant User as 用户
    participant Agent as Agent
推理层
    participant Harness as Harness
执行层
    participant Tool as 工具系统
    
    User->>Agent: 发送任务 prompt
    
    Agent->>Agent: 推理分析任务
    
    Agent->>Harness: 发送 tool_use 请求
    
    Harness->>Harness: 权限检查
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回工具输出
    
    Harness-->>Agent: 返回执行结果
    
    Agent->>Agent: 分析结果，调整策略
    
    Agent->>Harness: 发送下一个 tool_use
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回输出
    Harness-->>Agent: 返回结果
    
    Agent-->>User: 返回最终结果sequenceDiagram
    participant User as 用户
    participant Agent as Agent
推理层
    participant Harness as Harness
执行层
    participant Tool as 工具系统
    
    User->>Agent: 发送任务 prompt
    
    Agent->>Agent: 推理分析任务
    
    Agent->>Harness: 发送 tool_use 请求
    
    Harness->>Harness: 权限检查
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回工具输出
    
    Harness-->>Agent: 返回执行结果
    
    Agent->>Agent: 分析结果，调整策略
    
    Agent->>Harness: 发送下一个 tool_use
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回输出
    Harness-->>Agent: 返回结果
    
    Agent-->>User: 返回最终结果sequenceDiagram
    participant User as 用户
    participant Agent as Agent
推理层
    participant Harness as Harness
执行层
    participant Tool as 工具系统
    
    User->>Agent: 发送任务 prompt
    
    Agent->>Agent: 推理分析任务
    
    Agent->>Harness: 发送 tool_use 请求
    
    Harness->>Harness: 权限检查
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回工具输出
    
    Harness-->>Agent: 返回执行结果
    
    Agent->>Agent: 分析结果，调整策略
    
    Agent->>Harness: 发送下一个 tool_use
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回输出
    Harness-->>Agent: 返回结果
    
    Agent-->>User: 返回最终结果

sequenceDiagram
    participant User as 用户
    participant Agent as Agent<br/>推理层
    participant Harness as Harness<br/>执行层
    participant Tool as 工具系统
    
    User->>Agent: 发送任务 prompt
    
    Agent->>Agent: 推理分析任务
    
    Agent->>Harness: 发送 tool_use 请求
    
    Harness->>Harness: 权限检查
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回工具输出
    
    Harness-->>Agent: 返回执行结果
    
    Agent->>Agent: 分析结果，调整策略
    
    Agent->>Harness: 发送下一个 tool_use
    
    Harness->>Tool: 执行工具
    
    Tool-->>Harness: 返回输出
    Harness-->>Agent: 返回结果
    
    Agent-->>User: 返回最终结果

循环步骤详解

步骤	Agent 动作	Harness 动作	说明
1. 接收任务	接收用户 prompt	注入 System Prompt + CLAUDE.md	初始化阶段
2. 推理分析	分析任务，规划步骤	等待 Agent 决策	Agent 推理
3. 发送 tool_use	决定调用工具，发送请求	接收 tool_use	Agent 决策
4. 权限检查	等待执行结果	检查权限（deny/ask/allow）	Harness 管理
5. 执行工具	等待工具输出	调用工具，执行操作	Harness 执行
6. 返回结果	接收工具输出	返回执行结果	Harness 反馈
7. 分析调整	分析结果，调整策略	等待下一个 tool_use	Agent 调整
8. 循环继续	继续推理或结束	继续执行或结束	循环阶段

Agent 的角色：思考者

Agent 的核心职责

图表代码

graph TB
    subgraph AgentRole["Agent 角色"]
        A1[任务理解
解析用户意图]
        A2[规划分解
拆解任务步骤]
        A3[工具选择
决定调用哪个工具]
        A4[参数设计
设计工具参数]
        A5[结果分析
分析执行结果]
        A6[策略调整
调整下一步动作]
        A7[错误处理
处理执行错误]
        A8[状态判断
判断任务完成]
    end
    
    A1 --> A2 --> A3 --> A4 --> A5 --> A6 --> A7 --> A8graph TB
    subgraph AgentRole["Agent 角色"]
        A1[任务理解
解析用户意图]
        A2[规划分解
拆解任务步骤]
        A3[工具选择
决定调用哪个工具]
        A4[参数设计
设计工具参数]
        A5[结果分析
分析执行结果]
        A6[策略调整
调整下一步动作]
        A7[错误处理
处理执行错误]
        A8[状态判断
判断任务完成]
    end
    
    A1 --> A2 --> A3 --> A4 --> A5 --> A6 --> A7 --> A8graph TB
    subgraph AgentRole["Agent 角色"]
        A1[任务理解
解析用户意图]
        A2[规划分解
拆解任务步骤]
        A3[工具选择
决定调用哪个工具]
        A4[参数设计
设计工具参数]
        A5[结果分析
分析执行结果]
        A6[策略调整
调整下一步动作]
        A7[错误处理
处理执行错误]
        A8[状态判断
判断任务完成]
    end
    
    A1 --> A2 --> A3 --> A4 --> A5 --> A6 --> A7 --> A8

graph TB
    subgraph AgentRole["Agent 角色"]
        A1[任务理解<br/>解析用户意图]
        A2[规划分解<br/>拆解任务步骤]
        A3[工具选择<br/>决定调用哪个工具]
        A4[参数设计<br/>设计工具参数]
        A5[结果分析<br/>分析执行结果]
        A6[策略调整<br/>调整下一步动作]
        A7[错误处理<br/>处理执行错误]
        A8[状态判断<br/>判断任务完成]
    end
    
    A1 --> A2 --> A3 --> A4 --> A5 --> A6 --> A7 --> A8

职责详解：

职责	说明	示例
任务理解	解析用户意图，理解任务目标	“重构这个模块” → 理解重构目标
规划分解	拆解任务为多个步骤	重构 → 1.读取代码 2.分析结构 3.修改文件
工具选择	决定调用哪个工具	需要读取文件 → 选择 Read 工具
参数设计	设计工具调用参数	Read → 参数：file_path="/src/app.ts"
结果分析	分析工具执行结果	Read 返回 → 分析代码结构
策略调整	调整下一步动作	发现需要修改 → 调用 Edit 工具
错误处理	处理执行错误	Edit 失败 → 重试或换工具
状态判断	判断任务是否完成	修改完成 → 返回 end_turn

Agent 的决策过程

图表代码

graph LR
    Observe[observe
接收 messages] --> Think[think
Model 推理]
    Think --> Decide{决策}
    Decide -->|需要工具| PlanTool[规划 tool_use]
    Decide -->|任务完成| EndTurn[end_turn]
    
    PlanTool --> SelectTool[选择工具]
    SelectTool --> DesignParams[设计参数]
    DesignParams --> SendTool[发送请求]
    
    SendTool --> Harness[发送给 Harness]graph LR
    Observe[observe
接收 messages] --> Think[think
Model 推理]
    Think --> Decide{决策}
    Decide -->|需要工具| PlanTool[规划 tool_use]
    Decide -->|任务完成| EndTurn[end_turn]
    
    PlanTool --> SelectTool[选择工具]
    SelectTool --> DesignParams[设计参数]
    DesignParams --> SendTool[发送请求]
    
    SendTool --> Harness[发送给 Harness]graph LR
    Observe[observe
接收 messages] --> Think[think
Model 推理]
    Think --> Decide{决策}
    Decide -->|需要工具| PlanTool[规划 tool_use]
    Decide -->|任务完成| EndTurn[end_turn]
    
    PlanTool --> SelectTool[选择工具]
    SelectTool --> DesignParams[设计参数]
    DesignParams --> SendTool[发送请求]
    
    SendTool --> Harness[发送给 Harness]

graph LR
    Observe[observe<br/>接收 messages] --> Think[think<br/>Model 推理]
    Think --> Decide{决策}
    Decide -->|需要工具| PlanTool[规划 tool_use]
    Decide -->|任务完成| EndTurn[end_turn]
    
    PlanTool --> SelectTool[选择工具]
    SelectTool --> DesignParams[设计参数]
    DesignParams --> SendTool[发送请求]
    
    SendTool --> Harness[发送给 Harness]

决策流程：

observe：接收 messages 数组（包含历史 + 工具输出）
think：Model 推理下一步动作
decide：决定调用工具或结束任务
plan tool_use：如果需要工具，规划调用
select tool：选择合适的工具
design params：设计工具参数
send request：发送 tool_use 请求

Agent 的推理能力

Model 推理能力：

能力	说明	示例
语言理解	理解自然语言任务	“重构这个模块”
代码理解	理解代码结构和逻辑	分析 TypeScript 代码
工具理解	理解工具 Schema 和功能	知道 Read 工具的功能
推理规划	推理任务步骤和策略	规划重构步骤
错误诊断	诊断执行错误原因	分析 Edit 失败原因
策略调整	根据结果调整策略	调整工具选择

Harness 的角色：执行者

Harness 的核心职责

图表代码

graph TB
    subgraph HarnessRole["Harness 角色"]
        H1[接收请求
接收 tool_use]
        H2[权限检查
检查操作权限]
        H3[工具调用
调用具体工具]
        H4[执行操作
执行实际操作]
        H5[状态管理
管理 messages/tasks]
        H6[结果处理
处理工具输出]
        H7[错误处理
处理执行错误]
        H8[资源管理
管理上下文/MCP]
    end
    
    H1 --> H2 --> H3 --> H4 --> H5 --> H6 --> H7 --> H8graph TB
    subgraph HarnessRole["Harness 角色"]
        H1[接收请求
接收 tool_use]
        H2[权限检查
检查操作权限]
        H3[工具调用
调用具体工具]
        H4[执行操作
执行实际操作]
        H5[状态管理
管理 messages/tasks]
        H6[结果处理
处理工具输出]
        H7[错误处理
处理执行错误]
        H8[资源管理
管理上下文/MCP]
    end
    
    H1 --> H2 --> H3 --> H4 --> H5 --> H6 --> H7 --> H8graph TB
    subgraph HarnessRole["Harness 角色"]
        H1[接收请求
接收 tool_use]
        H2[权限检查
检查操作权限]
        H3[工具调用
调用具体工具]
        H4[执行操作
执行实际操作]
        H5[状态管理
管理 messages/tasks]
        H6[结果处理
处理工具输出]
        H7[错误处理
处理执行错误]
        H8[资源管理
管理上下文/MCP]
    end
    
    H1 --> H2 --> H3 --> H4 --> H5 --> H6 --> H7 --> H8

graph TB
    subgraph HarnessRole["Harness 角色"]
        H1[接收请求<br/>接收 tool_use]
        H2[权限检查<br/>检查操作权限]
        H3[工具调用<br/>调用具体工具]
        H4[执行操作<br/>执行实际操作]
        H5[状态管理<br/>管理 messages/tasks]
        H6[结果处理<br/>处理工具输出]
        H7[错误处理<br/>处理执行错误]
        H8[资源管理<br/>管理上下文/MCP]
    end
    
    H1 --> H2 --> H3 --> H4 --> H5 --> H6 --> H7 --> H8

职责详解：

职责	说明	示例
接收请求	接收 Agent 的 tool_use 请求	接收 Read 工具调用
权限检查	检查操作权限（deny/ask/allow）	检查 Read 是否允许
工具调用	调用具体工具执行	调用 Read 工具读取文件
执行操作	执行实际操作（文件读写、命令执行）	读取 /src/app.ts 文件
状态管理	管理 messages 数组和任务系统	追加工具输出到 messages
结果处理	处理工具输出，格式化返回	返回文件内容
错误处理	处理执行错误，返回错误信息	返回文件不存在错误
资源管理	管理上下文窗口、MCP 连接	上下文压缩、MCP 连接管理

Harness 的执行流程

图表代码

graph LR
    Receive[接收 tool_use] --> PermCheck{权限检查}
    PermCheck -->|deny| Deny[返回错误
禁止执行]
    PermCheck -->|ask| Ask[请求审批
等待用户]
    PermCheck -->|allow| Exec[执行工具]
    
    Ask -->|批准| Exec
    Ask -->|拒绝| Deny
    
    Exec --> Success{执行成功?}
    Success -->|成功| Return[返回结果]
    Success -->|失败| Error[返回错误]
    
    Return --> AppendMsg[追加 messages]
    Error --> AppendMsggraph LR
    Receive[接收 tool_use] --> PermCheck{权限检查}
    PermCheck -->|deny| Deny[返回错误
禁止执行]
    PermCheck -->|ask| Ask[请求审批
等待用户]
    PermCheck -->|allow| Exec[执行工具]
    
    Ask -->|批准| Exec
    Ask -->|拒绝| Deny
    
    Exec --> Success{执行成功?}
    Success -->|成功| Return[返回结果]
    Success -->|失败| Error[返回错误]
    
    Return --> AppendMsg[追加 messages]
    Error --> AppendMsggraph LR
    Receive[接收 tool_use] --> PermCheck{权限检查}
    PermCheck -->|deny| Deny[返回错误
禁止执行]
    PermCheck -->|ask| Ask[请求审批
等待用户]
    PermCheck -->|allow| Exec[执行工具]
    
    Ask -->|批准| Exec
    Ask -->|拒绝| Deny
    
    Exec --> Success{执行成功?}
    Success -->|成功| Return[返回结果]
    Success -->|失败| Error[返回错误]
    
    Return --> AppendMsg[追加 messages]
    Error --> AppendMsg

graph LR
    Receive[接收 tool_use] --> PermCheck{权限检查}
    PermCheck -->|deny| Deny[返回错误<br/>禁止执行]
    PermCheck -->|ask| Ask[请求审批<br/>等待用户]
    PermCheck -->|allow| Exec[执行工具]
    
    Ask -->|批准| Exec
    Ask -->|拒绝| Deny
    
    Exec --> Success{执行成功?}
    Success -->|成功| Return[返回结果]
    Success -->|失败| Error[返回错误]
    
    Return --> AppendMsg[追加 messages]
    Error --> AppendMsg

执行流程：

接收 tool_use：接收 Agent 的工具调用请求
权限检查：检查 deny/ask/allow 规则
审批处理：如果是 ask，请求用户审批
执行工具：调用具体工具执行
结果处理：返回执行结果或错误
追加 messages：将结果追加到 messages 数组

Harness 的管理能力

Harness 管理能力：

能力	说明	示例
工具调度	调度工具执行	调用 Read、Write、Edit 工具
权限控制	控制操作权限	deny 删除操作，ask 写入操作
状态维护	维护 messages 数组	追加工具输出，压缩上下文
资源管理	管理上下文窗口	四层压缩策略
外部连接	连接外部系统	MCP 服务器连接
错误恢复	处理执行错误	工具重试，错误返回

双向反馈机制

结果反馈：Harness → Agent

图表代码

graph LR
    ToolExec[工具执行] --> ToolResult[工具输出]
    ToolResult --> HarnessProcess[Harness 处理]
    HarnessProcess --> AppendMsg[追加 messages]
    AppendMsg --> AgentReceive[Agent 接收]
    
    AgentReceive --> AgentAnalyze[Agent 分析]graph LR
    ToolExec[工具执行] --> ToolResult[工具输出]
    ToolResult --> HarnessProcess[Harness 处理]
    HarnessProcess --> AppendMsg[追加 messages]
    AppendMsg --> AgentReceive[Agent 接收]
    
    AgentReceive --> AgentAnalyze[Agent 分析]graph LR
    ToolExec[工具执行] --> ToolResult[工具输出]
    ToolResult --> HarnessProcess[Harness 处理]
    HarnessProcess --> AppendMsg[追加 messages]
    AppendMsg --> AgentReceive[Agent 接收]
    
    AgentReceive --> AgentAnalyze[Agent 分析]

graph LR
    ToolExec[工具执行] --> ToolResult[工具输出]
    ToolResult --> HarnessProcess[Harness 处理]
    HarnessProcess --> AppendMsg[追加 messages]
    AppendMsg --> AgentReceive[Agent 接收]
    
    AgentReceive --> AgentAnalyze[Agent 分析]

反馈内容：

反馈类型	说明	示例
成功结果	工具执行成功的输出	Read 返回文件内容
错误信息	工具执行失败的错误	文件不存在错误
权限拒绝	用户拒绝操作的信息	用户拒绝 git push
状态变化	Harness 状态变化	任务系统更新

策略调整：Agent → Harness

图表代码

graph LR
    AgentAnalyze[Agent 分析结果] --> StrategyDecide{策略决策}
    StrategyDecide -->|继续工具| NewToolUse[新的 tool_use]
    StrategyDecide -->|调整工具| AdjustTool[调整工具/参数]
    StrategyDecide -->|结束任务| EndTurn[end_turn]
    
    NewToolUse --> HarnessReceive[Harness 接收]
    AdjustTool --> HarnessReceivegraph LR
    AgentAnalyze[Agent 分析结果] --> StrategyDecide{策略决策}
    StrategyDecide -->|继续工具| NewToolUse[新的 tool_use]
    StrategyDecide -->|调整工具| AdjustTool[调整工具/参数]
    StrategyDecide -->|结束任务| EndTurn[end_turn]
    
    NewToolUse --> HarnessReceive[Harness 接收]
    AdjustTool --> HarnessReceivegraph LR
    AgentAnalyze[Agent 分析结果] --> StrategyDecide{策略决策}
    StrategyDecide -->|继续工具| NewToolUse[新的 tool_use]
    StrategyDecide -->|调整工具| AdjustTool[调整工具/参数]
    StrategyDecide -->|结束任务| EndTurn[end_turn]
    
    NewToolUse --> HarnessReceive[Harness 接收]
    AdjustTool --> HarnessReceive

graph LR
    AgentAnalyze[Agent 分析结果] --> StrategyDecide{策略决策}
    StrategyDecide -->|继续工具| NewToolUse[新的 tool_use]
    StrategyDecide -->|调整工具| AdjustTool[调整工具/参数]
    StrategyDecide -->|结束任务| EndTurn[end_turn]
    
    NewToolUse --> HarnessReceive[Harness 接收]
    AdjustTool --> HarnessReceive

调整策略：

策略	说明	示例
继续工具	继续调用下一个工具	Read 完成 → 调用 Edit
调整工具	调整工具选择或参数	Edit 失败 → 重试或换工具
结束任务	判断任务完成，结束对话	修改完成 → end_turn
错误恢复	根据错误调整策略	文件不存在 → 创建文件

协作模式的关键特性

1. 分工明确

图表代码

graph TB
    subgraph Division["分工明确"]
        Agent[Agent
推理决策
思考者]
        Harness[Harness
执行落地
执行者]
    end
    
    Agent -->|决策| Harness -->|执行| Result
    
    Agent[只推理，不执行]
    Harness[只执行，不推理]graph TB
    subgraph Division["分工明确"]
        Agent[Agent
推理决策
思考者]
        Harness[Harness
执行落地
执行者]
    end
    
    Agent -->|决策| Harness -->|执行| Result
    
    Agent[只推理，不执行]
    Harness[只执行，不推理]graph TB
    subgraph Division["分工明确"]
        Agent[Agent
推理决策
思考者]
        Harness[Harness
执行落地
执行者]
    end
    
    Agent -->|决策| Harness -->|执行| Result
    
    Agent[只推理，不执行]
    Harness[只执行，不推理]

graph TB
    subgraph Division["分工明确"]
        Agent[Agent<br/>推理决策<br/>思考者]
        Harness[Harness<br/>执行落地<br/>执行者]
    end
    
    Agent -->|决策| Harness -->|执行| Result
    
    Agent[只推理，不执行]
    Harness[只执行，不推理]

分工原则：

原则	说明	理由
Agent 不执行	Agent 只推理，不直接执行	Agent 无执行能力
Harness 不推理	Harness 只执行，不推理决策	Harness 无推理能力
单向依赖	Harness 依赖 Agent 的决策	Agent 决策驱动 Harness
双向反馈	Agent 和 Harness 双向反馈	反馈驱动调整

2. 循环驱动

图表代码

graph LR
    AgentThink[Agent 推理] --> HarnessExec[Harness 执行]
    HarnessExec --> ResultFeedback[结果反馈]
    ResultFeedback --> AgentThink
    
    AgentThink[驱动循环]
    HarnessExec[响应执行]
    ResultFeedback[反馈驱动]graph LR
    AgentThink[Agent 推理] --> HarnessExec[Harness 执行]
    HarnessExec --> ResultFeedback[结果反馈]
    ResultFeedback --> AgentThink
    
    AgentThink[驱动循环]
    HarnessExec[响应执行]
    ResultFeedback[反馈驱动]graph LR
    AgentThink[Agent 推理] --> HarnessExec[Harness 执行]
    HarnessExec --> ResultFeedback[结果反馈]
    ResultFeedback --> AgentThink
    
    AgentThink[驱动循环]
    HarnessExec[响应执行]
    ResultFeedback[反馈驱动]

graph LR
    AgentThink[Agent 推理] --> HarnessExec[Harness 执行]
    HarnessExec --> ResultFeedback[结果反馈]
    ResultFeedback --> AgentThink
    
    AgentThink[驱动循环]
    HarnessExec[响应执行]
    ResultFeedback[反馈驱动]

循环特性：

特性	说明	价值
推理驱动	Agent 推理驱动循环	Agent 是主动方
执行响应	Harness 响应执行	Harness 是被动方
反馈闭环	结果反馈形成闭环	闭环驱动调整
持续迭代	循环持续直到完成	迭代完成任务

3. 状态同步

图表代码

graph LR
    AgentState[Agent 状态
messages/tasks] <-->|同步| HarnessState[Harness 状态
messages/tasks]
    
    AgentState -->|更新| HarnessState
    HarnessState -->|反馈| AgentStategraph LR
    AgentState[Agent 状态
messages/tasks] <-->|同步| HarnessState[Harness 状态
messages/tasks]
    
    AgentState -->|更新| HarnessState
    HarnessState -->|反馈| AgentStategraph LR
    AgentState[Agent 状态
messages/tasks] <-->|同步| HarnessState[Harness 状态
messages/tasks]
    
    AgentState -->|更新| HarnessState
    HarnessState -->|反馈| AgentState

graph LR
    AgentState[Agent 状态<br/>messages/tasks] <-->|同步| HarnessState[Harness 状态<br/>messages/tasks]
    
    AgentState -->|更新| HarnessState
    HarnessState -->|反馈| AgentState

同步内容：

状态	Agent 管理	Harness 管理
messages	Agent 接收 messages	Harness 追加 messages
tasks	Agent 使用 tasks	Harness 持久化 tasks
权限状态	Agent 知道权限结果	Harness 检查权限
执行状态	Agent 知道执行结果	Harness 执行工具

4. 错误恢复

图表代码

graph LR
    Error[错误发生] --> AgentDiagnose[Agent 诊断]
    AgentDiagnose --> StrategyAdjust[策略调整]
    StrategyAdjust --> HarnessRetry[Harness 重试]
    HarnessRetry --> Success{成功?}
    
    Success -->|成功| Continue[继续循环]
    Success -->|失败| Abort[终止或换策略]graph LR
    Error[错误发生] --> AgentDiagnose[Agent 诊断]
    AgentDiagnose --> StrategyAdjust[策略调整]
    StrategyAdjust --> HarnessRetry[Harness 重试]
    HarnessRetry --> Success{成功?}
    
    Success -->|成功| Continue[继续循环]
    Success -->|失败| Abort[终止或换策略]graph LR
    Error[错误发生] --> AgentDiagnose[Agent 诊断]
    AgentDiagnose --> StrategyAdjust[策略调整]
    StrategyAdjust --> HarnessRetry[Harness 重试]
    HarnessRetry --> Success{成功?}
    
    Success -->|成功| Continue[继续循环]
    Success -->|失败| Abort[终止或换策略]

graph LR
    Error[错误发生] --> AgentDiagnose[Agent 诊断]
    AgentDiagnose --> StrategyAdjust[策略调整]
    StrategyAdjust --> HarnessRetry[Harness 重试]
    HarnessRetry --> Success{成功?}
    
    Success -->|成功| Continue[继续循环]
    Success -->|失败| Abort[终止或换策略]

恢复机制：

错误类型	Agent 处理	Harness 处理
工具执行错误	Agent 调整策略	Harness 重试执行
权限拒绝	Agent 调整策略	Harness 返回拒绝信息
上下文溢出	Agent 继续（自动压缩）	Harness 压缩上下文
Model API 错误	Agent 自动重试	Harness 等待重试

协作模式的典型场景

场景 1：文件重构

图表代码

sequenceDiagram
    participant User as 用户
    participant Agent as Agent
    participant Harness as Harness
    
    User->>Agent: 重构 app.ts
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Agent: 分析结构
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 权限检查（ask）
    Harness->>User: 请求审批
    User-->>Harness: 批准
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证修改
    Agent-->>User: 返回完成sequenceDiagram
    participant User as 用户
    participant Agent as Agent
    participant Harness as Harness
    
    User->>Agent: 重构 app.ts
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Agent: 分析结构
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 权限检查（ask）
    Harness->>User: 请求审批
    User-->>Harness: 批准
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证修改
    Agent-->>User: 返回完成sequenceDiagram
    participant User as 用户
    participant Agent as Agent
    participant Harness as Harness
    
    User->>Agent: 重构 app.ts
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Agent: 分析结构
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 权限检查（ask）
    Harness->>User: 请求审批
    User-->>Harness: 批准
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证修改
    Agent-->>User: 返回完成

sequenceDiagram
    participant User as 用户
    participant Agent as Agent
    participant Harness as Harness
    
    User->>Agent: 重构 app.ts
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Agent: 分析结构
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 权限检查（ask）
    Harness->>User: 请求审批
    User-->>Harness: 批准
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证修改
    Agent-->>User: 返回完成

协作步骤：

步骤	Agent	Harness
1	接收任务	注入 CLAUDE.md
2	决定读取文件	执行 Read
3	分析文件结构	返回内容
4	决定修改文件	执行 Edit（需审批）
5	等待审批	请求用户审批
6	接收结果	返回修改结果
7	验证修改	执行 Read
8	判断完成	返回新内容

场景 2：错误恢复

图表代码

sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 错误：old_string 不唯一
    Agent->>Agent: 分析错误
    Agent->>Harness: Edit app.ts（调整参数）
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 成功修改
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证成功sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 错误：old_string 不唯一
    Agent->>Agent: 分析错误
    Agent->>Harness: Edit app.ts（调整参数）
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 成功修改
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证成功sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 错误：old_string 不唯一
    Agent->>Agent: 分析错误
    Agent->>Harness: Edit app.ts（调整参数）
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 成功修改
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证成功

sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Edit app.ts
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 错误：old_string 不唯一
    Agent->>Agent: 分析错误
    Agent->>Harness: Edit app.ts（调整参数）
    Harness->>Harness: 执行 Edit
    Harness-->>Agent: 成功修改
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回新内容
    Agent->>Agent: 验证成功

错误恢复步骤：

步骤	Agent	Harness
1	调用 Edit	执行 Edit
2	接收错误	返回错误信息
3	分析错误原因	等待调整
4	调整参数	执行新的 Edit
5	接收成功结果	返回成功
6	验证修改	执行 Read
7	判断成功	返回新内容

场景 3：多工具协作

图表代码

sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Glob *.ts
    Harness-->>Agent: 返回文件列表
    Agent->>Harness: Grep "function"
    Harness-->>Agent: 返回搜索结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Harness: Edit app.ts
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Bash npm test
    Harness-->>Agent: 返回测试结果
    Agent->>Agent: 判断完成sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Glob *.ts
    Harness-->>Agent: 返回文件列表
    Agent->>Harness: Grep "function"
    Harness-->>Agent: 返回搜索结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Harness: Edit app.ts
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Bash npm test
    Harness-->>Agent: 返回测试结果
    Agent->>Agent: 判断完成sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Glob *.ts
    Harness-->>Agent: 返回文件列表
    Agent->>Harness: Grep "function"
    Harness-->>Agent: 返回搜索结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Harness: Edit app.ts
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Bash npm test
    Harness-->>Agent: 返回测试结果
    Agent->>Agent: 判断完成

sequenceDiagram
    participant Agent as Agent
    participant Harness as Harness
    
    Agent->>Harness: Glob *.ts
    Harness-->>Agent: 返回文件列表
    Agent->>Harness: Grep "function"
    Harness-->>Agent: 返回搜索结果
    Agent->>Harness: Read app.ts
    Harness-->>Agent: 返回文件内容
    Agent->>Harness: Edit app.ts
    Harness-->>Agent: 返回修改结果
    Agent->>Harness: Bash npm test
    Harness-->>Agent: 返回测试结果
    Agent->>Agent: 判断完成

多工具协作步骤：

步骤	Agent	Harness
1	搜索文件（Glob）	执行 Glob
2	搜索内容（Grep）	执行 Grep
3	读取文件（Read）	执行 Read
4	修改文件（Edit）	执行 Edit
5	运行测试（Bash）	执行 Bash
6	判断完成	返回结果

协作模式的设计原则

原则总结

图表代码

graph TB
    subgraph Principles["协作原则"]
        P1[分工明确
Agent推理/Harness执行]
        P2[循环驱动
推理→执行→反馈]
        P3[状态同步
messages/tasks同步]
        P4[错误恢复
自动调整重试]
        P5[双向反馈
结果反馈策略调整]
    endgraph TB
    subgraph Principles["协作原则"]
        P1[分工明确
Agent推理/Harness执行]
        P2[循环驱动
推理→执行→反馈]
        P3[状态同步
messages/tasks同步]
        P4[错误恢复
自动调整重试]
        P5[双向反馈
结果反馈策略调整]
    endgraph TB
    subgraph Principles["协作原则"]
        P1[分工明确
Agent推理/Harness执行]
        P2[循环驱动
推理→执行→反馈]
        P3[状态同步
messages/tasks同步]
        P4[错误恢复
自动调整重试]
        P5[双向反馈
结果反馈策略调整]
    end

graph TB
    subgraph Principles["协作原则"]
        P1[分工明确<br/>Agent推理/Harness执行]
        P2[循环驱动<br/>推理→执行→反馈]
        P3[状态同步<br/>messages/tasks同步]
        P4[错误恢复<br/>自动调整重试]
        P5[双向反馈<br/>结果反馈策略调整]
    end

原则	说明	实现方式
分工明确	Agent 推理，Harness 执行	Agent 不执行，Harness 不推理
循环驱动	推理驱动执行，反馈驱动调整	Agent Loop 持续循环
状态同步	messages/tasks 双向同步	共享 messages 数组
错误恢复	自动调整策略重试	Agent 调整，Harness 重试
双向反馈	结果反馈，策略调整	Harness 返回，Agent 分析

本章小结

协作定义：Agent 推理决策，Harness 执行落地
Agent 角色：思考者——任务理解、规划分解、工具选择、参数设计、结果分析、策略调整、错误处理、状态判断
Harness 角色：执行者——接收请求、权限检查、工具调用、执行操作、状态管理、结果处理、错误处理、资源管理
双向反馈：结果反馈（Harness→Agent）、策略调整（Agent→Harness）
关键特性：分工明确、循环驱动、状态同步、错误恢复
典型场景：文件重构、错误恢复、多工具协作
设计原则：分工明确、循环驱动、状态同步、错误恢复、双向反馈

预告：下一篇我们进入第六部分——多智能体架构模式。

☕ 如果这篇文章对你有帮助

欢迎请我喝杯咖啡，你的支持是我持续创作的动力 ❤️

捐赠支持 GitHub Sponsors

第18章 Agent-Harness 协作模式 —— 推理与执行的完美配合

Agent-Harness 协作是什么

协作模式的核心流程

Agent → Harness → Agent 循环

循环步骤详解

Agent 的角色：思考者

Agent 的核心职责

Agent 的决策过程

Agent 的推理能力

Harness 的角色：执行者

Harness 的核心职责

Harness 的执行流程

Harness 的管理能力

双向反馈机制

结果反馈：Harness → Agent

策略调整：Agent → Harness

协作模式的关键特性

1. 分工明确

2. 循环驱动

3. 状态同步

4. 错误恢复

协作模式的典型场景

场景 1：文件重构

场景 2：错误恢复

场景 3：多工具协作

协作模式的设计原则

原则总结

本章小结

相关内容

目录