前言¶

在 Harness 裏做移動端或 Expo 相關開發時，Maestro 的 UI 測試往往在終端裏跑：maestro test 輸出一長串日誌，很難一眼看出當前 flow、當前步驟和整體進度。要在瀏覽器裏同時看場景編排、目標設備、運行日誌和截圖，通常得自己拼腳本或切多個窗口。下面介紹社區插件 dsh-maestro-progress（維護者 pimili-app），它在 Harness Web 側欄提供 Maestro 視圖，通過輪詢本地小 API，按 flow 與步驟展示執行狀態，並支持從已有 flow 組合端到端場景。

這是什麼¶

dsh-maestro-progress 是 DeepSeek Harness 的庫外插件（分類：工作流）。包內無構建步驟：index.js 在宿主側啓動測試、跟蹤 Maestro debug 日誌並提供 HTTP API；client.js 在瀏覽器註冊側欄圖標、主面板與右側欄 Tab。主面板約每 1.5 秒輪詢 API 刷新進度。

插件解決的核心問題：把 Maestro 套件執行過程可視化進 Harness，而不是隻在 CLI 裏讀日誌。

核心功能¶

執行狀態與進度¶

面板展示：

• 運行狀態（空閒、進行中、成功、失敗、已停止）與耗時；
• 進度條：已完成 / 計劃 flow 數，以及成功、失敗計數；
• 每個 flow 一行：狀態、耗時、當前步驟；
• 點擊某 flow 可看失敗步驟、Maestro 消息、最近步驟耗時、Maestro 保存的截圖；
• Lancer les tests / Arrêter（界面文案爲法文；配置裏可改啓動命令）。

運行中會把 Maestro 命令改寫成可讀句子（含變量解析；persona 密碼類變量不會顯示）。

組合 E2E 場景¶

