1. 这个标题到底在说什么第一次看到 SwiftUI-Agent-Skill 这个组合词我脑子里蹦出来的第一反应是这大概率不是一个官方框架也不是某个大厂放出来的 SDK而是某个开发者把三件当下最热的事情捏在了一起——SwiftUI 做界面、Agent 做决策、Skill 做能力封装。说白了就是想让一个智能体Agent具备操作 SwiftUI 界面的技能或者说让 SwiftUI 应用本身变成一个可以被智能体调用的能力集合。我先把这三个词拆开讲清楚不然后面没法聊。SwiftUI是苹果生态里声明式的 UI 框架写界面像写配置状态驱动视图State、Binding、Observable这些属性包装器是它的灵魂。它的核心特点是数据变了界面自己重绘开发者不用手动去reloadData或者setNeedsLayout。Agent这个词这两年被用烂了但落到工程上它其实就是一个能感知环境、能做决策、能执行动作的循环体。感知靠输入决策靠模型或者规则执行靠工具调用。它和传统的函数调用最大的区别在于Agent 有自主性它会根据当前状态决定下一步干什么而不是被一条固定的调用链牵着走。Skill则是 Agent 的能力单元。一个 Agent 可以挂载很多 Skill每个 Skill 负责一类具体任务比如读取当前界面状态点击某个按钮填写表单截图并分析。Skill 的设计好坏直接决定了 Agent 能不能真正干活。把这三个词拼在一起SwiftUI-Agent-Skill 的核心命题就是如何把 SwiftUI 应用里的界面元素和交互逻辑抽象成 Agent 可以理解和调用的 Skill从而让智能体能够自主地操作一个 SwiftUI 应用。这个方向听起来有点科幻但落到实际场景里非常具体——自动化测试、无障碍辅助、智能 UI 助手、低代码平台里的帮我操作功能都是它的用武之地。适合读这篇内容的人有三类一是做 iOS/macOS 开发、想把自己的 App 接入智能体能力的工程师二是做自动化测试、想摆脱脆弱 UI 测试脚本的测试开发三是对 Agent 架构感兴趣、想找一个具体落地场景来练手的技术爱好者。不管你是哪一类接下来的内容都会从设计思路一路讲到实操细节和踩坑经验。2. 整体设计思路与方案选型2.1 为什么要把 SwiftUI 和 Agent 绑在一起先说一个很多人会忽略的前提SwiftUI 的声明式特性天然适合被 Agent 操作。为什么这么说传统的 UIKit 或者 AppKit 是命令式的界面是一棵视图树你要操作某个按钮得先拿到它的引用然后调用sendActions(for:)。这中间涉及大量运行时状态Agent 很难在不侵入代码的情况下理解当前界面有哪些可操作元素。而 SwiftUI 的视图是状态的函数。给定一个状态界面就是确定的。这意味着 Agent 只要能够读取当前状态就能推断出界面上应该有哪些元素、哪些是可交互的。更重要的是SwiftUI 的Accessibility体系accessibilityIdentifier、accessibilityLabel、accessibilityValue提供了一套标准化的界面语义描述这简直就是为 Agent 量身定做的感知接口。我个人的判断是SwiftUI Accessibility Agent 这个组合是目前移动端智能体落地最顺滑的一条路径。原因有三点。第一SwiftUI 的状态可观测Agent 不需要去猜界面第二Accessibility 树提供了结构化的元素描述Agent 不需要做图像识别第三SwiftUI 的交互都是通过绑定和动作触发的Agent 可以通过注入状态或者触发动作来完成操作不需要模拟触摸坐标。2.2 Skill 的粒度怎么定这是整个项目里最容易翻车的地方。Skill 定得太粗Agent 没法灵活组合定得太细Agent 的决策空间爆炸调用链长得离谱。我的经验是遵循一个 Skill 对应一个用户意图的原则。什么叫用户意图就是用户想完成的一件事。比如登录搜索商品提交表单是一个意图而点击用户名输入框输入文字点击密码框就不是意图是操作步骤。但这里有个矛盾如果 Skill 粒度太粗Agent 就没法处理异常。比如登录这个 Skill 内部如果写死了输入用户名→输入密码→点登录那遇到验证码怎么办遇到密码错误怎么办所以我的方案是两层 Skill 结构原子 Skill对应单个 UI 操作比如tapElement、inputText、readValue、scrollTo。这些是 Agent 的手和脚。复合 Skill对应一个完整意图内部由原子 Skill 编排而成但暴露给 Agent 的是一个高层接口同时提供中断点让 Agent 可以在关键步骤介入。这样设计的好处是Agent 在正常情况下调用复合 Skill 一步到位遇到异常时可以降级到原子 Skill 手动处理。实测下来这种结构比纯原子或者纯复合的方案都要稳。2.3 感知层怎么设计Agent 要操作界面首先得看见界面。SwiftUI 里最靠谱的感知方式不是截图而是读取 Accessibility 树。具体做法是给每个需要被 Agent 操作的元素加上accessibilityIdentifier这个标识符是稳定的、不随界面文案变化的。然后通过UIAccessibility或者XCUIElement的接口去遍历整棵树拿到每个元素的类型、标识、值、可交互状态。这里有个关键决策要不要把整个 Accessibility 树都喂给 Agent。我的答案是不要。一棵复杂的界面树可能有上百个节点全喂给模型既浪费 token 又干扰决策。正确的做法是做一层过滤和摘要只保留可交互元素按钮、输入框、开关、列表项并且把每个元素压缩成一行结构化描述。我常用的摘要格式是这样的[idlogin_button] typebutton label登录 enabledtrue [idusername_field] typetextfield value focusedfalse [idpassword_field] typesecurefield value focusedfalse这种格式 Agent 一看就懂而且 token 消耗可控。实测一个中等复杂度的界面摘要后大概 20 到 40 行完全在可接受范围内。2.4 执行层怎么落地执行层是 Skill 真正干活的地方。SwiftUI 里触发一个按钮的点击有几种方式第一种是通过 Accessibility 触发也就是XCUIElement.tap()那一套。这种方式最接近真实用户操作但依赖 UI 测试框架只能在测试环境用。第二种是通过状态注入。因为 SwiftUI 是状态驱动的你可以直接修改驱动界面的那个状态变量界面就会自动响应。比如登录按钮的action是调用viewModel.login()那 Agent 直接调用这个方法就行。这种方式最快但需要代码层面暴露接口。第三种是通过 URL Scheme 或者 Deep Link。适合跨应用或者跨页面的跳转但粒度太粗不适合细粒度操作。我的建议是混合使用在开发调试阶段用状态注入快且稳在端到端测试或者真实用户场景用 Accessibility 触发更真实。两种方式通过一个统一的SkillExecutor抽象出来Agent 不需要关心底层用的是哪种。3. 核心细节解析与实操要点3.1 Accessibility 标识的命名规范这是整个项目的地基命名乱了后面全乱。我踩过的坑是一开始用中文 label 当标识结果界面文案一改Agent 就找不到元素了。正确的做法是标识和文案彻底分离。accessibilityIdentifier用英文小写下划线格式是页面_元素_类型比如login_username_field、home_search_button、cart_item_cell。这个标识一旦定下来就不要改它是 Agent 和界面之间的契约。还有一个细节列表项和动态元素的标识要带索引或者唯一 ID。比如购物车里的商品不能所有 cell 都叫cart_item_cell得是cart_item_cell_0、cart_item_cell_1或者用商品 ID 做后缀。否则 Agent 想操作第三个商品的时候会懵。// 推荐写法 Button(登录) { viewModel.login() } .accessibilityIdentifier(login_submit_button) // 列表项 ForEach(items) { item in ItemRow(item: item) .accessibilityIdentifier(item_row_\(item.id)) }注意accessibilityIdentifier在 SwiftUI 里有时候会被容器吞掉尤其是嵌套在List或者ScrollView里的时候。如果发现 Agent 读不到某个元素的标识先检查是不是被父容器覆盖了必要时用.accessibilityElement(children: .contain)显式声明。3.2 Skill 的接口设计Skill 的接口设计要遵循一个原则输入输出都是纯数据不依赖任何 UI 类型。这样 Skill 才能被独立测试也才能被不同的 Agent 复用。我定义的 Skill 协议大概长这样protocol AgentSkill { var name: String { get } var description: String { get } var parameters: [SkillParameter] { get } func execute(params: [String: Any]) async throws - SkillResult }name是 Skill 的唯一标识Agent 靠它来调用。description是给模型看的自然语言说明写得好不好直接决定 Agent 会不会用错。parameters声明参数类型和是否必填用于校验。execute是实际执行逻辑返回SkillResult里面包含成功与否、返回值、以及可能的错误信息。这里有个经验description要写得像给新人看的操作手册不要写执行点击操作这种废话要写点击指定标识的按钮如果按钮不可点击会返回错误。模型看到这种描述才知道什么时候该用、什么时候不该用。3.3 状态同步的时机Agent 操作界面之后界面状态会变Agent 需要重新感知。这里有个时序问题SwiftUI 的状态更新是异步的你调用了viewModel.login()界面不会立刻变得等下一个渲染周期。如果 Agent 执行完一个 Skill 立刻去读界面状态很可能读到的是旧状态。我踩过这个坑Agent 点完登录按钮马上检查是否跳转结果一直判断失败因为界面还没刷新。解决方案是在 Skill 执行后加一个等待稳定的步骤。具体做法是轮询 Accessibility 树直到连续两次读取的结果一致或者超时。这个等待时间一般设 0.5 到 2 秒太短容易误判太长影响效率。func waitForStable(timeout: TimeInterval 2.0) async throws - [ElementSnapshot] { var lastSnapshot: [ElementSnapshot] [] let deadline Date().addingTimeInterval(timeout) while Date() deadline { let current try readAccessibilityTree() if current lastSnapshot { return current } lastSnapshot current try await Task.sleep(nanoseconds: 200_000_000) } return lastSnapshot }3.4 错误处理与重试策略Agent 操作界面失败是常态不是异常。元素没找到、元素不可点击、输入被拦截这些都会发生。关键是怎么让 Agent 知道失败了以及失败了怎么办。我的做法是给每个 Skill 定义清晰的错误类型错误类型含义Agent 应对策略elementNotFound找不到指定标识的元素重新感知界面确认元素是否存在elementNotInteractable元素存在但不可交互检查是否被遮挡、是否 disabledtimeout操作超时重试一次仍失败则上报invalidParameter参数不合法修正参数后重试stateMismatch操作后状态不符合预期回退或走异常分支Agent 拿到错误类型后可以决定是重试、换策略还是放弃。这比单纯返回失败要有用得多。实操心得重试一定要有次数上限我一般设 2 次。无限重试的 Agent 是最危险的它会在一个死循环里把界面点烂。另外重试之间要加退避第一次等 0.5 秒第二次等 1.5 秒给界面足够的响应时间。4. 实操过程与核心环节实现4.1 环境搭建与依赖准备先说环境。这套东西的核心依赖其实很少主要是三块SwiftUI 本身系统自带、一个 Accessibility 读取的通道、以及 Agent 的决策循环。Accessibility 读取通道在测试环境用 XCTest 的XCUIApplication最方便它能直接拿到整棵元素树。在非测试环境可以用UIAccessibility的相关接口但能力有限很多信息拿不到。所以我的建议是开发和测试阶段用 XCTest 通道生产环境如果需要再考虑用私有接口或者自建桥接。Agent 决策循环这块可以自己写一个简单的状态机也可以接入现成的模型接口。我倾向于自己写循环因为可控性高调试方便。一个最小的循环大概是这样func runAgentLoop(goal: String, maxSteps: Int 20) async throws { var step 0 var history: [AgentStep] [] while step maxSteps { let snapshot try await perception.readStableTree() let decision try await brain.decide( goal: goal, currentState: snapshot, history: history ) switch decision { case .callSkill(let name, let params): let result try await skillRegistry.execute(name, params) history.append(.init(skill: name, params: params, result: result)) case .finish(let summary): print(任务完成: \(summary)) return case .fail(let reason): throw AgentError.taskFailed(reason) } step 1 } throw AgentError.maxStepsExceeded }这个循环看起来简单但每一行都有讲究。readStableTree保证读到的是稳定状态decide把目标、当前状态、历史一起喂给模型history让模型知道之前做过什么避免重复操作maxSteps是安全阀防止死循环。4.2 一个完整的登录场景拆解光讲理论没意思我拿一个登录场景从头到尾走一遍。假设界面上有用户名输入框、密码输入框、登录按钮还有一个可能出现的错误提示。目标是让 Agent 完成登录。第一步感知。Agent 读取 Accessibility 树得到摘要[idlogin_username_field] typetextfield value enabledtrue [idlogin_password_field] typesecurefield value enabledtrue [idlogin_submit_button] typebutton label登录 enabledfalse注意登录按钮是enabledfalse因为两个输入框都是空的。这个信息很关键Agent 如果直接点登录会失败。第二步决策。Agent 看到目标完成登录当前状态是两个空输入框加一个禁用按钮。它应该先填用户名。模型输出调用inputText参数是idlogin_username_field, texttestuser。第三步执行。inputTextSkill 找到对应元素注入文本。这里有个细节SwiftUI 的TextField绑定的是State或者Observable的属性注入文本的方式是修改绑定的值而不是模拟键盘输入。修改后界面会自动更新。第四步再感知。填完用户名后按钮还是禁用的因为密码没填。Agent 继续填密码。第五步填完密码。这次感知发现按钮变成enabledtrue了。Agent 调用tapElement参数是idlogin_submit_button。第六步等待结果。点击后界面会发起网络请求Agent 需要等待。用前面说的waitForStable等到界面稳定后检查是否出现了登录成功的标志比如首页的某个元素或者错误提示。整个流程走下来Agent 大概调用了 4 到 5 个 Skill。如果中间出现错误提示Agent 需要读取错误文案决定是重试还是上报。这就是为什么前面强调错误类型要清晰——Agent 得知道密码错误和网络超时是两回事前者重试没用后者可以重试。4.3 参数计算与阈值选择这套系统里有几个关键参数选得对不对直接影响稳定性。等待稳定的轮询间隔我设的是 200 毫秒。太短了 CPU 占用高太长了响应慢。200 毫秒在大多数设备上是一个渲染周期的量级比较合适。稳定判定次数连续 2 次读取一致就认为稳定。为什么不是 1 次因为单次读取可能刚好卡在两次渲染之间读到中间态。2 次能过滤掉大部分抖动。超时时间默认 2 秒。对于网络请求后的界面变化2 秒可能不够需要根据具体场景调整。我的做法是给每个 Skill 单独配置超时tapElement用 2 秒waitForNetwork用 10 秒。最大步数20 步。一个正常的任务流程很少超过 10 步20 步是留了余量。超过 20 步基本可以判定 Agent 卡住了。重试次数2 次。配合退避策略第一次 0.5 秒第二次 1.5 秒。这些参数不是拍脑袋定的是我在不同复杂度的界面上反复调出来的。你可以根据自己的场景微调但建议先按这套跑通再优化。4.4 感知摘要的压缩策略前面提到要把 Accessibility 树压缩成摘要具体怎么压我总结了三条规则。规则一只保留可交互元素和关键文本。按钮、输入框、开关、滑块、列表项这些要保留。纯展示的Text、Image除非是错误提示或者关键信息否则过滤掉。规则二每个元素一行字段固定。固定字段的好处是模型容易理解也方便做 diff。我用的字段是id、type、label、value、enabled、focused。规则三层级信息用缩进表示但不超过两层。太深的层级对 Agent 决策没帮助反而增加理解成本。列表项的子元素可以合并到父项描述里。压缩后的摘要一个中等复杂度界面大概 20 到 40 行token 消耗在 500 到 1000 之间完全可控。5. 常见问题与排查技巧实录5.1 元素找不到的几种情况这是最高频的问题。Agent 报elementNotFound原因可能有好几种得逐一排查。情况一标识没加上或者加错了。最常见。SwiftUI 里.accessibilityIdentifier有时候会被父视图覆盖尤其是用了.accessibilityElement(children: .combine)的时候。排查方法是直接在 Xcode 的 Accessibility Inspector 里看能不能找到这个标识。情况二元素还没渲染出来。界面有动画或者异步加载Agent 读得太早。解决办法是加等待或者用waitForElement(id:timeout:)这种带条件的等待。情况三元素在滚动视图外。列表很长目标元素在屏幕外Accessibility 树里可能读不到。需要先滚动到目标位置。我一般会加一个scrollToElement的 SkillAgent 找不到元素时先尝试滚动。情况四元素被模态视图遮挡。弹窗、Sheet、Alert 盖住了底层元素。这种情况下 Accessibility 树里底层元素可能还在但不可交互。Agent 需要先关闭弹窗。排查顺序建议是先看 Inspector 确认标识存在再看时序确认渲染完成再看位置确认在可视区最后看遮挡。5.2 Agent 决策跑偏怎么办Agent 跑偏的表现是明明该填密码它去点了别的按钮或者在一个步骤上反复重试。原因一摘要信息不够。Agent 看不到某个关键元素的状态做了错误判断。解决办法是补充摘要字段比如加上focused状态让 Agent 知道当前焦点在哪。原因二description 写得有歧义。两个 Skill 的描述太像模型分不清该用哪个。解决办法是把描述写得更具体明确使用场景和前置条件。原因三历史太长模型被干扰。对话历史积累太多模型注意力分散。解决办法是只保留最近 N 步的历史或者对历史做摘要。原因四目标描述太模糊。帮我操作一下这种目标模型没法执行。目标要具体比如用 testuser 和密码 123456 登录。我的经验是Agent 跑偏 90% 是感知或描述的问题不是模型能力的问题。先把摘要和 description 打磨好再考虑换模型。5.3 状态不同步的排查Agent 操作后读到的状态和实际不符这个问题很隐蔽。排查方法一加日志。每次读取 Accessibility 树都打时间戳和内容对比操作前后的变化。如果操作后立刻读到的还是旧状态就是时序问题。排查方法二手动复现。在 Xcode 里手动操作同样的步骤看界面变化需要多久。如果手动操作也要等一会儿那 Agent 就需要等。排查方法三检查绑定。SwiftUI 的状态绑定如果写错了界面可能根本不响应。比如State用了let而不是var或者Binding传错了层级。避坑技巧在开发阶段给每个 Skill 执行后强制加 500 毫秒延迟先保证功能跑通再逐步优化等待策略。不要一上来就追求零延迟那样调试起来会很痛苦。5.4 常见问题速查表现象可能原因排查动作解决方向elementNotFound标识缺失/未渲染/在屏幕外Inspector 检查、加日志补标识、加等待、先滚动elementNotInteractable被遮挡/disabled检查弹窗、检查 enabled关弹窗、等状态变化操作后状态不变时序问题/绑定错误加延迟测试、检查绑定加等待、修绑定Agent 反复重试错误类型不明确看 Skill 返回的错误细化错误类型Agent 决策跑偏摘要不足/描述歧义看摘要和 description补字段、改描述任务超时步数过多/卡死看 history加 maxSteps、加超时摘要 token 过多过滤不彻底看摘要行数收紧过滤规则5.5 几个我踩过的坑坑一用 label 当标识。一开始图省事直接用按钮文案当标识。结果产品改了一次文案所有 Skill 全挂。后来老老实实用独立的accessibilityIdentifier再也没出过这个问题。坑二忽略 disabled 状态。Agent 看到按钮就点不管它是不是禁用的。结果点了没反应Agent 以为失败了反复重试。后来在摘要里加上enabled字段Agent 就知道该等还是该点。坑三重试没有退避。早期版本重试是立即重试结果界面还没反应过来第二次又失败第三次还是失败。加了退避之后成功率明显提升。坑四历史无限增长。长任务跑下来history 积累了几十步token 爆炸模型还容易迷失。后来改成只保留最近 5 步效果反而更好。坑五没有 maxSteps。有一次 Agent 卡在一个循环里把界面点了几十次。加了 maxSteps 之后最多 20 步就强制退出安全多了。6. 扩展方向与个人体会这套东西跑通之后能扩展的方向其实挺多的。一个方向是多模态感知。现在只读 Accessibility 树信息有限。如果加上截图让模型同时看结构和图像对复杂界面的理解会更强。尤其是那些没有加标识的自定义控件图像识别能补上。另一个方向是Skill 的自动发现。现在 Skill 是手动注册的未来可以让 Agent 自己扫描界面发现可交互元素后自动生成临时 Skill。这样面对新界面时Agent 不需要预先配置就能操作。还有一个方向是跨应用编排。单个 App 内的操作已经跑通了如果能把多个 App 的 Skill 串起来就能完成更复杂的任务。当然这涉及权限和沙箱的问题得看具体平台的支持情况。我个人在实际操作中的体会是这套系统的瓶颈从来不在模型而在感知和描述。模型再强如果它看不到界面状态或者 Skill 描述得含糊不清照样干不了活。所以如果你要上手做类似的东西我的建议是把 80% 的精力花在 Accessibility 标识规范、摘要压缩策略和 Skill 描述打磨上剩下的 20% 再考虑模型选型和循环优化。最后再分享一个小技巧给每个 Skill 写单元测试。不是测 Agent是单独测 Skill。输入一组参数看它能不能正确操作界面、返回正确结果。Skill 稳了Agent 才有可能稳。我见过太多人跳过这一步直接测端到端结果出了问题根本不知道是 Skill 的锅还是 Agent 的锅。先把 Skill 测透再往上搭会省很多时间。