@veltra/ai 2.1.2 → 2.1.4

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

@@ -375,6 +375,8 @@ describe('useChat', () => {
 
     expect(chat.messages.value).toHaveLength(0)
     expect(chat.queue.value).toHaveLength(0)
+    expect(chat.tokenUsage.value).toBeNull()
+    expect(chat.lastTurnUsage.value).toBeNull()
   })
 
   it('请求携带 model 与 reasoningLevel', async () => {
@@ -567,4 +569,69 @@ describe('useChat', () => {
     // 最终同步给父级的快照也包含 assistant 消息
     expect(props.messages?.some((m) => m.role === 'assistant' && m.content === '回答')).toBe(true)
   })
+
+  it('累计 onUsage，无 usage 时保持 null；clear 一并重置', async () => {
+    const emit = createEmit()
+    const requests: ChatTransportRequest[] = []
+    const transport: ChatTransport = (req, handlers) => {
+      requests.push(req)
+      if (requests.length === 1) {
+        handlers.onToolCall?.({ id: 'call-1', name: 'add', arguments: '{"a":1,"b":2}' })
+        handlers.onUsage?.({
+          promptTokens: 10,
+          completionTokens: 4,
+          totalTokens: 14,
+          cacheHitTokens: 6,
+          cacheMissTokens: 4
+        })
+      } else {
+        handlers.onTextDelta('3')
+        handlers.onUsage?.({
+          promptTokens: 20,
+          completionTokens: 2,
+          totalTokens: 22,
+          cacheHitTokens: 12,
+          cacheMissTokens: 8
+        })
+      }
+    }
+    const tools: ChatTool[] = [
+      { name: 'add', description: '加法', parameters: {}, execute: () => 3 }
+    ]
+    const chat = useChat({ props: { transport, tools }, emit })
+
+    expect(chat.tokenUsage.value).toBeNull()
+    chat.send('算一下')
+    await waitFinish(emit)
+
+    expect(chat.lastTurnUsage.value).toEqual({
+      promptTokens: 30,
+      completionTokens: 6,
+      totalTokens: 36,
+      cacheHitTokens: 18,
+      cacheMissTokens: 12
+    })
+    expect(chat.tokenUsage.value).toEqual(chat.lastTurnUsage.value)
+
+    chat.send('再算')
+    await vi.waitFor(() => {
+      expect(emit.mock.calls.filter((call) => call[0] === 'finish')).toHaveLength(2)
+    })
+    expect(chat.lastTurnUsage.value?.totalTokens).toBe(22)
+    expect(chat.tokenUsage.value?.totalTokens).toBe(58)
+    expect(chat.tokenUsage.value?.cacheHitTokens).toBe(30)
+
+    chat.clear()
+    expect(chat.tokenUsage.value).toBeNull()
+    expect(chat.lastTurnUsage.value).toBeNull()
+  })
+
+  it('transport 不回调 onUsage 时不编造数字', async () => {
+    const emit = createEmit()
+    const chat = useChat({ props: { transport: textTransport('ok') }, emit })
+    chat.send('hi')
+    await waitFinish(emit)
+    expect(chat.tokenUsage.value).toBeNull()
+    expect(chat.lastTurnUsage.value).toBeNull()
+  })
 })

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

@@ -7,6 +7,7 @@ const baseHandlers = (): ChatTransportHandlers => ({
   onTextDelta: vi.fn(),
   onReasoningDelta: vi.fn(),
   onToolCall: vi.fn(),
+  onUsage: vi.fn(),
   onError: vi.fn()
 })
 
@@ -314,4 +315,143 @@ data: [DONE]
       arguments: '{"y":2}'
     })
   })
