@henjicc/ai-sdk 0.6.0 → 0.6.2

package/docs/model-adaptation/Fun-ASR-Realtime/Fun-ASR-Realtime_/347/231/276/347/202/274.md

@@ -2,7 +2,7 @@
 
 | 项目 | 内容 |
 |---|---|
-| 最后更新 | 2026-08-28 |
+| 最后更新 | 2026-09-24 |
 | 能力 | 实时语音识别（WebSocket） |
 | 平台模型 ID | `fun-asr-realtime`（稳定别名，官方当前等同 `fun-asr-realtime-2025-11-07`） |
 | 地域 | 华北2（北京）、新加坡 |
@@ -26,7 +26,27 @@
 
 Say-It 保留该稳定别名与 2026-02-28 快照供用户选择；SDK 不应自行把稳定别名锁定为某快照。空 `sentence_begin` 事件只推进状态，不产生 partial/final；重复 final 只累计一次。取消时主动关闭 socket，密钥和原始音频不记日志。
 
-## 4. 原始链接索引
+## 4. 服务端事件矩阵（fun-duplex 家族）
+
+2026-09-24 核对官方服务端事件页。此协议也服务于 `qwen-audio-3.1-asr-flash-streaming`，错误诊断必须标实际模型，不能统一叫 Fun-ASR。样本见 `tests/fixtures/bailian/asr-realtime-fun.json`，0.6.1 真实验证的空中间帧保持原语义。
+
+共享百炼实时驱动在握手发送失败时也返回已归一化的模型/协议/阶段；关闭连接若再次失败，以 `cleanupFailed=true` 补充首个故障，不覆盖原因为原始宿主异常。该边界由 `bailian-realtime-asr.test.ts` 的双故障 Mock 回归保护，同时用于 `fun-duplex` 与 `qwen-realtime`。
+
+| 事件 | 前置阶段与字段语义 | 迁移 / 输出 | 结束与资源 |
+|---|---|---|---|
+| `task-started` | opening，run-task 已发 | active / started | 继续 |
+| `result-generated` 心跳 | sentence.heartbeat=true，官方明确可跳过 | 无文本、无完成迁移 | 继续 |
+| `result-generated` 中间帧 | active/finishing；text 字符串、sentence_end=false；仅首帧可有 sentence_begin | 空 text 等待，有文字 partial | 继续 |
+| `result-generated` 句终帧 | active/finishing；text 字符串、sentence_end=true | 非空 final，保存时间戳与用量；重复相同 final 不重复累计 | 继续等待任务结束 |
+| `task-finished` | finishing；payload 通常空，无须含 text | 使用累计 final；未收到有效 final 则 invalid_response | SDK 关闭；官方允许以新 task_id 复用 |
+| `task-failed` | 任一未终止阶段；header.error_code/error_message | provider_task_failed，保留 code，不默认记录完整 message | 关闭，不复用 |
+| 缺失事件名、text 或布尔 sentence_end | 不用非空文字掩盖缺失状态；心跳除外 | invalid_response | 失败并释放 |
+| 有名未知扩展 | 官方未定义行为 | 脱敏警告，无文本/完成输出 | 等待已知终态 |
+| 提前断开 / 取消 | 无最终完成证据 | 断连错误或取消 | 释放连接，不重放计费请求 |
+
+校验不要求中间帧带 sentence_begin，也不要求心跳带文本。合法空中间帧不会被当失败；空 final 和只有 partial 的任务仍不能成功。
+
+## 5. 原始链接索引
 
 | 信息 | 链接 | 登录 |
 |---|---|---|

package/docs/model-adaptation/Qwen-MT-Flash/Qwen-MT-Flash_/347/231/276/347/202/274.md

@@ -2,7 +2,7 @@
 
 | 项目 | 内容 |
 |---|---|
-| 最后更新 | 2026-08-28 |
+| 最后更新 | 2026-09-24 |
 | 能力 | 文本翻译（增量流式 / 非流式） |
 | 平台模型 ID | `qwen-mt-flash` |
 | 地域 | 北京、新加坡、美国（弗吉尼亚）、德国（法兰克福）；以区域模型实际开通为准 |
