@pzy560117/opentest 0.1.9 → 0.1.11

package/assets/skills-zh/opentest/references/test-asset-layout.md

@@ -0,0 +1,64 @@
+# 测试资产目录契约
+
+OpenTest 默认测试资产采用方案 B：标准测试框架骨架。不得在 `author` 阶段临场决定目录。
+
+## 默认目录
+
+```text
+tests/
+  api/
+    conftest.py
+    clients/
+    fixtures/
+    schemas/
+    test_contract_*.py
+    test_permissions_*.py
+    test_crud_*.py
+  web/
+    playwright/
+    midscene/
+  android/
+    tests_py/
+    midscene/
+  desktop/
+    scripts/
+    midscene/
+    metadata/
+
+docs/opentest/
+  matrix.md
+  fixtures/
+  acceptance/
+  runs/
+  reports/
+
+scripts/
+  opentest-run-api.ps1
+  opentest-run-web.ps1
+  opentest-run-android.ps1
+  opentest-run-desktop.ps1
+```
+
+如果项目已经有接近的目录，优先贴合现有目录，但逻辑槽位必须保持一致：执行面测试放在 `tests/<surface>/`，证据放在 `docs/opentest/`，可重复入口放在 `scripts/opentest-run-*.ps1` 或仓库等价命令。
+
+## 形态规则
+
+- 默认不是大型 QA 平台，而是稳定的测试、fixtures、报告和运行入口骨架。
+- 不要把一次性脚本作为 durable path。一次性脚本只能用于 `instant-acceptance` 或 blocked 排查证据。
+- 除非用户明确选择团队级模板，不要创建独立顶层 QA 项目。
+- `author` 只能在已选目录契约内创建或更新资产。
+- `run` 调用固定入口命令，不临时发明路径。
+- `accept` 把验收证据写到 `docs/opentest/acceptance/`，把运行产物写到 `docs/opentest/runs/` 或 `docs/opentest/reports/`。
+
+## 执行面映射
+
+| 执行面 | 稳定测试位置 | 默认运行入口 |
+| --- | --- | --- |
+| `api` | `tests/api/` | `scripts/opentest-run-api.ps1` 或 `python -m pytest tests/api -v` |
+| `web-browser` | `tests/web/playwright/` 和 `tests/web/midscene/` | `scripts/opentest-run-web.ps1` 或项目 E2E 命令 |
+| `android-app` | `tests/android/tests_py/` 和 `tests/android/midscene/` | `scripts/opentest-run-android.ps1` 或现有 Android harness 中的 `python -m pytest tests_py -v` |
+| `desktop-gui` | `tests/desktop/scripts/`、`tests/desktop/midscene/`、`tests/desktop/metadata/` | `scripts/opentest-run-desktop.ps1` 或项目 GUI 命令 |
+
+## 什么时候使用轻量形态
+
+只有矩阵行明确是一次性、探索性或 blocked 排查时，才使用轻量脚本形态。必须标明它不是 durable regression，并在 `gap/blocker` 记录原因。

package/assets/skills-zh/opentest/references/test-surfaces.md

