foliko 2.0.30 → 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.30",
+  "version": "2.0.31",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "type": "commonjs",

package/src/agent/tool-loop.js

@@ -194,21 +194,13 @@ class ToolLoop extends EventEmitter {
           api.push({ role: 'user', content: text || '' });
         }
       } else if (msg.role === 'assistant') {
-        // ★ 检测是否有 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;
@@ -223,15 +215,24 @@ 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)) {