让 agent 做事

Flow：做过一次的事，以后一键重放

重复做的事存成 flow：按 App 分类、经过审阅的脚本，重放时不经过模型，不花 token。 agent 会自己找到某个 App 的 flow，一次调用跑完；在没有 flow 的 App 里做完一个多步任务后，它会问你要不要把刚才的操作存下来。

flow 是什么

flow 是一个格式严格的 JSON 文件（version: 1），步骤和 phone_run_steps 一样带保护（按定位器点击、launch_app、输入、wait_for 检查点等），另外可以声明具名的字符串输入。 iphone-use-mcp 不需要任何模型就能校验并运行它。flow 遇到第一个失败的步骤就停下，从不重试。

bash

$ MCP="$HOME/Applications/iPhoneUse.app/Contents/MacOS/iphone-use-mcp"
$ "$MCP" flow validate examples/flows/search-spotlight.json          # 离线校验
$ IPHONE_USE_TOKEN=… "$MCP" flow run examples/flows/search-spotlight.json --input 'query=coffee'

agent 怎么用 flow

🔎 进入 App 时自动发现

launch_app 的返回，或进入新 App 后第一次读屏，都带一个 registry 块，列出这个 App 已有的 flow。有合适的，agent 就用 phone_flow_run 跑：一次调用顶几十次。

💾 做完任务后主动询问

要不要把这次操作存成 flow？

返回里带 flow_suggestion，或者做完一个没有 flow 覆盖的多步任务时，agent 会问你。步骤守护进程已经录好了草稿。

只有你同意才会保存：

拿草稿：agent 取出草稿（phone_flow_draft，或 flow draft --out my-task.json），附一个要修的 todo 列表。
修好并验证：改完 todo，校验文件，在手机上跑一遍。
经你同意再发布：发布会向 flow 源提一个公开 PR，所以 agent 会再问一次，才调用 phone_flow_publish(confirm=true)。

IPHONE_USE_FLOWS_NO_SUGGEST=1 可以关闭保存提示。

在浏览器里录一个

控制页的「流程」面板会把你在手机上的操作录成可重放的 flow 文件：

只录已确认执行的操作。优先用精确的无障碍标签；按坐标的手势会标记为不稳定。
输入的文字会变成具名的运行时输入，原文被丢弃，不会写进下载的 JSON。
每一步之后，只有能确定出现了新的唯一标识或前台 App 变了，录制器才会插入一个可审阅的 wait_for 检查点；它不会把任意标签或值抄进检查点，因为那些可能是隐私。
可以审阅、调整顺序、删除、填输入，然后下载合法的 flow v1 JSON，或直接跑一遍。运行前必须填好所有输入，并明确勾选「没有不可撤销的操作」。

官方 flow 源

leeguooooo/iphone-use-flows 是官方的、也是唯一受支持的 flow 源，收录经过审阅的按 App 分类的 flow。守护进程会自己保持它最新（IPHONE_USE_FLOWS_NO_AUTO_UPDATE=1 关闭）。文件都是纯 JSON，安装 flow 源不会执行任何代码；任何一个校验和或格式校验失败，整次更新都会放弃，本地内容保持不变。

bash

$ "$MCP" flow update                        # 同步到 ~/.iphone-use/flows：sha256 + 严格校验
$ "$MCP" flow list --category health        # id · 风险 · 验证 · 输入 · 名称
$ "$MCP" flow info health/export-all-zh-cn  # 元数据和步骤模板
$ "$MCP" flow run health/export-all-zh-cn   # 失败时会说卡在哪一步、为什么
$ "$MCP" flow draft --out my-task.json      # 刚才在手机上做的事，导出成草稿
$ "$MCP" flow add my.json --as myapp/daily  # 你自己的 flow，update 后仍保留
$ "$MCP" flow publish my.json --as myapp/daily --alias MyApp --note "iPhone 17 Pro Max, iOS 26"   # 通过 gh 提 PR
$ "$MCP" flow report health/export-all --result @run.json --note "profile button renamed"           # 提一个 flow-broken issue

风险等级

risk	含义
`read_only`	只读手机内容。
`navigation`	在 App 里跳转。
`side_effect`	会发送、发布、付款或删除。不加 `--confirm` / `confirm=true` 就拒绝运行。

App 更新之后

每个 flow 都记着它在哪个 App（或 iOS）版本上验证过，CLI 会读取手机上实际安装的版本（flow apps），每次列出时都给一个 compat 结论：verified、untested-newer、incompatible、 broken、needs-verification、draft 或 unknown。flow run 不加 --force 会拒绝 broken 和 incompatible 的 flow。每晚有一次巡检在真机上重跑已验证的只读 flow： verified 刷新验证日期，failed 打上标记并提一个 flow-broken issue， skipped（手机锁着、被别人占着、不可操作或结果不确定）则原样不动。

运行失败时

结果里会多一个 diagnosis 块：失败的步骤、屏幕能不能读、原因（例如 locator_no_match、 locator_ambiguous），以及最多五个候选元素。它只是运行后的一次有限读取：不会重发任何操作，也不会悄悄改 flow。 --artifacts-dir DIR 还会写一份机器可读的运行记录（只有结构，不写输入内容和屏幕文字）。

⚠️ 输入里不要放秘密

--input KEY=VALUE 只在本次运行生效，不会写回文件，但命令行参数可能留在 shell 历史里。flow 的输入不能带密码、验证码或私人内容；发送、发布、付款、删除这类操作必须声明为 side_effect。

测试套件与定时运行

有两样东西建立在 flow 之上，都和 flow run 走同一个引擎。

🧪 测试套件

iphone-use-mcp test suite.yaml 把「打开、点几下、检查对不对」变成可重跑的文件。退出码 0 全部通过，1 有用例失败，2 套件无效或手机无法操作。--junit FILE 生成 JUnit XML，直接接 CI。

⏰ 定时任务

守护进程按 cron 运行一个 flow 或一个套件。手机被别人占用时会等，运行失败、错过或跳过时会弹 macOS 通知。有副作用的目标在创建定时任务时需要加 --confirm。

bash

$ iphone-use-mcp test examples/tests/settings-smoke.zh-CN.yaml --junit report.xml
$ iphone-use-mcp schedule add --cron "0 9 * * 1-5" --test ~/suites/smoke.yaml --name "morning smoke"
$ iphone-use-mcp schedule add --cron "@daily" --flow health/export-all-zh-cn
$ iphone-use-mcp schedule list

同样的定时任务列表在控制页的 /schedules。详见测试与定时任务。

接下来：可以让 agent 做什么 · 接上你的 agent。