Agent 架构图解

图 1: 整体分层架构

┌────────────────────────────────────────────────────────────────────────┐
│                          用户层 (User Layer)                           │
│                   CLI / TUI / Web API / MCP                            │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                     SessionPrompt 层                                    │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │  prompt() ──▶ createUserMessage() ──▶ loop()                    │  │
│  │                                                                  │  │
│  │  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   │  │
│  │  │ Agent    │   │ Message  │   │ Prompt   │   │ Instruction│   │  │
│  │  │ Selection │   │ Creation │   │ Resolve  │   │  Inject   │   │  │
│  │  └──────────┘   └──────────┘   └──────────┘   └──────────┘   │  │
│  └─────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
                    ▼               ▼               ▼
         ┌──────────────────┐ ┌──────────┐ ┌──────────────────┐
         │  Subtask Handler │ │Compaction│ │  Normal Handler  │
         │  (子Agent调用)    │ │(压缩)    │ │                  │
         └────────┬─────────┘ └────┬─────┘ └────────┬─────────┘
                  │                │                │
                  ▼                │                ▼
         ┌──────────────────┐       │      ┌──────────────────┐
         │  TaskTool       │       │      │SessionProcessor  │
         │  .execute()     │       │      │  .process()      │
         └────────┬─────────┘       │      └────────┬─────────┘
                  │                 │               │
                  ▼                 │               ▼
         ┌──────────────────┐       │      ┌──────────────────┐
         │ 子Session 创建   │       │      │   LLM.stream()   │
         │ + 递归 prompt()  │       │      └────────┬─────────┘
         └──────────────────┘       │               │
                                     │               ▼
                                     │      ┌──────────────────┐
                                     │      │  ToolRegistry    │
                                     │      │  工具解析        │
                                     │      └────────┬─────────┘
                                     │               │
                                     │       ┌───────┴───────┐
                                     │       ▼               ▼
                                     │  ┌──────────┐   ┌──────────┐
                                     │  │ 内置工具 │   │ MCP工具  │
                                     │  │Bash/Edit │   │ Server   │
                                     │  │Read/Grep │   │ Tools    │
                                     │  └──────────┘   └──────────┘
                                     │
└─────────────────────────────────────┴─────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        Storage 层 (MessageV2)                          │
│              Session.messages / Session.updateMessage                   │
└────────────────────────────────────────────────────────────────────────┘

图 2: 主子 Agent 调度流程

┌─────────────────────────────────────────────────────────────────────────┐
│                        主 Agent 调度时序图                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  用户          会话           Agent            TaskTool        子Agent  │
│   │             │              │                │               │      │
│   │ 输入消息    │              │                │               │      │
│   │────────────▶│              │                │               │      │
│   │             │              │                │               │      │
│   │             │ prompt()     │                │               │      │
│   │             │──────────────▶                │               │      │
│   │             │              │                │               │      │
│   │             │              │ loop()         │               │      │
│   │             │              │────┐           │               │      │
│   │             │              │    │           │               │      │
│   │             │              │◀───┘ 循环      │               │      │
│   │             │              │                │               │      │
│   │             │              │ LLM决定调用    │               │      │
│   │             │              │ @explore       │               │      │
│   │             │              │                │               │      │
│   │             │              │ execute()      │               │      │
│   │             │              │───────────────▶               │      │
│   │             │              │                │               │      │
│   │             │              │                │ 1.权限检查    │      │
│   │             │              │                │─────────────▶│      │
│   │             │              │                │               │      │
│   │             │              │                │ 2.创建子Session│     │
│   │             │              │                │─────────────▶│      │
│   │             │              │                │               │      │
│   │             │              │                │ prompt()      │      │
│   │             │              │                │──────────────▶│      │
│   │             │              │                │               │      │
│   │             │              │                │               │ ◀────│
│   │             │              │                │   子Agent执行  │
│   │             │              │                │               │ ────▶│
│   │             │              │                │               │      │
│   │             │              │                │◀───────────────│      │
│   │             │              │                │ 3.返回结果     │
│   │             │              │◀───────────────│               │      │
│   │             │              │                │               │      │
│   │             │              │ 继续循环处理    │               │      │
│   │             │              │────┐           │               │      │
│   │             │              │    │           │               │      │
│   │             │              │◀───┘           │               │      │
│   │             │              │                │               │      │
│   │ 返回结果    │              │                │               │      │
│   │◀────────────│              │                │               │      │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

图 3: Session 与 Agent 关系

