📚 喵喵的笔记库

02-核心架构

14分钟阅读

核心架构

Harness 的本质是控制论系统——前馈（指引）+ 反馈（传感器）。Agent = Model + Harness + Tools。 前置 → 01-Harness是什么 | Spec 驱动 → 03-SDD与Spec驱动 | Skills → 04-Skills设计 | 实战 → 05-企业实战案例

Harness Engineering 核心组件

综合三家权威来源的原术语，不做二次命名。

权威来源

| 来源 | 文章 | |------|------| | Anthropic | Effective context engineering for AI agents · Effective harnesses for long-running agents · Harness design for long-running apps | | OpenAI | Harness engineering: leveraging Codex in an agent-first world | | Alex Lavaee | How to Harness Coding Agents with the Right Infrastructure — 明确定义 "Four Pillars" |

Four Pillars（Alex Lavaee / Anthropic 共识）

这四项是多个独立团队（OpenAI、Anthropic、Huntley、Horthy、Vasilopoulos）共同收敛的结论：

| Pillar | 原文 | 含义 | |--------|------|------| | Context Architecture | Anthropic: "Context Engineering" · Lavaee: "tiered, progressive disclosure" | 分层上下文、渐进式披露、CLAUDE.md / AGENTS.md | | Agent Specialization | Anthropic: "Initializer / Coding / Evaluator agents" · Lavaee: "scoped prompts and restricted tools" | 分角色 Agent，限定工具和职责范围 | | Persistent Memory | Anthropic: "structured artifacts to carry context across sessions" · Lavaee: "filesystem-backed, not conversation history" | 文件级跨 session 记忆，不是对话历史 | | Structured Execution | Anthropic: "decomposing the build into tractable chunks" · Lavaee: "research, plan, execute, verify" | 任务分解 + 增量执行 + 验证 |

OpenAI 补充组件

OpenAI 在百万行代码实验中额外强调：

| 组件 | 原文 | |------|------| | Feedback Loops | "build feedback loops that allow Codex agents to do reliable work" | | Architectural Guardrails | "strict dependency layers enforced through custom linters and structural tests" | | Observability-Driven Iteration | "agents leverage telemetry — logs, metrics, spans — to reproduce bugs and validate fixes autonomously" | | AGENTS.md as Living Constraint System | "a living constraint system updated iteratively whenever agents encounter failures" |

Anthropic 补充组件

| 组件 | 原文 | |------|------| | Context Resets | "clearing the context window entirely and starting a fresh agent, combined with a structured handoff" | | GAN-Inspired Evaluator | "a multi-agent structure with a generator and evaluator agent" | | Compaction | "intelligent eviction and summarization of the context window" |

社区补充

| 组件 | 来源 | |------|------| | MCP (Model Context Protocol) | Anthropic 推出的开放 JSON-RPC 标准，定义 Agent 如何调用工具 | | Skills / Progressive Disclosure | Claude Code 官方机制，按需加载知识避免上下文污染 | | Security & Guardrails | Claude Code sandbox/permissions、OpenAI linter enforcement |

🧠 我的心智模型

Agent 三层架构：

（例：Agent = 大脑（Model）+ 神经系统（Harness 编排层）+ 手脚（Tools）） ✍️ 你的理解：

[来源：Anthropic] Anthropic 的三 Agent 架构把 Harness 层拆得更细：Planner（规划者）→ Generator（生成者）→ Evaluator（评估者）。Planner 负责理解需求、拆解任务、制定 Sprint Contract；Generator 按合同写代码；Evaluator（通过 Playwright MCP 模拟用户操作）验证 Generator 的产出是否真正可用。这不是三个独立 Agent，而是一个反馈闭环——Evaluator 的发现会回流到 Planner 重新规划。

[来源：Anthropic] Sprint Contract 是这套架构的关键发明：spec 只定义高层意图，contract 把它填补到可测试的粒度。每个 sprint 是一个原子交付单元——不是"做完整个功能"，而是"完成一个可验证的切片"。这让长时间运行的 Agent 不会因为上下文腐烂而失控。

Workflow vs Agent：

（例：Workflow 是流水线，步骤固定；Agent 是员工，给目标自己想办法） ✍️ 你的理解：

