# 状态管理系统

<cite>
**本文引用的文件**
- [src/hooks/use-chat.ts](file://src/hooks/use-chat.ts)
- [src/hooks/use-sessions.ts](file://src/hooks/use-sessions.ts)
- [src/hooks/use-workspaces.ts](file://src/hooks/use-workspaces.ts)
- [src/hooks/use-agents.ts](file://src/hooks/use-agents.ts)
- [src/hooks/use-settings.ts](file://src/hooks/use-settings.ts)
- [src/hooks/use-models.ts](file://src/hooks/use-models.ts)
- [src/hooks/use-skills.ts](file://src/hooks/use-skills.ts)
- [src/hooks/use-api-providers.ts](file://src/hooks/use-api-providers.ts)
- [src/hooks/use-im-channels.ts](file://src/hooks/use-im-channels.ts)
- [src/hooks/use-cron-tasks.ts](file://src/hooks/use-cron-tasks.ts)
- [src/hooks/use-task-executions.ts](file://src/hooks/use-task-executions.ts)
- [src/hooks/use-marketplace.ts](file://src/hooks/use-marketplace.ts)
- [src/hooks/use-agent-config.ts](file://src/hooks/use-agent-config.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 引言
本文件系统性梳理并解读本项目的“状态管理系统”，重点覆盖以下方面：
- 自定义 Hooks 的设计模式与实现机制：聊天状态、工作空间状态、会话管理、代理状态等
- 状态提升策略、上下文共享与状态同步机制
- 客户端状态缓存、数据持久化与离线支持策略
- 状态变更的触发机制、副作用处理与错误恢复
- 状态调试工具、性能监控与内存优化技巧
- 最佳实践与常见问题解决方案

## 项目结构
本项目采用“按功能域划分”的前端组织方式，状态管理以“自定义 Hooks + 类型定义 + 本地数据库”为核心：
- Hooks 层：封装各领域状态（聊天、会话、工作空间、代理、设置、模型、技能、IM、定时任务、执行记录、市场、代理配置）
- 类型层：统一定义消息、内容块、会话、代理、IM 渠道、定时任务等数据结构
- 数据层：基于 SQLite 的本地数据库，提供跨页面/实例的持久化能力，并承担迁移与一致性保障

```mermaid
graph TB
subgraph "Hooks 层"
HC["use-chat.ts<br/>聊天状态"]
HS["use-sessions.ts<br/>会话管理"]
HW["use-workspaces.ts<br/>工作空间"]
HA["use-agents.ts<br/>代理状态"]
HSE["use-settings.ts<br/>设置"]
HM["use-models.ts<br/>模型列表"]
HK["use-skills.ts<br/>技能"]
HAP["use-api-providers.ts<br/>API 提供者"]
HIC["use-im-channels.ts<br/>IM 渠道"]
HCT["use-cron-tasks.ts<br/>定时任务"]
HTE["use-task-executions.ts<br/>执行记录"]
HMP["use-marketplace.ts<br/>市场模板"]
HAC["use-agent-config.ts<br/>代理配置"]
end
subgraph "类型与数据"
T["types.ts<br/>数据模型"]
D["db.ts<br/>SQLite 持久化"]
end
HC --> T
HS --> T
HW --> T
HA --> T
HSE --> T
HM --> T
HK --> T
HAP --> T
HIC --> T
HCT --> T
HTE --> T
HMP --> T
HAC --> T
HC --> D
HS --> D
HW --> D
HA --> D
HCT --> D
HTE --> D
HAP --> D
HIC --> D
HMP --> D
HAC --> D
```

图表来源
- [src/hooks/use-chat.ts:1-696](file://src/hooks/use-chat.ts#L1-L696)
- [src/hooks/use-sessions.ts:1-81](file://src/hooks/use-sessions.ts#L1-L81)
- [src/hooks/use-workspaces.ts:1-77](file://src/hooks/use-workspaces.ts#L1-L77)
- [src/hooks/use-agents.ts:1-103](file://src/hooks/use-agents.ts#L1-L103)
- [src/hooks/use-settings.ts:1-56](file://src/hooks/use-settings.ts#L1-L56)
- [src/hooks/use-models.ts:1-31](file://src/hooks/use-models.ts#L1-L31)
- [src/hooks/use-skills.ts:1-77](file://src/hooks/use-skills.ts#L1-L77)
- [src/hooks/use-api-providers.ts:1-101](file://src/hooks/use-api-providers.ts#L1-L101)
- [src/hooks/use-im-channels.ts:1-77](file://src/hooks/use-im-channels.ts#L1-L77)
- [src/hooks/use-cron-tasks.ts:1-116](file://src/hooks/use-cron-tasks.ts#L1-L116)
- [src/hooks/use-task-executions.ts:1-98](file://src/hooks/use-task-executions.ts#L1-L98)
- [src/hooks/use-marketplace.ts:1-86](file://src/hooks/use-marketplace.ts#L1-L86)
- [src/hooks/use-agent-config.ts:1-165](file://src/hooks/use-agent-config.ts#L1-L165)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)

章节来源
- [src/hooks/use-chat.ts:1-696](file://src/hooks/use-chat.ts#L1-L696)
- [src/hooks/use-sessions.ts:1-81](file://src/hooks/use-sessions.ts#L1-L81)
- [src/hooks/use-workspaces.ts:1-77](file://src/hooks/use-workspaces.ts#L1-L77)
- [src/hooks/use-agents.ts:1-103](file://src/hooks/use-agents.ts#L1-L103)
- [src/hooks/use-settings.ts:1-56](file://src/hooks/use-settings.ts#L1-L56)
- [src/hooks/use-models.ts:1-31](file://src/hooks/use-models.ts#L1-L31)
- [src/hooks/use-skills.ts:1-77](file://src/hooks/use-skills.ts#L1-L77)
- [src/hooks/use-api-providers.ts:1-101](file://src/hooks/use-api-providers.ts#L1-L101)
- [src/hooks/use-im-channels.ts:1-77](file://src/hooks/use-im-channels.ts#L1-L77)
- [src/hooks/use-cron-tasks.ts:1-116](file://src/hooks/use-cron-tasks.ts#L1-L116)
- [src/hooks/use-task-executions.ts:1-98](file://src/hooks/use-task-executions.ts#L1-L98)
- [src/hooks/use-marketplace.ts:1-86](file://src/hooks/use-marketplace.ts#L1-L86)
- [src/hooks/use-agent-config.ts:1-165](file://src/hooks/use-agent-config.ts#L1-L165)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)

## 核心组件
- 聊天状态（use-chat）：负责消息流式渲染、权限请求、子代理内容、令牌统计与计时、中断控制、缓存与回放
- 会话管理（use-sessions）：会话列表、创建、更新、删除与刷新
- 工作空间（use-workspaces）：工作空间打开、移除、触达时间更新
- 代理（use-agents）：代理列表、创建、更新、删除、技能关联
- 设置（use-settings）：跨实例设置同步（DOM 事件）
- 模型（use-models）：模型列表获取
- 技能（use-skills）：技能 CRUD
- API 提供者（use-api-providers）：提供者 CRUD 与连通性测试
- IM 渠道（use-im-channels）：IM 渠道 CRUD
- 定时任务（use-cron-tasks）：任务 CRUD、心跳任务、手动执行
- 执行记录（use-task-executions）：分页加载、过滤
- 市场（use-marketplace）：模板 CRUD
- 代理配置（use-agent-config）：子代理与配置文件读写、字段更新、文件系统操作

章节来源
- [src/hooks/use-chat.ts:38-695](file://src/hooks/use-chat.ts#L38-L695)
- [src/hooks/use-sessions.ts:30-80](file://src/hooks/use-sessions.ts#L30-L80)
- [src/hooks/use-workspaces.ts:26-76](file://src/hooks/use-workspaces.ts#L26-L76)
- [src/hooks/use-agents.ts:47-102](file://src/hooks/use-agents.ts#L47-L102)
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)
- [src/hooks/use-models.ts:9-30](file://src/hooks/use-models.ts#L9-L30)
- [src/hooks/use-skills.ts:30-76](file://src/hooks/use-skills.ts#L30-L76)
- [src/hooks/use-api-providers.ts:36-100](file://src/hooks/use-api-providers.ts#L36-L100)
- [src/hooks/use-im-channels.ts:45-76](file://src/hooks/use-im-channels.ts#L45-L76)
- [src/hooks/use-cron-tasks.ts:47-115](file://src/hooks/use-cron-tasks.ts#L47-L115)
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
- [src/hooks/use-agent-config.ts:20-164](file://src/hooks/use-agent-config.ts#L20-L164)

## 架构总览
本系统采用“Hooks + 本地数据库 + 类型约束”的分层架构：
- Hooks 层：集中封装状态、副作用与网络交互；通过 ref 与缓存维持跨切换的流式体验
- 类型层：统一消息块、会话、代理、IM 渠道等模型，确保前后端契约一致
- 数据层：SQLite WAL 模式、外键约束、索引与迁移脚本，保证数据一致性与演进能力

```mermaid
graph TB
UI["UI 组件"] --> HC["use-chat"]
UI --> HS["use-sessions"]
UI --> HW["use-workspaces"]
UI --> HA["use-agents"]
HC --> API["后端 API"]
HS --> API
HW --> API
HA --> API
API --> DB["SQLite 数据库"]
DB --> FS["文件系统/配置目录"]
HC -.-> Types["类型定义"]
HS -.-> Types
HW -.-> Types
HA -.-> Types
```

图表来源
- [src/hooks/use-chat.ts:38-695](file://src/hooks/use-chat.ts#L38-L695)
- [src/hooks/use-sessions.ts:30-80](file://src/hooks/use-sessions.ts#L30-L80)
- [src/hooks/use-workspaces.ts:26-76](file://src/hooks/use-workspaces.ts#L26-L76)
- [src/hooks/use-agents.ts:47-102](file://src/hooks/use-agents.ts#L47-L102)
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

## 详细组件分析

### 聊天状态（use-chat）
- 设计要点
  - 流式渲染：基于 SSE 的增量事件驱动，首包到达才启动计时器，保证“首个 chunk 到达时启动”的语义
  - 平滑更新：文本与思考内容采用 60fps 合并刷新，避免频繁重排
  - 子代理内容：按 parent_tool_use_id 分组聚合，支持多代理并发流
  - 缓存与回放：为当前会话建立流缓存，切换会话时可恢复进度
  - 权限与工具：支持权限请求、工具调用、结果与进度展示
  - 中断与清理：支持取消、清理孤儿临时消息、清理定时器与 RAF
- 关键流程（发送消息到完成）
```mermaid
sequenceDiagram
participant C as "组件"
participant H as "use-chat"
participant S as "后端 /api/chat"
participant R as "SSE Reader"
C->>H : "sendMessage(content, attachments)"
H->>H : "乐观添加用户/占位助手消息"
H->>S : "POST /api/chat"
S-->>R : "SSE 流"
R-->>H : "text_delta/thinking_delta/agent_content/done"
H->>H : "合并刷新(60fps)"
H->>H : "更新令牌/耗时/权限/工具块"
H-->>C : "messages/streaming/isThinking/error"
H->>H : "done : 清理缓存/派发文件树刷新事件"
```

图表来源
- [src/hooks/use-chat.ts:75-667](file://src/hooks/use-chat.ts#L75-L667)

- 关键数据结构与复杂度
  - Message.blocks：数组查找/更新在单轮中最多 O(N)，其中 N 为块数量；通过索引定位与惰性合并降低开销
  - 子代理聚合：按 parent_tool_use_id 的 Map 查询与更新，平均 O(1)
  - 缓存：Map<string, StreamCacheEntry>，按会话维护快照，空间与重建成本可控

- 错误与中断
  - 请求失败：清理定时器、移除占位消息、删除缓存、设置错误标记
  - 用户取消：AbortController 触发，清理定时器与 RAF
  - 异常恢复：切换回会话时优先从缓存恢复，再回退到数据库

- 性能优化
  - requestAnimationFrame 合并更新，减少重绘
  - 文本累积与批量刷新，避免逐字符更新
  - 占位消息与孤儿清理，避免 UI 回退抖动

章节来源
- [src/hooks/use-chat.ts:38-695](file://src/hooks/use-chat.ts#L38-L695)
- [src/lib/types.ts:46-57](file://src/lib/types.ts#L46-L57)

### 会话管理（use-sessions）
- 功能：拉取、创建、更新、删除会话；刷新列表
- 数据映射：DbSession -> Session，保持字段对齐与默认值
- 并发注意：创建/更新后立即乐观地插入/替换，避免闪烁

章节来源
- [src/hooks/use-sessions.ts:30-80](file://src/hooks/use-sessions.ts#L30-L80)
- [src/lib/types.ts:6-15](file://src/lib/types.ts#L6-L15)

### 工作空间（use-workspaces）
- 功能：打开项目文件夹、删除、触达时间更新；存在性标记
- 交互：重复打开同一工作空间时就地更新，否则前置插入

章节来源
- [src/hooks/use-workspaces.ts:26-76](file://src/hooks/use-workspaces.ts#L26-L76)
- [src/lib/types.ts:66-74](file://src/lib/types.ts#L66-L74)

### 代理（use-agents）
- 功能：代理 CRUD；更新代理技能集合
- 数据映射：DbAgent -> Agent，含工具配置与技能 ID 数组

章节来源
- [src/hooks/use-agents.ts:47-102](file://src/hooks/use-agents.ts#L47-L102)
- [src/lib/types.ts:89-105](file://src/lib/types.ts#L89-L105)

### 设置（use-settings）
- 特性：跨实例同步（DOM 事件）、懒加载、读取便捷方法
- 同步机制：每次更新后广播自定义事件，其他实例监听并合并差异

章节来源
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)

### 模型（use-models）
- 特性：一次性拉取可用模型列表，避免硬编码

章节来源
- [src/hooks/use-models.ts:9-30](file://src/hooks/use-models.ts#L9-L30)

### 技能（use-skills）
- 功能：技能 CRUD；启用/禁用与内容编辑

章节来源
- [src/hooks/use-skills.ts:30-76](file://src/hooks/use-skills.ts#L30-L76)

### API 提供者（use-api-providers）
- 功能：提供者 CRUD；连通性测试（乐观更新状态）

章节来源
- [src/hooks/use-api-providers.ts:36-100](file://src/hooks/use-api-providers.ts#L36-L100)

### IM 渠道（use-im-channels）
- 功能：IM 渠道 CRUD；白名单与策略管理

章节来源
- [src/hooks/use-im-channels.ts:45-76](file://src/hooks/use-im-channels.ts#L45-L76)

### 定时任务（use-cron-tasks）
- 功能：任务 CRUD、心跳任务识别、手动执行
- 过滤：支持按工作空间筛选

章节来源
- [src/hooks/use-cron-tasks.ts:47-115](file://src/hooks/use-cron-tasks.ts#L47-L115)

### 执行记录（use-task-executions）
- 功能：分页加载、类型与状态过滤、加载更多
- 参数构建：URLSearchParams 组装查询参数

章节来源
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)

### 市场（use-marketplace）
- 功能：模板 CRUD；选中模板管理

章节来源
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)

### 代理配置（use-agent-config）
- 功能：子代理清单、配置文件清单；读写、字段更新、文件系统操作
- 依赖：工作空间 ID 作为作用域

章节来源
- [src/hooks/use-agent-config.ts:20-164](file://src/hooks/use-agent-config.ts#L20-L164)

## 依赖关系分析
- 类型依赖：所有 Hooks 依赖 types.ts 中的数据模型，确保前后端契约一致
- 数据持久化：db.ts 提供全局连接、表结构、索引与迁移，被各领域 API 与 UI 共享
- 事件同步：use-settings 使用 DOM 事件在同窗口多实例间同步设置
- 会话隔离：use-chat 通过会话级缓存与 ref 隔离不同会话的流状态

```mermaid
graph LR
T["types.ts"] --> HC["use-chat.ts"]
T --> HS["use-sessions.ts"]
T --> HW["use-workspaces.ts"]
T --> HA["use-agents.ts"]
T --> HSE["use-settings.ts"]
T --> HM["use-models.ts"]
T --> HK["use-skills.ts"]
T --> HAP["use-api-providers.ts"]
T --> HIC["use-im-channels.ts"]
T --> HCT["use-cron-tasks.ts"]
T --> HTE["use-task-executions.ts"]
T --> HMP["use-marketplace.ts"]
T --> HAC["use-agent-config.ts"]
D["db.ts"] --> HC
D --> HS
D --> HW
D --> HA
D --> HCT
D --> HTE
D --> HAP
D --> HIC
D --> HMP
D --> HAC
```

图表来源
- [src/lib/types.ts:1-221](file://src/lib/types.ts#L1-L221)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/hooks/use-chat.ts:38-695](file://src/hooks/use-chat.ts#L38-L695)
- [src/hooks/use-sessions.ts:30-80](file://src/hooks/use-sessions.ts#L30-L80)
- [src/hooks/use-workspaces.ts:26-76](file://src/hooks/use-workspaces.ts#L26-L76)
- [src/hooks/use-agents.ts:47-102](file://src/hooks/use-agents.ts#L47-L102)
- [src/hooks/use-settings.ts:10-55](file://src/hooks/use-settings.ts#L10-L55)
- [src/hooks/use-models.ts:9-30](file://src/hooks/use-models.ts#L9-L30)
- [src/hooks/use-skills.ts:30-76](file://src/hooks/use-skills.ts#L30-L76)
- [src/hooks/use-api-providers.ts:36-100](file://src/hooks/use-api-providers.ts#L36-L100)
- [src/hooks/use-im-channels.ts:45-76](file://src/hooks/use-im-channels.ts#L45-L76)
- [src/hooks/use-cron-tasks.ts:47-115](file://src/hooks/use-cron-tasks.ts#L47-L115)
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)
- [src/hooks/use-marketplace.ts:22-85](file://src/hooks/use-marketplace.ts#L22-L85)
- [src/hooks/use-agent-config.ts:20-164](file://src/hooks/use-agent-config.ts#L20-L164)

## 性能考量
- 更新合并
  - use-chat：使用 requestAnimationFrame 合并文本与思考增量，避免高频 setState 导致的重绘
  - 子代理内容：按父工具 ID 聚合，减少块级查找与更新次数
- 乐观更新
  - use-sessions、use-agents、use-skills、use-api-providers、use-im-channels、use-marketplace 等均采用乐观更新，提升交互响应
- 缓存与回放
  - use-chat：会话级流缓存，切换会话时可快速恢复进度，减少重复请求
- 分页与过滤
  - use-task-executions：分页加载与参数化过滤，避免一次性加载大量数据
- 数据库优化
  - db.ts：WAL 模式、外键约束、索引（如 messages(session_id, created_at)），提升读写性能与一致性
- 内存优化
  - 及时清理定时器与 RAF，异常路径与取消路径均需清理
  - 占位消息与孤儿清理，避免 UI 堆积

[本节为通用指导，不直接分析具体文件，故无章节来源]

## 故障排查指南
- 聊天流异常
  - 现象：无首包、无计时、无更新
  - 排查：确认 SSE 连接是否成功、事件类型是否正确、首包是否到达；检查占位消息是否存在、缓存是否命中
  - 参考路径：[src/hooks/use-chat.ts:313-498](file://src/hooks/use-chat.ts#L313-L498)
- 权限与工具问题
  - 现象：权限弹窗未关闭、工具结果缺失或重复
  - 排查：确认 permission_request 与 permission_resolved 的配对；去重逻辑是否生效；工具结果是否按 tool_use_id 匹配
  - 参考路径：[src/hooks/use-chat.ts:569-623](file://src/hooks/use-chat.ts#L569-L623)
- 会话切换错乱
  - 现象：切换会话后消息错位或丢失
  - 排查：确认流缓存是否按会话维护；setMessages 在非当前会话是否为 no-op；缓存是否及时更新
  - 参考路径：[src/hooks/use-chat.ts:162-168](file://src/hooks/use-chat.ts#L162-L168)
- 设置不同步
  - 现象：多个设置面板显示不一致
  - 排查：确认 DOM 事件是否正确派发与监听；更新是否合并到本地状态
  - 参考路径：[src/hooks/use-settings.ts:28-48](file://src/hooks/use-settings.ts#L28-L48)
- 数据库迁移失败
  - 现象：启动时报 schema 不一致
  - 排查：检查迁移脚本是否完整执行；必要时清理旧数据或手动修正
  - 参考路径：[src/lib/db.ts:226-387](file://src/lib/db.ts#L226-L387)
- 执行记录加载异常
  - 现象：翻页无效或过滤不生效
  - 排查：确认 URLSearchParams 参数是否正确拼接；服务端分页接口是否支持 limit/offset
  - 参考路径：[src/hooks/use-task-executions.ts:39-81](file://src/hooks/use-task-executions.ts#L39-L81)

章节来源
- [src/hooks/use-chat.ts:313-498](file://src/hooks/use-chat.ts#L313-L498)
- [src/hooks/use-settings.ts:28-48](file://src/hooks/use-settings.ts#L28-L48)
- [src/lib/db.ts:226-387](file://src/lib/db.ts#L226-L387)
- [src/hooks/use-task-executions.ts:39-81](file://src/hooks/use-task-executions.ts#L39-L81)

## 结论
本状态管理系统以 Hooks 为核心，结合类型约束与本地数据库，实现了：
- 高效的流式渲染与平滑更新
- 会话级状态隔离与缓存回放
- 跨实例设置同步与乐观更新
- 完整的 CRUD 与连通性测试
- 分页与过滤的长列表管理
- 数据库迁移与一致性保障

建议在后续迭代中持续关注：
- 更细粒度的缓存失效策略
- 更完善的错误边界与重试机制
- 性能指标埋点与可视化

[本节为总结性内容，不直接分析具体文件，故无章节来源]

## 附录

### 状态提升策略与上下文共享
- 策略
  - 将跨组件共享的状态下沉至 Hooks，避免层层 props 传递
  - 对于设置类状态，使用 DOM 事件在同窗口多实例间共享
- 上下文共享
  - 通过 use-chat 的会话缓存与 ref 实现“当前会话”与“正在流式会话”的上下文共享
- 状态同步
  - 乐观更新 + 服务端回写；失败回滚；成功后刷新局部状态

章节来源
- [src/hooks/use-settings.ts:28-48](file://src/hooks/use-settings.ts#L28-L48)
- [src/hooks/use-chat.ts:45-52](file://src/hooks/use-chat.ts#L45-L52)

### 客户端状态缓存、数据持久化与离线支持
- 缓存
  - use-chat：会话级流缓存，用于切换回放
  - use-task-executions：分页偏移缓存
- 持久化
  - db.ts：SQLite WAL 模式、外键、索引与迁移
- 离线支持
  - 当前以在线 API 为主；可在 UI 层增加“仅本地模式”提示与降级策略（建议）

章节来源
- [src/hooks/use-chat.ts:48-50](file://src/hooks/use-chat.ts#L48-L50)
- [src/hooks/use-task-executions.ts:37-38](file://src/hooks/use-task-executions.ts#L37-L38)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

### 状态变更触发机制、副作用处理与错误恢复
- 触发机制
  - 用户交互（点击、输入）触发 Hooks 内部回调
  - SSE 事件驱动 use-chat 的增量更新
- 副作用
  - DOM 事件（文件树刷新、设置同步）
  - 定时器与 RAF
  - 网络请求与数据库写入
- 错误恢复
  - 失败清理：定时器、RAF、缓存、占位消息
  - 回退策略：切换回会话时从缓存恢复，再回退到数据库

章节来源
- [src/hooks/use-chat.ts:646-666](file://src/hooks/use-chat.ts#L646-L666)
- [src/hooks/use-settings.ts:28-48](file://src/hooks/use-settings.ts#L28-L48)

### 状态调试工具、性能监控与内存优化技巧
- 调试
  - 控制台日志：请求失败、事件解析异常
  - DOM 事件：设置同步、文件树刷新
- 性能
  - 合并刷新、分页加载、索引优化
- 内存
  - 及时清理定时器与 RAF
  - 占位消息与孤儿清理

章节来源
- [src/hooks/use-chat.ts:646-666](file://src/hooks/use-chat.ts#L646-L666)
- [src/lib/db.ts:22-437](file://src/lib/db.ts#L22-L437)

### 最佳实践与常见问题解决方案
- 最佳实践
  - 优先使用 Hooks 封装状态与副作用
  - 乐观更新 + 失败回滚
  - 事件驱动的增量更新
  - 明确的错误边界与清理逻辑
- 常见问题
  - SSE 无响应：检查服务端流输出与事件格式
  - 权限弹窗不消失：核对请求/响应配对与去重
  - 设置不一致：确认 DOM 事件派发与监听

章节来源
- [src/hooks/use-chat.ts:313-498](file://src/hooks/use-chat.ts#L313-L498)
- [src/hooks/use-settings.ts:28-48](file://src/hooks/use-settings.ts#L28-L48)