# IM 工作台 AI 前后端对接文档

> 版本：v1.0  
> 日期：2026-09-25  
> 需求依据：[IM 工作台 AI 接入需求文档](./IM工作台AI接入需求文档.md)  
> IM 依据：[IM 前后端对接文档](./IM-前后端对接文档.md)  
> 参考格式：[禾圃集后院养成与物友动态前后端对接文档](./禾圃集-后院养成与物友动态前后端对接文档.md)  
> 说明：本文补充 IM 工作台 AI 能力的前后端对接契约，包括工作台 AI 入口、应用搜索、智能文档、智能表格、AI 美文、日报/月报 AI 接入、会议笔记 AI 总结、AI 任务与记录。IM 登录、租户、用户体系、文件服务、工作台原有日报/月报/会议接口沿用现有 IM 与 workbench 协议。

## 0. 公共对接约定

### 0.1 实现状态

| 状态 | 含义 |
| --- | --- |
| `新增` | 当前工作台接口未覆盖，需要新增服务端模型和接口 |
| `复用` | 沿用 IM 或 workbench 既有能力，例如登录、租户、文件上传、日报/月报提交 |
| `需改造` | 已有基础能力，但需要补充 AI 字段、记录、状态或权限判断 |
| `纯客户端` | 只影响本地 UI、动效、输入缓存或前端路由，不新增服务端接口 |

本文所有接口均为目标契约。接口完成前，前端可按相同字段结构使用 Mock；联调时以本文字段名、枚举值、错误码和幂等规则为准。所有 ID、游标、用户 ID、会议 ID、文件 ID 统一按字符串处理。

### 0.2 鉴权、租户与路径

工作台 AI 接口复用 IM 登录态：

1. 客户端必须先按 IM 登录流程拿到用户 Token，再访问本文接口。
2. 服务端从 Token 与 Header 解析当前租户和用户，客户端不得在请求体中传 `tenant_id`、`user_id` 来覆盖身份。
3. 工作台 AI 数据必须按租户、用户隔离；用户只能访问本人创建的 AI 任务和记录，会议 AI 总结按会议笔记权限判断。
4. 写接口必须支持幂等，客户端传 `Idempotency-Key`；同一幂等键请求体不同，返回 `IDEMPOTENCY_CONFLICT`。
5. AI 内容、原始输入、上传文件解析结果、模型响应和错误日志均需脱敏后入库或打印。

建议路径前缀：

```text
https://{host}/v1/workbench/ai/*
```

公共 Header：

| Header | 必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | `Bearer <IM 登录 token>` |
| `X-MeetingIM-APIKey` | 是 | 沿用 IM 客户端预置 API Key |
| `X-IM-Schema` | 是 | 固定传 `1` |
| `X-Tenant-Code` | 是 | 当前租户编码，例如 `system` |
| `X-Request-ID` | 是 | 客户端生成的请求追踪 ID |
| `Idempotency-Key` | 写接口必填 | 幂等键，避免弱网重复提交 |

文件上传沿用 IM 文件服务。智能表格原始文件建议上传为 `purpose=ai_table_source`，会议笔记附件仍沿用会议笔记既有 `purpose`。

### 0.3 成功与失败响应

成功响应统一为：

```json
{
  "code": 0,
  "data": {},
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWB",
  "server_time": "2026-09-25T08:30:15.123Z"
}
```

失败响应统一为：

```json
{
  "code": 30000,
  "reason": "MALFORMED_REQUEST",
  "message": "malformed request",
  "details": {
    "field": "source_text",
    "limit": 1000
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWB",
  "server_time": "2026-09-25T08:30:15.123Z"
}
```

前端只使用稳定 `reason` 分支和本地化文案，不解析 `message`。分页统一使用 `limit` 与不透明 `cursor`，返回 `items`、`next_cursor`、`has_more`。时间统一为 UTC RFC3339。

### 0.4 枚举约定

#### 0.4.1 AI 能力类型

| 枚举 | 说明 |
| --- | --- |
| `smart_document` | 智能文档 |
| `smart_table` | 智能表格/报告解读 |
| `text_polish` | AI 美文 |
| `daily_report_polish` | 日报 AI 美化 |
| `monthly_report_polish` | 月报 AI 美化 |
| `meeting_summary` | 会议笔记 AI 总结 |

#### 0.4.2 AI 任务状态

| 枚举 | 说明 |
| --- | --- |
| `queued` | 已入队，等待执行 |
| `processing` | 处理中 |
| `succeeded` | 处理成功 |
| `failed` | 处理失败 |
| `canceled` | 已取消 |
| `expired` | 结果已过期 |

#### 0.4.3 AI 记录类型

| 枚举 | 说明 |
| --- | --- |
| `smart_document` | 智能文档记录 |
| `smart_table` | 智能表格解读记录 |
| `text_polish` | AI 美文记录，首版可不展示到记录中心 |
| `meeting_summary` | 会议总结记录，挂在会议下 |

#### 0.4.4 文件类型

| 枚举 | 说明 |
| --- | --- |
| `xlsx` | Excel 工作簿 |
| `xls` | 旧版 Excel 工作簿 |
| `csv` | CSV 数据文件 |
| `docx` | Word 文档，导出场景使用 |
| `pdf` | PDF 文档，导出场景使用 |

#### 0.4.5 表格解读步骤

| 枚举 | 说明 |
| --- | --- |
| `read_file` | 读取表格数据 |
| `detect_metrics` | 识别核心指标 |
| `analyze_trends` | 分析趋势变化 |
| `generate_report` | 生成解读报告 |

#### 0.4.6 AI 推送结果类型

| 枚举 | 说明 |
| --- | --- |
| `text` | 文本结果，适用于 AI 美文、日报/月报润色、较短的智能文档草稿 |
| `file` | 文件结果，适用于导出 docx、pdf 等文件；推送中返回文件服务下载地址 |
| `record` | 记录结果，适用于智能表格、智能文档等已生成记录的能力 |
| `summary` | 会议总结类结果，挂在会议下展示 |

### 0.5 通用错误码

| reason | HTTP | 说明 | 前端处理 |
| --- | --- | --- | --- |
| `UNAUTHORIZED` | 401 | Token 缺失、过期或无效 | 回到登录 |
| `FORBIDDEN` | 403 | 无权限访问 AI 能力、记录或会议 | 展示无权限 |
| `MALFORMED_REQUEST` | 400 | 请求体格式错误 | 按接口提示修正 |
| `VALIDATION_FAILED` | 400 | 字段校验失败 | 按字段提示 |
| `RESOURCE_NOT_FOUND` | 404 | 对象不存在或无权感知 | 展示不存在或已失效 |
| `IDEMPOTENCY_CONFLICT` | 409 | 同一幂等键请求体不一致 | 停止重试并上报 |
| `AI_QUOTA_EXCEEDED` | 429 | AI 用量超限 | 提示今日次数已用完 |
| `RATE_LIMITED` | 429 | 触发频控 | 提示稍后再试 |
| `AI_PROVIDER_FAILED` | 502 | AI 供应商调用失败 | 可重试 |
| `AI_TIMEOUT` | 504 | AI 处理超时 | 展示超时并允许重试 |
| `AI_CONTENT_REJECTED` | 422 | 输入或输出命中内容安全 | 提示内容不适合生成 |
| `AI_TASK_FAILED` | 500 | AI 任务执行失败 | 展示失败并允许重试 |
| `FILE_TOO_LARGE` | 413 | 文件超过限制 | 提示压缩或更换文件 |
| `FILE_TYPE_UNSUPPORTED` | 415 | 文件类型不支持 | 提示仅支持 xls/xlsx/csv |
| `FILE_UNAVAILABLE` | 404 | 文件不存在、已过期或无权限 | 重新上传 |

