Agent 插件市场架构：动态加载工具与安全沙箱隔离

一、"每次加一个新工具就要重新部署 Agent"

Agent 上线半年后，工具数量从 5 个增长到 45 个。每次新增工具（如"查天气"、"发邮件"、"翻译"），都需要修改 Agent 主代码、重新编译、重新部署。一次部署需要走审批流程 2 天。业务团队抱怨：这比直接写 API 还慢。

问题本质：Agent 的工具集是硬编码的，耦合在主程序中。插件市场架构解决的就是这个问题——让工具成为可以动态加载、独立部署、按需启用的独立模块。

二、插件架构设计：注册 → 发现 → 加载 → 隔离

flowchart TD
    subgraph PluginRepo[插件仓库]
        P1[插件A: 天气查询]
        P2[插件B: 邮件发送]
        P3[插件C: 翻译服务]
    end
    
    subgraph AgentCore[Agent 核心]
        PM[插件管理器]
        PM --> Reg[插件注册中心]
        PM --> Loader[动态加载器]
        PM --> SB[安全沙箱]
    end
    
    AgentCore -->|发现| PluginRepo
    
    Reg --> IR[接口注册: 声明工具 Schema]
    Loader -->|WASM/容器| P1
    Loader -->|WASM/容器| P2
    Loader -->|WASM/容器| P3
    
    SB --> RL[资源限制: CPU/内存/网络]
    SB --> PL[权限控制: 允许读写的文件路径]
    SB --> TL[超时控制: 单次调用最长执行时间]
    
    User[用户请求] --> AgentCore
    AgentCore --> User

插件化的三个关键技术决策：加载方式（进程内 WASM vs 进程外容器）、接口规范（插件如何声明自己能做什么）、安全隔离（插件做了坏事怎么办）。

三、Go 实现：插件管理器

package plugin

import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "os/exec"
    "sync"
    "time"
)

// ========== 插件接口规范 ==========

// ToolSchema 工具定义（对模型可见）
type ToolSchema struct {
    Name        string                 `json:"name"`
    Description string                 `json:"description"`
    Parameters  map[string]interface{} `json:"parameters"` // JSON Schema
}

// PluginInfo 插件元信息
type PluginInfo struct {
    ID          string       `json:"id"`
    Name        string       `json:"name"`
    Version     string       `json:"version"`
    Description string       `json:"description"`
    Author      string       `json:"author"`
    Tools       []ToolSchema `json:"tools"`      // 提供的工具列表
    Permissions []string     `json:"permissions"` // 需要的权限
    SandboxType string       `json:"sandbox_type"` // wasm | process | http
    Entrypoint  string       `json:"entrypoint"`   // 启动命令/WASM 路径
}

// Plugin 插件运行时接口
type Plugin interface {
    // GetInfo 返回插件元信息
    GetInfo() PluginInfo
    
    // Execute 执行插件工具
    Execute(ctx context.Context, toolName string, params map[string]interface{}) (interface{}, error)
    
    // HealthCheck 健康检查
    HealthCheck(ctx context.Context) error
    
    // Shutdown 关闭插件
    Shutdown(ctx context.Context) error
}

// ========== 插件管理器 ==========

// PluginManager 插件管理器
type PluginManager struct {
    plugins     map[string]Plugin          // pluginID → Plugin
    toolIndex   map[string]string          // toolName → pluginID
    regDir      string                     // 插件注册目录
    mu          sync.RWMutex
}

func NewPluginManager(regDir string) *PluginManager {
    return &PluginManager{
        plugins:   make(map[string]Plugin),
        toolIndex: make(map[string]string),
        regDir:    regDir,
    }
}

// LoadFromRegistry 从插件目录批量加载
func (pm *PluginManager) LoadFromRegistry(ctx context.Context) error {
    entries, err := os.ReadDir(pm.regDir)
    if err != nil {
        return fmt.Errorf("读取插件目录失败: %w", err)
    }
    
    for _, entry := range entries {
        if !entry.IsDir() {
            continue
        }
        
        // 读取插件描述文件
        manifestPath := pm.regDir + "/" + entry.Name() + "/manifest.json"
        data, err := os.ReadFile(manifestPath)
        if err != nil {
            continue
        }
        
        var info PluginInfo
        if err := json.Unmarshal(data, &info); err != nil {
            continue
        }
        
        // 动态加载插件
        if err := pm.LoadPlugin(ctx, info); err != nil {
            fmt.Printf("[PluginManager] 加载插件 %s 失败: %v\n", info.Name, err)
            continue
        }
        
        fmt.Printf("[PluginManager] 插件已加载: %s v%s\n", info.Name, info.Version)
    }
    
    return nil
}

