介绍

欢迎阅读《AI Agent 技术博客》。本博客由 AI 生成，旨在深入探讨现代 AI Agent 的架构设计与最佳实践。

在这里，我们将通过 AI 架构师的视角，详细解析热门开源 AI Agent 的设计理念、实现细节以及实际应用场景。无论你是 AI 开发者、架构师还是技术爱好者，都能从中获得宝贵的见解和启发。

本博客的内容完全由 AI 生成，并明确标注了所使用的 AI 模型。我们希望通过这种方式，展示 AI 在技术写作领域的潜力，同时为读者提供高质量、深入浅出的技术分析。

我们将持续更新博客内容，欢迎大家关注并提出宝贵的意见和建议！

Claw Code 架构深度解析：AI Agent 系统设计的技术实践

Generated by AI | Date: 2026-04-02 Source: https://github.com/ultraworkers/claw-code

架构全景图

graph TB
    subgraph UI["USER INTERFACE LAYER"]
        CLI["CLI Entry"]
        Server["Server (SSE)"]
        LSP["LSP Client"]
        REPL["REPL Mode"]
    end

    subgraph Core["CORE RUNTIME ENGINE"]
        Runtime["ConversationRuntime<C: ApiClient, T: ToolExecutor>"]
        Session["Session Manager"]
        Permission["Permission Policy"]
        HookRunner["Hook Runner"]
    end

    subgraph Ext["EXTENSION LAYER"]
        Registry["Tool Registry"]
        Provider["Provider Abstraction"]
        MCP["MCP Servers"]
        Plugins["Plugins"]
    end

    subgraph Infra["INFRASTRUCTURE"]
        Claude["Claude API"]
        XAI["xAI (Grok)"]
        OpenAI["OpenAI API"]
    end

    CLI & Server & LSP & REPL --> Runtime
    Runtime --> Session & Permission & HookRunner
    Runtime --> Registry & Provider
    Registry --> MCP & Plugins
    Provider --> Claude & XAI & OpenAI

一、项目背景与定位

Claw Code 是一款面向开发者的高级 AI 编程 Agent，其核心定位是 “Better Harness Tools, not merely storing the archive”（更好的工具 harness，而非仅仅存储归档代码）。

1.1 技术演进

1.2 为什么选择 Rust？

二、核心设计模式深度解析

2.1 对话运行时 — 依赖倒置原则的极致实践

AI 架构师视角：为什么选择 Trait 泛型？

传统 AI Agent 系统通常将 API 客户端、工具执行器硬编码在运行时中，导致更换 AI 提供商需要修改核心代码，单元测试难以 mock 外部依赖。

Claw Code 通过 Trait 抽象实现了运行时与具体实现的完全解耦：

classDiagram
    class ApiClient {
        <<trait>>
        +stream(request) Result~Vec~AssistantEvent~~
        +send(request) Result~AssistantResponse~
    }

    class ToolExecutor {
        <<trait>>
        +execute(tool, input) Result~String~
        +list_tools() Vec~ToolSpec~
    }

    class ClawApiClient { }
    class XaiClient { }
    class OpenAiClient { }
    class LocalToolExecutor { }

    ApiClient <|.. ClawApiClient
    ApiClient <|.. XaiClient
    ApiClient <|.. OpenAiClient
    ToolExecutor <|.. LocalToolExecutor

设计收益：

• ✅ 高度可测试性（Mock 客户端注入）
• ✅ 零厂商锁定（任何实现 ApiClient 的客户端可用）
• ✅ 组合自由（运行时可以动态选择客户端）

权衡取舍：

• ⚠️ 编译期复杂度增加
• ⚠️ 需要理解 Rust Trait 系统

场景化讲解：多提供商工作流

假设用户要求 Claw Code 使用 Claude 生成代码骨架，然后使用 GPT-4 进行代码审查，最后使用 Grok 生成文档：

