果生態(tài)中大模型工具調(diào)用與技能調(diào)度實(shí)踐)
這陣子我一直在折騰一個(gè)基于 SwiftUI 的“Agent Skill”項(xiàng)目也就是標(biāo)題里那個(gè)SwiftUI-Agent-Skill。簡(jiǎn)單說(shuō)這是一個(gè)把大模型對(duì)話能力和系統(tǒng)功能調(diào)用打通的應(yīng)用框架用戶(hù)用自然語(yǔ)言說(shuō)話Agent 負(fù)責(zé)理解意圖然后調(diào)度到具體的 Skill 去執(zhí)行最后把結(jié)果再帶回對(duì)話里。你問(wèn)“幫我明天上午十點(diǎn)約個(gè)會(huì)議室”它不只是回一句“好的”而是真的往系統(tǒng)日歷里寫(xiě)一條日程。這種模式在蘋(píng)果生態(tài)里做起來(lái)比想象中麻煩因?yàn)?SwiftUI 本身只是個(gè) UI 框架不負(fù)責(zé)意圖識(shí)別也不負(fù)責(zé)工具調(diào)度。我踩了不少坑之后把這套東西拆成了幾個(gè)清晰的模塊今天這篇就完整梳理一遍從架構(gòu)設(shè)計(jì)、協(xié)議定義、并發(fā)處理到實(shí)際接入 SwiftUI 視圖和排錯(cuò)經(jīng)驗(yàn)。適合正在做 iOS / macOS 智能助手類(lèi)應(yīng)用、或者想在蘋(píng)果端落地 Agent 能力的開(kāi)發(fā)者參考。無(wú)論你是剛接觸 Swift 還是已經(jīng)有幾年經(jīng)驗(yàn)這篇文章里的關(guān)鍵代碼和取舍邏輯應(yīng)該都能幫你少走幾個(gè)彎路。1. 項(xiàng)目整體設(shè)計(jì)與思路拆解1.1 項(xiàng)目定位與核心需求SwiftUI-Agent-Skill本質(zhì)上解決的是一個(gè)很具體的問(wèn)題大模型本身只能輸出文本它沒(méi)法直接操作你的日歷、備忘錄、文件系統(tǒng)也發(fā)不了網(wǎng)絡(luò)請(qǐng)求。要讓 AI 真正“干活”你必須給它提供一套可執(zhí)行的工具。這就是 Skill 的定位。Agent 則是調(diào)度的大腦。它負(fù)責(zé)幾件事把用戶(hù)的自然語(yǔ)言輸入整理成結(jié)構(gòu)化請(qǐng)求根據(jù)請(qǐng)求選擇合適的 Skill解析 Skill 執(zhí)行結(jié)果再組織成用戶(hù)能看懂的自然語(yǔ)言回復(fù)這個(gè)分工其實(shí)和很多后端 Agent 框架的思路一致但在 SwiftUI 場(chǎng)景下有幾個(gè)額外訴求狀態(tài)要能驅(qū)動(dòng) UI 刷新、異步任務(wù)要跑得穩(wěn)、Skill 要做得易擴(kuò)展。比如用戶(hù)問(wèn)完問(wèn)題之后界面上要能看到“思考中 → 正在調(diào)用日程工具 → 已寫(xiě)入日歷”這樣的實(shí)時(shí)反饋否則體驗(yàn)會(huì)非常生硬。我最初也想過(guò)直接用某個(gè)現(xiàn)成的 SDK 把 Function Calling 包裝一下但試了一圈發(fā)現(xiàn)要么是重量級(jí) SDK 綁定了特定服務(wù)商要么是框架層強(qiáng)調(diào)服務(wù)端邏輯、在客戶(hù)端集成很別扭。最后決定自己封裝一套輕量的 Agent-Skill 內(nèi)核這樣既能適配任意 LLM 服務(wù)也可以隨時(shí)往注冊(cè)表里加新技能不需要改動(dòng)核心代碼。1.2 技術(shù)選型背后的理由很多 Swift 開(kāi)發(fā)者會(huì)問(wèn)為什么不用ObservableObject而是用Observable為什么 Skill 協(xié)議里要帶一個(gè)描述用的元數(shù)據(jù)這些選擇背后都有實(shí)際原因。先說(shuō)狀態(tài)管理。iOS 17 以后蘋(píng)果主推Observable它在視圖刷新粒度上比ObservableObject更精準(zhǔn)ObservableObject只要任何一個(gè)Published屬性變了整個(gè)觀察體就刷新Observable則只刷新真正被讀取屬性的視圖。這對(duì) Agent 這種狀態(tài)變化頻繁的場(chǎng)景很重要尤其是對(duì)話界面里的消息列表、技能執(zhí)行進(jìn)度、輸入框的可用狀態(tài)這些控件各自關(guān)心不同的狀態(tài)沒(méi)必要一鍋端地全部重繪。再說(shuō) Skill 的描述。大模型是根據(jù)字符串描述來(lái)“理解”一個(gè)工具能不能用的所以每個(gè) Skill 不能只提供一個(gè)執(zhí)行方法還要提供一個(gè)面向 LLM 的說(shuō)明書(shū)——包含技能名稱(chēng)、觸發(fā)場(chǎng)景、參數(shù)結(jié)構(gòu)。這個(gè)說(shuō)明書(shū)寫(xiě)得好不好直接決定模型能不能正確調(diào)用技能。后面我會(huì)專(zhuān)門(mén)展開(kāi)講這塊因?yàn)樗俏以谡麄€(gè)項(xiàng)目里調(diào)試時(shí)間最長(zhǎng)、收益也最明顯的部分。1.3 模塊劃分與數(shù)據(jù)流我最終把項(xiàng)目拆成了四個(gè)核心模塊模塊職責(zé)關(guān)鍵內(nèi)容AgentCore意圖理解、對(duì)話管理接收輸入、維護(hù)消息歷史、解析 LLM 返回的 tool_callSkillRegistry技能注冊(cè)與查詢(xún)保存所有 Skill 實(shí)例、向 LLM 提供技能描述列表Skill 層具體執(zhí)行能力每個(gè) Skill 獨(dú)立實(shí)現(xiàn)輸入解碼、系統(tǒng)調(diào)用、結(jié)果輸出SwiftUI UI 層展示與交互消息列表、技能執(zhí)行狀態(tài)卡片、輸入欄數(shù)據(jù)流是單向的用戶(hù)在界面輸入 → AgentCore 組裝請(qǐng)求 → 攜帶 SkillRegistry 的技能描述一起發(fā)給 LLM → LLM 決定調(diào)用哪個(gè) Skill 并返回結(jié)構(gòu)化參數(shù) → AgentCore 查注冊(cè)表拿到對(duì)應(yīng) Skill 實(shí)例 → 執(zhí)行并拿到結(jié)果 → 結(jié)果再交給 LLM 生成最終回復(fù) → UI 展示。整個(gè)過(guò)程里SkillRegistry 是一個(gè)純內(nèi)存的注冊(cè)中心不持有任何業(yè)務(wù)邏輯只做匹配和分發(fā)。這樣新增技能時(shí)只需要初始化一個(gè)實(shí)例并調(diào)用register方法完全不用改動(dòng) Agent 核心。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 Skill 協(xié)議設(shè)計(jì)與擴(kuò)展性Skill 協(xié)議是整個(gè)框架的地基設(shè)計(jì)得不好后面每加一個(gè)新能力都難受。我的最終版本是這樣的protocol Skill: Identifiable, Sendable { var id: String { get } var descriptor: SkillDescriptor { get } func execute(input: Data) async throws - SkillResult }協(xié)議只有三個(gè)要求id 用于注冊(cè)表索引descriptor 是給 LLM 看的描述和參數(shù)結(jié)構(gòu)execute 是真正的執(zhí)行入口。input 用Data而不是具體的 Codable 類(lèi)型是為了讓協(xié)議不綁定任何特定參數(shù)結(jié)構(gòu)——每個(gè) Skill 自己決定如何解碼輸入這樣有的技能可能要傳經(jīng)緯度坐標(biāo)有的要傳聯(lián)系人列表都可以各自維護(hù)自己的輸入模型。SkillDescriptor是支撐整個(gè)調(diào)度過(guò)程的關(guān)鍵struct SkillDescriptor: Codable, Sendable { let id: String let name: String let description: String let parametersSchema: String }調(diào)用 LLM 工具接口時(shí)系統(tǒng)需要傳一個(gè) JSON 格式的工具列表parametersSchema就是直接塞給模型看的。這個(gè)字段我用 JSON Schema 格式編寫(xiě)大多數(shù)商業(yè) LLM 的 Function Calling 接口都能直接兼容不需要額外的格式轉(zhuǎn)換。實(shí)際項(xiàng)目中我加過(guò)定時(shí)器、網(wǎng)絡(luò)請(qǐng)求、本地搜索等技能每次新增都只需要關(guān)注三件事技能描述怎么寫(xiě)、參數(shù) schema 怎么定、execute 里怎么調(diào)用系統(tǒng) API。AgentCore 和 UI 層零修改這一點(diǎn)讓我非常滿意——框架的價(jià)值就在于“加功能不改核心”。2.2 技能描述怎么寫(xiě)模型才聽(tīng)得懂這是我在整個(gè)項(xiàng)目里最想強(qiáng)調(diào)的經(jīng)驗(yàn)Skill 的描述不是給人看的注釋而是給模型看的“操作說(shuō)明”。大多數(shù)開(kāi)發(fā)者在第一步就把這事想簡(jiǎn)單了寫(xiě)個(gè)“創(chuàng)建日程”四個(gè)字就完事結(jié)果就是模型根本沒(méi)法判斷什么時(shí)候該調(diào)這個(gè)工具。我對(duì)比過(guò)幾輪實(shí)驗(yàn)差別非常明顯描述類(lèi)型實(shí)際效果“創(chuàng)建日程”模型經(jīng)常在用戶(hù)只提到“開(kāi)會(huì)”時(shí)就誤調(diào)用且參數(shù)經(jīng)常漏填日期帶觸發(fā)場(chǎng)景、參數(shù)約束、缺省策略的完整描述調(diào)用時(shí)機(jī)準(zhǔn)確、參數(shù)完整率明顯提升用戶(hù)在時(shí)間不全時(shí)會(huì)被反問(wèn)問(wèn)清楚最終我給日程技能寫(xiě)的是這樣一段當(dāng)用戶(hù)想要安排會(huì)議、創(chuàng)建提醒、規(guī)劃待辦事項(xiàng)時(shí)調(diào)用本技能。系統(tǒng)會(huì)讀取用戶(hù)提供的日期和時(shí)間自動(dòng)寫(xiě)入系統(tǒng)日歷。參數(shù) title 為事件標(biāo)題startDate 為 ISO8601 格式的開(kāi)始時(shí)間durationMinutes 為持續(xù)分鐘數(shù)。如果用戶(hù)沒(méi)有給出具體時(shí)間不要調(diào)用本技能應(yīng)當(dāng)先向用戶(hù)詢(xún)問(wèn)開(kāi)始時(shí)間。注意最后這句話——“如果用戶(hù)沒(méi)給出具體時(shí)間不要調(diào)用”。這是很多開(kāi)發(fā)者容易遺漏的關(guān)鍵約束。模型默認(rèn)傾向于“猜測(cè)并執(zhí)行”如果你不明確告訴它何時(shí)不該調(diào)用它會(huì)在信息不全時(shí)強(qiáng)行填一個(gè)當(dāng)前時(shí)間進(jìn)去。加上這個(gè)反例描述之后模型的調(diào)用準(zhǔn)確率提升非常顯著。另外我強(qiáng)烈建議在 description 里加入“示例”。比如對(duì)天氣查詢(xún)技能補(bǔ)一句“例如用戶(hù)問(wèn)‘上海明天冷不冷’應(yīng)當(dāng)傳 location上海date明天”模型會(huì)參考這個(gè)示例來(lái)構(gòu)造參數(shù)這比單純羅列字段描述有效得多。你可以把這理解為喂給模型的小樣本提示Function Calling 的場(chǎng)景下少量示例往往比一個(gè)嚴(yán)密的 JSON Schema 更管用。2.3 Agent 狀態(tài)驅(qū)動(dòng)的 UI 刷新Agent 的運(yùn)行不是一蹴而就的發(fā)起請(qǐng)求、等待模型返回、執(zhí)行技能、再次請(qǐng)求模型生成回復(fù)每個(gè)環(huán)節(jié)都有狀態(tài)變化。為了把過(guò)程展示清楚我定義了一個(gè)顯式的狀態(tài)枚舉enum AgentState: Equatable { case idle case thinking case executing(skill: String) case responding }這個(gè)狀態(tài)配合Observable之后SwiftUI 視圖可以直接根據(jù)狀態(tài)切換展示內(nèi)容thinking時(shí)顯示轉(zhuǎn)圈并輸出“正在思考”executing(skill:)時(shí)顯示一個(gè)技能卡片標(biāo)注當(dāng)前正在執(zhí)行的工具名稱(chēng)responding時(shí)顯示“正在組織回復(fù)”。我用了一個(gè)小技巧把狀態(tài)映射成界面上的“階段指示器”類(lèi)似一個(gè) Step 列表用戶(hù)能清楚看到當(dāng)下進(jìn)行到哪一步。實(shí)測(cè)下來(lái)這種過(guò)程可見(jiàn)性對(duì)主觀體驗(yàn)的提升巨大哪怕底層響應(yīng)慢一點(diǎn)用戶(hù)也會(huì)覺(jué)得應(yīng)用更“聰明”而不是卡頓。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 從零搭建技能注冊(cè)中心注冊(cè)中心是整個(gè)框架的核心數(shù)據(jù)結(jié)構(gòu)我設(shè)計(jì)得很輕本質(zhì)上是一個(gè)帶鎖的字典加一個(gè)描述列表MainActor final class SkillRegistry: ObservableObject { private var storage: [String: any Skill] [:] func register(_ skill: any Skill) { storage[skill.id] skill } func skill(for id: String) - (any Skill)? { return storage[id] } var descriptors: [SkillDescriptor] { storage.values.map { $0.descriptor } } }我把它標(biāo)成MainActor是有原因的Agent 的執(zhí)行和 UI 狀態(tài)經(jīng)常同步讀寫(xiě)放到主 actor 上可以避免一堆數(shù)據(jù)競(jìng)爭(zhēng)問(wèn)題。實(shí)際調(diào)用 Skill 的時(shí)候雖然可能涉及網(wǎng)絡(luò)請(qǐng)求、文件讀寫(xiě)但 Skill 內(nèi)部自己開(kāi)異步子任務(wù)注冊(cè)中心只負(fù)責(zé)同步查詢(xún)和枚舉因此不會(huì)阻塞 UI。App 啟動(dòng)時(shí)把所有內(nèi)置技能注冊(cè)進(jìn)去let registry SkillRegistry() registry.register(CreateEventSkill()) registry.register(WeatherQuerySkill()) registry.register(ReminderSkill())這一步我看到很多人在做的時(shí)候會(huì)糾結(jié)要不要用“自動(dòng)掃描”或“反射注冊(cè)”在 Swift 生態(tài)里沒(méi)必要手動(dòng)注冊(cè)幾個(gè)技能是十幾秒的事?lián)Q來(lái)的是清晰的依賴(lài)關(guān)系和編譯時(shí)就有的類(lèi)型檢查。3.2 實(shí)現(xiàn)一個(gè)真正可用的技能日歷日程寫(xiě)入以日程創(chuàng)建技能為例看一個(gè)完整的 Skill 實(shí)現(xiàn)長(zhǎng)什么樣。輸入?yún)?shù)用嵌套結(jié)構(gòu)這樣執(zhí)行方法里解碼會(huì)很干凈struct CreateEventSkill: Skill { var id: String { create_event } var descriptor: SkillDescriptor { SkillDescriptor( id: id, name: 創(chuàng)建日歷日程, description: 當(dāng)用戶(hù)想要安排會(huì)議、創(chuàng)建提醒、規(guī)劃待辦事項(xiàng)時(shí)調(diào)用……, parametersSchema: { type: object, properties: { title: { type: string, description: 日程標(biāo)題 }, startDate: { type: string, format: date-time, description: 開(kāi)始時(shí)間ISO8601格式 }, durationMinutes: { type: integer, description: 持續(xù)分鐘數(shù)默認(rèn)30 }, notes: { type: string, description: 日程備注可選 } }, required: [title, startDate] } ) } private struct Input: Codable { let title: String let startDate: String let durationMinutes: Int? let notes: String? } func execute(input: Data) async throws - SkillResult { let params try JSONDecoder().decode(Input.self, from: input) let store try await withCheckedThrowingContinuation { continuation in // EventKit 的授權(quán)和寫(xiě)入代碼省略 } let message 已創(chuàng)建日程\(params.title)開(kāi)始時(shí)間 \(params.startDate) return SkillResult(success: true, output: message) } }注意durationMinutes在 Input 中是可選類(lèi)型。模型經(jīng)常不填不必要字段如果把它設(shè)為必填會(huì)因?yàn)槿眳?shù)導(dǎo)致解碼失敗。所以在 schema 里我只把title和startDate設(shè)成 required其他字段要么給默認(rèn)值要么走“可選 代碼兜底”的策略。這一點(diǎn)非常關(guān)鍵LLM 輸出的 JSON 不像人手寫(xiě)的那么穩(wěn)定寬松解碼、默認(rèn)值兜底能省掉大量調(diào)錯(cuò)時(shí)間。3.3 自然語(yǔ)言到技能調(diào)用的完整流程有了注冊(cè)中心和 Skill 實(shí)例接下來(lái)是 AgentCore 的核心循環(huán)。我用的是一個(gè)比較標(biāo)準(zhǔn)的工具調(diào)用流程func processUserInput(_ text: String) async { state .thinking let messages buildMessages(addingUserText: text) let firstResponse try await llmProvider.chat( messages: messages, tools: registry.descriptors ) // 模型決定調(diào)用工具 if let call firstResponse.toolCall { state .executing(skill: call.name) guard let skill registry.skill(for: call.name) else { // 技能不存在把錯(cuò)誤反饋給模型 return } do { let result try await skill.execute(input: call.argumentsData) // 工具結(jié)果回傳給模型讓模型組織自然語(yǔ)言回復(fù) let finalResponse try await llmProvider.chat( messages: messages [ toolResultMessage(name: call.name, content: result.output) ] ) appendMessage(finalResponse) } catch { // 失敗時(shí)直接把錯(cuò)誤信息作為工具結(jié)果給模型 let errorMessage toolResultMessage( name: call.name, content: 執(zhí)行失敗\(error.localizedDescription) ) let retryResponse try await llmProvider.chat(messages: messages [errorMessage]) appendMessage(retryResponse) } } else { // 模型沒(méi)有調(diào)用工具直接回復(fù) appendMessage(firstResponse.message) } state .idle }這個(gè)流程最精華的地方在第 24 行到第 30 行Skill 執(zhí)行失敗時(shí)不是簡(jiǎn)單地把錯(cuò)誤拋給用戶(hù)而是把錯(cuò)誤信息重新交給 LLM讓模型自己決定是修正參數(shù)重試、還是換一個(gè)表達(dá)方式解釋問(wèn)題。比如模型調(diào)用日程技能時(shí)傳了一個(gè)已經(jīng)被占用的事件 ID技能返回錯(cuò)誤模型會(huì)在下一輪回復(fù)中告訴用戶(hù)“這個(gè)時(shí)段已有日程建議換到下午三點(diǎn)”而不是顯示一句冷冰冰的系統(tǒng)錯(cuò)誤。實(shí)際測(cè)試時(shí)我還發(fā)現(xiàn)給模型傳參數(shù)時(shí)保留原始 JSON 比編碼成字符串更可靠。call.argumentsData是模型返回的原始 JSON 數(shù)據(jù)解碼成Input時(shí)類(lèi)型更干凈。如果中間轉(zhuǎn)一次字符串格式偶爾會(huì)多出轉(zhuǎn)義符導(dǎo)致解碼失敗。3.4 接入 SwiftUI 視圖層UI 層我用一個(gè)AgentViewModel封裝狀態(tài)和邏輯Observable final class AgentViewModel { var messages: [ChatMessage] [] private(set) var state: AgentState .idle private let registry SkillRegistry() private let agent AgentCore() func send(_ text: String) async { let userMessage ChatMessage(role: .user, content: text) messages.append(userMessage) await agent.processUserInput(text) } }視圖層就變得很直白了struct ChatView: View { State private var vm AgentViewModel() var body: some View { VStack { List(vm.messages) { message in MessageRow(message: message) } if case .executing(let skillName) vm.state { SkillStatusCard(name: skillName) } InputBar { Task { await vm.send($0) } } } } }SkillStatusCard是我額外加的一個(gè)小組件它把“當(dāng)前在調(diào)用什么技能”變成可見(jiàn)狀態(tài)。你可以在這里加進(jìn)度條、技能圖標(biāo)、耗時(shí)統(tǒng)計(jì)都不影響核心邏輯。這個(gè)設(shè)計(jì)還有一個(gè)好處以后要接 IPC、推送或桌面小組件來(lái)展示 Agent 進(jìn)度可以直接復(fù)用同一個(gè)狀態(tài)源。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄這一節(jié)的內(nèi)容是我在真機(jī)調(diào)試和連續(xù)多天日常使用中積攢下來(lái)的。很多坑是意想不到的列出來(lái)給各位參考。4.1 模型返回的參數(shù) JSON 不合法LLM 輸出的tool_calls里的參數(shù)不一定每次都是合法 JSON。我遇到比較多的情況包括字段名被縮寫(xiě)、時(shí)間格式不是 ISO8601、數(shù)字被判定成字符串等。最典型的一次是模型把startDate: 2025-03-01 10:00傳進(jìn)來(lái)而不是2025-03-01T10:00:00Z導(dǎo)致解碼器直接拋錯(cuò)。我的解決方案是分兩層處理。第一層是捕獲解碼錯(cuò)誤時(shí)把錯(cuò)誤信息回傳給 LLM讓模型自己修正格式第二層是給核心字段寫(xiě)寬松解析比如時(shí)間字段用ISO8601DateFormatter嘗試多種格式解析不了再拋錯(cuò)。這兩層配合后絕大部分情況都能自動(dòng)通過(guò)。4.2 并發(fā)更新 UI 導(dǎo)致視圖卡頓早期版本我直接在execute方法里調(diào)用 EventKit 寫(xiě)入EventKit的接口是同步的寫(xiě)日歷的操作會(huì)阻塞當(dāng)前線程。因?yàn)?AgentCore 的調(diào)用鏈?zhǔn)窃谥骶€程上跑的結(jié)果就是點(diǎn)擊發(fā)送后整個(gè)界面僵住一兩秒。排查思路很直接在 Xcode 的 Instruments 里看 Time Profiler發(fā)現(xiàn)主線程上有大量 EventKit 堆棧占用。修復(fù)方式是所有耗時(shí)操作都放到獨(dú)立的異步函數(shù)里并用await等待確保主線程只做 UI 更新?？蚣軐用嬉部梢约右坏婪烙oSkillRegistry加上MainActor但 Skill 的execute用nonisolated或者放到后臺(tái)任務(wù)隊(duì)列里執(zhí)行。4.3 同一個(gè)技能被并發(fā)調(diào)用導(dǎo)致?tīng)顟B(tài)沖突多輪對(duì)話里用戶(hù)可能在上一輪技能還沒(méi)執(zhí)行完就發(fā)送了新消息。比如問(wèn)“幫我查天氣”馬上又跟一句“順便建個(gè)日程”。如果不加控制兩條流程會(huì)同時(shí)執(zhí)行日歷寫(xiě)入就可能和天氣查詢(xún)的狀態(tài)互相覆蓋。我最后用了一個(gè)簡(jiǎn)單的串行隊(duì)列AgentCore 內(nèi)部維護(hù)一個(gè)Task鏈新的輸入會(huì)等待上一個(gè)任務(wù)結(jié)束后再執(zhí)行。極端情況下你可以用AsyncSemaphore做并發(fā)控制但對(duì)絕大多數(shù)應(yīng)用場(chǎng)景來(lái)說(shuō)串行處理用戶(hù)輸入是符合預(yù)期的——因?yàn)閷?duì)話本身就有先后順序用戶(hù)很少需要真正并發(fā)的 Agent 處理。4.4 技能注冊(cè)了但模型就是不調(diào)用這個(gè)問(wèn)題最隱蔽也是最讓人惱火的技能明明注冊(cè)了描述寫(xiě)得也不錯(cuò)但模型就是視而不見(jiàn)。我排查后發(fā)現(xiàn)主要是兩個(gè)原因。第一個(gè)原因是注冊(cè)順序。有些 LLM 服務(wù)商對(duì)工具列表的長(zhǎng)度和順序敏感工具過(guò)多時(shí)偶爾會(huì)忽略排在后面的工具。解決辦法是給工具列表按調(diào)用頻率排序常用技能放前面或者把一個(gè) Agent 負(fù)責(zé)的技能數(shù)量控制在 5-8 個(gè)以?xún)?nèi)。第二個(gè)原因是名字和描述里的關(guān)鍵詞不匹配。模型是根據(jù)文本相關(guān)性來(lái)判斷何時(shí)調(diào)用技能的如果用戶(hù)在輸入里用了“改期”“挪一下時(shí)間”而技能描述里只寫(xiě)了“創(chuàng)建日程”模型就會(huì)猶豫。我的經(jīng)驗(yàn)是在描述里把常見(jiàn)的同義說(shuō)法都列一遍“改期、延期、換時(shí)間、重新安排都可以調(diào)用本技能”。這樣模型的命中率會(huì)大幅提高。4.5 狀態(tài)機(jī)狀態(tài)殘留與 UI 卡死還有一個(gè)值得記錄的問(wèn)題如果用戶(hù)發(fā)送消息后立刻切后臺(tái)或者 LLM 請(qǐng)求超時(shí)狀態(tài)機(jī)可能停在executing狀態(tài)界面一直顯示“正在調(diào)用技能”。排查后發(fā)現(xiàn)是異常分支沒(méi)有清理狀態(tài)。修復(fù)方式是在processUserInput外面套一個(gè)defer確保無(wú)論什么路徑退出最終都會(huì)回到state .idle。這個(gè)經(jīng)驗(yàn)對(duì)所有異步狀態(tài)機(jī)都通用狀態(tài)恢復(fù)必須和退出綁定而不是只放在成功分支里。為了便于參考我把典型問(wèn)題整理成一個(gè)簡(jiǎn)潔的速查表問(wèn)題根因處理方案參數(shù)解碼失敗LLM 輸出的 JSON 格式不合規(guī)寬容解碼 錯(cuò)誤信息回傳 LLM 重試界面卡頓同步操作阻塞主線程耗時(shí)任務(wù)異步化主線程只刷 UI狀態(tài)互相覆蓋并發(fā)處理用戶(hù)輸入AgentCore 內(nèi)維護(hù)串行任務(wù)隊(duì)列技能不觸發(fā)描述缺少場(chǎng)景關(guān)鍵詞列全同義說(shuō)法控制技能總數(shù)狀態(tài)卡死異常分支未恢復(fù)狀態(tài)用 defer 確保狀態(tài)回歸 idle5. 性能優(yōu)化與后續(xù)擴(kuò)展路徑5.1 抽象 LLM Provider 以支持切換框架運(yùn)行的核心依賴(lài)是 LLM 返回結(jié)果但我不希望整個(gè)項(xiàng)目綁死在哪一家模型服務(wù)上。所以我抽了一個(gè)LLMProvider協(xié)議讓所有模型請(qǐng)求都走統(tǒng)一接口protocol LLMProvider: Sendable { func chat( messages: [ChatMessage], tools: [SkillDescriptor] ) async throws - LLMResponse }這樣 AgentCore 完全不知道底層是云端大模型、私有化部署還是端側(cè)模型只要實(shí)現(xiàn)協(xié)議就能運(yùn)行。我日常調(diào)試用的是一個(gè)輕量級(jí)云端接口同時(shí)也在實(shí)驗(yàn)把簡(jiǎn)單意圖識(shí)別分流到端側(cè)模型減少不必要的網(wǎng)絡(luò)請(qǐng)求。這個(gè)抽象對(duì)后續(xù)做多模型切換、灰度測(cè)試、離線模式都很有價(jià)值。5.2 從單技能調(diào)用走向多技能編排當(dāng)前實(shí)現(xiàn)處理的是“一輪對(duì)話調(diào)用一個(gè)技能”但實(shí)際用戶(hù)需求經(jīng)常是復(fù)合的“幫我查下明天天氣如果下雨就提醒我?guī)恪?。這需要 Agent 具備多步推理和編排能力。我計(jì)劃引入一個(gè)簡(jiǎn)單的計(jì)劃器當(dāng)意圖識(shí)別為復(fù)合任務(wù)時(shí)Agent 先拆解出子任務(wù)清單逐個(gè)執(zhí)行對(duì)應(yīng) Skill再用最終結(jié)果組裝回復(fù)。技術(shù)上就是在一個(gè)循環(huán)里重復(fù)“調(diào) LLM → 執(zhí)行工具 → 回傳工具結(jié)果”直到 LLM 認(rèn)為所有子任務(wù)完成。這個(gè)模式的工程改造成本不大但能明顯提升真實(shí)場(chǎng)景的可用性。5.3 離線技能與隱私邊界蘋(píng)果生態(tài)里用戶(hù)對(duì)隱私的敏感度很高這個(gè)項(xiàng)目也天然適合做端側(cè)優(yōu)先本地日歷、提醒、文件都是不需要聯(lián)網(wǎng)就能執(zhí)行的 Skill。真正需要聯(lián)網(wǎng)的只有 LLM 請(qǐng)求本身。我調(diào)研過(guò) iOS 17 起引入的端側(cè)自然語(yǔ)言框架可以用它做短文本的意圖分類(lèi)把“打開(kāi)設(shè)置”“新建備忘錄”這類(lèi)簡(jiǎn)單請(qǐng)求直接映射到本地技能不經(jīng)過(guò)網(wǎng)絡(luò)響應(yīng)速度快、隱私性也好。LLM 更多是被用來(lái)處理需要復(fù)雜理解的長(zhǎng)尾請(qǐng)求。這種混合調(diào)度的思路既控制了成本也提升了體驗(yàn)是后續(xù)比較理想的演進(jìn)方向。最后說(shuō)一個(gè)我實(shí)際開(kāi)發(fā)中的體會(huì)Agent 項(xiàng)目調(diào)試時(shí)最大的成本其實(shí)不在代碼而在于和 LLM 交互時(shí)的“預(yù)期管理”。你寫(xiě)了一個(gè)技能描述以為模型一定能理解但它就是會(huì)用偏。我的辦法是在開(kāi)發(fā)階段寫(xiě)了不少自動(dòng)化測(cè)試用例把典型用戶(hù)語(yǔ)句喂進(jìn)去檢查模型是否選對(duì)技能、參數(shù)是否合理。這樣每次調(diào)整描述或 schema 后跑一遍用例回歸很快就能迭代出穩(wěn)定的表現(xiàn)。如果你打算把這套模式用到自己的項(xiàng)目里我強(qiáng)烈建議你從第一天就保留這樣的測(cè)試集它會(huì)是你最可靠的護(hù)航工具。 SwiftUI Agent Skill：蘋(píng)果生態(tài)中大模型工具調(diào)用與技能調(diào)度實(shí)踐
這陣子我一直在折騰一個(gè)基于 SwiftUI 的“Agent Skill”項(xiàng)目也就是標(biāo)題里那個(gè)SwiftUI-Agent-Skill。簡(jiǎn)單說(shuō)這是一個(gè)把大模型對(duì)話能力和系統(tǒng)功能調(diào)用打通的應(yīng)用框架用戶(hù)用自然語(yǔ)言說(shuō)話Agent 負(fù)責(zé)理解意圖然后調(diào)度到具體的 Skill 去執(zhí)行最后把結(jié)果再帶回對(duì)話里。你問(wèn)“幫我明天上午十點(diǎn)約個(gè)會(huì)議室”它不只是回一句“好的”而是真的往系統(tǒng)日歷里寫(xiě)一條日程。這種模式在蘋(píng)果生態(tài)里做起來(lái)比想象中麻煩因?yàn)?SwiftUI 本身只是個(gè) UI 框架不負(fù)責(zé)意圖識(shí)別也不負(fù)責(zé)工具調(diào)度。我踩了不少坑之后把這套東西拆成了幾個(gè)清晰的模塊今天這篇就完整梳理一遍從架構(gòu)設(shè)計(jì)、協(xié)議定義、并發(fā)處理到實(shí)際接入 SwiftUI 視圖和排錯(cuò)經(jīng)驗(yàn)。適合正在做 iOS / macOS 智能助手類(lèi)應(yīng)用、或者想在蘋(píng)果端落地 Agent 能力的開(kāi)發(fā)者參考。無(wú)論你是剛接觸 Swift 還是已經(jīng)有幾年經(jīng)驗(yàn)這篇文章里的關(guān)鍵代碼和取舍邏輯應(yīng)該都能幫你少走幾個(gè)彎路。1. 項(xiàng)目整體設(shè)計(jì)與思路拆解1.1 項(xiàng)目定位與核心需求SwiftUI-Agent-Skill本質(zhì)上解決的是一個(gè)很具體的問(wèn)題大模型本身只能輸出文本它沒(méi)法直接操作你的日歷、備忘錄、文件系統(tǒng)也發(fā)不了網(wǎng)絡(luò)請(qǐng)求。要讓 AI 真正“干活”你必須給它提供一套可執(zhí)行的工具。這就是 Skill 的定位。Agent 則是調(diào)度的大腦。它負(fù)責(zé)幾件事把用戶(hù)的自然語(yǔ)言輸入整理成結(jié)構(gòu)化請(qǐng)求根據(jù)請(qǐng)求選擇合適的 Skill解析 Skill 執(zhí)行結(jié)果再組織成用戶(hù)能看懂的自然語(yǔ)言回復(fù)這個(gè)分工其實(shí)和很多后端 Agent 框架的思路一致但在 SwiftUI 場(chǎng)景下有幾個(gè)額外訴求狀態(tài)要能驅(qū)動(dòng) UI 刷新、異步任務(wù)要跑得穩(wěn)、Skill 要做得易擴(kuò)展。比如用戶(hù)問(wèn)完問(wèn)題之后界面上要能看到“思考中 → 正在調(diào)用日程工具 → 已寫(xiě)入日歷”這樣的實(shí)時(shí)反饋否則體驗(yàn)會(huì)非常生硬。我最初也想過(guò)直接用某個(gè)現(xiàn)成的 SDK 把 Function Calling 包裝一下但試了一圈發(fā)現(xiàn)要么是重量級(jí) SDK 綁定了特定服務(wù)商要么是框架層強(qiáng)調(diào)服務(wù)端邏輯、在客戶(hù)端集成很別扭。最后決定自己封裝一套輕量的 Agent-Skill 內(nèi)核這樣既能適配任意 LLM 服務(wù)也可以隨時(shí)往注冊(cè)表里加新技能不需要改動(dòng)核心代碼。1.2 技術(shù)選型背后的理由很多 Swift 開(kāi)發(fā)者會(huì)問(wèn)為什么不用ObservableObject而是用Observable為什么 Skill 協(xié)議里要帶一個(gè)描述用的元數(shù)據(jù)這些選擇背后都有實(shí)際原因。先說(shuō)狀態(tài)管理。iOS 17 以后蘋(píng)果主推Observable它在視圖刷新粒度上比ObservableObject更精準(zhǔn)ObservableObject只要任何一個(gè)Published屬性變了整個(gè)觀察體就刷新Observable則只刷新真正被讀取屬性的視圖。這對(duì) Agent 這種狀態(tài)變化頻繁的場(chǎng)景很重要尤其是對(duì)話界面里的消息列表、技能執(zhí)行進(jìn)度、輸入框的可用狀態(tài)這些控件各自關(guān)心不同的狀態(tài)沒(méi)必要一鍋端地全部重繪。再說(shuō) Skill 的描述。大模型是根據(jù)字符串描述來(lái)“理解”一個(gè)工具能不能用的所以每個(gè) Skill 不能只提供一個(gè)執(zhí)行方法還要提供一個(gè)面向 LLM 的說(shuō)明書(shū)——包含技能名稱(chēng)、觸發(fā)場(chǎng)景、參數(shù)結(jié)構(gòu)。這個(gè)說(shuō)明書(shū)寫(xiě)得好不好直接決定模型能不能正確調(diào)用技能。后面我會(huì)專(zhuān)門(mén)展開(kāi)講這塊因?yàn)樗俏以谡麄€(gè)項(xiàng)目里調(diào)試時(shí)間最長(zhǎng)、收益也最明顯的部分。1.3 模塊劃分與數(shù)據(jù)流我最終把項(xiàng)目拆成了四個(gè)核心模塊模塊職責(zé)關(guān)鍵內(nèi)容AgentCore意圖理解、對(duì)話管理接收輸入、維護(hù)消息歷史、解析 LLM 返回的 tool_callSkillRegistry技能注冊(cè)與查詢(xún)保存所有 Skill 實(shí)例、向 LLM 提供技能描述列表Skill 層具體執(zhí)行能力每個(gè) Skill 獨(dú)立實(shí)現(xiàn)輸入解碼、系統(tǒng)調(diào)用、結(jié)果輸出SwiftUI UI 層展示與交互消息列表、技能執(zhí)行狀態(tài)卡片、輸入欄數(shù)據(jù)流是單向的用戶(hù)在界面輸入 → AgentCore 組裝請(qǐng)求 → 攜帶 SkillRegistry 的技能描述一起發(fā)給 LLM → LLM 決定調(diào)用哪個(gè) Skill 并返回結(jié)構(gòu)化參數(shù) → AgentCore 查注冊(cè)表拿到對(duì)應(yīng) Skill 實(shí)例 → 執(zhí)行并拿到結(jié)果 → 結(jié)果再交給 LLM 生成最終回復(fù) → UI 展示。整個(gè)過(guò)程里SkillRegistry 是一個(gè)純內(nèi)存的注冊(cè)中心不持有任何業(yè)務(wù)邏輯只做匹配和分發(fā)。這樣新增技能時(shí)只需要初始化一個(gè)實(shí)例并調(diào)用register方法完全不用改動(dòng) Agent 核心。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 Skill 協(xié)議設(shè)計(jì)與擴(kuò)展性Skill 協(xié)議是整個(gè)框架的地基設(shè)計(jì)得不好后面每加一個(gè)新能力都難受。我的最終版本是這樣的protocol Skill: Identifiable, Sendable { var id: String { get } var descriptor: SkillDescriptor { get } func execute(input: Data) async throws - SkillResult }協(xié)議只有三個(gè)要求id 用于注冊(cè)表索引descriptor 是給 LLM 看的描述和參數(shù)結(jié)構(gòu)execute 是真正的執(zhí)行入口。input 用Data而不是具體的 Codable 類(lèi)型是為了讓協(xié)議不綁定任何特定參數(shù)結(jié)構(gòu)——每個(gè) Skill 自己決定如何解碼輸入這樣有的技能可能要傳經(jīng)緯度坐標(biāo)有的要傳聯(lián)系人列表都可以各自維護(hù)自己的輸入模型。SkillDescriptor是支撐整個(gè)調(diào)度過(guò)程的關(guān)鍵struct SkillDescriptor: Codable, Sendable { let id: String let name: String let description: String let parametersSchema: String }調(diào)用 LLM 工具接口時(shí)系統(tǒng)需要傳一個(gè) JSON 格式的工具列表parametersSchema就是直接塞給模型看的。這個(gè)字段我用 JSON Schema 格式編寫(xiě)大多數(shù)商業(yè) LLM 的 Function Calling 接口都能直接兼容不需要額外的格式轉(zhuǎn)換。實(shí)際項(xiàng)目中我加過(guò)定時(shí)器、網(wǎng)絡(luò)請(qǐng)求、本地搜索等技能每次新增都只需要關(guān)注三件事技能描述怎么寫(xiě)、參數(shù) schema 怎么定、execute 里怎么調(diào)用系統(tǒng) API。AgentCore 和 UI 層零修改這一點(diǎn)讓我非常滿意——框架的價(jià)值就在于“加功能不改核心”。2.2 技能描述怎么寫(xiě)模型才聽(tīng)得懂這是我在整個(gè)項(xiàng)目里最想強(qiáng)調(diào)的經(jīng)驗(yàn)Skill 的描述不是給人看的注釋而是給模型看的“操作說(shuō)明”。大多數(shù)開(kāi)發(fā)者在第一步就把這事想簡(jiǎn)單了寫(xiě)個(gè)“創(chuàng)建日程”四個(gè)字就完事結(jié)果就是模型根本沒(méi)法判斷什么時(shí)候該調(diào)這個(gè)工具。我對(duì)比過(guò)幾輪實(shí)驗(yàn)差別非常明顯描述類(lèi)型實(shí)際效果“創(chuàng)建日程”模型經(jīng)常在用戶(hù)只提到“開(kāi)會(huì)”時(shí)就誤調(diào)用且參數(shù)經(jīng)常漏填日期帶觸發(fā)場(chǎng)景、參數(shù)約束、缺省策略的完整描述調(diào)用時(shí)機(jī)準(zhǔn)確、參數(shù)完整率明顯提升用戶(hù)在時(shí)間不全時(shí)會(huì)被反問(wèn)問(wèn)清楚最終我給日程技能寫(xiě)的是這樣一段當(dāng)用戶(hù)想要安排會(huì)議、創(chuàng)建提醒、規(guī)劃待辦事項(xiàng)時(shí)調(diào)用本技能。系統(tǒng)會(huì)讀取用戶(hù)提供的日期和時(shí)間自動(dòng)寫(xiě)入系統(tǒng)日歷。參數(shù) title 為事件標(biāo)題startDate 為 ISO8601 格式的開(kāi)始時(shí)間durationMinutes 為持續(xù)分鐘數(shù)。如果用戶(hù)沒(méi)有給出具體時(shí)間不要調(diào)用本技能應(yīng)當(dāng)先向用戶(hù)詢(xún)問(wèn)開(kāi)始時(shí)間。注意最后這句話——“如果用戶(hù)沒(méi)給出具體時(shí)間不要調(diào)用”。這是很多開(kāi)發(fā)者容易遺漏的關(guān)鍵約束。模型默認(rèn)傾向于“猜測(cè)并執(zhí)行”如果你不明確告訴它何時(shí)不該調(diào)用它會(huì)在信息不全時(shí)強(qiáng)行填一個(gè)當(dāng)前時(shí)間進(jìn)去。加上這個(gè)反例描述之后模型的調(diào)用準(zhǔn)確率提升非常顯著。另外我強(qiáng)烈建議在 description 里加入“示例”。比如對(duì)天氣查詢(xún)技能補(bǔ)一句“例如用戶(hù)問(wèn)‘上海明天冷不冷’應(yīng)當(dāng)傳 location上海date明天”模型會(huì)參考這個(gè)示例來(lái)構(gòu)造參數(shù)這比單純羅列字段描述有效得多。你可以把這理解為喂給模型的小樣本提示Function Calling 的場(chǎng)景下少量示例往往比一個(gè)嚴(yán)密的 JSON Schema 更管用。2.3 Agent 狀態(tài)驅(qū)動(dòng)的 UI 刷新Agent 的運(yùn)行不是一蹴而就的發(fā)起請(qǐng)求、等待模型返回、執(zhí)行技能、再次請(qǐng)求模型生成回復(fù)每個(gè)環(huán)節(jié)都有狀態(tài)變化。為了把過(guò)程展示清楚我定義了一個(gè)顯式的狀態(tài)枚舉enum AgentState: Equatable { case idle case thinking case executing(skill: String) case responding }這個(gè)狀態(tài)配合Observable之后SwiftUI 視圖可以直接根據(jù)狀態(tài)切換展示內(nèi)容thinking時(shí)顯示轉(zhuǎn)圈并輸出“正在思考”executing(skill:)時(shí)顯示一個(gè)技能卡片標(biāo)注當(dāng)前正在執(zhí)行的工具名稱(chēng)responding時(shí)顯示“正在組織回復(fù)”。我用了一個(gè)小技巧把狀態(tài)映射成界面上的“階段指示器”類(lèi)似一個(gè) Step 列表用戶(hù)能清楚看到當(dāng)下進(jìn)行到哪一步。實(shí)測(cè)下來(lái)這種過(guò)程可見(jiàn)性對(duì)主觀體驗(yàn)的提升巨大哪怕底層響應(yīng)慢一點(diǎn)用戶(hù)也會(huì)覺(jué)得應(yīng)用更“聰明”而不是卡頓。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 從零搭建技能注冊(cè)中心注冊(cè)中心是整個(gè)框架的核心數(shù)據(jù)結(jié)構(gòu)我設(shè)計(jì)得很輕本質(zhì)上是一個(gè)帶鎖的字典加一個(gè)描述列表MainActor final class SkillRegistry: ObservableObject { private var storage: [String: any Skill] [:] func register(_ skill: any Skill) { storage[skill.id] skill } func skill(for id: String) - (any Skill)? { return storage[id] } var descriptors: [SkillDescriptor] { storage.values.map { $0.descriptor } } }我把它標(biāo)成MainActor是有原因的Agent 的執(zhí)行和 UI 狀態(tài)經(jīng)常同步讀寫(xiě)放到主 actor 上可以避免一堆數(shù)據(jù)競(jìng)爭(zhēng)問(wèn)題。實(shí)際調(diào)用 Skill 的時(shí)候雖然可能涉及網(wǎng)絡(luò)請(qǐng)求、文件讀寫(xiě)但 Skill 內(nèi)部自己開(kāi)異步子任務(wù)注冊(cè)中心只負(fù)責(zé)同步查詢(xún)和枚舉因此不會(huì)阻塞 UI。App 啟動(dòng)時(shí)把所有內(nèi)置技能注冊(cè)進(jìn)去let registry SkillRegistry() registry.register(CreateEventSkill()) registry.register(WeatherQuerySkill()) registry.register(ReminderSkill())這一步我看到很多人在做的時(shí)候會(huì)糾結(jié)要不要用“自動(dòng)掃描”或“反射注冊(cè)”在 Swift 生態(tài)里沒(méi)必要手動(dòng)注冊(cè)幾個(gè)技能是十幾秒的事?lián)Q來(lái)的是清晰的依賴(lài)關(guān)系和編譯時(shí)就有的類(lèi)型檢查。3.2 實(shí)現(xiàn)一個(gè)真正可用的技能日歷日程寫(xiě)入以日程創(chuàng)建技能為例看一個(gè)完整的 Skill 實(shí)現(xiàn)長(zhǎng)什么樣。輸入?yún)?shù)用嵌套結(jié)構(gòu)這樣執(zhí)行方法里解碼會(huì)很干凈struct CreateEventSkill: Skill { var id: String { create_event } var descriptor: SkillDescriptor { SkillDescriptor( id: id, name: 創(chuàng)建日歷日程, description: 當(dāng)用戶(hù)想要安排會(huì)議、創(chuàng)建提醒、規(guī)劃待辦事項(xiàng)時(shí)調(diào)用……, parametersSchema: { type: object, properties: { title: { type: string, description: 日程標(biāo)題 }, startDate: { type: string, format: date-time, description: 開(kāi)始時(shí)間ISO8601格式 }, durationMinutes: { type: integer, description: 持續(xù)分鐘數(shù)默認(rèn)30 }, notes: { type: string, description: 日程備注可選 } }, required: [title, startDate] } ) } private struct Input: Codable { let title: String let startDate: String let durationMinutes: Int? let notes: String? } func execute(input: Data) async throws - SkillResult { let params try JSONDecoder().decode(Input.self, from: input) let store try await withCheckedThrowingContinuation { continuation in // EventKit 的授權(quán)和寫(xiě)入代碼省略 } let message 已創(chuàng)建日程\(params.title)開(kāi)始時(shí)間 \(params.startDate) return SkillResult(success: true, output: message) } }注意durationMinutes在 Input 中是可選類(lèi)型。模型經(jīng)常不填不必要字段如果把它設(shè)為必填會(huì)因?yàn)槿眳?shù)導(dǎo)致解碼失敗。所以在 schema 里我只把title和startDate設(shè)成 required其他字段要么給默認(rèn)值要么走“可選 代碼兜底”的策略。這一點(diǎn)非常關(guān)鍵LLM 輸出的 JSON 不像人手寫(xiě)的那么穩(wěn)定寬松解碼、默認(rèn)值兜底能省掉大量調(diào)錯(cuò)時(shí)間。3.3 自然語(yǔ)言到技能調(diào)用的完整流程有了注冊(cè)中心和 Skill 實(shí)例接下來(lái)是 AgentCore 的核心循環(huán)。我用的是一個(gè)比較標(biāo)準(zhǔn)的工具調(diào)用流程func processUserInput(_ text: String) async { state .thinking let messages buildMessages(addingUserText: text) let firstResponse try await llmProvider.chat( messages: messages, tools: registry.descriptors ) // 模型決定調(diào)用工具 if let call firstResponse.toolCall { state .executing(skill: call.name) guard let skill registry.skill(for: call.name) else { // 技能不存在把錯(cuò)誤反饋給模型 return } do { let result try await skill.execute(input: call.argumentsData) // 工具結(jié)果回傳給模型讓模型組織自然語(yǔ)言回復(fù) let finalResponse try await llmProvider.chat( messages: messages [ toolResultMessage(name: call.name, content: result.output) ] ) appendMessage(finalResponse) } catch { // 失敗時(shí)直接把錯(cuò)誤信息作為工具結(jié)果給模型 let errorMessage toolResultMessage( name: call.name, content: 執(zhí)行失敗\(error.localizedDescription) ) let retryResponse try await llmProvider.chat(messages: messages [errorMessage]) appendMessage(retryResponse) } } else { // 模型沒(méi)有調(diào)用工具直接回復(fù) appendMessage(firstResponse.message) } state .idle }這個(gè)流程最精華的地方在第 24 行到第 30 行Skill 執(zhí)行失敗時(shí)不是簡(jiǎn)單地把錯(cuò)誤拋給用戶(hù)而是把錯(cuò)誤信息重新交給 LLM讓模型自己決定是修正參數(shù)重試、還是換一個(gè)表達(dá)方式解釋問(wèn)題。比如模型調(diào)用日程技能時(shí)傳了一個(gè)已經(jīng)被占用的事件 ID技能返回錯(cuò)誤模型會(huì)在下一輪回復(fù)中告訴用戶(hù)“這個(gè)時(shí)段已有日程建議換到下午三點(diǎn)”而不是顯示一句冷冰冰的系統(tǒng)錯(cuò)誤。實(shí)際測(cè)試時(shí)我還發(fā)現(xiàn)給模型傳參數(shù)時(shí)保留原始 JSON 比編碼成字符串更可靠。call.argumentsData是模型返回的原始 JSON 數(shù)據(jù)解碼成Input時(shí)類(lèi)型更干凈。如果中間轉(zhuǎn)一次字符串格式偶爾會(huì)多出轉(zhuǎn)義符導(dǎo)致解碼失敗。3.4 接入 SwiftUI 視圖層UI 層我用一個(gè)AgentViewModel封裝狀態(tài)和邏輯Observable final class AgentViewModel { var messages: [ChatMessage] [] private(set) var state: AgentState .idle private let registry SkillRegistry() private let agent AgentCore() func send(_ text: String) async { let userMessage ChatMessage(role: .user, content: text) messages.append(userMessage) await agent.processUserInput(text) } }視圖層就變得很直白了struct ChatView: View { State private var vm AgentViewModel() var body: some View { VStack { List(vm.messages) { message in MessageRow(message: message) } if case .executing(let skillName) vm.state { SkillStatusCard(name: skillName) } InputBar { Task { await vm.send($0) } } } } }SkillStatusCard是我額外加的一個(gè)小組件它把“當(dāng)前在調(diào)用什么技能”變成可見(jiàn)狀態(tài)。你可以在這里加進(jìn)度條、技能圖標(biāo)、耗時(shí)統(tǒng)計(jì)都不影響核心邏輯。這個(gè)設(shè)計(jì)還有一個(gè)好處以后要接 IPC、推送或桌面小組件來(lái)展示 Agent 進(jìn)度可以直接復(fù)用同一個(gè)狀態(tài)源。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄這一節(jié)的內(nèi)容是我在真機(jī)調(diào)試和連續(xù)多天日常使用中積攢下來(lái)的。很多坑是意想不到的列出來(lái)給各位參考。4.1 模型返回的參數(shù) JSON 不合法LLM 輸出的tool_calls里的參數(shù)不一定每次都是合法 JSON。我遇到比較多的情況包括字段名被縮寫(xiě)、時(shí)間格式不是 ISO8601、數(shù)字被判定成字符串等。最典型的一次是模型把startDate: 2025-03-01 10:00傳進(jìn)來(lái)而不是2025-03-01T10:00:00Z導(dǎo)致解碼器直接拋錯(cuò)。我的解決方案是分兩層處理。第一層是捕獲解碼錯(cuò)誤時(shí)把錯(cuò)誤信息回傳給 LLM讓模型自己修正格式第二層是給核心字段寫(xiě)寬松解析比如時(shí)間字段用ISO8601DateFormatter嘗試多種格式解析不了再拋錯(cuò)。這兩層配合后絕大部分情況都能自動(dòng)通過(guò)。4.2 并發(fā)更新 UI 導(dǎo)致視圖卡頓早期版本我直接在execute方法里調(diào)用 EventKit 寫(xiě)入EventKit的接口是同步的寫(xiě)日歷的操作會(huì)阻塞當(dāng)前線程。因?yàn)?AgentCore 的調(diào)用鏈?zhǔn)窃谥骶€程上跑的結(jié)果就是點(diǎn)擊發(fā)送后整個(gè)界面僵住一兩秒。排查思路很直接在 Xcode 的 Instruments 里看 Time Profiler發(fā)現(xiàn)主線程上有大量 EventKit 堆棧占用。修復(fù)方式是所有耗時(shí)操作都放到獨(dú)立的異步函數(shù)里并用await等待確保主線程只做 UI 更新?？蚣軐用嬉部梢约右坏婪烙oSkillRegistry加上MainActor但 Skill 的execute用nonisolated或者放到后臺(tái)任務(wù)隊(duì)列里執(zhí)行。4.3 同一個(gè)技能被并發(fā)調(diào)用導(dǎo)致?tīng)顟B(tài)沖突多輪對(duì)話里用戶(hù)可能在上一輪技能還沒(méi)執(zhí)行完就發(fā)送了新消息。比如問(wèn)“幫我查天氣”馬上又跟一句“順便建個(gè)日程”。如果不加控制兩條流程會(huì)同時(shí)執(zhí)行日歷寫(xiě)入就可能和天氣查詢(xún)的狀態(tài)互相覆蓋。我最后用了一個(gè)簡(jiǎn)單的串行隊(duì)列AgentCore 內(nèi)部維護(hù)一個(gè)Task鏈新的輸入會(huì)等待上一個(gè)任務(wù)結(jié)束后再執(zhí)行。極端情況下你可以用AsyncSemaphore做并發(fā)控制但對(duì)絕大多數(shù)應(yīng)用場(chǎng)景來(lái)說(shuō)串行處理用戶(hù)輸入是符合預(yù)期的——因?yàn)閷?duì)話本身就有先后順序用戶(hù)很少需要真正并發(fā)的 Agent 處理。4.4 技能注冊(cè)了但模型就是不調(diào)用這個(gè)問(wèn)題最隱蔽也是最讓人惱火的技能明明注冊(cè)了描述寫(xiě)得也不錯(cuò)但模型就是視而不見(jiàn)。我排查后發(fā)現(xiàn)主要是兩個(gè)原因。第一個(gè)原因是注冊(cè)順序。有些 LLM 服務(wù)商對(duì)工具列表的長(zhǎng)度和順序敏感工具過(guò)多時(shí)偶爾會(huì)忽略排在后面的工具。解決辦法是給工具列表按調(diào)用頻率排序常用技能放前面或者把一個(gè) Agent 負(fù)責(zé)的技能數(shù)量控制在 5-8 個(gè)以?xún)?nèi)。第二個(gè)原因是名字和描述里的關(guān)鍵詞不匹配。模型是根據(jù)文本相關(guān)性來(lái)判斷何時(shí)調(diào)用技能的如果用戶(hù)在輸入里用了“改期”“挪一下時(shí)間”而技能描述里只寫(xiě)了“創(chuàng)建日程”模型就會(huì)猶豫。我的經(jīng)驗(yàn)是在描述里把常見(jiàn)的同義說(shuō)法都列一遍“改期、延期、換時(shí)間、重新安排都可以調(diào)用本技能”。這樣模型的命中率會(huì)大幅提高。4.5 狀態(tài)機(jī)狀態(tài)殘留與 UI 卡死還有一個(gè)值得記錄的問(wèn)題如果用戶(hù)發(fā)送消息后立刻切后臺(tái)或者 LLM 請(qǐng)求超時(shí)狀態(tài)機(jī)可能停在executing狀態(tài)界面一直顯示“正在調(diào)用技能”。排查后發(fā)現(xiàn)是異常分支沒(méi)有清理狀態(tài)。修復(fù)方式是在processUserInput外面套一個(gè)defer確保無(wú)論什么路徑退出最終都會(huì)回到state .idle。這個(gè)經(jīng)驗(yàn)對(duì)所有異步狀態(tài)機(jī)都通用狀態(tài)恢復(fù)必須和退出綁定而不是只放在成功分支里。為了便于參考我把典型問(wèn)題整理成一個(gè)簡(jiǎn)潔的速查表問(wèn)題根因處理方案參數(shù)解碼失敗LLM 輸出的 JSON 格式不合規(guī)寬容解碼 錯(cuò)誤信息回傳 LLM 重試界面卡頓同步操作阻塞主線程耗時(shí)任務(wù)異步化主線程只刷 UI狀態(tài)互相覆蓋并發(fā)處理用戶(hù)輸入AgentCore 內(nèi)維護(hù)串行任務(wù)隊(duì)列技能不觸發(fā)描述缺少場(chǎng)景關(guān)鍵詞列全同義說(shuō)法控制技能總數(shù)狀態(tài)卡死異常分支未恢復(fù)狀態(tài)用 defer 確保狀態(tài)回歸 idle5. 性能優(yōu)化與后續(xù)擴(kuò)展路徑5.1 抽象 LLM Provider 以支持切換框架運(yùn)行的核心依賴(lài)是 LLM 返回結(jié)果但我不希望整個(gè)項(xiàng)目綁死在哪一家模型服務(wù)上。所以我抽了一個(gè)LLMProvider協(xié)議讓所有模型請(qǐng)求都走統(tǒng)一接口protocol LLMProvider: Sendable { func chat( messages: [ChatMessage], tools: [SkillDescriptor] ) async throws - LLMResponse }這樣 AgentCore 完全不知道底層是云端大模型、私有化部署還是端側(cè)模型只要實(shí)現(xiàn)協(xié)議就能運(yùn)行。我日常調(diào)試用的是一個(gè)輕量級(jí)云端接口同時(shí)也在實(shí)驗(yàn)把簡(jiǎn)單意圖識(shí)別分流到端側(cè)模型減少不必要的網(wǎng)絡(luò)請(qǐng)求。這個(gè)抽象對(duì)后續(xù)做多模型切換、灰度測(cè)試、離線模式都很有價(jià)值。5.2 從單技能調(diào)用走向多技能編排當(dāng)前實(shí)現(xiàn)處理的是“一輪對(duì)話調(diào)用一個(gè)技能”但實(shí)際用戶(hù)需求經(jīng)常是復(fù)合的“幫我查下明天天氣如果下雨就提醒我?guī)恪?。這需要 Agent 具備多步推理和編排能力。我計(jì)劃引入一個(gè)簡(jiǎn)單的計(jì)劃器當(dāng)意圖識(shí)別為復(fù)合任務(wù)時(shí)Agent 先拆解出子任務(wù)清單逐個(gè)執(zhí)行對(duì)應(yīng) Skill再用最終結(jié)果組裝回復(fù)。技術(shù)上就是在一個(gè)循環(huán)里重復(fù)“調(diào) LLM → 執(zhí)行工具 → 回傳工具結(jié)果”直到 LLM 認(rèn)為所有子任務(wù)完成。這個(gè)模式的工程改造成本不大但能明顯提升真實(shí)場(chǎng)景的可用性。5.3 離線技能與隱私邊界蘋(píng)果生態(tài)里用戶(hù)對(duì)隱私的敏感度很高這個(gè)項(xiàng)目也天然適合做端側(cè)優(yōu)先本地日歷、提醒、文件都是不需要聯(lián)網(wǎng)就能執(zhí)行的 Skill。真正需要聯(lián)網(wǎng)的只有 LLM 請(qǐng)求本身。我調(diào)研過(guò) iOS 17 起引入的端側(cè)自然語(yǔ)言框架可以用它做短文本的意圖分類(lèi)把“打開(kāi)設(shè)置”“新建備忘錄”這類(lèi)簡(jiǎn)單請(qǐng)求直接映射到本地技能不經(jīng)過(guò)網(wǎng)絡(luò)響應(yīng)速度快、隱私性也好。LLM 更多是被用來(lái)處理需要復(fù)雜理解的長(zhǎng)尾請(qǐng)求。這種混合調(diào)度的思路既控制了成本也提升了體驗(yàn)是后續(xù)比較理想的演進(jìn)方向。最后說(shuō)一個(gè)我實(shí)際開(kāi)發(fā)中的體會(huì)Agent 項(xiàng)目調(diào)試時(shí)最大的成本其實(shí)不在代碼而在于和 LLM 交互時(shí)的“預(yù)期管理”。你寫(xiě)了一個(gè)技能描述以為模型一定能理解但它就是會(huì)用偏。我的辦法是在開(kāi)發(fā)階段寫(xiě)了不少自動(dòng)化測(cè)試用例把典型用戶(hù)語(yǔ)句喂進(jìn)去檢查模型是否選對(duì)技能、參數(shù)是否合理。這樣每次調(diào)整描述或 schema 后跑一遍用例回歸很快就能迭代出穩(wěn)定的表現(xiàn)。如果你打算把這套模式用到自己的項(xiàng)目里我強(qiáng)烈建議你從第一天就保留這樣的測(cè)試集它會(huì)是你最可靠的護(hù)航工具。