@@ -35,13 +35,34 @@ Authorization: Bearer <API Key>
 - 按需入口：`@henjicc/ai-sdk/capabilities/translation/bailian`，工厂 `createQwenMtFlashTranslationModule()`。
 - 默认走 OpenAI 兼容 Chat Completions 并开启 SSE；将官方增量块统一成 `delta(mode=append)`，最终输出完整 `item`，Token 计入 `usage`。
 - Say-It 当前保存的常用语言代码会先映射为官方英文语言名；术语表映射到 `terms`，翻译记忆映射到 `tm_list`，通用 `context` 映射到英文领域提示 `domains`。
-- 未核实的独立最大输出数不设默认值，也不发送 `max_tokens`。当前只有官方示例 fixture/单测证据，尚无真实付费请求证据。
+- 未核实的独立最大输出数不设默认值，也不发送 `max_tokens`。当前只有官方示例 fixture/单测证据，尚无真实付费请求证据。
+
+### 三模型共享事件契约与回归矩阵（2026-09-24）
+
+本节只复核响应及生命周期，价格和输入上限未重新调研。依据同页 OpenAI 兼容 API 的流式/非流式响应定义：Flash/Lite 增量、Plus 累积；生成中 `finish_reason=null`，自然结束为 `stop`，长度截断为 `length`。官方样例包含空首帧、两次相同 `stop` 帧及 `choices=[]` 用量帧。
+
+| 事件/序列 | SDK 行为 | 回归依据 |
+|---|---|---|
+| 空 `content` 中间块、连续增量/累积内容 | 等待或更新部分结果，不报失败 | 官方 fixture；既有三模型测试 |
+| 重复 `stop` + 独立 usage + DONE/正常 EOF | 只产出一次完整 item；累计模型重复最终快照不重复追加 | fixture 补齐官方重复结束块；生命周期测试 |
+| 空 `choices` 且有用量 | 用量通知，不作为完成依据 | 官方 usage 块 |
+| 部分结果后 DONE/EOF、末块无空行 | 缺少可分发最终块时报 `provider_response_invalid`；不补造 SSE 空行 | 删除结束块/截断分隔符的受控变异 |
+| `length`（流式及非流式） | `provider_task_failed`，details 保留 `finishReason=length`；不把截断译文作为完整 item | 官方枚举的受控变异 |
+| 缺少 choices/content/结束原因，字段错类型，最终内容继续变化 | 明确拒绝，不作为空状态通知跳过 | 从官方结果块移除或替换字段 |
+| 错误对象缺少 code、SSE `event:error`、HTTP 错误 | 明确失败，保留实际模型/协议/阶段及安全错误码；不默认输出原始 message | 错误 envelope 的受控注入 |
+| 未知具名 SSE 扩展事件 | 不提供成功或失败依据；继续等已知协议结果 | 扩展通知 + 正常/缺失结束序列 |
+| 取消、断流、回调失败、DONE 后连接未关闭 | 中止或失败，取消剩余流并释放锁；取消后不再发送 item/completed | Mock 流与取消回放 |
+
+`content` 必须是字符串，但不凭经验添加“最终译文必须非空”的限制；空输入本地短路仍受取消约束。SSE 分帧与聊天共用 `src/protocols/sse-events.ts`，结果校验和增量/累积语义保持在各适配器内。
+
+证据：`tests/fixtures/bailian-translation/official-qwen-mt-examples.json`、`tests/bailian-qwen-mt.test.ts`、`tests/bailian-qwen-mt-lifecycle.test.ts`。负例是明确标注的受控变异，不声称来自真实付费请求。
 
 ## 5. 原始链接索引
 
 | 信息 | 链接 | 登录 |
 |---|---|---|
