browser-preview - SKILL.md Agent Skill

name: browser-preview description: > Hub 内嵌浏览器预览 localhost 应用。 Use when: 写前端代码、跑 dev server、需要看页面效果、调 UI、operator说"看看效果"。 Not for: 后端纯 API 开发、不涉及页面的工作。 Output: 前端页面在 Hub browser panel 中实时预览。 triggers: - "看效果" - "看看页面" - "preview" - "浏览器预览" - "打开浏览器" - "pnpm dev" - "dev server" - "localhost" - "前端效果" - "看看 UI" - "HMR" - "热更新"

Browser Preview

Hub 内置了嵌入式浏览器面板（F120），可以直接预览运行中的 localhost 应用。猫猫写完前端代码不用让operator切浏览器看效果。

工作流

基础流程（端口发现 → 预览）

在 Terminal 启动 dev server（pnpm dev / npm start / vite 等）
Hub 自动检测端口 → 弹出 toast 提示"检测到 localhost:xxxx 启动"
点击 Open Preview → 自动打开 browser panel 并加载页面
也可以手动：切到 workspace 的 Browser tab，输入 localhost:port 按 Go

改代码 → HMR 热更新 → browser panel 内页面自动刷新，无需手动操作。

猫主动打开浏览器（Phase C — 必须掌握）

operator说过："别手动让我输入，你最好打开浏览器，把页面放出来。"

猫应该主动替operator打开浏览器，不要等operator点 toast 或手动输 URL。

调用步骤（按顺序执行，不要跳步）

Step 1: 确认目标服务器在跑
  curl -s -o /dev/null -w "%{http_code}" http://localhost:PORT
  → 200/301/304 = 可以继续
  → 000/connection refused = 服务器没起来，先启动再说

Step 2: 调用 typed MCP
  cat_cafe_preview_open({
    port: PORT,
    path: "/",
    worktreeId: "当前 worktreeId（有就传）",
    threadId: "当前 threadId（有就传）"
  })

Step 3: 等 1-2 秒，右侧 Browser panel 应自动打开
  → 如果没反应，检查 Step 1 是否真的返回了 200

工具参数

参数	必填	说明
`port`	是	dev server 端口号
`path`	否	页面路径，默认 `/`
`worktreeId`	建议传	传了保证精确送达；不传也能工作（走 global broadcast），但多 tab 场景可能误触其他 session

怎么获取 worktreeId：就是你当前工作的 worktree 目录名。例如你在 cat-cafe-f120-fix 目录里工作，worktreeId 就是 cat-cafe-f120-fix。如果你在主仓库 cat-cafe 里，就不需要传。

常见错误

现象	原因	修法
右侧无反应	目标服务器没在跑 / MCP callback 未配置	先 `curl localhost:PORT` 确认目标服务，再看工具返回错误
`{"error":"Proxy error","message":"socket hang up"}`	目标服务器已退出	重启服务器，再刷新 Browser panel
打开了系统 Chrome	用了 Playwright/Chrome MCP 等外部工具	不要用外部浏览器工具！ auto-open 是 Hub 内嵌预览，不是系统浏览器
两个重复 tab	React Strict Mode（已修复）	升级到最新代码

适用场景：写完前端代码后、operator说"看看效果"、需要展示复杂页面
⚠️ 不要传 html 参数（后端不支持）；简单 HTML 可视化用 html_widget rich block

两层可视化策略

operator拍板："简单的用富文本，复杂的用猫主动打开浏览器。"

场景	方式	怎么做
简单可视化（图表、动画、计算器）	`html_widget` rich block 内联渲染	用 `rich-messaging` skill 发 `html_widget` block
复杂应用（完整页面、多组件交互）	猫主动打开浏览器	调用 `auto-open` API

技术要点（猫猫需要知道的）

项目	说明
Preview Gateway	独立端口（默认 4100），反向代理 localhost 应用
为什么不直连	iframe 跨端口需要代理剥离 X-Frame-Options/CSP
iframe sandbox	`allow-scripts allow-forms allow-popups allow-downloads allow-same-origin`（安全：独立 origin）
WebSocket/HMR	代理层支持 WebSocket 升级，Vite/Next/Webpack HMR 正常工作
端口排除	Cat Cafe 自身端口（3003/3004/6398/6399/18888 等）自动排除
审计	每次 open/close/navigate 都有审计日志
Console 面板	bridge script 注入到 iframe，捕获 console.log/warn/error，在面板展示
一键截图	SVG foreignObject + canvas 截图，上传后端，toast 展示
多 Tab	同时预览多个 localhost 页面，Tab 切换独立状态
Socket room 隔离	preview 事件按 worktree room 定向发送，不会全局广播

什么时候主动用

写完前端组件/页面 → 主动调 auto-open 打开浏览器展示（不要等operator点）
调样式/布局 → 改代码后在 browser panel 里实时查看
operator说"看看效果"/"给我看看" → 主动打开 browser panel 展示
dev server 已在 Terminal 跑着 → 主动打开浏览器，不要只提示
简单可视化（图表/动画） → 用 html_widget rich block 内联渲染
Console 有报错 → browser panel 下方 Console 面板自动展开，可以看
需要截图 → browser panel 工具栏一键截图；默认先存到 ${TMPDIR}/cat-cafe-evidence/...，不要落仓库根目录（见 refs/evidence-output-contract.md）

不要做的事

不要跳过 Step 1（验证服务器）直接调 cat_cafe_preview_open — 服务器没跑 = proxy error
不要用 Playwright / Chrome MCP / open 命令打开系统浏览器 — F120 是 Hub 内嵌预览，走 iframe，不走系统浏览器
不要手写 /api/preview/auto-open 的 curl — 主路径是 cat_cafe_preview_open
不要手动去构造 gateway URL（让 Hub 前端处理）
不要尝试预览外部 URL（只支持 localhost）
不要预览 Cat Cafe 自身服务端口（会被端口验证拦截）
不要把临时截图顺手留在仓库根目录；要入库时再显式归档到正式目录

和其他 skill 的区别

Skill	关注点
browser-preview（本 skill）	Hub 内预览 localhost 前端页面
`tdd`	写代码的测试驱动纪律
`quality-gate`	开发完成后的自检（含对照设计稿）