结果预览
本页讲 Bot 如何把做好的网页、服务、桌面应用和小程序发布成预览，群成员怎么在浏览器里直接查看和操作。
Bot 在成员的机器上干活，它启动的服务只监听那台机器。预览通过机器与服务器之间的隧道，把结果送到群成员的浏览器里，不需要谁去访问 localhost。
预览的种类
预览由 Bot 在运行中自己发布，没有手动创建的按钮。直接告诉 Bot 你想看什么即可，例如：
@前端助手 把 todo-app 跑起来，发个预览给大家看看| 种类 | 适用场景 | 卡片上显示 |
|---|---|---|
| 网页 / 服务 | Bot 启动的开发服务器、接口服务（HTTP 与 WebSocket 都可以） | :端口 与路径 |
| 静态页面 | 工作区里的 HTML 报告、构建产物，不需要起服务 | :端口 与路径 |
| 桌面应用 | Electron、Tauri 等桌面应用的窗口实时画面 | 桌面应用 · 服务名 |
| 小程序 | 在机器上的微信开发者工具里打开，推送模拟器画面 | 小程序 · 页面路径 |
几点说明：
- Bot 启动服务（托管服务）和打开小程序项目会运行代码，和 Bot 执行命令一样按权限档位与命令审批规则处理，见 审批与提问。
- 托管服务由 Bot 所在的机器运行，这一轮结束后仍在运行。每个 Bot 最多同时托管 5 个服务。
- 同一个端口、同一个桌面应用、同一个小程序项目只保留一张预览卡片。小程序再次发布时，原卡片切换到新页面。
- 桌面应用只推送这个应用进程的窗口，不推整个屏幕。
预览卡片
Bot 发布预览后，群里出现一张预览卡片，显示首屏截图（小程序为模拟器截图）、状态和地址。
卡片状态：
| 状态 | 含义 |
|---|---|
| 在线 | 可以打开 |
| 离线 | Bot 所在的机器不在线 |
| 服务已停止 | 预览背后的服务已退出，卡片保留 |
| 已关闭 | 预览已关闭 |
点截图，在工作台打开预览（仅在线时可点）。卡片上的按钮：
| 按钮 | 作用 | 谁能用 |
|---|---|---|
| 打开 | 在浏览器新标签页打开（网页类） | 群成员 |
| 在工作台打开 | 在右侧工作台打开 | 群成员 |
| 启动服务 | 服务已停止时重新启动 | Bot 主人、群管理员 |
| 公开链接 | 生成给外部人员的链接，见 公开分享 | Bot 主人、群管理员 |
| 重新截图 | 刷新卡片上的截图（桌面应用除外） | Bot 主人、群管理员 |
| 停止穿透 / 停止穿透和服务 / 关闭预览 / 关闭预览并停止应用 | 关闭预览，并停止背后的服务或应用 | Bot 主人、群管理员 |
| 重新开放 | 已关闭的卡片重新开放，并重新启动服务 | Bot 主人、群管理员 |
其他入口
- 群里所有打开中的预览，会以标签形式显示在输入框上方，点标签可查看截图和操作。
- 「群设置 → 预览与服务」列出本群全部预览和托管服务，可在那里「在工作台打开」「关闭」预览，或「停止」托管服务。
预览工作台
预览在右侧工作台里以标签页打开，和 diff、文件等标签页并列。
- 「布局」可切换「分栏」「专注」「全屏」。快捷键：⌘\ 在分栏和专注之间切换，⌘⇧\ 全屏。
- ⌃Tab / ⌃⇧Tab 切换标签页，⌥W 关闭当前标签页；右键标签可「关闭」「关闭其他标签页」「关闭右侧标签页」。
- 最多同时开 12 个标签页。只有最近用过的 4 个网页标签保持加载，其余进入「休眠」，切回时重新加载。
- 手机上工作台全屏显示，点「返回聊天」回到群聊。
网页标签页的工具栏：
| 控件 | 作用 |
|---|---|
| 刷新 | 重新加载页面 |
| 进入路径 | 输入路径后回车，从这个路径重新进入；页面内的跳转不会同步到这里 |
| 视口尺寸 | 自适应 / 1440 / 1024 / 768 / 390，按预览分别记住 |
| 新窗口打开 | 在浏览器新标签页打开 |
| 公开链接… | 生成公开链接（Bot 主人、群管理员） |
服务停止时显示「服务已停止 · 等待 Bot 重新发布」，恢复在线后自动重新加载。
桌面应用与小程序的实时画面
桌面应用和小程序预览打开后是实时画面。有人在看时机器才推送画面。
远程操作
所有群成员都能观看，同一时间只有一个人能操作：
- 普通成员点「请求控制」，Bot 主人或群管理员在画面上「同意」或「拒绝」。
- Bot 主人或群管理员可以直接「开始控制」，有人在控制时可「接管控制」，也可「收回控制」。
- 正在控制的人显示「你正在控制」，用完点「交还控制」。停止观看会自动失去控制权。
控制时可以用鼠标点击、拖动、滚轮和键盘输入（包括中文输入法）。
工具栏可调「帧率」（自动 / 90 / 60 / 30 fps）和「画质」（自动 / 原画 / 超清 / 高清），还可显示画面数据（帧率、分辨率、码率、丢包、延迟、抖动）。
平台限制
| 场景 | 限制 |
|---|---|
| 桌面应用 | macOS、Windows 推送应用窗口；Linux 只能推送虚拟显示里的应用，需要 Bot 用虚拟显示方式启动服务 |
| 小程序实时画面 | 目前只支持 macOS 和 Windows |
| macOS 权限 | 推送画面需要「屏幕录制」权限，远程操作需要「辅助功能」权限 |
画面提示「机器未授权屏幕录制」或「机器未授权辅助功能，远程操作不会生效」时，请 Bot 主人在共工空间桌面端的「实时画面」页完成授权，见 权限与系统设置。
画面断开时会显示「N 秒后自动重试」，也可以点「立即重试」。
微信开发者工具引导
小程序预览依赖 Bot 所在机器上的微信开发者工具。卡在某一步时，画面上会出现引导，提示「请 Bot 主人在运行 Bot 的电脑上操作」：
| 提示 | 操作 |
|---|---|
| 请开启微信开发者工具的服务端口 | 打开微信开发者工具 → 菜单栏「设置 → 安全设置」→ 打开「服务端口」 |
| 请在微信开发者工具里允许共工空间访问 | 切换到微信开发者工具，在「Gonggong」授权弹窗中点击「允许」 |
| 请在微信开发者工具里信任此项目 | 切换到微信开发者工具，在「您信任此项目的作者吗？」弹窗中点击「信任并运行」；没有弹窗时查看开发者工具的编译输出 |
完成后自动继续。首次打开需要编译，可能要几十秒到一两分钟。
开发者工具没登录时，卡片提示「微信开发者工具未登录，请用微信扫码登录」，只有 Bot 主人和群管理员能看到二维码；其他成员看到「等待 Bot 主人登录微信开发者工具」。扫码后卡片自动切换到模拟器画面。
谁能访问预览
- 预览只对本群成员开放。从卡片或工作台打开时，共工空间自动完成身份校验，无需再登录。
- 预览地址直接发给群外的人是打不开的。要给外部人员看，由 Bot 主人或群管理员生成 公开链接。
- 常见提示：「请从共工空间的预览卡片打开这个预览。」「预览不存在或已关闭。」「链接已失效，请回到共工空间重新打开预览。」「预览所在的机器离线，稍后再试。」
空闲自动关闭
预览连续一段时间无人访问会自动关闭，默认 24 小时，由管理员在系统参数「预览无人访问后自动关闭」调整，见 系统参数。
- 打开页面、观看实时画面、重新截图都算访问。
- 关闭预览时，如果没有其他预览在用同一个服务，服务也一并停止。
- 卡片保留。Bot 重新启动服务，或 Bot 主人、群管理员在卡片上点「重新开放」即可恢复。
管理员
预览地址用独立域名还是端口段，由服务端部署决定，见 反向代理与预览域名。