✅ 理解扩展机制的三层架构（核心引擎→钩子→插件）

✅ 设计钩子系统：事件、优先级、管道模式、错误隔离

✅ 实现插件架构：清单声明 + 生命周期管理

✅ 理解 MCP 协议：Agent 与外部服务的标准化通信

✅ 对比 Claude Code 的扩展系统设计

✅ 掌握扩展机制的五大设计原则

① 关注点分离：核心逻辑与扩展功能解耦，各自独立演化

② 开闭原则：对扩展开放，对修改关闭——不改核心代码就能加功能

┌─────────────────────────────────────────┐│              应用层 (Application)         ││  ┌───────────────────────────────────┐   ││  │       插件系统 (Plugin System)     │   ││  │  ┌──────┐  ┌──────┐  ┌──────┐    │   ││  │  │插件A │  │插件B │  │插件C │    │   ││  │  └──────┘  └──────┘  └──────┘    │   ││  └───────────────────────────────────┘   ││                    ▼                      ││  ┌───────────────────────────────────┐   ││  │       钩子系统 (Hook System)       │   ││  │  ┌─────┐ ┌─────┐ ┌───────────┐   │   ││  │  │前置  │ │后置  │ │错误/完成   │   │   ││  │  └─────┘ └─────┘ └───────────┘   │   ││  └───────────────────────────────────┘   ││                    ▼                      ││  ┌───────────────────────────────────┐   ││  │       核心引擎 (Core Engine)       │   ││  │  Tool Call │ LLM Call │ Agent Loop │   ││  └───────────────────────────────────┘   │└─────────────────────────────────────────┘

💡 一句话理解：核心引擎是"发动机"，钩子系统是"传感网络"，插件系统是"配件商城"。三层各管各的，互不干扰。

┌──────────┐    ┌──────────────┐    ┌──────────┐│ 接收任务  │    │  调用工具     │    │ 调用 LLM  │└────┬─────┘    └──────┬───────┘    └────┬─────┘     │                 │                 │     ▼                 ▼                 ▼┌──────────┐  ┌────────────┐  ┌──────────────┐│beforeAll │  │beforeTool  │  │beforeLlmCall │└──────────┘  └──────┬─────┘  └──────┬───────┘                     │               │                     ▼               ▼              ┌────────────┐  ┌──────────────┐              │  工具执行   │  │  LLM 响应    │              └──────┬─────┘  └──────┬───────┘                     │               │                     ▼               ▼              ┌────────────┐  ┌──────────────┐              │afterTool   │  │afterLlmCall  │              └──────┬─────┘  └──────┬───────┘                     │               │                     └───────┬───────┘                             │                    ┌────────┴────────┐                    ▼                 ▼              ┌──────────┐    ┌────────────┐              │ onError  │    │ onComplete │              └──────────┘    └────────────┘

① 优先级排序：每个钩子注册时指定优先级（数值越小越先执行），关键校验设高优先级，日志记录设低优先级

② 管道模式：钩子可以修改上下文对象，后续钩子接收的是修改后的数据（类似 HTTP 中间件的"洋葱模型"）

③ 错误隔离：单个钩子失败不影响其他钩子，系统捕获异常后继续执行

输入上下文    │    ▼┌─────────┐     ┌─────────┐     ┌─────────┐│ 钩子 A   │ ──► │ 钩子 B   │ ──► │ 钩子 C   │ ──► 输出│(优先级 5)│     │(优先级10)│     │(优先级15)│└─────────┘     └─────────┘     └─────────┘

// 注册钩子hookSystem.register(event, handler, priority?);// 执行钩子链const context = await hookSystem.execute(event, initialData);// 移除钩子hookSystem.unregister(event, handler);hookSystem.unregisterByName(name);

// 创建钩子系统实例consthookSystem = newHookSystem();// 注册日志钩子（低优先级，后执行）hookSystem.register("beforeToolCall", loggingHook, 20);hookSystem.register("afterToolCall", loggingHook, 20);// 注册验证钩子（高优先级，先执行）hookSystem.register("beforeToolCall", validationHook, 5);// 执行时，先验证后记录日志constresult = await hookSystem.execute("beforeToolCall", {data: { toolName: "search", args: { query: "AI Agent" } },});

💡 执行顺序：validationHook（优先级 5）先跑校验 → loggingHook（优先级 20）后记日志。如果校验失败，可以拦截后续执行。