@@ -0,0 +1,101 @@
+# 测试执行面
+
+OpenTest 同时按执行面和证据层级分类验收：
+
+- `执行面` 是从用户或调用方视角实际操作需求的位置。
+- `证据层级` 是证明需求的方式，例如 unit、integration、contract、e2e、smoke 或 security review。
+- 测试资产使用 `opentest/references/test-asset-layout.md` 的固定目录；不得在 author 时临场发明目录。
+
+主执行面只能使用下面四个值：
+
+| 执行面 | 适用场景 | 默认验收路径 | 必需产物 |
+| --- | --- | --- | --- |
+| `web-browser` | 浏览器渲染的 Web 页面、Web App、后台、SaaS、仪表盘 | 使用 `opentest-web-browser`：优先 Playwright MCP，失败时降级 Playwright CLI；稳定回归用 `@playwright/test`；视觉补充才用 Midscene | 截图、snapshot、提交后断言、console/network 记录、稳定回归的 trace/report |
+| `android-app` | Android APK 或模拟器/真机上的 Android App GUI | 有 `android-midscene-pytest` skill 时使用它：pytest 编排，`@midscene/android` 执行视觉自动化，ADB/模拟器控制设备 | pytest 报告、Midscene HTML 报告、截图、logcat、设备/App 元数据 |
+| `desktop-gui` | 原生桌面 GUI 或 Electron/Tauri/Windows/macOS/Linux App UI | 使用 `opentest-desktop-gui`：优先项目 GUI 自动化；视觉桌面自动化、弱选择器、原生控件、多窗口流程或 RDP 用 `@midscene/computer`；没有自动化时才用脚本化人工 GUI 验收 | 截图或录屏、GUI 操作日志、窗口/App 元数据、确定性回读、失败截图 |
+| `api` | HTTP API、RPC、后端工作流、契约、服务端点 | 使用 `opentest-api`：优先项目 API/integration 命令；否则用 `pytest` + `httpx` 或 `requests`、schema 校验、fixtures 和写后读证据 | 请求/响应记录、状态码、payload/schema 断言、鉴权/权限结果、数据一致性、cleanup/teardown、日志 |
+
+不要发明第五种主执行面。`unit`、`component`、`integration`、`contract`、`smoke`、`security-review` 这类是证据层级或运行门禁，不是主执行面。
+
+## 执行面 vs 证据层级
+
+示例：
+
+| 需求 | 执行面 | 证据层级 |
+| --- | --- | --- |
+| 用户提交 Web 表单并看到保存后的条目 | `web-browser` | `browser-acceptance` + `integration` |
+| Android 用户在 App 里创建任务 | `android-app` | `e2e` + `visual-acceptance` |
+| 桌面应用打开设置弹窗并保存偏好 | `desktop-gui` | `gui-acceptance` + `integration` |
+| 调用方通过 REST API 创建实体 | `api` | `contract` + `integration` |
+
+## Android App 执行面
+
+Android GUI 工作如果已安装 `android-midscene-pytest`，默认路由到它：
+
+```text
+python -m pytest tests_py -v
+  -> npm/Vitest wrapper
+  -> @midscene/android
+  -> ADB + Android emulator/device
+  -> screenshots + logcat + Midscene HTML report
+```
+
+路线选择：
+
+- 稳定自动化、演示和可回归报告：默认 `pytest -> npm/Vitest -> @midscene/android -> ADB`。
+- 一次性自然语言探索：可选 Midscene YAML runner，但不能替代 pytest 主入口。
+- Agent 直接控制 Android：只有单独配置 `MIDSCENE_MCP_ANDROID_MODE=true` 时才可选 Midscene MCP；不得自动写入全局 MCP 配置。
+- 纯 Python 测试栈：只有用户明确要求时才评估 `midscene-python`。
+
+分层运行：
+
+- 面向用户的入口是 `python -m pytest tests_py -v`。
+- pytest 应先检查 ADB、准备模拟器/真机、安装 APK、运行 ADB 冒烟并采集证据，再进入 Midscene。
+- 只有模型环境变量齐全时才运行 `npm run test:android`。
+- 只有排查 Midscene 层问题时，才单独运行 `npm run test:android`。
+
+如果缺 Midscene 模型凭据、ADB、模拟器/真机、APK 路径或 package name，记录 `blocked` 并写清缺失前置条件。不能只凭静态截图把 Android GUI 验收标成 pass。
+
+失败证据应尽量包含 `midscene_run/log/ai-call.log`、`midscene_run/log/agent.log`、`midscene_run/log/android-device.log` 和 `midscene_run/report/*.html`。
+
+## Web 浏览器执行面
+
+`web-browser` 行读取 `opentest/references/web-browser-testing.md`，或调用 `opentest-web-browser`。
+
+必须设置 `验收模式`：
+
+- `instant-acceptance`：优先 Playwright MCP，失败或不稳定时降级 Playwright CLI。
+- `durable-regression`：`@playwright/test` 或项目已有 E2E 框架。
+- `visual-ai-assist`：Midscene 只用于弱选择器、canvas、跨 frame 或视觉匹配。
+
+不得把 MCP 或 Playwright CLI 证据本身当成稳定回归。
+
+## 桌面 GUI 执行面
+
+`desktop-gui` 行读取 `opentest/references/desktop-gui-testing.md`，或调用 `opentest-desktop-gui`。
+
+路线选择：
+
+- 仓库已有可重复命令时，优先项目 GUI 自动化。
+- 原生控件、视觉流程、弱选择器、多窗口流程，或需要 AI 视觉辅助的 Windows RDP，用 `@midscene/computer`。
+- Electron 或 Tauri 如果需求可通过 DOM 验证，使用 `web-browser`；原生外壳、托盘、文件选择器、菜单、系统弹窗、安装器、更新器和多窗口行为保留在 `desktop-gui`。
+- 脚本化人工 GUI 验收只作为一次性证据兜底，不是稳定回归。
+
+不得只凭 AI 视觉断言把 `desktop-gui` 标为 PASS。保存/新增/修改/删除流程必须包含截图或录屏、GUI 操作日志、窗口/App 元数据，以及重开、重启或读取可信 App/文件/配置状态后的确定性 read/assert changed result。
+
+## API 执行面
+
+`api` 行读取 `opentest/references/api-testing.md`，或调用 `opentest-api`。
+
+路线选择：
+
+- 优先使用明确的项目 API、integration、contract 或 smoke 命令。
+- 没有项目命令时，默认 `python -m pytest tests/api -v`，用 `httpx` 或 `requests` 发请求，用 `jsonschema` 或项目已有 Pydantic/DTO 模型做 schema 校验，并用 pytest fixtures 管 seed/teardown。
+- 用 OpenAPI、protobuf、schema 文件、DTO、serializer、typed client 或需求文档作为契约来源。
+- 第三方 API 默认 mock/stub；只有需求明确要求 live 外部服务时才直接调用。
+
+不得只凭 2xx 响应把 `api` 标为 PASS。API 写操作必须包含请求/响应记录、payload/schema 断言、适用时的鉴权/权限检查、写后读/数据一致性，以及 cleanup 或 teardown 证明。
+
+## 矩阵规则
+
+每条矩阵行必须同时包含 `执行面` 和 `证据层级`。`web-browser` 行还必须包含 `验收模式`。如果一个需求需要多个执行面或模式，拆成多行，或明确主执行面，并在 `必需证据` 中写次要证据。

