PowerAppsControl

<div align="center"> # 应用控制 ### 使用人工智能代理驱动、记录和报告您的Power Apps，就像真实用户一样 [](https://github.com/ilyafainberg/PowerAppsControl/releases) [](LICENSE)  <video src="https://github.com/user-attachments/assets/d6599636-906b-47ab-88ad-ddcf99eb32a5" controls muted autoplay loop playsinline width="880"></video> </div> --- ## 快速开始（首次使用） 1. **安装。** 下载最新的 **[发布版本](https://github.com/ilyafainberg/PowerAppsControl/releases)**： - **安装程序（推荐）：** 获取 `PowerAppsControl-<ver>-setup.zip`，解压，运行 `.exe`，按照向导操作。它会自动注册服务器（和 `/PowerAppsControl` 技能）与 **Microsoft Scout** 和 **GitHub Copilot CLI**，并提供安装 **FFmpeg**（视频录制所需）。 - **便携版：** 获取 `PowerAppsControl-<ver>-portable-win-x64.zip`，解压，然后运行 `PowerAppsControl.exe --register` 一次。 - 未签名构建 → Windows SmartScreen 可能会警告：**更多信息 → 运行任何方式**。 2. **重启您的主机**（Scout / Copilot CLI），使其加载新的服务器 + 技能。 3. **直接询问。** 在聊天中说： > **测试我的 Power App https://apps.powerapps.com/play/…** 代理将打开并验证应用，询问您 **如何** 测试它（烟雾测试 / 提出计划 / 您自己的计划），然后运行它并为您提供 HTML 报告。 --- ## ⚠️ 请阅读 - 安全性和责任 **此工具控制您的真实鼠标、键盘和屏幕，并驱动您的真实、已签名的 Power App。没有沙盒。** 使用它，您接受以下条件： - **它作用于实时数据。** 运行发生在您指向的任何租户/应用/记录上。它默认为 **只读** 导航，但任何测试点击 *保存*、*提交*、*删除*、*发送* 或命令栏操作 **可以创建、修改、删除或发送真实数据**。仅在您确定时批准此类步骤，并优先使用 **非生产/开发环境** 进行任何破坏性操作。 - **它接管输入。** 在会话活动时，工具移动您的光标并输入。不要在运行期间将机器用于其他工作。您可以通过点击应用窗口周围的猩红色 "代理控制" 框架上的 **✕** 立即 **停止**。 - **它记录您的屏幕。** 会话视频和截图写入 `%USERPROFILE%\PowerAppsControl\Sessions\…`。它们可能会捕获 **敏感的屏幕数据**（应用中可见的记录、名称、令牌）。在共享之前请查看；此工具不会将任何内容上传到任何地方。 - **它从互联网下载。** 更新程序和 FFmpeg 安装程序从 GitHub / winget / 静态 FFmpeg 构建中获取。仅在您信任源仓库时运行 `--update`。 - **没有保修。** 此软件按 **"原样"** 提供，不提供任何形式的保修，并根据 GPL-3.0 许可（参见 [LICENSE](LICENSE) 的第 15-16 节 - 免责声明和责任限制）。您 **单独负责** 测试的内容、环境和任何后果。作者不接受数据丢失、意外更改、停机时间或任何其他损害的任何责任。 - **仅在您授权的地方使用。** 测试您拥有或有明确权限测试的应用和租户。尊重您的组织的政策和任何适用的法规。 如果您不接受这些条款，请不要运行它。 --- ## 两种测试方式 您可以描述您想要的内容，使用 **自然语言** - 您永远不会编写 JSON 或脚本。两种模式都会生成记录的会话和 HTML 报告。 ### 1. 烟雾测试 - 让代理探索（推荐） 指向代理一个应用并说 *"烟雾测试它"*。它深入探索应用 **只读** - 打开菜单、检查表单、排序/过滤网格、打开记录、导航屏幕 - 不保存、不提交、不删除任何内容。然后它为您提供一个 **可重复的、自然语言的测试计划**（一个自然语言脚本，您和代理都可以阅读和重新运行），包含在报告中并可保存以重用为回归测试。 ### 2. 运行您的测试计划 - 您指定要测试的内容 用自然语言告诉代理要测试的内容（例如 *"打开第一个仓库，检查名称字段，返回，排序创建时间"*），或指向已保存的计划。它运行计划 - 可选地 **N 次** 或跨 **多个窗口** 一次进行轻负载测试 - 每个步骤有通过/失败和计时。 > 在幕后，代理在运行时将您的自然语言计划编译为精确的 UI 自动化步骤（优先使用名称控制，以便计划在布局、DPI 和主题更改后仍然有效）；该机器形式从未显示给您，从未保存为工件。 --- ## 清晰的视觉提示（低摩擦） 在会话活动期间，用户始终看到正在发生的事情： - **猩红色 "代理控制" 框架** 环绕每个正在驱动的窗口 - 一个圆润的框架，紧贴窗口边框（也适用于 **最大化窗口**），顶部边缘有一个集成的状态药丸，显示一个脉动的 REC 点和当前步骤。 - **立即中止：** 点击任何控件框架上的 ✕ 以停止所有操作。下一个工具调用返回 `⛔ 用户中止`，记录完成，代理停止。 ## 可点击的选择（MCP 诱导） 服务器通过可点击的按钮驱动工作流的决策点，使用 MCP **诱导** 功能 - 选择逻辑存在于服务器中，而不是代理提示： - `open_power_app` 验证 URL，然后询问 **哪种模式** 以按钮形式运行（烟雾测试 / 运行我的计划）并返回用户的选择。 - `ask_user_choice(question, options[])` 是一个可重用的提示，用于任何决策 - 批准计划、重新运行与修复等。 如果连接的 MCP 客户端不支持诱导，这些会优雅地回退到以文本形式返回选项，以便代理可以在聊天中询问。 --- ## 会话生命周期（强制） 测试工具在活动会话上进行门控，因此每个操作都被框架、记录和报告。 ``` start_test_session ──► run_test_script / smoke_step ──► end_test_session (控制 + REC + HUD) (进行测试) (停止 REC，写入报告) ``` | 工具 | 目的 | |------|---------| | `start_test_session(appName, windowQuery?, maxWindows?, fps?, recordVideo?)` | 解析 + 控制应用窗口（s），启动录制，显示框架状态药丸。 | | `test_session_status()` | 当前会话：应用，窗口，模式，已运行次数，探索步骤。 | | `end_test_session()` | 停止录制，释放窗口，写入 `report.html` + `report.json`。 | | `smoke_step(action, description?, …)` | 执行一个只读的探索性操作 **和** 将其记录到探索日志中。 | | `get_exploration_log(name?)` | 返回纯英文的探索日志（从中编写测试计划）。 | | `save_test_plan(name, plan)` | 将自然语言计划保存到库中并将其附加到报告中。 | | `load_test_plan(name)` / `list_test_plans()` | 读取 / 列出已保存的自然语言计划。 | | `run_test_script(scriptJson, runs?, parallelWindows?)` | 执行计划（代理将计划编译为步骤）`runs` 次，跨 `parallelWindows` 窗口。 | 桌面引擎工具也可用于自由表单探索： `find_window`, `control_window`, `release_window`, `screenshot_window`, `click_in_window`, `send_keys`, `scroll_mouse`, `find_element`, `hover_preview`, `record_window`, `crop_screenshot`, 以及绝对鼠标/键盘工具。 --- ## 测试计划是自然语言 您用 **自然语言** 描述测试 - 一个编号的步骤列表，每个步骤命名一个控件及其可见标签，并说明预期结果。代理（或烟雾测试）以相同形式生成计划，报告也以相同方式显示： ``` # Contoso 推荐 - 提交推荐 1. 等待应用加载完成 - “新建推荐”按钮应可见。 2. 点击“新建推荐” - 推荐表单打开。 3. 在“患者姓名”字段中输入“Jane Doe”，然后按 Tab。 4. 点击“提交”。 5. 验证出现“谢谢”确认信息。 ``` 这就是整个创作模型 - **没有 JSON，没有坐标**。在幕后，代理在运行时将每行编译为精确的 UI 自动化操作（优先使用名称控件，以便计划在布局、DPI 和主题更改后仍然有效）；该机器形式从未显示给您，从未保存为工件。 --- ## 重复和负载测试 - **重复：** 要求在同一个窗口中运行计划 **N 次** 以检查一致性。 - **负载：** 要求在 **多个窗口** 中运行它一次以模拟并发用户（首先打开多个应用副本）。 因为 Windows 序列化真正的合成输入（一个光标，一个前台窗口），所以负载测试 **交织**：对于每个步骤，运行器在每个窗口中执行一次，因此所有 M 个窗口一起推进计划。报告按 **每个窗口和每个运行** 分解结果。 --- ## 输出 会话的所有内容都放在一个便携的文件夹中： ``` %USERPROFILE%\PowerAppsControl\ ├─ Plans\ 已保存的自然语言测试计划（*.md） └─ Sessions\<app>_<timestamp>\ ├─ session.mp4 会话录制 ├─ report.html 自包含的 HTML 报告（在任何浏览器中打开） ├─ report.json 原始结果数据 └─ screenshots\ 每个步骤的截图（失败 + 截图步骤） ``` HTML 报告包括 KPI 瓦片（运行次数、通过率、平均持续时间、窗口）、嵌入式视频、每个运行的可展开步骤表和内联截图，以及 **可重复的、纯英文的测试计划**（适用于烟雾会话）。 --- ## 需求 - **Windows 10/11**，**.NET 10 SDK**（`net10.0-windows`）。 - **FFmpeg** 用于视频录制。您不必手动安装它 - 安装程序提供获取它，您可以运行 `PowerAppsControl.exe --ensure-ffmpeg` 或调用 `ensure_ffmpeg` MCP 工具（winget first，然后是用户直接下载）。如果没有 FFmpeg，会话仍然运行并报告 - 只是没有视频。要指向现有二进制文件，请将 `POWERAPPSCONTROL_FFMPEG` 设置为 `ffmpeg.exe`。 ## 安装（来自发布版本） 从 [发布页面](https://github.com/ilyafainberg/PowerAppsControl/releases) 获取最新版本： - **安装程序（推荐）：** 下载 `PowerAppsControl-<ver>-setup.zip`，解压，运行 `.exe`，按照向导操作。构建版本未签名，因此 Windows SmartScreen 可能会显示“未知发布者” - 选择 **更多信息 → 运行任何方式**。安装程序 **自动注册** PowerAppsControl 作为 MCP 服务器与 **Microsoft Scout** 和 **GitHub Copilot CLI**（如下文所述），并在卸载时注销。 - **便携版：** 下载 `PowerAppsControl-<ver>-portable-win-x64.zip`，解压到任意位置，运行 `PowerAppsControl.exe`。无需管理员权限，无安装程序。它是自包含的（捆绑 .NET 运行时），因此它在干净的机器上运行。注册它只需一个命令： ```powershell .\PowerAppsControl.exe --register ``` 使用 `SHA256SUMS.txt` 验证您的下载。 ## MCP 客户端注册 PowerAppsControl 可以注册到两个支持的 MCP 主机 - 无需手动 JSON 编辑： ```powershell PowerAppsControl.exe --register # 将服务器 + 技能添加到 Scout + GitHub Copilot CLI PowerAppsControl.exe --unregister # 从两者注销 PowerAppsControl.exe --ensure-ffmpeg # 如果缺少则安装 FFmpeg（视频录制） PowerAppsControl.exe --check-update # 检查 GitHub Releases 以获取新版本 PowerAppsControl.exe --update # 下载 + 安装最新版本（带有进度条） PowerAppsControl.exe --help # 用法 ``` `--register` 将一个条目合并到（保留所有其他内容）： | 主机 | 配置文件 | 条目 | |------|-------------|-------| | GitHub Copilot CLI | `%USERPROFILE%\.copilot\mcp-config.json` | `mcpServers["PowerAppsControl"]` | | Microsoft Scout | `%USERPROFILE%\.copilot\m-mcp-servers.json` | `servers["powerappscontrol"]` | Scout 条目仅在存在该文件时写入（即 Scout 已安装）。工具列表通过反射发现，因此它始终与服务器公开的内容匹配。**在注册后重启 Scout / Copilot CLI** 以使更改生效。 ### 配套技能（/PowerAppsControl） 注册还会安装一个 **配套技能**，该技能教会代理端到端工作流（打开和验证 → 选择模式 → 记录会话 → 报告）。如果没有它，代理会看到工具但不知道如何按顺序使用它们。它已安装到 **两个主机** - `%USERPROFILE%\.copilot\m-skills\PowerAppsControl\`（Scout，以及技能元数据条目）和 `%USERPROFILE%\.copilot\skills\PowerAppsControl\`（GitHub Copilot CLI）。通过 `/PowerAppsControl` 显式调用它，或只需说“测试我的 power app <url>”。 `--unregister` 从两者中删除它。 该技能还通过 **主机原生选择器**（Scout 中的 `m_ask_user`）驱动所有可点击的决策（模式选择、计划批准），因为大多数主机不支持服务器自己的 `ask_user_choice` 依赖的 MCP **诱导** 功能。 ## 更新 PowerAppsControl 从 **GitHub Releases** （无后端）更新。 `--check-update` 报告是否存在新版本； `--update` 下载正确的资产（可移植 zip 或安装程序，与您安装的匹配）并带有进度条，并通过等待主机关闭然后重新注册来应用它。代理也可以调用 `check_for_update` / `update_server` MCP 工具。更新后，**重启您的 MCP 主机** 以加载新版本。 ## 构建和运行 ```powershell dotnet build PowerAppsControl.sln -c Release # 直接作为 MCP stdio 服务器运行： dotnet run --project src/PowerAppsControl -c Release ``` ### 仓库布局 ``` PowerAppsControl.sln 解决方案（根） global.json .NET SDK 固定 src/PowerAppsControl/ MCP 服务器项目（源 + 技能） installer/ Inno Setup 脚本 + 更新帮助程序 .github/workflows/release.yml 标记触发的发布管道 docs/ 演示视频 + 资产 ``` ### 手动注册（如果您更喜欢自己编辑配置） ```json { "mcpServers": { "PowerAppsControl": { "command": "C:\\path\\to\\PowerAppsControl.exe" } } ``` 将 `command` 指向已安装/便携的 `PowerAppsControl.exe`（或开发期间的 `bin\Release\net10.0-windows\` 生成输出）。 ## 环境变量 | 变量 | 效果 | |----------|--------| | `POWERAPPSCONTROL_FFMPEG` | `ffmpeg.exe` 的显式路径，用于录制。 | | `POWERAPPSCONTROL_REQUIRE_WINDOW_SELECTION` | `0`/`false`/`off` 禁用桌面引擎窗口选择门控（默认开启）。 | ## 安全 这些工具驱动用户的 **真实桌面和真实 Power App** - 没有沙盒。代理被指示不要在没有明确确认的情况下提交创建/删除真实记录、发送消息或进行购买的表单，并避免在多窗口负载运行期间进行破坏性操作。 ## 许可证 在 **GNU General Public License v3.0 或更高版本（GPL-3.0-or-later）** 下许可 - 参见 [LICENSE](LICENSE)。作者：Ilya Fainberg。