会议纪要接口文档

AI降临派 Meeting System — 会议纪要 & 实时字幕接入指南
Version 2.1
Last Updated: 2026-09-30

本文档聚焦"会议纪要"主线业务的接口使用方式，并重点介绍本次新增的实时字幕定稿 + 翻译流水线（CAPTION_INTERIM / CAPTION_FINAL）。完整协议细节另见 meeting-system.md。

1. 本次更新亮点：实时字幕定稿 + 翻译

这是本次迭代新增的独立字幕流水线，不影响原有 TRANSCRIPT 转写、说话人识别、纪要生成任何一环——可以理解为在会议纪要主链路之外，"外挂"了一条只读订阅原始转写碎片的增强通道。

1.1 解决的问题

原有实时转写按 VAD 分句独立识别，句与句之间没有上下文，容易出现：

碎片化：一句话被切成好几段，逐段展示不连贯

无翻译能力：只能看到原语言文本，跨语言会议（如英文财报电话会）体验差

1.2 方案

新增 CaptionPipeline 组件：每来一条新的 TRANSCRIPT 碎片，就把"历史已定稿字幕（上下文）+ 当前未定稿碎片全量"一起交给 LLM，重新整理出这一段当前"最可能"的文本，并判断语义是否完整：

未完整 → 推送 CAPTION_INTERIM（覆盖式刷新，客户端整体替换显示，不是拼接追加）

已完整 → 推送 CAPTION_FINAL（锁定，之后这个 caption_seq 不会再变化）

同时按需将文本翻译成指定语言，实现"英文演讲 + 中英双语字幕实时滚动"的效果。

1.3 如何开启

在 AUTH 阶段追加两个可选参数即可，不传则完全不影响原有行为：

参数名	说明
`caption_target_lang`	目标语言 BCP-47 短码，如 `zh`、`en`。不传则不翻译，只做纠错整理
`caption_mode`	`original`（不翻译）/ `translated`（只看译文）/ `bilingual`（原文+译文都要）。不传时按有无 `caption_target_lang` 自动决定；传了 `translated`/`bilingual` 但没传 `caption_target_lang` 时按 `original` 处理

##START\x01[taskID][seqID]JWT_TOKEN##session_type:meeting##mode:vad##caption_target_lang:zh##caption_mode:bilingual##END

1.4 服务器下发的两种新帧

##START\x05[taskID]0000##CAPTION_INTERIM:<json>##END     // 未定稿，整体覆盖刷新
##START\x05[taskID]0000##CAPTION_FINAL:<json>##END       // 定稿，之后不再变化

{
  "type": "caption_final",
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b",
  "caption_seq": 5,
  "source_text": "整理纠错后的原文",
  "translated_text": "对应译文（caption_mode=original 时为空字符串）",
  "target_lang": "zh",
  "covered_raw_seqs": [12, 13, 14]
}

字段	说明
`caption_seq`	字幕流水线内部独立序号，从 1 递增，跟 `TRANSCRIPT.seq` 是两套编号；断线续会后从 1 重新计数
`source_text`	纠错、整理后的原文（`CAPTION_INTERIM` 阶段可能还会变化）
`translated_text`	目标语言译文
`target_lang`	实际使用的目标语言短码
`covered_raw_seqs`	这一段消费了哪些原始 `TRANSCRIPT.seq`

客户端展示逻辑：

收到 CAPTION_INTERIM → 用最新一条整体替换当前展示的"这一行"（不要拼接，内容可能因为后续信息而被重写）

收到 CAPTION_FINAL → 锁定这一行，追加进历史字幕列表，清空当前行等待下一个 caption_seq

调用 stop-and-summarize 时，服务器会在后台把剩余未定稿内容整理成最后一条 CAPTION_FINAL（接口返回后数秒内到达）；连接断开时不会补发，未定稿部分直接丢弃（原始 TRANSCRIPT 不受影响）

同一会话内字幕帧严格按生成顺序下发：某个 caption_seq 的 CAPTION_FINAL 之后不会再出现该 caption_seq 的 CAPTION_INTERIM

1.5 已知颗粒度限制 & 兼容性

