场景总览

环节输入执行内容输出
① AI 连接知识库 需求文档 读取需求，生成测试点与用例，保存到知识库 测试点 / 用例清单
② AI 接口测试 页面 / 接口清单 抓包整理接口，按清单调用验证 接口清单 / 执行结果
③ AI 连接数据库 数据需求描述 自然语言转 SQL，确认后执行 测试数据 / 查询结果
④ AI 执行 UI 自动化 操作指令 / 用例 用 Midscene 自动操作网页或 App，生成可回放报告 操作报告

场景一：AI 连接知识库

需求文档、接口清单、用例统一存放知识库，AI 读取需求生成用例并保存，实现「需求 → 用例 → 结果」的自动化闭环，产出可追溯、可复用。

技能包：knowledge-base-analysis（点击展开；复制后交给 agent 加载即可使用，agent 会自动检查并引导完成连接配置）

SKILL.md 内容（复制保存为 SKILL.md）：

---
name: knowledge-base-analysis
description: 基于知识库中的需求文档生成测试点清单与测试用例，支持需求变更后更新用例、检索历史需求与用例。当用户提到"生成用例""分析需求""需求转用例""更新用例""查历史用例"等任务时触发。加载本技能后，agent 自动检查并引导完成知识库连接配置，无需另行查找配置方式。
compatibility: 需要 agent 环境支持 MCP 连接；知识库为 MCP 协议接入
allowed-tools: Read, Write
---

# 知识库需求分析（knowledge-base-analysis）

## 一、技能包内容（全部内置，无需另行下载）
- assets/知识库连接配置模板.json — 连接配置模板（首次填写一次）
- assets/需求分析提示词模板.txt — 生成用例的标准提示词
- references/知识库目录规范.md — 需求库/接口库/用例库存放规则

## 二、连接配置（agent 按此引导，一次性完成）
第一步：检查连接是否已配置（检查 MCP 连接器列表中是否存在「知识库」连接）
  - 存在：进入第四步验证连接
  - 不存在：进入第二步引导配置
第二步：引导用户填写配置（使用 assets/知识库连接配置模板.json）
  - service_url：知识库 MCP 服务地址（企业专属，向管理员获取）
  - auth_token：授权 token（用户在知识库平台「开发者/密钥」处生成）
  - space_names：固定三个目录名（需求库 / 接口库 / 用例库）
  - 告知用户 token 是敏感信息，仅填入本地配置，不外传
第三步：建立连接（失败则根据错误信息引导排查：地址/过期/网络）
第四步：验证连接（必须通过才继续）
  - 执行「列出知识库目录」，应看到：需求库 / 接口库 / 用例库
  - 验证失败：回到第三步排查，不继续后续步骤

## 三、执行需求分析（连接就绪后）
需求输入（支持多种格式）：知识库文档（ID/链接）/ Word / PDF / 文本（粘贴正文或文件路径）；频繁变动的需求按版本归档，摘要标注「本次分析版本」
1. 确认要分析的需求文档（文档 ID / 链接 / 正文 / 文件）
2. 读取需求文档，输出「需求理解摘要」：功能点 / 业务规则 / 依赖的接口与数据 / 分析版本
3. 停下，等人工确认摘要方向无误（确认前不生成用例）
4. 收到「摘要无误」后，生成测试点清单，按功能模块分组
5. 生成测试用例，每条含：用例编号（模块-序号）/ 标题 / 前置条件 / 分步步骤 / 预期结果（可量化）/ 优先级（P0-P3）/ 类型
6. 覆盖度自查：正常流程、边界值、异常场景、数据一致性、并发、业务规则
7. 输出用例草稿后停下，等待人工复核

## 四、人工复核（不得跳过）
逐项检查：需求点全覆盖（缺项列清单）、边界值至少一例、预期结果可量化（禁"系统正常返回"）、优先级合理、步骤可执行
收到修改意见：逐条修改并说明改动点
收到「确认」：进入下一步

## 五、确认后保存到知识库
1. 用例写入知识库用例目录，命名：需求名 + 用例集
2. 关联需求文档 ID（用例条目中标注）
3. 输出保存结果（写入位置 + 关联 ID）

## 六、输入什么 / 产出什么（技能之间的交接约定）
输入：需求文档（ID/链接/正文/文件）+ 需求版本 +（可选）关联接口清单
输出（落知识库，固定命名）：
- 需求理解摘要 → 用例库/需求名+_摘要（功能点/业务规则/依赖/版本）
- 测试点清单 → 用例库/需求名+_测试点（模块/测试点/来源需求点）
- 用例集 → 用例库/需求名+用例集（编号/标题/前置条件/步骤/预期结果/优先级/类型/关联需求ID）
交接方式：下游通过「关联需求 ID」与「用例编号」引用本环节产物；需求变更基于原用例集 ID 更新，不重复创建；中断恢复从用例库读已落库产物