package/assets/skills-zh/opentest/references/web-browser-testing.md

@@ -0,0 +1,40 @@
+# Web 浏览器测试
+
+用于 `web-browser` 执行面的矩阵行。
+
+稳定 Web 资产遵循 `opentest/references/test-asset-layout.md`：Playwright 测试放 `tests/web/playwright/`，Midscene 视觉辅助放 `tests/web/midscene/`，可重复入口使用 `scripts/opentest-run-web.ps1` 或仓库已有 E2E 命令。
+
+## 验收模式
+
+| 模式 | 适用场景 | 默认工具 | 必需证据 |
+| --- | --- | --- | --- |
+| `instant-acceptance` | 现在就要证明本次变更在真实浏览器中生效 | 优先 Playwright MCP，失败或不稳定时降级 Playwright CLI | snapshot、操作步骤、提交后断言、截图、console/network 记录 |
+| `durable-regression` | 这个流程以后要在 CI 或版本回归里重复运行 | `@playwright/test` 或项目已有 E2E 框架 | 已提交测试文件、稳定 locator/断言、命令、report/trace 路径 |
+| `visual-ai-assist` | selector 难以可靠证明 UI 状态 | Midscene + Playwright 或项目浏览器驱动 | Midscene 报告、截图、确定性的回读/断言结果 |
+
+## 工具规则
+
+- Playwright MCP 和 Playwright CLI 是现场验收工具，适合即时探索和证明；它们本身不等于稳定回归。
+- `@playwright/test` 或项目已有 E2E 框架才是 Web 稳定回归的默认路径。
+- Midscene 是 AI 视觉 UI 自动化补充层，适合弱选择器、canvas、跨 frame、视觉匹配或自然语言探索。
+- `visual-ai-assist` 不能只凭 AI 断言标 PASS。写操作后必须重新读取可信结果面。
+
+## Web 写操作必需链路
+
+```text
+open -> snapshot -> fill/input -> click(submit/confirm) -> snapshot -> read/assert changed result -> screenshot -> PASS/FAIL
+```
+
+PASS 必须写明断言到的变更值，以及从页面、列表、详情、API 响应、存储记录或日志中的哪个位置回读。
+
+## 矩阵字段
+
+`web-browser` 行必须包含：
+
+- `执行面`：`web-browser`
+- `验收模式`：`instant-acceptance`、`durable-regression` 或 `visual-ai-assist`
+- `证据层级`：`browser-acceptance`、`e2e`、`visual-acceptance`、`integration` 或 `smoke`
+- `框架/命令`：MCP、Playwright CLI、`npx playwright test`、项目 E2E 命令或 Midscene 路由
+- `必需证据`：snapshot、截图、提交后断言、report/trace、console/network 记录或 Midscene 报告
+
+如果一个功能同时需要现场验收和稳定回归，拆成两条矩阵行。

package/assets/skills-zh/opentest/templates/acceptance-template.md

@@ -5,7 +5,9 @@
 - 意图:
 - 背景:
 - 执行角色:
-- 执行界面:
+- 执行面: web-browser | android-app | desktop-gui | api
+- 验收模式:
+- 证据层级:
 - 触发/输入:
 - 期望反馈位置:
 - status: pending

package/assets/skills-zh/opentest/templates/api-acceptance-template.md

@@ -0,0 +1,44 @@
+# API 验收
+
+## ACC-API-001
+
+- 执行面: api
+- 验收模式: n/a
+- 工具路线: 项目 API 命令 | pytest + httpx/requests | curl/httpie | Postman/Newman | 契约工具
+- 证据层级: contract | integration | smoke | security-review
+- base URL:
+- auth/role:
+- fixture/seed:
+- teardown:
+- 状态: pending
+
+### 请求
+
+- method:
+- path:
+- headers:
+- query:
+- body:
+
+### 期望响应
+
+- status code:
+- headers:
+- schema/source:
+- payload 断言:
+- error contract:
+
+### 回读契约
+
+- API 查询 endpoint:
+- DB/存储/日志/事件断言:
+- 幂等/retry 断言:
+- cleanup 断言:
+
+### 证据
+
+- 状态:
+- 请求/响应记录:
+- 报告路径:
+- 产物:
+- 阻塞项:

