my-ai-chat-framework 2.7.0 → 3.0.0

package/docs/DEVELOPER.md

@@ -0,0 +1,479 @@
+# 开发者文档
+
+> 版本 2.7.0 | 2026-06-05
+
+---
+
+## 架构
+
+```
+ChatService (核心)
+  ├── config        — 全部配置（model、apiKey、capabilities…）
+  ├── messages      — MessageStore 实例（对话历史）
+  ├── systemPrompts — SystemPromptStore 实例（可开关的 system 提示词）
+  ├── _adapter      — 当前适配器（openaiAdapter 等）
+  ├── _abortController — 当前请求的中断控制器
+  └── _isGenerating — 是否正在生成中
+
+插件（通过 chat.use() 安装）
+  ├── openaiAdapter         — HTTP 请求 + 流式解析
+  ├── toolCallingPlugin     — 工具调用循环
+  └── modelRegistryPlugin   — 模型能力表自动同步
+
+工具层
+  ├── MessageFormatter  — 消息格式转换（内置 openai，可注册自定义）
+  ├── EventEmitter      — 发布/订阅（ChatService 继承它）
+  └── Errors            — APIError / NetworkError / ConfigurationError / ParsingError
+```
+
+---
+
+## 配置
+
+配置按**归属分层**：谁消费，谁声明。内置与自定义插件走同一条路径。
+
+| 层 | 内容 | 归谁管 |
+|----|------|--------|
+| 运输层 | `apiKey` / `baseUrl` / `apiUrl` / `path` / `headers` | 适配器工厂 `createOpenAIAdapter(opts)` |
+| 请求层 | `model` / `temperature` / `maxTokens` / `modelParams.*` / `messageFormat` / `resolveImage` | 会话默认 + 请求级覆盖 |
+| 会话层 | `system` / `retry` / `ephemeralContinue` | `new ChatService({...})` + `updateConfig` |
+| 插件自有 | `toolTimeout` / `maxIterations` / `models` 等 | 各插件工厂 options |
+
+### 归属模式（自由）
+
+```javascript
+import { ChatService, createOpenAIAdapter, createToolCallingPlugin, createModelRegistryPlugin } from 'my-ai-chat-framework';
+
+const adapter = createOpenAIAdapter({
+  apiKey: 'sk-xxxx',
+  baseUrl: 'https://api.deepseek.com',
+  modelParams: { temperature: 0.8, maxTokens: 2000 }   // 请求默认参数
+});
+
+const chat = new ChatService({
+  adapter,                    // 构造时注入适配器（等价于 chat.use(adapter)）
+  model: 'deepseek-chat',     // 会话默认 model
+  system: '你是猫娘',          // 自动同步到 systemPrompts
+  retry: { maxRetries: 2, retryDelay: 1000 }
+});
+
+chat.use(createToolCallingPlugin({ timeout: 30000 }));       // 工具插件自带配置
+chat.use(createModelRegistryPlugin({ models: { 'my-model': { reasoning: true } } }));
+
+// 请求级覆盖：只对本次请求生效
+await chat.send('你好', { temperature: 0.2, model: 'deepseek-reasoner' });
+```
+
+### 平铺兼容写法（简单模式）
+
+```javascript
+// 运输层/请求层字段在构造时平铺传入，内部路由给内置 openaiAdapter
+const chat = new ChatService({
+  apiKey: 'sk-xxxx',
+  baseUrl: 'https://api.deepseek.com',
+  model: 'deepseek-chat',
+  modelParams: { temperature: 0.8, maxTokens: 2000 }
+});
+chat.use(openaiAdapter);      // 无状态单例，配置从 chat.config 读取
+```
+
+### 合并优先级
+
+```
+适配器默认(getRequestDefaults) ← 会话配置(this.config) ← 本次覆盖(params)
+```
+
+`modelParams` 深层合并；平铺便捷键（`temperature` / `maxTokens` / `reasoningEffort`）自动折叠进 `modelParams`。
+
+### 插件配置归属
+
+- 插件 options 在**工厂创建时**传入：`createXxxPlugin(opts)`
+- 也支持安装时传入：`chat.use(plugin, opts)`，合并进 `_options`
+- **推荐用工厂**：模块级单例（`openaiAdapter` / `toolCallingPlugin` / `modelRegistryPlugin`）装到多个 ChatService 实例会互相覆盖，仅作兼容保留
+
+---
+
+## 配置校验
+
+- 构造器：`model` 必填（`config.model` 或 `config.modelParams.model`）；`temperature` 0~2；`maxTokens` 正整数
+- `updateConfig`：只接受会话层字段（`model` / `temperature` / `maxTokens` / `modelParams` / `system` / `retry` / `ephemeralContinue`），非白名单字段或非法值抛 `ConfigurationError`，与构造器校验一致
+- 请求级覆盖（`chat.send(x, params)`）不做运行时校验——API 会返回错误，适合调试
+
+---
+
+## API
+
+### ChatService
+
+| 方法 | 说明 |
+|------|------|
+| `chat.send(input, params?)` | 发送消息，返回助手消息。`params` 为请求级覆盖（仅本次生效）。AbortError 内部捕获，不向外抛 |
+| `chat.stream(input, params?, onProgress, onDone)` | 流式发送。兼容旧签名 `stream(input, onProgress, onDone)`。AbortError 内部捕获 |
+| `chat.sendExisting(params?)` | 重发当前消息（不加用户消息）。AbortError 内部捕获 |
+| `chat.sendExistingStream(params?, onProgress, onDone)` | 流式重发。兼容旧签名。AbortError 内部捕获 |
+| `chat.continueLast()` | 前缀续写：从最后一条 assistant/ephemeral 续写并拼回原消息，续写后自动转正。AbortError 内部捕获，返回 target |
+| `chat.continueLastStream(onProgress, onDone)` | 流式前缀续写。AbortError 内部捕获，返回 target |
+| `chat.abort()` | 中断当前请求，触发 `aborted` 事件 |
+| `chat.use(plugin, options?)` | 安装插件，options 透传给 `plugin.install(chat, options)` |
+| `chat.updateConfig(partial)` | 更新会话层配置（白名单+校验），触发 `config-updated` |
+| `chat.registerTool(name, desc, fn, params?)` | 注册工具（需 toolCallingPlugin） |
+| `chat.registerModel(name, caps)` | 注册/覆盖模型能力（需 modelRegistryPlugin） |
+
+### 属性
+
+| 属性 | 说明 |
+|------|------|
+| `chat.messages` | MessageStore 实例 |
+| `chat.systemPrompts` | SystemPromptStore 实例 |
+| `chat.config` | 当前配置对象（可直接读） |
+| `chat.isGenerating` | 是否正在生成（只读） |
+
+### SystemPromptStore
+
+| 方法 | 说明 |
+|------|------|
+| `add(content, enabled?)` | 添加 system prompt |
+| `remove(index)` | 删除 |
+| `toggle(index)` | 切换启用/禁用 |
+| `update(index, content)` | 修改内容 |
+| `set(content)` | 清空并用一条替换 |
+| `getEnabled()` | 返回启用的 `[{role:'system',content}]` |
+| `getAll()` | 返回全部（含 enabled 状态） |
+
+### MessageStore
+
+| 方法 | 说明 |
+|------|------|
+| `add(msg)` | 添加消息 |
+| `addUser(content)` / `addAssistant(content)` / `addSystem(content)` / `addTool(content, toolCallId)` | 快捷方法 |
+| `addOnceAssistant(content, options?)` | 一次性引导消息：默认 `_ephemeral: true` + `prefix: true`，options 可传 `{ reasoningContent, prefix }` |
+| `getAll()` | 返回浅拷贝 |
+| `getLast()` | 最后一条（或 null） |
+| `clear()` | 清空 |
+| `undoToLastAssistant()` | 撤回最后 assistant 之后的消息 |
+| `undoToPreviousUser(id)` | 撤回到指定消息之前的最近 user：删除该 user 之后到该消息（含）之间的消息（适用于重发） |
+
+消息格式：
+
+```javascript
+{
+  id: 'msg_1716300000_1',
+  role: 'user' | 'assistant' | 'system' | 'tool',
+  content: string,
+  images?: ['https://...'],
+  toolCalls?: [{ id, type:'function', function:{name,arguments} }],
+  toolCallId?: string,
+  reasoningContent?: string,
+  // 流式标记（自动添加）
+  _streaming?: true,      // 正在生成
+  prefix?: boolean,       // 前缀续写标记
+  _ephemeral?: boolean,   // 临时消息：仅底部连续时参与请求，续写后转正
+  _complete?: boolean,    // 流式是否完成（false=未完成/中断，true=正常结束），非流式无此字段
+  timestamp: 1716300000,
+  metadata?: any
+}
+```
+
+---
+
+## 事件
+
+| 事件 | 数据 | 触发时机 |
+|------|------|---------|
+| `sending` | `{ addUser, userInput, timestamp }` | 请求发送前 |
+| `stream-progress` | chunk 对象 | 每个流式块 |
+| `message` | 助手消息对象 | 完整消息收到 |
+| `aborted` | `{ timestamp }` | 用户调用 abort() 中断请求 |
+| `error` | `{ error, timestamp }` | 请求失败（AbortError 不触发此事件） |
+| `retry` | `{ attempt, maxRetries, lastError }` | 网络错误重试 |
+| `config-updated` | `{ changes, timestamp }` | config 更新 |
+| `tool-success` | `{ toolName, result, toolCallId }` | 工具执行成功 |
+| `tool-error` | `{ toolName, error, toolCallId, stage }` | 工具执行失败（stage: parse / lookup / execute / timeout） |
+| `beforeRequest` | `{ messages, config, options }` | 请求发送前，可修改 messages/config（见下方钩子说明） |
+
+```javascript
+// 状态管理示例：用事件驱动 UI，不需要手动 catch
+chat.on('sending', () => { /* 按钮切发送中 */ });
+chat.on('message', () => { /* 按钮恢复 idle */ });
+chat.on('aborted', () => { /* 按钮恢复 idle */ });
+chat.on('error', ({ error }) => { /* 按钮恢复 idle + 显示错误 */ });
+```
+
+```javascript
+chat.on('error', ({ error }) => {
+  if (error instanceof APIError)     console.error('API错误', error.statusCode);
+  if (error instanceof NetworkError)  console.error('网络错误');
+  if (error instanceof ConfigurationError) console.error('配置错误');
+});
+```
+
+### beforeRequest 钩子
+
+在 adapter 构建请求体之前触发，可修改 messages 或 config。所有请求（send / stream / continueLast / continueLastStream）都会触发。
+
+```javascript
+chat._hooks.on('beforeRequest', async ({ messages, config, options }) => {
+  // messages — MessageStore 实例，可直接 add/update/clear
+  // config   — 当前配置对象，可修改（仅本次请求生效）
+  // options  — 本次请求的参数
+});
+```
+
+`options` 字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `addUser` | boolean | `true` = 普通发送（send/stream），`false` = 续写/重发 |
+| `isStream` | boolean | 是否流式 |
+| `userInput` | string\|object | 用户输入（续写时为 undefined） |
+| `mergeToEntry` | string\|undefined | 续写目标 id，有值 = 续写模式 |
+| `onProgress` | function | 流式进度回调 |
+| `onDone` | function | 流式结束回调 |
+
+**区分普通发送和续写**：
+
+```javascript
+chat._hooks.on('beforeRequest', async ({ messages, options }) => {
+  // 续写时不注入，避免重复
+  if (options.mergeToEntry) return;
+
+  // 普通发送时注入 ephemeral 引导
+  messages.add({
+    role: 'assistant', content: '',
+    _ephemeral: true, prefix: true
+  });
+});
+```
+
+---
+
+## 临时消息（Ephemeral）
+
+标记 `_ephemeral: true` 的消息**仅底部连续时参与请求**，其余位置自动被 MessageFormatter 过滤。
+续写后自动转正（`delete _ephemeral`），变为永久消息。
+
+```javascript
+// 注入临时引导消息（仅本次请求生效）
+chat._hooks.on('beforeRequest', async ({ messages }) => {
+  messages.add({
+    role: 'assistant', content: '让我分析一下：',
+    reasoningContent: '我需要逐步推理',
+    _ephemeral: true, prefix: true
+  });
+});
+
+// 续写后自动转正
+await chat.continueLast();
+// 该消息的 _ephemeral 已被清除，成为永久 assistant
+```
+
+### 自动续写（ephemeralContinue）
+
+`config.ephemeralContinue: true` 启用后，当底部消息带有 `prefix: true` 且角色为 `assistant` 或 `_ephemeral` 时，
+框架自动将其设为续写目标（`mergeToEntry`），结果拼回原消息而非追加为新消息。
+
+适用于 ephemeral 注入引导场景——钩子注入一条带 prefix 的引导消息后，API 的回复直接合并回该消息：
+
+```javascript
+const chat = new ChatService({
+  apiKey: 'sk-xxx',
+  model: 'deepseek-chat',
+  ephemeralContinue: true
+});
+
+chat._hooks.on('beforeRequest', async ({ messages }) => {
+  messages.addOnceAssistant('让我分析一下', { reasoningContent: '逐步推理' });
+});
+```
+
+启用后每次正常请求（send/stream）都会检测底部 prefix 消息，不影响已有语义。
+不启用时 `prefix` 仅透传给 API，结果作为新消息追加。
+
+---
+
+## MessageFormatter
+
+```javascript
+import { MessageFormatter } from 'my-ai-chat-framework';
+
+// 注册 Anthropic 格式
+MessageFormatter.register('anthropic', ({ messages, systemPrompts, capabilities }) => {
+  const result = [];
+  // Anthropic 格式：user/assistant 交替
+  for (const msg of messages) {
+    if (msg.role === 'user' || msg.role === 'assistant') {
+      result.push({ role: msg.role, content: msg.content });
+    }
+  }
+  return result;
+});
+
+// 使用
+const chat = new ChatService({
+  messageFormat: 'anthropic',  // 指定格式
+  // ...
+});
+
+// 列出所有格式
+console.log(MessageFormatter.listFormats()); // ['openai', 'anthropic']
+```
+
+---
+
+## 前缀续写
+
+调用 `chat.continueLast()` 从最后一条 assistant 消息续写——
+模型直接从原内容末尾接续，结果拼回原消息（不新增消息）。
+
+> 部分服务商需 baseUrl 加 `/beta` 开启该功能（如 DeepSeek）。
+
+```javascript
+// 中断后直接续写（流式标记 _complete 为 false）
+chat.abort();
+const msg = await chat.continueLast();
+// msg.content 已是原始 + 续写拼接，_complete 变为 true
+
+// 已完成的对话也可以续写（但通常没必要）
+await chat.continueLast();
+```
+
+---
+
+## 流式消息与 Vue 渲染
+
+框架自动在流式开始时 push 占位消息到 `messages`，并实时更新 content：
+
+```vue
+<template>
+  <div v-for="msg in messages" :key="msg.id">
+    <div v-if="msg.role === 'user'">{{ msg.content }}</div>
+    <div v-else-if="msg.role === 'assistant'" :class="{ streaming: msg._streaming }">
+      {{ msg.content }}
+      <span v-if="msg._complete === false">▊</span>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+const messages = ref([]);
+
+chat.on('stream-progress', (chunk) => {
+  // 不需要手动 push，messages 已实时更新
+  // 只需触发 Vue 响应
+});
+</script>
+```
+
+---
+
+## 自定义适配器
+
+适配器契约（`config` 为合并后的请求参数，运输层可从实例自持或 `config` 读取）：
+
+```javascript
+export const myAdapter = {
+  name: 'custom',
+  install(chat, options = {}) { chat.setAdapter(this); },
+
+  // 可选：工厂实例可提供的"请求默认参数"（运输键除外），
+  // 会话层会按 适配器默认 ← 会话配置 ← 本次覆盖 合并
+  getRequestDefaults() { return { modelParams: { temperature: 0.7 } }; },
+
+  buildRequest(messages, config, systemPrompts) {
+    return MessageFormatter.format({
+      messages, systemPrompts,
+      capabilities: config.capabilities,
+      format: config.messageFormat || 'openai'
+    });
+  },
+
+  async send(requestBody, config, options) { /* ... */ },
+
+  // stream 只负责解析 SSE：onProgress 传累积快照 { content, reasoningContent, toolCalls }，
+  // onDone 传最终消息。占位消息的创建/更新由 ChatService 管理，adapter 不碰
+  async stream(requestBody, config, onProgress, onDone, options) {
+    // ...解析 chunk，accumulated 累积后调用 onProgress({ ...accumulated })
+    // 结束时调用 onDone(finalMessage)
+  },
+
+  parseResponse(apiResponse) { /* ... */ },
+};
+```
+
+---
+
+## 完整示例
+
+```javascript
+import {
+  ChatService, openaiAdapter, toolCallingPlugin, modelRegistryPlugin,
+  APIError, NetworkError
+} from 'my-ai-chat-framework';
+
+const chat = new ChatService({
+  apiKey: 'sk-xxxx',
+  model: 'deepseek-chat',
+  system: '你是乐于助人的AI助手',
+  retry: { maxRetries: 2 },
+  toolTimeout: 10000,
+});
+
+chat.use(openaiAdapter);
+chat.use(modelRegistryPlugin);
+chat.use(toolCallingPlugin);
+
+chat.registerTool('get_weather', '查询天气', async (args) => {
+  return `${args.city}: 22°C, 晴`;
+}, { city: { type: 'string', description: '城市', required: true } });
+
+chat.on('message', msg => console.log('AI:', msg.content));
+chat.on('error', ({ error }) => console.error(error.message));
+
+// 基础对话
+await chat.send('你好');
+
+// 工具调用
+await chat.send('北京天气？');
+
+// 手动中断
+setTimeout(() => chat.abort(), 3000);
+await chat.stream('讲个长故事', ...);
+
+// 前缀续写（从最后一条 assistant 续写）
+await chat.continueLast();
+// 结果拼回原消息，不新增消息
+```
+
+---
+
+## 扩展：写一个"车间"（v3.0）
+
+核心流程已是一辆小车（ctx）依次开过车间。想加一个新功能 = 注册一个车间，核心代码一行不用改。
+
+```javascript
+const chat = new ChatService({ adapter, model: 'deepseek-chat' });
+
+// 发送前：给每句话注入角色卡（ctx.messages 是 MessageStore，可用 add / addUser …）
+chat.pipe({
+  name: '角色卡注入',
+  phase: 'beforeSend',            // 默认即 beforeSend
+  async run(ctx) {
+    ctx.messages.add({ role: 'system', content: '你是傲娇霸总' });
+  }
+});
+
+// 发送后：把回复打上时间戳（ctx.result 可改，send() 的返回值会跟着变）
+chat.pipe({
+  name: '回复打标',
+  phase: 'afterSend',
+  run(ctx) {
+    if (ctx.result?.content) ctx.result.content += '（来自' + new Date().toLocaleTimeString() + '）';
+  }
+});
+
+// 移除车间
+chat.unpipe('角色卡注入');
+```
+
+车间即"同级功能"：tool-calling / model-registry 本身现在就是车间（见 src/plugins/）。ctx 的全部字段见 ChatService.js 顶部 @typedef PipelineContext。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-ai-chat-framework",
-  "version": "2.7.0",
+  "version": "3.0.0",
   "description": "A lightweight AI chat framework with plugin system, unified message format, and tool calling support.",
   "type": "module",
   "main": "dist/my-ai-chat-framework.node.cjs.js",
