第12章 OpenClaw / Harness 与 Agent 生产基础设施

📖 AI Agent 全栈学习课程 · 可运行讲义

1. 深入理解 OpenClaw 的 Gateway 中心化架构2. 掌握 AgentSkills 和 ClawHub 的插件生态3. 了解 OpenHarness 作为开源 TypeScript Agent SDK 的设计亮点4. 理解 Agent 生产基础设施的全景图(Tracing / 评测 / 安全 / 部署)5. 学会设计可复用的 Agent 评测 Harness🎤 OpenClaw 和 Claude Code 的架构差异?🎤 什么是 Agent 的 Gateway 架构?有什么优势?🎤 Agent 生产化的基础设施包括哪些?🎤 如何搭建 Agent 的评测体系?

 

内容核对:2026-08-01

说明:标注为模拟的实现与数值用于讲解概念,不代表真实 SDK、协议或基准结果。

 

 

 

 

12.1 Gateway 中心化架构 —— Agent 生产化设计模式

 

OpenClaw 是真实存在的开源、自托管 Agent Gateway,而不是本章虚构的名字。

官方文档:https://docs.openclaw.ai/

 

它把聊天渠道、Agent 会话、工具/Skills、自动化和管理控制集中到 Gateway。

以下内容用于解释这种架构模式;具体配置、支持的渠道和命令可能随版本变化,

使用时应以官方文档和已安装版本为准。

 

设计目标:

一个中心化的 Gateway(Node.js 控制平面),

统一管理多条消息渠道 + 多个 LLM Provider + 持久化记忆。

 

OpenClaw 的 Gateway 中心化架构:

 

│ │ │

┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐

│ Channel 1 │ │ Channel 2 │ │ Channel 3 │

│ WhatsApp │ │ Telegram │ │ Discord │

└─────────────┘ └─────────────┘ └─────────────┘

📊 架构示意

  ┌─────────────────────────────────────────────────────────┐
  │                    The Gateway                           │
  │                  (Node.js 控制平面)                       │
  │                                                          │
  │  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐  │
  │  │ 消息路由   │  │ 状态管理中心  │  │ 安全策略执行      │  │
  │  │          │  │              │  │                  │  │
  │  └──────────┘  └──────────────┘  └──────────────────┘  │
  │                                                          │
  │  ┌──────────────────────────────────────────────────┐  │
  │  │             LLM Provider Abstraction             │  │
  │  │   Claude | GPT | Gemini | Ollama | 任意兼容API    │  │
  │  └──────────────────────────────────────────────────┘  │
  │                                                          │
  │  ┌──────────────────────────────────────────────────┐  │
  │  │            Persistent Memory Store               │  │
  │  │         长期记忆 + 用户偏好 + 对话历史             │  │
  │  └──────────────────────────────────────────────────┘  │
  └─────────────────────────────────────────────────────────┘

 

