@veltra/ai 1.4.0

package/src/chat/transports/openai.ts

@@ -0,0 +1,237 @@
+import type {
+  ChatMessage,
+  ChatTool,
+  ChatTransport,
+  ChatTransportHandlers,
+  ChatTransportRequest
+} from '../types'
+
+/** createOpenAITransport 的配置项 */
+export interface OpenAITransportOptions {
+  /** chat completions 端点，如 https://api.openai.com/v1/chat/completions */
+  endpoint: string
+  /** API Key（Bearer 鉴权） */
+  apiKey?: string
+  /** 模型名 */
+  model: string
+  /** 额外请求头 */
+  headers?: Record<string, string>
+  /** 额外请求体字段，如 temperature、top_p */
+  body?: Record<string, unknown>
+}
+
+interface OpenAIMessage {
+  role: string
+  content?: unknown
+  tool_calls?: unknown[]
+  tool_call_id?: string
+}
+
+function toOpenAIMessages(messages: ChatMessage[], systemPrompt?: string): OpenAIMessage[] {
+  const result: OpenAIMessage[] = []
+
+  if (systemPrompt) {
+    result.push({ role: 'system', content: systemPrompt })
+  }
+
+  for (const msg of messages) {
+    if (msg.role === 'user') {
+      if (msg.attachments?.length) {
+        const parts: unknown[] = []
+        if (msg.content) parts.push({ type: 'text', text: msg.content })
+        for (const att of msg.attachments) {
+          parts.push({ type: 'image_url', image_url: { url: att.dataUrl } })
+        }
+        result.push({ role: 'user', content: parts })
+      } else {
+        result.push({ role: 'user', content: msg.content })
+      }
+    } else if (msg.role === 'assistant') {
+      const item: OpenAIMessage = { role: 'assistant', content: msg.content || '' }
+      if (msg.toolCalls?.length) {
+        item.tool_calls = msg.toolCalls.map((call) => ({
+          id: call.id,
+          type: 'function',
+          function: { name: call.name, arguments: call.arguments }
+        }))
+      }
+      result.push(item)
+    } else if (msg.role === 'tool') {
+      result.push({ role: 'tool', tool_call_id: msg.toolCallId, content: msg.content })
+    }
+  }
+
+  return result
+}
+
+function toOpenAITools(tools: ChatTool[]): unknown[] {
+  return tools.map((tool) => ({
+    type: 'function',
+    function: { name: tool.name, description: tool.description, parameters: tool.parameters }
+  }))
+}
+
+interface AccumulatedToolCall {
+  id: string
+  name: string
+  arguments: string
+}
+
+/**
+ * 逐行解析 SSE 流。
+ * 兼容 OpenAI 及 DeepSeek 等 reasoning_content 风格的兼容端点。
+ */
+async function parseSSE(
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+  handlers: ChatTransportHandlers
+): Promise<void> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  // 按 OpenAI 流式协议中 tool_calls 的 index 累积参数片段
+  const accumulated = new Map<number, AccumulatedToolCall>()
+  let lastIndex = -1
+
+  const flushToolCalls = () => {
+    if (!handlers.onToolCall) return
+    for (const call of accumulated.values()) {
+      if (call.id && call.name) {
+        handlers.onToolCall({ id: call.id, name: call.name, arguments: call.arguments })
+      }
+    }
+    accumulated.clear()
+  }
+
+  const handleData = (data: string) => {
+    if (data === '[DONE]') return
+
+    let chunk: any
+    try {
+      chunk = JSON.parse(data)
+    } catch {
+      return
+    }
+
+    const delta = chunk.choices?.[0]?.delta
+    if (!delta) return
+
+    if (typeof delta.content === 'string' && delta.content) {
+      handlers.onTextDelta(delta.content)
+    }
+
+    // 兼容 reasoning_content（DeepSeek）与 reasoning（部分 OpenAI 兼容端点）
+    const reasoning = delta.reasoning_content ?? delta.reasoning
+    if (typeof reasoning === 'string' && reasoning) {
+      handlers.onReasoningDelta?.(reasoning)
+    }
+
+    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()
+        lastIndex = Math.max(lastIndex, index)
+
+        let call = accumulated.get(index)
+        if (!call) {
+          call = { id: '', name: '', arguments: '' }
+          accumulated.set(index, call)
+        }
+        if (tc.id) call.id = tc.id
+        if (tc.function?.name) call.name += tc.function.name
+        if (tc.function?.arguments) call.arguments += tc.function.arguments
+      }
+    }
+  }
+
+  try {
+    // 递归泵取代替 while 循环，避免 await-in-loop
+    const pump = async (): Promise<void> => {
+      const { done, value } = await reader.read()
+      if (done || signal.aborted) return
+
+      buffer += decoder.decode(value, { stream: true })
+
+      let newlineIndex: number
+      while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, newlineIndex).trim()
+        buffer = buffer.slice(newlineIndex + 1)
+        if (line.startsWith('data:')) {
+          handleData(line.slice(5).trim())
+        }
+      }
+
+      return pump()
+    }
+
+    await pump()
+
+    if (buffer.trim().startsWith('data:')) {
+      handleData(buffer.trim().slice(5).trim())
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  flushToolCalls()
+}
+
+/**
+ * 创建 OpenAI 兼容协议的传输层（chat/completions SSE）。
+ * 手写 fetch + SSE 解析，无任何第三方依赖。
+ */
+export function createOpenAITransport(options: OpenAITransportOptions): ChatTransport {
+  const { endpoint, apiKey, model, headers, body } = options
+
+  return async (request: ChatTransportRequest, handlers: ChatTransportHandlers) => {
+    const { messages, systemPrompt, tools, signal } = request
+
+    let response: Response
+    try {
+      response = await fetch(endpoint, {
+        method: 'POST',
+        signal,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+          ...headers
+        },
+        body: JSON.stringify({
+          model,
+          stream: true,
+          ...body,
+          messages: toOpenAIMessages(messages, systemPrompt),
+          ...(tools?.length ? { tools: toOpenAITools(tools) } : {})
+        })
+      })
+    } catch (error) {
+      if (!signal.aborted) {
+        handlers.onError?.(error instanceof Error ? error : new Error(String(error)))
+      }
+      return
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '')
+      handlers.onError?.(
+        new Error(`请求失败（${response.status}）：${text || response.statusText}`)
+      )
+      return
+    }
+
+    if (!response.body) {
+      handlers.onError?.(new Error('响应不包含可读取的流'))
+      return
+    }
+
+    try {
+      await parseSSE(response.body, signal, handlers)
+    } catch (error) {
+      if (!signal.aborted) {
+        handlers.onError?.(error instanceof Error ? error : new Error(String(error)))
+      }
+    }
+  }
+}

