实时协作（Liveblocks）
工作区代码编辑器支持多人实时协作：协作者同时打开同一个工作区时，编辑的内容会实时同步到彼此的编辑器，工具栏显示在线人数。基于 Liveblocks 云服务，无需自建服务器。
开启方式
实时协作依赖一个环境变量：
| 变量 | 说明 |
|---|---|
LIVEBLOCKS_SECRET_KEY | 在 Liveblocks 注册（免费额度足够日常使用）→ 项目设置 → Secret Keys 复制 Secret key（以 sk_dev_ 开头）。 |
配置后重新部署（本地开发则重启 dev server），打开任意工作区 → 代码 标签页即可看到实时协作状态：
- 🟢 绿色徽章：
实时协作已开启或N 人在线—— 实时连接正常 - ⏳ "正在连接实时协作..." —— 正在建立连接（几秒内完成）
- （无任何徽章）—— 未配置
LIVEBLOCKS_SECRET_KEY，或连接失败，自动降级为离线编辑，功能不受影响
功能细节
- 实时同步：同一工作区有多个协作者在线时，文件内容的修改实时广播到所有人（基于 Liveblocks Storage）
- 文件切换跟随：你当前编辑的文件路径会同步给协作者，方便知道彼此在看什么
- 只读协作者也能看到实时更新，只是无法编辑/保存
- 每个工作区对应一个独立的 Liveblocks Room（
cfos-ws-<workspaceId>），互不串扰
权限
实时协作的鉴权由本应用自行完成（/api/liveblocks/auth）：
- 只有工作区所有者和已受邀协作者能加入该工作区的房间，其他用户拿不到 token
- token 为 HS256 签名的 JWT，有效期与登录会话一致，过期后 Liveblocks 自动通过回调刷新
- 未登录用户无法加入任何房间
故障与降级
| 场景 | 表现 |
|---|---|
未配置 LIVEBLOCKS_SECRET_KEY | 打开代码页不显示实时徽章，纯离线编辑 |
| Secret key 无效 / 网络被墙 | 尝试连接约 5 秒后自动放弃，降级为离线编辑，编辑器照常可用 |
| 连接中途断开 | 协作者在线人数归零，本地编辑不丢失；下次进入页面会重新尝试连接 |
实时同步是"尽力而为"的协作增强，不会取代保存。请仍然点击 保存（或 Ctrl/Cmd+S）把修改持久化到服务器——文件历史/回滚始终以服务器保存的版本为准。
隐私说明
实时协作内容经过 Liveblocks 的加密 WebSocket 传输；房间 ID 不包含文件内容本身，只有获得授权的用户才能拿到加入房间的 ID token。若对数据出境有顾虑，可完全不配置 LIVEBLOCKS_SECRET_KEY，本应用保持纯离线协作模式。