#![allow(unused)]
fn main() {
// 初始化运行时（注入具体实现）
let runtime = ConversationRuntime::new(
    ClawApiClient::new("claude-opus-4-6"),
    LocalToolExecutor::new(),
    PermissionPolicy::default()
);

// 执行工作流 — 代码无需修改，运行时自动选择正确的 Provider
for step in workflow.steps() {
    runtime.execute_step(step).await?;
}
}

2.2 工具系统 — 分层架构的工程美学

AI 架构师视角：三层架构的模块化设计

graph TB
    subgraph L3["GlobalToolRegistry (Layer 3)"]
        GTR["统一入口 · 聚合分发"]
    end

    subgraph L2["mvp_tool_specs (Layer 2)"]
        bash["bash"]
        read["read_file"]
        write["write_file"]
    end

    subgraph L1["PluginTool (Layer 1)"]
        MCP["MCP Servers"]
        Ent["企业插件"]
    end

    GTR --> L2
    GTR --> L1

场景化讲解：企业工具治理

#![allow(unused)]
fn main() {
// 企业工具配置示例
let registry = GlobalToolRegistry::new();

// 设置工具可见性策略（白名单模式）
registry.set_visibility_policy(VisibilityPolicy::Whitelist(vec![
    "read_file", "write_file", "grep", "glob",
]));

// 工具调用拦截
registry.on_tool_call(|tool_name, input| {
    audit_logger.log(tool_name, input)?;
    security_check(tool_name)?;
    Ok(())
});
}

2.3 权限模型 — 零信任架构的实践

AI 架构师视角：精细化权限控制

stateDiagram-v2
    [*] --> ReadOnly
    ReadOnly --> WorkspaceWrite : upgrade
    WorkspaceWrite --> DangerFullAccess : upgrade
    DangerFullAccess --> Prompt : audit mode
    Prompt --> DangerFullAccess : allow once
    Prompt --> [*] : deny

    state DangerFullAccess {
        [*] --> AllowAll
        AllowAll --> [*]
    }

    state Prompt {
        [*] --> ConfirmDialog
        ConfirmDialog --> AllowOnce : Allow
        ConfirmDialog --> Deny : Deny
    }

权限级别：

场景化讲解：多环境权限配置

# 开发环境
permission_mode: DangerFullAccess

# 审计环境
permission_mode: Prompt
audit_enabled: true
require_reason: true

# 生产环境
permission_mode: ReadOnly
allowed_tools: [read_file, glob, grep]

2.4 Hook 系统 — 责任链模式的优雅实现

AI 架构师视角：开放-封闭原则的实践

Hook 系统允许开发者在不修改核心代码的情况下拦截和修改 Agent 的行为：

flowchart TD
    Start["用户请求"] --> Pre["PreToolUse Hooks"]
    Pre -->|denied| Deny["返回错误"]
    Pre -->|allowed| Exec["Tool Executor"]
    Exec --> Post["PostToolUse Hooks"]
    Post --> Result["返回结果"]

    subgraph Hooks["Hook 类型"]
        S["🔐 安全检查"]
        V["✅ 输入验证"]
        A["📝 审计日志"]
        C["💰 成本控制"]
    end

    Pre --> S & V
    Post --> A & C

场景化讲解：企业级 Hook 应用

#!/bin/bash
# hooks/pre_check.sh — 执行前安全检查
DANGEROUS_PATTERNS=("rm -rf /" "curl.*\|.*sh" ":(){:|:&}:")

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if echo "$COMMAND" | grep -qE "$pattern"; then
        echo "SECURITY_ALERT: Dangerous pattern detected"
        exit 1  # 阻止执行
    fi
done

2.5 多提供商支持 — 消除厂商锁定

AI 架构师视角：Provider 抽象

场景化讲解：智能成本优化