package/assets/skills-zh/opentest/templates/desktop-gui-acceptance-template.md

@@ -0,0 +1,43 @@
+# 桌面 GUI 验收
+
+## ACC-Desktop-001
+
+- 执行面: desktop-gui
+- 验收模式: n/a
+- 工具路线: 项目 GUI 自动化 | @midscene/computer | 可访问性/窗口元数据 | 脚本化人工 GUI 验收
+- 证据层级: gui-acceptance | visual-acceptance | integration | smoke
+- 目标 App/窗口:
+- 启动命令:
+- fixture/reset:
+- 状态: pending
+
+### 环境
+
+- OS/显示器/RDP:
+- 模型环境状态:
+- App 版本/build:
+- 目标进程/窗口元数据:
+
+### 步骤
+
+1.
+
+### 期望结果
+
+-
+
+### 回读契约
+
+- 持久化结果面:
+- 重开/重启检查:
+- 可访问性/窗口元数据断言:
+- 文件/配置/App 状态断言:
+
+### 证据
+
+- 状态:
+- 截图/录屏:
+- GUI 操作日志:
+- 窗口/App 元数据:
+- Midscene/computer 报告或日志:
+- 阻塞项:

package/assets/skills-zh/opentest/templates/matrix-template.md

@@ -1,13 +1,14 @@
 # 验收到测试矩阵
 