现有 ASR 按 VAD 整句识别，没有逐词流式输出，所以 CAPTION_INTERIM 的刷新颗粒度是"每来一条新的 TRANSCRIPT 碎片重新生成一次预览"，不是逐字级别刷新

若某一段字幕横跨的原始碎片之间到达间隔较长（如演讲者停顿），字幕可能会较久停留在"未定稿"状态才等到下一次刷新或结束时的强制定稿

服务端可通过 CAPTION_PIPELINE_ENABLED=false 完全关闭本功能，此时不会下发这两种帧，TRANSCRIPT/纪要流程不受任何影响；客户端应做好"可能收不到这两种帧"的兼容处理

1.6 已实测验证

已用真实会议录音（中文会议、英文会议、5 分钟阿里巴巴财报电话会）跑通完整链路，验证内容包括：

中↔英双向翻译准确性

字幕流式刷新（多碎片场景下先出 CAPTION_INTERIM 再定稿）

LLM 对 ASR 误识别碎片的自动纠错能力（如自动过滤识别错误的噪音片段）

2. 系统概述

会议系统在原有 TCP 实时对话服务的基础上，提供完整的会议记录与纪要生成能力：

实时转写：中英双语 VAD 自动分句，每句识别完成后即时推送 TRANSCRIPT 帧

字幕实时定稿 + 翻译（本次新增，可选）：见第 1 节

说话人识别：会议结束后自动标注每句话的说话人（SPK_00、SPK_01…）

智能纪要：自动生成结构化 Markdown 纪要，支持自定义模板

双通道推送：纪要结果同时通过 TCP 帧和 HTTP Webhook 推送至客户端

断线续会：TCP 意外断线后重连可无缝恢复会议，转写内容不丢失

3. TCP 接入与认证

3.1 认证格式

在标准 TCP AUTH 消息中加入 session_type:meeting 参数即可进入会议模式：

##START\x01[taskID][seqID]JWT_TOKEN##session_type:meeting##mode:vad##[可选参数]...##END

必要参数：

参数名	类型	说明
`session_type`	`meeting`	固定值，进入会议模式
`mode`	`vad`	会议模式必须使用 VAD 模式

可选参数：

参数名	类型	默认值	说明
`device_id`	string	—	设备 ID，推荐填写
`meeting_id`	string	—	填写已有 meeting_id 可续会
`summary_template`	string	—	纪要模板全文（YAML）；不填则自动选择
`input_audio_format`	`pcm` \| `opus`	`pcm`	上行音频格式
`caption_target_lang`	string	—	（本次新增）字幕目标语言，见第 1 节
`caption_mode`	`original` \| `translated` \| `bilingual`	自动	（本次新增）字幕定稿输出形式，见第 1 节
`asr_language`	`auto` \| `en` \| `zh`	`auto`	（本次新增）会议语言。`auto`：自动识别，但只允许 `asr_allowed_languages` 中的语种（口音英语被误识别成印地语等其他语种时自动按允许语种重转）；`en`/`zh`：强制按该语言转写（仅在现场只有一种语言时使用，否则另一种语言的发言会被强行"翻译"成错误内容）
`asr_allowed_languages`	string	`zh,en`	`auto` 模式下允许的语种（BCP-47，逗号分隔）
`meeting_topic`	string	—	会议主题 / 专有名词（≤500 字，不能含 `#`），作为字幕整理的背景上下文，帮助纠正口音与术语造成的识别错误

3.2 认证成功 & 会议创建

##START\x05[taskID]0000##INFO:认证成功，NPCID: <npcid>, 模式: vad##END

紧随其后，服务器发送会议创建通知（TEXT 帧）：

##START\x04[taskID]0000{"type":"meeting_started","meeting_id":"<uuid>"}##END

⚠️ 客户端必须等到收到 meeting_started 帧后，再发送 LISTEN:start 并开始推流音频。

##START\x08[taskID]0000{"state":"start"}##END

3.3 服务器下发帧一览

