@pzy560117/opentest 0.1.10 → 0.1.11

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

@@ -0,0 +1,27 @@
+# Web Browser Acceptance
+
+- ACC ID:
+- execution surface: web-browser
+- acceptance mode: instant-acceptance | durable-regression | visual-ai-assist
+- tool route: Playwright MCP | Playwright CLI | @playwright/test | Midscene
+- page/route:
+- actor/role:
+- fixture:
+
+## Steps
+
+1. open:
+2. snapshot:
+3. fill/input:
+4. submit/confirm:
+5. snapshot after submit:
+6. read/assert changed result:
+7. screenshot/report:
+
+## Evidence
+
+- status:
+- changed result asserted:
+- artifact paths:
+- console/network notes:
+- blocked reason:

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

@@ -5,19 +5,28 @@ description: "OpenTest phase 4: execute natural language, MCP, or real workflow
 
 # OpenTest Accept
 
-Execute required acceptance items and write PASS, FAIL, or blocked evidence back to cases and the matrix.
+Write PASS, FAIL, or blocked evidence to cases and matrix.
 
 ## Required references
 
 - `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`
 
 ## Steps
 
 1. Read the matrix, fixtures, and `docs/opentest/acceptance/`.
-2. For frontend interactions, prefer Chrome DevTools MCP and observe the real rendered UI.
-3. For API/backend workflows, use project commands or direct API checks.
-4. For CRUD/data changes, execute the full chain from the workflow reference.
-5. Record feedback location/shape, artifacts, blocked evidence, and matching ACC IDs.
-6. Update acceptance records and run `bash "$OPENTEST_GUARD" accept --apply`.
+2. Select the acceptance tool from the matrix execution surface.
+3. For `web-browser`, use `opentest-web-browser`: Playwright MCP/CLI, `@playwright/test` for durable regression, Midscene only for visual assist.
+4. For `android-app`, use `android-midscene-pytest`: `python -m pytest tests_py -v`, ADB smoke, Midscene HTML, logcat, and `midscene_run`; block missing prerequisites.
+5. For `desktop-gui`, use `opentest-desktop-gui`: project GUI automation or `@midscene/computer`, screenshot/recording, metadata, and read-back.
+6. For `api`, use `opentest-api`: project API command or `pytest` with `httpx`/`requests`, schema checks, fixtures, read-after-write, and cleanup/teardown.
+7. For CRUD/data changes, execute the full chain from the workflow reference.
+8. Record feedback location/shape, artifacts, blocked evidence, and matching ACC IDs.
+9. Update acceptance records and run `bash "$OPENTEST_GUARD" accept --apply`.

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

@@ -0,0 +1,25 @@
+---
+name: opentest-api
+description: "OpenTest API execution surface adapter. Use when planning, authoring, running, or accepting HTTP API, RPC, backend workflow, contract, auth, data consistency, idempotency, and integration evidence."
+---
+
+# OpenTest API
+
+Use this adapter for `api` matrix rows.
+
+## Required references
+
+- `opentest/references/api-testing.md`
+- `opentest/templates/api-acceptance-template.md`
+
+## Route
+
+1. Prefer the repository's existing API/integration test command when it is explicit and repeatable.
+2. If no project command exists, default to `pytest` with `httpx` or `requests`, schema checks via `jsonschema` or existing Pydantic/DTO models, and fixtures for seed/teardown.
+3. Use OpenAPI, protobuf, or existing contract docs as the contract source when present; otherwise write the expected status, headers, response schema, and business payload in the acceptance case.
+4. Mock or stub third-party APIs unless the requirement explicitly needs a live external dependency.
+5. Mark blocked when base URL, auth token, fixture data, seed/teardown, dependency service, or stable read-back surface is missing.
+
+## Evidence Contract
+
+PASS requires request/response records, status code, response payload or schema assertion, auth/permission result when applicable, data consistency/read-after-write evidence, and cleanup or teardown proof. API smoke only proves liveness; it does not replace contract, boundary, permission, or data consistency evidence for high-risk changes.

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

