docs: 更新 Agent 协议文档与部署配置

- 更新 Agent API 端点文档
- 更新 SSE 事件与输入输出文档
- 新增 deploy/.env.prod.example 配置模板

docs/protocols/agent/api-endpoints.md

@@ -1,6 +1,6 @@
 # Agent API Endpoints
 
-本文档列出所有 Agent 相关的 API 端点。
+本文档以当前后端实现为准，描述 `/api/v1/agent` 的 HTTP 接口契约。
 
 Base URL: `/api/v1/agent`
 
@@ -8,353 +8,220 @@ Base URL: `/api/v1/agent`
 
 ## 端点清单
 
-| 方法 | 路径 | 描述 |
-|------|------|------|
-| POST | `/runs` | 发起 Agent 运行 |
-| GET | `/runs/{thread_id}/events` | SSE 事件流 |
-| GET | `/history` | 获取对话历史快照 |
-| POST | `/attachments` | 上传附件 |
-| GET | `/attachments/signed-url` | 生成附件签名 URL |
-| POST | `/transcribe` | 语音转文字 (ASR) |
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| POST | `/runs` | 创建一次 agent run（异步入队） |
+| GET | `/runs/{thread_id}/events` | 订阅 SSE 事件流 |
+| GET | `/history` | 获取历史快照（按天分页） |
+| POST | `/attachments` | 上传用户图片附件 |
+| GET | `/attachments/signed-url` | 获取附件临时签名链接 |
+| POST | `/transcribe` | WAV 音频转写 |
 
 ---
 
-## 1. POST /runs
+## 1) POST `/runs`
 
-发起一个 Agent 运行任务。
+发起一次运行请求，后端会先持久化用户消息，再将命令放入异步队列。
 
 ### Request
 
-Request Body: `RunAgentInput`
-
-详细数据结构见 [run-agent-input.md](./run-agent-input.md)
+- Body: `RunAgentInput`
+- 详细结构见 `docs/protocols/agent/run-agent-input.md`
 
 ### Response
 