帧前缀	触发时机	说明
`##TRANSCRIPT:`	每句 VAD 识别完成	原始转写，一直存在，不受本次改动影响
`##TRANSCRIPT_PARTIAL:`	说话过程中约每秒一次	流式识别中间结果（服务端开启时），见下方说明
`##CAPTION_INTERIM:`	字幕未定稿刷新	本次新增，见第 1 节
`##CAPTION_FINAL:`	字幕定稿锁定	本次新增，见第 1 节
`##summary_start:` / `##summary_delta:` / `##summary_done:`	调用 `stop-and-summarize` 后	纪要流式生成，见第 7 节

TRANSCRIPT_PARTIAL 帧（流式识别，v2.2 起）：

{"type": "transcript_partial", "meeting_id": "...", "seq": 13, "timestamp": "00:01:05",
 "text": "We delivered strong performance this quarter, with total",
 "stable_text": "We delivered strong performance this",
 "unstable_text": " quarter, with total", "language": "English", "is_final": false}

seq = 这一段定稿后 TRANSCRIPT 将使用的 seq；收到同 seq 的 TRANSCRIPT 后，以它为准

stable_text：同一 seq 内只增不改（服务端以它为前缀续写，不会再改写），客户端可放心追加显示；
unstable_text：末尾约 3 个词 / 5 个汉字，下一次可能被改写，建议弱化显示（如灰色）

定稿 TRANSCRIPT.text 以 stable_text 开头（只补完尾巴），不会整段重写

旧服务端 / 未开启流式识别（MEETING_STREAM_ASR_ENABLED=false）时没有 stable_text，text 每次整体刷新；text 字段始终保留以兼容旧客户端

TRANSCRIPT 帧字段示例：

{
  "type": "transcript",
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b",
  "text": "大家好，欢迎参加本次产品评审会议。",
  "seq": 1,
  "timestamp": "00:00:05",
  "is_final": true
}

3.4 续会（断线重连）

若客户端因网络断线重连，可在 AUTH 中携带原 meeting_id 恢复会议，转写序号自动延续（续会条件：原会议必须处于 ongoing 状态）：

##START\x01[taskID][seqID]JWT_TOKEN##session_type:meeting##mode:vad##meeting_id:3b1cddf9-0832-43fa-bf0a-f36fb9790b8b##END

4. 会议纪要 REST API

Base URL： https://api.adventists.cn，所有接口返回 Content-Type: application/json。

4.1 创建会议

通过 TCP 认证进入会议模式时会自动创建会议，此接口仅用于纯 REST 场景。

POST /v2/meeting

// Request
{ "org_id": "WOQSOC", "device_id": "device-001", "summary_template": null }

// Response 201
{ "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b", "status": "created" }

4.2 查询会议状态

GET /v2/meeting/{meeting_id}

{
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b",
  "org_id": "WOQSOC",
  "device_id": "device-001",
  "status": "done",
  "created_at": "2026-07-05T05:42:54Z",
  "started_at": "2026-07-05T05:43:01Z",
  "ended_at": "2026-07-05T05:50:08Z",
  "transcript_count": 15,
  "summary": "**主题**：本季度财务表现\n\n**核心内容**：...",
  "error": null
}

4.3 结束并触发纪要

POST /v2/meeting/{meeting_id}/stop-and-summarize

无 Request Body（接口幂等，重复调用安全）。调用后服务器异步处理（含说话人识别、纪要生成，若开启了字幕流水线还会强制 flush 最后一段字幕），处理完成后通过 TCP 帧或 Webhook 推送结果（约 10–60 秒，取决于会议时长）。

// Response 200
{ "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b", "status": "summarizing" }

状态码	说明
404	会议不存在
409	会议已处于终态（`done` / `failed`），请使用 4.6 重试接口

4.4 查询纪要（轮询补偿）

GET /v2/meeting/{meeting_id}/summary

用于当 TCP 推送的 summary_done 帧未能收到时的轮询补偿：

{
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b",
  "status": "done",
  "summary": "**主题**：本季度财务表现...\n\n**核心内容**：...",
  "error": null
}

轮询建议： 每 5 秒请求一次，status 变为 done 或 failed 后停止，超时上限建议 3 分钟。