### 0.6 分页、轮询与幂等

| 场景 | 约定 |
| --- | --- |
| 列表分页 | `limit` 默认 20，最大 50；`cursor` 为服务端不透明字符串 |
| 任务轮询 | 前端创建任务后每 1.5 秒轮询一次，连续 30 秒后改为每 3 秒，最长 2 分钟 |
| 弱网重试 | 写接口使用同一个 `Idempotency-Key` 重试 |
| 取消任务 | 只允许取消 `queued`、`processing` 状态任务 |
| 记录保存 | 智能文档生成成功后，必须显式保存才进入文档记录；智能表格解读成功后默认生成记录 |
| 在线推送 | AI 任务完成后仅推送当前在线用户；离线用户不补推，上线后通过任务或记录接口重新拉取 |
| 推送兜底 | 前端接入推送后仍需保留轮询和页面恢复拉取，推送只作为实时体验优化 |

## 1. 工作台 AI 入口与应用搜索

本章对应工作台首页、搜索默认页、搜索结果页和无结果页。工作台原有应用仍走既有接口；本文补充 AI 能力开关、限制和搜索字段。

### 1.1 获取工作台 AI 能力

#### 需求图片

<img src="ai/工作台.png" alt="工作台" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/capabilities` |
| 用途 | 获取当前租户、当前用户可用的 AI 能力、用量限制和入口展示状态 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `scene` | string | 否 | 调用场景，默认 `workbench_home` |

#### 入参示例

```http
GET /v1/workbench/ai/capabilities?scene=workbench_home HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWB
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `enabled` | boolean | 工作台 AI 总开关 |
| `features[]` | array | 当前用户可用能力 |
| `features[].feature` | string | 能力类型，见 0.4.1 |
| `features[].enabled` | boolean | 是否可用 |
| `features[].entry_title` | string | 前端入口名称 |
| `features[].daily_limit` | number | 单用户每日可用次数，`0` 表示不限制 |
| `features[].remaining_today` | number | 今日剩余次数 |
| `features[].max_input_chars` | number | 输入最大字符数 |
| `features[].max_file_size_mb` | number | 文件大小限制，非文件能力为 `0` |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "enabled": true,
    "features": [
      {
        "feature": "smart_document",
        "enabled": true,
        "entry_title": "智能文档",
        "daily_limit": 20,
        "remaining_today": 18,
        "max_input_chars": 1000,
        "max_file_size_mb": 0
      },
      {
        "feature": "smart_table",
        "enabled": true,
        "entry_title": "智能表格",
        "daily_limit": 10,
        "remaining_today": 9,
        "max_input_chars": 100,
        "max_file_size_mb": 20
      }
    ]
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWB",
  "server_time": "2026-09-25T08:30:15.123Z"
}
```

#### 对接重点

1. 首页“智能文档”“智能表格”是否展示，以 `features[].enabled` 为准。
2. `remaining_today=0` 时入口可展示，但生成按钮置灰并提示次数已用完。
3. 前端不要写死 AI 能力开关，方便后续按租户灰度。

### 1.2 获取工作台应用搜索默认页

#### 需求图片

<img src="ai/工作台-搜索页面.png" alt="工作台搜索页面" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `需改造` |
| 方法 | `GET /v1/workbench/apps` |
| 用途 | 获取搜索页默认展示的常用应用和全部应用，包含 AI 应用 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `include_ai` | boolean | 否 | 是否包含 AI 应用，默认 `true` |

#### 入参示例

```http
GET /v1/workbench/apps?include_ai=true HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWC
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `common_apps[]` | array | 常用应用列表 |
| `all_apps[]` | array | 全部应用列表 |
| `app_id` | string | 应用 ID |
| `name` | string | 应用名称 |
| `icon` | string | 图标标识或图片 URL |
| `route` | string | 前端路由 |
| `type` | string | `builtin`、`ai` |
| `enabled` | boolean | 是否可点击 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "common_apps": [
      {"app_id": "daily_report", "name": "日报", "icon": "daily", "route": "/workbench/daily", "type": "builtin", "enabled": true},
      {"app_id": "smart_document", "name": "智能文档", "icon": "ai_document", "route": "/workbench/ai/document", "type": "ai", "enabled": true},
      {"app_id": "smart_table", "name": "智能表格", "icon": "ai_table", "route": "/workbench/ai/table", "type": "ai", "enabled": true}
    ],
    "all_apps": [
      {"app_id": "organization", "name": "组织框架", "icon": "org", "route": "/workbench/org", "type": "builtin", "enabled": true},
      {"app_id": "meeting_notes", "name": "会议笔记", "icon": "meeting_note", "route": "/workbench/meeting-notes", "type": "builtin", "enabled": true}
    ]
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWC"
}
```

#### 对接重点

1. `route` 由前端路由解释，后端只返回稳定应用 ID 和显示名称。
2. AI 应用是否出现在常用应用中，可由服务端按租户配置控制。

### 1.3 搜索工作台应用

#### 需求图片

<img src="ai/工作台-搜索页面-明确展示.png" alt="工作台搜索结果" width="360">
<img src="ai/工作台-搜索页面-无结果.png" alt="工作台搜索无结果" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `需改造` |
| 方法 | `GET /v1/workbench/apps/search` |
| 用途 | 按关键字搜索工作台应用，返回可跳转应用结果 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `q` | string | 是 | 搜索关键词，最长 50 字符 |
| `include_ai` | boolean | 否 | 是否搜索 AI 应用，默认 `true` |

#### 入参示例

```http
GET /v1/workbench/apps/search?q=%E7%BB%84%E7%BB%87&include_ai=true HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWD
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `items[]` | array | 匹配的应用 |
| `matched_text` | string | 命中的展示文本 |
| `highlight_ranges[]` | array | 高亮范围，可选 |
| `has_more` | boolean | 是否还有更多结果 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "app_id": "organization",
        "name": "组织框架",
        "matched_text": "组织框架",
        "icon": "org",
        "route": "/workbench/org",
        "type": "builtin",
        "enabled": true,
        "highlight_ranges": [{"start": 0, "end": 2}]
      }
    ],
    "has_more": false
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWD"
}
```

#### 对接重点

1. 无结果时返回 `items: []`，前端展示“暂无匹配结果”。
2. 搜索只返回当前用户有权限访问的应用。
3. 前端不要基于本地固定列表搜索，否则 AI 应用灰度会不一致。

## 2. 智能文档接口

本章对应智能文档输入页、生成结果页和文档记录页。智能文档是异步任务，生成成功后前端展示结果；用户点击“保存文档”后才进入文档记录。

### 2.1 创建智能文档生成任务

#### 需求图片

<img src="ai/智能文档(2).png" alt="智能文档输入" width="360">
<img src="ai/智能文档(1).png" alt="智能文档生成结果" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `POST /v1/workbench/ai/documents/generate` |
| 用途 | 根据用户输入生成结构化文档 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source_text` | string | 是 | 用户输入的核心内容，最长 1000 字 |
| `title_hint` | string | 否 | 标题提示，最长 80 字 |
| `document_type` | string | 否 | 文档类型，默认 `meeting_minutes`；可选 `meeting_minutes`、`plan`、`summary`、`general` |
| `language` | string | 否 | 语言，默认 `zh-CN` |

