web-preview-and-debug

name	web-preview-and-debug
description	当需要在浏览器中预览网页、调试前端实现、验证 UI 交互或捕获页面状态以辅助分析时必须使用本技能

网页预览与调试（Web Preview and Debug）

概述

网页预览与调试是前端交付的关键闭环。本技能提供从启动本地服务器到浏览器验证的完整动作流程，确保 UI/交互 改动在真实可访问环境中被验证。

何时使用

• 新增或修改前端组件、页面、样式后。
• 修复样式异常、交互 bug 或响应式布局问题时。
• 需要向用户展示运行效果或确认视觉还原度时。
• 需要捕获页面状态（报错、布局、截图）以辅助分析时。

不适用

• 纯后端接口测试。
• 无需浏览器环境的单元测试或脚本验证。
• 无法通过浏览器访问的 headless 流程。

工作流

1. 确认本地预览命令

   • 读取项目 package.json、README 或相关配置文件，确认本地 dev 脚本。
   • 常见命令如 npm run dev、pnpm dev、python -m http.server。

2. 启动本地预览服务器

   • 运行项目本地预览命令，确认服务器已监听并输出可访问地址。
   • 若需要图形界面，启动本地 IDE/Agent 图形会话并在浏览器中打开。
   • 若预览/调试耗时较长或需持续运行，可将其转为后台任务并记录任务 ID，稍后通过后台任务列表查询状态。

3. 操作真实浏览器（如需）

   • 对于需要登录态、动态内容、截图、点击验证的场景，通过本地浏览器桥接服务连接浏览器扩展。
   • 使用 Chrome DevTools Protocol 进行导航、截图、读取页面内容。
   • 避免使用安装了大量扩展或主 profile 冲突的浏览器实例；优先使用隔离浏览器 profile。

4. 回退到公开页面抓取（仅限静态公开内容）

   • 若页面是公开静态内容且无需登录态或交互，可获取 URL 内容做快速检查。

5. 记录并反馈

   • 将发现的 console 报错、布局异常、交互失败、截图与页面状态记录并返回给主任务。
   • 每条记录必须附带对应的 URL、视口尺寸与操作步骤。

常见错误

• 未确认本地服务器已启动就尝试访问。
• 在需要登录态或动态交互的场景中仍使用静态抓取。
• 浏览器桥接扩展未连接，或使用了冲突扩展的浏览器主 profile。
• 截图/页面内容未附带对应的 URL 与视口尺寸说明。
• 将长时间后台预览任务遗忘，未查询任务状态。

快速参考

意图	动作
启动项目本地预览	运行项目 dev 脚本
打开图形化 IDE/Agent 会话	启动本地 IDE/Agent 图形会话并打开浏览器
操作真实浏览器验证	通过本地浏览器桥接服务连接隔离浏览器 profile
获取公开页面文本	获取 URL 内容
查询后台预览/调试任务	查询后台任务列表