-```typescript
+`202 Accepted`
+
+```ts
 {
-  taskId: string,      // 任务 ID
-  threadId: string,   // 会话 ID
-  runId: string,      // 运行 ID
-  created: string     // ISO-8601 时间戳
+  taskId: string;
+  threadId: string;
+  runId: string;
+  created: boolean; // 是否新建了会话
 }
 ```
 
-### Example
+### 错误码
 
-```bash
-curl -X POST https://api.example.com/api/v1/agent/runs \
-  -H "Content-Type: application/json" \
-  -d '{
-    "threadId": "550e8400-e29b-41d4-a716-446655440000",
-    "runId": "run-001",
-    "state": {},
-    "messages": [
-      {
-        "id": "msg-001",
-        "role": "user",
-        "content": "帮我查一下北京今天的天气"
-      }
-    ],
-    "tools": [],
-    "context": [],
-    "forwardedProps": {}
-  }'
-```
-
-### Response Example
-
-```json
-{
-  "taskId": "task-abc123",
-  "threadId": "550e8400-e29b-41d4-a716-446655440000",
-  "runId": "run-001",
-  "created": "2026-03-16T10:00:00Z"
-}
-```
+- `401` 未认证
+- `422` 请求结构校验失败
+- `429` 超过 run 请求速率限制
 
 ---
 
-## 2. GET /runs/{thread_id}/events
+## 2) GET `/runs/{thread_id}/events`
 
-获取 SSE 事件流，用于实时接收 Agent 运行过程中的事件。
+订阅指定 thread 的实时事件流。
 
-### Path Parameters
+### Path
 
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| thread_id | string | 会话 ID |
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `thread_id` | string | 会话 ID |
 
-### Query Parameters
+### Query
 
-| 参数 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| Last-Event-ID | string | - | 可选，用于断点续传的事件 ID |
-| idle_limit | integer | 300 | 最大空闲轮询次数 (1-3600) |
+| 参数 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `idle_limit` | integer | `300` | 最大空闲轮询次数（1-3600） |
 
 ### Headers
 
-| 参数 | 描述 |
-|------|------|
-| Last-Event-ID | 可选的事件 ID，用于从指定位置恢复 |
+| Header | 必填 | 说明 |
+|---|---|---|
+| `Accept: text/event-stream` | 否 | 建议显式设置 |
+| `Last-Event-ID` | 否 | 从指定游标断点续流 |
 
 ### Response
 
-SSE (Server-Sent Events) 流，Content-Type: `text/event-stream`
+- `200 OK`
+- `Content-Type: text/event-stream`
+- 事件类型与字段见 `docs/protocols/agent/sse-events.md`
+- 空闲时会发送 keep-alive 注释行 `: keep-alive`
 
-事件类型详情见 [sse-events.md](./sse-events.md)
+### 错误码
 
-### Example
-
-```javascript
-const eventSource = new EventSource(
-  'https://api.example.com/api/v1/agent/runs/550e8400-e29b-41d4-a716-446655440000/events'
-);
-
-eventSource.addEventListener('run.started', (e) => {
-  const data = JSON.parse(e.data);
-  console.log('Started:', data);
-});
-
-eventSource.addEventListener('text.delta', (e) => {
-  const data = JSON.parse(e.data);
-  console.log('Delta:', data.data.delta);
-});
-
-eventSource.addEventListener('run.finished', (e) => {
-  const data = JSON.parse(e.data);
-  console.log('Finished:', data);
-});
-```
+- `401` 未认证
+- `403` 非会话所有者
+- `422` `Last-Event-ID` 非法
+- `429` 超过 SSE 连接数限制
 
 ---
 
-## 3. GET /history
+## 3) GET `/history`
 
-获取对话历史快照。
+返回历史快照（`HistorySnapshotResponse`），不是 SSE 包装事件。
 
-### Query Parameters
+### Query
 
-| 参数 | 类型 | 必填 | 描述 |
-|------|------|------|------|
-| threadId | string | 否 | 会话 ID，不指定则返回最新会话 |
-| before | date | 否 | 日期格式 `YYYY-MM-DD`，返回该日期之前的快照 |
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `threadId` | string | 否 | 指定会话，不传则取当前用户最近会话 |
+| `before` | `YYYY-MM-DD` | 否 | 返回该日期之前最近一天的快照 |
 
 ### Response
 
-```typescript
+```ts
 {
-  scope: "history_day",
-  threadId: string | null,
-  day: string | null,        // ISO date format "YYYY-MM-DD"
-  hasMore: boolean,
-  messages: HistoryMessage[]
+  scope: "history_day";
+  threadId: string | null;
+  day: string | null;      // YYYY-MM-DD
+  hasMore: boolean;
+  messages: Array<{
+    id: string;
+    seq: number;
+    role: "user" | "assistant" | "tool";
+    content: string;
+    url?: string | null;       // user 附件签名链接
+    ui_schema?: object | null; // assistant/tool 的编译后 UI
+    timestamp: string;         // ISO-8601
+  }>;
 }
 ```
 
-详细数据结构见 [run-agent-input.md](./run-agent-input.md)
+### 说明
 
-### Example
-
-```bash
-curl "https://api.example.com/api/v1/agent/history?threadId=550e8400-e29b-41d4-a716-446655440000&before=2026-03-15"
-```
-
-### Response Example
-
-```json
-{
-  "scope": "history_day",
-  "threadId": "550e8400-e29b-41d4-a716-446655440000",
-  "day": "2026-03-15",
-  "hasMore": false,
-  "messages": [
-    {
-      "id": "msg-001",
-      "seq": 1,
-      "role": "user",
-      "content": "帮我创建一个日程",
-      "url": null,
-      "timestamp": "2026-03-15T10:00:00Z"
-    },
-    {
-      "id": "msg-002",
-      "seq": 2,
-      "role": "assistant",
-      "content": "好的，我来帮您创建日程。",
-      "uiSchema": {
-        "version": "2.0",
-        "locale": "zh-CN",
-        "status": "success",
-        "theme": "default",
-        "root": {
-          "type": "stack",
-          "appearance": "card",
-          "children": [
-            {"type": "text", "content": "日程已创建", "role": "title"},
-            {"type": "badge", "label": "SUCCESS", "status": "success"}
-          ]
-        }
-      },
-      "timestamp": "2026-03-15T10:00:05Z"
-    }
-  ]
-}
-```
+- 若用户没有任何会话：返回
+  - `threadId = null`
+  - `day = null`
+  - `hasMore = false`
+  - `messages = []`
 
 ---
 