-| ID | 意图 | 覆盖维度 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 框架/命令 | 必需证据 | 缺口/阻塞 | 状态 |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| ACC-001 | 新增成功 | 新增 | 有效 fixture 实体 | 创建成功，并能在列表/详情中看到 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 新增证据、UI/API/DB 断言、使用的测试数据 | 无 | pending |
-| ACC-002 | 查询/列表/详情成功 | 查询/列表/详情 | 已 seed 的实体 | 列表、搜索/筛选、详情显示正确数据 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 查询/列表/详情证据和数据一致性检查 | 无 | pending |
-| ACC-003 | 修改成功 | 修改 | 编辑 fixture 实体 | 保存后回读仍是新值 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 修改证据和回读断言 | 无 | pending |
-| ACC-004 | 删除安全成功 | 删除 | 已存在 fixture 实体 | 删除确认/取消正确；确认删除后不可见 | high | integration + acceptance | `python -m pytest` + 真实工作流 | 删除证据、取消证据、删除后回读检查 | 无 | pending |
-| ACC-005 | 失败/边界路径可控 | 失败/边界 | 非法、空、重复、无权限或过期 fixture 数据 | 给出清晰反馈且不污染数据 | high | unit/integration/acceptance | `python -m pytest` + 验收 | 校验、权限、重复提交、过期状态证据 | 无 | pending |
-| ACC-006 | 数据一致性成立 | 数据一致性 | 新增/修改/删除闭环 | UI、API、数据库/存储、文件和日志一致 | high | integration | 项目命令或 `python -m pytest` | 跨界面一致性证据 | 无 | pending |
-| ACC-007 | 端到端 CRUD 链路可用 | 端到端 CRUD | 新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 | 完整用户链路通过并留下干净状态 | high | E2E/acceptance | 浏览器/API 工作流 | 全链路步骤、截图/日志、清理证据 | 无 | pending |
-| ACC-008 | 冒烟质量门通过 | 冒烟 | 应用启动且核心入口可访问 | 核心路由/API/CRUD 主路径不崩 | high | smoke | 项目冒烟命令或 targeted workflow | smoke_report 路径 | 无 | pending |
-| ACC-009 | pre-push 质量门通过 | pre-push | push 前 staged change | format/lint/type/unit/integration/smoke/diff 检查通过，否则阻止 push | high | pre-push | 项目命令序列 | pre_push_report 路径 | 无 | pending |
+| ID | 需求来源 | 意图 | 执行面 | 验收模式 | 覆盖维度 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 框架/命令 | 必需证据 | 缺口/阻塞 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| ACC-001 | REQ-001 / 用户故事 | Web UI 新增成功 | web-browser | instant-acceptance | 新增 | 有效 fixture 实体 | 创建成功，并能在列表/详情中看到 | high | browser-acceptance + integration | Playwright MCP / Playwright CLI + 项目命令 | 新增证据、UI/API/DB 断言、使用的测试数据 | 无 | pending |
+| ACC-002 | REQ-WEB-REG-001 / 回归需求 | Web CRUD 有稳定回归 | web-browser | durable-regression | 查询/列表/详情 + 端到端 CRUD | 已提交 E2E 测试 | 新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 可重复验证 | high | e2e | `npx playwright test` 或项目 E2E 命令 | 测试文件、trace/report、稳定 locator 断言 | 无 | pending |
+| ACC-003 | REQ-WEB-VIS-001 / 视觉风险 | Web 视觉状态可验证 | web-browser | visual-ai-assist | 视觉行为 | 弱选择器或 canvas UI | Midscene 辅助定位 UI，确定性回读证明结果 | medium | visual-acceptance | Midscene + Playwright 路由 | Midscene 报告、截图、回读断言结果 | 无 | pending |
+| ACC-004 | REQ-ANDROID-001 / 移动端流程 | Android App 新增成功 | android-app | n/a | 新增 | APK 已安装到模拟器/真机 | 任务创建成功，刷新后仍可见 | high | visual-acceptance + e2e | `android-midscene-pytest` / `python -m pytest tests_py -v` | pytest 报告、ADB 冒烟、Midscene HTML 报告、截图、logcat、`midscene_run` 日志 | 缺 ADB/APK/设备/package/模型环境变量时阻塞 | pending |
+| ACC-005 | REQ-DESKTOP-001 / 设置流程 | 桌面设置保存成功 | desktop-gui | n/a | 修改 | 桌面应用窗口已打开 | 设置保存并在重开后仍生效 | high | gui-acceptance + integration | `opentest-desktop-gui` / 项目 GUI 自动化 / `@midscene/computer` | 截图或录屏、GUI 操作日志、App/窗口元数据、确定性回读、使用 Midscene/computer 时的报告 | 缺 display/RDP/App 启动/窗口标识/模型环境变量/结果面时阻塞 | pending |
+| ACC-006 | REQ-API-001 / 契约 | API 新增成功 | api | n/a | 新增 | 合法请求 payload | 响应状态码和 payload 证明实体已创建 | high | contract + integration | `opentest-api` / 项目 API 命令 / `python -m pytest tests/api -v` | 请求/响应记录、状态码、payload/schema 断言、写后读、数据一致性、cleanup/teardown | 缺 base URL/auth/fixture/seed/teardown/依赖/schema/结果面时阻塞 | pending |
+| ACC-007 | 风险：非法和无权限输入 | 失败/边界路径可控 | api | n/a | 失败/边界 | 非法、空、重复、未登录、无权限、过期或 stale fixture 数据 | 给出清晰错误契约且不污染数据 | high | contract + security-review | `opentest-api` / 项目命令 / `python -m pytest tests/api -v` | 校验、鉴权/权限、重复/幂等、stale-state、错误 schema、敏感字段证据 | 无 | pending |
+| ACC-007A | 风险：列表契约漂移 | API 列表/搜索行为稳定 | api | n/a | 列表/过滤/排序/分页 | seeded collection 和 query params | 分页、过滤、排序、空结果符合契约 | medium | contract + integration | `opentest-api` / 项目 API 命令 | 请求/响应记录、schema 断言、分页元数据、fixture 隔离 | 未改列表 endpoint 时不适用 | pending |
+| ACC-008 | 质量门需求 | 冒烟质量门通过 | web-browser | instant-acceptance | 冒烟 | 应用启动且核心入口可访问 | 核心路由/API/CRUD 主路径不崩 | high | smoke | 项目冒烟命令或 targeted workflow | smoke_report 路径 | 无 | pending |
+| ACC-009 | 交付门禁需求 | pre-push 质量门通过 | api | n/a | pre-push | push 前 staged change | format/lint/type/unit/integration/smoke/diff 检查通过，否则阻止 push | high | pre-push | 项目命令序列 | pre_push_report 路径 | 无 | pending |

package/assets/skills-zh/opentest/templates/plan-template.md

@@ -24,5 +24,5 @@
 
 ## 证据计划
 
-| 证据层级 | 适用场景 | 命令或执行面 | 产物路径 | 状态 |
-| --- | --- | --- | --- | --- |
+| 执行面 | 验收模式 | 证据层级 | 适用场景 | 命令/工具 | 产物路径 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |

package/assets/skills-zh/opentest/templates/web-acceptance-template.md

@@ -0,0 +1,27 @@
+# Web 浏览器验收
+
+- ACC ID:
+- 执行面: web-browser
+- 验收模式: instant-acceptance | durable-regression | visual-ai-assist
+- 工具路由: Playwright MCP | Playwright CLI | @playwright/test | Midscene
+- 页面/路由:
+- 执行角色:
+- fixture:
+
+## 操作步骤
+
+1. open:
+2. snapshot:
+3. fill/input:
+4. submit/confirm:
+5. submit 后 snapshot:
+6. read/assert changed result:
+7. screenshot/report:
+
+## 证据
+
+- status:
+- 已断言的变更结果:
+- 产物路径:
+- console/network 记录:
+- blocked 原因:

