🛠️ Harness 工程深度解析：让 AI 连续干活几小时不拉胯的核心技术

# Harness 工程深度解析：让 AI 连续干活几小时不拉胯的核心技术 > 主题：AI 长时间自主工作的工程范式 > 核心来源：Ralph Loop (Geoffrey Huntley), Anthropic/Claude Code Harness, OpenAI Harness Engineering, Hatice/Sisyphus/dmux 开源实现 > 分析：小凯 > 时间：2026-04-27 --- ## 一、问题的本质：为什么 AI 不能长时间工作？ ### 1.1 三个致命障碍 让 AI 连续工作几小时，开发者会遇到三个根本性问题： **① 上下文窗口枯竭（Context Window Exhaustion）** 大模型的上下文窗口有限（~170-200K tokens）。一个复杂项目不可能在一轮对话里完成。随着对话变长，早期信息被压到窗口底部，模型逐渐"遗忘"之前做了什么。更糟的是，即使使用 compaction（上下文压缩），压缩后的指令往往不够清晰，导致下一轮模型在半成品状态上乱猜。 **② 上下文腐烂（Context Rot）** 不是窗口满了才出问题。即使没满，随着无关信息、错误尝试、调试输出在上下文中积累，模型的输出质量也会逐步下降。它会重复犯同样的错误，或者在已有进展的基础上宣布"任务已完成"（ premature termination）。 Anthropic 的内部实验发现：即使给 Claude Opus 4.5 一个高级提示"build a clone of claude.ai"，它也会： - **试图一次性做完** → 中间耗尽上下文，留下半成品 - **后期看到已有进展，宣布任务完成** → 实际上还差很远 **③ 状态丢失（State Amnesia）** 每个新会话开始时，模型对之前的工作一无所知。如果没有外部记忆机制，它必须从零开始理解项目结构、已有代码、设计决策——相当于每个班次换个完全没交接的工程师。 ### 1.2 传统方案的局限 | 方案 | 思想 | 问题 | |------|------|------| | **单会话超长对话** | 靠 compaction 撑时间 | Context rot 严重，质量逐步下降 | | **RAG 检索** | 把历史存入向量库，按需检索 | 检索精度有限，无法捕捉完整的执行状态 | | **人工分阶段** | 人类每步检查、手动推进 | 失去了" autonomous "的意义 | --- ## 二、Ralph 方案：用 while 循环和文件系统打败遗忘 ### 2.1 起源与核心思想 **Ralph Loop**（又称 "Ralph Wiggum technique"）由开源开发者 **Geoffrey Huntley** 提出并推广。名字来自《辛普森一家》里的 Ralph Wiggum——可爱但健忘，真诚但容易犯错。这恰好是 AI agents 的写照。 **核心哲学**： > "AI agents don't remember previous attempts and will cheerfully make the same mistakes twice." > —— Geoffrey Huntley 解决方案：**每轮迭代全新上下文，文件系统做持久记忆，重复足够多的次数让 Ralph 最终做对。** ### 2.2 最简形式 ```bash while :; do cat PROMPT.md | claude-code ; done ``` 就这么简单。一个 bash while 循环，每轮读取同一个 PROMPT.md，通过管道送入 claude-code（或任何 agent CLI），每轮都是一个**全新的会话**。 ### 2.3 关键设计：Fresh Context Per Iteration 这是 Ralph 与其他所有方案的根本区别： > **"If you're implementing Ralph as part of the agent harness via skill/command/etc you are missing the point of Ralph which is to use always a fresh context."** > —— Michael Arnaldi 每轮迭代： 1. **全新会话** = 全新 200K 上下文窗口，零负担 2. **从文件系统读取状态** = `progress.txt`、`prd.json`、`AGENTS.md` 3. **执行一步** = 只做一个任务，不贪心 4. **写入新状态** = 更新文件，git commit 5. **循环** ### 2.4 文件系统作为持久记忆 | 文件/目录 | 用途 | |-----------|------| | `PROMPT.md` | 每轮注入的核心指令，定义目标 | | `specs/*.md` | 每个功能一个规格文件，按需加载 | | `progress.txt` / `prd.json` | 当前进度、已完成的任务清单 | | `AGENTS.md` / `.claude/CLAUDE.md` | 机构记忆——编码标准、架构约束、方法论 | | `learnings.md` | 每轮迭代的经验教训，避免重复犯错 | | `state/recursion-depth.json` | 递归深度、agent lineage、预算追踪 | | `handoffs/` | 跨会话的架构决策文档 | Blake Crosley 的实现中，`.claude/` 目录演变成了一个 **7 层、650 文件** 的分布式上下文架构——这是 Ralph 在实践中自然生长出的复杂记忆系统。 ### 2.5 防退出机制（Stop Hooks） AI 有一个讨厌的习惯：做了 20% 就说"完成了"。Ralph 用 **hook 拦截退出意图**： ``` if "任务完成" in result or is_exit_intent(result): # Ralph 拦截！强制续命 write_file("fix_plan.md", update_plan(plan, result)) git commit(f"完成第 {step} 步") continue # 重新开启新会话 ``` Hook 检查机器可验证的完成条件： - 测试通过了吗？ - linter 干净吗？ - type check 通过了吗？ - 文件匹配了吗？ **不满足条件 = 不能退出。** ### 2.6 Backpressure：用工程工具做反馈环 Ralph 不做复杂的智能验证，而是**复用现有工程基础设施**： | 工具 | 作用 | |------|------| | **Tests** | 最硬的完成标准 | | **Linters** | 代码风格/质量 | | **Type checkers (mypy)** | 类型安全 | | **Security scanners** | 安全合规 | | **Git diff** | 变更审查 | > "The faster the wheel turns, the more iterations you can run." 每轮循环都跑测试、跑 lint、跑 type check。失败就把错误信息注入下一轮 prompt，让模型修复。这就是 backpressure——工程工具成为 agent 的"纠错机制"。 ### 2.7 Ralph 的局限性 **优点**： - 极其简单，几行 bash 就能跑 - 避免了 context rot - 每轮都有满血上下文 - 失败可预测、可调试 **缺点**： - **线性迭代**，无法并行 - **没有任务分解**，大任务需要人类先拆好 PRD - **重复犯错**，虽然能收敛，但效率不高 - **适合绿地项目**，对已有代码库的增量修改支持一般 - **文件系统污染**，650 个文件的 `.claude/` 目录可能让 repo 变得杂乱 Geoffrey Huntley 自己说： > "Ralph is deterministically bad in a non-deterministic world." > > "Any problem created by AI can be resolved through a different series of prompts." --- ## 三、多智能体方案（推荐）：主 Agent 只协调不干活 ### 3.1 为什么多智能体更好？ Ralph 解决了"长时间运行"，但没有解决"复杂任务分解"和"专业化分工"。 Anthropic 的研究发现： > **"Separating the agent doing the work from the agent judging it proves to be a strong lever to address this issue."** > —— Prithvi Rajasekaran, Anthropic Labs AI 评估自己的工作时会**系统性偏正**（self-evaluation bias）。就像学生自己批改自己的试卷，分数总是虚高。 多智能体方案把角色拆开： - **Planner**（规划者）：拆任务、定顺序、写 spec - **Generator/Worker**（执行者）：写代码、做实现 - **Evaluator/Reviewer**（评估者）：审代码、跑测试、给反馈 - **Coordinator/Supervisor**（协调者）：只调度，不干活 ### 3.2 Anthropic 三 Agent 架构 Anthropic 在 2026 年 4 月发布了生产级的三 Agent Harness： **① Initializer Agent（初始化者）** - **只做一次**，在第一轮运行 - 设置完整环境：安装依赖、创建目录结构、生成所有 feature spec - 输出：一个准备好的工作空间，后续 agent 可以直接用 **② Coding Agent（编码者）** - **每轮迭代运行** - 读取当前进度，执行一个 feature - 要求：增量推进 + 干净的结束状态（代码可合并到 main 分支） - 输出：git commit + 更新的进度文件 **③ Evaluator Agent（评估者）** - **在关键节点运行** - 用 Playwright MCP 导航实际页面、交互验证 - 针对前端设计任务，按四个维度评分：设计质量、原创性、工艺、功能性 - 输出：详细 critique，指导 generator 迭代 ### 3.3 结构化交接（Structured Handoff） 多 Agent 系统的核心不是"更多大脑"，而是**结构化交接**： ``` 交接工件（Artifacts）: ├── features.json # 所有功能清单及状态 ├── design.md # 当前设计决策 ├── tests/ # 测试套件 ├── commits/ # git 历史 └── evaluation-report.md # 最新评估报告 ``` 每个 agent 会话开始时读取这些文件，结束时更新它们。**上下文不是通过对话传递，而是通过 schema 化的文件传递。** Artem Bredikhin 总结得好： > "long-running AI agents fail for a simple reason: every new context window is amnesia. The breakthrough is structure: JSON feature specs, enforced testing, commit-by-commit progress, and an init script that ensures every session starts with a working app." ### 3.4 "写 bug 的人修 bug、提 bug 的人验收" 这是多智能体系统的精髓——**职责隔离**： | 角色 | 职责 | 不能做的事 | |------|------|-----------| | **Developer Agent** | 写代码、实现 feature | 不能评估自己的代码质量 | | **Reviewer Agent** | 审查代码、提出 bug | 不能写修复代码 | | **Tester Agent** | 跑测试、验证功能 | 不能修改测试来让它们通过 | | **Fixer Agent** | 修复 Reviewer 提出的 bug | 不能修改验收标准 | | **Coordinator** | 分配任务、检查完成条件 | 不直接写代码 | **为什么这样设计？** - 如果 Developer 自己评估，会漏掉 bug - 如果 Reviewer 自己修复，会放水 - 分离后，Reviewer 有动力找问题，Fixer 有动力解决问题 - 这和人类软件工程里的 code review 机制一模一样 ### 3.5 提示词工程：每个角色的 Prompt 设计 **Developer Prompt 模板**： ``` 你是一个开发者。你的任务是实现 features.json 中标记为 PENDING 的下一个 feature。 规则： 1. 一次只实现一个 feature 2. 必须写对应的单元测试 3. 代码必须通过 mypy 类型检查 4. 提交前运行完整测试套件 5. 如果测试失败，修复后再提交 6. 完成后更新 features.json 状态为 DONE 当前状态： {features_json} 当前代码库： {git_diff_summary} 开始工作。 ``` **Reviewer Prompt 模板**： ``` 你是一个严格的代码审查者。你的任务是审查最新提交。 审查维度： 1. 功能正确性（测试是否覆盖所有边界情况） 2. 代码质量（可读性、命名、注释） 3. 架构一致性（是否符合 design.md 的约束） 4. 安全（是否有注入风险、敏感信息泄露） 输出格式： - 每个问题必须包含：文件路径、行号、问题描述、建议修复 - 如果没有任何问题，输出 "SHIP"（可以合并） - 如果有问题，输出 "BLOCK" + 问题清单 不要修复代码。只审查。修复是另一个 agent 的工作。 ``` **关键原则**： - **约束行为（Constrained Action Schemas）**：每个 agent 只能做特定的事 - **类型化交接（Typed Handoffs）**：agent 之间的通信必须用 schema，不能自由对话 - **边界验证（Boundary Validation）**：每个交接点都要验证输入输出是否符合预期 --- ## 四、任务拆分与流程设计 ### 4.1 任务分解的艺术 Harness 工程的核心是**把一个大任务拆成机器可执行的小步骤**。不是让 AI "做一个网站"，而是： ``` 任务树： ├── [P0] 初始化项目结构 │ ├── 创建目录 │ ├── 安装依赖 │ └── 配置 linter + test runner ├── [P1] 用户认证模块 │ ├── [P1.1] 登录 API │ ├── [P1.2] 注册 API │ ├── [P1.3] JWT token 逻辑 │ └── [P1.4] 前端登录页面 ├── [P2] 核心功能模块 │ └── ... └── [P3] 部署配置 ``` 每个节点都是**机器可验证的**： - 不是"实现登录功能" - 而是"实现 POST /api/login，输入 {username, password}，输出 {token}，测试覆盖空密码、错误密码、SQL 注入" ### 4.2 Spec-Driven Development Harness 工程推崇**规格驱动开发**——不是写代码，而是先写规格： ```markdown ## Feature: User Login ### Acceptance Criteria - [ ] API endpoint POST /api/login returns 200 + JWT token on valid credentials - [ ] Returns 401 on invalid password - [ ] Returns 400 on missing username or password - [ ] Rate limit: 5 attempts per minute per IP - [ ] Password must be hashed with bcrypt (cost factor 12) ### Tests - test_login_success - test_login_invalid_password - test_login_missing_fields - test_login_rate_limit - test_login_sql_injection ### Dependencies - P0.1 (project structure) - P0.2 (database setup) ``` Agent 的工作就是勾掉这些 checkbox。验收标准机器可验证，没有模糊地带。 ### 4.3 迭代循环设计 一个典型的多 Agent 工作循环： ``` Round 1: Planning └── Coordinator 读取用户需求 → Planner 生成任务树 + specs Round 2: Implementation (并行) ├── Developer A 实现 P1.1 (登录 API) ├── Developer B 实现 P1.2 (注册 API) └── Developer C 实现 P1.4 (登录页面) Round 3: Review (并行) ├── Reviewer A 审查 P1.1 ├── Reviewer B 审查 P1.2 └── Reviewer C 审查 P1.4 Round 4: Fix (并行) ├── Fixer A 修复 Reviewer A 的问题 └── ... Round 5: Integration Test └── Tester 跑完整集成测试 Round 6: 如果测试失败 → 回到 Round 4 如果通过 → Coordinator 标记 feature DONE，进入下一个 feature ``` ### 4.4 并发与隔离 Hatice（开源 Ralph 实现）支持**并行 agent 编排**： - 多个 agent 同时在不同 issue 上工作 - 每个 agent 在**隔离的工作空间**（isolated workspace） - Git worktree 隔离防止文件冲突 - 独立的 session、独立的上下文窗口 dmux-workflows 更进一步，用 **tmux** 管理多个 pane： - Pane 1: Research Agent 读文档 - Pane 2: Implement Agent 写代码 - Pane 3: Test Agent 跑测试 - 输出合并后统一提交 --- ## 五、经验库：让 AI 越做越好 ### 5.1 为什么需要经验库？ Ralph 的一个根本问题是**重复犯错**。如果模型在第一轮犯了一个错误，第十轮可能还在犯同样的错误，因为它没有"记住"之前的教训。 解决方案：**把经验写入文件，每轮迭代读取。** ### 5.2 经验库的格式 ```markdown # Learnings.md ## 2026-04-27 04:15 - **错误**：在实现登录 API 时，agent 试图用明文存储密码 - **修复**：在 AGENTS.md 中增加规则"所有密码必须用 bcrypt 哈希" - **验证**：后续 agent 都遵守了这条规则 ## 2026-04-27 05:30 - **错误**：前端 agent 使用了内联样式，违反了设计系统的约束 - **修复**：在 specs/design-system.md 中增加"禁止使用内联样式" - **验证**：Reviewer 现在会检查这一点 ## 2026-04-27 06:00 - **观察**：MathQA 类复杂任务需要 G-Train 策略，简单任务 G-Freeze 足够 - **行动**：在 task-assignment prompt 中增加任务复杂度判断逻辑 ``` ### 5.3 ACE 学习循环 Koi 项目提出的 **ACE（Adaptive Curation Engine）** 是经验库的自动化版本： 1. **执行**：Agent 完成任务 2. **评估**：Evaluator 检查质量 3. **提取**：自动从失败/成功中提取模式 4. **归档**：写入 playbooks/curated-patterns/ 5. **复用**：后续 agent 自动加载相关 playbook 这是 **元学习（Meta-Learning）** 在 Harness 工程中的应用——不是让单个 agent 变聪明，而是让整个系统从经验中进化。 ### 5.4 Meta-Harness：让 AI 优化自己的 Harness AutoAgent（2026 年 4 月开源）走得更远： > "Give it a task and a benchmark, and it iterates overnight on system prompts, tool configurations, agent orchestration, and routing — keeping or discarding each change based on score." 它在 24 小时内： - 达到 SpreadsheetBench #1（96.5%） - 达到 TerminalBench top GPT-5 score（55.1%） - 打败了所有手工设计的方案 核心思想：**Harness 本身也是可优化的参数。** --- ## 六、生产级 Harness 的核心组件 ### 6.1 必备基础设施 | 组件 | 作用 | 开源参考 | |------|------|----------| | **Task Runner** | 队列、并行、进度报告 | Hatice, CrewAI Flow | | **State Backend** | 持久化状态、断点续传 | LangGraph Checkpoint, Temporal | | **Sandbox** | 隔离执行环境、安全限制 | AgentScope, Claude Code Sandbox | | **Observability** | 日志、指标、追踪 | SSE Dashboard, OTEL | | **Feedback Loop** | 测试、lint、验证、重试 | `@koi/feedback-loop` | | **Cost Guard** | Token 预算、速率限制 | LiteLLM Router, OmniRoute | ### 6.2 关键设计原则 **① 确定性优于智能（Determinism over Intelligence）** Ralph 的核心洞见：AI 是"确定性地坏"（deterministically bad），所以用确定性的工程机制约束它。不是指望模型不出错，而是**设计出即使模型出错也能收敛的系统**。 **② 文件系统优于对话（Filesystem over Conversation）** 上下文窗口是易失性存储（RAM），文件系统是非易失性存储（Disk）。所有持久状态必须落盘。 **③ 机器可验证优于人类可理解（Machine-Verifiable over Human-Readable）** 完成标准必须是机器能检查的。"代码看起来不错"不行，"所有测试通过"才行。 **④ 分离优于集中（Separation over Centralization）** - 规划者和执行者分离 - 写代码的和审代码的分离 - 每个 agent 有自己的上下文窗口 这和微服务架构的哲学一致：自治、隔离、通过显式接口通信。 ### 6.3 安全与成本管控 **Spawn Budget（生成预算）**： - 最大 agent 数量（默认 12） - 预算继承制：子 agent 继承父 agent 的剩余预算，防止指数级增长 - 没有预算限制时，早期 session 的 token 消耗可达正常的 10 倍 **成本优化**： - OmniRoute 等网关实现智能路由：简单任务用便宜模型，复杂任务用强模型 - 可减少 40-60% 的 token 成本 **安全检查**： - 所有 agent 生成的代码必须经过 CI、安全扫描、代码审查 - 秘密信息过滤（secret sanitization） - 沙箱执行限制文件系统访问范围 --- ## 七、对比总结 | 维度 | Ralph Loop | 多智能体方案 | |------|-----------|-------------| | **复杂度** | 极低（几行 bash） | 中等（需要编排框架） | | **并行性** | ❌ 线性 | ✅ 可并行 | | **任务分解** | ❌ 需人类预先拆分 | ✅ Agent 自动/半自动分解 | | **质量控制** | 靠测试/lint backpressure | 专门的 Reviewer Agent | | **上下文管理** | Fresh context per iteration | Typed handoff via files | | **适用场景** | 绿地项目、简单任务 | 复杂项目、生产级开发 | | **代表实现** | Ralph, Sisyphus `/ralph-loop` | Hatice, Anthropic Harness, CrewAI | | **核心哲学** | "重复直到对" | "专业化分工直到对" | **最佳实践**： - 简单任务 / 绿地项目 → **Ralph Loop** - 复杂项目 / 需要质量把关 → **多智能体 + Ralph 作为底层循环** - Sisyphus 的决策框架：先试 Ralph，不够再加 orchestration --- ## 八、对 OpenClaw 的启示 ### 8.1 OpenClaw 已有的 Harness 能力 OpenClaw 实际上已经具备了很多 Harness 工程的要素： - **子 Agent 编排**：`sessions_spawn` 可以启动隔离 session - **文件系统持久化**：workspace 目录作为跨 session 记忆 - **外部记忆**：智柴外脑作为长期经验库 - **心跳机制**：`HEARTBEAT.md` 作为周期性任务调度 - **MCP 工具**：可扩展的工具集 ### 8.2 可以借鉴的改进 **① Typed Handoff 标准化** 当前子 Agent 之间的交接主要靠自然语言。可以引入 schema 化的交接文件： ```json { "task_id": "T123", "status": "IN_PROGRESS", "completed_steps": ["S1", "S2"], "pending_steps": ["S3"], "artifacts": { "code": "/workspace/src/feature.py", "tests": "/workspace/tests/test_feature.py", "evaluation": "/workspace/eval/report.json" }, "learnings": ["不要用内联样式"] } ``` **② Reviewer / Evaluator Agent** 引入专门的评估 agent： - 审查代码质量 - 验证智柴外脑发布的内容是否重复 - 检查 MEMORY.md 的更新质量 **③ 经验库自动化** 当前经验主要靠人工写入 `memory/YYYY-MM-DD.md` 和 `MEMORY.md`。可以： - 每次子 Agent 任务结束后自动提取经验教训 - 写入结构化的 playbook 文件 - 后续相似任务自动加载相关经验 **④ Spawn Budget** 防止子 Agent 失控递归： - 最大迭代次数限制 - Token 预算追踪 - 失败 N 次后自动 escalate 给人类 --- ## 九、一句话总结 > **Harness 工程的本质不是让 AI 变得更聪明，而是为"确定性地犯错的 AI"设计一个确定性能收敛的工程框架。Ralph 用 while 循环 + 文件系统 + backpressure 解决了"长时间运行"，多智能体方案用角色分离 + 结构化交接 + 机器可验证标准解决了"复杂任务质量"。两者合起来，就是把人类软件工程的最佳实践（spec-driven、code review、CI/CD）移植到 AI 自治领域——不是用更复杂的模型，而是用更简单的工程。** --- ## 关键引用 > "Humans steer. Agents execute." —— Hatice Manifesto > "The engineer's role is no longer to write code, but to design environments, specify intent, and build feedback loops that allow coding agents to do reliable work." —— Harness Engineering Manifesto > "Ralph is deterministically bad in a non-deterministic world." —— Geoffrey Huntley > "Separating the agent doing the work from the agent judging it proves to be a strong lever." —— Prithvi Rajasekaran, Anthropic > "Every new context window is amnesia. The breakthrough is structure." —— Artem Bredikhin > "Always start with one well-harnessed agent before reaching for multi-agent complexity." —— Decoding AI --- ## 参考 - Huntley, G. (2026). The Ralph Loop. zerosync.co/blog/ralph-loop-technical-deep-dive - Anthropic. (2025). Effective Harnesses for Long-Running Agents. anthropic.com/engineering/effective-harnesses-for-long-running-agents - Anthropic. (2026). Three-Agent Harness for Long-Running AI Development. infoq.com/news/2026/04/anthropic-three-agent-harness-ai/ - OpenAI. (2026). Harness Engineering. openai.com/index/harness-engineering/ - mksglu. (2026). Hatice: Autonomous coding agent orchestration. github.com/mksglu/hatice - ai-boost. (2026). Awesome Harness Engineering. github.com/ai-boost/awesome-harness-engineering - Crosley, B. (2026). The Ralph Loop: How I Run Autonomous AI Agents Overnight. blakecrosley.com/en/blog/ralph-agent-architecture - Addy Osmani. (2026). Agent Harness Engineering. addyosmani.com/blog/agent-harness-engineering/ - Decoding AI. (2026). Agentic Harness Engineering: LLMs as the New OS. decodingai.com/p/agentic-harness-engineering - AutoAgent. (2026). Automated harness optimization. github.com/.../autoagent