@keo-ai/axiom 0.1.3 → 0.1.4

package/README.md

@@ -197,6 +197,362 @@ try {
 
 ---
 
+## Function Call Loop 模块
+
+Function Call Loop 是 Axiom 的底层 Function Call 引擎。它负责把 **LLM → Tool → Result → LLM** 的循环跑稳，同时向上层暴露完整的生命周期事件和执行历史（Harness）。
+
+### 核心设计
+
+| 设计点 | 说明 |
+|---|---|
+| **Harness 与 Messages 分离** | Harness 是只增不减的完整执行档案；Messages 是给 LLM 看的对话历史，可被压缩 |
+| **Prompt 完全外部化** | 引擎不内置任何系统提示词、告警文案或终止文案 |
+| **默认安全** | 默认不压缩、不隐藏 tool、不拦截执行 |
+| **Plan and Execute** | 单轮 LLM 可返回多个 tool call，这些 tool 在本轮内并行执行 |
+| **硬兜底与软策略并存** | Turn Policy 是每轮必走的软策略；`maxTurns` 是引擎底层的硬兜底 |
+
+### 快速开始
+
+#### 方式一：直接传模型参数（推荐）
+
+像 predict 模块一样，设置环境变量后一行调用：
+
+```bash
+export BAILIAN_API_KEY="your-api-key"
+```
+
+```ts
+import { FunctionCallLoop } from '@keo-ai/axiom';
+
+const result = await FunctionCallLoop.runLoopWithModel({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is the weather in Beijing?' },
+  ],
+  model: 'qwen-max',
+  temperature: 0.7,
+  maxTokens: 2048,
+  tools: [
+    {
+      name: 'get_weather',
+      description: 'Get weather for a city',
+      parameters: {
+        type: 'object',
+        properties: {
+          city: { type: 'string', description: 'City name' },
+        },
+        required: ['city'],
+      },
+      execute: async (args) => {
+        return { temperature: 25, condition: 'Sunny' };
+      },
+    },
+  ],
+  maxTurns: 5,
+  onEvent: (event) => {
+    if (event.type === 'execution:end') {
+      console.log(`${event.toolName}: ${event.status} (${event.durationMs}ms)`);
+    }
+  },
+});
+
+console.log(result.finalContent);
+console.log('Turns:', result.turns);
+console.log('Harness:', result.harness);
+```
+
+### 生命周期事件
+
+Loop 每处理一个 tool call，按顺序抛出两个事件：
+
+```ts
+const result = await FunctionCallLoop.runLoopWithModel({
+  // ...
+  onEvent: (event) => {
+    if (event.type === 'execution:start') {
+      console.log(`[${event.turn}] ${event.toolName} started`);
+    }
+    if (event.type === 'execution:end') {
+      console.log(`[${event.turn}] ${event.toolName} done in ${event.durationMs}ms`);
+      console.log(`[${event.turn}] ${event.toolName} result:`, event.result ?? event.error);
+    }
+  },
+});
+```
+
+| 事件 | 触发时机 | 包含字段 |
+|---|---|---|
+| `execution:start` | execute 函数被调用之前 | `callId`, `toolName`, `args`, `turn` |
+| `execution:end` | execute 函数返回之后 | `callId`, `toolName`, `status`, `durationMs`, `result` / `error`, `turn` |
+
+`status` 类型为 `HarnessRecordStatus`，取值如下：
+
+| 值 | 含义 |
+|---|---|
+| `'success'` | execute 函数正常返回 |
+| `'error'` | execute 函数抛异常 |
+| `'timeout'` | 执行超时 |
+| `'cancelled'` | 被 AbortSignal 取消 |
+
+### Harness（执行历史）
+
+Harness 是跨轮次累积的只读执行记录，tool 之间可以互相看见：
+
+```ts
+console.log(result.harness);
+// [
+//   { id: 'call-1', turn: 1, toolName: 'get_weather', status: 'success', ... },
+//   { id: 'call-2', turn: 2, toolName: 'get_time', status: 'success', ... },
+// ]
+```
+
+每条记录包含：唯一 ID、所属轮次、全局序号、tool 名称、参数、执行状态、返回值/错误、时间戳和耗时。
+
+**并行隔离原则**：本轮并行执行的多个 tool，各自收到的 Harness 是"本轮并行开始前"的快照，互相看不到同轮其他正在执行的 tool。
+
+### Tool 审批拦截
+
+对于敏感操作（转账、删除数据等），可以给 tool 配置 `approval`，Loop 会在执行前暂停并返回 `pendingApproval`：
+
+```ts
+const result = await FunctionCallLoop.runLoopWithModel({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Transfer 1000 to Alice' },
+  ],
+  metadata: { userId: 'u-123', orgId: 'o-456' },
+  tools: [
+    {
+      name: 'transfer_money',
+      description: 'Transfer money',
+      parameters: { /* ... */ },
+      approval: {
+        createTicket: async (args, context) => {
+          const { userId } = context.metadata as { userId: string };
+          const ticket = await createApprovalTicket({ ...args, applicant: userId });
+          return { ticketId: ticket.id };
+        },
+      },
+      execute: async (args) => {
+        // 审批通过后才会执行到这里
+        return await doTransfer(args);
+      },
+    },
+  ],
+});
+
+if (result.pendingApproval) {
+  // 保存 checkpoint，等待 webhook 回调或人工审批
+  await db.saveCheckpoint({
+    messages: result.messages,
+    ticketId: result.pendingApproval.ticketId,
+    toolName: result.pendingApproval.toolName,
+  });
+  return { status: 'waiting_approval' };
+}
+```
+
+审批通过后继续执行（tool 配置保持不变）：
+
+```ts
+const record = await db.findByTicketId(ticketId);
+
+const result = await FunctionCallLoop.runLoopWithModel({
+  messages: record.messages,
+  metadata: { userId: 'u-123', orgId: 'o-456' },
+  tools: [
+    {
+      name: 'transfer_money',
+      description: 'Transfer money',
+      parameters: { /* ... */ },
+      approval: {
+        createTicket: async (args, context) => {
+          // 查询该 ticket 是否已审批
+          const ticket = await db.findTicket(record.ticketId);
+          if (ticket?.status === 'approved') {
+            return { ticketId: ticket.id, approved: true };
+          }
+          return { ticketId: ticket.id };
+        },
+      },
+      execute: async (args) => await doTransfer(args),
+    },
+  ],
+});
+```
+
+**关键点**：
+- `approval.createTicket` 被调用时，`execute` **不会**执行；返回 `{ approved: true }` 时直接执行
+- `createTicket` 可通过 `context.metadata` 访问 `LoopConfig.metadata`，用于携带业务上下文
+- `result.messages` 中已包含完整的对话历史（assistant 的 tool_calls + 占位 tool result），可直接用于续跑
+- 恢复执行时无需去掉 `approval` 配置，通过 `createTicket` 内部判断审批状态即可
+
+### Tool 发现（动态可见性）
+
+每次调用 LLM 之前，Loop 会对所有已注册 tool 执行 `discover` 函数，动态决定本轮暴露哪些 tool：
+
+```ts
+const tool = {
+  name: 'admin_only',
+  description: 'Admin operation',
+  parameters: {},
+  discover: async (harness, metadata) => {
+    // 根据 Harness 或元数据决定是否暴露
+    const isAdmin = metadata?.role === 'admin';
+    return {
+      name: 'admin_only',
+      description: 'Admin operation',
+      parameters: {},
+      visible: isAdmin,
+    };
+  },
+  execute: async (args) => { /* ... */ },
+};
+```
+
+| 边界情况 | 行为 |
+|---|---|
+| `discover` 抛异常 | 视为 `visible: false`，该 tool 本轮隐藏 |
+| 所有 tool 都不可见 | LLM 接收空 tool 列表 |
+| LLM 调用了不可见的 tool | 按错误处理，记录 `error` 状态 |
+| 未配置 `discover` | 使用静态注册配置，`visible: true` |
+
+### Turn Policy（全局轮次策略）
+
+每轮开始时，Loop 先执行 Turn Policy 决定是继续还是终止：
+
+```ts
+const result = await FunctionCallLoop.runLoopWithModel({
+  // ...
+  turnPolicy: async (harness, turn, metadata) => {
+    // 连续失败降级
+    const failCount = harness.filter((r) => r.status === 'error').length;
+    if (failCount >= 3) {
+      return {
+        message: 'Too many failures, please try again later.',
+      };
+    }
+    return {};
+  },
+});
+```
+
+**默认策略**（未自定义时自动生效）：
+
+| 条件 | 行为 |
+|---|---|
+| `turn < maxTurns - 1` | 继续执行 |
+| `turn === maxTurns - 1` | 注入 `warningMessage`，继续执行 |
+| `turn >= maxTurns` | 注入 `terminateMessage`，终止 Loop |
+
+| 边界情况 | 行为 |
+|---|---|
+| `turnPolicy` 抛异常 | 视为 `continue`，记录异常 |
+| 返回 `terminate` | 向 Messages 塞入 `fallbackMessage`，结束 Loop，不再调 LLM |
+
+### 上下文压缩
+
+控制给 LLM 的历史消息长度，只动 Messages，不动 Harness：
+
+```ts
+const result = await FunctionCallLoop.runLoopWithModel({
+  // ...
+  compression: {
+    keepRounds: 3, // 最近 3 轮保持完整
+    compress: async (oldRounds) => {
+      // oldRounds: 需要压缩的轮次数组，每轮是一个 Message 数组
+      // 返回压缩后的 Message 数组
+      return [
+        {
+          role: 'system',
+          content: `Previous ${oldRounds.length} rounds summarized...`,
+        },
+      ];
+    },
+  },
+});
+```
+
+| 规则 | 说明 |
+|---|---|
+| 压缩只影响 Messages | Harness 始终完整保留 |
+| 系统消息和初始输入不参与压缩 | 始终保留 |
+| `compress` 抛异常 | 视为不压缩，使用原始 Messages 继续执行 |
+
+### 取消信号
+
+支持通过 `AbortSignal` 终止 Loop：
+
+```ts
+const controller = new AbortController();
+
+const promise = FunctionCallLoop.runLoopWithModel({
+  // ...
+  signal: controller.signal,
+});
+
+// 5 秒后取消
+setTimeout(() => controller.abort(), 5000);
+
+const result = await promise;
+```
+
+### 配置项
+
+#### `runLoopWithModel` 配置
+
+**对话入口**
+
+| 配置项 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `messages` | `Message[]` | ✓ | 初始消息列表，直接作为对话起点 |
+
+**Tool 与执行控制**
+
+| 配置项 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `tools` | `Tool[]` | ✅ | 注册的 tool 列表 |
+| `maxTurns` | `number` | — | 最大轮次，默认无限制 |
+| `turnPolicy` | `TurnPolicy` | — | 自定义轮次策略 |
+| `compression` | `CompressionConfig` | — | 上下文压缩配置 |
+| `metadata` | `unknown` | — | 传递给 Tool 和 Turn Policy 的元数据 |
+| `warningMessage` | `string` | — | 默认策略在 `maxTurns - 1` 时注入的告警文本 |
+| `terminateMessage` | `string` | — | 默认策略在 `maxTurns` 时注入的终止文本 |
+| `onEvent` | `(event) => void` | — | 生命周期事件监听器 |
+| `signal` | `AbortSignal` | — | 取消信号 |
+
+**LLM 调用参数**
+
+| 配置项 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `model` | `string` | — | 模型名称。默认从 `BAILIAN_DEFAULT_MODEL` 环境变量读取，否则 `qwen-max` |
+| `maxTokens` | `number` | — | 单次 LLM 调用的最大输出 token 数 |
+| `temperature` | `number` | — | 采样温度，范围 0~2 |
+| `topP` | `number` | — | 核采样概率阈值，范围 0~1 |
+| `reasoningEffort` | `'low' \| 'medium' \| 'high'` | — | 推理深度。仅部分模型支持（如 o1、o3） |
+
+### 返回结果
+
+```ts
+interface LoopResult {
+  messages: Message[];              // 完整的对话历史
+  harness: HarnessRecord[];         // 执行历史
+  finalContent: string | null;      // 最终回复内容
+  turns: number;                    // 实际执行轮数
+}
+```
+
+### 错误处理
+
+同其他模块：**直接抛异常**。常见场景：
+
+- `execute` 抛异常 → 记录 `error` 状态，发出事件，不影响同轮其他并行 tool
+- `discover` 抛异常 → 该 tool 本轮隐藏
+- `compress` 抛异常 → 视为不压缩
+- `turnPolicy` 抛异常 → 视为 `continue`
+
+---
+
 ## EmbeddingSearch 模块（向量检索）
 
 EmbeddingSearch 是 Axiom 的 RAG 底座。它封装了 `query → embedding → pgvector 检索 → [可选 rerank]` 的完整链路，只需一行代码即可实现语义检索。
@@ -235,6 +591,14 @@ CREATE TABLE documents (
 CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);
 ```
 
+### 列设计建议
+
+EmbeddingSearch 不限制你的 schema，但建议遵循这个分层原则：
+
+- **频繁过滤或需要索引的字段** → 放独立列（如 `category`、`price`），配合 `filter` 做数据库层过滤
+- **不参与索引的业务杂项** → 可以放入 JSONB 列（如 `metadata`），通过 `select` 整列取出后在应用层消费。JSONB 不适合 `filter`，普通等值比较走不了索引，容易触发全表扫描
+- **rerank 的文本内容** → 必须是独立的文本列（`TEXT`/`VARCHAR`），`rerankKey` 不支持指向 JSONB 列
+
 ### 快速开始
 
 不传 `select` 时默认返回所有列（`SELECT *`）：
@@ -301,10 +665,11 @@ interface SearchResult {
 | `embeddingThreshold` | `number` | `0.8` | embedding 相似度阈值过滤（cosine similarity） |
 | `rerankThreshold` | `number` | `0.1` | rerank 分数阈值过滤 |
 | `embeddingColumn` | `string` | `'embedding'` | 向量列名 |
-| `rerankKey` | `string` | `'query'` | 启用 rerank 时，用于重排序的文本列名 |
+| `rerankKey` | `string` | `'query'` | 启用 rerank 时，用于重排序的文本列名（必须是文本列，不支持 JSONB） |
 | `dimensions` | `number` | `1024` | embedding 输出维度（1 ~ 1024） |
 | `select` | `string[]` | `undefined` | 指定返回哪些列，不传则 `SELECT *` |
-| `filter` | `Record<string, unknown>` | — | 对表独立列做等值/范围过滤 |
+| `filter` | `Record<string, unknown>` | — | 对表独立列做等值/范围过滤（不支持 JSONB 内部字段） |
+| `parseEnum` | `boolean` | `true` | 是否将枚举字段的数字值自动解析为可读文本 |
 
 ### 过滤
 
@@ -333,6 +698,43 @@ const multi = await EmbeddingSearch.query('query', {
 }, pool);
 ```
 
+> `filter` 只支持对独立列做过滤，不支持 JSONB 内部字段（如 `metadata->>'field'`）。
+
+### 枚举值解析
+
+默认开启 `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
+```
+
+未知枚举值、非数字类型、非枚举字段均保持原样不变。
+
 ### 生成 Embedding
 
 如果你只需要把文本转成向量，直接用 `embed`：

package/dist/embedding_search/enums.d.ts

@@ -0,0 +1,6 @@
+export declare const JournalTypeMap: Record<number, string>;
+export declare const SubjectMap: Record<number, string>;
+export declare const DatabaseMap: Record<number, string>;
+export declare const AttributeMap: Record<number, string>;
+export declare const OAMap: Record<number, string>;
+export declare function parseEnumValues(results: Array<Record<string, unknown>>): Array<Record<string, unknown>>;

package/dist/embedding_search/enums.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAMap = exports.AttributeMap = exports.DatabaseMap = exports.SubjectMap = exports.JournalTypeMap = void 0;
+exports.parseEnumValues = parseEnumValues;
+exports.JournalTypeMap = {
+    1: '正刊',
+    2: '专刊',
+    3: '专刊(SI)',
+    4: '增刊',
+    5: '摘要集',
+    6: 'EI',
+    7: 'ESCI/Scopus',
+    8: '中英文普刊',
+    9: 'Scopus',
+    10: '中文核心',
+    11: 'SCI/SSCI/AHCI',
+    12: 'SCI&SSCI',
+    13: 'SCI',
+    14: '科技核心',
+    15: '英文普刊',
+    16: '中文普刊',
+};
+exports.SubjectMap = {
+    11: '医学',
+    12: '生物',
+    13: '农林科学',
+    14: '环境科学与生态学',
+    15: '化学',
+    16: '工程技术',
+    17: '计算机',
+    18: '数学',
+    19: '物理与天体物理',
+    20: '地球科学',
+    21: '人文社科',
+    22: '经济学与管理学',
+    23: '多学科',
+    24: '材料科学',
+    25: '心理学',
+};
+exports.DatabaseMap = {
+    1: 'SSCI',
+    2: 'SCI(SCIE)',
+    3: 'EI',
+    5: '知网(CNKI)',
+    6: 'A&HCI',
+    7: 'Scopus',
+    9: 'IEEE Xplore',
+    12: 'Google Scholar',
+    13: 'ESCI',
+    14: 'CPCI-S',
+    15: 'CPCI-SSH',
+    16: '维普(VIP)',
+    17: '万方(Wanfang)',
+    18: 'CNKI Scholar(知网外文库)',
+    19: 'Medline',
+    20: 'PubMed',
+    21: '万方应用',
+    22: '超星(Superstar)',
+    23: '龙源',
+    24: '中文社会科学引文索引(CSSCI/南大核心)',
+    25: '中文核心期刊要目(北大核心)',
+    26: '中国科技论文与引文数据库(CSTPCD/科技核心)',
+    27: 'CSSCI',
+    28: '中国科学引文数据库(CSCD)',
+    29: '中国科学引文数据库的扩展版本(CSCD扩展版)',
+    30: 'AMI核心',
+    31: 'AMI扩展',
+    32: '武大核心(RCCSE)',
+    33: 'Mycite',
+};
+exports.AttributeMap = {
+    1: '调研刊',
+    2: '合作刊',
+    3: '快审刊',
+    4: '速发刊',
+};
+exports.OAMap = {
+    1: '开源模式(OA)',
+    2: '订阅模式(非OA)',
+    3: '混合模式(OA/非OA)',
+};
+const EnumFieldMaps = {
+    type: exports.JournalTypeMap,
+    subject1: exports.SubjectMap,
+    db: exports.DatabaseMap,
+    attribute: exports.AttributeMap,
+    oa: exports.OAMap,
+};
+function parseEnumValues(results) {
+    return results.map((row) => {
+        const parsed = Object.assign({}, row);
+        for (const [field, map] of Object.entries(EnumFieldMaps)) {
+            if (field in parsed) {
+                const val = parsed[field];
+                if (typeof val === 'number' || typeof val === 'string') {
+                    const numVal = typeof val === 'string' ? Number(val) : val;
+                    if (!Number.isNaN(numVal) && numVal in map) {
+                        parsed[field] = map[numVal];
+                    }
+                }
+            }
+        }
+        return parsed;
+    });
+}

package/dist/embedding_search/index.js

@@ -23,6 +23,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.embed = exports.EmbeddingSearch = void 0;
 const pgvector_1 = require("./pgvector");
 const embed_1 = require("./embed");
+const enums_1 = require("./enums");
 const RERANK_URL = 'https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank';
 const RERANK_MODEL = 'qwen3-rerank';
 function rerank(query, documents, topN, apiKey) {
@@ -89,7 +90,7 @@ function rerank(query, documents, topN, apiKey) {
 class EmbeddingSearch {
     static query(query, config, pool) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { enableRerank = true, embeddingTopK = 10, finalTopN = 5, embeddingThreshold = 0.8, rerankThreshold = 0.1, tableName, embeddingColumn, rerankKey = 'query', dimensions, filter, select, } = config;
+            const { enableRerank = true, embeddingTopK = 10, finalTopN = 5, embeddingThreshold = 0.8, rerankThreshold = 0.1, tableName, embeddingColumn, rerankKey = 'query', dimensions, filter, select, parseEnum = true, } = config;
             const idColumn = 'id';
             const actualTopK = enableRerank
                 ? Math.max(embeddingTopK, finalTopN)
@@ -123,9 +124,15 @@ class EmbeddingSearch {
                     throw new Error(`Rerank requires column "${rerankKey}" but it was not found. ` +
                         `Either create this column in your table, or set rerankKey to the correct column name.`);
                 }
+                const nonStringRerank = searchResults.find((r) => typeof r[rerankKey] !== 'string');
+                if (nonStringRerank) {
+                    throw new Error(`Rerank requires column "${rerankKey}" to be a text column, but got ${typeof nonStringRerank[rerankKey]}. ` +
+                        `JSONB columns are not supported for rerank.`);
+                }
             }
             if (!enableRerank) {
-                return searchResults.slice(0, finalTopN);
+                const results = searchResults.slice(0, finalTopN);
+                return parseEnum ? (0, enums_1.parseEnumValues)(results) : results;
             }
             const rerankResults = yield rerank(query, searchResults.map((r) => ({
                 id: r[idColumn],
@@ -148,7 +155,7 @@ class EmbeddingSearch {
                     return rest;
                 });
             }
-            return reranked;
+            return parseEnum ? (0, enums_1.parseEnumValues)(reranked) : reranked;
         });
     }
     static vectorSearch(options) {

package/dist/embedding_search/types.d.ts

@@ -18,6 +18,7 @@ export interface EmbeddingSearchConfig {
     readonly dimensions?: number;
     readonly filter?: Record<string, FilterValue>;
     readonly select?: string[];
+    readonly parseEnum?: boolean;
 }
 export interface SearchResult {
     readonly [key: string]: unknown;

package/dist/function_call_loop/harness.d.ts

@@ -0,0 +1,34 @@
+import type { HarnessRecord, HarnessRecordStatus } from './types';
+/**
+ * 执行历史（Harness）。
+ * 按时间顺序累积执行记录，只追加不修改，跨轮次持续累积。
+ */
+export declare class Harness {
+    private records;
+    /** 当前 Harness 中的记录数量 */
+    get length(): number;
+    /** 获取完整记录数组的只读视图 */
+    getAll(): ReadonlyArray<HarnessRecord>;
+    /** 获取当前记录的副本（快照） */
+    snapshot(): ReadonlyArray<HarnessRecord>;
+    /**
+     * 追加一条记录。
+     * @param record - 要追加的记录
+     */
+    append(record: HarnessRecord): void;
+}
+/**
+ * 创建一条 pending 状态的 HarnessRecord。
+ */
+export declare function createPendingRecord(params: {
+    id: string;
+    turn: number;
+    globalIndex: number;
+    toolName: string;
+    args: unknown;
+    rawArgs: string;
+}): HarnessRecord;
+/**
+ * 将 pending 记录完善为最终状态。
+ */
+export declare function finalizeRecord(record: HarnessRecord, status: Exclude<HarnessRecordStatus, 'pending'>, result?: unknown, error?: string): HarnessRecord;

package/dist/function_call_loop/harness.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Harness = void 0;
+exports.createPendingRecord = createPendingRecord;
+exports.finalizeRecord = finalizeRecord;
+/**
+ * 执行历史（Harness）。
+ * 按时间顺序累积执行记录，只追加不修改，跨轮次持续累积。
+ */
+class Harness {
+    constructor() {
+        this.records = [];
+    }
+    /** 当前 Harness 中的记录数量 */
+    get length() {
+        return this.records.length;
+    }
+    /** 获取完整记录数组的只读视图 */
+    getAll() {
+        return this.records;
+    }
+    /** 获取当前记录的副本（快照） */
+    snapshot() {
+        return [...this.records];
+    }
+    /**
+     * 追加一条记录。
+     * @param record - 要追加的记录
+     */
+    append(record) {
+        this.records.push(record);
+    }
+}
+exports.Harness = Harness;
+/**
+ * 创建一条 pending 状态的 HarnessRecord。
+ */
+function createPendingRecord(params) {
+    return Object.assign(Object.assign({}, params), { status: 'pending', startedAt: Date.now(), durationMs: 0 });
+}
+/**
+ * 将 pending 记录完善为最终状态。
+ */
+function finalizeRecord(record, status, result, error) {
+    return Object.assign(Object.assign({}, record), { status,
+        result,
+        error, durationMs: Date.now() - record.startedAt });
+}

package/dist/function_call_loop/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Function Call Loop — Function Call 引擎。
+ *
+ * 核心能力：
+ * - 每次 tool 执行向上层回传执行前、执行后两个事件
+ * - 维护跨轮次的执行历史（Harness），tool 之间能互相看见
+ * - 每次调 LLM 之前动态决定暴露哪些 tool
+ * - 支持自定义上下文压缩
+ * - 每轮全局策略判断，决定继续执行还是终止降级
+ * - 单轮支持多个 tool 并行执行（Plan and Execute）
+ * - 系统 Prompt 完全由外部注入
+ */
+export { runLoopWithModel } from './loop';
+export type { Message, ToolCall, ToolDefinition, HarnessRecord, HarnessRecordStatus, ToolExecutionStartEvent, ToolExecutionEndEvent, LoopEvent, ToolDiscoverResult, ToolExecuteContext, Tool, ApprovalConfig, TurnPolicyResult, TurnPolicy, CompressionConfig, LLMCaller, LLMCallOptions, LoopConfig, LoopResult, PendingApprovalInfo, } from './types';