@@ -11,6 +11,7 @@ Turn the matrix into executable tests, fixtures, seed/teardown notes, and accept
 
 - `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`
 
@@ -18,7 +19,7 @@ Turn the matrix into executable tests, fixtures, seed/teardown notes, and accept
 
 1. Read `matrix` and `fixtures` from `.opentest.yaml`.
 2. Preserve each row's requirement source and expected behavior. Do not rewrite acceptance cases around current implementation names, component internals, or existing test files.
-3. For code evidence, use the project framework; if none exists, default to pytest with tests under `tests/` runnable by `python -m pytest`. Missing implementation means evidence stays pending; it does not remove the requirement acceptance case.
+3. Place assets in the fixed layout from `test-asset-layout.md`; default to pytest under `tests/` when no project framework exists. Missing implementation means evidence stays pending.
 4. Create/update fixtures, seed, teardown, users, roles, entities, files/images, and assertion surfaces.
 5. For CRUD/data changes, author the full acceptance flow: create -> list -> detail -> update -> read back -> delete -> confirm absence -> teardown.
 6. Record any gap/blocker with reason and risk.

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

@@ -0,0 +1,24 @@
+---
+name: opentest-desktop-gui
+description: "OpenTest desktop GUI execution surface adapter. Use when planning, authoring, running, or accepting native desktop, Electron, Tauri, Windows, macOS, Linux, or RDP workflows and deciding between project GUI automation, @midscene/computer, accessibility metadata, screenshots, and scripted manual acceptance."
+---
+
+# OpenTest Desktop GUI
+
+Use this adapter for `desktop-gui` matrix rows.
+
+## Required references
+
+- `opentest/references/desktop-gui-testing.md`
+- `opentest/templates/desktop-gui-acceptance-template.md`
+
+## Route
+
+1. Prefer the repository's existing GUI automation command when it is explicit and repeatable.
+2. Use `@midscene/computer` for visual desktop automation, weak selectors, native controls, cross-window flows, or remote Windows RDP when deterministic project automation is unavailable.
+3. For Electron or Tauri apps that expose a browser context, prefer `web-browser` or Playwright routes for DOM-verifiable flows, and use `desktop-gui` only for native shell, tray, file picker, menu, OS dialog, or multi-window behavior.
+4. If model credentials, desktop access, display/RDP availability, app launch command, or stable result surface is missing, record `blocked` instead of PASS.
+
+## Evidence Contract
+
+PASS requires the executed steps, screenshot or screen recording, window/app metadata, GUI action log, and a deterministic read-back result after writes. `@midscene/computer` assertions are visual assistance; they must not replace persisted-result checks such as reopening a settings screen, reading a file/config value, querying an app state surface, or confirming the expected window state after restart.

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

@@ -1,27 +1,33 @@
 ---
 name: opentest-plan
-description: "OpenTest phase 1: analyze the change, risks, project facts, and create a test strategy plus acceptance-to-test matrix."
+description: "OpenTest phase 1: create test strategy and acceptance matrix."
 ---
 
 # OpenTest Plan
 
-Create `docs/opentest/plans/`, `docs/opentest/matrices/`, and a fixtures plan before implementation.
+Create plan, matrix, and fixtures before implementation.
 
 ## Required references
 
 - `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`
 
 ## Steps
 
