Agent/Teakenote 系统（Swarm 架构）深度技术报告

1. 架构概述与核心概念

1.1 术语定义

表格

术语	定义	技术实现
Agent	独立的 AI 工作单元，可执行特定任务	独立的 Node.js 进程或远程实例
Teammate	运行在本地的 Agent（同机器不同窗格/进程）	`InProcessTeammate` 或 `LocalAgent`
Swarm	Agent 的集合，协作完成复杂任务	通过 `teammateMailbox` 通信的拓扑结构
Leader	主 Claude Code 实例，协调所有 Agent	当前用户交互的终端会话
Coordinator	特殊的规划 Agent，负责任务分配	`CoordinatorAgent`

1.2 架构定位

plain

复制代码

用户终端 (Leader)
    │
    ├──→ Agent 1 (探索者) ───────┐
    │   ├── Tmux Pane 1            │
    │   └── 任务：分析代码结构     │
    │                              │
    ├──→ Agent 2 (实现者) ───────┼──→ 共享状态 (teamMemory/)
    │   ├── Tmux Pane 2            │
    │   └── 任务：编写功能代码     │
    │                              │
    └──→ Agent 3 (测试者) ───────┘
        ├── Tmux Pane 3
        └── 任务：生成测试用例
    
    协调方式：
    ├── 广播消息 (broadcast)
    ├── 点对点消息 (direct message)
    └── 共享存储 (team memory sync)

2. 核心实现架构

2.1 Swarm 后端系统 (`src/utils/swarm/`)

这是 Swarm 架构的基础设施层，负责与终端模拟器集成：

2.1.1 后端类型矩阵

表格

后端类型	支持平台	实现文件	技术原理
Tmux	Linux/macOS	`TmuxBackend.ts`	Tmux socket 通信，窗格管理
iTerm2	macOS	`ITermBackend.ts`	Python API (`it2run`) 或 AppleScript
Windows Terminal	Windows	集成在 `PaneBackendExecutor.ts`	Windows Pseudo Console API
In-Process	全平台	`InProcessBackend.ts`	Node.js Worker Threads / 子进程

2.1.2 Tmux 集成深度分析 (`TmuxBackend.ts`)

技术实现：

TypeScript

复制代码

// Tmux 控制流程：
1. 检测现有 Tmux 会话 (TMUX 环境变量)
2. 若无，创建新会话: tmux new-session -s claude-swarm
3. 创建窗格: tmux split-window -t claude-swarm
4. 启动 Agent: tmux send-keys -t claude-swarm.1 "claude --agent-mode" Enter
5. 通信协议: tmux pipe-pane 捕获输出

关键文件：

tmuxSocket.ts - Tmux socket 路径管理（支持多用户隔离）
detection.ts - Tmux 版本检测（功能适配，如检查是否支持特定命令）
teammateLayoutManager.ts - 窗格布局算法（垂直/水平分屏优化）

窗格布局算法：

TypeScript

复制代码

// 智能布局策略：
if (agentCount <= 2) {
  // 2 个 Agent：左右分屏 (50%/50%)
  layout = 'horizontal-split';
} else if (agentCount <= 4) {
  // 3-4 个 Agent：田字格布局
  layout = 'quad-split';
} else {
  // 5+ 个 Agent：堆叠标签页（通过窗口切换）
  layout = 'tabbed';
}

2.1.3 iTerm2 集成 (`ITermBackend.ts` & `it2Setup.ts`)

macOS 专属优化：

AppleScript 控制：创建分屏、发送命令
Python API (it2run)：高性能通信，避免 AppleScript 延迟
图像支持：利用 iTerm2 的 inline image protocol 显示 Agent 状态

It2SetupPrompt.tsx - 首次使用引导：

检测 iTerm2 是否安装
请求 Accessibility 权限（macOS 安全）
下载/配置 it2run 工具

3. Agent 生命周期管理

3.1 Agent 创建流程 (`src/utils/swarm/spawnInProcess.ts` & `spawnUtils.ts`)

进程创建架构：

复制代码

Leader 进程
    │
    spawn('claude', ['--agent-mode', '--parent-session', 'xxx'], {
      env: {
        CLAUDE_AGENT_ROLE: 'explorer',
        CLAUDE_TEAM_ID: 'team-uuid',
        CLAUDE_LEADER_PID: process.pid,
        // 继承 API Key 等凭证
      },
      stdio: ['pipe', 'pipe', 'pipe', 'ipc'] // IPC 通道
    })
    │
    ├─→ Agent 进程 (Node.js 子进程)
    │    ├─→ 初始化 Agent 上下文 (teammateInit.ts)
    │    ├─→ 连接 team mailbox (teammateMailbox.ts)
    │    └─→ 向 Leader 发送 ready 信号
    │
    └─→ Leader 维护 PID 映射表 (teammateContext.ts)

