pro/olons_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d2e70efd9d01559fa3339c5f55dabce7b231e8b6
olons_server/docs/IM工作台AI前后端对接文档.md
T

57 KiB
Raw Blame History

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

版本：v1.0
日期：2026-09-25
需求依据：IM 工作台 AI 接入需求文档
IM 依据：IM 前后端对接文档
参考格式：禾圃集后院养成与物友动态前后端对接文档
说明：本文补充 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 内容、原始输入、上传文件解析结果、模型响应和错误日志均需脱敏后入库或打印。

建议路径前缀：

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 成功与失败响应

成功响应统一为：

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

失败响应统一为：

{
  "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 能力

需求图片

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

入参说明

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

入参示例

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

出参示例

{
  "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 获取工作台应用搜索默认页

需求图片

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

入参说明

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

入参示例

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 是否可点击

出参示例

{
  "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 搜索工作台应用

需求图片

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

入参说明

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

入参示例

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 是否还有更多结果

出参示例

{
  "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 创建智能文档生成任务

需求图片

智能文档输入 智能文档生成结果
项 内容
状态 新增
方法 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

入参示例

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 未保存结果过期时间

出参示例

{
  "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 是 路径参数

入参示例

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 失败原因，失败后返回

出参示例

{
  "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 保存智能文档

需求图片

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

入参说明

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

入参示例

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 更新时间

出参示例

{
  "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 文档记录列表

需求图片

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

入参说明

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

入参示例

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 是否还有更多

出参示例

{
  "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 登录态
幂等 读接口无需幂等

入参示例

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

出参示例

{
  "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 上传智能表格源文件

需求图片

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

入参说明

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

入参示例

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

出参示例

{
  "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

入参示例

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 建议轮询间隔

出参示例

{
  "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 查询表格解读进度

需求图片

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

出参示例

{
  "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

入参示例

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

出参示例

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

3.5 获取报告解读详情

需求图片

报告解读
项 内容
状态 新增
方法 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 可导出格式

出参示例

{
  "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 解读记录列表

需求图片

解读记录
项 内容
状态 新增
方法 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 是否还有下一页

出参示例

{
  "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

入参示例

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"}

出参示例

{
  "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 美文

需求图片

AI美文
项 内容
状态 新增
方法 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

入参示例

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 本次用量信息

出参示例

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

对接重点

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

4.2 日报 AI 接入

需求图片

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

对接流程

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

入参示例

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

对接重点

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

4.3 月报 AI 接入

需求图片

月报 AI 接入
项 内容
状态 复用 + 需改造
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 总结任务

需求图片

会议笔记 AI 总结
项 内容
状态 新增 + 需改造
方法 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

入参示例

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
}

出参示例

{
  "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 更新时间

出参示例

{
  "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

入参示例

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"
    }
  ]
}

出参示例

{
  "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

出参示例

{
  "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 登录态
幂等 删除接口幂等，同一记录重复删除返回成功

入参示例

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

出参示例

{
  "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 切后台等场景下，前端必须保留轮询兜底。

通用事件结构

{
  "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 示例

文本结果：

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

文件结果：

{
  "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"
  }
}

记录结果：

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

会议总结结果：

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

失败结果：

{
  "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 过期、跨租户访问、无权限访问。
Reference in New Issue View Git Blame Copy Permalink