-1. Read project rules, requirements/design/user request/diff, existing commands, and detection output.
-2. Treat requirements, design, user workflows, business rules, and risk notes as acceptance sources. Inspect current code only for project facts such as commands, routes, test framework, fixtures, or reusable helpers.
-3. Apply the CRUD baseline and test data requirements from the workflow reference for data-writing/API/form/file/stateful changes.
-4. Produce a requirement-first matrix with requirement source, user-observable expected behavior, coverage dimension, framework/command, required evidence, gap/blocker, and status.
-5. Write `.opentest.yaml` fields: `plan`, `matrix`, `fixtures`.
-6. Update handoff if present, then run `bash "$OPENTEST_GUARD" plan --apply`.
+1. Read rules, requirements/diff, commands, and detection output.
+2. Treat requirements and risks as sources; inspect current code only for project facts.
+3. Apply CRUD baseline and test data rules for data-writing/API/form/file/stateful changes.
+4. Classify execution surface and evidence layer separately: `web-browser`, `android-app`, `desktop-gui`, or `api`; use web modes, `opentest-desktop-gui`, and `opentest-api` where applicable.
+5. Produce a requirement-first matrix with source, behavior, surface, mode, evidence, command, gap/blocker, status, and fixed layout.
+6. Write `.opentest.yaml` fields: `plan`, `matrix`, `fixtures`.
+7. Update handoff if present, then run `bash "$OPENTEST_GUARD" plan --apply`.
 
 ## Gate
 
-Every applicable behavior, failure path, boundary, and risk surface needs evidence or a written gap/blocker. Every matrix row must cite a requirement source. Do not drop or narrow acceptance because current code has no matching function, component, API, or test file. CRUD baseline and test data are default requirements unless the matrix says why they are not applicable.
+Every behavior, failure path, boundary, and risk needs evidence or gap/blocker. Every row cites a source and includes surface plus evidence layer; web rows include acceptance mode. Do not use unit/component/integration/contract/smoke as the execution surface. Do not drop or narrow acceptance because current code has no matching file.

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

@@ -5,12 +5,17 @@ description: "OpenTest phase 3: run project verification commands in targeted, f
 
 # OpenTest Run
 
-Run matrix-driven commands and write evidence reports under `docs/opentest/runs/`.
+Run matrix-driven commands and write reports under `docs/opentest/runs/`.
 
 ## Required references
 
 - `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`
 
 ## Modes
 