4.5 获取全量转写

GET /v2/meeting/{meeting_id}/transcripts

{
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b",
  "total": 15,
  "transcripts": [
    {
      "seq": 1,
      "text": "Good day, ladies and gentlemen. Welcome to our earnings call.",
      "timestamp": "00:00:01",
      "speaker_label": "SPK_00",
      "start_ms": 1000,
      "end_ms": 7200
    }
  ]
}

注：这里的 transcripts 是原始 TRANSCRIPT 数据（含说话人标注），不包含字幕流水线的整理/翻译结果；字幕内容目前只通过 TCP 帧实时推送，不落库查询（如需持久化整理后的字幕，可在客户端侧自行收集 CAPTION_FINAL 帧）。

4.6 更换纪要模板

会议进行中（created / ongoing 状态）可更换纪要模板，新模板在 stop-and-summarize 时生效。

PUT /v2/meeting/{meeting_id}/summary-template

// Request
{ "summary_template": "template_id: custom_board_meeting\nname: 董事会会议\n..." }

4.7 重试生成纪要

当 status 为 done 或 failed 时，重新触发纪要生成（例如更换模板后重试）。

POST /v2/meeting/{meeting_id}/retry-summarize

4.8 配置 Webhook 地址

管理本 org 的会议结果推送地址，支持查询、更新和清除。

POST /v2/webhook-config

鉴权（Header）： api-key（32 位）+ org-id（6 位）

// 查询
{ "action": "query" }
// 更新
{ "action": "update", "webhook_url": "https://your.server/webhook", "webhook_secret": "your-hmac-secret" }
// 清除
{ "action": "delete" }

4.9 纪要生成进度与预计耗时

stop-and-summarize / retry-summarize 的响应新增：

{ "meeting_id": "...", "status": "summarizing", "estimated_seconds": 212.0,
  "stages": [{"key": "download", "label": "读取会议录音"}, {"key": "diarize", "label": "识别说话人"},
             {"key": "asr", "label": "整段重新转写"}, {"key": "clean", "label": "校对转写、标注发言人"},
             {"key": "save", "label": "保存精修转写"}, {"key": "map", "label": "分段提炼要点"},
             {"key": "reduce", "label": "生成纪要"}] }

生成过程中轮询 GET /v2/meeting/{meeting_id}（建议 3 秒一次），响应里的 summary_progress：

{ "stage": "diarize", "stage_label": "识别说话人", "stage_index": 2, "stage_count": 7,
  "elapsed_s": 41.2, "eta_s": 150.3, "percent": 21.5, "estimated_total_s": 212.0, "audio_duration_s": 3044.4 }

预估按录音时长计算：约 0.065 × 录音秒数 + 20 秒（51 分钟会议约 3.5 分钟），运行中按已完成阶段的实际速度自动校准

eta_s 在服务端按当前时间实时换算；两次轮询之间前端可以本地倒数平滑显示

完成后 stage 为 done、eta_s 为 0

4.10 按 npcid 查询历史会议

GET /v2/meetings?npcid={npcid}&limit=20&offset=0&include_summary=false
Header: api-key, org-id   （必填，只能查本 org 的会议）

{ "npcid": "...", "total": 13, "offset": 0, "limit": 20,
  "meetings": [{ "meeting_id": "...", "status": "done", "started_at": "...", "ended_at": "...",
                 "transcript_count": 402, "meeting_topic": "...", "template_id": "builtin_lecture",
                 "summary_preview": "前 120 字…", "refined_status": "done",
                 "audio": {"status": "available", "expires_at": "2026-10-08T04:04:10Z"} }] }

按开始时间倒序。完整纪要用 GET /v2/meeting/{meeting_id} 或 include_summary=true 获取。

4.11 下载会议录音

GET /v2/meeting/{meeting_id}/audio
Header: api-key, org-id

{ "meeting_id": "...", "url": "https://api.adventists.cn/v2/meeting/{id}/audio/download?exp=...&sig=...",
  "expires_in": 3600, "format": "mp3", "size": 18266949, "duration_s": 3044.4,
  "audio_expires_at": "2026-10-08T04:04:10Z" }