-| API/请求/响应 | https://help.aliyun.com/zh/model-studio/qwen-mt-api | 否 |
+| API/请求/响应 | https://help.aliyun.com/zh/model-studio/qwen-mt-api | 否 |
+| SSE 分帧与 EOF | https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation | 否 |
 | 选型/语言/限制 | https://help.aliyun.com/zh/model-studio/machine-translation | 否（本次访问触发验证码，未取正文） |
 | 价格 | https://help.aliyun.com/zh/model-studio/model-pricing | 否 |
 | API Key | https://bailian.console.aliyun.com/?apiKey=1#/api-key | **是** |

package/docs/model-adaptation/Qwen-MT-Lite/Qwen-MT-Lite_/347/231/276/347/202/274.md

@@ -2,7 +2,7 @@
 
 | 项目 | 内容 |
 |---|---|
-| 最后更新 | 2026-08-28 |
+| 最后更新 | 2026-09-24 |
 | 能力 | 文本翻译（增量流式 / 非流式） |
 | 平台模型 ID | `qwen-mt-lite` |
 | 地域 | 北京、新加坡、美国（弗吉尼亚）、德国（法兰克福）；以实际开通为准 |
@@ -27,7 +27,8 @@ OpenAI 兼容 `POST /compatible-mode/v1/chat/completions` 或 DashScope `POST /a
 - 按需入口：`@henjicc/ai-sdk/capabilities/translation/bailian`，工厂 `createQwenMtLiteTranslationModule()`。
 - 默认走 OpenAI 兼容 SSE；官方增量块归一为追加事件，使用 SDK 自带 UTF-8 增量解码器，不要求 UXP 等宿主提供 `TextDecoder`。
 - 支持 usage、术语、翻译记忆、领域提示、Say-It 常用语言代码兼容；密钥、原文和译文不写入结构化日志。
-- 未核实的独立最大输出数不设默认值，也不发送 `max_tokens`。当前只有官方示例 fixture/单测证据，尚无真实付费请求证据。
+- 未核实的独立最大输出数不设默认值，也不发送 `max_tokens`。当前只有官方示例 fixture/单测证据，尚无真实付费请求证据。
+- 2026-09-24 复核结束语义、合法空帧、用量、错误、截断及取消；详见 [三模型共享事件契约与回归矩阵](../Qwen-MT-Flash/Qwen-MT-Flash_百炼.md#三模型共享事件契约与回归矩阵2026-09-24)。Lite 保持增量拼接，错误诊断保留实际 `qwen-mt-lite` 模型名。
 
 ## 4. 原始链接索引
 

package/docs/model-adaptation/Qwen-MT-Plus/Qwen-MT-Plus_/347/231/276/347/202/274.md

@@ -2,7 +2,7 @@
 
 | 项目 | 内容 |
 |---|---|
-| 最后更新 | 2026-08-28 |
+| 最后更新 | 2026-09-24 |
 | 能力 | 文本翻译（非流式 / 累积流式） |
 | 平台模型 ID | `qwen-mt-plus` |
 | 地域 | 北京、新加坡、美国（弗吉尼亚）、德国（法兰克福）；以实际开通为准 |
@@ -27,7 +27,8 @@ OpenAI 兼容 `POST /compatible-mode/v1/chat/completions` 或 DashScope `POST /a
 - 按需入口：`@henjicc/ai-sdk/capabilities/translation/bailian`，工厂 `createQwenMtPlusTranslationModule()`。
 - 默认走 OpenAI 兼容 SSE；SDK 对官方累积序列计算前缀差，正常情况统一发 `delta(mode=append)`，供应商改写既有前缀时明确发 `mode=replace`，最终 `item` 始终是完整译文。
 - 支持单条/带稳定 id 的批量输入、usage 汇总、术语、翻译记忆、领域提示以及 Say-It 常用语言代码兼容。