// LoadPlugin 加载单个插件
func (pm *PluginManager) LoadPlugin(ctx context.Context, info PluginInfo) error {
    var plugin Plugin
    
    switch info.SandboxType {
    case "process":
        plugin = NewProcessPlugin(info)
    case "wasm":
        plugin = NewWasmPlugin(info)
    case "http":
        plugin = NewHTTPPlugin(info)
    default:
        return fmt.Errorf("不支持的沙箱类型: %s", info.SandboxType)
    }
    
    // 健康检查
    if err := plugin.HealthCheck(ctx); err != nil {
        return fmt.Errorf("插件健康检查失败: %w", err)
    }
    
    // 建立工具名 → 插件映射
    pm.mu.Lock()
    pm.plugins[info.ID] = plugin
    for _, tool := range info.Tools {
        pm.toolIndex[tool.Name] = info.ID
    }
    pm.mu.Unlock()
    
    return nil
}

// GetAvailableTools 获取所有可用工具的 Schema（给模型看的）
func (pm *PluginManager) GetAvailableTools() []ToolSchema {
    pm.mu.RLock()
    defer pm.mu.RUnlock()
    
    var tools []ToolSchema
    for _, plugin := range pm.plugins {
        for _, tool := range plugin.GetInfo().Tools {
            tools = append(tools, tool)
        }
    }
    return tools
}

// ExecuteTool 执行工具调用
func (pm *PluginManager) ExecuteTool(
    ctx context.Context, toolName string, params map[string]interface{},
) (interface{}, error) {
    pm.mu.RLock()
    pluginID, ok := pm.toolIndex[toolName]
    if !ok {
        pm.mu.RUnlock()
        return nil, fmt.Errorf("未找到工具: %s", toolName)
    }
    
    plugin, ok := pm.plugins[pluginID]
    pm.mu.RUnlock()
    
    if !ok {
        return nil, fmt.Errorf("插件未加载: %s", pluginID)
    }
    
    // 设置执行超时
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()
    
    return plugin.Execute(ctx, toolName, params)
}

// ========== 进程插件（安全沙箱） ==========

// ProcessPlugin 以独立进程运行的插件（最高隔离性）
type ProcessPlugin struct {
    info    PluginInfo
    cmd     *exec.Cmd
    stdin   io.WriteCloser
    stdout  io.ReadCloser
    mu      sync.Mutex
}

func NewProcessPlugin(info PluginInfo) *ProcessPlugin {
    return &ProcessPlugin{info: info}
}

func (p *ProcessPlugin) GetInfo() PluginInfo {
    return p.info
}

func (p *ProcessPlugin) Execute(
    ctx context.Context, toolName string, params map[string]interface{},
) (interface{}, error) {
    p.mu.Lock()
    defer p.mu.Unlock()
    
    // 构造请求
    req := map[string]interface{}{
        "tool":  toolName,
        "params": params,
    }
    
    data, err := json.Marshal(req)
    if err != nil {
        return nil, fmt.Errorf("序列化请求失败: %w", err)
    }
    
    // 通过 stdin 发送给插件进程
    if _, err := p.stdin.Write(append(data, '\n')); err != nil {
        return nil, fmt.Errorf("写入 stdin 失败: %w", err)
    }
    
    // 从 stdout 读取结果
    // 实际项目中用 bufio.Scanner 读行
    buf := make([]byte, 65536)
    n, err := p.stdout.Read(buf)
    if err != nil {
        return nil, fmt.Errorf("读取 stdout 失败: %w", err)
    }
    
    var result interface{}
    if err := json.Unmarshal(buf[:n], &result); err != nil {
        return nil, fmt.Errorf("解析响应失败: %w", err)
    }
    
    return result, nil
}