#### 入参示例

```http
POST /v1/workbench/ai/documents/generate HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWE
Idempotency-Key: ai_doc_01K8ZC3FZ6BTX9Z1SK8HV7QYWE
Content-Type: application/json

{
  "source_text": "今天讨论新项目排期，确认本周完成需求评审，下周启动开发，风险是接口字段还未冻结。",
  "title_hint": "新项目沟通纪要",
  "document_type": "meeting_minutes",
  "language": "zh-CN"
}
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | AI 任务 ID |
| `status` | string | 任务状态 |
| `polling_interval_ms` | number | 建议轮询间隔 |
| `expires_at` | string | 未保存结果过期时间 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_7R8mX5Nf4D2a",
    "status": "queued",
    "polling_interval_ms": 1500,
    "expires_at": "2026-09-25T10:30:15.123Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWE"
}
```

#### 对接重点

1. 前端创建任务后跳转或停留在结果页 loading 状态，通过 2.2 查询任务。
2. 输入为空、超过 1000 字或命中内容安全，必须返回明确错误码。
3. 重新生成可再次调用本接口，并传新的幂等键。

### 2.2 查询 AI 任务详情

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/tasks/{task_id}` |
| 用途 | 查询智能文档、智能表格等异步任务进度和结果 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `task_id` | string | 是 | 路径参数 |

#### 入参示例

```http
GET /v1/workbench/ai/tasks/aitask_7R8mX5Nf4D2a HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWF
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | AI 任务 ID |
| `feature` | string | AI 能力类型 |
| `status` | string | 任务状态 |
| `progress` | number | 进度，0～100 |
| `steps[]` | array | 表格类任务步骤，智能文档可为空 |
| `result` | object | 任务结果，成功后返回 |
| `error` | object | 失败原因，失败后返回 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_7R8mX5Nf4D2a",
    "feature": "smart_document",
    "status": "succeeded",
    "progress": 100,
    "steps": [],
    "result": {
      "title": "新项目沟通纪要",
      "content_markdown": "## 一、会议背景\n今天讨论新项目排期...\n\n## 二、关键结论\n- 本周完成需求评审\n- 下周启动开发",
      "sections": [
        {"heading": "会议背景", "content": "今天讨论新项目排期。"},
        {"heading": "关键结论", "content": "本周完成需求评审，下周启动开发。"}
      ],
      "source_excerpt": "今天讨论新项目排期...",
      "can_save": true
    },
    "error": null
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWF"
}
```

#### 对接重点

1. `status=succeeded` 且 `result.can_save=true` 时前端展示“保存文档”。
2. `content_markdown` 是主展示字段；`sections` 用于后续结构化编辑或导出。
3. `status=failed` 时返回 `error.reason` 和 `error.message`，前端展示重试。

### 2.3 保存智能文档

#### 需求图片

<img src="ai/智能文档.png" alt="智能文档编辑保存" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `POST /v1/workbench/ai/documents` |
| 用途 | 将生成结果保存为文档记录 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `task_id` | string | 是 | 生成任务 ID |
| `title` | string | 是 | 保存标题，最长 100 字 |
| `content_markdown` | string | 是 | 保存内容 |
| `content_plain` | string | 否 | 纯文本内容，用于搜索 |

#### 入参示例

```http
POST /v1/workbench/ai/documents HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWG
Idempotency-Key: ai_doc_save_01K8ZC3FZ6BTX9Z1SK8HV7QYWG
Content-Type: application/json

{
  "task_id": "aitask_7R8mX5Nf4D2a",
  "title": "新项目沟通纪要",
  "content_markdown": "## 一、会议背景\n今天讨论新项目排期...",
  "content_plain": "今天讨论新项目排期，本周完成需求评审。"
}
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `record_id` | string | 文档记录 ID |
| `title` | string | 文档标题 |
| `created_at` | string | 保存时间 |
| `updated_at` | string | 更新时间 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "record_id": "airec_doc_5Jv8mVb21Q",
    "title": "新项目沟通纪要",
    "created_at": "2026-09-25T08:35:00.000Z",
    "updated_at": "2026-09-25T08:35:00.000Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWG"
}
```

#### 对接重点

1. 同一个 `task_id` 可以保存一次；重复保存同一幂等键返回同一 `record_id`。
2. 前端编辑后的内容以保存接口入参为准，后端不再重新调用 AI。
3. 未保存结果过期后保存返回 `RESOURCE_NOT_FOUND` 或 `AI_TASK_FAILED`。

### 2.4 文档记录列表

#### 需求图片

<img src="ai/总结记录(1).png" alt="文档记录" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/documents` |
| 用途 | 查询当前用户保存的智能文档记录 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 否 | 标题或内容搜索 |
| `cursor` | string | 否 | 分页游标 |
| `limit` | number | 否 | 默认 20，最大 50 |

#### 入参示例

```http
GET /v1/workbench/ai/documents?query=%E9%A1%B9%E7%9B%AE&cursor=&limit=20 HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWH
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `items[]` | array | 文档记录 |
| `record_id` | string | 记录 ID |
| `title` | string | 标题 |
| `summary` | string | 摘要 |
| `document_type` | string | 文档类型 |
| `status` | string | 固定 `succeeded` |
| `created_at` | string | 创建时间 |
| `updated_at` | string | 更新时间 |
| `next_cursor` | string | 下一页游标 |
| `has_more` | boolean | 是否还有更多 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "record_id": "airec_doc_5Jv8mVb21Q",
        "title": "新项目沟通纪要",
        "summary": "确认本周完成需求评审，下周启动开发。",
        "document_type": "meeting_minutes",
        "status": "succeeded",
        "created_at": "2026-09-25T08:35:00.000Z",
        "updated_at": "2026-09-25T08:35:00.000Z"
      }
    ],
    "next_cursor": "",
    "has_more": false
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWH"
}
```

#### 对接重点

1. 文档记录只返回当前用户保存的数据。
2. 搜索建议同时匹配标题和 `content_plain`。