#![allow(unused)]
fn main() {
pub fn select_model(&self, task: &Task) -> String {
    match self.estimate_complexity(task) {
        Complexity::Trivial => self.select_cheapest(&["gpt-4o-mini", "claude-haiku"]),
        Complexity::Simple => self.select_fastest(&["gpt-4o", "claude-sonnet"]),
        Complexity::Medium => self.select_balanced(&["gpt-4-turbo", "claude-opus"]),
        Complexity::Complex => self.select_smartest(&["claude-opus-4", "grok-3"]),
    }
}
}

2.6 MCP 集成 — 生态连接的标准化

AI 架构师视角：协议化的生态连接

graph TB
    Client["Claw Code (MCP Client)"]
    Client --> DB["📊 Database"]
    Client --> Search["🔍 Search"]
    Client --> VCS["📦 Version Control"]
    Client --> Custom["🔧 Custom"]

    subgraph Config["连接类型"]
        Stdio["Stdio (本地进程)"]
        SSE["SSE (远程服务)"]
        WS["WebSocket (实时)"]
    end

场景化讲解：企业 MCP 配置

mcp_servers:
  - name: "enterprise-docs"
    type: "sse"
    url: "https://docs.internal.company.com/mcp"

  - name: "jira"
    type: "stdio"
    command: "npx @company/jira-mcp"

2.7 会话压缩 — 有限上下文的无限策略

AI 架构师视角：智能上下文管理

当上下文接近 token 限制时，系统自动压缩历史会话：

压缩策略：

1. 评估当前 token 使用量
2. 判断是否需要压缩
3. 生成智能摘要（保留工具调用、错误信息）
4. 保留最近 N 条消息完整

场景化讲解：大型重构项目

压缩后摘要示例：
───────────────────────────────────────────────
<summary>
Conversation summary:
- Phase 1: 分析了 45 个文件，识别出 4 个模块
- Phase 2: 创建了 auth-service/(12 文件), billing-service/(8 文件)
- Phase 3: 12 个单元测试通过，3 个集成测试失败
- 当前重点：修复 billing-service 中的 auth token 验证
</summary>
───────────────────────────────────────────────

2.8 插件系统 — 企业级扩展的基石

stateDiagram-v2
    [*] --> Discover
    Discover --> Validate : 发现插件
    Validate --> Install : 签名验证
    Install --> Init : 复制到目录
    Init --> Running : 执行 Setup
    Running --> Unload : 卸载请求
    Unload --> [*] : 清理资源

    state Running {
        [*] --> Active
        Active --> Hook : Hook Event
        Hook --> Active
    }

三、Slash 命令系统

采用声明式命令注册，使得命令系统可扩展、可测试、可文档化：

#![allow(unused)]
fn main() {
const SLASH_COMMAND_SPECS: &[SlashCommandSpec] = &[
    SlashCommandSpec { name: "help", aliases: &["h", "?"], ... },
    SlashCommandSpec { name: "compact", aliases: &["compress"], ... },
    SlashCommandSpec { name: "branch", aliases: &["branches"], category: Git, ... },
    SlashCommandSpec { name: "test", ... },
    SlashCommandSpec { name: "build", ... },
    // ... 20+ 命令
];
}

四、项目上下文发现

系统会自动发现项目根目录的配置文件：

五、关键设计启示

1. Trait 泛型解耦 — 运行时与具体实现完全解耦，便于测试和替换
2. 分层架构 — GlobalToolRegistry → mvp_tool_specs → PluginTool
3. 权限安全模型 — 分级权限控制，运行时权限提升需要确认
4. Hook 拦截机制 — PreToolUse/PostToolUse 支持安全和审计需求

六、与其他主流框架的对比

七、潜在的演进方向

7.1 多 Agent 协作

从单 Agent 演进出 Agent 池：CodeAgent（生成代码）、TestAgent（运行测试）、DocsAgent（编写文档）。

7.2 增量编译集成

