@veltra/ai 2.0.0 → 2.1.0

package/src/chat/__test__/use-chat.test.ts

@@ -212,13 +212,91 @@ describe('useChat', () => {
     expect(chat.messages.value).toHaveLength(2)
   })
 
-  it('生成中忽略重复 send', async () => {
+  it('生成中 send 进入队列，会话结束后按 FIFO 自动接续', async () => {
+    const emit = createEmit()
+    const resolvers: (() => void)[] = []
+
+    const transport: ChatTransport = (req, handlers) => {
+      const lastUser = [...req.messages].reverse().find((m) => m.role === 'user')
+      return new Promise<void>((resolve) => {
+        resolvers.push(() => {
+          handlers.onTextDelta(`回复:${lastUser?.content}`)
+          resolve()
+        })
+      })
+    }
+
+    const chat = useChat({ props: { transport }, emit })
+    chat.send('第一条')
+    chat.send('第二条')
+    chat.send('第三条')
+
+    // 进行中提交的消息进入队列，不直接追加为用户消息
+    expect(chat.queue.value.map((q) => q.content)).toEqual(['第二条', '第三条'])
+    expect(chat.messages.value.filter((m) => m.role === 'user')).toHaveLength(1)
+
+    resolvers[0]!()
+    await vi.waitFor(() => {
+      expect(chat.messages.value.filter((m) => m.role === 'user')).toHaveLength(2)
+    })
+    expect(chat.queue.value.map((q) => q.content)).toEqual(['第三条'])
+    expect(chat.messages.value[1]?.content).toBe('回复:第一条')
+
+    resolvers[1]!()
+    await vi.waitFor(() => {
+      expect(chat.messages.value.filter((m) => m.role === 'user')).toHaveLength(3)
+    })
+
+    resolvers[2]!()
+    await vi.waitFor(() => {
+      expect(chat.running.value).toBe(false)
+    })
+    expect(chat.queue.value).toHaveLength(0)
+    expect(chat.messages.value.at(-1)?.content).toBe('回复:第三条')
+  })
+
+  it('startQueued 中断当前会话并插队执行该条，其余保持顺序', async () => {
+    const emit = createEmit()
+    const resolvers: (() => void)[] = []
+
+    const transport: ChatTransport = (req, handlers) => {
+      return new Promise<void>((resolve) => {
+        resolvers.push(() => {
+          handlers.onTextDelta('ok')
+          resolve()
+        })
+        req.signal.addEventListener('abort', () => resolve(), { once: true })
+      })
+    }
+
+    const chat = useChat({ props: { transport }, emit })
+    chat.send('第一条')
+    chat.send('第二条')
+    chat.send('第三条')
+
+    const second = chat.queue.value[0]!
+    chat.startQueued(second.id)
+
+    // 当前会话中断，第二条插队开始执行，第三条仍在队列
+    await vi.waitFor(() => {
+      const users = chat.messages.value.filter((m) => m.role === 'user').map((m) => m.content)
+      expect(users).toEqual(['第一条', '第二条'])
+    })
+    expect(chat.messages.value[1]?.status).toBe('aborted')
+    expect(chat.queue.value.map((q) => q.content)).toEqual(['第三条'])
+
+    // 第二条完成后自动接续第三条
+    resolvers[1]!()
+    await vi.waitFor(() => {
+      expect(chat.messages.value.filter((m) => m.role === 'user')).toHaveLength(3)
+    })
+  })
+
+  it('手动 abort 后队列保留且不自动接续', async () => {
     const emit = createEmit()
-    let resolveStream: (() => void) | undefined
 
     const transport: ChatTransport = (req) => {
       return new Promise<void>((resolve) => {
-        resolveStream = resolve
         req.signal.addEventListener('abort', () => resolve(), { once: true })
       })
     }
@@ -226,22 +304,71 @@ describe('useChat', () => {
     const chat = useChat({ props: { transport }, emit })
     chat.send('第一条')
     chat.send('第二条')
-    resolveStream?.()
+    chat.abort()
 
-    await waitFinish(emit)
+    await vi.waitFor(() => {
+      expect(chat.running.value).toBe(false)
+    })
+    expect(chat.queue.value.map((q) => q.content)).toEqual(['第二条'])
     expect(chat.messages.value.filter((m) => m.role === 'user')).toHaveLength(1)
+    expect(emit).not.toHaveBeenCalledWith('finish', expect.anything())
   })
 
-  it('clear 清空消息', async () => {
+  it('enqueue 支持 beforeId 锚点插入，保持前后顺序', async () => {
     const emit = createEmit()
-    const chat = useChat({ props: { transport: textTransport('x') }, emit })
 
-    chat.send('hi')
-    await waitFinish(emit)
+    const transport: ChatTransport = (req) => {
+      return new Promise<void>((resolve) => {
+        req.signal.addEventListener('abort', () => resolve(), { once: true })
+      })
+    }
+
+    const chat = useChat({ props: { transport }, emit })
+    chat.send('第一条')
+    chat.enqueue('A')
+    chat.enqueue('C')
+    const cId = chat.queue.value[1]!.id
+    chat.enqueue('B', undefined, cId)
+
+    expect(chat.queue.value.map((q) => q.content)).toEqual(['A', 'B', 'C'])
+    chat.abort()
+  })
+
+  it('会话出错时不自动消耗队列', async () => {
+    const emit = createEmit()
+
+    const transport: ChatTransport = (_req, handlers) => {
+      handlers.onError?.(new Error('网络错误'))
+    }
+
+    const chat = useChat({ props: { transport }, emit })
+    chat.send('第一条')
+    chat.send('第二条')
 
+    await vi.waitFor(() => {
+      expect(emit).toHaveBeenCalledWith('error', expect.anything())
+    })
+    expect(chat.running.value).toBe(false)
+    expect(chat.queue.value.map((q) => q.content)).toEqual(['第二条'])
+  })
+
+  it('clear 同时清空待发送队列', async () => {
+    const emit = createEmit()
+
+    const transport: ChatTransport = (req) => {
+      return new Promise<void>((resolve) => {
+        req.signal.addEventListener('abort', () => resolve(), { once: true })
+      })
+    }
+
+    const chat = useChat({ props: { transport }, emit })
+    chat.send('第一条')
+    chat.send('第二条')
     chat.clear()
     await nextTick()
+
     expect(chat.messages.value).toHaveLength(0)
+    expect(chat.queue.value).toHaveLength(0)
   })
 
   it('请求携带 model 与 reasoningLevel', async () => {
@@ -314,4 +441,92 @@ describe('useChat', () => {
     await nextTick()
     expect(chat.reasoningLevel.value).toBe('low')
   })
+
+  it('terminal 工具执行成功后结束对话，不再请求模型生成文字', async () => {
+    const emit = createEmit()
+    const requests: ChatTransportRequest[] = []
+
+    const transport: ChatTransport = (req, handlers) => {
+      requests.push(req)
+      handlers.onToolCall?.({ id: 'call-1', name: 'getWeather', arguments: '{"city":"北京"}' })
+    }
+
+    const tools: ChatTool[] = [
+      {
+        name: 'getWeather',
+        description: '查天气',
+        parameters: {},
+        terminal: true,
+        execute: () => ({ temperature: 26 })
+      }
+    ]
+
+    const chat = useChat({ props: { transport, tools }, emit })
+    chat.send('北京天气')
+    await waitFinish(emit)
+
+    // 只请求一轮；工具结果仍进入消息历史
+    expect(requests).toHaveLength(1)
+    const messages = chat.messages.value
+    expect(messages.map((m) => m.role)).toEqual(['user', 'assistant', 'tool'])
+    expect(messages[1].toolCalls?.[0]).toMatchObject({ status: 'success' })
+  })
+
+  it('terminal 工具执行失败时仍回灌模型', async () => {
+    const emit = createEmit()
+    let round = 0
+
+    const transport: ChatTransport = (_req, handlers) => {
+      round++
+      if (round === 1) {
+        handlers.onToolCall?.({ id: 'call-1', name: 'getWeather', arguments: '{}' })
+      } else {
+        handlers.onTextDelta('没查到，换个城市试试')
+      }
+    }
+
+    const tools: ChatTool[] = [
+      {
+        name: 'getWeather',
+        description: '查天气',
+        parameters: {},
+        terminal: true,
+        execute: () => {
+          throw new Error('城市不存在')
+        }
+      }
+    ]
+
+    const chat = useChat({ props: { transport, tools }, emit })
+    chat.send('火星天气')
+    await waitFinish(emit)
+
+    expect(round).toBe(2)
+    expect(chat.messages.value[1].toolCalls?.[0]).toMatchObject({ status: 'error' })
+    expect(chat.messages.value[3]).toMatchObject({
+      role: 'assistant',
+      content: '没查到，换个城市试试'
+    })
+  })
+
+  it('模型持续调用工具时达到 maxToolRounds 上限即停止', async () => {
+    const emit = createEmit()
+    const requests: ChatTransportRequest[] = []
+
+    const transport: ChatTransport = (req, handlers) => {
+      requests.push(req)
+      handlers.onToolCall?.({ id: `call-${requests.length}`, name: 'noop', arguments: '{}' })
+    }
+
+    const tools: ChatTool[] = [
+      { name: 'noop', description: '空操作', parameters: {}, execute: () => ({}) }
+    ]
+
+    const chat = useChat({ props: { transport, tools, maxToolRounds: 3 }, emit })
+    chat.send('hi')
+    await waitFinish(emit)
+
+    expect(requests).toHaveLength(3)
+    expect(chat.running.value).toBe(false)
+  })
 })

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

@@ -236,4 +236,82 @@ describe('createOpenAITransport', () => {
       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

@@ -135,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)

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
 }

package/src/chat/use-chat.ts

@@ -3,7 +3,13 @@ import { reactive, ref, watch, type Ref } from 'vue'
 
 import { createBuiltinTools } from '../tools'
 import type { AiChatEmits, AiChatProps } from '../types'
-import type { ChatAttachment, ChatMessage, ChatTool, ChatToolCall } from './types'
+import type {
+  ChatAttachment,
+  ChatMessage,
+  ChatQueuedMessage,
+  ChatTool,
+  ChatToolCall
+} from './types'
 
 export interface UseChatOptions {
   props: AiChatProps
@@ -57,9 +63,16 @@ export function useChat(options: UseChatOptions) {
   /** 是否正在生成中（含工具执行与多轮循环） */
   const running = ref(false)
 
+  /** 待发送队列：会话进行中提交的新消息按序排队，收尾后先进先出自动接续 */
+  const queue = ref<ChatQueuedMessage[]>([])
+
   let abortController: AbortController | null = null
   /** needsConfirm 工具的挂起确认器，key 为 toolCallId */
   const confirmResolvers = new Map<string, (approved: boolean) => void>()
+  /** 当前会话是否自然完成（finish）；决定收尾后是否自动消耗队列 */
+  let finishedNaturally = false
+  /** startQueued 触发的中断需要在收尾后立即接续队首 */
+  let resumeAfterAbort = false
 
   /** 按当前模型校正推理等级（无 levels 则清空；值不合法则落到默认/首项） */
   const syncReasoningForModel = (modelId: string | undefined) => {
@@ -94,11 +107,67 @@ export function useChat(options: UseChatOptions) {
     emit('update:messages', messages.value.slice())
   }
 
-  /** 发送一条用户消息并启动对话循环 */
+  /**
+   * 发送一条用户消息。会话进行中时进入待发送队列（不丢失），
+   * 会话自然结束后按 FIFO 自动接续；空闲时立即开始新会话。
+   */
   const send = (content: string, attachments?: ChatAttachment[]) => {
-    if (running.value) return
     if (!content.trim() && !attachments?.length) return
+    enqueue(content, attachments)
+  }
+
+  /**
+   * 向队列插入一条消息；beforeId 指定插到某条之前（缺省追加到尾部）。
+   * 空闲时立即消耗队首（保持先来先发的合理顺序）。
+   */
+  const enqueue = (
+    content: string,
+    attachments?: ChatAttachment[],
+    beforeId?: string
+  ): ChatQueuedMessage => {
+    const item: ChatQueuedMessage = { 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: string) => {
+    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: string): ChatQueuedMessage | undefined => {
+    const index = queue.value.findIndex((item) => item.id === id)
+    if (index === -1) return undefined
+    const [item] = queue.value.splice(index, 1)
+    return item
+  }
+
+  /** 推送用户消息并启动对话循环 */
+  const startUserTurn = (content: string, attachments?: ChatAttachment[]) => {
     const message = reactive<ChatMessage>({ id: uid(), role: 'user', content, attachments })
     messages.value.push(message)
     snapshot()
@@ -162,20 +231,28 @@ export function useChat(options: UseChatOptions) {
     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()
+
+      // 队列接续：自然完成或 startQueued 中断插队时自动发下一条；
+      // 手动停止 / 出错时保留队列，交由用户处置
+      const shouldResume = finishedNaturally || resumeAfterAbort
+      finishedNaturally = false
+      resumeAfterAbort = false
+      if (shouldResume) drainQueue()
     }
   }
 
   /** 单轮生成；存在工具调用时执行后递归进入下一轮（递归避免 await-in-loop） */
-  const runRound = async (controller: AbortController): Promise<void> => {
+  const runRound = async (controller: AbortController, depth: number): Promise<void> => {
     if (!props.transport) return
     const { signal } = controller
     const tools = resolveTools(props.tools)
@@ -238,7 +315,7 @@ export function useChat(options: UseChatOptions) {
 
     const toolCalls = assistant.toolCalls ?? []
     if (!toolCalls.length) {
-      emit('finish', assistant)
+      completeAsFinish(assistant)
       return
     }
 
@@ -252,7 +329,28 @@ export function useChat(options: UseChatOptions) {
 
     if (signal.aborted) return
 
-    return runRound(controller)
+    // 终结工具执行成功：工具 UI 即最终答复，不再回灌模型生成文字
+    const hitTerminal = toolCalls.some(
+      (call) => call.status === 'success' && tools.some((t) => t.name === call.name && t.terminal)
+    )
+    if (hitTerminal) {
+      completeAsFinish(assistant)
+      return
+    }
+
+    // 达到最大轮次上限：停止继续请求，防止模型失控循环调用工具
+    if (depth + 1 >= (props.maxToolRounds ?? 10)) {
+      completeAsFinish(assistant)
+      return
+    }
+
+    return runRound(controller, depth + 1)
+  }
+
+  /** 标记本轮对话自然完成（收尾后据此自动消耗待发送队列） */
+  const completeAsFinish = (assistant: ChatMessage) => {
+    finishedNaturally = true
+    emit('finish', assistant)
   }
 
   /** 中断当前生成，挂起的工具确认按拒绝处理 */
@@ -284,9 +382,10 @@ export function useChat(options: UseChatOptions) {
     void runConversation()
   }
 
-  /** 清空消息，生成中则先中断 */
+  /** 清空消息与待发送队列，生成中则先中断 */
   const clear = () => {
     abort()
+    queue.value = []
     messages.value = []
     snapshot()
   }
@@ -296,10 +395,14 @@ export function useChat(options: UseChatOptions) {
     model,
     reasoningLevel,
     running,
+    queue,
     send,
     abort,
     regenerate,
     clear,
-    respondToolCall
+    respondToolCall,
+    enqueue,
+    startQueued,
+    removeQueued
   }
 }