@veltra/ai 1.4.0 → 2.1.0

package/src/chat/transports/__test__/openai.test.ts

@@ -0,0 +1,317 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { ChatTransportHandlers } from '../../types'
+import { createOpenAITransport } from '../openai'
+
+const baseHandlers = (): ChatTransportHandlers => ({
+  onTextDelta: vi.fn(),
+  onReasoningDelta: vi.fn(),
+  onToolCall: vi.fn(),
+  onError: vi.fn()
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('createOpenAITransport', () => {
+  it('providers 为空时抛错', () => {
+    expect(() => createOpenAITransport({ providers: [] })).toThrow(/providers 不能为空/)
+  })
+
+  it('跨 Provider 模型 id 重复时抛错', () => {
+    expect(() =>
+      createOpenAITransport({
+        providers: [
+          {
+            id: 'a',
+            endpoint: 'https://a.example/v1/chat/completions',
+            models: [{ id: 'shared' }]
+          },
+          { id: 'b', endpoint: 'https://b.example/v1/chat/completions', models: [{ id: 'shared' }] }
+        ]
+      })
+    ).toThrow(/模型 id "shared" 重复/)
+  })
+
+  it('挂载 models 与 defaultModel', () => {
+    const transport = createOpenAITransport({
+      providers: [
+        {
+          id: 'openai',
+          label: 'OpenAI',
+          endpoint: 'https://api.openai.com/v1/chat/completions',
+          apiKey: 'sk-test',
+          models: [
+            { id: 'gpt-4o', label: 'GPT-4o' },
+            { id: 'o3-mini', label: 'o3-mini' }
+          ]
+        }
+      ]
+    })
+
+    expect(transport.defaultModel).toBe('gpt-4o')
+    expect(transport.models).toEqual([
+      { id: 'gpt-4o', label: 'GPT-4o', providerId: 'openai', providerLabel: 'OpenAI' },
+      { id: 'o3-mini', label: 'o3-mini', providerId: 'openai', providerLabel: 'OpenAI' }
+    ])
+  })
+
+  it('按 model 路由到不同 endpoint，相对路径原样 fetch', async () => {
+    const fetchMock = vi.fn(async () => {
+      return new Response('data: {"choices":[{"delta":{"content":"ok"}}]}\n\ndata: [DONE]\n\n', {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' }
+      })
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const transport = createOpenAITransport({
+      providers: [
+        { id: 'proxy', endpoint: '/api/ai/chat', models: [{ id: 'proxy-model' }] },
+        {
+          id: 'remote',
+          endpoint: 'https://api.example.com/v1/chat/completions',
+          apiKey: 'sk-remote',
+          models: [{ id: 'remote-model' }]
+        }
+      ]
+    })
+
+    const handlers = baseHandlers()
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        model: 'remote-model',
+        signal: new AbortController().signal
+      },
+      handlers
+    )
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock.mock.calls[0]![0]).toBe('https://api.example.com/v1/chat/completions')
+    const remoteInit = fetchMock.mock.calls[0]![1] as RequestInit
+    expect(remoteInit.headers).toMatchObject({ Authorization: 'Bearer sk-remote' })
+    expect(JSON.parse(String(remoteInit.body))).toMatchObject({
+      model: 'remote-model',
+      stream: true
+    })
+
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        model: 'proxy-model',
+        signal: new AbortController().signal
+      },
+      handlers
+    )
+
+    expect(fetchMock.mock.calls[1]![0]).toBe('/api/ai/chat')
+    const proxyInit = fetchMock.mock.calls[1]![1] as RequestInit
+    expect((proxyInit.headers as Record<string, string>).Authorization).toBeUndefined()
+  })
+
+  it('无 apiKey 时不带 Authorization', async () => {
+    const fetchMock = vi.fn(async () => {
+      return new Response('data: [DONE]\n\n', {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' }
+      })
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const transport = createOpenAITransport({
+      providers: [{ id: 'local', endpoint: '/api/chat', models: [{ id: 'local-model' }] }]
+    })
+
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        signal: new AbortController().signal
+      },
+      baseHandlers()
+    )
+
+    const headers = fetchMock.mock.calls[0]![1]!.headers as Record<string, string>
+    expect(headers.Authorization).toBeUndefined()
+    expect(JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))).toMatchObject({
+      model: 'local-model'
+    })
+  })
+
+  it('缺省将 reasoningLevel 写入 reasoning_effort', async () => {
+    const fetchMock = vi.fn(async () => {
+      return new Response('data: [DONE]\n\n', {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' }
+      })
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const transport = createOpenAITransport({
+      providers: [
+        {
+          id: 'openai',
+          endpoint: 'https://api.openai.com/v1/chat/completions',
+          apiKey: 'sk',
+          models: [{ id: 'o3-mini' }]
+        }
+      ]
+    })
+
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        model: 'o3-mini',
+        reasoningLevel: 'high',
+        signal: new AbortController().signal
+      },
+      baseHandlers()
+    )
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))).toMatchObject({
+      model: 'o3-mini',
+      reasoning_effort: 'high'
+    })
+  })
+
+  it('applyReasoning 可自定义写入字段', async () => {
+    const fetchMock = vi.fn(async () => {
+      return new Response('data: [DONE]\n\n', {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' }
+      })
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const transport = createOpenAITransport({
+      providers: [
+        {
+          id: 'custom',
+          endpoint: 'https://custom.example/chat',
+          applyReasoning: (level, body) => {
+            body.thinking = { budget: level }
+          },
+          models: [{ id: 'custom-model' }]
+        }
+      ]
+    })
+
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        reasoningLevel: '8k',
+        signal: new AbortController().signal
+      },
+      baseHandlers()
+    )
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))).toMatchObject({
+      thinking: { budget: '8k' }
+    })
+    expect(JSON.parse(String(fetchMock.mock.calls[0]![1]!.body)).reasoning_effort).toBeUndefined()
+  })
+
+  it('未知 model 时通过 onError 报错且不发请求', async () => {
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+    const handlers = baseHandlers()
+
+    const transport = createOpenAITransport({
+      providers: [{ id: 'a', endpoint: 'https://a.example/chat', models: [{ id: 'known' }] }]
+    })
+
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        model: 'unknown',
+        signal: new AbortController().signal
+      },
+      handlers
+    )
+
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(handlers.onError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: expect.stringContaining('unknown') })
+    )
+  })
+
+  it('工具调用参数分片跨 chunk 累积为一次完整 onToolCall', async () => {
+    // 同一工具调用的多个分片共享 index:0，不得被误判为"新一轮"而提前 flush
+    const sse = String.raw`data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_1","function":{"name":"calculate","arguments":""}}]}}]}
+
+data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"ex"}}]}}]}
+
+data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"pression\":\"1+1\"}"}}]}}]}
+
+data: [DONE]
+`
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(sse, { status: 200 }))
+    )
+
+    const transport = createOpenAITransport({
+      providers: [{ id: 'a', endpoint: 'https://a.example/chat', models: [{ id: 'm' }] }]
+    })
+    const handlers = baseHandlers()
+
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        signal: new AbortController().signal
+      },
+      handlers
+    )
+
+    expect(handlers.onToolCall).toHaveBeenCalledTimes(1)
+    expect(handlers.onToolCall).toHaveBeenCalledWith({
+      id: 'call_1',
+      name: 'calculate',
+      arguments: '{"expression":"1+1"}'
+    })
+  })
+
+  it('多个工具调用按 index 顺序完整抛出', async () => {
+    const sse = String.raw`data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_1","function":{"name":"alpha","arguments":""}}]}}]}
+
+data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"x\":1}"}}]}}]}
+
+data: {"choices":[{"delta":{"tool_calls":[{"index":1,"id":"call_2","function":{"name":"beta","arguments":""}}]}}]}
+
+data: {"choices":[{"delta":{"tool_calls":[{"index":1,"function":{"arguments":"{\"y\":2}"}}]}}]}
+
+data: [DONE]
+`
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(sse, { status: 200 }))
+    )
+
+    const transport = createOpenAITransport({
+      providers: [{ id: 'a', endpoint: 'https://a.example/chat', models: [{ id: 'm' }] }]
+    })
+    const handlers = baseHandlers()
+
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        signal: new AbortController().signal
+      },
+      handlers
+    )
+
+    expect(handlers.onToolCall).toHaveBeenCalledTimes(2)
+    expect(handlers.onToolCall).toHaveBeenNthCalledWith(1, {
+      id: 'call_1',
+      name: 'alpha',
+      arguments: '{"x":1}'
+    })
+    expect(handlers.onToolCall).toHaveBeenNthCalledWith(2, {
+      id: 'call_2',
+      name: 'beta',
+      arguments: '{"y":2}'
+    })
+  })
+})