与 watchman、rust-analyzer 集成，实现文件变化自动检测和增量编译验证。

7.3 云原生部署

支持远程运行（Server 模式）、WebSocket 实时协作、分布式任务队列。

八、总结

Claw Code 展示了构建企业级 AI Agent 系统的完整技术栈：

1. 运行时架构：基于 Trait 的泛型设计，实现高度解耦
2. 安全模型：分层的权限控制和 Hook 拦截机制
3. 扩展性：插件系统和 MCP 协议支持
4. 工程实践：Rust 实现的性能与内存安全保证
5. 开发者体验：Slash 命令、CLAW.md 项目上下文、REPL 交互

作为 AI 架构师，我认为 Claw Code 最值得学习的地方在于：

• 抽象层次的选择：Trait 抽象在灵活性和复杂度之间取得了良好的平衡
• 安全优先的设计：默认危险模式，让开发者意识到安全风险
• 生态连接的开放性：MCP 支持使其能够融入更大的 AI 工具生态

参考来源：https://github.com/ultraworkers/claw-code

Agent Harness 架构深度解析：AI Agent 系统的核心基础设施

Generated by AI | Date: 2026-04-02 Source: https://contextua.dev/why-agent-harness-architecture-important/

架构全景图

graph TB
    subgraph External["EXTERNAL LAYER"]
        User["User Input"]
        Tools["External Tools"]
    end

    subgraph Harness["AGENT HARNESS"]
        Direction["Direction & Constraints"]
        Safety["Safety & Permissions"]
        Memory["Memory & Context"]
        ToolsMgr["Tool Manager"]
    end

    subgraph LLM["LLM CORE"]
        Model["Foundation Model"]
    end

    User --> Harness
    Tools --> ToolsMgr
    Harness --> Direction
    Direction --> Model
    Safety --> Model
    Memory --> Model
    ToolsMgr --> Model
    Model --> Harness

一、问题起源：为什么需要 Harness？

1.1 行业认知转变

2026 年，AI 行业经历了一次根本性认知转变：

架构师视角：这条洞察揭示了一个深刻事实 —— AI Agent 的可靠性瓶颈不在于模型本身，而在于 包裹模型的执行环境。就像一台高性能发动机需要精密的变速箱和传动系统，强大的模型也需要精心设计的 harness 才能在复杂任务中可靠运行。

1.2 两个相同的模型，不同的结果

场景：重构遗留代码库

给两个相同的 GPT-4.5 模型相同的任务：“重构这个 10 万行的遗留 Python 项目，采用领域驱动设计。”

• Agent A（无专业 harness）：产出 40% 可用代码，陷入死循环 3 次，产生 23 个冲突的修改
• Agent B（专业 harness）：产出 92% 可用代码，2 小时内完成，无冲突

问题：为什么同样的模型产生了截然不同的结果？

答案：Agent B 的 harness 提供了：

• 结构化的任务分解机制
• 上下文管理（避免陷入局部）
• 增量验证（每步检查）
• 状态回滚能力

二、Agent Harness 的定义与边界

2.1 什么是 Agent Harness？

架构师视角：如果把 AI 模型比作“大脑“，那么 Harness 就是这个大脑的“颅骨、神经系统和工作记忆“。它决定了模型如何感知、如何行动、如何保持一致性。

Agent Harness = 模型之外的一切
                = 意图捕捉 → 规范编译 → 执行 → 验证 → 持久化

2.2 Harness vs Prompt Engineering vs Context Engineering

架构师视角：这三个层次是包含关系。Prompt Engineering 是微观层面，Context Engineering 是中观层面，而 Agent Harness 是宏观架构层面。Harness Engineering 正是 2026 年兴起的新学科，它不是要取代前两者，而是为它们提供系统性的运行环境。

三、Agent Harness 的五大支柱

3.1 工具调用系统（Tool Calling System）

