第一次跑通

使用手册

从装上到出第一份报告。两种用法任选一种就行：打开图形控制台点几下，或者在终端敲 一条命令——两者操作的是同一套引擎、同一份用例。

跑在你自己的电脑上 测试数据默认不出本机 界面与命令全是中文

1三步准备

只需要一台电脑和一台 Android 手机。整个准备过程大约 10 分钟，其中第 2 步最容易卡住，所以写得细一些。

  1. 装工具

    要求 Python 3.11 以上、以及本机的 adb（Android 调试桥，装 Android Studio 或用 brew install android-platform-tools 都能得到）。挑一条命令即可：

    > py -m pip install --user mat-uitest > py -m insta_engine doctor

    Windows 上直接装到用户目录即可。若提示找不到 mat 命令，用 py -m insta_engine 代替（两者等价，全文同理）。

    $ pipx install mat-uitest && pipx ensurepath $ mat doctor

    没装 pipx 先 brew install pipx 或 sudo apt install pipx。不想装 Homebrew 就用 uv（Linux 上尤其省事，不需要 root）：先 curl -LsSf https://astral.sh/uv/install.sh | sh，再 uv tool install mat-uitest && uv tool update-shell——最后那步是把 ~/.local/bin 加进 PATH，装完重开终端才能直接用 mat。

    $ git clone <仓库地址> && cd <仓库名> $ python -m venv .venv && . .venv/bin/activate $ pip install -e ./engine[dev]

    开发模式安装。源码与许可全文（AGPL-3.0-or-later）随安装包一同提供。

  2. 连一台 Android 手机

    打开手机的「开发者选项」并把「USB 调试」打开——大多数手机上是：设置 → 关于手机 → 连点「版本号」7 次 → 回到设置里的「开发者选项」→ 打开「USB 调试」。然后用数据线插到电脑，手机上会弹「允许 USB 调试吗」，勾选「始终允许」并确定。

    $ adb devices List of devices attached 8KE5T19819001756 device

    看到一行以 device 结尾的设备号，就说明电脑已经认到手机了。若显示 unauthorized，在手机上重新确认一次授权弹窗；若列表为空，换一根数据线（很多线只能充电、不能传数据）。

  3. 跑一次自检

    mat doctor 会逐项检查 adb、设备、驱动、AI 配置，缺什么直接告诉你下一步做什么：

    $ mat doctor ✅ adb 可用 ✅ 已连接 1 台设备 ✅ AI 端点未配置（生成类命令需要，见手册第 5 节） 结论: 就绪，可以开测

    自检里“AI 端点未配置”不影响执行、自愈和报告——只有生成用例、描述页面、失败归因要用到模型。

iOS 目前支持到哪一步：只有模拟器预览（mat run --platform ios，需 WDA 在 localhost:8100）。真机未支持，页面索引、遍历探索、到达路径验证在 iOS 上会被明确拦下；定位能力也未在真实 App 上验证过。Android 才是完整能力。

2第一次跑通：打开控制台，点五下

这一段不需要记任何命令以外的知识。只想先看看它能干什么的话，看完这节就够了。

$ mat console 工作区: /你的工作目录 控制台: http://127.0.0.1:7420 （Ctrl+C 退出） （仅本机监听；要分享给同事用 `mat console --share`） 下一步: 手机插上 → 用例工作台运行 → 执行页看事件流 → 报告页看结果

跑起来后它会自动帮你打开浏览器（不想让它自动开就加 --no-open，自己打开 http://127.0.0.1:7420 也一样）。控制台跑在你自己的电脑上，默认只监听 127.0.0.1——同一局域网里的其他机器访问不到。界面左侧是菜单，右侧是内容区。

  1. 连设备 —— 菜单「设备 / 执行日志」

    选中你的手机，右边的投屏画面出现，就说明连上了。同一页下方是这台设备的执行日志（上）和最近的执行记录（下）。

  2. 遍历探索 —— 菜单「遍历探索」

    选好被测应用，点开始，它会自己把 App 点一遍：一边找崩溃、白屏这类异常，一边把走过的页面沉淀成页面图谱（每个页面有哪些控件、怎么从 A 页到 B 页）。

    这一步很划算。遍历是规则驱动的，不消耗 AI 生成额度；而它产出的页面图谱，正是后面 AI 生成用例的依据——有图谱，生成的用例才落在真实控件上。
  3. 生成用例 —— 菜单「用例生成 / 导入」

    用一句大白话描述场景，比如「搜索一个关键词，验证结果页出现」。AI 会结合上一步的页面图谱，生成一条可执行的用例——生成前如果描述比较含糊，可以先用「AI 润色」把它对齐到真实控件上。

    已经有手工用例的话，也可以直接导入 Excel、CSV、Markdown、纯文本，或者 XMind。

  4. 执行 —— 菜单「用例管理 / 执行」

    勾选用例、选好设备，点运行。界面上能看到跑到第几步；多台设备或多人同时用也没关系，同一台设备上的任务会自动排队，不会互相踩。

  5. 看报告 —— 菜单「报告」

    每一次执行都留下一份带证据链的报告：每一步的截图、当时的界面结构、日志，失败的步骤还能点「AI 归因」自动归类原因。报告按完成时间倒序排列，随时回看。

