WebSocket是实时协同标注系统的核心，通过语义化坐标、有序消息、断连恢复和权限分离实现秒级同步与稳定协作。
WebSocket 是网页端实时代码审查协同标注系统的核心通信机制，它让多人对同一份代码的评论、高亮、光标移动等操作真正“秒级同步”，而不是靠轮询或刷新。
批注必须精准绑定到代码行与字符范围
前端使用 CodeMirror 或 Monaco Editor 时，应监听用户选中代码的动作，调用编辑器 API 获取 lineStart、lineEnd、charStart、charEnd 等位置信息。服务端收到后，只存储这些逻辑坐标（不存像素值），并关联 fileId 和 userId。消息结构示例如下：
{
"type": "comment:add",
"payload": {
"fileId": "main.py",
"line": 42,
"charStart": 8,
"charEnd": 15,
"text": "这里建议加类型提示",
"userId": "u203"
}
}前端收到后，在对应行右侧渲染气泡，并支持点击展开详情；若该行已有多个批注，按 charStart 排序显示，避免重叠。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
多人光标需语义化广播，而非发送坐标
不要传 {x: 120, y: 80} 这类屏幕坐标——不同设备字体、缩放、换行策略不同，极易错位。应广播语义化指令：
- 用户开始选中 →
{type: "selection:start", fileId: "main.py", pos: 327} - 用户结束选中 →
{type: "selection:end", fileId: "main.py", pos: 341} - 光标移动 →
{type: "cursor:move", fileId: "main.py", line: 42, ch: 12}
每个光标标记用独立<span>插入文本流中（推荐零宽空格占位），再通过getBoundingClientRect()获取真实位置，套一层绝对定位容器显示头像和昵称。
消息有序性与断连恢复是稳定性的关键
所有 WebSocket 消息携带服务端生成的单调递增 seq 字段。前端维护本地已处理最大 seq，收到乱序旧消息直接丢弃；新消息按序排队应用。连接中断时：
- 前端自动重连（指数退避：1s → 2s → 4s）
- 重连成功后发送
sync:resume消息，附带最后收到的seq，服务端补推遗漏事件 - 断连期间新增批注暂存内存，超 5 分钟未恢复则提示导出草稿
权限与状态分离，前端只响应，不决策
用户能否添加/删除批注，不由前端判断，而由服务端在每次提交前校验其当前角色（如 reviewer / author）。服务端下发的消息中可含 canEdit: true 字段，前端据此控制气泡上的“删除”按钮是否可用。软删除批注时，仅标记 "isDeleted": true 并保留操作人与时间戳，方便审计与恢复。
不复杂但容易忽略