@@ -22,10 +27,11 @@ Run matrix-driven commands and write evidence reports under `docs/opentest/runs/
 
 ## Steps
 
-1. Read `run_mode`, matrix, fixtures, and required evidence.
-2. Prefer explicit project commands; otherwise use `python -m pytest` for code-level tests.
-3. For coverage, prefer `python -m pytest --cov=. --cov-report=term-missing`.
-4. Smoke evidence is required unless the matrix says not applicable.
-5. For `pre-push`, run or record format/check, lint, type, unit, targeted integration, smoke, and `git diff --check`.
-6. Write `run_report`, plus `coverage_report`, `smoke_report`, or `pre_push_report` when produced/required.
-7. Run `bash "$OPENTEST_GUARD" run --apply`.
+1. Read `run_mode`, matrix, fixtures, required evidence, and fixed asset layout.
+2. Choose by matrix execution surface: MCP/CLI or `npx playwright test` for `web-browser`; `python -m pytest tests_py -v` for `android-app`, with `npm run test:android` only when model env is ready or debugging Midscene; `opentest-desktop-gui` for `desktop-gui`; `opentest-api` or `python -m pytest tests/api -v` for `api`.
+3. Prefer explicit project commands; otherwise use `python -m pytest` for code-level tests.
+4. For coverage, prefer `python -m pytest --cov=. --cov-report=term-missing`.
+5. Smoke evidence is required unless the matrix says not applicable.
+6. For `pre-push`, run or record format/check, lint, type, unit, targeted integration, smoke, and `git diff --check`.
+7. Write `run_report`, `coverage_report`, `smoke_report`, or `pre_push_report` when required.
+8. Run `bash "$OPENTEST_GUARD" run --apply`.

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

@@ -0,0 +1,26 @@
+---
+name: opentest-web-browser
+description: "OpenTest web-browser execution surface adapter. Use when planning, authoring, running, or accepting browser-rendered web workflows and deciding between Playwright MCP, Playwright CLI, @playwright/test, and Midscene."
+---
+
+# OpenTest Web Browser
+
+Use this adapter for `web-browser` matrix rows.
+
+## Required references
+
+- `opentest/references/web-browser-testing.md`
+- `opentest/references/complete-testing-workflow.md`
+- `opentest/templates/web-acceptance-template.md`
+
+## Steps
+
+1. Decide `acceptance_mode`: `instant-acceptance`, `durable-regression`, or `visual-ai-assist`.
+2. For `instant-acceptance`, use Playwright MCP first; if browser MCP is unavailable or unstable, use Playwright CLI.
+3. For `durable-regression`, write or run `@playwright/test` or the repository's existing E2E framework.
+4. Use Midscene only for visual, weak-selector, canvas, cross-frame, or other UI surfaces selectors cannot prove well.
+5. For writes, run the full chain: open -> snapshot -> fill/input -> submit -> snapshot -> read/assert changed result -> screenshot -> PASS/FAIL.
+
+## Gate
+
+MCP or Playwright CLI evidence proves this acceptance run only. Do not count it as durable regression unless the repository has a committed repeatable test, command, and report path. Midscene must not replace read-after-write assertions.

package/assets/skills-zh/opentest/references/api-testing.md

@@ -0,0 +1,77 @@
+# API 测试
+
+用于 `api` 执行面的矩阵行。
+
+## 默认架构
+
+优先使用仓库已有 API 测试框架。项目没有明确 API 测试命令时，默认采用：
+
+```text
+pytest
+  -> httpx 或 requests client
+  -> pytest fixtures 管 seed/teardown
+  -> jsonschema 或项目已有 Pydantic/DTO 模型做契约断言
+  -> 可选 DB/存储/日志回读
+  -> pytest report 或 JUnit XML
+```
+
+依赖需要隔离时，用 Docker Compose、testcontainers 或仓库已有本地服务启动方式。第三方 API 默认 mock/stub；打 live 外部服务必须有明确需求和记录的风险说明。
+
+稳定 API 资产放入 `opentest/references/test-asset-layout.md` 约定的 `tests/api/`：client 放 `tests/api/clients/`，fixtures 放 `tests/api/fixtures/`，schemas 放 `tests/api/schemas/`，可重复入口使用 `scripts/opentest-run-api.ps1` 或仓库等价命令。
+
+## 证据层级
+
+| 层级 | 证明内容 | 常见命令/工具 |
+| --- | --- | --- |
+| contract | 状态码、headers、响应字段、schema、错误形态 | 项目 contract tests、`pytest`、OpenAPI 检查 |
+| integration | API handler、service、数据库/存储、队列/日志副作用 | 项目 integration 命令、`pytest`、本地服务 |
+| smoke | base URL 和关键 endpoint 存活 | 项目 smoke 命令、小型 `pytest`/curl 脚本 |
+| security-review | 鉴权、授权、敏感字段泄漏、注入风险 | 定向测试 + review 记录 |
+
+## 必需 API 用例
+
+API 变更应按适用性写入矩阵：
+
+- 主路径：期望状态码、payload、headers 和业务状态
+- 校验失败：非法、空、边界、格式错误、不支持字段
+- 鉴权和权限：未登录、token 过期、角色错误、对象级授权
+- 未找到和过期状态：资源不存在、已删除资源、stale version
+- 冲突和幂等：重复创建、重复提交、带 idempotency key 的 retry、并发修改
+- 适用时的限流或节流
+- 列表 endpoint 变更时的分页、过滤、排序和空结果
+- 数据一致性：响应、DB/存储、事件、队列消息、文件或日志
+- teardown/cleanup：创建资源已删除，或隔离 fixture namespace 已重置
+
+## 契约来源
+
+契约来源优先级：
+
+1. 仓库提交的 OpenAPI/protobuf/schema 文件。
+2. 既有 request/response DTO、Pydantic model、serializer 或 typed client。
+3. 明确写出字段和错误的需求/设计文档。
+4. 验收用例中手写 schema。
+
+当当前实现行为与需求冲突时，不得只按实现反推契约。
+
+## 阻塞规则
+
+缺少任一必需前置条件时记录 `blocked`：
+
+- base URL 或服务启动命令
+- auth token、角色或测试用户
+- fixture seed/teardown 路径
+- 依赖服务、数据库、队列或 mock server
+- 稳定契约来源或期望 schema
+- 确定性写后读结果面
+
+不得只凭 2xx 响应把 API 验收标为 PASS。写操作必须包含可信结果面的写后读证据，例如 API 查询 endpoint、DB/存储记录、队列/事件/日志，或另一个项目自有状态面。
+
+## 矩阵要求
+
+`api` 行必须包含：
+
+- `执行面`：`api`
+- `验收模式`：`n/a`
+- `证据层级`：`contract`、`integration`、`smoke` 或 `security-review`
+- `框架/命令`：项目 API 命令、`python -m pytest tests/api -v`、curl/httpie 脚本、项目已使用时的 Postman/Newman，或契约工具
+- `必需证据`：请求/响应记录、状态码、payload/schema 断言、适用时的鉴权/权限断言、写后读/数据一致性，以及 cleanup/teardown 证明

package/assets/skills-zh/opentest/references/codex-harness-coverage-heuristics.md

@@ -13,6 +13,9 @@ OpenTest 应根据变更类型、风险和项目事实选择适用覆盖面。
 - `tdd-workflow`
 - `e2e-runner`
 - `browser-e2e-testing`
+- `android-midscene-pytest`
+- `opentest-desktop-gui`
+- `opentest-api`
 - `verification-loop`
 - `code-reviewer`
 - `speckit-checklist`
@@ -28,6 +31,19 @@ OpenTest 应根据变更类型、风险和项目事实选择适用覆盖面。
 | 权限、支付、安全、数据写入、跨页面闭环 | high-risk 验收或 E2E 证据 |
 | 文案、配置、小范围无行为变更 | targeted review 或轻量证据 |
 
+## 执行面选择
+
+执行面和证据层级必须分开选择：
+
+| 执行面 | 默认路由 |
+| --- | --- |
+| `web-browser` | Chrome DevTools MCP、Playwright CLI 或浏览器验收 |
+| `android-app` | 已安装时使用 `android-midscene-pytest`；`python -m pytest tests_py -v` 通过 ADB 驱动 Midscene Android |
+| `desktop-gui` | `opentest-desktop-gui`；优先项目 GUI 自动化，视觉/原生/RDP GUI 流程用 `@midscene/computer`，无自动化时才用脚本化人工 GUI 验收 |
+| `api` | `opentest-api`；优先项目 API/integration 命令，否则用 `pytest` + `httpx`/`requests`、schema 校验、fixtures、写后读和 cleanup/teardown |
+
+不得把 unit、component、integration、contract、smoke 或 security review 这类代码检查归类成执行面；它们只能作为证据层级。
+
 ## 前端验收维度
 
 前端或真实链路验收可从以下维度中选择适用项，不要求每次全部覆盖：
@@ -74,7 +90,7 @@ OpenTest plan 阶段默认检查以下问题；适用则进入矩阵，不适用
 | ACC-001 | 用户保存后看到成功反馈 | medium | UI 验收 | pending |
 ```
 