package/src/chat/types.ts

@@ -0,0 +1,136 @@
+import type { Component } from 'vue'
+
+/** 聊天附件（首版仅支持图片） */
+export interface ChatAttachment {
+  /** 文件名 */
+  name: string
+  /** MIME 类型 */
+  mimeType: string
+  /** 字节大小 */
+  size: number
+  /** base64 data URL */
+  dataUrl: string
+}
+
+/** 工具调用状态 */
+export type ToolCallStatus =
+  | 'pending'
+  | 'awaiting-confirm'
+  | 'running'
+  | 'success'
+  | 'error'
+  | 'rejected'
+
+/** 一次工具调用 */
+export interface ChatToolCall {
+  /** 调用 id（由模型生成） */
+  id: string
+  /** 工具名 */
+  name: string
+  /** 模型输出的原始 JSON 参数串 */
+  arguments: string
+  /** 调用状态 */
+  status: ToolCallStatus
+  /** 序列化后的工具执行结果 */
+  result?: string
+  /** 执行失败信息 */
+  error?: string
+}
+
+/** 聊天消息 */
+export interface ChatMessage {
+  /** 消息 id */
+  id: string
+  /** 角色 */
+  role: 'user' | 'assistant' | 'tool'
+  /** markdown 内容 */
+  content: string
+  /** 思考过程（reasoning） */
+  reasoning?: string
+  /** 用户消息携带的附件 */
+  attachments?: ChatAttachment[]
+  /** assistant 消息上的工具调用列表 */
+  toolCalls?: ChatToolCall[]
+  /** role 为 tool 时关联的工具调用 id */
+  toolCallId?: string
+  /** 消息状态，仅 assistant 消息使用 */
+  status?: 'streaming' | 'done' | 'error' | 'aborted'
+}
+
+/** 工具执行上下文 */
+export interface ChatToolContext {
+  /** 本次工具调用 */
+  toolCall: ChatToolCall
+  /** 中断信号（用户点击停止时触发） */
+  signal: AbortSignal
+}
+
+/**
+ * 对话工具定义。
+ * 在不同场景传入不同的工具数组，即可赋予对话助手不同的能力。
+ */
+export interface ChatTool<A = any> {
+  /** 工具名（传给模型，需唯一） */
+  name: string
+  /** 工具描述（传给模型） */
+  description: string
+  /** 参数 JSON Schema（原样传给模型） */
+  parameters: Record<string, unknown>
+  /** 执行前是否需要用户在 UI 中确认 */
+  needsConfirm?: boolean
+  /** 工具图标组件，缺省用内置状态图标（状态颜色/加载旋转仍作用于图标容器） */
+  icon?: Component
+  /** 工具显示名，缺省取 name */
+  label?: string
+  /**
+   * 自定义工具卡片内容渲染（组件或渲染函数），props 为 ChatToolRenderProps。
+   * 设置后替换卡片 body 的默认参数/结果展示；优先级高于 tool-<name> 插槽。
+   */
+  render?: Component
+  /** 执行完成后是否自动折叠。缺省：设置了 render 时为 false，否则为 true */
+  autoCollapse?: boolean
+  /** 工具实现，返回值（或 Promise 返回值）会被 JSON 序列化后回灌给模型 */
+  execute: (args: A, ctx: ChatToolContext) => unknown
+}
+
+/** 工具自定义渲染组件 / 渲染函数的 props */
+export interface ChatToolRenderProps {
+  /** 本次工具调用（含 status/arguments/result/error，可自行渲染进度与错误） */
+  toolCall: ChatToolCall
+}
+
+/** transport 请求参数 */
+export interface ChatTransportRequest {
+  /** 完整消息历史（内部模型，transport 自行转换为 wire 格式） */
+  messages: ChatMessage[]
+  /** 系统提示词 */
+  systemPrompt?: string
+  /** 可用工具 */
+  tools?: ChatTool[]
+  /** 中断信号 */
+  signal: AbortSignal
+}
+
+/** transport 流式事件回调 */
+export interface ChatTransportHandlers {
+  /** 文本增量 */
+  onTextDelta(delta: string): void
+  /** 思考内容增量 */
+  onReasoningDelta?(delta: string): void
+  /**
+   * 一次完整的工具调用。
+   * 流式参数片段由 transport 内部累积，参数完整后才通过该回调抛出。
+   */
+  onToolCall?(call: { id: string; name: string; arguments: string }): void
+  /** 请求错误 */
+  onError?(error: Error): void
+}
+
+/**
+ * 对话传输层抽象。组件不关心具体的 LLM 协议，
+ * 可传入内置的 createOpenAITransport()，也可自行实现接入任意后端。
+ */
+export type ChatTransport = (
+  request: ChatTransportRequest,
+  handlers: ChatTransportHandlers
+) => Promise<void> | void

