@keo-ai/axiom 0.1.8 → 0.2.0

package/README.md

@@ -297,8 +297,12 @@ for await (const chunk of stream) {
     case 'turn_start':
       console.log(`\n--- Turn ${chunk.turn} ---`);
       break;
+    case 'reasoning':
+      // 实时流式输出模型的 reasoning content（思考过程）
+      process.stdout.write(chunk.delta);
+      break;
     case 'content':
-      // 实时流式输出 content（支持 reasoning 内容）
+      // 实时流式输出 content（正式回复内容）
       process.stdout.write(chunk.delta);
       break;
     case 'tool_call':
@@ -341,7 +345,8 @@ console.log('Turns:', result!.turns);
 | 事件 | 触发时机 | 包含字段 |
 |---|---|---|
 | `turn_start` | 新一轮开始 | `turn` |
-| `content` | LLM 输出 content 增量 | `delta`, `turn` |
+| `reasoning` | LLM 输出 reasoning content（推理过程）增量 | `delta`, `turn` |
+| `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` |
@@ -351,7 +356,7 @@ console.log('Turns:', result!.turns);
 | 场景 | 推荐方式 |
 |---|---|
 | 需要实时展示 LLM 输出（打字机效果） | `runLoopStream` |
-| 需要展示模型 reasoning 过程 | `runLoopStream`（content 增量中包含 reasoning） |
+| 需要实时展示模型 reasoning（思考）过程 | `runLoopStream`（通过 `reasoning` 事件独立透出） |
 | 后台静默执行，只关心最终结果 | `runLoop` |
 | 低延迟、简单场景 | `runLoop` |
 
@@ -406,6 +411,42 @@ console.log(result.harness);
 
 **并行隔离原则**：本轮并行执行的多个 tool，各自收到的 Harness 是"本轮并行开始前"的快照，互相看不到同轮其他正在执行的 tool。
 
+### Tool 结果分流（ToolResult）
+
+当 tool 返回大量结构化数据时，直接 `JSON.stringify` 给 LLM 会导致模型重复复述。此时可以用 `ToolResult` 把结果分成两份：
+
+```ts
+const recommendTool = {
+  name: 'recommend_conferences',
+  description: 'Recommend academic conferences',
+  parameters: { /* ... */ },
+  execute: async (args) => {
+    const raw = await recommendConferences(args);
+    return {
+      forLLM: `找到 ${raw.results.length} 个相关会议：${raw.results.map(r => r.name).join('、')}`,
+      forFrontend: raw,
+    };
+  },
+};
+```
+
+| 字段 | 去向 | 说明 |
+|---|---|---|
+| `forLLM` | `messages[]` → LLM 上下文 | 精简摘要，建议用自然语言 |
+| `forFrontend` | `tool_result` SSE 事件 | 完整原始数据，前端渲染用 |
+
+流式消费时前端可以拿到完整数据：
+
+```ts
+for await (const chunk of stream) {
+  if (chunk.type === 'tool_result' && chunk.frontendData) {
+    renderCard(chunk.frontendData);   // 前端拿到完整 JSON 渲染卡片
+  }
+}
+```
+
+**向后兼容**：返回普通值（非 `ToolResult`）时行为完全不变，仍按原有逻辑 `JSON.stringify` 后透给 LLM。
+
 ### Tool 审批拦截
 
 对于敏感操作（转账、删除数据等），可以给 tool 配置 `approval`，Loop 会在执行前暂停并返回 `pendingApproval`：
@@ -640,6 +681,19 @@ interface LoopResult {
 }
 ```
 
+**Message 中的 reasoningContent**：当使用支持推理的模型（如 DeepSeek-R1、QwQ）时，`messages` 中 `role: 'assistant'` 的条目会包含 `reasoningContent` 字段，记录该轮模型的完整推理过程。该字段会自动保留在对话上下文中，供多轮对话回传。
+
+```ts
+const result = await FunctionCallLoop.runLoop(config);
+
+for (const msg of result.messages) {
+  if (msg.role === 'assistant' && msg.reasoningContent) {
+    console.log('[Reasoning]', msg.reasoningContent);
+    console.log('[Content]', msg.content);
+  }
+}
+```
+
 ### 错误处理
 
 同其他模块：**直接抛异常**。常见场景：

package/dist/function_call_loop/loop.d.ts

@@ -21,6 +21,7 @@ export declare function compressMessages(config: LoopConfig, messages: Message[]
 export type ExecutionResult = {
     toolCallId: string;
     content: string;
+    frontendData?: unknown;
     record: HarnessRecord;
     events: LoopEvent[];
     pendingApproval?: {

package/dist/function_call_loop/loop.js

@@ -92,6 +92,7 @@ function runLoop(config) {
                 messages.push({
                     role: 'assistant',
                     content: (_f = llmResponse.content) !== null && _f !== void 0 ? _f : '',
+                    reasoningContent: llmResponse.reasoningContent,
                 });
                 return {
                     messages,
@@ -104,6 +105,7 @@ function runLoop(config) {
             messages.push({
                 role: 'assistant',
                 content: (_g = llmResponse.content) !== null && _g !== void 0 ? _g : '',
+                reasoningContent: llmResponse.reasoningContent,
                 tool_calls: llmResponse.tool_calls,
             });
             // 第七步：并行执行 tool
@@ -261,6 +263,12 @@ function compressMessages(config, messages, _turn) {
         }
     });
 }
+function isToolResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'forLLM' in value &&
+        typeof value.forLLM === 'string');
+}
 /**
  * 并行执行 tool。
  */
@@ -365,14 +373,27 @@ function executeToolsInParallel(config, harness, toolCalls, visibleToolNames, ha
                 error: finalRecord.error,
                 turn,
             };
-            const content = status === 'success'
-                ? typeof result === 'object' && result !== null
-                    ? JSON.stringify(result)
-                    : String(result !== null && result !== void 0 ? result : '')
-                : error !== null && error !== void 0 ? error : 'Execution failed';
+            let content;
+            let frontendData;
+            if (status === 'success') {
+                if (isToolResult(result)) {
+                    content = result.forLLM;
+                    frontendData = result.forFrontend;
+                }
+                else {
+                    content =
+                        typeof result === 'object' && result !== null
+                            ? JSON.stringify(result)
+                            : String(result !== null && result !== void 0 ? result : '');
+                }
+            }
+            else {
+                content = error !== null && error !== void 0 ? error : 'Execution failed';
+            }
             return {
                 toolCallId: callId,
                 content,
+                frontendData,
                 record: finalRecord,
                 events: [endEvent],
                 pendingApproval: typeof result === 'object' &&

package/dist/function_call_loop/provider.d.ts

@@ -14,6 +14,7 @@ export interface ProviderOptions {
 export declare function createLLMCaller(options: ProviderOptions): {
     call(messages: ReadonlyArray<Message>, tools: ReadonlyArray<ToolDefinition>, callOptions?: LLMCallOptions): Promise<{
         readonly content: string | null;
+        readonly reasoningContent?: string;
         readonly tool_calls?: ReadonlyArray<ToolCall>;
     }>;
     /**

package/dist/function_call_loop/provider.js

@@ -31,6 +31,7 @@ function toOpenAIMessages(messages) {
         return ({
             role: m.role,
             content: m.content,
+            reasoning_content: m.reasoningContent,
             tool_calls: (_a = m.tool_calls) === null || _a === void 0 ? void 0 : _a.map((tc) => ({
                 id: tc.id,
                 type: tc.type,
@@ -80,6 +81,7 @@ function createLLMCaller(options) {
                 const choice = data.choices[0];
                 return {
                     content: choice.message.content,
+                    reasoningContent: choice.message.reasoning_content,
                     tool_calls: (_b = choice.message.tool_calls) === null || _b === void 0 ? void 0 : _b.map((tc) => ({
                         id: tc.id,
                         type: tc.type,
@@ -137,6 +139,7 @@ function createLLMCaller(options) {
                 // 用于增量收集 tool_calls
                 const toolCallAccumulators = [];
                 let fullContent = '';
+                let fullReasoningContent = '';
                 let hasYieldedFinish = false;
                 try {
                     while (true) {
@@ -164,6 +167,11 @@ function createLLMCaller(options) {
                             if (!choice)
                                 continue;
                             const delta = choice.delta;
+                            // 收集 reasoning_content 增量
+                            if (delta.reasoning_content) {
+                                fullReasoningContent += delta.reasoning_content;
+                                yield yield __await({ type: 'reasoning', delta: delta.reasoning_content });
+                            }
                             // 收集 content 增量
                             if (delta.content) {
                                 fullContent += delta.content;
@@ -209,6 +217,7 @@ function createLLMCaller(options) {
                                 yield yield __await({
                                     type: 'finish',
                                     content: fullContent || null,
+                                    reasoningContent: fullReasoningContent || undefined,
                                     tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
                                 });
                                 hasYieldedFinish = true;
@@ -233,6 +242,7 @@ function createLLMCaller(options) {
                         yield yield __await({
                             type: 'finish',
                             content: fullContent || null,
+                            reasoningContent: fullReasoningContent || undefined,
                             tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
                         });
                     }

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;
+        var _d, _e, _f, _g, _h, _j, _k;
         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,
@@ -108,6 +108,7 @@ function runLoopStream(config) {
             const messagesForLLM = yield __await((0, loop_1.compressMessages)(config, messages, turn));
             // 第五步：流式调用 LLM
             let fullContent = '';
+            let fullReasoningContent = '';
             let finishChunk = null;
             const stream = llmCaller.stream(messagesForLLM, toolDefinitions, {
                 model: config.model,
@@ -117,14 +118,18 @@ function runLoopStream(config) {
                 reasoningEffort: config.reasoningEffort,
             });
             try {
-                for (var _k = 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; _k = true) {
+                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) {
                     _c = stream_1_1.value;
-                    _k = false;
+                    _l = false;
                     const chunk = _c;
                     if (chunk.type === 'content') {
                         fullContent += chunk.delta;
                         yield yield __await({ type: 'content', delta: chunk.delta, turn });
                     }
+                    else if (chunk.type === 'reasoning') {
+                        fullReasoningContent += chunk.delta;
+                        yield yield __await({ type: 'reasoning', delta: chunk.delta, turn });
+                    }
                     else if (chunk.type === 'finish') {
                         finishChunk = chunk;
                     }
@@ -133,7 +138,7 @@ function runLoopStream(config) {
             catch (e_1_1) { e_1 = { error: e_1_1 }; }
             finally {
                 try {
-                    if (!_k && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
+                    if (!_l && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
                 }
                 finally { if (e_1) throw e_1.error; }
             }
@@ -142,11 +147,13 @@ function runLoopStream(config) {
             }
             // 使用 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);
             // 第六步：检查 LLM 回复
             if (!finishChunk.tool_calls || finishChunk.tool_calls.length === 0) {
                 messages.push({
                     role: 'assistant',
                     content: assistantContent,
+                    reasoningContent: assistantReasoningContent,
                 });
                 yield yield __await({ type: 'turn_end', turn });
                 return yield __await({
@@ -165,6 +172,7 @@ function runLoopStream(config) {
             messages.push({
                 role: 'assistant',
                 content: assistantContent,
+                reasoningContent: assistantReasoningContent,
                 tool_calls: finishChunk.tool_calls,
             });
             // 第七步：并行执行 tool
@@ -183,6 +191,7 @@ function runLoopStream(config) {
                     callId: result.toolCallId,
                     toolName: result.record.toolName,
                     content: result.content,
+                    frontendData: result.frontendData,
                     status: result.record.status,
                 });
             }

package/dist/function_call_loop/types.d.ts

@@ -5,6 +5,7 @@
 export interface Message {
     readonly role: 'system' | 'user' | 'assistant' | 'tool';
     readonly content: string;
+    readonly reasoningContent?: string;
     readonly tool_calls?: ReadonlyArray<ToolCall>;
     readonly tool_call_id?: string;
 }
@@ -106,6 +107,15 @@ export interface ApprovalConfig {
         approved?: boolean;
     }>;
 }
+/**
+ * Tool 执行结果的分流包装。
+ * 当 execute 返回此类型时，forLLM 进入 messages[] 给 LLM 上下文，
+ * forFrontend 通过 SSE tool_result 事件透给前端渲染。
+ */
+export interface ToolResult {
+    readonly forLLM: string;
+    readonly forFrontend?: unknown;
+}
 /**
  * 注册到 Loop 中的 Tool。
  */
@@ -114,7 +124,7 @@ export interface Tool {
     readonly description: string;
     readonly parameters: unknown;
     readonly discover?: (harness: ReadonlyArray<HarnessRecord>, metadata: unknown) => ToolDiscoverResult | Promise<ToolDiscoverResult>;
-    readonly execute: (args: unknown, context: ToolExecuteContext) => unknown | Promise<unknown>;
+    readonly execute: (args: unknown, context: ToolExecuteContext) => unknown | ToolResult | Promise<unknown | ToolResult>;
     readonly approval?: ApprovalConfig;
 }
 /**
@@ -150,9 +160,13 @@ export interface LLMCallOptions {
 export type LLMStreamChunk = {
     readonly type: 'content';
     readonly delta: string;
+} | {
+    readonly type: 'reasoning';
+    readonly delta: string;
 } | {
     readonly type: 'finish';
     readonly content: string | null;
+    readonly reasoningContent?: string;
     readonly tool_calls?: ReadonlyArray<ToolCall>;
 };
 /**
@@ -161,6 +175,7 @@ export type LLMStreamChunk = {
 export interface LLMCaller {
     readonly call: (messages: ReadonlyArray<Message>, tools: ReadonlyArray<ToolDefinition>, options?: LLMCallOptions) => Promise<{
         readonly content: string | null;
+        readonly reasoningContent?: string;
         readonly tool_calls?: ReadonlyArray<ToolCall>;
     }>;
     readonly stream?: (messages: ReadonlyArray<Message>, tools: ReadonlyArray<ToolDefinition>, options?: LLMCallOptions) => AsyncGenerator<LLMStreamChunk, void, unknown>;
@@ -225,6 +240,10 @@ export type LoopStreamChunk = {
     readonly type: 'content';
     readonly delta: string;
     readonly turn: number;
+} | {
+    readonly type: 'reasoning';
+    readonly delta: string;
+    readonly turn: number;
 } | {
     readonly type: 'tool_call';
     readonly turn: number;
@@ -235,6 +254,7 @@ export type LoopStreamChunk = {
     readonly callId: string;
     readonly toolName: string;
     readonly content: string;
+    readonly frontendData?: unknown;
     readonly status: HarnessRecordStatus;
 } | {
     readonly type: 'turn_end';

package/dist/llm_provider/bailian.js

@@ -80,6 +80,7 @@ class BailianProvider {
             const choice = data.choices[0];
             return {
                 content: choice.message.content,
+                reasoningContent: choice.message.reasoning_content,
                 usage: data.usage
                     ? {
                         promptTokens: data.usage.prompt_tokens,
@@ -152,6 +153,9 @@ class BailianProvider {
                         if (!choice)
                             continue;
                         const delta = choice.delta;
+                        if (delta.reasoning_content) {
+                            yield yield __await({ type: 'reasoning', delta: delta.reasoning_content });
+                        }
                         if (delta.content) {
                             yield yield __await({ type: 'content', delta: delta.content });
                         }

package/dist/llm_provider/index.d.ts

@@ -5,6 +5,7 @@
 export interface OpenAIChatMessage {
     role: string;
     content: string | null;
+    reasoning_content?: string;
     tool_calls?: Array<{
         id: string;
         type: 'function';
@@ -42,6 +43,7 @@ export interface OpenAIChatResponse {
     choices: Array<{
         message: {
             content: string | null;
+            reasoning_content?: string;
             tool_calls?: Array<{
                 id: string;
                 type: 'function';

package/dist/llm_provider/types.d.ts

@@ -22,6 +22,7 @@ export interface LLMRequest {
  */
 export interface LLMResponse {
     readonly content: string | null;
+    readonly reasoningContent?: string;
     readonly usage?: {
         readonly promptTokens: number;
         readonly completionTokens: number;
@@ -35,6 +36,9 @@ export interface LLMResponse {
 export type StreamChunk = {
     readonly type: 'content';
     readonly delta: string;
+} | {
+    readonly type: 'reasoning';
+    readonly delta: string;
 } | {
     readonly type: 'finish';
     usage?: LLMResponse['usage'];

package/package.json

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