可從 .maestro/flows/*.yaml 在面板裏定義場景：Scénarios → Nouveau scénario，命名後按順序添加 flow（↑↓ 調整、× 移除）。每個場景單獨 Lancer，執行時通過 runFlow: file: 在同一次 Maestro 會話裏串聯所選 flow，無需再經插件 UI 逐步觸發。

• 定義文件：<projectDir>/.maestro/scenarios/scenarios.json（含 id、名稱、flow 順序）；
• 運行時生成：<projectDir>/.maestro/scenarios/<id>.yaml（可提交版本庫）；
• 每次運行的日誌與產物：<projectDir>/.maestro/scenarios/.runs/<runId>/（保留最近 20 次）。

目標設備¶

每個場景可在行內下拉或編輯器裏選擇設備（「Automatique」+ 檢測到的 iOS 模擬器 / 已連接 Android 模擬器）。列表來自 xcrun simctl 與 adb，含設備狀態。執行時對 Maestro 傳入 --udid（別名 --device）及對應平臺；模擬器未啓動或設備不存在會明確報錯。未選時：有已啓動 iOS 模擬器則默認 iOS，否則 Android。場景行上會以 badge 顯示目標設備。

場景間防假陰性（默認開啓）¶

每個場景默認在每個串聯 flow 之前插入條件恢復塊：若預期屏幕不可見，則通過 Expo deep link 重啓應用、處理密碼保存提示、執行 ensure-logged-out 並等待目標屏（默認預期屏 login-screen，最多兩次）。可在場景編輯器裏按場景關閉。README 還說明 iOS 系統級「建議強密碼」 sheet 對 Maestro 不可見，需在模擬器系統設置裏關閉，否則可能在 flow 之間仍出現假失敗。

右側欄 Tab¶

除主 Maestro 面板外，插件在 Harness 右側欄註冊 Tab（與簡介中的 right-sidebar tab 一致），便於在開發佈局裏並排查看。

安裝與啓用¶

前提（來自 README）：

• DeepSeek Harness ≥ 0.2.0-rc.1（在 0.2.1-rc.5 上測試過）；
• Maestro CLI 2.x（maestro --version）；
• 項目含 .maestro/flows/*.yaml（可選 .maestro/subflows/*.yaml）；
• 跑組合場景時需已啓動 iOS 模擬器或已連接 Android 模擬器，以及項目 Metro（Maestro 測試默認端口 8084，開發常用 8083）。

安裝命令（須完整退出桌面應用後再裝 desktop profile）：

# 桌面 Electron 應用（desktop profile）：安裝前完全退出應用，再重新打開
dsh plugin --profile desktop add github:pimili-app/dsh-maestro-progress

# 命令行 Harness（web profile）
dsh plugin --profile web add github:pimili-app/dsh-maestro-progress

桌面版若應用仍在運行，CLI 會拒絕安裝；使用應用內置 CLI 時，需通過菜單「Gérer la commande dsh」→ 安裝啓用。

安裝後檢查 ~/.dsh/profiles/desktop/package.json：dsh.profile.bundles 中應包含 "dsh-maestro-progress"。若包只出現在 dependencies 而未作爲 bundle 掛載，啓動日誌可能出現 patch: entry "maestro-progress" not found。

添加 bundle（改 package.json）後需重啓 Harness 服務；patch 可熱重載。改完後刷新瀏覽器 Tab 以重建 window.__DSH_BOOT__。

本地開發可鏈接：

dsh plugin --profile web add link:~/DSH-plugins/maestro-progress
dsh --profile web

配置¶

在 Harness 工作區的 cordis.patch.yml 中爲插件條目填寫 config（示例來自 README，路徑需改成你的項目根）：

- insert:
    - id: maestro-progress
      name: 'dsh-maestro-progress'
      config:
        projectDir: /chemin/vers/mon-projet
        command: make maestro
        metroPort: 8084

package.json 聲明引擎：dsh 版本 >=0.2.0-rc.1 <0.3.0-0；當前插件版本 0.1.0，許可證 MIT。

典型用法¶

1. 安裝插件並配置 projectDir、command（及按需 metroPort、appId 等）。
2. 在 Harness Web 打開 Maestro 側欄視圖，確認能列出 .maestro/flows 下的 flow。
3. 點擊 Lancer les tests 執行配置的 command，觀察 flow / 步驟進度與截圖。
4. 需要固定迴歸路徑時：Scénarios → Nouveau scénario，按業務順序添加 flow，選擇目標設備後 Lancer；需要改順序或名稱時用 Modifier，Enregistrer 保留同一 id。
5. 組合場景前確保 Metro 與模擬器/真機就緒；若 flow 間常因登錄態或殘留 sheet 失敗，保持默認 garde-fou，或按 README 調整預期屏並在 iOS 模擬器關閉強密碼建議。

適用場景與注意¶

適合：已在項目裏用 Maestro 2.x 維護 .maestro/flows，希望在 DSH Web 裏統一啓動測試、看進度、編場景、選設備並查最近 run 日誌與截圖的團隊或個人。

注意：

• 插件以當前 dsh 進程權限運行，會執行你配置的 command 並讀取 projectDir、Maestro 日誌目錄；安裝前請閱讀 GitHub 源碼 與 MIT 許可證，確認命令與路徑可信。
• 社區目錄 SkillHub 插件頁 與 GitHub 倉庫由維護者發佈，與 DeepSeek / 幻方無官方從屬關係；DSH 生態強調「一切皆插件」，本文事實以倉庫 README 與 package.json 爲準。
• GitHub 星標當前爲 0，不代表功能完整性；遇問題可走 Issues。

結尾¶

dsh-maestro-progress 把 Maestro UI 測試的執行態搬進 Harness：實時 flow/步驟、組合場景、設備選擇與運行產物一屏跟進，並附帶右側欄 Tab。若你已在 Harness ≥ 0.2.0-rc.1 下做移動端 E2E，可按上文命令安裝並在 cordis.patch.yml 指向你的 Maestro 項目根。

• 目錄頁：https://www.skillhub.cn/plugins/pimili-app/dsh-maestro-progress
• GitHub：https://github.com/pimili-app/dsh-maestro-progress