@veltra/ai 1.4.0

package/src/tools/ask-question/__test__/ask-question.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createApp, defineComponent, h, nextTick, ref } from 'vue'
+
+import type { ChatMessage, ChatTransport } from '../../../chat/types'
+import UAiChat from '../../../components/ai-chat/ai-chat.vue'
+import type { AiChatExposed } from '../../../types'
+import { createAskQuestionTool } from '../ask-question'
+
+// happy-dom 环境下用桩组件替换 MarkdownRender，仅验证组件自身逻辑
+vi.mock('markstream-vue', () => ({
+  default: defineComponent({
+    props: { content: { type: String, default: '' } },
+    setup(props) {
+      return () => h('div', { class: 'md-stub' }, props.content)
+    }
+  })
+}))
+
+function mountAiChat(transport: ChatTransport) {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+
+  const chatRef = ref<AiChatExposed>()
+
+  const app = createApp({
+    render() {
+      return h(UAiChat, { ref: chatRef, transport, tools: [createAskQuestionTool()] })
+    }
+  })
+
+  app.mount(host)
+
+  return {
+    host,
+    chat: chatRef,
+    unmount() {
+      app.unmount()
+      host.remove()
+    }
+  }
+}
+
+const QUESTIONS = [
+  { question: '目标用户是谁？', options: ['开发者', '设计师'] },
+  { question: '偏好什么风格？', options: ['简洁', '炫酷'] },
+  { question: '还有什么补充？', placeholder: '例如：需要深色模式' }
+]
+
+/** 第一轮发起提问工具调用、第二轮输出文本的 transport；rounds 记录每轮收到的消息 */
+function createAskTransport(rounds: ChatMessage[][]) {
+  let round = 0
+  const transport: ChatTransport = (req, handlers) => {
+    round++
+    rounds.push(req.messages)
+    if (round === 1) {
+      handlers.onToolCall?.({
+        id: 'q1',
+        name: 'askQuestion',
+        arguments: JSON.stringify({ questions: QUESTIONS })
+      })
+    } else {
+      handlers.onTextDelta('明白了')
+    }
+  }
+  return transport
+}
+
+const click = (el: HTMLElement) => el.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+
+/** 底部导航按钮（UButton disabled 体现为 is-disabled class） */
+const actionButton = (host: HTMLElement, text: string) => {
+  return [...host.querySelectorAll<HTMLElement>('.u-ai-chat__ask-question-actions button')].find(
+    (btn) => btn.textContent?.includes(text)
+  )
+}
+
+/** 当前题的选项按钮 */
+const optionButton = (host: HTMLElement, text: string) => {
+  return [...host.querySelectorAll<HTMLElement>('.u-ai-chat__ask-question-opt')].find((el) =>
+    el.textContent?.includes(text)
+  )
+}
+
+describe('createAskQuestionTool', () => {
+  it('分页提问：导航、作答、提交后展示问答摘要', async () => {
+    const rounds: ChatMessage[][] = []
+    const { host, chat, unmount } = mountAiChat(createAskTransport(rounds))
+
+    chat.value?.send('帮我做个页面')
+
+    // 第 1 题：进度、选项、「上一个」禁用、无「提交」
+    await vi.waitFor(() => {
+      expect(host.querySelector('.u-ai-chat__ask-question-q')?.textContent).toContain(
+        '目标用户是谁？'
+      )
+    })
+    expect(host.querySelector('.u-ai-chat__ask-question-count')?.textContent).toBe('1 / 3')
+    expect(actionButton(host, '上一个')?.className).toContain('is-disabled')
+    expect(actionButton(host, '下一个')).toBeTruthy()
+    expect(actionButton(host, '提交')).toBeUndefined()
+
+    // 点选「开发者」
+    click(optionButton(host, '开发者')!)
+    await nextTick()
+    expect(optionButton(host, '开发者')?.className).toContain('is-selected')
+
+    // 下一个 → 第 2 题，点选「简洁」
+    click(actionButton(host, '下一个')!)
+    await nextTick()
+    expect(host.querySelector('.u-ai-chat__ask-question-q')?.textContent).toContain(
+      '偏好什么风格？'
+    )
+    click(optionButton(host, '简洁')!)
+    await nextTick()
+
+    // 下一个 → 第 3 题（纯文本），「下一个」变为「提交」，未作答时禁用
+    click(actionButton(host, '下一个')!)
+    await nextTick()
+    expect(host.querySelector('.u-ai-chat__ask-question-q')?.textContent).toContain(
+      '还有什么补充？'
+    )
+    expect(actionButton(host, '下一个')).toBeUndefined()
+    expect(actionButton(host, '提交')?.className).toContain('is-disabled')
+
+    // 自定义输入作答后「提交」可用
+    const input = host.querySelector<HTMLInputElement>('.u-ai-chat__ask-question input')!
+    input.value = '需要深色模式'
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+    await nextTick()
+    expect(actionButton(host, '提交')?.className).not.toContain('is-disabled')
+
+    // 「上一个」返回第 1 题，选中态保留
+    click(actionButton(host, '上一个')!)
+    await nextTick()
+    click(actionButton(host, '上一个')!)
+    await nextTick()
+    expect(host.querySelector('.u-ai-chat__ask-question-q')?.textContent).toContain(
+      '目标用户是谁？'
+    )
+    expect(optionButton(host, '开发者')?.className).toContain('is-selected')
+
+    // 回到最后提交
+    click(actionButton(host, '下一个')!)
+    await nextTick()
+    click(actionButton(host, '下一个')!)
+    await nextTick()
+    click(actionButton(host, '提交')!)
+
+    // 第二轮 transport 收到含回答的 tool 消息
+    await vi.waitFor(() => {
+      expect(rounds.length).toBe(2)
+    })
+    const toolMessage = rounds[1]![rounds[1]!.length - 1]!
+    expect(toolMessage.role).toBe('tool')
+    expect(JSON.parse(toolMessage.content)).toEqual({
+      answers: [
+        { question: '目标用户是谁？', answer: '开发者' },
+        { question: '偏好什么风格？', answer: '简洁' },
+        { question: '还有什么补充？', answer: '需要深色模式' }
+      ]
+    })
+
+    // 问答摘要视图：命中选项的回答渲染为 chip，完成后保持展开
+    await vi.waitFor(() => {
+      expect(host.querySelectorAll('.u-ai-chat__ask-question-result').length).toBe(3)
+    })
+    const summary = host.querySelector('.u-ai-chat__ask-question')!.textContent!
+    expect(summary).toContain('目标用户是谁？')
+    expect(summary).toContain('需要深色模式')
+    expect(host.querySelector('.u-ai-chat__ask-question-chip')?.textContent).toBe('开发者')
+    expect(host.querySelector('.u-ai-chat__tool-call.is-success.is-expanded')).toBeTruthy()
+    unmount()
+  })
+
+  it('作答中停止生成，显示已取消', async () => {
+    const transport: ChatTransport = (_req, handlers) => {
+      handlers.onToolCall?.({
+        id: 'q1',
+        name: 'askQuestion',
+        arguments: JSON.stringify({ questions: [{ question: 'Q？' }] })
+      })
+    }
+    const { host, chat, unmount } = mountAiChat(transport)
+
+    chat.value?.send('提个问')
+
+    await vi.waitFor(() => {
+      expect(host.querySelector('.u-ai-chat__ask-question')).toBeTruthy()
+    })
+
+    chat.value?.abort()
+
+    await vi.waitFor(() => {
+      expect(host.querySelector('.u-ai-chat__ask-question-status')?.textContent).toBe('已取消')
+    })
+    unmount()
+  })
+})

