| 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 | 开发完成后的自检(含对照设计稿) |