深度分析 #4: WebUI 会话管理、LiveWire 事件总线与 Daemon API 响应结构

日期: 2026-06-23 | 循环分析第 4 轮

概述

本轮通过提取 WebUI 前端 JavaScript 完整逻辑，重建了 AtomCode 的 Web 端会话管理工作流、LiveWire 事件总线的完整事件类型/格式、以及 Daemon API 的所有响应数据结构。这是之前 42 份分析报告中完全未覆盖的领域。

---

1. Daemon API 完整响应结构（全部提取）

1.1 API Endpoints 汇总

方法	路径	请求结构	响应结构
GET	/health	—	HealthResponse { service }
POST	/shutdown	—	—
GET	/sessions	—	[]SessionDetail
GET	/cd	—	ChangeDirResponse { current_dir, project_hash }
POST	/cd	ChangeDirRequest { path, set_default }	ChangeDirResponse
GET	/projects/:hash/sessions	—	[]SessionDetail
GET	/projects/:hash/sessions/:id	—	SessionDetail
POST	/projects/:hash/sessions/:id/rename	RenameRequest { name }	—
GET	/models	—	[]ModelInfo { provider_type, is_default, effort_applicable }
POST	/chat	ChatRequest { message, images, provider, session_id }	SSE 流
POST	/chat/stop	StopChatRequest	—
GET	/chat/active	—	{ session_id }
GET	/tunnel/status	—	TunnelStatus { bind_host, reachable, remote_url, qr_svg }
GET	/skills	—	[]SkillInfo
POST	/fs/mkdir	FsMkdirRequest { path }	—
GET	/mcp/status	—	McpStatusResponse { servers: [McpServerStatus { name, tool_count }] }
POST	/mcp/reload	—	—
GET	/config	—	ConfigResponse { default_workdir }
POST	/config/reload	—	—
GET	/providers	—	[]ProviderInfo { ... }
PUT	/providers/:name/default	—	—
PATCH	/providers/:name/thinking	PatchThinkingRequest (6 字段)	—
POST	/auth/status	—	AuthStatusResponse { logged_in, auth_path }
POST	/auth/login/start	LoginStartRequest { open_browser }	LoginStartResponse { url, login_id, expires_in_seconds }
POST	/auth/login/:id/poll	—	LoginPollResponse
DELETE	/auth/login/:id	—	—
POST	/auth/logout	—	—
POST	/codingplan/setup	CodingPlanSetupRequest	CodingPlanSetupResponse { report_text, steps, ok, skipped }

1.2 WebUI 端使用的 API 请求结构

// 全部从 JS bundle 中提取

interface ChatRequest {
  message: string;
  images?: ImageData[];     // { media_type: string, data: string (base64) }
  provider?: string;
  session_id?: string;
}

interface RenameRequest { name: string; }
interface FsMkdirRequest { path: string; }
interface StopChatRequest {}
interface ChangeDirRequest { path: string; set_default?: boolean; }
interface CreateSessionRequest {}
interface PermissionDecisionRequest {
  decision: "allow" | "deny" | "always_allow" | "allow_persist" | "always";
  tool_name: string;
}
interface LoginStartRequest { open_browser: boolean; }
interface PatchThinkingRequest {
  thinking_budget?: number;
  thinking_type?: string;
  thinking_keep?: boolean;
  reasoning_history?: boolean;
  // 6 fields total
}

1.3 Provider 管理结构

interface ProviderInfo {
  provider: string;         // provider name
  provider_type: string;    // provider type
  model: string;
  is_default: boolean;
  effort_applicable: boolean;  // DeepSeek 特有
  has_api_key: boolean;
  ephemeral: boolean;
  // 15 fields total (ProviderConfig)
}

interface CreateProviderRequest {
  // 16 fields
}

interface PatchProviderRequest {
  // 19 fields
  clear_api_key?: boolean;
  clear_base_url?: boolean;
  user_agent?: string;
  max_tokens?: number;
  thinking_budget?: number;
  thinking_type?: string;
  thinking_keep?: boolean;
  reasoning_history?: boolean;
  skip_tls_verify?: boolean;
  set_default?: boolean;
}

---

2. LiveWire SSE 事件总线（完整格式重构）

之前 DEEP_ANALYSIS 报告覆盖了基本事件类型，但缺少 payload 结构和会话恢复机制。

2.1 所有 SSE 事件类型

事件类型	触发时机	关键 payload
snapshot	连接建立时	{ session_id, messages, provider }
state	状态变化	{ running: boolean }
user	用户输入	{ text, images? }
text	文本生成	{ content }
reasoning	推理过程	{ content }
tool_start	工具调用开始	{ id, name, arguments }
tool_output	工具输出流	{ chunk }
tool_result	工具结果	{ id, name, output, success, duration_ms }
tokens	Token 统计	{ prompt, completion, total }
provider	提供商切换	{ provider }
permission_request	权限请求	{ call_id, tool_name, reason, arguments }
done	完成	{ session_id }
stopped	停止	—
error	错误	{ message }
artifact_start	产物开始	{ artifact_type }
artifact_end	产物结束	—
artifact_type	产物类型	—

2.2 前端事件处理映射

// WebUI JS 中的事件分发逻辑
function handleEvent(e) {
  // snapshot → 会话恢复：接收完整消息历史 + 当前 provider
  // state → 更新 running/stopped 状态
  // user → 渲染用户消息（text + images）
  // permission_request → 弹出权限对话框（tool_name, reason, arguments）
  // text → 追加到当前 assistant 回复
  // reasoning → 追加到当前 assistant 的推理区
  // tool_start → 创建工具调用卡片（id, name, arguments）
  // tool_output → 追加到工具输出
  // tool_result → 更新工具状态（success/error, duration_ms）
  // tokens → 更新 token 统计
  // done → 保存 session_id，停止 loading
  // stopped → 停止 loading，清空工具批处理队列
  // error → 追加错误文本
}