-- 未核实的独立最大输出数不设默认值，也不发送 `max_tokens`。当前只有官方示例 fixture/单测证据，尚无真实付费请求证据。
+- 未核实的独立最大输出数不设默认值，也不发送 `max_tokens`。当前只有官方示例 fixture/单测证据，尚无真实付费请求证据。
+- 2026-09-24 复核结束语义、合法空帧、重复最终快照、用量、错误、截断及取消；详见 [三模型共享事件契约与回归矩阵](../Qwen-MT-Flash/Qwen-MT-Flash_百炼.md#三模型共享事件契约与回归矩阵2026-09-24)。Plus 仍按累积快照计算变化；只有 `stop` 才交付完整 item，`length` 明确报告截断。
 
 ## 4. 原始链接索引
 

package/docs/model-adaptation/Qwen3-ASR-Flash-Realtime/Qwen3-ASR-Flash-Realtime_/347/231/276/347/202/274.md

@@ -2,7 +2,7 @@
 
 | 项目 | 内容 |
 |---|---|
-| 最后更新 | 2026-08-28 |
+| 最后更新 | 2026-09-24 |
 | 能力 | 实时语音识别（WebSocket，VAD/Manual） |
 | 平台模型 ID | `qwen3-asr-flash-realtime`（稳定别名，官方当前等同 `qwen3-asr-flash-realtime-2025-10-27`） |
 | 地域 | 华北2（北京）、新加坡 |
@@ -24,7 +24,30 @@
 
 稳定别名与 2026-02-10 快照并列注册；不把官方当前指向的 2025-10-27 快照写死到请求构建器。该序列与 Fun-ASR 事件序列分开实现。
 
-## 4. 原始链接索引
+## 4. 服务端事件矩阵（稳定别名与 2026-02-10 快照共用）
+
+2026-09-24 核对官方服务端事件页，字段表构造样本见 `tests/fixtures/bailian/asr-realtime-qwen.json`。ID 和文本均为固定占位；删字段、改类型为测试中的 synthetic-negative，不代表真实供应商响应。
+
+| 事件 | 前置阶段与字段语义 | 迁移 / 输出 | 结束与资源 |
+|---|---|---|---|
+| `session.created` | opening；服务端默认 session，可含 null 配置 | 发送 update，等待 ready；不输出文字 | 继续 |
+| `session.updated` | opening；update 成功确认 | active，通知 started | 继续 |
+| `input_audio_buffer.speech_started` | VAD 检测语音；item_id 字符串、audio_start_ms 非负整数 | 已知状态通知，无文本 | 继续 |
+| `input_audio_buffer.speech_stopped` | VAD 停止语音；item_id 字符串、audio_end_ms 非负整数 | 已知状态通知，不当作 final | 继续 |
+| `input_audio_buffer.committed` | 音频提交确认；item_id 字符串 | 已知通知，不代替识别结果 | 继续 |
+| `conversation.item.created` | item 含 input_audio，transcript 固定为 null | 已知通知；item.status=completed 不等于识别完成 | 继续 |
+| `conversation.item.input_audio_transcription.text` | active/finishing；text/stash 均为字符串，任一可为空 | 原样 text + stash 作为 partial，不能分别 trim 破坏单词边界 | 继续 |
+| `conversation.item.input_audio_transcription.completed` | active/finishing；transcript 字符串 | final；不以未定义的 text 字段替代缺失 transcript | 句终态，仍等待会话结束 |
+| `conversation.item.input_audio_transcription.failed` | 某 item 识别失败；error.code/message | provider_task_failed，保留 code，不默认暴露完整 message | 失败并释放 |
+| `error` | 任一阶段；服务端或输入错误 | 同上，不能作为空事件忽略 | 失败并释放 |
+| `session.finished` | 仅客户端 finish 后；本事件无需 transcript | finishing → finished；使用累计 final，无有效 final 则 invalid_response | 主动断开，不复用 |
+| 有名未知事件 | 官方未定义扩展语义 | unknown 警告，不生成完成或文本 | 等待已有协议终态 |
+| 缺失 type / 错类型 / 无效必要结果字段 | 不能判定合法事件 | invalid_response，包含实际 model/protocol/阶段 | 失败并释放 |
+| 提前断开 / 取消 | 任一未完成阶段；无协议恢复事件 | 断连错误或取消，不当正常完成 | 关闭连接 |
+
+官方展示了 text 空而 stash 非空、以及相反的中间状态，未提供两者同时为空的有效结果示例；本次不据推测放宽该边界。现有 SDK 对有效 final 的要求仍是非空 transcript。状态通知不能掩盖缺失必要状态字段；不把所有未知扩展视为错误。错误诊断仅包含模型、协议、阶段、事件类型与供应商代码，不包含密钥、音频和完整识别/错误正文。
+
+## 5. 原始链接索引
 
 | 信息 | 链接 | 登录 |
 |---|---|---|

package/docs/model-adaptation/SeedASR-2.0-Realtime/SeedASR-2.0-Realtime_/347/201/253/345/261/261/345/274/225/346/223/216.md

@@ -2,7 +2,7 @@
 
 | 项目 | 内容 |
 |---|---|
-| 最后更新 | 2026-08-31 |
+| 最后更新 | 2026-09-24 |
 | 能力 | 双向实时语音识别（二进制 WebSocket） |
 | SDK `modelId` | `seedasr-2.0-realtime` |
 | 火山请求模型 | `request.model_name="bigmodel"` + 2.0 资源 ID `volc.seedasr.sauc.duration` |
@@ -105,14 +105,18 @@ SDK 对音频保留一块延迟：收到下一块时才把上一块以正 sequen
 | type `9`，非空 `result.text` | `partial` | 否 | 文本变化才发，重复内容去重 |
 | `result.utterances[].definite=true` | `final` | 否 | 表示句段已确定，不等于整个连接结束；按时间范围/文本去重 |
 | flag bit `2`（last） | `completed` | 是 | 只有客户端已 `finish()` 后才合法；输出 `result.text/utterances/audio_info.duration` |
-| type `15` | 无 | 是（错误） | 读取 uint32 错误码；错误 payload 可为 JSON 或安全 UTF-8 文本 |
+| type `15` | 无 | 是（错误） | 读取 uint32 错误码；错误 payload 可为 JSON 或 UTF-8 文本，默认异常/日志只保留错误码，不带原始 message |
 | 未知 `event` 数字 | 无 | 否 | 只记脱敏 warning，仍按 type/payload 处理 |
 | WebSocket 提前断开 | 无 | 是（错误） | `provider_connection_closed`，不误报完成 |
 | text WebSocket frame | 无 | 是（错误） | 协议要求二进制，报 `invalid_response` |
 
 `utterances[].definite=true` 只能判断句段 final，整个会话终态必须看帧头 last 标志。整个终帧仍无有效文本时严格报 `invalid_response`。
 
-用户主动取消只关闭连接，不发送负 sequence 终帧，也不把取消伪装成正常完成。full request 默认在 15 秒内必须收到首个服务端响应，可用 `openTimeoutMs` 显式调整；超时会关闭半开连接。`finish()`、连接释放和显式 `close()` 都幂等；发送失败、服务端错误、断线、超时和取消都走同一个释放边界。
+用户主动取消只关闭连接，不发送负 sequence 终帧，也不把取消伪装成正常完成。full request 默认在 15 秒内必须收到首个服务端响应，可用 `openTimeoutMs` 显式调整；超时会关闭半开连接。`finish()`、连接释放和显式 `close()` 都幂等；发送失败、服务端错误、断线、超时和取消都走同一个释放边界。
+
+同一响应帧可能同时产生 partial 与一个或多个 final。每次事件回调后重新检查取消/关闭，避免调用方在 partial 回调取消后，SDK 仍继续发出该帧的 final；该场景使用官方响应 payload 调整 last 标志构造，不代表新的供应商事件类型。
+
+2026-09-24 诊断复核：异常 details 保留实际 `modelId=seedasr-2.0-realtime`、`protocol=volcengine-binary-v1`、会话阶段、操作与最后一帧的序号/event/last 标志。原始服务端 message 和宿主异常可能包含识别内容或凭据，不进入默认诊断。握手失败后若关闭也失败，继续报告首个故障，并附 `cleanupFailed=true`。`volcengine-realtime-asr.test.ts` 使用既有官方帧结构、受控敏感文本错误与 Mock close 拒绝验证这些边界；不是额外真实服务实录。
 
 ## 5. 价格与免费额度
 

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//347/231/276/347/202/274.md

@@ -268,3 +268,15 @@ Qwen-MT 可通过 OpenAI 兼容 `POST /compatible-mode/v1/chat/completions` 或
 新增 keepDialect 和即时 vocabulary 参数；实时支持 vadModel。短音频说话人分离发送 speaker_diarization_enabled，文件转写发送 diarization_enabled。文件 channel_id 必须是整数数组，公共单声道选择 channelId 映射为 [channelId]；旧 Qwen3 file_url 契约不改变。短音频 sample_rate 按官方字符串发送，用户上下文 type=input_text。speakerId 作为可选公共输出字段，旧调用兼容。短音频按 tokens 计费，文件与实时不能沿用其 token 单价；未新增不可靠费用计算器。
 
 精确测试复用既有共享异步/实时失败、取消与释放测试，并补充 3.1 JSON/SSE、说话人分离、空 parameters 与新参数路由。样本区分字面与字段构造。
+
+### 2026-09-24 实时空文本中间帧实测补充
+
+以合成语音、合法 `SpeechRecognitionRealtimeStart` 在 SDK 0.6.0 直调 `qwen-audio-3.1-asr-flash-streaming`，复现句首事件之后继续返回 `text=""`、`sentence_end=false`、`end_time=null`、无 `sentence_begin` 的中间帧。官方事件页（https://help.aliyun.com/zh/model-studio/fun-asr-server-events，2026-09-24 核对）说明只有新句首个中间结果包含句首标记；空文本后续帧来自本次实测，并非官方字面示例。
+
+|事件|前置状态|字段与空值|状态/输出|错误与资源|
+|---|---|---|---|---|
+|空文本中间帧|任务已开始|text 是空字符串，sentence_end=false；sentence_begin 可省略，end_time 可为 null|保持会话，继续等待，不产生 partial/final|不关闭连接|
+|缺 text 或缺句子状态的无文本帧|任务已开始|缺字段/类型错误不能等同空字符串|invalid_response|失败并释放连接|
+|空 final 或全程无 final|任务已开始|sentence_end=true 但无文字，或 task-finished 前无 final|仍拒绝空结果|失败并释放连接|
+
+fixture `asr-realtime-fun.json.emptyIntermediate` 是实测脱敏结构。共享 Fun Duplex parser 的两个 Fun-ASR ID 与 Qwen-Audio 3.1 streaming 均沿同一规则；Qwen Realtime 独立解析器不受影响。

package/examples/llm-chat/README.md

@@ -1,6 +1,6 @@
 # llm-chat
 
-用 `@henjicc/ai-sdk@0.5.2` 的 `llm/streaming` 按需入口走 OpenAI-compatible SSE 流式对话，
+用 `@henjicc/ai-sdk@0.6.2` 的 `llm/streaming` 按需入口走 OpenAI-compatible SSE 流式对话，
 不会把 generation、BigModel preset/models/pricing、Groq 或 LLM modules 打进示例 bundle；
 通用端点身份解析所需的 BigModel profiles 仍会保留。默认目标是
 DeepSeek `deepseek-v4-flash`，提示词要求只回复 `SDK OK`，并限制最多 16 tokens。示例显式传入

package/examples/llm-chat/index.ts

@@ -30,7 +30,7 @@ class DryRunTransport implements Transport {
   async fetch(): Promise<Response> {
     this.calls += 1
     return new Response(
-      'data: {"choices":[{"delta":{"content":"SDK OK"}}]}\n\ndata: [DONE]\n\n',
+      'data: {"choices":[{"delta":{"content":"SDK OK"},"finish_reason":"stop"}]}\n\ndata: [DONE]\n\n',
       { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
     )
   }

package/examples/llm-chat/package.json

@@ -9,7 +9,7 @@
     "start": "npm run build && node dist/index.js --live"
   },
   "dependencies": {
-    "@henjicc/ai-sdk": "0.6.0"
+    "@henjicc/ai-sdk": "0.6.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henjicc/ai-sdk",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "痕迹AI 多供应商模型适配 SDK",
   "license": "Apache-2.0",
   "repository": {