From 386f86690a071140f9804242283cd925f40abf8f Mon Sep 17 00:00:00 2001
From: Cooper-X-Oak <Cooper-X-Oak@users.noreply.github.com>
Date: Thu, 30 Apr 2026 13:00:42 +0800
Subject: [PATCH] =?UTF-8?q?docs(windows):=20=E8=A1=A5=E9=BD=90=E4=B8=8A?=
 =?UTF-8?q?=E6=B8=B8=E4=BA=A4=E4=BB=98=E4=B8=8E=E6=B5=8B=E8=AF=95=E5=B7=A5?=
 =?UTF-8?q?=E4=BD=9C=E6=B5=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../tauri-webdriver-v2.workflow.yml           |  80 +++++++++++
 docs/windows-tauri-test-agent-research.md     | 127 ++++++++++++++++++
 docs/windows-upstream-pr-workflow.md          |  65 +++++++++
 3 files changed, 272 insertions(+)
 create mode 100644 docs/references/tauri-webdriver-v2.workflow.yml
 create mode 100644 docs/windows-tauri-test-agent-research.md
 create mode 100644 docs/windows-upstream-pr-workflow.md

diff --git a/docs/references/tauri-webdriver-v2.workflow.yml b/docs/references/tauri-webdriver-v2.workflow.yml
new file mode 100644
index 00000000..ee1eeccd
--- /dev/null
+++ b/docs/references/tauri-webdriver-v2.workflow.yml
@@ -0,0 +1,80 @@
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - ".github/workflows/webdriver-v2.yml"
+      - "v2/**"
+
+name: WebDriver (v2)
+
+jobs:
+  test:
+    name: Test
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [ubuntu-latest, windows-latest]
+        webdriver-test: [selenium, webdriverio]
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: install Tauri dependencies (Linux)
+        if: matrix.platform == 'ubuntu-latest'
+        run: >
+          sudo apt-get update &&
+          sudo apt-get install -y
+          webkit2gtk-4.1
+          libayatana-appindicator3-dev
+          webkit2gtk-driver
+          xvfb
+
+      - name: install msdgedriver (Windows)
+        if: matrix.platform == 'windows-latest'
+        run: |
+          cargo install --git https://github.com/chippers/msedgedriver-tool
+          & "$HOME/.cargo/bin/msedgedriver-tool.exe"
+          $PWD.Path >> $env:GITHUB_PATH
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          cache: false
+          rustflags: ""
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: v2/src-tauri
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Node v20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+          cache-dependency-path: |
+            v2/pnpm-lock.yaml
+            v2/webdriver/${{ matrix.webdriver-test }}/pnpm-lock.yaml
+
+      - name: install dependencies
+        run: pnpm install
+        working-directory: v2
+
+      - name: Install tauri-driver
+        run: cargo install tauri-driver --locked
+
+      - name: run tests using ${{ matrix.webdriver-test }} (Linux)
+        if: matrix.platform == 'ubuntu-latest'
+        run: |
+          pnpm install
+          xvfb-run pnpm test
+        working-directory: v2/webdriver/${{ matrix.webdriver-test }}
+
+      - name: run tests using ${{ matrix.webdriver-test }} (Windows)
+        if: matrix.platform == 'windows-latest'
+        run: |
+          pnpm install
+          pnpm test
+        working-directory: v2/webdriver/${{ matrix.webdriver-test }}
diff --git a/docs/windows-tauri-test-agent-research.md b/docs/windows-tauri-test-agent-research.md
new file mode 100644
index 00000000..0ea1126f
--- /dev/null
+++ b/docs/windows-tauri-test-agent-research.md
@@ -0,0 +1,127 @@
+# Windows Tauri 测试 Agent / Workflow 调研
+
+## 背景
+
+OpenLess 是 Tauri v2 + React/Vite + Rust 后端的桌面应用。Windows 真机问题主要集中在：
+
+- 启动首屏：空边框、白屏、前端首帧前窗口过早显示。
+- 系统能力：全局热键、麦克风隐私权限、剪贴板、前台输入框插入。
+- 本地状态：凭据读写、历史记录、设置保存。
+- 人工输入：物理热键无法用普通 synthetic SendInput 可靠替代。
+
+## 可复用方案
+
+### 1. 官方 tauri-driver + WebDriver
+
+来源：
+
+- https://v2.tauri.app/develop/tests/webdriver/
+- https://github.com/tauri-apps/webdriver-example
+
+适合做 CI 基线：
+
+- 启动 Tauri 应用。
+- 检查窗口出现、DOM 内容、按钮点击、设置页导航。
+- Windows CI 可配 `msedgedriver`，Linux CI 可配 `webkit2gtk-driver + xvfb`。
+
+参考 workflow：
+
+- `tauri-apps/webdriver-example/.github/workflows/webdriver-v2.yml`
+- 该 workflow 在 `ubuntu-latest` 和 `windows-latest` 上安装 `tauri-driver`，Windows 侧安装 `msedgedriver`，再分别跑 selenium / webdriverio 测试。
+
+建议落地：
+
+- 先选 WebdriverIO，生态和断言更贴近前端团队。
+- 新增 `openless -all/app/webdriver/`，覆盖：
+  - 应用启动后 1 秒内出现 OpenLess UI。
+  - 设置页提供商字段能读出已存在凭据的“非空状态”。
+  - 打开设置页不会把未修改字段写回空值。
+  - 权限页 Windows 文案不出现 macOS 辅助功能授权提示。
+
+### 2. tauri-plugin-playwright
+
+来源：
+
+- https://docs.rs/crate/tauri-plugin-playwright/0.1.0
+
+适合做更接近 Playwright 的 E2E：
+
+- 在 Tauri app 内嵌控制 server。
+- 使用 Playwright API 做页面级断言。
+- 对前端团队迁移成本较低。
+
+风险：
+
+- 需要引入 Tauri plugin，测试入口和生产入口要隔离。
+- 目前生态成熟度低于官方 WebDriver。
+
+建议落地：
+
+- 暂不作为第一阶段 CI 基线。
+- 等 WebDriver 跑通后，再评估是否用它补截图、网络、前端状态断言。
+
+### 3. Tauri MCP / AI Agent 调试插件
+
+来源：
+
+- https://github.com/P3GLEG/tauri-plugin-mcp
+- https://github.com/dirvine/tauri-mcp
+
+适合做 agent 辅助调试：
+
+- 截图。
+- 窗口管理。
+- DOM 读取。
+- 鼠标/键盘输入。
+- localStorage 检查。
+
+风险：
+
+- 需要在 app 中接入调试插件，必须确保只在 dev/test 构建启用。
+- 不适合直接放进 production bundle。
+
+建议落地：
+
+- 可以做 `devtools/agent` 分支实验。
+- 目标是让 Codex/Claude/Cursor 能直接看 Tauri 窗口截图和 DOM，降低“用户肉眼测试”的比例。
+
+### 4. TestDriver AI
+
+来源：
+
+- https://testdriver.ai/vscode
+- https://github.com/testdriverai/testdriverai
+
+适合黑盒探索：
+
+- 用自然语言描述流程。
+- 支持桌面应用、Windows、GitHub Actions。
+- 能生成测试报告/视频。
+
+风险：
+
+- 外部服务/账号/成本依赖。
+- 对本项目当前开源 CI 基线不应作为唯一门禁。
+
+建议落地：
+
+- 作为 nightly 或人工触发探索测试，不作为 PR 必过的第一层。
+- 可覆盖“打开 OpenLess Dev、进入设置、检查凭据字段非空、按热键后胶囊状态变化”等高层流程。
+
+## 推荐实施顺序
+
+1. 保留现有 PowerShell smoke：构建、启动、进程响应、hotkey listener 日志。
+2. 增加 WebDriverIO 基线：窗口、DOM、设置页、凭据字段非空状态、Windows 文案。
+3. 增加 Windows 手动门禁脚本：物理热键、真实 ASR、Notepad fallback、麦克风隐私开关。
+4. 评估 Tauri MCP：给 agent 提供截图/DOM/输入能力，减少人工描述。
+5. 评估 TestDriver AI：做黑盒探索和视频报告。
+
+## 第一批必须补的测试
+
+- 启动首屏不能先显示空窗口边框。
+- Windows 启动不等待麦克风 input stream 探测。
+- 设置页凭据字段加载完成前 blur 不会保存空值。
+- 设置页打开后不修改字段，`credentials.json` 不发生变化。
+- `get_credentials` 与 `read_credential` 对同一文件返回一致状态。
+- 右 Control 默认热键文案在概览、历史、设置中一致。
+- Windows 权限页不显示 macOS 辅助功能授权引导。
diff --git a/docs/windows-upstream-pr-workflow.md b/docs/windows-upstream-pr-workflow.md
new file mode 100644
index 00000000..d1a8bae4
--- /dev/null
+++ b/docs/windows-upstream-pr-workflow.md
@@ -0,0 +1,65 @@
+# Windows upstream PR workflow
+
+## 目标
+
+Windows 主线先在 `fork/dev` 完成发现、修复、CI、自审和复审，再收敛成明确 upstream 维护项。不要把未收敛的真机 findings 直接写到 upstream issues 或 upstream PR。
+
+## 标准流程
+
+1. 在 `fork/dev` 修复问题。
+   - 每个提交只解决一个明确问题。
+   - findings 先写到本地记录或 fork issue。
+   - 不向 upstream 新增噪声 issue。
+
+2. 在 `fork/dev` 触发 CI。
+   - Windows build 必须过。
+   - 新增/修改的 Windows smoke 必须能在本机复跑。
+   - 真实凭据、物理热键、ASR、插入 fallback 等不能完全 CI 化的项目，要留下本机证据路径和日志摘要。
+
+3. 在 fork 上开自有 PR。
+   - base: `fork/dev`
+   - head: 功能分支
+   - PR 描述使用中文，按模板填写。
+   - PR 必须包含 fork CI 链接、真机回归摘要、自审结论。
+
+4. 复审 fork PR。
+   - 先按 code review 方式找阻断项。
+   - 修完 review findings 后再次跑 fork CI。
+   - 只有 fork PR 复审通过，才能进入 upstream 收敛。
+
+5. 收敛 upstream 维护项。
+   - 从 fork PR 中拆出最小 upstream 维护切片。
+   - upstream PR 只包含已验证的最小改动。
+   - upstream PR 描述必须带 fork PR / fork CI 链接，说明该切片来自已验证的 `fork/dev` 工作流。
+   - upstream issue 只用于已经确认、可维护、可复现、需要 upstream 跟踪的问题；不要把探索期 findings 扔到 upstream。
+
+## upstream PR 进入条件
+
+- `fork/dev` 已包含修复。
+- fork PR 已通过 CI。
+- fork PR 已完成自审和复审。
+- upstream 分支从最新 upstream base 切出。
+- upstream diff 能独立解释，不依赖 fork/dev 的其他未提交上下文。
+- PR 描述包含：
+  - 单一目标
+  - 不包含范围
+  - fork PR 链接
+  - fork CI 链接
+  - 本机 Windows 回归证据
+
+## 禁止项
+
+- 禁止从未验证的本地 finding 直接创建 upstream issue。
+- 禁止绕过 fork/dev CI 直接推 upstream PR。
+- 禁止把多个 Windows 真机问题混成一个 upstream PR。
+- 禁止在 upstream PR 中提交真实服务凭据、用户本地配置、构建产物或临时目录。
+
+## 当前执行规则
+
+后续 Windows 主线默认顺序为：
+
+```text
+fork/dev 修复 -> fork/dev CI -> fork PR -> 自审/复审 -> upstream 最小 PR
+```
+
+如果 upstream PR 需要更新，先确认对应 fork PR 和 fork CI 证据，再同步 upstream PR。