@henjicc/ai-sdk 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.6.2 - 2026-09-24
+
+- 完善聊天与翻译 SSE 的事件边界和完成状态校验：保留合法空中间帧、用量与状态通知，提前结束、服务端错误和无效终态不再伪装成功；保留翻译增量/累积协议差异。
+- 修复百炼实时 ASR 字段校验、Qwen 中间文字拼接和状态通知处理；保留 0.6.1 空中间帧兼容，诊断包含实际模型、协议及失败阶段。
+- 收口共享实时会话的取消、超时、后台故障通知和资源释放；SDK 会话提供可选 result promise，旧自定义会话仍兼容。握手清理失败保留首个故障，火山服务错误默认脱敏。
+- 阻止聊天及火山实时识别在取消后继续派发同一帧的后续结果；明确智谱推理网络错误与上下文截断，扩展通知不冒充完成证据。
+- 增加脱敏事件序列回归并执行修复撤销验证，更新聊天示例的合法结束帧。未改变供应商配额、网络稳定性或模型识别质量。
+
 ## 0.6.1 - 2026-09-24
 
 - 修复百炼 Fun Duplex 实时识别把无句首标记的空文本中间帧误判为无效响应的问题；覆盖 Qwen Audio 3.1 streaming 与 Fun-ASR 共享协议。

package/README.md

