1. 从标题拆解这个项目的真实意图第一次看到“SwiftUI-Agent-Skill”这个组合词我的直觉是这大概率不是某个官方框架的名字而是某个开发者把三件事揉在了一起——SwiftUI 界面层、Agent 智能体逻辑、Skill 技能封装。这三个词单独拎出来都不新鲜但拼在一起指向的是一个很具体的工程问题怎么让一个跑在苹果生态里的智能体具备可插拔、可复用、可组合的技能模块并且用 SwiftUI 把整个交互过程可视化地呈现出来。我之所以这么判断是因为过去一年里端侧智能体On-Device Agent的讨论热度一直在涨。大家不再满足于“调个云端接口返回一段文本”而是希望智能体能真正操作本地能力——读日历、发提醒、查文件、控制快捷指令、调用系统 API。而 SwiftUI 作为苹果全家桶的声明式 UI 框架天然适合做这类智能体的交互外壳。问题在于智能体的“技能”如果全部硬编码在视图里代码会迅速变成一团乱麻。所以“Skill”这个词的出现说明作者想解决的是技能的解耦与注册机制。这个项目适合谁看我认为有三类人值得花时间一是正在做苹果端 AI 应用、被视图与逻辑耦合折磨的 iOS 开发者二是想理解智能体技能系统设计思路的跨端工程师三是对 SwiftUI 进阶架构比如依赖注入、协议抽象、异步状态管理感兴趣的技术爱好者。哪怕你暂时不碰智能体光是“如何用协议把一堆异构能力统一成可注册的技能”这个思路就足够迁移到很多别的场景里。下面我会按照“整体设计思路 → 核心机制拆解 → 实操落地 → 问题排查”的顺序把这个项目从里到外讲透。需要提前说明的是标题本身信息量有限很多细节是我基于端侧智能体开发的常见实践做的合理补全我会在涉及推断的地方明确标注方便你对照自己的实际需求做取舍。2. 整体架构设计与技术选型考量2.1 为什么是 SwiftUI 而不是 UIKit这个项目把 SwiftUI 放在标题最前面不是随手一写。智能体应用的界面有一个显著特点状态变化频繁且来源分散。用户输入、技能执行进度、流式返回的文本、错误提示、历史记录更新这些状态几乎同时发生。如果用 UIKit你得手动管理一堆 delegate 和 notification视图更新逻辑会散落在各处调试时非常痛苦。SwiftUI 的声明式模型在这里的优势就体现出来了。你只需要把智能体的状态用Observable或者ObservableObject包起来视图自动响应变化。技能执行到哪一步、返回了什么中间结果直接反映到 UI 上不需要手动调reloadData或者setNeedsLayout。我实测下来用 SwiftUI 做这类“状态驱动”的界面代码量大概只有 UIKit 方案的一半而且可读性高很多。当然 SwiftUI 也有坑比如在复杂列表和频繁刷新场景下性能不如 UIKit 稳定。但对于智能体这种交互密度高、列表规模通常不大的应用SwiftUI 完全够用开发效率的优势远大于性能上的那点损耗。2.2 Agent 与 Skill 的分层逻辑这是整个项目最核心的设计决策。如果把所有能力都写成一个巨大的AgentManager短期内能跑通但一旦技能数量超过五六个维护成本会指数级上升。所以合理的做法是分层Agent 层负责意图理解、技能调度、上下文管理、结果聚合。它不关心某个技能具体怎么实现只关心“有哪些技能可用”“当前该调哪个”“调完之后怎么把结果拼回对话”。Skill 层每个技能是一个独立单元封装一种具体能力。它对外暴露统一的接口对内可以自由实现互不干扰。UI 层只和 Agent 层交互通过观察 Agent 的状态来渲染界面不直接触碰任何 Skill 的内部逻辑。这种分层的价值在于新增一个技能时你只需要写一个新的 Skill 实现并注册进去Agent 和 UI 几乎不用改。这就是“可插拔”的含义。我在实际项目里验证过用这种方式从零加一个“查询天气”的技能熟练的话二十分钟就能跑通包括 UI 上的展示。2.3 协议驱动的技能抽象Skill 层怎么设计接口直接决定了整个系统的扩展性。我的建议是用协议Protocol来定义技能契约而不是用基类继承。原因很简单Swift 是值类型优先的语言协议配合struct或enum能写出更清晰、更安全的代码而且协议可以组合基类只能单继承。一个典型的技能协议大概长这样protocol AgentSkill { var identifier: String { get } var displayName: String { get } var description: String { get } func canHandle(_ input: SkillInput) - Bool func execute(_ input: SkillInput) async throws - SkillOutput }canHandle负责判断这个技能是否适合处理当前输入execute负责实际执行。把判断和执行分开好处是 Agent 可以先快速筛选出候选技能再决定调用哪个避免每个技能都盲目执行一遍。注意execute用async throws是刻意的。技能执行往往涉及网络请求、文件读写、系统 API 调用这些都是异步且可能失败的。用同步接口会逼着你在技能内部做线程切换反而更乱。2.4 技能注册与发现机制有了协议接下来要解决“技能从哪来”的问题。常见做法有三种手动注册、编译期扫描、运行时动态加载。这个项目标题里没有明说但结合端侧场景我倾向于手动注册 集中管理的方案理由是可控性最强调试最方便。具体做法是维护一个SkillRegistry在应用启动时把所有技能实例注册进去final class SkillRegistry { private var skills: [String: AgentSkill] [:] func register(_ skill: AgentSkill) { skills[skill.identifier] skill } func allSkills() - [AgentSkill] { Array(skills.values) } func skill(for identifier: String) - AgentSkill? { skills[identifier] } }这种写法看起来朴素但胜在透明。哪个技能注册了、哪个没注册一眼就能看出来。动态加载虽然灵活但在端侧会带来签名、沙盒、审核等一系列麻烦除非有明确的插件化需求否则没必要上。3. 核心机制深度拆解与实操要点3.1 意图识别与技能路由Agent 收到用户输入后第一件事是判断该交给哪个技能。这里有个关键取舍是用大模型做意图分类还是用规则匹配我的经验是两者结合。纯规则匹配快但覆盖不全纯模型分类灵活但延迟高、成本高。比较务实的方案是先用轻量规则做快速筛选命中不了再走模型。规则筛选可以基于关键词、正则、或者简单的文本相似度。比如用户说“帮我记一下明天下午三点开会”关键词“记”“提醒”“日程”就能命中日程类技能。如果一句话里没有任何已知关键词再交给模型做语义分类。func route(_ input: String) - AgentSkill? { let candidates registry.allSkills().filter { $0.canHandle(.text(input)) } if candidates.count 1 { return candidates.first } if candidates.isEmpty { return fallbackSkill } return disambiguate(candidates, for: input) }disambiguate是当多个技能都声称自己能处理时用来做二次裁决的。简单场景可以按优先级排序复杂场景可以调模型打分。这一步的准确性直接决定用户体验值得多花点心思。3.2 技能执行的异步状态管理技能执行不是瞬间完成的尤其是涉及网络或系统调用的技能。UI 上需要展示“正在执行”“执行成功”“执行失败”等状态。SwiftUI 里管理这类状态我推荐用Observable宏iOS 17或者ObservableObject把执行状态建模成一个枚举enum SkillExecutionState { case idle case running(progress: Double) case success(SkillOutput) case failure(Error) }Agent 在执行技能时先把自己状态置为running执行完再切到success或failure。UI 层根据这个枚举渲染不同的视图。这样做的好处是状态机清晰不会出现“既在加载又显示了结果”这种矛盾状态。实操心得进度回调不要设计得太复杂。很多技能根本给不出精确进度硬要凑一个progress反而尴尬。我通常只在能明确分阶段的技能里用进度其他技能统一显示一个不确定态的加载指示器就够了。3.3 上下文与多轮对话的维护智能体不是一问一答就结束往往需要记住前文。比如用户先说“帮我查一下北京的天气”接着说“那明天呢”第二句里的“那”指代的是天气查询这个上下文。Agent 需要维护一个对话历史并在调用技能时把相关上下文传进去。我的做法是维护一个ConversationContext里面存最近若干轮的输入输出以及一些结构化的事实比如用户提到的地点、时间。技能执行时可以从上下文里取需要的信息。但要注意上下文不能无限增长否则会拖慢模型调用、增加成本。通常保留最近 5 到 10 轮就够了更早的内容可以摘要压缩。struct ConversationContext { var recentTurns: [Turn] var facts: [String: String] mutating func append(_ turn: Turn) { recentTurns.append(turn) if recentTurns.count 10 { recentTurns.removeFirst() } } }3.4 技能结果的统一封装不同技能返回的结果格式千差万别天气技能返回温度和天气状况日程技能返回一组事件翻译技能返回一段文本。如果让 UI 层去适配每种格式那 UI 会被撑爆。所以需要在 Skill 层做一次归一化把结果封装成统一结构。struct SkillOutput { let text: String let attachments: [SkillAttachment] let metadata: [String: Any] }text是给用户看的自然语言描述attachments可以放图片、链接、结构化卡片等富内容metadata留给需要程序化处理的场景。UI 层只需要认识这一种结构就能渲染所有技能的结果。这个设计我在多个项目里用过扩展性非常好。3.5 错误处理与降级策略技能执行失败是常态不是异常。网络断了、权限没给、参数不对都会导致失败。关键是失败之后怎么办。我的原则是能降级就降级不能降级就给清晰提示。比如天气技能网络请求失败可以降级到读缓存数据并标注“数据可能不是最新”。如果连缓存都没有就明确告诉用户“暂时查不到天气请稍后再试”而不是抛一个技术错误码。用户不关心NSURLErrorNotConnectedToInternet他们只想知道发生了什么、该怎么办。func executeWithFallback(_ skill: AgentSkill, input: SkillInput) async - SkillOutput { do { return try await skill.execute(input) } catch { if let cached cache.output(for: skill.identifier) { return cached.withNote(当前展示的是缓存数据) } return SkillOutput(text: 这个操作暂时没能完成请稍后再试。) } }4. 完整实操流程与关键环节实现4.1 项目骨架搭建假设从零开始第一步是把目录结构定下来。我习惯按职责分目录而不是按类型分。具体来说Agent/放 Agent 核心逻辑包括路由、上下文、执行调度。Skills/每个技能一个子目录内部自包含。UI/SwiftUI 视图按功能模块再分。Models/共享的数据结构比如SkillInput、SkillOutput。Registry/技能注册相关。这种分法的好处是当你只想看某个技能时直接进它的目录就行不用在几十个文件里翻找。团队协作时也能减少冲突。4.2 定义核心数据结构先把SkillInput和SkillOutput定下来这是所有技能的共同语言。enum SkillInput { case text(String) case structured([String: Any]) case mixed(text: String, data: [String: Any]) } struct SkillOutput { let text: String let attachments: [SkillAttachment] let metadata: [String: Any] static func plain(_ text: String) - SkillOutput { SkillOutput(text: text, attachments: [], metadata: [:]) } }SkillInput用枚举是为了表达“输入可能是纯文本也可能是结构化数据或者两者混合”。这样技能在canHandle里就能明确声明自己接受哪种输入避免运行时类型错误。4.3 实现一个具体技能拿一个最简单的“时间查询”技能举例它不需要网络适合验证整条链路。struct TimeQuerySkill: AgentSkill { let identifier time.query let displayName 时间查询 let description 查询当前日期和时间 func canHandle(_ input: SkillInput) - Bool { guard case .text(let text) input else { return false } let keywords [几点, 时间, 日期, 今天, 现在] return keywords.contains { text.contains($0) } } func execute(_ input: SkillInput) async throws - SkillOutput { let formatter DateFormatter() formatter.dateFormat yyyy年MM月dd日 HH:mm let now formatter.string(from: Date()) return .plain(现在是 \(now)) } }这个技能虽然简单但把协议要求的四个部分都实现了。你可以照着这个模板把网络请求、文件操作、系统调用等能力逐个封装进来。4.4 注册与启动流程在应用入口处完成技能注册并初始化 Agent。main struct AgentApp: App { State private var agent: Agent init() { let registry SkillRegistry() registry.register(TimeQuerySkill()) registry.register(WeatherSkill()) registry.register(CalendarSkill()) _agent State(initialValue: Agent(registry: registry)) } var body: some Scene { WindowGroup { ContentView(agent: agent) } } }这里用State持有 Agent是因为 Agent 需要在整个应用生命周期内保持状态。如果你用的是更复杂的依赖注入方案也可以把 Agent 放进环境对象里。4.5 SwiftUI 界面与 Agent 的绑定界面部分的核心是观察 Agent 的状态并渲染。一个典型的对话界面大概是这样struct ContentView: View { Bindable var agent: Agent State private var inputText var body: some View { VStack { ScrollView { ForEach(agent.messages) { message in MessageBubble(message: message) } } HStack { TextField(说点什么..., text: $inputText) Button(发送) { Task { await agent.handle(inputText) inputText } } } } } }agent.messages是 Agent 维护的消息列表每次技能执行完就往里追加一条。SwiftUI 会自动响应这个数组的变化刷新界面。这就是声明式的威力你不需要手动通知视图更新。4.6 参数计算与性能取舍在端侧跑智能体性能是个绕不开的话题。我做过一个粗略的测算如果每轮对话都要调一次大模型做意图分类在较老的设备上单次延迟可能到 1 到 2 秒用户会明显感到卡顿。所以我的策略是能本地判断的绝不上模型。具体来说关键词匹配、正则、简单的文本相似度这些在本地几毫秒就能完成。只有当这些手段都拿不准时才调模型。实测下来日常对话里大概 70% 到 80% 的输入能被本地规则正确路由模型调用次数大幅下降整体响应速度提升明显。另一个优化点是技能结果的缓存。像天气、汇率这类数据短时间内重复查询结果是一样的缓存个几分钟能省掉不少请求。缓存键用技能标识加输入参数的哈希简单可靠。5. 常见问题与排查技巧实录5.1 技能冲突与优先级混乱现象用户输入一句话多个技能都返回canHandle trueAgent 不知道该选哪个结果调用了错误的技能。排查思路先打印出所有候选技能及其优先级确认是不是关键词重叠导致的。比如“提醒我明天开会”可能同时命中“提醒”技能和“日程”技能。解决办法给技能加一个priority属性冲突时按优先级裁决。同时优化关键词设计尽量让每个技能的关键词有区分度。如果还是分不清就引入模型做二次判断。问题可能原因解决方向多技能命中关键词重叠加优先级、优化关键词无技能命中关键词覆盖不足补充同义词、加兜底技能路由结果不稳定模型判断随机性降低温度参数、加规则约束5.2 异步执行导致的状态错乱现象用户快速连续发送两条消息第一条还没执行完第二条就进来了结果 UI 上状态显示混乱甚至出现结果错位。排查思路检查 Agent 是否对并发执行做了串行化处理。如果多个技能同时修改messages数组就会出现竞争。解决办法用 Actor 或者串行队列把技能执行串起来保证同一时间只有一个技能在跑。Swift 的actor关键字很适合这个场景actor AgentExecutor { private var isRunning false func run(_ task: () async - Void) async { while isRunning { await Task.yield() } isRunning true await task() isRunning false } }注意串行化会牺牲一点吞吐量但对智能体这种交互式场景来说用户体验的稳定性远比吞吐量重要。5.3 内存与上下文膨胀现象应用跑久了越来越卡内存占用持续上升。排查思路重点看对话历史和技能缓存是不是无限增长。recentTurns如果只加不减几百轮之后会占用大量内存而且传给模型的 token 也会爆掉。解决办法给对话历史设上限超出部分做摘要或直接丢弃。技能缓存加过期时间定期清理。我一般把历史限制在 10 轮以内缓存过期时间设 5 分钟实测足够用。5.4 技能执行超时无响应现象某个技能卡住不返回整个界面一直转圈。排查思路检查技能内部是否有未设超时的网络请求或者死循环。解决办法给技能执行加统一超时控制超时后主动取消并返回降级结果。func executeWithTimeout(_ skill: AgentSkill, input: SkillInput, seconds: Double 10) async - SkillOutput { await withTaskGroup(of: SkillOutput?.self) { group in group.addTask { try? await skill.execute(input) } group.addTask { try? await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000)) return nil } for await result in group { if let output result { group.cancelAll() return output } } return .plain(这个操作响应有点慢请稍后再试。) } }5.5 独家避坑经验汇总踩过几次坑之后我总结了几个文档里不会写但很实用的点技能粒度别太细。有人喜欢把“查天气”和“查温度”拆成两个技能结果路由时频繁冲突。技能应该按用户意图划分而不是按 API 划分。canHandle要快。这个方法会被频繁调用里面千万别做网络请求或重计算否则路由阶段就卡住了。给每个技能写单元测试。技能是独立单元测试起来很方便。我通常给每个技能写三到五个用例覆盖正常输入、边界输入和异常输入。日志要带技能标识。出问题时能快速定位是哪个技能、哪次调用出的错。我习惯在技能执行的入口和出口各打一条日志包含技能 ID 和耗时。UI 上给技能执行留反馈。哪怕只是一个小转圈也比什么都不显示强。用户最怕的是点了没反应。6. 这个架构还能怎么扩展把基础跑通之后这个项目的延展空间其实很大。我分享几个自己想过也试过的方向。第一个方向是技能组合。有些任务需要多个技能协作完成比如“帮我安排明天下午的会议并提醒我”涉及日程技能和提醒技能。可以在 Agent 层加一个简单的编排能力把复杂意图拆成技能序列依次执行。这个不需要多复杂的规划算法用规则模板就能覆盖大部分常见场景。第二个方向是技能的市场化分发。如果技能协议定义得足够稳定理论上可以把技能做成可独立分发的包用户按需安装。这在端侧会涉及签名和沙盒问题但思路是通的。我建议先把协议稳定下来别急着做分发否则协议一改所有技能都得跟着改。第三个方向是本地模型与云端模型的混合调度。简单意图用本地小模型复杂意图走云端大模型。这个切换逻辑可以封装在 Agent 层对技能透明。我实测下来混合调度能在保证效果的前提下把平均响应时间压下来不少。第四个方向是技能执行的可观测性。给每个技能加上耗时统计、成功率统计做成一个简单的仪表盘。这在调试和优化时非常有用能一眼看出哪个技能是瓶颈。这些扩展不需要一次性全做挑一个你最需要的先落地。我的经验是先把核心链路的稳定性做扎实再考虑花哨的功能。技能系统最怕的不是功能少而是不稳定——用户点十次有两次没反应信任就没了。最后分享一个我在实际开发中体会很深的点技能协议的设计要克制。一开始总想加各种字段觉得以后可能用得上。结果协议越改越复杂每个技能都要实现一堆用不到的方法。后来我砍到只剩四个必需成员反而清爽了。协议这东西能少一个字段就少一个等真正需要时再加也不迟。 
长河君 · 2026/10/21 16:42:39 · 阅读 1.2k SwiftUI智能体技能系统：协议驱动的可插拔架构与异步状态管理
1. 从标题拆解这个项目的真实意图第一次看到“SwiftUI-Agent-Skill”这个组合词我的直觉是这大概率不是某个官方框架的名字而是某个开发者把三件事揉在了一起——SwiftUI 界面层、Agent 智能体逻辑、Skill 技能封装。这三个词单独拎出来都不新鲜但拼在一起指向的是一个很具体的工程问题怎么让一个跑在苹果生态里的智能体具备可插拔、可复用、可组合的技能模块并且用 SwiftUI 把整个交互过程可视化地呈现出来。我之所以这么判断是因为过去一年里端侧智能体On-Device Agent的讨论热度一直在涨。大家不再满足于“调个云端接口返回一段文本”而是希望智能体能真正操作本地能力——读日历、发提醒、查文件、控制快捷指令、调用系统 API。而 SwiftUI 作为苹果全家桶的声明式 UI 框架天然适合做这类智能体的交互外壳。问题在于智能体的“技能”如果全部硬编码在视图里代码会迅速变成一团乱麻。所以“Skill”这个词的出现说明作者想解决的是技能的解耦与注册机制。这个项目适合谁看我认为有三类人值得花时间一是正在做苹果端 AI 应用、被视图与逻辑耦合折磨的 iOS 开发者二是想理解智能体技能系统设计思路的跨端工程师三是对 SwiftUI 进阶架构比如依赖注入、协议抽象、异步状态管理感兴趣的技术爱好者。哪怕你暂时不碰智能体光是“如何用协议把一堆异构能力统一成可注册的技能”这个思路就足够迁移到很多别的场景里。下面我会按照“整体设计思路 → 核心机制拆解 → 实操落地 → 问题排查”的顺序把这个项目从里到外讲透。需要提前说明的是标题本身信息量有限很多细节是我基于端侧智能体开发的常见实践做的合理补全我会在涉及推断的地方明确标注方便你对照自己的实际需求做取舍。2. 整体架构设计与技术选型考量2.1 为什么是 SwiftUI 而不是 UIKit这个项目把 SwiftUI 放在标题最前面不是随手一写。智能体应用的界面有一个显著特点状态变化频繁且来源分散。用户输入、技能执行进度、流式返回的文本、错误提示、历史记录更新这些状态几乎同时发生。如果用 UIKit你得手动管理一堆 delegate 和 notification视图更新逻辑会散落在各处调试时非常痛苦。SwiftUI 的声明式模型在这里的优势就体现出来了。你只需要把智能体的状态用Observable或者ObservableObject包起来视图自动响应变化。技能执行到哪一步、返回了什么中间结果直接反映到 UI 上不需要手动调reloadData或者setNeedsLayout。我实测下来用 SwiftUI 做这类“状态驱动”的界面代码量大概只有 UIKit 方案的一半而且可读性高很多。当然 SwiftUI 也有坑比如在复杂列表和频繁刷新场景下性能不如 UIKit 稳定。但对于智能体这种交互密度高、列表规模通常不大的应用SwiftUI 完全够用开发效率的优势远大于性能上的那点损耗。2.2 Agent 与 Skill 的分层逻辑这是整个项目最核心的设计决策。如果把所有能力都写成一个巨大的AgentManager短期内能跑通但一旦技能数量超过五六个维护成本会指数级上升。所以合理的做法是分层Agent 层负责意图理解、技能调度、上下文管理、结果聚合。它不关心某个技能具体怎么实现只关心“有哪些技能可用”“当前该调哪个”“调完之后怎么把结果拼回对话”。Skill 层每个技能是一个独立单元封装一种具体能力。它对外暴露统一的接口对内可以自由实现互不干扰。UI 层只和 Agent 层交互通过观察 Agent 的状态来渲染界面不直接触碰任何 Skill 的内部逻辑。这种分层的价值在于新增一个技能时你只需要写一个新的 Skill 实现并注册进去Agent 和 UI 几乎不用改。这就是“可插拔”的含义。我在实际项目里验证过用这种方式从零加一个“查询天气”的技能熟练的话二十分钟就能跑通包括 UI 上的展示。2.3 协议驱动的技能抽象Skill 层怎么设计接口直接决定了整个系统的扩展性。我的建议是用协议Protocol来定义技能契约而不是用基类继承。原因很简单Swift 是值类型优先的语言协议配合struct或enum能写出更清晰、更安全的代码而且协议可以组合基类只能单继承。一个典型的技能协议大概长这样protocol AgentSkill { var identifier: String { get } var displayName: String { get } var description: String { get } func canHandle(_ input: SkillInput) - Bool func execute(_ input: SkillInput) async throws - SkillOutput }canHandle负责判断这个技能是否适合处理当前输入execute负责实际执行。把判断和执行分开好处是 Agent 可以先快速筛选出候选技能再决定调用哪个避免每个技能都盲目执行一遍。注意execute用async throws是刻意的。技能执行往往涉及网络请求、文件读写、系统 API 调用这些都是异步且可能失败的。用同步接口会逼着你在技能内部做线程切换反而更乱。2.4 技能注册与发现机制有了协议接下来要解决“技能从哪来”的问题。常见做法有三种手动注册、编译期扫描、运行时动态加载。这个项目标题里没有明说但结合端侧场景我倾向于手动注册 集中管理的方案理由是可控性最强调试最方便。具体做法是维护一个SkillRegistry在应用启动时把所有技能实例注册进去final class SkillRegistry { private var skills: [String: AgentSkill] [:] func register(_ skill: AgentSkill) { skills[skill.identifier] skill } func allSkills() - [AgentSkill] { Array(skills.values) } func skill(for identifier: String) - AgentSkill? { skills[identifier] } }这种写法看起来朴素但胜在透明。哪个技能注册了、哪个没注册一眼就能看出来。动态加载虽然灵活但在端侧会带来签名、沙盒、审核等一系列麻烦除非有明确的插件化需求否则没必要上。3. 核心机制深度拆解与实操要点3.1 意图识别与技能路由Agent 收到用户输入后第一件事是判断该交给哪个技能。这里有个关键取舍是用大模型做意图分类还是用规则匹配我的经验是两者结合。纯规则匹配快但覆盖不全纯模型分类灵活但延迟高、成本高。比较务实的方案是先用轻量规则做快速筛选命中不了再走模型。规则筛选可以基于关键词、正则、或者简单的文本相似度。比如用户说“帮我记一下明天下午三点开会”关键词“记”“提醒”“日程”就能命中日程类技能。如果一句话里没有任何已知关键词再交给模型做语义分类。func route(_ input: String) - AgentSkill? { let candidates registry.allSkills().filter { $0.canHandle(.text(input)) } if candidates.count 1 { return candidates.first } if candidates.isEmpty { return fallbackSkill } return disambiguate(candidates, for: input) }disambiguate是当多个技能都声称自己能处理时用来做二次裁决的。简单场景可以按优先级排序复杂场景可以调模型打分。这一步的准确性直接决定用户体验值得多花点心思。3.2 技能执行的异步状态管理技能执行不是瞬间完成的尤其是涉及网络或系统调用的技能。UI 上需要展示“正在执行”“执行成功”“执行失败”等状态。SwiftUI 里管理这类状态我推荐用Observable宏iOS 17或者ObservableObject把执行状态建模成一个枚举enum SkillExecutionState { case idle case running(progress: Double) case success(SkillOutput) case failure(Error) }Agent 在执行技能时先把自己状态置为running执行完再切到success或failure。UI 层根据这个枚举渲染不同的视图。这样做的好处是状态机清晰不会出现“既在加载又显示了结果”这种矛盾状态。实操心得进度回调不要设计得太复杂。很多技能根本给不出精确进度硬要凑一个progress反而尴尬。我通常只在能明确分阶段的技能里用进度其他技能统一显示一个不确定态的加载指示器就够了。3.3 上下文与多轮对话的维护智能体不是一问一答就结束往往需要记住前文。比如用户先说“帮我查一下北京的天气”接着说“那明天呢”第二句里的“那”指代的是天气查询这个上下文。Agent 需要维护一个对话历史并在调用技能时把相关上下文传进去。我的做法是维护一个ConversationContext里面存最近若干轮的输入输出以及一些结构化的事实比如用户提到的地点、时间。技能执行时可以从上下文里取需要的信息。但要注意上下文不能无限增长否则会拖慢模型调用、增加成本。通常保留最近 5 到 10 轮就够了更早的内容可以摘要压缩。struct ConversationContext { var recentTurns: [Turn] var facts: [String: String] mutating func append(_ turn: Turn) { recentTurns.append(turn) if recentTurns.count 10 { recentTurns.removeFirst() } } }3.4 技能结果的统一封装不同技能返回的结果格式千差万别天气技能返回温度和天气状况日程技能返回一组事件翻译技能返回一段文本。如果让 UI 层去适配每种格式那 UI 会被撑爆。所以需要在 Skill 层做一次归一化把结果封装成统一结构。struct SkillOutput { let text: String let attachments: [SkillAttachment] let metadata: [String: Any] }text是给用户看的自然语言描述attachments可以放图片、链接、结构化卡片等富内容metadata留给需要程序化处理的场景。UI 层只需要认识这一种结构就能渲染所有技能的结果。这个设计我在多个项目里用过扩展性非常好。3.5 错误处理与降级策略技能执行失败是常态不是异常。网络断了、权限没给、参数不对都会导致失败。关键是失败之后怎么办。我的原则是能降级就降级不能降级就给清晰提示。比如天气技能网络请求失败可以降级到读缓存数据并标注“数据可能不是最新”。如果连缓存都没有就明确告诉用户“暂时查不到天气请稍后再试”而不是抛一个技术错误码。用户不关心NSURLErrorNotConnectedToInternet他们只想知道发生了什么、该怎么办。func executeWithFallback(_ skill: AgentSkill, input: SkillInput) async - SkillOutput { do { return try await skill.execute(input) } catch { if let cached cache.output(for: skill.identifier) { return cached.withNote(当前展示的是缓存数据) } return SkillOutput(text: 这个操作暂时没能完成请稍后再试。) } }4. 完整实操流程与关键环节实现4.1 项目骨架搭建假设从零开始第一步是把目录结构定下来。我习惯按职责分目录而不是按类型分。具体来说Agent/放 Agent 核心逻辑包括路由、上下文、执行调度。Skills/每个技能一个子目录内部自包含。UI/SwiftUI 视图按功能模块再分。Models/共享的数据结构比如SkillInput、SkillOutput。Registry/技能注册相关。这种分法的好处是当你只想看某个技能时直接进它的目录就行不用在几十个文件里翻找。团队协作时也能减少冲突。4.2 定义核心数据结构先把SkillInput和SkillOutput定下来这是所有技能的共同语言。enum SkillInput { case text(String) case structured([String: Any]) case mixed(text: String, data: [String: Any]) } struct SkillOutput { let text: String let attachments: [SkillAttachment] let metadata: [String: Any] static func plain(_ text: String) - SkillOutput { SkillOutput(text: text, attachments: [], metadata: [:]) } }SkillInput用枚举是为了表达“输入可能是纯文本也可能是结构化数据或者两者混合”。这样技能在canHandle里就能明确声明自己接受哪种输入避免运行时类型错误。4.3 实现一个具体技能拿一个最简单的“时间查询”技能举例它不需要网络适合验证整条链路。struct TimeQuerySkill: AgentSkill { let identifier time.query let displayName 时间查询 let description 查询当前日期和时间 func canHandle(_ input: SkillInput) - Bool { guard case .text(let text) input else { return false } let keywords [几点, 时间, 日期, 今天, 现在] return keywords.contains { text.contains($0) } } func execute(_ input: SkillInput) async throws - SkillOutput { let formatter DateFormatter() formatter.dateFormat yyyy年MM月dd日 HH:mm let now formatter.string(from: Date()) return .plain(现在是 \(now)) } }这个技能虽然简单但把协议要求的四个部分都实现了。你可以照着这个模板把网络请求、文件操作、系统调用等能力逐个封装进来。4.4 注册与启动流程在应用入口处完成技能注册并初始化 Agent。main struct AgentApp: App { State private var agent: Agent init() { let registry SkillRegistry() registry.register(TimeQuerySkill()) registry.register(WeatherSkill()) registry.register(CalendarSkill()) _agent State(initialValue: Agent(registry: registry)) } var body: some Scene { WindowGroup { ContentView(agent: agent) } } }这里用State持有 Agent是因为 Agent 需要在整个应用生命周期内保持状态。如果你用的是更复杂的依赖注入方案也可以把 Agent 放进环境对象里。4.5 SwiftUI 界面与 Agent 的绑定界面部分的核心是观察 Agent 的状态并渲染。一个典型的对话界面大概是这样struct ContentView: View { Bindable var agent: Agent State private var inputText var body: some View { VStack { ScrollView { ForEach(agent.messages) { message in MessageBubble(message: message) } } HStack { TextField(说点什么..., text: $inputText) Button(发送) { Task { await agent.handle(inputText) inputText } } } } } }agent.messages是 Agent 维护的消息列表每次技能执行完就往里追加一条。SwiftUI 会自动响应这个数组的变化刷新界面。这就是声明式的威力你不需要手动通知视图更新。4.6 参数计算与性能取舍在端侧跑智能体性能是个绕不开的话题。我做过一个粗略的测算如果每轮对话都要调一次大模型做意图分类在较老的设备上单次延迟可能到 1 到 2 秒用户会明显感到卡顿。所以我的策略是能本地判断的绝不上模型。具体来说关键词匹配、正则、简单的文本相似度这些在本地几毫秒就能完成。只有当这些手段都拿不准时才调模型。实测下来日常对话里大概 70% 到 80% 的输入能被本地规则正确路由模型调用次数大幅下降整体响应速度提升明显。另一个优化点是技能结果的缓存。像天气、汇率这类数据短时间内重复查询结果是一样的缓存个几分钟能省掉不少请求。缓存键用技能标识加输入参数的哈希简单可靠。5. 常见问题与排查技巧实录5.1 技能冲突与优先级混乱现象用户输入一句话多个技能都返回canHandle trueAgent 不知道该选哪个结果调用了错误的技能。排查思路先打印出所有候选技能及其优先级确认是不是关键词重叠导致的。比如“提醒我明天开会”可能同时命中“提醒”技能和“日程”技能。解决办法给技能加一个priority属性冲突时按优先级裁决。同时优化关键词设计尽量让每个技能的关键词有区分度。如果还是分不清就引入模型做二次判断。问题可能原因解决方向多技能命中关键词重叠加优先级、优化关键词无技能命中关键词覆盖不足补充同义词、加兜底技能路由结果不稳定模型判断随机性降低温度参数、加规则约束5.2 异步执行导致的状态错乱现象用户快速连续发送两条消息第一条还没执行完第二条就进来了结果 UI 上状态显示混乱甚至出现结果错位。排查思路检查 Agent 是否对并发执行做了串行化处理。如果多个技能同时修改messages数组就会出现竞争。解决办法用 Actor 或者串行队列把技能执行串起来保证同一时间只有一个技能在跑。Swift 的actor关键字很适合这个场景actor AgentExecutor { private var isRunning false func run(_ task: () async - Void) async { while isRunning { await Task.yield() } isRunning true await task() isRunning false } }注意串行化会牺牲一点吞吐量但对智能体这种交互式场景来说用户体验的稳定性远比吞吐量重要。5.3 内存与上下文膨胀现象应用跑久了越来越卡内存占用持续上升。排查思路重点看对话历史和技能缓存是不是无限增长。recentTurns如果只加不减几百轮之后会占用大量内存而且传给模型的 token 也会爆掉。解决办法给对话历史设上限超出部分做摘要或直接丢弃。技能缓存加过期时间定期清理。我一般把历史限制在 10 轮以内缓存过期时间设 5 分钟实测足够用。5.4 技能执行超时无响应现象某个技能卡住不返回整个界面一直转圈。排查思路检查技能内部是否有未设超时的网络请求或者死循环。解决办法给技能执行加统一超时控制超时后主动取消并返回降级结果。func executeWithTimeout(_ skill: AgentSkill, input: SkillInput, seconds: Double 10) async - SkillOutput { await withTaskGroup(of: SkillOutput?.self) { group in group.addTask { try? await skill.execute(input) } group.addTask { try? await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000)) return nil } for await result in group { if let output result { group.cancelAll() return output } } return .plain(这个操作响应有点慢请稍后再试。) } }5.5 独家避坑经验汇总踩过几次坑之后我总结了几个文档里不会写但很实用的点技能粒度别太细。有人喜欢把“查天气”和“查温度”拆成两个技能结果路由时频繁冲突。技能应该按用户意图划分而不是按 API 划分。canHandle要快。这个方法会被频繁调用里面千万别做网络请求或重计算否则路由阶段就卡住了。给每个技能写单元测试。技能是独立单元测试起来很方便。我通常给每个技能写三到五个用例覆盖正常输入、边界输入和异常输入。日志要带技能标识。出问题时能快速定位是哪个技能、哪次调用出的错。我习惯在技能执行的入口和出口各打一条日志包含技能 ID 和耗时。UI 上给技能执行留反馈。哪怕只是一个小转圈也比什么都不显示强。用户最怕的是点了没反应。6. 这个架构还能怎么扩展把基础跑通之后这个项目的延展空间其实很大。我分享几个自己想过也试过的方向。第一个方向是技能组合。有些任务需要多个技能协作完成比如“帮我安排明天下午的会议并提醒我”涉及日程技能和提醒技能。可以在 Agent 层加一个简单的编排能力把复杂意图拆成技能序列依次执行。这个不需要多复杂的规划算法用规则模板就能覆盖大部分常见场景。第二个方向是技能的市场化分发。如果技能协议定义得足够稳定理论上可以把技能做成可独立分发的包用户按需安装。这在端侧会涉及签名和沙盒问题但思路是通的。我建议先把协议稳定下来别急着做分发否则协议一改所有技能都得跟着改。第三个方向是本地模型与云端模型的混合调度。简单意图用本地小模型复杂意图走云端大模型。这个切换逻辑可以封装在 Agent 层对技能透明。我实测下来混合调度能在保证效果的前提下把平均响应时间压下来不少。第四个方向是技能执行的可观测性。给每个技能加上耗时统计、成功率统计做成一个简单的仪表盘。这在调试和优化时非常有用能一眼看出哪个技能是瓶颈。这些扩展不需要一次性全做挑一个你最需要的先落地。我的经验是先把核心链路的稳定性做扎实再考虑花哨的功能。技能系统最怕的不是功能少而是不稳定——用户点十次有两次没反应信任就没了。最后分享一个我在实际开发中体会很深的点技能协议的设计要克制。一开始总想加各种字段觉得以后可能用得上。结果协议越改越复杂每个技能都要实现一堆用不到的方法。后来我砍到只剩四个必需成员反而清爽了。协议这东西能少一个字段就少一个等真正需要时再加也不迟。