@aalis/plugin-llm-openai 0.14.1 → 0.16.0

package/dist/index.js

@@ -1,17 +1,12 @@
-import { LLMCapabilities, llm } from '@aalis/api-llm';
-import { config, definePlugin, lifecycle, logger, provide } from '@aalis/core';
+import { finishReasonOf, IDLE_TIMEOUT_MAX_MS, idleTimeout, LLMCapabilities, llm, metered, requestedThinking, } from '@aalis/api-llm';
+import { config, definePlugin, events, lifecycle, logger, provide } from '@aalis/core';
 import { configError, defineConfig, missingConfigError, parseConfig } from '@aalis/schema-config';
+import { TextError, textClauses, textOf, toSource } from '@aalis/schema-i18n';
 import { prepareLLMMessages, toLLMRole } from '@aalis/schema-message';
 import { truncateChars } from '@aalis/util-text-normalize';
+import { Agent, errors } from 'undici';
+import { t } from './texts.js';
 // ===== 插件元数据 =====
-/** 已知的内容审查错误关键词 */
-const CONTENT_FILTER_PATTERNS = [
-    'content exists risk',
-    'content_filter',
-    'content_policy',
-    'sensitive content',
-    'risk control',
-];
 /** 错误信息与日志里附带的摘录上限（字符）。网关的 HTML 错误页可达数十 KB；截断按代理对安全，不留孤代理 */
 const ERROR_BODY_MAX_CHARS = 500;
 /** 错误信息与日志里附带的摘录：空白（含 HTML 错误页的换行）折叠成一个空格后截断，不把换行带进错误信息与日志 */