┌─────────────────────────────────────────────────────────────────────────┐
│                          Session 层级结构                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ Root Session (sess_root_xxx)                                    │   │
│  │                                                                 │   │
│  │  agent: "build" (主 Agent)                                      │   │
│  │  parentID: undefined                                            │   │
│  │                                                                 │   │
│  │  ┌─────────────────────────────────────────────────────────┐   │   │
│  │  │ Message: user                                           │   │   │
│  │  │   agent: "build"                                        │   │   │
│  │  │   parts: [                                              │   │   │
│  │  │     { type: "text", text: "帮我搜索代码..." },          │   │   │
│  │  │     { type: "subtask", agent: "explore", prompt: "..." } │   │   │
│  │  │   ]                                                     │   │   │
│  │  └─────────────────────────────────────────────────────────┘   │   │
│  │                                                                 │   │
│  │  ┌─────────────────────────────────────────────────────────┐   │   │
│  │  │ Message: assistant                                      │   │   │
│  │  │   agent: "build"                                        │   │   │
│  │  │   parts: [                                              │   │   │
│  │  │     { type: "tool", tool: "task",                       │   │   │
│  │  │       state: { status: "completed", output: "..." } }  │   │   │
│  │  │   ]                                                     │   │   │
│  │  └─────────────────────────────────────────────────────────┘   │   │
│  │                                                                 │   │
│  └─────────────────────────────┬───────────────────────────────────┘   │
│                                │                                        │
│                                │ Session.parentID                       │
│                                ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ Child Session (sess_child_yyy) ─── 由 TaskTool 创建              │   │
│  │                                                                 │   │
│  │  agent: "explore" (子 Agent)                                    │   │
│  │  parentID: "sess_root_xxx"  ◀── 关联父会话                      │   │
│  │                                                                 │   │
│  │  ┌─────────────────────────────────────────────────────────┐   │   │
│  │  │ Message: user                                           │   │   │
│  │  │   agent: "explore"                                      │   │   │
│  │  │   parts: [                                              │   │   │
│  │  │     { type: "text", text: "搜索代码..." }               │   │   │
│  │  │   ]                                                     │   │   │
│  │  └─────────────────────────────────────────────────────────┘   │   │
│  │                                                                 │   │
│  │  ┌─────────────────────────────────────────────────────────┐   │   │
│  │  │ Message: assistant                                      │   │   │
│  │  │   agent: "explore"                                      │   │   │
│  │  │   parts: [ ... 搜索结果 ... ]                          │   │   │
│  │  └─────────────────────────────────────────────────────────┘   │   │
│  │                                                                 │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

图 4: 权限检查流程

