架构

四端 UI、协议、服务端、引擎、会话文件，自上而下五层。

架构一览

五层：四端 UI / 协议 / 服务端 / 引擎 / 会话文件。

apps/*四端 UI（Web · Desktop · CLI · Mobile）

@spark/protocol27 种事件词表 · zod schema · Transport

apps/serverFastify · SSE · 仅绑定 127.0.0.1

@spark/engineInputQueue → RunLoop → ToolPipeline

sessions/*.jsonldurable append-only · 完整可回放

↓ data flow: user input → engine → events → UI

事件模型

27 种事件构成完整词表（durable 24 / live-only 3），每种事件带三个属性：

durable: 24 种。落盘到 JSONL，可回放重建
live: 3 种 delta 类。不落盘，重连后不重现
surface: 2 种。模型可见面，必进模型历史

两个「投影」不同义：各端用同一份 applyEvent reducer 把事件流折叠成 UI 状态；引擎侧 Projector 投影的是模型上下文（surface 事件 → LlmMessage）。协议层是运行时代码，不是类型定义。新增事件走 new-event-type 全流程：类型定义 → zod schema → 归类 → reducer 单测 → 引擎 emit → 文档同步。

四端形态

共享 @spark/protocol，各自适配平台特性。

Web
主力交互界面，全功能覆盖
React 19 · Vite 7 · Tailwind CSS v4
Desktop
本地壳，系统集成与快捷键
Electron sidecar · 内嵌 server
CLI
终端原生体验，纯键盘操作
Ink 7 · Node.js 24
Mobile
移动端会话查看与轻量交互
Expo + RN · Taro 4 小程序

数据落点

会话数据以 append-only JSONL 存储在本地文件系统，不依赖外部数据库。

bash

# 会话数据落点（packages/engine/src/session/store.ts）
~/.spark/sessions/<cwd-munged>-<sha1前8位>/<ISO时间戳>_<sessionId>.jsonl

# 格式：append-only JSONL
# 第 0 行是 header（sparkVersion / cwd / createdAt / model）
# 其后每行一个事件信封，seq == 文件行号
# 只追加不改写，完整保留决策链
# 回放 = 从头逐行 reduce → 重建完整 UI 状态