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

Agent/Teakenote 系统Swarm 架构深度技术报告1. 架构概述与核心概念1.1 术语定义表格术语定义技术实现Agent独立的 AI 工作单元可执行特定任务独立的 Node.js 进程或远程实例Teammate运行在本地的 Agent同机器不同窗格/进程InProcessTeammate或LocalAgentSwarmAgent 的集合协作完成复杂任务通过teammateMailbox通信的拓扑结构Leader主 Claude Code 实例协调所有 Agent当前用户交互的终端会话Coordinator特殊的规划 Agent负责任务分配CoordinatorAgent1.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 后端类型矩阵表格后端类型支持平台实现文件技术原理TmuxLinux/macOSTmuxBackend.tsTmux socket 通信窗格管理iTerm2macOSITermBackend.tsPython API (it2run) 或 AppleScriptWindows TerminalWindows集成在PaneBackendExecutor.tsWindows Pseudo Console APIIn-Process全平台InProcessBackend.tsNode.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.tsit2Setup.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.tsspawnUtils.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.tsdirectMemberMessage.ts)消息传递系统表格通信方式适用场景实现延迟IPC (Inter-Process Communication)In-Process AgentNode.jsprocess.send() 1msNamed Pipes同机跨进程Unix domain socket / Windows named pipe~5msTmux BufferTmux 模式tmux load-buffer/tmux paste-buffer~50msSocket网络隔离环境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: 权限向上委托给 Leader3.3 状态同步机制 (teammateModel.tspermissionSync.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-size4.2 内置 Agent 类型 (built-in/)表格Agent 类型职责专用工具实现文件探索者(exploreAgent)代码库分析、依赖梳理FileRead, Grep, GlobexploreAgent.ts规划者(planAgent)任务拆解、依赖排序TaskCreate, TodoWriteplanAgent.ts实现者(generalPurposeAgent)代码编写、重构FileEdit, BashgeneralPurposeAgent.ts验证者(verificationAgent)测试、审查、安全检查Bash (test), LSPToolverificationAgent.ts指导者(claudeCodeGuideAgent)用户引导、最佳实践WebFetch, BriefclaudeCodeGuideAgent.tsstatuslineSetup.ts- Agent 状态栏集成在 Leader 的状态栏显示各 Agent 进度颜色编码 空闲 工作中 错误点击跳转在 Tmux 中聚焦到对应窗格4.3 Agent 记忆管理 (agentMemory.tsagentMemorySnapshot.ts)记忆隔离与共享Agent A 记忆空间 (隔离) ├── 短期记忆当前任务上下文 ├── 中期记忆本次会话的操作历史 └── 长期记忆跨会话的项目知识 (memdir/) 共享空间 (teamMemory/) ├── 共享发现代码库结构分析结果 ├── 共享规范项目编码规范 └── 共享 TODO团队任务列表teamMemoryOps.ts- 团队记忆操作读写冲突解决Last-Write-Wins (LWW) 策略同步触发Agent 完成子任务后自动推送更新秘密扫描(secretScanner.ts)防止 API Key 等写入共享记忆5. 任务调度与协调 (src/tasks/)5.1 任务类型架构表格任务类型文件特性LocalMainSessionTaskLocalMainSessionTask.tsLeader 的主任务循环LocalAgentTaskLocalAgentTask/本地 Agent 任务执行LocalShellTaskLocalShellTask/Shell 命令包装Kill 信号处理InProcessTeammateTaskInProcessTeammateTask/进程内轻量任务RemoteAgentTaskRemoteAgentTask/远程 Agent网络通信DreamTaskDreamTask/后台梦境任务离线思考5.2 后台任务系统 (BackgroundTask.tsxBackgroundTasksDialog.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/OpusMemoryStep- 配置记忆策略隔离/共享MethodStep- 执行方式In-Process/Tmux/RemoteLocationStep- 工作目录设置ColorStep- 分配颜色标识状态栏显示GenerateStep- AI 辅助生成 Agent 配置可选ConfirmStep- 预览并确认创建AgentNavigationFooter.tsx- 向导导航步骤验证未完成必填项阻止前进草稿保存意外退出后可恢复6.2 Agent 监控界面InProcessTeammateDetailDialog.tsx- 进程内 Agent 详情实时日志流WebSocket 推送Token 使用量监控上下文窗口使用率防止溢出手动干预按钮暂停/终止/调整参数AsyncAgentDetailDialog.tsx- 异步 Agent 监控进度条基于子任务完成数预估剩余时间基于历史速度产物预览生成的文件列表DreamDetailDialog.tsx- 梦境任务离线思考触发条件用户离开时自动启动处理内容代码库索引、记忆整理、依赖更新检查结果呈现下次启动时汇总报告6.3 团队视图 (TeamsDialog.tsxTeamStatus.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) 时立即停止并报告 Leader8. 协调者模式 (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 网络中断处理远程 AgentSessionsWebSocket.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 技术突破表格特性传统单 AgentClaude Code Swarm并行度单线程顺序执行多进程并行受限于硬件专业化通用提示词角色专用 Agent探索/编码/测试可靠性单点故障故障转移、自动重试可观测性黑盒实时多 Agent 监控、干预规模化上下文受限分片处理、结果聚合11.2 架构设计哲学终端原生与 Tmux/iTerm 深度集成而非自建窗口系统进程隔离利用 OS 进程隔离保证安全而非纯 JS 沙盒Leader 集权权限、协调集中管理避免分布式共识复杂性渐进式复杂度单 Agent 可用多 Agent 增强不强求分布式11.3 局限与改进方向跨机器支持目前主要单机多进程跨网络 Agent 需配合bridge/模块Agent 间直接通信目前主要通过 Leader 中继P2P 通信待优化成本管理多 Agent 并行显著增加 API 调用成本需更智能的 Agent 数量控制