## 七、边界情况
- 需求文档不存在：提示用户检查 ID/链接，不猜测
- 需求不存在的测试维度：说明原因，不编造规则
- 连接中途失效：提示重新验证连接，已生成内容不丢失
- 敏感数据：脱敏后展示
- 文档为图片/扫描件：提示先做文字识别（OCR）或改用文字版本

## 八、使用示例
用户说：「用知识库需求分析技能，分析《巡检问题处理需求_v2》生成用例」
agent 执行：检查连接 →（未配置则引导填写）→ 验证连接 → 读取需求 → 摘要 → 测试点 → 用例草稿 → 停下等复核 → 确认后保存到知识库（含输入/产出内容）

配套文件：

  1. 读取指定需求文档，输出测试点清单与测试用例。
  2. 按关键词检索知识库，定位相关需求、接口清单、历史用例。
  3. 将确认后的用例保存到知识库，建立需求与用例的对应关系。
实现步骤
  1. 配置知识库连接：在本地统一配置文件中写入 MCP 服务地址与授权 token，供 AI 调用。
  2. 需求文档录入知识库，归入对应项目空间，标注需求版本。
  3. 对话中让 AI 读取该需求文档，先确认 AI 输出的需求理解摘要，再生成测试点清单与用例（详见测试方法）。
  4. 人工复核覆盖度，补充遗漏的边界与异常场景，确认。
  5. 将确认后的用例保存到知识库，关联需求文档 ID。

需求输入格式说明：需求文档不限于知识库中的结构化文档，也支持 Word、PDF 等常见格式——直接粘贴正文或上传附件即可，AI 会先提取内容再分析。需求频繁变动时，按版本号归档（如 _v2、_v3），AI 基于指定版本分析，并在摘要中标注「本次分析版本」，避免新旧需求混淆。

测试方法
  1. 先总结需求：AI 先输出需求理解摘要（功能点、业务规则、依赖），人工确认方向无误后再生成用例，避免理解偏差传导到后续。
  2. 用例生成：按固定提示词模板生成用例，格式统一（编号/标题/前置条件/步骤/可量化预期/优先级/类型）。
  3. 覆盖度自查：AI 输出前自查正常流程、边界值、异常场景、数据一致性、并发、业务规则六类维度，缺项说明原因。
  4. 检查确认：人工按复核清单检查需求点覆盖、边界值、预期可量化性、优先级、可执行性，确认后保存到知识库。
复用方式
  1. 连接配置集中管理：服务地址与 token 存放在统一配置文件，token 失效时仅需更新该文件，脚本无需改动。
  2. 知识库目录固定三类：需求库、接口库、用例库，AI 按固定目录读取，路径不随需求变化。
  3. 提示词模板固定：同一份模板文件供所有需求复用，输出格式一致。
  4. 文档按 ID 定位：需求更新时基于原文档 ID 追加变更内容，不重复创建文档。
执行示例
步骤操作执行结果
① 读取需求 对话中让 AI 读取《巡检问题处理需求_v2》 AI 输出需求理解摘要（功能点、业务规则、依赖），标注本次分析版本
② 确认摘要 人工核对摘要方向无误 确认后 AI 继续生成测试点与用例
③ 生成用例 AI 按固定提示词模板生成测试点清单与用例草稿 输出格式统一的用例（编号/标题/步骤/可量化预期/优先级/类型）
④ 检查确认 人工按复核清单检查覆盖度，补充遗漏 用例确认完成
⑤ 保存 确认后的用例保存到知识库用例目录，关联需求文档 ID 形成需求 → 用例对应关系，可追溯

场景二：AI 接口测试

把页面操作转化为接口清单，直接调接口验证系统行为，覆盖页面操作不到的异常参数场景，并降低回归成本。

技能包：api-testing（点击展开；复制后交给 agent 加载即可使用，agent 会自动安装环境并引导配置）

SKILL.md 内容（复制保存为 SKILL.md）：

---
name: api-testing
description: 将页面操作转化为接口文档并按清单调用验证，支持接口回归、参数异常测试、接口与数据联动验证。当用户提到"抓包整理接口""按接口清单验证""接口回归""整理接口文档"等任务时触发。加载本技能后，agent 自动检查并引导完成环境安装与配置，无需另行查找安装方式。
compatibility: 需要 agent 环境支持 Node.js 与 npm；脚本已打包
allowed-tools: Read, Bash, Write
---

# 接口测试（api-testing）