package/src/tools/ask-question/ask-question.ts

@@ -0,0 +1,114 @@
+import { QuestionFilled } from '@veltra/icons/normal'
+import type { Component } from 'vue'
+
+import type { ChatTool } from '../../chat/types'
+import AskQuestion from '../../components/ai-chat/ask-question.vue'
+import { deferAskQuestion, takeAskQuestionDeferred } from './deferred'
+
+/** 单个提问项 */
+export interface AskQuestionItem {
+  /** 问题文案 */
+  question: string
+  /** 预设选项（单选）；缺省为纯文本题 */
+  options?: string[]
+  /** 自定义输入占位文案 */
+  placeholder?: string
+}
+
+/** 一条问答结果 */
+export interface AskQuestionAnswer {
+  /** 问题文案 */
+  question: string
+  /** 用户回答（选中的选项或自定义输入） */
+  answer: string
+}
+
+/** 提问工具参数（模型输出） */
+export interface AskQuestionArgs {
+  questions: AskQuestionItem[]
+}
+
+/** 提问工具结果（序列化后回灌模型，渲染层据此展示问答摘要） */
+export interface AskQuestionResult {
+  answers: AskQuestionAnswer[]
+}
+
+export interface CreateAskQuestionToolOptions {
+  /** 工具名（传给模型），默认 askQuestion */
+  name?: string
+  /** 工具描述（传给模型） */
+  description?: string
+  /** 工具显示名，默认「提问」 */
+  label?: string
+  /** 工具图标，默认 QuestionFilled */
+  icon?: Component
+}
+
+const DEFAULT_DESCRIPTION =
+  '当需求不明确或存在歧义时，向用户提问以澄清。一次可提 1-4 个关键问题；' +
+  '每个问题可提供若干预设选项，用户可选择选项或自定义输入。用户作答后再继续生成。'
+
+/** 提问参数 JSON Schema（原样传给模型） */
+const QUESTIONS_SCHEMA: Record<string, unknown> = {
+  type: 'object',
+  properties: {
+    questions: {
+      type: 'array',
+      description: '问题列表',
+      minItems: 1,
+      maxItems: 4,
+      items: {
+        type: 'object',
+        properties: {
+          question: { type: 'string', description: '问题文案' },
+          options: {
+            type: 'array',
+            description: '预设选项（单选）；缺省为纯文本题',
+            items: { type: 'string' }
+          },
+          placeholder: { type: 'string', description: '自定义输入占位文案' }
+        },
+        required: ['question']
+      }
+    }
+  },
+  required: ['questions']
+}
+
+/**
+ * 创建内置提问工具：execute 挂起等待用户在 UI 中作答，提交后结果回灌模型。
+ * 工具卡片由内联提问表单渲染（多题分页导航，提交后展示问答摘要，不自动折叠）。
+ */
+export function createAskQuestionTool(
+  options: CreateAskQuestionToolOptions = {}
+): ChatTool<AskQuestionArgs> {
+  const {
+    name = 'askQuestion',
+    description = DEFAULT_DESCRIPTION,
+    label = '提问',
+    icon = QuestionFilled
+  } = options
+
+  return {
+    name,
+    description,
+    parameters: QUESTIONS_SCHEMA,
+    icon,
+    label,
+    render: AskQuestion,
+    execute: (_args, { toolCall, signal }) =>
+      new Promise<AskQuestionResult>((resolve, reject) => {
+        deferAskQuestion(toolCall.id, { resolve, reject })
+        signal.addEventListener(
+          'abort',
+          () => {
+            // 不依赖 signal.reason（各环境 DOMException 行为不一），统一拒绝为 AbortError
+            const error = new Error('Aborted')
+            error.name = 'AbortError'
+            takeAskQuestionDeferred(toolCall.id)?.reject(error)
+          },
+          { once: true }
+        )
+      })
+  }
+}

