最近两周我一直在打磨一个叫 SwiftUI-Agent-Skill 的侧项目。它不是一个完整 App而更像一套把 AI 智能体Agent和 SwiftUI 结合起来的可复用骨架SwiftUI 负责声明界面状态Agent 负责理解输入Skill 模块负责执行具体动作。做这个项目的起因是之前写过几个 AI 工具类 Demo界面一复杂逻辑就开始乱所以我拆出来这套协议 注册表 调度的结构给同样在苹果生态里做智能应用的朋友一个参考。如果你正准备在 iOS 或 macOS 上做“自然语言触发任务”的小工具这篇文章应该能帮你省下不少试错时间。1. 为什么要拆Agent 和 UI 糊在一起有多痛1.1 我最初失败的“语音备忘录”第一次想做类似的东西时我图省事把 Agent 和 UI 写在了同一个 View Model 里。流程是这样的麦克风录音把音频转成文本文本直接丢给模型模型返回一段 JSON然后 View 的.task里解析 JSON再执行“写日记”“建日程”之类的副作用。听起来没问题但真实场景一多就崩了。第一个痛点每一个新动作都要在 View 里加一堆switch分支比如“如果是 scheduleEvent 就跳转日历页”“如果是 createNote 就打开编辑器”“如果是 setTimer 就启动 Timer”。第二个痛点网络请求、权限弹窗、数据库写入全混在视图生命周期里界面切到后台再回来任务不知道被系统取消了几次。第三个痛点最致命——预览彻底废了因为 View 初始化时必须注入一堆外部依赖没发起网络请求就已经崩溃。后来我把代码狠心砍掉重写才意识到问题根本不是“写起来不够简洁”而是没有把“识别”和“执行”拆开。界面应该只负责一件事把你的话传给 Agent再把 Agent 的结果变成用户能看懂的内容。至于这句话到底触发什么动作、动作怎么做、做完了返回什么都不该由视图来决定。1.2 上层只管“意图”下层只管“执行”想清楚之后我把整个结构分成了三层最上层是 SwiftUI 视图它只发送用户文本并显示消息列表和处理状态。中间是 Agent它维护技能注册表、消息历史和执行状态负责把自然语言“路由”到合适的 Skill。最底层是 Skill每个技能是一个独立模块只负责完成一件具体的事比如“创建日历事件”“查询天气”“设置提醒”。这样改完再往 Agent 里加新能力我只需要写一个新的 Skill 实现然后在启动时register进去。视图、Agent、其他技能完全不用改动。后面做到第五个技能时新增功能的时间从原来的大半天缩短到了半小时左右而且基本上不会把原有逻辑弄坏。1.3 为什么不全用苹果自带组件有朋友问我苹果不是已经提供了 App Intents、SiriKit 这些系统能力吗为什么还要自己造一套。我的理解是它们非常适合做“系统级快捷指令”和“Siri 集成”但如果你想要一个完全在 App 内运行的、支持多轮对话和自定义技能的智能助手系统框架会显得很重而且很难做“中间确认”和“动态路由”这类交互。举个具体例子我想让 Agent 先问一句“你要创建的是明天下午三点的项目评审吗”然后再写日历。系统组件通常是一次性执行不太方便做这种带确认流的双向交互。自己定义一套 Skill 协议后这个确认步骤就成了一个普通的AgentState枚举状态想怎么插入 UI 都可以。从那次重构开始我就确定了一条原则凡是可能频繁扩展的行为全部做成协议 注册表而不是做成 switch-case 分支。这也是 SwiftUI-Agent-Skill 这套设计里最重要的一条经验。2. 核心设计Skill 协议、注册表与调度器2.1 协议的最小化定义别让口袋太重很多人设计“技能系统”时容易犯一个错误把协议定义得特别大塞进一堆用不到的方法。结果每加一个新 Skill 都要实现一堆空方法特别劝退。我最后保留的最小协议长这样import Foundation // 技能执行完成后的统一输出 enum SkillOutput { case text(String) case calendarEvent(title: String, startDate: Date) case weather(city: String, temperature: Double, condition: String) case reminder(title: String, date: Date) } // 技能抛出的业务错误 enum SkillError: Error { case missingArgument(String) case permissionDenied case executionFailed(String) } // 每个具体技能必须遵循的协议 protocol Skill: AnyObject { var id: String { get } var displayName: String { get } var desc: String { get } var samplePhrases: [String] { get } var requiresUserConfirmation: Bool { get } func canHandle(_ userInput: String) - Bool func extractArguments(from userInput: String) - [String: String] func execute(arguments: [String: String]) async throws - SkillOutput }仔细看这个协议里没有“技能输出 UI 组件”这种字段也没有“技能自己的设置页面”。原因是技能不应该知道 UI 怎么展示它只需要返回一个语义化的SkillOutput由 Agent 层统一渲染成文本。假如将来某个技能想返回图片或自定义列表你可以在SkillOutput里增加一个枚举 case而不是让每个技能去依赖 SwiftUI 类型。samplePhrases是我在调试中发现最值得加的字段。它不给用户看也不参与核心逻辑主要给调度层做关键词匹配以及给开发预览时快速填充测试输入。更进阶的用法是把这些短语集合起来作为提示词示例传给模型做意图识别。2.2 技能注册表与调度器让技能自己报名有了协议下一步就是让技能“自己报名”。注册表非常简单就是一个字典技能 id 对应技能实例。MainActor Observable final class Agent { enum Phase: Equatable { case idle case processing case waitingConfirmation(PendingAction) } private(set) var skills: [String: any Skill] [:] private(set) var messages: [ChatMessage] [] var phase: Phase .idle func register(_ skill: any Skill) { skills[skill.id] skill } func send(_ text: String) async { messages.append(ChatMessage(role: .user, content: text)) phase .processing guard let skill selectSkill(for: text) else { messages.append(ChatMessage(role: .agent, content: 我还没有掌握处理这句话的能力)) phase .idle return } let arguments skill.extractArguments(from: text) do { let output try await skill.execute(arguments: arguments) try await confirmIfNeeded(skill: skill, output: output) let reply render(output) messages.append(ChatMessage(role: .agent, content: reply)) } catch { let message friendlyMessage(for: error) messages.append(ChatMessage(role: .agent, content: message)) } phase .idle } private func selectSkill(for text: String) - (any Skill)? { skills.values .filter { $0.canHandle(text) } .max { skillScore($0, text) skillScore($1, text) } } private func skillScore(_ skill: any Skill, text: String) - Int { var score 0 for phrase in skill.samplePhrases { let tokens phrase.split(separator: ) if tokens.allSatisfy({ text.contains($0) }) { score 2 } } if !skill.extractArguments(from: text).isEmpty { score 1 } return score } }这里有个容易被忽略的细节selectSkill不是直接把所有canHandle返回 true 的技能拿出来而是还要给它们打分。原因很简单——多个技能可能同时声称自己能处理同一句话。比如“明天下午三点提醒我开会”日历技能和提醒技能都觉得自己能处理这时候如果不打分结果就变成随机命中体感非常差。我用的打分维度很朴素命中一条 samplePhrase 得 2 分能成功抽取到参数再加 1 分。日常演示足够了。如果你接了真正的模型服务可以把文本、可用技能列表和 samplePhrases 一起发给模型让模型返回一个技能 id。规则打分的优势是零延迟、可离线劣势是泛化能力一般。我现在的做法是“规则为主模型兜底”后续会细说。2.3 状态管理选了 Observable 而不是 ObservableObject这个项目是 iOS 17 起的所以我直接用Observable宏代替了ObservableObject和Published。老写法的问题在于只要Published属性变了所有观察它的视图都会刷新哪怕那个视图只关心另一个字段。Agent 对象里有skills、messages、phase三个维度如果用Published标记messagesUI 上连“正在处理”状态的旋转圈都会被无关的消息更新抖动。Observable会在属性层面做粒度追踪视图只读它实际用到的属性刷新范围小很多。实际代码中我用State持有 Agent 实例而不是EnvironmentObject。因为 Agent 的生命周期和页面严格绑定暂时没有跨页面共享的需求。以后如果要做跨 Tab 或者菜单栏共享再升级成.environment注入也不迟。struct ChatView: View { State private var agent Agent() var body: some View { // ... } }有一点要提醒Observable类本身是MainActor跑在主线程上的这让 UI 状态更新特别安全。但 Skill 的execute如果做了重计算千万不要同步塞在主线程里否则再好的状态管理也救不了掉帧问题。3. 实操复现一个可运行的“智能日程助手”3.1 项目搭建与环境准备先说项目配置方便你直接照着搭。我用的是 Xcode 15 之后的版本iOS 17.0 作为最低部署版本Swift 5.9项目只引入系统框架EventKit日历事件、NotificationCenter本地提醒、CoreLocation定位当前城市。网络请求部分没有用第三方库直接写了一个基于 URLSession 的小客户端。创建项目后我的文件组织大概是这样的Agent/Agent.swiftAgent 主类和状态管理Agent/Skill.swiftSkill 协议和基础模型Skills/CreateEventSkill.swiftSkills/WeatherSkill.swiftSkills/RemindSkill.swiftViews/ChatView.swiftServices/WeatherAPI.swift这样放的最大好处是以后每加一个技能就多一个 Swift 文件其他文件基本不用动。3.2 第一个技能创建日历日程首先实现一个最实用的技能创建日历事件。它需要完成三件事判断用户话里的日期时间、从输入中抽取标题、写入系统日历。import EventKit final class CreateEventSkill: Skill { var id: String { calendar.create } var displayName: String { 创建日历日程 } var desc: String { 识别日期、时间和标题往系统日历添加事件 } var samplePhrases: [String] { [明天下午三点开会, 周六上午安排健身, 帮我预约一个日程] } var requiresUserConfirmation: Bool { true } func canHandle(_ userInput: String) - Bool { [日历, 日程, 安排, 预约, 开会, 会议].contains { userInput.contains($0) } } func extractArguments(from userInput: String) - [String: String] { var args: [String: String] [:] // 一个很朴素但够用的时间抽取规则 if let range userInput.range(of: #明天|后天|今天|周[一二三四五六日]#, options: .regularExpression) { args[day] String(userInput[range]) } if let range userInput.range(of: #\d{1,2}点#, options: .regularExpression) { args[time] String(userInput[range]) } // 去掉时间和日期词把剩下的当标题 var title userInput .replacingOccurrences(of: 帮我, with: ) .replacingOccurrences(of: 安排, with: ) .replacingOccurrences(of: 预约, with: ) .replacingOccurrences(of: 日程, with: ) .replacingOccurrences(of: #\d{1,2}点#, with: , options: .regularExpression) .trimmingCharacters(in: .whitespacesAndNewlines) if title.isEmpty { title 新日程 } args[title] title return args } func execute(arguments: [String: String]) async throws - SkillOutput { let store EKEventStore() let granted try await store.requestFullAccessToEvents() guard granted else { throw SkillError.permissionDenied } let event EKEvent(eventStore: store) event.title arguments[title] ?? 新日程 event.calendar store.defaultCalendarForNewEvents let startDate parseDate(from: arguments) event.startDate startDate event.endDate startDate.addingTimeInterval(60 * 60) event.isAllDay arguments[time] nil try store.save(event, span: .thisEvent) return .calendarEvent(title: event.title, startDate: event.startDate ?? startDate) } }requestFullAccessToEvents是 iOS 17 的新 API会异步弹出权限请求。如果用户的系统低于 iOS 17需要换成requestAccess(to: .event)的旧写法。我在调试时发现这个异步授权结果并不一定回到主线程所以 Agent 层调用execute时没有强制主线程这反而更安全。时间解析这里没有上正则库因为项目目标是自然语言理解能力的验证不是 NLP 研究。真要处理“下周三下午四点”这种说法我会把时间解析单独拆成一个DateParser服务甚至可以让模型直接从输入里抽参数而不是手写正则。3.3 第二个技能基于定位的天气查询第二个技能是天气查询。这里没有写死城市名而是通过定位拿到当前城市再传给一个示例 API。import CoreLocation final class WeatherSkill: Skill { var id: String { weather.current } var displayName: String { 查天气 } var desc: String { 返回当前所在城市的气温和天气状况 } var samplePhrases: [String] { [帮我看看天气, 今天多少度, 今天适合出门吗, 气温怎么样] } var requiresUserConfirmation: Bool { false } func canHandle(_ userInput: String) - Bool { userInput.contains(天气) || userInput.contains(气温) || userInput.contains(多少度) || userInput.contains(适合出门) } func extractArguments(from userInput: String) - [String: String] { // 先尝试从输入里抓“城市”抓不到就返回空 if let range userInput.range(of: #[\u4e00-\u9fa5]{2,6}(市|城)#, options: .regularExpression) { return [city: String(userInput[range])] } return [:] } func execute(arguments: [String: String]) async throws - SkillOutput { var city arguments[city] if city nil { city try await currentCityName() } let info try await WeatherAPI.shared.fetchWeather(city: city ?? 当前城市) return .weather(city: city ?? 当前城市, temperature: info.temperature, condition: info.condition) } private func currentCityName() async throws - String { let location try await LocationService.shared.currentLocation() return try await LocationService.shared.reverseGeocode(location) } }这个技能有个很好的示范作用它继承了协议里的execute是异步方法网络请求天然不阻塞主线程。如果未来天气 API 不稳定我可以在WeatherAPI内部加三秒超时然后返回一个“天气服务暂时不可用”的错误UI 层直接展示友好信息技能内部不用关心界面逻辑。实际开发中你大概率没有真实天气服务可用可以先用一个返回固定值的WeatherAPIStub来跑通流程等联调再替换成真实实现。3.4 Agent 主流程加“二次确认”别让用户被误伤创建日历事件这种操作是不可逆的直接执行非常危险。我在 Agent 里加了一个waitingConfirmation状态让 Skill 执行之后先不把结果发给用户而是生成一个待确认动作。代码层面很简单Agent.send拿到SkillOutput后先判断skill.requiresUserConfirmation是否为 true。如果是就调用对应的方法生成 PendingAction比如PendingAction.createCalendarEvent(title:startDate:)然后给用户回一句“我查到了这个日程标题是……时间是……确认创建吗”。用户在界面上点“确认”按钮后Agent 调用一个confirm()方法真正写入日历。这个交互逻辑一开始我没有做结果测试时用户随口说了一句“明天下午三点把会议记录发我”Agent 居然真的给自己创建了一个名为“把会议记录发我”的日历事件。从那以后我把“需要二次确认”作为每个技能的显式属性默认值设为 true只有查询类技能天气、计算器才设 false。enum PendingAction: Equatable { case createCalendarEvent(title: String, startDate: Date) case createReminder(title: String, date: Date) case none } extension Agent { func confirmPendingAction() async { guard case .waitingConfirmation(let action) phase else { return } switch action { case .createCalendarEvent(let title, let startDate): let output SkillOutput.calendarEvent(title: title, startDate: startDate) messages.append(ChatMessage(role: .agent, content: render(output))) case .createReminder(let title, let date): // 调用系统通知 let output SkillOutput.reminder(title: title, date: date) messages.append(ChatMessage(role: .agent, content: render(output))) case .none: break } phase .idle } }这里我先用render生成了确认文本实际业务里应该有一个更窄的“真正执行写入”的接口避免二次确认流和直接执行流重复。让我在下面实操里再展开。3.5 把整个流程接到 SwiftUI 上最后一步是界面。消息列表、输入框、处理状态、确认按钮加起来非常短struct ChatView: View { State private var agent Agent() State private var input var body: some View { VStack(spacing: 16) { ScrollViewReader { proxy in ScrollView { LazyVStack(alignment: .leading, spacing: 12) { ForEach(agent.messages) { message in MessageBubble(message: message) } } .padding() } .onChange(of: agent.messages.count) { _, _ in if let last agent.messages.last { withAnimation { proxy.scrollTo(last.id, anchor: .bottom) } } } } if agent.phase .waitingConfirmation(.none) { HStack { Button(确认) { Task { await agent.confirmPendingAction() } } Button(取消) { agent.cancelPendingAction() } } } HStack { TextField(说说你想做什么, text: $input) .textFieldStyle(.roundedBorder) Button(发送) { send() } .disabled(agent.phase .processing) } .padding() } .overlay { if agent.phase .processing { ProgressView(正在处理…) } } .task { let eventSkill CreateEventSkill() let weatherSkill WeatherSkill() agent.register(eventSkill) agent.register(weatherSkill) } } private func send() { let text input.trimmingCharacters(in: .whitespacesAndNewlines) guard !text.isEmpty else { return } input Task { await agent.send(text) } } }这里有个我反复调整的细节底部输入框在 Agent 处于processing状态时会禁用防止用户连续点发送导致任务重叠。任务重叠的后果很隐蔽——消息顺序错乱旧任务的结果可能晚于新任务到达反而显示在上一条消息下面。为彻底解决这个问题我后面加了executionID标记这里先不展开。4. 头皮发麻的问题排查清单下面是这个项目从写出来到稳定跑通我实际碰到过并且花了很多时间排查的问题。整理成一张表方便你对照。症状根因解决办法注册技能后找不到对应能力注册表被多个 Agent 实例共享或者 register 在 Task 外执行确保 register 只在 Agent 初始化时调用一次使用唯一 id 写入字典点击发送后 UI 卡住Agent 的send默认为主线程串行技能内同步等待网络确保 execute 是异步并且内部不阻塞主线程网络请求超时设置 3 秒消息顺序颠倒两个 Task 并发发送旧任务结果后到用 executionID 记录每次发送的序号渲染前校验是否是当前最新任务预览崩溃State初始化时注册技能但 EventKit 权限请求在预览环境失败在 preview 里注入 mock 技能或者把注册延迟到.task中等待确认按钮不出现phase .waitingConfirmation(.none)写法错误检查枚举关联值建议用if case判断而不是等值判断技能返回的 text 无法换行消息渲染用的是Text没有处理\n用Text(message.content)没问题但如果有 Markdown需要自定义渲染4.1 类型擦除之后协议方法为什么找不到这是最经典的一个坑。我在定义Agent.skills时用[String: any Skill]这样的字典一旦取出来就变成any Skill编译期不知道具体类型。如果你在selectSkill里直接调用skill.extractArgumentsSwiftUI 环境没问题但如果你想把某个具体技能返回到视图层就必须做类型擦除包装或者用if let concrete skill as? CreateEventSkill显式转换。我的建议是不要把具体的技能类型传到 UI 层。UI 只需要知道 Agent 返回的是文本或 PendingAction。如果某个技能有特殊 UI比如地图选点那就在SkillOutput里增加对应枚举 case然后让视图层按 case 渲染而不是去强转具体 Skill 类型。4.2 MainActor 和后台执行的数据竞争Agent 是MainActor类状态下标都在主线程更新这很好。但Skill.execute内部如果用了Task.detached做重模型推理再往回传结果时容易忘记切主线程。正确做法是技能内部不需要也不应该接触 UI 状态把SkillOutput当作“值”返回Agent 在send方法中等待返回后自然回到主线程更新消息。如果你在技能内部修改了外部共享状态那数据竞争几乎无法避免。我的经验是保持“技能无状态、Agent 有状态”这个边界比任何线程锁都好使。4.3Observable预览崩溃环境注入顺序的坑用Observable之后我一度把 Agent 放到environment里然后在 Preview 中这样写#Preview { ChatView() .environment(agent) }结果每次预览都崩溃。原因是 Agent 里注册了 EventKit 技能而预览进程没有日历权限也没有正确注入模拟。解决办法是把注册技能的代码从 Agent 的init移到ChatView.task中并且在预览环境用一组 mock 技能替代真实技能。所以我把 Agent 的初始化分为“纯空壳”和“技能装载”两个阶段。空壳负责状态管理技能装载由界面启动时调用。这样预览和测试都很舒服想测试哪个技能就只注册哪个技能。4.4 技能返回慢用户看不到进度刚开始我偷懒没有给send设置 processing 状态。用户点发送后界面看起来完全没反应五分钟后又弹出一条消息体感特别差。后来我在send开头立即把phase设为.processing结束无论成功失败都回到.idle再加上一个 ProgressView问题基本解决。更有用的是给每个技能增加一个“预计耗时”提示。比如天气查询标记为“约2秒”日历写入标记为“约1秒”。Agent 在调度到技能时可以先把这句提示显示出来用户知道不是在装死而是在干活。4.5 统一错误提示别让用户看到“executionFailed”最开始我的技能抛出的错误都是SkillError.executionFailed(EventKit xxx error)用户不管操作成功失败屏幕上只有一行冰冷的英文。我加了一个friendlyMessage(for:)方法把错误转换成用户能看懂的话。比如权限拒绝显示“需要日历权限才能创建日程请在设置中允许”网络失败显示“天气服务暂时不可用请稍后再试”。这层转换放在 Agent 层而不是每个技能内部尽量避免错误文案散落各处。下面是我现在用的错误映射逻辑private func friendlyMessage(for error: Error) - String { switch error { case SkillError.missingArgument(let name): return 我没找到「\(name)」的信息请补充一下 case SkillError.permissionDenied: return 需要权限才能继续请在系统设置里打开对应开关 case SkillError.executionFailed(let reason): return 执行失败了\(reason) case URLError.timedOut: return 请求超时了稍后再试试 default: return error.localizedDescription } }这样写之后用户至少知道下一步该干嘛而不是对着一个错误码干瞪眼。错误处理这件事越早统一越好不然后面技能一多每个技能返回的文案风格都不一样界面看起来特别散。5. 从 Demo 到正式功能Skill 的扩展设计5.1 先别急着堆技能把“选择”做准很多人看到这套架构很兴奋第一件事就是加十个技能。我的建议是先不要这样。调度器最怕的是多个技能长得太像比如“设置提醒”和“创建日程”它们自然语言里有大量重叠词。如果你开头没有把samplePhrases和评分规则调好后面技能越多选错概率越大。我自己是先把三个差异明显的技能跑通然后再慢慢增加。每增加一个新技能我会把所有技能的samplePhrases在本地跑一遍模拟测试看看有没有冲突。这个测试不用写单元测试框架直接在 playground 里循环调用selectSkill就行成本很低收益很高。5.2 技能编排当一个技能需要调用另一个技能时未来的趋势是复合技能。比如“如果明天下雨就提醒我带伞”涉及天气查询和创建提醒两个技能。目前我只支持技能内部直接调用另一个技能实例比如在execute里构造RemindSkill并调用但这会绕过 Agent 的状态管理。下一版我打算在 Agent 层加一个简单的“编排器”支持一个技能返回一个“还需执行其他技能”的标记。比如SkillOutput.chain(next:skillId, arguments:...)Agent 收到后自动调度下一个技能并把两个技能的结果拼接成一段上下文。这样用户一句话就能触发一串动作比固定流程自然得多。5.3 把 Agent 能力延伸到桌面端菜单栏苹果生态另一个让我觉得值得做的是 macOS 菜单栏。因为 Skill 层完全和 UI 解耦我可以在MenuBarExtra里直接复用同一个 Agent 实例和同一批技能。用户从菜单栏唤起一个快速输入框输入“提醒我两小时后喝水”Agent 调提醒技能桌面右下角弹系统通知。整个过程没有任何窗口特别轻。目前还没完全解决的问题是键盘快捷键。菜单栏的输入框如果支持全局快捷键体验会再上一个台阶。这部分和 Skill 无关主要是 SwiftUI 生命周期和事件监听的问题有机会单独写一篇。5.4 让技能可测试协议化的另一个好处是测试。过去我把视图和逻辑混在一起写单元测试覆盖率几乎为零。现在每个技能都能独立测试构造一个输入调用extractArguments断言参数是否正确调用execute断言返回的SkillOutput是否符合预期甚至可以用 mock Agent 验证调度器选到了正确的技能。我建议你在项目开始时就给每个技能写一个最小的测试用例至少覆盖正常输入、缺少参数、权限拒绝三种情况。这样重构的时候心里特别踏实我这次就是从重构里捡回一条命。最后说点真正的体会这套架构帮我解决的不只是代码组织问题更重要的是它改变了加功能时的心态。以前我每加一个自然语言入口都觉得是“开一个新项目”现在更像在已有的平台上插一个新插件先把协议实现好然后注册再写几条 samplePhrases 就完事。如果你也想在 SwiftUI 里做一个 AI 智能体类的小应用我建议从最小闭环开始一个 Agent、两个 Skill、一个聊天界面先把“选技能-执行-渲染”这条链路跑顺再去加多轮记忆、复杂编排和更多界面细节。还有一个小技巧想分享给刚好看到这里的人只要用户输入能被 samplePhrases 覆盖成功率通常就能到八成以上。所以认真维护这些短语比调模型参数更实用。我现在的习惯是每加一个用例就把它沉淀进 samplePhrases慢慢地技能会越来越“懂”用户说的话。