基于实际项目实践总结，适用于需要测试桌面应用的 QA 团队

---

一、Mano-P 是什么？

一句话：用 AI "看屏幕"来操作桌面应用，替代传统的元素定位器方案。

传统方案（Playwright/Selenium/Appium）：
  界面 → 读DOM/Accessibility Tree → 定位元素 → 操作
         ↑ 必须有API或SDK支持，没有就废了

Mano-P（纯视觉驱动 GUI-VLA）：
  截屏 → AI视觉模型"看"画面 → 理解内容 → 点击/输入/拖拽
         ↑ 屏幕上能看到的就能操作，不需要任何 API

适用场景：

• ✅ 桌面应用测试（WPS、微信、飞书、自研系统等）
• ✅ 没有 API 的老旧系统 / 自研客户端
• ✅ 跨应用流程测试（A系统→B系统→C系统）
• ✅ UI 频繁改版、维护定位器成本高的场景

不适用场景：

• ❌ 需要像素级精度的操作
• ❌ 实时性要求极高的场景
• ❌ 复杂逻辑判断为主的任务

---

二、环境准备

2.1 硬件要求

配置	最低要求	推荐配置
芯片	Apple M1 及以上	Apple M4
内存	16 GB	32 GB
系统	macOS Ventura (13.0) +	macOS Sequoia (15.0) +

⚠️ M1/M2 + 16GB：可运行但需使用云端模式（截图发送到官方服务器推理）
✅ M4 + 32GB：可使用本地模式（数据不出设备）

2.2 软件安装（3 步）

Step 1：安装 Homebrew（已有跳过）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2：安装命令行工具（Xcode CLT）

# 删除旧版本（如果有）
sudo rm -rf /Library/Developer/CommandLineTools

# 弹窗安装新版本
xcode-select --install
# → 弹出窗口后点"安装"，等它跑完（窗口自动消失 = 装好了）

# 接受许可协议
sudo xcodebuild -license accept

💡 踩坑提醒：Homebrew 对 Xcode 版本有强校验。如果报 Xcode is too outdated，必须先完成这步再继续。

Step 3：安装 mano-cua

brew install HanningWang/tap/mano-cua

验证安装

mano-cua -h
# 看到 run / stop 等命令说明 = 安装成功 ✅

2.3 系统权限配置

打开 系统设置 → 隐私与安全性，为终端（Terminal/iTerm） 开启两项权限：

权限	路径	用途
屏幕录制	隐私与安全性 → 屏幕录制	让 AI 能截取屏幕画面
辅助功能	隐私与安全性 → 辅助功能	让 AI 能模拟鼠标键盘操作

💡 快捷方式：在终端执行以下命令直接打开对应设置页

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

配置完成后重启终端生效！

---

三、核心使用模式：脚本 + 视觉混合

3.1 为什么不用全视觉？

经过实战验证，混合模式是最佳平衡点：

操作类型	用脚本	用 Mano-P 视觉	原因
启动应用	✅ open 命令		秒开，零失误
打开文件	✅ open 命令		秒开，零失误
点击按钮		✅ 视觉识别	UI 可能变，视觉自适应
输入文字		✅ 视觉定位+输入	输入框位置可能变
拖拽滑块		✅ 视觉（需特殊策略）	最难的操作，见下文
结果验证		✅ 视觉多维度验证	不依赖控件状态

3.2 混合模式代码模板

#!/bin/bash
# ====== 固定操作：脚本秒执行 ======
open "/Applications/目标应用.app"
echo "✅ 应用已启动"
sleep 3

open "$HOME/Downloads/test-file.docx"
echo "✅ 测试文档已打开"
sleep 3

# ====== UI交互：交给Mano-P纯视觉 ======
mano-cua run "目标应用已启动且文档已打开。
请依次执行以下操作：
1. 点击顶部菜单栏的'XXX'
2. 在弹出的菜单中点击'YYY'
3. 验证右侧面板中ZZZ功能是否已开启" \
  --expected-result "验证通过，功能正常开启"

3.3 Mano-P Prompt 编写技巧

好的 prompt = 清晰的步骤 + 明确的预期结果 + 关键策略提示：

# ✅ 好的 prompt 示例
mano-cua run "WPS Office已经打开了文档。请依次执行以下操作：
1. 点击顶部菜单栏的'WPS AI'
2. 在WPS AI功能区中点击'伴写'选项
3. 验证伴写开关状态（检查开关颜色、状态文字、底部状态栏）" \
  --expected-result "右侧面板显示AI伴写已开启"

# ❌ 差的 prompt 示例
mano-cua run "帮我开一下伴写"
# 太模糊，AI 不知道具体要点哪里、怎么验证

Prompt 编写原则：

1. 步骤编号：用数字列表明确顺序
2. 描述具体：写清楚界面元素的准确名称（如"WPS AI"而非"AI菜单"）
3. 预期明确：--expected-result 写清通过标准
4. 策略提示：难点操作单独标注策略（如滑块验证码）

---

四、难点攻克：滑块验证码

这是 Mano-P 视觉操作的最大挑战，经过 3 版迭代找到最佳方案：

4.1 三次策略演进

版本	策略	做法	尝试次数	结论
v1 ❌	一次性快拖	直接拖到底松开	6~7 次	过头没机会修正
v2 ⚠️	拖→松开→观察→调	拖70%松开看位置，不对再调	~3 次	松开后碎片复位需重拖
v3 ✅	按住不松+微调到完全重合再松	全程按住慢慢移+边移边微调+确认100%重合才松手	1~2 次	推荐！模拟人类自然操作