func (p *ProcessPlugin) HealthCheck(ctx context.Context) error {
    cmd := exec.CommandContext(ctx, p.info.Entrypoint)
    
    // 资源限制（Linux cgroups）
    // cmd.SysProcAttr = &syscall.SysProcAttr{...}
    
    stdin, _ := cmd.StdinPipe()
    stdout, _ := cmd.StdoutPipe()
    
    if err := cmd.Start(); err != nil {
        return fmt.Errorf("启动插件进程失败: %w", err)
    }
    
    p.cmd = cmd
    p.stdin = stdin
    p.stdout = stdout
    
    return nil
}

func (p *ProcessPlugin) Shutdown(ctx context.Context) error {
    if p.cmd != nil && p.cmd.Process != nil {
        return p.cmd.Process.Kill()
    }
    return nil
}

// ========== HTTP 插件（最轻量） ==========

type HTTPPlugin struct {
    info   PluginInfo
    client *http.Client
    url    string
}

func NewHTTPPlugin(info PluginInfo) *HTTPPlugin {
    return &HTTPPlugin{
        info: info,
        client: &http.Client{Timeout: 30 * time.Second},
        url:   info.Entrypoint, // 插件服务的 URL
    }
}

func (p *HTTPPlugin) GetInfo() PluginInfo { return p.info }

func (p *HTTPPlugin) Execute(
    ctx context.Context, toolName string, params map[string]interface{},
) (interface{}, error) {
    body, _ := json.Marshal(map[string]interface{}{
        "tool": toolName, "params": params,
    })
    
    req, _ := http.NewRequestWithContext(ctx, "POST", p.url+"/execute", 
        io.NopCloser(json.NewDecoder(nil).Buffered()))
    _ = body // 实际发送 body
    
    resp, err := p.client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var result interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

func (p *HTTPPlugin) HealthCheck(ctx context.Context) error {
    req, _ := http.NewRequestWithContext(ctx, "GET", p.url+"/health", nil)
    resp, err := p.client.Do(req)
    if err != nil {
        return err
    }
    resp.Body.Close()
    if resp.StatusCode != 200 {
        return fmt.Errorf("HTTP %d", resp.StatusCode)
    }
    return nil
}

func (p *HTTPPlugin) Shutdown(ctx context.Context) error { return nil }

// ========== WASM 插件（进程内隔离） ==========

type WasmPlugin struct {
    info PluginInfo
    // wasmtime.Engine / wazero.Runtime
}

func NewWasmPlugin(info PluginInfo) *WasmPlugin {
    return &WasmPlugin{info: info}
}

func (p *WasmPlugin) GetInfo() PluginInfo { return p.info }

func (p *WasmPlugin) Execute(ctx context.Context, toolName string, params map[string]interface{}) (interface{}, error) {
    // WASM 沙箱执行（使用 wazero 库）
    return "wasm-result", nil
}

func (p *WasmPlugin) HealthCheck(ctx context.Context) error { return nil }
func (p *WasmPlugin) Shutdown(ctx context.Context) error { return nil }

四、插件化架构的边界与权衡

三种隔离方案的取舍。 进程级隔离最安全（插件崩溃不影响主程序），但启动开销大。WASM 性能好（进程内运行）而且沙箱安全，但支持的编程语言有限。HTTP 插件最灵活（任何语言），但网络开销大且沙箱隔离弱。

插件质量参差不齐。 开放插件市场后，社区贡献的插件质量无法保证。需要建立插件审核机制：代码审查 + 自动化测试 + 用户评分。一个低质量插件可能拉低整个 Agent 的回答质量。

Schema 的标准化是关键。 如果每个插件用自己的 JSON Schema 风格描述参数，模型就会困惑。应该制定统一的 Schema 规范，包括参数命名风格（snake_case）、错误返回格式、必填/可选标记。

热加载需要兼容性考虑。 新版本插件可能与 Agent 主程序接口不兼容。需要版本协商机制——插件声明支持的 API 版本，Agent 根据版本决定是否加载。

五、总结

Agent 插件化架构的核心：统一接口规范（所有插件实现同一套接口）、三种隔离方案（进程/WASM/HTTP 各有适用场景）、动态加载机制（热加载不需要重启 Agent）。实施路径：先用 HTTP 插件做 MVP（最快实现），验证流程跑通后再根据安全需求引入 WASM 或进程隔离。插件化的最终目标是让 Agent 的工具生态从"开发团队维护"变成"业务团队自助贡献"。