-## 4. POST /attachments
+## 4) POST `/attachments`
 
-上传附件到存储。
+上传图片附件，返回可直接用于 `RunAgentInput.messages[].content[].url` 的签名链接。
 
-### Form Data
+### Request
 
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| threadId | string | 会话 ID |
-| file | file | 要上传的文件 |
+- `multipart/form-data`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `threadId` | string | 会话 ID |
+| `file` | file | 附件文件 |
 
 ### Response
 
-```typescript
+```ts
 {
   attachment: {
-    bucket: string,
-    path: string,
-    mimeType: string,
-    size: number,
-    url: string        // 临时访问 URL
-  }
+    bucket: string;
+    path: string;
+    mimeType: string;
+    url: string;
+  };
 }
 ```
 
-### Example
+### 错误码
 
-```bash
-curl -X POST https://api.example.com/api/v1/agent/attachments \
-  -F "threadId=550e8400-e29b-41d4-a716-446655440000" \
-  -F "file=@/path/to/image.png"
-```
-
-### Limits
-
-- 最大文件大小: 5MB
-- 支持的文件类型: 见后端配置
+- `401` 未认证
+- `403` 非会话所有者
+- `413` 附件超过大小限制
+- `422` 文件类型不支持/空文件等
+- `503` 存储服务不可用
 
 ---
 
-## 5. GET /attachments/signed-url
+## 5) GET `/attachments/signed-url`
 
-生成附件的签名 URL，用于直接访问存储中的文件。
+对已有存储对象重新签名。
 
-### Query Parameters
+### Query
 
-| 参数 | 类型 | 必填 | 描述 |
-|------|------|------|------|
-| bucket | string | 是 | 存储桶名称 |
-| path | string | 是 | 文件路径 |
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `bucket` | string | 是 | 存储桶 |
+| `path` | string | 是 | 对象路径 |
 
 ### Response
 
-```typescript
+```ts
 {
-  bucket: string,
-  path: string,
-  url: string        // 签名 URL
-}
-```
-
-### Example
-
-```bash
-curl "https://api.example.com/api/v1/agent/attachments/signed-url?bucket=agent-inputs&path=user-123/image.png"
-```
-
-### Response Example
-
-```json
-{
-  "bucket": "agent-inputs",
-  "path": "user-123/image.png",
-  "url": "https://storage.example.com/agent-inputs/user-123/image.png?signature=abc123..."
+  bucket: string;
+  path: string;
+  url: string;
 }
 ```
 
 ---
 
-## 6. POST /transcribe
+## 6) POST `/transcribe`
 
-语音转文字 (ASR)。
+WAV 音频转写。
 
 ### Request
 
-Form Data:
+- `multipart/form-data`
 
-| 参数 | 类型 | 描述 |
-|------|------|------|
-| audio | file | 音频文件 (WAV 格式) |
-
-### Headers
-
-| 参数 | 描述 |
-|------|------|
-| content-length | 文件大小 |
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `audio` | file | WAV 文件 |
 
 ### Response
 
