@veltra/ai 1.4.0 → 2.1.0

package/dist/types/ai-chat.d.ts

@@ -1,4 +1,6 @@
-import { ChatAttachment, ChatMessage, ChatTool, ChatToolCall, ChatTransport } from "../chat/types.js";
+import { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTool, ChatToolCall, ChatTransport } from "../chat/types.js";
+import { ChatModelOption } from "../providers/types.js";
+import { Ref } from "vue";
 import { DeconstructValue } from "@veltra/utils";
 //#region src/types/ai-chat.d.ts
 interface AiChatProps {
@@ -8,10 +10,24 @@ interface AiChatProps {
   tools?: ChatTool[];
   /** 系统提示词 */
   systemPrompt?: string;
+  /**
+   * 单次发送允许的最大生成轮次（一轮 = 一次模型生成 + 可能的工具执行），默认 10。
+   * 模型持续调用工具不收敛时，达到上限即停止继续请求并发出 finish，防止失控循环。
+   */
+  maxToolRounds?: number;
   /** 消息列表，支持 v-model:messages 受控 */
   messages?: ChatMessage[];
-  /** 空状态欢迎语 */
-  welcome?: string;
+  /**
+   * 可选模型列表；有值则在输入栏展示模型选择器。
+   * 可从 createOpenAITransport() 返回值的 `.models` 直接传入。
+   */
+  models?: ChatModelOption[];
+  /** 当前模型 id，支持 v-model:model */
+  model?: string;
+  /** 当前推理等级，支持 v-model:reasoning-level */
+  reasoningLevel?: string;
+  /** 空状态欢迎项（快捷提问，点击即发送）；字符串按单项处理 */
+  welcome?: string | string[];
   /** 输入框占位文本 */
   placeholder?: string;
   /** 附件 accept 类型，默认 image/* */
@@ -24,9 +40,13 @@ interface AiChatProps {
 interface AiChatEmits {
   /** 消息列表变化 */
   (e: 'update:messages', messages: ChatMessage[]): void;
+  /** 当前模型变化 */
+  (e: 'update:model', model: string | undefined): void;
+  /** 当前推理等级变化 */
+  (e: 'update:reasoningLevel', reasoningLevel: string | undefined): void;
   /** 用户发送消息 */
   (e: 'send', message: ChatMessage): void;
-  /** 一轮对话完成（无更多工具调用） */
+  /** 一轮对话完成（无更多工具调用、命中 terminal 工具或达到 maxToolRounds 上限） */
   (e: 'finish', message: ChatMessage): void;
   /** 对话出错 */
   (e: 'error', error: Error): void;
@@ -34,14 +54,22 @@ interface AiChatEmits {
   (e: 'tool-call', toolCall: ChatToolCall): void;
 }
 interface _AiChatExposed {
-  /** 发送一条用户消息 */
+  /** 发送一条用户消息（会话进行中时进入待发送队列） */
   send: (content: string, attachments?: ChatAttachment[]) => void;
-  /** 中断当前生成 */
+  /** 中断当前生成（保留待发送队列） */
   abort: () => void;
   /** 重新生成最后一条 assistant 回复 */
   regenerate: () => void;
-  /** 清空消息 */
+  /** 清空消息与待发送队列 */
   clear: () => void;
+  /** 待发送消息队列（会话进行中提交的消息按序排队，收尾后 FIFO 自动接续） */
+  queue: Ref<ChatQueuedMessage[]>;
+  /** 立即执行队列中的某条：中断当前会话并插队为下一条 */
+  startQueued: (id: string) => void;
+  /** 从队列移除某条（返回被移除项） */
+  removeQueued: (id: string) => ChatQueuedMessage | undefined;
+  /** 向队列插入一条消息（beforeId 插到某条之前，缺省追加尾部；空闲时自动消耗队首） */
+  enqueue: (content: string, attachments?: ChatAttachment[], beforeId?: string) => ChatQueuedMessage;
 }
 type AiChatExposed = DeconstructValue<_AiChatExposed>;
 //#endregion

package/dist/types/ai-orb.d.ts

@@ -0,0 +1,27 @@
+//#region src/types/ai-orb.d.ts
+/** 活体球生命状态：驱动常态动画（平静 / 思考 / 输出） */
+type AiOrbStatus = 'idle' | 'thinking' | 'speaking';
+/**
+ * 瞬时表情：播放约 1-2s 后自动回到 status 驱动的常态。
+ * - happy：成功 / 回答完毕 —— 先睁大眼睛，再弯眼大笑 + 点头
+ * - shock：惊讶 —— 睁大眼睛 + 小嘴微张 + 轻微后仰
+ * - frustrated：受挫（如工具调用失败）—— 闭紧眼睛 + 摇头 + 嘴角下撇
+ */
+type AiOrbReaction = 'happy' | 'shock' | 'frustrated';
+interface AiOrbProps {
+  /** 球体直径（px），默认 48 */
+  size?: number;
+  /** 生命状态，默认 idle */
+  status?: AiOrbStatus;
+}
+interface AiOrbEmits {
+  /** 点击球体（球体同时会做 Q 弹反馈） */
+  (e: 'click'): void;
+}
+interface AiOrbExposed {
+  /** 播放一次瞬时表情（对应阶段性事件，如回答完毕 / 工具调用失败） */
+  react: (reaction: AiOrbReaction) => void;
+}
+//#endregion
+export { AiOrbEmits, AiOrbExposed, AiOrbProps, AiOrbReaction, AiOrbStatus };
+//# sourceMappingURL=ai-orb.d.ts.map

package/dist/types/index.d.ts

@@ -1,2 +1,3 @@
 import { AiChatEmits, AiChatExposed, AiChatProps, _AiChatExposed } from "./ai-chat.js";
-export { AiChatEmits, AiChatExposed, AiChatProps, _AiChatExposed };
+import { AiOrbEmits, AiOrbExposed, AiOrbProps, AiOrbReaction, AiOrbStatus } from "./ai-orb.js";
+export { AiChatEmits, AiChatExposed, AiChatProps, AiOrbEmits, AiOrbExposed, AiOrbProps, AiOrbReaction, AiOrbStatus, _AiChatExposed };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/ai",
-  "version": "1.4.0",
+  "version": "2.1.0",
   "files": [
     "dist",
     "src"
@@ -27,14 +27,14 @@
     }
   },
   "dependencies": {
-    "markstream-vue": "^1.0.8"
+    "markstream-vue": "^1.0.9"
   },
   "peerDependencies": {
-    "@veltra/compositions": "1.4.0",
-    "@veltra/desktop": "1.4.0",
-    "@veltra/icons": "1.4.0",
-    "@veltra/styles": "1.4.0",
-    "@veltra/utils": "1.4.0",
-    "vue": ">=3.5.40"
+    "@veltra/compositions": "^1.6.0",
+    "@veltra/desktop": "^1.6.0",
+    "@veltra/icons": "^1.5.0",
+    "@veltra/styles": "^1.6.0",
+    "@veltra/utils": "^1.6.0",
+    "vue": ">=3.5.41"
   }
 }

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,21 +304,229 @@ 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 () => {
+    const emit = createEmit()
+    const requests: ChatTransportRequest[] = []
+
+    const transport: ChatTransport = (req, handlers) => {
+      requests.push(req)
+      handlers.onTextDelta('ok')
+    }
+
+    const chat = useChat({
+      props: {
+        transport,
+        models: [
+          {
+            id: 'gpt-4o',
+            providerId: 'openai',
+            reasoningLevels: [
+              { value: 'low', label: '低' },
+              { value: 'high', label: '高' }
+            ],
+            defaultReasoningLevel: 'low'
+          }
+        ],
+        model: 'gpt-4o',
+        reasoningLevel: 'high'
+      },
+      emit
+    })
+
+    chat.send('hi')
+    await waitFinish(emit)
+
+    expect(requests[0]).toMatchObject({ model: 'gpt-4o', reasoningLevel: 'high' })
+  })
+
+  it('切换模型时校正推理等级', async () => {
+    const emit = createEmit()
+    const chat = useChat({
+      props: {
+        transport: textTransport('x'),
+        models: [
+          {
+            id: 'with-reason',
+            providerId: 'a',
+            reasoningLevels: [
+              { value: 'low', label: '低' },
+              { value: 'high', label: '高' }
+            ],
+            defaultReasoningLevel: 'low'
+          },
+          { id: 'no-reason', providerId: 'a' }
+        ],
+        model: 'with-reason',
+        reasoningLevel: 'high'
+      },
+      emit
+    })
+
+    await nextTick()
+    expect(chat.model.value).toBe('with-reason')
+    expect(chat.reasoningLevel.value).toBe('high')
+
+    chat.model.value = 'no-reason'
+    await nextTick()
+    expect(chat.reasoningLevel.value).toBeUndefined()
+
+    chat.model.value = 'with-reason'
+    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)
   })
 })