架构师视角：工具调用是 Agent 与外部世界交互的唯一通道。工具系统的设计直接影响 Agent 的能力边界和可靠性。

核心问题：

• 如何让模型知道有哪些工具可用？
• 如何保证工具调用的正确性？
• 如何处理工具执行失败？

场景：代码重构任务

# 工具定义示例
ToolSpec {
    name: "read_file",
    description: "Read file contents with line numbers",
    input_schema: {
        "path": "string",
        "offset": "integer (optional)",
        "limit": "integer (optional)"
    },
    required_permission: "ReadOnly"
}

ToolSpec {
    name: "bash",
    description: "Execute shell command",
    input_schema: {
        "command": "string",
        "timeout": "integer (optional)"
    },
    required_permission: "DangerFullAccess"
}

设计决策：采用 声明式工具规范 而非运行时发现

• 权衡：获得 X = 工具定义可预测、可版本化；付出 Y = 需要预定义所有工具
• 替代方案：动态发现工具 —— 看似灵活，但导致不可预测性和安全风险

Claude Code 的 Deferred Loading 机制：

graph LR
    A["Tool Name Only"] -->|消耗少量 tokens| B["First Use"]
    B -->|按需加载完整定义| C["Full Schema"]
    C -->|缓存在内存| D["Subsequent Uses"]

这意味着：

• 默认只传递工具名称，不传递完整 schema
• 首次使用时才加载完整定义
• 大幅减少 context 开销

3.2 上下文管理系统（Context Management System）

架构师视角：上下文是 Agent 的“工作记忆“。与人类的工作记忆一样，它容量有限，且需要主动管理才能保持效率。上下文管理的失败是 Agent 系统最常见的故障模式。

核心问题：

• 有限的 context window 如何支持无限的任务？
• 如何在压缩历史信息的同时保留关键状态？
• 如何在多轮交互中保持上下文连贯性？

场景：为期一周的重构项目

用户要求 Agent 完成一个大型重构任务，预计需要 5 天，涉及 200+ 轮交互。

问题：

• 第 1 天：context 累积了 50,000 tokens
• 第 3 天：context 达到 180,000 tokens（接近限制）
• 第 5 天：Agent 忘记了最初的目标和关键设计决策

解决方案：四级压缩体系

stateDiagram-v2
    [*] --> Normal
    Normal --> MicroCompact: 特定消息过长
    Normal --> AutoCompact: 70% window 使用率
    AutoCompact --> SessionMemory: 90% window 使用率
    SessionMemory --> Reactive: 最后 10% 空间
    MicroCompact --> Normal
    AutoCompact --> Normal
    SessionMemory --> Normal
    Reactive --> Normal

架构师视角：Claude Code 的四级压缩体系展示了一个关键原则 —— 压缩应该是渐进的、可配置的，而非突发性的。最坏的设计是等到 context 满了才压缩，这会导致信息丢失和用户体验下降。

Instant Compaction 模式：

# 后台线程主动构建会话记忆
background_status = "initializing" if self.session_memory is None else "updating"

def _create_session_memory(self, messages: list[dict]) -> str:
    # 当 soft threshold 达到时，后台生成摘要
    compaction_messages = [{"role": "user", "content": SESSION_MEMORY_PROMPT}]
    return model.generate(compaction_messages)

这使得压缩是即时的，用户永远不需要等待。

3.3 错误恢复系统（Error Recovery System）

架构师视角：错误恢复是区分“概念验证“和“生产系统“的关键。在 Agent 系统中，错误处理不仅仅是 try-catch，而是涉及整个执行流程的容错设计。

核心问题：

• 工具执行失败后 Agent 应该怎么做？
• 如何避免 Agent 在错误方向上越走越远？
• 何时应该回滚状态，何时应该继续尝试？

场景：网络请求失败

