Claude Code UI WebSocket 机制：一条消息的完整旅程，断线 3 秒自动重连

Claude Code UI WebSocket 机制一条消息的完整旅程断线 3 秒自动重连【免费下载链接】claudecodeuiUse Claude Code, OpenCode, Cursor CLI, and Codex on mobile and web with CloudCLI (aka Claude Code UI). CloudCLI is a free open source webui/GUI that helps you manage your Claude Code session and projects remotely.项目地址: https://gitcode.com/GitHub_Trending/cl/claudecodeuiClaude Code UICloudCLI是 Claude Code CLI 的 Web 与移动端界面实时会话完全靠一条 WebSocket 承载模型回复、工具结果、项目状态都从这条管道推回断线后 3 秒自动重连。一条消息的旅程从输入框到 Claude 的回复打开页面时App挂载WebSocketProvider整个浏览器只打开一条/ws连接。聊天视图、侧边栏、任务面板都订阅这条 socket任何模块不再各自开连接。发出一条消息要经过四步前端把内容打包成chat.send帧带 sessionId 和文本经sendMessage发出服务端用 sessionId 查 sessions 表取 provider 和项目路径不信任客户端传入的任何信息provider 运行时执行text、tool_use、tool_result等帧依次回传服务端给每帧编连续seq号并保留重放缓冲前端按kind字段做一次分支更新对应界面。双模式连接代理与令牌分别怎么用连接地址的构造在buildWebSocketUrlsrc/shared/context/WebSocketContext.tsx分两种模式平台模式与页面同域直连/ws走反向代理URL 不带令牌服务端直接取数据库中第一个用户作为身份开源OSS模式直连服务主机URL 追加?tokenJWT 在 HTTP upgrade 阶段校验一次失败则拒绝建连令牌过期函数返回null不创建 socket等认证状态刷新后再连。令牌介入的时机就在建连前OSS 模式下令牌出现在连接 URL 里握手完成前校验就结束了。4 类 WebSocket 消息实时会话推送如何落到界面下行帧按kind字段分类四类消息各管一块界面消息示例kind触发的界面变化聊天消息text/stream_delta回复区实时追加delta 按 100ms 批量刷新工具调用结果tool_use/tool_result渲染工具面板权限请求弹出横幅项目状态更新session_upserted/loading_progress刷新侧边栏会话行与项目扫描进度会话管理通知chat_subscribed/permission_request同步处理状态与待审批权限工具需要审批时服务端发permission_request用户点允许后前端回发chat.permission-response不批准工具就不会执行。3 秒自动重连是怎么触发的错过内容怎么补触发点很直白onclose里确认关闭的仍是最新 socket 时排一个 3 秒定时器再调connect()——无退避、固定 3 秒、循环重连。isConnected是 context 上的状态字段随时可读取当前连通性。重连后如何补上错过的消息连接重建后前端派发一个合成的websocket_reconnected事件服务端并不发这个帧。聊天组件收到后带着已见过的最大lastSeq重发chat.subscribe服务端先回权威 ack、再重放缓冲帧项目列表同时刷新数据。run 本身跑在服务端中途关标签页也不会中断。TaskMaster 广播项目更新、任务状态与 MCP 变更任务侧复用同一条/wssocket但帧按type分类是kind协议的例外。server/modules/taskmaster/taskmaster.routes.ts 里的broadcastTaskMasterUpdate是唯一的广播出口taskmaster-project-updated项目更新广播携带项目最新状态包括 MCP 服务器配置是否变更taskmaster-tasks-updated任务状态同步携带最新任务数据。广播对象限定在connectedClients集合全部/wssocket而不是服务端全量wss.clients——否则帧会泄漏到终端与插件代理的 socket。 移动端网络切换时连接如何保持手机经常切换网络项目的做法不是保证 TCP 不断而是让内容层在断开后能重新对齐响应式布局与触摸操作适配小屏切网断开后同样走 3 秒重试加chat.subscribe重放会话内容不丢终端 socket 有专门防护旧 socket 迟到的close事件无法 detach 已接管的存活 PTY。「保持连接」的实际含义是断开后状态能重建而不是物理链路永不中断。安全与资源JWT、权限控制与卸载清理JWT 认证只在 upgrade 阶段做一次OSS 模式校验令牌平台模式取数据库首个用户后续帧不携带凭据权限控制一个permission_request帧对应一次chat.permission-responserequestId 必须匹配防丢帧事件同步分发给各监听器同一 tick 内的连续帧不会被合并防内存泄漏组件卸载时清理函数把 socket 的 handlers 置空、close()、清掉重连定时器unmountedRef阻止卸载后再次触发connect。旧版本里这些逻辑分散在src/utils/websocket.js、src/contexts/WebSocketContext.jsx与server/utils/taskmaster-websocket.js当前版本已整合进下面指到的文件。排查连接问题先看哪些文件症状先看哪里socket 建不起来 / 立即断开WebSocketContext.tsx 的 URL 构造与认证分支帧到了界面不动useChatRealtimeHandlers.ts 的kind分支与lastSeq记录任务板不更新taskmaster.routes.ts的广播目标集合协议细节01-websocket-transport.md 与chat-websocket.service.ts排查时先打开WebSocketContext.tsx看isConnected、wsRef、reconnectTimeoutRef三个状态字段——连接问题大多能在这三行里找到答案。【免费下载链接】claudecodeuiUse Claude Code, OpenCode, Cursor CLI, and Codex on mobile and web with CloudCLI (aka Claude Code UI). CloudCLI is a free open source webui/GUI that helps you manage your Claude Code session and projects remotely.项目地址: https://gitcode.com/GitHub_Trending/cl/claudecodeui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考