-```typescript
+```ts
 {
-  transcript: string,     // 转录文本
-  language: string,       // 检测到的语言
-  duration: number       // 音频时长 (秒)
+  transcript: string;
 }
 ```
 
-### Example
+### 限制
 
-```bash
-curl -X POST https://api.example.com/api/v1/agent/transcribe \
-  -F "audio=@/path/to/audio.wav"
-```
-
-### Response Example
-
-```json
-{
-  "transcript": "今天天气真不错",
-  "language": "zh-CN",
-  "duration": 3.5
-}
-```
-
-### Limits
-
-- 支持格式: `audio/wav`, `audio/x-wav`, `audio/wave`
-- 最大文件大小: 10MB
-- 速率限制: 20 次/分钟/用户
+- 内容类型：`audio/wav` / `audio/x-wav` / `audio/wave`
+- 文件大小：最大 10MB
+- 速率限制：20 次/分钟/用户
 
 ---
 
-## 错误响应
+## 通用错误
 
-所有端点可能返回以下错误：
-
-| 状态码 | 描述 |
-|--------|------|
-| 400 | 请求参数错误 |
-| 401 | 未认证 |
-| 403 | 无权限 |
-| 404 | 资源不存在 |
-| 413 | 请求体过大 |
-| 422 | 数据验证失败 |
-| 429 | 速率限制 |
-| 500 | 服务器内部错误 |
-
-### Error Response Format
+当前实现的错误主体为 FastAPI `detail` 字段：
 
 ```json
 {
-  "detail": "错误详情信息"
+  "detail": "..."
 }
 ```

docs/protocols/agent/run-agent-input.md

@@ -307,7 +307,7 @@ interface TaskAcceptedResponse {
   taskId: string;
   threadId: string;
   runId: string;
-  created: string;  // ISO-8601 timestamp
+  created: boolean; // 是否新建会话
 }
 ```
 
@@ -359,7 +359,7 @@ interface HistoryMessageTool {
   seq: number;
   role: "tool";
   content: string;
-  uiSchema: UiSchemaRenderer | null;  // 由 tool_agent_output.ui_hints 编译
+  ui_schema: UiSchemaRenderer | null; // 由 tool_agent_output.ui_hints 编译
   timestamp: string;
 }
 
@@ -369,7 +369,7 @@ interface HistoryMessageAssistant {
   seq: number;
   role: "assistant";
   content: string;
-  uiSchema: UiSchemaRenderer | null;  // 由 worker_agent_output.ui_hints 编译
+  ui_schema: UiSchemaRenderer | null; // 由 worker_agent_output.ui_hints 编译
   timestamp: string;
 }
 