url 为 1 小时有效的签名链接，可直接在浏览器打开下载（MP3，16kHz 单声道 48kbps，约 22MB/小时）

纪要完成后服务端自动导出 MP3；尚未导出时首次请求会现场转码（50 分钟约 15 秒）

录音保留期 AUDIO_RETENTION_DAYS（默认 7 天），过期后返回 410；纪要、转写、精修稿不受影响

会议未结束时返回 409

4.12 内置模板

template_id	名称	适用
`builtin_general`	通用会议纪要	默认
`builtin_lecture`	讲座/学术报告笔记	讲座、学术报告、大会演讲、公开课（知识型）
`builtin_paper`	论文分享/读书会笔记	paper reading、journal club、读书会（知识型）
`builtin_training`	培训/分享会纪要	内部培训、技术分享
`builtin_project_review` / `builtin_requirement_review` / `builtin_client_meeting` / `builtin_brainstorm` / `builtin_retrospective` / `builtin_interview` / `builtin_standup`	各类会议

绑定方式：PUT /v2/meeting/{id}/summary-template，body {"summary_template": "template_id: builtin_lecture"}（只传 id 即按内置模板全文），或传完整模板 YAML。
知识型模板（mode: knowledge）输出约 1500 字的听讲笔记，不强制「结论/待办/负责人」栏目。

5. 数据模型

5.1 MeetingStatus 枚举

值	说明
`created`	会议已创建，尚未开始录音
`ongoing`	录音进行中
`summarizing`	已触发结束，正在生成纪要
`done`	纪要生成完成
`failed`	纪要生成失败

5.2 TranscriptItem

5.3 CaptionUpdate（本次新增）

6. 会议状态机

          ┌─────────────────────────────────────────────────────┐
          │                                                     │
     [AUTH 成功]                                          [断线续会]
          │                                                     │
          ▼                                                     │
      created ──── [首帧音频] ──►  ongoing ────────────────────┘
                                     │
                              [stop-and-summarize]
                                     │
                                     ▼
                               summarizing
                                     │
                    ┌────────────────┴───────────────┐
                    │                                │
               [成功完成]                         [生成失败]
                    │                                │
                    ▼                                ▼
                  done ◄── [retry-summarize] ── failed

字幕流水线（CaptionPipeline）跟这个状态机是解耦的：它只在 ongoing 期间只读订阅 TRANSCRIPT 碎片，在 summarizing 触发时强制 flush 一次，本身不影响、也不依赖这个状态机的流转。

7. 纪要推送机制

系统支持三种方式获取纪要结果，建议同时实现 TCP 监听和轮询兜底。

7.1 TCP 帧推送（主通道）

调用 stop-and-summarize 后，纪要生成完成时服务器主动推送：

##summary_start:                       // 标志开始
##summary_delta:<增量文本>              // 流式增量，可逐字拼接展示
##summary_done:{"type":"summary_done","summary":"..."}   // 完成
##summary_error:<错误描述>              // 异常时

7.2 HTTP Webhook（补偿通道）

通过 4.8 节配置接收地址，纪要生成完成后服务器 POST 到该地址：

{
  "event": "meeting.finished",
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b",
  "org_id": "WOQSOC",
  "summary": "**主题**：...",
  "created_at": "2026-07-05T05:50:08Z"
}

配置了 webhook_secret 时，请求头 X-Webhook-Signature = HMAC-SHA256(payload_body, webhook_secret) 十六进制摘要，用于验签。

失败时：

{ "event": "meeting.failed", "meeting_id": "...", "org_id": "WOQSOC", "error": "会议无有效转写内容" }

7.3 HTTP 轮询（兜底）

不依赖推送通道，主动轮询 GET /v2/meeting/{id}/summary。

8. 纪要模板

纪要模板采用 YAML 格式，控制生成纪要的章节结构与写作规则。

8.1 内置模板列表

template_id	适用场景
`builtin_general`	通用会议（默认）
`builtin_board`	董事会 / 高管决策会议
`builtin_product_review`	产品评审 / Sprint Review
`builtin_sales`	销售复盘 / 客户沟通
`builtin_interview`	访谈 / 候选人面试记录
`builtin_standup`	日/周站会