## 一、技能包内容（全部内置，无需另行下载）
- scripts/setup-env.sh — 一键安装依赖（Node 初始化 + playwright + tsx）
- scripts/capture.ts — 抓包脚本（捕获 xhr/fetch 请求）
- assets/接口整理提示词模板.txt — 请求记录整理为接口文档的标准提示词

## 二、环境安装（agent 按此引导，一次性完成）
第一步：检查 Node.js（node -v），未装则引导安装
第二步：执行 scripts/setup-env.sh 一键安装依赖
第三步：下载浏览器内核（npx playwright install chromium），网络受限时配置国内镜像
第四步：运行示例抓包脚本验证环境，能打开页面即就绪

## 三、执行接口测试（环境就绪后）
方式 A：抓包整理（无现成清单）
1. 运行 capture.ts 打开被测页面，请用户手动操作一遍功能
2. 捕获请求记录（方法/URL/参数）输出 JSON
3. 用接口整理提示词模板整理为接口文档：接口名/方法/路径/入参/凭证方式/响应字段
4. 按业务模块分组，存入知识库接口目录
方式 B：按清单验证（已有清单）
1. 读取接口清单，展示待执行接口
2. 确认后按清单发起调用，逐条断言关键返回字段
3. 输出「接口执行结果表」，停下等人工核对

## 四、人工确认点（不得跳过）
- 调用前：展示将执行的接口清单，确认后批量执行
- 写操作接口（新增/修改/删除）：单独展示请求体，确认后执行
- 执行结果：人工核对失败项，确认是否为系统缺陷

## 五、测试方法
- 回归验证：按清单批量调用，断言关键返回字段，结果自动保存
- 参数异常：构造缺失字段/空值/超长/非法类型入参，验证错误处理
- 接口与数据联动：调用后查数据库核对状态一致
- 身份凭证验证：有效/无效凭证调用，验证未授权拦截

## 六、边界情况
- 抓包无请求记录：提示检查页面操作与监听
- 接口返回非 200：输出状态码与响应体，不强行断言
- 敏感信息（token、账号）：脱敏后展示

配套文件：

  1. 抓包或拦截页面请求，得到接口清单。
  2. 按统一模板整理接口文档：接口名、方法、路径、入参、返回字段、身份凭证方式。
  3. 按接口清单直接调用接口，构造参数并断言响应，验证系统行为。
  4. 接口变更时更新接口清单，后续用例与脚本自动复用。
实现步骤
  1. 打开被测页面，启用抓包工具（浏览器开发者工具 Network，或请求拦截脚本），完整操作一遍被测功能。
  2. 导出请求记录：方法、地址、参数、响应。
  3. 让 AI 按统一模板整理为接口清单，存入知识库接口目录。
  4. 编写接口调用脚本：按清单读取接口定义，构造请求并断言响应关键字段。
  5. 执行脚本，输出每个接口的调用结果。
测试方法
  1. 接口回归验证：按接口清单批量调用接口，逐条断言关键返回字段，结果自动保存；接口变更只改清单对应条目，回归脚本无需改动。
  2. 参数异常测试：对关键接口构造边界输入参数（缺失字段、空值、超长、非法类型），调用后验证系统返回与错误处理是否符合预期。
  3. 接口与数据联动：接口调用后查询数据库核对状态一致（如巡查结果上报后记录分类字段已写入），接口结果与数据状态互相印证。
  4. 身份凭证验证：按清单记录的身份凭证方式分别以有效/无效凭证调用，验证未授权访问的拦截处理。
复用方式
  1. 接口清单为唯一维护源：接口变更只更新清单中对应条目，调用脚本读取清单，无需逐处修改。
  2. 身份凭证统一封装：清单记录凭证方式（登录态 / token），脚本统一处理，调用处不重复实现。
  3. 调用脚本模板化：参数从用例中读取，新增用例只需补充参数，不重写脚本。
  4. 可挂定时回归：核心接口脚本可由定时任务触发，结果自动保存。
执行示例
步骤操作执行结果
① 抓包 无界面浏览器打开演示页面，注册请求监听（仅收集 xhr/fetch），页面自动加载触发请求 成功捕获到接口请求（方法 / URL / 参数）
② 整理清单 将捕获请求按统一模板整理为结构化接口清单 生成接口清单（含方法、路径、入参、返回字段）
③ 调用验证 按清单对接口发起实际调用，检查响应 接口返回 HTTP 200，响应正常

验证结论：「抓包 → 整理清单 → 调用验证」演示链路完整跑通；接入正式业务页面后，同一套流程直接复用，无需改造。

配套资源

