v0.12.3: 全面审计修复 + 稳定性加固 + 文档更新
P0 安全/稳定性修复 (6项):
- sqlite persist 改用临时文件+rename，I/O错误日志
- IPC fs 处理器加入 checkPathAllowed 路径验证
- handleCompress 命令注入修复 + 跨平台 (powershell/tar/zip/unzip)
- browser 全页截图简化，使用 capturePage full rect
- workspace 竞态条件修复
- editFile 5MB 大小限制
P1 安全/稳定性修复 (7项):
- 大小写不敏感搜索: query 同步转换小写
- web_fetch 无 content-length 时流式读取+10MB限制防OOM
- Windows SIGTERM 改用 taskkill /PID /T /F 强制终止
- startsWith 路径检查 Windows 大小写不敏感
- 安全黑名单扩展: 33个目录路径 + 30条危险命令 (Linux+Windows)
- plan_track stepIndex 改用 typeof === 'number' 精确检查
- MCP 前缀改用双下划线分隔 mcp_{server}__{tool} 防歧义
P2 代码质量修复 (8项):
- 修复 EXECUTING→THINKING 死循环Bug (转换表缺失)
- COMPRESSING 硬上限绕过时同步 _loopState 全局状态
- Abort 路径补齐 onDone 回调, 防止UI状态残留
- 幻觉检测从4条扩展到16条规则, 覆盖全部工具类别
- 移除 getTokenEfficiency 死代码
- 跨平台路径清理 (replace(/[\/]+$/, ''))
- 动态 import 加 try/catch, 失败自动批准不阻断
- #modelSelect 加 null 守卫, 防止运行时崩溃
文档 & UI 更新:
- README.md: 版本号/特性表/架构图/安全机制/工具清单全面刷新
- 帮助面板: 新增 Plan Mode、抗幻觉&稳定性章节, Agent Loop补8状态机
- 工具面板: plan_track卡片 + plan-mode徽章样式, 标题更新为42+1
- 工作空间面板宽度: 480px → 400px
- 源码注释移除所有版本标签, 仅保留4处必要位置
- 版本号 0.12.2 → 0.12.3
This commit is contained in:
紫影233
@@ -0,0 +1,439 @@
|
||||
# AI Agent 工程化完整文档：ReAct Loop 与 Harness Engineering
|
||||
|
||||
> 本文围绕当下 AI Agent 工程化的两大核心命题展开：作为智能体"思考与执行内核"的 **ReAct Loop（推理-行动-观察循环）**，以及作为"运行环境与管控体系"的 **Harness Engineering（驾驭工程）**。两者共同构成生产级 AI Agent 的工程底座。
|
||||
|
||||
---
|
||||
|
||||
## 一、背景：从"调教模型"到"建造系统"
|
||||
|
||||
2026 年，AI Agent 的叙事重心发生了根本性转移：从追求单个 Agent 的"智力上限"，转向构建整个系统的"可靠性下限"。大模型早已不是 AI 落地的唯一瓶颈，行业已达成共识：
|
||||
|
||||
```
|
||||
Agent = Model + Harness
|
||||
```
|
||||
|
||||
模型是引擎，而 Harness（驾驭系统）才是决定智能体能否稳定跑完复杂长任务、从演示级走向生产级的关键。
|
||||
|
||||
AI 工程范式经历了三个阶段的演进：
|
||||
|
||||
| 阶段 | 时间范围 | 核心关注点 | 解决的问题 | 典型技术 |
|
||||
|---|---|---|---|---|
|
||||
| Prompt Engineering | 2022-2024 | 如何让模型理解你的意图 | 单次输出的质量 | 提示词模板、Few-shot 示例 |
|
||||
| Context Engineering | 2025 | 如何给模型正确的知识边界 | 给模型看什么信息 | RAG、上下文窗口管理 |
|
||||
| Harness Engineering | 2026- | 如何让 Agent 可靠、持续、不失控 | 多步骤、长周期任务的可靠性 | 状态机、沙箱、权限系统 |
|
||||
|
||||
这个演进路径反映了 AI 工程从"单点优化"到"系统构建"的转变：早期关注如何让模型"听懂人话"，中期关注如何给模型"正确的参考资料"，而现在关注如何让整个系统"持续稳定运行"。
|
||||
|
||||
---
|
||||
|
||||
## 二、ReAct Loop：Agent 的思考与执行内核
|
||||
|
||||
### 2.1 ReAct 的起源与定义
|
||||
|
||||
ReAct 源自普林斯顿大学与 Google Brain 于 2022 年联合发表的经典论文《ReAct: Synergizing Reasoning and Acting in Language Models》。在 ReAct 出现之前，大模型只有单纯的推理能力（Reasoning），存在严重的幻觉、知识滞后、无法实操的问题；而单纯的工具调用只有行动能力（Acting），缺乏逻辑推理，无法自主判断何时调用工具、调用什么工具。
|
||||
|
||||
ReAct 的核心颠覆式创新在于：**将大模型的推理思考（Thought）与外部工具行动（Action）进行闭环融合**。
|
||||
|
||||
```
|
||||
ReAct = Reasoning（推理思考） + Acting（工具行动）
|
||||
```
|
||||
|
||||
它是一套迭代式循环执行范式：Agent 不再一次性输出答案，而是通过「思考→行动→观察→再思考」的无限循环，逐步拆解复杂任务、调用外部工具、修正推理偏差，直到任务完成。ReAct 是目前 90% 以上开源 Agent（LangChain、LlamaIndex、Meta Agent）的底层核心执行逻辑，也是工业界公认的 AI Agent 标准思考框架。
|
||||
|
||||
### 2.2 T-A-O 三步循环机制
|
||||
|
||||
所有基于 ReAct 的 Agent，底层都是统一的 **T-A-O 循环闭环**，这是必须掌握的核心底层逻辑。
|
||||
|
||||
```
|
||||
用户提问 → Thought 思考 → Action 行动 → Observation 观察 → 任务完成? → 否 → 再次 Thought → 是 → 输出最终答案
|
||||
```
|
||||
|
||||
**1. Thought（推理思考）**
|
||||
|
||||
大模型基于当前用户问题、历史上下文、已有工具列表，进行自主推理判断：
|
||||
- 当前任务是否需要调用工具？
|
||||
- 需要调用哪一个工具？
|
||||
- 工具入参应该如何构造？
|
||||
- 当前任务是否已经完成，可以直接输出答案？
|
||||
|
||||
这一步是 Agent 的智能核心，完全依靠大模型的理解与推理能力。
|
||||
|
||||
**2. Action（工具行动）**
|
||||
|
||||
Agent 根据 Thought 的推理结果，通过 Harness 工具编排层，执行具体外部操作：
|
||||
- 调用计算器、搜索引擎、数据库查询、接口请求、代码解释器等
|
||||
- 严格按照 Harness 约束规则执行，受超时、重试、权限管控
|
||||
- 单次仅执行单一工具任务，保证流程可控
|
||||
|
||||
**3. Observation（结果观察）**
|
||||
|
||||
获取 Action 工具执行的返回结果，将结果作为新的上下文信息喂给大模型，进入下一轮循环。Observation 是修正模型幻觉、补充真实信息的关键，让模型不再依赖陈旧参数知识。
|
||||
|
||||
完整闭环逻辑为：用户提问 → Thought 思考 → Action 执行工具 → Observation 获取结果 → 再次 Thought 迭代 → 任务完成 → 输出最终答案。
|
||||
|
||||
### 2.3 ReAct 范式与传统一次性 Prompt 的对比
|
||||
|
||||
很多新手分不清普通问答和 Agent 的区别，本质就是「是否具备 ReAct 循环能力」：
|
||||
|
||||
| 对比维度 | 传统一次性 Prompt 问答 | ReAct 智能体范式 |
|
||||
|---|---|---|
|
||||
| 执行方式 | 单次推理、一次性输出结果 | 迭代式循环、多轮思考执行 |
|
||||
| 信息来源 | 仅依赖模型训练参数知识 | 模型知识 + 实时外部工具数据 |
|
||||
| 复杂任务能力 | 无法拆解，复杂问题直接答错 | 自动拆解分步解决，适配复杂业务 |
|
||||
| 幻觉概率 | 极高，知识滞后严重 | 大幅降低，以工具真实结果为准 |
|
||||
| 工程依赖 | 无需 Harness，纯 Prompt 即可 | 强依赖 Harness 流程与工具管控 |
|
||||
| 落地场景 | 简单问答、文案生成 | 企业自动化、数据查询、任务调度 |
|
||||
|
||||
### 2.4 ReAct 核心约束 Prompt 模板
|
||||
|
||||
ReAct 之所以能自动完成 T-A-O 循环，核心靠固定格式的系统 Prompt 约束，这也是 Harness 规则约束层的核心体现。原生 ReAct 标准 Prompt 核心结构如下：
|
||||
|
||||
```
|
||||
你是一个可以自主思考和调用工具的智能体。
|
||||
你需要遵循【Thought → Action → Observation】循环逻辑解决问题。
|
||||
可用工具列表：{tools}
|
||||
严格遵循输出格式：
|
||||
1. 思考(Thought): 分析当前问题，判断是否需要调用工具
|
||||
2. 行动(Action): 需要调用工具时，输出工具名称和参数
|
||||
3. 观察(Observation): 接收工具返回结果
|
||||
如果已经获取足够信息，无需继续调用工具，直接输出最终答案。
|
||||
问题：{input}
|
||||
历史记录：{agent_scratchpad}
|
||||
```
|
||||
|
||||
其中 `agent_scratchpad` 是 ReAct 的核心缓存，记录每一轮的 Thought、Action、Observation，保存迭代全过程状态，属于 Harness 上下文记忆层能力；`tools` 是 Harness 注册的全部可调用工具列表；`input` 是用户原始任务指令。
|
||||
|
||||
---
|
||||
|
||||
## 三、Harness Engineering：Agent 的运行环境与管控体系
|
||||
|
||||
### 3.1 核心概念与思想
|
||||
|
||||
Harness Engineering，也叫"驾驭工程"或 Agent Harness，是围绕 AI Agent 构建工作环境的一套工程方法。它的目标不是让模型"回答得更好看"，而是让 Agent 在真实工程系统里：
|
||||
- 能理解任务
|
||||
- 能读取必要上下文
|
||||
- 能调用合适工具
|
||||
- 能安全修改代码
|
||||
- 能运行测试验证
|
||||
- 能观察日志和失败原因
|
||||
- 能根据反馈继续修复
|
||||
- 能在边界内完成交付
|
||||
|
||||
简而言之：**Prompt 是你怎么跟模型说话，Harness 是你怎么给 Agent 搭工作台**。如果说大模型本身提供的是推理和生成能力，那么 Harness 提供的就是工程环境、工具系统、反馈机制和安全边界。
|
||||
|
||||
Harness 的原意是"马具"——套在马身上用于控制方向、承受重负、连接马车的那套皮革与金属装置。这个比喻非常精准：大模型就像一匹充满力量但难以预测的野马，而 Harness 就是那套让它变得可控、有用的装置。更精确的公式是：
|
||||
|
||||
```
|
||||
生产级 Agent = 模型潜能 - 模型熵增 + Harness 约束
|
||||
```
|
||||
|
||||
其中"模型熵增"指大模型基于概率生成的不确定性，输入微小的 Prompt 变化可能导致巨大的行为漂移；而"Harness 约束"则是用确定性的代码逻辑去框住不确定的模型输出。Harness Engineering 的核心思想是：**每当 Agent 犯错，就将其工程化为一个永久性的系统修复，确保它不会再犯同样的错误**。
|
||||
|
||||
### 3.2 Harness 与 Prompt 工程的本质区别
|
||||
|
||||
| 维度 | Prompt Engineering | Harness Engineering |
|
||||
|---|---|---|
|
||||
| 核心问题 | 如何措辞指令 | 如何构建可靠系统 |
|
||||
| 作用范围 | 单次推理 | 全任务生命周期 |
|
||||
| 控制手段 | 文本指令 | 工具 + 约束 + 反馈 + 基建 |
|
||||
| 失败模式 | 误解意图 | 缺乏纠错机制 |
|
||||
| 可复现性 | 依赖模型一致性 | 依赖工程化保障 |
|
||||
| 类比 | 写指令邮件 | 建项目管理体系 |
|
||||
|
||||
一个具体例子可以说明这种区别。你在 prompt 里写"请遵守项目架构，不要跨层调用"——这是 Prompt 工程；但如果你把架构边界写进 custom linter，每次 Agent 改完代码都会被自动检查，违反规则就失败——这就是 Harness 工程。Prompt 可以是 Harness 的一部分，但 Harness 远远不止 Prompt。
|
||||
|
||||
### 3.3 Harness 七层内核
|
||||
|
||||
一个生产级 Harness 由七大协同组件构成，共同约束与增强智能体行为：
|
||||
|
||||
1. **System Prompts（系统提示）**：行为宪法，定义身份、边界、硬约束。
|
||||
2. **Tools and Capabilities（工具与能力）**：精准能力接口，命名自解释、参数精确、错误可修复。
|
||||
3. **Infrastructure（基础设施）**：沙箱、执行引擎、文件系统等安全运行环境。
|
||||
4. **Orchestration Logic（编排逻辑）**：子智能体调度、任务分发与路由。
|
||||
5. **Hooks and Middleware（钩子与中间件）**：确定性检查点，安全门控、质量回路、完成门控、可观测性。
|
||||
6. **Memory and State（记忆与状态）**：进度与记忆持久化，避免长任务"失忆"。
|
||||
7. **Verification Systems（验证系统）**：Linter、测试、审查 Agent，最后质量防线。
|
||||
|
||||
它们联动形成闭环：验证触发 Hook，记忆动态组装 Prompt，编排决定工具调用。
|
||||
|
||||
### 3.4 引导系统与反馈系统：双控机制
|
||||
|
||||
为方便理解，可以把 Harness 工程拆成两大子系统：
|
||||
|
||||
**引导系统（前馈控制 Guide）**——Agent 执行前，怎么知道该怎么做。核心是把项目里的隐性规则显性化，常见内容包括 AGENTS.md、CLAUDE.md、README、架构文档、编码规范、目录结构说明、项目启动脚本、测试命令说明、API 文档、领域知识、任务拆解模板、团队 review checklist 等。它的作用是行动前设路标与护栏，从源头减少错误。
|
||||
|
||||
**反馈系统（反馈控制 Sensor）**——Agent 执行后，怎么知道有没有做对。常见内容包括单元测试、接口测试、端到端测试、类型检查、linter、静态扫描、架构测试、安全扫描、浏览器自动化、运行日志、metrics、traces、错误堆栈、代码评审 Agent、LLM Judge、人工 review。反馈内部再分为：
|
||||
- **计算性反馈**：规则驱动、毫秒级、100% 可靠，优先用
|
||||
- **推理性反馈**：AI 判断、秒级、非确定，作为补充
|
||||
|
||||
---
|
||||
|
||||
## 四、ReAct 与 Harness 的层级关系
|
||||
|
||||
结合 AI Agent 完整工程化体系，三者层级关系清晰可见：
|
||||
|
||||
```
|
||||
1. LLM 模型：提供基础推理智能，是 Agent 的大脑基础
|
||||
2. ReAct 范式：定义大脑的思考方式（T-A-O 循环），是 Agent 的执行内核逻辑
|
||||
3. Harness 工程：为 ReAct 循环提供约束、容错、记忆、监控、工具调度的整套运行环境
|
||||
```
|
||||
|
||||
终极公式为：
|
||||
|
||||
```
|
||||
企业级 Agent = LLM + ReAct 执行逻辑 + Harness 工程管控
|
||||
```
|
||||
|
||||
如果大模型是 Agent 的大脑，那 ReAct 就是 Agent 的"思考与行动规则"，是让 AI 从"只会说话"变成"会干活"的关键转折点；而 Harness 则是为这套规则提供可靠运行环境的"操作系统"。ReAct 是执行内核，Harness 是运行环境，二者缺一不可。
|
||||
|
||||
---
|
||||
|
||||
## 五、生产级 Agent Harness 四层架构
|
||||
|
||||
深入分析 Claude Code、OpenCode、OpenClaw、Hermess 等代表性生产级 Agent 项目，可以发现一个生产级的 Agent Harness 通常分为四层，每一层都有明确的职责和边界。
|
||||
|
||||
### 5.1 架构全景
|
||||
|
||||
这四层围绕"感知→决策→行动→反馈"闭环紧密协作：
|
||||
|
||||
1. **推理与编排层**：Agent 的"大脑与调度中心"，负责核心决策逻辑。
|
||||
2. **上下文与记忆层**：Agent 的"工作记忆与长期记忆"，管理输入和进化。
|
||||
3. **工具与安全执行层**：Agent 的"双手与安全护栏"，封装外部调用。
|
||||
4. **支撑与基础架构层**：Agent 的"神经系统与循环系统"，提供底层支撑。
|
||||
|
||||
以"帮我在项目里添加用户登录功能"为例，完整流程为：支撑层接收请求并分配会话 ID → 上下文层组装输入（从 CLAUDE.md 读取技术栈、从记忆系统加载用户偏好）→ 推理层启动 Plan Mode 生成任务清单 → 用户批准后进入 Execute Mode → 安全层拦截工具调用做 AST 分析与风险评估 → 执行结果返回推理层 → 循环继续。
|
||||
|
||||
### 5.2 推理与编排层：Agent Loop 的状态机化
|
||||
|
||||
最基础的 Agent Loop 就是一个 while 循环：
|
||||
|
||||
```javascript
|
||||
while (!done) {
|
||||
const response = await callLLM(messages);
|
||||
if (response.toolCalls.length > 0) {
|
||||
const results = await executeTools(response.toolCalls);
|
||||
messages.push(...results);
|
||||
} else {
|
||||
done = true;
|
||||
return response.content;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
但在生产环境中这远远不够，需要处理流式响应、并行执行、错误恢复、用户中断、状态持久化等问题。因此生产级系统普遍采用状态机管理循环，例如 Claude Code 内部定义了精细的状态：
|
||||
|
||||
```javascript
|
||||
enum LoopState {
|
||||
INIT = 'INIT', // 初始化，准备上下文
|
||||
THINKING = 'THINKING', // 正在调用 LLM
|
||||
PARSING = 'PARSING', // 解析 LLM 输出
|
||||
EXECUTING = 'EXECUTING', // 执行工具（可能并行）
|
||||
OBSERVING = 'OBSERVING', // 收集工具结果
|
||||
REFLECTING = 'REFLECTING', // （可选）反思结果
|
||||
COMPRESSING = 'COMPRESSING', // 触发上下文压缩
|
||||
TERMINATED = 'TERMINATED' // 终止
|
||||
}
|
||||
```
|
||||
|
||||
状态机的优势在于明确的阶段划分、易于调试、支持暂停/恢复、错误隔离。实现要点包括：状态转换要原子化、状态数据要隔离、超时控制要精细、可观测性要内置。每个状态对应一个独立的处理器（Handler），状态机只负责调度。
|
||||
|
||||
对于复杂任务，还支持多智能体编排，常见两种模式：
|
||||
- **父子委派模式**（主 Agent 通过 Task 工具委派子任务给 SubAgent，具备上下文隔离、递归深度限制、结果聚合）
|
||||
- **对等协作模式**（多个 Agent 组成团队，通过消息总线异步通信）
|
||||
|
||||
### 5.3 上下文与记忆层：System Prompt 的结构化组装
|
||||
|
||||
生产级系统的 System Prompt 分为静态区和动态区。静态区（角色定义、输出格式、安全规范）放在前面以利用 LLM 缓存，减少 Token 消耗；动态区（项目名、技术栈、当前任务、历史摘要）放在后面每次更新。
|
||||
|
||||
项目级上下文通过智能加载机制实现：Agent 启动时自动扫描项目根目录，按优先级寻找 CLAUDE.md、AGENTS.md、.claude/context.md 等配置文件，并对内容做智能截断（只取前 N 个 Token）。
|
||||
|
||||
### 5.4 上下文工程：渐进式披露
|
||||
|
||||
上下文是稀缺资源，上下文腐烂和描述膨胀会让准确率暴跌。核心策略是**渐进式披露**，分三层管理：
|
||||
|
||||
- **索引层**：始终保留项目结构、入口地图。
|
||||
- **接口层**：操作模块时加载 API 与约束。
|
||||
- **实现层**：修改文件时才加载源码。
|
||||
|
||||
用目录式索引告诉智能体"去哪找"，而非"全记住"，上下文可从数万 Token 压至几千。
|
||||
|
||||
---
|
||||
|
||||
## 六、实战：从零实现标准 ReAct Agent
|
||||
|
||||
下面给出一份基于 LangChain 的标准原生 ReAct 智能体完整可运行代码，完整保留 T-A-O 循环、格式约束、容错机制与 Harness 管控能力，适配国内开源大模型。
|
||||
|
||||
### 6.1 环境依赖
|
||||
|
||||
```bash
|
||||
pip install langchain langchain-openai python-dotenv
|
||||
```
|
||||
|
||||
### 6.2 完整可运行代码
|
||||
|
||||
```python
|
||||
from dotenv import load_dotenv
|
||||
import os
|
||||
from langchain_openai import ChatOpenAI
|
||||
from langchain.agents import AgentExecutor, create_react_agent
|
||||
from langchain.tools import CalculatorTool
|
||||
from langchain_community.utilities import WikipediaAPIWrapper
|
||||
from langchain_community.tools import WikipediaQueryRun
|
||||
from langchain.prompts import PromptTemplate
|
||||
from langchain.globals import set_debug
|
||||
|
||||
# 加载环境变量
|
||||
load_dotenv()
|
||||
# 开启全链路日志（Harness 可观测能力）
|
||||
set_debug(True)
|
||||
|
||||
# ===================== 1. 初始化模型（适配国内任意 OpenAI 格式接口） =====================
|
||||
llm = ChatOpenAI(
|
||||
model="qwen-turbo",
|
||||
temperature=0.0, # 零随机性，保证 ReAct 思考逻辑稳定
|
||||
openai_api_key=os.getenv("OPENAI_API_KEY"),
|
||||
openai_api_base=os.getenv("OPENAI_API_BASE")
|
||||
)
|
||||
|
||||
# ===================== 2. 注册工具（Harness 工具层） =====================
|
||||
calc_tool = CalculatorTool()
|
||||
wiki_api = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=500)
|
||||
wiki_tool = WikipediaQueryRun(api_wrapper=wiki_api)
|
||||
tools = [calc_tool, wiki_tool]
|
||||
|
||||
# ===================== 3. 标准 ReAct 约束 Prompt（核心） =====================
|
||||
react_prompt = PromptTemplate.from_template("""
|
||||
你是严格遵循 ReAct 范式的智能体，必须按照 Thought → Action → Observation 循环执行任务。
|
||||
可用工具：{tools}
|
||||
执行规则：
|
||||
1. 遇到需要计算、外部知识查询的问题，必须调用工具，禁止自行编造答案
|
||||
2. 每一轮只能做一次思考 + 一次工具调用
|
||||
3. 信息足够后，停止循环，输出简洁完整的最终答案
|
||||
用户问题：{input}
|
||||
执行过程记录：{agent_scratchpad}
|
||||
""")
|
||||
|
||||
# ===================== 4. 创建 ReAct Agent + Harness 管控 =====================
|
||||
agent = create_react_agent(llm, tools, react_prompt)
|
||||
|
||||
# Harness 容错、限流、防死循环配置
|
||||
agent_executor = AgentExecutor(
|
||||
agent=agent,
|
||||
tools=tools,
|
||||
verbose=True,
|
||||
max_iterations=5, # 最大循环次数，防止 ReAct 死循环
|
||||
handle_parsing_errors=True, # 解析异常兜底
|
||||
timeout=15, # 超时熔断
|
||||
return_intermediate_steps=True # 返回完整 ReAct 步骤
|
||||
)
|
||||
|
||||
# ===================== 5. 测试运行 =====================
|
||||
if __name__ == "__main__":
|
||||
query = "请查询圆周率的近似定义，并计算 3.14159 * 128 的结果"
|
||||
result = agent_executor.invoke({"input": query})
|
||||
print("=" * 50)
|
||||
print("最终答案：", result["output"])
|
||||
print("=" * 50)
|
||||
print("完整 ReAct 迭代步骤：")
|
||||
for step in result["intermediate_steps"]:
|
||||
print(f"步骤详情：{step}")
|
||||
```
|
||||
|
||||
### 6.3 运行逻辑解析
|
||||
|
||||
执行过程遵循标准 ReAct 多轮迭代闭环：
|
||||
1. 第一轮 Thought 识别任务需要先查询圆周率定义，调用维基百科工具
|
||||
2. 第一轮 Action 执行百科查询
|
||||
3. 第一轮 Observation 拿到文本信息，判断还需要数学计算
|
||||
4. 第二轮 Thought 决定调用计算器工具执行乘法
|
||||
5. 第二轮 Action 执行计算
|
||||
6. 信息充足，终止循环输出最终答案
|
||||
|
||||
---
|
||||
|
||||
## 七、ReAct 工程落地常见踩坑与优化
|
||||
|
||||
在 Harness 工程落地中，ReAct 是故障高发点，核心问题全部来自循环机制本身。
|
||||
|
||||
| 问题 | 现象 | 根因 | 解决方案 |
|
||||
|---|---|---|---|
|
||||
| 无限循环 | Agent 反复调用同一工具，无法结束任务 | 模型无法判断任务是否完成、工具返回信息重复 | Harness 层配置 `max_iterations` 最大迭代限制，强制熔断 |
|
||||
| 格式解析失败 | 模型输出不遵循 Thought/Action 格式，任务中断 | Prompt 约束不严格 | 开启 `handle_parsing_errors` 异常兜底，优化 Prompt 格式约束 |
|
||||
| 过度调用工具 | 简单问题也强行调用工具，浪费 Token | 缺乏常识判断规则 | 在 Prompt 中增加规则：简单常识问题可直接回答 |
|
||||
| 上下文溢出 | 多轮迭代后 `agent_scratchpad` 过长触发超限 | 迭代日志累积 | 依托 Harness 记忆层，定时精简迭代日志、截断无效历史 |
|
||||
|
||||
### 企业级 ReAct 工程优化方案（结合 Harness 架构）
|
||||
|
||||
原生 ReAct 仅能实现基础能力，企业落地必须结合 Harness 架构做优化：
|
||||
|
||||
1. **约束层优化**：分级规则管控，简单任务弱约束、复杂任务强约束，平衡稳定性与灵活性。
|
||||
2. **容错层优化**：智能重试 + 失败降级，工具调用失败时自动重试 2 次，重试失败后触发兜底答案，不中断业务流程。
|
||||
3. **记忆层优化**：迭代过程轻量化存储，区分"有效迭代步骤"和"冗余日志"，长期只保存关键 ReAct 决策过程。
|
||||
4. **可观测层优化**：步骤级监控，统计每轮 ReAct 迭代耗时、失败率、工具调用命中率，数据驱动优化。
|
||||
|
||||
---
|
||||
|
||||
## 八、Harness 落地实践与治理
|
||||
|
||||
### 8.1 真实项目落地清单
|
||||
|
||||
在一个前后端分离的业务项目里，要让 Coding Agent 帮忙修 Bug、改接口、补测试，可以这样设计 Harness：
|
||||
|
||||
1. 用 AGENTS.md 或 CLAUDE.md 做统一入口，告知 Agent 项目结构、常用命令、关键约束和禁止事项。
|
||||
2. 把详细架构文档放到 docs 目录，让 Agent 按需读取，而不是每次都塞进 prompt。
|
||||
3. 用 linter、类型检查和架构测试限制跨层调用，避免 Agent 改出"能跑但不符合架构"的代码。
|
||||
4. 提供标准化启动脚本，如 `start-backend`、`start-frontend`、`run-unit-test`、`run-api-test`。
|
||||
5. 对接口任务接入 Swagger、OpenAPI、Postman Collection 或自动化接口测试。
|
||||
6. 对前端任务接入 Playwright，让 Agent 不只是看代码，而是真的打开页面验证。
|
||||
7. 暴露运行日志、metrics 和 traces，让 Agent 失败后能看到原因，而不是凭空猜。
|
||||
8. 在任务结束前加入 checklist，要求确认需求点、测试结果、修改范围和风险点。
|
||||
9. 对复杂任务引入独立 Review Agent 或人工 review，避免单 Agent 自说自话。
|
||||
10. 关键仓库必须配置权限和沙箱，限制 Agent 能访问什么、能修改什么、能执行什么命令。
|
||||
|
||||
### 8.2 治理三维度与落地四阶段
|
||||
|
||||
**治理三维度（从易到难）**：
|
||||
|
||||
1. **可维护性**：代码规范、圈复杂度，工具成熟、自动化高。
|
||||
2. **架构适应性**：性能、安全、依赖审计，需复杂基建。
|
||||
3. **行为正确性**：业务需求匹配，最难、自动化最低。
|
||||
|
||||
**落地四阶段**：
|
||||
|
||||
1. **基础验证**：部署 Lint 与测试，打底质量底线。
|
||||
2. **前馈增强**：把失败转为 AGENTS.md 规则，显性化隐性知识。
|
||||
3. **闭环优化**：高频错误变 Hook，形成自纠错。
|
||||
4. **度量驱动**：用指标仪表盘数据定向优化。
|
||||
|
||||
### 8.3 转向循环：让错误只犯一次
|
||||
|
||||
Harness 的终极价值是**复利效应**：观察失败 → 诊断根因 → 工程化修复 → 编码进 Harness → 验证部署。把单次人工修正，变成永久规则。比如智能体总提交超大代码，加一条"单次提交≤200 行"，所有会话永久遵守，同类错误彻底消失。
|
||||
|
||||
Terminal-Bench 2.0 基准显示：同一模型仅换 Harness，排名可偏移超 25 位；精良 Harness 的中等模型，能打败粗糙 Harness 的顶级模型——**Harness 质量，才是性能决定性因素**。
|
||||
|
||||
---
|
||||
|
||||
## 九、总结
|
||||
|
||||
ReAct 不是一个框架、不是一个工具，而是 AI Agent 的标准思考与执行范式，是所有智能体实现"自主解决复杂任务"的核心底层。它通过 T-A-O 循环让 AI 从"只会说话"变成"会干活"。
|
||||
|
||||
Harness Engineering 则让 AI 工程范式从"调教模型"转向"建造系统"，把不可控的概率输出变成可控、可复现、可持续优化的生产级能力。它的核心是搭建可验证、可约束的运行体系，让 AI 能可靠完成长链路任务。
|
||||
|
||||
二者的关系是：**ReAct 是执行内核，Harness 是运行环境**。只有吃透 ReAct 的迭代闭环、踩坑痛点与工程优化，同时构建完善的 Harness 约束、容错、记忆、监控体系，才能开发出稳定、可落地、可迭代的企业级 AI Agent，而不是只能跑 Demo 的玩具智能体。
|
||||
|
||||
AI Agent 的竞争早已不是模型军备竞赛，而是系统工程能力的比拼——未来决定 AI 落地上限的，不是模型有多强，而是你的 Harness 有多稳。
|
||||
|
||||
---
|
||||
|
||||
## 参考来源
|
||||
|
||||
- 《ReAct: Synergizing Reasoning and Acting in Language Models》— Yao et al., Princeton & Google Brain, 2022
|
||||
- Anthropic Claude Agent SDK 工程博客 — "Agent Harness"
|
||||
- Mitchell Hashimoto — "Harness Engineering" 概念提出
|
||||
- Terminal-Bench 2.0 基准测试数据
|
||||
- Claude Code / OpenCode / OpenClaw / Hermess 生产级 Agent 项目源码分析
|
||||
- CSDN 博客：《AI Agent 驾驭工程：从理论到生产级系统架构实战》
|
||||
- CSDN 博客：《AI Agent 核心范式 ReAct 深度详解》
|
||||
- CSDN 博客：《Harness Engineering：AI Agent 从"能用"到"可靠"的工程革命》
|
||||
- 博客园：《面试官问：什么是 Harness 工程？》
|
||||
- 腾讯新闻：《AI 大模型实战篇：AI Agent 设计模式 ReAct》
|
||||
+3
-3
@@ -91,7 +91,7 @@ npm run dist # NSIS 安装包
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `release/Metona Ollama Setup v0.11.11.exe` | NSIS 安装包（可选目录、创建快捷方式） |
|
||||
| `release/Metona Ollama Setup v0.12.2.exe` | NSIS 安装包（可选目录、创建快捷方式） |
|
||||
|
||||
> 仅提供 NSIS 安装包。
|
||||
|
||||
@@ -103,7 +103,7 @@ npm run dist # NSIS 安装包
|
||||
TOKEN="your_access_token"
|
||||
curl -X POST "https://gitee.com/api/v5/repos/thzxx/metona-ollama-desktop/releases?access_token=$TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"tag_name":"v0.11.11","name":"v0.11.11","body":"Release notes","target_commitish":"master"}'
|
||||
-d '{"tag_name":"v0.12.2","name":"v0.12.2","body":"Release notes","target_commitish":"master"}'
|
||||
```
|
||||
|
||||
### 上传附件
|
||||
@@ -112,7 +112,7 @@ curl -X POST "https://gitee.com/api/v5/repos/thzxx/metona-ollama-desktop/release
|
||||
TOKEN="your_access_token"
|
||||
RELEASE_ID="<release_id>"
|
||||
curl -X POST "https://gitee.com/api/v5/repos/thzxx/metona-ollama-desktop/releases/$RELEASE_ID/attach_files?access_token=$TOKEN" \
|
||||
-H "Content-Type: multipart/form-data" -F "file=@release/Metona Ollama Setup v0.11.11.exe"
|
||||
-H "Content-Type: multipart/form-data" -F "file=@release/Metona Ollama Setup v0.12.2.exe"
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# Metona Ollama Desktop — 开发规范
|
||||
|
||||
> 版本: v0.11.11 | 更新: 2026-06-05 | 维护: 项目团队
|
||||
> 版本: v0.12.2 | 更新: 2026-06-05 | 维护: 项目团队
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user