不知道下一步该干什么？回到「概览」页——它会根据你当前的环境（装好了没、设备连上没、有没有用例）给出一条主行动和跳转按钮，照着点就行。

3控制台里还有什么

第 2 节走的是最短路径。控制台本身是完整的，菜单分三块：

用例管理与执行

菜单能做什么
设备 / 执行日志设备实时投屏与快捷操控；本设备执行日志与近期任务日志。任务记录存在内存里，服务重启即清空，落盘的报告不受影响。
遍历探索自动遍历 App 找异常，同时沉淀页面图谱。执行期间会占用设备并打开被测应用。
用例生成 / 导入一句话生成用例；导入 Excel / CSV / Markdown / 纯文本 / XMind。
用例管理 / 执行结构化步骤卡片编辑、单条运行与批量执行、套件、数据驱动。

资产

菜单能做什么
报告带证据链的执行报告；套件批量执行按批次折叠汇总；顶部有失败原因汇总与 AI 归因。
自愈提案定位失败被自动救回的步骤在这里确认，确认后生成修复后的新用例。
页面复核复核 AI 给页面起的标题与功能描述；人工填过的会标记 manual，AI 补全不会覆盖它。

更多

菜单能做什么
设置档位与团队席位、用例凭据、本地数据导出、关于。右上角的按钮可以随时改你的名字。
操作记录多人共用时的写操作审计：谁、何时、改了什么。
使用手册左下角那本小书——控制台自带的同源手册，界面改版时会一起更新。
控制台和命令行是同一套东西：你在界面上勾选运行的用例，就是工作区 cases/ 目录里的 JSON 文件；界面里生成、编辑、保存的每一步，都能在终端用命令复现。

4用命令行跑

图形界面适合“一边看一边调”，命令行适合“只在终端操作”：接持续集成、批量回归、写进脚本。下面是三分钟的最小闭环。

建工作区

在你打算放用例的目录里执行 mat init，它会建好 cases/、artifacts/，放一条示例用例，并把 prompt 模板播种好：

$ cd 你的工作目录 $ mat init 工作区就绪: cases/example-settings.json prompt 模板已播种: prompts/gen.prompt, ... 下一步: mat devices / mat run cases/example-settings.json

跑第一条用例

$ mat devices $ mat run cases/example-settings.json

示例用例打开的是系统设置页，所以任何一台 Android 手机都能直接跑通。跑完终端会打印结果摘要，同时产出一份可翻阅的报告。

批量与设备选择

用例攒多了就按 App 批量跑，--app 同时起到过滤和防错的作用（不会把别的 App 的用例混进来）：

$ mat run cases/ --app 被测应用包名 $ mat run cases/ --app 被测应用包名 --serial 设备号 $ mat run cases/ --app 被测应用包名 --record

--record 会全程录屏：通过的自动删掉，失败的保留下来并嵌进报告里，回看的时候不用猜。

接进持续集成

$ mat run cases/ --app 被测应用包名 --junit-xml report.xml --json

JUnit XML 是 Jenkins、GitLab、GitHub Actions 都认的格式；--json 会在末尾追加一段机器可读的摘要，方便脚本判断成败。

5让 AI 更好用

先说清楚边界：本地执行、自愈、报告全程不需要 AI，也不消耗额度。需要模型参与的只有四件事——生成用例、描述页面、失败归因、视觉兜底。

配置模型：二选一

在工作区根目录建一个 .env 文件，写下面任意一种。

