| name | web-preview-and-debug |
| description | 当需要在浏览器中预览网页、调试前端实现、验证 UI 交互或捕获页面状态以辅助分析时必须使用本技能 |
网页预览与调试(Web Preview and Debug)
概述
网页预览与调试是前端交付的关键闭环。本技能提供从启动本地服务器到浏览器验证的完整动作流程,确保 UI/交互 改动在真实可访问环境中被验证。
何时使用
- 新增或修改前端组件、页面、样式后。
- 修复样式异常、交互 bug 或响应式布局问题时。
- 需要向用户展示运行效果或确认视觉还原度时。
- 需要捕获页面状态(报错、布局、截图)以辅助分析时。
不适用
- 纯后端接口测试。
- 无需浏览器环境的单元测试或脚本验证。
- 无法通过浏览器访问的 headless 流程。
工作流
-
确认本地预览命令
- 读取项目
package.json、README 或相关配置文件,确认本地 dev 脚本。
- 常见命令如
npm run dev、pnpm dev、python -m http.server。
-
启动本地预览服务器
- 运行项目本地预览命令,确认服务器已监听并输出可访问地址。
- 若需要图形界面,启动本地 IDE/Agent 图形会话并在浏览器中打开。
- 若预览/调试耗时较长或需持续运行,可将其转为后台任务并记录任务 ID,稍后通过后台任务列表查询状态。
-
操作真实浏览器(如需)
- 对于需要登录态、动态内容、截图、点击验证的场景,通过本地浏览器桥接服务连接浏览器扩展。
- 使用 Chrome DevTools Protocol 进行导航、截图、读取页面内容。
- 避免使用安装了大量扩展或主 profile 冲突的浏览器实例;优先使用隔离浏览器 profile。
-
回退到公开页面抓取(仅限静态公开内容)
- 若页面是公开静态内容且无需登录态或交互,可获取 URL 内容做快速检查。
-
记录并反馈
- 将发现的 console 报错、布局异常、交互失败、截图与页面状态记录并返回给主任务。
- 每条记录必须附带对应的 URL、视口尺寸与操作步骤。
常见错误
- 未确认本地服务器已启动就尝试访问。
- 在需要登录态或动态交互的场景中仍使用静态抓取。
- 浏览器桥接扩展未连接,或使用了冲突扩展的浏览器主 profile。
- 截图/页面内容未附带对应的 URL 与视口尺寸说明。
- 将长时间后台预览任务遗忘,未查询任务状态。
快速参考
| 意图 | 动作 |
|---|
| 启动项目本地预览 | 运行项目 dev 脚本 |
| 打开图形化 IDE/Agent 会话 | 启动本地 IDE/Agent 图形会话并打开浏览器 |
| 操作真实浏览器验证 | 通过本地浏览器桥接服务连接隔离浏览器 profile |
| 获取公开页面文本 | 获取 URL 内容 |
| 查询后台预览/调试任务 | 查询后台任务列表 |