foliko 2.0.29 → 2.0.31

package/docs/plugin-dev-guide.md

@@ -0,0 +1,850 @@
+# Plugin 开发指南
+
+> 本指南详细说明如何在 Foliko 框架中开发插件。
+
+---
+
+## 目录
+
+- [1. 概述](#1-概述)
+- [2. 插件存放位置](#2-插件存放位置)
+- [3. 用户插件开发](#3-用户插件开发)
+- [4. 内置插件开发](#4-内置插件开发)
+- [5. 插件属性](#5-插件属性)
+- [6. 生命周期](#6-生命周期)
+- [7. 工具注册](#7-工具注册)
+- [8. 扩展工具](#8-扩展工具)
+- [9. 子 Agent](#9-子-agent)
+- [10. 工作流](#10-工作流)
+- [11. Prompt Parts](#11-prompt-parts)
+- [12. Skill 管理](#12-skill-管理)
+- [13. 依赖管理](#13-依赖管理)
+- [14. 系统插件访问](#14-系统插件访问)
+- [15. 最佳实践](#15-最佳实践)
+
+---
+
+## 1. 概述
+
+Foliko 是一个基于插件的 Agent 框架，核心保持简单，通过插件扩展功能。
+
+### 插件 vs 技能
+
+| 类型 | 存储位置 | 说明 |
+|------|----------|------|
+| **Plugin（插件）** | `.foliko/plugins/` | 扩展功能模块 |
+| **Skill（技能）** | `.foliko/skills/` | 为 Agent 提供指导的知识包 |
+
+---
+
+## 2. 插件存放位置
+
+### 用户插件 `.foliko/plugins/`
+
+用户自定义插件放在项目根目录的 `.foliko/plugins/` 下，**自动加载**，无需手动注册。
+
+**推荐使用文件夹结构**（适合复杂插件）：
+
+```
+项目目录/
+└── .foliko/
+    └── plugins/
+        ├── my-plugin/              ✅ 文件夹结构（推荐）
+        │   ├── package.json        # 可选，main 字段指定入口
+        │   ├── index.js            # 默认入口
+        │   └── node_modules/       # 可选，插件私有依赖
+        ├── another-plugin/         ✅ 另一个文件夹插件
+        │   └── index.js
+        └── legacy.js               ✅ 单文件仍支持
+```
+
+### 内置插件 `plugins/`
+
+框架内置插件位于仓库根目录的 `plugins/` 目录，需要 `require` Plugin 基类。
+
+---
+
+## 3. 用户插件开发
+
+### 文件夹结构（推荐）
+
+```
+.foliko/plugins/my-plugin/
+├── package.json      # 可选
+└── index.js          # 入口
+```
+
+```javascript
+// .foliko/plugins/my-plugin/index.js
+const { z } = require('zod');
+
+module.exports = function (Plugin) {
+  return class MyPlugin extends Plugin {
+    constructor(config = {}) {
+      super();
+      this.name = 'my-plugin';
+      this.version = '1.0.0';
+      this.description = '我的工具插件';
+      this.priority = 10;
+    }
+
+    // 方式1：声明式工具定义
+    tools = {
+      my_tool: {
+        description: '我的工具',
+        inputSchema: z.object({
+          param: z.string().describe('参数描述'),
+        }),
+        execute: async (args) => {
+          return { success: true, result: args.param };
+        },
+      },
+    };
+
+    // 方式2：生命周期方法
+    onStart(framework) {
+      // 注册额外工具
+      this.tool.register({
+        name: 'another_tool',
+        description: '另一个工具',
+        inputSchema: z.object({}),
+        execute: async (args) => ({ success: true }),
+      });
+    }
+
+    uninstall(framework) {
+      // 清理资源
+    }
+  };
+};
+```
+
+### 单文件结构（仍支持）
+
+```javascript
+// .foliko/plugins/my-plugin.js
+const { z } = require('zod');
+
+module.exports = function (Plugin) {
+  return class MyPlugin extends Plugin {
+    constructor(config = {}) {
+      super();
+      this.name = 'my-plugin';
+      this.version = '1.0.0';
+      this.description = '我的工具插件';
+      this.priority = 10;
+    }
+
+    tools = {
+      my_tool: {
+        description: '我的工具',
+        inputSchema: z.object({
+          param: z.string().describe('参数描述'),
+        }),
+        execute: async (args) => {
+          return { success: true, result: args.param };
+        },
+      },
+    };
+
+    onStart(framework) {}
+    uninstall(framework) {}
+  };
+};
+```
+
+**注意**：如果文件夹和同名 `.js` 文件同时存在，**文件夹优先**。
+
+---
+
+## 4. 内置插件开发
+
+内置插件需要显式引入 Plugin 基类：
+
+```javascript
+// plugins/my-plugin.js
+const { Plugin } = require('../src/plugin/base');
+const { z } = require('zod');
+
+class MyPlugin extends Plugin {
+  constructor(config = {}) {
+    super();
+    this.name = 'my-plugin';
+    this.version = '1.0.0';
+    this.description = '我的工具插件';
+    this.priority = 10;
+  }
+
+  tools = {
+    my_tool: {
+      description: '我的工具',
+      inputSchema: z.object({
+        param: z.string().describe('参数描述'),
+      }),
+      execute: async (args) => {
+        return { success: true, result: args.param };
+      },
+    },
+  };
+
+  onStart(framework) {
+    // 注册额外工具
+    this.tool.register({
+      name: 'another_tool',
+      description: '另一个工具',
+      inputSchema: z.object({}),
+      execute: async (args) => ({ success: true }),
+    });
+  }
+
+  uninstall(framework) {}
+}
+
+module.exports = MyPlugin;
+```
+
+---
+
+## 5. 插件属性
+
+| 属性 | 类型 | 必须 | 说明 |
+|------|------|------|------|
+| `name` | string | ✅ | 唯一名称 |
+| `version` | string | ❌ | 版本号，默认 '1.0.0' |
+| `description` | string | ❌ | 插件描述 |
+| `priority` | number | ❌ | 加载优先级，默认 100 |
+| `tools` | object | ❌ | 声明式工具定义 |
+| `agents` | array | ❌ | 声明式子 Agent 定义 |
+| `prompts` | array | ❌ | 声明式 prompt parts |
+| `enabled` | boolean | ❌ | 是否启用，默认 true |
+| `system` | boolean | ❌ | 是否系统插件，默认 false |
+
+---
+
+## 6. 生命周期
+
+| 方法 | 调用时机 | 必须实现 | 说明 |
+|------|----------|----------|------|
+| `install(framework)` | 插件安装时 | ✅ | 初始化，获取 framework |
+| `onStart(framework)` | start/enable/reload 时 | 推荐 | 注册工具、扩展、子代理 |
+| `onStop()` | disable 时 | 可选 | 清理资源 |
+| `reload(framework)` | 热重载时 | 可选 | prompts 自动清理/注册 |
+| `uninstall(framework)` | 卸载时 | 推荐 | 清理资源 |
+
+### 生命周期流程
+
+```
+install() → onStart() → (reload()) → onStop() → uninstall()
+```
+
+### onStart / onStop（推荐方式）
+
+**推荐使用 `onStart` 注册工具和扩展**，基类自动处理生命周期：
+
+```javascript
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+
+  onStart(framework) {
+    // 注册 AI SDK 工具（直接调用）
+    this.tool.register({
+      name: 'hello',
+      description: '打招呼',
+      inputSchema: framework.z.object({
+        name: framework.z.string().describe('姓名')
+      }),
+      execute: async (args) => ({ message: `Hello, ${args.name}!` }),
+    });
+
+    // 注册扩展工具（通过 ext_call 调用）
+    this.extension.register({
+      name: 'greet_ext',
+      description: '打招呼扩展',
+      inputSchema: framework.z.object({
+        name: framework.z.string()
+      }),
+      execute: async (args) => ({ message: `Hi, ${args.name}!` }),
+    });
+  }
+
+  onStop() {
+    // 清理资源（如果需要）
+  }
+}
+```
+
+### 生命周期自动管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除工具/扩展（保留注册记录） |
+| `enable` | 自动重新注册工具/扩展 |
+| `reload` | 移除后重新注册 |
+| `uninstall` | 移除并清空注册记录 |
+
+---
+
+## 7. 工具注册
+
+### 方式1：`this.tools = {}`（声明式）
+
+插件将工具定义在 `this.tools = {}` 中，ExtensionExecutor 会自动扫描并注册：
+
+```javascript
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+
+  tools = {
+    my_tool: {
+      description: '我的工具',
+      inputSchema: z.object({
+        param: z.string().describe('参数描述'),
+      }),
+      execute: async (args) => {
+        return { success: true, result: args.param };
+      },
+    },
+  };
+}
+```
+
+### 方式2：`this.tool.register()`（推荐）
+
+在 `onStart` 中使用，支持完整的生命周期管理：
+
+```javascript
+onStart(framework) {
+  this.tool.register({
+    name: 'my_tool',
+    description: '我的工具',
+    inputSchema: framework.z.object({
+      param: framework.z.string().describe('参数描述')
+    }),
+    execute: async (args) => {
+      return { success: true, result: args.param };
+    }
+  });
+}
+```
+
+### 方式3：`this.registerTool()`（旧方式）
+
+```javascript
+install(framework) {
+  this.registerTool('my_tool', {
+    description: '我的工具',
+    inputSchema: framework.z.object({
+      param: framework.z.string().describe('参数描述')
+    }),
+    execute: async (args) => ({ success: true })
+  });
+  return this;
+}
+```
+
+### 工具操作
+
+```javascript
+// 注册
+this.tool.register({ name: 'xxx', ... });
+
+// 移除
+this.tool.remove('xxx');
+
+// 执行
+const result = await this.tool.execute('any-tool', { arg: 'value' });
+```
+
+---
+
+## 8. 扩展工具
+
+扩展工具通过 `ext_call` 间接调用，适合需要额外封装的工具。
+
+### 注册扩展工具
+
+```javascript
+onStart(framework) {
+  this.extension.register({
+    name: 'my_ext_tool',
+    description: '扩展工具',
+    inputSchema: framework.z.object({
+      param: framework.z.string()
+    }),
+    execute: async (args) => ({ success: true, data: args.param })
+  });
+}
+```
+
+### 调用扩展工具
+
+```javascript
+// 通过 ext_call 调用
+const result = await ext_call({
+  plugin: 'my-plugin',
+  tool: 'my_ext_tool',
+  args: { param: 'value' }
+});
+```
+
+### 扩展工具操作
+
+```javascript
+// 注册
+this.extension.register({ name: 'xxx', ... });
+
+// 移除
+this.extension.remove('xxx');
+
+// 执行（当前插件）
+const r1 = await this.extension.execute('xxx', { arg: 'value' });
+
+// 执行（指定插件）
+const r2 = await this.extension.execute('plugin-name', 'xxx', { arg: 'value' });
+```
+
+---
+
+## 9. 子 Agent
+
+### 配置式注册
+
+```javascript
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+
+  agents = [
+    {
+      name: 'code-agent',
+      role: '代码专家',
+      description: '处理代码开发任务',
+      tools: {
+        compile: {
+          description: '编译代码',
+          inputSchema: z.object({
+            language: z.string(),
+            code: z.string(),
+          }),
+          execute: async (args) => ({ success: true }),
+        },
+      },
+      parentTools: ['read_file', 'write_file'],
+    },
+  ];
+}
+```
+
+### 手动注册
+
+```javascript
+onStart(framework) {
+  this.agent.register({
+    name: 'code-agent',
+    role: '代码专家',
+    description: '处理代码开发任务',
+    tools: {
+      compile: {
+        description: '编译代码',
+        inputSchema: framework.z.object({
+          language: framework.z.string(),
+          code: framework.z.string(),
+        }),
+        execute: async (args) => ({ success: true }),
+      },
+    },
+    parentTools: ['read_file', 'write_file'],
+  });
+}
+```
+
+### 子 Agent 配置说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 子 Agent 名称（唯一标识） |
+| `role` | string | 角色描述 |
+| `description` | string | 详细描述 |
+| `tools` | object | 自定义工具，只属于此子 Agent |
+| `parentTools` | array | 从父 Agent 继承的工具名称列表 |
+
+### 子 Agent 操作
+
+```javascript
+// 获取
+const agent = this.agent.get('my-agent');
+
+// 移除
+this.agent.remove('my-agent');
+```
+
+---
+
+## 10. 工作流
+
+### 注册工作流
+
+```javascript
+onStart(framework) {
+  this.workflow.register('my-workflow', {
+    name: 'my-workflow',
+    description: '我的工作流',
+    inputSchema: framework.z.object({
+      msg: framework.z.string()
+    }),
+    steps: [
+      { type: 'tool', tool: 'hello', args: { name: '{{inputs.msg}}' } },
+      { type: 'action', code: 'return { result: inputs.msg + "!" }' }
+    ]
+  });
+}
+```
+
+### 工作流操作
+
+```javascript
+// 执行
+const result = await this.workflow.execute('my-workflow', { msg: 'hello' });
+
+// 移除
+this.workflow.remove('my-workflow');
+```
+
+---
+
+## 11. Prompt Parts
+
+### 配置式注册
+
+```javascript
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+
+  prompts = [
+    {
+      name: 'my-prompt',
+      scope: 'global',         // 'global' | 'main' | agentId
+      priority: 50,           // 数字越小越靠前
+      description: '我的提示词',
+      provider() {
+        return '这是动态生成的提示词内容';
+      },
+    },
+  ];
+}
+```
+
+### 手动注册
+
+```javascript
+onStart(framework) {
+  this.prompt.register('my-prompt', () => 'Prompt content', {
+    scope: 'global',
+    priority: 50
+  });
+}
+```
+
+### Prompt 操作
+
+```javascript
+// 移除
+this.prompt.remove('my-prompt');
+```
+
+---
+
+## 12. Skill 管理
+
+### 注册 Skill
+
+```javascript
+onStart(framework) {
+  this.skill.register(
+    'my-skill',
+    '# 我的技能\n\n这是一个技能说明',
+    {
+      description: '技能描述',
+      tags: ['test'],
+    },
+    {
+      commands: [
+        {
+          name: 'do',
+          description: '执行操作',
+          options: [
+            { flags: '-x <x>', description: '参数', required: true },
+          ],
+          execute: async (args) => ({ x: args.x }),
+        },
+      ],
+    }
+  );
+}
+```
+
+### Skill 操作
+
+```javascript
+// 检查是否存在
+this.skill.has('my-skill');
+
+// 获取详情
+this.skill.get('my-skill');
+this.skill.details('my-skill');
+
+// 列出
+this.skill.list();
+this.skill.listOwned();   // 本插件注册的
+
+// 执行
+await this.skill.execute('my-skill:do', { x: 1 });
+
+// 移除
+this.skill.remove('my-skill');
+```
+
+---
+
+## 13. 依赖管理
+
+### 依赖安装位置
+
+| 插件类型 | 安装位置 | 说明 |
+|----------|----------|------|
+| **文件夹插件** | `.foliko/plugins/插件名/node_modules/` | 插件自包含，可独立迁移 |
+| **单文件插件** | `.foliko/node_modules/` | 共享依赖 |
+
+### 安装工具
+
+```javascript
+// 安装到默认位置 .foliko/node_modules
+install({ package: 'zod' });
+
+// 安装到指定目录（文件夹插件）
+install({ package: 'axios', path: '.foliko/plugins/my-plugin' });
+
+// 从 package.json 安装
+install({ file: './my-plugin/package.json', path: '.foliko/plugins/my-plugin' });
+```
+
+### 重要依赖版本要求
+
+**zod 必须使用 `"zod": "^3.25.76"` 版本**
+
+---
+
+## 14. 系统插件访问
+
+### 可访问的系统插件
+
+| 插件名 | 说明 | 可用方法 |
+|--------|------|----------|
+| `storage` | 键值对存储 | `get(key)`, `set(key, value)`, `delete(key)` |
+| `session` | 会话管理 | `getSession(id)`, `getHistory(id)` |
+| `audit` | 审计日志 | `log(type, data)` |
+| `scheduler` | 定时任务 | `addTask()`, `removeTask()` |
+| `file-system` | 文件操作 | 工具已注册: `read_file`, `write_file` |
+| `tools` | 工具管理 | `list()`, `reload()` |
+| `ai` | AI 配置 | `getAIClient()` |
+
+### 访问示例
+
+```javascript
+install(framework) {
+  // 访问 storage 插件
+  const storage = this._framework.pluginManager.get('storage');
+
+  // 访问 session 插件
+  const session = this._framework.pluginManager.get('session');
+
+  // 访问 audit 插件
+  const audit = this._framework.pluginManager.get('audit');
+}
+```
+
+### Storage 插件 API
+
+```javascript
+const storage = this._framework.pluginManager.get('storage');
+
+// 方式1：通过工具调用（推荐）
+// storage_get({ key: 'xxx', namespace: 'yyy' })
+// storage_set({ key: 'xxx', value: {...}, namespace: 'yyy' })
+
+// 方式2：直接调用内部方法
+const value = storage.getStore().get('key');
+storage.setDirect('key', value);
+storage.deleteDirect('key');
+```
+
+### Session 插件 API
+
+```javascript
+const session = this._framework.pluginManager.get('session');
+
+// 获取会话
+const sess = session.getSession(sessionId);
+
+// 获取历史消息
+const messages = session.getHistory(sessionId);
+
+// 添加消息
+session.addMessage(sessionId, { role: 'user', content: 'hello' });
+```
+
+---
+
+## 15. 最佳实践
+
+### 核心规则
+
+| 规则 | 说明 |
+|------|------|
+| **优先使用 this.tools = {}** | ExtensionExecutor 自动扫描并注册到系统提示词 |
+| **优先使用文件夹结构** | 复杂插件推荐用文件夹，便于管理依赖和代码 |
+| **必须用 inputSchema** | `inputSchema: z.object({})`（不是 parameters!） |
+| **必须用 zod 定义参数** | `param: z.string().describe('描述')` |
+| **install 必须返回 this** | 确保链式调用 |
+| **文件夹与文件重名时** | 文件夹优先，同名 `.js` 文件会被忽略 |
+| **工具自动出现在系统提示词** | 定义在 `this.tools` 中会自动注册 |
+
+### 开发流程
+
+1. **创建插件**（优先使用文件夹结构）
+2. **安装依赖**：`install { package: "包名", path: ".foliko/plugins/插件名" }`
+3. **热重载**：`reload_plugins`
+4. **检查加载状态**
+
+### 引入第三方库
+
+**必须先安装依赖，再热重载！**
+
+```javascript
+// .foliko/plugins/my-plugin/index.js
+const { z } = require('zod');
+
+module.exports = function (Plugin) {
+  return class MyPlugin extends Plugin {
+    name = 'my-plugin';
+
+    tools = {
+      fetch_data: {
+        description: '获取远程数据',
+        inputSchema: z.object({
+          url: z.string().describe('API URL'),
+        }),
+        execute: async (args) => {
+          // 安装到插件自己的目录
+          await this._framework.callTool('install', {
+            package: 'axios',
+            path: '.foliko/plugins/my-plugin',
+          });
+
+          // 引入插件目录下的 node_modules
+          const axios = require('.foliko/plugins/my-plugin/node_modules/axios');
+          const response = await axios.get(args.url);
+          return { success: true, data: response.data };
+        },
+      },
+    };
+  };
+};
+```
+
+### 错误处理
+
+```javascript
+onStart(framework) {
+  try {
+    this.tool.register({ ... });
+  } catch (error) {
+    framework.logger.error(`[${this.name}] Failed to register tool: ${error.message}`);
+  }
+}
+
+uninstall(framework) {
+  // 确保清理所有资源
+  this.tool.remove('my_tool');
+  this.extension.remove('my_ext');
+  this.agent.remove('my-agent');
+}
+```
+
+---
+
+## 示例插件
+
+### 完整示例：天气插件
+
+```javascript
+// .foliko/plugins/weather/index.js
+const { z } = require('zod');
+
+module.exports = function (Plugin) {
+  return class WeatherPlugin extends Plugin {
+    constructor() {
+      super();
+      this.name = 'weather';
+      this.version = '1.0.0';
+      this.description = '天气查询插件';
+    }
+
+    tools = {
+      get_weather: {
+        description: '查询指定城市的天气',
+        inputSchema: z.object({
+          city: z.string().describe('城市名称'),
+          units: z.enum(['celsius', 'fahrenheit']).optional().describe('温度单位，默认 celsius'),
+        }),
+        execute: async (args) => {
+          // 这里应该是真实的 API 调用
+          return {
+            city: args.city,
+            temperature: 25,
+            units: args.units || 'celsius',
+            condition: 'Sunny',
+          };
+        },
+      },
+    };
+
+    onStart(framework) {
+      // 注册额外的工具
+      this.tool.register({
+        name: 'get_forecast',
+        description: '获取天气预报',
+        inputSchema: framework.z.object({
+          city: framework.z.string().describe('城市名称'),
+          days: framework.z.number().min(1).max(7).default(3).describe('预报天数'),
+        }),
+        execute: async (args) => {
+          return {
+            city: args.city,
+            forecast: Array.from({ length: args.days }, (_, i) => ({
+              day: i + 1,
+              temp: 20 + Math.floor(Math.random() * 10),
+              condition: ['Sunny', 'Cloudy', 'Rainy'][Math.floor(Math.random() * 3)],
+            })),
+          };
+        },
+      });
+    }
+
+    onStop() {
+      // 清理资源
+    }
+
+    uninstall(framework) {
+      // 完全清理
+    }
+  };
+};
+```
+
+---
+
+## 相关文档
+
+- [扩展系统](./extensions.md) - ext_call、ext_skill 统一调用
+- [Public API](./public-api.md) - 框架公共 API 参考
+- [架构文档](./architecture.md) - 系统架构设计

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "type": "commonjs",

package/src/agent/chat.js

@@ -112,6 +112,9 @@ class AgentChatHandler extends EventEmitter {
     this._toolsTokensCacheVersion = 0;
     this._systemPromptTokensCache = null;
     this._systemPromptTokensCacheKey = null;
+    // 消息 token 缓存（避免重复计算同一条消息）
+    this._messageTokenCache = new Map();
+    this._messageTokenCacheMaxSize = 200;
 
     // ChatQueueManager: 队列管理
     this.queueManager = new ChatQueueManager({
@@ -1028,7 +1031,7 @@ class AgentChatHandler extends EventEmitter {
     const totalTokens = cachedMsgTokens + toolsTokens + systemPromptTokens;
     const limit = this._maxContextTokens * SIMPLE_COMPRESS_TOKEN_RATIO;
 
-    logger.info(`[_prepareSession] BEFORE: messages=${messages.length}, tokens=${totalTokens}/${limit}, threshold=${this._compressionMessageThreshold}`);
+    //gger.info(`[_prepareSession] BEFORE: messages=${messages.length}, tokens=${totalTokens}/${limit}, threshold=${this._compressionMessageThreshold}`);
 
     if (totalTokens > limit || messages.length > this._compressionMessageThreshold) {
       logger.info(
@@ -1117,8 +1120,6 @@ class AgentChatHandler extends EventEmitter {
 
     for (let msgIdx = 0; msgIdx < messages.length; msgIdx++) {
       const msg = messages[msgIdx];
-
-      // ★ assistant 消息：content 数组格式的 tool-call
       if (msg.role === 'assistant' && Array.isArray(msg.content)) {
         for (let itemIdx = 0; itemIdx < msg.content.length; itemIdx++) {
           const item = msg.content[itemIdx];
@@ -1126,58 +1127,31 @@ class AgentChatHandler extends EventEmitter {
           if ((item.type === 'tool-call' || item.type === 'tool-use') && item.toolCallId) {
             const id = item.toolCallId;
             if (firstSeen.has(id)) {
+              // 冲突：生成唯一新 ID（不依赖全局计数器，避免跨调用泄露）
               const newId = `${id}_dup${msgIdx}_${itemIdx}`;
               item.toolCallId = newId;
+              // 同步修改紧随其后的 tool-result
               const renamed = this._renameFollowingToolResult(messages, msgIdx, id, newId);
               fixedCount += 1 + (renamed ? 1 : 0);
+              // 不更新 firstSeen（原始 ID 已被第一次声明占用）
             } else {
               firstSeen.set(id, { msgIdx, itemIdx, kind: 'call' });
             }
           }
         }
-      }
-
-      // ★ assistant 消息：tool_calls 数组格式（OpenAI 格式）
-      if (msg.role === 'assistant' && Array.isArray(msg.tool_calls)) {
-        for (let itemIdx = 0; itemIdx < msg.tool_calls.length; itemIdx++) {
-          const tc = msg.tool_calls[itemIdx];
-          if (!tc || !tc.id) continue;
-          const id = tc.id;
-          if (firstSeen.has(id)) {
-            const newId = `${id}_dup${msgIdx}_${itemIdx}`;
-            tc.id = newId;
-            const renamed = this._renameFollowingToolResult(messages, msgIdx, id, newId);
-            fixedCount += 1 + (renamed ? 1 : 0);
-          } else {
-            firstSeen.set(id, { msgIdx, itemIdx, kind: 'call' });
-          }
-        }
-      }
-
-      // ★ tool 消息：content 数组格式（AI SDK 格式）
-      // 注意：tool-result 与 assistant tool-call 配对使用同一 ID 是正常的，
-      // 此处只记录第一次出现的 ID，不做重命名（重命名由 _renameFollowingToolResult 在上面的 assistant 分支处理）
-      if (msg.role === 'tool' && Array.isArray(msg.content)) {
+      } else if (msg.role === 'tool' && Array.isArray(msg.content)) {
         for (let itemIdx = 0; itemIdx < msg.content.length; itemIdx++) {
           const item = msg.content[itemIdx];
           if (!item) continue;
           if ((item.type === 'tool-result' || item.type === 'tool_result') && item.toolCallId) {
             const id = item.toolCallId;
+            // 记录 tool-result 第一次出现（不与 call 比较，因为可能已被上面的分支处理过）
             if (!firstSeen.has(id)) {
               firstSeen.set(id, { msgIdx, itemIdx, kind: 'result' });
             }
           }
         }
       }
-
-      // ★ tool 消息：tool_call_id 字符串格式（OpenAI 格式）
-      // 同样只记录第一次出现，不做重命名
-      if (msg.role === 'tool' && msg.tool_call_id && !Array.isArray(msg.content)) {
-        const id = msg.tool_call_id;
-        if (!firstSeen.has(id)) {
-          firstSeen.set(id, { msgIdx, itemIdx: -1, kind: 'result' });
-        }
-      }
     }
     return fixedCount;
   }
@@ -1191,22 +1165,14 @@ class AgentChatHandler extends EventEmitter {
     for (let i = afterMsgIdx + 1; i < messages.length; i++) {
       const m = messages[i];
       if (m.role === 'assistant') return false;
-      if (m.role === 'tool') {
-        // AI SDK 数组格式
-        if (Array.isArray(m.content)) {
-          for (const item of m.content) {
-            if (!item) continue;
-            if ((item.type === 'tool-result' || item.type === 'tool_result') && item.toolCallId === oldId) {
-              item.toolCallId = newId;
-              return true;
-            }
+      if (m.role === 'tool' && Array.isArray(m.content)) {
+        for (const item of m.content) {
+          if (!item) continue;
+          if ((item.type === 'tool-result' || item.type === 'tool_result') && item.toolCallId === oldId) {
+            item.toolCallId = newId;
+            return true;
           }
         }
-        // OpenAI 字符串格式
-        if (m.tool_call_id === oldId) {
-          m.tool_call_id = newId;
-          return true;
-        }
       }
     }
     return false;
@@ -1397,11 +1363,10 @@ class AgentChatHandler extends EventEmitter {
    * @private
    */
   _createPrepareStep() {
-    const self = this;
     return async ({ stepNumber, messages: inputMessages }) => {
       try {
-        const tokenCount = self._countMessagesTokens(inputMessages);
-        const tokenLimit = self._maxContextTokens * SMART_COMPRESS_TOKEN_RATIO;
+        const tokenCount = this._countMessagesTokens(inputMessages);
+        const tokenLimit = this._maxContextTokens * SMART_COMPRESS_TOKEN_RATIO;
 
         // 超过限制时，保留三分之一的消息
         if (tokenCount > tokenLimit) {
@@ -1419,8 +1384,8 @@ class AgentChatHandler extends EventEmitter {
         //   所以不再需要 _stripStaleToolCalls 提前清理
 
         // 单次遍历完成：修复 invalid tool-call + 修复错误 text + 重映射历史 ID
-        const repairedCount = self._repairInvalidToolCallsInMessages(inputMessages);
-        self._repairAndPrefixHistoricalIds(inputMessages);
+        const repairedCount = this._repairInvalidToolCallsInMessages(inputMessages);
+        this._repairAndPrefixHistoricalIds(inputMessages);
 
         // ★ 防御性 sanitize：确保所有 message 符合 AI SDK ModelMessage[] schema
         // 每次 LLM step 前都跑一次（messages 数组里可能有 AI SDK 上一步加进来的）

package/src/agent/tool-loop.js

@@ -183,13 +183,6 @@ class ToolLoop extends EventEmitter {
     const api = [];
     if (systemPrompt) api.push({ role: 'system', content: systemPrompt });
 
-    // ★ 单遍扫描：跟踪"已遇到过的 assistant 中的 tool_call_id"，
-    //    tool-result 只能匹配其之前的 assistant，不能匹配其之后的。
-    //    防止历史会话中的 orphaned tool-result 被错误地保留。
-    const seenAssistantToolCallIds = new Set();
-    // ★ 追踪已输出的 tool_call_id，防止重复
-    const seenOutputToolCallIds = new Set();
-
     for (const msg of messages) {
       if (msg.role === 'system') {
         api.push({ role: 'system', content: typeof msg.content === 'string' ? msg.content : '' });
@@ -201,40 +194,13 @@ class ToolLoop extends EventEmitter {
           api.push({ role: 'user', content: text || '' });
         }
       } else if (msg.role === 'assistant') {
-        // ★ 先收集此 assistant 消息中的 tool_call_id（推入 api 前更新 seen 集合）
-        const currentToolCallIds = new Set();
-        if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
-          for (const tc of msg.tool_calls) {
-            if (tc.id) currentToolCallIds.add(tc.id);
-          }
-        }
-        if (Array.isArray(msg.content)) {
-          for (const part of msg.content) {
-            if (part && (part.type === 'tool-call' || part.type === 'tool-use') && part.toolCallId) {
-              currentToolCallIds.add(part.toolCallId);
-            }
-          }
-        }
-        // ★ 将这些 ID 加入 seenAssistantToolCallIds，之后的 tool-result 才能匹配
-        for (const id of currentToolCallIds) {
-          seenAssistantToolCallIds.add(id);
-        }
-
-        // ★ 检测是否有 reasoning 内容（thinking mode 必须携带）
-        const hasReasoningInContent = Array.isArray(msg.content) && msg.content.some(p => p && p.type === 'reasoning');
-        const hasReasoningTopLevel = msg.reasoning_content || msg.reasoning;
+        // ★ 提取 text + tool_calls（兼容 content=string、content=array、顶层 tool_calls 三种格式）
+        let text = '';
+        const toolCalls = [];
 
         if (typeof msg.content === 'string') {
-          if (msg.tool_calls && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
-            // thinking mode 下，无 reasoning 则自动补 placeholder
-            const reasonVal = hasReasoningTopLevel || (this._thinkingMode ? '...' : '');
-            api.push({ role: 'assistant', content: msg.content || null, tool_calls: msg.tool_calls, ...(reasonVal ? { reasoning_content: reasonVal } : {}) });
-          } else {
-            api.push({ role: 'assistant', content: msg.content });
-          }
+          text = msg.content;
         } else if (Array.isArray(msg.content)) {
-          let text = '';
-          const toolCalls = [];
           for (const part of msg.content) {
             if (!part) continue;
             if (part.type === 'text') text += part.text;
@@ -249,50 +215,39 @@ class ToolLoop extends EventEmitter {
               });
             }
           }
+        }
 
-          if (toolCalls.length > 0) {
-            const reasonVal = hasReasoningTopLevel || (this._thinkingMode ? '...' : '');
-            api.push({ role: 'assistant', content: text || null, tool_calls: toolCalls, ...(reasonVal ? { reasoning_content: reasonVal } : {}) });
-          } else {
-            api.push({ role: 'assistant', content: text });
+        // ★ 合并顶层 tool_calls（OpenAI 格式，来自 session 文件）
+        const existingIds = new Set(toolCalls.map(tc => tc.id));
+        if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
+          for (const tc of msg.tool_calls) {
+            if (!existingIds.has(tc.id)) toolCalls.push(tc);
+            existingIds.add(tc.id);
           }
+        }
+
+        if (toolCalls.length > 0) {
+          // ★ 核心：thinking mode 下，所有带 tool_calls 的消息都必须有 reasoning_content
+          //   无条件注入，不依赖 hasReasoningTopLevel 检测
+          const reasonVal = msg.reasoning_content || msg.reasoning || (this._thinkingMode ? '...' : '');
+          api.push({ role: 'assistant', content: text || null, tool_calls: toolCalls, ...(reasonVal ? { reasoning_content: reasonVal } : {}) });
         } else {
-          api.push({ role: 'assistant', content: String(msg.content ?? '') });
+          api.push({ role: 'assistant', content: text || '' });
         }
       } else if (msg.role === 'tool') {
         if (Array.isArray(msg.content)) {
           for (const part of msg.content) {
             if (!part || (part.type !== 'tool-result' && part.type !== 'tool_result')) continue;
-            const id = part.toolCallId;
-            // ★ 过滤：tool-result 必须匹配已出现过的 assistant 中的 tool_call_id
-            if (!seenAssistantToolCallIds.has(id)) {
-              log.warn(`[ToolLoop] 过滤无效 tool-result(顺序/无匹配): toolCallId=${id}`);
-              continue;
-            }
-            // ★ 过滤重复的 tool_call_id（同一 ID 多次出现）
-            if (seenOutputToolCallIds.has(id)) {
-              log.warn(`[ToolLoop] 跳过重复 tool-result: toolCallId=${id}`);
-              continue;
-            }
-            seenOutputToolCallIds.add(id);
             const output = part.output;
             let content;
             if (output?.type === 'text') content = output.value;
             else if (output?.type === 'json') content = JSON.stringify(output.value);
             else content = typeof output === 'string' ? output : JSON.stringify(output);
-            api.push({ role: 'tool', tool_call_id: id, content });
+            api.push({ role: 'tool', tool_call_id: part.toolCallId, content });
           }
         } else if (msg.tool_call_id && typeof msg.content === 'string') {
-          const id = msg.tool_call_id;
-          // ★ 过滤：tool-result 必须匹配已出现过的 assistant 中的 tool_call_id
-          if (!seenAssistantToolCallIds.has(id)) {
-            log.warn(`[ToolLoop] 过滤无效 tool-result(顺序/无匹配): tool_call_id=${id}`);
-          } else if (seenOutputToolCallIds.has(id)) {
-            log.warn(`[ToolLoop] 跳过重复 tool-result: tool_call_id=${id}`);
-          } else {
-            seenOutputToolCallIds.add(id);
-            api.push(msg);
-          }
+          // 已经是 OpenAI 格式（streaming 完成后的消息）
+          api.push(msg);
         }
       }
     }
@@ -494,12 +449,6 @@ class ToolLoop extends EventEmitter {
 
       let response;
       try {
-        // ★ DEBUG: 记录所有 tool 消息的 ID
-        for (const m of apiMessages) {
-          if (m.role === 'tool') {
-            log.warn(`[ToolLoop] [DEBUG] 发送 tool-result: tool_call_id=${m.tool_call_id}, content_len=${(m.content||'').length}`);
-          }
-        }
         response = await client.chat.completions.create({
           model,
           messages: apiMessages,
@@ -597,13 +546,6 @@ class ToolLoop extends EventEmitter {
 
       let stream;
       try {
-        // ★ DEBUG: 记录所有 tool 消息的 ID
-        for (const m of apiMessages) {
-          if (m.role === 'tool') {
-            log.warn(`[ToolLoop] [DEBUG] 发送 tool-result: tool_call_id=${m.tool_call_id}, content_len=${(m.content||'').length}`);
-          }
-        }
-
         stream = await client.chat.completions.create({
           model,
           messages: apiMessages,

package/src/common/constants.js

@@ -24,7 +24,7 @@ const DEFAULT_MAX_OUTPUT_TOKENS = 8192;
 const DEFAULT_TEMPERATURE = 0.3;
 
 /** 默认 Max Steps（工具调用最大轮数） */
-const DEFAULT_MAX_STEPS = 1000;
+const DEFAULT_MAX_STEPS = 20;
 
 /** 需要禁用 temperature 的 thinking mode 模型列表 */
 const THINKING_MODELS = [
@@ -54,7 +54,7 @@ const DEFAULT_MAX_MESSAGES_PER_SESSION = 1000;
 const KEEP_RECENT_MESSAGES = 20;
 
 /** 压缩消息数量阈值 */
-const COMPRESSION_MESSAGE_THRESHOLD = 120;
+const COMPRESSION_MESSAGE_THRESHOLD = 150;
 
 /** 智能压缩启用 */
 const ENABLE_SMART_COMPRESS = true;

package/src/llm/tokens.js

@@ -5,6 +5,16 @@
  * Ported from pi's compaction/compaction.ts with enhancements
  */
 
+// 全局 token 缓存（避免重复计算相同内容）
+const _tokenCache = new Map();
+const _TOKEN_CACHE_MAX_SIZE = 500;
+
+function _getCacheKey(message) {
+  if (message.id) return message.id;
+  if (message.role === 'tool') return `tool:${message.tool_call_id || message.toolName}`;
+  return `${message.role}:${JSON.stringify(message.content || '').slice(0, 100)}`;
+}
+
 function encode(text, bytesPerToken = 4) {
   if (!text) return 0;
   const bytes = Buffer.byteLength(String(text), 'utf8');
@@ -26,6 +36,12 @@ function safeJsonStringify(value) {
 }
 
 function estimateTokens(message) {
+  // 性能优化：使用缓存避免重复计算
+  const cacheKey = _getCacheKey(message);
+  if (_tokenCache.has(cacheKey)) {
+    return _tokenCache.get(cacheKey);
+  }
+
   let chars = 0;
 
   switch (message.role) {
@@ -40,7 +56,9 @@ function estimateTokens(message) {
           }
         }
       }
-      return Math.ceil(chars / 4);
+      const result = Math.ceil(chars / 4);
+      _updateCache(cacheKey, result);
+      return result;
     }
     case 'assistant': {
       const assistant = message;
@@ -53,7 +71,9 @@ function estimateTokens(message) {
           chars += block.name.length + safeJsonStringify(block.arguments).length;
         }
       }
-      return Math.ceil(chars / 4);
+      const result = Math.ceil(chars / 4);
+      _updateCache(cacheKey, result);
+      return result;
     }
     case 'custom':
     case 'toolResult': {
@@ -69,22 +89,40 @@ function estimateTokens(message) {
           }
         }
       }
-      return Math.ceil(chars / 4);
+      const result = Math.ceil(chars / 4);
+      _updateCache(cacheKey, result);
+      return result;
     }
     case 'bashExecution': {
       chars = message.command.length + (message.output?.length || 0);
-      return Math.ceil(chars / 4);
+      const result = Math.ceil(chars / 4);
+      _updateCache(cacheKey, result);
+      return result;
     }
     case 'branchSummary':
     case 'compactionSummary': {
       chars = message.summary.length;
-      return Math.ceil(chars / 4);
+      const result = Math.ceil(chars / 4);
+      _updateCache(cacheKey, result);
+      return result;
     }
   }
 
   return 0;
 }
 
+function _updateCache(key, value) {
+  if (_tokenCache.size >= _TOKEN_CACHE_MAX_SIZE) {
+    // 删除最旧的 20%
+    const keysToDelete = Math.floor(_TOKEN_CACHE_MAX_SIZE * 0.2);
+    const iterator = _tokenCache.keys();
+    for (let i = 0; i < keysToDelete; i++) {
+      _tokenCache.delete(iterator.next().value);
+    }
+  }
+  _tokenCache.set(key, value);
+}
+
 function calculateContextTokens(usage) {
   return usage.totalTokens || (usage.input || 0) + (usage.output || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
 }

package/src/session/session.js

@@ -123,6 +123,11 @@ class SessionManager {
   _loadEntriesFromFile(filePath) {
     if (!fs.existsSync(filePath)) return [];
 
+    // 性能优化：使用流式读取大文件，减少内存占用
+    const stats = fs.statSync(filePath);
+    if (stats.size > 5 * 1024 * 1024) { // > 5MB 使用流
+      return this._loadEntriesFromFileStream(filePath);
+    }
     const content = fs.readFileSync(filePath, 'utf8');
     const entries = [];
     const lines = content.trim().split('\n');
@@ -152,6 +157,28 @@ class SessionManager {
     return entries;
   }
 
+  async _loadEntriesFromFileStream(filePath) {
+    // 性能优化：流式读取大文件
+    const entries = [];
+    const seenIds = new Set();
+    const readline = require('readline');
+    const rl = readline.createInterface({
+      input: fs.createReadStream(filePath),
+      crlfDelay: Infinity
+    });
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+      try {
+        const entry = JSON.parse(line);
+        if (!entry || typeof entry !== 'object') continue;
+        if (entry.id && seenIds.has(entry.id)) continue;
+        if (entry.id) seenIds.add(entry.id);
+        entries.push(entry);
+      } catch { /* skip */ }
+    }
+    return entries;
+  }
+
   _buildIndex() {
     this.byId.clear();
     this.labelsById.clear();
@@ -175,7 +202,8 @@ class SessionManager {
 
   _rewriteFile() {
     if (!this.persist || !this.sessionFile) return;
-    const content = `${this.fileEntries.map(e => JSON.stringify(e)).join('\n')}\n`;
+    // 性能优化：单次写入代替多次追加
+    const content = this.fileEntries.map(e => JSON.stringify(e)).join('\n') + '\n';
     fs.writeFileSync(this.sessionFile, content);
   }
 
@@ -190,10 +218,10 @@ class SessionManager {
       return;
     }
 
+    // 性能优化：使用批量写入代替多次追加
     if (!this.flushed) {
-      for (const e of this.fileEntries) {
-        fs.appendFileSync(this.sessionFile, `${JSON.stringify(e)}\n`);
-      }
+      const batch = this.fileEntries.map(e => `${JSON.stringify(e)}\n`).join('');
+      fs.writeFileSync(this.sessionFile, batch);
       this.flushed = true;
     } else {
       fs.appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);

package/src/storage/jsonl.js

@@ -136,7 +136,8 @@ class JsonlSessionStorage {
   }
 
   static async _loadJsonlStorage(fsModule, filePath) {
-    const content = fsModule.readFileSync(filePath, 'utf-8');
+    // 性能优化：使用异步读取，避免阻塞事件循环
+    const content = await fsModule.promises.readFile(filePath, 'utf-8');
     const lines = content.split('\n').filter(line => line.trim());
     if (lines.length === 0) {
       throw invalidSession(filePath, 'missing session header');
@@ -195,7 +196,7 @@ class JsonlSessionStorage {
       timestamp: new Date().toISOString(),
       targetId: leafId
     };
-    fs.appendFileSync(this.filePath, JSON.stringify(entry) + '\n');
+    await this.fs.promises.appendFile(this.filePath, JSON.stringify(entry) + '\n');
     this.entries.push(entry);
     this.byId.set(entry.id, entry);
     this.currentLeafId = leafId;
@@ -206,7 +207,8 @@ class JsonlSessionStorage {
   }
 
   async appendEntry(entry) {
-    fs.appendFileSync(this.filePath, JSON.stringify(entry) + '\n');
+    // 性能优化：使用异步追加，减少阻塞时间
+    await this.fs.promises.appendFile(this.filePath, JSON.stringify(entry) + '\n');
     this.entries.push(entry);
     this.byId.set(entry.id, entry);
     updateLabelCache(this.labelsById, entry);

package/tests/core/tool-loop.test.js

@@ -59,13 +59,14 @@ describe('ToolLoop._buildApiMessages 格式转换', () => {
     expect(api[3].content).toBe('{"data":"ok"}');
   });
 
-  it('tool 消息无对应 assistant 时被过滤（防止 orphaned tool-result）', () => {
+  it('tool 消息已经用 OpenAI 格式时保持', () => {
     const api = loop._buildApiMessages([
       { role: 'tool', tool_call_id: 'c1', content: 'done' },
     ], 'system prompt');
-    // orphaned tool-result 被过滤，只有 system 消息
-    expect(api).toHaveLength(1);
+    // 已经符合 OpenAI 格式的直接保留
     expect(api[0].role).toBe('system');
+    expect(api[1].role).toBe('tool');
+    expect(api[1].tool_call_id).toBe('c1');
   });
 
   it('systemPrompt 为空时不加 system 消息', () => {