4.2 v3 最佳实践 Prompt 片段

8. 【滑块拼图-v3最佳策略】必须严格执行：
   - 先仔细观察拼图缺口位置（左/中/右）
   - 点击并按住滑块拖动手柄，全程不松开鼠标！
   - 按住状态下慢慢向缺口方向移动，边移边观察碎片实时位置
   - 当碎片接近缺口时进一步放慢速度
   - 左右精细微调直到碎片和原图完全重合（像素级对齐）
   - 确认100%完全重合后才松开鼠标提交验证
   - 如果没通过就重新观察再试一次，同样用按住不松策略
   - 绝对禁止：快速一拖到底、拖一段就松开、还没对齐就松开

⚠️ 即使用了 v3 策略，滑块对纯视觉模型依然是高难度操作。
如果业务允许，可以考虑：测试环境关闭验证码 或 使用专用验证码破解服务。

---

五、测试用例设计规范

5.1 用例模板结构

## 测试用例：[功能名称]

### 基本信息
- 用例名称：xxx
- 测试目标：xxx
- 执行方式：脚本 + Mano-P 混合模式

### 步骤列表
| Step | 方式 | 操作 | 预期结果 |
|:---|:---|:---|:---|
| 1 | 🖥️ 脚本 | xxx | xxx |
| 2 | 👁️ 视觉 | xxx | xxx |
| 3 | 👁️ 验证 | xxx | xxx（多重证据）|

### 判定标准
| 检查项 | PASS | FAIL |
|:---|:---|:---|
| xxx | xxx | xxx |

5.2 验证设计原则（三重证据法）

不要只检查一处！至少从 2-3 个独立位置 验证结果：

❌ 单一验证：只看右侧开关颜色
✅ 三重验证：
   ① 右侧面板开关颜色（蓝紫色 = 激活态）
   ② 开关旁状态文字（"已开启" vs "未开启"）
   ③ 底部状态栏文字（"AI 伴写：已开启"）
   
三项全过 = PASS，任一不过 = FAIL + 截图留证

5.3 结果判定自动化

Mano-P 的 --expected-result 参数会驱动 AI 自动做结果对比：

mano-cua run "操作指令..." --expected-result "期望的最终状态描述"
# AI 执行完后会自动对比当前界面和期望结果
# 输出：COMPLETED（通过）或 FAILED（失败+原因分析）

---

六、常见问题 FAQ

Q1：Mano-P 报错 No active session？

原因：上一次任务还在运行或异常退出
解决：先执行 mano-cua stop 再重新开始

Q2：AI 点错了位置怎么办？

原因：视觉模型偶尔误判（尤其是相似图标、小按钮）
解决：

• Prompt 中增加更精确的描述（“右上角的XX按钮"而不是"XX按钮”）
• 分步执行，每步只做一个操作，降低复杂度

Q3：滑块验证码总是通不过？

原因：拼图缺口小，像素级对齐困难
解决：

• 优先使用 v3 策略（按住不松+慢移微调）
• 联系开发在测试环境关闭验证码
• 作为最后手段：该步骤改为手动辅助

Q4：多显示器支持吗？

当前限制：只支持主显示器。确保被测应用在主屏上操作。

Q5：Windows/Linux 可以用吗？

当前状态：macOS 稳定支持，Windows/Linux 仍在 Beta。建议团队优先在 Mac 上开展。

Q6：如何处理弹窗/对话框遮挡？

现状：Mano-P 会自动检测并处理大部分弹窗（如更新提示、协议弹窗）
技巧：Prompt 中加上条件语句：“如果出现xx弹窗，点击xx关闭/同意”

Q7：数据安全？截图会发到哪里？

• 本地模式（M4+32GB）：所有数据不出设备
• 云端模式（M1/M2+16GB）：截图发送到官方服务器推理
• 敏感数据场景建议用本地模式或评估云端安全风险

---

七、快速上手 Checklist

团队成员首次上手时，按此清单逐项确认：

• 环境检查：macOS 13.0+ / Homebrew 已装
• CLT 安装：xcode-select --install 完成
• mano-cua 安装：brew install HanningWang/tap/mano-cua
• 权限配置：屏幕录制 ✅ + 辅助功能 ✅
• 终端重启：权限配置后重启了终端
• 基础验证：mano-cua -h 正常显示帮助信息
• 首跑测试：用一个简单操作验证端到端流程（如"启动记事本→输入文字"）

---

八、今日实战案例参考

完整的 WPS Office 登录 + AI 伴写测试用例（13步），详见：

• 测试用例文档：wps-ai-banxie-testcase.md
• 执行脚本：wps-ai-banxie-test.sh

关键经验总结：

1. 固定操作用 open 脚本，UI 交互交给视觉模型
2. 滑块验证码用 v3 策略（按住不松+微调到重合才松开）
3. 结果验证用三重证据法，避免误判
4. Prompt 要写具体步骤和明确预期，不能模糊
5. 分步执行比一步到位更稳定，特别是复杂流程

---

九、技术栈总览

组件	说明
mano-cua	Mano-P CLI 工具，封装了会话管理和任务调度
Mano-P 服务端	视觉语言模型（VLA），负责截图理解→动作决策
本地模式	Apple Silicon 本地推理（需 M4+32GB）
云端模式	截图上传至官方服务器推理（任意 Mac 可用）
Bash 脚本	编排固定操作和 mano-cua 调用序列