Kylinos Automated Testing

SKILL.md

---
name: kylinos-automated-testing
description: "指导 Agent 独立完成银河麒麟 V11 桌面软件的 GUI 兼容性自动化适配测试，不依赖特定工具链"
---

# 银河麒麟桌面软件 GUI 自动化适配测试

本 Skill 指导 Agent 在银河麒麟 V11 桌面上独立完成软件的 GUI 兼容性适配测试。Agent 应具备窗口控制、截图、界面元素识别和 LLM 视觉理解能力；具体工具不限。

## 前置条件

- 已登录桌面会话（Wayland / wlcom），桌面可被截图和控制。
- Agent 具备以下能力（或可调用对应工具）：
  - **窗口控制**：列出窗口、获取窗口信息、移动/调整窗口、发送键鼠事件。
  - **截图**：全屏截图或指定窗口截图。
  - **界面元素识别**：通过视觉模型或 OCR 从截图中提取可交互元素及其位置、文本。
  - **LLM 视觉理解**：结合截图和元素信息判断界面状态、规划动作。
  - **进程管理**：启动/停止进程、读取进程 PID。
  - **包管理**：安装/卸载 deb、apk 或其他格式的软件包。

## 整体流程

测试分五个阶段：**安装 → 启动 → 功能测试 → 卸载 → 报告**。
安装和卸载是确定性流程；功能测试有两种策略可选。

## 一、安装测试

安装是确定性流程，不需要 LLM 规划，但需要视觉确认安装界面出现并操作。

1. **记录窗口基线**：安装前记录当前所有窗口 UUID 列表。
2. **启动安装程序**：执行安装命令打开安装器。
3. **检测安装窗口**：轮询窗口列表，优先关注基线外新增弹窗；否则寻找标题为「安装器」或图标为安装器的窗口。
4. **截图 + 界面识别**：对安装窗口截图，识别界面中的按钮（如「一键安装」「继续安装」「确定」）。
5. **确定性点击**：按优先级点击安装按钮；若需要等待，按固定间隔轮询。
6. **日志判定**：读取安装器日志确认安装成功/失败。
7. **关闭安装器**：安装成功后必须点击「确定」或关闭按钮退出安装器。

安装失败则后续启动测试、功能测试、卸载测试全部标记为跳过。

## 二、启动测试

启动测试验证软件能否正常启动并出现预期界面。

1. **记录窗口基线和进程基线**：记录当前窗口 UUID 列表和进程列表。
2. **确定启动命令**：
   - 若软件为 deb 包，安装后查找系统 desktop 文件，使用其 `Exec` 字段作为启动命令；多个候选依次尝试。
   - 否则使用用户提供的启动命令或从开始菜单搜索。
3. **执行启动命令**。
4. **检测新窗口**：启动后轮询窗口列表，必须出现基线外新增窗口。
5. **截图确认关联**：对新增窗口截图，判断其是否与目标软件有关联（标题、图标、界面内容）。
6. **记录主窗口信息**：通过后记录主窗口 UUID、PID、窗口基线和清理候选基线。

若无新窗口出现或截图与目标软件无关，启动测试失败，功能测试标记为跳过。

## 三、功能测试

功能测试有两种策略，根据对软件的熟悉程度选择。

### 策略 A：预生成用例（适合已知软件）

在功能测试前，根据软件名称、简介和测试目标，由 LLM 预先生成一组场景级功能用例，然后逐个执行。

**用例生成**：
- LLM 根据软件画像生成至少 15 个功能用例，覆盖核心功能路径。
- 每个用例是一个测试场景，包含测试目标和预期行为。
- 若 LLM 生成不足，用 fallback 用例补足。

**用例执行**：见下方「功能测试循环」。

### 策略 B：在线探索（适合陌生软件）

不预生成用例。启动测试通过后，以首张界面截图为起点，由 LLM 动态规划测试目标，逐个在线探索，探索完成后归纳为用例。

