@keo-ai/axiom 0.2.0 → 0.2.1

package/README.md

@@ -4,10 +4,8 @@
 
 > **The execution foundation for LLM agents.**
 
-
 **Axiom 不是编排框架。它是大模型调用工具的「底盘」**
 
-
 </div>
 
 ---
@@ -27,17 +25,13 @@ Axiom 是 **keo** 的 LLM 底座库。它不碰业务编排（意图路由、节
 ├────────────────────────────────────────────┤
 │                 ⚡ AXIOM                    │
 │  ┌─────────┐ ┌──────────┐ ┌─────────────┐ │
-│  │ LLM调用  │ │ Harness  │ │   记忆系统   │ │
-│  │  故障转移 │ │ 状态机   │ │  · Faiss    │ │
-│  │  流式输出 │ │ 副作用   │ │  · 槽位     │ │
-│  └─────────┘ │ 传播     │ │  · 语义     │ │
-│              │ 幻觉防控 │ └─────────────┘ │
-│              └──────────┘ ┌─────────────┐ │
-│                         │  RAG基础      │ │
-│                         │  Embedding   │ │
-│                         │  pgvector    │ │
-│                         │  rerank      │ │
-│                         └─────────────┘ │
+│  │ LLM调用  │ │ Function │ │   RAG基础   │ │
+│  │ 故障转移 │ │ Call     │ │  Embedding │ │
+│  │ 流式输出 │ │ Loop     │ │  pgvector  │ │
+│  └─────────┘ │ 状态机   │ │  rerank    │ │
+│              │ 副作用   │ └─────────────┘ │
+│              │ 传播     │                 │
+│              └──────────┘                 │
 └────────────────────────────────────────────┘
 ```
 
@@ -46,9 +40,8 @@ Axiom 是 **keo** 的 LLM 底座库。它不碰业务编排（意图路由、节
 **Axiom 做：**
 - ✅ LLM 统一调用 + Provider 故障转移
 - ✅ Function Call Loop 的驱动、记录、校验、副作用传播
-- ✅ 记忆系统的抽象与基础实现
 - ✅ RAG 基础（Embedding / pgvector 向量检索 / rerank）
-- ✅ 基础配置中心
+- ✅ 环境变量配置
 
 **Axiom 不做：**
 - ❌ 意图识别与路由
@@ -57,6 +50,7 @@ Axiom 是 **keo** 的 LLM 底座库。它不碰业务编排（意图路由、节
 - ❌ 消息队列与削峰
 - ❌ 具体业务 Tool 的实现逻辑
 - ❌ Provider 排序策略（成本/能力/速度）
+- ❌ 记忆系统（Faiss / 语义记忆 / 槽位）— 由上层业务实现
 
 > 上层写业务，Axiom 跑底盘。
 
@@ -105,39 +99,54 @@ export BAILIAN_API_KEY="your-api-key"
 ```ts
 import { LLM } from '@keo-ai/axiom';
 
-const res = await LLM.predict({ model: 'qwen3.7-max', prompt: '你好' });
-console.log(res);
+const { content, usage } = await LLM.predict({ model: 'qwen-max', prompt: '你好' });
+console.log(content);        // 模型回复
+console.log(usage);          // { promptTokens, completionTokens, totalTokens, cachedPromptTokens? }
 ```
 
 ### API 概览
 
 | 方法 | 用途 | 返回类型 |
 |---|---|---|
-| `LLM.predict(config)` | 单轮快速调用，自动构建 user message | 依 `responseFormat` 而定（见下） |
+| `LLM.predict(config)` | 单轮快速调用，自动构建 user message | `{ content, usage?: TokenUsage }`，依 `responseFormat` 而定（见下） |
 | `LLM.predictWithMessages(messages, config)` | 传入完整消息列表，适用于多轮对话 | 同上 |
 | `LLM.streamPredict(config)` | 流式调用，逐块返回内容 | `AsyncGenerator<StreamChunk>` |
 | `LLM.streamPredictWithMessages(messages, config)` | 流式 + 自定义消息列表 | `AsyncGenerator<StreamChunk>` |
 
+需要自定义 Provider 列表或故障转移策略时，直接使用 `Predictor` 类：
+
+```ts
+import { Predictor, BailianProvider } from '@keo-ai/axiom';
+
+const predictor = new Predictor({
+  providers: [
+    new BailianProvider({ name: 'bailian', apiKey, baseUrl, defaultModel: 'qwen-max' }),
+  ],
+});
+const response = await predictor.generateForModel('qwen-max', { messages: [...] });
+```
+
 ### responseFormat 与返回类型
 
-`predict` 和 `predictWithMessages` 的返回类型由 `responseFormat` 决定：
+`predict` 和 `predictWithMessages` 返回 `{ content, usage?: TokenUsage }`，其中 `content` 的类型由 `responseFormat` 决定：
 
-| `responseFormat` | 返回值 | 说明 |
+| `responseFormat` | `content` 类型 | 说明 |
 |---|---|---|
 | 未设置 / `'text'` | `string` | 直接返回模型输出的文本 |
-| `'json'` | `any` | 自动 `JSON.parse` |
+| `'json'` | `any` | 自动 `JSON.parse`。注意：`glm-5.1` 不支持此模式 |
 
 ```ts
