前言¶

在 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