interfacePluginManifest {name: string;           // 插件名称（唯一标识）version: string;        // 语义化版本号description: string;    // 功能描述  hooks?: Array<{         // 钩子注册列表event: string;handler: Function;  }>;  tools?: ToolDefinition[];  // 提供的工具  systemPrompt?: string;     // 追加到系统提示的文本}

注册插件│▼┌───────────┐│ load(加载) │── 读取清单，验证依赖└─────┬─────┘│▼┌────────────┐│init(初始化)│── 分配资源，建立连接└─────┬──────┘│▼┌──────────────┐│activate(激活)│── 注册钩子/工具，开始服务└──────┬───────┘│┌────┴────┐││▼▼运行中    停用/卸载│▼┌──────────────┐│ deactivate   │── 释放资源，取消注册└──────────────┘

const codeFormatterPlugin: PluginManifest = {  name: "code-formatter",  version: "1.0.0",  description: "代码格式化能力",  tools: [{    name: "format_code",    description: "格式化代码",    inputSchema: { ... },    execute: async (args) => { ... },  }],  hooks: [{    event: "beforeToolCall",    handler: (ctx) => { /* 验证输入 */ },  }],  systemPrompt: "你拥有代码格式化能力...",};

const gitHelperPlugin: PluginManifest = {  name: "git-helper",  version: "2.1.0",  description: "Git 版本控制辅助",  tools: [    { name: "git_status", ... },    { name: "git_commit", ... },  ],  hooks: [{    event: "afterToolCall",    handler: (ctx) => { /* 记录操作日志 */ },  }],  systemPrompt: "你具备 Git 版本控制辅助能力...",};

💡 关键点：注册这两个插件后，Agent 自动获得代码格式化和 Git 操作能力，核心代码不需要任何修改。这就是"对扩展开放，对修改关闭"。

┌───────────────┐       MCP 协议       ┌───────────────┐│               │ ◄══════════════════► │               ││  MCP 客户端    │                      │  MCP 服务器    ││  (AI Agent)   │                      │ (工具/数据源)  ││               │                      │               ││  发现能力      │ ── 列出工具/资源 ──► │               ││  调用工具      │ ── 执行工具调用 ───► │               ││  获取资源      │ ── 读取资源/数据 ──► │               ││  订阅变更      │ ◄── 状态变更通知 ──── │               │└───────────────┘                      └───────────────┘

插件系统：Agent 进程内的扩展 → 适合与 Agent 生命周期绑定的能力（如代码格式化）

MCP：Agent 进程间的扩展 → 适合独立运行的外部服务（如数据库、文件系统、云服务）

💡 最佳实践：在实际框架中，MCP 服务器适配器本身就可以实现为一个插件。这样插件系统成为 MCP 的"网关"，Agent 同时拥有进程内的高效集成和进程间的灵活扩展。

┌─────────────────────────────────────────┐│ClaudeCodeCLI│├─────────────────────────────────────────┤│││  插件 /SlashCommands││┌─────────┐┌─────────┐│││/review │  │ /fix    │...││└─────────┘└─────────┘││││  工具 (Tools)                            ││┌────┐┌────┐┌────┐┌────┐│││Bash││Read││Edit││grep│...││└────┘└────┘└────┘└────┘││││MCP 服务器                              ││┌────────────────────────┐│││ 外部 MCPServer(filesys)│...││└────────────────────────┘││││  钩子 (Hooks)                            ││┌────────┐┌────────┐│││前置钩子 ││后置钩子 │...││└────────┘└────────┘│├─────────────────────────────────────────┤│       settings.json /CLAUDE.md          │└─────────────────────────────────────────┘

① 配置驱动 > 代码驱动：通过 manifest 文件声明扩展，而不是直接改代码

② 分层扩展：不同需求用不同机制（钩子 vs 插件 vs MCP），不一刀切

③ 进程隔离：不稳定的第三方工具用独立进程运行（MCP）

④ 渐进式复杂度：简单场景用钩子，复杂场景用插件，跨进程用 MCP

从"出生"到"长骨骼"，十一章的内容构成了一个完整的 Agent 架构体系。扩展机制是最后一块拼图——它让 Agent 不再是一个固定的程序，而是一个可无限生长的平台。

原则一：核心引擎只做最基础的事，能力通过扩展注入

原则二：钩子是"点"，插件是"面"，MCP 是"跨进程"

原则三：每个扩展点都要有错误隔离，一个插件崩不能带垮全局

原则四：配置驱动优于代码驱动，声明式注册优于硬编码

原则五：渐进式复杂度——简单用钩子，复杂用插件，跨进程用 MCP

下一章预告

第十二章我们将深入探讨 Agent 的性能优化与生产化部署——如何让 Agent 跑得更快、更稳、更省 Token，从"能跑"到"能上线"。

练习 1：实现一个 RateLimitHook 钩子，在 beforeToolCall 中限制调用频率（1秒内不超过3次）

练习 2：为 PluginSystem 添加 getTool(name) 和 hasPlugin(name) 方法

练习 3：构建一个翻译插件，提供 translate 工具 + beforeToolCall 验证 + afterToolCall 统计

练习 4（选做）：设计 MCPPluginAdapter，将 MCP 服务器包装为插件