Menu
Hub 内嵌浏览器预览 localhost 应用。 Use when: 写前端代码、跑 dev server、需要看页面效果、调 UI、铲屎官说"看看效果"。 Not for: 后端纯 API 开发、不涉及页面的工作。 Output: 前端页面在 Hub browser panel 中实时预览。
| name | browser-preview |
| description | Hub 内嵌浏览器预览 localhost 应用。 Use when: 写前端代码、跑 dev server、需要看页面效果、调 UI、铲屎官说"看看效果"。 Not for: 后端纯 API 开发、不涉及页面的工作。 Output: 前端页面在 Hub browser panel 中实时预览。 |
| triggers | ["看效果","看看页面","preview","浏览器预览","打开浏览器","pnpm dev","dev server","localhost","前端效果","看看 UI","HMR","热更新"] |
Hub 内置了嵌入式浏览器面板（F120），可以直接预览运行中的 localhost 应用。猫猫写完前端代码不用让铲屎官切浏览器看效果。
pnpm dev / npm start / vite 等）localhost:port 按 Go改代码 → HMR 热更新 → browser panel 内页面自动刷新，无需手动操作。
铲屎官说过："别手动让我输入，你最好打开浏览器，把页面放出来。"
猫应该主动替铲屎官打开浏览器，不要等铲屎官点 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（已修复） | 升级到最新代码 |
html 参数（后端不支持）；简单 HTML 可视化用 html_widget rich block铲屎官拍板："简单的用富文本，复杂的用猫主动打开浏览器。"
| 场景 | 方式 | 怎么做 |
|---|---|---|
| 简单可视化（图表、动画、计算器） | 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 定向发送，不会全局广播 |
html_widget rich block 内联渲染${TMPDIR}/cat-cafe-evidence/...，不要落仓库根目录（见 refs/evidence-output-contract.md）cat_cafe_preview_open — 服务器没跑 = proxy erroropen 命令打开系统浏览器 — F120 是 Hub 内嵌预览，走 iframe，不走系统浏览器/api/preview/auto-open 的 curl — 主路径是 cat_cafe_preview_open| Skill | 关注点 |
|---|---|
| browser-preview（本 skill） | Hub 内预览 localhost 前端页面 |
tdd | 写代码的测试驱动纪律 |
quality-gate | 开发完成后的自检（含对照设计稿） |
检测摩擦信号或陌生任务 → 搜证据确认重复 → 诊断根因 → 用代码修已有 harness 或建新 harness。 两种模式：Fix（确认重复后 → 写 hook/lint/guard）+ Build（反复出现的新任务类型 → Agent Team Leadership 规划新 skill/tool/流程）。 Use when: 铲屎官表达不满且搜证据确认历史上确实重复出现过同类问题（不是字面匹配"又"）、 连续 cancel 工具调用、收到反复出现的陌生任务类型且无对应 skill。 Not for: 一次性批评（搜证据未发现重复）、玩笑式"笨猫"（后跟哈哈哈）、 有明确 error message 的首次代码 bug（用 debugging）、reviewer P1/P2 反馈（用 receive-review）、 一次性新任务（直接做，不建 harness）。 Output: Rich block 诊断卡（根因 + 证据 + 建议）+ 可选 F128 新 thread 提议（平行修复不打断当前任务）。 GOTCHA: 不是每次被批评都弹诊断卡——必须先搜证据确认重复，才进入诊断流程。 过度触发 = 猫在逃避批评。一次性陌生任务直接做不建 harness，只有反复出现才沉淀。
跨 thread 协同：发现平行 session → 通知（3+2 件套）→ 争用协调 → 确认。 Use when: 平行 session 之间需要协同、通知改动影响、共享文件争用。 Not for: 跨猫工作交接（用 cross-cat-handoff）、需要新建 thread 时（用 propose_thread / thread-orchestration）。 Boundary with F128: 发现跨 scope 问题 → 先 list_threads 查有没有已有 thread → 有 = 本 skill（cross_post）→ 没有 = propose_thread。 Output: cross-post 通知 + 争用协调完成。
Feature 立项、讨论、完成的全生命周期管理。 Use when: 开个新功能、new feature、F0xx、立项、feature 完成、验收通过、讨论新功能需求。 Not for: 代码实现、review、merge（那些有专门的 skill）。 Output: Feature 聚合文件 + BACKLOG 索引 + 真相源同步。
合入 main 的完整流程：门禁检查 → PR → 云端 review → squash merge → Phase 文档同步 → 清理。 Use when: reviewer 放行后准备合入、开 PR、触发云端 review、准备 merge。 Not for: 开发中、review 未通过、自检未完成。 Output: PR merged + worktree cleaned。
富媒体消息发送：语音、图片、卡片、清单、代码 diff、交互选择。 Use when: 发语音、发图、发卡片、展示结构化信息、长结构化汇报、想发一堆文字/日志/步骤、庆祝、给我听听、给我看看、让用户选、确认操作。 Not for: 纯文字聊天、技术讨论、日常回复。 Output: rich block 附着在消息上。
大任务的主动拆解与多 thread 并行编排。 Use when: 任务涉及 2+ 个独立可交付子任务，需要不同猫参与、不同 thread 并行推进。 Not for: 单一任务（直接做）、已有 thread 之间的被动协调（用 cross-thread-sync）、单 session 内 subagent 并行（CLI 内置能力）、发现跨 scope 问题但已有归属 thread（用 cross_post_message，不要新建 thread）。 Output: 子 thread 创建 + 选猫 + 各 thread 交付 + 主 thread 汇聚报告。