@@ -48,10 +48,10 @@ try {
 
 百炼工厂必须传 `baseUrl` 为实际地域/工作空间的 API 根地址，不包含端点路径。其他供应商可以覆盖根地址与 `credentialId`；SDK 不自动切换地域或账号。不同模型的向量不能混用；切换模型通常需要重建向量索引。Rerank 分数仅在本次请求内比较。
 
-SDK `0.6.1` 的正式分发渠道为公共 npm，无需配置 registry 或访问令牌：
+SDK `0.6.2` 的正式分发渠道为公共 npm，无需配置 registry 或访问令牌：
 
 ```bash
-npm install @henjicc/ai-sdk@0.6.1
+npm install @henjicc/ai-sdk@0.6.2
 ```
 
 然后提供 4 个宿主能力（`Transport` / `CredentialStore` / `MediaReader` / `Logger`），创建客户端：
@@ -493,7 +493,20 @@ await capabilities.dispose()
 - `llm/bigmodel`：智谱同一 provider family 下的中国大陆/Global 端点 profile、独立凭据槽与 GLM-5.3-Flash 能力。
 - `llm/modules`：外部包、插件与内置 LLM 共用的注册、执行、发现、取消和 namespace 卸载边界。
 
-ASR module ID 固定为 `<providerId>.speech-recognition.<modelId>`，翻译固定为
+实时会话仍使用 `openSession → send → finish/close`。由 client 创建的会话额外提供 `result` Promise：
+它不主动发送 finish；在最终结果到达或后台失败、取消、超时、主动关闭，并完成资源收尾后结算。
+调用方可以观察 `session.result` 以获知停止发送音频期间的后台失败，不必等到下一次 `send/finish`。
+`finish()` 幂等且返回同一结果；正常关闭但没有最终结果时 `result` 拒绝 `realtime_session_closed`，
+取消是 `cancelled`，超时是 `timeout`，供应商失败保留原错误。未订阅该 Promise 不产生未处理拒绝，
+SDK 仍按现有日志契约记录失败。
+
+外部实时驱动可以提供可选 `result` Promise，致命后台/发送错误必须拒绝它，成功则返回有效最终结果。
+输入校验等可恢复的单次 send 错误只拒绝该调用，不应结束 result。旧驱动无需新增字段即可继续使用；
+如果旧驱动没有提供结果通道，SDK 无法自行发现它的后台失败。公共类型中的可选属性用于兼容旧会话实现。
+完成、失败、取消与关闭竞争时只结算一次；清理失败不能覆盖首个失败，但成功路径清理失败不能报成功。
+连接、监听器与定时器回收后，原 requestId 可用于新会话；不会自动重连或重放已可能计费的音频。
+
+ASR module ID 固定为 `<providerId>.speech-recognition.<modelId>`，翻译固定为
 `bailian.translation.<modelId>`；供应商 ID 使用 `bailian` / `volcengine` / `siliconflow` / `groq`，
 没有 `funasr` 兼容供应商别名。火山文件标准版不会读取本地 bytes/media-ref；宿主必须先通过自己受控的
 对象存储发布成供应商可访问 URL。SDK 不提供公共 URL 文本框或冒充上传成功的回退路径。

package/dist/capabilities/client.js

@@ -193,117 +193,134 @@ export function createCapabilityClient(config) {
                         ? new AiRuntimeError('timeout', `Capability session timed out: ${requestId}`)
                         : cancelledError(requestId);
                 }
-                let ended = false;
                 let closePromise;
                 let finishPromise;
+                let outcome;
+                let settlement;
+                let cleanupError;
+                const pendingSends = new Set();
+                let resolveResult;
+                let rejectResult;
+                const result = new Promise((resolve, reject) => { resolveResult = resolve; rejectResult = reject; });
+                // Observing is optional; the original promise remains rejected for callers.
+                void result.catch(() => undefined);
                 const closeDriver = () => {
                     closePromise ??= Promise.resolve().then(async () => await driver.close?.());
                     return closePromise;
                 };
-                const end = (error) => {
-                    if (ended)
-                        return;
-                    ended = true;
-                    options.signal?.removeEventListener('abort', forwardAbort);
-                    if (timeout !== undefined)
-                        clearTimeout(timeout);
-                    active.delete(requestId);
-                    markFinished();
-                    span.end(error);
-                };
-                const closeAfterAbort = async () => {
-                    if (ended)
-                        return;
-                    const error = timedOut
-                        ? new AiRuntimeError('timeout', `Capability session timed out: ${requestId}`)
-                        : cancelledError(requestId);
-                    try {
-                        await closeDriver();
-                    }
-                    finally {
-                        runtime.logger.error('能力实时会话失败', {
-                            event: 'capability.session.failed', requestId, context: { capabilityId: id }, error,
-                        });
-                        end(error);
-                    }
-                };
-                controller.signal.addEventListener('abort', () => { void closeAfterAbort(); }, { once: true });
-                const sessionInactiveError = () => timedOut
+                const abortError = () => timedOut
                     ? new AiRuntimeError('timeout', `Capability session timed out: ${requestId}`)
                     : cancelledError(requestId);
+                const normalize = (error) => controller.signal.aborted
+                    ? abortError() : normalizeExecutionError(id, error);
+                const inactiveError = () => outcome && outcome.kind !== 'completed'
+                    ? outcome.error : new AiRuntimeError('realtime_session_inactive', `Capability session is inactive: ${requestId}`);
+                const settle = (next) => {
+                    if (settlement)
+                        return settlement;
+                    outcome = next;
+                    for (const reject of pendingSends)
+                        reject(inactiveError());
+                    pendingSends.clear();
+                    settlement = (async () => {
+                        let terminal = next;
+                        try {
+                            await closeDriver();
+                        }
+                        catch (error) {
+                            cleanupError = normalizeExecutionError(id, error);
+                            // Keep the first failure/cancellation; failed cleanup cannot make
+                            // a successful result or explicit close look successful.
+                            if (terminal.kind !== 'failed')
+                                terminal = { kind: 'failed', error: cleanupError };
+                        }
+                        outcome = terminal;
+                        controller.signal.removeEventListener('abort', onAbort);
+                        options.signal?.removeEventListener('abort', forwardAbort);
+                        if (timeout !== undefined)
+                            clearTimeout(timeout);
+                        active.delete(requestId);
+                        markFinished();
+                        if (terminal.kind === 'failed') {
+                            runtime.logger.error('能力实时会话失败', {
+                                event: 'capability.session.failed', requestId,
+                                context: { capabilityId: id, ...(cleanupError ? { cleanupErrorCode: cleanupError.code } : {}) },
+                                error: terminal.error,
+                            });
+                        }
+                        else {
+                            runtime.logger.info(terminal.kind === 'completed' ? '能力实时会话完成' : '能力实时会话关闭', {
+                                event: `capability.session.${terminal.kind}`, requestId, context: { capabilityId: id },
+                            });
+                        }
+                        span.end(terminal.kind === 'failed' ? terminal.error : undefined);
+                        if (terminal.kind === 'completed')
+                            resolveResult(terminal.output);
+                        else
+                            rejectResult(terminal.error);
+                    })();
+                    return settlement;
+                };
+                const onAbort = () => { void settle({ kind: 'failed', error: abortError() }); };
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+                if (driver.result) {
+                    void driver.result.then(output => settle({ kind: 'completed', output }), error => settle({ kind: 'failed', error: normalize(error) }));
+                }
                 return {
                     requestId,
                     descriptor: registered.module.descriptor,
+                    result,
                     send: async (value) => {
-                        if (ended || controller.signal.aborted)
-                            throw sessionInactiveError();
-                        await driver.send(value);
+                        if (outcome || finishPromise)
+                            throw inactiveError();
+                        if (controller.signal.aborted)
+                            throw abortError();
+                        let rejectSend;
+                        const pending = new Promise((resolve, reject) => {
+                            rejectSend = reject;
+                            pendingSends.add(reject);
+                            void Promise.resolve().then(async () => {
+                                if (outcome)
+                                    throw inactiveError();
+                                await driver.send(value);
+                            }).then(resolve, reject);
+                        });
+                        try {
+                            await pending;
+                        }
+                        finally {
+                            pendingSends.delete(rejectSend);
+                        }
                     },
                     finish: () => {
                         if (finishPromise)
                             return finishPromise;
-                        if (ended || controller.signal.aborted)
-                            return Promise.reject(sessionInactiveError());
-                        finishPromise = (async () => {
-                            let output;
-                            try {
-                                output = await driver.finish();
-                                if (controller.signal.aborted)
-                                    throw cancelledError(requestId);
-                            }
-                            catch (error) {
-                                const normalized = controller.signal.aborted
-                                    ? cancelledError(requestId)
-                                    : normalizeExecutionError(id, error);
+                        finishPromise = result;
+                        if (!outcome) {
+                            void Promise.resolve().then(async () => {
+                                if (outcome)
+                                    return;
                                 try {
-                                    await closeDriver();
+                                    const output = await driver.finish();
+                                    if (controller.signal.aborted)
+                                        throw abortError();
+                                    await settle({ kind: 'completed', output });
                                 }
-                                catch {
-                                    // 保留 finish 的首个失败；close 仅负责尽力释放连接。
+                                catch (error) {
+                                    await settle({ kind: 'failed', error: normalize(error) });
                                 }
-                                runtime.logger.error('能力实时会话失败', {
-                                    event: 'capability.session.failed', requestId, context: { capabilityId: id }, error: normalized,
-                                });
-                                end(normalized);
-                                throw normalized;
-                            }
-                            try {
-                                await closeDriver();
-                            }
-                            catch (error) {
-                                const normalized = normalizeExecutionError(id, error);
-                                runtime.logger.error('能力实时会话失败', {
-                                    event: 'capability.session.failed', requestId, context: { capabilityId: id }, error: normalized,
-                                });
-                                end(normalized);
-                                throw normalized;
-                            }
-                            runtime.logger.info('能力实时会话完成', {
-                                event: 'capability.session.completed', requestId, context: { capabilityId: id },
                             });
-                            end();
-                            return output;
-                        })();
+                        }
                         return finishPromise;
                     },
                     close: async () => {
-                        if (ended)
+                        if (outcome) {
+                            await settlement;
                             return;
-                        try {
-                            await closeDriver();
-                            runtime.logger.info('能力实时会话关闭', {
-                                event: 'capability.session.closed', requestId, context: { capabilityId: id },
-                            });
-                            end();
-                        }
-                        catch (error) {
-                            const normalized = normalizeExecutionError(id, error);
-                            runtime.logger.error('能力实时会话失败', {
-                                event: 'capability.session.failed', requestId, context: { capabilityId: id }, error: normalized,
-                            });
-                            end(normalized);
-                            throw normalized;
                         }
+                        await settle({ kind: 'closed', error: new AiRuntimeError('realtime_session_closed', `Capability session was closed: ${requestId}`) });
+                        if (cleanupError)
+                            throw cleanupError;
                     },
                 };
             }

package/dist/capabilities/speech-recognition/bailian/realtime/module.js

@@ -84,6 +84,8 @@ export function createBailianRealtimeAsrModule(preset, options = {}) {
             if (context.signal.aborted)
                 throw cancelledError(context.requestId);
             const credential = await apiKey(context);
+            if (context.signal.aborted)
+                throw cancelledError(context.requestId);
             const transport = context.runtime.realtime;
             if (!transport)
                 throw new AiRuntimeError('realtime_transport_missing', 'Host did not provide realtime transport');
@@ -118,21 +120,32 @@ async function openDriver(preset, input, taskId, connection, context) {
     let lastPartial = '';
     let durationMs;
     let terminalError;
+    let lastEventKind;
     const segments = [];
     const created = deferred();
     const ready = deferred();
     const finished = deferred();
+    const onAbort = () => fail(cancelledError(context.requestId));
     const closeConnection = () => {
+        context.signal.removeEventListener('abort', onAbort);
         closePromise ??= Promise.resolve().then(async () => await connection.close(1000, 'session complete'));
         return closePromise;
     };
     const fail = (error) => {
         if (phase === 'finished' || phase === 'closed' || phase === 'failed')
             return;
+        const failedPhase = phase;
         phase = 'failed';
-        const normalized = error instanceof AiRuntimeError
+        const original = error instanceof AiRuntimeError
             ? error
-            : new AiRuntimeError('provider_realtime_error', error instanceof Error ? error.message : 'Bailian realtime failed');
+            : new AiRuntimeError('provider_realtime_error', 'Realtime transport or event handler failed');
+        const message = original.message.replace(`[${original.code}] `, '');
+        const normalized = new AiRuntimeError(original.code, original.details?.modelId === preset.modelId ? message : `${preset.modelId} (${preset.protocol}): ${message}`, {
+            providerId: 'bailian', modelId: preset.modelId, protocol: preset.protocol,
+            stage: failedPhase, operation: original.details?.stage,
+            eventType: original.details?.eventType ?? lastEventKind,
+            providerCode: original.details?.providerCode,
+        });
         terminalError = normalized;
         created.reject(normalized);
         ready.reject(normalized);
@@ -159,6 +172,7 @@ async function openDriver(preset, input, taskId, connection, context) {
         await closeConnection();
     };
     const handle = async (event) => {
+        lastEventKind = event.kind;
         if (event.kind === 'created') {
             if (preset.protocol !== 'qwen-realtime' || phase !== 'opening') {
                 throw new AiRuntimeError('protocol_event_out_of_order', 'Unexpected Bailian realtime created event');
@@ -206,7 +220,10 @@ async function openDriver(preset, input, taskId, connection, context) {
             return;
         }
         if (event.kind === 'error') {
-            throw new AiRuntimeError('provider_task_failed', `${event.code ? `${event.code}: ` : ''}${event.message}`);
+            // Provider messages can echo request content. Retain the diagnostic code,
+            // never the full upstream message in the default error/logging path.
+            const providerCode = event.code && /^[\w.-]{1,80}$/.test(event.code) ? event.code : undefined;
+            throw new AiRuntimeError('provider_task_failed', 'Server reported a realtime task failure', { providerCode });
         }
         if (event.kind === 'ignored')
             return;
@@ -238,9 +255,10 @@ async function openDriver(preset, input, taskId, connection, context) {
         }
     };
     void consume();
-    const onAbort = () => fail(cancelledError(context.requestId));
     context.signal.addEventListener('abort', onAbort, { once: true });
     try {
+        if (context.signal.aborted)
+            throw cancelledError(context.requestId);
         if (preset.protocol === 'fun-duplex') {
             await connection.send(buildFunStart(preset, input, taskId));
         }
@@ -252,10 +270,19 @@ async function openDriver(preset, input, taskId, connection, context) {
     }
     catch (error) {
         fail(error);
-        await closeConnection();
-        throw error;
+        try {
+            await closeConnection();
+        }
+        catch {
+            const primary = terminalError;
+            throw new AiRuntimeError(primary.code, primary.message.replace(`[${primary.code}] `, ''), {
+                ...primary.details, cleanupFailed: true,
+            });
+        }
+        throw terminalError ?? error;
     }
     return {
+        result: finished.promise,
         send: async (chunk) => {
             if (terminalError)
                 throw terminalError;
@@ -263,7 +290,14 @@ async function openDriver(preset, input, taskId, connection, context) {
                 throw new AiRuntimeError('realtime_session_inactive', 'Bailian realtime session is not active');
             if (chunk.bytes.byteLength === 0)
                 return;
-            await connection.send(preset.protocol === 'fun-duplex' ? chunk.bytes : buildQwenAudio(chunk.bytes));
+            const data = preset.protocol === 'fun-duplex' ? chunk.bytes : buildQwenAudio(chunk.bytes);
+            try {
+                await connection.send(data);
+            }
+            catch (error) {
+                fail(error);
+                throw terminalError ?? error;
+            }
         },
         finish: () => {
             if (finishPromise)
@@ -286,6 +320,7 @@ async function openDriver(preset, input, taskId, connection, context) {
                 }
                 return await finished.promise;
             })();
+            void finishPromise.catch(error => fail(error));
             return finishPromise;
         },
         close: async () => {

package/dist/capabilities/speech-recognition/bailian/realtime/protocol.js

@@ -116,17 +116,33 @@ export function qwenUsesManualCommit(input) {
     return inputOptions(input).turnDetection === 'manual';
 }
 export function parseRealtimeMessage(preset, payload) {
-    let parsed;
+    let eventType;
     try {
-        parsed = JSON.parse(payload);
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch {
+            throw new AiRuntimeError('invalid_response', 'Server returned invalid JSON');
+        }
+        const root = record(parsed);
+        if (!root)
+            throw new AiRuntimeError('invalid_response', 'Server returned a non-object event');
+        const discriminator = preset.protocol === 'fun-duplex' ? record(root.header)?.event : root.type;
+        if (typeof discriminator !== 'string' || !discriminator.trim()) {
+            throw new AiRuntimeError('invalid_response', 'Server event has no event type');
+        }
+        eventType = /^[a-zA-Z][\w.-]{0,127}$/.test(discriminator) ? discriminator : 'unrecognized-event';
+        return preset.protocol === 'fun-duplex' ? parseFunEvent(root) : parseQwenEvent(root);
     }
-    catch {
-        throw new AiRuntimeError('invalid_response', 'Bailian realtime server returned invalid JSON');
+    catch (error) {
+        if (!(error instanceof AiRuntimeError))
+            throw error;
+        throw new AiRuntimeError(error.code, `${preset.modelId} (${preset.protocol}): ${error.message.replace(`[${error.code}] `, '')}`, {
+            providerId: 'bailian', modelId: preset.modelId, protocol: preset.protocol,
+            stage: 'parse', eventType,
+        });
     }
-    const root = record(parsed);
-    if (!root)
-        throw new AiRuntimeError('invalid_response', 'Bailian realtime server returned a non-object event');
-    return preset.protocol === 'fun-duplex' ? parseFunEvent(root) : parseQwenEvent(root);
 }
 function parseFunEvent(root) {
     const header = record(root.header);
@@ -147,6 +163,9 @@ function parseFunEvent(root) {
         const sentence = record(record(record(root.payload)?.output)?.sentence);
         if (sentence?.heartbeat === true)
             return { kind: 'ignored', eventType: 'heartbeat' };
+        if (typeof sentence?.text !== 'string' || typeof sentence.sentence_end !== 'boolean') {
+            throw new AiRuntimeError('invalid_response', 'Result requires text and boolean sentence_end');
+        }
         const segment = parseBailianSentence(sentence);
         const transcript = segment?.text ?? string(sentence?.text);
         if (!transcript) {
@@ -156,16 +175,16 @@ function parseFunEvent(root) {
                 return { kind: 'ignored', eventType: sentence.sentence_begin === true ? 'empty-sentence-begin' : 'empty-intermediate' };
             }
             if (sentence?.sentence_end === true) {
-                throw new AiRuntimeError('invalid_response', 'Bailian Fun-ASR final result has no text');
+                throw new AiRuntimeError('invalid_response', 'Final result has no text');
             }
-            throw new AiRuntimeError('invalid_response', 'Bailian Fun-ASR result has no text or sentence state');
+            throw new AiRuntimeError('invalid_response', 'Result has no text or sentence state');
         }
         const duration = number((record(root.usage) ?? record(record(root.payload)?.usage))?.duration);
         return sentence?.sentence_end === true
             ? { kind: 'final', text: transcript, segment, durationMs: duration === undefined ? undefined : duration * 1_000 }
             : { kind: 'partial', text: transcript, segment };
     }
-    return { kind: 'unknown', eventType: eventType || 'missing-event' };
+    return { kind: 'unknown', eventType: /^[a-zA-Z][\w.-]{0,127}$/.test(eventType) ? eventType : 'unrecognized-event' };
 }
 function parseQwenEvent(root) {
     const eventType = string(root.type) ?? '';
@@ -176,19 +195,42 @@ function parseQwenEvent(root) {
         return { kind: 'ready', sessionId: string(record(root.session)?.id) ?? string(root.session_id) };
     }
     if (eventType === 'conversation.item.input_audio_transcription.text') {
-        const transcript = `${string(root.text) ?? ''}${string(root.stash) ?? ''}`.trim();
-        if (!transcript)
+        if (typeof root.text !== 'string' || typeof root.stash !== 'string') {
+            throw new AiRuntimeError('invalid_response', 'Partial event requires string text and stash');
+        }
+        const transcript = root.text + root.stash;
+        if (!transcript.trim())
             throw new AiRuntimeError('invalid_response', 'Bailian Qwen realtime partial event has no text');
         return { kind: 'partial', text: transcript };
     }
     if (eventType === 'conversation.item.input_audio_transcription.completed') {
-        const transcript = string(root.transcript) ?? string(root.text);
+        const transcript = string(root.transcript);
         if (!transcript)
             throw new AiRuntimeError('invalid_response', 'Bailian Qwen realtime final event has no transcript');
         return { kind: 'final', text: transcript };
     }
     if (eventType === 'session.finished')
         return { kind: 'finished' };
+    if (eventType === 'input_audio_buffer.speech_started' || eventType === 'input_audio_buffer.speech_stopped') {
+        const timestamp = root[eventType.endsWith('speech_started') ? 'audio_start_ms' : 'audio_end_ms'];
+        if (!string(root.item_id) || typeof timestamp !== 'number' || !Number.isInteger(timestamp) || timestamp < 0) {
+            throw new AiRuntimeError('invalid_response', 'Invalid speech activity notification');
+        }
+        return { kind: 'ignored', eventType };
+    }
+    if (eventType === 'input_audio_buffer.committed') {
+        if (!string(root.item_id))
+            throw new AiRuntimeError('invalid_response', 'Commit notification has no item_id');
+        return { kind: 'ignored', eventType };
+    }
+    if (eventType === 'conversation.item.created') {
+        const item = record(root.item);
+        if (!string(item?.id) || !Array.isArray(item?.content)
+            || !item.content.some(value => record(value)?.type === 'input_audio' && record(value)?.transcript === null)) {
+            throw new AiRuntimeError('invalid_response', 'Invalid audio item notification');
+        }
+        return { kind: 'ignored', eventType };
+    }
     if (eventType === 'error' || eventType === 'conversation.item.input_audio_transcription.failed') {
         const error = record(root.error);
         return {
@@ -196,5 +238,5 @@ function parseQwenEvent(root) {
             message: string(error?.message) ?? string(root.message) ?? 'Bailian Qwen realtime task failed',
         };
     }
-    return { kind: 'unknown', eventType: eventType || 'missing-type' };
+    return { kind: 'unknown', eventType: /^[a-zA-Z][\w.-]{0,127}$/.test(eventType) ? eventType : 'unrecognized-event' };
 }