Cloud Agent 开发笔记(3)：Web 交互与数据持久化

上一篇搭好了 Agent 引擎和 Tool 体系：query() 能跑、Tool 能调、安全有 pathGuard 兜底。但这一切都是在服务端发生的。Agent 生产的事件怎么到浏览器？消息怎么存才能让用户刷新页面不丢？多个会话同时跑怎么互不干扰？用户点了停止怎么办？

这四个问题串起了 CLI 到 Web 的最后一段路：Agent 的结果要送到浏览器，浏览器的用户要能随时回来接着聊。

事件怎么到浏览器：SSE 还是 WebSocket

Claude Code 的输出端是终端渲染器（Ink + React），事件通过 AsyncGenerator 直接传给 React 组件，没有网络传输这一步。V2 需要一套从服务端到浏览器的流式协议。

两个选项：WebSocket 还是 SSE？WebSocket 双向通信，能力更强。但 V2 的交互模式本质是单向的：服务端推送流式结果，客户端只在初始请求和点"停止"时发信号。SSE 更轻，原生支持断线重连，Hono 内置支持，不需要额外库。因此选了 SSE。

对于前端接收方式，浏览器有 EventSource API，原生处理 SSE，但它不支持自定义 headers，加不了 JWT token。所以用 fetch + ReadableStream 手动解析 SSE 字节流。多写了点代码，但认证链路不需要妥协。

线缆格式很直接：

event: text
data: {"content": "..."}

event: tool_result
data: {"tool_use_id":"xxx","content":"...","is_error":false}

定义了 10 种事件类型覆盖对话全部状态：

一轮 query() 调用中事件的典型时序：

时间 →

  text ─── text ─── content_block_start ─── content_block_delta* ─── content_block_stop ─── tool_result ─── usage ─── done
  (LLM 思考)       (开始调 Tool)            (参数逐个到达)          (参数完整)          (执行结果)     (token 统计)  (结束)

  中间可能穿插多轮：
  ... ─── content_block_start ─── content_block_delta* ─── tool_result ─── text ─── content_block_start ─── ...
         (第二轮 Tool 调用)                                            (LLM 基于结果继续分析)

事件命名有个小插曲。最初是沿用了V1版本中类似消息类型的名字，后来翻 Claude Code 源码发现它的事件名更简洁（text、tool_use、tool_result），就统一过去了。

多用户多会话：状态怎么隔离

SSE 把事件推到了浏览器，但一个用户可能同时开着好几个Session，也就是对话。

Claude Code 也有多会话——一个进程里切来切去、--resume 恢复历史对话。但那是单用户的，所有会话共享同一个文件系统和权限上下文。V2 是 Web 应用，多个用户同时在线，各自的会话各自跑，谁也不能看到别人的消息、串到别人的 SSE 流里。

Zustand store 按 sessionId 分区。每个会话的消息、SSE 连接状态、工具执行状态都存在独立的分区里。用户从会话 A 切到 B 时，A 的 SSE 流在后台继续跑到结束，不会因为切走了就被强行终止。B 的消息从独立分区加载，不会和 A 的数据串到一起。

这个设计踩过一个坑：切换会话时 SSE 事件串到了另一个会话里。排查发现是 store 没有严格按 sessionId 隔离：收到 SSE 事件后直接往"当前会话"的数组里 push，没检查事件的 sessionId 和当前显示的 sessionId 是否一致。修完之后加了分区边界检查，tool_use 的 running 状态也按 sessionId 独立追踪。

切会话后后台流继续跑的设计有一个副作用：后台流跑完最后一轮时 tool_result 事件没有地方显示。用户切回来时看到的是完整结果，看不到工具执行的中间状态。体验不够好，但业务侧的对话轮数通常在 3 到 5 轮，后台跑完很快。没做更复杂的恢复逻辑，属于"知道不完美但优先级不够"的范畴。

打断对话：中断不只是 abort

多会话跑起来了，"用户点了停止按钮要怎么办"这件事就绕不开了。

Claude Code 的中断通过 AbortController 实现：调用 abort() 终止 LLM 流式请求，清理当前轮次的中间状态。V2 延续了这个机制，但 Web 场景多了一个硬要求：前端要给即时反馈。用户点了"停止"不能等后端处理完才更新 UI，那体验太差了。

前端的设计：点"停止"瞬间，立即将所有 running 状态的 tool_use 标记为 error、清除 streaming 状态。用户点下去就看到 UI 反应。后端的中断是异步完成的，前端不用等。

AbortController 存在 sessionAbortControllers 这个 Map 里，按键是 sessionId。中断触发后，后端的处理链路如下：

用户点"停止"
  │
  ▼
POST /api/sessions/:id/interrupt
  │
  ▼
abortController.abort('user_interrupt')
  │
  ▼