@@ -13,6 +13,35 @@
       "browser": "./dist/my-ai-chat-framework.browser.umd.js"
     }
   },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "preview": "vite preview",
+    "test": "node tests/core.test.js && node tests/pipeline.test.js",
+    "test:integration": "node tests/integration.test.js",
+    "selfcheck": "node examples/selfcheck.js",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "README_ZH.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/DEVELOPER.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/233zrl/my-chat-test.git"
+  },
+  "homepage": "https://github.com/233zrl/my-chat-test#readme",
+  "bugs": {
+    "url": "https://github.com/233zrl/my-chat-test/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "ai",
     "chat",
@@ -22,16 +51,10 @@
     "streaming",
     "plugin"
   ],
-  "author": "Your Name",
+  "author": "233zrl <zrl233333@outlook.com>",
   "license": "MIT",
   "devDependencies": {
     "dotenv": "^17.3.1",
     "vite": "^8.0.2"
-  },
-  "scripts": {
-    "build": "vite build",
-    "dev": "vite",
-    "preview": "vite preview",
-    "test": "node test.js"
   }
 }

package/src/adapters/openai.js

@@ -8,29 +8,64 @@ import { isString } from "../utils/typeCheck.js";
 import { APIError, NetworkError, ParsingError } from '../core/Errors.js';
 import { MessageFormatter } from '../utils/MessageFormatter.js';
 
