更新协议文档 md格式
authorSnickerSun <snickersun@163.com>
Tue, 12 May 2026 01:50:30 +0000 (09:50 +0800)
committerSnickerSun <snickersun@163.com>
Tue, 12 May 2026 01:50:30 +0000 (09:50 +0800)
67 files changed:
1.doc/RVC Service WebSocket V3 API 开发文档.md [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-001.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-002.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-003.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-004.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-005.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-006.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-007.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-008.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-009.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-010.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-011.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-012.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-013.png [new file with mode: 0644]
1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-014.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-001.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-002.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-003.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-004.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-005.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-006.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-007.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-008.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-009.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-010.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-011.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-012.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-013.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-014.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-015.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-016.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-017.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-018.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-019.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-020.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-021.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-022.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-023.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-024.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-025.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-026.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-027.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-028.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-029.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-030.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-031.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-032.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-033.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-034.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-035.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-036.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-037.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-038.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-039.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-040.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-041.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-042.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-043.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-044.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-045.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-046.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-047.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-048.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-049.png [new file with mode: 0644]
1.doc/assets/金三服务-语音对话V2.5/page-050.png [new file with mode: 0644]
1.doc/convert_pdf_to_hybrid_md.py [new file with mode: 0644]
1.doc/金三服务-语音对话V2.5.md [new file with mode: 0644]

diff --git a/1.doc/RVC Service WebSocket V3 API 开发文档.md b/1.doc/RVC Service WebSocket V3 API 开发文档.md
new file mode 100644 (file)
index 0000000..8c6fbce
--- /dev/null
@@ -0,0 +1,1052 @@
+# RVC Service WebSocket V3 API 开发文档
+
+> 本文档由原始 PDF 自动转换生成,默认预览展示 PDF 页面 PNG,视觉上尽量贴近原文件。
+> 原始文件: `RVC Service WebSocket V3 API 开发文档.pdf`;页数: 14;生成时间: 2026-05-11 19:08:51。
+
+<details>
+<summary>AI 使用说明</summary>
+
+- 页面图片来自 PDF 逐页渲染,是人工核对的基准。
+- 每页图片后面的折叠区保留结构化抽取文本和逐行重排文本,方便 AI 检索、总结和问答。
+- 如抽取文本与图片不一致,请以页面图片或原始 PDF 为准。
+
+</details>
+
+<a id="page-1"></a>
+
+<!-- Page 1 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-001.png" alt="RVC Service WebSocket V3 API 开发文档 Page 1" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-2"></a>
+
+<!-- Page 2 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-002.png" alt="RVC Service WebSocket V3 API 开发文档 Page 2" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-3"></a>
+
+<!-- Page 3 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-003.png" alt="RVC Service WebSocket V3 API 开发文档 Page 3" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-4"></a>
+
+<!-- Page 4 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-004.png" alt="RVC Service WebSocket V3 API 开发文档 Page 4" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-5"></a>
+
+<!-- Page 5 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-005.png" alt="RVC Service WebSocket V3 API 开发文档 Page 5" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-6"></a>
+
+<!-- Page 6 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-006.png" alt="RVC Service WebSocket V3 API 开发文档 Page 6" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-7"></a>
+
+<!-- Page 7 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-007.png" alt="RVC Service WebSocket V3 API 开发文档 Page 7" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-8"></a>
+
+<!-- Page 8 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-008.png" alt="RVC Service WebSocket V3 API 开发文档 Page 8" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-9"></a>
+
+<!-- Page 9 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-009.png" alt="RVC Service WebSocket V3 API 开发文档 Page 9" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-10"></a>
+
+<!-- Page 10 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-010.png" alt="RVC Service WebSocket V3 API 开发文档 Page 10" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-11"></a>
+
+<!-- Page 11 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-011.png" alt="RVC Service WebSocket V3 API 开发文档 Page 11" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-12"></a>
+
+<!-- Page 12 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-012.png" alt="RVC Service WebSocket V3 API 开发文档 Page 12" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-13"></a>
+
+<!-- Page 13 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-013.png" alt="RVC Service WebSocket V3 API 开发文档 Page 13" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-14"></a>
+
+<!-- Page 14 visual layer: rendered from the original PDF. -->
+
+<img src="assets/RVC%20Service%20WebSocket%20V3%20API%20%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3/page-014.png" alt="RVC Service WebSocket V3 API 开发文档 Page 14" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<details>
+<summary>AI 可读文本全集</summary>
+
+> 以下文本来自 PDF 抽取和逐行重排,用于检索、总结和问答;视觉核对请以前面的页面图片为准。
+
+## Page 1
+
+### 结构化抽取
+
+# RVC Service WebSocket V3 API 开发文档
+
+## RVC Service WebSocket API 开发文档
+
+### •
+模型定义: [rvc service/internal/model/types.go](../internal/model/types.go)
+
+### • Python 示例: [rvc - service/examples/python - demo/real_time_audio.py]
+
+### 概览
+
+RVC Service 提供基于 WebSocket 的低延迟语音对话接口,支持:
+
+### • 实时音频上行(PCM/Opus)与下行 TTS 音频(二进制帧)
+
+### • VAD→ASR→LLM→TTS 端到端链路
+
+### • 两种会话模式: realtime (持续监听)与 push_to_talk (按键说话)
+
+### • 多种输入/输出模式: audio 、 text 、 both 、 none  •
+
+可配置打断策略:关键词打断、始终允许、从不允许
+
+### 原始逐行文本重排
+
+RVC Service WebSocket V3 API 开发文档
+
+RVC Service WebSocket API 开发文档
+
+ 参考实现与数据结构:
+
+  • 模型定义: [rvc-service/internal/model/types.go](../internal/model/types.go)
+  • Python 示例: [rvc-service/examples/python-demo/real_time_audio.py]
+     (../examples/python-demo/real_time_audio.py)
+
+概览
+
+RVC Service 提供基于 WebSocket 的低延迟语音对话接口,支持:
+
+• 实时音频上行(PCM/Opus)与下行 TTS 音频(二进制帧)
+• VAD→ASR→LLM→TTS 端到端链路
+
+              (持续监听)与 push_to_talk (按键说话)• 两种会话模式:realtime
+• 多种输入/输出模式:audio 、text 、both 、none
+• 可配置打断策略:关键词打断、始终允许、从不允许
+
+连接
+
+• URL:ws://{host}:{port}/rvc-service/api/v3/ws
+
+示例:
+
+## Page 2
+
+### 结构化抽取
+
+1. DMP授权
+
+2. Apikey 授权
+
+a. Query 参数 api_key 固定授权
+
+b. Query 参数 user_id/device_id 自定义用户ID或者设备ID
+
+### 消息封装(Envelope)
+
+所有 JSON 文本消息遵循以下 Envelope(参考 `WebSocketMessage` ):
+
+### •
+
+`type` :字符串,见下文“客户端消息类型/服务端事件类型”
+
+### • data :事件负载,对应 types.go 中的具体结构
+
+### 原始逐行文本重排
+
+```
+ws://115.190.94.208:8087/rvc-service/api/v3/ws
+```
+
+授权方式:
+
+1. DMP授权
+
+    a. Query 参数 dt/ut 通过dmp登录获取设备或者用户token
+
+2. Apikey 授权
+
+    a. Query 参数 api_key 固定授权
+
+    b. Query 参数 user_id/device_id 自定义用户ID或者设备ID
+
+消息封装(Envelope)
+
+所有 JSON 文本消息遵循以下 Envelope(参考 WebSocketMessage ):
+
+```
+{
+"type": "started",
+"data": { /* 事件负载,结构随类型而变 */ },
+"timestamp": "2025-01-01T12:00:00Z",
+"message_id": "optional",
+"session_id": "optional",
+"metadata": { "k": "v" }
+}
+```
+
+•  type :字符串,见下文“客户端消息类型/服务端事件类型”
+•  data :事件负载,对应 types.go 中的具体结构
+•  timestamp / message_id / session_id / metadata :可选
+
+二进制消息:
+
+## Page 3
+
+### 结构化抽取
+
+### • 服务端向客户端返回 TTS 音频以二进制帧形式发送(PCM 或 Opus,取决于会话的输出音频配置)  •
+
+客户端上行音频通常直接发送二进制帧(见“音频帧与格式”)
+
+### 客户端消息类型(发送到服务端)
+
+#### ~~—~~
+#### 1)`start` 开始会话
+
+```
+{
+
+ "type": "start",
+
+ "data": {
+
+  "device_id": "test_device",
+
+  "user_id": "u123",
+
+  "agent_id": "assistant",
+
+  "session_mode": "realtime",
+
+  "input_mode": "audio",
+
+  "output_mode": "audio",
+
+  "audio_config": {
+
+   "input": {"format": "pcm", "sample_rate": 16000, "bit_rate": 16,
+
+"channel": 1},
+
+   "output": {"format": "pcm", "sample_rate": 16000, "bit_rate": 16,
+
+"channel": 1}
+
+},
+
+  "audio_encryption": {
+
+   "enabled": true,
+
+   "algorithm": "x25519-aes-256-gcm",
+
+   "client_public_key": "base64-public-key-bytes"
+
+},
+
+  "interrupt_options": {
+
+   "strategy": "keyword",
+```
+
+`"interrupt_keywords": ["` 停 `", "` 停止 `", "` 别说了 `"],`
+
+```
+   "concatenate_results": false
+
+```
+
+### 原始逐行文本重排
+
+服务端向客户端返回 TTS 音频以二进制帧形式发送(PCM 或 Opus,取决于会话的输出音频配置)•
+• 客户端上行音频通常直接发送二进制帧(见“音频帧与格式”)
+
+客户端消息类型(发送到服务端)
+
+1)`start` — 开始会话
+
+负载结构:StartData
+
+```
+{
+"type": "start",
+"data": {
+"device_id": "test_device",
+"user_id": "u123",
+"agent_id": "assistant",
+7
+"session_mode": "realtime",
+"input_mode": "audio",
+"output_mode": "audio",
+11
+"audio_config": {
+"input":  {"format": "pcm",  "sample_rate": 16000, "bit_rate": 16,
+"channel": 1},
+"output": {"format": "pcm",  "sample_rate": 16000, "bit_rate": 16,
+"channel": 1}
+},
+16
+"audio_encryption": {
+"enabled": true,
+"algorithm": "x25519-aes-256-gcm",
+"client_public_key": "base64-public-key-bytes"
+},
+22
+"interrupt_options": {
+"strategy": "keyword",
+"interrupt_keywords": ["停", "停止", "别说了"],
+"concatenate_results": false
+```
+
+## Page 4
+
+### 结构化抽取
+
+```
+}
+
+}
+
+}
+
+```
+
+### • session_mode:realtime | push_to_talk 对话模式
+
+### • input_mode:audio | text 输入类型
+
+### • output_mode:audio | text | both 输出类型
+
+### • audio_config.input/output.format:pcm | opus 音频配置
+
+### • audio_config.output.speech_rate: 语速调整百分比 [ - 100, 100],基于初始语速增减,0=不调整,
+
+50=加快50%, 50=减慢50%
+
+### • audio_encryption:可选;开启后仅加密上下行二进制音频帧,JSON 控制消息不加密
+
+### • interrupt_options.strategy:keyword | always_allow | never_allow 打断模式
+
+### • welcome_options: 自定义开场白
+
+### • Metadata: 智能体自定义参数
+
+#### ~~—~~
+
+#### 2)`audio.create` 开始发送音频(Push -T o -T alk)
+
+### •
+
+### • 仅在 push_to_talk 模式使用; realtime 模式无需此事件
+
+#### ~~—~~ 3) 二进制帧 上行音频数据
+
+### •
+
+直接发送二进制数据帧(非 JSON)
+
+### •
+
+具体帧格式见“音频帧与格式”
+
+#### ~~—~~
+#### 4)`audio.completed` 结束发送音频(Push -T o -T alk)
+
+### 原始逐行文本重排
+
+27      }
+   28     }
+   29   }
+
+字段要点:
+
+•  session_mode:realtime | push_to_talk 对话模式
+• input_mode:audio | text 输入类型
+• output_mode:audio | text | both 输出类型
+•  audio_config.input/output.format:pcm | opus 音频配置
+
+                  语速调整百分比 [-100, 100],基于初始语速增减,0=不调整,•  audio_config.output.speech_rate:
+  50=加快50%,-50=减慢50%
+• audio_encryption:可选;开启后仅加密上下行二进制音频帧,JSON 控制消息不加密
+•  interrupt_options.strategy:keyword  | always_allow | never_allow 打断模式
+
+          自定义开场白•  welcome_options:
+•  Metadata: 智能体自定义参数
+
+2)`audio.create` — 开始发送音频(Push-To-Talk)
+
+• 无负载;发送后开始以二进制帧上行音频
+
+ 仅在 push_to_talk 模式使用;realtime 模式无需此事件•
+
+```
+{"type": "audio.create"}
+```
+
+3) 二进制帧 — 上行音频数据
+
+ 直接发送二进制数据帧(非 JSON)•
+• 具体帧格式见“音频帧与格式”
+
+4)`audio.completed` — 结束发送音频(Push-To-Talk)
+
+## Page 5
+
+### 结构化抽取
+
+### •
+
+#### ~~—~~ 5)`prompt` 文本提示(Text 模式)
+
+#### ~~—~~ 6)`synthesis` 直接请求 TTS 合成
+
+#### ~~—~~ 7)`cancel` 取消当前处理
+
+### 原始逐行文本重排
+
+• 无负载;表示本轮语音输入结束
+
+```
+{"type": "audio.completed"}
+```
+
+5)`prompt` — 文本提示(Text 模式)
+
+负载结构:PromptData
+
+```
+{
+"type": "prompt",
+"data": {
+"messages": [
+{"role": "user", "content": "你好,给我讲个笑话"}
+]
+}
+}
+```
+
+6)`synthesis` — 直接请求 TTS 合成
+
+负载结构:SynthesisData
+
+```
+{
+"type": "synthesis",
+"data": {"text": "这是一段需要合成的文本"}
+}
+```
+
+7)`cancel` — 取消当前处理
+
+## Page 6
+
+### 结构化抽取
+
+### •
+
+可用于打断正在进行的 LLM/TTS
+
+#### ~~—~~ 8)`metadata.update` 会话中动态更新 metadata
+
+### • metadata 为任意 JSON 对象,会覆盖会话当前 metadata。
+
+### • 对 Dify Provider:更新后会同步刷新 inputs ,并应用到后续 LLM 请求。
+
+### • 若 metadata 顶层包含 inputs 对象,则会展开并合并到 Dify inputs 。
+
+### • 仅影响后续请求,不回溯已在执行中的 LLM 调用。
+
+### 服务端事件类型(发送到客户端)
+
+### 原始逐行文本重排
+
+可用于打断正在进行的 LLM/TTS•
+
+```
+{"type": "cancel"}
+```
+
+8)`metadata.update` — 会话中动态更新 metadata
+
+负载结构:MetadataUpdateData
+
+```
+{
+"type": "metadata.update",
+"data": {
+"metadata": {
+"inputs": {
+"scene": "car",
+"city": "shanghai"
+},
+"trace_tag": "demo-001"
+}
+}
+}
+```
+
+字段要点:
+
+       为任意 JSON 对象,会覆盖会话当前 metadata。•  metadata
+
+  对 Dify Provider:更新后会同步刷新 inputs ,并应用到后续 LLM 请求。•
+
+  若 metadata 顶层包含 inputs 对象,则会展开并合并到 Dify inputs 。•
+
+ 仅影响后续请求,不回溯已在执行中的 LLM 调用。•
+
+服务端事件类型(发送到客户端)
+
+## Page 7
+
+### 结构化抽取
+
+### • started :会话已启动,返回 StartedConfig
+
+### • canceled :当前对话流程被取消 • metadata.updated :metadata 更新已应用
+
+### • completed :一次完整的 ASR→LLM→TTS 流程结束(如有)
+
+### • error :错误,负载为 ErrorData
+
+```
+{
+
+ "type": "metadata.updated",
+
+```
+
+### 原始逐行文本重排
+
+会话/流程事件
+
+•  started :会话已启动,返回 StartedConfig
+
+```
+{
+"type": "started",
+"data": {
+"agent": {"id": "2004431198008324097", "name": "assistant",
+"welcome_message": "你好"},
+"input_mode": "audio",
+"output_mode": "audio",
+"audio_config": {
+"input": {"format": "pcm", "sample_rate": 16000, "bit_rate": 16,
+"channel": 1},
+"output": {"format": "pcm", "sample_rate": 16000, "bit_rate": 16,
+"channel": 1}
+},
+"audio_encryption": {
+"enabled": true,
+"algorithm": "x25519-aes-256-gcm",
+"server_public_key": "base64-public-key-bytes",
+"salt": "base64-16-byte-random-salt",
+"frame_format": "nonce+ciphertext_with_tag"
+},
+"interrupt_options": {"strategy": "keyword", "interrupt_keywords": ["停"]},
+"welcome_enabled": true,
+"welcome_message": "你好!我可以帮你什么?"
+}
+}
+```
+
+•  canceled :当前对话流程被取消
+•  metadata.updated :metadata 更新已应用
+•  completed :一次完整的 ASR→LLM→TTS 流程结束(如有)
+•  error :错误,负载为 ErrorData
+
+```
+{
+"type": "metadata.updated",
+```
+
+## Page 8
+
+### 结构化抽取
+
+```
+ "data": {
+
+  "session_id": "sess_xxx",
+
+  "status": "updated",
+
+  "metadata": {
+
+   "inputs": {"scene": "car"}
+
+}
+
+}
+
+}
+
+```
+
+### • vad.active / vad.silence :VAD 检测到开始/结束说话(无负载或简单元数据)
+
+### • asr.result :转写片段( TranscriptData ;流式部分 or 最终)
+
+### •
+
+### 原始逐行文本重排
+
+3     "data": {
+   4       "session_id": "sess_xxx",
+   5       "status": "updated",
+   6       "metadata": {
+   7         "inputs": {"scene": "car"}
+   8      }
+   9     }
+   10   }
+
+```
+{
+"type": "error",
+"data": {"code": "BadRequest", "message": "参数不合法", "details": "..."}
+}
+```
+
+VAD/ASR 事件
+
+•  vad.active  / vad.silence :VAD 检测到开始/结束说话(无负载或简单元数据)
+•  asr.started :开始识别
+•  asr.result :转写片段(TranscriptData ;流式部分 or 最终)
+
+```
+{
+"type": "asr.result",
+"data": {
+"text": "今天天气",
+"confidence": 0.92,
+"language": "zh",
+"is_final": false,
+"start_time": 0,
+"end_time": 800
+}
+}
+```
+
+•  asr.completed :识别完成
+
+## Page 9
+
+### 结构化抽取
+
+#### LLM 事件
+
+### • llm.delta :流式增量文本(示例负载形如 { "delta": "......" } )
+
+### • llm.done :生成完成
+
+#### TTS 事件与音频
+
+### • tts.started :开始返回音频 •
+
+二进制帧:连续下发音频数据(PCM/Opus)
+
+### • tts.done :音频发送结束
+
+客户端需根据 `audio_config.output.format` 决定是否解码( `opus` 需解码, `pcm` 可直接
+
+播放)。
+
+#### 音频帧加密(可选)
+
+### • 当前支持算法:x25519 - aes - 256 - gcm、x25519 - chacha20 - poly1305、p256 - aes - 256 - gcm
+
+### 原始逐行文本重排
+
+LLM 事件
+
+•  llm.started :开始生成
+•  llm.delta :流式增量文本(示例负载形如 { "delta": "......" } )
+•  llm.done :生成完成
+
+```
+{"type": "llm.delta", "data": {"delta": "你好!"}}
+```
+
+TTS 事件与音频
+
+•  tts.started :开始返回音频
+• 二进制帧:连续下发音频数据(PCM/Opus)
+•  tts.done :音频发送结束
+
+ 客户端需根据 audio_config.output.format 决定是否解码(opus 需解码,pcm 可直接
+ 播放)。
+
+音频帧与格式
+
+音频帧加密(可选)
+
+客户端在 start.data.audio_encryption.enabled=true 时启用音频帧加密:
+
+• 当前支持算法:x25519-aes-256-gcm、x25519-chacha20-poly1305、p256-aes-256-gcm
+
+## Page 10
+
+### 结构化抽取
+
+### • 客户端发送 client_public_key ,服务端在 started.data.audio_encryption 返
+
+|户端发送|client_public_key|
+|---|---|
+|`server_public_key` 与 `salt`|`server_public_key` 与 `salt`|
+
+### • 双方使用 X25519 或 P - 256 共享密钥 + HKDF - SHA256 派生上下行 AEAD key
+
+### • X25519 公钥为 32 - byte raw public key;P - 256 公钥为 65 - byte X9.62 uncompressed point  • • •
+
+解密后的 `raw_audio_payload` 仍由 `audio_config.input/output.format` 决定是
+
+PCM 还是 Opus
+
+服务端内部按 `algorithm` 使用独立的音频帧加密接口和算法工厂。后续新增算法时,WebSocket
+
+层不需要改动音频读写流程,只需要在 `audioenc` 下新增具体算法包并注册。
+
+未启用 `audio_encryption` 时,二进制帧保持原始 PCM/Opus bytes,与旧客户端兼容。
+
+#### →
+
+#### 上行(客户端 服务端)
+
+### •
+
+PCM(推荐入门):
+
+### ◦
+
+编码:S16LE(小端)
+
+### ◦ 采样率:16000 Hz  ◦
+
+声道:1(单声道)
+
+### ◦ 建议单帧大小:1600 样本 ≈ 100 ms(示例中使用)  ◦
+
+发送方式:直接以二进制帧写入 WebSocket(非 JSON)
+
+### •
+
+Opus(可选):
+
+#### →
+#### 下行(服务端 客户端)
+
+### ◦
+
+`pcm` :S16LE/16k/mono 原始帧;可直接写入音频播放流
+
+### ◦
+
+`opus` :Opus 数据包;客户端需解码后播放
+
+### 原始逐行文本重排
+
+客户端发送 client_public_key ,服务端在 started.data.audio_encryption 返•
+  回 server_public_key 与 salt
+
+ 双方使用 X25519 或 P-256 共享密钥 + HKDF-SHA256 派生上下行 AEAD key•
+
+     公钥为 32-byte raw public key;P-256 公钥为 65-byte X9.62 uncompressed point• X25519
+
+ 服务端不会返回对称密钥•
+
+                                        仍包含在密• 加密帧格式:12-byte random nonce + AEAD(raw_audio_payload) ,tag
+ 文尾部
+
+ 解密后的 raw_audio_payload 仍由 audio_config.input/output.format 决定是•
+  PCM 还是 Opus
+
+服务端内部按 algorithm 使用独立的音频帧加密接口和算法工厂。后续新增算法时,WebSocket
+层不需要改动音频读写流程,只需要在 audioenc 下新增具体算法包并注册。
+
+未启用 audio_encryption 时,二进制帧保持原始 PCM/Opus bytes,与旧客户端兼容。
+
+上行(客户端 → 服务端)
+
+• PCM(推荐入门):
+    ◦ 编码:S16LE(小端)
+    ◦ 采样率:16000 Hz
+    ◦ 声道:1(单声道)
+
+             样本 ≈ 100 ms(示例中使用)    ◦ 建议单帧大小:1600
+    ◦ 发送方式:直接以二进制帧写入 WebSocket(非 JSON)
+• Opus(可选):
+    ◦ 帧时长:建议 60 ms(示例中 frame_size = sample_rate * 60 / 1000 = 960 )
+
+   客户端需先编码再发送二进制帧    ◦
+
+   仅在 audio_config.input.format = opus 时使用    ◦
+
+下行(服务端 → 客户端)
+
+  与 audio_config.output 保持一致:•
+    ◦  pcm :S16LE/16k/mono 原始帧;可直接写入音频播放流
+    ◦  opus :Opus 数据包;客户端需解码后播放
+
+## Page 11
+
+### 结构化抽取
+
+### ◦ realtime :持续监听麦克风,VAD 自动分段;无需
+
+`audio.create` / `audio.completed` 包裹一轮语音
+
+|realtime|:持|
+|---|---|
+|||
+|`audio.create`<br>`push_to_talk`|`audio.create`<br>`push_to_talk`|
+|`audio.create`|`audio.create`|
+
+### ◦ audio :启用 VAD+ASR;向上游发送音频二进制帧
+
+### ◦ text :不启用 VAD/ASR,通过 prompt 输入文本
+
+### ◦ none :无输入,仅监听服务端事件
+
+### ◦ audio :返回 TTS 音频(二进制)
+
+### ◦ text :仅返回文本(LLM 事件)
+
+### ◦ both :同时音频与文本
+
+### ◦ none :不返回输出
+
+### ◦ keyword :命中 interrupt_keywords 时打断
+
+### ◦ thinking_time_only :仅在 LLM 思考期允许打断(示例客户端映射)
+
+### ◦ always_allow :始终允许打断
+
+### ◦ never_allow :不允许打断
+
+### • concatenate_results :是否拼接打断前后的 ASR 结果  •
+
+`interrupt_keywords` :关键词数组( `keyword` 策略生效)
+
+### 原始逐行文本重排
+
+会话与输入/输出模式
+
+•  session_mode
+    ◦  realtime :持续监听麦克风,VAD 自动分段;无需
+      audio.create / audio.completed      ◦  push_to_talk :按键/指令控制讲话开始与结束;使用
+      audio.create / audio.completed 包裹一轮语音
+•  input_mode
+    ◦  audio :启用 VAD+ASR;向上游发送音频二进制帧
+    ◦  text :不启用 VAD/ASR,通过 prompt 输入文本
+    ◦  none :无输入,仅监听服务端事件
+•  output_mode
+    ◦  audio :返回 TTS 音频(二进制)
+    ◦  text :仅返回文本(LLM 事件)
+    ◦  both :同时音频与文本
+    ◦  none :不返回输出
+
+打断策略(InterruptOptions)
+
+•  strategy
+    ◦  keyword :命中 interrupt_keywords 时打断
+    ◦  thinking_time_only :仅在 LLM 思考期允许打断(示例客户端映射)
+    ◦  always_allow :始终允许打断
+    ◦  never_allow :不允许打断
+•  concatenate_results :是否拼接打断前后的 ASR 结果
+•  interrupt_keywords :关键词数组(keyword 策略生效)
+
+示例:
+
+## Page 12
+
+### 结构化抽取
+
+#### A) Realtime(持续监听)
+
+1. 客户端连接 WebSocket
+
+2. 发送 `start` ( `session_mode=realtime` 、 `input_mode=audio` )
+
+5. 如需打断:发送 `cancel`
+
+#### B) Push -T o -T alk(按键说话)
+
+2. 每轮讲话: `audio.create` → 发送音频二进制帧 → `audio.completed`
+
+3. 服务端推送与 A 类似
+
+4. 新一轮讲话重复第 2 步
+
+### Python 示例快速开始
+
+### 原始逐行文本重排
+
+```
+{
+"strategy": "keyword",
+"interrupt_keywords": ["停", "停止", "别说了"],
+"concatenate_results": false
+}
+```
+
+典型交互流程
+
+A) Realtime(持续监听)
+
+1. 客户端连接 WebSocket
+
+2. 发送 start (session_mode=realtime 、input_mode=audio )
+
+3. 持续发送音频二进制帧
+
+4. 服务端按序推送:vad.active → asr.started → 若干 asr.result (部分) →
+   asr.completed → llm.started → 若干 llm.delta → llm.done →
+   tts.started → 若干二进制音频帧 → tts.done
+
+5. 如需打断:发送 cancel
+
+B) Push-To-Talk(按键说话)
+
+1. 发送 start (session_mode=push_to_talk )
+
+2. 每轮讲话:audio.create → 发送音频二进制帧 → audio.completed
+
+3. 服务端推送与 A 类似
+
+4. 新一轮讲话重复第 2 步
+
+Python 示例快速开始
+
+依赖:
+
+## Page 13
+
+### 结构化抽取
+
+### •
+
+### • --device :音频输入设备索引
+
+### 原始逐行文本重排
+
+```
+# macOS 推荐先安装 PortAudio(用于 PyAudio)
+brew install portaudio # 如已安装可跳过
+3
+# Python 依赖
+pip install websockets pyaudio
+# 可选(Opus 支持)
+pip install opuslib
+```
+
+运行示例:
+
+```
+# 列出设备
+python rvc-service/examples/python-demo/real_time_audio.py --list-devices
+3
+# 实时语音(默认:PCM/16k/单声道,音频输入+输出)
+python rvc-service/examples/python-demo/real_time_audio.py
+6
+# Push-To-Talk 模式
+python rvc-service/examples/python-demo/real_time_audio.py --session
+push_to_talk
+9
+# 文本输入 → 音频输出(TTS)
+python rvc-service/examples/python-demo/real_time_audio.py --input text --
+output audio
+12
+# 仅文本往返
+python rvc-service/examples/python-demo/real_time_audio.py --input text --
+output text
+15
+# 使用 Opus(需 opuslib)
+python rvc-service/examples/python-demo/real_time_audio.py --format opus
+```
+
+常用参数:
+
+•  --host/--port :服务地址与端口
+•  --device :音频输入设备索引
+
+## Page 14
+
+### 结构化抽取
+
+### • --session : realtime | push_to_talk  •
+
+### • --strategy : keyword | thinking | always | never
+
+### • --echo-cancel :播放 TTS 时暂停录音(减少回声)
+
+更多示例用法见示例脚本注释: [../examples/python demo/real_time_audio.py]
+
+### •
+
+入参音频推荐:S16LE、16kHz、单声道
+
+### • Opus 传输需客户端/服务端共同支持;帧长与码率可按实现配置,示例采用 60 ms 帧  •
+
+文本消息体字段以 [types.go](../internal/model/types.go) 为准;服务端可能扩展兼容字段
+
+### • cancel :立即请求打断当前流程;实际打断时机受 interrupt_options.strategy 影响
+
+### •
+
+初版:根据模型定义与 Python 示例整理端到端数据流与事件类型
+
+### 原始逐行文本重排
+
+•  --session :realtime  | push_to_talk
+•  --input/--output :输入/输出模式
+•  --strategy :keyword  | thinking  | always  | never
+•  --echo-cancel :播放 TTS 时暂停录音(减少回声)
+
+ 更多示例用法见示例脚本注释: [../examples/python-demo/real_time_audio.py]
+  (../examples/python-demo/real_time_audio.py)
+
+兼容性与约束
+
+• 入参音频推荐:S16LE、16kHz、单声道
+• Opus 传输需客户端/服务端共同支持;帧长与码率可按实现配置,示例采用 60 ms 帧
+
+ 文本消息体字段以 [types.go](../internal/model/types.go) 为准;服务端可能扩展兼容字段•
+
+错误处理与取消
+
+•  error :ErrorData = { code, message, details? }
+•  cancel :立即请求打断当前流程;实际打断时机受 interrupt_options.strategy 影响
+
+变更记录
+
+• 初版:根据模型定义与 Python 示例整理端到端数据流与事件类型
+
+</details>
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-001.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-001.png
new file mode 100644 (file)
index 0000000..bd0a785
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-001.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-002.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-002.png
new file mode 100644 (file)
index 0000000..8d4e1a0
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-002.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-003.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-003.png
new file mode 100644 (file)
index 0000000..e7fb32e
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-003.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-004.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-004.png
new file mode 100644 (file)
index 0000000..cedee09
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-004.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-005.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-005.png
new file mode 100644 (file)
index 0000000..c1b0ca7
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-005.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-006.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-006.png
new file mode 100644 (file)
index 0000000..ae44004
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-006.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-007.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-007.png
new file mode 100644 (file)
index 0000000..5989a6f
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-007.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-008.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-008.png
new file mode 100644 (file)
index 0000000..e2c66f3
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-008.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-009.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-009.png
new file mode 100644 (file)
index 0000000..39e1962
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-009.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-010.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-010.png
new file mode 100644 (file)
index 0000000..ef7f848
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-010.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-011.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-011.png
new file mode 100644 (file)
index 0000000..47d6eb4
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-011.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-012.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-012.png
new file mode 100644 (file)
index 0000000..c248e9d
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-012.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-013.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-013.png
new file mode 100644 (file)
index 0000000..9121eec
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-013.png" differ
diff --git a/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-014.png b/1.doc/assets/RVC Service WebSocket V3 API 开发文档/page-014.png
new file mode 100644 (file)
index 0000000..b130e42
Binary files /dev/null and "b/1.doc/assets/RVC Service WebSocket V3 API \345\274\200\345\217\221\346\226\207\346\241\243/page-014.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-001.png b/1.doc/assets/金三服务-语音对话V2.5/page-001.png
new file mode 100644 (file)
index 0000000..12abff6
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-001.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-002.png b/1.doc/assets/金三服务-语音对话V2.5/page-002.png
new file mode 100644 (file)
index 0000000..d5e9c0c
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-002.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-003.png b/1.doc/assets/金三服务-语音对话V2.5/page-003.png
new file mode 100644 (file)
index 0000000..a74aa49
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-003.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-004.png b/1.doc/assets/金三服务-语音对话V2.5/page-004.png
new file mode 100644 (file)
index 0000000..f8f12e7
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-004.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-005.png b/1.doc/assets/金三服务-语音对话V2.5/page-005.png
new file mode 100644 (file)
index 0000000..16b133a
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-005.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-006.png b/1.doc/assets/金三服务-语音对话V2.5/page-006.png
new file mode 100644 (file)
index 0000000..bd30e78
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-006.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-007.png b/1.doc/assets/金三服务-语音对话V2.5/page-007.png
new file mode 100644 (file)
index 0000000..55f8a2b
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-007.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-008.png b/1.doc/assets/金三服务-语音对话V2.5/page-008.png
new file mode 100644 (file)
index 0000000..a96e798
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-008.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-009.png b/1.doc/assets/金三服务-语音对话V2.5/page-009.png
new file mode 100644 (file)
index 0000000..8e25c4e
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-009.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-010.png b/1.doc/assets/金三服务-语音对话V2.5/page-010.png
new file mode 100644 (file)
index 0000000..a426297
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-010.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-011.png b/1.doc/assets/金三服务-语音对话V2.5/page-011.png
new file mode 100644 (file)
index 0000000..b63c494
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-011.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-012.png b/1.doc/assets/金三服务-语音对话V2.5/page-012.png
new file mode 100644 (file)
index 0000000..6d7a6c2
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-012.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-013.png b/1.doc/assets/金三服务-语音对话V2.5/page-013.png
new file mode 100644 (file)
index 0000000..6c62ba7
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-013.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-014.png b/1.doc/assets/金三服务-语音对话V2.5/page-014.png
new file mode 100644 (file)
index 0000000..5dff470
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-014.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-015.png b/1.doc/assets/金三服务-语音对话V2.5/page-015.png
new file mode 100644 (file)
index 0000000..c86641a
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-015.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-016.png b/1.doc/assets/金三服务-语音对话V2.5/page-016.png
new file mode 100644 (file)
index 0000000..4aea092
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-016.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-017.png b/1.doc/assets/金三服务-语音对话V2.5/page-017.png
new file mode 100644 (file)
index 0000000..d711fcd
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-017.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-018.png b/1.doc/assets/金三服务-语音对话V2.5/page-018.png
new file mode 100644 (file)
index 0000000..4dfc82c
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-018.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-019.png b/1.doc/assets/金三服务-语音对话V2.5/page-019.png
new file mode 100644 (file)
index 0000000..28e5f7f
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-019.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-020.png b/1.doc/assets/金三服务-语音对话V2.5/page-020.png
new file mode 100644 (file)
index 0000000..1aa8ec8
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-020.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-021.png b/1.doc/assets/金三服务-语音对话V2.5/page-021.png
new file mode 100644 (file)
index 0000000..cf92155
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-021.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-022.png b/1.doc/assets/金三服务-语音对话V2.5/page-022.png
new file mode 100644 (file)
index 0000000..55ec935
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-022.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-023.png b/1.doc/assets/金三服务-语音对话V2.5/page-023.png
new file mode 100644 (file)
index 0000000..27e9159
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-023.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-024.png b/1.doc/assets/金三服务-语音对话V2.5/page-024.png
new file mode 100644 (file)
index 0000000..36bb4be
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-024.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-025.png b/1.doc/assets/金三服务-语音对话V2.5/page-025.png
new file mode 100644 (file)
index 0000000..8a0bd3c
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-025.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-026.png b/1.doc/assets/金三服务-语音对话V2.5/page-026.png
new file mode 100644 (file)
index 0000000..0546a11
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-026.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-027.png b/1.doc/assets/金三服务-语音对话V2.5/page-027.png
new file mode 100644 (file)
index 0000000..91428c2
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-027.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-028.png b/1.doc/assets/金三服务-语音对话V2.5/page-028.png
new file mode 100644 (file)
index 0000000..8f68f8b
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-028.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-029.png b/1.doc/assets/金三服务-语音对话V2.5/page-029.png
new file mode 100644 (file)
index 0000000..1e2a7c5
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-029.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-030.png b/1.doc/assets/金三服务-语音对话V2.5/page-030.png
new file mode 100644 (file)
index 0000000..4bc0523
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-030.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-031.png b/1.doc/assets/金三服务-语音对话V2.5/page-031.png
new file mode 100644 (file)
index 0000000..fd7c506
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-031.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-032.png b/1.doc/assets/金三服务-语音对话V2.5/page-032.png
new file mode 100644 (file)
index 0000000..89c201a
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-032.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-033.png b/1.doc/assets/金三服务-语音对话V2.5/page-033.png
new file mode 100644 (file)
index 0000000..7bc6a99
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-033.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-034.png b/1.doc/assets/金三服务-语音对话V2.5/page-034.png
new file mode 100644 (file)
index 0000000..5fc944e
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-034.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-035.png b/1.doc/assets/金三服务-语音对话V2.5/page-035.png
new file mode 100644 (file)
index 0000000..869bd44
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-035.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-036.png b/1.doc/assets/金三服务-语音对话V2.5/page-036.png
new file mode 100644 (file)
index 0000000..f51200e
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-036.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-037.png b/1.doc/assets/金三服务-语音对话V2.5/page-037.png
new file mode 100644 (file)
index 0000000..17c6b0b
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-037.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-038.png b/1.doc/assets/金三服务-语音对话V2.5/page-038.png
new file mode 100644 (file)
index 0000000..cd0ca66
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-038.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-039.png b/1.doc/assets/金三服务-语音对话V2.5/page-039.png
new file mode 100644 (file)
index 0000000..39291a7
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-039.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-040.png b/1.doc/assets/金三服务-语音对话V2.5/page-040.png
new file mode 100644 (file)
index 0000000..e2c5e79
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-040.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-041.png b/1.doc/assets/金三服务-语音对话V2.5/page-041.png
new file mode 100644 (file)
index 0000000..000019f
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-041.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-042.png b/1.doc/assets/金三服务-语音对话V2.5/page-042.png
new file mode 100644 (file)
index 0000000..e1aea2a
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-042.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-043.png b/1.doc/assets/金三服务-语音对话V2.5/page-043.png
new file mode 100644 (file)
index 0000000..1086a2e
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-043.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-044.png b/1.doc/assets/金三服务-语音对话V2.5/page-044.png
new file mode 100644 (file)
index 0000000..e169717
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-044.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-045.png b/1.doc/assets/金三服务-语音对话V2.5/page-045.png
new file mode 100644 (file)
index 0000000..56aeaac
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-045.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-046.png b/1.doc/assets/金三服务-语音对话V2.5/page-046.png
new file mode 100644 (file)
index 0000000..27f4ff3
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-046.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-047.png b/1.doc/assets/金三服务-语音对话V2.5/page-047.png
new file mode 100644 (file)
index 0000000..a66e611
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-047.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-048.png b/1.doc/assets/金三服务-语音对话V2.5/page-048.png
new file mode 100644 (file)
index 0000000..fb840b1
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-048.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-049.png b/1.doc/assets/金三服务-语音对话V2.5/page-049.png
new file mode 100644 (file)
index 0000000..53b6efe
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-049.png" differ
diff --git a/1.doc/assets/金三服务-语音对话V2.5/page-050.png b/1.doc/assets/金三服务-语音对话V2.5/page-050.png
new file mode 100644 (file)
index 0000000..1674738
Binary files /dev/null and "b/1.doc/assets/\351\207\221\344\270\211\346\234\215\345\212\241-\350\257\255\351\237\263\345\257\271\350\257\235V2.5/page-050.png" differ
diff --git a/1.doc/convert_pdf_to_hybrid_md.py b/1.doc/convert_pdf_to_hybrid_md.py
new file mode 100644 (file)
index 0000000..46f2b17
--- /dev/null
@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+from datetime import datetime
+from pathlib import Path
+from urllib.parse import quote
+
+import fitz
+import pymupdf4llm
+
+
+DOCS = [
+    Path("RVC Service WebSocket V3 API 开发文档.pdf"),
+    Path("金三服务-语音对话V2.5.pdf"),
+]
+
+ROOT = Path(__file__).resolve().parent
+ASSET_ROOT = ROOT / "assets"
+PAGE_IMAGE_WIDTH = 1200
+
+
+def normalize_text(text: str) -> str:
+    text = unicodedata.normalize("NFKC", text)
+    text = (
+        text.replace("\u200b", "")
+        .replace("\ufeff", "")
+        .replace("\x01", "")
+        .replace("\xa0", " ")
+    )
+    text = re.sub(r"[ \t]+\n", "\n", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def clean_structured_text(text: str) -> str:
+    text = normalize_text(text)
+    text = re.sub(r"<br>`?\d{1,3}`?(?=(<br>|$))", "", text)
+
+    cleaned_lines = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        # PDFs generated from web pages often expose code-block line numbers as
+        # standalone text. They hurt AI parsing more than they help readers.
+        if re.fullmatch(r"`?\d{1,3}`?", stripped) or re.fullmatch(r"#{1,6}", stripped):
+            continue
+        cleaned_lines.append(line.rstrip())
+    text = "\n".join(cleaned_lines).strip()
+    text = re.sub(r"```\n\s*```", "", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+def clean_plain_text(text: str) -> str:
+    return normalize_text(text)
+
+
+def strip_pdf_line_number(line: str):
+    match = re.match(r"^\s*\d{1,4}\s+(.*\S)\s*$", line)
+    if not match:
+        return None
+    return match.group(1)
+
+
+def plain_text_to_markdown(text: str) -> str:
+    """Rebuild Markdown from the PDF text layer.
+
+    The source PDFs render code as a visible "代码块" label followed by normal
+    text lines with printed line numbers. Neither PyMuPDF nor PyMuPDF4LLM sees
+    those regions as semantic code blocks, so we recover them from that pattern.
+    """
+    lines = clean_plain_text(text).splitlines()
+    out: list[str] = []
+    in_code = False
+    pending_code = False
+
+    def close_code() -> None:
+        nonlocal in_code
+        if in_code:
+            while out and out[-1] == "":
+                out.pop()
+            out.extend(["```", ""])
+            in_code = False
+
+    for raw_line in lines:
+        line = raw_line.rstrip()
+        stripped = line.strip()
+        code_content = strip_pdf_line_number(line)
+
+        if stripped == "代码块":
+            close_code()
+            pending_code = True
+            continue
+
+        if pending_code:
+            if not stripped:
+                continue
+            if code_content is not None:
+                out.extend(["```", code_content])
+                in_code = True
+                pending_code = False
+                continue
+            out.append(stripped)
+            pending_code = False
+            continue
+
+        if in_code:
+            if code_content is not None:
+                out.append(code_content)
+                continue
+            if not stripped:
+                close_code()
+                continue
+            # Keep obvious wrapped code lines such as long signatures split by
+            # the PDF generator. A non-indented line usually means normal prose.
+            if raw_line.startswith(" ") and not stripped.startswith(("•", "◦")):
+                out.append(stripped)
+                continue
+            close_code()
+
+        if stripped:
+            out.append(line)
+        elif out and out[-1] != "":
+            out.append("")
+
+    close_code()
+    return "\n".join(out).strip()
+
+
+def html_escape(text: str) -> str:
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def render_page_images(pdf_path: Path, asset_dir: Path) -> list[str]:
+    asset_dir.mkdir(parents=True, exist_ok=True)
+    for old_image in asset_dir.glob("page-*.png"):
+        old_image.unlink()
+
+    doc = fitz.open(pdf_path)
+    image_links: list[str] = []
+    for page_index, page in enumerate(doc, start=1):
+        zoom = PAGE_IMAGE_WIDTH / page.rect.width
+        pix = page.get_pixmap(matrix=fitz.Matrix(zoom, zoom), alpha=False)
+        image_path = asset_dir / f"page-{page_index:03d}.png"
+        pix.save(image_path)
+        rel_path = image_path.relative_to(ROOT).as_posix()
+        image_links.append(quote(rel_path, safe="/"))
+    return image_links
+
+
+def extract_markdown_chunks(pdf_path: Path) -> list[str]:
+    chunks = pymupdf4llm.to_markdown(
+        str(pdf_path),
+        page_chunks=True,
+        force_text=True,
+        table_strategy="lines_strict",
+        show_progress=False,
+        use_glyphs=False,
+    )
+    return [clean_structured_text(chunk.get("text", "")) for chunk in chunks]
+
+
+def extract_plain_text_chunks(pdf_path: Path) -> list[str]:
+    doc = fitz.open(pdf_path)
+    return [clean_plain_text(page.get_text("text", sort=True)) for page in doc]
+
+
+def build_markdown(pdf_path: Path) -> str:
+    doc = fitz.open(pdf_path)
+    page_count = doc.page_count
+    title = pdf_path.stem
+    asset_dir = ASSET_ROOT / title
+    image_links = render_page_images(pdf_path, asset_dir)
+    text_chunks = extract_markdown_chunks(pdf_path)
+    plain_text_chunks = extract_plain_text_chunks(pdf_path)
+
+    generated_at = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    lines: list[str] = [
+        f"# {title}",
+        "",
+        "> 本文档由原始 PDF 自动转换生成,默认预览展示 PDF 页面 PNG,视觉上尽量贴近原文件。",
+        f"> 原始文件: `{pdf_path.name}`;页数: {page_count};生成时间: {generated_at}。",
+        "",
+        "<details>",
+        "<summary>AI 使用说明</summary>",
+        "",
+        "- 页面图片来自 PDF 逐页渲染,是人工核对的基准。",
+        "- 每页图片后面的折叠区保留结构化抽取文本和逐行重排文本,方便 AI 检索、总结和问答。",
+        "- 如抽取文本与图片不一致,请以页面图片或原始 PDF 为准。",
+        "",
+        "</details>",
+        "",
+    ]
+    ai_lines: list[str] = [
+        "<details>",
+        "<summary>AI 可读文本全集</summary>",
+        "",
+        "> 以下文本来自 PDF 抽取和逐行重排,用于检索、总结和问答;视觉核对请以前面的页面图片为准。",
+        "",
+    ]
+
+    for page_number in range(1, page_count + 1):
+        image_link = image_links[page_number - 1]
+        text = text_chunks[page_number - 1] if page_number - 1 < len(text_chunks) else ""
+        plain_text = (
+            plain_text_chunks[page_number - 1]
+            if page_number - 1 < len(plain_text_chunks)
+            else ""
+        )
+        lines.extend(
+            [
+                f"<a id=\"page-{page_number}\"></a>",
+                "",
+                f"<!-- Page {page_number} visual layer: rendered from the original PDF. -->",
+                "",
+                f"<img src=\"{image_link}\" alt=\"{html_escape(title)} Page {page_number}\" style=\"width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;\" />",
+                "",
+            ]
+        )
+        ai_lines.extend(
+            [
+                f"## Page {page_number}",
+                "",
+                "### 结构化抽取",
+                "",
+                text or "_本页未抽取到结构化文本。_",
+                "",
+                "### 原始逐行文本重排",
+                "",
+                plain_text_to_markdown(plain_text) or "_本页未抽取到原始文本。_",
+                "",
+            ]
+        )
+
+    ai_lines.extend(["</details>", ""])
+    return "\n".join(lines + ai_lines).rstrip() + "\n"
+
+
+def main() -> None:
+    for pdf_name in DOCS:
+        pdf_path = ROOT / pdf_name
+        if not pdf_path.exists():
+            raise FileNotFoundError(pdf_path)
+        md_path = pdf_path.with_suffix(".md")
+        with md_path.open("w", encoding="utf-8", newline="\n") as file:
+            file.write(build_markdown(pdf_path))
+        print(f"converted: {pdf_path.name} -> {md_path.name}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/1.doc/金三服务-语音对话V2.5.md b/1.doc/金三服务-语音对话V2.5.md
new file mode 100644 (file)
index 0000000..5e59a44
--- /dev/null
@@ -0,0 +1,6001 @@
+# 金三服务-语音对话V2.5
+
+> 本文档由原始 PDF 自动转换生成,默认预览展示 PDF 页面 PNG,视觉上尽量贴近原文件。
+> 原始文件: `金三服务-语音对话V2.5.pdf`;页数: 50;生成时间: 2026-05-11 19:09:07。
+
+<details>
+<summary>AI 使用说明</summary>
+
+- 页面图片来自 PDF 逐页渲染,是人工核对的基准。
+- 每页图片后面的折叠区保留结构化抽取文本和逐行重排文本,方便 AI 检索、总结和问答。
+- 如抽取文本与图片不一致,请以页面图片或原始 PDF 为准。
+
+</details>
+
+<a id="page-1"></a>
+
+<!-- Page 1 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-001.png" alt="金三服务-语音对话V2.5 Page 1" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-2"></a>
+
+<!-- Page 2 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-002.png" alt="金三服务-语音对话V2.5 Page 2" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-3"></a>
+
+<!-- Page 3 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-003.png" alt="金三服务-语音对话V2.5 Page 3" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-4"></a>
+
+<!-- Page 4 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-004.png" alt="金三服务-语音对话V2.5 Page 4" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-5"></a>
+
+<!-- Page 5 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-005.png" alt="金三服务-语音对话V2.5 Page 5" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-6"></a>
+
+<!-- Page 6 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-006.png" alt="金三服务-语音对话V2.5 Page 6" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-7"></a>
+
+<!-- Page 7 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-007.png" alt="金三服务-语音对话V2.5 Page 7" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-8"></a>
+
+<!-- Page 8 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-008.png" alt="金三服务-语音对话V2.5 Page 8" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-9"></a>
+
+<!-- Page 9 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-009.png" alt="金三服务-语音对话V2.5 Page 9" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-10"></a>
+
+<!-- Page 10 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-010.png" alt="金三服务-语音对话V2.5 Page 10" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-11"></a>
+
+<!-- Page 11 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-011.png" alt="金三服务-语音对话V2.5 Page 11" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-12"></a>
+
+<!-- Page 12 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-012.png" alt="金三服务-语音对话V2.5 Page 12" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-13"></a>
+
+<!-- Page 13 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-013.png" alt="金三服务-语音对话V2.5 Page 13" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-14"></a>
+
+<!-- Page 14 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-014.png" alt="金三服务-语音对话V2.5 Page 14" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-15"></a>
+
+<!-- Page 15 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-015.png" alt="金三服务-语音对话V2.5 Page 15" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-16"></a>
+
+<!-- Page 16 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-016.png" alt="金三服务-语音对话V2.5 Page 16" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-17"></a>
+
+<!-- Page 17 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-017.png" alt="金三服务-语音对话V2.5 Page 17" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-18"></a>
+
+<!-- Page 18 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-018.png" alt="金三服务-语音对话V2.5 Page 18" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-19"></a>
+
+<!-- Page 19 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-019.png" alt="金三服务-语音对话V2.5 Page 19" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-20"></a>
+
+<!-- Page 20 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-020.png" alt="金三服务-语音对话V2.5 Page 20" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-21"></a>
+
+<!-- Page 21 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-021.png" alt="金三服务-语音对话V2.5 Page 21" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-22"></a>
+
+<!-- Page 22 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-022.png" alt="金三服务-语音对话V2.5 Page 22" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-23"></a>
+
+<!-- Page 23 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-023.png" alt="金三服务-语音对话V2.5 Page 23" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-24"></a>
+
+<!-- Page 24 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-024.png" alt="金三服务-语音对话V2.5 Page 24" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-25"></a>
+
+<!-- Page 25 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-025.png" alt="金三服务-语音对话V2.5 Page 25" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-26"></a>
+
+<!-- Page 26 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-026.png" alt="金三服务-语音对话V2.5 Page 26" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-27"></a>
+
+<!-- Page 27 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-027.png" alt="金三服务-语音对话V2.5 Page 27" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-28"></a>
+
+<!-- Page 28 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-028.png" alt="金三服务-语音对话V2.5 Page 28" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-29"></a>
+
+<!-- Page 29 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-029.png" alt="金三服务-语音对话V2.5 Page 29" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-30"></a>
+
+<!-- Page 30 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-030.png" alt="金三服务-语音对话V2.5 Page 30" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-31"></a>
+
+<!-- Page 31 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-031.png" alt="金三服务-语音对话V2.5 Page 31" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-32"></a>
+
+<!-- Page 32 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-032.png" alt="金三服务-语音对话V2.5 Page 32" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-33"></a>
+
+<!-- Page 33 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-033.png" alt="金三服务-语音对话V2.5 Page 33" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-34"></a>
+
+<!-- Page 34 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-034.png" alt="金三服务-语音对话V2.5 Page 34" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-35"></a>
+
+<!-- Page 35 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-035.png" alt="金三服务-语音对话V2.5 Page 35" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-36"></a>
+
+<!-- Page 36 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-036.png" alt="金三服务-语音对话V2.5 Page 36" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-37"></a>
+
+<!-- Page 37 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-037.png" alt="金三服务-语音对话V2.5 Page 37" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-38"></a>
+
+<!-- Page 38 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-038.png" alt="金三服务-语音对话V2.5 Page 38" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-39"></a>
+
+<!-- Page 39 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-039.png" alt="金三服务-语音对话V2.5 Page 39" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-40"></a>
+
+<!-- Page 40 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-040.png" alt="金三服务-语音对话V2.5 Page 40" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-41"></a>
+
+<!-- Page 41 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-041.png" alt="金三服务-语音对话V2.5 Page 41" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-42"></a>
+
+<!-- Page 42 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-042.png" alt="金三服务-语音对话V2.5 Page 42" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-43"></a>
+
+<!-- Page 43 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-043.png" alt="金三服务-语音对话V2.5 Page 43" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-44"></a>
+
+<!-- Page 44 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-044.png" alt="金三服务-语音对话V2.5 Page 44" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-45"></a>
+
+<!-- Page 45 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-045.png" alt="金三服务-语音对话V2.5 Page 45" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-46"></a>
+
+<!-- Page 46 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-046.png" alt="金三服务-语音对话V2.5 Page 46" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-47"></a>
+
+<!-- Page 47 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-047.png" alt="金三服务-语音对话V2.5 Page 47" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-48"></a>
+
+<!-- Page 48 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-048.png" alt="金三服务-语音对话V2.5 Page 48" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-49"></a>
+
+<!-- Page 49 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-049.png" alt="金三服务-语音对话V2.5 Page 49" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<a id="page-50"></a>
+
+<!-- Page 50 visual layer: rendered from the original PDF. -->
+
+<img src="assets/%E9%87%91%E4%B8%89%E6%9C%8D%E5%8A%A1-%E8%AF%AD%E9%9F%B3%E5%AF%B9%E8%AF%9DV2.5/page-050.png" alt="金三服务-语音对话V2.5 Page 50" style="width: 100%; max-width: 960px; display: block; margin: 0 auto 12px auto;" />
+
+<details>
+<summary>AI 可读文本全集</summary>
+
+> 以下文本来自 PDF 抽取和逐行重排,用于检索、总结和问答;视觉核对请以前面的页面图片为准。
+
+## Page 1
+
+### 结构化抽取
+
+## DMP 授权服务
+
+设备通过DMP管理平台获取设备授权拿到 dt 后请求AMP服务
+
+### 设备激活流程
+
+### 原始逐行文本重排
+
+金三服务-语音对话V2.5
+
+DMP 授权服务
+
+ 设备通过DMP管理平台获取设备授权拿到 dt 后请求AMP服务
+
+设备激活流程
+
+用户接入
+
+BaseUrl
+
+```
+https://app-api.raisound.com
+```
+
+## Page 2
+
+### 结构化抽取
+
+#### 设备激活
+
+|接口名称|设备激活|
+|---|---|
+|业务说明|当App检查密码时,发现没有密码,这个时候发起激活调用。携带用户的token,如果没有则<br>会静默注册一个用户,并且返回token给App.|
+|请求路径|/dev/auth/active|
+|请求方法|PUT|
+|请求参数|•<br>body<br>代码块<br>`{`<br>`  deviceId:'`设备`ID',`<br>`  pid:'`产品`ID',`<br>`  sign:'`签名结果`',`<br>`  timeStamp:'`时间戳`',`<br>`  signMethod:'`签名方法,`HMACSHA1/HMACSHA256/MD5'`<br>`}`<br>◦<br>签名内容:deviceId+pid+timeStamp,加密算法的key是productSecret,从后台管<br>理中心的产品页获取(签名是为了防止篡改)<br>◦<br>MD5签名示例:<br>代码块<br>`# `设备`ID`:`1234567890`<br>`# PID`:`Amg1HJ3dJkX3kLiLPNFg`<br>`# `时间戳:`1717752535000`<br>`# `秘钥` productSecret`<br>`# `签名内容:<br>`1234567890Amg1HJ3dJkX3kLiLPNFg1717752535000productSecre`<br>`t`<br>`# `签名结果:`34bf037d9f6b22cf07aeb028e1ea7cc8`<br>`6`|
+
+##### 请求结果  • 激活成功
+
+```
+{
+
+```
+
+### 原始逐行文本重排
+
+设备激活
+
+ 接口名称    设备激活
+
+ 业务说明    当App检查密码时,发现没有密码,这个时候发起激活调用。携带用户的token,如果没有则
+          会静默注册一个用户,并且返回token给App.
+
+ 请求路径       /dev/auth/active
+
+ 请求方法      PUT
+
+ 请求参数        •  body
+
+```
+{
+deviceId:'设备ID',
+pid:'产品ID',
+sign:'签名结果',
+timeStamp:'时间戳',
+signMethod:'签名方法,HMACSHA1/HMACSHA256/MD5'
+}
+```
+
+                     ◦  签名内容:deviceId+pid+timeStamp,加密算法的key是productSecret,从后台管
+            理中心的产品页获取(签名是为了防止篡改)
+
+                     ◦ MD5签名示例:
+
+```
+# 设备ID:1234567890
+# PID:Amg1HJ3dJkX3kLiLPNFg
+# 时间戳:1717752535000
+# 秘钥 productSecret
+# 签名内容:
+1234567890Amg1HJ3dJkX3kLiLPNFg1717752535000productSecre
+t
+# 签名结果:34bf037d9f6b22cf07aeb028e1ea7cc8
+```
+
+ 请求结果        • 激活成功
+
+```
+{
+```
+
+## Page 3
+
+### 结构化抽取
+
+```
+success:true,
+```
+
+`msg:'` 激活成功 `',`
+
+```
+code:20000,
+
+data:{
+
+```
+
+`deviceId:'` 设备 `ID',`
+
+`password:'` 设备密码 `',`
+
+`nonce:'16` 个字符的随机字符串 `'`
+
+```
+}
+
+}
+
+```
+
+##### ◦ 密码通讯加密,请参考附录,注意,需要把密码解密出来,保存到一个安全空间。  • 激活失败
+
+##### • 非法设备
+
+##### • 签名错误
+
+### 原始逐行文本重排
+
+2       success:true,
+      3     msg:'激活成功',
+      4       code:20000,
+      5       data:{
+      6          deviceId:'设备ID',
+      7         password:'设备密码',
+      8        nonce:'16个字符的随机字符串'
+      9      }
+     10   }
+
+    ◦ 密码通讯加密,请参考附录,注意,需要把密码解密出来,保存到一个安全空间。
+• 激活失败
+
+```
+{
+success:false,
+msg:'激活失败',
+code:50025,
+data:null
+}
+```
+
+• 非法设备
+
+```
+{
+success:false,
+msg:'非法设备',
+code:50026,
+data:null
+}
+```
+
+• 签名错误
+
+```
+{
+success:false,
+msg:'签名错误',
+code:50019,
+data:null
+}
+```
+
+## Page 4
+
+### 结构化抽取
+
+|接口名称|设备登录|
+|---|---|
+|业务说明|如果token(50027)失效的时候|
+|请求路径|/dev/auth/sign_in|
+|请求方法|POST|
+|请求参数|•<br>body参数<br>代码块<br>`{`<br>`  deviceId:'`设备`ID',`<br>`  pid:'`产品`ID',`<br>`  password:'`密码`',`<br>`  nonce:'16`个字符的随机字符串`'`<br>`}`<br>◦<br>密码通讯加密,请参考附录[#密码通讯加密]<br>`6`|
+
+##### 请求结果  • 登录成功
+
+### 原始逐行文本重排
+
+设备登录
+
+ 接口名称    设备登录
+
+ 业务说明     如果token(50027)失效的时候
+
+ 请求路径       /dev/auth/sign_in
+
+ 请求方法      POST
+
+ 请求参数        •  body参数
+
+```
+{
+deviceId:'设备ID',
+pid:'产品ID',
+password:'密码',
+nonce:'16个字符的随机字符串'
+}
+```
+
+                     ◦ 密码通讯加密,请参考附录[#密码通讯加密]
+
+ 请求结果        • 登录成功
+
+```
+{
+success:true,
+msg:'登录成功',
+code:20000,
+data:{
+id:'设备ID',
+deviceName:'设备名称',
+productName:'产品名称',
+quotaList:[
+{
+serviceName:'服务名称,比如说TTS/ASR..',
+platform:'平台,比如说aliyun/spark..',
+balance:'余额,整数',
+type:'limit按余额算,unlimit不限制',
+unit:'单位,比如说token/次/分钟'
+}
+]
+}
+}
+```
+
+## Page 5
+
+### 结构化抽取
+
+##### •
+
+设备未激活/密码错误(这种情况几乎没有)
+
+|接口名称|检查设备令牌是否有效|
+|---|---|
+|业务说明|如果手上有bz~~-~~dt的令牌,可以检查一下是否有效,无效的话可以去登陆|
+|请求路径|/dev/auth/token|
+|请求方法|GET|
+|请求参数|•<br>无|
+
+##### 请求结果  • 账号已登录
+
+### 原始逐行文本重排
+
+• 设备未激活/密码错误(这种情况几乎没有)
+
+```
+{
+success:false,
+msg:'设备未激活/密码错误',
+code:50000,
+data:null
+}
+```
+
+                  • 登录成功token会在头部的bz-dt 字段返回,保存起来,并且要监听每个请求头的bz-
+                 dt 是否有值,有的话覆盖本地的设备令牌。
+
+设备令牌检查
+
+ 接口名称    检查设备令牌是否有效
+
+ 业务说明    如果手上有bz-dt的令牌,可以检查一下是否有效,无效的话可以去登陆
+
+ 请求路径       /dev/auth/token
+
+ 请求方法       GET
+
+ 请求参数        •  无
+
+ 请求结果        • 账号已登录
+
+```
+{
+success:true,
+msg:'账号已登录',
+code:20000,
+data:{
+"deviceId":"设备ID",
+"productName":"产品名称",
+"deviceName":"设备名称",
+"companyId":"公司ID",
+"productId":"产品ID",
+"productImage":"产品图片",
+}
+}
+```
+
+## Page 6
+
+### 结构化抽取
+
+```
+import requests
+
+import time
+
+import hashlib
+
+import hmac
+
+import json
+
+from typing import Dict, Optional
+
+class DeviceAuth:
+
+  def __init__(self):
+
+```
+
+`#` 授权 `API` 接口
+
+```
+self.API_BASE_URL = "https://app-api.raisound.com"
+
+```
+
+`#` 产品 `ID`
+
+```
+self.PRODUCT_ID = ""
+
+self.PRODUCT_SECRET = ""
+
+```
+
+`#` 设备 `ID`
+
+```
+self.DEVICE_ID = "953b065fec223eea"
+
+```
+
+`self.dt_token = None` `#` 存储设备令牌
+
+```
+  def _generate_md5_signature(self, data: str) -> str:
+```
+
+`"""` 生成 `MD5` 签名 `(` 用于设备激活 `)"""`
+
+`#` 创建 `MD5` 哈希对象
+
+```
+md5_hash = hashlib.md5()
+
+```
+
+`#` 更新哈希内容(需编码为 `bytes` )
+
+```
+md5_hash.update(data.encode())
+
+     return md5_hash.hexdigest()
+
+  def _generate_hmac_sha256(self, data: str) -> str:
+```
+
+`"""` 生成 `HMAC-SHA256` 签名 `(` 更高安全性 `)"""`
+
+`#` 使用 `product_secret` 作为密钥, `SHA256` 算法
+
+### 原始逐行文本重排
+
+• 账号未登录
+
+```
+{
+success:false,
+msg:'账号未登录',
+code:50001,
+data:null
+}
+```
+
+```
+import requests
+import time
+import hashlib
+import hmac
+import json
+from typing import Dict, Optional
+7
+class DeviceAuth:
+# 初始化全局配置
+def __init__(self):
+# 授权API接口
+self.API_BASE_URL = "https://app-api.raisound.com"
+# 产品ID
+self.PRODUCT_ID = ""
+# 产品密钥
+self.PRODUCT_SECRET = ""
+# 设备ID
+self.DEVICE_ID = "953b065fec223eea"
+# 存储设备令牌的变量
+self.dt_token = None # 存储设备令牌
+```
+
+21
+22       def _generate_md5_signature(self, data: str) -> str:
+23        """生成MD5签名(用于设备激活)"""
+24       # 创建MD5哈希对象
+25           md5_hash = hashlib.md5()
+26       # 更新哈希内容(需编码为bytes)
+27           md5_hash.update(data.encode())
+28       # 返回16进制格式的哈希值
+29           return md5_hash.hexdigest()
+30
+31       def _generate_hmac_sha256(self, data: str) -> str:
+32         """生成HMAC-SHA256签名(更高安全性)"""
+33       # 使用product_secret作为密钥,SHA256算法
+
+## Page 7
+
+### 结构化抽取
+
+```
+signature =hmac.new(
+```
+
+`self.PRODUCT_SECRET.encode(), #` 密钥
+
+`data.encode(),         #` 待签名的数据
+
+`hashlib.sha256         #` 哈希算法
+
+```
+)
+
+     return signature.hexdigest()
+
+```
+
+`# http` 请求
+
+```
+  def _perform_http_request(
+
+self,
+```
+
+`endpoint: str,         # API` 请求路径(如 `"/dev/auth/active"` )
+
+`method: str,          # http` 请求方法( `GET/POST/PUT` )
+
+`body: Optional[Dict] = None,  #` 请求体(字典格式)
+
+`token: Optional[str] = None` `#` 可选的认证 `token`
+
+```
+) -> Dict:
+
+```
+
+`"""` 执行 `HTTP` 请求 `"""`
+
+`url = f"{self.API_BASE_URL}{endpoint}"` `#` 构造完整的 `URL`
+
+`headers = {"Content-Type": "application/json"}   #` 基础请求头
+
+`#` 如果提供了 `token` ,添加到 `headers` 信息头中
+
+```
+     if token:
+
+       print(token)
+
+headers["bz-dt"] = f"{token}"
+
+     try:
+
+       if method.upper() == "GET":
+
+response = requests.get(url, headers=headers)
+
+       elif method.upper() == "POST":
+
+response = requests.post(url, headers=headers, json=body)
+
+       elif method.upper() == "PUT":
+
+response = requests.put(url, headers=headers, json=body)
+
+       else:
+
+         raise ValueError(f"Unsupported HTTP method: {method}")
+
+```
+
+`#` 检查响应头中是否有 `bz-dt` 令牌
+
+```
+       if 'bz-dt' in response.headers:
+
+self.dt_token = response.headers['bz-dt']
+
+```
+
+`print(f"` 获取到设备令牌 `: {self.dt_token}")`
+
+`#` 返回 `JSON` 格式的响应体
+
+```
+       return response.json()
+
+     except requests.exceptions.RequestException as e:
+
+```
+
+`print(f"HTTP` 请求失败 `: {e}")`
+
+### 原始逐行文本重排
+
+34           signature =hmac.new(
+35               self.PRODUCT_SECRET.encode(), # 密钥
+36               data.encode(),           # 待签名的数据
+37               hashlib.sha256           # 哈希算法
+38          )
+39       # 返回16进制格式的哈希值
+40           return signature.hexdigest()
+41
+42    # http请求
+43       def _perform_http_request(
+44           self,
+45           endpoint: str,           # API请求路径(如"/dev/auth/active")
+46           method: str,            # http请求方法(GET/POST/PUT)
+47           body: Optional[Dict] = None,  # 请求体(字典格式)
+48           token: Optional[str] = None  # 可选的认证token
+49      ) -> Dict:
+50         """执行HTTP请求"""
+51           url = f"{self.API_BASE_URL}{endpoint}"        # 构造完整的URL
+52           headers = {"Content-Type": "application/json"}   # 基础请求头
+53
+54
+55       # 如果提供了token,添加到headers信息头中
+56           if token:
+57               print(token)
+58               headers["bz-dt"] = f"{token}"
+59
+60           try:
+61         # 根据方法类型发出请求
+62              if method.upper() == "GET":
+63                   response = requests.get(url, headers=headers)
+64               elif method.upper() == "POST":
+65                   response = requests.post(url, headers=headers, json=body)
+66               elif method.upper() == "PUT":
+67                   response = requests.put(url, headers=headers, json=body)
+68               else:
+69                   raise ValueError(f"Unsupported HTTP method: {method}")
+70
+71         # 检查响应头中是否有bz-dt令牌
+72              if 'bz-dt' in response.headers:
+73                   self.dt_token = response.headers['bz-dt']
+74              print(f"获取到设备令牌: {self.dt_token}")
+75
+76         # 返回JSON格式的响应体
+77               return response.json()
+78
+79           except requests.exceptions.RequestException as e:
+80             print(f"HTTP请求失败: {e}")
+
+## Page 8
+
+### 结构化抽取
+
+```
+       return {"success": False, "msg": str(e), "code": 500}
+
+  def activate_device(self) -> Optional[Dict]:
+
+```
+
+`"""` 设备激活 `"""`
+
+`timestamp = int(time.time() * 1000) #` 毫秒时间戳
+
+`#` 构造签名内容( `deviceId + pid + timestamp + productSecret` )
+
+```
+sign_content = f"{self.DEVICE_ID}{self.PRODUCT_ID}{timestamp}
+
+{self.PRODUCT_SECRET}"
+
+```
+
+`#` 生成 `MD5` 签名
+
+```
+sign = self._generate_md5_signature(sign_content)
+
+request_body = {
+
+       "deviceId": self.DEVICE_ID,
+
+       "pid": self.PRODUCT_ID,
+
+       "sign": sign,
+
+       "timeStamp": timestamp,
+
+       "signMethod": "MD5"
+
+}
+
+```
+
+`#` 发送请求
+
+```
+response = self._perform_http_request("/dev/auth/active", "PUT",
+
+request_body)
+
+     if response.get("success"):
+```
+
+`print("` 设备激活成功 `")`
+
+`#` 返回密码和 `nonce` (需解密后使用)
+
+```
+       return {
+
+         "password": response["data"]["password"],
+
+         "nonce": response["data"]["nonce"]
+
+}
+
+     else:
+
+```
+
+`print(f"` 设备激活失败 `: {response.get('msg', '` 未知错误 `')}")`
+
+```
+       return None
+
+  def login_device(self, password: str, nonce: str) -> Optional[Dict]:
+
+```
+
+`"""` 设备登录 `"""`
+
+`#` 注意:这里 `password` 应该是加密后的,根据实际需求实现加密逻辑
+
+```
+request_body = {
+
+       "deviceId": self.DEVICE_ID,
+
+       "password": password,
+
+       "nonce": nonce
+
+}
+
+response = self._perform_http_request("/dev/auth/sign_in", "POST",
+
+request_body)
+
+```
+
+### 原始逐行文本重排
+
+81               return {"success": False, "msg": str(e), "code": 500}
+ 82
+ 83       def activate_device(self) -> Optional[Dict]:
+ 84        """设备激活"""
+ 85           timestamp = int(time.time() * 1000) # 毫秒时间戳
+ 86
+ 87       # 构造签名内容(deviceId + pid + timestamp + productSecret)
+ 88           sign_content = f"{self.DEVICE_ID}{self.PRODUCT_ID}{timestamp}
+      {self.PRODUCT_SECRET}"
+ 89       # 生成MD5签名
+ 90           sign = self._generate_md5_signature(sign_content)
+ 91
+ 92       # 构建请求体
+ 93           request_body = {
+ 94               "deviceId": self.DEVICE_ID,
+ 95               "pid": self.PRODUCT_ID,
+ 96               "sign": sign,
+ 97               "timeStamp": timestamp,
+ 98               "signMethod": "MD5"
+ 99          }
+100
+101       # 发送请求
+102           response = self._perform_http_request("/dev/auth/active", "PUT",
+      request_body)
+103
+104           if response.get("success"):
+105           print("设备激活成功")
+106         # 返回密码和nonce(需解密后使用)
+107               return {
+108                   "password": response["data"]["password"],
+109                   "nonce": response["data"]["nonce"]
+110              }
+111           else:
+112           print(f"设备激活失败: {response.get('msg', '未知错误')}")
+113               return None
+114
+115       def login_device(self, password: str, nonce: str) -> Optional[Dict]:
+116        """设备登录"""
+117       # 注意:这里password应该是加密后的,根据实际需求实现加密逻辑
+118           request_body = {
+119               "deviceId": self.DEVICE_ID,
+120               "password": password,
+121               "nonce": nonce
+122          }
+123
+124           response = self._perform_http_request("/dev/auth/sign_in", "POST",
+      request_body)
+
+## Page 9
+
+### 结构化抽取
+
+```
+     if response.get("success"):
+```
+
+`print("` 设备登录成功 `")`
+
+`print("` 设备登录数据 `:", request_body)`
+
+```
+       return response["data"]
+
+     else:
+
+```
+
+`print(f"` 设备登录失败 `: {response.get('msg', '` 未知错误 `')}")`
+
+```
+       return None
+
+  def check_device_token(self) -> Optional[Dict]:
+
+response = self._perform_http_request("/dev/auth/token", "GET",
+
+token=self.dt_token)
+
+     if response.get("success"):
+```
+
+`print("` 设备令牌有效 `")`
+
+```
+       return response["data"]
+
+     else:
+
+```
+
+`print(f"` 设备令牌无效 `: {response.get('msg', '` 未知错误 `')}")`
+
+```
+       return None
+
+  def run_auth_flow(self):
+
+```
+
+`# 1.` 激活设备
+
+```
+activation_result = self.activate_device()
+
+     if not activation_result:
+
+       return False
+
+```
+
+`# 2.` 使用激活返回的密码和 `nonce` 登录
+
+```
+login_result = self.login_device(
+
+activation_result["password"],
+
+activation_result["nonce"]
+
+)
+
+     if not login_result:
+
+       return False
+
+token_check = self.check_device_token()
+
+     if not token_check:
+
+       return False
+
+```
+
+`#` 此时设备已获得授权 `(dt)` ,可以用于后续操作
+
+`print("` 授权流程完成,设备令牌 `:", self.dt_token)`
+
+```
+     return True
+
+if __name__ == "__main__":
+
+auth = DeviceAuth()
+
+```
+
+### 原始逐行文本重排
+
+125
+126           if response.get("success"):
+127           print("设备登录成功")
+128            print("设备登录数据:", request_body)
+129               return response["data"]
+130           else:
+131           print(f"设备登录失败: {response.get('msg', '未知错误')}")
+132               return None
+133
+134       def check_device_token(self) -> Optional[Dict]:
+135        """检查设备令牌"""
+136           response = self._perform_http_request("/dev/auth/token", "GET",
+      token=self.dt_token)
+137
+138           if response.get("success"):
+139           print("设备令牌有效")
+140               return response["data"]
+141           else:
+142           print(f"设备令牌无效: {response.get('msg', '未知错误')}")
+143               return None
+144
+145       def run_auth_flow(self):
+146       """执行完整的授权流程"""
+147       # 1. 激活设备
+148           activation_result = self.activate_device()
+149           if not activation_result:
+150               return False
+151
+152       # 2. 使用激活返回的密码和nonce登录
+153           login_result = self.login_device(
+154               activation_result["password"],
+155               activation_result["nonce"]
+156          )
+157           if not login_result:
+158               return False
+159
+160       # 3. 检查设备令牌
+161           token_check = self.check_device_token()
+162           if not token_check:
+163               return False
+164
+165       # 此时设备已获得授权(dt),可以用于后续操作
+166        print("授权流程完成,设备令牌:", self.dt_token)
+167           return True
+168
+169   if __name__ == "__main__":
+170       auth = DeviceAuth()
+
+## Page 10
+
+### 结构化抽取
+
+```
+
+### 角色
+
+  if auth.run_auth_flow():
+
+```
+
+`print("` 授权成功! `")`
+
+```
+  else:
+
+```
+
+`print("` 授权失败! `")`
+
+#### 角色列表
+
+|接口名称|角色列表获取|
+|---|---|
+|业务说明|获取角色列表,需要携带设备ID获取,由设备ID角色产品,由产品决定可以看到哪些角色|
+|请求路径|/bot/bot/list/{page}|
+|请求方法|GET|
+|请求参数|•<br>path<br>◦<br>page 页码<br>•<br>query<br>◦<br>deviceId 设备ID|
+
+##### 响应结果  • 获取列表成功
+
+```
+{
+
+  "success":,
+```
+
+`"msg": "` 获取角色列表成功 `.",`
+
+```
+  "code": 50000,
+
+  "data": {
+
+     "list": [
+
+{
+
+```
+
+`"userName": "` 创建者的名称 `",`
+
+`"avatar": "` 创建者的头像 `",`
+
+```
+         "voiceName": "voiceName",
+```
+
+`"styleName": "` 风格名称 `",`
+
+`"id": "` 角色 `ID",`
+
+`"name": "` 智体名称 `",`
+
+`"sysPrompt": "` 系统提示词 `",`
+
+`"userId": "` 创建者 `ID` ,用户 `ID` ,系统创建则没有 `",`
+
+### 原始逐行文本重排
+
+171       if auth.run_auth_flow():
+  172         print("授权成功!")
+  173       else:
+  174         print("授权失败!")
+
+        go_dmp_device_auth_demo.zip
+           98.52KB
+
+角色
+
+角色列表
+
+ 接口名称     角色列表获取
+
+ 业务说明    获取角色列表,需要携带设备ID获取,由设备ID角色产品,由产品决定可以看到哪些角色
+
+ 请求路径         /bot/bot/list/{page}
+
+ 请求方法        GET
+
+ 请求参数         •  path
+                      ◦  page 页码
+                   •  query
+                      ◦  deviceId 设备ID
+
+ 响应结果         • 获取列表成功
+
+```
+{
+"success": false,
+"msg": "获取角色列表成功.",
+"code": 50000,
+"data": {
+"list": [
+{
+"userName": "创建者的名称",
+"avatar": "创建者的头像",
+"voiceName": "voiceName",
+"styleName": "风格名称",
+"id": "角色ID",
+"name": "智体名称",
+"sysPrompt": "系统提示词",
+"userId": "创建者ID,用户ID,系统创建则没有",
+```
+
+## Page 11
+
+### 结构化抽取
+
+`"voiceId": "` 音色 `ID",`
+
+`"gender": "0` 是女, `1` 是男 `",`
+
+`"cover": "` 封面 `",`
+
+`"description": "` 简介 `",`
+
+`"sayHello": "` 开场白 `",`
+
+`"styleId": "` 风格 `ID",`
+
+`"isJson": "` 是否启用 `json` 配置: `0.` 否 `1.` 是 `",`
+
+`"jsonStr": "` 自定义扩展 `json",`
+
+`"companyId": "` 公司 `ID",`
+
+`"createTime": "` 创建时间 `"`
+
+```
+}
+
+],
+
+     "total": 2,
+
+     "pageSize": 30,
+
+     "currentPage": 1,
+
+     "hasNext":,
+
+     "hasPre":,
+
+     "totalPage": 1
+
+}
+
+}
+
+```
+
+|接口名称|获取音色列表|
+|---|---|
+|请求路径|/bot/bot~~-~~voice/list|
+|请求方法|GET|
+|请求参数|•<br>query<br>◦<br>category: 分类,所有填空字符串<br>▪<br>platform:平台类型,volcengine<br>◦<br>searchText:搜索内容|
+
+##### 响应结果  • 获取角色列表成功
+
+```
+{
+
+ "success": true,
+```
+
+`"msg": "` 获取音色列表成功 `.",`
+
+```
+ "code": 20000,
+
+ "data": [
+
+{
+
+```
+
+### 原始逐行文本重排
+
+16                   "voiceId": "音色ID",
+                  17                   "gender": "0是女,1是男",
+                  18                   "cover": "封面",
+                  19                   "description": "简介",
+                  20                   "sayHello": "开场白",
+                  21                   "styleId": "风格ID",
+                  22                   "isJson": "是否启用json配置:0.否 1.是",
+                  23                   "jsonStr": "自定义扩展json",
+                  24                   "companyId": "公司ID",
+                  25                   "createTime": "创建时间"
+                  26              }
+                  27           ],
+                  28           "total": 2,
+                  29           "pageSize": 30,
+                  30           "currentPage": 1,
+                  31           "hasNext": false,
+                  32           "hasPre": false,
+                  33           "totalPage": 1
+                  34      }
+                  35   }
+
+获取音色列表
+
+ 接口名称     获取音色列表
+
+ 请求路径         /bot/bot-voice/list
+
+ 请求方法        GET
+
+ 请求参数         •  query
+                      ◦  category: 分类,所有填空字符串
+                          ▪  platform:平台类型,volcengine
+                      ◦  searchText:搜索内容
+
+ 响应结果         • 获取角色列表成功
+
+```
+{
+"success": true,
+"msg": "获取音色列表成功.",
+"code": 20000,
+"data": [
+{
+```
+
+## Page 12
+
+### 结构化抽取
+
+```
+   "id": "1993559126688346114",
+```
+
+`"name": "` 咪仔(多情绪) `",`
+
+```
+   "voiceId": "zh_female_mizai_saturn_bigtts",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 女声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "",
+
+   "avatar": "https://u
+oss.thisiot.com/images/2025_11_26/1993559120230449154.png",
+
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/zh_female_m
+
+izai_saturn_bigtts.wav",
+
+   "createTime": "2025-11-26 13:55",
+
+   "updateTime": "2025-11-26 13:55"
+
+},
+
+{
+
+   "id": "1993547204098207746",
+```
+
+`"name": "` 魅力女友 `(` 多情绪) `",`
+
+```
+   "voiceId": "zh_female_meilinvyou_saturn_bigtts",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 女声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "",
+
+   "avatar": "https://u
+oss.thisiot.com/images/2025_11_26/1993546901530836993.png",
+
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/zh_female_m
+
+eilinvyou_saturn_bigtts.wav",
+
+   "createTime": "2025-11-26 13:07",
+
+   "updateTime": "2025-11-26 13:07"
+
+},
+
+{
+
+   "id": "1990606609449349121",
+```
+
+`"name": "vivi` (多情绪) `",`
+
+```
+   "voiceId": "zh_female_vv_uranus_bigtts",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 推荐 `,` 女声 `",`
+
+```
+   "vip": "0",
+
+   "language": "",
+
+```
+
+### 原始逐行文本重排
+
+7         "id": "1993559126688346114",
+ 8         "name": "咪仔(多情绪)",
+ 9         "voiceId": "zh_female_mizai_saturn_bigtts",
+10         "gender": "0",
+11         "labels": null,
+12         "platform": "volcengine",
+13         "category": "女声,推荐",
+14         "vip": "0",
+15         "language": "",
+16         "avatar": "https://u-
+     oss.thisiot.com/images/2025_11_26/1993559120230449154.png",
+17         "trialUrl": "https://lf3-
+     static.bytednsdoc.com/obj/eden-
+     cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/zh_female_m
+     izai_saturn_bigtts.wav",
+18         "createTime": "2025-11-26 13:55",
+19         "updateTime": "2025-11-26 13:55"
+20       },
+21      {
+22         "id": "1993547204098207746",
+23         "name": "魅力女友(多情绪)",
+24         "voiceId": "zh_female_meilinvyou_saturn_bigtts",
+25         "gender": "0",
+26         "labels": null,
+27         "platform": "volcengine",
+28         "category": "女声,推荐",
+29         "vip": "0",
+30         "language": "",
+31         "avatar": "https://u-
+     oss.thisiot.com/images/2025_11_26/1993546901530836993.png",
+32         "trialUrl": "https://lf3-
+     static.bytednsdoc.com/obj/eden-
+     cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/zh_female_m
+     eilinvyou_saturn_bigtts.wav",
+33         "createTime": "2025-11-26 13:07",
+34         "updateTime": "2025-11-26 13:07"
+35       },
+36      {
+37         "id": "1990606609449349121",
+38         "name": "vivi(多情绪)",
+39         "voiceId": "zh_female_vv_uranus_bigtts",
+40         "gender": "0",
+41         "labels": null,
+42         "platform": "volcengine",
+43         "category": "推荐,女声",
+44         "vip": "0",
+45         "language": "",
+
+## Page 13
+
+### 结构化抽取
+
+```
+   "avatar": "https://u
+oss.thisiot.com/images/2025_11_18/1990606225348460546.png",
+
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/zh_female_v
+
+v1_mars_bigtts.mp3",
+
+   "createTime": "2025-11-18 10:22",
+
+   "updateTime": "2025-11-18 10:22"
+
+},
+
+{
+
+   "id": "1920762281130500098",
+```
+
+`"name": "` 性感御姐 `",`
+
+```
+   "voiceId": "ICL_zh_female_xingganyujie_tob",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 女声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": null,
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 性感
+
+御姐 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/ICL_zh_fem
+
+ale_xingganyujie_tob.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762281277300738",
+```
+
+`"name": "` 懒音绵宝 `",`
+
+```
+   "voiceId": "zh_male_lanxiaoyang_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 男声 `,` 童声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 懒音
+
+绵宝 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_la
+
+nxiaoyang_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+```
+
+### 原始逐行文本重排
+
+46         "avatar": "https://u-
+     oss.thisiot.com/images/2025_11_18/1990606225348460546.png",
+47         "trialUrl": "https://lf3-
+     static.bytednsdoc.com/obj/eden-
+     cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/zh_female_v
+     v1_mars_bigtts.mp3",
+48         "createTime": "2025-11-18 10:22",
+49         "updateTime": "2025-11-18 10:22"
+50       },
+51      {
+52         "id": "1920762281130500098",
+53         "name": "性感御姐",
+54         "voiceId": "ICL_zh_female_xingganyujie_tob",
+55         "gender": "0",
+56         "labels": null,
+57         "platform": "volcengine",
+58         "category": "女声,推荐",
+59         "vip": "0",
+60         "language": null,
+61         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+     cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/性感
+    御姐.png",
+62         "trialUrl": "https://lf3-
+     static.bytednsdoc.com/obj/eden-
+     cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/ICL_zh_fem
+     ale_xingganyujie_tob.mp3",
+63         "createTime": "2025-05-09 16:46",
+64         "updateTime": "2025-05-09 16:46"
+65       },
+66      {
+67         "id": "1920762281277300738",
+68         "name": "懒音绵宝",
+69         "voiceId": "zh_male_lanxiaoyang_mars_bigtts",
+70         "gender": "1",
+71         "labels": null,
+72         "platform": "volcengine",
+73         "category": "男声,童声,推荐",
+74         "vip": "0",
+75         "language": "cn",
+76         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+     cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/懒音
+    绵宝.png",
+77         "trialUrl": "https://lf3-
+     static.bytednsdoc.com/obj/eden-
+     cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_la
+     nxiaoyang_mars_bigtts.mp3",
+78         "createTime": "2025-05-09 16:46",
+
+## Page 14
+
+### 结构化抽取
+
+```
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762281340215298",
+```
+
+`"name": "` 亮嗓萌仔 `",`
+
+```
+   "voiceId": "zh_male_dongmanhaimian_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 男声 `,` 童声 `,` 推荐 `,` 趣味口音 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 亮嗓
+
+萌仔 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_do
+
+ngmanhaimian_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762278223847426",
+```
+
+`"name": "` 湾湾小何 `",`
+
+```
+   "voiceId": "zh_female_wanwanxiaohe_moon_bigtts",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 推荐 `,` 趣味口音 `,` 女声 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 湾湾
+
+小何 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/` 湾湾小
+
+何 `.mp3",`
+
+```
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762278316122113",
+```
+
+`"name": "` 广州德哥 `",`
+
+```
+   "voiceId": "zh_male_guozhoudege_moon_bigtts",
+
+   "gender": "1",
+
+```
+
+### 原始逐行文本重排
+
+79         "updateTime": "2025-05-09 16:46"
+ 80       },
+ 81      {
+ 82         "id": "1920762281340215298",
+ 83         "name": "亮嗓萌仔",
+ 84         "voiceId": "zh_male_dongmanhaimian_mars_bigtts",
+ 85         "gender": "1",
+ 86         "labels": null,
+ 87         "platform": "volcengine",
+ 88         "category": "男声,童声,推荐,趣味口音",
+ 89         "vip": "0",
+ 90         "language": "cn",
+ 91         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/亮嗓
+     萌仔.png",
+ 92         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_do
+      ngmanhaimian_mars_bigtts.mp3",
+ 93         "createTime": "2025-05-09 16:46",
+ 94         "updateTime": "2025-05-09 16:46"
+ 95       },
+ 96      {
+ 97         "id": "1920762278223847426",
+ 98         "name": "湾湾小何",
+ 99         "voiceId": "zh_female_wanwanxiaohe_moon_bigtts",
+100         "gender": "0",
+101         "labels": null,
+102         "platform": "volcengine",
+103         "category": "推荐,趣味口音,女声",
+104         "vip": "0",
+105         "language": "cn",
+106         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/湾湾
+     小何.png",
+107         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/湾湾小
+     何.mp3",
+108         "createTime": "2025-05-09 16:46",
+109         "updateTime": "2025-05-09 16:46"
+110       },
+111      {
+112         "id": "1920762278316122113",
+113         "name": "广州德哥",
+114         "voiceId": "zh_male_guozhoudege_moon_bigtts",
+115         "gender": "1",
+
+## Page 15
+
+### 结构化抽取
+
+```
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 趣味口音 `,` 推荐 `,` 男声 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 广州
+
+德哥 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/` 广州德
+
+哥 `.mp3",`
+
+```
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762278345482241",
+```
+
+`"name": "` 北京小爷 `",`
+
+```
+   "voiceId": "zh_male_beijingxiaoye_moon_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 趣味口音 `,` 男声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 北京
+
+小爷 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/` 北京小
+
+爷 `.mp3",`
+
+```
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762278374842369",
+
+```
+
+`"name": "` 浩宇小哥 `",`
+
+```
+   "voiceId": "zh_male_haoyuxiaoge_moon_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 趣味口音 `,` 推荐 `,` 男声 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 浩宇
+
+### 原始逐行文本重排
+
+116         "labels": null,
+117         "platform": "volcengine",
+118         "category": "趣味口音,推荐,男声",
+119         "vip": "0",
+120         "language": "cn",
+121         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/广州
+     德哥.png",
+122         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/广州德
+     哥.mp3",
+123         "createTime": "2025-05-09 16:46",
+124         "updateTime": "2025-05-09 16:46"
+125       },
+126      {
+127         "id": "1920762278345482241",
+128         "name": "北京小爷",
+129         "voiceId": "zh_male_beijingxiaoye_moon_bigtts",
+130         "gender": "1",
+131         "labels": null,
+132         "platform": "volcengine",
+133         "category": "趣味口音,男声,推荐",
+134         "vip": "0",
+135         "language": "cn",
+136         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/北京
+     小爷.png",
+137         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/北京小
+     爷.mp3",
+138         "createTime": "2025-05-09 16:46",
+139         "updateTime": "2025-05-09 16:46"
+140       },
+141      {
+142         "id": "1920762278374842369",
+143         "name": "浩宇小哥",
+144         "voiceId": "zh_male_haoyuxiaoge_moon_bigtts",
+145         "gender": "1",
+146         "labels": null,
+147         "platform": "volcengine",
+148         "category": "趣味口音,推荐,男声",
+149         "vip": "0",
+150         "language": "cn",
+151         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/浩宇
+
+## Page 16
+
+### 结构化抽取
+
+小哥 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/` 浩宇小
+
+哥 `.mp3",`
+
+```
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762278425174018",
+```
+
+`"name": "` 广西远舟 `",`
+
+```
+   "voiceId": "zh_male_guangxiyuanzhou_moon_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 趣味口音 `,` 男声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 广西
+
+远舟 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/` 广西远
+
+舟 `.mp3",`
+
+```
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762278521643009",
+```
+
+`"name": "` 豫州子轩 `",`
+
+```
+   "voiceId": "zh_male_yuzhouzixuan_moon_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 趣味口音 `,` 男声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 豫州
+
+子轩 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/` 豫州子
+
+轩 `.mp3",`
+
+```
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+```
+
+### 原始逐行文本重排
+
+小哥.png",
+152         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/浩宇小
+     哥.mp3",
+153         "createTime": "2025-05-09 16:46",
+154         "updateTime": "2025-05-09 16:46"
+155       },
+156      {
+157         "id": "1920762278425174018",
+158         "name": "广西远舟",
+159         "voiceId": "zh_male_guangxiyuanzhou_moon_bigtts",
+160         "gender": "1",
+161         "labels": null,
+162         "platform": "volcengine",
+163         "category": "趣味口音,男声,推荐",
+164         "vip": "0",
+165         "language": "cn",
+166         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/广西
+     远舟.png",
+167         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/广西远
+     舟.mp3",
+168         "createTime": "2025-05-09 16:46",
+169         "updateTime": "2025-05-09 16:46"
+170       },
+171      {
+172         "id": "1920762278521643009",
+173         "name": "豫州子轩",
+174         "voiceId": "zh_male_yuzhouzixuan_moon_bigtts",
+175         "gender": "1",
+176         "labels": null,
+177         "platform": "volcengine",
+178         "category": "趣味口音,男声,推荐",
+179         "vip": "0",
+180         "language": "cn",
+181         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/豫州
+     子轩.png",
+182         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/豫州子
+     轩.mp3",
+183         "createTime": "2025-05-09 16:46",
+184         "updateTime": "2025-05-09 16:46"
+
+## Page 17
+
+### 结构化抽取
+
+```
+},
+
+{
+
+   "id": "1920762279800905730",
+```
+
+`"name": "` 天才童声 `",`
+
+```
+   "voiceId": "zh_male_tiancaitongsheng_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 童声 `,` 趣味口音 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 天才
+
+童声 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_ti
+
+ancaitongsheng_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762279821877250",
+```
+
+`"name": "` 奶气萌娃 `",`
+
+```
+   "voiceId": "zh_male_naiqimengwa_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 男声 `,` 趣味口音 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 奶气
+
+萌娃 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_na
+
+iqimengwa_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762279847043073",
+
+```
+
+`"name": "` 猴哥 `",`
+
+```
+   "voiceId": "zh_male_sunwukong_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+```
+
+### 原始逐行文本重排
+
+185       },
+186      {
+187         "id": "1920762279800905730",
+188         "name": "天才童声",
+189         "voiceId": "zh_male_tiancaitongsheng_mars_bigtts",
+190         "gender": "1",
+191         "labels": null,
+192         "platform": "volcengine",
+193         "category": "童声,趣味口音,推荐",
+194         "vip": "0",
+195         "language": "cn",
+196         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/天才
+     童声.png",
+197         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_ti
+      ancaitongsheng_mars_bigtts.mp3",
+198         "createTime": "2025-05-09 16:46",
+199         "updateTime": "2025-05-09 16:46"
+200       },
+201      {
+202         "id": "1920762279821877250",
+203         "name": "奶气萌娃",
+204         "voiceId": "zh_male_naiqimengwa_mars_bigtts",
+205         "gender": "1",
+206         "labels": null,
+207         "platform": "volcengine",
+208         "category": "男声,趣味口音,推荐",
+209         "vip": "0",
+210         "language": "cn",
+211         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/奶气
+     萌娃.png",
+212         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_na
+      iqimengwa_mars_bigtts.mp3",
+213         "createTime": "2025-05-09 16:46",
+214         "updateTime": "2025-05-09 16:46"
+215       },
+216      {
+217         "id": "1920762279847043073",
+218         "name": "猴哥",
+219         "voiceId": "zh_male_sunwukong_mars_bigtts",
+220         "gender": "1",
+221         "labels": null,
+
+## Page 18
+
+### 结构化抽取
+
+```
+   "platform": "volcengine",
+```
+
+`"category": "` 推荐 `,` 趣味口音 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 猴
+
+哥 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_su
+
+nwukong_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762279863820290",
+```
+
+`"name": "` 熊二 `",`
+
+```
+   "voiceId": "zh_male_xionger_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 推荐 `,` 趣味口音 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 熊
+
+二 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_xi
+
+onger_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762279901569025",
+```
+
+`"name": "` 佩奇猪 `",`
+
+```
+   "voiceId": "zh_female_peiqi_mars_bigtts",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 童声 `,` 趣味口音 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 佩奇
+
+猪 `.png",`
+
+### 原始逐行文本重排
+
+222         "platform": "volcengine",
+223         "category": "推荐,趣味口音",
+224         "vip": "0",
+225         "language": "cn",
+226         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/猴
+     哥.png",
+227         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_su
+      nwukong_mars_bigtts.mp3",
+228         "createTime": "2025-05-09 16:46",
+229         "updateTime": "2025-05-09 16:46"
+230       },
+231      {
+232         "id": "1920762279863820290",
+233         "name": "熊二",
+234         "voiceId": "zh_male_xionger_mars_bigtts",
+235         "gender": "1",
+236         "labels": null,
+237         "platform": "volcengine",
+238         "category": "推荐,趣味口音",
+239         "vip": "0",
+240         "language": "cn",
+241         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/熊
+     二.png",
+242         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_xi
+      onger_mars_bigtts.mp3",
+243         "createTime": "2025-05-09 16:46",
+244         "updateTime": "2025-05-09 16:46"
+245       },
+246      {
+247         "id": "1920762279901569025",
+248         "name": "佩奇猪",
+249         "voiceId": "zh_female_peiqi_mars_bigtts",
+250         "gender": "0",
+251         "labels": null,
+252         "platform": "volcengine",
+253         "category": "童声,趣味口音,推荐",
+254         "vip": "0",
+255         "language": "cn",
+256         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/佩奇
+     猪.png",
+
+## Page 19
+
+### 结构化抽取
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_female_
+
+peiqi_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762280027398146",
+```
+
+`"name": "` 四郎 `",`
+
+```
+   "voiceId": "zh_male_silang_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 推荐 `,` 男声 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden
+```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 四
+
+郎 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_si
+
+lang_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762280060952578",
+```
+
+`"name": "` 樱桃丸子 `",`
+
+```
+   "voiceId": "zh_female_yingtaowanzi_mars_bigtts",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 女声 `,` 童声 `,` 趣味口音 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 樱桃
+
+丸子 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_female_
+
+yingtaowanzi_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+```
+
+### 原始逐行文本重排
+
+257         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_female_
+      peiqi_mars_bigtts.mp3",
+258         "createTime": "2025-05-09 16:46",
+259         "updateTime": "2025-05-09 16:46"
+260       },
+261      {
+262         "id": "1920762280027398146",
+263         "name": "四郎",
+264         "voiceId": "zh_male_silang_mars_bigtts",
+265         "gender": "1",
+266         "labels": null,
+267         "platform": "volcengine",
+268         "category": "推荐,男声",
+269         "vip": "0",
+270         "language": "cn",
+271         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/四
+     郎.png",
+272         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_si
+      lang_mars_bigtts.mp3",
+273         "createTime": "2025-05-09 16:46",
+274         "updateTime": "2025-05-09 16:46"
+275       },
+276      {
+277         "id": "1920762280060952578",
+278         "name": "樱桃丸子",
+279         "voiceId": "zh_female_yingtaowanzi_mars_bigtts",
+280         "gender": "0",
+281         "labels": null,
+282         "platform": "volcengine",
+283         "category": "女声,童声,趣味口音,推荐",
+284         "vip": "0",
+285         "language": "cn",
+286         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/樱桃
+     丸子.png",
+287         "trialUrl": "https://lf3-
+      static.bytednsdoc.com/obj/eden-
+      cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_female_
+      yingtaowanzi_mars_bigtts.mp3",
+288         "createTime": "2025-05-09 16:46",
+289         "updateTime": "2025-05-09 16:46"
+290       },
+
+## Page 20
+
+### 结构化抽取
+
+```
+{
+
+   "id": "1920762280090312706",
+```
+
+`"name": "` 磁性解说男声 `",`
+
+```
+   "voiceId": "zh_male_jieshuonansheng_mars_bigtts",
+
+   "gender": "1",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 男声 `,` 推荐 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 磁性
+
+解说男声 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_ji
+
+eshuonansheng_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+},
+
+{
+
+   "id": "1920762280111284225",
+```
+
+`"name": "` 鸡汤妹妹 `",`
+
+```
+   "voiceId": "zh_female_jitangmeimei_mars_bigtts",
+
+   "gender": "0",
+
+   "labels": null,
+
+   "platform": "volcengine",
+```
+
+`"category": "` 推荐 `,` 女声 `",`
+
+```
+   "vip": "0",
+
+   "language": "cn",
+
+   "avatar": "https://lf3-static.bytednsdoc.com/obj/eden```
+
+`cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/` 鸡汤
+
+妹妹 `.png",`
+
+```
+   "trialUrl": "https://lf3
+static.bytednsdoc.com/obj/eden
+cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_female_
+
+jitangmeimei_mars_bigtts.mp3",
+
+   "createTime": "2025-05-09 16:46",
+
+   "updateTime": "2025-05-09 16:46"
+
+}
+
+]
+
+}
+
+```
+
+### 原始逐行文本重排
+
+291      {
+                 292         "id": "1920762280090312706",
+                 293         "name": "磁性解说男声",
+                 294         "voiceId": "zh_male_jieshuonansheng_mars_bigtts",
+                 295         "gender": "1",
+                 296         "labels": null,
+                 297         "platform": "volcengine",
+                 298         "category": "男声,推荐",
+                 299         "vip": "0",
+                 300         "language": "cn",
+                 301         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+                       cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/磁性
+                  解说男声.png",
+                 302         "trialUrl": "https://lf3-
+                       static.bytednsdoc.com/obj/eden-
+                       cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_male_ji
+                       eshuonansheng_mars_bigtts.mp3",
+                 303         "createTime": "2025-05-09 16:46",
+                 304         "updateTime": "2025-05-09 16:46"
+                 305       },
+                 306      {
+                 307         "id": "1920762280111284225",
+                 308         "name": "鸡汤妹妹",
+                 309         "voiceId": "zh_female_jitangmeimei_mars_bigtts",
+                 310         "gender": "0",
+                 311         "labels": null,
+                 312         "platform": "volcengine",
+                 313         "category": "推荐,女声",
+                 314         "vip": "0",
+                 315         "language": "cn",
+                 316         "avatar": "https://lf3-static.bytednsdoc.com/obj/eden-
+                       cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/portal/bigtts/avatar/鸡汤
+                   妹妹.png",
+                 317         "trialUrl": "https://lf3-
+                       static.bytednsdoc.com/obj/eden-
+                       cn/lm_hz_ihsph/ljhwZthlaukjlkulzlp/console/bigtts/zh_female_
+                       jitangmeimei_mars_bigtts.mp3",
+                 318         "createTime": "2025-05-09 16:46",
+                 319         "updateTime": "2025-05-09 16:46"
+                 320      }
+                 321     ]
+                 322   }
+
+更新设备角色音色
+
+## Page 21
+
+### 结构化抽取
+
+|接口名称|更新设备角色音色|
+|---|---|
+|请求路径|/dev/device/dev~~-~~bot|
+|请求方法|PUT|
+|请求参数|•<br>query<br>◦<br>deviceId:设备ID <br>◦<br>botId:角色ID<br>◦<br>speakerId:音色ID,非必填,不填会使用角色默认音色<br>◦<br>longTermMemory:长期记忆,非必填|
+
+##### 响应结果  • 设备与角色关联成功
+
+```
+{
+
+"success": true,
+```
+
+`"msg": "` 设备与角色关联成功 `.",`
+
+```
+"code": 20000,
+
+"data": {
+
+"id": "1991681340612751361",
+
+          ```
+
+`"name": "` 测试 魅魔 `",`
+
+`"sysPrompt": "` 魅魔。 `",`
+
+```
+"userId": null,
+
+"deviceId": null,
+
+"voiceId": "1990606609449349121",
+
+"isJson": "1",
+
+"jsonStr": "
+```
+
+`{\"agent_id\":\"7462617881076351002\",\"agent_name\":\"` 魅魔
+
+`\",\"welcome_message\":\"` 你来了。 `\",\"system_prompt\":`
+
+`{\"type\":\"text\",\"content\":\"` 魅魔。 `\"},\"voice_config\":`
+
+```
+{\"provider\":\"volcengine\",\"options\":{\"volcengine\":
+
+{\"voice_id\":\"saturn_zh_female_keainvsheng_tob\",\"voice_n
+```
+
+`ame\":\"` 可爱女生
+
+```
+2.0\",\"voice_source\":\"system\"}}},\"model_config\":
+
+{\"provider\":\"dify\",\"options\":{\"dify\":
+
+{\"base_url\":\"http://13.229.120.241/v1\",\"bot_id\":\"app
+NpBLaXjsNqYyfFnR5bqrDBDO\",\"files\":[]}}},\"asr_config\":
+
+{\n  \"provider\": \"\",\n  \"interrupt_options\":
+
+{},\n  \"cfg\": {}\n },\"created_at\":\"0001-01
+01T00:00:00Z\",\"updated_at\":\"0001-01-01T00:00:00Z\"}",
+```
+
+`"language": "` 中文 `",`
+
+```
+"vip": "0",
+
+"voiceProvider": "volcengine",
+
+"modelProvider": "dify",
+
+```
+
+### 原始逐行文本重排
+
+接口名称     更新设备角色音色
+
+请求路径         /dev/device/dev-bot
+
+请求方法        PUT
+
+请求参数         •  query
+                     ◦  deviceId:设备ID
+                     ◦  botId:角色ID
+                     ◦ speakerId:音色ID,非必填,不填会使用角色默认音色
+                     ◦ longTermMemory:长期记忆,非必填
+
+响应结果         • 设备与角色关联成功
+
+```
+{
+"success": true,
+"msg": "设备与角色关联成功.",
+"code": 20000,
+"data": {
+"id": "1991681340612751361",
+"name": " 测试-魅魔",
+"sysPrompt": "魅魔。",
+"userId": null,
+"deviceId": null,
+"voiceId": "1990606609449349121",
+"isJson": "1",
+"jsonStr": "
+{\"agent_id\":\"7462617881076351002\",\"agent_name\":\"魅魔
+\",\"welcome_message\":\"你来了。\",\"system_prompt\":
+{\"type\":\"text\",\"content\":\"魅魔。\"},\"voice_config\":
+{\"provider\":\"volcengine\",\"options\":{\"volcengine\":
+{\"voice_id\":\"saturn_zh_female_keainvsheng_tob\",\"voice_n
+ame\":\"可爱女生
+2.0\",\"voice_source\":\"system\"}}},\"model_config\":
+{\"provider\":\"dify\",\"options\":{\"dify\":
+{\"base_url\":\"http://13.229.120.241/v1\",\"bot_id\":\"app-
+NpBLaXjsNqYyfFnR5bqrDBDO\",\"files\":[]}}},\"asr_config\":
+{\n    \"provider\": \"\",\n    \"interrupt_options\":
+{},\n    \"cfg\": {}\n  },\"created_at\":\"0001-01-
+01T00:00:00Z\",\"updated_at\":\"0001-01-01T00:00:00Z\"}",
+"language": "中文",
+"vip": "0",
+"voiceProvider": "volcengine",
+"modelProvider": "dify",
+```
+
+## Page 22
+
+### 结构化抽取
+
+```
+
+## APIKEY 授权
+
+"asrProvider": "",
+
+"gender": "0",
+
+"cover": "https://u
+oss.thisiot.com/images/2025_11_21/1991680596242563074.png",
+
+"emojiDownloadUrl": null,
+
+"crc32": null,
+
+"description": "1",
+```
+
+`"sayHello": "` 你来了。 `",`
+
+```
+"styleId": "1925437238271934465",
+
+"companyId": null,
+
+"isPrivate": "1",
+
+"isCloneVoice": "0",
+
+"createTime": "2025-11-21 09:33",
+
+"updateTime": "2025-11-21 09:33"
+
+}
+
+}
+
+```
+
+1. 申请一个固定的 API_KEY
+
+2. 开启websocket 将 API_KEY 通过 query 参数提交
+
+a. 例如: [ws://example.com/vc/chat?token=${API_KEY}](http://example.com/vc/chat?token=${API_KEY})
+
+### 授权说明
+
+### • 通过 DMP平台获取设备授权dt或者用户授权ut 通过url query参数 ?dt=xxx&ut=xxx 这种形式提交
+
+### • 通过固定apikey 授权 通过url query 参数 ?token=xxx 提交认证
+
+### 原始逐行文本重排
+
+18       "asrProvider": "",
+                  19       "gender": "0",
+                  20       "cover": "https://u-
+                       oss.thisiot.com/images/2025_11_21/1991680596242563074.png",
+                  21       "emojiDownloadUrl": null,
+                  22       "crc32": null,
+                  23       "description": "1",
+                  24       "sayHello": "你来了。",
+                  25       "styleId": "1925437238271934465",
+                  26       "companyId": null,
+                  27       "isPrivate": "1",
+                  28       "isCloneVoice": "0",
+                  29       "createTime": "2025-11-21 09:33",
+                  30       "updateTime": "2025-11-21 09:33"
+                  31     }
+                  32   }
+
+APIKEY 授权
+
+1. 申请一个固定的 API_KEY
+
+2. 开启websocket 将 API_KEY 通过 query 参数提交
+
+    a. 例如: ws://example.com/vc/chat?token=${API_KEY}
+
+语音对话
+
+授权说明
+
+ 通过 DMP平台获取设备授权dt或者用户授权ut 通过url query参数 ?dt=xxx&ut=xxx 这种形式提交•
+ 认证
+
+         授权 通过url query 参数 ?token=xxx 提交认证• 通过固定apikey
+
+时序图
+
+ 语音对话返回语音
+
+## Page 23
+
+### 结构化抽取
+
+_本页未抽取到结构化文本。_
+
+### 原始逐行文本重排
+
+文本对话返回语音
+
+## Page 24
+
+### 结构化抽取
+
+金三测试环境:ws://115.190.94.208:22080/vc/agent
+
+国内网关:[wss/ws]://amp.raisound.com/vc/agent
+
+新加坡:[wss/ws]://amp intl.mouseai.vip/vc/chat
+
+新加坡(CDN):[wss/ws]://amp xiaosu.raisound.com/vc/chat
+
+### 发送事件
+
+如果开启Vad 不需要发送 audio.create 以及 audio.completed 两个事件,当收到服务器返回
+
+started 后直接发送音频就行。
+
+如果本地没有做回音消除 可以在收到 vad.silence 事件后关闭录音。等音频播放结束后重新开启录
+
+### 原始逐行文本重排
+
+AMP网关地址
+
+测试网关
+
+  金三测试环境:ws://115.190.94.208:22080/vc/agent
+
+正式服务器
+
+  国内网关:[wss/ws]://amp.raisound.com/vc/agent
+
+  新加坡:[wss/ws]://amp-intl.mouseai.vip/vc/chat
+
+  新加坡(CDN):[wss/ws]://amp-xiaosu.raisound.com/vc/chat
+
+发送事件
+
+ 如果开启Vad 不需要发送 audio.create 以及 audio.completed 两个事件,当收到服务器返回
+  started 后直接发送音频就行。
+
+ 如果本地没有做回音消除 可以在收到 vad.silence 事件后关闭录音。等音频播放结束后重新开启录
+ 音。
+
+## Page 25
+
+### 结构化抽取
+
+|音色名称|voice|语种|
+|---|---|---|
+|妹坨洁儿|zh_female_meituojieer_moon_bigtts|中文~~-~~长沙口音|
+|湾湾小何|zh_female_wanwanxiaohe_moon_bigtts|中文~~-~~台湾口音|
+|Amanda|en_female_amanda_mars_bigtts|美式英语|
+
+#### Start 开启
+
+开启对话服务 初始化 ASR LLM TTS 服务
+
+```
+{
+
+  "event": "start",
+
+  "payload": {
+```
+
+`"device_id": "123123123", //` 设备 `ID`
+
+`"user_agent": "AudioClient/1.0", //` 浏览器 `UA`
+
+`"simple_response": true, // true` 只返回完整的 `LLM` 文本 默认 `false` 返回增量 `LLM`
+
+文本
+
+`"outbound_attributes": { // TTS` 输出音频配置
+
+```
+       "cfg": {
+
+```
+
+`"format": "pcm", //` 音频输出格式
+
+`"codec":"raw"` `// raw ogg (` 当 `format` 为 `opus` 默认使用 `ogg` 封装
+
+`codec` 使用 `raw` 为原始 `opus)`
+
+`"sample_rate": 16000, //` 音频输出采样率
+
+`"bit_rate": 16, //` 比特率
+
+`"channel": 1, //` 声道 `1` 单声道
+
+`"volume": 100, //` 音量 `0-100`
+
+`"speech_rate": 0, //` 语速 `[-50,100]` 默认 `0`
+
+`"chunk_interval_ms": 100` `//` 配置每段音频入队间隔时间 `100ms`
+
+```
+}
+
+},
+
+```
+
+`"inbound_attributes": { // ASR` 输入音频配置
+
+`"disable_vad": false, //` 开启 `vad` 自动断句 (开启后可以有客户端处理回音消
+
+除后持续发送音频由服务器判断是否转写和发送 `LLM` )
+
+`"vad_silence": 400, //` 设置 `vad` 静音阈值 (毫秒) 连续静音超过 阈值自动切
+
+```
+       "interrupt_options": {
+
+```
+
+`"concatenate_results": true, //` 是否在打断后拼接前后的 `ASR` 结果
+
+`"thinking_time_only": true` `//` 是否只在思考时间允许打断 思考时间 `(ASR`
+
+结束 `--->` 第一帧音频合成 `)`
+
+`// "keyword_interrupt": false, //` 启用打断词功能 (打断词只有在思考
+
+### 原始逐行文本重排
+
+TTS音色
+
+ 音色名称       voice                             语种
+
+ 妹坨洁儿      zh_female_meituojieer_moon_bigtts        中文-长沙口音
+
+ 湾湾小何     zh_female_wanwanxiaohe_moon_bigtts      中文-台湾口音
+
+ Amanda      en_female_amanda_mars_bigtts          美式英语
+
+Start 开启
+
+ 开启对话服务 初始化 ASR LLM TTS 服务
+
+```
+{
+"event": "start",
+"payload": {
+"device_id": "123123123", // 设备ID
+"user_agent": "AudioClient/1.0", // 浏览器 UA
+"simple_response": true, // true 只返回完整的LLM文本 默认false 返回增量LLM
+文本
+"outbound_attributes": { // TTS输出音频配置
+"cfg": {
+"format": "pcm", // 音频输出格式
+"codec":"raw" // raw ogg (当 format 为 opus 默认使用 ogg 封装
+codec使用 raw 为原始opus)
+"sample_rate": 16000, // 音频输出采样率
+"bit_rate": 16, // 比特率
+"channel": 1, // 声道 1 单声道
+"volume": 100, // 音量 0-100
+"speech_rate": 0, // 语速 [-50,100] 默认 0
+"chunk_interval_ms": 100 // 配置每段音频入队间隔时间 100ms
+}
+},
+"inbound_attributes": { // ASR输入音频配置
+"disable_vad": false, // 开启vad 自动断句 (开启后可以有客户端处理回音消
+除后持续发送音频由服务器判断是否转写和发送LLM)
+"vad_silence": 400, // 设置vad 静音阈值 (毫秒) 连续静音超过 阈值自动切
+换状态
+"interrupt_options": {
+"concatenate_results": true, // 是否在打断后拼接前后的ASR结果
+"thinking_time_only": true // 是否只在思考时间允许打断 思考时间(ASR
+结束--->第一帧音频合成)
+// "keyword_interrupt": false, // 启用打断词功能 (打断词只有在思考
+以及之后才能打断)
+```
+
+## Page 26
+
+### 结构化抽取
+
+`// "interrupt_keywords": ["` 停止 `", "` 打断 `","` 打断一下 `", "` 等一下 `", "` 别
+
+说了 `", "` 打住 `"] //` 配置打断词列表
+
+```
+},
+
+       "cfg": {
+```
+
+`"format": "pcm", //` 音频输入格式
+
+`"sample_rate": 16000, //` 音频输入采样率 目前只支持 `16000`
+
+`"bit_rate": 16, //` 比特率 目前只支持 `16bit`
+
+`"channel": 1, //` 声道 目前只支持单声道
+
+`"enable_punctuation": true, //` 开启标点
+
+`"enable_itn": true, //` 开启 `itn`
+
+```
+         "keywords": [
+
+```
+
+`"` 张三 `"`
+
+`] //` 热词
+
+```
+}
+
+}
+
+}
+
+}
+
+```
+
+#### Audio.Create 开始发送音频
+
+#### Audio.Completed 结束发送音频
+
+只有当VAD 关闭时 需要在说话结束/音频发送结束后发送这个事件。
+
+#### Cancel 取消
+
+取消当前对话 (只能在收到 asr.completed 事件后才能发送取消)
+
+### 原始逐行文本重排
+
+26              // "interrupt_keywords": ["停止", "打断","打断一下", "等一下", "别
+     说了", "打住"] // 配置打断词列表
+   27              },
+   28               "cfg": {
+   29                   "format": "pcm", // 音频输入格式
+   30                   "sample_rate": 16000, // 音频输入采样率 目前只支持 16000
+   31                   "bit_rate": 16, // 比特率 目前只支持 16bit
+   32                   "channel": 1, // 声道 目前只支持单声道
+   33                   "enable_punctuation": true, // 开启标点
+   34                   "enable_itn": true, // 开启itn
+   35                   "keywords": [
+   36                "张三"
+   37                  ] // 热词
+   38              }
+   39          }
+   40      }
+   41   }
+
+Audio.Create 开始发送音频
+
+ 只有当VAD 关闭时 需要在说话前/发送音频前发送这个事件。
+
+```
+{
+"event": "audio.create",
+"payload": {}
+}
+```
+
+Audio.Completed 结束发送音频
+
+ 只有当VAD 关闭时 需要在说话结束/音频发送结束后发送这个事件。
+
+```
+{
+"event": "audio.completed",
+"payload": {}
+}
+```
+
+Cancel 取消
+
+ 取消当前对话 (只能在收到 asr.completed 事件后才能发送取消)
+
+## Page 27
+
+### 结构化抽取
+
+#### Prompt 发送自定义消息
+
+发送自定义消息 例如图片等. 不同LLM供应商 prompt 参数不同
+
+#### Synthesis 文本合成
+
+#### AudioPlayed 音频播放结束
+
+使用关键词打断时需要在音频播放结束后立即发送该事件同时服务器进入下一轮对话
+
+如果开启关键词打断没有发送该事件 不会进入对话状态
+
+### 原始逐行文本重排
+
+1代码块{
+   2       "event": "cancel",
+   3       "payload": {}
+   4   }
+
+Prompt 发送自定义消息
+
+ 发送自定义消息 例如图片等. 不同LLM供应商 prompt 参数不同
+
+```
+{
+"event": "prompt",
+"payload": {
+"prompt": [
+{
+"role": "user",
+"content": "今天是礼拜几?",
+"content_type": "text", // 可以不提交
+"type": "question" // 可以不提交
+}
+]
+}
+}
+```
+
+Synthesis 文本合成
+
+ 直接合成文本返回音频
+
+```
+{
+"event": "synthesis",
+"payload": {
+"text": "今天是礼拜几?"
+}
+}
+```
+
+AudioPlayed 音频播放结束
+
+ 使用关键词打断时需要在音频播放结束后立即发送该事件同时服务器进入下一轮对话
+
+ 如果开启关键词打断没有发送该事件 不会进入对话状态
+
+## Page 28
+
+### 结构化抽取
+
+#### 音频播放
+
+端侧发送音频文件远程地址 编解码后推送音频流
+
+上传/接收 音频均为 二进制音频流 使用websocket 协议 二进制帧BinaryFrame
+
+```
+{
+
+  "event": "canceled",
+
+  "payload": {
+
+```
+
+### 原始逐行文本重排
+
+1代码块{
+   2       "event": "audio.played",
+   3       "payload": {}
+   4   }
+
+音频播放
+
+ 端侧发送音频文件远程地址 编解码后推送音频流
+
+```
+{
+"event": "audio.convert",
+"payload": {
+"audio_convert_request": {
+"audio_url": "https://fileserver.tos-cn-
+guangzhou.volces.com/songs/mp3/huahua/烟火里的尘埃.mp3",
+"bit_depth": 16,
+"channels": 1,
+"sample_rate": 16000,
+"target_format": "pcm" // 端侧预期格式
+}
+}
+}
+```
+
+接收服务器事件
+
+ 上传/接收 音频均为 二进制音频流 使用websocket 协议 二进制帧BinaryFrame
+
+开始
+
+```
+{
+"event": "started",
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+取消
+
+```
+{
+"event": "canceled",
+"payload": {
+```
+
+## Page 29
+
+### 结构化抽取
+
+```
+     "dialog_id": "9ec025eb99c24ba7bd37c5c01fa17b66_1744162831205391454"
+
+},
+
+  "sid": "9ec025eb99c24ba7bd37c5c01fa17b66"
+
+}
+
+```
+
+#### CMD 指令解析
+
+```
+{
+
+  "event": "command",
+
+  "sid": "04fd606094e14ffc98a61867e385439b",
+
+  "payload": {
+```
+
+`"command": "SHUTDOWN",   //` 指令
+
+`"pattern": "` 关闭设备 `",    //` 匹配词
+
+`"confidence": 1,      //` 置信度
+
+`"match_type": "exact",   //` 匹配模式
+
+`"original_asr": "` 关闭设备。 `"` `//` 原始内容
+
+`"params": {} //` 正则提取参数 例如正则 `(?P<number>\d{4,20}) params:`
+
+```
+{"number":"15300000000"}
+
+}
+
+}
+
+```
+
+`//` 通过智能体调用端侧插件 返回内容
+
+```
+{
+
+ "event": "command",
+
+```
+
+### 原始逐行文本重排
+
+4           "dialog_id": "9ec025eb99c24ba7bd37c5c01fa17b66_1744162831205391454"
+   5       },
+   6       "sid": "9ec025eb99c24ba7bd37c5c01fa17b66"
+   7   }
+
+VAD 检测到说话
+
+```
+{
+"event": "vad.active",
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+VAD 检测到停止说话
+
+```
+{
+"event": "vad.silence",
+"sid": "04fd606094e14ffc98a61867e385439b"
+}
+```
+
+CMD 指令解析
+
+```
+{
+"event": "command",
+"sid": "04fd606094e14ffc98a61867e385439b",
+"payload": {
+"command": "SHUTDOWN",    // 指令
+"pattern": "关闭设备",     // 匹配词
+"confidence": 1,        // 置信度
+"match_type": "exact",    // 匹配模式
+"original_asr": "关闭设备。" // 原始内容
+"params": {} // 正则提取参数 例如正则 (?P<number>\d{4,20}) params:
+{"number":"15300000000"}
+}
+}
+13
+// 通过智能体调用端侧插件 返回内容
+{
+"event": "command",
+```
+
+## Page 30
+
+### 结构化抽取
+
+```
+ "payload": {
+
+  "functions": [
+
+{
+
+     "id": "7332417498915246062",
+
+     "type": "function",
+
+     "function": {
+
+      "name": "control_volumn",
+```
+
+`"arguments": "{\"command\":\"SHUTDOWN\",\"speech_text\":\"` 关闭设备 `\"}"`
+
+```
+}
+
+}
+
+]
+
+},
+
+ "sid": "7c39e7896cfa4cdfa274186655e58c6e"
+
+}
+
+```
+
+#### ASR 开始
+
+#### ASR 结果
+
+#### ASR 结束
+
+### 原始逐行文本重排
+
+17     "payload": {
+   18       "functions": [
+   19        {
+   20           "id": "7332417498915246062",
+   21           "type": "function",
+   22           "function": {
+   23             "name": "control_volumn",
+   24             "arguments": "{\"command\":\"SHUTDOWN\",\"speech_text\":\"关闭设备\"}"
+   25          }
+   26        }
+   27      ]
+   28     },
+   29     "sid": "7c39e7896cfa4cdfa274186655e58c6e"
+   30   }
+
+ASR 开始
+
+```
+{
+"event": "asr.started",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+ASR 结果
+
+```
+{
+"event": "asr.result",
+"payload": {
+"content": "你好。",
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+ASR 结束
+
+## Page 31
+
+### 结构化抽取
+
+```
+{
+
+  "event": "asr.completed",
+
+  "payload": {
+
+     "dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+
+},
+
+  "sid": "f56fd6081f6e4f40bf325fd625f214ea"
+
+}
+
+```
+
+#### LLM 创建成功
+
+#### LLM 回复内容
+
+#### LLM 回复完成
+
+```
+{
+
+  "event": "llm.completed",
+
+  "payload": {
+```
+
+`"content": "` 哈喽呀小 `a` !今天过得咋样? `",`
+
+```
+     "dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+
+},
+
+  "sid": "f56fd6081f6e4f40bf325fd625f214ea"
+
+```
+
+### 原始逐行文本重排
+
+1   {
+   2       "event": "asr.completed",
+   3       "payload": {
+   4           "dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+   5       },
+   6       "sid": "f56fd6081f6e4f40bf325fd625f214ea"
+   7   }
+
+LLM 创建成功
+
+```
+{
+"event": "llm.created",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+LLM 回复内容
+
+```
+{
+"event": "llm.delta",
+"payload": {
+"content": "哈喽",
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+LLM 回复完成
+
+```
+{
+"event": "llm.completed",
+"payload": {
+"content": "哈喽呀小a!今天过得咋样?",
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+```
+
+## Page 32
+
+### 结构化抽取
+
+```
+}
+
+```
+
+#### LLM 结束
+
+#### TTS 创建成功
+
+#### TTS 音频发送结束
+
+### 原始逐行文本重排
+
+8   }
+
+LLM 结束
+
+```
+{
+"event": "llm.done",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+TTS 创建成功
+
+```
+{
+"event": "tts.created",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+TTS 开始返回音频
+
+```
+{
+"event": "tts.started",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+TTS 音频发送结束
+
+## Page 33
+
+### 结构化抽取
+
+#### 结束
+
+标识本轮对话结束
+
+音乐全部推送结束
+
+### 原始逐行文本重排
+
+1   {
+   2       "event": "tts.completed",
+   3       "payload": {
+   4           "dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+   5       },
+   6       "sid": "f56fd6081f6e4f40bf325fd625f214ea"
+   7   }
+
+结束
+
+ 标识本轮对话结束
+
+```
+{
+"event": "completed",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+开始播放音乐
+
+ 音频编解码结束开始下发音频
+
+```
+{
+"event": "audio.convert.started",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009",
+"original_url":"",
+"target_format":"",
+"message":""
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+音乐解码发送结束
+
+ 音乐全部推送结束
+
+## Page 34
+
+### 结构化抽取
+
+```
+{
+
+  "event": "audio.convert.completed",
+
+  "payload": {
+
+     "dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+
+},
+
+  "sid": "f56fd6081f6e4f40bf325fd625f214ea"
+
+}
+
+```
+
+错误事件
+
+### 原始逐行文本重排
+
+1   {
+   2       "event": "audio.convert.completed",
+   3       "payload": {
+   4           "dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009"
+   5       },
+   6       "sid": "f56fd6081f6e4f40bf325fd625f214ea"
+   7   }
+
+音乐编解码出现异常
+
+```
+{
+"event": "audio.convert.failed",
+"payload": {
+"dialog_id": "f56fd6081f6e4f40bf325fd625f214ea_1744162450468050009",
+"message":  "音频转换失败"
+},
+"sid": "f56fd6081f6e4f40bf325fd625f214ea"
+}
+```
+
+错误
+
+ 错误事件
+
+```
+{
+"event": "failed",
+"payload": {
+"error":   "AUDIO_FILE_READ_ERROR",
+"message": "音频文件读取失败",
+}
+}
+```
+
+## Page 35
+
+### 结构化抽取
+
+Python 调用示例
+
+```
+import json
+
+import uuid
+
+import pyaudio
+
+import websocket
+
+import threading
+
+import time
+
+import logging
+
+import numpy as np
+
+import queue
+
+logging.basicConfig(
+
+level=logging.INFO,
+
+  format='[%(asctime)s.%(msecs)03d] [%(levelname)s] %(message)s',
+
+datefmt='%Y-%m-%d %H:%M:%S'
+
+)
+
+logger = logging.getLogger("AudioClientWithAEC")
+
+```
+
+`#` 配置
+
+```
+WS_SERVER_URL = "ws://127.0.0.1:9099/vc/chat"
+
+```
+
+`#` 北京
+
+```
+# WS_SERVER_URL = "ws://115.190.94.208:22080/vc/chat"
+
+SAMPLE_RATE = 16000
+
+CHUNK = 1024
+
+FORMAT = pyaudio.paInt16
+
+CHANNELS = 1
+
+```
+
+`HEARTBEAT_INTERVAL = 10` `#` 秒
+
+### 原始逐行文本重排
+
+Python 调用示例
+
+```
+import json
+import uuid
+import pyaudio
+import websocket
+import threading
+import time
+import logging
+import numpy as np
+import queue
+10
+# 配置日志
+logging.basicConfig(
+level=logging.INFO,
+format='[%(asctime)s.%(msecs)03d] [%(levelname)s] %(message)s',
+datefmt='%Y-%m-%d %H:%M:%S'
+)
+logger = logging.getLogger("AudioClientWithAEC")
+18
+# 配置
+WS_SERVER_URL = "ws://127.0.0.1:9099/vc/chat"
+# 北京
+# WS_SERVER_URL = "ws://115.190.94.208:22080/vc/chat"
+SAMPLE_RATE = 16000
+CHUNK = 1024
+FORMAT = pyaudio.paInt16
+CHANNELS = 1
+HEARTBEAT_INTERVAL = 10 # 秒
+28
+```
+
+## Page 36
+
+### 结构化抽取
+
+```
+class AudioClient:
+
+```
+
+`"""` 主音频客户端类,处理所有功能 `"""`
+
+```
+  def __init__(self):
+
+self.is_recording = False
+
+self.is_playing = False
+
+self.websocket = None
+
+self.pyaudio_instance = pyaudio.PyAudio()
+
+self.audio_input_stream = None
+
+self.audio_output_stream = None
+
+self.audio_queue = queue.Queue()
+
+self.player_thread = None
+
+self.player_running = False
+
+self.lock = threading.RLock()
+
+```
+
+`#` 播放会话控制
+
+```
+self.playback_session_active = False
+
+self.playback_session_lock = threading.Lock()
+
+```
+
+`#` 保存最近播放的音频数据(用于回音消除)
+
+```
+self.recent_playback = None
+
+self.recent_playback_lock = threading.Lock()
+
+  def send_start_command(self):
+
+     if not self.websocket:
+
+```
+
+`logger.error("WebSocket` 未连接,无法发送开始命令 `")`
+
+```
+       return
+
+start_payload = {
+
+       "event": "start",
+
+       "payload": {
+
+         "simple_response": False,
+
+         "device_id": "WangQunTestID",
+
+         "user_agent": "AudioClientWithAEC/1.0",
+
+         "dialog_attributes": {
+
+           "provider": "bailian",
+
+           "cfg": {
+
+              "disable_empty_prompt": True,
+
+              "greeting":{
+
+```
+
+### 原始逐行文本重排
+
+29   class AudioClient:
+30    """主音频客户端类,处理所有功能"""
+31
+32       def __init__(self):
+33       # 初始化状态变量
+34           self.is_recording = False
+35           self.is_playing = False
+36           self.websocket = None
+37
+38       # 初始化音频组件
+39           self.pyaudio_instance = pyaudio.PyAudio()
+40           self.audio_input_stream = None
+41           self.audio_output_stream = None
+42
+43       # 设置音频队列和线程管理
+44           self.audio_queue = queue.Queue()
+45           self.player_thread = None
+46           self.player_running = False
+47
+48       # 初始化锁以确保线程安全
+49           self.lock = threading.RLock()
+50
+51       # 播放会话控制
+52           self.playback_session_active = False
+53           self.playback_session_lock = threading.Lock()
+54
+55       # 保存最近播放的音频数据(用于回音消除)
+56           self.recent_playback = None
+57           self.recent_playback_lock = threading.Lock()
+58
+59       def send_start_command(self):
+60       """向服务器发送初始化命令"""
+61           if not self.websocket:
+62            logger.error("WebSocket未连接,无法发送开始命令")
+63               return
+64
+65           start_payload = {
+66               "event": "start",
+67               "payload": {
+68                   "simple_response": False,
+69                   "device_id": "WangQunTestID",
+70                   "user_agent": "AudioClientWithAEC/1.0",
+71                   "dialog_attributes": {
+72                       "provider": "bailian",
+73                       "cfg": {
+74                           "disable_empty_prompt": True,
+75                           "greeting":{
+
+## Page 37
+
+### 结构化抽取
+
+```
+                "enabled": True,
+```
+
+`"content": "` 你好,我是 林悦 `!",`
+
+```
+},
+
+              "bailian_option": {
+
+                "system": {
+
+                  "type": "file",
+
+                  "content": "1567d9e19ac09269d8ce6c887494ff01"
+
+```
+
+`#` 林悦
+
+```
+},
+
+```
+
+`"app_id": "ee8c568a748f4af4b30478d77df8c3b2"` `#` 玩偶
+
+```
+}
+
+}
+
+},
+
+         "outbound_attributes": {
+
+           "provider": "cosyvoice-v2",
+
+           "cfg": {
+
+              "format": "pcm",
+
+              "sample_rate": 16000,
+
+              "bit_rate": 16,
+
+              "channel": 1,
+
+              "volume": 100,
+
+              "voice": "longyan_v2", #"cosyvoice-v2-amp-2f7d423",#
+
+"longjielidou",
+
+              "speech_rate": 0,
+
+              "chunk_interval_ms": 50
+
+}
+
+},
+
+         "inbound_attributes": {
+
+           "provider": "aliyun",
+
+           "disable_vad": False,
+
+           "vad_silence": 200,
+
+           "interrupt_options": {
+
+              "concatenate_results": True,
+
+              "thinking_time_only": True,
+
+              "keyword_interrupt": True,
+```
+
+`"interrupt_keywords": ["` 停止 `", "` 打断 `","` 打断一下 `", "` 等一
+
+下 `", "` 别说了 `", "` 打住 `"]`
+
+```
+},
+
+           "cfg": {
+
+              "format": "pcm",
+
+              "sample_rate": 16000,
+
+              "bit_rate": 16,
+
+              "channel": 1,
+
+              "enable_punctuation": True,
+
+              "enable_itn": True,
+
+              "keywords": [
+
+```
+
+### 原始逐行文本重排
+
+76                               "enabled": True,
+ 77                               "content": "你好,我是 林悦!",
+ 78                          },
+ 79                           "bailian_option": {
+ 80                               "system": {
+ 81                                   "type": "file",
+ 82                                   "content": "1567d9e19ac09269d8ce6c887494ff01"
+    # 林悦
+ 83                              },
+ 84                               "app_id": "ee8c568a748f4af4b30478d77df8c3b2" # 玩偶
+    通用智能体
+ 85                          }
+ 86                      }
+ 87                  },
+ 88                   "outbound_attributes": {
+ 89                       "provider": "cosyvoice-v2",
+ 90                       "cfg": {
+ 91                           "format": "pcm",
+ 92                           "sample_rate": 16000,
+ 93                           "bit_rate": 16,
+ 94                           "channel": 1,
+ 95                           "volume": 100,
+ 96                           "voice": "longyan_v2", #"cosyvoice-v2-amp-2f7d423",#
+      "longjielidou",
+ 97                           "speech_rate": 0,
+ 98                           "chunk_interval_ms": 50
+ 99                      }
+100                  },
+101                   "inbound_attributes": {
+102                       "provider": "aliyun",
+103                       "disable_vad": False,
+104                       "vad_silence": 200,
+105                       "interrupt_options": {
+106                           "concatenate_results": True,
+107                           "thinking_time_only": True,
+108                           "keyword_interrupt": True,
+109                           "interrupt_keywords": ["停止", "打断","打断一下", "等一
+     下", "别说了", "打住"]
+110                      },
+111                       "cfg": {
+112                           "format": "pcm",
+113                           "sample_rate": 16000,
+114                           "bit_rate": 16,
+115                           "channel": 1,
+116                           "enable_punctuation": True,
+117                           "enable_itn": True,
+118                           "keywords": [
+
+## Page 38
+
+### 结构化抽取
+
+`"` 停止 `",`
+
+`"` 打断 `",`
+
+`"` 打断一下 `",`
+
+`"` 等一下 `",`
+
+`"` 别说了 `",`
+
+`"` 打住 `"`
+
+```
+]
+
+}
+
+}
+
+}
+
+}
+
+self.websocket.send(json.dumps(start_payload))
+
+  def start_recording(self):
+
+     with self.lock:
+
+       if self.is_recording:
+```
+
+`logger.warning("` 录制已在进行中 `")`
+
+```
+         return
+
+self.is_recording = True
+
+```
+
+`#` 如果需要,创建输入流
+
+```
+       if not self.audio_input_stream:
+
+self.audio_input_stream = self.pyaudio_instance.open(
+
+           format=FORMAT,
+
+channels=CHANNELS,
+
+rate=SAMPLE_RATE,
+
+           input=True,
+
+frames_per_buffer=CHUNK
+
+)
+
+recording_thread = threading.Thread(
+
+target=self._recording_thread_func,
+
+daemon=True
+
+)
+
+recording_thread.start()
+```
+
+`logger.info("` 录制已开始 `")`
+
+```
+  def _recording_thread_func(self):
+
+     try:
+
+       while self.is_recording and self.websocket:
+
+         try:
+
+```
+
+### 原始逐行文本重排
+
+119                        "停止",
+120                        "打断",
+121                     "打断一下",
+122                      "等一下",
+123                      "别说了",
+124                      "打住"
+125                          ]
+126                      }
+127                  }
+128              }
+129          }
+130           self.websocket.send(json.dumps(start_payload))
+131
+132       def start_recording(self):
+133       """开始音频录制和传输"""
+134           with self.lock:
+135              if self.is_recording:
+136                logger.warning("录制已在进行中")
+137                   return
+138
+139               self.is_recording = True
+140
+141         # 如果需要,创建输入流
+142              if not self.audio_input_stream:
+143                   self.audio_input_stream = self.pyaudio_instance.open(
+144                       format=FORMAT,
+145                       channels=CHANNELS,
+146                       rate=SAMPLE_RATE,
+147                       input=True,
+148                       frames_per_buffer=CHUNK
+149                  )
+150
+151         # 启动录制线程
+152               recording_thread = threading.Thread(
+153                   target=self._recording_thread_func,
+154                   daemon=True
+155              )
+156               recording_thread.start()
+157            logger.info("录制已开始")
+158
+159       def _recording_thread_func(self):
+160       """录制和发送音频数据的线程函数"""
+161           try:
+162               while self.is_recording and self.websocket:
+163                   try:
+164              # 读取音频数据
+
+## Page 39
+
+### 结构化抽取
+
+```
+audio_data = self.audio_input_stream.read(CHUNK,
+
+exception_on_overflow=False)
+
+```
+
+`#` 检查 `websocket` 是否仍然连接
+
+```
+           if not self.websocket or not self.websocket.sock or not
+
+self.websocket.sock.connected:
+
+```
+
+`logger.error("WebSocket` 断开连接,停止录制 `")`
+
+```
+              break
+
+self.websocket.send(audio_data,
+
+opcode=websocket.ABNF.OPCODE_BINARY)
+
+         except Exception as e:
+```
+
+`logger.error(f"` 录制线程错误 `: {e}")`
+
+```
+           break
+
+     finally:
+
+       with self.lock:
+
+self.is_recording = False
+```
+
+`logger.info("` 录制已停止 `")`
+
+```
+  def stop_recording(self):
+
+     with self.lock:
+
+self.is_recording = False
+```
+
+`logger.info("` 录制已停止 `")`
+
+```
+  def start_playback_thread(self):
+
+     with self.lock:
+
+       if self.player_running and self.player_thread and
+
+self.player_thread.is_alive():
+```
+
+`logger.info("` 播放线程已在运行 `")`
+
+```
+         return
+
+self.player_running = True
+
+self.player_thread = threading.Thread(
+
+target=self._playback_thread_func,
+
+daemon=True
+
+)
+
+self.player_thread.start()
+```
+
+`logger.info("` 播放线程已启动 `")`
+
+```
+  def _playback_thread_func(self):
+
+     try:
+
+output_stream = self.pyaudio_instance.open(
+
+```
+
+### 原始逐行文本重排
+
+165                       audio_data = self.audio_input_stream.read(CHUNK,
+      exception_on_overflow=False)
+166
+167              # 检查websocket是否仍然连接
+168                      if not self.websocket or not self.websocket.sock or not
+      self.websocket.sock.connected:
+169                      logger.error("WebSocket断开连接,停止录制")
+170                           break
+171
+172              # 发送处理后的音频数据到服务器
+173                       self.websocket.send(audio_data,
+      opcode=websocket.ABNF.OPCODE_BINARY)
+174                   except Exception as e:
+175                   logger.error(f"录制线程错误: {e}")
+176                       break
+177           finally:
+178               with self.lock:
+179                   self.is_recording = False
+180                logger.info("录制已停止")
+181
+182       def stop_recording(self):
+183        """停止音频录制"""
+184           with self.lock:
+185               self.is_recording = False
+186            logger.info("录制已停止")
+187
+188       def start_playback_thread(self):
+189        """启动音频播放线程"""
+190           with self.lock:
+191              if self.player_running and self.player_thread and
+      self.player_thread.is_alive():
+192               logger.info("播放线程已在运行")
+193                   return
+194
+195               self.player_running = True
+196               self.player_thread = threading.Thread(
+197                   target=self._playback_thread_func,
+198                   daemon=True
+199              )
+200               self.player_thread.start()
+201            logger.info("播放线程已启动")
+202
+203       def _playback_thread_func(self):
+204        """音频播放线程函数"""
+205           try:
+206         # 创建输出流
+207               output_stream = self.pyaudio_instance.open(
+
+## Page 40
+
+### 结构化抽取
+
+```
+         format=FORMAT,
+
+channels=CHANNELS,
+
+rate=SAMPLE_RATE,
+
+output=True,
+
+frames_per_buffer=CHUNK
+
+)
+
+```
+
+`logger.info("` 播放线程就绪 `")`
+
+```
+       while self.player_running:
+
+         try:
+
+```
+
+`#` 获取音频数据(带超时)
+
+```
+audio_data = self.audio_queue.get(timeout=0.5)
+
+           with self.playback_session_lock:
+
+              if not self.playback_session_active:
+
+self.playback_session_active = True
+
+         except queue.Empty:
+
+           with self.playback_session_lock:
+
+              if self.playback_session_active:
+
+self.playback_session_active = False
+```
+
+`logger.info("` 全部音频播放结束 `")`
+
+`#` 发送音频播放完成事件
+
+```
+self.send_audio_played_event()
+
+           continue
+
+         if not self.player_running:
+
+           break
+
+```
+
+`#` 播放音频
+
+```
+         with self.lock:
+
+self.is_playing = True
+
+```
+
+`#` 记录录音状态,但不要停止录音
+
+```
+was_recording = self.is_recording
+
+         try:
+
+```
+
+`#` 存储当前播放的音频,用于回音消除
+
+```
+           with self.recent_playback_lock:
+
+self.recent_playback = audio_data
+
+```
+
+`#` 标准化音频(可选)
+
+```
+audio_array = np.frombuffer(audio_data, dtype=np.int16)
+
+```
+
+### 原始逐行文本重排
+
+208                   format=FORMAT,
+209                   channels=CHANNELS,
+210                   rate=SAMPLE_RATE,
+211                   output=True,
+212                   frames_per_buffer=CHUNK
+213              )
+214
+215            logger.info("播放线程就绪")
+216
+217         # 处理音频队列
+218               while self.player_running:
+219                   try:
+220              # 获取音频数据(带超时)
+221                       audio_data = self.audio_queue.get(timeout=0.5)
+222
+223              # 标记播放会话开始
+224                       with self.playback_session_lock:
+225                          if not self.playback_session_active:
+226                               self.playback_session_active = True
+227
+228                   except queue.Empty:
+229              # 队列为空,检查是否需要结束播放会话
+230                       with self.playback_session_lock:
+231                          if self.playback_session_active:
+232                               self.playback_session_active = False
+233                        logger.info("全部音频播放结束")
+234                   # 发送音频播放完成事件
+235                               self.send_audio_played_event()
+236                       continue
+237
+238            # 检查我们是否仍在运行
+239                  if not self.player_running:
+240                       break
+241
+242            # 播放音频
+243                   with self.lock:
+244                       self.is_playing = True
+245              # 记录录音状态,但不要停止录音
+246                       was_recording = self.is_recording
+247
+248                   try:
+249              # 存储当前播放的音频,用于回音消除
+250                       with self.recent_playback_lock:
+251                           self.recent_playback = audio_data
+252
+253              # 标准化音频(可选)
+254                       audio_array = np.frombuffer(audio_data, dtype=np.int16)
+
+## Page 41
+
+### 结构化抽取
+
+```
+peak = np.max(np.abs(audio_array))
+```
+
+`if peak > 0` `and peak < 10000: #` 只有当音量太小时才标准化
+
+```
+gain = min(20000 / peak, 3.0)
+
+audio_array = (audio_array * gain).astype(np.int16)
+
+audio_data = audio_array.tobytes()
+
+```
+
+`#` 播放音频
+
+```
+output_stream.write(audio_data)
+
+         except Exception as e:
+```
+
+`logger.error(f"` 播放音频错误 `: {e}")`
+
+```
+self.audio_queue.task_done()
+
+         with self.lock:
+
+self.is_playing = False
+
+```
+
+`#` 播放结束后,确保录音正在进行
+
+```
+         with self.lock:
+
+           if was_recording and not self.is_recording:
+```
+
+`logger.info("` 音频播放结束,恢复之前的录音状态 `")`
+
+```
+time.sleep(0.2)
+
+self.start_recording()
+
+```
+
+`#` 如果需要始终在播放后启动录音(无论之前状态如何),则使用以下代码
+
+```
+           # if not self.is_recording:
+```
+
+`#   logger.info("` 音频播放结束,开始录音 `")`
+
+```
+           #   time.sleep(0.2)
+
+           #   self.start_recording()
+
+     except Exception as e:
+
+```
+
+`logger.error(f"` 播放线程错误 `: {e}")`
+
+```
+     finally:
+
+       try:
+
+         if output_stream:
+
+output_stream.stop_stream()
+
+output_stream.close()
+
+       except Exception as e:
+```
+
+`logger.error(f"` 关闭输出流错误 `: {e}")`
+
+```
+       with self.lock:
+
+self.player_running = False
+
+self.is_playing = False
+```
+
+`logger.info("` 播放线程已停止 `")`
+
+### 原始逐行文本重排
+
+255                       peak = np.max(np.abs(audio_array))
+256                      if peak > 0 and peak < 10000: # 只有当音量太小时才标准化
+257                          gain = min(20000 / peak, 3.0)
+258                           audio_array = (audio_array * gain).astype(np.int16)
+259                           audio_data = audio_array.tobytes()
+260
+261              # 播放音频
+262                       output_stream.write(audio_data)
+263                   except Exception as e:
+264                   logger.error(f"播放音频错误: {e}")
+265
+266                   self.audio_queue.task_done()
+267
+268                   with self.lock:
+269                       self.is_playing = False
+270
+271            # 播放结束后,确保录音正在进行
+272            # 如果之前在录音但现在没有录音,重新启动录音
+273                   with self.lock:
+274                      if was_recording and not self.is_recording:
+275                   logger.info("音频播放结束,恢复之前的录音状态")
+276                 # 短暂延迟确保资源释放
+277                           time.sleep(0.2)
+278                           self.start_recording()
+279              # 如果需要始终在播放后启动录音(无论之前状态如何),则使用以下代码
+    替代
+280              # if not self.is_recording:
+281              #   logger.info("音频播放结束,开始录音")
+282              #    time.sleep(0.2)
+283              #    self.start_recording()
+284           except Exception as e:
+285            logger.error(f"播放线程错误: {e}")
+286           finally:
+287         # 清理资源
+288               try:
+289                  if output_stream:
+290                       output_stream.stop_stream()
+291                       output_stream.close()
+292               except Exception as e:
+293               logger.error(f"关闭输出流错误: {e}")
+294
+295               with self.lock:
+296                   self.player_running = False
+297                   self.is_playing = False
+298               logger.info("播放线程已停止")
+299
+300            # 确保播放线程结束后录音能继续
+
+## Page 42
+
+### 结构化抽取
+
+```
+         if not self.is_recording:
+```
+
+`logger.info("` 播放线程结束,尝试重新启动录音 `")`
+
+```
+time.sleep(0.3)
+
+self.start_recording()
+
+  def play_audio(self, audio_data):
+
+```
+
+`if` `not audio_data or` `len(audio_data) < 10: #` 跳过非常小的块
+
+```
+       return
+
+     if not self.player_running:
+
+self.start_playback_thread()
+
+self.audio_queue.put(audio_data)
+
+```
+
+`logger.debug(f"` 已将 `{len(audio_data)}` 字节的音频排队等待播放 `")`
+
+```
+  def stop_playback(self):
+
+     with self.lock:
+
+self.is_playing = False
+
+```
+
+`#` 清除队列
+
+```
+     while not self.audio_queue.empty():
+
+       try:
+
+self.audio_queue.get_nowait()
+
+self.audio_queue.task_done()
+
+       except queue.Empty:
+
+         break
+
+     with self.recent_playback_lock:
+
+self.recent_playback = None
+
+```
+
+`logger.info("` 播放已停止,队列已清除 `")`
+
+```
+     if not self.is_recording:
+
+```
+
+`logger.info("` 播放停止后重新启动录音 `")`
+
+```
+self.start_recording()
+
+  def toggle_echo_cancellation(self, enabled=None):
+
+```
+
+`"""` 切换回音消除功能的开启 `/` 关闭状态 `"""`
+
+```
+is_active = self.echo_canceller.toggle(enabled)
+```
+
+`logger.info(f"` 回音消除 `{'` 已启用 `'` `if is_active else` `'` 已禁用 `'}")`
+
+```
+     return is_active
+
+```
+
+### 原始逐行文本重排
+
+301                  if not self.is_recording:
+302                 logger.info("播放线程结束,尝试重新启动录音")
+303              # 短暂延迟确保资源释放
+304                       time.sleep(0.3)
+305                       self.start_recording()
+306       def play_audio(self, audio_data):
+307       """将音频数据添加到播放队列"""
+308           if not audio_data or len(audio_data) < 10: # 跳过非常小的块
+309               return
+310
+311       # 确保播放线程正在运行
+312           if not self.player_running:
+313               self.start_playback_thread()
+314
+315       # 添加到队列
+316           self.audio_queue.put(audio_data)
+317          logger.debug(f"已将 {len(audio_data)} 字节的音频排队等待播放")
+318
+319       def stop_playback(self):
+320       """停止音频播放并清除队列"""
+321           with self.lock:
+322               self.is_playing = False
+323
+324       # 清除队列
+325           while not self.audio_queue.empty():
+326               try:
+327                   self.audio_queue.get_nowait()
+328                   self.audio_queue.task_done()
+329               except queue.Empty:
+330                   break
+331
+332       # 清除最近播放的音频引用
+333           with self.recent_playback_lock:
+334               self.recent_playback = None
+335
+336        logger.info("播放已停止,队列已清除")
+337
+338       # 确保录音重新开始
+339           if not self.is_recording:
+340           logger.info("播放停止后重新启动录音")
+341               self.start_recording()
+342
+343       def toggle_echo_cancellation(self, enabled=None):
+344       """切换回音消除功能的开启/关闭状态"""
+345           is_active = self.echo_canceller.toggle(enabled)
+346         logger.info(f"回音消除 {'已启用' if is_active else '已禁用'}")
+347           return is_active
+
+## Page 43
+
+### 结构化抽取
+
+```
+  def reset_echo_canceller(self):
+
+self.echo_canceller.reset()
+
+```
+
+`logger.info("` 回音消除器已重置 `")`
+
+```
+  def on_websocket_message(self, ws, message):
+
+```
+
+`"""` 处理传入的 `WebSocket` 消息 `"""`
+
+```
+self.websocket = ws
+
+     if isinstance(message, bytes):
+```
+
+`logger.info(f"` 收到音频数据 `({len(message)}` 字节 `)")`
+
+```
+self.play_audio(message)
+
+       return
+
+     try:
+```
+
+`# logger.info(f"` 收到消息 `:{message}")`
+
+`#` 解析 `JSON` 消息
+
+```
+data = json.loads(message)
+
+self._handle_json_message(data)
+
+     except json.JSONDecodeError:
+```
+
+`logger.info(f"` 收到文本消息 `: {message}")`
+
+```
+     except Exception as e:
+```
+
+`logger.error(f"` 处理消息错误 `: {e}")`
+
+```
+  def _handle_json_message(self, data):
+
+```
+
+`"""` 处理来自服务器的 `JSON` 消息 `"""`
+
+`# logger.info(f"` 收到消息 `:{json.dumps(data)}")`
+
+```
+event = data.get("header", {}).get("event", "")
+
+     if not event:
+
+event = data.get("event", "")
+
+```
+
+`event = event.lower() #` 转为小写以便匹配
+
+```
+payload = data.get("payload", {})
+
+sid = data.get("sid", "")
+
+dialog_id = payload.get("dialog_id","")
+
+     if event == "started":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 会话已开始 `")`
+
+```
+     elif event == "failed":
+
+```
+
+### 原始逐行文本重排
+
+348
+349       def reset_echo_canceller(self):
+350       """重置回音消除器状态"""
+351           self.echo_canceller.reset()
+352         logger.info("回音消除器已重置")
+353
+354       def on_websocket_message(self, ws, message):
+355         """处理传入的WebSocket消息"""
+356           self.websocket = ws
+357
+358       # 处理二进制音频数据
+359           if isinstance(message, bytes):
+360            logger.info(f"收到音频数据 ({len(message)} 字节)")
+361               self.play_audio(message)
+362               return
+363
+364       # 处理文本消息
+365           try:
+366         # logger.info(f"收到消息:{message}")
+367         # 解析JSON消息
+368               data = json.loads(message)
+369               self._handle_json_message(data)
+370           except json.JSONDecodeError:
+371            logger.info(f"收到文本消息: {message}")
+372           except Exception as e:
+373            logger.error(f"处理消息错误: {e}")
+374
+375       def _handle_json_message(self, data):
+376        """处理来自服务器的JSON消息"""
+377
+378       # logger.info(f"收到消息:{json.dumps(data)}")
+379       # 提取事件类型
+380           event = data.get("header", {}).get("event", "")
+381           if not event:
+382               event = data.get("event", "")
+383
+384           event = event.lower() # 转为小写以便匹配
+385
+386       # 提取有效载荷
+387           payload = data.get("payload", {})
+388           sid = data.get("sid", "")
+389           dialog_id = payload.get("dialog_id","")
+390
+391       # 根据事件类型处理
+392           if event == "started":
+393               logger.info(f"{sid}  {dialog_id}:会话已开始")
+394           elif event == "failed":
+
+## Page 44
+
+### 结构化抽取
+
+`logger.info(f"` 会话错误 `:{payload}")`
+
+```
+     elif event == "canceled":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 会话已取消 `")`
+
+```
+self.stop_playback()
+
+     elif event == "command":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 收到命令 `: {data}")`
+
+```
+output = {
+
+```
+
+`"command": "` 设置闹钟 `",`
+
+`"fail_prompt": "` 设置闹钟失败,请重试 `",`
+
+`"succeed_prompt": "` 设置闹钟 `"`
+
+```
+}
+
+payload = data.get("payload",{})
+
+functions = payload.get("functions",[])
+
+tool_call_id = functions[0].get("id")
+
+       # output = {
+
+       #   "command":
+
+       # }
+
+submit = {
+
+         "event": "submit.tool_output",
+
+         "payload": {
+
+           "tool_output": {
+
+              "tool_call_id": tool_call_id,
+
+              "output": json.dumps(output)
+
+}
+
+}
+
+}
+
+self.websocket.send(json.dumps(submit))
+
+     elif event == "vad.active":
+
+```
+
+`logger.info(f"{sid}:` 检测到语音 `-` 停止播放 `")`
+
+```
+self.stop_playback()
+
+       if not self.is_recording:
+
+self.start_recording()
+
+     elif event == "vad.silence":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 检测到静音 `")`
+
+```
+     elif event == "asr.started":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 语音识别开始 `")`
+
+```
+     elif event == "asr.result":
+
+result = payload.get("content", "")
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 语音识别结果 `: {result}")`
+
+```
+     elif event == "asr.completed":
+
+```
+
+### 原始逐行文本重排
+
+395             logger.info(f"会话错误:{payload}")
+396           elif event == "canceled":
+397               logger.info(f"{sid}  {dialog_id}:会话已取消")
+398               self.stop_playback()
+399           elif event == "command":
+400               logger.info(f"{sid}  {dialog_id}:收到命令: {data}")
+401
+402               output = {
+403                   "command": "设置闹钟",
+404                   "fail_prompt": "设置闹钟失败,请重试",
+405                   "succeed_prompt": "设置闹钟"
+406              }
+407               payload = data.get("payload",{})
+408
+409               functions = payload.get("functions",[])
+410               tool_call_id = functions[0].get("id")
+411         # output = {
+412         #    "command":
+413         # }
+414               submit = {
+415                   "event": "submit.tool_output",
+416                   "payload": {
+417                       "tool_output": {
+418                           "tool_call_id": tool_call_id,
+419                           "output": json.dumps(output)
+420                      }
+421                  }
+422              }
+423               self.websocket.send(json.dumps(submit))
+424
+425           elif event == "vad.active":
+426             logger.info(f"{sid}:检测到语音 - 停止播放")
+427               self.stop_playback()
+428         # 确保录音继续进行
+429              if not self.is_recording:
+430                   self.start_recording()
+431
+432           elif event == "vad.silence":
+433               logger.info(f"{sid}  {dialog_id}:检测到静音")
+434           elif event == "asr.started":
+435               logger.info(f"{sid}  {dialog_id}:语音识别开始")
+436
+437           elif event == "asr.result":
+438               result = payload.get("content", "")
+439               logger.info(f"{sid}  {dialog_id}:语音识别结果: {result}")
+440
+441           elif event == "asr.completed":
+
+## Page 45
+
+### 结构化抽取
+
+```
+final_result = payload.get("content", "")
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 语音识别完成 `: {final_result}")`
+
+```
+     elif event == "llm.created":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:LLM` 会话已创建 `")`
+
+```
+     elif event == "llm.delta":
+
+content = payload.get("content", "")
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:LLM` 增量响应 `: {content}")`
+
+```
+     elif event == "llm.completed":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:LLM` 响应完成 `")`
+
+```
+     elif event == "llm.done":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:LLM` 结束 `")`
+
+```
+     elif event == "tts.started":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 语音合成开始 `")`
+
+```
+     elif event == "tts.completed":
+
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 语音合成完成 `")`
+
+`#` 不要在这里调用 `stop_playback()`
+
+`#` 如果不在录音状态,且不在播放状态,则开始录音
+
+`#` 使用定时器延迟启动录音,让当前播放的音频能够完成
+
+```
+       if not self.is_recording and not self.is_playing:
+```
+
+`logger.info(f"{sid}:TTS` 完成,等待当前音频播放完毕后将启动录音 `")`
+
+```
+         def delayed_start_recording():
+
+```
+
+`#` 再次检查状态,确保播放已结束
+
+```
+           if not self.is_playing and not self.is_recording:
+```
+
+`logger.info("` 延迟启动录音 `")`
+
+```
+self.start_recording()
+
+```
+
+`#` 设置较长的延迟,确保有足够时间完成播放
+
+```
+threading.Timer(0.2, delayed_start_recording).start()
+
+     elif event == "completed":
+```
+
+`logger.info(f"{sid}` `{dialog_id}:` 会话已完成 `")`
+
+```
+     else:
+
+```
+
+`logger.debug(f"` 收到未知事件 `: {event},` 数据 `: {data}")`
+
+```
+     if "error" in data:
+
+error = data.get("error", {})
+
+error_code = error.get("code", "unknown")
+```
+
+`error_message = error.get("message", "` 未知错误 `")`
+
+`logger.error(f"` 服务器报告错误 `: [{error_code}] {error_message}")`
+
+```
+  def on_websocket_open(self, ws):
+
+```
+
+### 原始逐行文本重排
+
+442               final_result = payload.get("content", "")
+443               logger.info(f"{sid}  {dialog_id}:语音识别完成: {final_result}")
+444
+445           elif event == "llm.created":
+446               logger.info(f"{sid}  {dialog_id}:LLM会话已创建")
+447
+448           elif event == "llm.delta":
+449               content = payload.get("content", "")
+450               logger.info(f"{sid}  {dialog_id}:LLM增量响应: {content}")
+451
+452           elif event == "llm.completed":
+453               logger.info(f"{sid}  {dialog_id}:LLM响应完成")
+454           elif event == "llm.done":
+455               logger.info(f"{sid}  {dialog_id}:LLM结束")
+456           elif event == "tts.started":
+457               logger.info(f"{sid}  {dialog_id}:语音合成开始")
+458           elif event == "tts.completed":
+459               logger.info(f"{sid}  {dialog_id}:语音合成完成")
+460
+461         # 不要在这里调用stop_playback()
+462         # 只需要确保录音功能准备好
+463
+464         # 如果不在录音状态,且不在播放状态,则开始录音
+465         # 使用定时器延迟启动录音,让当前播放的音频能够完成
+466              if not self.is_recording and not self.is_playing:
+467              logger.info(f"{sid}:TTS完成,等待当前音频播放完毕后将启动录音")
+468                   def delayed_start_recording():
+469              # 再次检查状态,确保播放已结束
+470                      if not self.is_playing and not self.is_recording:
+471                      logger.info("延迟启动录音")
+472                           self.start_recording()
+473
+474            # 设置较长的延迟,确保有足够时间完成播放
+475                   threading.Timer(0.2, delayed_start_recording).start()
+476           elif event == "completed":
+477               logger.info(f"{sid}  {dialog_id}:会话已完成")
+478           else:
+479         # 处理未知事件
+480            logger.debug(f"收到未知事件: {event}, 数据: {data}")
+481
+482       # 检查是否有错误信息
+483           if "error" in data:
+484               error = data.get("error", {})
+485               error_code = error.get("code", "unknown")
+486               error_message = error.get("message", "未知错误")
+487            logger.error(f"服务器报告错误: [{error_code}] {error_message}")
+488       def on_websocket_open(self, ws):
+
+## Page 46
+
+### 结构化抽取
+
+`"""` 处理 `WebSocket` 连接打开 `"""`
+
+`logger.info("WebSocket` 已连接 `")`
+
+```
+self.websocket = ws
+
+self.start_playback_thread()
+
+self.send_start_command()
+
+self.start_recording()
+
+heartbeat_thread = threading.Thread(
+
+target=self._send_heartbeat,
+
+daemon=True
+
+)
+
+heartbeat_thread.start()
+
+  def _send_heartbeat(self):
+
+     while self.websocket and self.websocket.sock and
+
+self.websocket.sock.connected:
+
+       try:
+
+self.websocket.send("ping")
+```
+
+`logger.debug("` 已发送心跳 `")`
+
+```
+       except Exception as e:
+```
+
+`logger.error(f"` 心跳错误 `: {e}")`
+
+```
+         break
+
+time.sleep(HEARTBEAT_INTERVAL)
+
+  def on_websocket_close(self, ws, close_code, close_msg):
+
+```
+
+`"""` 处理 `WebSocket` 连接关闭 `"""`
+
+```
+                                     "
+
+```
+
+`logger.info(f"WebSocket` 已关闭 `: {close_code} - {close_msg}` `)`
+
+```
+self.stop_recording()
+
+```
+
+`#` 这里可以解析来自 `Go` 服务器的错误信息
+
+```
+     if close_code == 1000:
+
+```
+
+`print(f"` 服务器正常关闭,原因 `: {close_msg}")`
+
+```
+     else:
+
+```
+
+`print(f"` 异常关闭,错误信息 `: {close_msg}")`
+
+```
+  def on_websocket_error(self, ws, error):
+
+```
+
+`"""` 处理 `WebSocket` 错误 `"""`
+
+`logger.error(f"WebSocket` 错误 `: {error}")`
+
+### 原始逐行文本重排
+
+489         """处理WebSocket连接打开"""
+490          logger.info("WebSocket已连接")
+491           self.websocket = ws
+492
+493       # 启动播放线程
+494           self.start_playback_thread()
+495
+496       # 发送开始命令
+497           self.send_start_command()
+498
+499       # 开始录制
+500           self.start_recording()
+501
+502       # 启动心跳线程
+503           heartbeat_thread = threading.Thread(
+504               target=self._send_heartbeat,
+505               daemon=True
+506          )
+507           heartbeat_thread.start()
+508
+509       def _send_heartbeat(self):
+510       """发送定期心跳以保持连接活跃"""
+511           while self.websocket and self.websocket.sock and
+      self.websocket.sock.connected:
+512               try:
+513                   self.websocket.send("ping")
+514                logger.debug("已发送心跳")
+515               except Exception as e:
+516                logger.error(f"心跳错误: {e}")
+517                   break
+518
+519               time.sleep(HEARTBEAT_INTERVAL)
+520
+521       def on_websocket_close(self, ws, close_code, close_msg):
+522         """处理WebSocket连接关闭"""
+523          logger.info(f"WebSocket已关闭: {close_code} - {close_msg}")
+524           self.stop_recording()
+525       # 这里可以解析来自Go服务器的错误信息
+526           if close_code == 1000:
+527           print(f"服务器正常关闭,原因: {close_msg}")
+528           else:
+529           print(f"异常关闭,错误信息: {close_msg}")
+530
+531       def on_websocket_error(self, ws, error):
+532         """处理WebSocket错误"""
+533          logger.error(f"WebSocket错误: {error}")
+534
+
+## Page 47
+
+### 结构化抽取
+
+```
+  def cleanup(self):
+
+```
+
+`logger.info("` 正在清理资源 `")`
+
+```
+self.stop_recording()
+
+     with self.lock:
+
+self.player_running = False
+
+     if self.audio_input_stream:
+
+       try:
+
+self.audio_input_stream.stop_stream()
+
+self.audio_input_stream.close()
+
+self.audio_input_stream = None
+
+       except Exception as e:
+```
+
+`logger.error(f"` 关闭输入流错误 `: {e}")`
+
+```
+     if self.audio_output_stream:
+
+       try:
+
+self.audio_output_stream.stop_stream()
+
+self.audio_output_stream.close()
+
+self.audio_output_stream = None
+
+       except Exception as e:
+```
+
+`logger.error(f"` 关闭输出流错误 `: {e}")`
+
+`#` 终止 `PyAudio`
+
+```
+     if self.pyaudio_instance:
+
+       try:
+
+self.pyaudio_instance.terminate()
+
+self.pyaudio_instance = None
+
+       except Exception as e:
+```
+
+`logger.error(f"` 终止 `PyAudio` 错误 `: {e}")`
+
+`logger.info("` 清理完成 `")`
+
+```
+  def send_audio_played_event(self):
+
+     if not self.websocket:
+
+```
+
+`logger.error("WebSocket` 未连接,无法发送音频播放完成事件 `")`
+
+```
+       return
+
+audio_played_payload = {
+
+       "event": "audio.played",
+
+       "payload": {}
+
+}
+
+```
+
+### 原始逐行文本重排
+
+535       def cleanup(self):
+536        """清理所有资源"""
+537         logger.info("正在清理资源")
+538
+539       # 停止录制和播放
+540           self.stop_recording()
+541
+542           with self.lock:
+543               self.player_running = False
+544
+545       # 关闭音频流
+546           if self.audio_input_stream:
+547               try:
+548                   self.audio_input_stream.stop_stream()
+549                   self.audio_input_stream.close()
+550                   self.audio_input_stream = None
+551               except Exception as e:
+552               logger.error(f"关闭输入流错误: {e}")
+553
+554           if self.audio_output_stream:
+555               try:
+556                   self.audio_output_stream.stop_stream()
+557                   self.audio_output_stream.close()
+558                   self.audio_output_stream = None
+559               except Exception as e:
+560               logger.error(f"关闭输出流错误: {e}")
+561
+562       # 终止PyAudio
+563           if self.pyaudio_instance:
+564               try:
+565                   self.pyaudio_instance.terminate()
+566                   self.pyaudio_instance = None
+567               except Exception as e:
+568                 logger.error(f"终止PyAudio错误: {e}")
+569
+570         logger.info("清理完成")
+571
+572       def send_audio_played_event(self):
+573       """发送音频播放完成事件到服务器"""
+574           if not self.websocket:
+575           logger.error("WebSocket未连接,无法发送音频播放完成事件")
+576               return
+577
+578           audio_played_payload = {
+579               "event": "audio.played",
+580               "payload": {}
+581          }
+
+## Page 48
+
+### 结构化抽取
+
+```
+     try:
+
+self.websocket.send(json.dumps(audio_played_payload))
+```
+
+`logger.info("` 已发送音频播放完成事件 `")`
+
+```
+     except Exception as e:
+```
+
+`logger.error(f"` 发送音频播放完成事件错误 `: {e}")`
+
+```
+def main():
+
+client = AudioClient()
+
+  try:
+
+```
+
+`logger.info(f"` 初始化 `")`
+
+`#` 设置 `WebSocket`
+
+```
+ws = websocket.WebSocketApp(
+
+WS_SERVER_URL,
+
+on_open=client.on_websocket_open,
+
+on_message=client.on_websocket_message,
+
+on_error=client.on_websocket_error,
+
+on_close=client.on_websocket_close
+
+)
+
+```
+
+`logger.info(f"` 正在连接到服务器 `: {WS_SERVER_URL}")`
+
+```
+ws.run_forever()
+
+  except KeyboardInterrupt:
+```
+
+`logger.info("` 用户中断,退出 `")`
+
+```
+  except Exception as e:
+```
+
+`logger.error(f"` 主函数错误 `: {e}")`
+
+```
+  finally:
+
+client.cleanup()
+
+if __name__ == "__main__":
+
+main()
+
+```
+
+1. 将开始事件"inbound_attributes.cfg" 中format参数 设置为 opus codec 设置为 raw
+
+### 原始逐行文本重排
+
+582
+  583           try:
+  584               self.websocket.send(json.dumps(audio_played_payload))
+  585           logger.info("已发送音频播放完成事件")
+  586           except Exception as e:
+  587           logger.error(f"发送音频播放完成事件错误: {e}")
+  588
+  589   def main():
+  590     """启动客户端的主函数"""
+  591    # 创建客户端实例
+  592       client = AudioClient()
+  593
+  594       try:
+  595       # 连接到服务器
+  596          logger.info(f"初始化")
+  597       # 设置WebSocket
+  598           ws = websocket.WebSocketApp(
+  599               WS_SERVER_URL,
+  600               on_open=client.on_websocket_open,
+  601               on_message=client.on_websocket_message,
+  602               on_error=client.on_websocket_error,
+  603               on_close=client.on_websocket_close
+  604          )
+  605
+  606       # 连接到服务器
+  607         logger.info(f"正在连接到服务器: {WS_SERVER_URL}")
+  608           ws.run_forever()
+  609       except KeyboardInterrupt:
+  610         logger.info("用户中断,退出")
+  611       except Exception as e:
+  612         logger.error(f"主函数错误: {e}")
+  613       finally:
+  614           client.cleanup()
+  615
+  616   if __name__ == "__main__":
+  617       main()
+
+OPUS音频处理相关
+
+客户端发送opus 音频
+
+1. 将开始事件"inbound_attributes.cfg" 中format参数 设置为 opus codec 设置为 raw
+
+2. 客户端需要发送libopus编码后的原始opus音频、不需要任何容器封装
+
+## Page 49
+
+### 结构化抽取
+
+1. 将开始事件"outbound_attributes.cfg.format"参数设置为 opus
+
+2. 服务端返回 无任何封装的 opus帧。每次返回 60ms 的opus 压缩帧
+
+### 原始逐行文本重排
+
+服务端发送opus音频
+
+1. 将开始事件"outbound_attributes.cfg.format"参数设置为 opus
+
+2. 服务端返回 无任何封装的 opus帧。每次返回 60ms 的opus 压缩帧
+
+解码demo
+
+```
+def decode_opus(self, opus_data):
+"""
+将原始Opus帧解码为PCM格式(无容器封装)
+4
+参数:
+opus_data: 原始Opus编码的音频数据(单帧,无容器封装)
+7
+返回:
+解码后的PCM数据
+"""
+if not self.opus_decoder or not opus_data:
+logger.warning("Opus解码器不可用或数据为空")
+return b''
+14
+try:
+# 直接解码原始Opus数据帧(每次收到的都是一个完整的Opus帧)
+pcm_data = self.opus_decoder.decode(opus_data, OPUS_FRAME_SIZE)
+18
+if pcm_data:
+logger.debug(f"原始Opus帧解码成功: 输入{len(opus_data)}字节 -> 输
+出{len(pcm_data)}字节")
+return pcm_data
+else:
+logger.warning(f"Opus帧解码失败,返回空数据。帧大小:
+{len(opus_data)}字节")
+return b''
+25
+except Exception as e:
+logger.error(f"Opus帧解码错误: {e},帧大小: {len(opus_data)}字节")
+if len(opus_data) >= 8:
+logger.debug(f"帧头部数据: {opus_data[:8].hex()}")
+return b''
+31
+```
+
+## Page 50
+
+### 结构化抽取
+
+_本页未抽取到结构化文本。_
+
+### 原始逐行文本重排
+
+_本页未抽取到原始文本。_
+
+</details>