接口整理提示词模板：

  1. 以下是页面抓包得到的请求列表，请整理为接口文档：
  2. 每个接口给出：接口名/方法/路径/入参(含类型)/身份凭证方式/响应关键字段；
  3. 按业务模块分组；输出为可直接存入知识库接口目录的结构化条目。

抓包脚本（存为 capture.ts）：

  1. 新建项目：npm init -y、npm pkg set type=module；安装 npm install playwright tsx；下载内核 npx playwright install chromium。
  2. 脚本逻辑：启动浏览器 → 注册 page.on('request') 监听（仅收集 xhr/fetch）→ 打开被测页面 → 手动操作 → 将请求（方法/URL/参数）输出为 JSON 文件。
  3. 运行：npx tsx capture.ts。

工具定位说明：日常接口测试用 agent 对话完成（抓包、整理、调用、断言）；Postman / Apifox 作为人工复核与排查工具，agent 断言失败时手动查看响应；JMeter 用于压测性能场景，不在本方案范围内。

场景三：AI 连接数据库

用自然语言操作测试库，完成测试数据准备与结果验证，确认操作后数据状态符合预期。

技能包：database-query（点击展开；复制后交给 agent 加载即可使用，agent 会自动检查配置与依赖并引导填写连接参数）

SKILL.md 内容（复制保存为 SKILL.md）：

---
name: database-query
description: 用自然语言生成 SQL 并执行测试库查询，支持查数、统计、造数、改数。当用户提到"查数据""统计""生成 SQL""查一下""造数""改数"等数据需求时触发。加载本技能后，agent 自动检查配置与依赖，引导完成环境就绪，无需另行查找配置方式。
compatibility: 需要 Python 3.8+；脚本与配置模板已打包
allowed-tools: Read, Bash, Write
---

# 数据库查询（database-query）

## 一、技能包内容（全部内置，无需另行下载）
- scripts/db_tool.py — 主工具：只读保护 + 自然语言转 SQL + 执行
- assets/config.example.json — 连接配置模板（首次填写一次）

## 二、环境与配置（agent 按此引导，一次性完成）
第一步：检查 Python 环境（python --version），未装则引导安装
第二步：检查依赖，缺 pymysql 则 pip install pymysql（可配国内镜像）
第三步：配置数据库连接（首次必做）
  复制 assets/config.example.json 为 config.json，引导用户填写：
  host（测试库地址）/ port / user / password / database
  告知用户：凭据是敏感信息，仅写入本地 config.json，不外传
第四步：验证连接（必须通过才继续）
  运行 python scripts/db_tool.py run "SELECT 1"，能返回结果即正常
  失败则根据错误信息引导排查（地址/端口/账号/网络）

## 三、执行查询（环境就绪后）
只读查询（默认）：
1. 用户描述自然语言需求（如「统计 8 月 10 日以来各主播巡检异常占比…」）
2. agent 转换为 SQL 并完整展示，说明各子句用途
3. 展示后等人工确认，确认前不执行
4. 确认后执行：python scripts/db_tool.py run ""
5. 输出结果（表格 + 行数），附一句结果说明
写操作（必须显式声明 + 确认）：
1. 用户提出写需求（造数/改数）
2. agent 生成 SQL 并完整展示
3. 明确提示这是写操作，将影响数据库
4. 确认后执行：python scripts/db_tool.py run --write ""
5. 输出影响行数

## 四、安全规则（不可省略）
- 默认只读：SELECT / SHOW / DESC 直接可执行
- 写操作必须 --write 显式声明 + 人工确认
- 仅操作测试环境数据库
- 批量写操作：先查询影响范围再执行

## 五、测试方法
- 造数：在测试库准备数据（测试账号走正常流程 / 复制历史样本）
- 验证：操作后查库核对状态字段（如"人工复核后记录进入复核池"）
- 边界构造：对测试数据修改字段（空置信度/超长 reason/缺分类）
- 结果对比：AI 生成 SQL 与手工 SQL 对比一致性

## 六、边界情况
- 需求模糊：先向用户确认查询范围与条件，不猜测
- 查询超时/无结果：如实反馈，不编造数据
- 连接失败：引导检查 config.json 与网络

配套文件：

  1. 查数：验证操作后数据状态，如人工复核后记录是否进入复核池。
  2. 造数：在测试库准备测试数据（仅限测试环境，不影响线上统计），如用测试账号走正常流程产生记录、复制真实样本到测试库。
  3. 改数：对测试库数据构造边界状态，如修改测试记录的分类与置信度，供用例使用。
实现步骤
  1. 建立数据库连接工具：使用 PyMySQL 直连测试库，连接配置统一维护、不硬编码在脚本中。
  2. 用自然语言描述数据需求，例如「统计 8 月 10 日以来各主播巡检异常占比，只保留异常 3 次以上的，按占比从高到低排」。
  3. AI 将描述转换为 SQL 并完整展示。
  4. 人工核对 SQL 正确性，确认后执行，仅限测试环境数据库。
  5. 返回查询结果或造数结果，供用例使用。
