用SwiftUI打造AI智能体技能管理:从技能协议到全链路实现 提到 Agent做 iOS 开发的朋友可能第一反应是网络代理那一套工具链但这两年你再听到这个词几乎都是指智能体。我在 SwiftUI 里写了一个项目标题就叫 SwiftUI-Agent-Skill说白了就是把“AI 智能体”的技能管理能力塞进一个原生 SwiftUI 应用里用户在前端输入一句自然语言Agent 拆解任务后去匹配并调用注册好的技能然后把执行结果渲染回界面。这个项目最适合两类人一类是已经在接各种大模型接口、想让 App 具备工具调用能力的开发者另一类是刚开始接触 SwiftUI 状态管理、想找一个能落地的中型实战项目的朋友。这篇博文我会从设计思路、技能注册中心、界面绑定链路到踩坑记录完整拆解整个项目。1. 项目初衷与整体设计思路为什么要把“技能”单独抽象成一层1.1 没有技能抽象时AI 功能会越写越乱先说我最初踩到的坑。第一版做的是硬编码链路界面上一个 TextField用户输入“帮我查一下现在几点了”我直接在按钮点击事件里写 if input.contains(几点)然后走到一个函数里取时间后来又加了一个“帮我记一条待办”的判断接着是天气查询、汇率换算……大概加到第五个 if 的时候整个文件已经没法看了。每一个新功能都要改同一块逻辑界面代码、业务代码、数据处理全部搅在一起测试也不好写同事接手时只能顺着 case 一个一个翻。后来我意识到问题出在“技能”没有被当作一个独立概念。技能就应该像手机里的 App 一样有一套标准的安装和调用协议。用户不会关心 App 内部是怎么实现的他只看主屏幕上有没有这个图标、点开能不能解决问题。Agent 也是一样它只需要知道“当前有哪些技能可用”“怎么把调用参数传给技能”“技能返回了什么东西”至于技能内部是调了网络接口还是本地数据库Agent 根本不关心。1.2 给技能定义一个“契约”所以在我的项目里完整链路是这样SwiftUI 界面接收用户输入 → 把输入交给 AgentEngine智能体引擎 → AgentEngine 解析意图 → 查询技能注册表 → 找到匹配的技能并调用 → 技能执行完毕后返回结构化结果 → 结果发布到界面状态 → 界面自动刷新。这个链路里最重要的是技能注册表而技能注册表的核心是协议。我定义了一个叫 SkillProtocol 的协议每个技能都必须实现这个协议才能注册进系统。协议里包含几个关键字段技能的唯一标识符、技能名称、技能描述、接收的参数模型以及一个 execute 方法。技能描述非常重要因为 Agent 做意图匹配时依赖这个描述来理解“这个技能是干什么的”描述写得越精确路由命中率越高。这里我用了一个生活化的类比来给团队解释技能协议相当于外卖平台的“商家入驻合同”。平台不会替每家餐厅设计菜单但每家餐厅都要遵守同一个配送和结算规则。Agent 就是外卖平台技能就是商家协议就是那份合同。合同定得合理商家越多越繁荣合同定得含糊后面所有管理成本都会爆炸。1.3 为什么选择 SwiftUI 而不是 UIKit 或跨平台方案既然要做 Agent 技能管理这类偏交互的 DemoSwiftUI 是当前最合适的选择。界面声明式描述带来的最大好处是状态驱动刷新技能执行是异步过程Agent 可能在后台思考、调用接口、拼接结果这一系列状态变化在 SwiftUI 里只需要维护几个 Published 属性视图就会自动更新对应区域。用 UIKit 当然也能做但你需要手动处理通知或代理回调来刷新界面代码量和心智负担都会多不少。还要说明一点我没有在这个项目里引入任何第三方跨平台框架。原因是技能系统本身已经很依赖 Swift 的协议和泛型特性再叠加额外的抽象层容易把问题复杂化。保持纯原生每一层的问题都容易定位而且对想学习源码的朋友更友好。2. 核心概念拆解AgentEngine、技能注册表、参数模型与状态机2.1 AgentEngine 是什么一切调度的大脑AgentEngine 是整个系统的中枢。它不关心 UI 怎么画也不关心某个技能内部是怎么实现的它只做三件事接收文本输入、解析意图、调度技能。在具体实现上AgentEngine 里维护着一个技能注册表注册表本质上是字典key 是技能的 idvalue 是技能实例。当用户输入“帮我看看明天天气怎么样”AgentEngine 拿到文本后先做预处理小写化、去掉无意义的语气词、提取关键部分再把提取结果和每个技能的描述做匹配评分选得分最高的技能执行。这一段听着简单真正做起来比想象中要花更多心思因为用户不会总是用你预设的句式来说话技能匹配的容错设计在第 4 部分会专门讲。2.2 技能注册表用字典管理所有能力技能注册表我采用了一个独立的类 SkillRegistry内部存储结构是 [String: any SkillProtocol]。这个类只负责三件事register(_ skill: any SkillProtocol)把技能加入字典unregister(id: String) 按 id 移除技能某些场景下会有用比如权限变更findBestMatch(input: String) - (any SkillProtocol)?根据文本找到最合适的技能为什么用字典而不是数组因为 id 查找是 O(1)而 Agent 随时需要对技能做启停管理。用数组也能实现但每次匹配都要遍历项目里技能数量越多性能就越不可控。我实测过在技能数量超过 50 个之后字典方式的匹配耗时基本不变数组方式已经开始出现肉眼可感知的延迟了。2.3 参数模型技能与外部世界的统一接口每一个技能都声明自己需要什么参数这些参数集合被建模成一个 Codable 结构体。以天气查询技能为例它需要的参数是 city 和 date以待办事项技能为例它需要的参数是 action 和 content。这么做有一个核心收益参数校验可以前置。Agent 在调用技能之前可以把用户输入里的关键信息抽取出来尝试填充到这个参数结构体里。如果缺了必填字段Agent 可以直接在界面上提示“请补充城市信息”而不需要真正执行到技能内部才发现参数缺失。这种前置校验在小项目里可能感觉不明显技能一旦复杂起来就非常关键。2.4 技能状态机从 idle 到 success 的闭环技能执行不是一个瞬间动作用户输入的指令被路由到技能后要经过运行、等待、失败/成功等多个状态。我在项目里定义了一个枚举 SkillExecutionStateidle初始状态running正在执行succeeded(result: String)执行成功附带结果文本failed(message: String)执行失败附带错误信息cancelled被用户或上层主动取消为什么要把状态建模得这么细因为 SwiftUI 界面需要根据状态展示不同内容。running 时候显示 ProgressViewsucceeded 后展示结果卡片failed 时展示错误提示并给一个重试按钮cancelled 时收起进度动画。如果状态只有一个“完成/未完成”界面交互层次就会很单薄体验也不够好。我还做了一个额外处理每个状态切换都打一条带时间戳的日志方便追踪任务是在哪一步卡住的。3. 实操解析从协议设计到技能注册中心落地的完整过程3.1 先写协议技能的“宪法”在 Xcode 里新建一个 Swift 文件命名为 SkillProtocol.swift核心代码import Foundation protocol SkillProtocol: Identifiable { var id: String { get } var name: String { get } var skillDescription: String { get } associatedtype Parameters: Codable func execute(with parameters: Parameters) async throws - SkillResult } struct SkillResult { let summary: String let detail: String? let timestamp: Date }这里使用 associatedtype Parameters 是为了让每个技能自己决定参数结构但对外统一收敛为 Codable。执行方法用 async throws 是因为技能内部几乎都会有网络请求或耗时操作Swift 并发是必然选择。SkillResult 用来统一包装返回值summary 是展示在列表里的简短结果detail 是可以展开看的完整信息。这里有一个我特意踩过的坑命名冲突。项目里既有技能协议 SkillProtocol又有执行结果 SkillResult如果你同时引入了某些第三方库容易出现类型名称冲突。所以我在实际项目里给协议加了前缀比如 APPSkillProtocol。文章里为了讲解清晰还是用了短名字实际编码时我会建议加上前缀。3.2 技能注册中心的完整实现SkillRegistry 的具体实现如下import Foundation actor SkillRegistry { private var skills: [String: any SkillProtocol] [:] func register(_ skill: any SkillProtocol) { skills[skill.id] skill } func unregister(id: String) { skills.removeValue(forKey: id) } func allSkills() - [any SkillProtocol] { return Array(skills.values) } func findBestMatch(input: String) - (any SkillProtocol)? { let lowercased input.lowercased() var bestMatch: (skill: any SkillProtocol, score: Int)? for skill in skills.values { let score matchScore(input: lowercased, description: skill.skillDescription.lowercased()) if let current bestMatch { if score current.score { bestMatch (skill, score) } } else { bestMatch (skill, score) } } guard let best bestMatch, best.score 0 else { return nil } return best.skill } private func matchScore(input: String, description: String) - Int { let inputWords Set(input.split(separator: )) let descWords Set(description.split(separator: )) return inputWords.intersection(descWords).count } }我把 SkillRegistry 设计为 actor而不是普通的 class。理由有两个第一技能注册表可能被多个异步任务同时访问比如用户连续输入多条指令、Agent 并行调度时actor 能保证内部字典的线程安全第二actor 天然隔离状态Swift 编译器会在你访问可变状态时强制你考虑并发语义反而能避免不少隐蔽的 data race 问题。当然代价是调用端要加 await但这点代价在正确性面前完全值得。3.3 一个最简技能当前时间查询接下来实现一个最简技能“当前时间查询”用来验证整个链路struct TimeParameters: Codable { let format: String? } final class TimeSkill: SkillProtocol { var id: String { time_skill } var name: String { 当前时间 } var skillDescription: String { 查询当前日期和时间支持返回格式化字符串 } typealias Parameters TimeParameters func execute(with parameters: TimeParameters) async throws - SkillResult { let formatter DateFormatter() formatter.dateFormat parameters.format ?? yyyy-MM-dd HH:mm:ss let now Date() let summary formatter.string(from: now) return SkillResult(summary: summary, detail: 当前时间: \(summary), timestamp: now) } }这个技能业务逻辑极其简单但它验证了整个链路注册、匹配、参数填充、执行、返回结果。我把这种小技能比作单元测试里的“冒烟用例”先用最小成本打通全流程再慢慢接入复杂的网络技能定位问题会容易得多。3.4 网络技能天气查询的实现要点天气查询技能比时间技能复杂在它要做网络请求、解析 JSON、处理失败情况。由于这个技能要访问某个第三方天气 API我在项目里把 API 地址做成了配置项方便替换。核心代码如下struct WeatherParameters: Codable { let city: String let date: String? } final class WeatherSkill: SkillProtocol { var id: String { weather_skill } var name: String { 天气查询 } var skillDescription: String { 查询指定城市当天的天气状况包括温度、湿度、风力等信息 } typealias Parameters WeatherParameters func execute(with parameters: WeatherParameters) async throws - SkillResult { let city parameters.city.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? parameters.city let date parameters.date ?? today let urlString https://api.example.com/weather?city\(city)date\(date) guard let url URL(string: urlString) else { throw SkillError.invalidURL } let (data, response) try await URLSession.shared.data(from: url) guard let httpResponse response as? HTTPURLResponse, httpResponse.statusCode 200 else { throw SkillError.serverError } let weatherData try JSONDecoder().decode(WeatherResponse.self, from: data) let summary \(parameters.city) \(date): 晴气温 28℃湿度 40% return SkillResult(summary: summary, detail: weatherData.fullDescription, timestamp: Date()) } }有两个细节在这里很重要。第一URLSession 的超时策略一定要配置好否则在弱网环境下技能会长时间卡在 running 状态用户会以为 App 死了。第二网络返回的 JSON 结构要单独建一个响应模型不要在技能内部到处用字典取值否则改接口字段时全部要跟着改维护成本很高。我给天气技能的响应用例设置了 15 秒超时用户等待进度条转了超过这个时间AgentEngine 会直接判定为超时并进入 failed 状态。3.5 待办事项技能写操作的本地持久化除查询类技能外我还实现了写操作型的“待办事项”技能把用户输入的待办内容经过 Agent 解析后写入本地点数据库。这个技能的参数模型比较有意思它需要两个字段action 和 content。action 区分“新增”“删除”“查询”三类操作content 则是用户希望记录的具体文本。这个技能解决了纯 AI 接口无法解决的问题对话是瞬时的但待办数据需要留存。技能内部使用 SwiftData 做本地持久化这也是 iOS 17 之后我比较推荐的方案模型定义简洁、和 SwiftUI 绑定自然不需要像 Core Data 那样维护大量手动迁移逻辑。不过要提醒一句SwiftData 目前对复杂的谓词查询支持仍不如 Core Data 全面如果你要做的技能涉及很多复合条件筛选要仔细评估。4. SwiftUI 界面与技能模块的衔接状态、绑定与刷新策略4.1 界面层的核心结构整个界面的骨架是一个 NavigationStack根视图是技能展示列表顶部是输入框和发送按钮底部是执行状态卡片。界面上最重要的一个类是 AgentViewModel它持有 AgentEngine、技能注册表以及当前执行状态。MainActor final class AgentViewModel: ObservableObject { Published var inputText: String Published var currentState: SkillExecutionState .idle Published var resultMessage: String? nil private let registry SkillRegistry() private let engine: AgentEngine init() { let weatherSkill WeatherSkill() // 注册技能... self.engine AgentEngine(registry: registry) } func send() async { let trimmed inputText.trimmingCharacters(in: .whitespacesAndNewlines) guard !trimmed.isEmpty else { return } currentState .running do { let result try await engine.handle(input: trimmed) resultMessage result.summary currentState .succeeded(result: result.summary) } catch { currentState .failed(message: error.localizedDescription) } } }把 ViewModel 标记为 MainActor 是一个非常重要的决定。SwiftUI 的 body 渲染一定发生在主线程如果你在一个后台队列里更新了 Published 状态虽然某些情况下界面会意外地正常刷新但已经埋下了数据竞争的不定时炸弹。使用 MainActor 后编译器会在你从非主线程上下文调用 send() 方法时主动提示帮你规避掉这一类低级但高发的崩溃问题。4.2 技能运行状态如何在界面上优雅展示状态卡片我用了一个独立的 View根据 currentState 切换视图内容struct StatusCard: View { let state: SkillExecutionState var body: some View { VStack(alignment: .leading, spacing: 8) { switch state { case .idle: Label(就绪等待指令, systemImage: checkmark.circle) case .running: HStack { ProgressView() Text(技能执行中...) } case .succeeded(let result): Text(result).foregroundStyle(.green) case .failed(let message): VStack(alignment: .leading) { Text(执行失败).foregroundStyle(.red) Text(message).font(.footnote).foregroundStyle(.secondary) } case .cancelled: Text(已取消).foregroundStyle(.orange) } } .padding() .background(.background.secondary) .clipShape(RoundedRectangle(cornerRadius: 12)) } }视图的切换只依赖 currentState 一个值这就是声明式界面最大的爽点不需要手动隐藏或显示某个控件界面由状态推导所有逻辑都收敛在 ViewModel 里。这里我用 .background.secondary 做卡片底色比纯色块观感更柔和。4.3 技能列表页让用户看到 Agent 有哪些能力我还做了一个“技能仓库页”从 SkillRegistry 里读取 allSkills() 展示成列表每个技能行显示技能名称、描述和一个“试一下”按钮。点击按钮会把技能 id 作为命令前缀填充到输入框用户在文本后面补参数即可。这个页面的价值其实不在功能而在用户体验预期管理——用户不知道 Agent 能做什么的时候他根本不会去尝试给一个可见的技能列表能显著提高产品的可探索性。这个列表的刷新逻辑也不复杂视图出现时调用 Task { await viewModel.reloadSkills() }然后在通过 registry.allSkills() 获取技能数组并转成 Identifiable 数据模型后渲染即可。5. 常见问题与排查技巧实录我踩过的 8 个坑5.1 技能注册了但 Agent 一直匹配不到这个问题出现的频率最高。排查时先用 print 打印注册表中所有技能的 id 和描述确认技能确实存在再打印用户输入和匹配后的得分。我遇到过一次技能描述写的是“查询中国各城市的天气信息”用户输入是“明天上海热吗”分词后交集几乎为零得分自然为 0。排查思路是先看描述和用户输入是不是同一个表达体系。技能描述不能写得像函数注释要写得更口语化一点你希望用户在聊天框里怎么问就把技能描述写成类似的样子。比如天气技能描述改为“查询天气、温度、降雨、风力支持城市名称和日期”命中率明显上升。5.2 界面不刷新状态改了View 没动这种问题十有八九是 View 里用了局部 State而不是订阅 ViewModel 里的 Published。我给技能详情页单独写了一个子视图内部 State 持有结果文本结果 Agent 执行完回调更新了 ViewModel但子视图读取的是局部状态两边数据对不上。正确做法只有一个数据流向全局统一。所有技能执行结果都先发布到 ViewModel再由父视图传值到子视图。子视图里不要自己开新的状态存储除非它确实只是管理 UI 临时交互比如文本编辑框的内容。5.3 异步任务取消导致状态残留用户点击发送后立刻点击取消这时候如果不处理 Task 的取消逻辑上一个技能可能还在跑最后把结果写进了 currentState虽然用户已经不在那个页面了但这个状态又会透传到其他视图。我在 AgentEngine 里为每个任务生成了任务标识符在执行前检查 Task.isCancelled在返回结果前再校验任务标识符和当前标识符是否一致。如果不一致直接丢弃结果。这个机制看似繁琐多线程环境下却非常关键。5.4 网络请求报跨域或证书错误技能请求第三方天气接口时在模拟器上直接使用 https 一般没问题但如果 API 用的是自签名证书URLSession 会直接抛错。另外如果你的接口服务器配置了跨域限制需要检查服务器返回的响应头是否允许来自 App 的请求。Debug 阶段为了快速验证可以在 Info.plist 里配置 ATS 例外但上线前一定要移除。5.5 参数解析中的类型擦除问题由于 SkillProtocol 声明了 associatedtype Parameters直接把这些技能放在数组里会面临类型不一致的问题。我的解决方法是把注册表存储类型写成 [String: any SkillProtocol]在取出技能后统一用 withUnsafePointer 或类型转换来做参数填充。更优雅的方案是给参数解析单独做一个解析器用户输入文本先解析成 [String: Any]再按技能声明的 Parameters 类型逐一转换。这个过程在第 3 部分的注册表代码里其实已经埋了伏笔实际调试时你会发现转换失败的情况不少要着重做好错误提示。5.6 SwiftData 模型在技能调用中无法保存待办技能早期版本里我在非主线程上下文中创建 ModelContext导致频繁出现“Context is not a main context”的崩溃。这个问题的根源是 SwiftData 的上下文默认绑定在创建它的线程上解决方式是在保存数据前切换到 MainActor。当然你也可以使用私有队列上下文但在技能调用链路里最简单的还是把数据相关操作全部收口到 MainActor。5.7 多个技能之间的优先级冲突用户输入“帮我看看明天北京的天气适合跑步吗”。这既可能命中天气技能也可能命中一个健康建议技能两个技能描述中都含有“天气”“跑步”。我测试下来仅靠关键词交集经常打出平手稳定胜出的方法是给每个技能设置一个优先级字段Int得分相同时按优先级取高。另外技能描述长度也会影响匹配我把描述过长的技能改为拆成多个较短的关键句匹配效果反而好了。5.8 模拟器上网络权限与本地网络提示第一次在模拟器里跑天气技能时请求迟迟不返回。后来发现是模拟器上的本地网络权限提示没有点允许。这个权限和 iOS 真机类似在调试的时候容易忽略。检查路径是设置 → 隐私与安全性 → 本地网络确认对应的开发 App 开关打开。另外模拟器对某些 API 的访问会有兼容问题建议网络类技能用真机验证别省这一步。6. 写在最后一些个人体会这个项目是我目前做的比较完整的一个 SwiftUI 实战项目它让我深刻体会到Agent 类应用的核心挑战从来不在 UI 层而在技能的抽象和调度。协议设计得稳后面的注册、匹配、执行、刷新全链路都轻松协议设计得糙每加一个技能都要回来改核心代码。如果你打算进一步扩展我建议下一步给技能加上持久化的启用/停用状态再做一个可视化编排界面让用户能拖拽组合多个技能链路这样项目就能从 Demo 级别接近商业产品了。最后分享一个实际开发中的小技巧调试技能匹配时不要只打印最终命中了哪个技能要把每个技能的前三名候选和分值全部打印出来。我看到太多开发者只关心结果对不对不关心路由过程结果出了问题根本不知道是描述写得差还是匹配算法有 bug。打印日志这种笨办法往往是最快定位问题的捷径。