package/src/tools/ask-question/deferred.ts

@@ -0,0 +1,27 @@
+import type { AskQuestionResult } from './ask-question'
+
+interface AskQuestionDeferred {
+  resolve: (result: AskQuestionResult) => void
+  reject: (reason?: unknown) => void
+}
+
+/** 挂起的提问 Promise，key 为 toolCallId */
+const pending = new Map<string, AskQuestionDeferred>()
+
+/** 注册挂起的提问 Promise（由 createAskQuestionTool 的 execute 调用） */
+export function deferAskQuestion(toolCallId: string, deferred: AskQuestionDeferred): void {
+  pending.set(toolCallId, deferred)
+}
+
+/** 取出并移除挂起项（abort 监听用）；不存在则返回 undefined */
+export function takeAskQuestionDeferred(toolCallId: string): AskQuestionDeferred | undefined {
+  const deferred = pending.get(toolCallId)
+  if (!deferred) return undefined
+  pending.delete(toolCallId)
+  return deferred
+}
+
+/** 兑现挂起的提问 Promise（由提问表单在用户提交时调用） */
+export function resolveAskQuestion(toolCallId: string, result: AskQuestionResult): void {
+  takeAskQuestionDeferred(toolCallId)?.resolve(result)
+}

package/src/tools/ask-question/index.ts

@@ -0,0 +1 @@
+export * from './ask-question'

package/src/tools/index.ts

@@ -0,0 +1 @@
+export * from './ask-question'

package/src/types/ai-chat.ts

@@ -0,0 +1,56 @@
+import type { DeconstructValue } from '@veltra/utils'
+
+import type {
+  ChatAttachment,
+  ChatMessage,
+  ChatTool,
+  ChatToolCall,
+  ChatTransport
+} from '../chat/types'
+
+export interface AiChatProps {
+  /** 传输层（必填），可使用导出的 createOpenAITransport() 创建 */
+  transport: ChatTransport
+  /** 工具定义列表，不同场景传入不同工具赋予助手不同能力 */
+  tools?: ChatTool[]
+  /** 系统提示词 */
+  systemPrompt?: string
+  /** 消息列表，支持 v-model:messages 受控 */
+  messages?: ChatMessage[]
+  /** 空状态欢迎语 */
+  welcome?: string
+  /** 输入框占位文本 */
+  placeholder?: string
+  /** 附件 accept 类型，默认 image/* */
+  accept?: string
+  /** 单个附件最大字节数，默认 10MB */
+  maxAttachmentSize?: number
+  /** 透传给内部 MarkdownRender 的属性 */
+  rendererProps?: Record<string, unknown>
+}
+
+export interface AiChatEmits {
+  /** 消息列表变化 */
+  (e: 'update:messages', messages: ChatMessage[]): void
+  /** 用户发送消息 */
+  (e: 'send', message: ChatMessage): void
+  /** 一轮对话完成（无更多工具调用） */
+  (e: 'finish', message: ChatMessage): void
+  /** 对话出错 */
+  (e: 'error', error: Error): void
+  /** 模型发起工具调用 */
+  (e: 'tool-call', toolCall: ChatToolCall): void
+}
+
+export interface _AiChatExposed {
+  /** 发送一条用户消息 */
+  send: (content: string, attachments?: ChatAttachment[]) => void
+  /** 中断当前生成 */
+  abort: () => void
+  /** 重新生成最后一条 assistant 回复 */
+  regenerate: () => void
+  /** 清空消息 */
+  clear: () => void
+}
+
+export type AiChatExposed = DeconstructValue<_AiChatExposed>

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from './ai-chat'