-只有当风险或变更类型需要时，才增加覆盖维度、命令、证据路径和阻塞原因列。
+当矩阵需要驱动验收执行或风险要求时，再增加执行面、证据层级、命令/工具、证据路径和阻塞原因列。
 
 ## 质量门启发
 

package/assets/skills-zh/opentest/references/complete-testing-workflow.md

@@ -14,6 +14,27 @@ plan -> matrix -> fixtures -> tests -> run -> accept -> smoke -> pre-push -> ver
 
 unit、component、integration、contract、E2E、smoke、browser acceptance 都是证据层级。它们描述实现期间或实现后如何证明需求，不能决定需求是什么。如果代码还没出现，保留验收用例，并把依赖代码的证据标成 pending 或 blocked 且写明原因。
 
+## 执行面
+
+每条矩阵行必须同时写执行面和证据层级。执行面表示需求从哪里被实际操作；证据层级表示如何证明结果。
+
+编写测试前必须先按 `opentest/references/test-asset-layout.md` 选定固定资产目录。默认使用方案 B 的标准测试框架骨架；一次性脚本只能用于明确的非稳定验收或 blocked 排查。
+
+主执行面只有：
+
+- `web-browser`：浏览器渲染页面和 Web App
+- `android-app`：模拟器或真机上的 Android APK/App GUI
+- `desktop-gui`：原生桌面 GUI、Electron、Tauri 或类似 App UI
+- `api`：HTTP API、RPC、后端工作流、契约或服务端点
+
+不得把 unit、component、integration、contract、smoke 或 security review 当成执行面；它们是证据层级或运行门禁。如果存在 Android GUI 需求，已安装 `android-midscene-pytest` 时用它执行验收，并要求 pytest/Midscene/截图/logcat 证据。如果存在原生桌面 GUI 行为，用 `opentest-desktop-gui` 执行验收，并要求项目 GUI 自动化或 `@midscene/computer` 证据，加上截图、GUI 操作日志、窗口/App 元数据和确定性回读。如果存在 API 行为，用 `opentest-api` 执行验收，并按适用性要求契约、状态码、payload/schema、鉴权/权限、写后读和 cleanup/teardown 证据。
+
+`web-browser` 必须按 `opentest/references/web-browser-testing.md` 选择验收模式。MCP 和 Playwright CLI 是现场验收路径；稳定回归必须有已提交、可重复运行的测试，例如 `@playwright/test`。
+
+`desktop-gui` 使用 `opentest/references/desktop-gui-testing.md`。Electron/Tauri 的 DOM 可验证流程可以保留在 `web-browser`；原生外壳、托盘、文件选择器、菜单、系统弹窗、安装器、更新器、RDP 和多窗口行为保留在 `desktop-gui`。
+
+`api` 使用 `opentest/references/api-testing.md`。优先项目 API/integration 命令；没有项目命令时，用 `pytest` + `httpx` 或 `requests`、schema 校验、fixtures 和确定性回读。
+
 ## 测试数据
 
 变更涉及数据、文件、角色、权限、API 或有状态流程时，创建 `docs/opentest/fixtures/`。