[来源：Anthropic/deusyu] deusyu 的 Ralph Wiggum 循环把 Agent 推到极致：while true; do claude ... done——一个无限循环，Claude 写代码，测试不通过就继续修，通过了就下一个任务。六条信条：测试质量决定一切、为 Claude 设计（不打印大量无用输出）、Agent 角色专精、测试先行、快速反馈、相信循环。这不是 Workflow 也不是单次 Agent，而是一种新的编程范式——用循环替代手动干预。

前馈 vs 反馈：

（例：前馈是出发前给地图，反馈是到了之后看有没有走错） ✍️ 你的理解：

[来源：Anthropic] GAN 启发的生成器-评估器分离设计把前馈和反馈的关系具象化了：Generator 写代码（前馈——按 spec 和规则生成），Evaluator 验证代码（反馈——像用户一样点页面看效果）。两者的分离是关键——如果同一个 Agent 既写代码又自评，它会"自己骗自己"，默认通过有问题的实现。

🎯 核心问题

  1. Workflow 和 Agent 有什么本质区别？什么场景用 Workflow，什么场景用 Agent？
  2. Harness 层解决了什么问题？如果 Model 足够强，Harness 还需要吗？
  3. Claude Code / OpenClaw 的架构里，Model、Harness、Tools 分别对应什么？
  4. 反压机制（Backpressure）的核心设计原则是什么？

📝 我的理解

Agent 架构

✍️

[来源：综合] Harness 可以拆解为五大子系统：Instructions（指令层——AGENTS.md、Skills、系统提示）、State（状态层——跨会话记忆、上下文压缩、文件级持久化）、Verification（验证层——测试、linter、浏览器自动化、Evaluator Agent）、Scope（范围层——工具权限、文件访问边界、Sub-agent 隔离）、Lifecycle（生命周期层——Hooks、会话管理、Sprint Contract、上下文重置）。这五层共同构成了让 Agent 可靠运行的"操作系统"。

[来源：OpenAI] OpenAI 在百万行代码实验中总结了六大经验，本质上是对这五层的实证：(1) 仓库即记录系统——代码库本身是最可靠的知识载体；(2) 地图而非手册——AGENTS.md 当索引不当代码；(3) 智能体可读性——Agent 看不到的东西 = 不存在；(4) 规范架构——严格分层 + 自定义 linter 机械执行；(5) 吞吐量改变合并——Agent 产出量级变了，合并策略也要变；(6) 熵管理——"AI Slop"垃圾回收，Golden Principles 持续执行。

[来源：NLAHs 论文] NLAHs（Natural Language Agent Harnesses）论文提出了一个重要视角：Harness 是自然语言可执行工件。它不是传统意义上的"代码"，而是用自然语言编写的、可被 LLM 直接执行的程序。AGENTS.md 本质上就是一份用 Markdown 写的"可执行规范"——人能读，Agent 也能执行。这重新定义了"编程"的含义。

前馈与反馈

✍️

上下文管理

✍️

⚡ 我的实战

✍️ 我自己做过什么、踩过什么坑。

🔒 关书自测

  1. Anthropic 的「Building effective agents」里，Workflow 和 Agent 的区别是什么？各举一个适用场景。
  2. Harness 的核心循环（ReAct / Plan-Execute）两种模式的区别？
  3. 上下文腐烂（Context Rot）是什么？Harness 提供了哪些防线？
  4. 反压机制的三条设计原则是什么？

🎤 费曼输出

1 句话版本:✍️ 3 分钟版本:✍️ 信心:_/10 最可能翻车的地方:✍️

参考资料

设计原则

  • 分层机制：1 个 Router Agent + 多个 Sub-Agents，Router 负责将用户问题映射到对应的 Sub-Agent
  • Spec-first：先写规格说明，再让 Agent 实现
  • Anti-Fragile：处理边缘情况，要求生产级代码质量

Workflow vs Agent

来源：Anthropic「Building effective agents」

| 维度 | Workflow | Agent | |------|----------|-------| | 本质 | 预定义的步骤序列 | 给目标，自己想办法 | | 灵活性 | 低——走固定路线 | 高——按需决策 | | 可靠性 | 高——确定性执行 | 中——依赖模型判断 | | 适用 | 结构化任务（数据处理、CI/CD） | 开放式任务（编码、调试） |

