[Bug] Agent 运行时前端反复断开重连 (ping timeout) — 后台任务阻塞 Socket.IO 心跳

[VanemKrAu]

Bug Report: Agent 运行时前端反复断开重连（ping timeout）

描述

在使用 Agent 进行小说创作协作时，前端（Electron 桌面版）频繁出现"断开连接 → 自动重连"，严重干扰写作流程。连接日志显示断连原因为 ping timeout。

环境

• OpenFic 版本：0.10.2（桌面版）
• 操作系统：Windows
• 模型：自定义 OpenAI 兼容 provider（CommandCode 的 deepseek/deepseek-v4-flash）
• 项目规模：百万字级别长篇小说（大量章节、设定、角色）

复现步骤

1. 打开一个较大的项目
2. 在 Agent 会话中发送消息，触发 Agent 运行（同时可能有后台章节摘要任务在跑）
3. 观察连接状态：频繁显示断开并自动重连

日志证据（runtime/logs/connect.log）

[2026-08-26T11:53:19.487Z] socket event=disconnected url=http://127.0.0.1:52940 transport=websocket active=true message=ping timeout
[2026-08-26T11:53:20.070Z] socket event=reconnect-attempt url=http://127.0.0.1:52940 transport=websocket attempt=1
[2026-08-26T11:53:40.073Z] socket event=connect-error url=http://127.0.0.1:52940 transport=websocket active=true message=timeout
[2026-08-26T11:53:41.826Z] socket event=reconnect-attempt url=http://127.0.0.1:52940 transport=websocket attempt=2
[2026-08-26T12:00:51.918Z] socket event=disconnected url=http://127.0.0.1:52940 transport=websocket active=true message=ping timeout
[2026-08-26T12:04:32.122Z] socket event=disconnected url=http://127.0.0.1:57375 transport=websocket active=true message=ping timeout

断连后重连也出现 connect-error timeout，说明后端在断连期间完全无响应（连新连接都无法建立），持续数分钟。

根因分析（源码定位）

1. Socket.IO 心跳超时配置偏紧 — backend/app/socket/server.py:

sio = socketio.AsyncServer(
    async_mode="asgi",
    ping_interval=25,   # 25 秒一次心跳
    ping_timeout=20,    # 20 秒无响应即判定断连
)

当后端事件循环被大任务短暂阻塞超过 20 秒时，前端即判定 ping timeout 并断连。

2. 后台 worker 与 WebSocket 服务器共用同一事件循环 — backend/app/background/runtime/supervisor.py:

worker = BackgroundWorker(...)
self._worker_tasks.append(asyncio.create_task(worker.run()))  # 同一 asyncio 事件循环

后台任务（章节摘要批量生成、检索索引、上下文压缩）与 Socket.IO 心跳处理运行在同一个 asyncio 事件循环。百万字项目的摘要批次任务会持续长时间运行（日志显示每 30-60 秒一个章节摘要），期间任何同步阻塞（LLM 流式响应、大 SQLite 事务、向量索引）都会饿死心跳处理，导致 ping 超时。

3. 断连期间重连也失败：主事件循环被占满时，新的 WebSocket 连接也无法被接受（日志 connect-error timeout），放大为"断连后长时间连不上"。

影响

• Agent 协作创作时频繁断连重连，打断写作流程
• 重连期间可能丢失部分实时事件（Agent 进度、工具结果）
• 大项目 + 自动摘要场景下问题尤其严重

建议修复

1. 调大心跳超时：ping_interval=60, ping_timeout=60 或更高，容忍正常的后台任务阻塞
2. 后台 worker 与主事件循环隔离：将 BackgroundWorker 放到独立进程（ZMQ transport 已经支持跨进程，background_zmq_job_endpoint 目前是 inproc://，可考虑改为真正的进程间通道），或用 asyncio.to_thread 包装同步阻塞操作
3. 断连后快速恢复：确保新连接在事件循环繁忙时也能被优先接受

临时规避（供其他用户参考）

• 将 server.py 的 ping_timeout 调大到 60 秒可显著缓解（已验证有效）
• Agent 使用时暂停自动章节摘要任务可减少事件循环压力

[panda-april]

已定位到主要根因并提交修复：#376

根因核实（对 issue 中的分析做了一点修正）：后台 worker 与 Socket.IO 共用事件循环属实，但后台任务本身都是 async（aiosqlite / 异步 LLM 客户端 / LanceDB async API），正常不会饿死心跳。真正的阻塞源是 #187 引入的 seed_bundled_encodings()——每次 token 计数都会把约 5.6MB 词表无条件重写到 tiktoken 缓存目录，而这个计数在代码里是高频操作（auto-compact 逐消息计数且每轮 LLM 调用重数全上下文、角色列表接口逐条目计数、每个后台摘要任务创建 LLM 客户端时也会触发）。大项目下累计 GB 级同步磁盘 I/O 全部落在事件循环上，心跳无响应 → ping timeout，阻塞期间新连接握手也排队 → connect-error timeout，与日志现象一致。

Windows 上还有两个放大器：Defender 对临时目录实时扫描；tiktoken ≥0.13 校验缓存哈希，行尾被 autocrlf 转成 CRLF 的检出上校验必失败，每次加载还会"删缓存 + 联网重下"。

修复内容（backend/app/core/utils/tiktoken.py）：

• seeding 改为"缓存已存在即跳过"（每机器一次，而非每次调用）；
• 原子写（临时文件 + os.replace）；
• 加载失败时从内置资源重建缓存重试，离线场景比 fix(backend): 修复离线环境下的分词表加载失败的问题 #187 时更稳。

热路径微基准：预热后 1000 次计数约 0.1s（修复前每次约 11MB 同步 I/O）。

关于 issue 里的建议：调大 ping_timeout 可以作为临时缓解，但阻塞期间 UI 依旧无响应；worker 进程隔离对本根因非必要。另有一个不在本 PR 范围的次要阻塞源供后续参考：内置 embedding 向量模型首次加载仍会同步阻塞事件循环（最长约 120s），如果修复后仍在首次建索引时断连，可以往这个方向查。