package/assets/skills-zh/opentest/references/desktop-gui-testing.md

@@ -0,0 +1,52 @@
+# 桌面 GUI 测试
+
+用于 `desktop-gui` 执行面的矩阵行。
+
+稳定桌面 GUI 资产遵循 `opentest/references/test-asset-layout.md`：脚本放 `tests/desktop/scripts/`，Midscene 资产放 `tests/desktop/midscene/`，元数据采集放 `tests/desktop/metadata/`，可重复入口使用 `scripts/opentest-run-desktop.ps1` 或项目 GUI 命令。
+
+## 工具路线
+
+| 路线 | 适用场景 | 必需证据 |
+| --- | --- | --- |
+| 项目 GUI 自动化 | 仓库已有可重复的桌面自动化命令 | 命令、报告/日志、截图或录屏、操作后回读 |
+| `@midscene/computer` | 原生桌面控件、弱选择器、视觉流程、多窗口流程，或 Windows RDP 需要 AI 视觉辅助 | Midscene/computer 运行日志、截图、模型环境状态、窗口/App 元数据、确定性回读 |
+| 可访问性/窗口元数据 | 原生控件能暴露稳定可访问性树、标题、进程、窗口句柄或菜单状态 | 元数据 dump、操作日志、期望状态断言 |
+| 脚本化人工 GUI 验收 | 没有可靠自动化且验收是一次性的 | 精确步骤、截图、窗口/App 元数据、观察结果、阻塞/风险说明 |
+
+## Midscene 桌面路线
+
+`@midscene/computer` 是 Midscene 的桌面自动化包，可控制本地 Windows、macOS 和 Linux 桌面，也可在配置后通过 RDP 控制远程 Windows 桌面。
+
+在 OpenTest 中把它作为视觉自动化层，而不是整个质量门：
+
+```text
+desktop-gui 矩阵行
+  -> 项目启动 / 环境检查
+  -> @midscene/computer 或项目 GUI 自动化
+  -> 截图 + GUI 操作日志 + 窗口/App 元数据
+  -> 确定性 read/assert changed result
+```
+
+Electron 或 Tauri 先判断需求是否能用 DOM 验证。DOM 可验证流程归入 `web-browser`；原生外壳、托盘、文件选择器、原生菜单、系统弹窗、安装器、更新器和多窗口行为归入 `desktop-gui`。
+
+## 阻塞规则
+
+缺少任一必需前置条件时记录 `blocked`：
+
+- Midscene 视觉自动化的模型凭据
+- 桌面访问、显示器或 RDP 会话
+- App 启动命令或目标进程/窗口标识
+- 稳定 fixture 数据或 reset/teardown 路径
+- 写操作后的确定性结果面
+
+不得只凭 AI 视觉断言把 `desktop-gui` 验收标为 PASS。新增/修改/删除/保存后，必须重新读取可信结果面：重开的窗口状态、文件/配置值、App 存储/API、可访问性元数据、进程/窗口元数据，或重启后仍可见的持久化值。
+
+## 矩阵要求
+
+`desktop-gui` 行必须包含：
+
+- `执行面`：`desktop-gui`
+- `验收模式`：`n/a`
+- `证据层级`：`gui-acceptance`、`visual-acceptance`、`integration` 或 `smoke`
+- `框架/命令`：项目 GUI 命令、`@midscene/computer`、可访问性/窗口元数据脚本，或脚本化人工 GUI 路线
+- `必需证据`：截图或录屏、GUI 操作日志、窗口/App 元数据、确定性回读，以及不可用时的 blocked 前置条件

