@veltra/ai 2.1.3 → 2.1.5

package/src/chat/use-chat.ts

@@ -7,6 +7,7 @@ import type {
   ChatAttachment,
   ChatMessage,
   ChatQueuedMessage,
+  ChatTokenUsage,
   ChatTool,
   ChatToolCall
 } from './types'
@@ -38,6 +39,27 @@ function resolveTools(userTools?: ChatTool[]): ChatTool[] {
   return [...builtins, ...(userTools ?? []).filter((t) => !names.has(t.name))]
 }
 
+function mergeOptionalCount(a?: number, b?: number): number | undefined {
+  if (a == null && b == null) return undefined
+  return (a ?? 0) + (b ?? 0)
+}
+
+/** 累加两次 usage；缓存字段只在至少一侧有值时保留 */
+function addTokenUsage(a: ChatTokenUsage, b: ChatTokenUsage): ChatTokenUsage {
+  const usage: ChatTokenUsage = {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    totalTokens: a.totalTokens + b.totalTokens
+  }
+  const cacheHitTokens = mergeOptionalCount(a.cacheHitTokens, b.cacheHitTokens)
+  if (cacheHitTokens != null) usage.cacheHitTokens = cacheHitTokens
+  const cacheMissTokens = mergeOptionalCount(a.cacheMissTokens, b.cacheMissTokens)
+  if (cacheMissTokens != null) usage.cacheMissTokens = cacheMissTokens
+  const cacheCreationTokens = mergeOptionalCount(a.cacheCreationTokens, b.cacheCreationTokens)
+  if (cacheCreationTokens != null) usage.cacheCreationTokens = cacheCreationTokens
+  return usage
+}
+
 /**
  * AI 对话核心状态机：消息管理、流式追加、工具调用循环编排。
  * 与 UI 解耦，ai-chat.vue 只负责渲染与交互转发。
@@ -66,6 +88,11 @@ export function useChat(options: UseChatOptions) {
   /** 待发送队列：会话进行中提交的新消息按序排队，收尾后先进先出自动接续 */
   const queue = ref<ChatQueuedMessage[]>([])
 
+  /** 当前会话累计 token；从未收到 usage 时为 null */
+  const tokenUsage = ref<ChatTokenUsage | null>(null)
+  /** 最近一轮用户对话（含工具多轮请求）的 token；该轮无 usage 时为 null */
+  const lastTurnUsage = ref<ChatTokenUsage | null>(null)
+
   let abortController: AbortController | null = null
   /** needsConfirm 工具的挂起确认器，key 为 toolCallId */
   const confirmResolvers = new Map<string, (approved: boolean) => void>()