inProcessRunner.ts - 进程内执行优化：

使用 worker_threads 而非子进程（更低开销）
共享内存（避免消息序列化开销）
适用于轻量级 Agent（简单查询类任务）

3.2 Agent 通信协议 (`teammateMailbox.ts` & `directMemberMessage.ts`)

消息传递系统：

表格

通信方式	适用场景	实现	延迟
IPC (Inter-Process Communication)	In-Process Agent	Node.js `process.send()`	< 1ms
Named Pipes	同机跨进程	Unix domain socket / Windows named pipe	~5ms
Tmux Buffer	Tmux 模式	`tmux load-buffer` / `tmux paste-buffer`	~50ms
Socket	网络隔离环境	TCP/Unix socket	网络依赖

消息类型定义：

复制代码

// teammateMailbox.ts
interface TeamMessage {
  type: 'task' | 'result' | 'broadcast' | 'query' | 'shutdown';
  from: string;        // Agent ID
  to?: string;         // 目标 Agent（广播时为空）
  payload: unknown;
  timestamp: number;
  priority: 'high' | 'normal' | 'low';
}

// 特殊消息：
// - heartbeat: 存活检测
// - context-sync: 共享记忆同步
// - permission-request: 权限向上委托给 Leader

3.3 状态同步机制 (`teammateModel.ts` & `permissionSync.ts`)

Agent 状态机：

复制代码

┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ Standby │ → │ Working  │ → │ Paused  │ → │ Resuming│ → │Completed│
└─────────┘    └──────────┘    └─────────┘    └─────────┘    └─────────┘
    ↑              │               │              │               │
    └──────────────┴──────────────┴──────────────┴──────────→ 失败
                                                         (Error)

permissionSync.ts - 权限状态同步：

Leader 集权：所有权限决策由 Leader 代理
权限缓存：Agent 缓存最近 5 分钟的权限决策（减少询问延迟）
规则继承 ：Agent 继承 Leader 的 .claudepermissions 规则

4. Agent 工具系统 (`src/tools/AgentTool/`)

4.1 Agent 派遣实现 (`AgentTool.tsx`)

这是用户通过自然语言创建 Agent 的入口：

复制代码

// 用户输入: "@探索者 分析这个代码库的架构"
// 解析流程：
1. 识别 @mention → 提取 Agent 名称/角色
2. 查询 Agent 定义 (loadAgentsDir.ts / builtInAgents.ts)
3. 创建 Agent 配置：
   {
     role: 'explorer',
     model: 'claude-3-opus',  // 可为不同 Agent 分配不同模型
     permissions: 'read-only', // 限制权限
     workingDirectory: '/path/to/repo',
     systemPrompt: '你是一位架构分析专家...'
   }
4. 调用 forkSubagent.ts 创建进程
5. 分配任务 (runAgent.ts)

forkSubagent.ts - 进程分叉细节：

写时复制 (COW)：利用操作系统 COW 减少内存占用
环境隔离 ：每个 Agent 独立的 NODE_OPTIONS，避免相互影响
资源限制 ：可选的内存限制（--max-old-space-size）

4.2 内置 Agent 类型 (`built-in/`)

表格

Agent 类型	职责	专用工具	实现文件
探索者 (exploreAgent)	代码库分析、依赖梳理	FileRead, Grep, Glob	`exploreAgent.ts`
规划者 (planAgent)	任务拆解、依赖排序	TaskCreate, TodoWrite	`planAgent.ts`
实现者 (generalPurposeAgent)	代码编写、重构	FileEdit, Bash	`generalPurposeAgent.ts`
验证者 (verificationAgent)	测试、审查、安全检查	Bash (test), LSPTool	`verificationAgent.ts`
指导者 (claudeCodeGuideAgent)	用户引导、最佳实践	WebFetch, Brief	`claudeCodeGuideAgent.ts`

statuslineSetup.ts - Agent 状态栏集成：

在 Leader 的状态栏显示各 Agent 进度
颜色编码：🟢 空闲 🟡 工作中 🔴 错误
点击跳转：在 Tmux 中聚焦到对应窗格

4.3 Agent 记忆管理 (`agentMemory.ts` & `agentMemorySnapshot.ts`)

记忆隔离与共享：

复制代码

Agent A 记忆空间 (隔离)
├── 短期记忆：当前任务上下文
├── 中期记忆：本次会话的操作历史
└── 长期记忆：跨会话的项目知识 (memdir/)

共享空间 (teamMemory/)
├── 共享发现：代码库结构分析结果
├── 共享规范：项目编码规范
└── 共享 TODO：团队任务列表

teamMemoryOps.ts - 团队记忆操作：