package/src/chat/transports/openai.ts

@@ -1,3 +1,4 @@
+import type { ChatModelOption, ChatProvider } from '../../providers'
 import type {
   ChatMessage,
   ChatTool,
@@ -6,20 +7,24 @@ import type {
   ChatTransportRequest
 } from '../types'
 
-/** createOpenAITransport 的配置项 */
+/** createOpenAITransport 的配置项（多 Provider） */
 export 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 */
+export type OpenAITransport = ChatTransport & {
+  /** 供 UI 使用的扁平模型列表 */
+  readonly models: ChatModelOption[]
+  /** 默认模型 id（首个 Provider 的首个模型） */
+  readonly defaultModel: string
+}
+
 interface OpenAIMessage {
   role: string
   content?: unknown
@@ -130,8 +135,8 @@ async function parseSSE(
     if (Array.isArray(delta.tool_calls)) {
       for (const tc of delta.tool_calls) {
         const index: number = tc.index ?? 0
-        // index 回退说明新的一轮 tool_calls 开始，先把已累积的抛出去
-        if (index <= lastIndex && accumulated.size > 0) flushToolCalls()
+        // 同一调用的参数分片共享 index；index 变大才说明前一个调用已完整，先抛出去
+        if (index > lastIndex && accumulated.size > 0) flushToolCalls()
         lastIndex = Math.max(lastIndex, index)
 
         let call = accumulated.get(index)
@@ -178,33 +183,88 @@ async function parseSSE(
   flushToolCalls()
 }
 
+/** 校验 providers 并展开扁平模型列表 */
+function flattenModels(providers: ChatProvider[]): {
+  models: ChatModelOption[]
+  byModelId: Map<string, ChatProvider>
+} {
+  if (!providers.length) {
+    throw new Error('[createOpenAITransport] providers 不能为空')
+  }
+
+  const models: ChatModelOption[] = []
+  const byModelId = new Map<string, ChatProvider>()
+
+  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: string, body: Record<string, unknown>) {
+  body.reasoning_effort = level
+}
+
 /**
  * 创建 OpenAI 兼容协议的传输层（chat/completions SSE）。
- * 手写 fetch + SSE 解析，无任何第三方依赖。
+ * 按 request.model 路由到对应 Provider 的 endpoint；手写 fetch + SSE，无第三方依赖。
  */
-export function createOpenAITransport(options: OpenAITransportOptions): ChatTransport {
-  const { endpoint, apiKey, model, headers, body } = options
+export function createOpenAITransport(options: OpenAITransportOptions): OpenAITransport {
+  const { providers, headers: globalHeaders, body: globalBody } = options
+  const { models, byModelId } = flattenModels(providers)
+  const defaultModel = models[0]!.id
 
-  return async (request: ChatTransportRequest, handlers: ChatTransportHandlers) => {
-    const { messages, systemPrompt, tools, signal } = request
+  const send: ChatTransport = async (
+    request: ChatTransportRequest,
+    handlers: ChatTransportHandlers
+  ) => {
+    const { messages, systemPrompt, tools, signal, reasoningLevel } = request
+    const modelId = request.model ?? defaultModel
+    const provider = byModelId.get(modelId)
+
+    if (!provider) {
+      handlers.onError?.(new Error(`未找到模型 "${modelId}" 对应的 Provider`))
+      return
+    }
+
+    const requestBody: Record<string, unknown> = {
+      ...globalBody,
+      model: modelId,
+      stream: true,
+      messages: toOpenAIMessages(messages, systemPrompt),
+      ...(tools?.length ? { tools: toOpenAITools(tools) } : {})
+    }
+
+    if (reasoningLevel) {
+      const apply = provider.applyReasoning ?? defaultApplyReasoning
+      apply(reasoningLevel, requestBody)
+    }
 
     let response: 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) {
@@ -234,4 +294,6 @@ export function createOpenAITransport(options: OpenAITransportOptions): ChatTran
       }
     }
   }
+
+  return Object.assign(send, { models, defaultModel })
 }

package/src/chat/types.ts

@@ -57,6 +57,16 @@ export interface ChatMessage {
   status?: 'streaming' | 'done' | 'error' | 'aborted'
 }
 
+/** 队列中的待发送消息（会话进行中提交的消息按序排队） */
+export interface ChatQueuedMessage {
+  /** 队列项 id */
+  id: string
+  /** 消息内容 */
+  content: string
+  /** 携带的附件 */
+  attachments?: ChatAttachment[]
+}
+
 /** 工具执行上下文 */
 export interface ChatToolContext {
   /** 本次工具调用 */
@@ -85,10 +95,36 @@ export 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
 }
@@ -107,6 +143,10 @@ export interface ChatTransportRequest {
   systemPrompt?: string
   /** 可用工具 */
   tools?: ChatTool[]
+  /** 选中的模型 id（内置 OpenAI transport 按此路由 Provider） */
+  model?: string
+  /** 选中的推理等级（不透明字符串，由 Provider.applyReasoning 写入请求体） */
+  reasoningLevel?: string
   /** 中断信号 */
   signal: AbortSignal
 }