query() 循环内 5 个检查点（按执行时序）：
  │
  ├──[1] 每一轮循环开始前
  │       如果已中断 → yield user 消息，return
  │
  ├──[2] LLM 流式处理期间（每收到一个事件都检查）
  │       正在接收 tool_use → 为当前 + 已收集的全部 tool_use 生成 synthetic tool_result
  │
  ├──[3] LLM 调用抛错后的 catch 块
  │       区分"LLM 自己报错"还是"中断导致抛错" → 后者走 synthetic tool_result 逻辑
  │
  ├──[4] 工具执行前
  │       LLM 返回了 tool_use 但还没执行 → 为所有 tool_use 生成 synthetic tool_result
  │
  └──[5] 工具执行期间
         Promise.race([executionPromise, abortPromise]) → 中断胜出 → synthetic tool_result

synthetic tool_result 的核心作用：假设 LLM 刚返回了 3 个 tool_use 块（读文件、查数据库、写报告），用户点了停止。这 3 个 tool_use 成了"孤儿"——LLM 发出了指令，但没有 tool_result 返回给它。如果下一轮对话以这个不一致的状态开始，LLM 会困惑：上一轮它要求执行了 3 个操作，为什么没有结果？

解决办法：为每个"孤儿"tool_use 生成一个占位结果，内容为 [工具执行已被用户中断]，标记为 error。下一轮对话开始时消息列表是自洽的：每个 tool_use 都有对应的 tool_result，虽然结果是"中断"，但状态一致。

数据持久化：消息、元数据、大文件各放各的

SSE 流通了，消息到了前端，但一刷新就没了。

Claude Code 的消息持久化依托于 transcript 文件。进程活着时在内存里，进程退出时写进文件。这是单机 CLI 的心智模型。Web 用户随时可能刷新页面或关闭浏览器，多用户系统也不能假设只有一个进程。

面对一堆风格不同的数据，我选择了三种存储机制：

JSONL 存消息内容

消息的写入模式很单一：流式追加。LLM 每吐一个字、每个 tool_result 产生，都是 append 到末尾。没有修改、没有删除、没有复杂查询。JSONL 天然匹配这个模式：每行一个 JSON 对象，文件路径 data/messages/{sessionId}.jsonl，append 就完事，不需要事务、建索引、migration。读的时候逐行加载，解析成本比 SQL 查询低。删除会话时直接删文件，和生命周期绑定。

SQLite 存结构化元数据

用户、项目、会话、文件元信息、技能注册表、LLM 配置、MCP 服务器配置、系统配置。这些数据需要关联查询、筛选、排序。比如"某用户启用了哪些技能"要 JOIN 两张表，文件系统做这件事要么遍历所有文件要么自己维护索引。这正是关系型数据库最擅长的。

为什么是 SQLite 而不是 MySQL 或 PostgreSQL？最直接的理由是零运维。Bun 内置 bun:sqlite，编译进二进制，没有独立进程、没有连接字符串、没有端口。WAL 模式下的并发读性能不差，单文件备份和恢复极其简单。

但还有一个往前看的考虑：为集群部署预留迁移路径。 SQLite 的局限很清楚，只有一个写入者，做不到多实例共享。但 SQLite 的 schema 设计可以按关系型数据库的方式做——建表、建索引、理清关联关系。将来需要多实例部署时，这些表结构迁移到 PostgreSQL 或 MySQL 直接能用，不用重新设计数据模型。当前用 SQLite，但不是"将就着用"，而是"按标准设计，当前用最简单的实现"。

哪些数据适合关系型数据库，哪些适合文件系统

这个划分靠数据的访问模式决定，不靠直觉。

适合关系型数据库的： 用户、项目、会话、文件元信息、技能注册表、用户技能禁用记录、LLM 配置、MCP 服务器配置、系统配置。共同特征：结构化字段、需要条件筛选和关联查询、写入频率低、需要事务保证一致性。

适合文件系统的： 消息 JSONL、上传文件、工具执行结果、技能 SKILL.md 正文。共同特征：体积大、顺序读写、不需要复杂查询、按 ID 或路径直接定位。上传文件是二进制大对象，放数据库里会让备份和迁移变得非常重。技能 SKILL.md 有一个额外的理由：LLM 运行时通过 Read 工具直接读文件系统，放数据库里要多一层转换。

集群化文件系统怎么做，目前没实现，但分析过可行方向。

四个方案，按复杂度从低到高：

方案一：共享存储挂载。 所有实例挂同一个 NAS/NFS 卷，data/ 目录指向共享路径。最简单，但 NAS 本身是单点，网络延迟对 JSONL 频繁 append 的影响需要实测。

方案二：对象存储。 上传文件和工具结果迁到 MinIO 或 S3。适合大文件，但对 JSONL 的逐行追加语义支持不好，需要额外封装。

方案三：分布式文件系统。 GlusterFS 或 Ceph，多节点冗余、自动分片。运维负担重，以当前的业务体量杀鸡用牛刀。