2.3 会话恢复机制

当 WebUI 恢复一个历史会话时:

POST /chat (session_id=xxx) → SSE 流
  → 收到 snapshot 事件 { messages, provider, session_id }
  → 从 Messages 数组重建 UI 状态（包含用户消息、助理回复、工具结果）
  → 工具调用显示三种状态: pending → waiting_approval → done/error
  → 只需请求一个空消息即可恢复（通过 session_id 匹配）

2.4 工具调用状态机（WebUI 端）

工具调用: { id, name, args: string, status, output?, duration_ms? }
状态: 
  pending          → 等待执行
  waiting_approval → 等待用户批准（显示弹窗）
  done             → 执行成功
  error            → 执行失败

---

3. LiveWire /live/ 子 API

// WebUI 通过这些端点发送命令
POST /live/message      → { message, images?, provider?, session_id? }
POST /live/provider     → { provider }
POST /live/reasoning_effort → { reasoning_effort, provider? }
POST /live/permission   → { decision, tool_name }

这些 POST /live/* 与 /chat 配合工作:

• /live/message — 发送用户消息
• /live/provider — 切换提供商
• /live/reasoning_effort — 修改推理努力级别
• /live/permission — 响应权限请求

---

4. Chat 事件日志结构（telemetry 层）

从二进制提取的聊天事件的遥测日志字段:

interface ChatEvent {
  session_duration_secs: number;
  turns_completed: number;
  last_tool_name: string;
  last_event: string;
  tool_batch?: ToolBatch;
  calls: number;
  reasoning: boolean;
  tool_start: number;
  tool_output: number;
  tool_result: number;
  output: number;         // output tokens
  completion: number;     // completion tokens
  total: number;          // total tokens
  artifact_start: boolean;
  artifact_type: string;
  artifact_end: boolean;
  tool_calls: ToolCallInfo[];
  permission_request: boolean;
  call_ids: string[];
  stopped: boolean;
  image_data?: ImageData[];
  media_type: string;
}

---

5. Daemon 发现的服务信息结构

5.1 会话/项目管理

interface ProjectInfo {
  hash: string;
  previous_dir: string;
  recent_dirs: string[];
  session_count: number;
  last_updated: string;
}

interface SessionDetail {
  id: string;
  project_hash: string;
  name: string;
  created_at: string;
  updated_at: string;
  // via ConfigResponse
}

interface ChangeDirResponse {
  current_dir: string;
  project_hash: string;
}

5.2 健康 & 状态

interface HealthResponse {
  service: string;   // "AtomCode API server listening on http://..."
}

interface McpStatusResponse {
  servers: McpServerStatus[];
}

interface McpServerStatus {
  name: string;
  tool_count: number;
  // ...+ tool definitions
}

interface TunnelStatus {
  bind_host: string;
  reachable: boolean;
  remote_url: string;
  qr_svg: string;
}

5.3 提供商信息

interface ModelInfo {
  id: string;
  provider: string;
  provider_type: string;
  is_default: boolean;
  effort_applicable: boolean;
  // display_name, 等
}

---

6. Artifact 系统细节

之前未发现 artifact 系统:

事件	说明
artifact_start	产物开始（含 artifact_type）
artifact_end	产物结束
artifact_type	产物类型（如代码块、HTML 预览等）

Artifact 在工具调用/回复中被追踪，日志中包含 artifact_start、artifact_duration_ms、artifact_size 等信息。

---

7. SetupSteps/CodingPlanSetupResponse

interface CodingPlanSetupResponse {
  report_text: string;     // 设置报告文本
  steps: SetupStep[];      // 步骤列表
  ok: boolean;             // 是否成功
  skipped: boolean;        // 是否跳过
}

interface SetupStep {
  name: string;
  status: "ok" | "skipped" | "error";
  details?: string;
}

---

8. IDLE Timeout

Idle timeout: disabled

可配置的闲置超时设置，默认禁用。这控制 daemon 在用户消息之间空闲多久后自动关闭连接。

---

9. 已无新盲区 — 覆盖率评估

本轮是深度分析中最丰富的一轮。主要发现了:

1. Daemon API 响应结构 — 20+ 完整 TypeScript 接口
2. LiveWire 事件总线 — 15+ 事件类型的完整 payload 格式
3. WebUI 会话恢复 — snapshot 机制的完整工作流
4. 工具调用状态机 — WebUI 端的 4 种状态
5. ChatEvent 日志结构 — 17+ 字段
6. Artifact 系统 — 3 事件
7. SetupSteps — CodingPlan 设置状态机
8. Provider CRUD API — 创建/更新/删除的完整参数

---

结论

#	领域	之前状态	本次发现
1	Daemon API 响应类型	路径已知	20+ 完整接口定义
2	LiveWire 事件 payload	未覆盖	15+ 事件 payload 格式
3	WebUI 会话恢复	未覆盖	snapshot 重建 + 状态机
4	工具调用前端状态	未覆盖	4 态: pending→waiting→done→error
5	Artifact 系统	完全未覆盖	start/type/end
6	SetupSteps 状态机	完全未覆盖	ok/skipped/error
7	ChatEvent 对象	部分覆盖	17+ 字段

目前静态分析可覆盖的内容已基本耗尽。剩余未覆盖方向全部需要运行时环境（daemon 启动、VS Code 扩展、HarmonyOS 平台）。