1. 从“SwiftUI-Agent-Skill”这个名字说起它到底想解决什么第一次看到“SwiftUI-Agent-Skill”这个组合词我的直觉是这大概率不是某个官方框架而是一个把三件事揉在一起的项目命名——SwiftUI 的界面能力、Agent 的自主决策能力、以及Skill 的可复用封装。换句话说它想做的事情是让一个具备自主行为的智能体能够通过一套标准化的“技能包”去驱动 SwiftUI 构建的界面完成一系列原本需要人工点击、输入、判断的操作。为什么我会这么判断因为单独看这三个词各自都有明确的指向。SwiftUI 是苹果生态里声明式 UI 的代表写界面快、状态驱动清晰Agent 在近两年的技术语境里通常指能感知环境、做出决策、执行动作的智能实体Skill 则强调“可插拔、可复用、有明确输入输出边界”的能力单元。把三者拼在一起最合理的解释就是用 Skill 的形式把 SwiftUI 界面操作或界面生成能力封装成 Agent 可以调用的工具。这个方向解决的真实问题很具体。过去我们做自动化测试、做界面辅助、做流程机器人往往要写大量针对具体控件的硬编码逻辑按钮在哪、输入框叫什么、点击顺序是什么。一旦界面改版脚本全废。而如果让 Agent 通过“技能”去理解当前界面状态再决定下一步动作整个系统的鲁棒性和可维护性会完全不一样。它适合谁参考我认为三类人最该关注一是做 iOS/macOS 自动化工具链的开发者二是研究 Agent 工具调用Tool Use / Function Calling的工程人员三是想给自家 App 加“智能操作层”的产品技术团队。需要提前说明的是由于输入里项目正文、关键词、摘要都是空的下面所有关于架构、步骤、参数的展开都是基于“一名合格从业者在构建此类系统时最可能采用的合理方案”进行的逻辑补全。我会尽量把每个选择的理由讲透让你能直接拿去改、拿去用。2. 拆解核心架构Agent、Skill、SwiftUI 三者如何握手2.1 为什么不能让 Agent 直接操作 SwiftUI 视图树很多人第一反应是Agent 既然能调用工具那我直接把 SwiftUI 的 View 树暴露给它不就行了实测下来这条路走不通原因有三层。第一层是语义鸿沟。SwiftUI 的视图树是声明式的、带大量泛型与修饰符的结构一个简单的Button背后可能嵌套了ModifiedContent、_ConditionalContent等一堆包装类型。Agent 拿到这棵树就像让一个只会看地图的人去读电路板信息全在但无法决策。第二层是状态同步问题。SwiftUI 的界面由State、Binding、Observable等状态源驱动视图树只是某一时刻的投影。Agent 如果直接改视图下一次状态刷新就会把它的修改冲掉产生“我明明点了但没生效”的诡异现象。第三层是安全与边界。让一个自主决策的 Agent 拥有任意修改界面的能力等于把整个 App 的控制权交出去。一旦它的决策逻辑跑偏用户看到的就是界面乱跳、数据错乱。所以正确的做法是在 Agent 和 SwiftUI 之间加一层 Skill 抽象层。Agent 只跟 Skill 打交道Skill 负责把高层意图翻译成对 SwiftUI 状态或系统 API 的合法调用。这一层是整个项目的心脏。2.2 Skill 的接口设计输入、输出与副作用一个可用的 Skill我建议按下面的结构来定义。它不是某个官方标准而是我在多个类似项目里总结出的、最不容易翻车的形态。struct SkillDescriptor { let name: String // 技能名如 tapElement let description: String // 给 Agent 看的自然语言说明 let parameters: [SkillParam] // 参数 schema let handler: (SkillContext) async throws - SkillResult } struct SkillParam { let name: String let type: ParamType // string / number / bool / enum let required: Bool let description: String } struct SkillResult { let success: Bool let payload: [String: Any] // 返回给 Agent 的结构化数据 let errorMessage: String? }这里有几个关键设计点值得展开。description 字段是给 Agent 读的不是给人读的所以它必须写得像“操作手册”而不是“功能简介”。比如tapElement的描述应该写成“点击当前界面上匹配指定标识符的可交互元素若存在多个匹配则返回歧义错误”而不是“点击元素”。Agent 的决策质量极大程度取决于这段文字写得够不够精确。parameters 用 schema 而不是裸字典是为了让 Agent 在调用前就能知道自己该传什么。现代 Agent 框架大多支持 JSON Schema 形式的工具定义把参数类型、是否必填、枚举值写清楚能显著降低调用失败率。handler 返回结构化结果而不是抛异常了事是因为 Agent 需要根据结果决定下一步。比如点击失败时它可能想先滚动屏幕再重试而不是直接放弃。把错误信息作为正常返回值的一部分比抛异常更利于 Agent 做恢复决策。2.3 SwiftUI 侧的“可操作性”改造Skill 要能操作界面界面本身得先“可被操作”。SwiftUI 原生提供了accessibilityIdentifier这本来是为无障碍功能设计的但用在 Agent 场景里简直是天赐之物。Button(提交) { submit() } .accessibilityIdentifier(submit_button) TextField(请输入, text: $input) .accessibilityIdentifier(input_field)给每个需要被 Agent 操作的元素加上稳定的标识符Skill 层就能通过标识符去查找元素而不是靠坐标或文本匹配。坐标会随屏幕尺寸变文本会随语言变只有标识符是稳定的。但光有标识符还不够。SwiftUI 没有提供“运行时遍历视图树并找到某个标识符对应元素”的公开 API这是很多人卡住的地方。我的做法是维护一份注册表在视图出现时把标识符和对应的操作闭包注册到一个全局的SkillRegistry里。struct SkillRegistry { static var shared SkillRegistry() private var actions: [String: () - Void] [:] private var values: [String: () - Any] [:] mutating func registerAction(id: String, action: escaping () - Void) { actions[id] action } func perform(id: String) - Bool { guard let action actions[id] else { return false } action() return true } }然后在视图里这样挂载Button(提交) { submit() } .accessibilityIdentifier(submit_button) .onAppear { SkillRegistry.shared.registerAction(id: submit_button) { submit() } }这个模式的好处是Skill 层完全不需要理解 SwiftUI 的视图树它只需要知道“有个叫 submit_button 的动作可以执行”。视图怎么改版、层级怎么变只要标识符和注册逻辑还在Skill 就照常工作。这就是关注点分离带来的稳定性。3. 把 Skill 暴露给 Agent工具调用协议怎么定3.1 工具描述文档的生成策略Agent 要调用 Skill首先得“知道有哪些 Skill”。这一步通常是把所有 SkillDescriptor 序列化成一份工具清单喂给 Agent 的推理环节。问题在于Skill 多了之后这份清单会变得很长占用大量上下文窗口还会让 Agent 的选择变慢。我的经验是分层暴露。把 Skill 按功能域分组比如“界面操作类”“数据查询类”“导航类”Agent 先选组再选具体技能。这样每次喂给它的清单只有当前组的内容上下文压力小很多。另一个技巧是动态裁剪。根据当前界面状态只暴露那些“此刻可执行”的 Skill。比如当前页面没有输入框那inputText这个技能就没必要出现在清单里。实现方式是在生成工具清单时先跑一遍可用性检查。func availableSkills(for context: SkillContext) - [SkillDescriptor] { allSkills.filter { $0.isAvailable(context) } }isAvailable可以检查当前页面是否有对应标识符的元素、是否处于可交互状态等。这个过滤逻辑本身也是 Skill 的一部分需要认真设计。3.2 参数校验与歧义处理Agent 生成的参数不总是合法的。它可能传了一个不存在的标识符可能把数字传成了字符串也可能漏传了必填项。Skill 层必须做严格校验并且把错误信息写得足够具体让 Agent 能自我纠正。func validate(_ params: [String: Any], against schema: [SkillParam]) - ValidationResult { for param in schema where param.required { guard params[param.name] ! nil else { return .failure(缺少必填参数 \(param.name)\(param.description)) } } // 类型校验、枚举校验略 return .success }注意错误信息里我特意带上了参数的 description。这样 Agent 看到错误后能直接理解这个参数是干什么的下次调用就更可能传对。这比单纯说“参数缺失”有用得多。歧义处理是另一个高频问题。比如界面上有两个都叫“确认”的按钮Agent 说“点击确认”Skill 该点哪个我的做法是返回歧义错误并附带候选列表让 Agent 重新决策。{ success: false, errorMessage: 找到 2 个匹配元素无法确定目标, candidates: [ {id: confirm_dialog, label: 对话框确认}, {id: confirm_form, label: 表单确认} ] }Agent 拿到这个结果就能结合上下文判断该点哪个或者向用户澄清。这比 Skill 自己猜一个要好得多。3.3 执行结果的回传格式Skill 执行完回传给 Agent 的数据格式直接影响后续决策质量。我建议遵循三个原则结构化、可读、带上下文。结构化是指用 JSON 而不是自然语言。Agent 解析 JSON 比解析散文可靠得多。可读是指字段名要自解释别用r、s这种缩写。带上下文是指除了结果本身还要带上“当前状态快照”比如操作后界面变成了什么样。{ success: true, action: tapElement, target: submit_button, stateAfter: { currentScreen: result_page, visibleElements: [back_button, share_button] } }stateAfter这个字段特别有用。Agent 不用再单独调一次“查询当前界面”的技能就能知道操作后的状态减少一轮交互。在 Agent 场景里每一轮交互都是成本能省则省。4. 实战搭建从零跑通一个最小可用版本4.1 环境准备与项目骨架先说环境。SwiftUI 部分需要 Xcode 15 以上、iOS 17 以上的目标版本因为要用到Observable宏来简化状态管理。Agent 部分我建议先用一个本地的推理循环来模拟不要一上来就接远程模型那样调试成本太高。项目骨架我习惯分成四个模块App 层SwiftUI 视图和状态负责界面呈现。SkillKit 层Skill 的定义、注册、校验、执行。AgentCore 层决策循环负责选技能、生成参数、处理结果。Bridge 层把 SkillKit 的能力暴露给 AgentCore把 AgentCore 的决策转成 Skill 调用。Bridge 层是最容易被忽略但最关键的。它定义了 Agent 和 Skill 之间的契约一旦契约稳定两边可以独立演进。我通常把契约写成一个协议protocol SkillProvider { func listSkills() - [SkillDescriptor] func execute(skillName: String, params: [String: Any]) async throws - SkillResult }AgentCore 只依赖这个协议不关心 Skill 是怎么实现的。这样以后要把 Skill 换成远程服务、换成另一套实现AgentCore 一行都不用改。4.2 第一个 Skill点击元素我们从最简单的tapElement开始。它的职责是根据标识符找到对应元素并触发其动作。let tapElementSkill SkillDescriptor( name: tapElement, description: 点击当前界面上指定标识符的可交互元素。若标识符不存在返回 notFound若匹配多个返回 ambiguous。, parameters: [ SkillParam(name: identifier, type: .string, required: true, description: 目标元素的 accessibilityIdentifier) ], handler: { context in let id context.params[identifier] as? String ?? guard !id.isEmpty else { return SkillResult(success: false, payload: [:], errorMessage: identifier 不能为空) } let ok SkillRegistry.shared.perform(id: id) if ok { return SkillResult(success: true, payload: [tapped: id], errorMessage: nil) } else { return SkillResult(success: false, payload: [:], errorMessage: 未找到标识符为 \(id) 的可点击元素) } } )这段代码看起来简单但有几个细节值得说。description 里明确写了两种失败模式这是为了让 Agent 提前知道可能遇到什么从而在决策时留好退路。handler 里先做参数校验再做执行避免把非法参数传到注册表里。返回结果里带上 tapped 字段方便 Agent 确认操作对象。注册这个 Skill 只需要一行SkillKit.shared.register(tapElementSkill)4.3 第二个 Skill读取界面状态Agent 要决策得先知道当前界面长什么样。queryState这个 Skill 负责返回当前可见元素清单。let queryStateSkill SkillDescriptor( name: queryState, description: 返回当前界面上所有可交互元素的标识符与标签用于决策下一步操作。, parameters: [], handler: { _ in let elements SkillRegistry.shared.visibleElements() return SkillResult(success: true, payload: [elements: elements], errorMessage: nil) } )visibleElements的实现依赖注册表里维护的元素元信息。我建议在注册动作时顺便把标签也存进去mutating func registerAction(id: String, label: String, action: escaping () - Void) { actions[id] action labels[id] label }这样queryState返回的就是[{id: submit_button, label: 提交}]这样的结构Agent 一看就懂。4.4 第三个 Skill输入文本输入比点击复杂因为涉及焦点管理和文本绑定。SwiftUI 里TextField的文本是通过Binding控制的Skill 没法直接“往输入框里打字”只能改绑定值。我的做法是让视图在注册时提供一个 setter 闭包TextField(请输入, text: $input) .accessibilityIdentifier(input_field) .onAppear { SkillRegistry.shared.registerSetter(id: input_field) { newValue in input newValue as? String ?? } }然后 Skill 这样实现let inputTextSkill SkillDescriptor( name: inputText, description: 向指定标识符的输入框写入文本。会覆盖原有内容。, parameters: [ SkillParam(name: identifier, type: .string, required: true, description: 输入框标识符), SkillParam(name: text, type: .string, required: true, description: 要写入的文本) ], handler: { context in let id context.params[identifier] as? String ?? let text context.params[text] as? String ?? let ok SkillRegistry.shared.performSet(id: id, value: text) return SkillResult(success: ok, payload: ok ? [input: id, length: text.count] : [:], errorMessage: ok ? nil : 输入框 \(id) 不存在或不可写) } )注意返回里带了length而不是原文。这是出于隐私考虑——Agent 不需要知道用户输入的具体内容只需要知道写入了多少字符。这个细节在涉及敏感信息的场景里很重要。4.5 串起来一个完整的决策循环三个 Skill 就位后Agent 的决策循环可以这样写func runAgentLoop(goal: String, maxSteps: Int 10) async { var step 0 while step maxSteps { let state try? await skillProvider.execute(skillName: queryState, params: [:]) let skills skillProvider.listSkills() let decision await agent.decide(goal: goal, state: state, skills: skills) guard let decision decision else { break } let result try? await skillProvider.execute( skillName: decision.skillName, params: decision.params ) if result?.success true decision.isTerminal { break } step 1 } }这个循环里agent.decide是核心它接收目标、当前状态、可用技能输出下一步动作。isTerminal标记表示这个动作完成后目标达成可以退出循环。maxSteps是安全阀防止 Agent 陷入死循环。实测下来这个最小版本已经能完成“填写表单并提交”这类任务。但离生产可用还有距离下面几节讲的就是从能跑到好用的那些坑。5. 踩坑实录那些让 Agent 行为失控的细节5.1 状态刷新时机导致的“幽灵点击”最早跑通点击 Skill 后我遇到一个诡异现象Agent 报告点击成功但界面毫无反应。排查了半天发现是状态刷新时机的问题。SwiftUI 的状态更新是异步的。当 Skill 调用submit()修改了State视图不会立刻重建而是要等到下一个渲染周期。如果 Agent 在点击后立刻调queryState拿到的还是旧状态于是它以为点击没生效又点了一次造成重复提交。解决办法是在 Skill 执行后主动等待一个渲染周期再返回。可以用Task { MainActor in ... }配合await Task.yield()来让出执行权等 SwiftUI 完成刷新。handler: { context in let ok SkillRegistry.shared.perform(id: id) await Task.yield() // 让出等 SwiftUI 刷新 return SkillResult(success: ok, ...) }这个Task.yield()看起来不起眼但它把“幽灵点击”问题彻底解决了。类似的时机问题在导航跳转、弹窗弹出等场景都会出现统一加一个 yield 是最省事的做法。5.2 标识符冲突当两个元素叫同一个名字第二个坑是标识符冲突。开发时随手给两个按钮都写了accessibilityIdentifier(button)结果 Agent 点击时随机命中一个行为完全不可预测。这个问题在代码审查阶段很难发现因为标识符不影响正常用户操作。我的做法是在注册表里做唯一性检查重复注册时直接报错。mutating func registerAction(id: String, label: String, action: escaping () - Void) { precondition(actions[id] nil, 标识符 \(id) 已被注册请检查是否有重复) actions[id] action labels[id] label }precondition在 Debug 构建里会直接崩溃逼着开发者改掉重复标识符。Release 构建里它会被优化掉不影响性能。这个策略比运行时返回错误更有效因为它把问题暴露在开发阶段。另外我建议给标识符定一套命名规范比如页面名_元素类型_用途像login_button_submit、profile_field_nickname。规范本身不强制但团队里统一了之后冲突概率会大幅下降。5.3 Agent 陷入“查询-决策-查询”死循环第三个坑最隐蔽Agent 反复调用queryState但从不执行实际操作。日志里看它每轮都在“思考”但界面纹丝不动。根因是决策提示词里没有强调“必须推进”。Agent 看到状态后觉得信息不够想再查一次于是陷入循环。解决方式有两个层面。提示词层面明确告诉它“如果连续两次查询状态没有变化必须执行一个改变状态的操作”。代码层面加一个状态指纹机制每次queryState返回时计算一个哈希如果连续 N 次哈希相同就强制 Agent 从可用技能里选一个非查询类的执行。var lastStateHash: Int? var stagnantCount 0 func checkStagnation(currentHash: Int) - Bool { if currentHash lastStateHash { stagnantCount 1 } else { stagnantCount 0 lastStateHash currentHash } return stagnantCount 2 }这个机制救过我好几次。Agent 的自主性是把双刃剑没有这类护栏它很容易在某个局部最优里打转。5.4 异步操作的竞态点击后立刻查询第四个坑和第一个相关但更微妙。有些操作是异步的比如点击“加载更多”后要等网络请求回来列表才会更新。Agent 点击后立刻查询看到列表没变就以为失败了。这种场景下Skill 需要支持等待条件。我加了一个waitFor参数让 Agent 可以指定“等到某个标识符出现为止”。SkillParam(name: waitFor, type: .string, required: false, description: 可选。指定一个标识符Skill 会等待该元素出现后再返回最多等 5 秒。)handler 里用轮询实现if let waitId context.params[waitFor] as? String { let deadline Date().addingTimeInterval(5) while Date() deadline { if SkillRegistry.shared.exists(id: waitId) { break } try? await Task.sleep(nanoseconds: 100_000_000) } }100 毫秒的轮询间隔是个经验值。太短了浪费 CPU太长了响应迟钝。5 秒超时也是经验值覆盖大多数网络请求场景又不至于让 Agent 等太久。6. 让 Skill 体系真正可维护的几个工程习惯6.1 Skill 的版本管理与兼容性Skill 一旦被 Agent 依赖就不能随便改接口。改个参数名Agent 的调用就全废了。我的做法是给每个 Skill 加版本号接口变更时升版本而不是改原接口。struct SkillDescriptor { let name: String let version: Int // ... }Agent 调用时指定版本SkillKit 负责路由到对应实现。旧版本保留一段时间等所有 Agent 都迁移完再下线。这套机制在 Skill 数量少的时候显得多余但一旦超过二十个没有版本管理会非常痛苦。6.2 用日志还原 Agent 的决策链路调试 Agent 最头疼的是“它为什么这么做”。光看最终结果完全猜不出中间发生了什么。我的做法是每个环节都打结构化日志Agent 收到的状态、它生成的决策、Skill 收到的参数、Skill 返回的结果全部按时间戳串起来。struct AgentTrace { let timestamp: Date let step: Int let stateHash: Int let decision: String let params: [String: Any] let result: String }把这些 trace 存下来出问题时能完整回放。我甚至写了个小工具把 trace 渲染成时间线视图一眼就能看出 Agent 在哪一步跑偏了。这个投入在项目初期看似浪费但省下的调试时间远超写它的成本。6.3 给 Skill 写“契约测试”Skill 的接口是 Agent 和界面之间的契约这个契约必须稳定。我习惯给每个 Skill 写一组契约测试覆盖正常路径、参数缺失、标识符不存在、歧义匹配等场景。func testTapElement_NotFound() async { let result try? await skillProvider.execute( skillName: tapElement, params: [identifier: nonexistent] ) XCTAssertEqual(result?.success, false) XCTAssertTrue(result?.errorMessage?.contains(未找到) ?? false) }这些测试跑得快、覆盖关键路径每次改 Skill 实现都跑一遍能挡住大部分回归问题。更重要的是它们把“Skill 应该怎么表现”这件事文档化了新同学接手时看测试比看实现更快。6.4 性能考量Skill 调用的开销Skill 调用本身开销不大但 Agent 的决策循环可能很频繁。我实测过一个中等复杂度的界面Agent 完成一个任务平均要 6 到 8 轮交互每轮涉及一次状态查询和一次操作。如果每轮决策要调远程模型延迟会累积到好几秒。优化方向有两个。一是本地缓存状态queryState的结果在短时间内可以复用不必每次都重新遍历注册表。二是批量操作如果 Agent 明确知道要连续做几步可以提供一个executeSequence技能把多个操作打包执行减少往返。let executeSequenceSkill SkillDescriptor( name: executeSequence, description: 按顺序执行多个技能任一失败则中止并返回已执行的部分。, parameters: [ SkillParam(name: steps, type: .array, required: true, description: 步骤数组每项包含 skillName 和 params) ], handler: { context in // 依次执行收集结果 } )这个技能在表单填写场景特别有用Agent 可以一次性提交“填姓名、填电话、点提交”三步而不是来回三轮。7. 这套模式还能往哪些方向延伸跑通基础版本后我陆续试了几个延伸方向有些效果不错有些还在摸索。方向一是把 Skill 从“操作界面”扩展到“生成界面”。既然 Skill 能改状态那它也能根据 Agent 的意图动态构建视图。比如 Agent 说“展示一个包含三个选项的对话框”Skill 就生成对应的 SwiftUI 视图并挂载。这让 Agent 从“操作者”变成“创造者”适合做动态表单、自适应引导这类场景。方向二是引入 Skill 的组合与嵌套。单个 Skill 是原子操作但真实任务往往是复合的。我试过让 Skill 之间可以互相调用比如fillForm内部调用多次inputText。这样 Agent 面对高层任务时只需要调一个复合技能决策负担小很多。代价是复合技能的设计更复杂需要仔细定义失败回滚策略。方向三是把 Skill 的执行结果反馈给 Agent 做学习。每次任务完成后记录哪些 Skill 组合成功率高、哪些参数容易出错用这些数据去优化 Agent 的提示词或微调决策模型。这个方向我还在早期实验阶段但初步看经过几轮反馈后Agent 的首次调用成功率有明显提升。需要提醒的是这些延伸都建立在基础版本稳定的前提上。我见过不少项目一上来就追求复杂组合结果基础 Skill 的边界都没理清Agent 行为一团糟。先把三五个原子 Skill 打磨到可靠再考虑扩展这是我踩过坑之后最想强调的顺序。最后分享一个我在实际使用中养成的习惯每次给项目加新 Skill先问自己三个问题——它的输入输出边界清楚吗它的失败模式有哪些、都返回明确错误了吗它的标识符命名和现有 Skill 冲突吗这三个问题答不上来就先别加。Skill 体系的健康度比数量重要得多。