方案四：应用层会话亲和。 不做文件系统层面的集群化，而是让同一个 sessionId 的请求始终路由到同一个实例。Sticky session 把问题从"文件系统怎么共享"变成"路由怎么亲和"，零存储改造。代价是实例宕机时该会话暂时不可用，但恢复后文件在本地磁盘上不会丢。当前业务体量下，这个方案最务实。

当前是单实例，不需要集群化文件系统。但四个方向在架构设计时都考虑过，确保将来不会因为"数据放文件系统所以改不了"卡住。

已存储的关系型数据

当前 SQLite 有 9 张表，统一用 aac_ 前缀命名：

前四张是核心业务链路：用户→项目→会话→文件。后面五张是配置和能力扩展，分别对应技能系统、MCP 集成、LLM 接入和系统级开关。

表之间的关系：

aac_users (1) ────── (N) aac_projects (1) ────── (N) aac_sessions
                              │                         │
                              │                         └── (N) JSONL 消息文件
                              │                              (data/messages/{sessionId}.jsonl)
                              │
                              └── (N) aac_files
                                     │
                                     └── (N) 磁盘文件
                                            (data/projects/{projectId}/files/)

aac_skill_registry (N) ──── (N) aac_user_disabled_global_skills
      │                                    │
      └── (N) 磁盘文件                      └── 用户级禁用开关
           (data/skills/{name}/SKILL.md)

aac_sys_config ─── 独立配置项，无外键关联
aac_llm_configs ── 独立配置项，运行时按 is_active 选择
aac_mcp_servers ── 独立配置项，启动时初始化连接

核心链路是两条：业务链和能力链。

业务链 用户 → 项目 → 会话 → 文件 的设计思路：

• 用户登录后首先面对的是项目列表。一个项目对应一个业务场景——比如"2025年度审计"、"供应商对账"。项目是文件的上传边界和会话的组织容器：上传 Excel 对账单到项目 A，在项目 B 的会话里是看不到这些文件的。

• 会话挂在项目下，一个项目可以有多个会话——可能是一次分析任务的完整对话，也可能拆成"数据清洗""分析""写报告"三个独立会话，取决于用户的习惯。消息 JSONL 跟着会话走，删除会话时对应的消息文件一并清理。

• 文件属于项目而非会话，这是一个刻意设计。同一个 Excel 对账单可能在多个会话里被引用——先在一号会话里清理数据，再在二号会话里做分析。如果文件跟着会话走，换个会话就要重新上传。文件元信息存 aac_files 表，实际文件在 data/projects/{projectId}/files/，这样不管从哪个会话引用，路径都是稳定的。

能力链是另一条独立的配置链路：技能注册表 ↔ 用户禁用开关，MCP 服务器配置、LLM 接入配置、系统配置各自独立。

对于aac_skill_registry和aac_user_disabled_global_skills的实际作用，在下一篇文章中会再做分析。

项目目录下的文件管理：上传、生成和保护

除了 JSONL，还有两类数据直接落磁盘：用户上传的文件、Agent 生成的输出。都放在 data/projects/{projectId}/files/ 下同一个目录，但通过数据库aac_files表的 source 字段区分身份：

• user_upload：用户上传的原始文件（Excel、PDF、Word）。Agent 可以读，不能改也不能删。
• temp：Agent 在执行过程中生成的中间文件和输出。Agent 可以自由读写。
• final_output：用户手动标记的输出文件。和上传文件一样，Agent 不能动。

用数据库字段而不是目录结构来区分，是因为一个文件的身份可能变——Agent 生成的报告初稿是 temp，用户审查完标记为定稿就变成 final_output。如果是按目录隔离（上传放 /uploads/，生成放 /output/），改身份就得移动文件、更新所有引用路径。改一个字段比搬运文件省事得多。

上传文件的保护在 02 的 pathGuard 里已经提过：checkFileWritable 检查 source，遇到 user_upload 或 final_output 直接拒绝写入。从存储视角看，这意味着 Agent 可以在项目目录里自由创建、修改文件，但用户手动上传的原始数据和用户确认的最终结果被锁住了，不会因为 LLM 的一次误操作被覆盖。

工具执行的大结果走另一条路：超过 100KB 的不回传给 LLM，持久化到 data/projects/{projectId}/tool-results/{toolUseId}.txt，LLM 只收到路径加前 2000 字节的预览。单个响应内所有工具结果的总字符数有 20 万上限，防止一轮对话里几个大文件同时返回把上下文窗口撑爆。

Chat 路由里的持久化逻辑很保守：先写盘，再推 SSE。SSE 推失败（客户端断了），消息已经落盘了。不会出现"看到一半刷新页面，中间几条消息丢了"的情况。

下一篇聊能力扩展层：Skill 系统和 MCP 集成在 Web 多租户下的设计。