# 聊天系统

<cite>
**本文引用的文件**
- [src/app/api/chat/route.ts](file://src/app/api/chat/route.ts)
- [src/app/api/chat/permission/route.ts](file://src/app/api/chat/permission/route.ts)
- [src/lib/sdk/message-mapper.ts](file://src/lib/sdk/message-mapper.ts)
- [src/lib/sdk/permission-bridge.ts](file://src/lib/sdk/permission-bridge.ts)
- [src/lib/im/conversation-engine.ts](file://src/lib/im/conversation-engine.ts)
- [src/hooks/use-chat.ts](file://src/hooks/use-chat.ts)
- [src/components/chat/slash-command-menu.tsx](file://src/components/chat/slash-command-menu.tsx)
- [src/hooks/use-slash-commands.ts](file://src/hooks/use-slash-commands.ts)
- [src/lib/slash-commands.ts](file://src/lib/slash-commands.ts)
- [src/components/views/chat-view.tsx](file://src/components/views/chat-view.tsx)
- [src/app/api/sessions/[id]/messages/route.ts](file://src/app/api/sessions/[id]/messages/route.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [README_CN.md](file://README_CN.md)
</cite>

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

## 简介
本文件系统性阐述 Forge 的聊天系统，覆盖实时流式聊天的实现原理（SSE 事件流）、Claude Agent SDK 集成、消息映射机制、会话管理、权限控制、附件处理、思维模式配置、Slash 命令菜单与自定义命令开发、聊天界面使用指南、API 调用示例、错误处理策略、消息历史恢复、内存管理与性能优化等内容。目标是帮助从入门到进阶的用户全面掌握 Forge 聊天系统的使用与定制。

## 项目结构
Forge 聊天系统主要由以下层次构成：
- 前端层：React 组件与 Hooks，负责渲染、交互、流式渲染与权限决策提交。
- 业务层：Next.js App Router API 路由，处理聊天请求、权限决策、会话消息查询。
- SDK 集成层：Claude Agent SDK 客户端封装，消息映射与权限桥接。
- 数据层：SQLite 存储会话与消息；上传目录用于附件访问；工作区文件系统用于记忆归档与文件检测。
- IM 层：与飞书/Telegram/Discord 的 IM Bridge，支持图片/文件收发与命令触发。

```mermaid
graph TB
subgraph "前端"
CV["ChatView 组件"]
SC["SlashCommandMenu 组件"]
UC["use-chat Hook"]
USC["use-slash-commands Hook"]
end
subgraph "后端 API"
API_CHAT["/api/chat 路由"]
API_PERM["/api/chat/permission 路由"]
API_MSGS["/api/sessions/:id/messages 路由"]
end
subgraph "SDK 集成"
MSGMAP["MessageMapper 消息映射器"]
PERM["PermissionBridge 权限桥"]
CE["ConversationEngine IM 引擎"]
end
subgraph "数据与文件"
DB["SQLite 数据库"]
UPLOADS["上传目录 /api/upload"]
FS[".claude/ 工作区文件系统"]
end
CV --> UC
SC --> USC
UC --> API_CHAT
API_CHAT --> MSGMAP
API_CHAT --> PERM
API_CHAT --> DB
API_CHAT --> UPLOADS
API_CHAT --> FS
API_PERM --> PERM
API_MSGS --> DB
CE --> MSGMAP
CE --> PERM
CE --> DB
CE --> UPLOADS
CE --> FS
```

图表来源
- [src/components/views/chat-view.tsx:1-800](file://src/components/views/chat-view.tsx#L1-L800)
- [src/hooks/use-chat.ts:1-696](file://src/hooks/use-chat.ts#L1-L696)
- [src/components/chat/slash-command-menu.tsx:1-85](file://src/components/chat/slash-command-menu.tsx#L1-L85)
- [src/hooks/use-slash-commands.ts:1-129](file://src/hooks/use-slash-commands.ts#L1-L129)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/chat/permission/route.ts:1-42](file://src/app/api/chat/permission/route.ts#L1-L42)
- [src/app/api/sessions/[id]/messages/route.ts](file://src/app/api/sessions/[id]/messages/route.ts#L1-L13)
- [src/lib/sdk/message-mapper.ts:1-705](file://src/lib/sdk/message-mapper.ts#L1-L705)
- [src/lib/sdk/permission-bridge.ts:1-285](file://src/lib/sdk/permission-bridge.ts#L1-L285)
- [src/lib/im/conversation-engine.ts:1-459](file://src/lib/im/conversation-engine.ts#L1-L459)

章节来源
- [src/components/views/chat-view.tsx:1-800](file://src/components/views/chat-view.tsx#L1-L800)
- [src/hooks/use-chat.ts:1-696](file://src/hooks/use-chat.ts#L1-L696)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)

## 核心组件
- SSE 事件流与流式渲染：前端通过 fetch + ReadableStream 接收 text/event-stream，逐条解析并增量更新 UI，支持文本、思考、工具调用、权限请求、附件等事件类型。
- Claude Agent SDK 集成：后端使用 createForgeQuery 创建查询，消费 SDK 流，MessageMapper 将 SDK 消息映射为 SSE 事件；PermissionBridge 将 SDK 的 canUseTool 回调桥接到前端权限确认。
- 会话与消息持久化：SQLite 存储会话与消息；支持会话标题更新、消息历史查询、压缩与导出。
- 附件处理：支持图片与文件上传、解析 MEDIA: 协议、工具调用推断路径、复制到上传目录供 /api/upload 访问。
- 权限控制：支持“询问”和“全量放行”两种模式；支持会话级允许；超时自动拒绝；审计日志。
- 思维模式：支持 off/auto/max，按请求、按提供商、按全局设置优先级决定。
- Slash 命令：内置命令 + 技能/代理/MCP 动态发现，自动补全与快捷执行。

章节来源
- [src/lib/sdk/message-mapper.ts:1-705](file://src/lib/sdk/message-mapper.ts#L1-L705)
- [src/lib/sdk/permission-bridge.ts:1-285](file://src/lib/sdk/permission-bridge.ts#L1-L285)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/hooks/use-chat.ts:1-696](file://src/hooks/use-chat.ts#L1-L696)
- [src/lib/slash-commands.ts:1-69](file://src/lib/slash-commands.ts#L1-L69)

## 架构总览
下面的序列图展示了桌面聊天的完整流程：从前端发起消息，到后端通过 SDK 流式返回，再到前端增量渲染与持久化。

```mermaid
sequenceDiagram
participant UI as "ChatView/用户"
participant Hook as "use-chat Hook"
participant API as "/api/chat"
participant SDK as "Claude Agent SDK"
participant Mapper as "MessageMapper"
participant Perm as "PermissionBridge"
participant DB as "SQLite"
participant Upload as "上传目录"
UI->>Hook : "sendMessage(content, attachments)"
Hook->>API : "POST /api/chat {sessionId, message, attachments, permissionMode, thinkingMode}"
API->>Perm : "createPermissionBridge(可选)"
API->>SDK : "createForgeQuery(...) 启动流"
SDK-->>API : "流式事件"
API->>Mapper : "mapMessage(msg) -> SSE 事件"
Mapper-->>Hook : "SSE : text_delta/thinking_delta/tool_use/..."
Hook->>UI : "增量渲染60fps 合并"
Note over API,SDK : "权限请求时，Mapper.emit(permission_request)"
Hook->>API : "POST /api/chat/permission {requestId, decision}"
API->>Perm : "resolvePermission()"
Perm-->>SDK : "返回 allow/deny"
SDK-->>API : "继续流"
API->>DB : "保存用户/助手消息"
API->>Upload : "复制附件到 /api/upload"
API-->>Hook : "SSE : done (tokens, messageId)"
Hook->>DB : "最终持久化"
```

图表来源
- [src/app/api/chat/route.ts:74-350](file://src/app/api/chat/route.ts#L74-L350)
- [src/lib/sdk/message-mapper.ts:53-85](file://src/lib/sdk/message-mapper.ts#L53-L85)
- [src/lib/sdk/permission-bridge.ts:62-152](file://src/lib/sdk/permission-bridge.ts#L62-L152)
- [src/hooks/use-chat.ts:314-667](file://src/hooks/use-chat.ts#L314-L667)

章节来源
- [src/app/api/chat/route.ts:74-350](file://src/app/api/chat/route.ts#L74-L350)
- [src/lib/sdk/message-mapper.ts:1-705](file://src/lib/sdk/message-mapper.ts#L1-L705)
- [src/lib/sdk/permission-bridge.ts:1-285](file://src/lib/sdk/permission-bridge.ts#L1-L285)
- [src/hooks/use-chat.ts:1-696](file://src/hooks/use-chat.ts#L1-L696)

## 详细组件分析

### SSE 事件流与流式渲染
- 事件类型：文本增量、思考增量、工具调用、工具结果、权限请求、权限解决、附件、完成、错误等。
- 前端采用 TransformStream + ReadableStream + TextDecoder 解析 data: 行，逐条事件处理。
- 文本与思考增量采用 60fps 合并刷新，保证顺滑；子代理（agent_content）单独缓冲，合并后统一刷新。
- 完成事件携带 input/output tokens 与消息 ID，用于最终持久化与统计。

章节来源
- [src/hooks/use-chat.ts:345-667](file://src/hooks/use-chat.ts#L345-L667)
- [src/lib/sdk/message-mapper.ts:11-14](file://src/lib/sdk/message-mapper.ts#L11-L14)

### Claude Agent SDK 集成与消息映射
- SDK 查询：根据 sessionId、model、workspaceId、权限模式、思维模式、附件等参数创建查询。
- 消息映射：将 SDK 的 stream_event、assistant、tool_use_summary、tool_progress、result、system、user 等消息类型映射为 SSE 事件。
- 子代理（agent_content）：当 parent_tool_use_id 存在时，将事件路由到 agent_content，以便在 UI 中渲染子代理的中间过程。
- 结果汇总：最终 result 中的 usage 用于统计 tokens；错误 result 转换为 error 事件。

章节来源
- [src/lib/sdk/message-mapper.ts:53-704](file://src/lib/sdk/message-mapper.ts#L53-L704)

### 权限控制与桥接
- 权限模式：
  - confirm：每次工具调用前弹出权限请求，等待前端决策。
  - full：绕过权限，直接放行。
- 权限桥：
  - createPermissionBridge 将 canUseTool 回调桥接到 SSE permission_request，并维护请求超时与会话级允许。
  - resolvePermission 由 /api/chat/permission 调用，返回 allow/allow_session/deny。
  - 会话级允许：一次授权可自动放行同工具后续请求；定期清理过期会话允许。
- 审计日志：记录权限决策，限制最大条目数防止内存膨胀。

章节来源
- [src/lib/sdk/permission-bridge.ts:62-285](file://src/lib/sdk/permission-bridge.ts#L62-L285)
- [src/app/api/chat/permission/route.ts:1-42](file://src/app/api/chat/permission/route.ts#L1-L42)

### 会话管理与消息持久化
- 会话：包含 id、title、workspace、model、permissionMode、status、时间戳。
- 消息：支持 text、thinking、tool_use、tool_result、tool_raw_result、tool_progress、agent_content、permission_request、image_attachment、file_attachment 等块类型。
- 历史加载：GET /api/sessions/:id/messages 返回按时间排序的消息列表。
- 标题更新：会话前两条消息时自动设置标题；后续仅更新时间戳。
- 压缩与导出：支持压缩历史与导出会话为 Markdown。

章节来源
- [src/lib/types.ts:6-57](file://src/lib/types.ts#L6-L57)
- [src/app/api/sessions/[id]/messages/route.ts](file://src/app/api/sessions/[id]/messages/route.ts#L1-L13)
- [src/app/api/chat/route.ts:282-296](file://src/app/api/chat/route.ts#L282-L296)

### 附件处理与文件检测
- 上传：前端上传文件到 /api/upload，后端保存到 uploads 目录。
- 解析 MEDIA: 协议：从文本中提取显式声明的文件路径，剥离协议行。
- 工具推断：从 Write/Bash/Read 等工具调用中提取文件路径，合并去重。
- 复制与回传：将检测到的文件复制到 uploads 目录，发出 attachment 事件即时渲染。
- 类型识别：根据扩展名识别图片与非图片文件，设置 MIME 与大小。

章节来源
- [src/app/api/chat/route.ts:240-280](file://src/app/api/chat/route.ts#L240-L280)
- [src/lib/im/conversation-engine.ts:365-459](file://src/lib/im/conversation-engine.ts#L365-L459)

### 思维模式配置
- 优先级：请求覆盖 > 提供商设置 > 全局设置 > 默认 auto。
- 可选值：off/auto/max。
- 前端 UI：在 ChatView 中通过下拉菜单切换，影响 SDK 查询参数。

章节来源
- [src/app/api/chat/route.ts:114-118](file://src/app/api/chat/route.ts#L114-L118)
- [src/components/views/chat-view.tsx:750-791](file://src/components/views/chat-view.tsx#L750-L791)

### Slash 命令菜单与自定义命令
- 内置命令：clear、compact、cost、diff、export、init、memory、model、rename、save-as-template、stop、workspace 等。
- 动态命令：技能、代理、MCP 服务器名称动态发现并加入自动补全。
- 交互：输入 / 触发菜单，支持上下键导航、Tab/Enter 选择、Esc 关闭。
- 执行：内置命令通过 API 或事件触发；技能/代理通过发送指令；MCP 为预留占位。

章节来源
- [src/lib/slash-commands.ts:20-69](file://src/lib/slash-commands.ts#L20-L69)
- [src/hooks/use-slash-commands.ts:45-129](file://src/hooks/use-slash-commands.ts#L45-L129)
- [src/components/chat/slash-command-menu.tsx:22-85](file://src/components/chat/slash-command-menu.tsx#L22-L85)
- [src/components/views/chat-view.tsx:182-350](file://src/components/views/chat-view.tsx#L182-L350)

### IM 桥接与对话引擎（可选）
- ConversationEngine：处理 IM 消息，保存用户消息，调用 SDK 流，回调 onTyping/onDraft/onFinal/onAttachments，保存助手消息，更新会话标题。
- 附件：支持图片与文件保存到 uploads，用于渲染与回传。
- 权限：支持 IM 权限模式，canUseTool 回调通过回调函数返回决策。
- 优化：IM 场景跳过 MCP 服务器，减少启动延迟。

章节来源
- [src/lib/im/conversation-engine.ts:40-355](file://src/lib/im/conversation-engine.ts#L40-L355)

## 依赖关系分析

```mermaid
classDiagram
class MessageMapper {
+mapMessage(msg) SseEvent[]
+getBlocks() Record[]
+inputTokens number
+outputTokens number
}
class PermissionBridge {
+createPermissionBridge(sessionId, emit) CanUseTool
+resolvePermission(requestId, decision) boolean
+cleanupStaleSessionAllowances() number
}
class ChatRoute {
+POST(req) Response
-drainQuery(q, mapper, emit)
-buildPromptWithHistory(newMessage, recent)
}
class UseChatHook {
+sendMessage()
+stopStreaming()
+sendPermissionDecision()
+loadMessages()
}
class SlashCommandMenu {
+commands SlashCommand[]
+selectedIndex number
+onSelect(cmd)
}
class ConversationEngine {
+processMessage(msg, sessionId, workspace, callbacks) Promise
}
ChatRoute --> MessageMapper : "映射 SDK 消息"
ChatRoute --> PermissionBridge : "创建/解析权限"
UseChatHook --> ChatRoute : "SSE 流式消费"
SlashCommandMenu --> UseChatHook : "触发命令"
ConversationEngine --> MessageMapper : "映射 SDK 消息"
ConversationEngine --> PermissionBridge : "IM 权限回调"
```

图表来源
- [src/lib/sdk/message-mapper.ts:28-103](file://src/lib/sdk/message-mapper.ts#L28-L103)
- [src/lib/sdk/permission-bridge.ts:62-214](file://src/lib/sdk/permission-bridge.ts#L62-L214)
- [src/app/api/chat/route.ts:25-37](file://src/app/api/chat/route.ts#L25-L37)
- [src/hooks/use-chat.ts:75-667](file://src/hooks/use-chat.ts#L75-L667)
- [src/components/chat/slash-command-menu.tsx:9-13](file://src/components/chat/slash-command-menu.tsx#L9-L13)
- [src/lib/im/conversation-engine.ts:30-355](file://src/lib/im/conversation-engine.ts#L30-L355)

章节来源
- [src/lib/sdk/message-mapper.ts:1-705](file://src/lib/sdk/message-mapper.ts#L1-L705)
- [src/lib/sdk/permission-bridge.ts:1-285](file://src/lib/sdk/permission-bridge.ts#L1-L285)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/hooks/use-chat.ts:1-696](file://src/hooks/use-chat.ts#L1-L696)
- [src/components/chat/slash-command-menu.tsx:1-85](file://src/components/chat/slash-command-menu.tsx#L1-L85)
- [src/lib/im/conversation-engine.ts:1-459](file://src/lib/im/conversation-engine.ts#L1-L459)

## 性能考量
- 流式渲染优化
  - 前端使用 requestAnimationFrame 合并文本与思考增量，避免频繁重绘。
  - 子代理（agent_content）独立缓冲，合并后统一刷新，降低 UI 抖动。
- SSE 传输
  - 使用 TransformStream + ReadableStream + TextDecoder，避免整体缓冲，提升首包延迟体验。
  - 服务端对 writer closed 做容错，客户端断开时及时停止写入。
- 会话恢复与降级
  - 会话恢复失败时自动回退到“历史提示 + 新会话”，避免长时间阻塞。
  - 会话标题仅在前两条消息时更新，减少不必要的写操作。
- 附件与文件检测
  - 仅复制有效文件（非空、小于阈值、非跳过的扩展名），并去重合并。
  - 附件检测优先 MEDIA: 协议，其次工具推断，减少误报。
- 权限与审计
  - 会话级允许自动去重，避免重复弹窗。
  - 权限日志限制最大条目，防止内存增长。
- IM 引擎优化
  - IM 场景跳过 MCP 服务器，减少启动开销。
  - 流水线回调节流（onDraft 每 800ms 一次），平衡实时性与性能。

章节来源
- [src/hooks/use-chat.ts:190-311](file://src/hooks/use-chat.ts#L190-L311)
- [src/app/api/chat/route.ts:193-238](file://src/app/api/chat/route.ts#L193-L238)
- [src/lib/sdk/permission-bridge.ts:193-214](file://src/lib/sdk/permission-bridge.ts#L193-L214)
- [src/lib/im/conversation-engine.ts:279-288](file://src/lib/im/conversation-engine.ts#L279-L288)

## 故障排查指南
- SSE 连接异常
  - 现象：前端长时间无响应或报错。
  - 排查：检查服务端是否正确返回 text/event-stream 头；确认 TransformStream 写入未被提前关闭；查看前端 reader 是否被中断。
  - 参考：[src/app/api/chat/route.ts:333-342](file://src/app/api/chat/route.ts#L333-L342)、[src/hooks/use-chat.ts:339-341](file://src/hooks/use-chat.ts#L339-L341)
- 权限请求未响应
  - 现象：出现 permission_request 但无后续 permission_resolved。
  - 排查：确认 /api/chat/permission 是否收到请求；检查 resolvePermission 是否被调用；查看会话活动清理是否过早清除。
  - 参考：[src/lib/sdk/permission-bridge.ts:158-182](file://src/lib/sdk/permission-bridge.ts#L158-L182)、[src/app/api/chat/permission/route.ts:33-41](file://src/app/api/chat/permission/route.ts#L33-L41)
- 会话恢复失败
  - 现象：resumeSession 成功但无内容块，或抛出异常。
  - 排查：检查 drainQuery 的异常路径与“无声错误”检测；必要时回退到历史提示 + 新会话。
  - 参考：[src/app/api/chat/route.ts:193-238](file://src/app/api/chat/route.ts#L193-L238)
- 附件未显示
  - 现象：工具调用产生文件但前端未渲染。
  - 排查：确认 MEDIA: 协议是否存在于文本；检查工具推断路径；确认文件大小与扩展名符合要求；检查 /api/upload 是否可达。
  - 参考：[src/app/api/chat/route.ts:240-280](file://src/app/api/chat/route.ts#L240-L280)、[src/lib/im/conversation-engine.ts:365-459](file://src/lib/im/conversation-engine.ts#L365-L459)
- 令牌统计异常
  - 现象：done 事件缺少 input/output tokens。
  - 排查：确认 SDK result 中 usage 字段是否存在；检查 MessageMapper 是否正确提取。
  - 参考：[src/lib/sdk/message-mapper.ts:688-693](file://src/lib/sdk/message-mapper.ts#L688-L693)

章节来源
- [src/app/api/chat/route.ts:193-238](file://src/app/api/chat/route.ts#L193-L238)
- [src/lib/sdk/permission-bridge.ts:158-182](file://src/lib/sdk/permission-bridge.ts#L158-L182)
- [src/hooks/use-chat.ts:339-341](file://src/hooks/use-chat.ts#L339-L341)
- [src/lib/sdk/message-mapper.ts:688-693](file://src/lib/sdk/message-mapper.ts#L688-L693)

## 结论
Forge 的聊天系统以 Claude Agent SDK 为核心，结合 SSE 事件流、消息映射器与权限桥，实现了流畅、可观测、可扩展的本地 AI 工作站体验。通过完善的会话管理、权限控制、附件处理与思维模式配置，以及灵活的 Slash 命令系统，既满足日常使用，也为高级定制提供了坚实基础。建议在生产环境中关注流式渲染的帧率控制、权限日志的容量管理与附件的合规性校验，以获得更稳定的体验。

## 附录

### 聊天界面使用指南
- 发送消息：在输入框中输入文本或附加图片/文件，点击发送或按 Enter。
- Slash 命令：输入 / 触发命令菜单，选择内置命令或动态命令（技能/代理/MCP）。
- 权限模式：在工具调用前可选择“询问”或“全量放行”，支持会话级允许。
- 思维模式：在下拉菜单中选择 Off/Auto/Max，影响模型推理深度。
- 附件预览：上传后会在输入框上方显示，可移除。
- 导出与清空：通过菜单或命令导出会话，或清空当前会话。

章节来源
- [src/components/views/chat-view.tsx:449-483](file://src/components/views/chat-view.tsx#L449-L483)
- [src/components/chat/slash-command-menu.tsx:22-85](file://src/components/chat/slash-command-menu.tsx#L22-L85)

### API 调用示例
- 发送聊天消息（SSE）
  - 方法：POST /api/chat
  - 请求体字段：sessionId、message、attachments（可选）、permissionMode（可选）、thinkingMode（可选）
  - 响应：text/event-stream，事件类型包括 text_delta、thinking_delta、tool_use、tool_result、permission_request、done、error、attachment 等
  - 参考：[src/app/api/chat/route.ts:74-350](file://src/app/api/chat/route.ts#L74-L350)
- 提交权限决策
  - 方法：POST /api/chat/permission
  - 请求体字段：requestId、decision（allow/allow_session/deny）
  - 响应：JSON，包含 ok 与 resolved
  - 参考：[src/app/api/chat/permission/route.ts:6-41](file://src/app/api/chat/permission/route.ts#L6-L41)
- 加载会话消息
  - 方法：GET /api/sessions/:id/messages
  - 响应：按 created_at 升序排列的消息数组
  - 参考：[src/app/api/sessions/[id]/messages/route.ts](file://src/app/api/sessions/[id]/messages/route.ts#L4-L12)

章节来源
- [src/app/api/chat/route.ts:74-350](file://src/app/api/chat/route.ts#L74-L350)
- [src/app/api/chat/permission/route.ts:6-41](file://src/app/api/chat/permission/route.ts#L6-L41)
- [src/app/api/sessions/[id]/messages/route.ts](file://src/app/api/sessions/[id]/messages/route.ts#L4-L12)

### 错误处理策略
- 请求体无效：返回 JSON 错误，状态码 400。
- 会话不存在：返回 404。
- SSE 写入失败：忽略并结束流。
- SDK 异常：捕获并保存已生成的部分助手消息；若无内容则删除用户消息。
- 客户端断开：AbortController 触发，停止 SDK 流。
- 权限超时：自动拒绝，记录审计日志。

章节来源
- [src/app/api/chat/route.ts:344-350](file://src/app/api/chat/route.ts#L344-L350)
- [src/app/api/chat/route.ts:309-326](file://src/app/api/chat/route.ts#L309-L326)
- [src/lib/sdk/permission-bridge.ts:158-182](file://src/lib/sdk/permission-bridge.ts#L158-L182)

### 消息历史恢复与内存管理
- 历史恢复：当 resumeSession 失败（无内容块或异常）时，回退到“历史提示 + 新会话”，避免长时间阻塞。
- 内存归档：按天归档旧记忆，受设置控制；定期清理过期会话允许。
- 令牌统计：done 事件携带 input/output tokens，便于成本统计与优化。

章节来源
- [src/app/api/chat/route.ts:193-238](file://src/app/api/chat/route.ts#L193-L238)
- [src/app/api/chat/route.ts:134-141](file://src/app/api/chat/route.ts#L134-L141)
- [src/lib/sdk/permission-bridge.ts:238-256](file://src/lib/sdk/permission-bridge.ts#L238-L256)
- [src/lib/sdk/message-mapper.ts:688-693](file://src/lib/sdk/message-mapper.ts#L688-L693)

### Slash 命令菜单使用与自定义命令开发
- 内置命令：clear、compact、cost、diff、export、init、memory、model、rename、save-as-template、stop、workspace。
- 动态命令：技能、代理、MCP 服务器名称从后端树形结构动态发现。
- 自定义命令开发：在 use-slash-commands 中聚合树结构，生成命令列表；在 ChatView 中通过 executeCommand 执行；支持带参数命令与内联模型选择器。

章节来源
- [src/lib/slash-commands.ts:20-69](file://src/lib/slash-commands.ts#L20-L69)
- [src/hooks/use-slash-commands.ts:45-129](file://src/hooks/use-slash-commands.ts#L45-L129)
- [src/components/views/chat-view.tsx:182-350](file://src/components/views/chat-view.tsx#L182-L350)