**目标规划**：
1. 把启动后首张截图作为「首页证据」。
2. LLM 结合软件名称、简介、测试目标和首页截图，规划一组**单一可验证功能点**作为测试目标。
3. 每个目标必须是一个独立的用户可见功能点（如：创建内容、编辑内容、保存、打开文件、搜索、播放、设置变更）。
4. **粒度校验**：合并了多个独立功能点的目标触发重新规划，仍不合格则过滤。
5. Undo/Redo 不因可见就作为独立目标；只有测试目标明确要求或属于已规划编辑流程的低优先级验证时才允许。

**在线探索**：见下方「功能测试循环」，但循环围绕单个测试目标进行，目标达成/失败/阻塞后切换到下一个目标。

**用例归纳**：所有目标探索完成后，每个目标归纳为一个功能用例；失败目标保留失败判据和证据；若发现崩溃则生成崩溃复现用例。

### 功能测试循环（两种策略共用）

每个功能用例或测试目标按以下循环执行：

1. **环境重置**：每个用例/目标开始前，重新启动软件，刷新窗口 UUID/PID，确保上一用例的界面状态不会污染当前用例。

2. **截图 + 去重**：
   - 对当前窗口截图。
   - 与上一张有效截图比较；若内容相同，删除本次截图，复用上一张的界面观察结果，避免重复推理。
   - 若内容不同，保留截图，进行界面识别。

3. **界面识别**：
   - 调用界面元素识别，提取可交互元素的位置、类型和文本。
   - 若 LLM 支持视觉输入，把截图一并交给 LLM，由 LLM 结合截图判断元素身份和控件语义。

4. **状态判定**：LLM 根据当前界面观察判断：
   - 当前用例/目标是否已达成、失败、阻塞，或应继续探索。
   - 若已有结论，记录结果，进入下一步。

5. **动作规划**：LLM 围绕当前目标规划下一步键鼠动作：
   - 点击、输入、快捷键、等待等。
   - **动作校验**（Guard）：
     - 保存/打开/取消等业务按钮不能误定位到标题栏 Close 控件。
     - 画布/文档内容区的绘制必须落到内容区，而不是工具栏图标。
     - 文件对话框中进入目录必须双击目录，不能用 Enter 或「打开」把目录当文件打开。
     - 拖拽动作必须有明显分离的起点和终点。

6. **执行动作**：发送键鼠事件。

7. **等待界面稳定**：按固定策略等待（LLM 规划动作指定的等待时间 > 默认等待时间）。

8. **动作后截图 + 识别**：
   - 再次截图 → 去重 → 界面识别。
   - 抽取确定性状态事实：文本增删、计时器变化、弹窗开闭、截图变化、重复动作摘要。

9. **交互模式更新**：
   - 连续鼠标动作执行成功但界面无有效变化 → 进入键盘探测模式（优先规划方向键、回车、空格）。
   - 键盘动作被证明有效 → 进入键盘优先模式。
   - 文件对话框内明确目标仍可鼠标双击。

10. **事实冲突校验**：
    - 若 LLM 结论（如「界面无变化」「未放置」）与确定性事实（截图、OCR、计时器、弹窗）矛盾，降级为 `uncertain` 或修正为已通过，并记录冲突原因。

11. **循环判断**：
    - 未达成且未达最大步数 → 回到步骤 2。
    - 达成 → 记录结果，进入下一个用例/目标。
    - 达到最大步数 → 强制最终判定：通过 / 规划失败 / 阻塞 / 无法判断 / 明确兼容性失败。
    - **归因约束**：若最后一次动作刚建立前置状态、或仍缺前置条件、或界面已等价空白/默认状态，不能直接归因为软件/系统兼容性失败，应记为 `planning_failed` / `blocked` / `uncertain`。

### 崩溃检测（贯穿功能测试）

功能测试期间持续监控程序健康状态：