@@ -418,7 +418,7 @@ interface UiSchemaRenderer {
       "seq": 2,
       "role": "assistant",
       "content": "好的，我来帮您创建日程。",
-      "uiSchema": {
+      "ui_schema": {
         "version": "2.0",
         "locale": "zh-CN",
         "status": "success",
@@ -447,3 +447,4 @@ interface UiSchemaRenderer {
 - binary content 的 url 必须是有效的 signed URL，由 `/api/v1/agent/attachments` 端点生成
 - backend 验证通过后，会将 binary url 转换为内部存储路径
 - tools 为空数组时，prompt 中不会包含工具说明
+- `RunAgentInput` 同时接受 camelCase 与 snake_case 别名输入（推荐统一使用 camelCase）

docs/protocols/agent/sse-events.md

@@ -1,370 +1,213 @@
 # Agent SSE Events
 
-本文档记录 Agent Runtime 产生的所有 Server-Sent Events (SSE) 事件，用于前端实时展示。
+本文档描述 `GET /api/v1/agent/runs/{thread_id}/events` 的事件协议。
 
-## 事件流转架构
+---
+
+## 1) 事件管道
+
+后端事件流转如下：
+
+1. Runtime 直接产出 AG-UI 事件（如 `RUN_STARTED`、`TOOL_CALL_RESULT`）
+2. `agui_codec` 仅做协议对齐与字段净化（例如移除仅后端内部统计字段）
+3. 事件同时：
+   - 持久化到数据库（用于 history）
+   - 发布到 Redis Stream（用于 SSE）
+4. `/runs/{thread_id}/events` 从 Redis Stream 读取并输出 SSE
+
+---
+
+## 2) SSE 帧格式
+
+每条事件遵循标准 SSE：
+
+```text
+id: <redis-stream-id>
+event: <AG-UI-EVENT-TYPE>
+data: <json>
 
-```
-pipeline.emit()
-    ↓
-AgentScopeEventPipeline.emit()
-    ├─→ store.persist()  → 持久化到数据库
-    └─→ bus.publish()    → 发布到 Redis Stream
-            ↓
-前端通过 GET /runs/{thread_id}/events 读取
 ```
 
-## 事件统一格式
+- `id` 可用于断点续流（`Last-Event-ID`）
+- `event` 与 JSON 内 `type` 一致（例如 `RUN_STARTED`）
+- 空闲时可能出现 keep-alive 注释帧：
 
-所有事件在 Redis 中传输时都包含以下字段：
+```text
+: keep-alive
 
-```typescript
-{
-  type: string,       // 事件类型
-  threadId: string,   // 会话 ID
-  runId: string,      // 运行 ID
-  data: object        // 事件数据
-}
 ```
 
 ---
 
-## 1. Orchestrator 生命周期事件
+## 3) 事件类型（当前实现）
 
-### run.started
+### 3.1 Run 生命周期
 
-Agent 开始运行时触发。
+#### `RUN_STARTED`
 
-```typescript
+```json
 {
-  type: "run.started",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {}
+  "type": "RUN_STARTED",
+  "threadId": "...",
+  "runId": "..."
 }
 ```
 
-### run.finished
+#### `RUN_FINISHED`
 
-Agent 成功完成时触发。
-
-```typescript
+```json
 {
-  type: "run.finished",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {}
+  "type": "RUN_FINISHED",
+  "threadId": "...",
+  "runId": "..."
 }
 ```
 
-### run.error
+#### `RUN_ERROR`
 
-Agent 运行出错时触发。
-
-```typescript
+```json
 {
-  type: "run.error",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    message: "runtime execution failed"
-  }
+  "type": "RUN_ERROR",
+  "threadId": "...",
+  "runId": "...",
+  "message": "runtime execution failed",
+  "code": null
 }
 ```
 
+### 3.2 阶段事件
+
+#### `STEP_STARTED`
+
+```json
+{
+  "type": "STEP_STARTED",
+  "threadId": "...",
+  "runId": "...",
+  "stepName": "router" | "worker"
+}
+```
+
+#### `STEP_FINISHED`
+
+```json
+{
+  "type": "STEP_FINISHED",
+  "threadId": "...",
+  "runId": "...",
+  "stepName": "router" | "worker"
+}
+```
+
+### 3.3 Tool 事件
+
+#### `TOOL_CALL_START`
+
+```json
+{
+  "type": "TOOL_CALL_START",
+  "threadId": "...",
+  "runId": "...",
+  "messageId": "...",
+  "toolCallId": "...",
+  "toolCallName": "...",
+  "stage": "worker"
+}
+```
+
+#### `TOOL_CALL_ARGS`
+
+```json
+{
+  "type": "TOOL_CALL_ARGS",
+  "threadId": "...",
+  "runId": "...",
+  "messageId": "...",
+  "toolCallId": "...",
+  "toolCallName": "...",
+  "args": {},
+  "stage": "worker"
+}
+```
+
+#### `TOOL_CALL_END`
+
+```json
+{
+  "type": "TOOL_CALL_END",
+  "threadId": "...",
+  "runId": "...",
+  "messageId": "...",
+  "toolCallId": "...",
+  "toolCallName": "...",
+  "stage": "worker"
+}
+```
+
+#### `TOOL_CALL_RESULT`
+
+```json
+{
+  "type": "TOOL_CALL_RESULT",
+  "threadId": "...",
+  "runId": "...",
+  "messageId": "...",
+  "role": "tool",
+  "stage": "worker",
+  "tool_name": "...",
+  "tool_call_id": "...",
+  "tool_call_args": {},
+  "status": "success" | "failed",
+  "result_summary": "...",
+  "ui_schema": {},
+  "error": null
+}
+```
+
+### 3.4 文本完成事件
+
+#### `TEXT_MESSAGE_END`
+
+当前实现仅在 worker 输出完成后发送完整结果，不发送 token delta 事件。
+
+```json
+{
+  "type": "TEXT_MESSAGE_END",
+  "threadId": "...",
+  "runId": "...",
+  "messageId": "...",
+  "role": "assistant",
+  "stage": "worker",
+  "status": "success" | "partial_success" | "failed",
+  "answer": "...",
+  "key_points": [],
+  "result_type": "execution_report" | "clarification" | "error_report" | "unknown",
+  "suggested_actions": [],
+  "error": null,
+  "ui_schema": {}
+}
+```
+
+`inputTokens`、`outputTokens`、`cost`、`latencyMs`、`model` 属于后端内部统计字段，不在 SSE 对外协议中暴露。
+
+### 3.5 快照事件
+
+编码器支持以下 AG-UI 类型映射：
+
+- `STATE_SNAPSHOT`
+- `MESSAGES_SNAPSHOT`
+
+当前 `/runs/{thread_id}/events` 主流程通常不主动产出这两类事件；历史查询请使用 `/history`。
+
 ---
 
-## 2. Step 阶段事件
+## 4) 字段命名约定
 
-### step.start
+- 事件顶层通用字段使用 AG-UI 风格：`type`、`threadId`、`runId`
+- 部分业务字段沿运行时模型历史命名保留下划线：
+  - `tool_name`
+  - `tool_call_id`
+  - `tool_call_args`
+  - `ui_schema`
 
-阶段开始时触发。
-
-```typescript
-{
-  type: "step.start",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    stepName: "router" | "worker"
-  }
-}
-```
-
-### step.finish
-
-阶段结束时触发。
-
-```typescript
-{
-  type: "step.finish",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    stepName: "router" | "worker"
-  }
-}
-```
-
----
-
-## 3. Worker 运行时事件
-
-### 3.1 文本消息事件
-
-#### text.start
-
-文本消息开始时触发。
-
-```typescript
-{
-  type: "text.start",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    messageId: "msg-xxx",
-    role: "assistant",
-    stage: "worker"
-  }
-}
-```
-
-#### text.delta
-
-文本内容增量更新时触发。
-
-```typescript
-{
-  type: "text.delta",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    messageId: "msg-xxx",
-    delta: "这是新增的文本内容",
-    stage: "worker"
-  }
-}
-```
-
-#### text.end
-
-文本消息结束时触发，包含完整输出和使用统计。
-
-```typescript
-{
-  type: "text.end",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    messageId: "msg-xxx",
-    role: "assistant",
-    stage: "worker",
-    workerAgentOutput: {
-      status: "success" | "partial_success" | "failed",
-      answer: "主回复文本",
-      key_points: ["要点1", "要点2"],
-      result_type: "execution_report" | "clarification" | "error_report" | "unknown",
-      suggested_actions: ["建议操作1"],
-      error: null | { code: string, message: string },
-      ui_hints: { ... } | null  // 仅在 ui_mode 非空时存在
-    },
-    model: "gpt-4o",
-    inputTokens: 1000,
-    outputTokens: 500,
-    cost: 0.025,
-    latencyMs: 1500
-  }
-}
-```
-
-**workerAgentOutput 详细结构：**
-
-```typescript
-// WorkerAgentOutputLite
-{
-  status: "success" | "partial_success" | "failed",
-  answer: string,
-  key_points: string[],
-  result_type: "execution_report" | "clarification" | "error_report" | "unknown",
-  suggested_actions: string[],
-  error: { code: string, message: string } | null
-}
-
-// WorkerAgentOutputRich (当 ui.ui_mode 非空时)
-{
-  // ... WorkerAgentOutputLite 字段
-  ui_hints: {
-    ui_mode: string,
-    ui_state: object,
-    actions: UiHintAction[]
-  }
-}
-```
-
----
-
-### 3.2 工具调用事件
-
-#### tool.start
-
-工具调用开始时触发。
-
-```typescript
-{
-  type: "tool.start",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    messageId: "msg-xxx",
-    toolCallId: "call-abc",
-    toolName: "calendar_read",
-    stage: "worker"
-  }
-}
-```
-
-#### tool.args
-
-工具调用参数时触发。
-
-```typescript
-{
-  type: "tool.args",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    messageId: "msg-xxx",
-    toolCallId: "call-abc",
-    toolName: "calendar_read",
-    args: { start_date: "2024-01-01", end_date: "2024-01-07" },
-    stage: "worker"
-  }
-}
-```
-
-#### tool.end
-
-工具调用结束时触发。
-
-```typescript
-{
-  type: "tool.end",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    messageId: "msg-xxx",
-    toolCallId: "call-abc",
-    toolName: "calendar_read",
-    stage: "worker"
-  }
-}
-```
-
-#### tool.result
-
-工具执行结果时触发。
-
-```typescript
-{
-  type: "tool.result",
-  threadId: "xxx",
-  runId: "yyy",
-  data: {
-    messageId: "msg-xxx",
-    toolCallId: "call-abc",
-    toolName: "calendar_read",
-    stage: "worker",
-    toolAgentOutput: {
-      tool_name: "calendar_read",
-      tool_call_id: "call-abc",
-      tool_call_args: { start_date: "2024-01-01", end_date: "2024-01-07" },
-      status: "success" | "failed",
-      result_summary: "找到3个事件...",
-      ui_hints: null,
-      attachments: null
-    }
-  }
-}
-```
-
-**toolAgentOutput 详细结构：**
-
-```typescript
-{
-  tool_name: string,
-  tool_call_id: string,
-  tool_call_args: object | null,
-  status: "success" | "failed",
-  result_summary: string,
-  ui_hints: object | null,
-  attachments: Array<{
-    bucket: string,
-    path: string,
-    mime_type: string,
-    url: string
-  }> | null
-}
-```
-
----
-
-## 使用统计字段
-
-`text.end` 事件中包含使用统计：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `model` | string | 使用的模型名称 |
-| `inputTokens` | number | 输入 token 数量 |
-| `outputTokens` | number | 输出 token 数量 |
-| `cost` | number | 花费（美元） |
-| `latencyMs` | number | 延迟（毫秒） |
-
----
-
-## 前端接收示例
-
-```javascript
-const eventSource = new EventSource(`/runs/${threadId}/events`);
-
-eventSource.addEventListener('run.started', (e) => {
-  console.log('Agent started:', JSON.parse(e.data));
-});
-
-eventSource.addEventListener('step.start', (e) => {
-  console.log('Step started:', JSON.parse(e.data));
-});
-
-eventSource.addEventListener('text.delta', (e) => {
-  const data = JSON.parse(e.data);
-  console.log('Text delta:', data.data.delta);
-});
-
-eventSource.addEventListener('tool.start', (e) => {
-  const data = JSON.parse(e.data);
-  console.log('Tool called:', data.data.toolName);
-});
-
-eventSource.addEventListener('tool.result', (e) => {
-  const data = JSON.parse(e.data);
-  console.log('Tool result:', data.data.toolAgentOutput);
-});
-
-eventSource.addEventListener('text.end', (e) => {
-  const data = JSON.parse(e.data);
-  console.log('Worker output:', data.data.workerAgentOutput);
-  console.log('Usage:', {
-    inputTokens: data.data.inputTokens,
-    outputTokens: data.data.outputTokens,
-    cost: data.data.cost
-  });
-});
-
-eventSource.addEventListener('run.finished', (e) => {
-  console.log('Agent finished:', JSON.parse(e.data));
-});
-
-eventSource.addEventListener('run.error', (e) => {
-  console.log('Agent error:', JSON.parse(e.data));
-});
-```
+这部分命名属于当前后端实现约束，文档与实现保持一致。