### 2.5 文档记录详情

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/documents/{record_id}` |
| 用途 | 获取智能文档保存内容 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参示例

```http
GET /v1/workbench/ai/documents/airec_doc_5Jv8mVb21Q HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWI
```

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "record_id": "airec_doc_5Jv8mVb21Q",
    "title": "新项目沟通纪要",
    "document_type": "meeting_minutes",
    "content_markdown": "## 一、会议背景\n今天讨论新项目排期...",
    "source_excerpt": "今天讨论新项目排期...",
    "created_at": "2026-09-25T08:35:00.000Z",
    "updated_at": "2026-09-25T08:35:00.000Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWI"
}
```

## 3. 智能表格与报告解读接口

本章对应智能表格首页、选择文件、上传成功、分析进度、报告解读和解读记录。文件上传先走 IM 文件服务，再创建表格解读任务。

### 3.1 上传智能表格源文件

#### 需求图片

<img src="ai/智能表格.png" alt="智能表格" width="360">
<img src="ai/选择文件.png" alt="选择文件" width="360">
<img src="ai/智能表格-文件上传成功.png" alt="文件上传成功 xlsx" width="360">
<img src="ai/智能表格-文件上传成功(1).png" alt="文件上传成功 xls" width="360">
<img src="ai/智能表格-文件上传成功(2).png" alt="文件上传成功 csv" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `复用` |
| 方法 | `POST /v0/file/u/` |
| 用途 | 上传智能表格待分析文件，返回 `file_id` |
| 鉴权 | 沿用 IM 文件服务鉴权 |
| 幂等 | 文件服务按既有规则处理 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 客户端文件上传 ID |
| `purpose` | string | 是 | 固定 `ai_table_source` |
| `file` | file | 是 | 支持 `.xlsx`、`.xls`、`.csv` |

#### 入参示例

```http
POST /v0/file/u/ HTTP/1.1
X-MeetingIM-APIKey: <api_key>
X-MeetingIM-Auth: token <im_token>
X-IM-Schema: 1
X-Tenant-Code: system
Content-Type: multipart/form-data

id=file_01K8ZC3FZ6BTX9Z1SK8HV7QYWJ
purpose=ai_table_source
file=@sales_august.xlsx
```

#### 出参示例

```json
{
  "ctrl": {
    "id": "file_01K8ZC3FZ6BTX9Z1SK8HV7QYWJ",
    "code": 200,
    "text": "ok",
    "params": {
      "file_id": "fil_8xMb92qK7L",
      "name": "sales_august.xlsx",
      "size": 2726297,
      "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    }
  }
}
```

#### 对接重点

1. 文件服务响应结构沿用 IM `ctrl`，不是 workbench 统一 `code/data` 包装。
2. 前端需在本地先校验扩展名和大小，后端仍必须二次校验。
3. `file_id` 只作为后续创建 AI 表格任务的输入，不直接暴露给其他用户。

### 3.2 创建表格解读任务

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `POST /v1/workbench/ai/table-analyses` |
| 用途 | 根据上传文件和报表主题创建智能表格解读任务 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file_id` | string | 是 | 文件服务返回的文件 ID |
| `file_name` | string | 是 | 原始文件名 |
| `file_type` | string | 是 | `xlsx`、`xls`、`csv` |
| `file_size` | number | 是 | 文件大小，单位 byte |
| `topic` | string | 是 | 报表主题，最长 100 字 |
| `sheet_name` | string | 否 | 指定分析工作表；为空时服务端自动选择 |
| `language` | string | 否 | 默认 `zh-CN` |

#### 入参示例

```http
POST /v1/workbench/ai/table-analyses HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWK
Idempotency-Key: ai_table_01K8ZC3FZ6BTX9Z1SK8HV7QYWK
Content-Type: application/json

{
  "file_id": "fil_8xMb92qK7L",
  "file_name": "sales_august.xlsx",
  "file_type": "xlsx",
  "file_size": 2726297,
  "topic": "8月销售数据",
  "sheet_name": "",
  "language": "zh-CN"
}
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `task_id` | string | AI 任务 ID |
| `record_id` | string | 预生成记录 ID；任务成功后可打开详情 |
| `status` | string | 任务状态 |
| `polling_interval_ms` | number | 建议轮询间隔 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_tbl_2Fh9aQx73K",
    "record_id": "airec_tbl_6LP0nM9s3B",
    "status": "queued",
    "polling_interval_ms": 1500
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWK"
}
```

#### 对接重点

1. 表格解读成功后默认生成记录，无需用户另点保存。
2. 文件不存在、类型不支持、超过大小限制必须在创建任务时拦截。
3. 同一用户可同时运行的表格任务建议限制为 1～3 个，超过返回 `RATE_LIMITED`。

### 3.3 查询表格解读进度

#### 需求图片

<img src="ai/会议总结-识别中.png" alt="智能解读报告处理中" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/tasks/{task_id}` |
| 用途 | 查询表格解读任务进度 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_tbl_2Fh9aQx73K",
    "feature": "smart_table",
    "status": "processing",
    "progress": 68,
    "steps": [
      {"step": "read_file", "title": "读取表格数据", "status": "succeeded"},
      {"step": "detect_metrics", "title": "识别核心指标", "status": "succeeded"},
      {"step": "analyze_trends", "title": "分析趋势变化", "status": "processing"},
      {"step": "generate_report", "title": "生成解读报告", "status": "pending"}
    ],
    "result": null,
    "error": null
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWL"
}
```

#### 对接重点

1. 前端进度条使用 `progress`，步骤列表使用 `steps`。
2. 服务端不保证每次轮询都有进度变化，但状态必须单向推进。
3. 任务成功后 `result.record_id` 指向报告详情。

### 3.4 取消表格解读任务

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `POST /v1/workbench/ai/tasks/{task_id}/cancel` |
| 用途 | 取消正在排队或处理中的 AI 任务 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参示例

```http
POST /v1/workbench/ai/tasks/aitask_tbl_2Fh9aQx73K/cancel HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWM
Idempotency-Key: ai_cancel_01K8ZC3FZ6BTX9Z1SK8HV7QYWM
```

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_tbl_2Fh9aQx73K",
    "status": "canceled",
    "canceled_at": "2026-09-25T08:40:00.000Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWM"
}
```

### 3.5 获取报告解读详情

#### 需求图片