package/assets/skills-zh/opentest-accept/SKILL.md

@@ -11,13 +11,22 @@ description: "OpenTest 阶段 4：执行自然语言验收、MCP 验收或真实
 
 - `opentest/references/acceptance-evidence.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-surfaces.md`
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/references/api-testing.md`
 - `opentest/templates/acceptance-template.md`
+- `opentest/templates/desktop-gui-acceptance-template.md`
+- `opentest/templates/api-acceptance-template.md`
 
 ## 步骤
 
 1. 读取矩阵、fixtures 和 `docs/opentest/acceptance/`。
-2. 前端交互优先用 Chrome DevTools MCP 执行真实页面验收。
-3. API/后台链路使用项目命令或直接 API 检查。
-4. CRUD/数据变更执行 workflow 引用中的完整链路。
-5. 记录反馈位置/形态、产物、blocked evidence 和对应 ACC ID。
-6. 更新验收记录并运行 `bash "$OPENTEST_GUARD" accept --apply`。
+2. 根据矩阵里的执行面选择验收工具。
+3. `web-browser` 使用 `opentest-web-browser`：优先 Playwright MCP，失败时降级 Playwright CLI；稳定回归证据用 `@playwright/test`；视觉补充才用 Midscene。
+4. `android-app` 已安装 `android-midscene-pytest` 时使用它；入口是 `python -m pytest tests_py -v`，收集 pytest、ADB 冒烟、Midscene HTML、截图、logcat、设备/App 元数据和可用的 `midscene_run` 日志。缺 ADB、模拟器/真机、APK、package 或模型凭据时标为 blocked。
+5. `desktop-gui` 使用 `opentest-desktop-gui`：优先项目 GUI 自动化，视觉桌面/原生/RDP 流程用 `@midscene/computer`，并收集截图或录屏、GUI 操作日志、窗口/App 元数据和确定性回读。缺 display/RDP、App 启动、目标窗口标识、模型凭据或稳定结果面时标为 blocked。
+6. `api` 使用 `opentest-api`：优先项目 API 命令；否则用 `pytest` + `httpx`/`requests`、schema 校验、fixtures、写后读和 cleanup/teardown 证据。
+7. CRUD/数据变更执行 workflow 引用中的完整链路。
+8. 记录反馈位置/形态、产物、blocked evidence 和对应 ACC ID。
+9. 更新验收记录并运行 `bash "$OPENTEST_GUARD" accept --apply`。

package/assets/skills-zh/opentest-api/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: opentest-api
+description: "OpenTest 的 API 执行面适配器。用于 HTTP API、RPC、后端工作流、契约、鉴权、数据一致性、幂等和集成证据的规划、编写、运行与验收。"
+---
+
+# OpenTest API
+
+用于矩阵中的 `api` 执行面。
+
+## 必读引用
+
+- `opentest/references/api-testing.md`
+- `opentest/templates/api-acceptance-template.md`
+
+## 路由
+
+1. 仓库已有明确、可重复的 API/integration 测试命令时，优先使用项目命令。
+2. 没有项目命令时，默认用 `pytest` 编排，`httpx` 或 `requests` 发请求，`jsonschema` 或项目已有 Pydantic/DTO 模型做 schema 校验，fixtures 管 seed/teardown。
+3. 有 OpenAPI、protobuf 或既有契约文档时，把它们作为契约来源；否则在验收用例里写清 expected status、headers、response schema 和业务 payload。
+4. 第三方 API 默认 mock/stub；只有需求明确要求真实外部依赖时才打 live 服务。
+5. 缺 base URL、auth token、fixture 数据、seed/teardown、依赖服务或稳定回读结果面时，记录 `blocked`。
+
+## 证据契约
+
+PASS 必须包含请求/响应记录、状态码、响应 payload 或 schema 断言、适用时的鉴权/权限结果、数据一致性/写后读证据，以及 cleanup 或 teardown 证明。API 冒烟只证明存活；对高风险变更，它不能替代契约、边界、权限或数据一致性证据。

package/assets/skills-zh/opentest-author/SKILL.md

@@ -11,14 +11,16 @@ description: "OpenTest 阶段 2：根据矩阵补齐测试资产、fixtures 和
 
 - `opentest/references/opentest-driven-development.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-asset-layout.md`
 - `opentest/templates/fixtures-template.md`
 - `opentest/templates/acceptance-template.md`
 
 ## 步骤
 
 1. 读取 `.opentest.yaml` 的 `matrix` 和 `fixtures`。
-2. 代码级证据优先用项目框架；没有框架时默认使用 pytest，测试放入 `tests/` 并可用 `python -m pytest` 运行。
-3. 创建/更新 fixtures、seed、teardown、用户、角色、实体、文件/图片和断言界面。
-4. CRUD/数据变更必须补全链路：新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 -> 确认消失 -> 清理。
-5. 记录 gap/blocker 的原因和风险。
-6. 写入 `.opentest.yaml` 的 `fixtures`、`acceptance`，再运行 `bash "$OPENTEST_GUARD" author --apply`。
+2. 保留每条矩阵行的需求来源和期望行为。不要围绕当前实现命名、组件内部结构或已有测试文件重写验收用例。
+3. 资产必须放入 `test-asset-layout.md` 的固定目录；没有项目框架时默认使用 pytest + `tests/`。实现缺失只表示证据 pending。
+4. 创建/更新 fixtures、seed、teardown、用户、角色、实体、文件/图片和断言界面。
+5. CRUD/数据变更必须补全链路：新增 -> 列表 -> 详情 -> 修改 -> 回读 -> 删除 -> 确认消失 -> 清理。
+6. 记录 gap/blocker 的原因和风险。
+7. 写入 `.opentest.yaml` 的 `fixtures`、`acceptance`，再运行 `bash "$OPENTEST_GUARD" author --apply`。

package/assets/skills-zh/opentest-desktop-gui/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: opentest-desktop-gui
+description: "OpenTest 的桌面 GUI 执行面适配器。用于原生桌面、Electron、Tauri、Windows、macOS、Linux 或 RDP 工作流验收，并在项目 GUI 自动化、@midscene/computer、可访问性元数据、截图和脚本化人工验收之间选择路线。"
+---
+
+# OpenTest Desktop GUI
+
+用于矩阵中的 `desktop-gui` 执行面。
+
+## 必读引用
+
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/templates/desktop-gui-acceptance-template.md`
+
+## 路由
+
+1. 如果仓库已有明确、可重复的 GUI 自动化命令，优先使用项目命令。
+2. 对视觉桌面自动化、弱选择器、原生控件、跨窗口流程，或没有确定性项目自动化的远程 Windows RDP，可使用 `@midscene/computer`。
+3. Electron 或 Tauri 如果能暴露浏览器上下文，DOM 可验证流程优先走 `web-browser` 或 Playwright；只有原生外壳、托盘、文件选择器、菜单、系统弹窗或多窗口行为才走 `desktop-gui`。
+4. 缺模型凭据、桌面访问、显示器/RDP、App 启动命令或稳定结果面时，记录 `blocked`，不得标 PASS。
+
+## 证据契约
+
+PASS 必须包含执行步骤、截图或录屏、窗口/App 元数据、GUI 操作日志，以及写操作后的确定性回读结果。`@midscene/computer` 断言只能作为视觉辅助，不能替代持久化结果检查，例如重开设置页、读取文件/配置值、查询 App 状态面，或重启后确认窗口状态。