# 方式一：用本站提供的代理 —— token 请联系我们获取（公众号「Mobile AI Test」或客服微信 lazy_vizen） GEN_BASE_URL=https://mobileaitest.com GEN_API_KEY=<你的 token> GEN_PROMPT_MODE=server # 方式二：自带 Key，指向任意 OpenAI 兼容端点 GEN_BASE_URL=<你的端点> GEN_API_KEY=<你的 Key> GEN_MODEL=<语言模型名> # 语言模型：读页面结构、写用例、起页面名、归因失败 GEN_VL_MODEL=<视觉模型名> # 视觉模型：视觉兜底时按截图找控件 GEN_VL_FALLBACK=1 # 总开关：光配上一行还不够，要这一行才真的启用
变量作用
GEN_MODEL语言模型。生成用例、给页面起标题与描述、失败归因都靠它。不配它，生成类命令用不了（执行、自愈、报告不受影响）。
GEN_VL_MODEL视觉模型。只在视觉兜底这一步用：常规定位都找不到控件时，让它看一眼当前截图、按位置把控件认出来。
GEN_VL_FALLBACK=1视觉兜底的总开关——两种配置方式都要加。只配 GEN_VL_MODEL 是不够的：这一步会把当前屏幕截图发给模型、并消耗视觉额度，所以默认是关的，要你显式打开（另一种开法：给个别步骤标 onFailure: heal，只让那一步允许）。

配好后跑 mat doctor 确认一遍；mat status 里能看到视觉兜底现在是“已启用”还是“未配置”。想给某一条命令单独换个模型，可以加 GEN_MODEL_<命令名大写>（如 GEN_MODEL_DIAGNOSE）覆盖，其余命令仍用 GEN_MODEL。自带模型时，与之相关的事项由你自行承担（详见服务协议）。

页面图谱：AI 的“底图”

AI 最容易犯的错是“编一个界面上根本不存在的按钮”。MAT 的做法是先让工具把 App 走一遍，把真实控件记下来，再让模型在这份材料里挑——所以先有图谱、再生成用例，产物才可靠。

命令作用
mat index 包名真机爬取，构建页面索引（控件清单）——生成与导入的防幻觉底座。
mat explore 包名规则驱动遍历，找异常的同时把图谱铺开。可用 --minutes、--steps 限时限量。
mat describe 包名给图谱里的页面补标题和功能描述（可选，计一次生成）。
mat review 包名人工复核页面标题：生成复核页 → --apply 应用结论 → --replay 回放验证。
mat arrival 包名试跑验证“怎么到达某个页面”的路径是否稳定。

生成与导入

$ mat gen "搜索一个关键词并验证结果页出现" --package 被测应用包名 $ mat import 手工用例.xlsx --package 被测应用包名

生成不满意可以直接改措辞重来，也可以在控制台里对描述先做一次「AI 润色」（不占用生成额度）。

6失败之后怎么办

用例失败时，多数情况不是功能坏了，而是界面变了几个字。MAT 有三条处理路径。

定位失败：三级自愈

  1. 本地模糊重定位 —— 先在自己这端找最接近的控件，不联网、不花额度；
  2. 页面图谱匹配 —— 在已沉淀的页面结构里找同一个控件的等价描述；
  3. 视觉兜底 —— 以上都没命中时，让视觉模型看一眼截图，按位置把控件找回来（默认关闭，要你显式打开 GEN_VL_FALLBACK=1，一次算一次视觉额度）。

被救回的步骤不会悄悄溜过去，而是进入「自愈提案」：你确认后才生成一条修复后的新用例，原用例不动——所以自愈永远不会把你写好的用例改坏。

$ mat heal list artifacts/某次执行 $ mat heal apply artifacts/某次执行

真的失败了：归因与校准

命令作用
mat diagnose 产物目录把失败步骤归类（崩溃 / 定位 / 断言 / 环境等）并给出证据与建议。没配模型时自动回退到规则结果，不会报错。
mat calibrate 产物目录人工改判失败的归类，并把这次判断落成规则，下次同类失败自动按你的口径分。

关于「可选步骤」：启动广告、权限弹窗这类“可能来、也可能不来”的步骤会被标成可选，目标没出现时记为跳过并继续，不算失败。工具拉起 App 后也会顺手清掉广告和权限弹窗。

7多人一起用

控制台跑在一台机器上，团队可以共用它——不需要给每个人装一套。几件需要提前知道的事：

让同事也能打开界面

$ mat console --share 控制台: http://127.0.0.1:7420 （Ctrl+C 退出） ⚠️ 局域网分享开启：同网段内需访问口令（含运行/删改用例权限），仅限可信内网。 🔑 访问口令: a1b2c3 （同事首次打开链接时输入一次即可） 内网分享链接（发给同一 Wi-Fi/VPN 下的同事，浏览器直接打开）: http://192.168.1.20:7420

加上 --share，它会改听局域网，并打印一条内网地址和一串访问口令（不指定就每次随机生成；也可以自己定 --password 口令）。同事在浏览器打开那条内网地址，首次输入口令即可，之后同一个浏览器不必再输。

