Devlab Web Visual Ops

DevLab Web Visual Ops — Web 视觉化操作

Purpose

对 Web 应用做可重复的视觉化操作：观察页面、导航、交互、检查（Console/Network/Runtime）、验证、截图捕获，并沉淀为 Debug / UI Review / Visual Regression / E2E / Browser Automation 五类 Workflow 的标准化产物。

定位边界（与 Stagehand 的关系）：Stagehand 本质是 AI Browser Automation；本技能是范围更大的 Web Visual Operations。因此 Stagehand 是 Router 层的 AI Adapter 之一，不是 Skill 底座。Console/Network/Trace/截图/视觉回归/UI Review 是 Skill 自己的核心能力，不抽象成"Stagehand 能力"，避免被具体框架绑死。

适用条件

• 目标是有浏览器 UI 的 Web 应用（SPA / 微前端 / MPA 均可）；
• 需要浏览器端到端执行的操作：视觉走查、UI 审查、页面调试、截图对比、视觉回归、浏览器自动化；
• 执行环境可运行 Node ≥ 18 + Playwright。浏览器获取方式可选（三选一）：① npx playwright install chromium 自动下载到 ms-playwright 缓存；② 复用已有 ms-playwright 缓存；③ 系统 Chrome/Edge（executablePath 或 channel）。无头模式默认可用：Playwright 与 Vision/CUA 路径还可用更轻的 chromium_headless_shell（实测三项全 PASS）。
• Stagehand AI 增强路径需 Node ≥ 22.18.0 + newapi 消费 key（chat_default 模型，见 infra-aimodel-ops）；必须完整 Chromium（headless 模式即可，实测全 PASS），headless shell 不支持扩展注入（实测失败）；
• 无 DOM 或 DOM 不可靠的场景（canvas / 复杂 iframe / 纯视觉渲染）走 Vision/CUA 兜底。

核心设计：三层架构

devlab-web-visual-ops
│
├── Core      能力原语（Observe / Navigate / Interact / Inspect / Validate / Capture）
├── Router    执行路由（Playwright / Stagehand / DevTools / Vision-CUA）
└── Workflows 业务闭环（Debug / UI Review / Visual Regression / E2E / Browser Automation）

1. Core 定义"做什么"，与具体执行器解耦；所有 Workflow 只调用 Core 原语。
2. Router 决定"用谁执行"：默认确定性执行（Playwright）；AI 增强/非确定性页面切 Stagehand；Console/Network/Runtime 检查走 DevTools；无 DOM 走 Vision/CUA。统一输入 task + page，统一输出 action / observation / extraction 协议，保证执行器可替换。
3. Workflows 组装"业务闭环"：每个 Workflow 是 Core 原语 + Router 选路的固定编排，输出标准化产物。

资产结构

.visual-ops/
├── artifacts/          # 产物：screenshots/ traces/ hars/ 报告/ 视频
│   ├── baselines/      # 视觉回归基线（更新需用户确认 HD-3）
│   └── reports/        # Debug / UI Review / Regression 报告
├── cases/              # E2E / 自动化用例（复用 devlab-web-test-e2e 约定）
└── config.local.*      # 项目侧本地覆盖（不入库）

工作流

0. 入口：意图解析与 Router 判定

1. 读取 ~/.harness-ai-kit/config.yaml 的 assets.devlab-web-visual-ops 段（preview_base_url / preview_start_command / stagehand_enabled 等）；缺失时按项目探测。
2. 按用户意图归类到 Workflow（Debug / UI Review / Visual Regression / E2E / Browser Automation）；意图不明确时询问用户。
3. 按下表选择 Router 执行器；执行器不可用时按降级路径切换并记录原因。

Router 选择规则

切换执行器时在报告中记录 router: 切换原因。详细适配器操作见 references/REFERENCE-ROUTER-ADAPTERS.md。

Core 能力原语

Workflows

各 Workflow 详细步骤与判定规则见 references/REFERENCE-WORKFLOWS.md。

Integration Points

约束

• 不绑定单一框架：Stagehand 只作为 Router 的 AI Adapter；新增/替换执行器不改 Skill 骨架，只改 Router 插槽与 REFERENCE-ROUTER-ADAPTERS.md。
• Stagehand 依赖 pin ==4.0.0（v4 破坏性变更：无 agent、无 MCP client；Node ≥ 22.18.0）；本地模式走 localBrowser.launch + generate callback，无需 Browserbase key；newapi 结构化请求用 forced tool call（HD-4）。
• Vision/CUA 已实现（v0.1.2）：本地视觉驱动（截图 + newapi 多模态模型 + forced tool call），无需专用 CUA 模型；CUA 执行闭环中导航/点击类自动执行，不可逆操作（表单提交/删除/数据修改）必须 HD-1 确认（HD-5）。
• 写操作默认拦截：表单提交、删除、修改数据等不可逆操作前必须 🔔 HUMAN-DECISION [HD-1]。
• 基线更新必须确认：视觉回归基线覆盖前必须 🔔 HUMAN-DECISION [HD-3]。
• 依赖版本 pinned；外部公开依赖统一写入 skill.json 的 environment / runtime_requirements，不在正文硬编码版本。
• 产物默认落 .visual-ops/；缓存、临时文件、凭据不入库、不入正式文档。
• Router 切换需记录原因，禁止静默降级。

专题引用

• references/REFERENCE-ROUTER-ADAPTERS.md — Router 四类执行器的启用条件、典型命令/API、降级路径。
• references/REFERENCE-WORKFLOWS.md — 五类 Workflow 的步骤序列、判定规则与产物规范。
• references/REFERENCE-INDEX.md — 专题文档导航。

输出模板

DevLab Web Visual Ops 报告
════════════════════════════════════════
Target: {preview_base_url | URL}
Router: {playwright | stagehand | devtools | vision}
Workflow: {debug | ui-review | visual-regression | e2e | automation}
Time:   {timestamp}

[执行摘要]
  操作数: {n}
  验证结果: {PASS | FAIL | BLOCKED}

[发现]
  - {severity}: {finding} (证据: {artifact 路径})

[产物]
  - {artifact 类型}: {路径}

结论: {conclusion}

建议:
  1. {recommendation_1}
  2. {recommendation_2}

示例

场景：前端项目反馈"列表页偶发白屏，控制台有报错，但本地复现不稳定"。 调用本技能 Debug Workflow：

1. Router 判定：Console/Network 检查 → DevTools；复现交互 → Playwright。
2. Inspect：抓 Console 错误与 Network 失败请求，定位疑似未捕获的 API 异常。
3. Capture：录制 trace + 截图，标记失败时间点。
4. 输出 Debug 报告：根因、复现步骤、修复建议、trace 产物。 合格输出：报告包含根因结论、可复现路径、证据产物路径。

Human Decisions