+
+  it('请求体带 stream_options.include_usage', async () => {
+    const fetchMock = vi.fn(async () => {
+      return new Response('data: [DONE]\n\n', {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' }
+      })
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const transport = createOpenAITransport({
+      providers: [{ id: 'a', endpoint: 'https://a.example/chat', models: [{ id: 'm' }] }]
+    })
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        signal: new AbortController().signal
+      },
+      baseHandlers()
+    )
+
+    expect(JSON.parse(String(fetchMock.mock.calls[0]![1]!.body))).toMatchObject({
+      stream: true,
+      stream_options: { include_usage: true }
+    })
+  })
+
+  it('解析末包 usage，含缓存命中 / 未命中，无 usage 不回调', async () => {
+    const sse = String.raw`data: {"choices":[{"delta":{"content":"hi"}}]}
+
+data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15,"prompt_tokens_details":{"cached_tokens":8},"prompt_cache_hit_tokens":8,"prompt_cache_miss_tokens":4}}
+
+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.onTextDelta).toHaveBeenCalledWith('hi')
+    expect(handlers.onUsage).toHaveBeenCalledTimes(1)
+    expect(handlers.onUsage).toHaveBeenCalledWith({
+      promptTokens: 12,
+      completionTokens: 3,
+      totalTokens: 15,
+      cacheHitTokens: 8,
+      cacheMissTokens: 4
+    })
+  })
+
+  it('仅有 cached_tokens 时由 prompt − 命中得到未命中；缺 usage 不编造', async () => {
+    const withCache = String.raw`data: {"choices":[{"delta":{"content":"a"}}],"usage":{"prompt_tokens":10,"completion_tokens":1,"total_tokens":11,"prompt_tokens_details":{"cached_tokens":7}}}
+
+data: [DONE]
+`
+    const noUsage = String.raw`data: {"choices":[{"delta":{"content":"b"}}]}
+
+data: [DONE]
+`
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response(withCache, { status: 200 }))
+      .mockResolvedValueOnce(new Response(noUsage, { status: 200 }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const transport = createOpenAITransport({
+      providers: [{ id: 'a', endpoint: 'https://a.example/chat', models: [{ id: 'm' }] }]
+    })
+
+    const withCacheHandlers = baseHandlers()
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        signal: new AbortController().signal
+      },
+      withCacheHandlers
+    )
+    expect(withCacheHandlers.onUsage).toHaveBeenCalledWith({
+      promptTokens: 10,
+      completionTokens: 1,
+      totalTokens: 11,
+      cacheHitTokens: 7,
+      cacheMissTokens: 3
+    })
+
+    const noUsageHandlers = baseHandlers()
+    await transport(
+      {
+        messages: [{ id: '1', role: 'user', content: 'hi' }],
+        signal: new AbortController().signal
+      },
+      noUsageHandlers
+    )
+    expect(noUsageHandlers.onUsage).not.toHaveBeenCalled()
+  })
+
+  it('解析 Anthropic 风格 cache_read / cache_creation', async () => {
+    const sse = String.raw`data: {"choices":[{"delta":{"content":"ok"}}],"usage":{"prompt_tokens":20,"completion_tokens":2,"total_tokens":22,"cache_read_input_tokens":15,"cache_creation_input_tokens":3}}
+
+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.onUsage).toHaveBeenCalledWith({
+      promptTokens: 20,
+      completionTokens: 2,
+      totalTokens: 22,
+      cacheHitTokens: 15,
+      cacheMissTokens: 5,
+      cacheCreationTokens: 3
+    })
+  })
 })

package/src/chat/transports/openai.ts

