会议系统接口文档

AI降临派 Meeting System — 接入与开发指南
Version 1.0
Last Updated: 2026-07-05

1. 系统概述

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

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

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

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

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

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

2. TCP 会议模式接入

2.1 认证（AUTH）

在标准 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`	上行音频格式

认证成功响应：

##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 并开始推流音频。

客户端发送 LISTEN:start 启动 VAD：

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

2.2 服务器下发帧

TRANSCRIPT 帧（每句识别完成即时下发）

帧格式：

##START\x05[taskID][seqID]##TRANSCRIPT:<json>##END

JSON 字段：

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

字段	类型	说明
`type`	string	固定 `"transcript"`
`meeting_id`	string	会议 UUID
`text`	string	识别文本（支持中英文混合）
`seq`	int	本次会议内递增序号（从 1 开始）
`timestamp`	string	相对会议开始的时间 `HH:MM:SS`
`is_final`	bool	固定 `true`（VAD 模式只下发最终结果）

2.3 纪要回调帧

调用 stop-and-summarize 后，纪要生成完成时服务器向客户端推送以下帧序列：

summary_start

##START\x05[taskID]0000##summary_start:##END

标志纪要开始流式输出。

summary_delta

##START\x05[taskID]0000##summary_delta:<增量文本>##END

流式推送纪要内容片段，可逐字拼接展示。

summary_done

##START\x05[taskID]0000##summary_done:<json>##END

JSON 字段：

{
  "type":    "summary_done",
  "summary": "**主题**：本季度财务回顾\n\n**核心内容**：..."
}

summary_error（异常时）

##START\x05[taskID]0000##summary_error:<错误描述>##END

2.4 续会（断线重连）

若客户端因网络断线重连，可在 AUTH 中携带原 meeting_id 恢复会议，转写序号自动延续：

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

续会条件： 原会议必须处于 ongoing 状态（未调用 stop-and-summarize）。

2.5 会议模式完整流程示例

# 1. 客户端认证
C→S: ##START\x01000000000000<JWT>##session_type:meeting##mode:vad##device_id:device-001##END

# 2. 服务器：认证成功
S→C: ##START\x05000000000000##INFO:认证成功，NPCID: <npcid>, 模式: vad##END

# 3. 服务器：会议创建通知（TEXT 帧）
S→C: ##START\x04000000000000{"type":"meeting_started","meeting_id":"027ff465-..."}##END

# 4. 客户端：启动 VAD 监听
C→S: ##START\x08<taskID>0000{"state":"start"}##END

# 5. 客户端：持续推流 PCM 音频（16kHz 单声道 16bit）
C→S: ##START\x02<taskID>xxxx<PCM 音频数据>##END
C→S: ##START\x02<taskID>xxxx<PCM 音频数据>##END
...

# 6. 服务器：每句话识别完成下发 TRANSCRIPT
S→C: ##START\x05<taskID>xxxx##TRANSCRIPT:{"type":"transcript","meeting_id":"027ff465-...","text":"大家好...","seq":1,"timestamp":"00:00:05","is_final":true}##END
S→C: ##START\x05<taskID>xxxx##TRANSCRIPT:{"type":"transcript","meeting_id":"027ff465-...","text":"本季度增长超过预期...","seq":2,"timestamp":"00:00:23","is_final":true}##END
...

# （会议进行中，持续推流 + 接收 TRANSCRIPT）

# 7. 客户端：调用 REST API 触发纪要（见第 3 节）
#    POST https://api.adventists.cn/meeting/v2/meeting/027ff465-.../stop-and-summarize

# 8. 服务器：纪要生成完成后推送
S→C: ##START\x05000000000000##summary_start:##END
S→C: ##START\x05000000000000##summary_delta:**主题**：##END
S→C: ##START\x05000000000000##summary_delta:本季度产品评审##END
...
S→C: ##START\x05000000000000##summary_done:{"type":"summary_done","summary":"**主题**：本季度..."}##END

3. 会议管理 REST API

Base URL： https://api.adventists.cn/meeting

所有接口返回 Content-Type: application/json。

3.1 创建会议

说明： 通过 TCP 认证进入会议模式时，服务器会自动创建会议并通过 meeting_started 帧下发 meeting_id，客户端无需手动调用此接口。此接口适用于纯 REST 场景（如服务端预建会议）。

POST /v2/meeting

Request Body：

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

字段	类型	必填	说明
`org_id`	string	✅	组织 ID
`device_id`	string	✅	设备 ID
`summary_template`	string \| null	❌	纪要模板全文（YAML）；不填则自动选择

Response 201：

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

3.2 查询会议状态

GET /v2/meeting/{meeting_id}

Response 200：

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

字段	说明
`status`	见会议状态机
`transcript_count`	已识别的句子总数
`summary`	最终纪要（Markdown 格式，`done` 状态时有值）
`error`	错误描述（`failed` 状态时有值）

3.3 结束并触发纪要

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

无 Request Body（接口幂等，重复调用安全）。

Response 200：

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

调用后服务器异步处理（含说话人识别、纪要生成），处理完成后通过 TCP 帧或 Webhook 推送结果（约 10–60 秒，取决于会议时长）。

错误码：

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

3.4 查询纪要

GET /v2/meeting/{meeting_id}/summary

用于 轮询补偿：当 TCP 推送的 summary_done 帧未能收到时，可轮询此接口获取最终结果。

Response 200：

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

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

3.5 获取全量转写

GET /v2/meeting/{meeting_id}/transcripts

Response 200：

{
  "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
    },
    {
      "seq":           2,
      "text":          "大家好，欢迎参加本次财报会议。",
      "timestamp":     "00:01:53",
      "speaker_label": "SPK_01",
      "start_ms":      113000,
      "end_ms":        118500
    }
  ]
}

字段	类型	说明
`seq`	int	转写序号（从 1 起）
`text`	string	识别文本
`timestamp`	string	相对会议开始 `HH:MM:SS`
`speaker_label`	string \| null	说话人标注（会议结束处理后有值，如 `SPK_00`、`SPK_01`）
`start_ms`	int \| null	片段开始毫秒（相对会议开始）
`end_ms`	int \| null	片段结束毫秒

3.6 更换纪要模板

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

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

Request Body：

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

Response 200：

{
  "ok":         true,
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b"
}

3.7 重试生成纪要

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

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

无 Request Body。

Response 200：

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

3.8 配置 Webhook 地址

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

POST /v2/webhook-config

鉴权（Header）：

Header	说明
`api_key`	32 位 API Key
`org_id`	6 位组织 ID

Request Body：

// 查询当前配置
{ "action": "query" }

// 更新 Webhook 地址（webhook_secret 可选）
{ "action": "update", "webhook_url": "https://your.server/webhook", "webhook_secret": "your-hmac-secret" }

// 清除配置（停止推送）
{ "action": "delete" }

Response 200：

{
  "org_id":         "WOQSOC",
  "webhook_url":    "https://your.server/webhook",
  "webhook_secret": "***"
}

webhook_secret 在响应中始终脱敏为 "***"（已配置）或 "" （未配置）。
delete 成功后 webhook_url 返回空字符串。
配置生效立即，下一次会议结束时开始使用新地址推送。

错误码：

状态码	说明
400	action 不合法，或 `update` 时未提供 `webhook_url`
401	api_key 或 org_id 无效

4. 数据模型

4.1 MeetingStatus 枚举

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

4.2 TranscriptItem

5. 会议状态机

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

6. 纪要推送机制

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

6.1 TCP 帧推送（主通道）

调用 stop-and-summarize 后，纪要生成完成时服务器主动向保持连接的客户端推送 summary_start → summary_delta × N → summary_done 帧序列（详见 2.3 节）。

6.2 HTTP Webhook（补偿通道）

通过 POST /v2/webhook-config 为本 org 配置接收地址。会议纪要生成完成后，服务器向该地址发送 POST 请求：

Webhook Payload（event: meeting.finished）：

{
  "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) 的十六进制摘要。接收方可据此验证推送来源。

Webhook Payload（event: meeting.failed）：

{
  "event":      "meeting.failed",
  "meeting_id": "3b1cddf9-0832-43fa-bf0a-f36fb9790b8b",
  "org_id":     "WOQSOC",
  "error":      "会议无有效转写内容"
}

6.3 HTTP 轮询（兜底）

客户端可主动轮询 GET /v2/meeting/{id}/summary，不依赖推送通道，适合对推送可靠性要求高的场景。

7. 纪要模板

纪要模板采用 YAML 格式，控制生成纪要的章节结构与写作规则。可在 AUTH 时通过 summary_template 参数传入，也可通过 PUT /v2/meeting/{id}/summary-template 更新。

7.1 内置模板列表

不传 summary_template 时，系统根据会议内容自动选择最合适的内置模板：

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

7.2 自定义模板格式

字段说明：

字段	说明
`template_id`	唯一标识，建议以 `custom_` 开头
`output.sections`	纪要章节列表，按顺序生成
`sections[].title`	章节标题
`sections[].guidance`	写作提示，指导 AI 提炼内容
`sections[].required`	`false` 时若内容为空则省略该节
`rules`	全局规则，约束整体写作风格
`selector.signals`	自动匹配关键词，用于无模板时的自动选择

8. 错误处理

8.1 HTTP 错误码

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

8.2 TCP 错误帧

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

8.3 常见问题

Q: 音频推流后收不到 TRANSCRIPT 帧？
A: 确认认证成功并收到 meeting_started 后，发送了 LISTEN:start 消息（类型 \x08）。会议模式必须先收到该消息才开始处理音频。

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

Q: TCP 断线后会议数据会丢失吗？
A: 不会。会议保持 ongoing 状态，已识别的转写内容完整保留。重连时带 meeting_id 参数即可续会。

Q: 纪要 summary_done 帧未收到怎么办？
A: 轮询 GET /v2/meeting/{id}/summary，每 5 秒一次，status 变为 done 即可获取完整纪要。

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

如有接入问题，请联系技术支持，或参阅 TCP 协议文档。

目录#

1. 系统概述#

2. TCP 会议模式接入#

2.1 认证（AUTH）#

2.2 服务器下发帧#

TRANSCRIPT 帧（每句识别完成即时下发）#

2.3 纪要回调帧#

summary_start#

summary_delta#

summary_done#

summary_error（异常时）#

2.4 续会（断线重连）#

2.5 会议模式完整流程示例#

3. 会议管理 REST API#

3.1 创建会议#

3.2 查询会议状态#

3.3 结束并触发纪要#

3.4 查询纪要#

3.5 获取全量转写#

3.6 更换纪要模板#

3.7 重试生成纪要#

3.8 配置 Webhook 地址#

4. 数据模型#

4.1 MeetingStatus 枚举#

4.2 TranscriptItem#

5. 会议状态机#

6. 纪要推送机制#

6.1 TCP 帧推送（主通道）#

6.2 HTTP Webhook（补偿通道）#

6.3 HTTP 轮询（兜底）#

7. 纪要模板#

7.1 内置模板列表#

7.2 自定义模板格式#

8. 错误处理#

8.1 HTTP 错误码#

8.2 TCP 错误帧#

8.3 常见问题#

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

目录

1. 系统概述

2. TCP 会议模式接入

2.1 认证（AUTH）

2.2 服务器下发帧

TRANSCRIPT 帧（每句识别完成即时下发）

2.3 纪要回调帧

summary_start

summary_delta

summary_done

summary_error（异常时）

2.4 续会（断线重连）

2.5 会议模式完整流程示例

3. 会议管理 REST API

3.1 创建会议

3.2 查询会议状态

3.3 结束并触发纪要

3.4 查询纪要

3.5 获取全量转写

3.6 更换纪要模板

3.7 重试生成纪要

3.8 配置 Webhook 地址

4. 数据模型

4.1 MeetingStatus 枚举

4.2 TranscriptItem

5. 会议状态机

6. 纪要推送机制

6.1 TCP 帧推送（主通道）

6.2 HTTP Webhook（补偿通道）

6.3 HTTP 轮询（兜底）

7. 纪要模板

7.1 内置模板列表

7.2 自定义模板格式

8. 错误处理

8.1 HTTP 错误码

8.2 TCP 错误帧

8.3 常见问题

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