用 SwiftUI 构建一个 Agent 可视化工作台

每一步执行都实时显示在时间线上——文本输出、工具调用、执行结果、错误信息全部可视化这不是一个终端里的 CLI 工具也不是一个网页应用。它是用 SwiftUI 写的原生 macOS 应用用Observable做状态管理用 SwiftData 做数据持久化用 Apple 原生的渲染管线做 Markdown 和代码高亮。为什么做 SwiftWork做 SwiftWork 有两个动机。第一SDK 需要一个展示应用。SDK 的 31 个示例项目覆盖了各种用法——流式输出、自定义工具、MCP 集成——但都是命令行工具。SDK 的能力需要一个 GUI 来完整展示尤其是工具调用的可视化、事件流的实时渲染这些 CLI 做不好的事情。第二Agent 应用的可视化是一个被低估的问题。当前的 Agent 应用包括 Claude Code 自己在终端里跑用户看到的是滚动的文字流。但 Agent 在执行一个复杂任务时可能调用十几次工具、读写多个文件、执行多条命令。终端里的线性输出很难让用户理解全局进展。SwiftWork 试图用事件时间线和工具卡片来改善这个问题。架构总览SwiftWork 采用事件驱动架构。整条数据流是一条单向管线SDK Agent Loop │ │ AsyncStreamSDKMessage ▼ AgentBridge (Observable) │ │ EventMapper.map() → AgentEvent ▼ AgentBridge.events: [AgentEvent] │ │ SwiftUI 自动响应 Observable 变化 ▼ TimelineView → 各 EventView四个角色组件职责Agent LoopSDK 提供跑 Agent 的推理循环产出SDKMessage流AgentBridge消费AsyncStreamSDKMessage映射成AgentEvent管理生命周期EventMapper纯函数SDKMessage → AgentEvent的类型映射TimelineViewSwiftUI 视图消费AgentEvent数组渲染时间线核心设计决策视图不直接接触 SDK 类型。AgentEvent是 SwiftWork 自己定义的 UI 模型跟 SDK 的SDKMessage完全解耦。视图只认AgentEvent不知道也不关心事件来自哪个 SDK 版本。核心数据流用户发一条消息整条管线的运转过程1. 用户输入 → Agent 启动// AgentBridge.swift func sendMessage(_ text: String) { // 用户消息直接追加到事件列表 let userEvent AgentEvent(type: .userMessage, content: text, timestamp: .now) appendAndPersist(userEvent) isRunning true // 在后台 Task 中消费 stream currentTask Task { [weak self] in let stream agent.stream(text) for await message in stream { let event EventMapper.map(message) self.appendAndPersist(event) } self.isRunning false } }用户消息先追加到事件列表即时显示然后启动一个Task来消费 SDK 的AsyncStream。2. SDKMessage → AgentEventEventMapper是一个纯函数把 SDK 的 18 种SDKMessage映射成 SwiftWork 的AgentEventType// EventMapper.swift static func map(_ message: SDKMessage) - AgentEvent { switch message { case .assistant(let data): return AgentEvent(type: .assistant, content: data.text, metadata: [model: data.model, stopReason: data.stopReason], timestamp: .now) case .toolUse(let data): return AgentEvent(type: .toolUse, content: data.toolName, metadata: [toolName: data.toolName, toolUseId: data.toolUseId, input: data.input], timestamp: .now) case .toolResult(let data): return AgentEvent(type: .toolResult, content: data.content, metadata: [toolUseId: data.toolUseId, isError: data.isError], timestamp: .now) // ... 18 种消息类型 } }为什么要有这一层映射因为 SDK 的类型是给 Agent 运行时用的它包含很多 UI 不需要的细节。AgentEvent只保留 UI 渲染需要的字段类型、内容、元数据、时间戳。视图不需要知道SDKMessage的枚举定义只需要处理AgentEventType。3. 事件追加 持久化每条事件都经过appendAndPersist同时更新内存数组和 SwiftData 数据库private func appendAndPersist(_ event: AgentEvent) { events.append(event) processToolContentMap(for: event) guard event.type ! .partialMessage, let eventStore, let currentSession else { return } try eventStore.persist(event, session: currentSession, order: eventOrder) eventOrder 1 trimOldEvents() }注意partialMessage不持久化——它是流式文本的中间片段累积完成后会生成一条完整的.assistant事件。4. SwiftUI 自动渲染AgentBridge标记了Observable。当events数组变化时TimelineView自动重新渲染// TimelineView.swift ForEach(virtualizedEvents) { event in eventView(for: event) }eventView根据event.type分派到不同的视图组件——UserMessageView、AssistantMessageView、ToolCardView、SystemEventView等。项目结构SwiftWork/ ├── App/ │ ├── SwiftWorkApp.swift # main 入口注册 SwiftData 模型 │ └── ContentView.swift # NavigationSplitView 根视图 ├── Models/ │ ├── UI/ # UI 模型层 │ │ ├── AgentEvent.swift # 事件模型SwiftUI 渲染用 │ │ ├── AgentEventType.swift # 18 种事件类型枚举 │ │ ├── ToolContent.swift # 工具内容配对 toolUse toolResult │ │ ├── PermissionDecision.swift # 权限决策 │ │ └── AppError.swift # 错误模型 │ └── SwiftData/ # 持久化模型层 │ ├── Session.swift # 会话 │ ├── Event.swift # 持久化事件 │ ├── AppConfiguration.swift # 应用配置 │ └── PermissionRule.swift # 权限规则 ├── ViewModels/ │ ├── SessionViewModel.swift # 会话 CRUD │ └── SettingsViewModel.swift # 设置管理 ├── Views/ │ ├── Sidebar/ # 会话列表 │ ├── Workspace/ │ │ ├── Timeline/ │ │ │ ├── TimelineView.swift # 时间线主视图 虚拟化 │ │ │ ├── EventViews/ # 各事件类型视图 ToolCardView │ │ │ │ ├── ToolRenderers/ # 5 个内置工具渲染器 │ │ │ │ ├── StreamingTextView.swift │ │ │ │ ├── MarkdownContentView.swift │ │ │ │ └── ... │ │ │ └── Inspector/ # 事件详情面板 │ │ └── InputBar/ # 消息输入框 │ ├── Settings/ # 设置界面 │ ├── Onboarding/ # 首次启动引导 │ └── Permission/ # 权限审批弹窗 ├── SDKIntegration/ │ ├── AgentBridge.swift # SDK ↔ ViewModel 桥接 │ ├── AgentBridgeToolContentMap.swift # 工具内容配对逻辑 │ ├── EventMapper.swift # SDKMessage → AgentEvent │ ├── ToolRenderable.swift # 工具渲染协议 │ └── ToolRendererRegistry.swift # 工具渲染注册表 ├── Services/ │ ├── CodeHighlighter.swift # Splash 代码高亮 │ ├── MarkdownRenderer.swift # swift-markdown 渲染 │ ├── KeychainManager.swift # API Key 安全存储 │ ├── EventStore.swift # 事件持久化接口 │ ├── AppStateManager.swift # 应用状态保存/恢复 │ └── TitleGenerator.swift # 自动生成会话标题 └── Utils/ └── Extensions/ # 颜色、日期格式化等结构上的核心分层Models/UI/和Models/SwiftData/是两套独立的模型层。UI 模型AgentEvent是给 SwiftUI 渲染用的SwiftData 模型Event是给持久化用的。两者之间有转换逻辑。SDKIntegration/是 SDK 和 UI 之间的桥梁层。视图和 ViewModel 不直接 importOpenAgentSDK。Views/按功能分区每个事件类型一个视图文件工具渲染器有独立的子目录。技术选型组件选择原因语言Swift 6.1 严格并发Agent SDK 要求Sendable保证线程安全UISwiftUI ObservablemacOS 14 支持跟 Swift 并发配合好持久化SwiftData跟 SwiftUI 深度集成比 Core Data 简洁Markdownswift-markdown (Apple)原生 Apple 库CommonMark 兼容代码高亮Splash (John Sundell)轻量、支持 Swift/Python/JS/Bash自动更新Sparkle 2.xmacOS 应用更新的标准方案Agent SDKOpen Agent SDK自己写的 SDK当然用自己的