<img src="ai/报告解读.png" alt="报告解读" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/table-analyses/{record_id}` |
| 用途 | 获取智能表格解读报告详情 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `record_id` | string | 报告记录 ID |
| `title` | string | 报告标题 |
| `file` | object | 源文件信息 |
| `metrics[]` | array | 核心指标 |
| `preview` | object | 数据预览 |
| `alerts[]` | array | 异常提醒 |
| `interpretation` | string | 核心解读 |
| `export_options[]` | array | 可导出格式 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "record_id": "airec_tbl_6LP0nM9s3B",
    "title": "8月销售数据",
    "file": {
      "file_id": "fil_8xMb92qK7L",
      "file_name": "sales_august.xlsx",
      "file_type": "xlsx",
      "file_size": 2726297
    },
    "metrics": [
      {"name": "销售额", "value": "128.6万", "change_text": "+12.3%", "trend": "up"},
      {"name": "订单量", "value": "3,842", "change_text": "+8.7%", "trend": "up"},
      {"name": "退款率", "value": "2.1%", "change_text": "-0.4%", "trend": "down"}
    ],
    "preview": {
      "columns": ["日期", "销售额", "订单量", "退款率"],
      "rows": [
        ["8/1", "42,300", "126", "2.3%"],
        ["8/2", "48,120", "139", "2.0%"]
      ],
      "total_rows": 31
    },
    "alerts": [
      {"level": "warning", "title": "8月15日订单量异常下降", "description": "订单量较前一日下降 18%，建议核对促销和渠道数据。"}
    ],
    "interpretation": "8月整体销售额较上月增长，订单量同步提升，退款率下降，说明转化质量改善。",
    "export_options": ["docx", "pdf"],
    "created_at": "2026-09-25T08:42:00.000Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWN"
}
```

#### 对接重点

1. 核心指标、异常提醒、核心解读都由后端生成并持久化，前端只负责展示。
2. `preview.rows` 只返回前 N 行用于展示，不返回完整表格数据。
3. 前端展示“由 AI 生成，请核对后使用”的风险提示。

### 3.6 解读记录列表

#### 需求图片

<img src="ai/总结记录.png" alt="解读记录" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/table-analyses` |
| 用途 | 查询当前用户的表格解读记录 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 否 | 按标题或文件名搜索 |
| `cursor` | string | 否 | 分页游标 |
| `limit` | number | 否 | 默认 20，最大 50 |

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `items[].record_id` | string | 解读记录 ID |
| `items[].title` | string | 解读报告标题 |
| `items[].summary` | string | 解读摘要，列表页可展示前几行 |
| `items[].format` | string | 展示用文件格式，取值为小写文件后缀，例如 `xlsx`、`xls`、`csv` |
| `items[].file_type` | string | 原始文件类型，当前与 `format` 一致，保留给前端逻辑判断 |
| `items[].file_name` | string | 原始文件名 |
| `items[].file_size` | number | 原始文件大小，单位 byte |
| `items[].status` | string | 解读状态，见 0.4.2 |
| `items[].created_at` | string | 创建时间，UTC RFC3339 |
| `items[].updated_at` | string | 更新时间，UTC RFC3339 |
| `next_cursor` | string | 下一页游标，为空表示无下一页 |
| `has_more` | boolean | 是否还有下一页 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "record_id": "airec_tbl_6LP0nM9s3B",
        "title": "8月销售数据",
        "summary": "本次报表展示 8 月销售数据的核心指标、异常波动和区域表现。",
        "format": "xlsx",
        "file_name": "sales_august.xlsx",
        "file_type": "xlsx",
        "file_size": 18146135,
        "status": "succeeded",
        "created_at": "2026-09-25T08:42:00.000Z",
        "updated_at": "2026-09-25T08:42:00.000Z"
      }
    ],
    "next_cursor": "",
    "has_more": false
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWO"
}
```

### 3.7 导出解读报告

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `POST /v1/workbench/ai/table-analyses/{record_id}/export` |
| 用途 | 将解读报告导出为文件 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `format` | string | 是 | `docx` 或 `pdf` |

#### 入参示例

```http
POST /v1/workbench/ai/table-analyses/airec_tbl_6LP0nM9s3B/export HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWP
Idempotency-Key: ai_export_01K8ZC3FZ6BTX9Z1SK8HV7QYWP
Content-Type: application/json

{"format": "docx"}
```

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "file_id": "fil_export_9pLm2Q",
    "file_name": "8月销售数据-解读报告.docx",
    "download_url": "https://api.118im.com/v0/file/s/fil_export_9pLm2Q",
    "expires_at": "2026-09-26T08:42:00.000Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWP"
}
```

## 4. AI 美文与日报/月报接入

AI 美文是同步接口，用于优化短文案。日报、月报仍使用原提交接口，AI 只负责生成或优化输入框内容。

### 4.1 AI 美文

#### 需求图片

<img src="ai/AI美文.png" alt="AI美文" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `POST /v1/workbench/ai/text/polish` |
| 用途 | 对原文进行润色，返回可直接使用的优化文案 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `source_text` | string | 是 | 原文，最长 300 字 |
| `scene` | string | 是 | `general`、`daily_report`、`monthly_report` |
| `tone` | string | 否 | 语气，默认 `professional` |
| `max_output_chars` | number | 否 | 输出最大长度，默认 300 |

#### 入参示例

```http
POST /v1/workbench/ai/text/polish HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWQ
Idempotency-Key: ai_polish_01K8ZC3FZ6BTX9Z1SK8HV7QYWQ
Content-Type: application/json

{
  "source_text": "今天完成接口联调，处理了几个bug，明天继续测试。",
  "scene": "daily_report",
  "tone": "professional",
  "max_output_chars": 300
}
```

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `polished_text` | string | 润色后的文案 |
| `source_text` | string | 原文回显 |
| `usage` | object | 本次用量信息 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "source_text": "今天完成接口联调，处理了几个bug，明天继续测试。",
    "polished_text": "今日已完成接口联调，并修复联调过程中发现的多个问题。明日将继续推进测试验证，确保相关功能稳定可用。",
    "usage": {
      "remaining_today": 17
    }
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWQ"
}
```

#### 对接重点

1. 前端“重新生成”再次调用本接口，使用新的幂等键。
2. 前端“使用文案”只把 `polished_text` 回填到原业务输入框，不自动提交日报或月报。
3. 输出仍允许用户编辑，业务提交以用户最终输入为准。

### 4.2 日报 AI 接入

#### 需求图片

<img src="ai/日报.png" alt="日报 AI 接入" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `复用 + 需改造` |
| AI 接口 | `POST /v1/workbench/ai/text/polish` |
| 业务接口 | 沿用日报新增/编辑接口 |
| 用途 | 在日报“今日工作总结”等输入框中接入 AI 美文 |
| 鉴权 | 需要 IM 登录态 |

#### 对接流程

1. 用户在日报输入框填写原文。
2. 前端点击“AI 美文”，调用 4.1，`scene=daily_report`。
3. 前端展示 AI 美文弹层，用户可重新生成或使用文案。
4. 用户点击“使用文案”后，前端把 `polished_text` 回填到日报字段。
5. 用户点击“提交”后，仍调用原日报提交接口。

#### 入参示例

```json
{
  "source_text": "完成工作台接口联调，修复会议笔记字段问题。",
  "scene": "daily_report",
  "tone": "professional",
  "max_output_chars": 300
}
```

#### 对接重点

1. AI 不改变日报是否可提交、是否冲突、是否重复的业务规则。
2. 日报保存成功后不需要额外保存 AI 记录；如后端需要审计，可写入用量日志。

### 4.3 月报 AI 接入

#### 需求图片

<img src="ai/月报-发布中.png" alt="月报 AI 接入" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `复用 + 需改造` |
| AI 接口 | `POST /v1/workbench/ai/text/polish` |
| 业务接口 | 沿用月报新增/编辑接口 |
| 用途 | 在月报“本月工作总结”“其他事项”等输入框中接入 AI 美文 |
| 鉴权 | 需要 IM 登录态 |

