@veltra/ai 1.4.0 → 2.1.0

package/dist/chat/index.d.ts

@@ -1,5 +1,5 @@
-import { ChatAttachment, ChatMessage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus } from "./types.js";
+import { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus } from "./types.js";
 import { UseChatOptions, useChat } from "./use-chat.js";
-import { OpenAITransportOptions, createOpenAITransport } from "./transports/openai.js";
+import { OpenAITransport, OpenAITransportOptions, createOpenAITransport } from "./transports/openai.js";
 import "./transports/index.js";
-export { ChatAttachment, ChatMessage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, OpenAITransportOptions, ToolCallStatus, UseChatOptions, createOpenAITransport, useChat };
+export { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, OpenAITransport, OpenAITransportOptions, ToolCallStatus, UseChatOptions, createOpenAITransport, useChat };

package/dist/chat/transports/index.d.ts

@@ -1,2 +1,2 @@
-import { OpenAITransportOptions, createOpenAITransport } from "./openai.js";
-export { OpenAITransportOptions, createOpenAITransport };
+import { OpenAITransport, OpenAITransportOptions, createOpenAITransport } from "./openai.js";
+export { OpenAITransport, OpenAITransportOptions, createOpenAITransport };

package/dist/chat/transports/openai.d.ts

@@ -1,23 +1,27 @@
 import { ChatTransport } from "../types.js";
+import { ChatModelOption, ChatProvider } from "../../providers/types.js";
 //#region src/chat/transports/openai.d.ts
-/** createOpenAITransport 的配置项 */
+/** createOpenAITransport 的配置项（多 Provider） */
 interface OpenAITransportOptions {
-  /** chat completions 端点，如 https://api.openai.com/v1/chat/completions */
-  endpoint: string;
-  /** API Key（Bearer 鉴权） */
-  apiKey?: string;
-  /** 模型名 */
-  model: string;
-  /** 额外请求头 */
+  /** 至少一个 Provider；模型 id 须跨 Provider 全局唯一 */
+  providers: ChatProvider[];
+  /** 全局额外请求头（与各 Provider headers 合并，Provider 优先） */
   headers?: Record<string, string>;
-  /** 额外请求体字段，如 temperature、top_p */
+  /** 全局额外请求体字段，如 temperature、top_p */
   body?: Record<string, unknown>;
 }
+/** 带扁平模型列表元数据的 OpenAI 兼容 transport */
+type OpenAITransport = ChatTransport & {
+  /** 供 UI 使用的扁平模型列表 */
+  readonly models: ChatModelOption[];
+  /** 默认模型 id（首个 Provider 的首个模型） */
+  readonly defaultModel: string;
+};
 /**
  * 创建 OpenAI 兼容协议的传输层（chat/completions SSE）。
- * 手写 fetch + SSE 解析，无任何第三方依赖。
+ * 按 request.model 路由到对应 Provider 的 endpoint；手写 fetch + SSE，无第三方依赖。
  */
-declare function createOpenAITransport(options: OpenAITransportOptions): ChatTransport;
+declare function createOpenAITransport(options: OpenAITransportOptions): OpenAITransport;
 //#endregion
-export { OpenAITransportOptions, createOpenAITransport };
+export { OpenAITransport, OpenAITransportOptions, createOpenAITransport };
 //# sourceMappingURL=openai.d.ts.map

package/dist/chat/transports/openai.js

