@ai-zen/agents-sdk 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/config/migrate.js

@@ -0,0 +1,89 @@
+/**
+ * 配置字段迁移 —— 历史形状升级到当前形状
+ *
+ * 三条遗留字段被淘汰：
+ *
+ * 1. `Model.maxContextTokens` / `Model.maxContextChars` → **`Model.tokenThresholds`**
+ *    旧名字一直在误导：它既不是「模型的真实上下文窗口」，也不是单一概念。现在拆成两条线：
+ *    `handoff`（交接阈值，软线）与 `guard`（强行阻断阈值，硬线）。
+ *    `maxContextChars` 是 token 口径之前的历史遗留，按 `floor(chars / 4)` 折成 tokens
+ *    （与旧代码的回退算法一致）后并入 `handoff`。
+ *
+ * 迁移时机：`ConfigManager.read()` 读出即迁（内存里永远是当前形状）；
+ * 落盘由 `ensureDefaultConfig()` 负责 —— 它比较迁移结果与磁盘原文，不同才写回，
+ * 因此迁移只发生一次，且不会在每次启动时无谓地改写文件。
+ */
+/** 当前字段名 */
+export const TOKEN_THRESHOLDS_KEY = "tokenThresholds";
+/** 已淘汰的旧字段名（仅迁移代码认识它们） */
+export const LEGACY_TOKEN_FIELD = "maxContextTokens";
+export const LEGACY_CHARS_FIELD = "maxContextChars";
+/**
+ * 旧数据缺失阈值时的交接阈值兜底。
+ *
+ * 与 CLI 新建模型的默认值一致；宁可给一个保守值，也不要让模型缺阈值——
+ * 缺阈值意味着既没有交接触发、也没有阻断保护。
+ */
+export const DEFAULT_HANDOFF_THRESHOLD = 128_000;
+function toPositiveInt(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return undefined;
+    return Math.floor(value);
+}
+function readThresholds(value) {
+    if (typeof value !== "object" || value === null)
+        return {};
+    const raw = value;
+    return {
+        handoff: toPositiveInt(raw.handoff),
+        guard: toPositiveInt(raw.guard),
+    };
+}
+/**
+ * 迁移单个模型条目。
+ *
+ * 优先级：已有 `tokenThresholds` 的成员 > 旧 tokens 字段 > 旧 chars 字段折算 > 兜底默认。
+ * 旧字段一律删除（连同一份数据里残留的脏值），保证迁移后的形状唯一。
+ * 已有 `handoff` 但缺 `guard` 时按 1.5 倍补齐。
+ */
+export function migrateModelThresholds(model) {
+    const source = model;
+    const current = readThresholds(source[TOKEN_THRESHOLDS_KEY]);
+    const legacyTokens = toPositiveInt(source[LEGACY_TOKEN_FIELD]);
+    const legacyChars = toPositiveInt(source[LEGACY_CHARS_FIELD]);
+    const legacySingle = toPositiveInt(source.tokenThreshold);
+    const hasLegacy = LEGACY_TOKEN_FIELD in source ||
+        LEGACY_CHARS_FIELD in source ||
+        "tokenThreshold" in source;
+    const complete = current.handoff !== undefined && current.guard !== undefined;
+    if (!hasLegacy && complete)
+        return { model, changed: false };
+    const fromChars = legacyChars !== undefined ? Math.max(1, Math.floor(legacyChars / 4)) : undefined;
+    const handoff = current.handoff ?? legacyTokens ?? fromChars ?? legacySingle ?? DEFAULT_HANDOFF_THRESHOLD;
+    // 旧数据里没有 guard 这一项：按重构前 ContextGuardPlugin 的默认 ratio（1.5）折算一次，
+    // 让迁移后的实际行为与迁移前一致。这是**一次性**换算，落盘后两个值都是整数，
+    // 运行时不再有任何倍数关系（想调硬线就直接改 guard 的数字）。
+    const guard = current.guard ?? Math.round(handoff * 1.5);
+    const next = { ...source };
+    delete next[LEGACY_TOKEN_FIELD];
+    delete next[LEGACY_CHARS_FIELD];
+    delete next.tokenThreshold;
+    next[TOKEN_THRESHOLDS_KEY] = { handoff, guard };
+    return { model: next, changed: true };
+}
+/**
+ * 迁移整个配置。只处理对话模型（`models`）——
+ * 图片模型（`imageModels`）从来没有上下文阈值概念。
+ */
+export function migrateConfig(config) {
+    let changed = false;
+    const models = (config.models ?? []).map((model) => {
+        const result = migrateModelThresholds(model);
+        if (result.changed)
+            changed = true;
+        return result.model;
+    });
+    if (!changed)
+        return { config, changed };
+    return { config: { ...config, models }, changed };
+}

