先讲一个我最近反复撞见的场景。把大模型对话能力接进 SwiftUI 应用之后最尴尬的事情往往不是“回答得不好”而是它只会“说”不会“做”。用户问了一句“帮我把明天下午的会议室订好”模型立刻回了一段非常得体的“好的已为您预订成功”但后台日志里根本没有出现过任何一条调起会议室系统的记录。这个场景下用户不会觉得应用智能只会觉得应用在骗人。我做的这个项目代号叫SwiftUI-Agent-Skill本质上就是想给 SwiftUI 应用里的 AI 加一层“手和脚”用原生 Swift 实现一组可执行的能力Skill再让大模型在对话过程中通过工具调用协议去触发这些能力。这个项目不是某一家厂商的 SDK而是一套跑在客户端侧的轻量 Agent 编排骨架。它解决的问题很明确怎么让 AI 从“会聊天”变成“会操作”。如果你正在做 iOS / macOS 应用里的大模型功能已经不想再停留在“问答盒子”的阶段想知道大模型到底是怎么调用你写好的功能的、Swift 并发模型该怎么配合这种多回合调用、以及哪些细节最容易翻车这篇文章就把这个项目从 0 到 1 的架构思路和排坑记录全摊开讲。1. 为什么我会在 SwiftUI 里塞一个 Agent 而不是一个聊天对话框1.1 从“会回答”到“会操作”的关键一步纯接大模型 API 的做法是“一问一答”把用户消息丢过去再把返回文本渲染到气泡里。可一个真正会被日常使用的应用用户想要的往往不是一份“番茄炒蛋怎么做”的菜谱而是“帮我在冰箱清单里加上番茄和两个鸡蛋”。前者只需要模型的知识后者需要模型去动 App 里的真实数据。因此 Agent 的核心在我看来不是“更聪明”而是“能操作”。Agent 和普通聊天的最大区别就是它可以调用外部能力去完成用户的目标。而 Skill 就是我给“外部能力”定的最小封装单位。我不需要复刻一整套复杂的多智能体系统先把单个 Agent 稳定地调起多个技能这件事做扎实就可以覆盖绝大多数真实应用的诉求。举一个我在项目里反复用的对照例子聊天式做法用户说“我今晚要加班帮我记录一下”模型回“好的已为您记录工作安排”。操作式做法用户说完之后模型真的调起add_todo技能把一条待办写进了本地存储再回一句“已经记好了今晚加班别忘了吃晚饭”。这一步的差别直接决定用户是“觉得你有点东西”还是“发现你在装模作样”。1.2 为什么把技能放在客户端而不是云端你可能想问为什么不把技能放到服务端让云上的 Agent 去调 HTTP 接口客户端只负责收发消息理论上可行但客户端方案有几个独特优势本机数据与隐私。很多技能操作的是本机内容——日历、备忘录、App 内部单据、用户授权过的本地资源。这些数据不一定适合全部上传到服务端。链路短、体感快。从“模型要调用技能”到“技能结果返回模型”只在本地完成交互延迟低很多。原生能力直通。技能可以直接驱动 SwiftUI 视图、系统框架能力比如唤起相机、发本地通知、控制 App 当前页面状态这种深度是纯 HTTP 接口很难模拟的。当然客户端 Agent 也有代价设备电量与算力有限、模型推理依赖你选的模型服务、多回合工具调用要面对 Swift 并发模型的种种约束。这些约束恰好构成了这个项目一步步演化的主线。1.3 这个骨架适合谁我把这个项目定位成一套“轻量 Agent 骨架”适合以下情况的开发者已经有一个 SwiftUI 应用想接大模型对话能力并且希望模型能触发 App 内的真实功能想研究工具调用Tool Calling协议在客户端侧落地时怎么写最稳需要一套不绑定特定模型厂商的抽象层以后切换服务不用重写所有技能对 Swift 的 Actor、Async/Await 在 AI 功能里的实战用法感兴趣。下面我从协议设计、调用闭环、并发边界到踩坑记录按这个项目的实际演化顺序讲。2. 技能抽象一个 Protocol 撑起“模型能理解、程序能执行”的接口2.1 一个 Skill 需要暴露的最少信息技能是要被模型“看”的也是要被程序“跑”的。模型天然不认识 Swift 函数它只知道文本和结构化描述。所以我给Skill协议定的最小契约是这样protocol Skill { /// 技能唯一标识例如 add_todo_item var name: String { get } /// 用自然语言写清楚“什么时候该调用我”这是意图识别的关键 var description: String { get } /// 参数说明按 JSON Schema 描述供模型的工具调用使用 var schema: String { get } /// 真正的执行入口模型会传一份 JSON技能负责解析并返回文本结果 func execute(args: Data) async throws - String }四个成员分别回答了四个问题模型看到它叫什么name、什么时候该用它description、用的时候要带什么参数schema、调完之后程序要跑什么execute。name必须全局唯一。我踩过一个很实际的坑早期把两个技能都叫“查询”结果模型在对话里确实选了其中一个但注册表执行时命中了错误的实现。后来我统一改成“动词_对象”的命名风格比如query_todo、add_todo、remove_todo模型识别准确率立刻上去了。2.2 参数入口为什么选 Data 而不是字典最初我纠结过入参到底用[String: Any]还是Data。[String: Any]的好处是“即插即用”模型传什么都能直接取。但用上两周就会发现问题取值全靠as?强转、缺字段要到运行期才炸、嵌套结构一多就变成一团乱麻。而Data加Codable的方式每个技能内部可以自己定义参数结构体解码失败时还能给模型返回明确的错误文本让它自行修正。一个具体的技能实现会长这样struct WeatherSkill: Skill { var name: String { get_weather } var description: String { 查询指定城市的实时天气适合回答温度、降水等问题。 } var schema: String { # { type: object, properties: { city: { type: string, description: 城市名称 } }, required: [city] } # } struct Params: Codable { let city: String } func execute(args: Data) async throws - String { let p try JSONDecoder().decode(Params.self, from: args) // 实际项目在这里调用天气数据源 return \(p.city) 当前晴24°C北风 3 级 } }每个技能自包含参数定义、业务逻辑、返回文本都在同一个类型里。想加一个技能就新增一个结构体不污染别处。这也是这个项目里“技能可插拔”的基础。2.3 SkillRegistry技能清单与执行分发有了技能还得有一个地方登记它们。我用一个注册中心来管理技能表、给模型生成工具描述、按名字分发执行actor SkillRegistry { private var storage: [String: any Skill] [:] func register(_ skill: any Skill) { storage[skill.name] skill } func toolsPayload() - [[String: Any]] { storage.values.map { skill in [ type: function, function: [ name: skill.name, description: skill.description, parameters: skill.schema ] ] } } func execute(name: String, args: Data) async throws - String { guard let skill storage[name] else { throw SkillError.unknownSkill(name) } return try await skill.execute(args: args) } }我把注册中心声明成actor因为它的操作可能来自多路并发用户一边说话、后台一边处理另一个技能的回调。actor能保证注册和查表不出现数据竞争。另外提醒一点storage.values.map里用any Skill这在 Swift 5.7 之后很自然。如果项目还停留在老版本需要把any Skill换成Skill的写法但语义上是一样的。3. 回合制循环对话、工具调用、结果回填如何闭环3.1 工具调用协议的运行原理很多初学者第一次见到“工具调用”会以为是大模型内部直接执行了代码。其实不是。它的本质是一次“多回合的约定”你把所有技能的描述发给模型模型在生成回复时如果判断“这里需要实际执行某个操作”它不会直接写最终回答而是返回一个结构化指令里面包含技能名和参数 JSON。比如用户说“帮我查一下明天的天气”模型可能返回{ tool_call: { name: get_weather, arguments: {\city\: \示例城市\} } }注意arguments在不少服务里是以字符串形式返回的并非已经解析好的 JSON 对象。到手之后要先转成Data再喂给技能的解码器。3.2 四类消息角色怎么流转要支撑这种多回合消息历史不能只有“用户-助手”两种角色。这个项目里我给消息定义了四个角色角色谁写入说明system客户端设定助手人设、回答风格、可用技能边界user客户端用户输入assistant模型普通回复也可能包含工具调用意图tool客户端把技能执行结果回传给模型必须关联调用 ID对应到代码里就是struct ChatMessage: Identifiable, Codable { enum Role: String, Codable { case system, user, assistant, tool } var id UUID() var role: Role var content: String var toolCallID: String? var toolName: String? }关键点在于每当模型要调技能你就要往历史里补两条消息——一条是“助手表示我要调用这个工具”一条是“工具的返回结果”。模型看到tool角色的结果之后才能继续生成面向用户的最终回答。这条链条一旦断了模型就会出现“我不知道刚才的技能返回了什么所以我在瞎编”的恶劣行为。3.3 一个极简的 Agent Turn 实现把上面的机制串起来就形成了所谓的“回合制循环”。我在项目里的实现大概是func runAgentTurn(userText: String, maxTurns: Int 5) async throws - String { var history await conversation.loadHistory() history.append(ChatMessage(role: .user, content: userText)) for _ in 0..maxTurns { let payload makeAPIPayload(history) let reply try await llmClient.complete( messages: payload, tools: await registry.toolsPayload() ) if let call reply.toolCall { let result try await registry.execute( name: call.name, args: Data(call.arguments.utf8) ) history.append(ChatMessage( role: .assistant, content: reply.content ?? , toolCallID: call.id, toolName: call.name )) history.append(ChatMessage( role: .tool, content: result, toolCallID: call.id, toolName: call.name )) } else { history.append(ChatMessage(role: .assistant, content: reply.content ?? )) await conversation.commit(history) return reply.content ?? } } throw AgentError.turnLimitExceeded }maxTurns这个上限务必要加。我曾经见过模型因为技能描述写得含糊反复调用同一个技能停不下来既浪费时间又消耗额度。设置 5 到 6 轮上限超出就把当前历史原样提交至少保证对话不崩。还有一个小细节历史记录commit只在最后一轮成功时写入。中间过程不要写否则一旦技能调用失败用户再重试一次历史里会多出一堆半途而废的tool消息模型就很容易被绕晕。4. Swift 并发下的编排细节Actor 边界、流式刷新、超时取消4.1 技能到底该跑在哪个隔离域这是我在项目里反复折腾过的点。早期的注册中心我直接加了MainActor理由是很多技能要读 UI 状态这样调用起来不用额外跳线程。可真这么干之后遇到一个技能内部做大量 JSON 解码的耗时任务界面虽然因为async/await的挂起没有完全卡死但主线程被占用的时间明显变长滚动列表掉了帧。后来我调整了策略注册中心本身不用MainActor让技能自己决定要不要回主线程。纯计算、纯网络请求的技能直接跑在后台需要操作 UI 的技能在execute内部用Task { MainActor in ... }切回主线程。这样并发策略从框架下沉到了技能实现灵活很多代价是写技能时要有一点并发意识。实际写起来的一个参考struct PresentSheetSkill: Skill { // ... func execute(args: Data) async throws - String { let p try JSONDecoder().decode(Params.self, from: args) let result await MainActor.run { // 在这里安全地操作 SwiftUI 状态或持有视图控制器 return 已弹出确认面板 } return result } }4.2 让进度和中间状态流式回到 SwiftUI纯对话的流式输出大家都做过就是不断把模型吐出来的片段 append 到消息数组里。但带技能调用的时候用户会想知道“现在到底进行到哪一步了”。我建议把 Agent 的执行过程抽成事件流enum AgentEvent { case messageAppended(ChatMessage) case skillStarted(String) case skillFinished(String, result: String) case turnDone(String) }视图模型消费这些事件聊天列表里就能自然显示“正在调用 查询待办 技能”的中间状态而不是让用户盯着一个转圈圈的发呆气泡干等。用到AsyncStream或者 Combine 的PassthroughSubject都可以关键是事件要先于结果推送否则用户感知不到“有事情真的在发生”。4.3 超时与取消防止一个技能拖死整段对话技能调用本质上是一次外部副作用操作网络抖一下、权限弹窗没响应都有可能卡住。我给技能执行包了一层统一超时func executeWithTimeout( name: String, args: Data, timeout: Duration .seconds(30) ) async throws - String { try await withThrowingTaskGroup(of: String.self) { group in group.addTask { try await self.execute(name: name, args: args) } group.addTask { try await Task.sleep(for: timeout) throw SkillError.timeout } defer { group.cancelAll() } return try await group.next()! } }逻辑很简单两个子任务赛跑谁先完成取谁另一个任务被取消。要注意的是Task.sleep抛出的取消异常要能被外层识别如果技能本身耗时很长最好在循环里检查Task.isCancelled及时收手。这样至少保证整段对话不会被某一个失控技能“绑架”。5. 实测最容易翻车的三个环节参数解码、状态同步、描述博弈5.1 模型给的 JSON 和 Swift 解码规则对不上怎么办这是所有接工具调用的人都会撞上的第一堵墙。模型返回的arguments经常出现必填字段缺失、字段类型写错、日期格式跟预期不一致等。比如 Schema 里写了required: [title]模型偏偏漏了title你的JSONDecoder直接抛错。我的处理方式非常朴素不要在execute里让解码错误直接抛到上层而是把错误转成一段可读文本作为tool消息回给模型。模型看到“参数解析失败缺少 title 字段”大概率会自己修正后重新调用。这个自愈循环跑起来之后我遇到参数问题的概率小了很多。核心逻辑是func safeExecute(skill: any Skill, args: Data) async - String { do { return try await skill.execute(args: args) } catch let error as DecodingError { return 参数解析失败请检查参数格式。错误详情\(error) } catch { return 技能执行出错\(error.localizedDescription) } }另一个值得养成习惯的做法是多余字段的情况并不需要担心JSONDecoder默认会忽略未知 key所以 Schema 写宽一点没关系需要担心的永远是缺失 required 字段。5.2 无状态技能很快撞墙跨回合状态怎么同步系统刚跑起来时技能很容易设计成“无状态”的进来一个参数返回一个结果。但真实对话不是这样。用户会说“加一条明天九点的待办名字叫开周会”下一条又追一句“顺便把上一条改成十点”。如果每个技能都是无状态的模型根本没有能力去引用“上一条”产生的数据。我的做法是技能之间共享一个状态容器并且让技能返回稳定的标识符。比如add_todo执行完不返回“已添加”三个字而是返回一段 JSON{ id: ABCD-1234, title: 开周会, message: 已添加 }这样模型在后续回合里就能拿着ABCD-1234去调update_todo或remove_todo。跨回合状态的本质就是让每一次技能调用的产物成为下一轮对话的上下文。5.3 技能描述怎么写模型才会在正确时机调用我见过的最典型失败案例是技能名称写得像内部函数名描述又写成“我是谁”完全不提“什么时候该用我”。模型在工具列表里看到一坨抽象文本宁可基于记忆瞎编也不调用你。正确的写法是让描述回答“我解决什么请求”。比如差此技能用于添加待办事项。好当用户要求新建、创建、记录一项待办任务或日程提醒时使用。输入为任务标题 title 与可选截止时间 due_at。还要注意多个技能之间的边界。我项目里最早有query_weather和query_city_info两个描述都提到城市模型经常犹豫不决。后来我把城市信息查询并入天气技能只保留一个入口准确率立刻稳定下来。技能数量不是越多越好相互重叠的描述会直接拉低模型的决策质量。6. 一个可以跑通全流程的 TodoSkill 实战6.1 状态容器与技能实现前面几章讲了很多抽象最后用待办这个最常见的场景把整个链路串一遍。先定义一个最简状态容器final class TodoStore { private(set) var items: [TodoItem] [] func add(_ item: TodoItem) { items.append(item) } func remove(id: UUID) - Bool { items.removeAll { $0.id id } return true } } struct TodoItem: Codable, Identifiable { let id: UUID let title: String let dueAt: Date? }然后实现add_todo技能struct AddTodoSkill: Skill { var name: String { add_todo } var description: String { 当用户要求新建、创建、记录待办或日程提醒时使用需要提供任务标题和可选的截止时间。 } var schema: String { # { type: object, properties: { title: { type: string, description: 任务标题 }, due_at: { type: string, format: date-time, description: 截止时间ISO 8601 } }, required: [title] } # } private let store: TodoStore init(store: TodoStore) { self.store store } func execute(args: Data) async throws - String { struct Params: Codable { let title: String let due_at: String? } let p try JSONDecoder().decode(Params.self, from: args) let item TodoItem(id: UUID(), title: p.title, dueAt: parseISO8601(p.due_at)) store.add(item) // 返回结构化结果便于模型在后续回合里引用这个 id let payload: [String: Any] [ id: item.id.uuidString, title: item.title, message: 已添加待办 ] return String(data: try JSONSerialization.data(withJSONObject: payload), encoding: .utf8) ?? } }TodoStore在 demo 里直接用类持有数组实际项目里可以换成 CoreData 或者 SwiftData。需要注意并发问题如果TodoStore被多个技能共享建议把它隔离到主线程或一个专门的 actor 里避免同时读写集合。这里为了可读性做了简化。6.2 注册中心接入与真实对话效果把所有技能集中注册就完成了接入let store TodoStore() let registry SkillRegistry() registry.register(AddTodoSkill(store: store)) registry.register(QueryTodoSkill(store: store, store: store)) registry.register(RemoveTodoSkill(store: store, store: store))上面是一种简写示意实际项目中QueryTodoSkill和RemoveTodoSkill各写各的实现构造函数按需要传store即可。跑通之后一次真实对话大概长这样用户“帮我记录明天上午十点参加产品评审会。”模型返回工具调用add_todo参数{title: 产品评审会, due_at: 2025-06-11T10:00:0008:00}。应用执行技能把结果作为tool消息回填。模型看到结果向用户输出“已经记好了明天上午十点参加产品评审会。”如果用户再补一句“改成下午两点”模型会拿第一步返回的id去调update_todo而不是新建一条。这套流程跑通之后才真正算把“对话 操作”闭环了。6.3 踩过几轮之后我总结的扩展顺序我在实际接入过程中一开始总想着把技能做得又全又细结果被各种边界问题牵着走。后来我把扩展顺序固定成了三步先做无状态的信息查询技能比如查天气、查文档。这类技能不涉及跨回合状态最容易验证协议和循环有没有问题。再做有状态的操作技能比如待办、购物车。这时候重点处理状态容器、ID 引用和并发边界。最后再做能驱动 UI 的技能比如弹确认框、切换页面。这类技能要把主线程隔离和事件流一起设计好否则 SwiftUI 状态会被搅得一团糟。我自己现在的习惯是每加一个技能先写三段测试话术——直接触发、间接暗示、模糊请求——分别看模型能不能在正确的时机调起技能。描述写得再漂亮这三句话里有一句不达标就继续调description和命名而不是急着堆下一个技能。这个项目到这里骨架已经足够支撑一个真实 App 里的“AI 操作员”了。剩下的路就看你打算给模型接上哪些“手脚”。