package/src/chat/use-chat.ts

@@ -0,0 +1,245 @@
+import { useModel } from '@veltra/compositions'
+import { reactive, ref, type Ref } from 'vue'
+
+import type { AiChatEmits, AiChatProps } from '../types'
+import type { ChatAttachment, ChatMessage, ChatToolCall } from './types'
+
+export interface UseChatOptions {
+  props: AiChatProps
+  emit: AiChatEmits
+}
+
+const uid = () => {
+  return typeof crypto !== 'undefined' && crypto.randomUUID
+    ? crypto.randomUUID()
+    : `${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+function serializeResult(result: unknown): string {
+  if (typeof result === 'string') return result
+  try {
+    return JSON.stringify(result) ?? 'null'
+  } catch {
+    return String(result)
+  }
+}
+
+/**
+ * AI 对话核心状态机：消息管理、流式追加、工具调用循环编排。
+ * 与 UI 解耦，ai-chat.vue 只负责渲染与交互转发。
+ */
+export function useChat(options: UseChatOptions) {
+  const { props, emit } = options
+
+  const messages = useModel({
+    props,
+    propName: 'messages',
+    emit,
+    local: true,
+    defaultValue: []
+  }) as Ref<ChatMessage[]>
+
+  /** 是否正在生成中（含工具执行与多轮循环） */
+  const running = ref(false)
+
+  let abortController: AbortController | null = null
+  /** needsConfirm 工具的挂起确认器，key 为 toolCallId */
+  const confirmResolvers = new Map<string, (approved: boolean) => void>()
+
+  /** 向父组件同步消息快照（流式 delta 过于频繁，不同步，只在关键节点同步） */
+  const snapshot = () => {
+    emit('update:messages', messages.value.slice())
+  }
+
+  /** 发送一条用户消息并启动对话循环 */
+  const send = (content: string, attachments?: ChatAttachment[]) => {
+    if (running.value) return
+    if (!content.trim() && !attachments?.length) return
+
+    const message = reactive<ChatMessage>({ id: uid(), role: 'user', content, attachments })
+    messages.value.push(message)
+    snapshot()
+    emit('send', message)
+
+    void runConversation()
+  }
+
+  /** 执行单个工具调用（含确认门控），结果以 tool 消息追加 */
+  const executeToolCall = async (toolCall: ChatToolCall, signal: AbortSignal) => {
+    const appendToolMessage = (content: string) => {
+      messages.value.push(
+        reactive<ChatMessage>({ id: uid(), role: 'tool', toolCallId: toolCall.id, content })
+      )
+    }
+
+    const tool = props.tools?.find((t) => t.name === toolCall.name)
+
+    if (!tool) {
+      toolCall.status = 'error'
+      toolCall.error = `未找到名为 "${toolCall.name}" 的工具`
+      appendToolMessage(`Error: tool "${toolCall.name}" is not available.`)
+      return
+    }
+
+    if (tool.needsConfirm) {
+      toolCall.status = 'awaiting-confirm'
+      const approved = await new Promise<boolean>((resolve) => {
+        confirmResolvers.set(toolCall.id, resolve)
+        signal.addEventListener('abort', () => resolve(false), { once: true })
+      })
+      confirmResolvers.delete(toolCall.id)
+
+      if (!approved) {
+        toolCall.status = 'rejected'
+        appendToolMessage(`The user rejected the execution of tool "${toolCall.name}".`)
+        return
+      }
+    }
+
+    toolCall.status = 'running'
+    try {
+      const args = toolCall.arguments ? JSON.parse(toolCall.arguments) : {}
+      const result = await tool.execute(args, { toolCall, signal })
+      toolCall.status = 'success'
+      toolCall.result = serializeResult(result)
+      appendToolMessage(toolCall.result)
+    } catch (error) {
+      toolCall.status = 'error'
+      toolCall.error = error instanceof Error ? error.message : String(error)
+      appendToolMessage(`Error: ${toolCall.error}`)
+    }
+  }
+
+  /** 对话主循环入口：生成 → 工具执行 → 再生成，直至模型不再调用工具 */
+  const runConversation = async () => {
+    if (!props.transport) return
+
+    running.value = true
+    const controller = new AbortController()
+    abortController = controller
+
+    try {
+      await runRound(controller)
+    } finally {
+      running.value = false
+      abortController = null
+      snapshot()
+    }
+  }
+
+  /** 单轮生成；存在工具调用时执行后递归进入下一轮（递归避免 await-in-loop） */
+  const runRound = async (controller: AbortController): Promise<void> => {
+    if (!props.transport) return
+    const { signal } = controller
+
+    const assistant = reactive<ChatMessage>({
+      id: uid(),
+      role: 'assistant',
+      content: '',
+      status: 'streaming',
+      toolCalls: []
+    })
+    messages.value.push(assistant)
+
+    let requestError: Error | null = null
+
+    try {
+      await props.transport(
+        {
+          // 排除刚追加的 assistant 占位消息
+          messages: messages.value.slice(0, -1),
+          systemPrompt: props.systemPrompt,
+          tools: props.tools,
+          signal
+        },
+        {
+          onTextDelta: (delta) => {
+            assistant.content += delta
+          },
+          onReasoningDelta: (delta) => {
+            assistant.reasoning = (assistant.reasoning ?? '') + delta
+          },
+          onToolCall: (call) => {
+            const toolCall = reactive<ChatToolCall>({ ...call, status: 'pending' })
+            assistant.toolCalls!.push(toolCall)
+            emit('tool-call', toolCall)
+          },
+          onError: (error) => {
+            requestError = error
+          }
+        }
+      )
+    } catch (error) {
+      requestError = error instanceof Error ? error : new Error(String(error))
+    }
+
+    if (signal.aborted) {
+      assistant.status = 'aborted'
+      return
+    }
+
+    if (requestError) {
+      assistant.status = 'error'
+      emit('error', requestError)
+      return
+    }
+
+    assistant.status = 'done'
+
+    const toolCalls = assistant.toolCalls ?? []
+    if (!toolCalls.length) {
+      emit('finish', assistant)
+      return
+    }
+
+    // 工具串行执行（保持结果消息与调用顺序一致），用 Promise 链避免 await-in-loop
+    await toolCalls.reduce<Promise<void>>(
+      (prev, toolCall) =>
+        prev.then(() => (signal.aborted ? undefined : executeToolCall(toolCall, signal))),
+      Promise.resolve()
+    )
+    snapshot()
+
+    if (signal.aborted) return
+
+    return runRound(controller)
+  }
+
+  /** 中断当前生成，挂起的工具确认按拒绝处理 */
+  const abort = () => {
+    abortController?.abort()
+  }
+
+  /** 响应 needsConfirm 工具的用户确认 */
+  const respondToolCall = (toolCallId: string, approved: boolean) => {
+    confirmResolvers.get(toolCallId)?.(approved)
+  }
+
+  /** 重新生成：移除最后一条用户消息之后的所有消息，重新跑对话循环 */
+  const regenerate = () => {
+    if (running.value) return
+
+    const list = messages.value
+    let lastUserIndex = -1
+    for (let i = list.length - 1; i >= 0; i--) {
+      if (list[i]?.role === 'user') {
+        lastUserIndex = i
+        break
+      }
+    }
+    if (lastUserIndex === -1 || lastUserIndex === list.length - 1) return
+
+    messages.value = list.slice(0, lastUserIndex + 1)
+    snapshot()
+    void runConversation()
+  }
+
+  /** 清空消息，生成中则先中断 */
+  const clear = () => {
+    abort()
+    messages.value = []
+    snapshot()
+  }
+
+  return { messages, running, send, abort, regenerate, clear, respondToolCall }
+}