package/assets/skills-zh/opentest-plan/SKILL.md

@@ -5,23 +5,29 @@ description: "OpenTest 阶段 1：分析变更、风险和项目事实，生成
 
 # OpenTest Plan
 
-在实现前生成 `docs/opentest/plans/`、`docs/opentest/matrices/` 和测试数据计划。
+在实现前生成 plan、matrix 和测试数据计划。
 
 ## 必读引用
 
 - `opentest/references/codex-harness-coverage-heuristics.md`
 - `opentest/references/matrix-format.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-asset-layout.md`
+- `opentest/references/test-surfaces.md`
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/references/api-testing.md`
 
 ## 步骤
 
-1. 读取项目规则、需求/设计/diff、现有命令和 detect 输出。
-2. 判断风险、适用覆盖面、测试数据，以及代码测试使用项目框架还是默认 `pytest`。
+1. 读取规则、需求/设计/请求/diff、现有命令和 detect 输出。
+2. 把需求、流程、业务规则和风险当成验收来源；读取当前代码只用于发现项目事实，例如命令、路由、框架、fixtures 和 helper。
 3. 数据写入、API、表单、文件或有状态流程默认套用 CRUD 基线和测试数据要求。
-4. 生成矩阵，包含覆盖维度、框架/命令、必需证据、缺口/阻塞和状态。
-5. 写入 `.opentest.yaml` 的 `plan`、`matrix`、`fixtures`。
-6. 如存在 handoff，同步 plan/matrix/fixtures 路径，然后运行 `bash "$OPENTEST_GUARD" plan --apply`。
+4. 分开判定执行面和证据层级。执行面只能是 `web-browser`、`android-app`、`desktop-gui` 或 `api`；Web 行必须写验收模式，原生桌面行用 `opentest-desktop-gui`，API 行用 `opentest-api`。
+5. 生成需求先行矩阵，包含来源、行为、执行面、验收模式、证据层级、命令/工具、证据、缺口/阻塞、状态和固定资产目录。
+6. 写入 `.opentest.yaml` 的 `plan`、`matrix`、`fixtures`。
+7. 如存在 handoff，同步 plan/matrix/fixtures 路径，然后运行 `bash "$OPENTEST_GUARD" plan --apply`。
 
 ## 质量门
 
-每个适用行为、失败路径、边界和风险面都要有证据或明确 gap/blocker。CRUD 基线和测试数据默认必需；不适用时必须在矩阵写明原因。
+每个行为、失败路径、边界和风险面都要有证据或 gap/blocker。每行必须引用需求来源，并包含执行面和证据层级；Web 行还要有验收模式。不得把 unit/component/integration/contract/smoke 当执行面。不得因为当前代码没有对应函数、组件、API 或测试文件就删除或缩小验收。CRUD 基线和测试数据默认必需；不适用时在矩阵写明原因。

package/assets/skills-zh/opentest-run/SKILL.md

@@ -11,6 +11,11 @@ description: "OpenTest 阶段 3：按 targeted、fast、full、ci-like 或 pre-p
 
 - `opentest/references/command-routing.md`
 - `opentest/references/complete-testing-workflow.md`
+- `opentest/references/test-asset-layout.md`
+- `opentest/references/test-surfaces.md`
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/references/api-testing.md`
 
 ## 模式
 
@@ -22,10 +27,11 @@ description: "OpenTest 阶段 3：按 targeted、fast、full、ci-like 或 pre-p
 
 ## 步骤
 
-1. 读取 `run_mode`、矩阵、fixtures 和必需证据。
-2. 优先使用项目命令；没有代码级命令时用 `python -m pytest`。
-3. 覆盖率优先用 `python -m pytest --cov=. --cov-report=term-missing`。
-4. 除非矩阵写明不适用，否则必须有冒烟证据。
-5. `pre-push` 运行或记录 format/check、lint、type、unit、targeted integration、smoke、`git diff --check`。
-6. 写入 `run_report`，必要时写入 `coverage_report`、`smoke_report`、`pre_push_report`。
-7. 运行 `bash "$OPENTEST_GUARD" run --apply`。
+1. 读取 `run_mode`、矩阵、fixtures、必需证据和固定资产目录。
+2. 根据矩阵执行面和验收模式选择命令/工具：`web-browser` 走 MCP/CLI 或 `npx playwright test`，`android-app` 走 `python -m pytest tests_py -v`；只有模型环境变量齐全或排查 Midscene 层时才跑 `npm run test:android`；`desktop-gui` 走 `opentest-desktop-gui`、项目 GUI 自动化或 `@midscene/computer`，`api` 走 `opentest-api`、项目 API 命令或 `python -m pytest tests/api -v`。
+3. 优先使用项目命令；没有代码级命令时用 `python -m pytest`。
+4. 覆盖率优先用 `python -m pytest --cov=. --cov-report=term-missing`。
+5. 除非矩阵写明不适用，否则必须有冒烟证据。
+6. `pre-push` 运行或记录 format/check、lint、type、unit、targeted integration、smoke、`git diff --check`。
+7. 写入 `run_report`，必要时写入 `coverage_report`、`smoke_report`、`pre_push_report`。
+8. 运行 `bash "$OPENTEST_GUARD" run --apply`。

package/assets/skills-zh/opentest-web-browser/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: opentest-web-browser
+description: "OpenTest 的 Web 浏览器执行面适配器。用于浏览器页面验收、Web 回归测试规划，以及在 Playwright MCP、Playwright CLI、@playwright/test 和 Midscene 之间选择工具。"
+---
+
+# OpenTest Web Browser
+
+用于矩阵中 `web-browser` 执行面的用例。
+
+## 必读引用
+
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/web-acceptance-template.md`
+
+## 步骤
+
+1. 先判定 `验收模式`：`instant-acceptance`、`durable-regression` 或 `visual-ai-assist`。
+2. `instant-acceptance` 优先用 Playwright MCP；浏览器 MCP 不可用或不稳定时用 Playwright CLI。
+3. `durable-regression` 写入或运行 `@playwright/test`，或项目已有 E2E 框架。
+4. 只有视觉定位、弱选择器、canvas、跨 frame 等 selector 难以证明的界面，才使用 Midscene。
+5. 写操作必须执行完整链路：open -> snapshot -> fill/input -> submit -> snapshot -> read/assert changed result -> screenshot -> PASS/FAIL。
+
+## 质量门
+
+MCP 或 Playwright CLI 证据只能证明本次现场验收，不等于稳定回归。没有提交到仓库的可重复测试、命令和报告路径时，不得把它当成 durable regression。Midscene 不能替代写后读断言。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pzy560117/opentest",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "OpenTest quality evidence lifecycle skills for Codex",
   "keywords": [
     "opentest",