- 每次动作前后采集窗口列表、目标窗口/PID 状态。
- 发现与主窗口 PID 一致的非主窗口（弹窗），优先截图该弹窗并交给界面识别/LLM 理解。
- 动作后若主窗口或进程异常消失、出现崩溃/系统错误提示、或进程日志表明快速退出：
  - 保存崩溃证据：截图、窗口快照、进程状态、日志摘要。
  - 记录为 `application_failed`。
  - 若为在线探索模式，构造崩溃复现用例，结束当前软件的功能测试。
- 只有截图工具、坐标转换等自动化基础设施失败时才记录为 `automation_failed`。

### 文件工作流约束（编辑类软件）

对于具有新建、打开、保存、另存为等编辑功能的软件：

1. **先创建后保存**：先测试新建/创建可保存内容，再测试保存。
2. **打开只用本轮文件**：只打开本轮保存/另存为产生的测试文件，不打开未知已有文件。
3. **另存为可选**：仅在测试目标明确要求或界面入口明显且安全时作为低优先级独立目标。
4. **样例文件**：若家目录下存在 `samples` 目录且含匹配类型样例，播放器/阅读器/导入器优先使用；不存在则不强制。`samples` 目录只读，不保存/删除/覆盖。
5. **文件对话框操作**：
   - 拉起系统文件管理器时先点击左侧「主目录/个人」入口。
   - 进入目录使用双击。
   - 不打开未知用户文件，不删除或覆盖用户已有文件。

### 用例/目标间的清理

每个功能用例/目标结束后，按以下策略重置被测应用：

1. 优先按记录到的可信主窗口 PID 结束该进程及其子进程。
2. 若 PID 缺失或清理失败，把基线外新增窗口作为候选，筛选条件：
   - PID 不属于基线。
   - 窗口标题/app_id/icon/启动记录能确认与被测软件相关。
   - 不属于安装器、卸载器、终端、桌面组件等排除项。
3. 无法确认归属的新增窗口只记录跳过原因，不强制清理。
4. 清理完成后重新启动软件，进入下一个用例/目标。

## 四、卸载测试

卸载是确定性流程，不需要 LLM 规划。

1. **关闭清理**：按功能测试的清理策略先关闭被测应用。
2. **启动卸载程序**：执行卸载命令打开卸载器。
3. **检测卸载窗口**：优先关注基线外新增弹窗；否则寻找标题为「卸载器」的窗口。
4. **截图 + 界面识别**：对卸载窗口截图，识别按钮（如「卸载」「确认」）。
5. **确定性点击**：点击卸载/确认按钮。
6. **日志判定**：读取卸载器日志确认卸载成功/失败。

## 五、报告

测试完成后生成结构化报告，包含：

- **软件画像**：名称、版本、包类型、启动命令。
- **测试结果摘要**：安装/启动/各功能用例/卸载的通过/失败/跳过状态。
- **功能测试详情**：每个用例/目标的关键步骤、操作前/操作后截图、界面识别结果、判定依据。
- **崩溃证据**：若发生崩溃，附带截图、窗口快照、进程状态、日志摘要。
- **性能统计**：各阶段耗时、LLM 调用次数和耗时、界面识别调用次数和耗时。
- **归因说明**：区分「界面确实无变化」与「动作执行失败」与「软件/系统兼容性失败」与「判定证据冲突」。

## 关键决策原则

1. **截图去重**：避免对相同界面重复推理，节省 LLM 调用。
2. **交互模式升级**：鼠标无效才尝试键盘，键盘有效后优先键盘；但不放弃文件对话框中的鼠标双击。
3. **Guard 校验**：每次动作前校验目标一致性，避免误操作关键控件。
4. **崩溃一等公民**：崩溃/闪退/主窗口消失必须保存证据，不能只依赖 LLM 看图结论。
5. **事实冲突校验**：LLM 结论与确定性事实冲突时，以事实为准，降级或修正 LLM 判定。
6. **归因约束**：前置条件未建立或界面等价空白/默认时，不归因为软件/系统兼容性失败。
7. **环境隔离**：每个用例/目标间重启应用，避免状态污染。