测试方法
  1. 用例执行前造数：按用例前置条件在测试库准备数据，如「用测试 UID 触发一次巡检，产生一条真实记录」或「复制 10 条历史记录到测试库」，供异常分类展示、人工复核池等用例使用。
  2. 用例执行后验证：操作完成后查询数据库核对状态字段是否符合预期，如「人工复核后确认该记录已进入人工复核池」。
  3. 边界状态构造：对测试库中的测试数据修改字段构造边界状态（空置信度、超长 reason、缺分类），供异常与边界用例使用。
  4. 结果对比：同一数据需求分别用 AI 生成 SQL 与手工 SQL 查询，对比结果一致性，确认 AI 翻译准确后持续使用。
复用方式
  1. 只读保护：写操作必须显式声明并经过人工确认，防止误操作（工具行为见配套资源）。
  2. 连接配置集中维护：主机、账号、库名统一存放在配置表，脚本启动时解析，变更只改配置。
  3. 常用操作积累为脚本库：高频查询与测试库造数场景形成可重复调用的脚本。
  4. SQL 生成后强制展示确认环节，不经确认不执行。
执行示例
步骤操作执行结果
① 建立连接 数据库连接脚本从统一配置读取测试库连接参数 连接成功，测试库多张表可读
② 自然语言转 SQL 输入「按项目分组统计主播数量与在播数」 AI 生成对应聚合查询 SQL 并完整展示
③ 确认执行 人工核对 SQL 后执行 查询正常返回，结果格式化输出
④ 写操作保护 执行一条未显式声明的 DELETE 语句 被工具拒绝，提示需显式声明，零数据改动

验证结论：「自然语言 → SQL → 人工确认 → 执行」链路完整可用；只读保护生效，未声明写操作无法执行，数据安全有保障。

配套资源

数据库工具脚本：

  1. 连接参数从统一配置文件读取（不硬编码）。
  2. 默认只读：SQL 以 SELECT 开头才允许直接执行；写操作需显式声明并打印 SQL 由人工确认。
  3. 用法示例：在 agent 工具对话窗口输入「统计 8 月 10 日以来各主播巡检异常占比，只保留异常 3 次以上的，按占比从高到低排」→ AI 生成 SQL → 展示 → 确认后执行。复杂查询（多条件聚合、分组统计、百分比计算）由 AI 一次生成，人工核对后执行。

对应生成的 SQL（AI 产出，实测返回 7 行结果）：

