H1: 型別檢查深度與相依矩陣

Author: JE-Chen

.github/workflows/quality.yml

@@ -229,6 +229,31 @@ jobs:
       # regression in that arrangement.
       - run: python test/verify/typing_contract_verify.py
 
+  typing-extras:
+    if: inputs.verification_scope != 'native-shortcut'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[gui,webrtc]"  # NOSONAR githubactions:S8544  # reason: installs the checked-out project
+      - run: "pip install mypy==2.3.0 uiautomator2==3.7.0 adbutils==2.12.0 facebook-wda==1.5.4"
+      - name: Check complete definitions and real Qt stubs with mobile SDKs installed
+        run: python test/verify/typing_contract_verify.py --extras
+      - name: Preserve installed SDK and typing dependency versions
+        if: always()
+        run: pip freeze > typing-extras-versions.txt
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: typing-extras-${{ matrix.python-version }}
+          path: typing-extras-versions.txt
+
   wayland-shortcut-native:
     runs-on: ubuntu-22.04
     timeout-minutes: 10

CHANGELOG.md

@@ -8,6 +8,8 @@ only when documented here with a migration path.
 
 New entries go under `## Unreleased
 
+- Modernization modules now require complete mypy definitions/generics. Installed-extras checks validate real Qt stubs; SDK adapters expose typed Protocol interfaces. GUI fixes preserve QWidget.style(), use scoped Qt enums and retain translation widget subtypes.
+
 - MCP adds mode/profile/page-size stdio flags and measured disclosure costs. Readonly now rejects mutating custom-registry calls; concurrent workers preserve accepted client roots and capabilities after session termination.`. The version bump on `main` is automated
 and does not touch this file, so after a release tag appears, move the entries
 it shipped into a `## [x.y.z] - date` section of their own; the tag's

Progress.md

@@ -9,13 +9,13 @@
 核准設計：[跨平台自動化與 GUI 改版](docs/superpowers/specs/2026-10-02-platform-gui-modernization-design.md)。
 實作計畫：[分階段交付計畫](docs/superpowers/plans/2026-10-02-modernization-index.md)，已核准，依序實作。
 現有 `[Answer]` 決策沿用；後續交付包含 E–H 與完整整合驗收。
-從 H1 接續原有計畫；不額外新增付費型功能。既有 API 介面及相關修正繼續，
+從 H2 接續原有計畫；不額外新增付費型功能。既有 API 介面及相關修正繼續，
 目前以本機／離線測試驗證；缺少真實 API 條件的既有項目保留待驗證。
 正向實體裝置擷取、GNOME/KDE 授權與鍵態恢復仍列 H3；
 歷史 Qt 原生崩潰的後續追蹤仍保留在下列驗收項目。
 WDA 專用 endpoint、外部 client／別名競態、未知建立回覆及 SDK 擷取後的
 App session 接續／恢復仍列 H3；受控閒置檢查不能冒充原生互斥證據。
-H1–H3 的型別、文件與整合驗收繼續依序實作。
+H2–H3 的文件與整合驗收繼續依序實作。
 H3 仍需自有錄製的原生輸出內容、實體鍵態恢復及外部輸入 client 競態證據；
 受控 GUI 所有權、重試、container 關閉與 widget 刪除不代表實體恢復或有效錄影。
 

README.md

@@ -1080,3 +1080,5 @@ Configure the real deployment with the environment settings above. More details:
 [session contract](docs/MCP_DISCOVERY.md).
 
 MCP stdio also accepts `--tool-mode full|progressive|static`, `--tool-profile ac_screenshot,ac_probe_capabilities` and `--tool-page-size 1..100`; explicit flags override corresponding deployment settings. `--list-tools` still prints the complete authorized catalog for inspection. Example: `python -m je_auto_control.utils.mcp_server --tool-mode static --tool-profile ac_screenshot`. Discovery changes availability only: execution still checks RBAC, schema, roots/env, rate limits and confirmation. Readonly rejects mutating calls from custom registries too. Concurrent workers retain accepted identity, roots and capabilities across session termination. [Measured local schema cost](benchmarks/results/mcp-discovery-g3/report.json): full747 /363544bytes versus core6 /2506bytes; local handshake/list medians37.91/9.56ms, search9.78/9.65ms (five samples, no network).
