pkg/
├── agent/               # Agent 核心逻辑
│   ├── agent.go
│   ├── dependencies.go
│   └── workflow/
├── memory/              # 记忆系统
│   ├── semantic.go
│   └── working.go
├── session/             # Session 管理
├── store/               # 持久化
│   ├── interface.go
│   └── json.go
├── backends/            # Backend 抽象层
├── middleware/          # Middleware 系统
├── tools/               # 工具系统
├── provider/            # LLM Provider
├── router/              # 模型路由
├── sandbox/             # 沙箱
└── types/               # 类型定义

config := &types.AgentConfig{
    TemplateID: "assistant",
    LLMProvider: "openai",
    LLMModel: "gpt-4",
}

ag, _ := agent.Create(ctx, config, deps)
result, _ := ag.Chat(ctx, "Hello!")

Request → M1 → M2 → M3 → Handler → M3 → M2 → M1 → Response
          ↓    ↓    ↓              ↑    ↑    ↑
      Before Before Before       After After After

type Middleware interface {
    Name() string
    Priority() int  // 0-100: 系统, 100-500: 功能, 500+: 用户
    Tools() []tools.Tool

    // 双向拦截
    WrapModelCall(ctx, req, handler) (*ModelResponse, error)
    WrapToolCall(ctx, req, handler) (*ToolCallResponse, error)

    // 生命周期钩子
    OnAgentStart(ctx, agentID) error
    OnAgentStop(ctx, agentID) error
}

type BackendProtocol interface {
    ListInfo(ctx, path) ([]FileInfo, error)
    Read(ctx, path, offset, limit) (string, error)
    Write(ctx, path, content) (*WriteResult, error)
    Edit(ctx, path, old, new, replaceAll) (*EditResult, error)
    GrepRaw(ctx, pattern, path, glob) ([]GrepMatch, error)
    GlobInfo(ctx, pattern, path) ([]FileInfo, error)
}

// 单一后端
backend := backends.NewStateBackend()

// 组合后端（路由）
composite := backends.NewCompositeBackend(
    backends.NewStateBackend(), // 默认
    []backends.RouteConfig{
        {Prefix: "/memories/", Backend: storeBackend},
        {Prefix: "/workspace/", Backend: fsBackend},
    },
)

sessions (1) ──<─ (N) session_events
  - id, app_name, user_id, agent_id
  - status, metadata, timestamps
              └─> - id, session_id, invocation_id
                  - content, actions, metadata

// 定义协议
type BackendProtocol interface { ... }

// 工厂函数
type BackendFactory func(ctx) (BackendProtocol, error)

// 延迟初始化
backend := factory(ctx)

type Middleware interface {
    WrapModelCall(ctx, req, next) (*Response, error)
    WrapToolCall(ctx, req, next) (*Response, error)
}

// 自动链式调用
stack := NewStack(middlewares)  // 按 Priority 排序

type Middleware interface {
    Priority() int  // 数值越小优先级越高
}

// 0-100: 系统核心功能
// 100-500: 通用功能(文件、子代理等)
// 500-1000: 业务逻辑

type MyBackend struct {
    // 你的存储逻辑
}

func (b *MyBackend) Read(ctx, path, offset, limit) (string, error) {
    // 实现读取
}

// ... 实现其他方法

type MyMiddleware struct {
    *middleware.BaseMiddleware
}

func NewMyMiddleware() *MyMiddleware {
    return &MyMiddleware{
        BaseMiddleware: middleware.NewBaseMiddleware("my-middleware", 300),
    }
}

func (m *MyMiddleware) Tools() []tools.Tool {
    return []tools.Tool{&MyTool{}}
}

func (m *MyMiddleware) WrapToolCall(ctx, req, handler) (*ToolCallResponse, error) {
    // 前置处理
    log.Printf("Before: %s", req.ToolName)

    // 调用下一层
    resp, err := handler(ctx, req)

    // 后置处理
    log.Printf("After: %v", resp.Result)

    return resp, err
}

// 工具返回结构化错误
return map[string]interface{}{
    "ok":    false,
    "error": "详细错误信息",
    "recommendations": []string{
        "建议1",
        "建议2",
    },
}, nil  // 不要返回 error，让 LLM 看到错误信息