读写冲突解决：Last-Write-Wins (LWW) 策略
同步触发：Agent 完成子任务后自动推送更新
秘密扫描 (secretScanner.ts)：防止 API Key 等写入共享记忆

5. 任务调度与协调 (`src/tasks/`)

5.1 任务类型架构

表格

任务类型	文件	特性
LocalMainSessionTask	`LocalMainSessionTask.ts`	Leader 的主任务循环
LocalAgentTask	`LocalAgentTask/`	本地 Agent 任务执行
LocalShellTask	`LocalShellTask/`	Shell 命令包装（Kill 信号处理）
InProcessTeammateTask	`InProcessTeammateTask/`	进程内轻量任务
RemoteAgentTask	`RemoteAgentTask/`	远程 Agent（网络通信）
DreamTask	`DreamTask/`	后台梦境任务（离线思考）

5.2 后台任务系统 (`BackgroundTask.tsx` & `BackgroundTasksDialog.tsx`)

异步任务架构：

任务队列：优先级队列（高优先级任务抢占）
资源限制：并发 Agent 数量限制（默认 CPU 核心数）
持久化：任务状态写入磁盘（支持跨会话恢复）

pillLabel.ts - 任务标签系统：

复制代码

// 任务分类标签：
{
  type: 'coding' | 'testing' | 'review' | 'documentation',
  urgency: 'blocking' | 'background',
  estimatedDuration: 'short' | 'medium' | 'long'
}

5.3 任务结果聚合 (`renderToolActivity.tsx`)

多 Agent 结果汇总：

代码合并：多个 Agent 修改同一文件时的冲突解决
测试汇总：并行测试结果的合并报告
审查汇总：多维度代码审查结果聚合（性能/安全/风格）

6. UI 与交互 (`src/components/agents/` & `src/components/tasks/`)

6.1 Agent 创建向导 (`CreateAgentWizard.tsx`)

多步骤表单（11 步）：

TypeStep - 选择 Agent 类型（内置/自定义）
DescriptionStep - 描述 Agent 职责
PromptStep - 编辑 System Prompt（支持模板）
ToolsStep - 选择可用工具集（FileEdit/Bash/WebFetch 等）
ModelStep - 选择底层模型（Haiku/Sonnet/Opus）
MemoryStep - 配置记忆策略（隔离/共享）
MethodStep - 执行方式（In-Process/Tmux/Remote）
LocationStep - 工作目录设置
ColorStep - 分配颜色标识（状态栏显示）
GenerateStep - AI 辅助生成 Agent 配置（可选）
ConfirmStep - 预览并确认创建

AgentNavigationFooter.tsx - 向导导航：

步骤验证（未完成必填项阻止前进）
草稿保存（意外退出后可恢复）

6.2 Agent 监控界面

InProcessTeammateDetailDialog.tsx - 进程内 Agent 详情：

实时日志流（WebSocket 推送）
Token 使用量监控
上下文窗口使用率（防止溢出）
手动干预按钮（暂停/终止/调整参数）

AsyncAgentDetailDialog.tsx - 异步 Agent 监控：

进度条（基于子任务完成数）
预估剩余时间（基于历史速度）
产物预览（生成的文件列表）

DreamDetailDialog.tsx - 梦境任务（离线思考）：

触发条件：用户离开时自动启动
处理内容：代码库索引、记忆整理、依赖更新检查
结果呈现：下次启动时汇总报告

6.3 团队视图 (`TeamsDialog.tsx` & `TeamStatus.tsx`)

拓扑可视化：

复制代码

Leader (你)
├─ Agent 1 [🟢 空闲] [explorer] 
│  └─ 最近活动：分析了 src/utils/ (2分钟前)
│
├─ Agent 2 [🟡 工作中] [coder]
│  └─ 当前任务：重构 auth.ts (预计 5分钟)
│  └─ 进度：███░░░░░░░ 30%
│
└─ Agent 3 [🔴 错误] [tester]
   └─ 状态：测试失败 (点击查看日志)

7. 权限与安全管理 (`leaderPermissionBridge.ts`)

7.1 权限委托架构

代理权限流程：

复制代码

Agent (请求 FileWrite)
    ↓
检查本地权限缓存 (5分钟 TTL)
    ↓
未命中 → 通过 IPC 发送给 Leader
    ↓
Leader 弹出 PermissionDialog
    ↓
用户决策 → 广播给所有相关 Agent
    ↓
更新权限缓存 (permissionSync.ts)

leaderPermissionBridge.ts - 桥接实现：

请求队列：避免 Leader UI 被大量权限请求淹没（批量展示）
决策传播：Leader 的权限规则变更实时同步到所有 Agent
紧急模式：Agent 可标记紧急请求（弹窗置顶）

7.2 沙盒与隔离 (`utils/permissions/` 集成)

