# API参考

<cite>
**本文引用的文件**
- [src/app/api/agents/route.ts](file://src/app/api/agents/route.ts)
- [src/app/api/api-providers/route.ts](file://src/app/api/api-providers/route.ts)
- [src/app/api/api-providers/cli-login/route.ts](file://src/app/api/api-providers/cli-login/route.ts)
- [src/app/api/chat/route.ts](file://src/app/api/chat/route.ts)
- [src/app/api/cron-engine/route.ts](file://src/app/api/cron-engine/route.ts)
- [src/app/api/data/export/route.ts](file://src/app/api/data/export/route.ts)
- [src/app/api/im-channels/route.ts](file://src/app/api/im-channels/route.ts)
- [src/app/api/im-events/route.ts](file://src/app/api/im-events/route.ts)
- [src/app/api/marketplace/route.ts](file://src/app/api/marketplace/route.ts)
- [src/app/api/models/route.ts](file://src/app/api/models/route.ts)
- [src/app/api/sessions/route.ts](file://src/app/api/sessions/route.ts)
- [src/app/api/settings/route.ts](file://src/app/api/settings/route.ts)
- [src/app/api/skills/route.ts](file://src/app/api/skills/route.ts)
- [src/app/api/task-executions/route.ts](file://src/app/api/task-executions/route.ts)
- [src/app/api/upload/route.ts](file://src/app/api/upload/route.ts)
- [src/app/api/workspaces/route.ts](file://src/app/api/workspaces/route.ts)
</cite>

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

## 简介
本文件为 Forge 的公共 API 接口参考文档，覆盖以下两类接口形态：
- RESTful API：记录 HTTP 方法、URL 模式、请求/响应结构与认证方式（如适用）。
- SSE 实时事件流：说明连接处理、消息格式、事件类型与实时交互模式。

文档同时提供各端点的参数说明、返回值定义、错误码与示例调用路径，并给出最佳实践与性能优化建议，帮助开发者快速理解并正确使用所有公开 API。

## 项目结构
- 所有 API 路由位于 src/app/api 下，采用 Next.js App Router 的约定式路由组织，按功能域分层（如 agents、sessions、chat、upload 等）。
- 大多数路由导出一个或多个 HTTP 方法处理器（GET/POST/PUT 等），部分路由返回 Server-Sent Events 流。
- 数据访问统一通过数据库封装模块，部分路由涉及文件系统写入与外部 CLI 集成。

```mermaid
graph TB
subgraph "API 路由"
AG["agents/route.ts"]
AP["api-providers/route.ts"]
CLI["api-providers/cli-login/route.ts"]
CH["chat/route.ts"]
CE["cron-engine/route.ts"]
EX["data/export/route.ts"]
IMC["im-channels/route.ts"]
IME["im-events/route.ts"]
MKT["marketplace/route.ts"]
MD["models/route.ts"]
SESS["sessions/route.ts"]
ST["settings/route.ts"]
SK["skills/route.ts"]
TE["task-executions/route.ts"]
UP["upload/route.ts"]
WS["workspaces/route.ts"]
end
subgraph "后端服务"
DB["数据库封装(getDb)"]
FS["文件系统"]
CLI_BIN["本地CLI(如claude)"]
end
AG --> DB
AP --> DB
CLI --> CLI_BIN
CH --> DB
CH --> FS
CE --> DB
EX --> DB
IMC --> DB
IME --> DB
MKT --> DB
MKT --> FS
MD --> DB
SESS --> DB
ST --> DB
SK --> DB
TE --> DB
UP --> FS
WS --> DB
WS --> FS
```

图表来源
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/api-providers/route.ts:1-35](file://src/app/api/api-providers/route.ts#L1-L35)
- [src/app/api/api-providers/cli-login/route.ts:1-88](file://src/app/api/api-providers/cli-login/route.ts#L1-L88)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/cron-engine/route.ts:1-30](file://src/app/api/cron-engine/route.ts#L1-L30)
- [src/app/api/data/export/route.ts:1-38](file://src/app/api/data/export/route.ts#L1-L38)
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/app/api/marketplace/route.ts:1-40](file://src/app/api/marketplace/route.ts#L1-L40)
- [src/app/api/models/route.ts:1-35](file://src/app/api/models/route.ts#L1-L35)
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)
- [src/app/api/settings/route.ts:1-49](file://src/app/api/settings/route.ts#L1-L49)
- [src/app/api/skills/route.ts:1-27](file://src/app/api/skills/route.ts#L1-L27)
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)
- [src/app/api/upload/route.ts:1-91](file://src/app/api/upload/route.ts#L1-L91)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)

章节来源
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)
- [src/app/api/api-providers/route.ts:1-35](file://src/app/api/api-providers/route.ts#L1-L35)
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)

## 核心组件
- 数据库访问：统一通过 getDb 获取连接，执行 SQL 查询与事务。
- 文件系统：上传目录与工作区初始化等操作。
- SSE 流：聊天与 IM 事件均以 Server-Sent Events 形式推送。
- 外部 CLI：通过本地命令行工具触发登录流程。

章节来源
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/app/api/api-providers/cli-login/route.ts:1-88](file://src/app/api/api-providers/cli-login/route.ts#L1-L88)

## 架构总览
下图展示 Forge API 的主要交互：前端通过 REST 或 SSE 访问后端；后端读写数据库与文件系统，并在需要时调用外部 CLI。

```mermaid
graph TB
FE["前端应用/客户端"]
REST["REST API 路由"]
SSE["SSE 事件流"]
DB["SQLite 数据库"]
FS["文件系统"]
CLI["本地 CLI"]
FE --> REST
FE --> SSE
REST --> DB
REST --> FS
REST --> CLI
SSE --> DB
```

图表来源
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/app/api/api-providers/cli-login/route.ts:1-88](file://src/app/api/api-providers/cli-login/route.ts#L1-L88)

## 详细组件分析

### 代理管理（Agents）
- 描述：列出与创建代理，支持附加技能 ID 列表。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/agents
    - 响应：数组，元素包含代理信息与 skill_ids 字段。
  - POST /api/agents
    - 请求体字段：name、description、model、permission_mode、is_main、parent_id、instructions、soul、identity、tools_config。
    - 响应：新创建的代理对象（skill_ids 初始化为空）。
- 错误码：400（无效 JSON）、409（冲突，未见直接抛出）、201（创建成功）。
- 示例调用路径：
  - [agents GET:5-17](file://src/app/api/agents/route.ts#L5-L17)
  - [agents POST:19-41](file://src/app/api/agents/route.ts#L19-L41)

章节来源
- [src/app/api/agents/route.ts:1-42](file://src/app/api/agents/route.ts#L1-L42)

### API 提供商（API Providers）
- 描述：列出与创建自定义提供商。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/api-providers
    - 响应：提供商列表。
  - POST /api/api-providers
    - 请求体字段：name、baseUrl、apiKey、modelName。
    - 响应：新建提供商记录。
- 错误码：400（缺少必填字段或 JSON 无效）。
- 示例调用路径：
  - [api-providers GET:4-8](file://src/app/api/api-providers/route.ts#L4-L8)
  - [api-providers POST:10-34](file://src/app/api/api-providers/route.ts#L10-L34)

章节来源
- [src/app/api/api-providers/route.ts:1-35](file://src/app/api/api-providers/route.ts#L1-L35)

### CLI 登录（CLI Login）
- 描述：通过本地 CLI 触发登录流程并轮询认证结果。
- 认证：无显式认证头要求。
- 请求/响应：
  - POST /api/api-providers/cli-login
    - 响应：成功时返回账户信息；失败时返回错误信息。
- 错误码：404（CLI 未找到）、500（登录失败或超时）。
- 示例调用路径：
  - [cli-login POST:41-87](file://src/app/api/api-providers/cli-login/route.ts#L41-L87)

章节来源
- [src/app/api/api-providers/cli-login/route.ts:1-88](file://src/app/api/api-providers/cli-login/route.ts#L1-L88)

### 聊天（Chat）
- 描述：发起对话并以 SSE 流式返回结果；支持权限确认、思维模式、会话恢复、附件等。
- 认证：无显式认证头要求。
- 请求/响应：
  - POST /api/chat
    - 请求体字段：sessionId、message、permissionMode（可选）、thinkingMode（可选）、attachments（可选）。
    - 响应：SSE 流，事件类型包括但不限于 attachment、done、error。
    - 连接特性：保持长连接，包含心跳与断开清理。
- 错误码：400（JSON 无效、缺少参数）、404（会话不存在）、500（内部错误）。
- 示例调用路径：
  - [chat POST:74-342](file://src/app/api/chat/route.ts#L74-L342)

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "POST /api/chat"
participant DB as "数据库"
participant SDK as "SDK查询"
participant MAP as "消息映射器"
C->>API : "发送JSON(含sessionId/message/可选参数)"
API->>DB : "读取会话信息"
API->>SDK : "创建查询(支持恢复/权限/思维模式/附件)"
SDK-->>API : "异步生成消息块"
API->>MAP : "映射消息块"
API-->>C : "SSE : attachment/done/error"
API->>DB : "保存用户/助手消息"
API-->>C : "关闭连接(完成/异常)"
```

图表来源
- [src/app/api/chat/route.ts:74-342](file://src/app/api/chat/route.ts#L74-L342)

章节来源
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)

### 定时引擎（Cron Engine）
- 描述：检查与启停定时任务引擎。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/cron-engine
    - 响应：running 布尔值。
  - POST /api/cron-engine
    - 请求体字段：action（"start"|"stop"）。
    - 响应：running 状态。
- 错误码：400（action 非法）。
- 示例调用路径：
  - [cron-engine GET:4-8](file://src/app/api/cron-engine/route.ts#L4-L8)
  - [cron-engine POST:10-29](file://src/app/api/cron-engine/route.ts#L10-L29)

章节来源
- [src/app/api/cron-engine/route.ts:1-30](file://src/app/api/cron-engine/route.ts#L1-L30)

### 数据导出（Data Export）
- 描述：导出会话与消息数据，支持按工作区过滤。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/data/export?workspace=<id>
    - 响应：包含 exportedAt、version、totalSessions、scope、data 的对象。
- 错误码：200（成功）。
- 示例调用路径：
  - [data/export GET:6-37](file://src/app/api/data/export/route.ts#L6-L37)

章节来源
- [src/app/api/data/export/route.ts:1-38](file://src/app/api/data/export/route.ts#L1-L38)

### 即时通讯通道（IM Channels）
- 描述：列出即时通讯通道。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/im-channels
    - 响应：通道列表。
- 错误码：200（成功）。
- 示例调用路径：
  - [im-channels GET:5-12](file://src/app/api/im-channels/route.ts#L5-L12)

章节来源
- [src/app/api/im-channels/route.ts:1-13](file://src/app/api/im-channels/route.ts#L1-L13)

### 即时通讯事件（IM Events）
- 描述：桌面 UI 通过 SSE 订阅 IM 事件。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/im-events
    - 响应：SSE 流，事件类型来自 IM 子系统。
    - 心跳：每 30 秒发送一次 keepalive。
- 错误码：200（成功）。
- 示例调用路径：
  - [im-events GET:13-65](file://src/app/api/im-events/route.ts#L13-L65)

```mermaid
sequenceDiagram
participant UI as "桌面UI(EventSource)"
participant SSE as "GET /api/im-events"
participant BUS as "IM事件总线"
UI->>SSE : "建立SSE连接"
SSE->>BUS : "订阅IM事件"
BUS-->>SSE : "事件到达"
SSE-->>UI : "SSE : event+data"
SSE-->>UI : "keepalive(每30秒)"
UI-->>SSE : "断开(取消订阅)"
```

图表来源
- [src/app/api/im-events/route.ts:13-65](file://src/app/api/im-events/route.ts#L13-L65)

章节来源
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)

### 市场（Marketplace）
- 描述：模板列表与创建空模板。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/marketplace
    - 响应：模板列表。
  - POST /api/marketplace
    - 请求体字段：name。
    - 响应：新建模板记录。
- 错误码：400（name 缺失或无效）。
- 示例调用路径：
  - [marketplace GET:7-15](file://src/app/api/marketplace/route.ts#L7-L15)
  - [marketplace POST:17-39](file://src/app/api/marketplace/route.ts#L17-L39)

章节来源
- [src/app/api/marketplace/route.ts:1-40](file://src/app/api/marketplace/route.ts#L1-L40)

### 模型（Models）
- 描述：聚合内置模型与已连接的自定义提供商模型。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/models
    - 响应：模型列表（包含 provider 与 providerId）。
- 错误码：200（成功）。
- 示例调用路径：
  - [models GET:12-34](file://src/app/api/models/route.ts#L12-L34)

章节来源
- [src/app/api/models/route.ts:1-35](file://src/app/api/models/route.ts#L1-L35)

### 会话（Sessions）
- 描述：列出与创建会话。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/sessions
    - 响应：活动会话列表。
  - POST /api/sessions
    - 请求体字段：title、workspace、model。
    - 响应：新建会话。
- 错误码：201（创建成功）。
- 示例调用路径：
  - [sessions GET:6-16](file://src/app/api/sessions/route.ts#L6-L16)
  - [sessions POST:18-33](file://src/app/api/sessions/route.ts#L18-L33)

章节来源
- [src/app/api/sessions/route.ts:1-34](file://src/app/api/sessions/route.ts#L1-L34)

### 设置（Settings）
- 描述：读取与批量更新设置；首次加载时预热相关服务。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/settings
    - 响应：键值对设置。
  - PUT /api/settings
    - 请求体：键值对集合。
    - 响应：{ ok: true }。
- 错误码：200（成功）。
- 示例调用路径：
  - [settings GET:19-29](file://src/app/api/settings/route.ts#L19-L29)
  - [settings PUT:31-48](file://src/app/api/settings/route.ts#L31-L48)

章节来源
- [src/app/api/settings/route.ts:1-49](file://src/app/api/settings/route.ts#L1-L49)

### 技能（Skills）
- 描述：列出与创建技能。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/skills
    - 响应：技能列表。
  - POST /api/skills
    - 请求体字段：name、description、scope、content。
    - 响应：新建技能。
- 错误码：201（创建成功）。
- 示例调用路径：
  - [skills GET:5-9](file://src/app/api/skills/route.ts#L5-L9)
  - [skills POST:11-26](file://src/app/api/skills/route.ts#L11-L26)

章节来源
- [src/app/api/skills/route.ts:1-27](file://src/app/api/skills/route.ts#L1-L27)

### 任务执行（Task Executions）
- 描述：查询与上报任务执行结果。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/task-executions?task_id=...&workspace_id=...&limit=...&offset=...&type=...&status=...
    - 响应：执行记录列表。
  - POST /api/task-executions
    - 请求体字段：task_id、task_name、result、status、session_id。
    - 响应：新建执行记录。
- 错误码：400（task_id 缺失或无效）。
- 示例调用路径：
  - [task-executions GET:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
  - [task-executions POST:51-75](file://src/app/api/task-executions/route.ts#L51-L75)

章节来源
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)

### 上传（Upload）
- 描述：上传文件附件，限制大小与类型分类。
- 认证：无显式认证头要求。
- 请求/响应：
  - POST /api/upload
    - 表单字段：file（multipart/form-data）。
    - 响应：上传元信息（含 tier 分类）。
- 错误码：400（非 multipart/form-data、文件缺失、文件过大）。
- 示例调用路径：
  - [upload POST:30-90](file://src/app/api/upload/route.ts#L30-L90)

章节来源
- [src/app/api/upload/route.ts:1-91](file://src/app/api/upload/route.ts#L1-L91)

### 工作区（Workspaces）
- 描述：列出与注册工作区，必要时初始化默认目录。
- 认证：无显式认证头要求。
- 请求/响应：
  - GET /api/workspaces
    - 响应：工作区列表（包含派生 name 与存在性）。
  - POST /api/workspaces
    - 请求体字段：path。
    - 响应：新建或更新的工作区。
- 错误码：400（path 缺失或无效）。
- 示例调用路径：
  - [workspaces GET:8-22](file://src/app/api/workspaces/route.ts#L8-L22)
  - [workspaces POST:24-59](file://src/app/api/workspaces/route.ts#L24-L59)

章节来源
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)

## 依赖关系分析
- 组件耦合：
  - 路由层仅负责输入校验、调用业务逻辑与返回响应，耦合度低。
  - 数据库封装集中于 getDb，避免重复连接与配置。
  - SSE 路由依赖事件总线与编码器，生命周期内需正确清理。
- 外部依赖：
  - CLI 登录依赖本地可执行文件与用户主目录下的配置文件。
  - 聊天流依赖 SDK 查询与消息映射器，异常路径包含回退策略。

```mermaid
graph LR
CH["chat/route.ts"] --> DB["数据库"]
CH --> FS["文件系统"]
IME["im-events/route.ts"] --> DB
CLI["api-providers/cli-login/route.ts"] --> BIN["本地CLI"]
UP["upload/route.ts"] --> FS
WS["workspaces/route.ts"] --> FS
```

图表来源
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/app/api/api-providers/cli-login/route.ts:1-88](file://src/app/api/api-providers/cli-login/route.ts#L1-L88)
- [src/app/api/upload/route.ts:1-91](file://src/app/api/upload/route.ts#L1-L91)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)

章节来源
- [src/app/api/chat/route.ts:1-350](file://src/app/api/chat/route.ts#L1-L350)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
- [src/app/api/api-providers/cli-login/route.ts:1-88](file://src/app/api/api-providers/cli-login/route.ts#L1-L88)
- [src/app/api/upload/route.ts:1-91](file://src/app/api/upload/route.ts#L1-L91)
- [src/app/api/workspaces/route.ts:1-60](file://src/app/api/workspaces/route.ts#L1-L60)

## 性能考虑
- SSE 流式输出：
  - 使用 TransformStream 保证块级刷新，避免 Next.js 默认缓冲整包。
  - 聊天与 IM 事件均设置 no-cache、no-transform、keep-alive 与 X-Accel-Buffering=no。
- 数据库访问：
  - 合理使用索引列（如 updated_at、created_at）进行排序与筛选。
  - 导出接口按会话分页读取消息，避免一次性拉取大量数据。
- 文件系统：
  - 上传限制最大尺寸，避免内存与磁盘压力。
  - 附件复制到受控目录，便于后续访问与清理。
- 会话与权限：
  - 会话恢复失败时自动回退至历史提示拼接，减少重复计算。
  - 权限桥接仅在“确认”模式启用，降低额外开销。

章节来源
- [src/app/api/chat/route.ts:147-342](file://src/app/api/chat/route.ts#L147-L342)
- [src/app/api/im-events/route.ts:57-65](file://src/app/api/im-events/route.ts#L57-L65)
- [src/app/api/upload/route.ts:7-90](file://src/app/api/upload/route.ts#L7-L90)
- [src/app/api/data/export/route.ts:10-37](file://src/app/api/data/export/route.ts#L10-L37)

## 故障排查指南
- 聊天流异常：
  - 确认客户端正确处理 SSE 事件类型与错误事件。
  - 若出现“恢复零块”或异常，服务端会自动回退到历史提示重试。
- 会话不存在：
  - 发送聊天请求前先创建会话并获取有效 sessionId。
- CLI 登录失败：
  - 检查本地 CLI 是否安装与可执行；确认 ~/.claude.json 是否存在且可解析。
- 上传失败：
  - 确认 Content-Type 为 multipart/form-data；检查文件大小与扩展名是否被识别为文本/图片/PDF。
- IM 事件不更新：
  - 确保桌面 UI 正确打开 /api/im-events 并维持连接；注意浏览器/代理的心跳超时。

章节来源
- [src/app/api/chat/route.ts:194-238](file://src/app/api/chat/route.ts#L194-L238)
- [src/app/api/api-providers/cli-login/route.ts:41-87](file://src/app/api/api-providers/cli-login/route.ts#L41-L87)
- [src/app/api/upload/route.ts:30-90](file://src/app/api/upload/route.ts#L30-L90)
- [src/app/api/im-events/route.ts:13-65](file://src/app/api/im-events/route.ts#L13-L65)

## 结论
Forge 的 API 设计遵循清晰的领域划分与最小职责原则：路由层专注输入校验与响应，业务逻辑通过数据库与文件系统协作完成；SSE 用于实时交互，CLI 集成满足本地认证场景。遵循本文档的参数、错误码与最佳实践，可高效构建稳定可靠的集成方案。

## 附录
- 最佳实践
  - SSE 客户端：使用 EventSource，定期检查连接状态，实现自动重连与心跳处理。
  - 聊天请求：在发送前确保会话存在与权限模式符合预期；合理设置 thinkingMode 与附件类型。
  - 上传附件：优先使用受支持的文本/图片/PDF 类型，控制文件大小与数量。
  - 设置项：通过 /api/settings 批量更新，避免频繁小事务。
- 常见用例
  - 创建工作区并初始化默认文件夹，随后注册会话与代理。
  - 通过 SSE 订阅 IM 事件，实现实时同步。
  - 使用 CLI 登录获取账户信息，再创建自定义提供商。
- 调试工具
  - 使用浏览器网络面板观察 SSE 连接与事件类型。
  - 通过 /api/data/export 导出会话数据进行离线分析。
  - 在服务端日志中关注“恢复零块”“权限确认”等关键路径。