feat: support usage

Author: qddegtya

packages/components/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astack-tech/components",
-  "version": "0.1.1-beta.3",
+  "version": "0.1.1-beta.4",
   "description": "Components for the Astack AI Framework.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",

packages/components/src/agents/StreamingAgent.ts

@@ -79,6 +79,17 @@ export interface StreamingChunk {
    * 错误信息（当 type 为 error 时）
    */
   error?: string;
+
+  /**
+   * Token 使用统计信息（当 type 为 completed 时）
+   */
+  usage?: {
+    completion_tokens: number;
+    prompt_tokens: number;
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
+    total_tokens: number;
+  };
 }
 
 /**
@@ -217,6 +228,7 @@ export class StreamingAgent extends Component {
       let iteration = 0;
       let lastAssistantMessage: MessageWithToolCalls | null = null;
       let hasMoreToolsToCall = true;
+      let capturedUsage: StreamingChunk['usage'] | undefined;
 
       // 获取 Agent 的配置（通过反射访问私有属性）
       const maxIterations =
@@ -373,6 +385,23 @@ export class StreamingAgent extends Component {
             }
             modelResponse.tool_calls = finalToolCalls;
           }
+
+          // 捕获 token 使用统计信息
+          const chunkWithUsage = chunk as Partial<MessageWithToolCalls> & {
+            usage?: StreamingChunk['usage'];
+          };
+          if (chunkWithUsage.usage) {
+            capturedUsage = {
+              completion_tokens: chunkWithUsage.usage.completion_tokens || 0,
+              prompt_tokens: chunkWithUsage.usage.prompt_tokens || 0,
+              prompt_cache_hit_tokens: chunkWithUsage.usage.prompt_cache_hit_tokens,
+              prompt_cache_miss_tokens: chunkWithUsage.usage.prompt_cache_miss_tokens,
+              total_tokens: chunkWithUsage.usage.total_tokens || 0,
+            };
+            if (verbose) {
+              console.log('[StreamingAgent Debug] 捕获到 usage 信息:', capturedUsage);
+            }
+          }
         }
 
         if (verbose) {
@@ -551,6 +580,7 @@ export class StreamingAgent extends Component {
         finalMessage: lastAssistantMessage?.content || '',
         history: currentMessages,
         allToolCalls: toolCalls,
+        usage: capturedUsage,
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);

packages/components/src/agents/index.ts

@@ -35,6 +35,17 @@ export interface Message {
    * 消息的附加元数据
    */
   metadata?: Record<string, unknown>;
+
+  /**
+   * Token 使用统计（可选）
+   */
+  usage?: {
+    completion_tokens: number;
+    prompt_tokens: number;
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
+    total_tokens: number;
+  };
 }
 
 /**
@@ -225,6 +236,17 @@ export interface AgentOutput {
    * 完整的消息历史
    */
   history: Message[];
+
+  /**
+   * Token 使用统计（可选）
+   */
+  usage?: {
+    completion_tokens: number;
+    prompt_tokens: number;
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
+    total_tokens: number;
+  };
 }
 
 /**
@@ -406,6 +428,7 @@ export class Agent extends Component {
       let iteration = 0;
       let lastAssistantMessage: MessageWithToolCalls | null = null;
       let hasMoreToolsToCall = true;
+      let accumulatedUsage: AgentOutput['usage'] | undefined;
 
       // 2. 开始迭代循环，直到达到最大迭代次数或模型没有更多工具调用
       while (hasMoreToolsToCall && iteration < this.maxIterations) {
@@ -422,6 +445,30 @@ export class Agent extends Component {
         // 保存模型回复作为最后的助手消息
         lastAssistantMessage = modelResponse;
 
+        // 累积 token 使用统计
+        if (modelResponse.usage) {
+          if (!accumulatedUsage) {
+            accumulatedUsage = {
+              completion_tokens: 0,
+              prompt_tokens: 0,
+              total_tokens: 0,
+            };
+          }
+          accumulatedUsage.completion_tokens += modelResponse.usage.completion_tokens || 0;
+          accumulatedUsage.prompt_tokens += modelResponse.usage.prompt_tokens || 0;
+          accumulatedUsage.total_tokens += modelResponse.usage.total_tokens || 0;
+          if (modelResponse.usage.prompt_cache_hit_tokens) {
+            accumulatedUsage.prompt_cache_hit_tokens =
+              (accumulatedUsage.prompt_cache_hit_tokens || 0) +
+              modelResponse.usage.prompt_cache_hit_tokens;
+          }
+          if (modelResponse.usage.prompt_cache_miss_tokens) {
+            accumulatedUsage.prompt_cache_miss_tokens =
+              (accumulatedUsage.prompt_cache_miss_tokens || 0) +
+              modelResponse.usage.prompt_cache_miss_tokens;
+          }
+        }
+
         // 4. 检查是否有工具调用
         if (!modelResponse.tool_calls || modelResponse.tool_calls.length === 0) {
           // 没有工具调用，完成迭代
@@ -538,6 +585,7 @@ export class Agent extends Component {
         message: lastAssistantMessage?.content || '',
         history: currentMessages,
         toolCalls,
+        usage: accumulatedUsage,
       };
     } catch (error) {
       console.error(