#### 对接流程

1. 用户在月报输入框填写原文。
2. 前端点击对应输入框附近的“AI 美文”。
3. 前端调用 4.1，`scene=monthly_report`。
4. 用户确认使用后，前端只回填当前字段。
5. 月报发布仍调用原月报接口。

#### 对接重点

1. 月报字段上限以月报业务接口为准；AI 输入建议最长 1000 字，输出不超过原字段限制。
2. “发布中”状态由原月报接口控制，AI 美文接口不返回发布状态。

## 5. 会议笔记 AI 总结接口

会议 AI 总结挂在会议笔记详情下，使用会议附件、会议标题、参与人等已有会议上下文生成摘要。会议列表、会议笔记列表和文件上传仍沿用既有工作台会议接口。

### 5.1 创建会议 AI 总结任务

#### 需求图片

<img src="ai/会议笔记- AI总结.png" alt="会议笔记 AI 总结" width="360">

| 项 | 内容 |
| --- | --- |
| 状态 | `新增 + 需改造` |
| 方法 | `POST /v1/workbench/meetings/{meeting_id}/ai-summary` |
| 用途 | 对会议笔记附件或会议内容生成 AI 总结 |
| 鉴权 | 需要 IM 登录态和会议笔记查看权限 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `meeting_id` | string | 是 | 路径参数 |
| `file_ids[]` | array | 否 | 指定参与总结的会议附件；为空时使用会议下可读附件 |
| `summary_type` | string | 否 | 默认 `standard` |
| `force_regenerate` | boolean | 否 | 已存在总结时是否重新生成，默认 `false` |

#### 入参示例

```http
POST /v1/workbench/meetings/mtg_7YUHoLTqrl4ZO_G6/ai-summary HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWR
Idempotency-Key: ai_meeting_01K8ZC3FZ6BTX9Z1SK8HV7QYWR
Content-Type: application/json

{
  "file_ids": ["fil_note_1", "fil_note_2"],
  "summary_type": "standard",
  "force_regenerate": false
}
```

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "task_id": "aitask_mtg_3Rn8qU2b6X",
    "meeting_id": "mtg_7YUHoLTqrl4ZO_G6",
    "status": "queued",
    "polling_interval_ms": 1500
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWR"
}
```

#### 对接重点

1. 无会议查看权限返回 `FORBIDDEN`。
2. 会议没有可分析内容时返回 `VALIDATION_FAILED`，details 中标明 `missing_source=true`。
3. 已有总结且 `force_regenerate=false` 时可直接返回现有总结或返回 `CONFLICT`，建议返回现有总结以减少前端分支。

### 5.2 查询会议 AI 总结

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/meetings/{meeting_id}/ai-summary` |
| 用途 | 获取会议 AI 总结内容 |
| 鉴权 | 需要 IM 登录态和会议笔记查看权限 |
| 幂等 | 读接口无需幂等 |

#### 出参说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `meeting_id` | string | 会议 ID |
| `summary_id` | string | 总结 ID |
| `status` | string | `empty`、`processing`、`succeeded`、`failed` |
| `conclusions[]` | array | 会议结论 |
| `decisions[]` | array | 关键决策 |
| `action_items[]` | array | 后续安排 |
| `editable` | boolean | 当前用户是否可编辑 |
| `updated_at` | string | 更新时间 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "meeting_id": "mtg_7YUHoLTqrl4ZO_G6",
    "summary_id": "aisum_7Kp2N8aV",
    "status": "succeeded",
    "conclusions": [
      "工作台 AI 首版接入智能文档、智能表格和 AI 美文。",
      "日报、月报沿用原业务提交接口。"
    ],
    "decisions": [
      "表格解读采用异步任务，成功后默认生成记录。",
      "会议 AI 总结挂载在会议笔记详情页。"
    ],
    "action_items": [
      {
        "owner_user_id": "usrABAAnqj42BU",
        "owner_display_name": "张三",
        "content": "补充 AI 任务表结构设计",
        "due_at": "2026-09-26T10:00:00.000Z",
        "status": "pending"
      }
    ],
    "editable": true,
    "updated_at": "2026-09-25T08:50:00.000Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWS"
}
```

#### 对接重点

1. `status=empty` 时前端展示空态和“生成 AI 总结”入口。
2. `status=processing` 时前端可复用任务轮询，也可定时刷新本接口。
3. `action_items.owner_user_id` 必须是字符串，不允许返回数字。

### 5.3 编辑会议 AI 总结

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `PUT /v1/workbench/meetings/{meeting_id}/ai-summary` |
| 用途 | 保存用户手动编辑后的 AI 总结 |
| 鉴权 | 需要会议笔记编辑权限 |
| 幂等 | 必须携带 `Idempotency-Key` |

#### 入参示例

```http
PUT /v1/workbench/meetings/mtg_7YUHoLTqrl4ZO_G6/ai-summary HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWT
Idempotency-Key: ai_meeting_save_01K8ZC3FZ6BTX9Z1SK8HV7QYWT
Content-Type: application/json

{
  "summary_id": "aisum_7Kp2N8aV",
  "conclusions": ["工作台 AI 首版接入三类能力。"],
  "decisions": ["会议 AI 总结挂载在会议笔记详情页。"],
  "action_items": [
    {
      "owner_user_id": "usrABAAnqj42BU",
      "content": "补充 AI 任务表结构设计",
      "due_at": "2026-09-26T10:00:00.000Z",
      "status": "pending"
    }
  ]
}
```

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "meeting_id": "mtg_7YUHoLTqrl4ZO_G6",
    "summary_id": "aisum_7Kp2N8aV",
    "updated_at": "2026-09-25T09:00:00.000Z"
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWT"
}
```

#### 对接重点

1. 编辑保存后内容不再标记为纯 AI 原文，前端仍可展示“由 AI 自动生成，如有不准确可手动编辑”。
2. 会议总结编辑权限建议复用会议笔记 `can_replace` 或 `can_upload` 权限，最终以后端权限判断为准。

## 6. AI 记录与任务通用接口

### 6.1 通用 AI 记录列表

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `GET /v1/workbench/ai/records` |
| 用途 | 按类型查询 AI 记录，供后续统一记录中心使用 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 读接口无需幂等 |