@@ -88,7 +88,7 @@ async function parseSSE(body, signal, handlers) {
 		if (typeof reasoning === "string" && reasoning) handlers.onReasoningDelta?.(reasoning);
 		if (Array.isArray(delta.tool_calls)) for (const tc of delta.tool_calls) {
 			const index = tc.index ?? 0;
-			if (index <= lastIndex && accumulated.size > 0) flushToolCalls();
+			if (index > lastIndex && accumulated.size > 0) flushToolCalls();
 			lastIndex = Math.max(lastIndex, index);
 			let call = accumulated.get(index);
 			if (!call) {
@@ -124,31 +124,68 @@ async function parseSSE(body, signal, handlers) {
 	}
 	flushToolCalls();
 }
+/** 校验 providers 并展开扁平模型列表 */
+function flattenModels(providers) {
+	if (!providers.length) throw new Error("[createOpenAITransport] providers 不能为空");
+	const models = [];
+	const byModelId = /* @__PURE__ */ new Map();
+	for (const provider of providers) {
+		if (!provider.models?.length) throw new Error(`[createOpenAITransport] Provider "${provider.id}" 未配置 models`);
+		for (const model of provider.models) {
+			if (byModelId.has(model.id)) throw new Error(`[createOpenAITransport] 模型 id "${model.id}" 重复（跨 Provider 须全局唯一）`);
+			byModelId.set(model.id, provider);
+			models.push({
+				...model,
+				providerId: provider.id,
+				providerLabel: provider.label
+			});
+		}
+	}
+	return {
+		models,
+		byModelId
+	};
+}
+/** 缺省：写入 OpenAI 兼容的 reasoning_effort */
+function defaultApplyReasoning(level, body) {
+	body.reasoning_effort = level;
+}
 /**
 * 创建 OpenAI 兼容协议的传输层（chat/completions SSE）。
-* 手写 fetch + SSE 解析，无任何第三方依赖。
+* 按 request.model 路由到对应 Provider 的 endpoint；手写 fetch + SSE，无第三方依赖。
 */
 function createOpenAITransport(options) {
-	const { endpoint, apiKey, model, headers, body } = options;
-	return async (request, handlers) => {
-		const { messages, systemPrompt, tools, signal } = request;
+	const { providers, headers: globalHeaders, body: globalBody } = options;
+	const { models, byModelId } = flattenModels(providers);
+	const defaultModel = models[0].id;
+	const send = async (request, handlers) => {
+		const { messages, systemPrompt, tools, signal, reasoningLevel } = request;
+		const modelId = request.model ?? defaultModel;
+		const provider = byModelId.get(modelId);
+		if (!provider) {
+			handlers.onError?.(/* @__PURE__ */ new Error(`未找到模型 "${modelId}" 对应的 Provider`));
+			return;
+		}
+		const requestBody = {
+			...globalBody,
+			model: modelId,
+			stream: true,
+			messages: toOpenAIMessages(messages, systemPrompt),
+			...tools?.length ? { tools: toOpenAITools(tools) } : {}
+		};
+		if (reasoningLevel) (provider.applyReasoning ?? defaultApplyReasoning)(reasoningLevel, requestBody);
 		let response;
 		try {
-			response = await fetch(endpoint, {
+			response = await fetch(provider.endpoint, {
 				method: "POST",
 				signal,
 				headers: {
 					"Content-Type": "application/json",
-					...apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
-					...headers
+					...provider.apiKey ? { Authorization: `Bearer ${provider.apiKey}` } : {},
+					...globalHeaders,
+					...provider.headers
 				},
-				body: JSON.stringify({
-					model,
-					stream: true,
-					...body,
-					messages: toOpenAIMessages(messages, systemPrompt),
-					...tools?.length ? { tools: toOpenAITools(tools) } : {}
-				})
+				body: JSON.stringify(requestBody)
 			});
 		} catch (error) {
 			if (!signal.aborted) handlers.onError?.(error instanceof Error ? error : new Error(String(error)));
@@ -169,6 +206,10 @@ function createOpenAITransport(options) {
 			if (!signal.aborted) handlers.onError?.(error instanceof Error ? error : new Error(String(error)));
 		}
 	};
+	return Object.assign(send, {
+		models,
+		defaultModel
+	});
 }
 //#endregion
 export { createOpenAITransport };

package/dist/chat/transports/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","names":[],"sources":["../../../src/chat/transports/openai.ts"],"sourcesContent":["import type {\n  ChatMessage,\n  ChatTool,\n  ChatTransport,\n  ChatTransportHandlers,\n  ChatTransportRequest\n} from '../types'\n\n/** createOpenAITransport 的配置项 */\nexport interface OpenAITransportOptions {\n  /** chat completions 端点，如 https://api.openai.com/v1/chat/completions */\n  endpoint: string\n  /** API Key（Bearer 鉴权） */\n  apiKey?: string\n  /** 模型名 */\n  model: string\n  /** 额外请求头 */\n  headers?: Record<string, string>\n  /** 额外请求体字段，如 temperature、top_p */\n  body?: Record<string, unknown>\n}\n\ninterface OpenAIMessage {\n  role: string\n  content?: unknown\n  tool_calls?: unknown[]\n  tool_call_id?: string\n}\n\nfunction toOpenAIMessages(messages: ChatMessage[], systemPrompt?: string): OpenAIMessage[] {\n  const result: OpenAIMessage[] = []\n\n  if (systemPrompt) {\n    result.push({ role: 'system', content: systemPrompt })\n  }\n\n  for (const msg of messages) {\n    if (msg.role === 'user') {\n      if (msg.attachments?.length) {\n        const parts: unknown[] = []\n        if (msg.content) parts.push({ type: 'text', text: msg.content })\n        for (const att of msg.attachments) {\n          parts.push({ type: 'image_url', image_url: { url: att.dataUrl } })\n        }\n        result.push({ role: 'user', content: parts })\n      } else {\n        result.push({ role: 'user', content: msg.content })\n      }\n    } else if (msg.role === 'assistant') {\n      const item: OpenAIMessage = { role: 'assistant', content: msg.content || '' }\n      if (msg.toolCalls?.length) {\n        item.tool_calls = msg.toolCalls.map((call) => ({\n          id: call.id,\n          type: 'function',\n          function: { name: call.name, arguments: call.arguments }\n        }))\n      }\n      result.push(item)\n    } else if (msg.role === 'tool') {\n      result.push({ role: 'tool', tool_call_id: msg.toolCallId, content: msg.content })\n    }\n  }\n\n  return result\n}\n\nfunction toOpenAITools(tools: ChatTool[]): unknown[] {\n  return tools.map((tool) => ({\n    type: 'function',\n    function: { name: tool.name, description: tool.description, parameters: tool.parameters }\n  }))\n}\n\ninterface AccumulatedToolCall {\n  id: string\n  name: string\n  arguments: string\n}\n\n/**\n * 逐行解析 SSE 流。\n * 兼容 OpenAI 及 DeepSeek 等 reasoning_content 风格的兼容端点。\n */\nasync function parseSSE(\n  body: ReadableStream<Uint8Array>,\n  signal: AbortSignal,\n  handlers: ChatTransportHandlers\n): Promise<void> {\n  const reader = body.getReader()\n  const decoder = new TextDecoder()\n  let buffer = ''\n\n  // 按 OpenAI 流式协议中 tool_calls 的 index 累积参数片段\n  const accumulated = new Map<number, AccumulatedToolCall>()\n  let lastIndex = -1\n\n  const flushToolCalls = () => {\n    if (!handlers.onToolCall) return\n    for (const call of accumulated.values()) {\n      if (call.id && call.name) {\n        handlers.onToolCall({ id: call.id, name: call.name, arguments: call.arguments })\n      }\n    }\n    accumulated.clear()\n  }\n\n  const handleData = (data: string) => {\n    if (data === '[DONE]') return\n\n    let chunk: any\n    try {\n      chunk = JSON.parse(data)\n    } catch {\n      return\n    }\n\n    const delta = chunk.choices?.[0]?.delta\n    if (!delta) return\n\n    if (typeof delta.content === 'string' && delta.content) {\n      handlers.onTextDelta(delta.content)\n    }\n\n    // 兼容 reasoning_content（DeepSeek）与 reasoning（部分 OpenAI 兼容端点）\n    const reasoning = delta.reasoning_content ?? delta.reasoning\n    if (typeof reasoning === 'string' && reasoning) {\n      handlers.onReasoningDelta?.(reasoning)\n    }\n\n    if (Array.isArray(delta.tool_calls)) {\n      for (const tc of delta.tool_calls) {\n        const index: number = tc.index ?? 0\n        // index 回退说明新的一轮 tool_calls 开始，先把已累积的抛出去\n        if (index <= lastIndex && accumulated.size > 0) flushToolCalls()\n        lastIndex = Math.max(lastIndex, index)\n\n        let call = accumulated.get(index)\n        if (!call) {\n          call = { id: '', name: '', arguments: '' }\n          accumulated.set(index, call)\n        }\n        if (tc.id) call.id = tc.id\n        if (tc.function?.name) call.name += tc.function.name\n        if (tc.function?.arguments) call.arguments += tc.function.arguments\n      }\n    }\n  }\n\n  try {\n    // 递归泵取代替 while 循环，避免 await-in-loop\n    const pump = async (): Promise<void> => {\n      const { done, value } = await reader.read()\n      if (done || signal.aborted) return\n\n      buffer += decoder.decode(value, { stream: true })\n\n      let newlineIndex: number\n      while ((newlineIndex = buffer.indexOf('\\n')) !== -1) {\n        const line = buffer.slice(0, newlineIndex).trim()\n        buffer = buffer.slice(newlineIndex + 1)\n        if (line.startsWith('data:')) {\n          handleData(line.slice(5).trim())\n        }\n      }\n\n      return pump()\n    }\n\n    await pump()\n\n    if (buffer.trim().startsWith('data:')) {\n      handleData(buffer.trim().slice(5).trim())\n    }\n  } finally {\n    reader.releaseLock()\n  }\n\n  flushToolCalls()\n}\n\n/**\n * 创建 OpenAI 兼容协议的传输层（chat/completions SSE）。\n * 手写 fetch + SSE 解析，无任何第三方依赖。\n */\nexport function createOpenAITransport(options: OpenAITransportOptions): ChatTransport {\n  const { endpoint, apiKey, model, headers, body } = options\n\n  return async (request: ChatTransportRequest, handlers: ChatTransportHandlers) => {\n    const { messages, systemPrompt, tools, signal } = request\n\n    let response: Response\n    try {\n      response = await fetch(endpoint, {\n        method: 'POST',\n        signal,\n        headers: {\n          'Content-Type': 'application/json',\n          ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),\n          ...headers\n        },\n        body: JSON.stringify({\n          model,\n          stream: true,\n          ...body,\n          messages: toOpenAIMessages(messages, systemPrompt),\n          ...(tools?.length ? { tools: toOpenAITools(tools) } : {})\n        })\n      })\n    } catch (error) {\n      if (!signal.aborted) {\n        handlers.onError?.(error instanceof Error ? error : new Error(String(error)))\n      }\n      return\n    }\n\n    if (!response.ok) {\n      const text = await response.text().catch(() => '')\n      handlers.onError?.(\n        new Error(`请求失败（${response.status}）：${text || response.statusText}`)\n      )\n      return\n    }\n\n    if (!response.body) {\n      handlers.onError?.(new Error('响应不包含可读取的流'))\n      return\n    }\n\n    try {\n      await parseSSE(response.body, signal, handlers)\n    } catch (error) {\n      if (!signal.aborted) {\n        handlers.onError?.(error instanceof Error ? error : new Error(String(error)))\n      }\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"openai.js","names":[],"sources":["../../../src/chat/transports/openai.ts"],"sourcesContent":["import type { ChatModelOption, ChatProvider } from '../../providers'\nimport type {\n  ChatMessage,\n  ChatTool,\n  ChatTransport,\n  ChatTransportHandlers,\n  ChatTransportRequest\n} from '../types'\n\n/** createOpenAITransport 的配置项（多 Provider） */\nexport interface OpenAITransportOptions {\n  /** 至少一个 Provider；模型 id 须跨 Provider 全局唯一 */\n  providers: ChatProvider[]\n  /** 全局额外请求头（与各 Provider headers 合并，Provider 优先） */\n  headers?: Record<string, string>\n  /** 全局额外请求体字段，如 temperature、top_p */\n  body?: Record<string, unknown>\n}\n\n/** 带扁平模型列表元数据的 OpenAI 兼容 transport */\nexport type OpenAITransport = ChatTransport & {\n  /** 供 UI 使用的扁平模型列表 */\n  readonly models: ChatModelOption[]\n  /** 默认模型 id（首个 Provider 的首个模型） */\n  readonly defaultModel: string\n}\n\ninterface OpenAIMessage {\n  role: string\n  content?: unknown\n  tool_calls?: unknown[]\n  tool_call_id?: string\n}\n\nfunction toOpenAIMessages(messages: ChatMessage[], systemPrompt?: string): OpenAIMessage[] {\n  const result: OpenAIMessage[] = []\n\n  if (systemPrompt) {\n    result.push({ role: 'system', content: systemPrompt })\n  }\n\n  for (const msg of messages) {\n    if (msg.role === 'user') {\n      if (msg.attachments?.length) {\n        const parts: unknown[] = []\n        if (msg.content) parts.push({ type: 'text', text: msg.content })\n        for (const att of msg.attachments) {\n          parts.push({ type: 'image_url', image_url: { url: att.dataUrl } })\n        }\n        result.push({ role: 'user', content: parts })\n      } else {\n        result.push({ role: 'user', content: msg.content })\n      }\n    } else if (msg.role === 'assistant') {\n      const item: OpenAIMessage = { role: 'assistant', content: msg.content || '' }\n      if (msg.toolCalls?.length) {\n        item.tool_calls = msg.toolCalls.map((call) => ({\n          id: call.id,\n          type: 'function',\n          function: { name: call.name, arguments: call.arguments }\n        }))\n      }\n      result.push(item)\n    } else if (msg.role === 'tool') {\n      result.push({ role: 'tool', tool_call_id: msg.toolCallId, content: msg.content })\n    }\n  }\n\n  return result\n}\n\nfunction toOpenAITools(tools: ChatTool[]): unknown[] {\n  return tools.map((tool) => ({\n    type: 'function',\n    function: { name: tool.name, description: tool.description, parameters: tool.parameters }\n  }))\n}\n\ninterface AccumulatedToolCall {\n  id: string\n  name: string\n  arguments: string\n}\n\n/**\n * 逐行解析 SSE 流。\n * 兼容 OpenAI 及 DeepSeek 等 reasoning_content 风格的兼容端点。\n */\nasync function parseSSE(\n  body: ReadableStream<Uint8Array>,\n  signal: AbortSignal,\n  handlers: ChatTransportHandlers\n): Promise<void> {\n  const reader = body.getReader()\n  const decoder = new TextDecoder()\n  let buffer = ''\n\n  // 按 OpenAI 流式协议中 tool_calls 的 index 累积参数片段\n  const accumulated = new Map<number, AccumulatedToolCall>()\n  let lastIndex = -1\n\n  const flushToolCalls = () => {\n    if (!handlers.onToolCall) return\n    for (const call of accumulated.values()) {\n      if (call.id && call.name) {\n        handlers.onToolCall({ id: call.id, name: call.name, arguments: call.arguments })\n      }\n    }\n    accumulated.clear()\n  }\n\n  const handleData = (data: string) => {\n    if (data === '[DONE]') return\n\n    let chunk: any\n    try {\n      chunk = JSON.parse(data)\n    } catch {\n      return\n    }\n\n    const delta = chunk.choices?.[0]?.delta\n    if (!delta) return\n\n    if (typeof delta.content === 'string' && delta.content) {\n      handlers.onTextDelta(delta.content)\n    }\n\n    // 兼容 reasoning_content（DeepSeek）与 reasoning（部分 OpenAI 兼容端点）\n    const reasoning = delta.reasoning_content ?? delta.reasoning\n    if (typeof reasoning === 'string' && reasoning) {\n      handlers.onReasoningDelta?.(reasoning)\n    }\n\n    if (Array.isArray(delta.tool_calls)) {\n      for (const tc of delta.tool_calls) {\n        const index: number = tc.index ?? 0\n        // 同一调用的参数分片共享 index；index 变大才说明前一个调用已完整，先抛出去\n        if (index > lastIndex && accumulated.size > 0) flushToolCalls()\n        lastIndex = Math.max(lastIndex, index)\n\n        let call = accumulated.get(index)\n        if (!call) {\n          call = { id: '', name: '', arguments: '' }\n          accumulated.set(index, call)\n        }\n        if (tc.id) call.id = tc.id\n        if (tc.function?.name) call.name += tc.function.name\n        if (tc.function?.arguments) call.arguments += tc.function.arguments\n      }\n    }\n  }\n\n  try {\n    // 递归泵取代替 while 循环，避免 await-in-loop\n    const pump = async (): Promise<void> => {\n      const { done, value } = await reader.read()\n      if (done || signal.aborted) return\n\n      buffer += decoder.decode(value, { stream: true })\n\n      let newlineIndex: number\n      while ((newlineIndex = buffer.indexOf('\\n')) !== -1) {\n        const line = buffer.slice(0, newlineIndex).trim()\n        buffer = buffer.slice(newlineIndex + 1)\n        if (line.startsWith('data:')) {\n          handleData(line.slice(5).trim())\n        }\n      }\n\n      return pump()\n    }\n\n    await pump()\n\n    if (buffer.trim().startsWith('data:')) {\n      handleData(buffer.trim().slice(5).trim())\n    }\n  } finally {\n    reader.releaseLock()\n  }\n\n  flushToolCalls()\n}\n\n/** 校验 providers 并展开扁平模型列表 */\nfunction flattenModels(providers: ChatProvider[]): {\n  models: ChatModelOption[]\n  byModelId: Map<string, ChatProvider>\n} {\n  if (!providers.length) {\n    throw new Error('[createOpenAITransport] providers 不能为空')\n  }\n\n  const models: ChatModelOption[] = []\n  const byModelId = new Map<string, ChatProvider>()\n\n  for (const provider of providers) {\n    if (!provider.models?.length) {\n      throw new Error(`[createOpenAITransport] Provider \"${provider.id}\" 未配置 models`)\n    }\n    for (const model of provider.models) {\n      if (byModelId.has(model.id)) {\n        throw new Error(\n          `[createOpenAITransport] 模型 id \"${model.id}\" 重复（跨 Provider 须全局唯一）`\n        )\n      }\n      byModelId.set(model.id, provider)\n      models.push({ ...model, providerId: provider.id, providerLabel: provider.label })\n    }\n  }\n\n  return { models, byModelId }\n}\n\n/** 缺省：写入 OpenAI 兼容的 reasoning_effort */\nfunction defaultApplyReasoning(level: string, body: Record<string, unknown>) {\n  body.reasoning_effort = level\n}\n\n/**\n * 创建 OpenAI 兼容协议的传输层（chat/completions SSE）。\n * 按 request.model 路由到对应 Provider 的 endpoint；手写 fetch + SSE，无第三方依赖。\n */\nexport function createOpenAITransport(options: OpenAITransportOptions): OpenAITransport {\n  const { providers, headers: globalHeaders, body: globalBody } = options\n  const { models, byModelId } = flattenModels(providers)\n  const defaultModel = models[0]!.id\n\n  const send: ChatTransport = async (\n    request: ChatTransportRequest,\n    handlers: ChatTransportHandlers\n  ) => {\n    const { messages, systemPrompt, tools, signal, reasoningLevel } = request\n    const modelId = request.model ?? defaultModel\n    const provider = byModelId.get(modelId)\n\n    if (!provider) {\n      handlers.onError?.(new Error(`未找到模型 \"${modelId}\" 对应的 Provider`))\n      return\n    }\n\n    const requestBody: Record<string, unknown> = {\n      ...globalBody,\n      model: modelId,\n      stream: true,\n      messages: toOpenAIMessages(messages, systemPrompt),\n      ...(tools?.length ? { tools: toOpenAITools(tools) } : {})\n    }\n\n    if (reasoningLevel) {\n      const apply = provider.applyReasoning ?? defaultApplyReasoning\n      apply(reasoningLevel, requestBody)\n    }\n\n    let response: Response\n    try {\n      response = await fetch(provider.endpoint, {\n        method: 'POST',\n        signal,\n        headers: {\n          'Content-Type': 'application/json',\n          ...(provider.apiKey ? { Authorization: `Bearer ${provider.apiKey}` } : {}),\n          ...globalHeaders,\n          ...provider.headers\n        },\n        body: JSON.stringify(requestBody)\n      })\n    } catch (error) {\n      if (!signal.aborted) {\n        handlers.onError?.(error instanceof Error ? error : new Error(String(error)))\n      }\n      return\n    }\n\n    if (!response.ok) {\n      const text = await response.text().catch(() => '')\n      handlers.onError?.(\n        new Error(`请求失败（${response.status}）：${text || response.statusText}`)\n      )\n      return\n    }\n\n    if (!response.body) {\n      handlers.onError?.(new Error('响应不包含可读取的流'))\n      return\n    }\n\n    try {\n      await parseSSE(response.body, signal, handlers)\n    } catch (error) {\n      if (!signal.aborted) {\n        handlers.onError?.(error instanceof Error ? error : new Error(String(error)))\n      }\n    }\n  }\n\n  return Object.assign(send, { models, defaultModel })\n}\n"],"mappings":"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"}

package/dist/chat/types.d.ts

@@ -47,6 +47,15 @@ interface ChatMessage {
   /** 消息状态，仅 assistant 消息使用 */
   status?: 'streaming' | 'done' | 'error' | 'aborted';
 }
+/** 队列中的待发送消息（会话进行中提交的消息按序排队） */
+interface ChatQueuedMessage {
+  /** 队列项 id */
+  id: string;
+  /** 消息内容 */
+  content: string;
+  /** 携带的附件 */
+  attachments?: ChatAttachment[];
+}
 /** 工具执行上下文 */
 interface ChatToolContext {
   /** 本次工具调用 */
@@ -74,10 +83,36 @@ interface ChatTool<A = any> {
   /**
    * 自定义工具卡片内容渲染（组件或渲染函数），props 为 ChatToolRenderProps。
    * 设置后替换卡片 body 的默认参数/结果展示；优先级高于 tool-<name> 插槽。
+   * renderTo 为 'panel' 时改为在右侧侧边面板中渲染。
    */
   render?: Component;
-  /** 执行完成后是否自动折叠。缺省：设置了 render 时为 false，否则为 true */
+  /**
+   * 渲染位置。缺省 'inline'：render 组件展示在会话内的工具卡片中；
+   * 'panel'：render 组件展示在对话区右侧的侧边面板（新调用自动打开面板，
+   * 工具卡片内仅保留「查看面板」入口，面板与会话区宽度可拖拽调节）。
+   * 适合打开后台页面、表单、图表、列表等需要较大交互区域的工具。
+   */
+  renderTo?: 'inline' | 'panel';
+  /**
+   * 侧边面板默认宽度（px，最小 320），仅 renderTo: 'panel' 时生效。
+   * 聚焦到该工具的调用时应用；缺省时面板打开取「容器宽 - 860」（即默认尽可能大，
+   * 给会话区保留 860px）；面板已打开时切换聚焦保持当前宽度（含用户拖拽结果）。
+   */
+  panelWidth?: number;
+  /**
+   * 侧边面板标题，仅 renderTo: 'panel' 时生效。
+   * 面板标题通常是「业务对象 + 动作」（如「编辑用户 · 张三」）而非工具名，
+   * 可传固定字符串，或传函数按本次调用的参数动态生成。缺省取 label ?? name。
+   */
+  panelTitle?: string | ((toolCall: ChatToolCall) => string);
+  /** 执行完成后是否自动折叠。缺省：renderTo 为 'panel' 时为 true；否则设置了 render 时为 false，否则为 true */
   autoCollapse?: boolean;
+  /**
+   * 终结工具：执行成功后对话即结束，结果不再回灌模型生成额外文字（工具 UI 即最终答复）。
+   * 适合天气卡片这类"UI 即答案"的工具，需配合 render 或 tool-<name> 插槽提供完整结果 UI。
+   * 工具结果仍会记录到消息历史供后续轮次使用；执行失败/被拒绝时错误照常回灌模型。
+   */
+  terminal?: boolean;
   /** 工具实现，返回值（或 Promise 返回值）会被 JSON 序列化后回灌给模型 */
   execute: (args: A, ctx: ChatToolContext) => unknown;
 }
@@ -94,6 +129,10 @@ interface ChatTransportRequest {
   systemPrompt?: string;
   /** 可用工具 */
   tools?: ChatTool[];
+  /** 选中的模型 id（内置 OpenAI transport 按此路由 Provider） */
+  model?: string;
+  /** 选中的推理等级（不透明字符串，由 Provider.applyReasoning 写入请求体） */
+  reasoningLevel?: string;
   /** 中断信号 */
   signal: AbortSignal;
 }
@@ -121,5 +160,5 @@ interface ChatTransportHandlers {
  */
 type ChatTransport = (request: ChatTransportRequest, handlers: ChatTransportHandlers) => Promise<void> | void;
 //#endregion
-export { ChatAttachment, ChatMessage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus };
+export { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus };
 //# sourceMappingURL=types.d.ts.map

package/dist/chat/use-chat.d.ts

@@ -1,4 +1,4 @@
-import { ChatAttachment, ChatMessage } from "./types.js";
+import { ChatAttachment, ChatMessage, ChatQueuedMessage } from "./types.js";
 import { AiChatEmits, AiChatProps } from "../types/ai-chat.js";
 import "../types/index.js";
 import { Ref } from "vue";
@@ -10,15 +10,40 @@ interface UseChatOptions {
 /**
  * AI 对话核心状态机：消息管理、流式追加、工具调用循环编排。
  * 与 UI 解耦，ai-chat.vue 只负责渲染与交互转发。
+ * 始终注入内置工具（如 askQuestion），无需经 props 传入。
  */
 declare function useChat(options: UseChatOptions): {
   messages: Ref<ChatMessage[], ChatMessage[]>;
+  model: Ref<string | undefined, string | undefined>;
+  reasoningLevel: Ref<string | undefined, string | undefined>;
   running: Ref<boolean, boolean>;
+  queue: Ref<{
+    id: string;
+    content: string;
+    attachments?: {
+      name: string;
+      mimeType: string;
+      size: number;
+      dataUrl: string;
+    }[] | undefined;
+  }[], ChatQueuedMessage[] | {
+    id: string;
+    content: string;
+    attachments?: {
+      name: string;
+      mimeType: string;
+      size: number;
+      dataUrl: string;
+    }[] | undefined;
+  }[]>;
   send: (content: string, attachments?: ChatAttachment[]) => void;
   abort: () => void;
   regenerate: () => void;
   clear: () => void;
   respondToolCall: (toolCallId: string, approved: boolean) => void;
+  enqueue: (content: string, attachments?: ChatAttachment[], beforeId?: string) => ChatQueuedMessage;
+  startQueued: (id: string) => void;
+  removeQueued: (id: string) => ChatQueuedMessage | undefined;
 };
 //#endregion
 export { UseChatOptions, useChat };

package/dist/chat/use-chat.js

@@ -1,5 +1,6 @@
+import { createBuiltinTools } from "../tools/index.js";
 import { useModel } from "@veltra/compositions";
-import { reactive, ref } from "vue";
+import { reactive, ref, watch } from "vue";
 //#region src/chat/use-chat.ts
 const uid = () => {
 	return typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
@@ -12,9 +13,16 @@ function serializeResult(result) {
 		return String(result);
 	}
 }
+/** 内置工具 + 用户工具，同名时内置优先 */
+function resolveTools(userTools) {
+	const builtins = createBuiltinTools();
+	const names = new Set(builtins.map((t) => t.name));
+	return [...builtins, ...(userTools ?? []).filter((t) => !names.has(t.name))];
+}
 /**
 * AI 对话核心状态机：消息管理、流式追加、工具调用循环编排。
 * 与 UI 解耦，ai-chat.vue 只负责渲染与交互转发。
+* 始终注入内置工具（如 askQuestion），无需经 props 传入。
 */
 function useChat(options) {
 	const { props, emit } = options;
@@ -25,19 +33,102 @@ function useChat(options) {
 		local: true,
 		defaultValue: []
 	});
+	const model = useModel({
+		props,
+		propName: "model",
+		emit,
+		local: true
+	});
+	const reasoningLevel = useModel({
+		props,
+		propName: "reasoningLevel",
+		emit,
+		local: true
+	});
 	/** 是否正在生成中（含工具执行与多轮循环） */
 	const running = ref(false);
+	/** 待发送队列：会话进行中提交的新消息按序排队，收尾后先进先出自动接续 */
+	const queue = ref([]);
 	let abortController = null;
 	/** needsConfirm 工具的挂起确认器，key 为 toolCallId */
 	const confirmResolvers = /* @__PURE__ */ new Map();
+	/** 当前会话是否自然完成（finish）；决定收尾后是否自动消耗队列 */
+	let finishedNaturally = false;
+	/** startQueued 触发的中断需要在收尾后立即接续队首 */
+	let resumeAfterAbort = false;
+	/** 按当前模型校正推理等级（无 levels 则清空；值不合法则落到默认/首项） */
+	const syncReasoningForModel = (modelId) => {
+		const option = props.models?.find((m) => m.id === modelId);
+		if (!option?.reasoningLevels?.length) {
+			if (reasoningLevel.value !== void 0) reasoningLevel.value = void 0;
+			return;
+		}
+		const levels = option.reasoningLevels;
+		if (reasoningLevel.value && levels.some((l) => l.value === reasoningLevel.value)) return;
+		reasoningLevel.value = option.defaultReasoningLevel ?? levels[0]?.value;
+	};
+	watch(() => [props.models, model.value], ([models, current]) => {
+		if (!models?.length) return;
+		if (!current || !models.some((m) => m.id === current)) {
+			model.value = models[0].id;
+			return;
+		}
+		syncReasoningForModel(current);
+	}, { immediate: true });
 	/** 向父组件同步消息快照（流式 delta 过于频繁，不同步，只在关键节点同步） */
 	const snapshot = () => {
 		emit("update:messages", messages.value.slice());
 	};
-	/** 发送一条用户消息并启动对话循环 */
+	/**
+	* 发送一条用户消息。会话进行中时进入待发送队列（不丢失），
+	* 会话自然结束后按 FIFO 自动接续；空闲时立即开始新会话。
+	*/
 	const send = (content, attachments) => {
-		if (running.value) return;
 		if (!content.trim() && !attachments?.length) return;
+		enqueue(content, attachments);
+	};
+	/**
+	* 向队列插入一条消息；beforeId 指定插到某条之前（缺省追加到尾部）。
+	* 空闲时立即消耗队首（保持先来先发的合理顺序）。
+	*/
+	const enqueue = (content, attachments, beforeId) => {
+		const item = {
+			id: uid(),
+			content,
+			attachments
+		};
+		const anchorIndex = beforeId ? queue.value.findIndex((q) => q.id === beforeId) : -1;
+		if (anchorIndex === -1) queue.value.push(item);
+		else queue.value.splice(anchorIndex, 0, item);
+		if (!running.value) drainQueue();
+		return item;
+	};
+	/** 消耗队首并开始新一轮会话 */
+	const drainQueue = () => {
+		const next = queue.value.shift();
+		if (next) startUserTurn(next.content, next.attachments);
+	};
+	/** 立即执行队列中的某条：中断当前会话，该条插队为下一条（其余保持原顺序） */
+	const startQueued = (id) => {
+		const item = removeQueued(id);
+		if (!item) return;
+		if (!running.value) {
+			startUserTurn(item.content, item.attachments);
+			return;
+		}
+		queue.value.unshift(item);
+		resumeAfterAbort = true;
+		abort();
+	};
+	/** 从队列移除某条（返回被移除项；编辑场景由 UI 取回内容） */
+	const removeQueued = (id) => {
+		const index = queue.value.findIndex((item) => item.id === id);
+		if (index === -1) return void 0;
+		const [item] = queue.value.splice(index, 1);
+		return item;
+	};
+	/** 推送用户消息并启动对话循环 */
+	const startUserTurn = (content, attachments) => {
 		const message = reactive({
 			id: uid(),
 			role: "user",
@@ -50,7 +141,7 @@ function useChat(options) {
 		runConversation();
 	};
 	/** 执行单个工具调用（含确认门控），结果以 tool 消息追加 */
-	const executeToolCall = async (toolCall, signal) => {
+	const executeToolCall = async (toolCall, signal, tools) => {
 		const appendToolMessage = (content) => {
 			messages.value.push(reactive({
 				id: uid(),
@@ -59,7 +150,7 @@ function useChat(options) {
 				content
 			}));
 		};
-		const tool = props.tools?.find((t) => t.name === toolCall.name);
+		const tool = tools.find((t) => t.name === toolCall.name);
 		if (!tool) {
 			toolCall.status = "error";
 			toolCall.error = `未找到名为 "${toolCall.name}" 的工具`;
@@ -99,20 +190,26 @@ function useChat(options) {
 	const runConversation = async () => {
 		if (!props.transport) return;
 		running.value = true;
+		finishedNaturally = false;
 		const controller = new AbortController();
 		abortController = controller;
 		try {
-			await runRound(controller);
+			await runRound(controller, 0);
 		} finally {
 			running.value = false;
 			abortController = null;
 			snapshot();
+			const shouldResume = finishedNaturally || resumeAfterAbort;
+			finishedNaturally = false;
+			resumeAfterAbort = false;
+			if (shouldResume) drainQueue();
 		}
 	};
 	/** 单轮生成；存在工具调用时执行后递归进入下一轮（递归避免 await-in-loop） */
-	const runRound = async (controller) => {
+	const runRound = async (controller, depth) => {
 		if (!props.transport) return;
 		const { signal } = controller;
+		const tools = resolveTools(props.tools);
 		const assistant = reactive({
 			id: uid(),
 			role: "assistant",
@@ -126,7 +223,9 @@ function useChat(options) {
 			await props.transport({
 				messages: messages.value.slice(0, -1),
 				systemPrompt: props.systemPrompt,
-				tools: props.tools,
+				tools,
+				model: model.value,
+				reasoningLevel: reasoningLevel.value,
 				signal
 			}, {
 				onTextDelta: (delta) => {
@@ -162,13 +261,26 @@ function useChat(options) {
 		assistant.status = "done";
 		const toolCalls = assistant.toolCalls ?? [];
 		if (!toolCalls.length) {
-			emit("finish", assistant);
+			completeAsFinish(assistant);
 			return;
 		}
-		await toolCalls.reduce((prev, toolCall) => prev.then(() => signal.aborted ? void 0 : executeToolCall(toolCall, signal)), Promise.resolve());
+		await toolCalls.reduce((prev, toolCall) => prev.then(() => signal.aborted ? void 0 : executeToolCall(toolCall, signal, tools)), Promise.resolve());
 		snapshot();
 		if (signal.aborted) return;
-		return runRound(controller);
+		if (toolCalls.some((call) => call.status === "success" && tools.some((t) => t.name === call.name && t.terminal))) {
+			completeAsFinish(assistant);
+			return;
+		}
+		if (depth + 1 >= (props.maxToolRounds ?? 10)) {
+			completeAsFinish(assistant);
+			return;
+		}
+		return runRound(controller, depth + 1);
+	};
+	/** 标记本轮对话自然完成（收尾后据此自动消耗待发送队列） */
+	const completeAsFinish = (assistant) => {
+		finishedNaturally = true;
+		emit("finish", assistant);
 	};
 	/** 中断当前生成，挂起的工具确认按拒绝处理 */
 	const abort = () => {
@@ -192,20 +304,27 @@ function useChat(options) {
 		snapshot();
 		runConversation();
 	};
-	/** 清空消息，生成中则先中断 */
+	/** 清空消息与待发送队列，生成中则先中断 */
 	const clear = () => {
 		abort();
+		queue.value = [];
 		messages.value = [];
 		snapshot();
 	};
 	return {
 		messages,
+		model,
+		reasoningLevel,
 		running,
+		queue,
 		send,
 		abort,
 		regenerate,
 		clear,
-		respondToolCall
+		respondToolCall,
+		enqueue,
+		startQueued,
+		removeQueued
 	};
 }
 //#endregion