@@ -238,6 +265,7 @@ export function useChat(options: UseChatOptions) {
 
     running.value = true
     finishedNaturally = false
+    lastTurnUsage.value = null
     const controller = new AbortController()
     abortController = controller
 
@@ -297,6 +325,12 @@ export function useChat(options: UseChatOptions) {
             assistant.toolCalls!.push(toolCall)
             emit('tool-call', toolCall)
           },
+          onUsage: (usage) => {
+            lastTurnUsage.value = lastTurnUsage.value
+              ? addTokenUsage(lastTurnUsage.value, usage)
+              : usage
+            tokenUsage.value = tokenUsage.value ? addTokenUsage(tokenUsage.value, usage) : usage
+          },
           onError: (error) => {
             requestError = error
           }
@@ -388,11 +422,13 @@ export function useChat(options: UseChatOptions) {
     void runConversation()
   }
 
-  /** 清空消息与待发送队列，生成中则先中断 */
+  /** 清空消息、待发送队列与 token 统计，生成中则先中断 */
   const clear = () => {
     abort()
     queue.value = []
     messages.value = []
+    tokenUsage.value = null
+    lastTurnUsage.value = null
     snapshot()
   }
 
@@ -402,6 +438,8 @@ export function useChat(options: UseChatOptions) {
     reasoningLevel,
     running,
     queue,
+    tokenUsage,
+    lastTurnUsage,
     send,
     abort,
     regenerate,

package/src/components/ai-chat/__test__/ai-chat.test.ts

@@ -23,6 +23,7 @@ function mountAiChat(options: {
   models?: ChatModelOption[]
   model?: string
   reasoningLevel?: string
+  tokenUsageDetail?: boolean
   slots?: Record<string, (scope: any) => any>
 }) {
   const host = document.createElement('div')
@@ -41,7 +42,8 @@ function mountAiChat(options: {
           welcome: options.welcome,
           models: options.models,
           model: options.model,
-          reasoningLevel: options.reasoningLevel
+          reasoningLevel: options.reasoningLevel,
+          tokenUsageDetail: options.tokenUsageDetail
         },
         options.slots
       )
@@ -1131,4 +1133,122 @@ describe('UAiChat', () => {
       vi.useRealTimers()
     }
   })
+
+  it('输入区提供清除入口；clear 清空后回到欢迎区', async () => {
+    const transport: ChatTransport = (_req, handlers) => {
+      handlers.onTextDelta('回复')
+    }
+    const { host, chat, unmount } = mountAiChat({ transport, welcome: '有什么可以帮你？' })
+
+    expect(host.querySelector('.u-ai-chat__input-clear')).toBeTruthy()
+    expect(
+      host.querySelector('.u-ai-chat__input-clear-wrap')?.classList.contains('is-disabled')
+    ).toBe(true)
+    expect(host.querySelector('.u-ai-chat__input-usage')).toBeFalsy()
+
+    chat.value?.send('你好')
+    await vi.waitFor(() => {
+      expect(host.querySelector('.md-stub')?.textContent).toContain('回复')
+    })
+    expect(
+      host.querySelector('.u-ai-chat__input-clear-wrap')?.classList.contains('is-disabled')
+    ).toBe(false)
+
+    chat.value?.clear()
+    await vi.waitFor(() => {
+      expect(host.querySelector('.u-ai-chat__welcome')?.textContent).toContain('有什么可以帮你？')
+    })
+    expect(host.querySelector('.md-stub')).toBeFalsy()
+    unmount()
+  })
+
+  it('生成中 clear 中止请求并立即恢复欢迎区', async () => {
+    const transport: ChatTransport = (req) => {
+      return new Promise<void>((resolve) => {
+        req.signal.addEventListener('abort', () => resolve(), { once: true })
+      })
+    }
+    const { host, chat, unmount } = mountAiChat({ transport, welcome: '欢迎回来' })
+
+    chat.value?.send('hi')
+    await nextTick()
+    expect(host.querySelector('.u-ai-chat__working')).toBeTruthy()
+
+    chat.value?.clear()
+    await vi.waitFor(() => {
+      expect(host.querySelector('.u-ai-chat__working')).toBeFalsy()
+      expect(host.querySelector('.u-ai-chat__welcome')?.textContent).toContain('欢迎回来')
+    })
+    unmount()
+  })
+
+  it('有 usage 时默认只显示总 token，tokenUsageDetail 追加缓存命中/未命中', async () => {
+    const usageTransport: ChatTransport = (_req, handlers) => {
+      handlers.onTextDelta('ok')
+      handlers.onUsage?.({
+        promptTokens: 10,
+        completionTokens: 2,
+        totalTokens: 12,
+        cacheHitTokens: 4,
+        cacheMissTokens: 6
+      })
+    }
+
+    const compact = mountAiChat({ transport: usageTransport })
+    compact.chat.value?.send('hi')
+    await vi.waitFor(() => {
+      expect(compact.host.querySelector('.u-ai-chat__input-usage')?.textContent).toBe('总 token 12')
+    })
+    expect(compact.host.querySelector('.u-ai-chat__input-usage')?.textContent).not.toContain(
+      '缓存命中'
+    )
+    compact.unmount()
+
+    const detail = mountAiChat({ transport: usageTransport, tokenUsageDetail: true })
+    detail.chat.value?.send('hi')
+    await vi.waitFor(() => {
+      expect(detail.host.querySelector('.u-ai-chat__input-usage')?.textContent).toBe(
+        '总 token 12 · 缓存命中 4 · 缓存未命中 6'
+      )
+    })
+    const text = detail.host.querySelector('.u-ai-chat__input-usage')?.textContent ?? ''
+    expect(text).not.toContain('本次')
+    expect(text).not.toContain('累计')
+    expect(text).not.toContain('输入')
+    expect(text).not.toContain('输出')
+    detail.unmount()
+  })
+
+  it('token 用量数字按 K/M 缩写，缓存字段缺失时不展示该项', async () => {
+    const scaledTransport: ChatTransport = (_req, handlers) => {
+      handlers.onTextDelta('ok')
+      handlers.onUsage?.({
+        promptTokens: 800,
+        completionTokens: 700,
+        totalTokens: 1500,
+        cacheHitTokens: 1000,
+        cacheMissTokens: 1_000_000
+      })
+    }
+    const scaled = mountAiChat({ transport: scaledTransport, tokenUsageDetail: true })
+    scaled.chat.value?.send('hi')
+    await vi.waitFor(() => {
+      expect(scaled.host.querySelector('.u-ai-chat__input-usage')?.textContent).toBe(
+        '总 token 1.5K · 缓存命中 1K · 缓存未命中 1M'
+      )
+    })
+    scaled.unmount()
+
+    const noCacheTransport: ChatTransport = (_req, handlers) => {
+      handlers.onTextDelta('ok')
+      handlers.onUsage?.({ promptTokens: 10, completionTokens: 2, totalTokens: 12 })
+    }
+    const noCache = mountAiChat({ transport: noCacheTransport, tokenUsageDetail: true })
+    noCache.chat.value?.send('hi')
+    await vi.waitFor(() => {
+      expect(noCache.host.querySelector('.u-ai-chat__input-usage')?.textContent).toBe('总 token 12')
+    })
+    expect(noCache.host.querySelector('.u-ai-chat__input-usage')?.textContent).not.toContain('缓存')
+    noCache.unmount()
+  })
 })