graph TD
    A["Execute Tool: API Call"] --> B{Success?}
    B -->|Yes| C["Continue"]
    B -->|No| D{Retry Count < 3?}
    D -->|Yes| E["Wait 2s"]
    E --> A
    D -->|No| F{Human Recoverable?}
    F -->|Yes| G["Ask Human"]
    F -->|No| H["Abort with Context"]

关键设计：Checkpoint + Rollback

# 每个检查点保存状态快照
checkpoint = {
    "turn": 15,
    "context_summary": "已完成模块 A 和 B 的重构",
    "pending_changes": ["src/auth/*", "src/payment/*"],
    "verified_files": ["tests/test_a.py"]
}

# 失败时恢复到检查点
def rollback_to_checkpoint(checkpoint):
    restore_context_summary(checkpoint["context_summary"])
    discard_pending_changes()
    replay_verification(checkpoint["verified_files"])

架构师视角：Rollback 机制的核心洞察是 —— Agent 应该保守地前进，激进地回退。当不确定时，宁可回到已知的良好状态，也不要在错误的基础上继续构建。

3.4 状态持久化系统（State Persistence System）

架构师视角：真实世界的任务往往跨越多个会话。用户周一开始的重构任务，周五可能还需要继续。如果 Agent 每次启动都是“空白大脑“，生产效率将大幅下降。

核心问题：

• 如何在会话之间保持 Agent 状态？
• 如何处理长时间运行的任务？
• 如何支持会话的暂停和恢复？

场景：跨会话的大型重构

用户周一下午开始一个涉及 20 个微服务的重构，进行了 3 小时。周二早上回来继续工作。

Claude Code 的持久化方案：

graph TB
    subgraph Session1["Monday Session"]
        A1["Start: 8,700 tokens overhead"]
        B1["Add: project context, tools, history"]
        C1["Session ends at 95% capacity"]
    end

    subgraph Compaction["Auto Compaction"]
        D["Generate Session Summary"]
        E["Preserve: goals, completed work, errors"]
        F["Discard: redundant context"]
    end

    subgraph Session2["Tuesday Session"]
        G1["Resume: load session summary"]
        H1["Add: CLAUDE.md conventions"]
        I1["Continue with fresh context"]
    end

    C1 --> D
    E --> G1

会话记忆的关键要素：

## Session Memory Template

### Completed Work
- 模块 A 的重构完成（周一）
- 测试覆盖率从 60% 提升到 85%

### Active Work
- 正在进行模块 B 的数据库迁移
- 遇到问题：外键约束冲突

### Key Decisions
- 采用事件溯源模式
- 使用 PostgreSQL 而非 MongoDB

### User Intent
- 本周目标：完成 20 个微服务的领域驱动设计重构

3.5 权限与安全系统（Permission & Safety System）

架构师视角：Agent 可以在真实环境中执行操作这一事实，使其成为一个潜在的风险系统。权限系统的设计必须在可用性和安全性之间找到精确的平衡 —— 过于严格会让 Agent 无法工作，过于宽松会造成灾难性后果。

核心问题：

• 如何防止 Agent 执行危险操作？
• 如何在效率和安全之间取得平衡？
• 如何让用户对 Agent 的行为保持信心？

场景：执行删除操作

graph TD
    A["Agent: rm -rf /src/legacy"] --> B{User Permission Level}
    B -->|ReadOnly| C["BLOCK: Insufficient permissions"]
    B -->|WorkspaceWrite| D{Path in Workspace?}
    D -->|Yes| E["PROMPT: Confirm deletion?"]
    D -->|No| F["BLOCK: Path outside workspace"]
    E -->|Yes| G["ALLOW"]
    E -->|No| H["BLOCK: Denied by user"]
    B -->|DangerFullAccess| I["ALLOW (with warning logged)"]

权限分级模型：

