From 9c13d8a46905fdeda829e45db006020e05507c7c Mon Sep 17 00:00:00 2001 From: AskaEth Date: Tue, 27 Oct 2026 21:57:55 +0800 Subject: [PATCH] docs(contract): v0.98 outbound voice - speak tool budget, tts source, fallback marking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 模型侧 speak 工具（她的自主媒介决策）+ 字数预算公式 + 六错误码登记 - voice DTO: source 增 tts、fallbackReason（仅 failed 时）、四键同生共死含降级行 - 判据变更如实标注: voice 存在 && status != failed = 可播气泡; failed = 文字+降级小标 - QQ record 段真语音条（silk 待真机）与微信降级口径 --- Docs/api-client.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/Docs/api-client.md b/Docs/api-client.md index 768822e..86b919e 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -610,9 +610,9 @@ { "name": "web_search", "status": "ok", "durationMs": 1200, "argsSummary": "{\"query\":\"明天天气\"}", "resultSummary": "晴，18~26℃" } ], - "voice": { // v0.67 登记，v0.79 已实现（切片 L45）；非语音消息键缺席；🎤 判据 = 本键存在 - "source": "asr", // "asr"（服务端识别，含云端）| "platform"（渠道平台自带转写） - "status": "transcribed", // "transcribed" | "empty" | "failed"（闭集三态） + "voice": { // v0.67 登记，v0.79 已实现（切片 L45）；v0.98 起也承载她的出站语音；非语音消息键缺席；🎤 判据 = 本键存在 && status != "failed"（v0.98） + "source": "asr", // "asr"（服务端识别，含云端）| "platform"（渠道平台自带转写）| "tts"（她的出站合成语音，v0.98） + "status": "transcribed", // "transcribed" | "empty" | "failed"（闭集三态；failed 时 fallbackReason 可选在场，v0.98） "name": "a1b2c3….ogg", // 音频副本存储名；无副本 ⇒ 键省略 "mime": "audio/ogg", "size": 12345, @@ -649,9 +649,9 @@ **`voice` 语义（v0.67 登记；✅ **v0.79 已实现**，切片 L45 —— 覆盖率见本节末）**： -- 形状：`{source,status,name?,mime?,size?,durationMs?,url?}`，`omitempty`（**非语音消息键缺席**，与引入语音前逐字相同）。 -- **🎤 判据 = `voice` 键存在**（这条消息来自一条语音消息）。客户端**绝不**从 `content` 正文里认媒体类型：QQ 语音正文里那个 `[语音]` 占位标记自 v0.67 起**不再下发**（见 §6 的 v0.67 行为变更），正文里也可能出现用户自己打出的 `[语音]` 字样。**只认 `voice` 键**。 -- `source` ∈ `"asr"`（服务端语音识别所得，含云端）/ `"platform"`（渠道平台自带转写，微信 iLink 的 `voice_item.text`）。 +- 形状：`{source,status,name?,mime?,size?,durationMs?,url?,fallbackReason?}`，`omitempty`（**非语音消息键缺席**，与引入语音前逐字相同；`fallbackReason` 仅 `status=="failed"` 时在场，v0.98）。 +- **🎤 判据 = `voice` 键存在 && `status != "failed"`（v0.98 起）**（这条消息是一条可播放的语音）。🔴 **v0.98 变更**：出站降级行（她请求语音但 TTS 超时/失败转文字）与入站转写失败行都是 `status:"failed"` 且**不可播**——按旧判据（仅键存在）会被误渲染成语音气泡；`status=="failed"` 的行按**文字消息 + 降级小标**显示（`fallbackReason` 如 `"tts_timeout"` 可做特殊提示）。客户端**绝不**从 `content` 正文里认媒体类型：QQ 语音正文里那个 `[语音]` 占位标记自 v0.67 起**不再下发**（见 §6 的 v0.67 行为变更），正文里也可能出现用户自己打出的 `[语音]` 字样。 +- `source` ∈ `"asr"`（服务端语音识别所得，含云端）/ `"platform"`（渠道平台自带转写，微信 iLink 的 `voice_item.text`）/ **`"tts"`（v0.98：她的出站合成语音——她调了模型侧 `speak` 工具且合成成功；播放与入站语音走同一 `GET /api/v1/media/{name}`）**。 - `status` ∈ `"transcribed"`（正文即转写文本）/ `"empty"`（转写成功但没识别出文字）/ `"failed"`（没拿到转写文本 —— 正文是那行中文诚实提示）。**客户端按 `status` 分支，绝不按正文文案分支**（§0.3 的同一纪律）。设计还**刻意不下发** `failed` 的机器可读细分（未配置 / 鉴权 / 欠费 / 限流 / 超时 / 格式不支持 / 无字节 ⇒ 分类只进服务端日志，正文给的是人读的原因方向）。 - `name` / `mime` / `size` / `url` **四者同生共死**：有音频副本时全在，**无副本时全缺席**（**不会**出现 `url` 指着一个不存在的 `name` 这种形状）。 - `durationMs` **只有渠道如实给出时才有**；读不出来就**省略键，绝不估算**（当前未确证各渠道是否都给得出，见 design/24 §10.12-8）。 @@ -1583,7 +1583,19 @@ curl -s -X POST -H "X-API-Key: $KEY" \ > 只保留最近若干版（**v0.60 起**）；更早的全部历史见归档 `Docs/archive/api-client.v0.65.md` §5（v0.28 → v0.59）。 > 每版一句话 + 三档标注。**三档定义见 [§0.4](#04-三档标注惯例)。** -### v0.97（当前契约版本） +### v0.98（当前契约版本） + +**「她的出站语音」版（M57 / M58 / M59；一处判据变更如实标注，其余纯增量）** + +- **模型侧新工具 `speak`**（不是客户端端点，客户端零新调用）：她自主决定某条回复用**语音**发。参数 `{text, emotion?}`；执行 = 按字数算超时预算（`clamp(3000 + 25×rune, 3000, 20000)` ms，`utf8.RuneCountInString` 一字一算）→ emotionTTS（发音人按生效人格，v0.96 链不动）→ 成功落音频副本（内容寻址 0600）；**超时/失败返回结构化错误**（`tts_timeout` / `tts_failed` / `tts_no_audio` / `tts_store_failed` / `text_too_long` / `not_configured`，均带预算与实际耗时）——她能在后续输出里读到成败并自然改用文字。 + - 🔴 **speak 豁免能力收缩**（quiet/awake 等状态也广告）但**不豁免安全门**：群聊/陌生人在工具策略面按「未知工具」deny（fail-closed，design/11 §3）、owner 恒放行；「群聊是否放行 speak」留待后续裁决。 + - ⚠️ `OutboundVoice.DurationMs` 恒 `0`（本版不解析音频时长）；客户端**不得**以 `durationMs==0` 判定失败。 +- **出站 `voice` 落列与降级标记（M58）**：她请求语音且合成成功 ⇒ assistant 消息的 `voice` 列写 `{source:"tts", status:"transcribed", name, mime, size, durationMs}`（**与入站 DTO 形状一致**，`source` 新值 `"tts"` = 她说的合成语音；`url` 由网关派生，规则同入站）；**她请求了但降级**（超时/失败）⇒ 写 `{source:"tts", status:"failed", fallbackReason}`（如 `"tts_timeout"`）——**`name`/`mime`/`size`/`url` 四键整体缺席**，正文照发文字。降级事实**随消息落库**（不只实时帧）——历史回看可见。 +- 🔴 **判据变更（唯一 breaking，如实标注）**：🎤 判据从「`voice` 键存在」改为 **「`voice` 键存在 && `status != "failed"` = 可播语音气泡；`status == "failed"` = 文字消息 + 降级小标**（`fallbackReason` 供特殊显示，如「语音超时，已转文字」）。**入站同样适用**：入站转写失败的行本就是 `status:"failed"` 且不可播——判据统一后语义更干净。旧判据客户端会把降级行误渲染成语音气泡。 +- **渠道侧（M59）**：QQ OneBot v11 以 `record` 段发**真语音条**（`base64://` 内联首选，Napcat 自行转 silk；真机 silk 效果**待验证**）；微信 iLink 无语音发送能力 ⇒ 该渠道降级纯文本（但全端语音副本仍可见——IM 文本与 Web/安卓语音气泡并存）。**出站 Media 由语音事实单独构造**，绝不透传入站 Media（2026-10-04 事故纪律）。 +- **全部读面自动生效**：`source` 闭集在 `voice` 包单点（`asr`/`platform`/`tts`）；REST 读面 / 实时帧 / 握手回放 / `message_edited` 经同一投影点 `attachVoiceTo`，首帧即带（M44 顺序纪律沿用）。 + +### v0.97 **「语音帧补全 + 上游错误出口收敛」版（M44 / M47 / M49 / M50；以纯增量为主，一处行为变更如实标注）** @@ -2017,7 +2029,7 @@ curl -s -X POST -H "X-API-Key: $KEY" \ - **纯增量**： ① 新端点 `GET /api/v1/media/{name}`（用户侧，**owner/admin 必须 Bearer**）：`200` 字节流 / `206 Partial Content` / `304 Not Modified`；`Content-Type: audio/*`；`Content-Disposition: inline; filename=""`；`nosniff`；`Accept-Ranges: bytes`；`Cache-Control: private, max-age=86400, immutable`；支持 `Range` 与 `HEAD`；`404 media_not_found`；`401`/`403` 由中间件给出。⚠️ **`416` 是标准库直写的非 JSON 响应**（见 §0.3、§4.1、§4.5）。 - ② 消息 DTO 增**可选** `voice` 对象（`omitempty`；**非语音消息键缺席**）：`{source,status,name?,mime?,size?,durationMs?,url?}`；`source` ∈ `asr`/`platform`，`status` ∈ `transcribed`/`empty`/`failed`，`name`/`mime`/`size`/`url` **四者同生共死**（有副本时才在）；`url` 是服务端相对路径 `/api/v1/media/`。**🎤 判据 = `voice` 键存在**。⚠️ **v0.79 校正（实测覆盖）**：真正会带 `voice` 的读取面**只有** `GET /sessions/{id}/messages`、`GET /admin/channels[/{platform}]/messages`、`PATCH /messages/{id}` 响应与 `message_edited`；**`message_persisted` / `channel_persisted` 与握手 `history` 回放不带**（✅ **已由 v0.97（切片 M44）补齐**，见 §3.2、§3.4.4、§4.4 覆盖率）。 + ② 消息 DTO 增**可选** `voice` 对象（`omitempty`；**非语音消息键缺席**）：`{source,status,name?,mime?,size?,durationMs?,url?}`；`source` ∈ `asr`/`platform`（🔴 **v0.98 增 `tts`** = 她的出站合成语音，含 `fallbackReason` 降级标记与判据变更，见 §4.4 / §6 v0.98），`status` ∈ `transcribed`/`empty`/`failed`，`name`/`mime`/`size`/`url` **四者同生共死**（有副本时才在；**降级行四键整体缺席**）；`url` 是服务端相对路径 `/api/v1/media/`。**🎤 判据 = `voice` 键存在 && `status != "failed"`（v0.98 起）**。⚠️ **v0.79 校正（实测覆盖）**：真正会带 `voice` 的读取面**只有** `GET /sessions/{id}/messages`、`GET /admin/channels[/{platform}]/messages`、`PATCH /messages/{id}` 响应与 `message_edited`；**`message_persisted` / `channel_persisted` 与握手 `history` 回放不带**（✅ **已由 v0.97（切片 M44）补齐**，见 §3.2、§3.4.4、§4.4 覆盖率）。 ③ 新错误码 **`media_not_found`（404）** → 加进 §4.1 的 404 行（与 `document_not_found` 并列；**刻意不复用**它，否则客户端分不清缺的是文档还是语音）。 ④ 新错误形态 **`416`**（**非信封**，标准库直写）→ §0.3 / §4.1 / §4.5。 ⑤ 新 admin 端点 **`GET /api/v1/admin/channels/events`**（非消息事件列表，倒序；`?platform=&tier=&category=&channelId=&since=&until=&limit=&offset=`；响应 `{data:{events:[…],total}}`；`since`/`until` 按 UTC ISO-8601 定宽字符串**字典序**比较、**跨度上限 90 天**；不含正文、不含媒体 URL、不含任何凭据 / `flag`）—— §2.4(a)。**已落地**（`owner|admin` 档；元素键名 camelCase，逐字见 §2.4(a)；未给窗口 ⇒ 不注入窗口）。 @@ -2243,4 +2255,4 @@ curl -s -X POST -H "X-API-Key: $KEY" \ --- -*本文件由「以代码为真源」维护（当前 `v0.97`；`v0.96` ~ `v0.68` 见本文件 §6，`v0.67` 及更早见本文件 §6 与 `Docs/archive/`）。范围：`v0.97`（三面 —— M44 `voice` 进 WS 实时帧/握手回放 / M47 emotionTTS 自启（默认关）/ M49+M50+M48+M52 上游错误出口「构造即安全」）同步了 `internal/services/gateway/**`（`broadcast.go` / `history_voice.go` / `ws_history.go` 及 `broadcast_voice_test.go`）、`internal/services/channelbridge/**`（`persist.go` / `inbound_voice_copy.go` / `coalesce_batch.go` 及 `inbound_voice_gateway_e2e_test.go`）、`cmd/cyrene/**`（`voice_tts_launch.go` 及测试 / `main.go`）、`internal/config/runtimeconfig/voice_tts_launch.go`、`internal/runtime/voice/ttslaunch/**`、`internal/runtime/trace/**`（`upstream.go` 等）与本文件（§3.2 / §4.4 / §4.5 / §6 / §7.2 / §7.4）；`v0.96` ~ `v0.82` 各版的文件级范围见各自 §6 条目；更早版本（`v0.81` ~ `v0.68`）的文件级范围按原记录保留如下：`v0.81` 同步了 backthink/flowgraph/gateway 的自排轮可见面；`v0.80` 同步了 flowgraph timeline、websearch 热重载、wire_channels 的 VoiceTranscoder 注入；`v0.79` 同步了 plugin actions、memory review、history_voice、media、CODE-TC-2；`v0.78` 同步了迁移 0020/0023、voice 包、channelbridge inbound_voice、panels、iLink 三态；`v0.77` 同步了 trace graph 分桶、loop/flow、memory tidy、admin_flow；`v0.76` 的未读面同步了 broadcast/session_read；`v0.75` ~ `v0.71` 同步了 memory tidy、proactive、flowgraph、loop 各面（详见归档）。* +*本文件由「以代码为真源」维护（当前 `v0.98`；`v0.97` ~ `v0.68` 见本文件 §6，`v0.67` 及更早见本文件 §6 与 `Docs/archive/`）。范围：`v0.98`（她的出站语音 —— M57 `speak` 工具 + 字数预算 / M58 出站 voice 落列 + 降级标记 + 判据变更 / M59 QQ record 段）同步了 `internal/runtime/loop/**`（`speak_tool.go` / `voice.go` / `request.go` / `tools*.go` 及测试）、`internal/runtime/voice/voice.go`（`SourceTTS` / `Ref.FallbackReason`）、`internal/services/channelbridge/**`（`outbound_voice.go` 及 e2e / `bubbles.go` / `inbound*.go` / `persist*.go` / `proactive*.go`）、`internal/services/gateway/history_voice.go`、`plugins/channels/qq_obv11/outbound_segments.go` 及测试与本文件（§4.4 / §6 / 旧横幅加注）；`v0.97` ~ `v0.82` 各版的文件级范围见各自 §6 条目。*