@@ -1,6 +1,7 @@
 import type { ChatModelOption, ChatProvider } from '../../providers'
 import type {
   ChatMessage,
+  ChatTokenUsage,
   ChatTool,
   ChatTransport,
   ChatTransportHandlers,
@@ -82,6 +83,58 @@ interface AccumulatedToolCall {
   arguments: string
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** 非负有限整数；非法或缺省返回 undefined（不把缺失当成 0） */
+function readCount(value: unknown): number | undefined {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return undefined
+  return Math.floor(value)
+}
+
+/**
+ * 从 OpenAI 兼容 usage 对象解析。
+ * 缓存字段只在源数据出现时写入；未命中可在「有命中 + prompt」时由差值得出。
+ */
+function parseOpenAIUsage(raw: unknown): ChatTokenUsage | null {
+  if (!isRecord(raw)) return null
+
+  const promptTokens = readCount(raw.prompt_tokens) ?? readCount(raw.input_tokens)
+  const completionTokens = readCount(raw.completion_tokens) ?? readCount(raw.output_tokens)
+  if (promptTokens == null && completionTokens == null) return null
+
+  const prompt = promptTokens ?? 0
+  const completion = completionTokens ?? 0
+  const usage: ChatTokenUsage = {
+    promptTokens: prompt,
+    completionTokens: completion,
+    totalTokens: readCount(raw.total_tokens) ?? prompt + completion
+  }
+
+  const details = isRecord(raw.prompt_tokens_details) ? raw.prompt_tokens_details : undefined
+  const inputDetails = isRecord(raw.input_tokens_details) ? raw.input_tokens_details : undefined
+  const cacheHitTokens =
+    readCount(details?.cached_tokens) ??
+    readCount(inputDetails?.cached_tokens) ??
+    readCount(raw.prompt_cache_hit_tokens) ??
+    readCount(raw.cache_read_input_tokens) ??
+    readCount(raw.cached_tokens)
+  if (cacheHitTokens != null) usage.cacheHitTokens = cacheHitTokens
+
+  const cacheMissTokens =
+    readCount(raw.prompt_cache_miss_tokens) ??
+    (cacheHitTokens != null && promptTokens != null
+      ? Math.max(0, promptTokens - cacheHitTokens)
+      : undefined)
+  if (cacheMissTokens != null) usage.cacheMissTokens = cacheMissTokens
+
+  const cacheCreationTokens = readCount(raw.cache_creation_input_tokens)
+  if (cacheCreationTokens != null) usage.cacheCreationTokens = cacheCreationTokens
+
+  return usage
+}
+
 /**
  * 逐行解析 SSE 流。
  * 兼容 OpenAI 及 DeepSeek 等 reasoning_content 风格的兼容端点。
@@ -112,15 +165,21 @@ async function parseSSE(
   const handleData = (data: string) => {
     if (data === '[DONE]') return
 
-    let chunk: any
+    let chunk: unknown
     try {
       chunk = JSON.parse(data)
     } catch {
       return
     }
+    if (!isRecord(chunk)) return
+
+    const usage = parseOpenAIUsage(chunk.usage)
+    if (usage) handlers.onUsage?.(usage)
 
-    const delta = chunk.choices?.[0]?.delta
-    if (!delta) return
+    const choices = chunk.choices
+    const first = Array.isArray(choices) ? choices[0] : undefined
+    const delta = isRecord(first) ? first.delta : undefined
+    if (!isRecord(delta)) return
 
     if (typeof delta.content === 'string' && delta.content) {
       handlers.onTextDelta(delta.content)
@@ -134,7 +193,8 @@ async function parseSSE(
 
     if (Array.isArray(delta.tool_calls)) {
       for (const tc of delta.tool_calls) {
-        const index: number = tc.index ?? 0
+        if (!isRecord(tc)) continue
+        const index = typeof tc.index === 'number' ? tc.index : 0
         // 同一调用的参数分片共享 index；index 变大才说明前一个调用已完整，先抛出去
         if (index > lastIndex && accumulated.size > 0) flushToolCalls()
         lastIndex = Math.max(lastIndex, index)
@@ -144,9 +204,10 @@ async function parseSSE(
           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
+        if (typeof tc.id === 'string') call.id = tc.id
+        const fn = isRecord(tc.function) ? tc.function : undefined
+        if (typeof fn?.name === 'string') call.name += fn.name
+        if (typeof fn?.arguments === 'string') call.arguments += fn.arguments
       }
     }
   }
@@ -240,10 +301,15 @@ export function createOpenAITransport(options: OpenAITransportOptions): OpenAITr
       return
     }
 
+    const extraStreamOptions = isRecord(globalBody?.stream_options)
+      ? globalBody.stream_options
+      : undefined
     const requestBody: Record<string, unknown> = {
       ...globalBody,
       model: modelId,
       stream: true,
+      // 流式默认要末包 usage；OpenAI / DeepSeek 等兼容端点靠这个字段才会返回
+      stream_options: { ...extraStreamOptions, include_usage: true },
       messages: toOpenAIMessages(messages, systemPrompt),
       ...(tools?.length ? { tools: toOpenAITools(tools) } : {})
     }

package/src/chat/types.ts

@@ -151,6 +151,32 @@ export interface ChatTransportRequest {
   signal: AbortSignal
 }
 
+/**
+ * 一次模型请求的 token 用量。
+ * 仅包含接口实际返回的字段；缓存类数字缺省为 undefined，不补 0。
+ */
+export interface ChatTokenUsage {
+  /** 输入 token */
+  promptTokens: number
+  /** 输出 token */
+  completionTokens: number
+  /** 合计 token */
+  totalTokens: number
+  /**
+   * 缓存命中。
+   * 来源：`prompt_tokens_details.cached_tokens` / `prompt_cache_hit_tokens` /
+   * `cache_read_input_tokens` / `cached_tokens`。
+   */
+  cacheHitTokens?: number
+  /**
+   * 缓存未命中。
+   * 来源：`prompt_cache_miss_tokens`；若无该字段但有命中与 prompt，则为 prompt − 命中。
+   */
+  cacheMissTokens?: number
+  /** 写入缓存（Anthropic 风格 `cache_creation_input_tokens`），有才有 */
+  cacheCreationTokens?: number
+}
+
 /** transport 流式事件回调 */
 export interface ChatTransportHandlers {
   /** 文本增量 */
@@ -162,6 +188,11 @@ export interface ChatTransportHandlers {
    * 流式参数片段由 transport 内部累积，参数完整后才通过该回调抛出。
    */
   onToolCall?(call: { id: string; name: string; arguments: string }): void
+  /**
+   * 本次请求的 token 用量（流式末包或非流式 usage）。
+   * 接口未返回 usage 时不要调用，不要填 0 充数。
+   */
+  onUsage?(usage: ChatTokenUsage): void
   /** 请求错误 */
   onError?(error: Error): void
 }

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,