@keo-ai/axiom 0.1.9 → 0.2.0

package/README.md

@@ -411,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`：

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

@@ -263,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。
  */
@@ -367,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/stream.js

@@ -191,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

@@ -107,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。
  */
@@ -115,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;
 }
 /**
@@ -245,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/package.json

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