package/dist/config/reasoning-presets.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 思考预设 —— 出厂种子 + 策略表文件名
+ *
+ * 这里的内容只是**初始值**：`ConfigManager.ensureReasoningPresets()` 在首次运行时把它
+ * 写到 `<basePath>/reasoning-presets.json`，之后以磁盘文件为准（用户可改、可加）。
+ * 与 `DEFAULT_APP_CONFIG` 写进 `config.json` 完全同一个套路。
+ *
+ * 为什么档位细节不留在代码里：档位与厂商协议绑定，属于「数据」而非「逻辑」。
+ * 放进用户目录后，厂商新增档位或接入新端点时用户能自己加，不必等 SDK 发版。
+ *
+ * ## 为什么每张表长这样（**全部来自官方文档，不要凭印象改**）
+ *
+ * | 端点 | 官方依据 | 若写错会怎样 |
+ * |------|---------|-------------|
+ * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort`（`none/minimal/low/medium/high/xhigh/max`） | 无 `thinking` 参数，写了会被当未知参数拒绝 → 表里干脆不出现该键 |
+ * | DeepSeek | `api-docs.deepseek.com/guides/thinking_mode` | 可调 `low/high/max`；关闭用 `thinking.type = "disabled"` |
+ * | 智谱 GLM-5.3 系 | `docs.bigmodel.cn/cn/guide/capabilities/thinking` | **只认** `low/high/max`，其余输入报错；**不再支持关闭**（传 disabled 也报错）→ 表里没有 `off` |
+ * | 智谱 GLM-4.7 | 同上 | 强制思考且无 `reasoning_effort` 参数 → 不给它挂策略 |
+ *
+ * 三个结构性保证，都是「表的形状」带来的，不需要任何代码分支：
+ *   1. 可选档位 = `Object.keys(levels)`，不会有「菜单里有、发出去报错」的档位；
+ *   2. 能否关闭思考 = 表里有没有 `off` 键；
+ *   3. 某个键属于思考参数 = 它在表里出现过 —— 写入时按此剔除旧值，不需要硬编码键名。
+ */
+import type { ReasoningPresets } from "../types/index.js";
+/** 策略表文件名（位于 `<basePath>/` 下，与 `config.json` 同级） */
+export declare const REASONING_PRESETS_FILE = "reasoning-presets.json";
+/** 出厂策略表 */
+export declare const FACTORY_REASONING_PRESETS: ReasoningPresets;

package/dist/config/reasoning-presets.js

@@ -0,0 +1,56 @@
+/**
+ * 思考预设 —— 出厂种子 + 策略表文件名
+ *
+ * 这里的内容只是**初始值**：`ConfigManager.ensureReasoningPresets()` 在首次运行时把它
+ * 写到 `<basePath>/reasoning-presets.json`，之后以磁盘文件为准（用户可改、可加）。
+ * 与 `DEFAULT_APP_CONFIG` 写进 `config.json` 完全同一个套路。
+ *
+ * 为什么档位细节不留在代码里：档位与厂商协议绑定，属于「数据」而非「逻辑」。
+ * 放进用户目录后，厂商新增档位或接入新端点时用户能自己加，不必等 SDK 发版。
+ *
+ * ## 为什么每张表长这样（**全部来自官方文档，不要凭印象改**）
+ *
+ * | 端点 | 官方依据 | 若写错会怎样 |
+ * |------|---------|-------------|
+ * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort`（`none/minimal/low/medium/high/xhigh/max`） | 无 `thinking` 参数，写了会被当未知参数拒绝 → 表里干脆不出现该键 |
+ * | DeepSeek | `api-docs.deepseek.com/guides/thinking_mode` | 可调 `low/high/max`；关闭用 `thinking.type = "disabled"` |
+ * | 智谱 GLM-5.3 系 | `docs.bigmodel.cn/cn/guide/capabilities/thinking` | **只认** `low/high/max`，其余输入报错；**不再支持关闭**（传 disabled 也报错）→ 表里没有 `off` |
+ * | 智谱 GLM-4.7 | 同上 | 强制思考且无 `reasoning_effort` 参数 → 不给它挂策略 |
+ *
+ * 三个结构性保证，都是「表的形状」带来的，不需要任何代码分支：
+ *   1. 可选档位 = `Object.keys(levels)`，不会有「菜单里有、发出去报错」的档位；
+ *   2. 能否关闭思考 = 表里有没有 `off` 键；
+ *   3. 某个键属于思考参数 = 它在表里出现过 —— 写入时按此剔除旧值，不需要硬编码键名。
+ */
+/** 策略表文件名（位于 `<basePath>/` 下，与 `config.json` 同级） */
+export const REASONING_PRESETS_FILE = "reasoning-presets.json";
+/** 出厂策略表 */
+export const FACTORY_REASONING_PRESETS = {
+    /** OpenAI 系：只认 `reasoning_effort`；关闭思考 = `"none"` */
+    openai: {
+        levels: {
+            minimal: { reasoning_effort: "minimal" },
+            low: { reasoning_effort: "low" },
+            medium: { reasoning_effort: "medium" },
+            high: { reasoning_effort: "high" },
+            off: { reasoning_effort: "none" },
+        },
+    },
+    /** 智谱 GLM-5.3 / 5.3-Flash / 5.3-FlashX：只认三档，且**不能关闭思考** */
+    "zhipu-5.3": {
+        levels: {
+            low: { thinking: { type: "enabled" }, reasoning_effort: "low" },
+            high: { thinking: { type: "enabled" }, reasoning_effort: "high" },
+            max: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+        },
+    },
+    /** DeepSeek：`thinking` 开关 + `reasoning_effort`，可关闭 */
+    deepseek: {
+        levels: {
+            low: { thinking: { type: "enabled" }, reasoning_effort: "low" },
+            high: { thinking: { type: "enabled" }, reasoning_effort: "high" },
+            max: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+            off: { thinking: { type: "disabled" } },
+        },
+    },
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { PermissionPolicy, AgentPermissions, Endpoint, EndpointCapabilities, Model, ImageModel, AgentDefinition, AppConfig, ToolEnv, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
+export type { PermissionPolicy, AgentPermissions, Endpoint, EndpointCapabilities, Model, TokenThresholds, ReasoningPatch, ReasoningPreset, ReasoningPresets, ImageModel, AgentDefinition, AppConfig, ToolEnv, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
 export { PermissionEvaluator } from "./scope/PermissionEvaluator.js";
 export type { CandidateSets } from "./scope/PermissionEvaluator.js";
 export { createDisclosureParam } from "./scope/disclosure.js";
@@ -21,10 +21,12 @@ export { allInOne } from "./scope/plugins/allInOne.js";
 export type { AllInOneOptions } from "./scope/plugins/allInOne.js";
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
 export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
+export { FACTORY_REASONING_PRESETS, REASONING_PRESETS_FILE, } from "./config/reasoning-presets.js";
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
 export { fileToContentSection, resolveModelAndEndpoint, supportsFilesApi, mimeOf, toDataUrl, base64ByteLength, contentHash, clearUploadCache, MIME_BY_EXT, DEFAULT_MAX_INLINE_BYTES, } from "./shared/content-blocks.js";
 export type { FileSource, FileToSectionInput, FileToSectionResult, ContentTransport, UploadFn, } from "./shared/content-blocks.js";
+export { applyReasoningEffort, modelLevels, presetOf, readReasoningEffort, resolveModelParams, resolveReasoningEffort, } from "./shared/reasoning.js";
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";
 export type { AgentPlugin, SendContext } from "./runtime/SdkAgent.js";

package/dist/index.js

@@ -19,11 +19,15 @@ export { allInOne } from "./scope/plugins/allInOne.js";
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
 // 出厂资产 — 出厂 Skill（随版本释放到 <basePath>/skills/）
 export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
+// 出厂资产 — 出厂思考策略（随版本释放到 <basePath>/reasoning-presets.json）
+export { FACTORY_REASONING_PRESETS, REASONING_PRESETS_FILE, } from "./config/reasoning-presets.js";
 // CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
 // 文件 → 内容块（统一入口）— 上层应用构造媒体消息时请走这里，不要自己判断上传还是内联
 export { fileToContentSection, resolveModelAndEndpoint, supportsFilesApi, mimeOf, toDataUrl, base64ByteLength, contentHash, clearUploadCache, MIME_BY_EXT, DEFAULT_MAX_INLINE_BYTES, } from "./shared/content-blocks.js";
+// 思考预设（reasoning presets）— 档位读取、校验与参数写入
+export { applyReasoningEffort, modelLevels, presetOf, readReasoningEffort, resolveModelParams, resolveReasoningEffort, } from "./shared/reasoning.js";
 // 运行时
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";

package/dist/runtime/HandoffService.d.ts

@@ -37,7 +37,7 @@ export interface HandoffContext {
     /** 当前 prompt token 用量（自动迁移时由插件提供；手动触发可省略） */
     promptTokens?: number;
     /** 上下文阈值（自动迁移时由插件提供；手动触发可省略） */
-    maxTokens?: number;
+    handoffTokens?: number;
     /** 本次是否会在交接后开新会话（`migrate()` 为 true，`handoff()` 为 false）。钩子据此区分两种语义 */
     migrating: boolean;
     /** 交接前消息总数 */
@@ -83,7 +83,7 @@ export interface HandoffParams {
     /** 当前 prompt token 用量（可选，仅透传给钩子） */
     promptTokens?: number;
     /** 上下文阈值（可选，仅透传给钩子） */
-    maxTokens?: number;
+    handoffTokens?: number;
     /** 会话 id（可选，用于交接文件名，便于回溯） */
     conversationId?: string;
 }

package/dist/runtime/HandoffService.js

@@ -194,7 +194,7 @@ export class HandoffService {
         }
     }
     async runHandoff(params, migrating) {
-        const { agent, promptTokens, maxTokens, conversationId } = params;
+        const { agent, promptTokens, handoffTokens, conversationId } = params;
         const requestedMode = params.mode ?? this.defaultMode;
         const handoffPath = join(this.handoffDirPath, HandoffService.createHandoffFileName(new Date(), conversationId));
         const model = this.model ?? agent.model;
@@ -207,7 +207,7 @@ export class HandoffService {
             handoffPath,
             model,
             promptTokens,
-            maxTokens,
+            handoffTokens,
             migrating,
             messageCountBefore,
             historyText: "",
@@ -241,7 +241,7 @@ export class HandoffService {
             handoffDoc,
             model,
             promptTokens,
-            maxTokens,
+            handoffTokens,
             migrating,
             messageCountBefore,
             historyText,

package/dist/runtime/createAgent.js

@@ -18,7 +18,10 @@ export async function createAgent(scope, agentId) {
     const modelId = definition.modelId ?? scope.config.defaultModel;
     if (!modelId)
         throw new Error("未指定模型且无默认模型");
-    const { client, model, modelConfig } = createModel(scope, modelId);
+    const { client, model, modelConfig } = createModel(scope, modelId, {
+        // Agent 级思考档位覆盖（未声明时为 undefined，行为与以前一致）
+        reasoningEffort: definition.reasoningEffort,
+    });
     const tools = scope.buildTools(definition, {
         exclude: {
             subagents: definition.function?.name

package/dist/runtime/createModel.d.ts

@@ -1,5 +1,6 @@
 import OpenAI from "openai";
 import type { Scope } from "../scope/Scope.js";
+import type { AgentDefinition } from "../types/index.js";
 /**
  * Agent 模型装配结果：openai SDK client + 模型名 + 模型参数。
  * Agent 构造时直接消费此结构。
@@ -17,5 +18,10 @@ export interface AgentModel {
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
+ *
+ * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
+ * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
+ * 档位如何翻译成请求参数，由 `scope.reasoningPresets` 里该模型引用的策略表决定
+ * （见 `shared/reasoning.ts`）。
  */
-export declare function createModel(scope: Scope, modelId: string): AgentModel;
+export declare function createModel(scope: Scope, modelId: string, overrides?: Pick<AgentDefinition, "reasoningEffort">): AgentModel;

package/dist/runtime/createModel.js

@@ -1,11 +1,17 @@
 import OpenAI from "openai";
+import { resolveModelParams } from "../shared/reasoning.js";
 /**
  * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
+ *
+ * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
+ * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
+ * 档位如何翻译成请求参数，由 `scope.reasoningPresets` 里该模型引用的策略表决定
+ * （见 `shared/reasoning.ts`）。
  */
-export function createModel(scope, modelId) {
+export function createModel(scope, modelId, overrides) {
     const config = scope.config;
     const modelConfig = config.models.find((m) => m.id === modelId);
     if (!modelConfig)
@@ -25,6 +31,7 @@ export function createModel(scope, modelId) {
     return {
         client,
         model: apiModelName,
-        modelConfig: modelConfig.defaultParams,
+        // 档位覆盖在这里生效：未声明 reasoningEffort 时原样返回模型 defaultParams
+        modelConfig: resolveModelParams(modelConfig, scope.reasoningPresets, overrides),
     };
 }

package/dist/scope/Scope.d.ts

@@ -1,5 +1,5 @@
 import type { Tool } from "@ai-zen/agents-core";
-import type { AppConfig, AgentDefinition, ToolEnv } from "../types/index.js";
+import type { AppConfig, AgentDefinition, ReasoningPresets, ToolEnv } from "../types/index.js";
 import type { ScopePlugin } from "./ScopePlugin.js";
 /**
  * 能力过滤系统的公共类型。
@@ -56,6 +56,13 @@ export declare class Scope {
     readonly env: ToolEnv;
     /** Agent 定义目录（createAgent 用） */
     readonly agentsDir: string;
+    /**
+     * 思考策略表（`<basePath>/reasoning-presets.json`）。
+     *
+     * 与 `config` 平级、同样由调用方加载后注入：`createModel` 靠它把 Agent 的
+     * `reasoningEffort` 翻译成具体请求参数。不传则视为「无任何可选档位」。
+     */
+    readonly reasoningPresets: ReasoningPresets;
     /** 已注册的插件 */
     private _plugins;
     /** 是否已 init（init 之后禁止再 use） */
@@ -64,6 +71,7 @@ export declare class Scope {
         config: AppConfig;
         agentsDir: string;
         cwd?: string;
+        reasoningPresets?: ReasoningPresets;
     });
     /** 已注册插件（只读视图） */
     get plugins(): readonly ScopePlugin[];

package/dist/scope/Scope.js

@@ -29,12 +29,20 @@ export class Scope {
     env;
     /** Agent 定义目录（createAgent 用） */
     agentsDir;
+    /**
+     * 思考策略表（`<basePath>/reasoning-presets.json`）。
+     *
+     * 与 `config` 平级、同样由调用方加载后注入：`createModel` 靠它把 Agent 的
+     * `reasoningEffort` 翻译成具体请求参数。不传则视为「无任何可选档位」。
+     */
+    reasoningPresets;
     /** 已注册的插件 */
     _plugins = [];
     /** 是否已 init（init 之后禁止再 use） */
     _initialized = false;
     constructor(options) {
         this.config = options.config;
+        this.reasoningPresets = options.reasoningPresets ?? {};
         this.cwd = options.cwd ?? process.cwd();
         this.env = { cwd: this.cwd, config: this.config };
         this.agentsDir = options.agentsDir;

package/dist/shared/errors.d.ts

@@ -8,17 +8,13 @@ export declare class SdkError extends Error {
 }
 /**
  * 上下文超限错误。由 ContextGuardPlugin 在请求前抛出，用于中断对话。
- * 触发条件通常是上下文 token 用量远超阈值（如读入超大文件），
+ * 触发条件通常是上下文 token 用量超过硬线（如读入超大文件），
  * 继续对话已无意义且会持续放大费用/延迟，故由上层捕获后向用户显式报错。
  */
 export declare class ContextOverflowError extends Error {
     /** 触发中断时的刚用量（usage.prompt_tokens） */
     readonly promptTokens: number;
-    /** 配置的告警阈值（maxTokens） */
-    readonly maxTokens: number;
-    /** 实际生效的硬上限（maxTokens × ratio，越界即中断） */
-    readonly threshold: number;
-    /** 超出比例（如 1.2 表示 20%） */
-    readonly ratio: number;
-    constructor(promptTokens: number, maxTokens: number, ratio: number);
+    /** 被越过的强行阻断阈值（`tokenThresholds.guard`，绝对值） */
+    readonly guardTokens: number;
+    constructor(promptTokens: number, guardTokens: number);
 }

package/dist/shared/errors.js

@@ -15,26 +15,20 @@ export class SdkError extends Error {
 }
 /**
  * 上下文超限错误。由 ContextGuardPlugin 在请求前抛出，用于中断对话。
- * 触发条件通常是上下文 token 用量远超阈值（如读入超大文件），
+ * 触发条件通常是上下文 token 用量超过硬线（如读入超大文件），
  * 继续对话已无意义且会持续放大费用/延迟，故由上层捕获后向用户显式报错。
  */
 export class ContextOverflowError extends Error {
     /** 触发中断时的刚用量（usage.prompt_tokens） */
     promptTokens;
-    /** 配置的告警阈值（maxTokens） */
-    maxTokens;
-    /** 实际生效的硬上限（maxTokens × ratio，越界即中断） */
-    threshold;
-    /** 超出比例（如 1.2 表示 20%） */
-    ratio;
-    constructor(promptTokens, maxTokens, ratio) {
-        const threshold = maxTokens * ratio;
-        super(`🛑 上下文严重超限：已用 ${promptTokens} token，超过硬上限 ${threshold}（${Math.round((ratio - 1) * 100)}%，配置上限 ${maxTokens}）。` +
-            `当前对话可能因读入超大文件而失控，已中断，请检查并重新开始。`);
+    /** 被越过的强行阻断阈值（`tokenThresholds.guard`，绝对值） */
+    guardTokens;
+    constructor(promptTokens, guardTokens) {
+        super(`🛑 上下文严重超限：已用 ${promptTokens} token，超过阻断阈值 ${guardTokens}。` +
+            `当前对话可能因读入超大文件而失控，已中断，请检查并重新开始。` +
+            `（如确需更长上下文，请调高 config.json 中该模型的 tokenThresholds.guard。）`);
         this.name = "ContextOverflowError";
         this.promptTokens = promptTokens;
-        this.maxTokens = maxTokens;
-        this.threshold = threshold;
-        this.ratio = ratio;
+        this.guardTokens = guardTokens;
     }
 }

package/dist/shared/reasoning.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 思考预设（reasoning presets）—— 档位读取、校验与参数写入的唯一实现
+ *
+ * ## 为什么是「表」而不是「字段」
+ *
+ * 档位不是全局统一枚举：各端点接受的值域互不相同，同一家不同型号也不同
+ * （见 `config/reasoning-presets.ts` 的文档表）。所以本模块不判断「厂商是谁」，
+ * 只做一件事：**在模型关联的那张策略表里查档位、写补丁**。
+ *
+ * 于是三个问题都变成查表，不需要任何 if/else 分支：
+ *   1. 可选档位有哪些？      → `Object.keys(preset.levels)`
+ *   2. 能不能关闭思考？      → 表里有没有 `off` 键
+ *   3. 哪些参数键属于思考？  → 所有补丁里出现过的键的并集（写入前先剔除）
+ *
+ * 第 3 条是关键：有了它，从 `max` 切到 `off` 不会残留上一档的参数，而代码里
+ * 一个键名都不必硬编码（`thinking` / `reasoning_effort` 只出现在策略表里）。
+ */
+import type { AgentDefinition, Model, ReasoningPreset, ReasoningPresets } from "../types/index.js";
+/**
+ * 模型关联的策略（未声明 `reasoningPreset`、或名字在表里不存在 → `undefined`）。
+ *
+ * 名字不存在时**不猜、不兜底**：宁可视作不可调档，也不把来路不明的参数发给服务端。
+ */
+export declare function presetOf(model?: Model | null, presets?: ReasoningPresets | null): ReasoningPreset | undefined;
+/**
+ * 模型可选的全部档位（顺序 = 策略表声明顺序）。
+ *
+ * 不再区分「档位」与「关闭」：表里的键就是菜单里的项。未关联策略 → 空数组。
+ */
+export declare function modelLevels(model?: Model | null, presets?: ReasoningPresets | null): string[];
+/**
+ * 反查当前档位：参数里命中哪个补丁的键值，就是哪一档。
+ *
+ * 与 `applyReasoningEffort()` 互为逆运算，两边共用同一张表。
+ * 多张补丁同时命中时取**最具体**的那个（键最多的），键数相同取先声明的。
+ *
+ * 返回 `undefined` = 参数不完整匹配任何档位（例如 DeepSeek 出厂只写了
+ * `thinking: { type: "enabled" }` 而没写 effort），展示层应视为「跟随模型默认」。
+ */
+export declare function readReasoningEffort(model?: Model | null, presets?: ReasoningPresets | null, params?: Record<string, unknown> | null): string | undefined;
+/**
+ * 把档位写成请求参数（不改入参）。
+ *
+ * 写入方式 = **先剔除思考参数键的旧值，再合并新补丁**。这样 `max` → `off` 不会残留
+ * 上一档的 `reasoning_effort`，模型换策略也不会反刍旧策略的参数，而「哪些键属于思考」
+ * 由策略表自己声明，代码零硬编码。
+ *
+ * @throws 模型未关联策略、或策略里没有该档位（绝不静默降级：档位写错必须当场发现）
+ */
+export declare function applyReasoningEffort(model: Model | null | undefined, presets: ReasoningPresets | null | undefined, level: string, params?: Record<string, unknown> | null): Record<string, unknown>;
+/**
+ * 解析某 Agent 的实际档位：Agent 声明优先，否则反查模型默认参数。
+ *
+ * 声明了但策略里没有这一档 → 退化为模型默认（宁可忽略设置，也不发非法参数）。
+ */
+export declare function resolveReasoningEffort(model?: Model | null, presets?: ReasoningPresets | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): string | undefined;
+/**
+ * 把 Agent 的档位覆盖应用到模型参数上（`createModel` 用）。
+ *
+ * 未声明 `reasoningEffort` 时原样返回模型参数，保证既有行为不变。
+ */
+export declare function resolveModelParams(model?: Model | null, presets?: ReasoningPresets | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): Record<string, unknown> | undefined;

package/dist/shared/reasoning.js

@@ -0,0 +1,159 @@
+/**
+ * 思考预设（reasoning presets）—— 档位读取、校验与参数写入的唯一实现
+ *
+ * ## 为什么是「表」而不是「字段」
+ *
+ * 档位不是全局统一枚举：各端点接受的值域互不相同，同一家不同型号也不同
+ * （见 `config/reasoning-presets.ts` 的文档表）。所以本模块不判断「厂商是谁」，
+ * 只做一件事：**在模型关联的那张策略表里查档位、写补丁**。
+ *
+ * 于是三个问题都变成查表，不需要任何 if/else 分支：
+ *   1. 可选档位有哪些？      → `Object.keys(preset.levels)`
+ *   2. 能不能关闭思考？      → 表里有没有 `off` 键
+ *   3. 哪些参数键属于思考？  → 所有补丁里出现过的键的并集（写入前先剔除）
+ *
+ * 第 3 条是关键：有了它，从 `max` 切到 `off` 不会残留上一档的参数，而代码里
+ * 一个键名都不必硬编码（`thinking` / `reasoning_effort` 只出现在策略表里）。
+ */
+/** 安全取自有属性（策略名源自用户配置，可能是 `constructor` / `__proto__` 等） */
+function own(bag, key) {
+    if (!bag || !Object.prototype.hasOwnProperty.call(bag, key))
+        return undefined;
+    return bag[key];
+}
+/** 结构化相等 —— 补丁是纯 JSON，逐层比对即可 */
+function sameValue(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const left = a;
+    const right = b;
+    const leftKeys = Object.keys(left);
+    if (leftKeys.length !== Object.keys(right).length)
+        return false;
+    return leftKeys.every((k) => Object.prototype.hasOwnProperty.call(right, k) && sameValue(left[k], right[k]));
+}
+/**
+ * 模型关联的策略（未声明 `reasoningPreset`、或名字在表里不存在 → `undefined`）。
+ *
+ * 名字不存在时**不猜、不兜底**：宁可视作不可调档，也不把来路不明的参数发给服务端。
+ */
+export function presetOf(model, presets) {
+    const name = model?.reasoningPreset;
+    if (!name)
+        return undefined;
+    return own(presets ?? undefined, name);
+}
+/**
+ * 模型可选的全部档位（顺序 = 策略表声明顺序）。
+ *
+ * 不再区分「档位」与「关闭」：表里的键就是菜单里的项。未关联策略 → 空数组。
+ */
+export function modelLevels(model, presets) {
+    const preset = presetOf(model, presets);
+    if (!preset)
+        return [];
+    return Object.keys(preset.levels ?? {});
+}
+/**
+ * 「思考参数键」的全集 —— **整张策略表**里任何补丁出现过的键。
+ *
+ * 用整张表而非单个策略，是为了让换策略时不留残渣：模型从 `deepseek` 改挂 `openai`
+ * 时，旧策略写进去的 `thinking` 也必须被清掉（OpenAI 不认这个参数，带着就 400）。
+ * 好处依旧：键名一个都不用在代码里硬编码，全部由表声明。
+ */
+function ownedKeys(presets) {
+    const keys = new Set();
+    for (const preset of Object.values(presets ?? {})) {
+        for (const patch of Object.values(preset?.levels ?? {})) {
+            for (const key of Object.keys(patch ?? {}))
+                keys.add(key);
+        }
+    }
+    return keys;
+}
+/**
+ * 反查当前档位：参数里命中哪个补丁的键值，就是哪一档。
+ *
+ * 与 `applyReasoningEffort()` 互为逆运算，两边共用同一张表。
+ * 多张补丁同时命中时取**最具体**的那个（键最多的），键数相同取先声明的。
+ *
+ * 返回 `undefined` = 参数不完整匹配任何档位（例如 DeepSeek 出厂只写了
+ * `thinking: { type: "enabled" }` 而没写 effort），展示层应视为「跟随模型默认」。
+ */
+export function readReasoningEffort(model, presets, params) {
+    const preset = presetOf(model, presets);
+    if (!preset)
+        return undefined;
+    // 显式传 null = 「没有参数」，不回落模型默认；不传才读模型默认
+    const actual = params === undefined ? model?.defaultParams : params;
+    if (!actual)
+        return undefined;
+    let best;
+    let bestSize = 0;
+    for (const [level, patch] of Object.entries(preset.levels ?? {})) {
+        const keys = Object.keys(patch ?? {});
+        if (keys.length === 0 || keys.length <= bestSize)
+            continue;
+        if (!keys.every((k) => sameValue(actual[k], patch[k])))
+            continue;
+        best = level;
+        bestSize = keys.length;
+    }
+    return best;
+}
+/**
+ * 把档位写成请求参数（不改入参）。
+ *
+ * 写入方式 = **先剔除思考参数键的旧值，再合并新补丁**。这样 `max` → `off` 不会残留
+ * 上一档的 `reasoning_effort`，模型换策略也不会反刍旧策略的参数，而「哪些键属于思考」
+ * 由策略表自己声明，代码零硬编码。
+ *
+ * @throws 模型未关联策略、或策略里没有该档位（绝不静默降级：档位写错必须当场发现）
+ */
+export function applyReasoningEffort(model, presets, level, params) {
+    const id = model?.id ?? "(未知)";
+    const name = model?.reasoningPreset;
+    const preset = presetOf(model, presets);
+    if (!preset) {
+        throw new Error(name
+            ? `模型 "${id}" 关联的思考策略 "${name}" 不存在（检查 reasoning-presets.json）`
+            : `模型 "${id}" 未关联思考策略（reasoningPreset），无法设置档位`);
+    }
+    const patch = own(preset.levels, level);
+    if (!patch) {
+        throw new Error(`策略 "${name}" 没有档位 "${level}"（可选：${Object.keys(preset.levels).join(" / ")}）`);
+    }
+    const owned = ownedKeys(presets);
+    const base = params === undefined ? model?.defaultParams : params;
+    const kept = Object.entries(base ?? {}).filter(([key]) => !owned.has(key));
+    return { ...Object.fromEntries(kept), ...patch };
+}
+/**
+ * 解析某 Agent 的实际档位：Agent 声明优先，否则反查模型默认参数。
+ *
+ * 声明了但策略里没有这一档 → 退化为模型默认（宁可忽略设置，也不发非法参数）。
+ */
+export function resolveReasoningEffort(model, presets, definition) {
+    const declared = definition?.reasoningEffort;
+    if (declared && modelLevels(model, presets).includes(declared))
+        return declared;
+    return readReasoningEffort(model, presets);
+}
+/**
+ * 把 Agent 的档位覆盖应用到模型参数上（`createModel` 用）。
+ *
+ * 未声明 `reasoningEffort` 时原样返回模型参数，保证既有行为不变。
+ */
+export function resolveModelParams(model, presets, definition) {
+    const declared = definition?.reasoningEffort;
+    if (!declared)
+        return model?.defaultParams;
+    // 模型没关联策略、或策略里没这一档：保持模型默认，绝不发非法参数
+    if (!modelLevels(model, presets).includes(declared))
+        return model?.defaultParams;
+    return applyReasoningEffort(model, presets, declared);
+}