-// text → string
-const text = await LLM.predict({ model: 'qwen3.7-max', prompt: '讲个故事', responseFormat: 'text' });
+// text → { content: string, usage?: TokenUsage }
+const { content, usage } = await LLM.predict({ model: 'qwen-max', prompt: '讲个故事', responseFormat: 'text' });
 
-// json → 自动解析为对象
-const obj = await LLM.predict({
-  model: 'qwen3.7-max',
+// json → { content: any, usage?: TokenUsage }
+const { content: obj, usage } = await LLM.predict({
+  model: 'qwen-max',
   prompt: '生成一个 JSON',
   responseFormat: 'json',
 });
 console.log(obj.name);
+console.log(usage);  // { promptTokens, completionTokens, totalTokens, cachedPromptTokens? }
 ```
 
 ### Provider 配置
@@ -147,7 +156,7 @@ console.log(obj.name);
 ```bash
 BAILIAN_API_KEY           # 必填
 BAILIAN_BASE_URL          # 可选，默认 https://dashscope.aliyuncs.com/compatible-mode/v1
-BAILIAN_DEFAULT_MODEL     # 可选，默认 qwen3.7-max
+BAILIAN_DEFAULT_MODEL     # 可选，默认 qwen-max
 ```
 
 ### 故障转移
@@ -161,10 +170,13 @@ Predictor 内部按模型查询 `MODEL_REGISTRY`，获取候选 Provider 队列
 流式版本返回 `AsyncGenerator<StreamChunk>`，迭代即可逐块消费：
 
 ```ts
-for await (const chunk of LLM.streamPredict({ model: 'qwen3.7-max', prompt: '讲个故事' })) {
+for await (const chunk of LLM.streamPredict({ model: 'qwen-max', prompt: '讲个故事' })) {
   if (chunk.type === 'content') {
     process.stdout.write(chunk.delta);
   }
+  if (chunk.type === 'reasoning') {
+    process.stdout.write(chunk.delta);  // 推理过程
+  }
 }
 ```
 
@@ -172,19 +184,20 @@ for await (const chunk of LLM.streamPredict({ model: 'qwen3.7-max', prompt: '讲
 
 当前支持的模型（通过 `Model` 类型枚举）：
 
-| 模型 | 推理深度 | 说明 |
-|------|----------|------|
-| `deepseek-v4-pro` | ✅ 原生支持 | `low`/`medium`/`high` 直接传递 |
-| `deepseek-v4-flash` | ✅ 原生支持 | `low`/`medium`/`high` 直接传递 |
-| `kimi-k2.6` | ✅ 原生支持 | `low`/`medium`/`high` 直接传递 |
-| `qwen-plus` | ✅ 映射支持 | `low` 关闭推理，`medium`/`high` 映射为 `enable_thinking` |
-| `qwen-turbo` | ✅ 映射支持 | 同上 |
-| `qwen3.7-max` | ✅ 映射支持 | 同上 |
-| `qwq-plus` | ❌ 不支持 | 固定推理行为，不可调节 |
-| `glm-5.1` | ❌ 不支持 | 不支持推理参数 |
-| `qwen-vl-plus` | ❌ 不支持 | 视觉模型，不支持推理参数 |
-
-> 推理深度的支持方式由 Provider 内部维护。百炼 Provider 中，Qwen 系列通过 `extra_body.enable_thinking` 映射实现，DeepSeek / Kimi 则原生透传 `reasoning_effort`。
+| 模型 | 推理深度 | json 模式 | 说明 |
+|------|----------|-----------|------|
+| `qwen-max` | ❌ 不支持 | ✅ | **默认模型** |
+| `qwen3.7-max` | ✅ 映射支持 | ✅ | `low`/`medium`/`high` 映射为 `enable_thinking` |
+| `qwen-plus` | ✅ 映射支持 | ✅ | 同上 |
+| `qwen-turbo` | ✅ 映射支持 | ✅ | 同上 |
+| `deepseek-v4-pro` | ✅ 原生支持 | ✅ | `low`/`medium`/`high` 直接传递 |
+| `deepseek-v4-flash` | ✅ 原生支持 | ✅ | 同上 |
+| `kimi-k2.6` | ✅ 原生支持 | ✅ | 同上 |
+| `qwq-plus` | ❌ 不支持 | ✅ | 固定推理行为，不可调节 |
+| `glm-5.1` | ❌ 不支持 | ❌ | 不支持推理参数，不支持 json 模式 |
+| `qwen-vl-plus` | ❌ 不支持 | ✅ | 视觉模型，不支持推理参数 |
+
+> 推理深度的支持方式由 Provider 内部维护。百炼 Provider 中，Qwen 系列通过 `extra_body.enable_thinking` 映射实现（`low` 关闭，`medium`/`high` 开启），DeepSeek / Kimi 则原生透传 `reasoning_effort`。
 >
 > 目前所有模型均路由到百炼 Provider。后续接入其他厂商时，通过 `MODEL_REGISTRY` 扩展映射即可。
 
@@ -194,7 +207,7 @@ Predict 模块遵循 Axiom 的统一错误策略：**直接抛异常，调用方
 
 ```ts
 try {
-  const res = await LLM.predict({ model: 'qwen3.7-max', prompt: 'hi' });
+  const { content, usage } = await LLM.predict({ model: 'qwen-max', prompt: 'hi' });
 } catch (e) {
   // e.message 包含 Provider 汇总错误信息
 }
@@ -232,7 +245,7 @@ const result = await FunctionCallLoop.runLoop({
     { role: 'system', content: 'You are a helpful assistant.' },
     { role: 'user', content: 'What is the weather in Beijing?' },
   ],
-  model: 'qwen3.7-max',
+  model: 'qwen-max',
   temperature: 0.7,
   maxTokens: 2048,
   tools: [
@@ -262,6 +275,8 @@ const result = await FunctionCallLoop.runLoop({
 console.log(result.finalContent);
 console.log('Turns:', result.turns);
 console.log('Harness:', result.harness);
+console.log('Token usage:', result.totalUsage);        // 累计 token 消耗
+console.log('Usage history:', result.usageHistory);    // 每轮明细
 ```
 
 > 💡 需要**流式输出**（实时展示 LLM 生成内容）？使用下方的 [`runLoopStream`](#流式调用runloopstream)。
@@ -349,7 +364,7 @@ console.log('Turns:', result!.turns);
 | `content` | LLM 输出 content（正式回复）增量 | `delta`, `turn` |
 | `tool_call` | LLM 决定调用 tool（流结束、完整 tool_calls 解析完成） | `toolCalls`, `turn` |
 | `tool_result` | tool 执行完成 | `callId`, `toolName`, `content`, `status`, `turn` |
-| `turn_end` | 一轮结束（tool 全部执行完或 content 直接返回） | `turn` |
+| `turn_end` | 一轮结束（tool 全部执行完或 content 直接返回） | `turn`, `usage?` |
 
 #### 流式 vs 非流式的选择
 
@@ -678,6 +693,15 @@ interface LoopResult {
   harness: HarnessRecord[];         // 执行历史
   finalContent: string | null;      // 最终回复内容
   turns: number;                    // 实际执行轮数
+  usageHistory: TokenUsage[];       // 每轮 LLM 调用的 token 消耗明细
+  totalUsage: TokenUsage;           // 累计 token 消耗（含 cachedPromptTokens）
+}
+
+interface TokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  cachedPromptTokens?: number;      // 命中缓存的 prompt token（Prompt Caching）
 }
 ```
 
@@ -825,7 +849,7 @@ interface SearchResult {
 
 ### 过滤
 
-支持对表的任意独立列做等值和范围过滤：
+支持对表的任意独立列做等值、范围和 IN 查询：
 
 ```ts
 // 等值过滤
@@ -833,7 +857,7 @@ const results = await EmbeddingSearch.query('query', {
   filter: { category: '衣服', shop: '旗舰店' },
 }, pool);
 
-// 混合：等值 + 数值范围
+// 数值范围
 const ranked = await EmbeddingSearch.query('query', {
   filter: {
     category: '衣服',
@@ -854,36 +878,7 @@ const multi = await EmbeddingSearch.query('query', {
 
 ### 枚举值解析
 
-默认开启 `parseEnum`，返回结果中的枚举字段会自动从数字值解析为可读文本。当前支持以下字段：
-
-| 字段 | 说明 | 示例（原值 → 解析后） |
-|---|---|---|
-| `type` | 期刊类型 | `11` → `"SCI/SSCI/AHCI"` |
-| `subject1` | 学科大类 | `17` → `"计算机"` |
-| `db` | 数据库 | `2` → `"SCI(SCIE)"` |
-| `attribute` | 刊物属性 | `3` → `"快审刊"` |
-| `oa` | 发表模式 | `1` → `"开源模式(OA)"` |
-
-```ts
-const results = await EmbeddingSearch.query('query', {
-  tableName: 'journals',
-}, pool);
-
-// 默认 parseEnum: true，枚举字段自动解析为文本
-console.log(results[0].type);      // "SCI/SSCI/AHCI"
-console.log(results[0].subject1);  // "计算机"
-```
-
-如需关闭解析（保留原始数字值）：
-
-```ts
-const results = await EmbeddingSearch.query('query', {
-  tableName: 'journals',
-  parseEnum: false,
-}, pool);
-
-console.log(results[0].type);  // 11
-```
+默认开启 `parseEnum`，返回结果中的特定枚举字段会自动从数字值解析为可读文本。如需关闭解析（保留原始数字值），设置 `parseEnum: false`。
 
 未知枚举值、非数字类型、非枚举字段均保持原样不变。
 
@@ -970,5 +965,3 @@ EmbeddingSearch 模块内部调用百炼的 embedding 和 rerank 服务，无需
 - **项目层填充内容** — 上层准备消息、工具、业务逻辑，Axiom 负责可靠执行
 - **副作用即状态** — 工具调用改变外部世界，Harness 让这种改变在 Loop 间可见
 - **单一事实来源** — Harness 的执行记录是 Function Call 的唯一权威来源
-
----

package/dist/function_call_loop/loop.js

@@ -44,7 +44,24 @@ function runLoop(config) {
         const harness = new harness_1.Harness();
         const messages = buildInitialMessages(config);
         let turn = 0;
+        const usageHistory = [];
         const signal = config.signal;
+        function addUsage(usage) {
+            if (usage) {
+                usageHistory.push(usage);
+            }
+        }
+        function computeTotalUsage() {
+            return usageHistory.reduce((acc, u) => {
+                var _a, _b;
+                return ({
+                    promptTokens: acc.promptTokens + u.promptTokens,
+                    completionTokens: acc.completionTokens + u.completionTokens,
+                    totalTokens: acc.totalTokens + u.totalTokens,
+                    cachedPromptTokens: ((_a = acc.cachedPromptTokens) !== null && _a !== void 0 ? _a : 0) + ((_b = u.cachedPromptTokens) !== null && _b !== void 0 ? _b : 0),
+                });
+            }, { promptTokens: 0, completionTokens: 0, totalTokens: 0 });
+        }
         while (true) {
             // 检查取消信号
             if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
@@ -87,6 +104,7 @@ function runLoop(config) {
                 topP: config.topP,
                 reasoningEffort: config.reasoningEffort,
             });
+            addUsage(llmResponse.usage);
             // 第六步：检查 LLM 回复
             if (!llmResponse.tool_calls || llmResponse.tool_calls.length === 0) {
                 messages.push({
@@ -99,6 +117,8 @@ function runLoop(config) {
                     harness: harness.getAll(),
                     finalContent: llmResponse.content,
                     turns: turn,
+                    usageHistory,
+                    totalUsage: computeTotalUsage(),
                 };
             }
             // 有 tool_calls，将 assistant message 加入 Messages
@@ -133,6 +153,8 @@ function runLoop(config) {
                         args: pending.pendingApproval.args,
                         callId: pending.toolCallId,
                     },
+                    usageHistory,
+                    totalUsage: computeTotalUsage(),
                 };
             }
             // 第八步：回到第一步继续下一轮
@@ -144,6 +166,8 @@ function runLoop(config) {
             harness: harness.getAll(),
             finalContent: (lastMessage === null || lastMessage === void 0 ? void 0 : lastMessage.role) === 'assistant' ? lastMessage.content : null,
             turns: turn,
+            usageHistory,
+            totalUsage: computeTotalUsage(),
         };
     });
 }

package/dist/function_call_loop/provider.d.ts

@@ -2,7 +2,7 @@
  * Function Call Loop 的 LLM Provider 适配器。
  * 基于 predict 模块的 `callChatCompletions` 构建，共用底层 OpenAI 协议 HTTP 层。
  */
-import type { Message, ToolCall, ToolDefinition, LLMCallOptions, LLMStreamChunk } from './types';
+import type { Message, ToolCall, ToolDefinition, LLMCallOptions, LLMStreamChunk, TokenUsage } from './types';
 export interface ProviderOptions {
     readonly apiKey: string;
     readonly baseUrl: string;
@@ -16,6 +16,7 @@ export declare function createLLMCaller(options: ProviderOptions): {
         readonly content: string | null;
         readonly reasoningContent?: string;
         readonly tool_calls?: ReadonlyArray<ToolCall>;
+        readonly usage?: TokenUsage;
     }>;
     /**
      * 流式调用 LLM，支持 content 和 tool_calls 的增量输出。

package/dist/function_call_loop/provider.js

@@ -67,7 +67,7 @@ function createLLMCaller(options) {
     return {
         call(messages, tools, callOptions) {
             return __awaiter(this, void 0, void 0, function* () {
-                var _a, _b;
+                var _a, _b, _c;
                 const body = provider.adaptRequest({
                     model: (_a = callOptions === null || callOptions === void 0 ? void 0 : callOptions.model) !== null && _a !== void 0 ? _a : options.defaultModel,
                     messages: toOpenAIMessages(messages),
@@ -90,6 +90,14 @@ function createLLMCaller(options) {
                             arguments: tc.function.arguments,
                         },
                     })),
+                    usage: data.usage
+                        ? {
+                            promptTokens: data.usage.prompt_tokens,
+                            completionTokens: data.usage.completion_tokens,
+                            totalTokens: data.usage.total_tokens,
+                            cachedPromptTokens: (_c = data.usage.prompt_tokens_details) === null || _c === void 0 ? void 0 : _c.cached_tokens,
+                        }
+                        : undefined,
                 };
             });
         },
@@ -100,7 +108,7 @@ function createLLMCaller(options) {
          */
         stream(messages, tools, callOptions) {
             return __asyncGenerator(this, arguments, function* stream_1() {
-                var _a, _b, _c, _d, _e;
+                var _a, _b, _c, _d, _e, _f;
                 const body = provider.adaptRequest({
                     model: (_a = callOptions === null || callOptions === void 0 ? void 0 : callOptions.model) !== null && _a !== void 0 ? _a : options.defaultModel,
                     messages: toOpenAIMessages(messages),
@@ -160,7 +168,7 @@ function createLLMCaller(options) {
                             try {
                                 parsed = JSON.parse(data);
                             }
-                            catch (_f) {
+                            catch (_g) {
                                 continue;
                             }
                             const choice = (_c = parsed.choices) === null || _c === void 0 ? void 0 : _c[0];
@@ -219,6 +227,14 @@ function createLLMCaller(options) {
                                     content: fullContent || null,
                                     reasoningContent: fullReasoningContent || undefined,
                                     tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+                                    usage: parsed.usage
+                                        ? {
+                                            promptTokens: parsed.usage.prompt_tokens,
+                                            completionTokens: parsed.usage.completion_tokens,
+                                            totalTokens: parsed.usage.total_tokens,
+                                            cachedPromptTokens: (_f = parsed.usage.prompt_tokens_details) === null || _f === void 0 ? void 0 : _f.cached_tokens,
+                                        }
+                                        : undefined,
                                 });
                                 hasYieldedFinish = true;
                             }

package/dist/function_call_loop/stream.js

@@ -69,7 +69,24 @@ function runLoopStream(config) {
         const harness = new harness_1.Harness();
         const messages = buildInitialMessages(config);
         let turn = 0;
+        const usageHistory = [];
         const signal = config.signal;
+        function addUsage(usage) {
+            if (usage) {
+                usageHistory.push(usage);
+            }
+        }
+        function computeTotalUsage() {
+            return usageHistory.reduce((acc, u) => {
+                var _a, _b;
+                return ({
+                    promptTokens: acc.promptTokens + u.promptTokens,
+                    completionTokens: acc.completionTokens + u.completionTokens,
+                    totalTokens: acc.totalTokens + u.totalTokens,
+                    cachedPromptTokens: ((_a = acc.cachedPromptTokens) !== null && _a !== void 0 ? _a : 0) + ((_b = u.cachedPromptTokens) !== null && _b !== void 0 ? _b : 0),
+                });
+            }, { promptTokens: 0, completionTokens: 0, totalTokens: 0 });
+        }
         while (true) {
             // 检查取消信号
             if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
@@ -145,6 +162,7 @@ function runLoopStream(config) {
             if (!finishChunk) {
                 throw new Error('LLM stream ended without a finish chunk');
             }
+            addUsage(finishChunk.usage);
             // 使用 finish chunk 中的 content（优先级更高，可能包含完整格式化内容）
             const assistantContent = (_j = finishChunk.content) !== null && _j !== void 0 ? _j : fullContent;
             const assistantReasoningContent = (_k = finishChunk.reasoningContent) !== null && _k !== void 0 ? _k : (fullReasoningContent || undefined);
@@ -155,12 +173,14 @@ function runLoopStream(config) {
                     content: assistantContent,
                     reasoningContent: assistantReasoningContent,
                 });
-                yield yield __await({ type: 'turn_end', turn });
+                yield yield __await({ type: 'turn_end', turn, usage: finishChunk.usage });
                 return yield __await({
                     messages,
                     harness: harness.getAll(),
                     finalContent: assistantContent,
                     turns: turn,
+                    usageHistory,
+                    totalUsage: computeTotalUsage(),
                 });
             }
             // 有 tool_calls，将 assistant message 加入 Messages
@@ -198,7 +218,7 @@ function runLoopStream(config) {
             // 检查是否有待审批的 tool
             const pending = parallelResults.find((r) => r.pendingApproval);
             if (pending === null || pending === void 0 ? void 0 : pending.pendingApproval) {
-                yield yield __await({ type: 'turn_end', turn });
+                yield yield __await({ type: 'turn_end', turn, usage: finishChunk.usage });
                 return yield __await({
                     messages,
                     harness: harness.getAll(),
@@ -210,9 +230,11 @@ function runLoopStream(config) {
                         args: pending.pendingApproval.args,
                         callId: pending.toolCallId,
                     },
+                    usageHistory,
+                    totalUsage: computeTotalUsage(),
                 });
             }
-            yield yield __await({ type: 'turn_end', turn });
+            yield yield __await({ type: 'turn_end', turn, usage: finishChunk.usage });
             // 第八步：回到第一步继续下一轮
         }
         // Loop 被终止（Turn Policy 或硬限制）
@@ -222,6 +244,8 @@ function runLoopStream(config) {
             harness: harness.getAll(),
             finalContent: (lastMessage === null || lastMessage === void 0 ? void 0 : lastMessage.role) === 'assistant' ? lastMessage.content : null,
             turns: turn,
+            usageHistory,
+            totalUsage: computeTotalUsage(),
         });
     });
 }

package/dist/function_call_loop/types.d.ts

@@ -1,3 +1,5 @@
+import type { TokenUsage } from '../llm_provider/types';
+export type { TokenUsage };
 /**
  * LLM 对话消息。支持 system、user、assistant、tool 四种角色。
  * assistant 角色可携带 tool_calls；tool 角色需携带 tool_call_id。
@@ -168,6 +170,7 @@ export type LLMStreamChunk = {
     readonly content: string | null;
     readonly reasoningContent?: string;
     readonly tool_calls?: ReadonlyArray<ToolCall>;
+    readonly usage?: TokenUsage;
 };
 /**
  * LLM 调用接口。由外部注入，Loop 内部不绑定具体 Provider。
@@ -177,6 +180,7 @@ export interface LLMCaller {
         readonly content: string | null;
         readonly reasoningContent?: string;
         readonly tool_calls?: ReadonlyArray<ToolCall>;
+        readonly usage?: TokenUsage;
     }>;
     readonly stream?: (messages: ReadonlyArray<Message>, tools: ReadonlyArray<ToolDefinition>, options?: LLMCallOptions) => AsyncGenerator<LLMStreamChunk, void, unknown>;
 }
@@ -229,6 +233,10 @@ export interface LoopResult {
     readonly finalContent: string | null;
     readonly turns: number;
     readonly pendingApproval?: PendingApprovalInfo;
+    /** 每轮 LLM 调用的 token 消耗明细 */
+    readonly usageHistory: TokenUsage[];
+    /** 累计 token 消耗 */
+    readonly totalUsage: TokenUsage;
 }
 /**
  * runLoopStream 的流式事件类型。
@@ -259,4 +267,5 @@ export type LoopStreamChunk = {
 } | {
     readonly type: 'turn_end';
     readonly turn: number;
+    readonly usage?: TokenUsage;
 };

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * import 'dotenv/config';
  * import { LLM } from '@keo-ai/axiom';
  *
- * const res = await LLM.predict({ model: 'qwen3.7-max', prompt: '你好' });
+ * const { content, usage } = await LLM.predict({ model: 'qwen3.7-max', prompt: '你好' });
  * ```
  *
  * 必需环境变量：

package/dist/index.js

@@ -7,7 +7,7 @@
  * import 'dotenv/config';
  * import { LLM } from '@keo-ai/axiom';
  *
- * const res = await LLM.predict({ model: 'qwen3.7-max', prompt: '你好' });
+ * const { content, usage } = await LLM.predict({ model: 'qwen3.7-max', prompt: '你好' });
  * ```
  *
  * 必需环境变量：

package/dist/llm_provider/bailian.js

@@ -74,7 +74,7 @@ class BailianProvider {
      */
     generate(request) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
+            var _a, _b;
             const body = this.adaptRequest(Object.assign(Object.assign({}, this.buildRequestBody(request)), { stream: false }));
             const data = yield (0, index_1.callChatCompletions)(this.config.baseUrl, this.config.apiKey, body, this.name);
             const choice = data.choices[0];
@@ -86,9 +86,10 @@ class BailianProvider {
                         promptTokens: data.usage.prompt_tokens,
                         completionTokens: data.usage.completion_tokens,
                         totalTokens: data.usage.total_tokens,
+                        cachedPromptTokens: (_a = data.usage.prompt_tokens_details) === null || _a === void 0 ? void 0 : _a.cached_tokens,
                     }
                     : undefined,
-                model: (_a = data.model) !== null && _a !== void 0 ? _a : body.model,
+                model: (_b = data.model) !== null && _b !== void 0 ? _b : body.model,
             };
         });
     }
@@ -100,7 +101,7 @@ class BailianProvider {
      */
     stream(request) {
         return __asyncGenerator(this, arguments, function* stream_1() {
-            var _a, _b;
+            var _a, _b, _c;
             const url = `${this.config.baseUrl}/chat/completions`;
             const body = this.adaptRequest(Object.assign(Object.assign({}, this.buildRequestBody(request)), { stream: true }));
             let response;
@@ -146,7 +147,7 @@ class BailianProvider {
                         try {
                             parsed = JSON.parse(data);
                         }
-                        catch (_c) {
+                        catch (_d) {
                             continue;
                         }
                         const choice = (_b = parsed.choices) === null || _b === void 0 ? void 0 : _b[0];
@@ -166,6 +167,7 @@ class BailianProvider {
                                     promptTokens: parsed.usage.prompt_tokens,
                                     completionTokens: parsed.usage.completion_tokens,
                                     totalTokens: parsed.usage.total_tokens,
+                                    cachedPromptTokens: (_c = parsed.usage.prompt_tokens_details) === null || _c === void 0 ? void 0 : _c.cached_tokens,
                                 },
                             });
                         }

package/dist/llm_provider/index.d.ts

@@ -59,6 +59,9 @@ export interface OpenAIChatResponse {
         prompt_tokens: number;
         completion_tokens: number;
         total_tokens: number;
+        prompt_tokens_details?: {
+            cached_tokens: number;
+        };
     };
     model?: string;
 }

package/dist/llm_provider/types.d.ts

@@ -17,17 +17,23 @@ export interface LLMRequest {
     readonly model?: string;
     readonly responseFormat?: 'text' | 'json';
 }
+/**
+ * LLM 调用的 token 消耗统计。
+ */
+export interface TokenUsage {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+    /** 命中缓存的 prompt token 数（Prompt Caching） */
+    readonly cachedPromptTokens?: number;
+}
 /**
  * 标准化 LLM 响应。各 Provider 将原始响应解析为此格式后返回。
  */
 export interface LLMResponse {
     readonly content: string | null;
     readonly reasoningContent?: string;
-    readonly usage?: {
-        readonly promptTokens: number;
-        readonly completionTokens: number;
-        readonly totalTokens: number;
-    };
+    readonly usage?: TokenUsage;
     readonly model: string;
 }
 /**

package/dist/predict/predict.d.ts

@@ -1,4 +1,4 @@
-import type { Message, StreamChunk } from '../llm_provider/types';
+import type { Message, StreamChunk, TokenUsage } from '../llm_provider/types';
 import type { PredictConfig, PredictWithMessagesConfig } from './config';
 /**
  * LLM 静态类。封装 Provider 连接、请求组装、故障转移和返回解析。
@@ -8,8 +8,8 @@ import type { PredictConfig, PredictWithMessagesConfig } from './config';
  * ```ts
  * import { LLM } from 'axiom';
  *
- * const res = await LLM.predict({ model: 'qwen-max', prompt: '你好' });
- * console.log(res);
+ * const { content, usage } = await LLM.predict({ model: 'qwen-max', prompt: '你好' });
+ * console.log(content, usage);
  * ```
  */
 export declare class LLM {
@@ -20,33 +20,45 @@ export declare class LLM {
      * 内部自动构造单条 user message，支持可选的 system prompt。
      *
      * 根据 `responseFormat` 返回不同类型：
-     * - 未设置 / `'text'` → `string`
-     * - `'json'` → 解析后的对象（`any`）
+     * - 未设置 / `'text'` → `{ content: string, usage?: TokenUsage }`
+     * - `'json'` → `{ content: any, usage?: TokenUsage }`
      *
      * @param config - 预测配置（模型、prompt、温度等）
-     * @returns 模型生成的完整响应
+     * @returns 模型生成的完整响应及 token 消耗统计
      * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
      */
     static predict(config: PredictConfig & {
         responseFormat: 'json';
-    }): Promise<any>;
-    static predict(config: PredictConfig): Promise<string>;
+    }): Promise<{
+        content: any;
+        usage?: TokenUsage;
+    }>;
+    static predict(config: PredictConfig): Promise<{
+        content: string;
+        usage?: TokenUsage;
+    }>;
     /**
      * 使用自定义消息列表调用 LLM。适用于多轮对话等需要精细控制 message 结构的场景。
      *
      * 根据 `responseFormat` 返回不同类型：
-     * - 未设置 / `'text'` → `string`
-     * - `'json'` → 解析后的对象（可用泛型指定类型）
+     * - 未设置 / `'text'` → `{ content: string, usage?: TokenUsage }`
+     * - `'json'` → `{ content: any, usage?: TokenUsage }`
      *
      * @param messages - 消息列表（user/assistant 角色）
      * @param config - 预测配置（不含 prompt，因为由 messages 提供）
-     * @returns 模型生成的完整响应
+     * @returns 模型生成的完整响应及 token 消耗统计
      * @throws Error - Provider 未配置、模型不存在、或所有 Provider 均失败时抛出
      */
     static predictWithMessages(messages: ReadonlyArray<Message>, config: PredictWithMessagesConfig & {
         responseFormat: 'json';
-    }): Promise<any>;
-    static predictWithMessages(messages: ReadonlyArray<Message>, config: PredictWithMessagesConfig): Promise<string>;
+    }): Promise<{
+        content: any;
+        usage?: TokenUsage;
+    }>;
+    static predictWithMessages(messages: ReadonlyArray<Message>, config: PredictWithMessagesConfig): Promise<{
+        content: string;
+        usage?: TokenUsage;
+    }>;
     /**
      * 流式调用 LLM，逐块返回模型输出。
      *

package/dist/predict/predict.js

@@ -69,14 +69,15 @@ function toLLMRequest(config, messages) {
 }
 function unwrapResponse(response, responseFormat) {
     var _a;
+    const usage = response.usage;
     if (responseFormat === 'json') {
         if (!response.content) {
             throw new Error('Empty response content when responseFormat is json');
         }
-        return JSON.parse(response.content);
+        return { content: JSON.parse(response.content), usage };
     }
     // 默认按 text 返回（包括未设置 responseFormat 的情况）
-    return (_a = response.content) !== null && _a !== void 0 ? _a : '';
+    return { content: (_a = response.content) !== null && _a !== void 0 ? _a : '', usage };
 }
 /**
  * LLM 静态类。封装 Provider 连接、请求组装、故障转移和返回解析。
@@ -86,8 +87,8 @@ function unwrapResponse(response, responseFormat) {
  * ```ts
  * import { LLM } from 'axiom';
  *
- * const res = await LLM.predict({ model: 'qwen-max', prompt: '你好' });
- * console.log(res);
+ * const { content, usage } = await LLM.predict({ model: 'qwen-max', prompt: '你好' });
+ * console.log(content, usage);
  * ```
  */
 class LLM {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keo-ai/axiom",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "基于 LLM 的预测与推理库，支持多 Provider 切换",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",