AI 生成、自愈、留证——移动端回归的完整闭环
它是配给你的 AI 助手用的：装好、注册一次，之后「测一下这个页面」交给对话就行。用例由自然语言生成、真机试跑校准，执行失败自动自愈，每一步强制截图与 logcat 证据。执行在你自己电脑上完成，测试数据默认只存本机；AI 生成的内容由官方代理交云端模型服务商处理，或自带 API Key 直连你选择的服务商。
# 1. 装好（已装 uv 可跳过第一条） $ curl -LsSf https://astral.sh/uv/install.sh | sh $ uv tool install mat-uitest $ uv tool update-shell # 2. 注册给你的 AI 助手（自动检测装了哪个） $ mat mcp install # 3. 然后交给对话 # 「用 MAT 测一下 com.example.app，先跑冒烟」 # 它会自己看环境、跑用例、给结论；你也可以随时自己敲： # 改完代码到拿到机器可判定的结论，三分钟： $ mat verify cases/x.json --apk build/app-debug.apk --json # 返回的 JSON 会说：过没过、没过该修什么（分类 + 下一步动作）； # 什么都不用读终端。看现场也可以随时敲： $ mat verify cases/x.json --json # 想点着用就开本地控制台，浏览器自动打开： $ mat console
自动化最贵的不是写脚本，是养脚本
UI 一改就挂、存量用例搬不进来、报告说不清责任、数据不敢往外发——MAT 逐条对着这四件事做。
页面一改，脚本全挂
定位失败会自动重试与自愈，给出修正提案；确认后回写为 -healed.json 新用例，不动你的原文件。
存量用例搬不进来
Excel / XMind / 禅道导出的用例批量导入，自动转成可执行步骤；低置信的不会硬造，标出来交给人判。
报告说不清是不是产品的问题
每一步强制截图 + logcat 留痕，失败自动分类（产品 / 用例 / 环境），环境抖动不再算到产品头上。
敢把执行交给 AI，是因为它确定
用例是确定性 DSL，执行期默认不调用大模型；每步强制截图与 logcat 留证。AI 负责生成与判断，执行本身不掺随机性——这是它能被助手直接调用的前提。
配好之后，这四步它替你走
你只需要装好、配给助手，然后说一句「用 MAT 测一下这个 App」。下面是它实际执行的命令，每一条你也可以自己敲——没有藏在后台的魔法。
装好并自检
逐项检查 Python、adb、在线设备、驱动、提示词与 AI 端点，缺什么直接告诉你怎么补。
$ mat doctor
一句话生成
描述场景即可生成结构化用例；--calibrate 会先在真机试跑，把定位对不上的地方当场校准。
$ mat gen "…" --calibrate
执行与自愈
按 DSL 逐步执行，定位失败先重试、再自愈；支持数据驱动多组数据与套件批量执行。
$ mat run cases/x.json
看证据、下结论
报告里每步截图与日志齐全；失败可归因，判错了还能人工纠正并把规则沉淀下来。
$ mat diagnose <目录>
STEP 02–04 也能在控制台里点（mat console 打开，仅监听 127.0.0.1），只有生成时的真机校准 --calibrate 要回到命令行；想先摸清一个 App 有哪些页面，用 mat explore。要让脚本或 CI 判断成败，用 mat verify --json——它只给结论和下一步动作。
该有的都在，且都能在本地跑
所有能力都通过同一个命令行与本地控制台操作，数据源只有一份。
生成与探索
- 自然语言生成用例
mat gen - 手工用例导入转换（Excel / XMind / 禅道）
- 探索测试：时长与步数双上限，敏感控件自动跳过
- 页面索引与图谱沉淀
mat index/mat arrival
执行与自愈
- 确定性 DSL：12 类动作，可读可审
- 失败自愈与提案回写
mat heal - 数据驱动：一组步骤跑多组数据
- 套件批量执行与产物归档
证据与报告
- 每步强制截图 + logcat 日志切片
- 失败自动分类，可人工纠正并沉淀规则
- 自包含 HTML 报告，单文件可转发
- 数据可携带导出
mat export
设备与入口
- Android 真机（adb），Windows / macOS / Linux
- iOS 模拟器与真机（beta）
mat run --platform ios - 本地控制台
mat console：看图写用例、复核草稿 - 局域网分享，数据零出域
集成与扩展
- 37 个子命令，可脚本化、可进 CI
- MCP 服务：15 个工具供 AI 编程助手调用
- skill 教助手怎么用工具（随包附带，也可单独获取）
- 凭据管理
mat cred，账号密码不写进用例
数据与可信
- 执行期默认不调用大模型，结果可复现
- 截图、日志、用例默认只存本机
- 控制台仅监听本机，不对局域网开放
- 视觉兜底需显式开启；开启后截图发往你配置的服务商或官方代理所配的云端模型服务商
一条命令装上，先自检再开始
要求 Python 3.11+ 与本机 adb。装完跑一次 mat mcp install 把它注册给你的 AI 助手，之后对助手说话就行；想自己看界面，mat console 一直都在。
Windows 上直接 pip 装到用户目录即可。[mcp] 是给助手调用用的可选依赖，少了它 mat mcp install 仍能写配置，但客户端启动服务器会失败。命令找不到时用 py -m insta_engine 代替 mat（两者等价）。
uv 自动解决 Python 3.11+，不需要预装；已有 uv 跳过第一行。uv tool update-shell 把 ~/.local/bin 写进 PATH，重开终端 mat 才能直接用。已装 pipx 可用等价备选 pipx install "mat-uitest[mcp]" && pipx ensurepath（没有 pipx 先 brew install pipx 或 sudo apt install pipx）。Homebrew / Debian 12+ / Ubuntu 23.04+ 的系统 Python 受 PEP 668 保护，裸 pip install 会被拒——用 uv / pipx，或自建 venv。
发给能执行终端命令的 AI 助手（Claude Code、WorkBuddy 等）。skill 装好后在新会话里说「用 mobileapp-testing 技能测一下 <你的 App>」即可。助手不能执行命令时（只能用「技能上传」入口的 IDE），按手册第 8 章从公开的技能仓直接取。
不用告诉它你用的是哪个——它自己看本机装了 Trae / Cursor / Claude Desktop / WorkBuddy 中的哪一个；装了多个会把可选项列出来，一个都没有说明客户端还没装、或装了还没启动过。写完会告诉你写进了哪个文件、旧文件备份在哪，撤销是 mat mcp uninstall。重启客户端后让它调用 mat_status，能看到设备与用例就是通了。
也可以把下面这段发给能执行命令的助手，让它自己装：
两种方式，本地能力全程免费
本地真机执行、自愈、证据报告——都不限量，也不需要任何码。只有官方 AI 代理这条通道会计数；多人共用控制台与共享用例库随团队授权提供。
单人模式
推荐自带 API Key；没有 Key 也能用，不需要激活码
- 推荐：自带 API Key —— 不设上限，请求直连你的服务商，控件文本与截图都不经过本站
- 没有 Key 也能用：官方代理每月 300 次生成 · 100 次视觉，按自然月重置
- 本地真机执行 / 自愈 / 报告 不限量
- 探索测试 / 失败归因 / 控制台 可用
- 走官方代理时，AI 任务内容由服务端交给云端模型服务商（当前为阿里云百炼）处理；不希望内容发往该服务商，可改用自带 API Key
- 支持：文档 + 问题反馈（工作日有人跟进）
团队模式
几个人共用一套控制台 · 随团队授权提供
- 随团队授权提供：单人模式只有安装者本人，多人共用需要团队授权
mat console --share局域网共享，自动生成访问口令- 同事在自己浏览器里执行用例、看报告、删改用例
- 成员按名字登记，名额按授权给（可联系我们增加）
- 控制台与报告不出内网；截图是否出网看 AI 接入
- 人工支持（工作日 48 小时内回复）+ 2 次远程陪跑
常见问题
我的被测 App 数据会上传吗？
MAT_NO_UPDATE_CHECK=1 可关闭）。逐项说明见 隐私政策。执行的时候会调用大模型吗？
mat import（把 Excel/CSV/文本的手工用例转成 DSL，Maestro flow 走确定性映射、不花额度）、mat diagnose（失败归因，没配 Key 自动回退规则结果）、mat describe（给页面图谱补描述，计 1 次生成额度），以及控制台里的「AI 润色」（把你写的自然语言描述润色成用例，会把描述与控件清单发出去）。需要会写代码吗？
支持 iOS 吗？
mat ios-setup 体检（首次需在 Xcode 里登录账号、设备信任证书并 ⌘U 一次），之后 mat run --platform ios 即可：接着一台真机时缺省就选它，多台用 --serial <udid> 指定。真机限制：仅 USB（Wi-Fi 暂不支持）、须保持解锁、免费证书 7 天要续期、真机不支持录屏（模拟器可以）。依赖页面图谱的能力（index / explore / arrival / graph-repair）在 iOS 上会被明确拦下。AI 生成有次数限制吗？
mat status 查看，调用次数与耗时用 mat ai-stats 看。探索测试会不会误点支付、客服这类控件？
能接进 CI 吗？
--json 另给机器可读输出）。仓库根带了一个 composite action：uses: vlmpilot/mat-uitest@main，输入包名与用例目录，输出 JUnit XML、报告 artifact、通过数与总数，以及一份可直接贴到 PR 的摘要；examples/ci/mat-pr.yml 是可以直接抄的 PR 门禁模板。前置条件是一台插着 Android 测试机的 self-hosted runner——真实设备没法在云端 runner 上跑。跑完也可以用 mat summary 把 run.json 压成 ≤40 行摘要，贴进流水线日志给人看。装完怎么确认环境没问题？
mat doctor。它逐项检查 Python 版本（≥3.11）、adb、在线设备、uiautomator2 驱动、AI 生成 prompt、AI 模型配置与视觉兜底，缺哪一项、怎么补都会直接写出来，能修的项还可以一键修。iOS 另有一份体检：mat ios-setup（Xcode / 账号 / 团队 / 证书有效期 / 设备 / WDA）。也可以开 mat console——控制台首页跑的是同一份检查，没达标的项会标出来，点开就是补齐办法。团队怎么一起用？
mat console --share，终端会打印一个内网链接和一枚访问口令；同事在同一个局域网里用浏览器打开、输一次口令就能用——都能触发测试（同一台设备会自动排队，不会互相抢）、看实时投屏、看报告。口令缺省自动生成并打印，也可以 --password 自己定。多人共用需要团队授权：标准/体验授权面向单人使用，--share 下也只有安装者本人 1 人。口令只拦误入的同网段设备，别把链接和口令发给不可信的人。