+// 属于"运输层"的配置键：工厂实例持有，请求时覆盖 config 中同名项
+const TRANSPORT_KEYS = ['apiKey', 'baseUrl', 'apiUrl', 'path', 'headers'];
+
 export const openaiAdapter = {
   name: 'openai',
 
-  install(chatService) {
+  /**
+   * 安装适配器。
+   * - 单例（openaiAdapter）：options 无意义，配置从 chat.config 读取（平铺兼容路径）
+   * - 工厂实例（createOpenAIAdapter）：options 并入实例自持的运输配置
+   */
+  install(chatService, options = {}) {
+    if (this._transport) this._transport = { ...this._transport, ...options };
     chatService.setAdapter(this);
   },
 
+  /**
+   * 实例自持配置（运输层）覆盖调用方传入的 config 同名项。
+   * modelParams 特殊处理：深度合并（config 优先，transport 兜底）——
+   * 避免工厂实例的默认参数覆盖掉会话/请求级覆盖。
+   */
+  _resolveConfig(config) {
+    const transport = this._transport || {};
+    const resolved = { ...config, ...transport };
+    if (transport.modelParams) {
+      resolved.modelParams = { ...transport.modelParams, ...(config.modelParams || {}) };
+    }
+    return resolved;
+  },
+
+  /** 工厂实例可提供给会话层的"请求默认参数"（非运输键的部分） */
+  getRequestDefaults() {
+    if (!this._transport) return {};
+    const defaults = {};
+    for (const [key, value] of Object.entries(this._transport)) {
+      if (!TRANSPORT_KEYS.includes(key) && value !== undefined) defaults[key] = value;
+    }
+    return defaults;
+  },
+
   /**
    * 构建 OpenAI 格式的请求体
    * @param {Array} messages - 内部消息列表
-   * @param {Object} config - 完整配置对象
+   * @param {Object} config - 合并后的请求参数（含 model/temperature 等）
    * @param {Array} [systemPrompts=[]] - 启用的 system prompt 列表
    * @returns {Object} 请求体
    */
   buildRequest(messages, config, systemPrompts = []) {
+    config = this._resolveConfig(config);
     const model = config.model || config.modelParams?.model;
     if (!model) {
       throw new Error('Missing required config: model (either at top level or in modelParams)');
     }
 
-    const temperature = config.modelParams?.temperature ?? config.temperature ?? 0.7;
-    const maxTokens = config.modelParams?.maxTokens ?? config.maxTokens ?? 2000;
-    const reasoningEffort = config.modelParams?.reasoningEffort ?? config.reasoningEffort;
+    const mp = config.modelParams || {};
+    const temperature = mp.temperature ?? config.temperature ?? 0.7;
+    const maxTokens = mp.maxTokens ?? config.maxTokens ?? 2000;
+    const reasoningEffort = mp.reasoningEffort ?? config.reasoningEffort;
 
     // 用 MessageFormatter 统一处理：system 置顶、消息过滤、字段映射、图片解析
     // format 由 config.messageFormat 指定（默认 'openai'）
@@ -50,15 +85,35 @@ export const openaiAdapter = {
       stream: false
     };
 
+    // 硬编码常用参数：驼峰命名，适配器负责转 API 格式
+    if (mp.topP !== undefined) requestBody.top_p = mp.topP;
+    if (mp.frequencyPenalty !== undefined) requestBody.frequency_penalty = mp.frequencyPenalty;
+    if (mp.presencePenalty !== undefined) requestBody.presence_penalty = mp.presencePenalty;
+    if (mp.stop !== undefined) requestBody.stop = mp.stop;
+    if (mp.responseFormat !== undefined) requestBody.response_format = mp.responseFormat;
+    if (mp.seed !== undefined) requestBody.seed = mp.seed;
+
     if (config.tools && Array.isArray(config.tools) && config.tools.length > 0) {
       requestBody.tools = config.tools;
       requestBody.tool_choice = 'auto';
     }
 
-    if (reasoningEffort && model === 'deepseek-reasoner') {
+    if (reasoningEffort !== undefined) {
       requestBody.reasoning_effort = reasoningEffort;
     }
 
+    // modelParams 中未被硬编码处理的字段，透传到请求体
+    const consumedKeys = new Set([
+      'model', 'temperature', 'maxTokens', 'reasoningEffort',
+      'topP', 'frequencyPenalty', 'presencePenalty',
+      'stop', 'responseFormat', 'seed'
+    ]);
+    for (const [key, value] of Object.entries(mp)) {
+      if (!consumedKeys.has(key) && value !== undefined) {
+        requestBody[key] = value;
+      }
+    }
+
     return requestBody;
   },
 
@@ -93,6 +148,7 @@ export const openaiAdapter = {
    */
   async send(requestBody, config, options = {}) {
     try {
+      config = this._resolveConfig(config);
       const url = this._getUrl(config);
 
       const headers = {
@@ -156,6 +212,7 @@ export const openaiAdapter = {
    * @param {Object} [options] — { signal, headers: {...} }
    */
   async stream(requestBody, config, onProgress, onDone, options = {}) {
+    config = this._resolveConfig(config);
     const streamBody = { ...requestBody, stream: true };
     const url = this._getUrl(config);
     let response;
@@ -277,4 +334,22 @@ export const openaiAdapter = {
     throw new APIError(errorMessage, response.status, null, errorText);
   }
 
-};
+};
+
+/**
+ * 创建 OpenAI 兼容适配器实例（工厂）。
+ *
+ * 与单例 openaiAdapter 的区别：每个实例自持一份运输配置（apiKey/baseUrl/apiUrl/path/headers），
+ * 互不干扰——解决"同一适配器装到多个 ChatService 互相覆盖"的单例陷阱。
+ *
+ * 用法：
+ *   const adapter = createOpenAIAdapter({ apiKey, baseUrl, modelParams: { temperature: 0.8 } });
+ *   const chat = new ChatService({ adapter, model: 'deepseek-chat' });
+ *   chat.use(adapter);  // 或直接 new ChatService({ adapter })
+ *
+ * 非运输键（model/modelParams/messageFormat/resolveImage/capabilities 等）会作为
+ * "请求默认参数"供会话层合并，单次请求仍可覆盖。
+ */
+export function createOpenAIAdapter(options = {}) {
+  return { ...openaiAdapter, _transport: { ...options } };
+}