实际中多数系统是混合的：Stripe 的蓝图中，确定性节点（linter、分支推送）+ Agent 循环节点（理解任务、写代码、修复失败）混合编排。

控制论框架（Birgitta Böckeler / Martin Fowler）

前馈（指引）：预测 Agent 行为，力求在行动前引导。

  • 推断型：AGENTS.md、Skills（语义引导）
  • 计算型：LSP、CLI、代码迁移工具（确定性引导）

反馈（传感器）：行动后观察，帮助自我纠正。

  • 计算型：ESLint、类型检查、测试覆盖率（确定性验证）
  • 推断型：AI 代码评审 Agent（语义验证）
  • 混合型：变异测试 + 质量评审

关键洞见：单独使用前馈或反馈都有问题。仅有反馈则 Agent 不断重蹈覆辙；仅有前馈则 Agent 编码了规则却无从验证是否生效。

反压机制（Backpressure）

来源：HumanLayer 团队实战经验。

什么是反压：让 Agent 在完成工作后能自动检验产出质量、不合格时被迫回头修正的反馈回路。

三条设计原则：

  1. 成功时静默——通过的测试不应向上下文注入任何信息。沉默就是最好的信号
  2. 失败时精准——只暴露错误信息，且包含修复指引
  3. 运行要快——超过 5 分钟的反馈失去在 Agent 循环中嵌入的价值

公式：好的反压 = 快速 + 静默成功 + 精准失败

上下文腐烂的三重防线

来源：Vivek Trivedy、Claude Code 源码分析

  1. 上下文压缩（Compaction）：智能卸载并总结现有的上下文窗口，使 Agent 能够继续工作
  2. 工具调用输出卸载：保留超出 token 阈值的工具输出头尾，完整输出卸载到文件系统
  3. Skills 渐进式披露：避免启动时加载过多工具描述，保护模型免受上下文腐烂侵害

从 LLM 到 Agent 的演进

| 阶段 | 能力 | Harness 需求 | |------|------|-------------| | LLM API（对话） | 一问一答 | 几乎不需要 | | RAG / 长上下文 | 检索增强 | 需要知识管理 | | 工具使用 | 执行操作 | 需要工具设计+权限 | | Agent（单次） | 自主规划执行 | 完整 Harness（提示+工具+反馈） | | Agent（长时间运行） | 跨会话持久工作 | + 记忆管理+上下文压缩+Sub-agents | | Agent 团队 | 多 Agent 协同 | + 编排协议+任务分解+合并策略 |

Agent 框架生态

| 框架 | 特点 | 适合场景 | |------|------|---------| | LangGraph | State Machine + Sub-agent 编排 | 复杂工作流 | | CrewAI | 多角色协作（Role/Goal/Backstory） | 多角色团队模拟 | | OpenAI Agents SDK | 与 Codex 深度集成 | OpenAI 生态 | | OpenClaw | 多渠道 + Skills + 多 Agent | 个人助手/多平台 | | OpenHarness | 43+ 工具、Skill 按需加载 | 研究/学术 |

Harness Engineering 核心资源（按优先级）

Tier 1：AI 实验室一手资料

Tier 2：学术论文

Tier 3：行业高影响力文章

实战文章

  1. 狠人揭秘ClaudeCode、Cursor、OpenAI智能体工程技术：模型几乎无关紧要，Harness就是一切！ ⭐⭐⭐ — 万字长文，覆盖 Harness 全貌：SWE-agent ACI 概念、Anthropic 双 Agent、OpenAI 百万行实验、7 层分类法、5 个重复设计模式
  2. Qoder 工程实践：Harness Engineering 指南 ⭐⭐⭐ — 验证管道、预验证机制、协调者/子代理分层、交叉 Review、自进化机制、三种记忆
  3. Meta-Harness：斯坦福让 harness 实现自我改进 — 让 AI 自己设计 Harness，TerminalBench-2 上自动发现超过人工调优
  4. AI编程王炸组合：OpenSpec+Superpowers+Harness 三剑客 — OpenSpec（规范驱动）+ Superpowers（工程纪律）+ Harness（多Agent协同）

关系图谱

反向链接