@@ -19,51 +14,45 @@ function bodyExcerpt(body) {
     return truncateChars(body.replace(/\s+/g, ' ').trim(), ERROR_BODY_MAX_CHARS, '…');
 }
 /**
- * 读配置时校验 baseUrl，解析不了的与带用户名或密码的抛配置错误。带凭据的 URL fetch 拒发，凭据还会随报错与
- * 条目名称（WebUI 的模型下拉）显示出来；解析不了的无从判断有没有凭据，请求同样发不出去。消息不带 URL
+ * 读配置时校验 baseUrl，解析不了的、带查询串或片段的与带用户名或密码的抛配置错误。插件在 baseUrl 后面拼路径，带查询串或
+ * 片段时路径落进查询串或片段，请求地址是坏的；末尾只有一个 ? 时解析后查询串为空，拼出来照样是坏的，所以按原文判。带凭据
+ * 的 URL fetch 拒发，凭据还会随报错与条目名称（WebUI 的模型下拉）显示出来；解析不了的无从判断有没有凭据，请求同样发不
+ * 出去。消息不带 URL
  */
 function checkBaseUrl(baseUrl) {
     if (!URL.canParse(baseUrl)) {
-        throw configError('baseUrl 不是有效的 URL，需写成完整地址，如 https://api.openai.com/v1');
+        throw configError(t('baseUrlInvalid'));
+    }
+    if (/[?#]/.test(baseUrl)) {
+        throw configError(t('baseUrlQuery'));
     }
     const { username, password } = new URL(baseUrl);
     if (username || password) {
-        throw configError('baseUrl 不能带用户名或密码（user:pass@），密钥请填在 apiKey');
+        throw configError(t('baseUrlCredentials'));
     }
 }
 /**
- * 错误信息与日志里显示的 URL：去掉查询串（有的网关把密钥写在查询串里）。没有查询串时原样返回，保留配置里的写法。
- * 带用户名或密码的 baseUrl 读配置时已拒绝（见 checkBaseUrl）
- */
-function redactUrl(url) {
-    const parsed = new URL(url);
-    if (!parsed.search)
-        return url;
-    parsed.search = '';
-    return parsed.href;
-}
-/**
- * 错误消息连同底层原因，写成一行。fetch 网络失败的消息固定是「fetch failed」，真实原因（DNS、拒绝连接、TLS）在
- * cause 上；连 localhost 时两个地址族都失败，cause 是消息为空的 AggregateError，原因在它的子错误上
+ * 错误连同底层原因，写成一行（日志取 toSource）。fetch 网络失败的消息固定是「fetch failed」，真实原因（DNS、拒绝连接、TLS）
+ * 在 cause 上；连 localhost 时两个地址族都失败，cause 是消息为空的 AggregateError，原因在它的子错误上
  */
 function describeError(err) {
     const cause = err instanceof Error ? err.cause : undefined;
     const reasons = cause instanceof AggregateError ? cause.errors : cause instanceof Error ? [cause] : [];
     const detail = reasons.map(e => (e instanceof Error ? e.message : String(e))).join('; ');
-    return `${err instanceof Error ? err.message : String(err)}${detail ? ` ← ${detail}` : ''}`;
+    return detail ? t('withCause', { error: textOf(err), detail }) : textOf(err);
 }
 /** 常见状态码的一句提示 */
 function statusHint(status) {
     if (status === 401 || status === 403)
-        return '密钥无效或没有权限';
+        return t('hintAuth');
     if (status === 402)
-        return '余额不足或需要付费';
+        return t('hintPayment');
     if (status === 404)
-        return '模型或地址不对';
+        return t('hintNotFound');
     if (status === 429)
-        return '请求过多或额度不足';
+        return t('hintRateLimit');
     if (status >= 500)
-        return '上游服务故障';
+        return t('hintUpstream');
     return undefined;
 }
 /**
@@ -89,73 +78,121 @@ function upstreamMessage(body) {
 function httpErrorMessage(provider, status, body) {
     const hint = statusHint(status);
     const message = upstreamMessage(body);
-    return `${provider} API 错误 (${status})${hint ? `：${hint}` : ''}；${message ? `上游说明：${message}` : '详情见日志'}`;
+    return textClauses([
+        hint ? t('apiErrorHint', { provider, status, hint }) : t('apiError', { provider, status }),
+        message ? t('upstreamMessage', { message }) : t('seeLogs'),
+    ]);
 }
-/** 解析 API 错误：内容审查类错误按完整响应体识别，给固定提示；其余见 httpErrorMessage */
-function parseApiError(provider, status, body) {
-    const lower = body.toLowerCase();
-    if (status === 400 && CONTENT_FILTER_PATTERNS.some(p => lower.includes(p))) {
-        return `${provider} 拒绝了此次请求（内容安全策略），请尝试换一个话题或缩短上下文`;
+const LOW_TO_HIGH = [
+    { id: 'low', label: t('levelLow') },
+    { id: 'medium', label: t('levelMedium') },
+    { id: 'high', label: t('levelHigh') },
+];
+/**
+ * reasoning_effort 写法下模型的档位，按模型族给：gpt-5.1 起（gpt-5.<n>）多一档关（none），不带字段时就是关；gpt-5 本身
+ * 最浅是最低（minimal）；o1-mini 与 o1-preview 会思考却不收这个字段，不声明；其余能思考的模型是低、中、高
+ */
+function effortLevels(model) {
+    const lower = model.toLowerCase();
+    if (/^o1-(mini|preview)/.test(lower))
+        return undefined;
+    if (/^gpt-5\.\d/.test(lower))
+        return { levels: [{ id: 'none', label: t('levelOff') }, ...LOW_TO_HIGH], default: 'none' };
+    if (lower.startsWith('gpt-5')) {
+        return { levels: [{ id: 'minimal', label: t('levelMinimal') }, ...LOW_TO_HIGH], default: 'medium' };
     }
-    return httpErrorMessage(provider, status, body);
+    return { levels: LOW_TO_HIGH, default: 'medium' };
 }
+/**
+ * 思考档位的两种写法（thinkingParam）：能思考的模型（能力里有 thinking 的）按实例选的写法声明档位，fields 把档位翻成
+ * 请求体字段。请求带了档位才发，没带时不发、按端点自己的默认，默认档写的就是端点的默认
+ */
+const THINKING_STYLES = {
+    reasoning_effort: {
+        levels: effortLevels,
+        fields: level => ({ reasoning_effort: level }),
+    },
+    thinking: {
+        levels: () => ({
+            levels: [
+                { id: 'off', label: t('levelOff') },
+                { id: 'on', label: t('levelOn') },
+            ],
+            default: 'on',
+        }),
+        fields: level => ({ thinking: { type: level === 'on' ? 'enabled' : 'disabled' } }),
+    },
+};
 const configSchema = defineConfig({
     apiKey: {
         type: 'string',
         label: 'API Key',
         secret: true,
         onInvalid: 'error',
-        description: 'OpenAI API 密钥（本地服务可留空）',
+        description: t('apiKeyDescription'),
     },
     baseUrl: {
         type: 'string',
-        label: 'API 地址',
+        label: t('baseUrlLabel'),
         default: 'https://api.openai.com/v1',
         onInvalid: 'error',
-        description: 'API 端点完整前缀（含版本段，如 https://api.openai.com/v1）；插件只在其后拼 /chat/completions 与 /models。' +
-            '可替换为任何兼容服务（如 Gemini 的 https://generativelanguage.googleapis.com/v1beta/openai）。',
+        description: t('baseUrlDescription'),
     },
     customModels: {
         type: 'textarea',
-        label: '自定义模型',
+        label: t('customModelsLabel'),
         default: '',
-        description: '手动添加的模型名称（每行一个或逗号分隔）。用于补充自动发现列表中未出现的模型。与自动发现重复时会提示去重。',
+        description: t('customModelsDescription'),
     },
     discoverModels: {
         type: 'boolean',
-        label: '自动发现模型',
+        label: t('discoverModelsLabel'),
         default: true,
-        description: '启动时请求 /models 发现可用模型，WebUI 可刷新模型列表。网关不提供 /models 时关闭：不发发现请求，只注册 customModels（此时必填），也不支持刷新。',
+        description: t('discoverModelsDescription'),
     },
     modelCapabilities: {
         type: 'textarea',
-        label: '单模型能力覆盖',
+        label: t('modelCapabilitiesLabel'),
         default: '',
-        description: '按行指定某个模型的能力集。有该模型的表项时**覆盖**插件启发式推断，与 adapter 默认能力仍取并集。\n格式：`<modelId>: <cap1>,<cap2>,...`，每行一条。如：gpt-4o: chat,tool_calling,vision,streaming\n可用能力：chat / tool_calling / vision / streaming / thinking 等。',
+        description: t('modelCapabilitiesDescription'),
     },
     providerCapabilities: {
         type: 'string',
-        label: '适配器默认能力（逗号分隔）',
+        label: t('providerCapabilitiesLabel'),
         default: '',
-        description: '为本适配器下所有模型额外补充的能力。最终某模型的能力 = 此处能力 ∪ 模型级别能力。例：chat,tool_calling,streaming',
+        description: t('providerCapabilitiesDescription'),
     },
     timeout: {
         type: 'number',
-        label: '请求超时 (秒)',
+        label: t('timeoutLabel'),
         default: 120,
-        description: 'LLM 请求超时时间（秒）。思考模式或长文本建议适当调大。0 = 不限制。',
+        description: t('timeoutDescription'),
+    },
+    temperature: { type: 'number', label: t('temperatureLabel'), default: 0.7, description: t('temperatureDescription') },
+    maxTokens: {
+        type: 'number',
+        label: t('maxTokensLabel'),
+        default: 4096,
+        min: 1,
+        integer: true,
+        onInvalid: 'error',
+        description: t('maxTokensDescription'),
+    },
+    contextLength: {
+        type: 'number',
+        label: t('contextLengthLabel'),
+        default: 128000,
+        description: t('contextLengthDescription'),
     },
-    temperature: { type: 'number', label: '温度', default: 0.7, description: '0-2，越高越随机' },
-    maxTokens: { type: 'number', label: '最大 Token', default: 4096, description: '单次回复最大生成 token 数' },
-    contextLength: { type: 'number', label: '上下文长度', default: 128000, description: '模型上下文窗口大小' },
     thinkingParam: {
-        type: 'boolean',
-        label: '透传 thinking 开关（DeepSeek 风格）',
-        default: false,
-        description: '开启后把请求的 think 开关编码为 DeepSeek 风格的 `thinking: {type: enabled|disabled}` 字段发给端点，' +
-            '使会话级 /session.set -t 与平台档 think 对本 provider 生效。' +
-            '仅在端点是 DeepSeek 或会原样透传该字段的中转时开启——OpenAI 官方端点不认此字段会拒收请求。' +
-            '请求未指定 think 时不发送该字段（沿用端点默认）。',
+        type: 'select',
+        label: t('thinkingParamLabel'),
+        default: 'reasoning_effort',
+        options: [
+            { label: t('thinkingParamEffort'), value: 'reasoning_effort' },
+            { label: t('thinkingParamThinking'), value: 'thinking' },
+        ],
+        description: t('thinkingParamDescription'),
     },
 });
 /**
@@ -172,28 +209,26 @@ class OpenAIClient {
     timeout;
     temperature;
     maxTokens;
-    thinkingParam;
+    thinkingFields;
     logger;
+    /**
+     * 生成请求的连接池：不设等响应头与读响应体的时限（默认各 300 秒），timeout 是唯一的时限。dispatcher 是 Node 自带 fetch
+     * 认的扩展字段，DOM 的 RequestInit 里没有（测试的类型检查带 DOM），带它的选项按 RequestInit 断言
+     */
+    dispatcher = new Agent({ headersTimeout: 0, bodyTimeout: 0 });
     constructor(cfg, logger) {
         this.apiKey = cfg.apiKey;
         this.baseUrl = cfg.baseUrl.replace(/\/+$/, '');
-        // schema 中 timeout 单位为「秒」，存储为毫秒；0 或负数视为不限制 → 用一个非常大的值
-        this.timeout = cfg.timeout > 0 ? cfg.timeout * 1000 : 2_147_483_647;
+        // schema 中 timeout 单位为「秒」，存储为毫秒；0 或负数不限，超过定时器上限按上限计，报错里的秒数是生效的值（见 idleTimeout）
+        this.timeout = Math.min(cfg.timeout * 1000, IDLE_TIMEOUT_MAX_MS);
         this.temperature = cfg.temperature;
         this.maxTokens = cfg.maxTokens;
-        this.thinkingParam = cfg.thinkingParam;
+        this.thinkingFields = THINKING_STYLES[cfg.thinkingParam].fields;
         this.logger = logger;
     }
-    /**
-     * 请求的 think 开关 → 线上字段。本插件原本只按真 OpenAI 写（无思考开关，o 系列隐式推理），
-     * request.think 一直被无视——走 OpenAI 兼容中转的 DeepSeek 因此收不到会话级开关。
-     * DeepSeek 风格 `thinking: {type}` 由配置显式开启（真 OpenAI 端点不认此字段会 400）；
-     * think 未指定时不发字段，端点默认行为不被触碰。
-     */
-    applyThinking(body, request) {
-        if (!this.thinkingParam || request.think === undefined)
-            return;
-        body.thinking = { type: request.think ? 'enabled' : 'disabled' };
+    /** 停用时关掉生成请求的连接池，之后的请求被拒（报插件已停用或重载）。不等在飞的请求读完：它们是调用方的，等它们会让重载卡到回复写完 */
+    close() {
+        void this.dispatcher.close();
     }
     /** 构造请求头（无 apiKey 时不发 Authorization） */
     get headers() {
@@ -202,24 +237,27 @@ class OpenAIClient {
             h.Authorization = `Bearer ${this.apiKey}`;
         return h;
     }
-    /** 对话请求的非 2xx 应答：截断后的响应体记 warn，抛出的错误见 parseApiError */
+    /** 对话请求的非 2xx 应答：截断后的响应体记 warn，抛出的错误见 httpErrorMessage */
     apiError(status, body) {
         this.logger.warn(`LLM API 错误 (${status}): ${bodyExcerpt(body)}`);
-        return new Error(parseApiError('LLM', status, body));
+        return new TextError(httpErrorMessage('LLM', status, body));
     }
     /**
-     * 对话请求没拿到完整应答（fetch 或读响应体时抛出）：原始错误连同原因记 warn，超时与连不上各换成一句说明，其它错误
-     * 原样返回。调用方经 request.signal 中止时原样返回、不记日志，agent 按中止收尾
+     * 对话请求没拿到完整应答（fetch 或读响应体时抛出）：原始错误连同原因记 warn，超时、连不上与连接池已关闭（插件停用或重载）
+     * 各换成一句说明，其它错误原样返回。调用方经 request.signal 中止时原样返回、不记日志，agent 按中止收尾
      */
     requestError(err, request, startedAt) {
         if (request.signal?.aborted)
             return err;
-        this.logger.warn(`LLM 请求失败 (耗时 ${Date.now() - startedAt}ms): ${describeError(err)}`);
+        this.logger.warn(`LLM 请求失败 (耗时 ${Date.now() - startedAt}ms): ${toSource(describeError(err))}`);
         if (err instanceof DOMException && err.name === 'TimeoutError') {
-            return new Error(`LLM 请求超时：${this.timeout / 1000} 秒内没有完成，可在配置里调大 timeout`);
+            return new TextError(t('requestTimeout', { seconds: this.timeout / 1000 }));
         }
         if (err instanceof TypeError && err.message === 'fetch failed') {
-            return new Error('LLM 连不上服务：检查 baseUrl 与网络，详情见日志');
+            if (err.cause instanceof errors.ClientClosedError || err.cause instanceof errors.ClientDestroyedError) {
+                return new TextError(t('pluginClosed'));
+            }
+            return new TextError(t('unreachable'));
         }
         return err;
     }
@@ -230,7 +268,7 @@ class OpenAIClient {
         }
         catch {
             this.logger.warn(`LLM 应答不是 JSON (${status}): ${bodyExcerpt(text)}`);
-            throw new Error(`LLM 应答不是 JSON (${status})；详情见日志`);
+            throw new TextError(t('notJson', { status }));
         }
     }
     /**
@@ -258,20 +296,21 @@ class OpenAIClient {
                 data = JSON.parse(text);
             }
             catch {
-                throw new Error(`响应不是 JSON: ${bodyExcerpt(text)}`);
+                throw new TextError(t('discoveryNotJson', { excerpt: bodyExcerpt(text) }));
             }
             const list = data?.data;
             if (!Array.isArray(list) || !list.every(m => typeof m?.id === 'string')) {
-                throw new Error(`响应不是模型列表（需要 data 数组，每项带字符串 id）: ${bodyExcerpt(JSON.stringify(data))}`);
+                throw new TextError(t('discoveryNotList', { excerpt: bodyExcerpt(JSON.stringify(data)) }));
             }
             return list.map(m => m.id);
         }
         catch (err) {
             signal?.throwIfAborted();
-            throw new Error(`模型发现失败 ${redactUrl(url)}: ${describeError(err)}`, { cause: err });
+            throw new TextError(t('discoveryFailed', { url, error: describeError(err) }), { cause: err });
         }
     }
-    async chat(model, request) {
+    /** level 是请求带的思考档位，没带时不发字段 */
+    async chat(model, request, level) {
         const messages = prepareLLMMessages(request.messages).map(m => this.toAPIMessage(m));
         const tools = request.tools?.map(t => this.toAPITool(t));
         const reasoning = isReasoningModel(model);
@@ -283,14 +322,12 @@ class OpenAIClient {
             [reasoning ? 'max_completion_tokens' : 'max_tokens']: request.maxTokens ?? this.maxTokens,
             ...(reasoning ? {} : { temperature: request.temperature ?? this.temperature }),
         };
-        this.applyThinking(body, request);
+        if (level !== undefined)
+            Object.assign(body, this.thinkingFields(level));
         if (tools && tools.length > 0) {
             body.tools = tools;
         }
         this.logger.debug(`请求 LLM: ${body.model}, ${messages.length} 条消息, ${tools?.length ?? 0} 个工具`);
-        const signals = [AbortSignal.timeout(this.timeout)];
-        if (request.signal)
-            signals.push(request.signal);
         const startedAt = Date.now();
         let response;
         let text;
@@ -299,7 +336,8 @@ class OpenAIClient {
                 method: 'POST',
                 headers: this.headers,
                 body: JSON.stringify(body),
-                signal: AbortSignal.any(signals),
+                signal: idleTimeout(this.timeout, request.signal).signal,
+                dispatcher: this.dispatcher,
             });
             text = await response.text();
         }
@@ -311,10 +349,11 @@ class OpenAIClient {
         const data = this.parseJsonBody(response.status, text);
         const choice = data.choices[0];
         if (!choice) {
-            throw new Error('LLM 返回了空的 choices');
+            throw new TextError(t('emptyChoices'));
         }
         const result = {
             content: choice.message.content,
+            finishReason: finishReasonOf(choice.finish_reason),
         };
         if (choice.message.tool_calls && choice.message.tool_calls.length > 0) {
             result.toolCalls = choice.message.tool_calls.map(tc => ({
@@ -336,7 +375,7 @@ class OpenAIClient {
         }
         return result;
     }
-    async *chatStream(model, request) {
+    async *chatStream(model, request, level) {
         const messages = prepareLLMMessages(request.messages).map(m => this.toAPIMessage(m));
         const tools = request.tools?.map(t => this.toAPITool(t));
         const reasoning = isReasoningModel(model);
@@ -350,14 +389,22 @@ class OpenAIClient {
             // 流式必须显式声明才会在收尾帧返回 usage（真 OpenAI 端点无此开关则整条流不含 usage）。
             stream_options: { include_usage: true },
         };
-        this.applyThinking(body, request);
+        if (level !== undefined)
+            Object.assign(body, this.thinkingFields(level));
         if (tools && tools.length > 0) {
             body.tools = tools;
         }
         this.logger.debug(`流式请求 LLM: ${body.model}, ${messages.length} 条消息`);
-        const signals = [AbortSignal.timeout(this.timeout)];
-        if (request.signal)
-            signals.push(request.signal);
+        // 交出一段期间不计时：调用方处理一段的时间不算停顿
+        const timer = idleTimeout(this.timeout, request.signal);
+        for await (const chunk of this.readStream(body, request, timer)) {
+            timer.pause();
+            yield chunk;
+            timer.resume();
+        }
+    }
+    /** 发出流式请求并逐段解析，timer 管这次请求的停顿超时 */
+    async *readStream(body, request, timer) {
         const reqStart = Date.now();
         const slowConnectTimer = setTimeout(() => {
             this.logger.warn(`LLM 连接慢：已等待 15s 仍未收到响应头 (url=${this.baseUrl}/chat/completions)`);
@@ -368,7 +415,8 @@ class OpenAIClient {
                 method: 'POST',
                 headers: this.headers,
                 body: JSON.stringify(body),
-                signal: AbortSignal.any(signals),
+                signal: timer.signal,
+                dispatcher: this.dispatcher,
             });
         }
         catch (err) {
@@ -384,8 +432,9 @@ class OpenAIClient {
             throw this.apiError(response.status, errorText);
         }
         const toolCallBuffers = new Map();
+        let finishReason;
         if (!response.body) {
-            throw new Error('LLM API 返回了空的响应体，无法进行流式读取');
+            throw new TextError(t('emptyBody'));
         }
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
@@ -421,14 +470,17 @@ class OpenAIClient {
                         for (const [, tc] of [...toolCallBuffers.entries()].sort((a, b) => a[0] - b[0])) {
                             toolCalls.push({ id: tc.id, type: 'function', function: { name: tc.name, arguments: tc.args } });
                         }
-                        yield { done: true, toolCalls: toolCalls.length > 0 ? toolCalls : undefined };
+                        yield { done: true, toolCalls: toolCalls.length > 0 ? toolCalls : undefined, finishReason };
                         return;
                     }
                     try {
                         const data = JSON.parse(payload);
                         const chunk = {};
-                        // usage 必须在 delta 守卫**之前**取：OpenAI 的 include_usage 形态把
-                        // usage 挂在 `choices: []` 的收尾帧上，等到守卫之后再取整帧已被跳过。
+                        // usage 与结束原因必须在 delta 守卫**之前**取：OpenAI 的 include_usage 形态把 usage 挂在 `choices: []` 的
+                        // 收尾帧上，兼容端点的结束原因可能在不带 delta 的末帧上，等到守卫之后再取整帧已被跳过。
+                        const reason = finishReasonOf(data.choices?.[0]?.finish_reason);
+                        if (reason)
+                            finishReason = reason;
                         if (data.usage) {
                             chunk.usage = {
                                 promptTokens: data.usage.prompt_tokens,
@@ -443,11 +495,17 @@ class OpenAIClient {
                                 yield chunk; // 纯 usage 收尾帧照样上报
                             continue;
                         }
+                        // 带生成内容的增量重新计时：思考本插件不交出，照样算（兼容端点写在 reasoning_content 或 reasoning）
+                        if (delta.content || delta.reasoning_content || delta.reasoning)
+                            timer.touch();
                         if (delta.content)
                             chunk.contentDelta = delta.content;
-                        // 累积工具调用
+                        // 累积工具调用；同一帧里有几个调用，进度就各报一次
+                        const progress = [];
                         if (delta.tool_calls) {
                             for (const tc of delta.tool_calls) {
+                                if (tc.function?.name || tc.function?.arguments)
+                                    timer.touch();
                                 const idx = tc.index ?? 0;
                                 if (tc.id) {
                                     toolCallBuffers.set(idx, { id: tc.id, name: tc.function?.name ?? '', args: '' });
@@ -458,18 +516,14 @@ class OpenAIClient {
                                         entry.name = tc.function.name;
                                     if (tc.function?.arguments)
                                         entry.args += tc.function.arguments;
-                                    // 每次 delta 都 yield 进度（不影响最终 done chunk）
-                                    chunk.toolCallProgress = {
-                                        index: idx,
-                                        name: entry.name,
-                                        charsAccumulated: entry.args.length,
-                                    };
+                                    progress.push({ index: idx, name: entry.name, charsAccumulated: entry.args.length });
                                 }
                             }
                         }
-                        if (chunk.contentDelta || chunk.usage || chunk.toolCallProgress) {
+                        if (chunk.contentDelta || chunk.usage)
                             yield chunk;
-                        }
+                        for (const toolCallProgress of progress)
+                            yield { toolCallProgress };
                     }
                     catch {
                         /* skip malformed JSON */
@@ -485,7 +539,7 @@ class OpenAIClient {
             clearTimeout(streamStallTimer);
             // cancel 而非仅 releaseLock：中止/提前退出时要主动关闭响应体。releaseLock 只是放锁，
             // 底层流仍开着——被打断的生成会让 undici 挂着半读的响应与套接字，直到请求超时兜底
-            // 才释放（本地慢生成 + lane 中止高频后，这类残留一挂就是整个超时窗）。
+            // 才释放（本地慢生成时回合常被停下，这类残留一挂就是整个超时窗）。
             // cancel 自带放锁。三条退出路径的语义：读尽 EOF（done:true）→ 流已 closed，cancel 是
             // 真 no-op；收到终帧即 return（未读到 EOF）与消费方提前 break → cancel 中止残余响应体，
             // 这正是本修复要的「立即交还套接字」，代价是该连接不回 keep-alive 池。
@@ -496,7 +550,7 @@ class OpenAIClient {
         for (const [, tc] of [...toolCallBuffers.entries()].sort((a, b) => a[0] - b[0])) {
             toolCalls.push({ id: tc.id, type: 'function', function: { name: tc.name, arguments: tc.args } });
         }
-        yield { done: true, toolCalls: toolCalls.length > 0 ? toolCalls : undefined };
+        yield { done: true, toolCalls: toolCalls.length > 0 ? toolCalls : undefined, finishReason };
     }
     toAPIMessage(msg) {
         // 调用方已经 prepareLLMMessages 处理过：role 已是 WellKnownRole，
@@ -551,8 +605,7 @@ class OpenAIClient {
 const { Chat, ToolCalling, Streaming, Vision, Thinking } = LLMCapabilities;
 // resolveCapabilities 的前缀匹配按表序取第一个命中，更具体的前缀必须排在更短的前缀之前
 // （gpt-4.1 在 gpt-4 之前，否则 gpt-4.1-mini 会命中 gpt-4、丢掉 Vision）。
-// 表里的 Vision 影响 media 的视觉路由、vision.delivery=auto 的交付判定，以及 media 缺席时
-// WebUI（/api/status）是否显示图片上传按钮；漏标只是退回识别模型转文字，误标会把原图直通给
+// 表里的 Vision 影响 media 的视觉路由与 vision.delivery=auto 的交付判定；漏标只是退回识别模型转文字，误标会把原图直通给
 // 不收图的模型，故只收确认全系支持看图的族。
 const MODEL_CAPABILITIES = {
     'gpt-4o': [Chat, ToolCalling, Streaming, Vision],
@@ -560,6 +613,8 @@ const MODEL_CAPABILITIES = {
     'gpt-4.1': [Chat, ToolCalling, Streaming, Vision],
     'gpt-4-turbo': [Chat, ToolCalling, Streaming],
     'gpt-4': [Chat, ToolCalling, Streaming],
+    // gpt-5-chat 是非推理的对话模型，不收思考档位
+    'gpt-5-chat': [Chat, ToolCalling, Streaming, Vision],
     'gpt-5': [Chat, ToolCalling, Streaming, Vision, Thinking],
     'gpt-3.5-turbo': [Chat, ToolCalling, Streaming],
     o1: [Chat, Thinking],
@@ -665,10 +720,13 @@ class OpenAIModelHandle {
     contextLength;
     maxOutputTokens;
     capabilities;
+    thinking;
     refresh;
     constructor(client, id, providerId, contextLength, maxOutputTokens, 
     /** 该 model 的能力元数据（供 media 发现/下拉展示读取，非 DI 选择机制）。 */
     capabilities, 
+    /** 能调思考的模型才有：按实例选的写法与模型族 */
+    thinking, 
     /** Provider 级共享的 refresh 闭包；webui 按 providerId 找到该 provider 的任一 entry 调一次即可。关闭模型发现时没有 */
     refresh) {
         this.client = client;
@@ -677,17 +735,18 @@ class OpenAIModelHandle {
         this.contextLength = contextLength;
         this.maxOutputTokens = maxOutputTokens;
         this.capabilities = capabilities;
+        this.thinking = thinking;
         this.refresh = refresh;
     }
-    chat(request) {
-        return this.client.chat(this.id, request);
+    async chat(request) {
+        return this.client.chat(this.id, request, requestedThinking(this, request));
     }
-    chatStream(request) {
-        return this.client.chatStream(this.id, request);
+    async *chatStream(request) {
+        yield* this.client.chatStream(this.id, request, requestedThinking(this, request));
     }
 }
 // ===== 插件定义 =====
-const uses = { config, logger, lifecycle, provide };
+const uses = { config, logger, lifecycle, provide, events };
 export default definePlugin({
     name: '@aalis/plugin-llm-openai',
     displayName: 'OpenAI',
@@ -698,23 +757,24 @@ export default definePlugin({
     uses,
     apply: registerModels,
 });
-async function registerModels({ config, logger, lifecycle, provide }) {
-    const cfg = parseConfig(configSchema, config, logger);
+async function registerModels({ config, logger, lifecycle, provide, events }) {
+    const cfg = parseConfig(configSchema, config.use, logger.use);
     const customModels = parseCustomModels(cfg.customModels);
     const modelCapabilities = parseModelCapabilities(cfg.modelCapabilities);
     const providerCapabilities = parseProviderCapabilities(cfg.providerCapabilities);
     checkBaseUrl(cfg.baseUrl);
-    // 官方端点判定按 URL host（前缀字符串匹配会误伤 api.openai.com.cn 等镜像域名）
+    // 官方端点不收不带 key 的请求：留空时激活就报缺 apiKey，不等第一次调用才回 401；兼容端点（本地服务等）可以不要 key，
+    // 所以只按 host 认官方（按前缀匹配会误伤 api.openai.com.cn 这类镜像域名）
     const isOfficialOpenAI = new URL(cfg.baseUrl).hostname === 'api.openai.com';
     if (!cfg.apiKey && isOfficialOpenAI) {
-        throw missingConfigError('apiKey', '使用 OpenAI 官方 API 时必填');
+        throw missingConfigError('apiKey', t('apiKeyRequired'));
     }
     if (!cfg.discoverModels && customModels.length === 0) {
-        throw missingConfigError('customModels', '关闭 discoverModels 时必填');
+        throw missingConfigError('customModels', t('customModelsRequired'));
     }
-    const client = new OpenAIClient(cfg, logger);
+    const client = new OpenAIClient(cfg, logger.use);
+    lifecycle.use.onDispose(() => client.close(), '关闭生成请求的连接池');
     const baseLabel = `OpenAI (${cfg.baseUrl.replace(/^https?:\/\//, '')})`;
-    const shownBaseUrl = redactUrl(cfg.baseUrl);
     // 已注册 model entry 的句柄表：modelId → dispose（来自 provide 返回值）
     const registered = new Map();
     // 关闭模型发现时不提供 refresh：没有可重新发现的列表
@@ -723,10 +783,10 @@ async function registerModels({ config, logger, lifecycle, provide }) {
         if (registered.has(modelId))
             return;
         const capabilities = resolveCapabilities(modelId, modelCapabilities.get(modelId), providerCapabilities);
-        const handle = new OpenAIModelHandle(client, modelId, lifecycle.id, cfg.contextLength, cfg.maxTokens, capabilities, refresh);
-        const dispose = provide(llm, handle, {
+        const handle = new OpenAIModelHandle(client, modelId, lifecycle.use.id, cfg.contextLength, cfg.maxTokens, capabilities, capabilities.includes(Thinking) ? THINKING_STYLES[cfg.thinkingParam].levels(modelId) : undefined, refresh);
+        const dispose = provide.use(llm, metered(handle, events.use), {
             label: `${baseLabel} / ${modelId}`,
-            entryId: `${lifecycle.id}/${modelId}`,
+            entryId: `${lifecycle.use.id}/${modelId}`,
         });
         registered.set(modelId, dispose);
     }
@@ -738,7 +798,7 @@ async function registerModels({ config, logger, lifecycle, provide }) {
             d();
         }
         catch (err) {
-            logger.warn(`卸载 model entry "${modelId}" 失败: ${err}`);
+            logger.use.warn(`卸载 model entry "${modelId}" 失败: ${err}`);
         }
         registered.delete(modelId);
     }
@@ -747,7 +807,7 @@ async function registerModels({ config, logger, lifecycle, provide }) {
         const remoteSet = new Set(remoteIds);
         for (const cm of customModels) {
             if (remoteSet.has(cm)) {
-                logger.warn(`自定义模型 "${cm}" 与自动发现的模型重复，请在配置中去重`);
+                logger.use.warn(`自定义模型 "${cm}" 与自动发现的模型重复，请在配置中去重`);
             }
         }
         return [...remoteIds, ...customModels.filter(id => !remoteSet.has(id))];
@@ -757,36 +817,36 @@ async function registerModels({ config, logger, lifecycle, provide }) {
     // err 交给 logger 会按因果链把原因再记一遍
     let discoveryError;
     const remoteIds = cfg.discoverModels
-        ? await client.fetchRemoteModelIds(lifecycle.signal).catch((err) => {
-            discoveryError = err instanceof Error ? err.message : String(err);
+        ? await client.fetchRemoteModelIds(lifecycle.use.signal).catch((err) => {
+            discoveryError = textOf(err);
             return [];
         })
         : [];
-    lifecycle.signal.throwIfAborted();
+    lifecycle.use.signal.throwIfAborted();
     const initialIds = withCustomModels(remoteIds);
     // 一个模型都没有时抛配置错误，原因成为实例的错误信息；否则只剩 core 的「声明 provides [llm] 但未实际注册」。
     // 提示写在原因之前：原因里可能带着一段响应体
     if (initialIds.length === 0) {
         throw configError(discoveryError
-            ? `未配置 customModels，没有可注册的模型；${discoveryError}`
-            : `已连接 ${shownBaseUrl}，但未发现任何可用模型；可在 customModels 里写明要用的模型`);
+            ? t('noModelsDiscoveryFailed', { error: discoveryError })
+            : t('noModels', { baseUrl: cfg.baseUrl }));
     }
     if (discoveryError)
-        logger.warn(`启动时只注册 customModels 里的模型；${discoveryError}`);
+        logger.use.warn(`启动时只注册 customModels 里的模型；${toSource(discoveryError)}`);
     for (const modelId of initialIds)
         registerOne(modelId);
-    logger.info(!cfg.discoverModels
-        ? `未开启模型发现: ${shownBaseUrl}，注册 customModels 里的 ${initialIds.length} 个 model entry`
+    logger.use.info(!cfg.discoverModels
+        ? `未开启模型发现: ${cfg.baseUrl}，注册 customModels 里的 ${initialIds.length} 个 model entry`
         : discoveryError
-            ? `模型发现失败: ${shownBaseUrl}，注册 customModels 里的 ${initialIds.length} 个 model entry`
-            : `已连接: ${shownBaseUrl}，注册 ${initialIds.length} 个 model entry`);
+            ? `模型发现失败: ${cfg.baseUrl}，注册 customModels 里的 ${initialIds.length} 个 model entry`
+            : `已连接: ${cfg.baseUrl}，注册 ${initialIds.length} 个 model entry`);
     /**
      * 重新发现并按差异增删条目（WebUI 触发）。与初次注册一样随停用或停机中止：中止即抛出，不再增删条目。
      * 发现失败同样抛出（WebUI 据此报错）、不增删条目：按空列表处理会把自动发现的条目全部注销
      */
     async function refreshModels() {
-        const next = withCustomModels(await client.fetchRemoteModelIds(lifecycle.signal));
-        lifecycle.signal.throwIfAborted();
+        const next = withCustomModels(await client.fetchRemoteModelIds(lifecycle.use.signal));
+        lifecycle.use.signal.throwIfAborted();
         const nextSet = new Set(next);
         const added = [];
         const removed = [];
@@ -803,10 +863,10 @@ async function registerModels({ config, logger, lifecycle, provide }) {
             }
         }
         if (added.length || removed.length) {
-            logger.info(`OpenAI 模型列表已刷新: +${added.length} (${added.join(',') || '-'}) / -${removed.length} (${removed.join(',') || '-'}) / 现共 ${registered.size}`);
+            logger.use.info(`OpenAI 模型列表已刷新: +${added.length} (${added.join(',') || '-'}) / -${removed.length} (${removed.join(',') || '-'}) / 现共 ${registered.size}`);
         }
         else {
-            logger.debug(`OpenAI 模型列表已刷新: 无变化 (共 ${registered.size})`);
+            logger.use.debug(`OpenAI 模型列表已刷新: 无变化 (共 ${registered.size})`);
         }
         return { added, removed, total: registered.size };
     }