CodeNomad 浏览器预览与 SideCar
打开会话浏览器
- 在对话工具栏中选择打开网页预览。
- 输入不含凭据的
http://或https://预览 URL，然后选择打开预览。使用工具栏导航、刷新和后退/前进。 - 使用预览关闭按钮返回聊天。在该对话中重新打开即可继续。
每个预览属于其项目文件夹和会话。切换对话、项目、信息或聊天会隐藏已显式打开的原生访客页面，但不丢弃活动文档/历史。隐藏页面不是自动化目标。关闭项目/窗口或重启渲染器会结束活动文档。
保存的历史只在显式重新打开该会话浏览器时恢复，而非启动/选择会话时。它保存 URL 和游标，不保存未发送表单、DOM、POST 正文或 JavaScript 内存。历史受每会话 32 个 URL 和共享布局预算限制；旧条目可能被裁剪。恢复 URL 可能重新加载页面；不是事务重放。
共享登录与自动化边界
在同一桌面引擎和配置文件/配置范围内，原生预览跨项目/会话共享 cookie、登录和站点存储，与可信 CodeNomad 渲染器分开。在一个预览中退出站点会影响使用该存储的其他预览。文档、表单、会话存储、导航历史和自动化附件仍归各会话所有。iframe 预览不是完整共享原生浏览器配置文件。
| 客户端 | 预览实现 | 智能体浏览器自动化 | 移动模板 |
|---|---|---|---|
| 支持的桌面平台上的 Electron | 原生 Chromium 访客页面 | 支持可见且归属已确认的会话预览 | Android/Chromium 身份、触摸和像素密度仿真 |
| Windows Tauri | 原生 WebView2 子窗口 | 支持可见且归属已确认的会话预览 | Android/Chromium 身份、触摸和像素密度仿真 |
| macOS/Linux Tauri | 沙箱 iframe | 无原生浏览器自动化 | 仅尺寸 |
| 普通浏览器/远程视图 | iframe 后备实现 | 无本地原生预览目标 | 仅尺寸 |
原生自动化在桌面启动时准备好，使用会话绑定的 codenomad.browser 工具进行打开、导航、快照、截图和页面操作：点击、输入、选择、悬停、拖动、滚动、按键以及等待文本出现。工具可用不代表对每个窗口都已获授权：执行会检查所属后端、原生能力、会话和可见目标。如果操作所针对的页面在此期间已被隐藏、替换或导航离开，该操作会被拒绝，而不会发送到其他页面；操作也绝不会被自动重复。页面内容仍不可信。目标禁止嵌入时 iframe 可能失败；请使用外部浏览器，不要削弱保护。
选择六种视口模板之一
- 打开预览视口菜单。
- 选择下列模板。直接使用纵向/横向条目；没有单独旋转控件。
- 进入/更改移动仿真或返回仅尺寸模板时，预期会发生原生重新加载。
| 模板 | CSS 视口 |
|---|---|
| 响应式视口 | 可用预览空间 |
| 桌面视口 | 1440 × 900 |
| 平板视口 | 768 × 1024 |
| 平板横向 | 1024 × 768 |
| 手机视口 | 390 × 844 |
| 手机横向 | 844 × 390 |
原生移动模板仅对所属访客页面设置 Android/Chromium 身份、方向、触摸和 DPR 2.75。返回响应式/桌面/平板会清除覆盖值并重新加载。iframe 后备实现只调整尺寸。这些是可重现的布局参考，而非 Safari/Firefox 仿真，也不模拟手机键盘、浏览器/系统栏或移动操作系统文字设置。切换模板前请保存页面工作，因为重新加载可能丢弃未发送页面状态。
注册 SideCar
- 在 CodeNomad 后端主机上单独启动网页工具，监听
127.0.0.1:<port>。 - 打开设置 → SideCars。输入名称和端口；检查推导出的基础路径（
/sidecars/<id>）。 - 将协议设为匹配上游服务，并选择前缀模式。
- 选择添加 SideCar，然后从主页选择打开 SideCar打开其标签页。
| 选择 | 精确影响 |
|---|---|
| HTTPS（表单默认） | CodeNomad 以上游 https://127.0.0.1:<port> 连接。 |
| HTTP | CodeNomad 以上游 http://127.0.0.1:<port> 连接。不改变公共 CodeNomad 连接的 TLS 设置。 |
| 移除前缀（默认） | /sidecars/<id>/path 转发到上游时变为 /path。 |
| 保留前缀 | /sidecars/<id>/path 原样转发到上游。请相应配置服务自身基础路径。 |
注册是服务器配置，由客户端共享；既不安装也不启动服务。端口位于后端主机，而非查看用的笔记本电脑或手机。运行中表示可达，不表示工具应用/认证正常。移除注册不会停止单独启动的进程。关闭标签页也不会停止它。
不可达时，检查后端进程和端口。HTML 可加载但资源/WebSocket 失败时，检查工具基础路径和前缀模式。以目标设置重新创建错误注册；不要仅为绕过代理错误而公开上游。SideCar 应用可能以服务器账户权限提供终端或文件；请信任其用户和配置。
SideCar 是 CodeNomad 的可信扩展，而不是沙箱预览：其页面以 CodeNomad 自身的源运行，因此其脚本可以凭借你的登录访问权限使用 CodeNomad。只注册你信任其代码的服务。CodeNomad 不会将自身的登录 cookie 转发给该服务，但会保留该服务自己的 cookie。远程控制不暴露 SideCar 应用代理流量；请使用远程访问和远程控制中描述的适当直接访问路径。
OpenVSCode Server 示例
- 在后端主机运行 Docker，将服务绑定到回环地址：
docker run -it --init -p 127.0.0.1:8000:3000 -v "${HOME}:${HOME}:cached" -e HOME=${HOME} gitpod/openvscode-server --server-base-path /sidecars/vscode
- 注册名称
VSCode、端口8000、协议HTTP、前缀模式 保留前缀。 - 验证显示基础路径为
/sidecars/vscode，然后打开 SideCar。
此 Shell 示例将主目录挂载到容器中；如果编辑器只应访问更小范围，请缩小挂载。服务的 --server-base-path 必须与注册精确匹配。完成后单独停止容器；删除 SideCar 不会移除容器或其文件。
ttyd 终端示例
- 在后端主机上启动绑定回环地址的可写 Shell 终端：
ttyd --interface 127.0.0.1 --writable zsh
- 注册名称
Terminal、端口7681、协议HTTP、前缀模式 移除前缀。 - 在显示的
/sidecars/terminal基础路径打开 SideCar。
终端以启动 ttyd 的账户权限运行。zsh 不可用时选择其他 Shell。若更改 ttyd 默认端口，请使用实际端口，并在完成后单独停止 ttyd。为 CodeNomad 访问启用认证并加以保护；可写终端不是沙箱。