SELECT r.uid, r.project, r.star_level,
       COUNT(*) AS patrol_cnt,
       SUM(CASE WHEN r.category_label LIKE 'BAD%' OR r.category_label LIKE '异常%'
                THEN 1 ELSE 0 END) AS abnormal_cnt,
       ROUND(SUM(CASE WHEN r.category_label LIKE 'BAD%' OR r.category_label LIKE '异常%'
                THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 1) AS abnormal_pct
FROM 巡检记录表 r
WHERE r.audit_at >= '2026-08-10 00:00:00'
GROUP BY r.uid, r.project, r.star_level
HAVING abnormal_cnt >= 3
ORDER BY abnormal_pct DESC, patrol_cnt DESC
LIMIT 10;

界面化工具（常用操作预置成网页按钮）：高频、固定的数据库操作可以做成网页界面，输入条件点按钮即执行（如按 UID 查询/修改主播开播状态、替换巡检截图），省去每次打开数据库工具拼 SQL。这类工具与 AI 自然语言互补：高频固定操作走界面按钮（较快），偶发灵活查询走 AI 自然语言（多种查询方式）。界面按钮属于模板化落地，AI 自然语言属于灵活查询。

场景四：AI 执行 UI 自动化（网页与 App）

使用 Midscene（网页端 @midscene/web、App 端 @midscene/android，基于 Playwright）：自然语言指令驱动 AI 自动操作网页或 App，自动生成可回放报告。定位靠视觉模型识别截图，无需维护页面选择器，页面改版不影响脚本。

技能包：ui-automation（点击展开；复制后交给 agent 加载即可使用，agent 会自动安装环境并引导配置视觉模型）

SKILL.md 内容（复制保存为 SKILL.md）：

---
name: ui-automation
description: 用自然语言操作指令驱动 Midscene 自动执行网页或 App 界面操作并生成可回放报告。当用户提到"自动操作界面""执行 UI 操作""跑一下流程""生成操作报告"等任务时触发。加载本技能后，agent 自动检查并引导完成环境安装与模型配置，无需另行查找安装方式。
compatibility: 需要 agent 环境支持 Node.js 与 npm；App 端需 adb 与安卓真机
allowed-tools: Read, Bash, Write
---

# UI 自动化（ui-automation）

## 一、技能包内容（全部内置，无需另行下载）
- scripts/setup-env.sh — 网页端一键安装（Midscene + Playwright + tsx）
- scripts/setup-android.sh — App 端一键安装（@midscene/android）
- scripts/demo.web.ts / demo.android.ts — 示例脚本（可直接改）
- assets/.env.example — 视觉模型配置模板

## 二、环境安装（agent 按此引导，一次性完成）
网页端：
1. 检查 Node.js（node -v），未装则引导安装
2. 执行 scripts/setup-env.sh 一键安装依赖
3. 下载浏览器内核（npx playwright install chromium）
4. 复制 assets/.env.example 为 .env，引导用户填写视觉模型配置：
   MIDSCENE_MODEL_BASE_URL（服务地址）/ API_KEY（密钥）/ MODEL_NAME / FAMILY
5. 运行 npx tsx scripts/demo.web.ts 验证，能执行操作即就绪
App 端（安卓）：
1. 手机开启「开发者选项 → USB 调试」，连接电脑
2. 验证设备：adb devices 显示 device（unauthorized 需在手机弹窗点允许）
3. 执行 scripts/setup-android.sh 安装依赖
4. 视觉模型配置复用同一份 .env
5. 运行 npx tsx scripts/demo.android.ts 验证

## 三、执行 UI 自动化（环境就绪后）
1. 确认用户的操作指令（自然语言）
2. 将指令拆分为可执行步骤（输入/点击/滑动/断言）
3. 选择脚本形式：YAML 场景文件（固定流程）或 TS 脚本（需变量/分支时）
4. 执行脚本，每步操作自动截图
5. 生成可回放报告：操作日志 + 每步截图 + 断言结果
6. 输出报告后停下，等人工核对关键步骤

## 四、人工确认点（不得跳过）
- 断言失败步骤：标注失败原因并建议排查方向
- 涉及金额、提现等敏感操作：执行前单独确认
- 执行结果：人工核对报告，确认操作与预期一致

## 五、复用方式
- 模型配置集中在 .env：网页端与 App 端共用，换模型只改两处
- 指令描述意图而非元素：页面结构变化不影响执行
- 公共操作拆出：登录等写成共用脚本，其他测试直接引用
- 核心流程可挂定时任务，无人值守回归

## 六、边界情况
- 元素识别不准：视觉模型偶发误识别，报告展示截图供人工核对
- 页面改版：视觉定位免维护，无需改脚本
- adb 未识别设备：引导检查 USB 调试授权与数据线
- 敏感信息（账号/金额）：脱敏后展示

配套文件：

  1. 网页：自动打开页面，执行输入、点击、滚动等操作，抽取页面数据，断言页面状态。
  2. App：通过 USB 调试连接安卓设备，启动指定应用，用自然语言操作应用界面（点击、输入、滑动），抽取界面数据并断言。
  3. 执行过程自动生成可视化报告，每步操作附截图，可逐步回放。
实现步骤

网页端：

  1. 初始化项目：新建目录，执行 npm init -y，设置 npm pkg set type=module（脚本使用顶层 await，需按 ESM 运行）。
  2. 安装依赖：npm install @midscene/web playwright tsx dotenv。
  3. 下载浏览器内核：npx playwright install chromium（未安装会报 Executable doesn't exist）。
  4. 配置视觉模型：新建 .env，填写模型服务地址、密钥、模型名与模型系列（MIDSCENE_MODEL_BASE_URL / API_KEY / MODEL_NAME / FAMILY）。
  5. 编写操作脚本：用 PlaywrightAgent，操作以自然语言描述，如「在搜索框输入 耳机，点击搜索」。
  6. 运行脚本（npx tsx demo.web.ts），AI 自动执行操作并生成报告。

App 端（安卓）：

  1. 前置准备：手机开启「开发者选项 → USB 调试」，用数据线连接电脑。
  2. 确认设备识别：命令行执行 adb devices，设备序列号后跟 device 表示已连接；显示 unauthorized 表示需在手机弹窗点「允许 USB 调试」并勾选始终允许。
  3. 安装依赖：npm install @midscene/android tsx dotenv；视觉模型配置复用同一份 .env。
  4. 编写操作脚本：用 AndroidAgent / AndroidDevice，通过 getConnectedDevices 获取设备，device.launch 打开 App（传包名或网址），操作以自然语言描述。
  5. 运行脚本（npx tsx demo.android.ts），AI 在真机自动执行操作并生成报告。
复用方式
  1. 模型配置集中在 .env：网页端与 App 端共用同一份配置，更换模型只需修改模型名与模型系列两项，脚本无需改动。
  2. 指令描述意图而非元素：脚本用自然语言描述操作目的，页面或界面结构变化不影响执行。
  3. App 设备连接步骤固定：adb 路径与设备确认流程不变，手机授权一次后长期有效。
  4. 核心流程可挂定时任务，实现无人值守回归，仅需查看报告判断结果。
执行与复用

两种脚本形式，按场景选用：

  1. YAML 场景文件：把操作步骤写成纯步骤清单（自然语言指令），适合固定场景直接执行。文件内容就是步骤本身：
# 登录后进入直播间并送出礼物
- aiAct: 如果未打开礼物面板，点击底部礼物按钮打开
- aiAct: 选一个最便宜的礼物（避开超值、礼包、充值入口）
- aiAct: 点击"赠送"按钮
- aiAssert: 公屏出现送礼消息，无充值弹窗
  1. TS 脚本：需要变量、条件分支、调用共用脚本（如登录脚本）时用代码写，逻辑更强。编写时保存为 .ts 文件，运行时不需任何描述。

运行命令：

  1. 每次执行自动生成可回放报告（含每步截图），失败可通过截图定位到具体步骤。

复用层级：

层级做法效果
1. 直接重跑已验证的脚本原样再次执行同一测试随时可重复
2. 场景固化为 YAML跑通的流程整理成 YAML 步骤文件，以后直接执行，步骤一目了然固定场景即存即用
3. 共用操作拆出登录等共用操作单独写成一份脚本（如 lib/login.ts），其他测试直接使用，不用重复写登录逻辑只维护这一处
4. 参数化账号、数据通过命令行参数传入，脚本内用变量引用一套脚本覆盖多账号、多场景
5. 模板化复制已验证的脚本模板，仅替换操作指令与断言新增测试 = 复制模板 + 补充指令

步骤示例（以 App 登录脚本为例）：

  1. 新建公共登录函数 lib/login.ts：输入手机号、输入密码、点击登录、断言进入成功界面。
  2. 新建业务脚本 test-xxx.ts：连接设备 → 调用登录函数 → 执行业务操作 → 断言结果 → 生成报告。
  3. 业务脚本运行：node --import tsx test-xxx.ts 账号 密码 操作指令（账号密码作参数传入）。
执行示例
步骤自然语言指令执行结果
① 邮箱登录 在邮箱输入框输入测试账号，输入密码，点击登录 进入 App 主界面，登录成功
② 进入直播间 点击第一个正在直播的房间卡片 进入直播间，画面与工具栏正常显示
③ 发送消息 点击公屏输入框，输入消息，点击发送 消息上屏显示
④ 送出礼物 打开礼物面板，选择一个小额礼物，点击赠送 公屏出现送礼消息，无充值弹窗

覆盖的界面范围：

界面验证内容
底部导航直播 / 家族 / 社區 / 訊息 / 我 五个页面正常切换
直播页地区筛选（多地区切换）、搜索直播间、进入直播间
个人中心用户信息、关注/粉丝统计、功能菜单正常展示
消息中心会话列表与消息分类正常展示
家族页家族推荐列表、创建入口、加入按钮正常展示
社区页动态内容、发布入口正常展示

执行产物：每步操作自动截图并生成可回放报告；报告含操作日志、截图、断言结果，失败时可按截图定位到具体步骤。整个流程的脚本固化后，后续以同样命令直接重跑，无需重新编写。

配套资源

UI 自动化脚本：按工具官方文档编写示例脚本，配置视觉模型后替换被测网址与操作指令即可运行，执行后自动生成可回放报告。

工作流程

四个场景由编排技能（test-workflow-orchestrator）调度，一条指令「完整跑一遍《需求名》」即可触发全流程。执行顺序与并行关系：

顺序动作输入来源产出（存知识库）是否可并行
①知识库：读需求 → 生成用例知识库需求文档用例集（用例库/需求名+用例集）—
②接口：抓包整理接口清单被测页面操作接口清单（接口库/模块+接口）可与①并行
③数据库：按用例准备测试数据用例集数据状态（用例库/需求名+数据状态）等①完成
④UI 自动化：按用例执行界面操作用例集 + 数据状态操作报告（用例库/需求名+操作报告）可与⑤并行
⑤接口：按清单执行验证接口清单接口执行结果（接口库/模块+执行结果）可与④并行
⑥汇总：读取全部产物，按需求ID+用例编号关联，输出完整测试报告④⑤的产物汇总报告等④⑤完成

产物传递规则：每个环节的产出一律存知识库固定位置（命名：需求名 + 产物类型），下一个环节从知识库读取，禁止口头交接。环节之间用「需求 ID + 用例编号」关联。

稳定运行需要做到以下几点：

  1. 知识库为统一存放地：需求、接口、用例、结果统一存放，AI 从库读取、写入，环节之间靠知识库衔接。
  2. 内容相互关联：用例关联需求 ID，接口清单关联功能模块，变更一处即可让后续环节自动更新。
  3. 人工确认环节：SQL 执行前确认、用例确认前复核、执行结果抽检，三个环节不省略。
  4. 配置和模板统一管理：知识库连接、数据库连接、视觉模型配置统一管理；提示词、接口、用例模板统一维护。
  5. 一处修改，后续同步生效：需求或接口变更时，仅更新知识库中对应条目；UI 脚本因视觉定位免维护，后续直接复用，不重复抓包、不重复分析。
编排技能：test-workflow-orchestrator（点击展开；复制后交给 agent 加载，即可一条指令跑完整流程）

SKILL.md 内容（复制保存为 SKILL.md）：

---
name: test-workflow-orchestrator
description: 接收需求文档，按顺序调用四个测试技能完成完整测试流程，自动传递中间产物，输出汇总报告。当用户说"完整跑一遍测试""执行测试工作流""从需求开始测""跑全流程"等任务时触发。本技能只负责调度，具体执行调用对应技能完成。
compatibility: 需要四个场景技能已安装（knowledge-base-analysis / api-testing / database-query / ui-automation）
allowed-tools: Read, Bash, Write
---

# 测试工作流（test-workflow-orchestrator）

## 本技能是什么
本技能是调度员，不自己做具体测试。它按顺序调用四个场景技能，
把上一个环节的产出交给下一个环节，最后汇总成一份完整报告。

## 执行流程（按序）
第 1 步：准备
1. 确认四个场景技能都已安装，缺少哪个先提示安装，不继续
2. 向用户确认要测试的需求文档（ID / 链接 / 正文 / 文件）

第 2 步：知识库环节（生成用例）
1. 调用 knowledge-base-analysis，加载「先总结需求 → 生成用例」流程
2. 产出：用例集（存知识库 用例库/需求名+用例集）
3. 人工确认用例后，进入下一步

第 3 步：接口环节（整理接口清单）
1. 调用 api-testing，加载「抓包整理清单」流程
2. 产出：接口清单（存知识库 接口库/模块+接口）
3. 可与第 2 步并行（若用户已提供页面操作条件）

第 4 步：数据环节（准备测试数据）
1. 调用 database-query，按用例所需数据条件准备数据
2. 产出：数据状态（存知识库 用例库/需求名+数据状态）
3. 写操作必须用户确认后执行

第 5 步：执行环节（两个子任务，可并行）
- 子任务 A：调用 ui-automation，按用例执行界面操作
  产出：操作报告（存知识库 用例库/需求名+操作报告）
- 子任务 B：调用 api-testing，按接口清单执行验证
  产出：接口执行结果（存知识库 接口库/模块+执行结果）

第 6 步：汇总
1. 从知识库读取：用例集 + 操作报告 + 接口执行结果
2. 按「需求 ID + 用例编号」关联
3. 输出汇总报告：需求 → 用例 → 执行结果 → 结论

## 中间产物怎么传（关键规则）
- 一律存知识库，禁止口头交接：每个环节的产出必须写入知识库固定位置
- 命名规则统一：需求名 + 产物类型（如：巡检问题处理需求_v2_操作报告）
- 关联键统一：需求 ID + 用例编号贯穿全程

## 失败怎么处理（不跳过）
- 环节失败：先修正该环节再重跑，不直接跑到下一个环节
- 比如接口验证失败 → 回到接口环节排查，而不是继续汇总
- 中断恢复：从知识库读取已保存的产物，已完成的环节不重复做

## 人工确认点（不可省略）
| 环节 | 确认点 |
| 用例生成后 | 人工检查用例覆盖度 |
| 数据准备前 | 写操作（造数/改数）必须人工确认 SQL |
| UI 执行后 | 人工核对操作报告关键步骤 |
| 汇总报告后 | 人工确认结论 |

## 使用示例
用户说：「完整跑一遍《巡检问题处理需求_v2》」
agent 执行：
1. 检查四个技能已安装 → 确认需求文档
2. 调用知识库技能生成用例 → 等人工确认
3. 调用接口技能整理清单 → 入库
4. 调用数据技能准备数据 → 等人工确认
5. 并行调用 UI 技能 + 接口验证
6. 汇总所有产物 → 输出完整测试报告

配套文件：