#![allow(unused)]
fn main() {
pub enum PermissionMode {
    ReadOnly,           // 只能读取文件
    WorkspaceWrite,     // 可以在工作区写入
    DangerFullAccess,   // 可以执行任何操作（含危险命令）
    Prompt,             // 每次操作前询问
    Allow,              // 允许所有（不推荐）
}
}

架构师视角：最关键的设计决策是 “默认拒绝，显式允许” 原则。在安全系统中，永远不应该有“Allow All“作为默认选项。DangerFullAccess 应该是一个明确的、用户主动选择的模式，而不是默认状态。

四、Hook 系统：可扩展性的核心

4.1 Hook 架构设计

架构师视角：Hook 系统是 Agent Harness 的“插件机制“。它允许在不修改核心代码的情况下，改变 Agent 的行为。这是一种控制反转（IoC） 的实现 —— 不是 Agent 控制何时调用什么，而是 Harness 控制在何时、以何种方式干预 Agent 的执行。

核心概念：

graph TD
    A["Agent Loop"] --> B["Hook Manager"]
    B --> C["PreToolUse Hook"]
    B --> D["PostToolUse Hook"]
    B --> E["OnError Hook"]
    B --> F["PreResponse Hook"]

    C -->|Allow| G["Execute Tool"]
    C -->|Deny| H["Block & Log"]
    D -->|Modify| I["Transform Output"]
    D -->|Error| J["Trigger Recovery"]

4.2 Hook 的实际应用场景

场景 1：自动代码检查

{
  "hooks": {
    "PreToolUse": [
      {
        "match": {"tool": "Bash"},
        "type": "command",
        "command": "echo 'Checking if tests pass before commit...'"
      }
    ],
    "PostToolUse": [
      {
        "match": {"tool": "Write", "path": "*.py"},
        "type": "command",
        "command": "ruff check {path} --fix"
      }
    ]
  }
}

场景 2：架构合规检查

{
  "hooks": {
    "PreToolUse": [
      {
        "match": {"tool": "Edit", "path": "**/domain/*.py"},
        "type": "agent",
        "agent": "architect-review",
        "prompt": "Verify this edit follows DDD principles: {input}"
      }
    ]
  }
}

架构师视角：Hook 的强大之处在于它的组合性。通过组合 PreToolUse、PostToolUse、OnError 等多种 Hook，可以构建复杂的治理逻辑，而无需修改 Agent 本身。这与 Web 开发中的中间件模式有异曲同工之妙。

五、Subagent 与多代理系统

5.1 何时需要 Subagent？

架构师视角：Subagent 是解决“context 爆炸“问题的关键策略。当主 Agent 的 context 接近饱和时，将任务委托给 Subagent，让它在独立的上下文中工作，主 Agent 只保留协调者的角色。

场景：大型代码库探索

graph TB
    subgraph Main["Main Agent"]
        A["Orchestrator"]
    end

    subgraph Subagents["Parallel Subagents"]
        B["explorer-1: src/auth"]
        C["explorer-2: src/payment"]
        D["explorer-3: src/orders"]
    end

    subgraph Results["Consolidated Results"]
        E["Combined Analysis"]
    end

    A -->|探索请求| B
    A -->|探索请求| C
    A -->|探索请求| D
    B -->|发现| E
    C -->|发现| E
    D -->|发现| E
    E -->|汇总报告| A

关键设计原则：

1. 隔离的上下文：每个 Subagent 有自己的 context window
2. 共享的技能：Subagent 可以访问主 Agent 的技能定义
3. 结构化通信：Subagent 通过结构化格式返回结果
4. 缓存优化：共享的 system prompt 只需要加载一次

5.2 Agent Spawning 架构

# Subagent 配置
AgentConfig {
    description: "Architecture Reviewer",
    prompt: "You are an architecture expert...",
    tools: ["Read", "Grep", "Glob", "Agent"],
    disallowed_tools: ["Bash", "Write"],
    model: "claude-sonnet-4-20250514",
    permission_mode: "ReadOnly",
    max_turns: 20
}