口令不是可选项。不带口令的分享，等于把用例的运行与删改权限开放给同网段所有人——所以只在可信内网里用，用完 Ctrl-C 就收工。

席位与署名

首次进入控制台会让你填名字，名字就是席位（默认最多 5 人）。之后每条执行记录、每份报告都会署上执行人，套件批次里能看到是谁跑的。

套件：把一批用例打包

$ mat suite list $ mat suite new 冒烟 --add cases/a.json cases/b.json $ mat suite check 冒烟

check 会拦住跨 App 混跑（一个套件里的用例必须属于同一个 App），避免出现“看着全过、其实跑错对象”的报告。

两条必须守的纪律

  • 同一台手机同时只能跑一个任务。工具会自动排队，但请别手动去插队——并发操作同一台设备会产出“看着正常、实际无效”的结果。
  • 账号密码不要写进用例文件。用例里用 ${cred.名称} 引用，每个人的电脑上各自执行一次 mat cred set 配好，这样用例文件可以放心提交到代码仓库。

共用时的写操作都会记进「操作记录」，谁在什么时候改了什么，一查就知道。

8接到 AI 编码助手

如果你平时用 Cursor、Codex 这类工具写代码，可以把 MAT 直接挂上去：让助手读页面结构、写用例、跑用例、看报告，全程不用你手动搬数据。

$ pip install "mat-uitest[mcp]" $ mat mcp # 按标准输入输出启动 MCP 服务，填进助手的配置里 $ mat skill install # 把随包技能包装进助手的技能目录

建议先手动跑一次 mat mcp，看到「MAT MCP 就绪」再填进助手的配置。已经装好的技能包可以用 mat skill path 找到位置、手动复制。

9遇到问题

现象怎么办
找不到 mat 命令Windows 用 py -m insta_engine 代替；装了 uv 的情况多半是漏了 uv tool update-shell，补跑一次并重开终端。
adb devices 列表是空的先换数据线（很多线只供电不传数据），再看手机上的授权弹窗有没有点确认。
设备显示 unauthorized在手机上重新允许一次 USB 调试；必要时在开发者选项里「撤销 USB 调试授权」再插一次。
只连了一台设备，但它不是我想要的那台用 --serial 设备号 指定，设备号从 mat devices 里拿。
生成用例说没配模型看第 5 节，在工作区 .env 里配 GEN_*，再跑 mat doctor 确认。执行、自愈、报告不受影响。
报告太大打不开报告内嵌了每一步的截图，体积会比较大。自动化里建议直接读同目录的 run.json。
前面跑过的日志不见了控制台的任务记录存在内存里，重启服务会清空——这是正常的；已落盘的报告在「报告」页里。
换了一台电脑重新装好后跑一次 mat activate <原激活码>；要腾出名额则先在原机器上 mat activate --machines 查、mat activate --unbind 设备标识 解绑。

没找到答案？到反馈页留言，或扫码联系我们（首页「联系」分区），也可以关注公众号「Mobile AI Test」。

10命令速查

图形界面里能做的事，命令行都有对应入口。下面是最常用的一批。

起步

mat doctor环境自检：adb、设备、驱动、AI 配置
mat devices列出在线设备
mat status档位、额度、凭据、设备一览
mat init建工作区（cases / artifacts + 示例用例）
mat console打开本地控制台（加 --share 供局域网共用）

摸清 App

mat index 包名真机爬取，建页面索引（控件清单）
mat explore 包名规则驱动遍历：找异常 + 沉淀页面图谱
mat describe 包名给页面补标题与功能描述
mat review 包名人工复核页面标题（生成 → 应用 → 回放）
mat arrival 包名验证到达某页面的路径是否稳定

用例

mat gen "一句话" --package 包名自然语言生成用例
mat import 文件 --package 包名导入手工用例（Excel / CSV / Markdown / 文本）
mat run 文件或目录 --app 包名执行用例；目录 + --app 即批量
mat suite list / new / add / check套件：分组、校验、批量执行
mat heal list / apply查看自愈提案 / 回写成新用例
mat diagnose 产物目录失败归因
mat calibrate 产物目录改判失败归类并落成规则

其它

mat cred set配置用例里 ${cred.名称} 引用的凭据
mat export导出全部本地数据（用例、索引、报告）
mat activate 激活码激活标准版；--machines 查绑定、--unbind 解绑
mat mcp / mat skill install接到 AI 编码助手
每条命令都带完整帮助：mat run --help、mat suite --help……记不住参数时先问它。