docs(windows): 补齐上游交付与测试工作流#67
Merged
appergb merged 1 commit intoApr 30, 2026
Merged
Conversation
Reviewer's GuideThis PR adds and updates documentation to formalize the desktop platform adapter architecture, define a Windows-focused upstream PR workflow, and capture research and reference workflows for Windows Tauri testing and WebDriver-based CI, without changing runtime code or build pipelines. Sequence diagram for hotkey event flow through platform adaptersequenceDiagram
actor User
participant OS_Windows
participant LowLevelKeyboardHookAdapter
participant HotkeyAdapterTrait as HotkeyAdapter
participant Coordinator
participant ProductCore
participant UI
User->>OS_Windows: Press right_control
OS_Windows-->>LowLevelKeyboardHookAdapter: Keyboard event
LowLevelKeyboardHookAdapter->>HotkeyAdapterTrait: pressed edge event
HotkeyAdapterTrait->>Coordinator: on_hotkey_pressed()
Coordinator->>ProductCore: start_dictation_session()
ProductCore->>UI: update_recording_indicator(active)
User->>OS_Windows: Release right_control
OS_Windows-->>LowLevelKeyboardHookAdapter: Keyboard event
LowLevelKeyboardHookAdapter->>HotkeyAdapterTrait: released edge event
HotkeyAdapterTrait->>Coordinator: on_hotkey_released()
Coordinator->>ProductCore: stop_dictation_session()
ProductCore->>UI: update_recording_indicator(inactive)
Class diagram for platform adapters and hotkey implementationsclassDiagram
class AdapterError {
+code
+platform
+operation
+recoverable
+user_message
+debug_message
}
class AdapterCapability {
+supported
+requires_permission
+permission_name
+fallback_available
}
class HotkeyStatus {
+installed
+last_error: AdapterError
}
class HotkeyAdapter {
<<interface>>
+install()
+uninstall()
+update_binding(binding)
+get_status(): HotkeyStatus
+get_capability(): AdapterCapability
}
class AudioAdapter {
<<interface>>
+list_input_devices()
+probe_permissions(): AdapterCapability
+start_probe_capture(device_id)
+stop_probe_capture()
+open_stream(device_id)
+close_stream()
}
class InsertionAdapter {
<<interface>>
+insert_text(text)
+fallback_clipboard_insert(text)
+classify_insertion_result(result)
}
class AppContextAdapter {
<<interface>>
+get_foreground_app()
+get_active_window()
+probe_text_field_capabilities()
}
class TrayAdapter {
<<interface>>
+create_tray()
+update_menu()
+open_window(window_id)
+quit_app()
}
class AutostartAdapter {
<<interface>>
+read_autostart()
+write_autostart(enabled)
}
class MacHotkeyAdapter {
+cg_event_tap_handle
+install()
+uninstall()
+update_binding(binding)
+get_status(): HotkeyStatus
+get_capability(): AdapterCapability
}
class LowLevelKeyboardHookAdapter {
+hook_handle
+install()
+uninstall()
+update_binding(binding)
+get_status(): HotkeyStatus
+get_capability(): AdapterCapability
}
class RegisteredShortcutAdapter {
+shortcut_id
+install()
+uninstall()
+update_binding(binding)
+get_status(): HotkeyStatus
+get_capability(): AdapterCapability
}
class LegacyRdevHotkeyAdapter {
+install()
+uninstall()
+update_binding(binding)
+get_status(): HotkeyStatus
+get_capability(): AdapterCapability
}
HotkeyAdapter <|.. MacHotkeyAdapter
HotkeyAdapter <|.. LowLevelKeyboardHookAdapter
HotkeyAdapter <|.. RegisteredShortcutAdapter
HotkeyAdapter <|.. LegacyRdevHotkeyAdapter
HotkeyStatus --> AdapterError
HotkeyAdapter --> HotkeyStatus
HotkeyAdapter --> AdapterCapability
AudioAdapter --> AdapterCapability
AutostartAdapter --> AdapterError
InsertionAdapter --> AdapterError
AppContextAdapter --> AdapterCapability
Flow diagram for Windows upstream PR workflowgraph TD
A[Start: Windows issue discovered] --> B[Fix in fork/dev]
B --> B1[Keep commits focused and findings local]
B1 --> C[Run fork/dev CI]
C --> C1{CI and local smoke pass?}
C1 -- No --> B
C1 -- Yes --> D[Open fork PR]
D --> D1[Include fork CI links and local evidence]
D1 --> E[Self review fork PR]
E --> F[Peer review fork PR]
F --> F1{Review approved?}
F1 -- No --> B
F1 -- Yes --> G[Extract minimal upstream maintenance slice]
G --> H[Create upstream PR from latest upstream base]
H --> H1[Describe single goal and include fork links]
H1 --> I[Upstream review and merge]
I --> J[End: Windows fix merged upstream]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- In
docs/references/tauri-webdriver-v2.workflow.yml, the Windowsinstall msdgedriverstep has both a typo in the step name (msdgedrivervsmsedgedriver) and an incomplete PATH update ($PWD.Path >> $env:GITHUB_PATHwon’t work as written in PowerShell); consider correcting the name and using an explicitOut-Fileorechopipeline to append the driver directory toGITHUB_PATH. - The adapter layer now standardizes error and capability shapes (
code/platform/operation/recoverable/...,supported/requires_permission/...); it would help future implementation if you add a short, single source of truth type/schema snippet (e.g., Rust struct + TS interface name/location) in the architecture doc so both sides know exactly which types to reuse.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `docs/references/tauri-webdriver-v2.workflow.yml`, the Windows `install msdgedriver` step has both a typo in the step name (`msdgedriver` vs `msedgedriver`) and an incomplete PATH update (`$PWD.Path >> $env:GITHUB_PATH` won’t work as written in PowerShell); consider correcting the name and using an explicit `Out-File` or `echo` pipeline to append the driver directory to `GITHUB_PATH`.
- The adapter layer now standardizes error and capability shapes (`code/platform/operation/recoverable/...`, `supported/requires_permission/...`); it would help future implementation if you add a short, single source of truth type/schema snippet (e.g., Rust struct + TS interface name/location) in the architecture doc so both sides know exactly which types to reuse.
## Individual Comments
### Comment 1
<location path="docs/references/tauri-webdriver-v2.workflow.yml" line_range="20" />
<code_context>
+ platform: [ubuntu-latest, windows-latest]
+ webdriver-test: [selenium, webdriverio]
+ steps:
+ - uses: actions/checkout@v2
+
+ - name: install Tauri dependencies (Linux)
</code_context>
<issue_to_address>
**🚨 suggestion (security):** Consider updating `actions/checkout` to the latest major version for security and maintenance benefits.
This workflow is pinned to `actions/checkout@v2`. Please upgrade to `actions/checkout@v4` so you get the latest security and performance fixes; the migration is typically drop‑in for most workflows.
```suggestion
- uses: actions/checkout@v4
```
</issue_to_address>
### Comment 2
<location path="docs/references/tauri-webdriver-v2.workflow.yml" line_range="32-37" />
<code_context>
+ 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
</code_context>
<issue_to_address>
**suggestion (performance):** Clarify and potentially optimize the Windows Edge WebDriver installation step.
There’s a small typo in the step name (`msdgedriver` → `msedgedriver`). Also, since this installs a custom tool from a Git repo on every run, consider switching to the official Edge WebDriver distribution (or a maintained action) and/or caching the driver by version and platform to improve stability and reduce CI time on Windows jobs.
Suggested implementation:
```
- name: install msedgedriver (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
```
To fully address the suggestion about stability and CI time improvements, you may also want to:
1. Replace the `cargo install --git` approach with a step that downloads a specific, versioned Edge WebDriver directly from Microsoft's official distribution for the target platform (e.g., via `Invoke-WebRequest` / `Expand-Archive` in PowerShell), and add a cache step (using `actions/cache`) keyed by `{ os, driverVersion }` to avoid re-downloading on every run.
2. Alternatively, switch to a maintained GitHub Action that installs Edge WebDriver on Windows and relies on internal caching, then remove the `msedgedriver-tool` install step entirely.
3. Document in this workflow (e.g., via a comment above the step) which Edge channel/version you are targeting so future updates to the driver/caching key are straightforward.
These changes depend on how you prefer to manage browser versions and what other parts of your CI configuration look like, so they should be tailored to your existing setup.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| platform: [ubuntu-latest, windows-latest] | ||
| webdriver-test: [selenium, webdriverio] | ||
| steps: | ||
| - uses: actions/checkout@v2 |
There was a problem hiding this comment.
🚨 suggestion (security): Consider updating actions/checkout to the latest major version for security and maintenance benefits.
This workflow is pinned to actions/checkout@v2. Please upgrade to actions/checkout@v4 so you get the latest security and performance fixes; the migration is typically drop‑in for most workflows.
Suggested change
| - uses: actions/checkout@v2 | |
| - uses: actions/checkout@v4 |
Comment on lines
+32
to
+37
| - 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 |
There was a problem hiding this comment.
suggestion (performance): Clarify and potentially optimize the Windows Edge WebDriver installation step.
There’s a small typo in the step name (msdgedriver → msedgedriver). Also, since this installs a custom tool from a Git repo on every run, consider switching to the official Edge WebDriver distribution (or a maintained action) and/or caching the driver by version and platform to improve stability and reduce CI time on Windows jobs.
Suggested implementation:
- name: install msedgedriver (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
To fully address the suggestion about stability and CI time improvements, you may also want to:
- Replace the
cargo install --gitapproach with a step that downloads a specific, versioned Edge WebDriver directly from Microsoft's official distribution for the target platform (e.g., viaInvoke-WebRequest/Expand-Archivein PowerShell), and add a cache step (usingactions/cache) keyed by{ os, driverVersion }to avoid re-downloading on every run. - Alternatively, switch to a maintained GitHub Action that installs Edge WebDriver on Windows and relies on internal caching, then remove the
msedgedriver-toolinstall step entirely. - Document in this workflow (e.g., via a comment above the step) which Edge channel/version you are targeting so future updates to the driver/caching key are straightforward.
These changes depend on how you prefer to manage browser versions and what other parts of your CI configuration look like, so they should be tailored to your existing setup.
appergb
force-pushed
the
codex/windows-docs-workflow-pr
branch
from
9ec8ad9 to
386f866
Compare
appergb
pushed a commit
that referenced
this pull request
Apr 30, 2026
包含本轮所有合并： - Codex 终审两条 HIGH (cancel race) 修复 (PR #79) - 6 个 Cooper-X-Oak/Codex bot PRs 自动合并 (#44 #49 #53 #68 #72 #73) - 2 个有冲突 PR 本地 rebase 后合并 (#66 cancel + 空转写并存 / #67 Windows docs) - README 破图修复 (PR #80) - workflow-scope 受限的 #48 + #75 由用户在 GitHub UI 直接合并 3 处版本字段同步：package.json + tauri.conf.json + Cargo.toml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
摘要
关联 fork 验证：Cooper-X-Oak#12。
本 PR 是从 fork/dev 已验证批次拆出的文档维护项：补齐 Windows 平台适配架构、Tauri 测试 agent 调研、上游 PR 交付门禁和 WebDriver workflow 参考。
fork/dev 先行验证
b9ee8b8。修复 / 新增 / 改进
docs/platform-adapter-architecture.md，明确 desktop core / platform adapter 分层方向。docs/windows-tauri-test-agent-research.md，记录 Windows Tauri 测试 agent / workflow 调研。docs/windows-upstream-pr-workflow.md，规定 fork/dev CI、自 PR、复审后再拆 upstream PR。docs/references/tauri-webdriver-v2.workflow.yml，作为后续 WebDriver CI 落地参考。兼容
测试计划
git diff --checkSummary by Sourcery
Document the planned desktop platform adapter architecture and Windows-focused workflows for testing and upstream PR delivery.
Documentation: