@keo-ai/axiom 0.2.1 → 0.2.3

package/README.md

@@ -177,9 +177,15 @@ for await (const chunk of LLM.streamPredict({ model: 'qwen-max', prompt: '讲个
   if (chunk.type === 'reasoning') {
     process.stdout.write(chunk.delta);  // 推理过程
   }
+  if (chunk.type === 'finish' && chunk.usage) {
+    console.log('Token usage:', chunk.usage);
+    // { promptTokens, completionTokens, totalTokens, cachedPromptTokens? }
+  }
 }
 ```
 
+> 💡 流式调用自动启用 `stream_options: { include_usage: true }`，`finish` 事件携带完整的 token 消耗统计。usage 可能与 `finish_reason` 在同一个 SSE chunk，也可能在独立的 chunk（`choices: []`）中返回，两种情况均已兼容。
+
 ### 模型列表
 
 当前支持的模型（通过 `Model` 类型枚举）：
@@ -328,6 +334,9 @@ for await (const chunk of stream) {
       break;
     case 'turn_end':
       console.log(`\n--- Turn ${chunk.turn} End ---`);
+      if (chunk.usage) {
+        console.log(`Token usage: prompt=${chunk.usage.promptTokens}, completion=${chunk.usage.completionTokens}`);
+      }
       break;
   }
 }
@@ -366,6 +375,8 @@ console.log('Turns:', result!.turns);
 | `tool_result` | tool 执行完成 | `callId`, `toolName`, `content`, `status`, `turn` |
 | `turn_end` | 一轮结束（tool 全部执行完或 content 直接返回） | `turn`, `usage?` |
 
+> 💡 `turn_end` 的 `usage` 字段携带该轮 LLM 调用的 token 消耗统计（`promptTokens`、`completionTokens`、`totalTokens`、`cachedPromptTokens?`）。流式请求自动启用 `stream_options: { include_usage: true }`，确保 API 返回 usage 数据。
+
 #### 流式 vs 非流式的选择
 
 | 场景 | 推荐方式 |
@@ -462,6 +473,37 @@ for await (const chunk of stream) {
 
 **向后兼容**：返回普通值（非 `ToolResult`）时行为完全不变，仍按原有逻辑 `JSON.stringify` 后透给 LLM。
 
+#### 用 ToolResult 终止 Loop（end tool）
+
+当某个 tool 的执行结果就是最终答案、不需要再调 LLM 时，可以设置 `endLoop: true`：
+
+```ts
+const finalAnswerTool = {
+  name: 'get_answer',
+  description: 'Get final answer',
+  parameters: { /* ... */ },
+  execute: async (args) => {
+    const answer = await computeAnswer(args);
+    return {
+      forLLM: '已找到最终答案',
+      forFrontend: answer,
+      endLoop: true,
+      finalContent: answer.summary,
+    };
+  },
+};
+```
+
+| 字段 | 说明 |
+|---|---|
+| `endLoop` | 为 `true` 时，该 tool 执行完成后直接结束 Loop，不再进入下一轮 LLM 调用 |
+| `finalContent` | 可选。设置后作为 `LoopResult.finalContent` 返回；不设置则使用 `forLLM` |
+
+**行为规则**：
+- `endLoop` 仅在 execute 成功返回 `ToolResult` 时生效
+- 若一轮并行调用中有多个 tool 都设置 `endLoop`，取第一个完成的结果作为最终输出
+- `pendingApproval` 的优先级高于 `endLoop`：未审批时先返回 `pendingApproval`
+
 ### Tool 审批拦截
 
 对于敏感操作（转账、删除数据等），可以给 tool 配置 `approval`，Loop 会在执行前暂停并返回 `pendingApproval`：

package/dist/function_call_loop/loop.d.ts

@@ -29,6 +29,8 @@ export type ExecutionResult = {
         toolName: string;
         args: unknown;
     };
+    endLoop?: boolean;
+    finalContent?: string;
 };
 /**
  * 并行执行 tool。

package/dist/function_call_loop/loop.js

@@ -32,7 +32,7 @@ const DEFAULT_BAILIAN_BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode
 const DEFAULT_BAILIAN_MODEL = 'qwen-max';
 function runLoop(config) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h;
         const llmCaller = (_a = config.llmCaller) !== null && _a !== void 0 ? _a : (0, provider_1.createLLMCaller)({
             apiKey: (_b = process.env.BAILIAN_API_KEY) !== null && _b !== void 0 ? _b : '',
             baseUrl: (_c = process.env.BAILIAN_BASE_URL) !== null && _c !== void 0 ? _c : DEFAULT_BAILIAN_BASE_URL,
@@ -157,6 +157,18 @@ function runLoop(config) {
                     totalUsage: computeTotalUsage(),
                 };
             }
+            // 检查是否有 tool 要求结束 Loop
+            const endLoopResult = parallelResults.find((r) => r.endLoop);
+            if (endLoopResult === null || endLoopResult === void 0 ? void 0 : endLoopResult.endLoop) {
+                return {
+                    messages,
+                    harness: harness.getAll(),
+                    finalContent: (_h = endLoopResult.finalContent) !== null && _h !== void 0 ? _h : endLoopResult.content,
+                    turns: turn,
+                    usageHistory,
+                    totalUsage: computeTotalUsage(),
+                };
+            }
             // 第八步：回到第一步继续下一轮
         }
         // Loop 被终止（Turn Policy 或硬限制）
@@ -399,10 +411,14 @@ function executeToolsInParallel(config, harness, toolCalls, visibleToolNames, ha
             };
             let content;
             let frontendData;
+            let endLoop;
+            let finalContent;
             if (status === 'success') {
                 if (isToolResult(result)) {
                     content = result.forLLM;
                     frontendData = result.forFrontend;
+                    endLoop = result.endLoop;
+                    finalContent = result.finalContent;
                 }
                 else {
                     content =
@@ -418,6 +434,8 @@ function executeToolsInParallel(config, harness, toolCalls, visibleToolNames, ha
                 toolCallId: callId,
                 content,
                 frontendData,
+                endLoop,
+                finalContent,
                 record: finalRecord,
                 events: [endEvent],
                 pendingApproval: typeof result === 'object' &&

package/dist/function_call_loop/provider.js

@@ -118,6 +118,7 @@ function createLLMCaller(options) {
                     tools: tools.length > 0 ? toOpenAITools(tools) : undefined,
                     reasoning_effort: callOptions === null || callOptions === void 0 ? void 0 : callOptions.reasoningEffort,
                     stream: true,
+                    stream_options: { include_usage: true },
                 });
                 const url = `${options.baseUrl}/chat/completions`;
                 let response;
@@ -148,7 +149,27 @@ function createLLMCaller(options) {
                 const toolCallAccumulators = [];
                 let fullContent = '';
                 let fullReasoningContent = '';
-                let hasYieldedFinish = false;
+                // 累积 usage：OpenAI 兼容 API 在 stream_options.include_usage 开启时，
+                // usage 可能与 finish_reason 在同一个 chunk，也可能在独立的 chunk（choices: []）中返回。
+                // 统一在此收集，流结束后合并到 finish 事件中 yield。
+                let streamUsage;
+                let hasFinishReason = false;
+                function buildToolCalls() {
+                    const toolCalls = [];
+                    for (const acc of toolCallAccumulators) {
+                        if (acc.id && acc.type && acc.function.name) {
+                            toolCalls.push({
+                                id: acc.id,
+                                type: acc.type,
+                                function: {
+                                    name: acc.function.name,
+                                    arguments: acc.function.arguments,
+                                },
+                            });
+                        }
+                    }
+                    return toolCalls;
+                }
                 try {
                     while (true) {
                         const { done, value } = yield __await(reader.read());
@@ -171,7 +192,16 @@ function createLLMCaller(options) {
                             catch (_g) {
                                 continue;
                             }
-                            const choice = (_c = parsed.choices) === null || _c === void 0 ? void 0 : _c[0];
+                            // 从任意 chunk 中收集 usage（包括 choices 为空的独立 usage chunk）
+                            if (parsed.usage) {
+                                streamUsage = {
+                                    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,
+                                };
+                            }
+                            const choice = (_d = parsed.choices) === null || _d === void 0 ? void 0 : _d[0];
                             if (!choice)
                                 continue;
                             const delta = choice.delta;
@@ -199,69 +229,29 @@ function createLLMCaller(options) {
                                         acc.id = tcDelta.id;
                                     if (tcDelta.type)
                                         acc.type = tcDelta.type;
-                                    if ((_d = tcDelta.function) === null || _d === void 0 ? void 0 : _d.name) {
+                                    if ((_e = tcDelta.function) === null || _e === void 0 ? void 0 : _e.name) {
                                         acc.function.name = tcDelta.function.name;
                                     }
-                                    if ((_e = tcDelta.function) === null || _e === void 0 ? void 0 : _e.arguments) {
+                                    if ((_f = tcDelta.function) === null || _f === void 0 ? void 0 : _f.arguments) {
                                         acc.function.arguments += tcDelta.function.arguments;
                                     }
                                 }
                             }
-                            // 流结束
+                            // 标记流结束（不立即 yield finish，等 usage 收集完毕）
                             if (choice.finish_reason) {
-                                const toolCalls = [];
-                                for (const acc of toolCallAccumulators) {
-                                    if (acc.id && acc.type && acc.function.name) {
-                                        toolCalls.push({
-                                            id: acc.id,
-                                            type: acc.type,
-                                            function: {
-                                                name: acc.function.name,
-                                                arguments: acc.function.arguments,
-                                            },
-                                        });
-                                    }
-                                }
-                                yield yield __await({
-                                    type: 'finish',
-                                    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;
-                            }
-                        }
-                    }
-                    // 兜底：如果流正常结束但没有收到 finish_reason，也 yield 一个 finish
-                    if (!hasYieldedFinish) {
-                        const toolCalls = [];
-                        for (const acc of toolCallAccumulators) {
-                            if (acc.id && acc.type && acc.function.name) {
-                                toolCalls.push({
-                                    id: acc.id,
-                                    type: acc.type,
-                                    function: {
-                                        name: acc.function.name,
-                                        arguments: acc.function.arguments,
-                                    },
-                                });
+                                hasFinishReason = true;
                             }
                         }
-                        yield yield __await({
-                            type: 'finish',
-                            content: fullContent || null,
-                            reasoningContent: fullReasoningContent || undefined,
-                            tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
-                        });
                     }
+                    // 流结束，统一 yield finish 事件（确保包含累积的 usage）
+                    const toolCalls = buildToolCalls();
+                    yield yield __await({
+                        type: 'finish',
+                        content: fullContent || null,
+                        reasoningContent: fullReasoningContent || undefined,
+                        tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+                        usage: streamUsage,
+                    });
                 }
                 finally {
                     reader.releaseLock();

package/dist/function_call_loop/stream.js

@@ -54,7 +54,7 @@ function buildInitialMessages(config) {
 function runLoopStream(config) {
     return __asyncGenerator(this, arguments, function* runLoopStream_1() {
         var _a, e_1, _b, _c;
-        var _d, _e, _f, _g, _h, _j, _k;
+        var _d, _e, _f, _g, _h, _j, _k, _l;
         const llmCaller = (_d = config.llmCaller) !== null && _d !== void 0 ? _d : (0, provider_1.createLLMCaller)({
             apiKey: (_e = process.env.BAILIAN_API_KEY) !== null && _e !== void 0 ? _e : '',
             baseUrl: (_f = process.env.BAILIAN_BASE_URL) !== null && _f !== void 0 ? _f : DEFAULT_BAILIAN_BASE_URL,
@@ -135,9 +135,9 @@ function runLoopStream(config) {
                 reasoningEffort: config.reasoningEffort,
             });
             try {
-                for (var _l = true, stream_1 = (e_1 = void 0, __asyncValues(stream)), stream_1_1; stream_1_1 = yield __await(stream_1.next()), _a = stream_1_1.done, !_a; _l = true) {
+                for (var _m = true, stream_1 = (e_1 = void 0, __asyncValues(stream)), stream_1_1; stream_1_1 = yield __await(stream_1.next()), _a = stream_1_1.done, !_a; _m = true) {
                     _c = stream_1_1.value;
-                    _l = false;
+                    _m = false;
                     const chunk = _c;
                     if (chunk.type === 'content') {
                         fullContent += chunk.delta;
@@ -155,7 +155,7 @@ function runLoopStream(config) {
             catch (e_1_1) { e_1 = { error: e_1_1 }; }
             finally {
                 try {
-                    if (!_l && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
+                    if (!_m && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
                 }
                 finally { if (e_1) throw e_1.error; }
             }
@@ -234,6 +234,19 @@ function runLoopStream(config) {
                     totalUsage: computeTotalUsage(),
                 });
             }
+            // 检查是否有 tool 要求结束 Loop
+            const endLoopResult = parallelResults.find((r) => r.endLoop);
+            if (endLoopResult === null || endLoopResult === void 0 ? void 0 : endLoopResult.endLoop) {
+                yield yield __await({ type: 'turn_end', turn, usage: finishChunk.usage });
+                return yield __await({
+                    messages,
+                    harness: harness.getAll(),
+                    finalContent: (_l = endLoopResult.finalContent) !== null && _l !== void 0 ? _l : endLoopResult.content,
+                    turns: turn,
+                    usageHistory,
+                    totalUsage: computeTotalUsage(),
+                });
+            }
             yield yield __await({ type: 'turn_end', turn, usage: finishChunk.usage });
             // 第八步：回到第一步继续下一轮
         }

package/dist/function_call_loop/types.d.ts

@@ -113,10 +113,15 @@ export interface ApprovalConfig {
  * Tool 执行结果的分流包装。
  * 当 execute 返回此类型时，forLLM 进入 messages[] 给 LLM 上下文，
  * forFrontend 通过 SSE tool_result 事件透给前端渲染。
+ * 设置 endLoop 为 true 可让 Loop 在执行完该 tool 后直接终止，不再调用 LLM。
  */
 export interface ToolResult {
     readonly forLLM: string;
     readonly forFrontend?: unknown;
+    /** 为 true 时，tool 执行完成后直接结束 Loop，不再进入下一轮 LLM 调用 */
+    readonly endLoop?: boolean;
+    /** endLoop 为 true 时，作为 LoopResult.finalContent 返回；不设置则使用 forLLM */
+    readonly finalContent?: string;
 }
 /**
  * 注册到 Loop 中的 Tool。

package/dist/llm_provider/bailian.js

@@ -103,7 +103,7 @@ class BailianProvider {
         return __asyncGenerator(this, arguments, function* stream_1() {
             var _a, _b, _c;
             const url = `${this.config.baseUrl}/chat/completions`;
-            const body = this.adaptRequest(Object.assign(Object.assign({}, this.buildRequestBody(request)), { stream: true }));
+            const body = this.adaptRequest(Object.assign(Object.assign({}, this.buildRequestBody(request)), { stream: true, stream_options: { include_usage: true } }));
             let response;
             try {
                 response = yield __await(fetch(url, {
@@ -128,6 +128,10 @@ class BailianProvider {
             const reader = response.body.getReader();
             const decoder = new TextDecoder();
             let buffer = '';
+            // 累积 usage：OpenAI 兼容 API 在 stream_options.include_usage 开启时，
+            // usage 可能与 finish_reason 在同一个 chunk，也可能在独立的 chunk（choices: []）中返回。
+            // 统一在此收集，流结束后一次性 yield finish 事件。
+            let streamUsage;
             try {
                 while (true) {
                     const { done, value } = yield __await(reader.read());
@@ -150,7 +154,16 @@ class BailianProvider {
                         catch (_d) {
                             continue;
                         }
-                        const choice = (_b = parsed.choices) === null || _b === void 0 ? void 0 : _b[0];
+                        // 从任意 chunk 中收集 usage（包括 choices 为空的独立 usage chunk）
+                        if (parsed.usage) {
+                            streamUsage = {
+                                promptTokens: parsed.usage.prompt_tokens,
+                                completionTokens: parsed.usage.completion_tokens,
+                                totalTokens: parsed.usage.total_tokens,
+                                cachedPromptTokens: (_b = parsed.usage.prompt_tokens_details) === null || _b === void 0 ? void 0 : _b.cached_tokens,
+                            };
+                        }
+                        const choice = (_c = parsed.choices) === null || _c === void 0 ? void 0 : _c[0];
                         if (!choice)
                             continue;
                         const delta = choice.delta;
@@ -160,20 +173,9 @@ class BailianProvider {
                         if (delta.content) {
                             yield yield __await({ type: 'content', delta: delta.content });
                         }
-                        if (choice.finish_reason && parsed.usage) {
-                            yield yield __await({
-                                type: 'finish',
-                                usage: {
-                                    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,
-                                },
-                            });
-                        }
                     }
                 }
-                yield yield __await({ type: 'finish' });
+                yield yield __await({ type: 'finish', usage: streamUsage });
             }
             finally {
                 reader.releaseLock();
@@ -194,6 +196,8 @@ class BailianProvider {
             response_format: request.responseFormat
                 ? { type: request.responseFormat === 'json' ? 'json_object' : 'text' }
                 : undefined,
+            stream: request.stream,
+            stream_options: request.streamOptions,
         };
     }
 }

package/dist/llm_provider/index.d.ts

@@ -35,6 +35,10 @@ export interface OpenAIChatRequest {
         type: 'text' | 'json_object';
     };
     stream?: boolean;
+    /** 流式请求时是否在最后一个 chunk 中返回 usage 信息。OpenAI 兼容 API 默认不返回，需显式开启 */
+    stream_options?: {
+        include_usage: boolean;
+    };
     reasoning_effort?: 'low' | 'medium' | 'high';
     /** 百炼等平台的扩展参数 */
     extra_body?: Record<string, unknown>;

package/dist/llm_provider/types.d.ts

@@ -14,6 +14,9 @@ export interface LLMRequest {
     readonly maxTokens?: number;
     readonly topP?: number;
     readonly stream?: boolean;
+    readonly streamOptions?: {
+        include_usage: boolean;
+    };
     readonly model?: string;
     readonly responseFormat?: 'text' | 'json';
 }

package/package.json

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