package/src/components/ai-chat/ai-chat.vue

@@ -40,8 +40,12 @@
         :placeholder="placeholder"
         :accept="accept"
         :max-attachment-size="maxAttachmentSize"
+        :clearable="clearable"
+        :token-usage="tokenUsage"
+        :token-usage-detail="tokenUsageDetail"
         @send="handleSend"
         @abort="abort"
+        @clear="clear"
       />
     </div>
 
@@ -102,6 +106,8 @@ const {
   reasoningLevel,
   running,
   queue,
+  tokenUsage,
+  lastTurnUsage,
   send,
   abort,
   regenerate,
@@ -115,6 +121,11 @@ const {
 /** 空会话（无可见消息）：输入区垂直居中；欢迎区钉在滚动容器外、贴于输入框上方 */
 const isEmpty = computed(() => !messages.value.some((msg) => msg.role !== 'tool'))
 
+/** 有对话内容、队列或生成中才允许清除，避免误触空会话 */
+const clearable = computed(
+  () => messages.value.length > 0 || queue.value.length > 0 || running.value
+)
+
 /** 所有 renderTo: 'panel' 的工具调用（按消息顺序，面板内容的来源） */
 const panelCalls = computed(() => {
   const calls: ChatToolCall[] = []
@@ -269,6 +280,8 @@ defineExpose<_AiChatExposed>({
   abort,
   regenerate,
   clear,
+  tokenUsage,
+  lastTurnUsage,
   queue,
   startQueued,
   removeQueued,

package/src/components/ai-chat/chat-input.vue

@@ -30,6 +30,26 @@
             <Attach />
           </UIcon>
         </UFilePicker>
+
+        <span :class="[cls.e('input-clear-wrap'), bem.is('disabled', !clearable)]">
+          <UPopConfirm
+            title="清空当前对话？进行中的生成将被中止。"
+            confirm-text="清空"
+            direction="top"
+            alignment="start"
+            @confirm="emit('clear')"
+          >
+            <template #reference>
+              <UIcon :class="cls.e('input-clear')" title="清除会话">
+                <Clear />
+              </UIcon>
+            </template>
+          </UPopConfirm>
+        </span>
+
+        <span v-if="tokenUsage" :class="cls.e('input-usage')" :title="usageText">
+          {{ usageText }}
+        </span>
       </div>
 
       <!-- 右簇：模型/推理选择 → 发送或停止（互斥） -->
@@ -69,12 +89,12 @@
 </template>
 
 <script lang="ts" setup>
-import { UButton, UFilePicker, UIcon } from '@veltra/desktop'
-import { Attach, Close, Up } from '@veltra/icons/normal'
+import { UButton, UFilePicker, UIcon, UPopConfirm } from '@veltra/desktop'
+import { Attach, Clear, Close, Up } from '@veltra/icons/normal'
 import { bem } from '@veltra/utils'
 import { computed, inject, nextTick, ref, shallowRef } from 'vue'
 
-import type { ChatAttachment } from '../../chat/types'
+import type { ChatAttachment, ChatTokenUsage } from '../../chat/types'
 import type { ChatModelOption } from '../../providers'
 import { AiChatDIKey } from './di'
 import ModelPicker from './model-picker.vue'
@@ -92,6 +112,12 @@ const props = defineProps<{
   accept?: string
   /** 单个附件最大字节数 */
   maxAttachmentSize?: number
+  /** 是否可清除（有消息 / 队列 / 生成中） */
+  clearable?: boolean
+  /** 会话累计 token；无 usage 时为 null，不展示 */
+  tokenUsage?: ChatTokenUsage | null
+  /** 是否展示缓存命中 / 未命中（默认只显示总 token） */
+  tokenUsageDetail?: boolean
 }>()
 
 const model = defineModel<string>('model')
@@ -100,6 +126,7 @@ const reasoningLevel = defineModel<string>('reasoningLevel')
 const emit = defineEmits<{
   (e: 'send', content: string, attachments: ChatAttachment[]): void
   (e: 'abort'): void
+  (e: 'clear'): void
 }>()
 
 const di = inject(AiChatDIKey)
@@ -114,6 +141,40 @@ const hasContent = computed(() => !!text.value.trim() || attachments.value.lengt
 /** 生成中且输入为空时显示停止；有内容则显示发送（入队） */
 const showStop = computed(() => props.running && !hasContent.value)
 
+/**
+ * 用量数字：不到 1000 原样；≥1000 用 K；≥100 万用 M。
+ * 最多 1 位小数，整数不写 `.0`（1000 → 1K，1500 → 1.5K）。
+ */
+const formatTokenCount = (n: number) => {
+  const scaled = (value: number, unit: 'K' | 'M') => {
+    const rounded = Math.round(value * 10) / 10
+    return `${Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1)}${unit}`
+  }
+  if (n < 1000) return String(n)
+  if (n < 1_000_000) {
+    const k = Math.round((n / 1000) * 10) / 10
+    // 四舍五入后会变成 1000K 时改用 M
+    return k >= 1000 ? scaled(n / 1_000_000, 'M') : scaled(n / 1000, 'K')
+  }
+  return scaled(n / 1_000_000, 'M')
+}
+
+/** 会话累计：总 token；明细再拼有数据的缓存项，缺字段不写 0 */
+const usageText = computed(() => {
+  const usage = props.tokenUsage
+  if (!usage) return ''
+  const parts = [`总 token ${formatTokenCount(usage.totalTokens)}`]
+  if (props.tokenUsageDetail) {
+    if (usage.cacheHitTokens != null) {
+      parts.push(`缓存命中 ${formatTokenCount(usage.cacheHitTokens)}`)
+    }
+    if (usage.cacheMissTokens != null) {
+      parts.push(`缓存未命中 ${formatTokenCount(usage.cacheMissTokens)}`)
+    }
+  }
+  return parts.join(' · ')
+})
+
 /** 生成中提示用户消息将进入队列 */
 const placeholderText = computed(() => {
   if (props.running) return '会话进行中，发送的消息将进入待发送队列'

package/src/components/ai-chat/message-list.vue

@@ -317,6 +317,15 @@ watch(
     }
     if (!prev) return
 
+    // 清除会话后列表已空：跳过结束停留，立刻回到欢迎区
+    if (visibleMessages.value.length === 0) {
+      finishing.value = false
+      workingLeaving.value = false
+      idleLeaving.value = false
+      idleEnter.value = false
+      return
+    }
+
     finishing.value = true
     idleLeaving.value = false
     const last = visibleMessages.value[visibleMessages.value.length - 1]
@@ -341,6 +350,19 @@ watch(
   }
 )
 
+// 消息被清空（clear）：立刻收掉工作球，欢迎区恢复
+watch(
+  () => visibleMessages.value.length,
+  (len) => {
+    if (len > 0) return
+    clearJumpTimers()
+    finishing.value = false
+    workingLeaving.value = false
+    idleLeaving.value = false
+    idleEnter.value = false
+  }
+)
+
 // 空闲欢迎区展示期间自动轮换；跳到工作位后停止
 watch(
   () => [welcomeItems.value.length, showIdleWelcome.value] as const,

package/src/components/ai-chat/style.scss

@@ -889,7 +889,6 @@ $root-name: ai-chat;
     font-size: fn.use-var(font-size-main, default);
     font-family: inherit;
     line-height: 1.6;
-    padding: fn.use-var(gap, small);
     box-sizing: border-box;
 
     &::placeholder {
@@ -906,7 +905,8 @@ $root-name: ai-chat;
   @include m.e(input-toolbar-left) {
     @include m.flex(flex, flex-start, center);
     gap: fn.use-var(gap, small);
-    flex-shrink: 0;
+    flex: 1;
+    min-width: 0;
   }
 
   @include m.e(input-toolbar-right) {
@@ -960,6 +960,35 @@ $root-name: ai-chat;
     }
   }
 
+  @include m.e(input-clear-wrap) {
+    flex-shrink: 0;
+    display: inline-flex;
+    line-height: 0;
+
+    @include m.is(disabled) {
+      opacity: 0.4;
+      pointer-events: none;
+    }
+  }
+
+  @include m.e(input-clear) {
+    color: fn.use-var(text-color, assist);
+    cursor: pointer;
+    font-size: 18px;
+
+    &:hover {
+      color: fn.use-var(color, danger);
+    }
+  }
+
+  @include m.e(input-usage) {
+    min-width: 0;
+    @include m.ellipsis;
+    font-size: fn.use-var(font-size-main, small);
+    color: fn.use-var(text-color, assist);
+    line-height: 1.4;
+  }
+
   @include m.e(input-stop) {
     display: block;
     width: 10px;

package/src/components/ai-chat/style.ts

@@ -5,6 +5,7 @@ import '@veltra/desktop/components/icon/style'
 import '@veltra/desktop/components/input/style'
 import '@veltra/desktop/components/layout/style'
 import '@veltra/desktop/components/message/style'
+import '@veltra/desktop/components/pop-confirm/style'
 import '@veltra/desktop/components/scroll/style'
 import '@veltra/desktop/components/select/style'
 import '@veltra/styles/animations/shine.scss'

package/src/types/ai-chat.ts

@@ -5,6 +5,7 @@ import type {
   ChatAttachment,
   ChatMessage,
   ChatQueuedMessage,
+  ChatTokenUsage,
   ChatTool,
   ChatToolCall,
   ChatTransport
@@ -44,6 +45,11 @@ export interface AiChatProps {
   maxAttachmentSize?: number
   /** 透传给内部 MarkdownRender 的属性 */
   rendererProps?: Record<string, unknown>
+  /**
+   * 是否展示 token 用量明细（缓存命中 / 未命中；缺字段不显示）。
+   * 默认 false：仅在拿到 usage 时显示会话累计「总 token」。接口未返回 usage 时不展示。
+   */
+  tokenUsageDetail?: boolean
 }
 
 export interface AiChatEmits {
@@ -70,8 +76,12 @@ export interface _AiChatExposed {
   abort: () => void
   /** 重新生成最后一条 assistant 回复 */
   regenerate: () => void
-  /** 清空消息与待发送队列 */
+  /** 清空消息、待发送队列与 token 统计（生成中会先中止） */
   clear: () => void
+  /** 当前会话累计 token（从未收到 usage 时为 null） */
+  tokenUsage: Ref<ChatTokenUsage | null>
+  /** 最近一轮用户对话的 token（含工具多轮请求；该轮无 usage 时为 null） */
+  lastTurnUsage: Ref<ChatTokenUsage | null>
   /** 待发送消息队列（会话进行中提交的消息按序排队，收尾后 FIFO 自动接续） */
   queue: Ref<ChatQueuedMessage[]>
   /** 立即执行队列中的某条：中断当前会话并插队为下一条 */