架构师视角：Subagent 的设计揭示了一个重要的系统设计原则 —— 任务分解 + 独立执行 + 结果聚合。这与函数式编程中的 map-reduce 模式有相似之处。关键的权衡是：

• 获得：水平扩展能力，独立处理多个任务
• 付出：协调复杂性，结果聚合可能丢失信息

六、主流 Agent 的 Harness 实现对比

架构师视角：从对比可以看出，Claude Code 在 Harness 层面提供了最完整的设计。这不是偶然的 —— 它反映了 Anthropic 对 Agent 系统可靠性的深刻理解。特别是 deferred tool loading 和 四级压缩体系，是其他系统尚未充分解决的难题。

七、MCP：工具发现的标准化

7.1 为什么需要 MCP？

架构师视角：MCP（Model Context Protocol）的出现解决了一个根本性问题 —— AI 模型与工具之间缺乏标准化的连接协议。在没有 MCP 之前，每个 Agent 系统都需要为每个工具编写定制化的集成代码，导致：

• 工具不可移植
• 集成成本高昂
• 安全模型不一致

7.2 MCP 架构

graph TB
    subgraph ClaudeCode["Claude Code"]
        MC["MCP Client"]
    end

    subgraph Servers["MCP Servers"]
        File["Filesystem Server"]
        Git["Git Server"]
        DB["Database Server"]
    end

    MC -->|stdio| File
    MC -->|stdio| Git
    MC -->|SSE| DB

    MC -->|Tool Request| File
    MC -->|Tool Request| Git
    MC -->|Tool Request| DB

MCP 服务器配置示例：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    },
    "git": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git"]
    },
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp"
    }
  }
}

八、设计模式总结

8.1 核心设计模式

8.2 每个模式的权衡

Progressive Compaction vs Full Summarization：

• Progressive：计算成本高，但信息保留更完整
• Full：计算成本低，但可能丢失细节

Deferred Loading vs Eager Loading：

• Deferred：初始 context 小，但首次工具使用有延迟
• Eager：无首次使用延迟，但初始 context 大

Permission Pipeline vs Single Check：

• Pipeline：更安全，但性能略低
• Single：更快，但安全性较低

九、未来展望

9.1 当前瓶颈

1. Context 仍然有限：200K tokens 对于真正的长时间任务仍然不够
2. 压缩仍有信息丢失：即使是最好的压缩也会丢失细节
3. 多代理协调困难：Subagent 之间的通信仍然脆弱
4. 安全边界模糊：Hook 系统可能被恶意利用

9.2 未来方向

总结

Agent Harness 是 2026 年 AI Agent 系统的核心基础设施。它不是一个单一的技术组件，而是由五大支柱组成的复杂系统：

1. 工具调用系统 — Agent 与世界交互的通道
2. 上下文管理系统 — 有限资源下的高效利用
3. 错误恢复系统 — 生产环境必需的可靠性保障
4. 状态持久化系统 — 跨会话的连续性
5. 权限与安全系统 — 防止灾难性后果

关键洞察：

• “Agents aren’t hard; the Harness is hard” — OpenAI Codex 团队
• 模型是引擎，Harness 是变速箱和传动系统
• 可靠性瓶颈不在于模型能力，而在于执行环境

实践建议：

1. 构建 Agent 系统时，先设计 Harness，再选择模型
2. 采用渐进式压缩，而非等到 context 满了才处理
3. 实现 Hook 系统，为未来的扩展预留空间
4. 采用“默认拒绝“的权限模型
5. 利用 MCP 标准化工具集成

参考资料：

• ContextUA: Why Agent Harness Architecture is Important
• NxCode: Harness Engineering Complete Guide 2026
• Epsilla: Why Harness Engineering Replaced Prompting in 2026
• Claude Code Official Documentation
• Penligent: Inside Claude Code Architecture
• OpenAI: Harness Engineering