Gateway 的职责:

  • 1. 消息路由:从不同 Channel 接收消息,路由到正确的 LLM Provider
  • 2. 状态管理:维护每个用户的对话状态和 Agent 运行状态
  • 3. 安全策略:权限控制、速率限制、内容过滤
  • 4. Provider 抽象:统一接口,可热切换底层 LLM
  •  

    Channel Integrations(消息渠道):

    OpenClaw 不是只能通过 CLI 交互,它可以接入:

  • WhatsApp
  • Telegram
  • Discord
  • Slack
  • iMessage
  • Web Chat
  •  

    Agent 在这些渠道上表现得像一个「真人」。

     

     

    12.2 OpenClaw 的 AgentSkills 和 ClawHub

     

    这是 OpenClaw 最具特色的设计。

     

    AgentSkills:

  • 类似 Node.js 的 npm 包
  • 社区可以开发、发布、安装 Agent 的「技能」
  • 每个 Skill 是一个独立的模块(含工具定义 + 实现)
  •  

    示例 Skill:

    skill/weather → 天气查询

    skill/calendar → 日历管理

    skill/email → 邮件发送

    skill/translation → 翻译服务

    skill/code-review → 代码审查

     

    ClawHub:

  • AgentSkills 的注册中心
  • 类似 npm registry 或 Docker Hub
  • 社区贡献和共享 Skill
  •  

    与 MCP 的关系:

  • MCP 定义了「协议」—— 如何连接和通信
  • AgentSkill 定义了「能力」—— 具体做什么
  • 一个 AgentSkill 可以通过 MCP 协议暴露给 LLM
  • 两者是协议层和功能层的关系
  •  

     

    12.2.1 Gateway 模式为什么适合 Agent?—— 工程取舍分析

     

    面试官问:「Agent 为什么用 Gateway 模式,不用微服务+API Gateway?」

     

    ▍ Gateway vs 微服务的核心差异

     

    传统微服务 → 每个服务独立部署、独立数据库、独立运维

    Agent 的 Gateway → 集中式控制平面 + 可插拔的 Channel/Provider/AgentSkill

     

    为什么 Agent 架构不适合微服务模式?

     

  • 1. 成本共享问题 —— Agent 的「状态」不是无状态的
  • 微服务推崇 stateless → 但 Agent 的对话上下文必须共享

    → 每个请求都重建上下文 = 前 20 条消息重新计费 = 成本爆炸

    → Gateway 模式下对话历史存在控制平面,无需跨服务传递

     

  • 2. LLM Provider 的切换频率 —— 应该是运行时切换,不是部署时
  • 微服务要换模型 → 改代码 → 重新部署 → 全量回归测试

    Gateway 换模型 → /model gpt-5.6-sol → 即刻生效,零部署

     

  • 3. AgentSkill 的安装卸载 —— 需要运行时热插拔
  • 微服务下装新 Skill → 部署新服务 → 配 Service Discovery

    Gateway 下装新 Skill → install agent-skill/weather → 即刻生效

     

    ▍ Gateway 模式的设计取舍(面试可以主动分析)

     

    优点:集中式状态管理、运行时热切换 Provider/模型、单点安全审计

    代价:Gateway 成为单点瓶颈(需要水平扩展 + 队列)

    解决:Gateway 本身可以是多实例 + 共享存储的

     

    类比:Gateway 模式像「OS 内核」—— 管理所有资源,

    但允许动态加载驱动(AgentSkill)和切换硬件(LLM Provider)

     

     

    12.3 OpenHarness —— 可嵌入应用的 TypeScript Agent SDK

     

    OpenHarness 也是真实开源项目。它的定位是 code-first TypeScript SDK,

    不是本章旧版描述中的虚构 CLI 编码 Agent。

    官方文档:https://docs.open-harness.dev/

     

    核心抽象:

  • Agent:模型、指令、工具和运行策略
  • Session:保存一段 Agent 交互及其事件
  • Event stream:应用可逐事件渲染文本、工具调用和状态
  • Middleware:承载压缩、重试、持久化、hook 等横切能力
  • Integrations:MCP、Skills、Subagents、Shell/Filesystem 工具和前端辅助
  •  

    最小使用形态(结构示意,安装时检查当前包名与 API):

     

    const agent = createAgent({ model, tools })

    const session = agent.createSession()

    for await (const event of session.send("List all TypeScript files")) {

    render(event)

    }

     

    与“完整编码产品”的边界:

    SDK 提供可组合的运行时积木;权限 UI、租户隔离、审计、部署和业务状态仍由

    宿主应用负责。不能把 SDK 支持某个能力,等同于产品已经安全地默认启用它。

     

     

    12.4 Agent 评测基础设施 —— 教学用 Eval Harness

     

    下面的 Scenario → Task → Sandbox → Metrics 是本章总结的教学评测模型,

    不是名为 “MultiAgentEval” 的已验证企业产品或 SDK。真实项目可以把这些

    概念映射到自己的测试框架、OpenTelemetry trace evaluator 或供应商评测服务。

     

    核心概念:

     

  • 1. Scenario(评测场景)
  • 定义要评测什么:场景描述 + 任务列表 + 成功标准

     

  • 2. Task(评测任务)
  • 每个 Scenario 包含多个 Task:

  • task_id:任务ID
  • description:Agent 收到的提示词
  • success_criteria:评测指标 + 阈值
  • required_tools:Agent 应该调用的工具
  • expected_state_changes:期望的状态变化
  •  

  • 3. Tool Sandbox(工具沙箱)
  • 模拟工具调用(不调用真实 API)
  • 工具行为由 Scenario 定义控制
  • 支持策略检查(Policy Check)
  •  

  • 4. Metrics(评测指标)
  • policy_compliance:策略合规性
  • path_parsimony:执行效率(步骤越少越好)
  • state_verification:状态验证
  • calculation_accuracy:计算准确性
  • planning_quality:规划质量
  • root_cause_analysis_correctness:诊断准确性
  • consistency_score:多次运行一致性
  • luna_judge_score:LLM-as-Judge 语义评测
  •  

    评测流程:

    ┌───────────────┐

    │ Tool Sandbox │ ← 模拟工具调用

    │ Policy Engine │ ← 检查合规性

    └───────────────┘

    📊 架构示意

      ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
      │ 加载场景  │───→│ 执行任务  │───→│ 收集指标  │───→│ 生成报告  │
      └──────────┘    └──────────┘    └──────────┘    └──────────┘

     

     

    12.5 Agent 生产基础设施全景图

     

    一个生产级 Agent 系统需要以下基础设施:

     

    📊 架构示意

    ┌─────────────────────────────────────────────────────────────┐
    │                      生产基础设施全景                          │
    ├─────────────────┬─────────────────┬─────────────────────────┤
    │   可观测性       │      评测        │        安全              │
    │  ─────────────  │  ─────────────  │  ─────────────────────  │
    │  • LangSmith     │  • Eval Harness  │  • Prompt Injection防护 │
    │  • Langfuse      │  • RAGAS        │  • 权限最小化            │
    │  • OpenTelemetry │  • AgentBench   │  • 审计日志              │
    │  • 自定义 Tracing│  • SWE-bench    │  • 数据脱敏              │
    │  • 日志聚合      │  • 自定义评测集   │  • Rate Limiting       │
    ├─────────────────┼─────────────────┼─────────────────────────┤
    │   成本控制       │      部署        │        可靠性            │
    │  ─────────────  │  ─────────────  │  ─────────────────────  │
    │  • 模型分层      │  • Docker/K8s    │  • 重试机制              │
    │  • 语义缓存      │  • Serverless    │  • 超时控制              │
    │  • Token 预算    │  • 负载均衡      │  • 熔断器                │
    │  • 批处理        │  • 蓝绿部署      │  • 降级策略              │
    │  • 使用配额      │  • Feature Flag  │  • 健康检查              │
    └─────────────────┴─────────────────┴─────────────────────────┘

     

    可观测性(最重要!):

  • 每次 LLM 调用:model + input_tokens + output_tokens + latency
  • 每次 Tool Call:tool_name + args + result + latency
  • 每个 Agent 步骤:step_number + action + observation
  • 指标看板:成功率、平均延迟、Token 消耗趋势、错误分布
  •  

    LangSmith / Langfuse 的使用:

    ┌──────────┐ ┌──────────────┐ ┌──────────┐

    │ Agent │────→│ LangSmith │────→│ 可视化 │

    │ 执行过程 │ │ (Tracing) │ │ Dashboard │

    └──────────┘ └──────────────┘ └──────────┘

    ┌──────────┐

    │ 告警系统 │ ← PagerDuty / Slack

    └──────────┘

    📝 对应的代码实现
    💻 代码 (43 行)
    checkprint_checklistAgentProductionChecklist
    class AgentProductionChecklist:
        """Agent 生产化就绪度检查清单。"""
    
        CHECKLIST = [
            # 可观测性
            ("可观测性", "每次 LLM 调用记录 input/output tokens + latency"),
            ("可观测性", "每次 Tool Call 记录工具名 + 参数 + 结果 + 耗时"),
            ("可观测性", "核心指标看板:成功率 / P50/P99延迟 / Token消耗趋势"),
            ("可观测性", "告警规则:成功率 < 95% → 通知"),
            # 评测
            ("评测", "离线评测集覆盖典型场景 + 边界条件 + Bad Case"),
            ("评测", "上线前回归评测(确保新版本不退化)"),
            ("评测", "A/B 测试框架(对比新老版本效果)"),
            # 安全
            ("安全", "Prompt Injection 检测与过滤"),
            ("安全", "工具调用分级:读自动 / 写确认 / 危险需二次确认"),
            ("安全", "审计日志:记录所有操作,可追溯"),
            ("安全", "敏感信息脱敏(API Key、用户数据等)"),
            # 成本
            ("成本", "模型分层:简单任务用小模型 (gpt-5.6-terra)"),
            ("成本", "语义缓存:避免重复查询消耗 Token"),
            ("成本", "Token 预算告警:单用户/单日/单月上限"),
            # 可靠性
            ("可靠性", "LLM 调用重试 (exponential backoff)"),
            ("可靠性", "超时控制 (30s 超时 + 降级策略)"),
            ("可靠性", "熔断器:连续失败 N 次 → 暂停 → 恢复"),
            ("可靠性", "优雅降级:LLM 不可用时返回兜底回答"),
        ]
    
        class="d">@classmethod
        def check(cls) -> list[tuple[str, str, bool]]:
            """返回检查清单及每项的完成状态(这里标注为待检查)。
    
            Returns:
                (类别, 检查项, 是否完成) 的列表。
            """
            return [(cat, item, False) for cat, item in cls.CHECKLIST]
    
        class="d">@classmethod
        def print_checklist(cls):
            """打印检查清单。"""
            for cat, item in cls.CHECKLIST:
                print(f"  [{cat:8s}] ☐ {item}")

    12.6 全课程体系梳理 —— 回顾与展望

     

    现在你学完了全部 12 章:

     

    Ch0 → 课程概览,理解 Agent 是什么

    Ch1-3 → Agent 的基础理论(循环、组件、类型)

    Ch4-5 → Agent 的工程实践(框架、Multi-Agent)

    Ch6-7 → Agent 的评估与求职(评测、面试)

    Ch8 → Claude Code 架构(nO/h2A/Compaction/SubAgent)

    Ch9 → RAG 深度(Naive→Advanced→GraphRAG→Agentic RAG)

    Ch10 → MCP 协议(JSON-RPC/原语/能力协商/传输层)

    Ch11 → Tool Calling 底层(OpenAI vs Anthropic/Streaming/Strict)

    Ch12 → 生产基础设施(OpenClaw/Harness/评测/可观测性)← 你在这里

     

    面试时你可以自信地讨论:

    ✓ Agent 的核心循环和组件

    ✓ Function Calling 的底层原理

    ✓ MCP 协议的架构和调用流程

    ✓ RAG 的技术演进和 GraphRAG

    ✓ Claude Code 的设计哲学

    ✓ Multi-Agent 系统的架构模式

    ✓ Agent 的生产化 Checklist

     

    核心能力矩阵:

    📊 架构示意

    ┌──────────────────┬──────────────────────────┬─────────┐
    │      能力         │         覆盖章节          │  深度    │
    ├──────────────────┼──────────────────────────┼─────────┤
    │ Agent 基础理论    │ Ch1, Ch2, Ch3            │  ⭐⭐⭐  │
    │ 框架上手          │ Ch4, Ch5                 │  ⭐⭐⭐  │
    │ RAG 技术栈        │ Ch9                      │  ⭐⭐⭐⭐ │
    │ MCP 协议          │ Ch10                     │  ⭐⭐⭐⭐ │
    │ Tool Calling     │ Ch11                     │  ⭐⭐⭐⭐⭐│
    │ Claude Code 架构  │ Ch8                      │  ⭐⭐⭐⭐⭐│
    │ 生产基础设施      │ Ch6, Ch12                │  ⭐⭐⭐  │
    │ 面试准备          │ Ch7                      │  ⭐⭐⭐⭐ │
    └──────────────────┴──────────────────────────┴─────────┘

    12.7 本章总结

     

    核心要点回顾:

     

  • 1. Gateway 架构(OpenClaw 的真实项目案例)
  • Gateway 中心化架构(Node.js 控制平面)
  • 多 Channel 接入(WhatsApp/Telegram/Discord)
  • AgentSkills + ClawHub 插件生态
  • 设计定位:「是 Agent,不是框架」
  •  

  • 2. 可嵌入 Agent SDK(OpenHarness)
  • TypeScript 的 Agent / Session / Event 抽象
  • Middleware、MCP、Skills 与 Subagents 集成
  • 权限、持久化和 UI 由宿主应用补齐
  •  

  • 3. Agent 评测基础设施
  • Eval Harness:本章教学模型,不冒充真实产品
  • 核心概念:Scenario → Task → Sandbox → Metrics
  • 8 种内置评测指标
  •  

  • 4. 生产 Checklist(面试最爱问!)
  • 可观测性(Tracing + Dashboard + Alerting)
  • 评测体系(离线评测 + A/B测试 + 回归评测)
  • 安全防护(Prompt Injection + 权限分级 + 审计)
  • 成本控制(模型分层 + 缓存 + 预算)
  • 可靠性(重试 + 超时 + 熔断 + 降级)
  •  

    面试速记:

    "Agent 怎么上生产?"

    → 可观测性 + 评测体系 + 安全防护 + 成本控制 + 可靠性

    → 每个环节都可以展开讲具体方案

    → 关键在于「工程化思维」而非「Demo 思维」

    📝 对应的代码实现
    💻 代码 (62 行)
    if __name__ == "__main__":
        print("╔══════════════════════════════════════════════════════╗")
        print("║  第12章:OpenClaw / Harness 与 Agent 生产基础设施      ║")
        print("║  Gateway架构 · AgentSkills · 评测 · 生产Checklist    ║")
        print("╚══════════════════════════════════════════════════════╝")
    
        print("\n▶ 12.1 OpenClaw 架构概览")
        print("-" * 50)
        oc_features = [
            "Gateway 中心化架构(Node.js 控制平面)",
            "多 Channel 接入:WhatsApp / Telegram / Discord / Slack",
            "LLM Provider 抽象:Claude / GPT / Gemini / Ollama",
            "持久化记忆存储:用户偏好 + 对话历史",
            "AgentSkills + ClawHub:OpenClaw 的技能与插件生态",
        ]
        for f in oc_features:
            print(f"  • {f}")
    
        print("\n▶ 12.2 AgentSkills vs MCP 关系")
        print("-" * 50)
        print("  MCP 定义「协议」—— 如何连接和通信")
        print("  AgentSkill 定义「能力」—— 具体做什么")
        print("  关系:AgentSkill 通过 MCP 协议暴露给 LLM")
        print("  类比:MCP = USB-C标准,AgentSkill = USB设备")
    
        print("\n▶ 12.3 Harness 亮点")
        print("-" * 50)
        h_features = [
            "TypeScript Agent / Session 抽象",
            "事件流驱动的宿主应用集成",
            "Middleware + MCP + Skills + Subagents",
            "权限、审计和 UI 由宿主应用负责",
        ]
        for f in h_features:
            print(f"  • {f}")
    
        print("\n▶ 12.5 Agent 生产化 Checklist")
        print("-" * 50)
        AgentProductionChecklist.print_checklist()
    
        print("\n▶ 12.6 全课程回顾")
        print("-" * 50)
        chapters = [
            "Ch0   → 课程概览",
            "Ch1-3 → Agent 基础理论(循环/组件/类型)",
            "Ch4-5 → 工程实践(框架/Multi-Agent)",
            "Ch6-7 → 评估与求职(评测/面试)",
            "Ch8   → Claude Code 架构深度剖析",
            "Ch9   → RAG 技术全览(Naive→Agentic RAG)",
            "Ch10  → MCP 协议详解",
            "Ch11  → Tool Calling 底层机制",
            "Ch12  → 生产基础设施(OpenClaw/Harness/评测)",
        ]
        for ch in chapters:
            print(f"  {ch}")
    
        print("\n" + "=" * 60)
        print("  🎓 全课程体系完成!")
        print("  从 Agent 基础到 Claude Code 逆向分析")
        print("  从 RAG 到 MCP 到 Tool Calling 底层原理")
        print("  你现在已经具备了成为顶级 Agent 工程师的所有知识")
        print("=" * 60)

    📦 完整源代码 (449 行)
    """
    第12章:OpenClaw / Harness 与 Agent 生产基础设施
    ================================================
    
    内容核对:2026-08-01
    说明:标注为模拟的实现与数值用于讲解概念,不代表真实 SDK、协议或基准结果。
    
    📌 本章目标:
      1. 深入理解 OpenClaw 的 Gateway 中心化架构
      2. 掌握 AgentSkills 和 ClawHub 的插件生态
      3. 了解 OpenHarness 作为开源 TypeScript Agent SDK 的设计亮点
      4. 理解 Agent 生产基础设施的全景图(Tracing / 评测 / 安全 / 部署)
      5. 学会设计可复用的 Agent 评测 Harness
    
    📌 面试高频点:
      - OpenClaw 和 Claude Code 的架构差异?
      - 什么是 Agent 的 Gateway 架构?有什么优势?
      - Agent 生产化的基础设施包括哪些?
      - 如何搭建 Agent 的评测体系?
    
    
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    12.1 Gateway 中心化架构 —— Agent 生产化设计模式
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    
    OpenClaw 是真实存在的开源、自托管 Agent Gateway,而不是本章虚构的名字。
    官方文档:https://docs.openclaw.ai/
    
    它把聊天渠道、Agent 会话、工具/Skills、自动化和管理控制集中到 Gateway。
    以下内容用于解释这种架构模式;具体配置、支持的渠道和命令可能随版本变化,
    使用时应以官方文档和已安装版本为准。
    
    设计目标:
      一个中心化的 Gateway(Node.js 控制平面),
      统一管理多条消息渠道 + 多个 LLM Provider + 持久化记忆。
    
    OpenClaw 的 Gateway 中心化架构:
    
      ┌─────────────────────────────────────────────────────────┐
      │                    The Gateway                           │
      │                  (Node.js 控制平面)                       │
      │                                                          │
      │  ┌──────────┐  ┌──────────────┐  ┌──────────────────┐  │
      │  │ 消息路由   │  │ 状态管理中心  │  │ 安全策略执行      │  │
      │  │          │  │              │  │                  │  │
      │  └──────────┘  └──────────────┘  └──────────────────┘  │
      │                                                          │
      │  ┌──────────────────────────────────────────────────┐  │
      │  │             LLM Provider Abstraction             │  │
      │  │   Claude | GPT | Gemini | Ollama | 任意兼容API    │  │
      │  └──────────────────────────────────────────────────┘  │
      │                                                          │
      │  ┌──────────────────────────────────────────────────┐  │
      │  │            Persistent Memory Store               │  │
      │  │         长期记忆 + 用户偏好 + 对话历史             │  │
      │  └──────────────────────────────────────────────────┘  │
      └─────────────────────────────────────────────────────────┘
               │                  │                  │
        ┌──────┴──────┐   ┌──────┴──────┐   ┌──────┴──────┐
        │  Channel 1   │   │  Channel 2   │   │  Channel 3   │
        │  WhatsApp    │   │  Telegram    │   │   Discord    │
        └─────────────┘   └─────────────┘   └─────────────┘
    
    Gateway 的职责:
      1. 消息路由:从不同 Channel 接收消息,路由到正确的 LLM Provider
      2. 状态管理:维护每个用户的对话状态和 Agent 运行状态
      3. 安全策略:权限控制、速率限制、内容过滤
      4. Provider 抽象:统一接口,可热切换底层 LLM
    
    Channel Integrations(消息渠道):
      OpenClaw 不是只能通过 CLI 交互,它可以接入:
      - WhatsApp
      - Telegram
      - Discord
      - Slack
      - iMessage
      - Web Chat
    
      Agent 在这些渠道上表现得像一个「真人」。
    
    
    12.2 OpenClaw 的 AgentSkills 和 ClawHub
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    
    这是 OpenClaw 最具特色的设计。
    
    AgentSkills:
      - 类似 Node.js 的 npm 包
      - 社区可以开发、发布、安装 Agent 的「技能」
      - 每个 Skill 是一个独立的模块(含工具定义 + 实现)
    
      示例 Skill:
        skill/weather         → 天气查询
        skill/calendar        → 日历管理
        skill/email           → 邮件发送
        skill/translation     → 翻译服务
        skill/code-review     → 代码审查
    
    ClawHub:
      - AgentSkills 的注册中心
      - 类似 npm registry 或 Docker Hub
      - 社区贡献和共享 Skill
    
    与 MCP 的关系:
      - MCP 定义了「协议」—— 如何连接和通信
      - AgentSkill 定义了「能力」—— 具体做什么
      - 一个 AgentSkill 可以通过 MCP 协议暴露给 LLM
      - 两者是协议层和功能层的关系
    
    
    12.2.1 Gateway 模式为什么适合 Agent?—— 工程取舍分析
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    
    面试官问:「Agent 为什么用 Gateway 模式,不用微服务+API Gateway?」
    
    ▍ Gateway vs 微服务的核心差异
    
      传统微服务 → 每个服务独立部署、独立数据库、独立运维
      Agent 的 Gateway → 集中式控制平面 + 可插拔的 Channel/Provider/AgentSkill
    
      为什么 Agent 架构不适合微服务模式?
    
      1. 成本共享问题 —— Agent 的「状态」不是无状态的
         微服务推崇 stateless → 但 Agent 的对话上下文必须共享
         → 每个请求都重建上下文 = 前 20 条消息重新计费 = 成本爆炸
         → Gateway 模式下对话历史存在控制平面,无需跨服务传递
    
      2. LLM Provider 的切换频率 —— 应该是运行时切换,不是部署时
         微服务要换模型 → 改代码 → 重新部署 → 全量回归测试
         Gateway 换模型 → /model gpt-5.6-sol → 即刻生效,零部署
    
      3. AgentSkill 的安装卸载 —— 需要运行时热插拔
         微服务下装新 Skill → 部署新服务 → 配 Service Discovery
         Gateway 下装新 Skill → install agent-skill/weather → 即刻生效
    
    ▍ Gateway 模式的设计取舍(面试可以主动分析)
    
      优点:集中式状态管理、运行时热切换 Provider/模型、单点安全审计
      代价:Gateway 成为单点瓶颈(需要水平扩展 + 队列)
      解决:Gateway 本身可以是多实例 + 共享存储的
    
      类比:Gateway 模式像「OS 内核」—— 管理所有资源,
      但允许动态加载驱动(AgentSkill)和切换硬件(LLM Provider)
    
    
    12.3 OpenHarness —— 可嵌入应用的 TypeScript Agent SDK
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    
    OpenHarness 也是真实开源项目。它的定位是 code-first TypeScript SDK,
    不是本章旧版描述中的虚构 CLI 编码 Agent。
    官方文档:https://docs.open-harness.dev/
    
    核心抽象:
      - Agent:模型、指令、工具和运行策略
      - Session:保存一段 Agent 交互及其事件
      - Event stream:应用可逐事件渲染文本、工具调用和状态
      - Middleware:承载压缩、重试、持久化、hook 等横切能力
      - Integrations:MCP、Skills、Subagents、Shell/Filesystem 工具和前端辅助
    
    最小使用形态(结构示意,安装时检查当前包名与 API):
    
      const agent = createAgent({ model, tools })
      const session = agent.createSession()
      for await (const event of session.send("List all TypeScript files")) {
        render(event)
      }
    
    与“完整编码产品”的边界:
      SDK 提供可组合的运行时积木;权限 UI、租户隔离、审计、部署和业务状态仍由
      宿主应用负责。不能把 SDK 支持某个能力,等同于产品已经安全地默认启用它。
    
    
    12.4 Agent 评测基础设施 —— 教学用 Eval Harness
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    
    下面的 Scenario → Task → Sandbox → Metrics 是本章总结的教学评测模型,
    不是名为 “MultiAgentEval” 的已验证企业产品或 SDK。真实项目可以把这些
    概念映射到自己的测试框架、OpenTelemetry trace evaluator 或供应商评测服务。
    
    核心概念:
    
      1. Scenario(评测场景)
         定义要评测什么:场景描述 + 任务列表 + 成功标准
    
      2. Task(评测任务)
         每个 Scenario 包含多个 Task:
         - task_id:任务ID
         - description:Agent 收到的提示词
         - success_criteria:评测指标 + 阈值
         - required_tools:Agent 应该调用的工具
         - expected_state_changes:期望的状态变化
    
      3. Tool Sandbox(工具沙箱)
         - 模拟工具调用(不调用真实 API)
         - 工具行为由 Scenario 定义控制
         - 支持策略检查(Policy Check)
    
      4. Metrics(评测指标)
         - policy_compliance:策略合规性
         - path_parsimony:执行效率(步骤越少越好)
         - state_verification:状态验证
         - calculation_accuracy:计算准确性
         - planning_quality:规划质量
         - root_cause_analysis_correctness:诊断准确性
         - consistency_score:多次运行一致性
         - luna_judge_score:LLM-as-Judge 语义评测
    
    评测流程:
      ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
      │ 加载场景  │───→│ 执行任务  │───→│ 收集指标  │───→│ 生成报告  │
      └──────────┘    └──────────┘    └──────────┘    └──────────┘
                           │
                           ▼
                   ┌───────────────┐
                   │ Tool Sandbox  │  ← 模拟工具调用
                   │ Policy Engine │  ← 检查合规性
                   └───────────────┘
    
    
    12.5 Agent 生产基础设施全景图
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    
    一个生产级 Agent 系统需要以下基础设施:
    
    ┌─────────────────────────────────────────────────────────────┐
    │                      生产基础设施全景                          │
    ├─────────────────┬─────────────────┬─────────────────────────┤
    │   可观测性       │      评测        │        安全              │
    │  ─────────────  │  ─────────────  │  ─────────────────────  │
    │  • LangSmith     │  • Eval Harness  │  • Prompt Injection防护 │
    │  • Langfuse      │  • RAGAS        │  • 权限最小化            │
    │  • OpenTelemetry │  • AgentBench   │  • 审计日志              │
    │  • 自定义 Tracing│  • SWE-bench    │  • 数据脱敏              │
    │  • 日志聚合      │  • 自定义评测集   │  • Rate Limiting       │
    ├─────────────────┼─────────────────┼─────────────────────────┤
    │   成本控制       │      部署        │        可靠性            │
    │  ─────────────  │  ─────────────  │  ─────────────────────  │
    │  • 模型分层      │  • Docker/K8s    │  • 重试机制              │
    │  • 语义缓存      │  • Serverless    │  • 超时控制              │
    │  • Token 预算    │  • 负载均衡      │  • 熔断器                │
    │  • 批处理        │  • 蓝绿部署      │  • 降级策略              │
    │  • 使用配额      │  • Feature Flag  │  • 健康检查              │
    └─────────────────┴─────────────────┴─────────────────────────┘
    
    可观测性(最重要!):
      - 每次 LLM 调用:model + input_tokens + output_tokens + latency
      - 每次 Tool Call:tool_name + args + result + latency
      - 每个 Agent 步骤:step_number + action + observation
      - 指标看板:成功率、平均延迟、Token 消耗趋势、错误分布
    
      LangSmith / Langfuse 的使用:
        ┌──────────┐     ┌──────────────┐     ┌──────────┐
        │ Agent    │────→│ LangSmith    │────→│ 可视化    │
        │ 执行过程  │     │ (Tracing)    │     │ Dashboard │
        └──────────┘     └──────────────┘     └──────────┘
                                │
                                ▼
                          ┌──────────┐
                          │ 告警系统  │ ← PagerDuty / Slack
                          └──────────┘
    """
    
    
    class AgentProductionChecklist:
        """Agent 生产化就绪度检查清单。"""
    
        CHECKLIST = [
            # 可观测性
            ("可观测性", "每次 LLM 调用记录 input/output tokens + latency"),
            ("可观测性", "每次 Tool Call 记录工具名 + 参数 + 结果 + 耗时"),
            ("可观测性", "核心指标看板:成功率 / P50/P99延迟 / Token消耗趋势"),
            ("可观测性", "告警规则:成功率 < 95% → 通知"),
            # 评测
            ("评测", "离线评测集覆盖典型场景 + 边界条件 + Bad Case"),
            ("评测", "上线前回归评测(确保新版本不退化)"),
            ("评测", "A/B 测试框架(对比新老版本效果)"),
            # 安全
            ("安全", "Prompt Injection 检测与过滤"),
            ("安全", "工具调用分级:读自动 / 写确认 / 危险需二次确认"),
            ("安全", "审计日志:记录所有操作,可追溯"),
            ("安全", "敏感信息脱敏(API Key、用户数据等)"),
            # 成本
            ("成本", "模型分层:简单任务用小模型 (gpt-5.6-terra)"),
            ("成本", "语义缓存:避免重复查询消耗 Token"),
            ("成本", "Token 预算告警:单用户/单日/单月上限"),
            # 可靠性
            ("可靠性", "LLM 调用重试 (exponential backoff)"),
            ("可靠性", "超时控制 (30s 超时 + 降级策略)"),
            ("可靠性", "熔断器:连续失败 N 次 → 暂停 → 恢复"),
            ("可靠性", "优雅降级:LLM 不可用时返回兜底回答"),
        ]
    
        class="d">@classmethod
        def check(cls) -> list[tuple[str, str, bool]]:
            """返回检查清单及每项的完成状态(这里标注为待检查)。
    
            Returns:
                (类别, 检查项, 是否完成) 的列表。
            """
            return [(cat, item, False) for cat, item in cls.CHECKLIST]
    
        class="d">@classmethod
        def print_checklist(cls):
            """打印检查清单。"""
            for cat, item in cls.CHECKLIST:
                print(f"  [{cat:8s}] ☐ {item}")
    
    
    """
    12.6 全课程体系梳理 —— 回顾与展望
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    
    现在你学完了全部 12 章:
    
      Ch0   → 课程概览,理解 Agent 是什么
      Ch1-3 → Agent 的基础理论(循环、组件、类型)
      Ch4-5 → Agent 的工程实践(框架、Multi-Agent)
      Ch6-7 → Agent 的评估与求职(评测、面试)
      Ch8   → Claude Code 架构(nO/h2A/Compaction/SubAgent)
      Ch9   → RAG 深度(Naive→Advanced→GraphRAG→Agentic RAG)
      Ch10  → MCP 协议(JSON-RPC/原语/能力协商/传输层)
      Ch11  → Tool Calling 底层(OpenAI vs Anthropic/Streaming/Strict)
      Ch12  → 生产基础设施(OpenClaw/Harness/评测/可观测性)← 你在这里
    
    面试时你可以自信地讨论:
      ✓ Agent 的核心循环和组件
      ✓ Function Calling 的底层原理
      ✓ MCP 协议的架构和调用流程
      ✓ RAG 的技术演进和 GraphRAG
      ✓ Claude Code 的设计哲学
      ✓ Multi-Agent 系统的架构模式
      ✓ Agent 的生产化 Checklist
    
    核心能力矩阵:
    ┌──────────────────┬──────────────────────────┬─────────┐
    │      能力         │         覆盖章节          │  深度    │
    ├──────────────────┼──────────────────────────┼─────────┤
    │ Agent 基础理论    │ Ch1, Ch2, Ch3            │  ⭐⭐⭐  │
    │ 框架上手          │ Ch4, Ch5                 │  ⭐⭐⭐  │
    │ RAG 技术栈        │ Ch9                      │  ⭐⭐⭐⭐ │
    │ MCP 协议          │ Ch10                     │  ⭐⭐⭐⭐ │
    │ Tool Calling     │ Ch11                     │  ⭐⭐⭐⭐⭐│
    │ Claude Code 架构  │ Ch8                      │  ⭐⭐⭐⭐⭐│
    │ 生产基础设施      │ Ch6, Ch12                │  ⭐⭐⭐  │
    │ 面试准备          │ Ch7                      │  ⭐⭐⭐⭐ │
    └──────────────────┴──────────────────────────┴─────────┘
    """
    
    
    """
    12.7 本章总结
    ━━━━━━━━━━━━━━
    
    核心要点回顾:
    
    1. Gateway 架构(OpenClaw 的真实项目案例)
       - Gateway 中心化架构(Node.js 控制平面)
       - 多 Channel 接入(WhatsApp/Telegram/Discord)
       - AgentSkills + ClawHub 插件生态
       - 设计定位:「是 Agent,不是框架」
    
    2. 可嵌入 Agent SDK(OpenHarness)
       - TypeScript 的 Agent / Session / Event 抽象
       - Middleware、MCP、Skills 与 Subagents 集成
       - 权限、持久化和 UI 由宿主应用补齐
    
    3. Agent 评测基础设施
       - Eval Harness:本章教学模型,不冒充真实产品
       - 核心概念:Scenario → Task → Sandbox → Metrics
       - 8 种内置评测指标
    
    4. 生产 Checklist(面试最爱问!)
       - 可观测性(Tracing + Dashboard + Alerting)
       - 评测体系(离线评测 + A/B测试 + 回归评测)
       - 安全防护(Prompt Injection + 权限分级 + 审计)
       - 成本控制(模型分层 + 缓存 + 预算)
       - 可靠性(重试 + 超时 + 熔断 + 降级)
    
    面试速记:
      "Agent 怎么上生产?"
      → 可观测性 + 评测体系 + 安全防护 + 成本控制 + 可靠性
      → 每个环节都可以展开讲具体方案
      → 关键在于「工程化思维」而非「Demo 思维」
    """
    
    
    if __name__ == "__main__":
        print("╔══════════════════════════════════════════════════════╗")
        print("║  第12章:OpenClaw / Harness 与 Agent 生产基础设施      ║")
        print("║  Gateway架构 · AgentSkills · 评测 · 生产Checklist    ║")
        print("╚══════════════════════════════════════════════════════╝")
    
        print("\n▶ 12.1 OpenClaw 架构概览")
        print("-" * 50)
        oc_features = [
            "Gateway 中心化架构(Node.js 控制平面)",
            "多 Channel 接入:WhatsApp / Telegram / Discord / Slack",
            "LLM Provider 抽象:Claude / GPT / Gemini / Ollama",
            "持久化记忆存储:用户偏好 + 对话历史",
            "AgentSkills + ClawHub:OpenClaw 的技能与插件生态",
        ]
        for f in oc_features:
            print(f"  • {f}")
    
        print("\n▶ 12.2 AgentSkills vs MCP 关系")
        print("-" * 50)
        print("  MCP 定义「协议」—— 如何连接和通信")
        print("  AgentSkill 定义「能力」—— 具体做什么")
        print("  关系:AgentSkill 通过 MCP 协议暴露给 LLM")
        print("  类比:MCP = USB-C标准,AgentSkill = USB设备")
    
        print("\n▶ 12.3 Harness 亮点")
        print("-" * 50)
        h_features = [
            "TypeScript Agent / Session 抽象",
            "事件流驱动的宿主应用集成",
            "Middleware + MCP + Skills + Subagents",
            "权限、审计和 UI 由宿主应用负责",
        ]
        for f in h_features:
            print(f"  • {f}")
    
        print("\n▶ 12.5 Agent 生产化 Checklist")
        print("-" * 50)
        AgentProductionChecklist.print_checklist()
    
        print("\n▶ 12.6 全课程回顾")
        print("-" * 50)
        chapters = [
            "Ch0   → 课程概览",
            "Ch1-3 → Agent 基础理论(循环/组件/类型)",
            "Ch4-5 → 工程实践(框架/Multi-Agent)",
            "Ch6-7 → 评估与求职(评测/面试)",
            "Ch8   → Claude Code 架构深度剖析",
            "Ch9   → RAG 技术全览(Naive→Agentic RAG)",
            "Ch10  → MCP 协议详解",
            "Ch11  → Tool Calling 底层机制",
            "Ch12  → 生产基础设施(OpenClaw/Harness/评测)",
        ]
        for ch in chapters:
            print(f"  {ch}")
    
        print("\n" + "=" * 60)
        print("  🎓 全课程体系完成!")
        print("  从 Agent 基础到 Claude Code 逆向分析")
        print("  从 RAG 到 MCP 到 Tool Calling 底层原理")
        print("  你现在已经具备了成为顶级 Agent 工程师的所有知识")
        print("=" * 60)
    
    👀 全站总访问 -- | 🧑 全站访客 -- | 📄 本页阅读 --