8.2 自定义模板格式

9. 错误处理 & 常见问题

9.1 HTTP 错误码

状态码	场景
400	请求参数格式错误
404	会议不存在
409	状态冲突（如对终态会议调用 stop-and-summarize）
500	服务器内部错误（可通过 retry-summarize 重试）

9.2 TCP 错误帧

内容	说明
`##ERROR:token error`	JWT 无效或已过期
`##ERROR:meeting session error`	会议会话初始化失败
`##summary_error:<描述>`	纪要生成失败（可调用 retry-summarize）

9.3 常见问题

Q: 音频推流后收不到 TRANSCRIPT 帧？
A: 确认认证成功并收到 meeting_started 后，发送了 LISTEN:start 消息（类型 \x08）。另外 VAD 需要实际观察到静音帧才能判断一句话结束——如果音频流到最后一帧就直接停止发送（没有补发静音），最后一段话可能永远不会被判定结束、也就不会触发识别。

Q: 配置了 caption_target_lang 但收不到 CAPTION_INTERIM/CAPTION_FINAL？
A: 依次排查：① 服务端是否设置了 CAPTION_PIPELINE_ENABLED=false（会完全关闭该功能）；② AUTH 参数拼写是否正确（caption_target_lang、caption_mode）；③ 该功能不影响 TRANSCRIPT 帧，若连 TRANSCRIPT 都没收到，先按上一条排查 VAD/推流问题。

Q: CAPTION_INTERIM 内容会不会跟上一条矛盾/变短？
A: 会。这是设计如此——每一条 CAPTION_INTERIM 都是根据当前已知的全部碎片信息重新生成的"最可能"结果，客户端应整体替换展示，而不是拼接追加。

Q: stop-and-summarize 返回 409？
A: 会议已处于 done 或 failed 状态，请改用 POST /v2/meeting/{id}/retry-summarize。

Q: TCP 断线后会议数据会丢失吗？
A: 不会。会议保持 ongoing 状态，已识别的转写内容完整保留；重连时带 meeting_id 参数即可续会。字幕流水线未定稿的内容在断线时会被丢弃（连接已断、无法下发），续会后字幕从 caption_seq=1 重新开始；需要完整字幕记录请以 TRANSCRIPT / GET /transcripts 为准。

10. 端到端完整示例（Python）

如有接入问题，请联系技术支持，或参阅完整协议文档 meeting-system.md。

会议系统接口文档

会议纪要接口文档#

目录#

1. 本次更新亮点：实时字幕定稿 + 翻译#

1.1 解决的问题#

1.2 方案#

1.3 如何开启#

1.4 服务器下发的两种新帧#

1.5 已知颗粒度限制 & 兼容性#

1.6 已实测验证#

2. 系统概述#

3. TCP 接入与认证#

3.1 认证格式#

3.2 认证成功 & 会议创建#

3.3 服务器下发帧一览#

3.4 续会（断线重连）#

4. 会议纪要 REST API#

4.1 创建会议#

4.2 查询会议状态#

4.3 结束并触发纪要#

4.4 查询纪要（轮询补偿）#

4.5 获取全量转写#

4.6 更换纪要模板#

4.7 重试生成纪要#

4.8 配置 Webhook 地址#

4.9 纪要生成进度与预计耗时#

4.10 按 npcid 查询历史会议#

4.11 下载会议录音#

4.12 内置模板#

5. 数据模型#

5.1 MeetingStatus 枚举#

5.2 TranscriptItem#

5.3 CaptionUpdate（本次新增）#

6. 会议状态机#

7. 纪要推送机制#

7.1 TCP 帧推送（主通道）#

7.2 HTTP Webhook（补偿通道）#

7.3 HTTP 轮询（兜底）#

8. 纪要模板#

8.1 内置模板列表#

8.2 自定义模板格式#

9. 错误处理 & 常见问题#

9.1 HTTP 错误码#

9.2 TCP 错误帧#

9.3 常见问题#

10. 端到端完整示例（Python）#