package/assets/skills-zh/opentest/references/matrix-format.md

@@ -2,11 +2,15 @@
 
 ## 最小列
 
-| ID | 需求来源 | 意图 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 必需证据 | 状态 |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| ID | 需求来源 | 意图 | 执行面 | 验收模式 | 触发/输入 | 期望行为 | 风险 | 证据层级 | 必需证据 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 
 `需求来源` 是必填项。可填写需求 ID、设计章节、用户故事、业务规则、风险说明、issue 或用户明确请求。不要把函数名、组件路径或已有测试文件当成验收来源。
 
+`执行面` 是必填项，应使用 `web-browser`、`android-app`、`desktop-gui` 或 `api` 之一。
+
+`web-browser` 行必须填写 `验收模式`：`instant-acceptance`、`durable-regression` 或 `visual-ai-assist`。
+
 ## 可选列
 
 - 覆盖面
@@ -28,4 +32,6 @@
 - `e2e`：跨页面、登录、权限、关键业务闭环。
 - `smoke`：关键页面或主路径不崩。
 - `browser-acceptance`：真实浏览器交互、反馈位置、响应式和视觉状态。
+- `visual-acceptance`：Android App 或桌面 GUI 执行面上的视觉 GUI 行为。
+- `gui-acceptance`：桌面 GUI 行为、窗口状态、弹窗、菜单和原生控件。
 - `security-review`：权限、敏感信息、越权、重复提交、注入风险。

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` 行还必须包含 `验收模式`。如果一个需求需要多个执行面或模式，拆成多行，或明确主执行面，并在 `必需证据` 中写次要证据。