#### 入参说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | string | 否 | `smart_document`、`smart_table` |
| `query` | string | 否 | 搜索词 |
| `cursor` | string | 否 | 分页游标 |
| `limit` | number | 否 | 默认 20，最大 50 |

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "items": [
      {
        "record_id": "airec_doc_5Jv8mVb21Q",
        "type": "smart_document",
        "title": "新项目沟通纪要",
        "summary": "确认本周完成需求评审，下周启动开发。",
        "status": "succeeded",
        "created_at": "2026-09-25T08:35:00.000Z",
        "route": "/workbench/ai/document/airec_doc_5Jv8mVb21Q"
      },
      {
        "record_id": "airec_tbl_6LP0nM9s3B",
        "type": "smart_table",
        "title": "8月销售数据",
        "summary": "销售额增长 12.3%，退款率下降。",
        "status": "succeeded",
        "created_at": "2026-09-25T08:42:00.000Z",
        "route": "/workbench/ai/table/airec_tbl_6LP0nM9s3B"
      }
    ],
    "next_cursor": "",
    "has_more": false
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWU"
}
```

### 6.2 删除 AI 记录

| 项 | 内容 |
| --- | --- |
| 状态 | `新增` |
| 方法 | `DELETE /v1/workbench/ai/records/{record_id}` |
| 用途 | 删除当前用户自己的 AI 记录 |
| 鉴权 | 需要 IM 登录态 |
| 幂等 | 删除接口幂等，同一记录重复删除返回成功 |

#### 入参示例

```http
DELETE /v1/workbench/ai/records/airec_doc_5Jv8mVb21Q HTTP/1.1
Authorization: Bearer <token>
X-MeetingIM-APIKey: <api_key>
X-IM-Schema: 1
X-Tenant-Code: system
X-Request-ID: 01K8ZC3FZ6BTX9Z1SK8HV7QYWV
```

#### 出参示例

```json
{
  "code": 0,
  "data": {
    "record_id": "airec_doc_5Jv8mVb21Q",
    "deleted": true
  },
  "request_id": "01K8ZC3FZ6BTX9Z1SK8HV7QYWV"
}
```

### 6.3 AI 任务事件

| 项 | 内容 |
| --- | --- |
| 状态 | `建议接入` |
| 事件 | `workbench.ai.task.updated` |
| 用途 | 服务端主动推送 AI 任务完成、失败或取消状态，减少前台等待 |
| 鉴权 | 复用 IM WebSocket 登录态 |

#### 推送边界

1. 仅推送在线用户。用户离线时服务端不保存离线 AI 推送、不补发历史推送。
2. 用户重新上线、重新进入工作台 AI 页面时，前端通过任务详情、记录列表或业务详情接口恢复状态。
3. 推送内容只放任务状态、结果索引和轻量结果；完整长文本、大对象和权限敏感内容仍以 HTTP 详情接口为准。
4. 文件结果不推裸 OSS 签名地址，统一推 IM 文件服务稳定地址：`/v0/file/s/{file_id}` 或其绝对 URL。
5. 推送丢失、WebSocket 断线、App 切后台等场景下，前端必须保留轮询兜底。

#### 通用事件结构

```json
{
  "topic": "workbench.ai.task.updated",
  "data": {
    "task_id": "aitask_tbl_2Fh9aQx73K",
    "feature": "smart_table",
    "status": "succeeded",
    "progress": 100,
    "result_type": "record",
    "record_id": "airec_tbl_6LP0nM9s3B",
    "result": {
      "title": "8月销售数据解读",
      "summary": "销售额整体平稳，建议重点关注渠道结构和异常订单。"
    },
    "updated_at": "2026-09-25T08:42:00.000Z"
  }
}
```

#### 字段说明

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `task_id` | string | 是 | AI 任务 ID |
| `feature` | string | 是 | AI 能力类型，见 0.4.1 |
| `status` | string | 是 | `succeeded`、`failed`、`canceled` 为主要推送状态 |
| `progress` | number | 否 | 进度，完成态一般为 `100` |
| `result_type` | string | 否 | `text`、`file`、`record`、`summary` |
| `record_id` | string | 否 | 记录类结果 ID |
| `meeting_id` | string | 否 | 会议总结所属会议 ID |
| `summary_id` | string | 否 | 会议总结 ID |
| `result` | object | 否 | 轻量结果体，按 result_type 区分 |
| `error` | object | 否 | 失败信息，包含 `reason`、`message` |
| `updated_at` | string | 是 | 更新时间，UTC RFC3339 |

#### result 示例

文本结果：

```json
{
  "result_type": "text",
  "result": {
    "text": "润色后的文本内容",
    "scene": "daily_report_polish"
  }
}
```

文件结果：

```json
{
  "result_type": "file",
  "result": {
    "file_id": "IHC4k7rlpo0.docx",
    "file_name": "阿德勒-解读报告.docx",
    "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "file_size": 2870,
    "download_url": "https://api.118im.com/v0/file/s/IHC4k7rlpo0.docx"
  }
}
```

记录结果：

```json
{
  "result_type": "record",
  "record_id": "airec_tbl_6LP0nM9s3B",
  "result": {
    "title": "8月销售数据解读",
    "summary": "销售额整体平稳，建议关注渠道结构。"
  }
}
```

会议总结结果：

```json
{
  "result_type": "summary",
  "meeting_id": "mtg_7YUHoLTqrl4ZO_G6",
  "summary_id": "aisum_3Rn8qU2b6X",
  "result": {
    "conclusion_count": 3,
    "action_item_count": 2
  }
}
```

失败结果：

```json
{
  "task_id": "aitask_tbl_2Fh9aQx73K",
  "feature": "smart_table",
  "status": "failed",
  "progress": 100,
  "error": {
    "reason": "AI_TASK_FAILED",
    "message": "生成失败，请重试"
  },
  "updated_at": "2026-09-25T08:42:00.000Z"
}
```

#### 各接口推送建议

| 接口/能力 | 是否异步 | 是否推送 | result_type | 推送内容建议 |
| --- | --- | --- | --- | --- |
| `POST /v1/workbench/ai/documents/generate` 智能文档生成 | 是 | 是 | `text` 或 `record` | 内容较短可直接推 `title`、`content_plain`、`content_markdown`；内容较长只推 `task_id` 和摘要，前端拉任务详情 |
| `POST /v1/workbench/ai/documents` 保存文档 | 否 | 否 | - | 用户主动保存，HTTP 返回即可 |
| `POST /v1/workbench/ai/table-analyses` 智能表格解读 | 是 | 是 | `record` | 推 `record_id`、标题、摘要；前端可直接展示完成卡片，点开时拉详情 |
| `POST /v1/workbench/ai/table-analyses/{record_id}/export` 导出报告 | 可异步 | 是 | `file` | 推 `file_id`、`file_name`、`mime_type`、`file_size`、`download_url` |
| `POST /v1/workbench/ai/text/polish` AI 美文 | 可同步；超过 2 秒建议异步 | 异步时推 | `text` | 推润色后的 `text`，内容过长时只推摘要并拉任务详情 |
| 日报 AI 润色 | 可同步；超过 2 秒建议异步 | 异步时推 | `text` | 推润色后的日报内容或草稿 ID |
| 月报 AI 润色 | 可同步；超过 2 秒建议异步 | 异步时推 | `text` | 推 `work_summary`、`next_plan` 或草稿 ID |
| `POST /v1/workbench/meetings/{meeting_id}/ai-summary` 会议 AI 总结 | 是 | 是 | `summary` | 推 `meeting_id`、`summary_id`、结论数、待办数；完整内容拉详情 |
| `GET /v1/workbench/ai/tasks/{task_id}` 查询任务 | 否 | 否 | - | 前端主动拉取，作为推送兜底 |
| `POST /v1/workbench/ai/tasks/{task_id}/cancel` 取消任务 | 否 | 可选 | - | 多端在线时可推 `status=canceled`；单端场景可只依赖 HTTP 返回 |

#### 对接重点

1. 推送用于“在线即时更新”，不是最终数据源；最终状态以 HTTP 查询为准。
2. 前端收到 `succeeded` 后，可优先使用推送中的轻量结果更新 UI；需要完整内容时再拉详情。
3. 前端收到 `file` 类型结果后，可直接展示下载按钮，下载地址使用 `download_url`。
4. 前端收到 `failed` 后展示失败并允许重试，不展示供应商原始错误。
5. App 启动、WebSocket 重连、进入 AI 页面时，前端重新拉任务或记录列表恢复离线期间完成的任务。

## 7. 对接重难点

### 7.1 IM 登录与 workbench AI 边界

AI 接口只接受 IM 登录态，不单独做 AI 登录。租户、用户、部门权限全部由 IM Token 和工作台权限体系派生。前端不要在请求体中传用户身份字段。

### 7.2 异步任务与用户体验

智能文档、智能表格、会议 AI 总结都可能耗时。前端必须处理 `queued`、`processing`、`succeeded`、`failed`、`canceled`，并在用户离开页面后可通过任务、记录或业务详情恢复结果。

推荐交互流程：

1. 创建任务接口立即返回 `task_id`、`status=queued`、`polling_interval_ms`，前端进入 loading 或后台任务状态。
2. 用户在线时，服务端通过 IM WebSocket 推送 `workbench.ai.task.updated`，前端收到完成事件后直接刷新 UI。
3. 用户离线、App 切后台、WebSocket 断线时，服务端不补发离线 AI 推送；前端重新上线后主动拉任务详情、AI 记录列表或业务详情。
4. 推送结果为 `text` 时，短文本可直接展示；长文本以 HTTP 任务详情为准。
5. 推送结果为 `file` 时，前端直接使用 `download_url` 展示下载入口；该地址应为 IM 文件服务稳定地址，不是裸 OSS 签名地址。
6. 推送结果为 `record` 或 `summary` 时，前端可先展示标题和摘要，点开详情时再请求对应详情接口。
7. 同一账号多端在线时，所有在线端都可以收到任务完成推送；各端仍需按页面状态决定是否自动展示或只更新角标。
8. 失败、取消也应更新本地任务状态；失败文案按 `error.reason` 做本地化，不展示供应商原始报错。

### 7.3 文件服务与 AI 服务衔接

智能表格先上传文件，再创建解读任务。后端创建任务时必须校验 `file_id` 属于当前租户和当前用户，并检查文件类型、大小、有效期。AI 服务不得直接信任前端传入的 `file_name`、`file_type`。

### 7.4 字段类型一致性

所有用户 ID、会议 ID、记录 ID、任务 ID、文件 ID 都是字符串。尤其是 `owner_user_id`、`attendee_user_ids`、`recorder_user_id`、`participant.user_id` 不允许使用 number。

### 7.5 内容安全与合规

AI 输入和输出都需要内容安全检查。命中安全规则时返回 `AI_CONTENT_REJECTED`；前端展示温和提示，不展示供应商原始错误。日志中不得打印完整用户输入、完整模型输出、Token、文件下载地址和内部密钥。

### 7.6 用量限制与灰度开关

AI 能力需要按租户和用户配置开关、每日次数、并发数和文件大小。前端展示入口前先读取 1.1；后端接口仍必须强校验，不能只依赖前端隐藏入口。

### 7.7 会议 AI 总结权限

会议 AI 总结不能只判断会议 ID 存在。生成、查看、编辑必须分别判断会议笔记权限；附件参与总结前也要校验附件属于该会议且当前用户可读。

## 8. 接口清单

| 模块 | 接口 | 方法 | 状态 | 说明 |
| --- | --- | --- | --- | --- |
| AI 能力 | `/v1/workbench/ai/capabilities` | GET | 新增 | 获取 AI 能力开关和用量 |
| 工作台应用 | `/v1/workbench/apps` | GET | 需改造 | 默认应用列表包含 AI 应用 |
| 工作台搜索 | `/v1/workbench/apps/search` | GET | 需改造 | 搜索工作台应用 |
| 智能文档 | `/v1/workbench/ai/documents/generate` | POST | 新增 | 创建文档生成任务 |
| AI 任务 | `/v1/workbench/ai/tasks/{task_id}` | GET | 新增 | 查询任务进度与结果 |
| 智能文档 | `/v1/workbench/ai/documents` | POST | 新增 | 保存生成文档 |
| 智能文档 | `/v1/workbench/ai/documents` | GET | 新增 | 文档记录列表 |
| 智能文档 | `/v1/workbench/ai/documents/{record_id}` | GET | 新增 | 文档记录详情 |
| 文件上传 | `/v0/file/u/` | POST | 复用 | 上传表格源文件 |
| 智能表格 | `/v1/workbench/ai/table-analyses` | POST | 新增 | 创建表格解读任务 |
| AI 任务 | `/v1/workbench/ai/tasks/{task_id}/cancel` | POST | 新增 | 取消 AI 任务 |
| 智能表格 | `/v1/workbench/ai/table-analyses/{record_id}` | GET | 新增 | 报告解读详情 |
| 智能表格 | `/v1/workbench/ai/table-analyses` | GET | 新增 | 解读记录列表 |
| 智能表格 | `/v1/workbench/ai/table-analyses/{record_id}/export` | POST | 新增 | 导出解读报告 |
| AI 美文 | `/v1/workbench/ai/text/polish` | POST | 新增 | 文案润色 |
| 会议总结 | `/v1/workbench/meetings/{meeting_id}/ai-summary` | POST | 新增 | 创建会议 AI 总结 |
| 会议总结 | `/v1/workbench/meetings/{meeting_id}/ai-summary` | GET | 新增 | 查询会议 AI 总结 |
| 会议总结 | `/v1/workbench/meetings/{meeting_id}/ai-summary` | PUT | 新增 | 编辑会议 AI 总结 |
| AI 记录 | `/v1/workbench/ai/records` | GET | 新增 | 通用记录列表 |
| AI 记录 | `/v1/workbench/ai/records/{record_id}` | DELETE | 新增 | 删除 AI 记录 |

## 9. 前后端联调建议

1. 先联调 `capabilities`、应用列表和搜索，确保入口展示一致。
2. 再联调 AI 美文，因为它是同步接口，最适合验证鉴权、租户、用量和错误包。
3. 智能文档联调重点是任务轮询、保存文档、文档记录。
4. 智能表格联调重点是文件上传、文件归属校验、任务步骤、报告详情和导出。
5. 会议 AI 总结最后联调，重点验证会议权限、附件权限和编辑保存。
6. 每个写接口都要测试同一 `Idempotency-Key` 重试、不同请求体冲突、Token 过期、跨租户访问、无权限访问。