cursor-control-ui

用途

cursor-control-ui 用于通过本地浏览器自动化来验证 UI 行为，并留下可核查的证据。它面向本地 UI 验证、截图与无障碍检查等场景，帮助在发布前确认 Web、IDE 或 Electron 界面的实际表现。

主要能力

复现依赖真实浏览器焦点、键盘输入、滚动、缩放或渲染的 UI 缺陷。
用截图和快照验证视觉或无障碍改动。
在发布前检查本地 Web、IDE 或 Electron 行为。
采集控制台日志、网络日志、CPU 性能分析、追踪或堆快照。
为 verify-this 创建前后对比证据。

使用方式

设置模式

使用仓库文档中的开发命令在本地启动应用。
发现已有的本地测试装置：Playwright 测试、Cypress 规格、Storybook、浏览器脚本、Electron 启动脚本或快照工具。
对于 Web 应用，用已有的浏览器工具连接本地 URL。
对于 Electron/Chromium，在支持时启用远程调试端口。
通过稳定的应用标记选择正确的页面，而不是仅依赖标签页顺序。
优先使用无障碍角色、标签和稳定的 data-* 选择器，而不是坐标。

通用 Web 测试装置

尽可能使用仓库已安装的浏览器工具。如果仓库已有 Playwright，一个最小的一次性探针如下：

import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
await page.goto("http://127.0.0.1:<port>");
await page.getByRole("button", { name: /submit/i }).click();
await page.screenshot({ path: "/tmp/ui-harness-after.png", fullPage: true });
await browser.close();

除非用户要求，不要仅为该探针把 Playwright 添加为项目依赖。优先使用已有的开发依赖或环境中已可用的外部浏览器工具。

通用 CDP 测试装置

对于 Electron 或使用 --remote-debugging-port=<port> 启动的 Chromium 应用，通过 CDP 连接：

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP("http://127.0.0.1:<debug-port>");
const pages = browser.contexts().flatMap((context) => context.pages());
let page;
for (const candidate of pages) {
  if (await candidate.locator("<app-root-selector>").count()) {
    page = candidate;
    break;
  }
}

if (!page) {
  console.log(await Promise.all(pages.map(async (p) => ({
    title: await p.title(),
    url: p.url(),
  }))));
  throw new Error("No matching app page found");
}

await page.screenshot({ path: "/tmp/ui-harness-cdp.png", fullPage: true });
await browser.close();

将 <app-root-selector> 替换为当前仓库中的稳定标记，例如根应用节点、地标或产品特定的 data-* 属性。

交互循环

在操作前捕获页面快照或截图。
从最新的页面结构中选择目标。
只执行一个结构性操作：点击、输入、按键、拖拽、滚动、导航或缩放。
捕获新的快照/截图。
验证预期的状态变化。
当用户要求证据时，保存用于前后对比的产物。

CDP 能力

仅当更高层浏览器 API 不足时使用原始 CDP：

性能：CPU 性能分析、追踪、绘制闪烁、FPS 计、布局偏移检查。
内存：堆快照和强制 GC，用于泄漏调查。
网络：请求拦截、限流、禁用缓存、请求/响应日志。
渲染：视口变更、配色方案模拟、减少动态效果、无障碍检查。
调试：控制台流式输出、异常捕获、DOM 快照。

页面选择

当多个应用窗口/标签页共享调试端口时：

优先为被测界面使用正向标记，例如应用根选择器。
必要时使用负向标记以避免选错界面。
如果没有页面匹配，列出可用的页面标题和 URL，而不是猜测。

适用场景

本地 UI 验证与截图。
无障碍检查。
复现依赖真实浏览器行为的 UI 缺陷。
发布前检查本地 Web、IDE 或 Electron 行为。
采集控制台、网络、性能或内存证据。

限制与护栏

导航或结构变化后，不要依赖过期的元素引用。
除非在点击前立即捕获了新的截图，否则避免坐标点击。
保持测试数据本地且可丢弃。
除非用户明确同意，不要存储来自隐私敏感工作区的截图或堆快照。
不要硬编码来自其他仓库的选择器、端口或脚本路径。发现当前仓库的本地应用标记。
完成后清理开发服务器、调试会话和临时配置文件。

边界说明

在遵循上游步骤之前，请根据当前 Codex 会话中实际可用的内容来解析所命名的技能、工具、连接器和账户。不要从该镜像推断连接、认证、额度或运行时一致性。保留上游命名的外部产品，并在需要时报告具体缺失的能力。