+
+Modernization type validation: `python test/verify/typing_contract_verify.py` checks win32/linux/darwin with zero exemptions. New/rewritten modules additionally require complete definitions and generic arguments. After installing `[gui]`, `python test/verify/typing_contract_verify.py --extras` checks all modernization GUI modules against real PySide6 stubs. CI also installs pinned Android/WDA SDKs; Protocol-backed lazy adapters keep raw SDK objects inside their boundary. JSON/event payloads retain explicit dynamic fields.

README/README_zh-CN.md

@@ -902,3 +902,5 @@ Tools → MCP 工具发现提供可取消的 Actions，在本机搜索或查看
 真正部署请使用上述环境设置。详见[session 契约](../docs/MCP_DISCOVERY.md)。
 
 MCP stdio 支持 `--tool-mode full|progressive|static`、`--tool-profile ac_screenshot,ac_probe_capabilities` 和 `--tool-page-size 1..100`；参数覆盖对应部署设置。`--list-tools` 仍输出完整已授权目录供检查。例如：`python -m je_auto_control.utils.mcp_server --tool-mode static --tool-profile ac_screenshot`。披露只改变可见列表，执行仍检查 RBAC、schema、roots/env、限流与确认。只读也拒绝自定义 registry 的修改调用；后台任务在 session 终止后保留原请求身份、roots 与 capabilities。[本机测量](../benchmarks/results/mcp-discovery-g3/report.json)：完整747个／363544bytes，核心6个／2506bytes；本机握手及列表中位数37.91／9.56ms，搜索9.78／9.65ms（五次样本，未含网络）。
+
+改版类型验证：`python test/verify/typing_contract_verify.py` 检查 win32/linux/darwin，豁免为零；新／重写模块还要求完整函数和泛型参数。安装 `[gui]` 后，`python test/verify/typing_contract_verify.py --extras` 使用真实 PySide6 stubs 检查全部改版 GUI 模块。CI 另安装固定版本 Android/WDA SDK；延迟 adapter 以 Protocol 限定 SDK 接口。JSON／事件数据保留明确的动态字段。

README/README_zh-TW.md

@@ -903,3 +903,5 @@ Tools → MCP 工具探索提供可取消的 Actions，在本機搜尋或查看
 真正部署請使用上述環境設定。詳見[session 契約](../docs/MCP_DISCOVERY.md)。
 
 MCP stdio 支援 `--tool-mode full|progressive|static`、`--tool-profile ac_screenshot,ac_probe_capabilities` 與 `--tool-page-size 1..100`；旗標覆寫對應部署設定。`--list-tools` 仍輸出完整已授權目錄供檢查。例如：`python -m je_auto_control.utils.mcp_server --tool-mode static --tool-profile ac_screenshot`。揭露只改變可見清單，執行仍檢查 RBAC、schema、roots/env、限流與確認。唯讀也拒絕自訂 registry 的修改呼叫；背景工作在 session 終止後保留原請求身分、roots 與 capabilities。[本機量測](../benchmarks/results/mcp-discovery-g3/report.json)：完整747個／363544bytes，核心6個／2506bytes；本機交握及清單中位數37.91／9.56ms，搜尋9.78／9.65ms（五次樣本，未含網路）。
+
+改版型別驗證：`python test/verify/typing_contract_verify.py` 檢查 win32/linux/darwin，豁免為零；新／重寫模組還要求完整函式與泛型參數。安裝 `[gui]` 後，`python test/verify/typing_contract_verify.py --extras` 使用真實 PySide6 stubs 檢查全部改版 GUI 模組。CI 另安裝固定版本 Android/WDA SDK；延遲 adapter 以 Protocol 限定 SDK 介面。JSON／事件資料保留明確的動態欄位。

architecture.md

@@ -471,3 +471,5 @@ bounded lifetime/count, and standing HTTP notification writers are looked up fro
 live session metadata. Preview surfaces never mutate real serving sessions.
 
 G3 concurrent MCP workers retain accepted transport identity, capabilities and bounded roots even after session drop. ContextVar authorization/view leases remain intact. Readonly is checked at execution for custom registries; mode/profile/page-size flags preserve full defaults. Local cost artifacts use the same registry/policy.
+
+H1 strict module manifest mirrors mypy complete-definition/generic overrides. Stable targets preserve zero exemptions; installed-extras runs expose actual Qt signatures on all modernization GUI files. Android/iOS lazy clients and literal DeviceSession.adapter overloads expose structural SDK interfaces; dynamic SDK bootstrap/disposal and extension compatibility remain at their adapter boundary. Generic translation helpers preserve QWidget subtype. ConnectionTasks uses composition of owner-bound PanelTasks, preserving its connect API without overriding QObject.connect.