┌─────────────────────────────────────────────────────────────────────────┐
│                       PermissionNext 权限流程                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌───────────────┐                                                     │
│  │ Tool 执行请求  │                                                     │
│  └───────┬───────┘                                                     │
│          │                                                             │
│          ▼                                                             │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  PermissionNext.ask({                                            │   │
│  │    permission: "bash",                                          │   │
│  │    patterns: ["/tmp/test.sh"],                                   │   │
│  │    ruleset: [agent.permission, session.permission]                │   │
│  │  })                                                              │   │
│  └───────┬───────────────────────────────────────────────────────────┘   │
│          │                                                             │
│          ▼                                                             │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  evaluate("bash", "/tmp/test.sh", ...ruleset)                    │   │
│  │                                                                 │   │
│  │  1. 合并 ruleset                                                │   │
│  │  2. findLast() 从后往前找匹配的规则                              │   │
│  │     ┌─────────────────────────────────────────────────────┐     │   │
│  │     │ Agent.permission:                                    │     │   │
│  │     │   { permission: "bash", pattern: "*", action: "ask" }│     │   │
│  │     │   { permission: "edit", pattern: "*", action: "deny" }│     │   │
│  │     │                                                       │     │   │
│  │     │ Session.permission:                                   │     │   │
│  │     │   { permission: "bash", pattern: "/tmp/*", action: "allow" }│   │
│  │     │                                                       │     │   │
│  │     │ 合并后 findLast("bash", "/tmp/test.sh")              │     │   │
│  │     │   → { permission: "bash", pattern: "/tmp/*", action: "allow" }│ │
│  │     │   (因为是最后一个匹配，且 /tmp/* 匹配 /tmp/test.sh)    │     │   │
│  │     └─────────────────────────────────────────────────────┘     │   │
│  └───────┬───────────────────────────────────────────────────────────┘   │
│          │                                                             │
│          ▼                                                             │
│  ┌───────────────┐     ┌───────────────┐     ┌───────────────┐       │
│  │ action =      │     │ action =      │     │ action =      │       │
│  │ "allow"       │     │ "ask"         │     │ "deny"        │       │
│  └───────┬───────┘     └───────┬───────┘     └───────┬───────┘       │
│          │                     │                     │                 │
│          ▼                     ▼                     ▼                 │
│  ┌───────────────┐     ┌───────────────┐     ┌───────────────┐       │
│  │ 直接执行工具   │     │ 弹出用户确认   │     │ 抛出错误      │       │
│  │               │     │                │     │ DeniedError   │       │
│  │ ┌───────────┐ │     │ ┌───────────┐ │     │               │       │
│  │ │ bash tool │ │     │ │ ┌───────┐ │ │     │ ┌───────────┐ │       │
│  │ │ .execute()│ │     │ │ │ Allow?│ │ │     │ │ Error:    │ │       │
│  │ └───────────┘ │     │ │ │Once│All│ │ │     │ │ Permission│ │       │
│  │               │     │ │ └───────┘ │ │     │ │ denied    │ │       │
│  │               │     │ └───────────┘ │     │ └───────────┘ │       │
│  └───────────────┘     └───────┬───────┘     └───────────────┘       │
│                                │                                     │
│                     ┌──────────┴──────────┐                          │
│                     │                     │                          │
│                     ▼                     ▼                          │
│              ┌───────────────┐     ┌───────────────┐               │
│              │ 用户选择 Allow │     │ 用户选择 Deny │               │
│              │ 记住选项       │     │               │               │
│              └───────────────┘     └───────────────┘               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

图 5: Loop 循环状态机

┌─────────────────────────────────────────────────────────────────────────┐
│                      SessionPrompt.loop() 状态机                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│                          ┌─────────────┐                                │
│                          │   START     │                                │
│                          └──────┬──────┘                                │
│                                 │                                        │
│                                 ▼                                        │
│                    ┌────────────────────────┐                           │
│                    │  1. 加载消息历史       │                           │
│                    │ 2. 提取 user/assistant │                           │
│                    │ 3. 查找 pending tasks  │                           │
│                    └───────────┬────────────┘                           │
│                                │                                        │
│                                ▼                                        │
│                    ┌────────────────────────┐                           │
│                    │   检测 Subtask?        │                           │
│                    └───────────┬────────────┘                           │
│                           ┌────┴────┐                                    │
│                          Yes      No                                     │
│                           │       │                                     │
│                           ▼       │                                     │
│                    ┌─────────────┐ │                                    │
│                    │ executeTask │ │                                    │
│                    │ (调用子Agent) │                                    │
│                    └──────┬──────┘ │                                    │
│                           │       │                                     │
│                           │       │                                     │
│                           ▼       │                                     │
│                    ┌────────────────────────┐                           │
│                    │   检测 Compaction?     │                           │
│                    └───────────┬────────────┘                           │
│                           ┌────┴────┐                                    │
│                          Yes      No                                     │
│                           │       │                                     │
│                           ▼       │                                     │
│                    ┌─────────────┐ │                                    │
│                    │  doCompact  │ │                                    │
│                    │ (上下文压缩) │ │                                    │
│                    └──────┬──────┘ │                                    │
│                           │       │                                     │
│                           │       │                                     │
│                           ▼       │                                     │
│                    ┌────────────────────────┐                           │
│                    │   检测 Overflow?       │                           │
│                    │ (token超限)           │                           │
│                    └───────────┬────────────┘                           │
│                           ┌────┴────┐                                    │
│                          Yes      No                                     │
│                           │       │                                     │
│                           ▼       │                                     │
│                    ┌─────────────┐ │                                    │
│                    │ createAuto   │ │                                    │
│                    │ Compaction   │ │                                    │
│                    └──────┬──────┘ │                                    │
│                           │       │                                     │
│                           │       │                                     │
│                           ▼       │                                     │
│                    ┌────────────────────────┐                           │
│                    │   正常处理流程         │                           │
│                    │                       │                           │
│                    │ ┌───────────────────┐ │                           │
│                    │ │ resolveTools()    │ │                           │
│                    │ │ SessionProcessor  │ │                           │
│                    │ │   .process()     │ │                           │
│                    │ │       │          │ │                           │
│                    │ │   ┌───┴───┐      │ │                           │
│                    │ │   ▼       ▼      │ │                           │
│                    │ │ LLM    工具     │ │                           │
│                    │ │       执行      │ │                           │
│                    │ └───────────────────┘ │                           │
│                    └───────────┬────────────┘                           │
│                                │                                        │
│                    ┌───────────┴───────────┐                           │
│                    │                       │                           │
│                    ▼                       ▼                           │
│           ┌─────────────┐         ┌─────────────┐                       │
│           │ result =    │         │ result =    │                       │
│           │ "stop"      │         │ "continue"   │                       │
│           └──────┬──────┘         └──────┬──────┘                       │
│                  │                       │                              │
│                  ▼                       ▼                              │
│           ┌─────────────┐         ┌─────────────┐                       │
│           │   END       │         │  继续循环   │                       │
│           │ (loop结束)  │         │  step++     │                       │
│           └─────────────┘         └──────┬──────┘                       │
│                                         │                               │
│                                         └───────────────────────────────┘

---

架构图版本: 1.0 生成时间: 2026-03-28