@henjicc/ai-sdk 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.2 - 2026-09-21
+
+- `llm/streaming` 新增有类型定义的文本、JSON Object 与 JSON Schema 输出配置，并把它正式写入 Chat Completions 的 `response_format`。
+- 模型能力现在可声明结构化输出与思考模式能否并用；不支持或尚未核实的组合在网络请求前返回可解析错误码，Groq 流式 JSON Schema 按官方限制明确拒绝。
+- 新增 `maxOutputTokens`，OpenAI/Groq/MiMo 使用 `max_completion_tokens`，其余兼容端点沿用 `max_tokens`；省略时不再强制 4096，流结束用 `truncated` 标记 token 上限截断。
+- 最终发送体复用正式构建结果，`onRequestBuilt` 只收到观察快照；保留正文/思考分流、AbortSignal、可选总时限与轻量受限宿主边界。
+
 ## 0.5.1 - 2026-09-21
 
 - Grsai GPT Image 2.5 默认变体从维护中的 Flare 切换为可用的 Standard；显式 Flare/Sunburst 参数保持兼容，等待官方恢复公告。

package/README.md

@@ -48,10 +48,10 @@ try {
 
 百炼工厂必须传 `baseUrl` 为实际地域/工作空间的 API 根地址，不包含端点路径。其他供应商可以覆盖根地址与 `credentialId`；SDK 不自动切换地域或账号。不同模型的向量不能混用；切换模型通常需要重建向量索引。Rerank 分数仅在本次请求内比较。
 
-SDK `0.5.1` 的正式分发渠道为公共 npm，无需配置 registry 或访问令牌：
+SDK `0.5.2` 的正式分发渠道为公共 npm，无需配置 registry 或访问令牌：
 
 ```bash
-npm install @henjicc/ai-sdk@0.5.1
+npm install @henjicc/ai-sdk@0.5.2
 ```
 
 然后提供 4 个宿主能力（`Transport` / `CredentialStore` / `MediaReader` / `Logger`），创建客户端：
@@ -192,14 +192,50 @@ import {
   type RuntimeContext,
 } from '@henjicc/ai-sdk/llm/streaming'
 
-const request: LlmChatRequestDto = {
-  requestId: 'chat-1', providerId: 'openai', modelId: 'gpt-5-mini',
-  messages: [{ role: 'user', content: '你好' }],
-}
-const result = await runLlmChatStream(request, 'chat-1', onStreamEvent, runtime as RuntimeContext)
-console.log(result.output, result.reasoningOutput, result.usage, result.finishReason)
-cancelLlmChatTask('chat-1')
-```
+const request: LlmChatRequestDto = {
+  requestId: 'chat-1', providerId: 'openai', modelId: 'gpt-5-mini',
+  messages: [{ role: 'user', content: '你好' }],
+  capabilities: {
+    structuredOutputMode: 'schema',
+    reasoning: true,
+    structuredOutputWithReasoning: true,
+    maxOutputTokens: 32_000,
+  },
+  reasoning: { enabled: true, effort: 'high' },
+  structuredOutput: {
+    type: 'json_schema',
+    name: 'subtitle_segments',
+    strict: true,
+    schema: {
+      type: 'object',
+      properties: {
+        segments: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: { text: { type: 'string' } },
+            required: ['text'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['segments'],
+      additionalProperties: false,
+    },
+  },
+  maxOutputTokens: 24_000,
+}
+const result = await runLlmChatStream(request, 'chat-1', onStreamEvent, runtime as RuntimeContext)
+console.log(result.output, result.reasoningOutput, result.usage, result.finishReason, result.truncated)
+cancelLlmChatTask('chat-1')
+```
+
+`structuredOutput` 支持 `text`、`json_object`、`json_schema`。轻量入口只执行 Chat Completions，
+所以这里会正式映射到最终请求体的 `response_format`；它不包含 Responses API 执行器，Responses
+路径的等价字段 `text.format` 由完整 `llm` 入口处理。JSON Object、JSON Schema 和“结构化输出 +
+思考”都必须由 `capabilities` 明确声明；未知或不支持的组合会在网络请求前返回结构化错误，不会静默
+降级。省略 `maxOutputTokens` 时 SDK 不再强加 4096 tokens，而是交给供应商默认值；省略执行参数里的
+`timeoutMs` 则没有请求总时限，宿主可在 `Transport` 中实现长时间无数据才超时。
 
 ### 可选模型分发包与统一能力筛选
 

package/dist/llm/chat.d.ts

@@ -28,10 +28,11 @@ export interface LlmChatCompletedInfo {
     reasoningOutput: string;
     usage: LlmUsageDto | null;
     finishReason: string | null;
+    truncated: boolean;
     toolCalls?: LlmStreamToolCall[];
 }
 export interface LlmChatStreamHooks {
-    /** 请求体与 endpoint 已经构建好，即将发出网络请求前触发一次。 */
+    /** 请求体与 endpoint 已经构建好，即将发出网络请求前触发一次；requestPayload 是只用于观察的快照。 */
     onRequestBuilt?: (info: LlmChatRequestBuiltInfo) => void;
     /** 流式响应正常读完（未被取消、未抛错）后触发一次。 */
     onCompleted?: (info: LlmChatCompletedInfo) => void;
@@ -47,6 +48,7 @@ export interface LlmChatStreamOutcome {
     reasoningOutput: string;
     usage: LlmUsageDto | null;
     finishReason: string | null;
+    truncated: boolean;
     toolCalls?: LlmStreamToolCall[];
 }
 export interface LlmChatExecutionOptions {

package/dist/llm/chat.js

@@ -53,11 +53,16 @@ export async function runLlmChatStream(request, taskId, emit, runtime, hooks = {
             ? resolvePpioChatEndpoint(processedRequest.baseUrl)
             : resolveOpenAiCompatibleEndpoint(processedRequest);
         const requestPayload = buildOpenAiCompatiblePayload(processedRequest);
-        hooks.onRequestBuilt?.({ endpoint, requestPayload, processedRequest });
+        hooks.onRequestBuilt?.({
+            endpoint,
+            requestPayload: cloneJsonObject(requestPayload),
+            processedRequest,
+        });
         const output = await streamOpenAiCompatibleChat({
             endpoint,
             apiKey,
-            request: processedRequest,
+            providerId: identity.providerFamilyId,
+            payload: requestPayload,
             signal: controller.signal,
             emit,
             transport: runtime.transport,
@@ -77,6 +82,7 @@ export async function runLlmChatStream(request, taskId, emit, runtime, hooks = {
             reasoningOutput: output.reasoningOutput,
             usage: output.usage,
             finishReason: output.finishReason,
+            truncated: output.truncated,
             toolCalls: output.toolCalls,
         });
         span?.end();
@@ -91,6 +97,7 @@ export async function runLlmChatStream(request, taskId, emit, runtime, hooks = {
             reasoningOutput: output.reasoningOutput,
             usage: output.usage,
             finishReason: output.finishReason,
+            truncated: output.truncated,
             toolCalls: output.toolCalls,
         };
     }
@@ -142,3 +149,6 @@ function isAbortError(error) {
 function isJsonObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function cloneJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/llm/chatTypes.d.ts

@@ -1,5 +1,6 @@
 import type { JsonObject, JsonValue } from '../types/runtime.js';
 import type { LlmReasoningConfig } from './reasoning.js';
+import type { LlmCapabilities, LlmStructuredOutputConfig } from './types.js';
 export type { JsonObject, JsonValue };
 /**
  * 原生 SSE 流式聊天路径（`llm:chatStream`）的请求/响应 DTO。
@@ -34,7 +35,10 @@ export interface LlmChatRequestDto {
     baseUrl?: string;
     reasoning?: LlmReasoningConfig;
     messages: LlmChatMessageDto[];
-    capabilities?: JsonObject;
+    capabilities?: Partial<LlmCapabilities>;
+    structuredOutput?: LlmStructuredOutputConfig;
+    /** 正整数；不设置时不下发限制，由供应商或模型默认值决定。 */
+    maxOutputTokens?: number;
     tools?: JsonValue;
     policy?: JsonObject;
     memory?: JsonObject;
@@ -75,6 +79,8 @@ export interface LlmStreamOutput {
     reasoningOutput: string;
     usage: LlmUsageDto | null;
     finishReason: string | null;
+    /** 供应商明确因输出 token 上限结束时为 true。 */
+    truncated: boolean;
     toolCalls?: LlmStreamToolCall[];
 }
 export interface LlmStreamToolCall {

package/dist/llm/defaults.js

@@ -28,6 +28,7 @@ export const DEFAULT_LLM_CAPABILITIES = {
     parallelTools: false,
     jsonOutput: false,
     structuredOutputMode: 'none',
+    structuredOutputWithReasoning: null,
     reasoning: false,
     sampling: true,
     contextWindow: null,

package/dist/llm/groq/module.js

@@ -39,6 +39,7 @@ export function createGroqLlmModule() {
                 reasoningOutput: outcome.reasoningOutput,
                 usage: outcome.usage,
                 finishReason: outcome.finishReason,
+                truncated: outcome.truncated,
                 toolCalls: outcome.toolCalls,
             };
         },

package/dist/llm/groq/preset.js

@@ -40,6 +40,7 @@ export const GROQ_DEFAULT_MODEL_CONFIG = {
         parallelTools: false,
         jsonOutput: true,
         structuredOutputMode: 'json',
+        structuredOutputWithReasoning: true,
         reasoning: true,
         sampling: true,
         contextWindow: 131_072,

package/dist/llm/modelCatalog.d.ts

@@ -28,6 +28,8 @@ export interface LlmModelCatalogEntry {
     toolCall: boolean;
     parallelTools: boolean;
     structuredOutputMode: LlmCapabilities['structuredOutputMode'];
+    /** 结构化输出与思考模式能否同时启用；省略表示官方资料尚未核实。 */
+    structuredOutputWithReasoning?: boolean;
     reasoning: boolean;
     /** 是否接受 temperature / top_p；官方声明为固定值的模型要记 false */
     sampling: boolean;

package/dist/llm/modelCatalog.js

@@ -44,6 +44,7 @@ export function applyLlmModelCatalogEntry(base, entry) {
         toolCall: entry.toolCall,
         parallelTools: entry.parallelTools,
         structuredOutputMode: entry.structuredOutputMode,
+        structuredOutputWithReasoning: entry.structuredOutputWithReasoning ?? null,
         jsonOutput: entry.structuredOutputMode !== 'none',
         reasoning: entry.reasoning,
         sampling: entry.sampling,

package/dist/llm/modelCatalogEntries.js

@@ -37,6 +37,7 @@ export const LLM_MODEL_CATALOG_ENTRIES = [
         toolCall: true,
         parallelTools: false,
         structuredOutputMode: 'json',
+        structuredOutputWithReasoning: true,
         reasoning: true,
         sampling: true,
         contextWindow: 131_072,
@@ -117,6 +118,7 @@ export const LLM_MODEL_CATALOG_ENTRIES = [
         toolCall: true,
         parallelTools: false,
         structuredOutputMode: 'schema',
+        structuredOutputWithReasoning: true,
         reasoning: true,
         // 官方文档把 temperature / top_p 等列为固定值并明确"建议不要显式传入"，
         // sampling=false 会让模型步骤不再下发这两个参数。

package/dist/llm/modelStep.d.ts

@@ -55,8 +55,8 @@ export type ModelStepTool = z.infer<typeof modelStepToolSchema>;
 export declare const modelStepTraceMetadataSchema: z.ZodObject<{
     kind: z.ZodEnum<{
         fallback: "fallback";
-        router: "router";
         primary: "primary";
+        router: "router";
         summarizer: "summarizer";
         observer: "observer";
         other: "other";
@@ -174,8 +174,8 @@ export declare const modelStepInputSchema: z.ZodObject<{
     trace: z.ZodOptional<z.ZodObject<{
         kind: z.ZodEnum<{
             fallback: "fallback";
-            router: "router";
             primary: "primary";
+            router: "router";
             summarizer: "summarizer";
             observer: "observer";
             other: "other";

package/dist/llm/providerProtocolCore.js

@@ -7,8 +7,9 @@ export function resolveProviderExtraAuthHeaders(providerId, apiKey) {
 }
 export function applyProviderRequestBodyQuirks(providerId, body) {
     const normalizedProviderId = providerId.trim().toLowerCase();
-    if (normalizedProviderId === 'mimo')
+    if (normalizedProviderId === 'mimo' || normalizedProviderId === 'openai') {
         return renameMaxCompletionTokens(body);
+    }
     if (normalizedProviderId !== 'groq')
         return body;
     const withTokenLimit = renameMaxCompletionTokens(body);

package/dist/llm/streaming/index.d.ts

@@ -7,7 +7,7 @@
 export { cancelLlmChatTask, normalizeLlmChatError, resolveLlmTaskId, runLlmChatStream, } from '../chat.js';
 export type { LlmChatCompletedInfo, LlmChatRequestBuiltInfo, LlmChatStreamHooks, LlmChatStreamOutcome, } from '../chat.js';
 export type { JsonObject, JsonValue, LlmChatMessageDto, LlmChatRequestDto, LlmContentPart, LlmRole, LlmStreamEmitter, LlmStreamEventDto, LlmStreamOutput, LlmTraceDto, LlmUsageDto, } from '../chatTypes.js';
-export type { LlmReasoningConfig, LlmReasoningEffort } from '../reasoning.js';
+export type { LlmReasoningConfig, LlmReasoningEffort, LlmStructuredOutputConfig, } from '../types.js';
 export { parseModelProviderError, ProviderModelStepError, serializeModelProviderError, } from '../../runtime/provider-error-core.js';
 export type { ModelProviderError, ModelProviderErrorCategory, } from '../../runtime/provider-error-core.js';
 export type { RuntimeContext } from '../../runtime/RuntimeContext.js';

package/dist/llm/streaming.d.ts

@@ -12,7 +12,8 @@ import type { JsonObject, LlmChatMessageDto, LlmChatRequestDto, LlmStreamEmitter
 interface StreamChatOptions {
     endpoint: string;
     apiKey: string;
-    request: LlmChatRequestDto;
+    providerId: string;
+    payload: JsonObject;
     signal: AbortSignal;
     emit: LlmStreamEmitter;
     transport: Transport;

package/dist/llm/streaming.js

@@ -25,15 +25,15 @@ export function resolveOpenAiCompatibleEndpoint(request) {
         : `${normalized}/v1/chat/completions`;
 }
 export function buildOpenAiCompatiblePayload(request) {
-    const policy = request.policy ?? {};
     const payload = {
         model: request.modelId,
         messages: request.messages.map(serializeMessage),
         stream: true,
         stream_options: { include_usage: true },
     };
-    const maxTokens = readNumber(policy.max_tokens ?? policy.maxTokens);
-    payload.max_tokens = maxTokens ?? 4096;
+    const maxTokens = resolveMaxOutputTokens(request);
+    if (maxTokens !== undefined)
+        payload.max_tokens = maxTokens;
     if (request.tools !== undefined) {
         payload.tools = request.tools;
     }
@@ -45,23 +45,23 @@ export function buildOpenAiCompatiblePayload(request) {
      * 用模型能力表兜一层，没标"支持思考"的模型仍然一个字段都不发。
      */
     const identity = resolveLlmEndpointIdentity(request);
+    const withStructuredOutput = applyStructuredOutputRequestBody(request, identity.providerFamilyId, payload);
     const reasoningCapable = request.capabilities?.reasoning === true;
     const withReasoning = reasoningCapable
-        ? applyProviderReasoningRequestBody(identity.providerFamilyId, request.adapter, payload, request.reasoning)
-        : payload;
+        ? applyProviderReasoningRequestBody(identity.providerFamilyId, request.adapter, withStructuredOutput, request.reasoning)
+        : withStructuredOutput;
     return applyProviderRequestBodyQuirks(identity.providerFamilyId, withReasoning);
 }
 export async function streamOpenAiCompatibleChat(options) {
-    const identity = resolveLlmEndpointIdentity(options.request);
-    const response = await fetchProvider(identity.providerFamilyId, options.endpoint, {
+    const response = await fetchProvider(options.providerId, options.endpoint, {
         method: 'POST',
         headers: {
             Accept: 'text/event-stream',
             Authorization: `Bearer ${options.apiKey}`,
-            ...resolveProviderExtraAuthHeaders(identity.providerFamilyId, options.apiKey),
+            ...resolveProviderExtraAuthHeaders(options.providerId, options.apiKey),
             'Content-Type': 'application/json',
         },
-        body: JSON.stringify(buildOpenAiCompatiblePayload(options.request)),
+        body: JSON.stringify(options.payload),
         signal: options.signal,
     }, {
         transport: options.transport,
@@ -160,7 +160,14 @@ async function readSseStream(body, emit) {
         for (const event of parsed.events) {
             const chunk = parseSseData(event);
             if (chunk.done) {
-                return { output, reasoningOutput, usage, finishReason, toolCalls: [...toolCalls.values()] };
+                return {
+                    output,
+                    reasoningOutput,
+                    usage,
+                    finishReason,
+                    truncated: isOutputTruncated(finishReason),
+                    toolCalls: [...toolCalls.values()],
+                };
             }
             usage = chunk.usage ?? usage;
             finishReason = chunk.finishReason ?? finishReason;
@@ -194,7 +201,89 @@ async function readSseStream(body, emit) {
             emit({ type: 'Token', data: chunk.content });
         }
     }
-    return { output, reasoningOutput, usage, finishReason, toolCalls: [...toolCalls.values()] };
+    return {
+        output,
+        reasoningOutput,
+        usage,
+        finishReason,
+        truncated: isOutputTruncated(finishReason),
+        toolCalls: [...toolCalls.values()],
+    };
+}
+function applyStructuredOutputRequestBody(request, providerId, body) {
+    const output = request.structuredOutput;
+    if (!output)
+        return body;
+    if (output.type === 'text') {
+        return { ...body, response_format: { type: 'text' } };
+    }
+    const supportedMode = request.capabilities?.structuredOutputMode ?? 'none';
+    if (output.type === 'json_object' && supportedMode === 'none') {
+        throw invalidRequest('STRUCTURED_OUTPUT_JSON_OBJECT_UNSUPPORTED', `Model "${request.modelId}" is not declared to support JSON Object output.`);
+    }
+    if (output.type === 'json_schema' && supportedMode !== 'schema') {
+        throw invalidRequest('STRUCTURED_OUTPUT_JSON_SCHEMA_UNSUPPORTED', `Model "${request.modelId}" is not declared to support JSON Schema output.`);
+    }
+    if (request.reasoning?.enabled === true) {
+        if (request.capabilities?.reasoning !== true) {
+            throw invalidRequest('REASONING_UNSUPPORTED', `Model "${request.modelId}" is not declared to support reasoning.`);
+        }
+        const compatibility = request.capabilities.structuredOutputWithReasoning;
+        if (compatibility !== true) {
+            throw invalidRequest(compatibility === false
+                ? 'STRUCTURED_OUTPUT_WITH_REASONING_UNSUPPORTED'
+                : 'STRUCTURED_OUTPUT_WITH_REASONING_CAPABILITY_REQUIRED', compatibility === false
+                ? `Model "${request.modelId}" does not support structured output with reasoning enabled.`
+                : `Model "${request.modelId}" must explicitly declare structuredOutputWithReasoning before structured output and reasoning can be combined.`);
+        }
+    }
+    if (output.type === 'json_object') {
+        return { ...body, response_format: { type: 'json_object' } };
+    }
+    if (providerId.trim().toLowerCase() === 'groq') {
+        throw invalidRequest('STRUCTURED_OUTPUT_STREAMING_UNSUPPORTED', 'Groq does not support JSON Schema structured output with streaming.');
+    }
+    if (!output.name.trim()) {
+        throw invalidRequest('INVALID_STRUCTURED_OUTPUT', 'JSON Schema output requires a non-empty name.');
+    }
+    if (!isRecord(output.schema)) {
+        throw invalidRequest('INVALID_STRUCTURED_OUTPUT', 'JSON Schema output requires schema to be an object.');
+    }
+    if (typeof output.strict !== 'boolean') {
+        throw invalidRequest('INVALID_STRUCTURED_OUTPUT', 'JSON Schema output requires an explicit strict boolean.');
+    }
+    return {
+        ...body,
+        response_format: {
+            type: 'json_schema',
+            json_schema: {
+                name: output.name.trim(),
+                schema: output.schema,
+                strict: output.strict,
+            },
+        },
+    };
+}
+function resolveMaxOutputTokens(request) {
+    const policy = request.policy ?? {};
+    const legacy = policy.max_tokens ?? policy.maxTokens;
+    const candidate = request.maxOutputTokens ?? legacy;
+    if (candidate === undefined)
+        return undefined;
+    if (typeof candidate !== 'number' || !Number.isInteger(candidate) || candidate <= 0) {
+        throw invalidRequest('INVALID_MAX_OUTPUT_TOKENS', 'maxOutputTokens must be a positive integer.');
+    }
+    const modelLimit = request.capabilities?.maxOutputTokens;
+    if (typeof modelLimit === 'number' && candidate > modelLimit) {
+        throw invalidRequest('MAX_OUTPUT_TOKENS_EXCEEDED', `Requested ${candidate} output tokens, but model "${request.modelId}" declares a limit of ${modelLimit}.`);
+    }
+    return candidate;
+}
+function invalidRequest(code, message) {
+    return Object.assign(new Error(message), { code, statusCode: 400 });
+}
+function isOutputTruncated(finishReason) {
+    return finishReason === 'length' || finishReason === 'max_tokens' || finishReason === 'max_output_tokens';
 }
 function drainSseEvents(input) {
     const events = [];
@@ -312,9 +401,6 @@ function readDelta(value) {
 function readString(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
-function readNumber(value) {
-    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
-}
 function readTokenCount(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
 }

package/dist/llm/types.d.ts

@@ -1,6 +1,18 @@
 import type { LlmApiProtocol } from './providerProtocol.js';
 import type { LlmReasoningConfig } from './reasoning.js';
+import type { JsonObject } from '../types/runtime.js';
 export type { LlmReasoningConfig, LlmReasoningEffort } from './reasoning.js';
+/** Chat Completions 的正式输出格式配置；省略时由供应商使用默认文本格式。 */
+export type LlmStructuredOutputConfig = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    name: string;
+    schema: JsonObject;
+    strict: boolean;
+};
 export interface LlmCapabilities {
     text: boolean;
     image: boolean;
@@ -13,6 +25,11 @@ export interface LlmCapabilities {
     parallelTools: boolean;
     jsonOutput: boolean;
     structuredOutputMode: 'none' | 'json' | 'schema';
+    /**
+     * 结构化输出能否与思考模式同时启用。`null` / 缺省表示尚未核实；
+     * 轻量流式入口在调用方明确开启两者时会拒绝未知组合，避免静默丢参数。
+     */
+    structuredOutputWithReasoning?: boolean | null;
     reasoning: boolean;
     sampling: boolean;
     contextWindow: number | null;
@@ -282,6 +299,8 @@ export interface LlmChatRequest {
     reasoning?: LlmReasoningConfig;
     messages: LlmChatMessage[];
     capabilities?: Partial<LlmCapabilities>;
+    structuredOutput?: LlmStructuredOutputConfig;
+    maxOutputTokens?: number;
     tools?: LlmToolSchema[];
     policy?: Partial<LlmPolicy>;
     memory?: LlmMemoryScope;

package/docs/consumers.md

@@ -3,13 +3,19 @@
 本清单是 `@henjicc/ai-sdk` 消费方的唯一维护入口，用于 SDK 发布后的跨仓升级协调。
 绝对路径仅描述当前开发机上的仓库位置，不进入 SDK 运行时代码、发布包或用户配置。
 
-最后核对日期：2026-09-14
+最后核对日期：2026-09-21
 
 Henji-AI 安装包的 GPT Image 2.5 高分辨率报错归属：宿主智能比例预处理曾忽略联动过滤，将 `smart` 转成 KIE 仅限 1K 的 `27:16`，SDK 在请求前正确拒绝。修复位于应用公共预处理，按当前分辨率/渠道的合法选项匹配；Flare/Sunburst 的 1K/2K/4K 及 APIMart、Grsai 同类筛选已有定向覆盖。无需放宽 SDK 契约或发布 SDK；安装包需随应用更新才包含修复，现有版本可手动选合法比例规避。
 
-当前仓内及公共 npm SDK 版本：`0.5.0`（2026-09-21 已发布并完成公共匿名回装）
-
-发布运行时代码提交 `1333422e`，补充边界回归提交 `da37e4bc`；后者必需 CI `35535140722` 全部成功。12组修复撤销验证均检测到失败，恢复后定向测试通过。固定候选包经仓外回装后发布，公共 registry 匿名安装的 shasum/integrity 与候选包一致；Vite公开入口和无TextEncoder/TextDecoder的受限宿主消费通过。npm网页登录与发布二次验证已完成；发布后等待公共索引可读才执行匿名验证，没有重复发布。
+当前仓内及公共 npm SDK 版本：`0.5.1`（2026-09-21 已发布并完成公共匿名回装）
+
+`0.5.1` 将 Grsai GPT Image 2.5 未指定变体时的默认值从官方公告仍在维护的 Flare 改为 Standard，并同步默认价格；显式选择 Flare / Sunburst 的调用保持兼容。公共 DTO、请求协议、宿主边界和其余模型未变。发布前 77 个测试文件 / 899 项测试、可移植性、构建、49 个 Vite 公开入口和受限宿主门禁通过；公共索引可读后，已在隔离用户 npm 配置的仓外目录匿名安装并完成 ESM 导入。
+
+- `0.5.1` tarball：https://registry.npmjs.org/@henjicc/ai-sdk/-/ai-sdk-0.5.1.tgz
+- `0.5.1` shasum：`40087e680f1b7de63a601d12758acb7280de305f`
+- `0.5.1` integrity：`sha512-+L/mAmFU6zgJ0gdsIwy0T1Z9TDOABaxO3HgLsEvMUNbRQhs9K55golF1472EgSJsIDysScnUulFJfBVg0xsNBg==`
+
+`0.5.0` 发布运行时代码提交 `1333422e`，补充边界回归提交 `da37e4bc`；后者必需 CI `35535140722` 全部成功。12组修复撤销验证均检测到失败，恢复后定向测试通过。固定候选包经仓外回装后发布，公共 registry 匿名安装的 shasum/integrity 与候选包一致；Vite公开入口和无TextEncoder/TextDecoder的受限宿主消费通过。npm网页登录与发布二次验证已完成；发布后等待公共索引可读才执行匿名验证，没有重复发布。
 
 - tarball：https://registry.npmjs.org/@henjicc/ai-sdk/-/ai-sdk-0.5.0.tgz
 - shasum：`1b66a7c54f4f86a01b73fdca68b1c63e53dcbe10`

package/examples/llm-chat/README.md

@@ -1,11 +1,17 @@
 # llm-chat
 
-用 `@henjicc/ai-sdk@0.4.1` 的 `llm/streaming` 按需入口走 OpenAI-compatible SSE 流式对话，
+用 `@henjicc/ai-sdk@0.5.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。示例显式传入
 `reasoning: { enabled: false, effort: 'high' }`，避免短输出预算被供应商默认思考过程占用；若流结束后
-没有任何文本 token，示例会明确失败。
+没有任何文本 token，示例会明确失败。
+
+输出上限使用有类型定义的 `maxOutputTokens`。省略时 SDK 不再自动写入 4096；调用方可以按字幕长度
+和模型上限选择更大的值。`runLlmChatStream` 的执行参数不传 `timeoutMs` 时没有请求总时限，CEP
+网络适配可在 `Transport` 中实现“长时间无数据才超时”。正式结构化输出可通过
+`structuredOutput` 选择 `text`、`json_object` 或带 `name/schema/strict` 的 `json_schema`，并通过
+`capabilities.structuredOutputMode` 与 `structuredOutputWithReasoning` 明确声明模型能力。
 
 ```bash
 npm install

package/examples/llm-chat/index.ts

@@ -68,7 +68,7 @@ async function main(): Promise<void> {
     reasoning: providerId === 'deepseek'
       ? { enabled: false, effort: 'high' }
       : undefined,
-    policy: { max_tokens: 16 },
+    maxOutputTokens: 16,
   }
   const taskId = resolveLlmTaskId(request)
   let output = ''

package/package.json

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