Agent 隔离级别：

表格

级别	范围	实现方式
宽松	继承 Leader 全部权限	仅通过 JS 对象隔离
标准	只读 + 指定目录写入	chroot + 权限规则
严格	完全沙盒	Docker 容器（若可用）

teammatePromptAddendum.ts - Agent 安全提示：

每个 Agent 的 System Prompt 追加安全约束

复制代码

[安全约束]
1. 你只能访问 ${WORKING_DIR} 目录
2. 禁止执行破坏性命令 (rm -rf, git reset --hard 等)
3. 发现敏感信息 (.env, API keys) 时立即停止并报告 Leader

8. 协调者模式 (Coordinator Mode)

8.1 协调者 Agent (`src/coordinator/coordinatorMode.ts`)

复杂任务自动化协调：

复制代码

用户输入：重构整个项目架构
    ↓
Coordinator Agent 启动
    ↓
1. 分析阶段：派遣探索者 Agent 分析现状
2. 规划阶段：生成重构计划（任务依赖图）
3. 执行阶段：
   ├─ 派遣 Agent A 重构模块 1 (独立)
   ├─ 派遣 Agent B 重构模块 2 (独立)
   ├─ 派遣 Agent C 更新接口 (依赖 A,B 完成)
   └─ 派遣 Agent D 生成测试 (依赖 C)
4. 验证阶段：派遣验证者检查整体一致性
5. 提交阶段：生成 PR 摘要（汇总所有变更）

依赖调度算法：

DAG (有向无环图) 任务调度
关键路径优化：优先调度阻塞后续任务的 Agent
动态负载均衡：根据 Agent 历史速度调整任务分配

9. 故障恢复与重连 (`reconnection.ts`)

9.1 Agent 崩溃恢复

检测机制：

心跳检测：每 30 秒 Agent 发送 heartbeat
进程监控 ：Leader 监听 child_process.on('exit')
输出监控：检测 "Fatal Error" / "Out of Memory" 等关键字

恢复策略：

复制代码

// reconnection.ts
if (agentCrash) {
  if (retryCount < 3 && taskIdempotent) {
    // 1. 重试：重启 Agent 重新执行相同任务
    restartAgent();
  } else if (checkpointExists) {
    // 2. 恢复：从最近检查点继续（需任务支持断点续传）
    resumeFromCheckpoint();
  } else {
    // 3. 降级：将任务转交给 Leader 或其他 Agent
    escalateToLeader();
  }
}

9.2 网络中断处理（远程 Agent）

SessionsWebSocket.ts 集成：

WebSocket 断线检测（ping/pong）
自动重连（指数退避）
消息队列：断线期间消息本地持久化，重连后批量同步

10. 性能优化与资源管理

10.1 内存管理 (`utils/memory/` 集成)

Agent 内存策略：

内存限额：单个 Agent 默认 512MB，可配置
OOM 防护：监控内存使用，接近上限时触发会话压缩
共享内存 ：多个 Agent 读取相同文件时，通过 fileReadCache.ts 共享缓存

10.2 并发控制

useSwarmInitialization.ts - 启动优化：

渐进式启动：避免同时启动 10+ Agent 导致 CPU spike
模型降级：高并发时，次要 Agent 使用轻量级模型 (Haiku)
I/O 节流：限制同时进行的文件系统操作数（避免 IO 阻塞）

10.3 上下文优化

agentMemorySnapshot.ts - 快照机制：

Agent 定期向 Leader 发送上下文摘要（而非完整历史）
Leader 维护全局上下文视图，避免每个 Agent 重复加载大上下文

11. 总结：Swarm 架构的工程价值

11.1 技术突破

表格

特性	传统单 Agent	Claude Code Swarm
并行度	单线程顺序执行	多进程并行（受限于硬件）
专业化	通用提示词	角色专用 Agent（探索/编码/测试）
可靠性	单点故障	故障转移、自动重试
可观测性	黑盒	实时多 Agent 监控、干预
规模化	上下文受限	分片处理、结果聚合

11.2 架构设计哲学

终端原生：与 Tmux/iTerm 深度集成，而非自建窗口系统
进程隔离：利用 OS 进程隔离保证安全，而非纯 JS 沙盒
Leader 集权：权限、协调集中管理，避免分布式共识复杂性
渐进式复杂度：单 Agent 可用，多 Agent 增强，不强求分布式

11.3 局限与改进方向

跨机器支持 ：目前主要单机多进程，跨网络 Agent 需配合 bridge/ 模块
Agent 间直接通信：目前主要通过 Leader 中继，P2P 通信待优化
成本管理：多 Agent 并行显著增加 API 调用成本，需更智能的 Agent 数量控制

Agent/Teakenote 系统（Swarm 架构）深度技术报告