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

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [1.0.0-alpha.14] - 2026-10-22
+
+### 🔧 行为变更（不兼容）
+
+- **思考能力声明从「模型字段」改为「策略表」** —— alpha.13 那版用 `Model.reasoning: { efforts, disable? }` 表达厂商差异，结果三处结构性缺陷：`disable` 一词双义（既指关闭方式又指能力）、`off` 靠拼接而非声明（`disable ? ["off", ...efforts] : efforts`）、用全局 `ReasoningEffort` 枚举假装各家档位等价。现在改为**档位 → 请求参数补丁**的声明式表：
+  - 新增 `<basePath>/reasoning-presets.json`（与 `config.json` 同级），出厂内容见 `config/reasoning-presets.ts`；
+  - `Model.reasoning?` → **`Model.reasoningPreset?: string`**（引用策略名；缺省 = 不可调档）；
+  - `AgentDefinition.reasoningEffort` 类型 `ReasoningEffort` → **`string`**（档位名由策略表定义，不再用假枚举假装统一）；
+  - 删除 `ReasoningEffort` / `ReasoningCapability` 类型与 `capabilityOf` / `modelEfforts` / `modelAllowedEfforts` / `isReasoningEffort` 函数；
+  - 函数签名统一以 `(model, presets, …)` 开头：`readReasoningEffort(model, presets, params?)`、`applyReasoningEffort(model, presets, level, params?)`、`resolveReasoningEffort(model, presets, definition?)`、`resolveModelParams(model, presets, definition?)`；
+  - `Scope` 新增 `reasoningPresets`（与 `config` 平级注入，不做全局单例）。
+
+  换来三个结构性保证，全部来自表的形状、代码零分支：① 可选档位 = `Object.keys(levels)`；② 能否关闭思考 = 表里有没有 `off` 键；③ 「哪些参数键属于思考」= 整张表出现过的键的并集（写入前按此剔除旧值，`max` → `off` 不再残留 `reasoning_effort`，模型换策略也不会反刍上一套参数）。
+
+- **`applyReasoningEffort` 的档位校验更严** —— 策略里没有该档位直接抛错（旧版对未声明能力的模型给的是「不支持档位」文案），错误信息带上策略名与可选档位列表。
+
+### 🚀 新功能
+
+- **`ConfigManager.readReasoningPresets()` / `ensureReasoningPresets()`** —— 策略表的读写与出厂同步。同步粒度**到单个策略**，规则与出厂模型同步同构：文件缺失即写种子；`custom: true` 的策略冻结；未标的用出厂版覆盖；用户自建的非出厂策略永远保留。`bootstrap()` 会自动调用。文件缺失或损坏时 `readReasoningPresets()` 回落到出厂种子，不让上层拿到空表。
+- **`presetOf(model, presets)` / `modelLevels(model, presets)`** —— 策略查找与可选档位读取（`modelLevels` 取代旧的 `modelEfforts` + `modelAllowedEfforts` 两个函数：`off` 现在只是表里的一行，没有「档位」与「关闭」的二分）。
+- **包入口补导出 `TokenThresholds` / `ReasoningPatch` / `ReasoningPreset` / `ReasoningPresets`** —— alpha.13 漏了这几个类型的导出（原 `7b10196` 补丁并入本版本）。
+
+### ✅ 测试
+
+- `src/shared/reasoning.test.ts` 重写（26 例）：出厂表协议事实（OpenAI 表无 `thinking` 键、`zhipu-5.3` 表无 `off`、DeepSeek 用 `thinking.type` 关闭）、可调档位 = 表的键、反查取最具体匹配、写入剔除旧键、往返一致、Agent 声明非法回退模型默认、原型链污染名字（`constructor`）不生效。
+- `src/config/reasoning-presets.test.ts` 新增（11 例）：落盘位置、首次释放、幂等不写盘、未标 `custom` 被覆盖、标了 `custom` 冻结、用户自建策略保留、损坏/数组内容回落种子、`bootstrap()` 顺带释放。
+
+### 📄 文档
+
+- `docs/{zh,en}/sdk.md`：「思考强度」章节重写为「思考预设（reasoning presets）」，含策略表结构、出厂策略对照表、三个结构性保证、新 API 表与 `Scope` 注入示例。
+- 顺手修掉 alpha.13 之后就过期的示例：`ContextGuardPlugin({ maxTokens, isSuspended })` → `{ guardTokens }`、`AutoMigratePlugin({ maxTokens })` → `{ handoffTokens }`、「交接回合护栏放宽 × 2」的旧描述。
+
 ## [1.0.0-alpha.13] - 2026-10-22
 
 ### 💥 Breaking Changes

package/dist/config/ConfigManager.d.ts

@@ -1,4 +1,4 @@
-import type { AppConfig, AgentDefinition } from "../types/index.js";
+import type { AppConfig, AgentDefinition, ReasoningPresets } from "../types/index.js";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
@@ -58,6 +58,27 @@ export declare class ConfigManager {
         agent: AgentDefinition | null;
         subAgent: AgentDefinition | null;
     }>;
+    /** 策略表文件路径（与 config.json 同级） */
+    get reasoningPresetsPath(): string;
+    /**
+     * 读取思考策略表。
+     *
+     * 文件缺失或无法解析时返回出厂种子（内存值，不写盘）——保证调用方永远拿到可用的表：
+     * 用户误删文件后仍能正常选档位，下次 `ensureReasoningPresets()` 会重新释放。
+     */
+    readReasoningPresets(): Promise<ReasoningPresets>;
+    /**
+     * 释放 / 同步出厂思考策略。
+     *
+     * 覆盖策略与 `syncManagedModels` 同构，**按策略逐个判断**（粒度到单个策略）：
+     *   - 文件不存在 → 写入出厂种子；
+     *   - 某策略标了 `custom: true` → 用户自有，原样保留；
+     *   - 某策略未标 → 用出厂版覆盖该策略（内容相同则不写盘）；
+     *   - 用户自建的非出厂策略 → 始终保留。
+     *
+     * @returns 实际写入的策略名列表（未变化 / 用户自有 均不计入）
+     */
+    ensureReasoningPresets(): Promise<string[]>;
     /**
      * 释放 / 同步出厂 Skill。
      *

package/dist/config/ConfigManager.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import { dirname, join } from "node:path";
 import { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
 import { FACTORY_SKILLS, isCustomSkill } from "./factory-skills.js";
+import { FACTORY_REASONING_PRESETS, REASONING_PRESETS_FILE, } from "./reasoning-presets.js";
 import { migrateConfig } from "./migrate.js";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
@@ -188,9 +189,75 @@ export class ConfigManager {
         const subAgent = await this.ensureDefaultSubAgent();
         await this.ensureDefaultMcpConfig();
         await this.ensureFactorySkills();
+        await this.ensureReasoningPresets();
         return { config, agent, subAgent };
     }
     // -----------------------------------------------------------------------
+    // 思考策略表（{basePath}/reasoning-presets.json）
+    // -----------------------------------------------------------------------
+    /** 策略表文件路径（与 config.json 同级） */
+    get reasoningPresetsPath() {
+        return join(this.basePath, REASONING_PRESETS_FILE);
+    }
+    /**
+     * 读取思考策略表。
+     *
+     * 文件缺失或无法解析时返回出厂种子（内存值，不写盘）——保证调用方永远拿到可用的表：
+     * 用户误删文件后仍能正常选档位，下次 `ensureReasoningPresets()` 会重新释放。
+     */
+    async readReasoningPresets() {
+        try {
+            const raw = await fs.readFile(this.reasoningPresetsPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // 缺失或损坏 → 回落出厂种子
+        }
+        return { ...FACTORY_REASONING_PRESETS };
+    }
+    /**
+     * 释放 / 同步出厂思考策略。
+     *
+     * 覆盖策略与 `syncManagedModels` 同构，**按策略逐个判断**（粒度到单个策略）：
+     *   - 文件不存在 → 写入出厂种子；
+     *   - 某策略标了 `custom: true` → 用户自有，原样保留；
+     *   - 某策略未标 → 用出厂版覆盖该策略（内容相同则不写盘）；
+     *   - 用户自建的非出厂策略 → 始终保留。
+     *
+     * @returns 实际写入的策略名列表（未变化 / 用户自有 均不计入）
+     */
+    async ensureReasoningPresets() {
+        let onDisk = null;
+        try {
+            onDisk = JSON.parse(await fs.readFile(this.reasoningPresetsPath, "utf-8"));
+        }
+        catch {
+            onDisk = null;
+        }
+        if (!onDisk || typeof onDisk !== "object" || Array.isArray(onDisk)) {
+            await fs.mkdir(this.basePath, { recursive: true });
+            await fs.writeFile(this.reasoningPresetsPath, JSON.stringify(FACTORY_REASONING_PRESETS, null, 2), "utf-8");
+            return Object.keys(FACTORY_REASONING_PRESETS);
+        }
+        const next = { ...onDisk };
+        const written = [];
+        for (const [name, preset] of Object.entries(FACTORY_REASONING_PRESETS)) {
+            const existing = onDisk[name];
+            if (existing?.custom === true)
+                continue; // 用户改过 → 冻结
+            if (JSON.stringify(existing) === JSON.stringify(preset))
+                continue; // 已是最新
+            next[name] = preset;
+            written.push(name);
+        }
+        if (written.length > 0) {
+            await fs.writeFile(this.reasoningPresetsPath, JSON.stringify(next, null, 2), "utf-8");
+        }
+        return written;
+    }
+    // -----------------------------------------------------------------------
     // 出厂 Skill（{basePath}/skills/<id>/SKILL.md）
     // -----------------------------------------------------------------------
     /**

package/dist/config/constants.js

@@ -103,15 +103,10 @@ export const DEFAULT_APP_CONFIG = {
     // 出厂取值：窗口 ≥1M 的模型统一 handoff=250K / guard=375K（约窗口的 25% / 37.5%），
     // glm-4.7-flash 窗口仅 200K，取 handoff=100K / guard=150K。
     //
-    // reasoning（思考强度能力）按厂商官方文档声明，**不要推测**：
-    //   OpenAI   → openai-node 的 Shared.ReasoningEffort（none/minimal/low/medium/high/xhigh/max）；
-    //              关闭用 reasoning_effort:"none"（OpenAI 没有 thinking 参数，写它会被当未知参数）
-    //   DeepSeek → api-docs.deepseek.com/guides/thinking_mode：可调 low/high/max；
-    //              关闭用 thinking.type:"disabled"；默认开思考且默认 effort=high
-    //   智谱     → docs.bigmodel.cn/cn/guide/capabilities/thinking：GLM-5.3 系**只认**
-    //              low/high/max（其余输入报错），且不再支持关闭思考（传 disabled 会报错）；
-    //              GLM-4.7 强制思考且无 reasoning_effort 参数（仅 5.2+ 支持）
-    // 未声明 reasoning 的模型 = 不可调档，`modelAllowedEfforts()` 返回空数组。
+    // reasoningPreset：思考策略名，引用 `<basePath>/reasoning-presets.json` 里的键
+    // （出厂内容见 `config/reasoning-presets.ts`，档位的协议差异全部写在表里）。
+    // 不写这个字段 = 不可调档（如 GLM-4.7 强制思考且无 reasoning_effort 参数）。
+    // 新接入端点时先在策略表里加一张表，再在这里引用它的名字。
     models: [
         // ---------- OpenAI ----------
         {
@@ -122,7 +117,7 @@ export const DEFAULT_APP_CONFIG = {
             tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: {},
             vision: true,
-            reasoning: { efforts: ["minimal", "low", "medium", "high"], disable: "effort-none" },
+            reasoningPreset: "openai",
             description: "OpenAI 最强旗舰（2026-09）：高级分析、软件工程、深度研究与科学工作",
         },
         {
@@ -133,7 +128,7 @@ export const DEFAULT_APP_CONFIG = {
             tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: {},
             vision: true,
-            reasoning: { efforts: ["minimal", "low", "medium", "high"], disable: "effort-none" },
+            reasoningPreset: "openai",
             description: "OpenAI 最新旗舰（2026-09-29）：Agentic Coding、计算机操作与文档密集型专业任务",
         },
         {
@@ -144,7 +139,7 @@ export const DEFAULT_APP_CONFIG = {
             tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: {},
             vision: true,
-            reasoning: { efforts: ["minimal", "low", "medium", "high"], disable: "effort-none" },
+            reasoningPreset: "openai",
             description: "OpenAI GPT-6 系列快速低成本模型：适合高吞吐、低延迟场景",
         },
         // ---------- 智谱 BigModel ----------
@@ -155,7 +150,7 @@ export const DEFAULT_APP_CONFIG = {
             modelName: "glm-5.3",
             tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
-            reasoning: { efforts: ["low", "high", "max"] },
+            reasoningPreset: "zhipu-5.3",
             description: "智谱最新旗舰：复杂软件工程与长程 Agent 任务（强制开启思考，1M 上下文）",
         },
         {
@@ -166,7 +161,7 @@ export const DEFAULT_APP_CONFIG = {
             tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
             vision: true,
-            reasoning: { efforts: ["low", "high", "max"] },
+            reasoningPreset: "zhipu-5.3",
             description: "智谱原生多模态模型（图片/视频/文件）：视觉 Coding，1M 上下文",
         },
         {
@@ -177,7 +172,7 @@ export const DEFAULT_APP_CONFIG = {
             tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
             vision: true,
-            reasoning: { efforts: ["low", "high", "max"] },
+            reasoningPreset: "zhipu-5.3",
             description: "GLM-5.3-Flash 高速版（200 tokens/s），原生多模态",
         },
         {
@@ -188,7 +183,6 @@ export const DEFAULT_APP_CONFIG = {
             // 该模型真实窗口仅 200K，阈值下调至 100K（约窗口的 50%），留足 response 空间
             tokenThresholds: { handoff: 100_000, guard: 150_000 },
             defaultParams: {},
-            reasoning: { efforts: [] },
             description: "智谱免费文本模型：200K 上下文，适合轻量任务",
         },
         // ---------- DeepSeek ----------
@@ -200,7 +194,7 @@ export const DEFAULT_APP_CONFIG = {
             tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" } },
             vision: true,
-            reasoning: { efforts: ["low", "high", "max"], disable: "thinking" },
+            reasoningPreset: "deepseek",
             description: "DeepSeek 旗舰（2026-09-10）：552B MoE 非对称架构，原生多模态，1M 上下文",
         },
     ],

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,11 +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, capabilityOf, isReasoningEffort, modelAllowedEfforts, modelEfforts, readReasoningEffort, resolveModelParams, resolveReasoningEffort, } from "./shared/reasoning.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,13 +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 effort）— 能力声明、可用档位与参数写入
-export { applyReasoningEffort, capabilityOf, isReasoningEffort, modelAllowedEfforts, modelEfforts, readReasoningEffort, resolveModelParams, resolveReasoningEffort, } from "./shared/reasoning.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/createModel.d.ts

@@ -21,6 +21,7 @@ export interface AgentModel {
  *
  * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
  * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
- * 写入方式按模型的 `reasoning` 能力声明决定（见 `shared/reasoning.ts`）。
+ * 档位如何翻译成请求参数，由 `scope.reasoningPresets` 里该模型引用的策略表决定
+ * （见 `shared/reasoning.ts`）。
  */
 export declare function createModel(scope: Scope, modelId: string, overrides?: Pick<AgentDefinition, "reasoningEffort">): AgentModel;

package/dist/runtime/createModel.js

@@ -8,7 +8,8 @@ import { resolveModelParams } from "../shared/reasoning.js";
  *
  * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
  * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
- * 写入方式按模型的 `reasoning` 能力声明决定（见 `shared/reasoning.ts`）。
+ * 档位如何翻译成请求参数，由 `scope.reasoningPresets` 里该模型引用的策略表决定
+ * （见 `shared/reasoning.ts`）。
  */
 export function createModel(scope, modelId, overrides) {
     const config = scope.config;
@@ -31,6 +32,6 @@ export function createModel(scope, modelId, overrides) {
         client,
         model: apiModelName,
         // 档位覆盖在这里生效：未声明 reasoningEffort 时原样返回模型 defaultParams
-        modelConfig: resolveModelParams(modelConfig, overrides),
+        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/reasoning.d.ts

@@ -1,64 +1,62 @@
 /**
- * 思考强度（reasoning effort）—— 能力声明、可用档位与参数写入的唯一实现
+ * 思考预设（reasoning presets）—— 档位读取、校验与参数写入的唯一实现
  *
- * 为什么要有这一层：档位不是全局统一枚举，各端点接受的值域**互不相同**，而且
- * 同一家不同型号也不同（智谱文档原文）：
+ * ## 为什么是「表」而不是「字段」
  *
- * | 端点 | 官方依据 | 可调档位 | 能否关闭 |
- * |------|---------|---------|---------|
- * | DeepSeek | `/guides/thinking_mode` | `low / high / max` | 能，`thinking.type = "disabled"` |
- * | 智谱 GLM-5.3 系 | `/cn/guide/capabilities/thinking` | `low / high / max`（**其余报错**） | **不能**，传 disabled 直接报错 |
- * | 智谱 GLM-5.2 | 同上 | `none / minimal / low / medium / high / xhigh / max` | 能（`none` 或 `disabled`） |
- * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort` | `minimal / low / medium / high`（枚举含 none/xhigh/max） | 能，`reasoning_effort = "none"` |
+ * 档位不是全局统一枚举：各端点接受的值域互不相同，同一家不同型号也不同
+ * （见 `config/reasoning-presets.ts` 的文档表）。所以本模块不判断「厂商是谁」，
+ * 只做一件事：**在模型关联的那张策略表里查档位、写补丁**。
  *
- * 所以「能力声明在模型上，Agent 只能收窄」，写入时按声明选择表达方式，
- * 绝不把端点不认的值发出去。
+ * 于是三个问题都变成查表，不需要任何 if/else 分支：
+ *   1. 可选档位有哪些？      → `Object.keys(preset.levels)`
+ *   2. 能不能关闭思考？      → 表里有没有 `off` 键
+ *   3. 哪些参数键属于思考？  → 所有补丁里出现过的键的并集（写入前先剔除）
+ *
+ * 第 3 条是关键：有了它，从 `max` 切到 `off` 不会残留上一档的参数，而代码里
+ * 一个键名都不必硬编码（`thinking` / `reasoning_effort` 只出现在策略表里）。
  */
-import type { AgentDefinition, Model, ReasoningCapability, ReasoningEffort } from "../types/index.js";
-/** 是否为合法档位值 */
-export declare function isReasoningEffort(value: unknown): value is ReasoningEffort;
-/** 模型的能力声明（缺省 = 不可调档） */
-export declare function capabilityOf(model?: Model | null): ReasoningCapability | undefined;
+import type { AgentDefinition, Model, ReasoningPreset, ReasoningPresets } from "../types/index.js";
 /**
- * 模型可调的档位（不含 `off`）。
+ * 模型关联的策略（未声明 `reasoningPreset`、或名字在表里不存在 → `undefined`）。
  *
- * 未声明能力的模型返回空数组 —— 不猜、不给默认值，避免把非法参数发给服务端。
+ * 名字不存在时**不猜、不兜底**：宁可视作不可调档，也不把来路不明的参数发给服务端。
  */
-export declare function modelEfforts(model?: Model | null): ReasoningEffort[];
+export declare function presetOf(model?: Model | null, presets?: ReasoningPresets | null): ReasoningPreset | undefined;
 /**
- * 模型允许的全部取值（含 `off`）。
+ * 模型可选的全部档位（顺序 = 策略表声明顺序）。
  *
- * `off` 只在声明了 `disable` 方式时出现：没有合法表达式时，「关闭思考」这个选项
- * 本身就不该出现在菜单里。
+ * 不再区分「档位」与「关闭」：表里的键就是菜单里的项。未关联策略 → 空数组。
  */
-export declare function modelAllowedEfforts(model?: Model | null): ReasoningEffort[];
+export declare function modelLevels(model?: Model | null, presets?: ReasoningPresets | null): string[];
 /**
- * 从 `defaultParams` 读当前档位。
+ * 反查当前档位：参数里命中哪个补丁的键值，就是哪一档。
+ *
+ * 与 `applyReasoningEffort()` 互为逆运算，两边共用同一张表。
+ * 多张补丁同时命中时取**最具体**的那个（键最多的），键数相同取先声明的。
  *
- * 返回 `undefined` 表示「没有显式档位」：可能是模型默认开思考但没写 effort
- * （DeepSeek 出厂配置就是 `{thinking:{type:"enabled"}}`），也可能压根没有思考参数。
- * 展示层要区分这两种情况，请配合 `capabilityOf()` 判断。
+ * 返回 `undefined` = 参数不完整匹配任何档位（例如 DeepSeek 出厂只写了
+ * `thinking: { type: "enabled" }` 而没写 effort），展示层应视为「跟随模型默认」。
  */
-export declare function readReasoningEffort(params?: Record<string, unknown> | null): ReasoningEffort | undefined;
+export declare function readReasoningEffort(model?: Model | null, presets?: ReasoningPresets | null, params?: Record<string, unknown> | null): string | undefined;
 /**
- * 按档位生成新的 `defaultParams`（不改入参）。
+ * 把档位写成请求参数（不改入参）。
  *
- * 三种写入形态，取决于模型声明：
- * - `disable: "thinking"` → 同时维护 `thinking.type` 与 `reasoning_effort`
- * - `disable: "effort-none"` → 只写 `reasoning_effort`（OpenAI 不认 `thinking` 键，
- *   对它写 `thinking` 会被当作未知参数拒绝）
- * - 未声明 `disable`（如 GLM-5.3 系）→ 只写 `reasoning_effort`，传 `off` 直接抛错
+ * 写入方式 = **先剔除思考参数键的旧值，再合并新补丁**。这样 `max` → `off` 不会残留
+ * 上一档的 `reasoning_effort`，模型换策略也不会反刍旧策略的参数，而「哪些键属于思考」
+ * 由策略表自己声明，代码零硬编码。
  *
- * @throws 当档位为 `off` 而模型不支持关闭思考，或档位不在模型能力范围内
+ * @throws 模型未关联策略、或策略里没有该档位（绝不静默降级：档位写错必须当场发现）
  */
-export declare function applyReasoningEffort(params: Record<string, unknown> | undefined | null, model: Model | null | undefined, effort: ReasoningEffort): Record<string, unknown>;
+export declare function applyReasoningEffort(model: Model | null | undefined, presets: ReasoningPresets | null | undefined, level: string, params?: Record<string, unknown> | null): Record<string, unknown>;
 /**
- * 解析某 Agent 的实际档位：Agent 声明优先，否则看模型默认参数。
+ * 解析某 Agent 的实际档位：Agent 声明优先，否则反查模型默认参数。
+ *
+ * 声明了但策略里没有这一档 → 退化为模型默认（宁可忽略设置，也不发非法参数）。
  */
-export declare function resolveReasoningEffort(model?: Model | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): ReasoningEffort | undefined;
+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, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): Record<string, unknown> | undefined;
+export declare function resolveModelParams(model?: Model | null, presets?: ReasoningPresets | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): Record<string, unknown> | undefined;

package/dist/shared/reasoning.js

@@ -1,151 +1,159 @@
 /**
- * 思考强度（reasoning effort）—— 能力声明、可用档位与参数写入的唯一实现
+ * 思考预设（reasoning presets）—— 档位读取、校验与参数写入的唯一实现
  *
- * 为什么要有这一层：档位不是全局统一枚举，各端点接受的值域**互不相同**，而且
- * 同一家不同型号也不同（智谱文档原文）：
+ * ## 为什么是「表」而不是「字段」
  *
- * | 端点 | 官方依据 | 可调档位 | 能否关闭 |
- * |------|---------|---------|---------|
- * | DeepSeek | `/guides/thinking_mode` | `low / high / max` | 能，`thinking.type = "disabled"` |
- * | 智谱 GLM-5.3 系 | `/cn/guide/capabilities/thinking` | `low / high / max`（**其余报错**） | **不能**，传 disabled 直接报错 |
- * | 智谱 GLM-5.2 | 同上 | `none / minimal / low / medium / high / xhigh / max` | 能（`none` 或 `disabled`） |
- * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort` | `minimal / low / medium / high`（枚举含 none/xhigh/max） | 能，`reasoning_effort = "none"` |
+ * 档位不是全局统一枚举：各端点接受的值域互不相同，同一家不同型号也不同
+ * （见 `config/reasoning-presets.ts` 的文档表）。所以本模块不判断「厂商是谁」，
+ * 只做一件事：**在模型关联的那张策略表里查档位、写补丁**。
  *
- * 所以「能力声明在模型上，Agent 只能收窄」，写入时按声明选择表达方式，
- * 绝不把端点不认的值发出去。
+ * 于是三个问题都变成查表，不需要任何 if/else 分支：
+ *   1. 可选档位有哪些？      → `Object.keys(preset.levels)`
+ *   2. 能不能关闭思考？      → 表里有没有 `off` 键
+ *   3. 哪些参数键属于思考？  → 所有补丁里出现过的键的并集（写入前先剔除）
+ *
+ * 第 3 条是关键：有了它，从 `max` 切到 `off` 不会残留上一档的参数，而代码里
+ * 一个键名都不必硬编码（`thinking` / `reasoning_effort` 只出现在策略表里）。
  */
-/** `defaultParams` 里承载开关的键 */
-const THINKING_KEY = "thinking";
-/** `defaultParams` 里承载档位的键 */
-const EFFORT_KEY = "reasoning_effort";
-const KNOWN_EFFORTS = [
-    "off",
-    "none",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max",
-];
-/** 是否为合法档位值 */
-export function isReasoningEffort(value) {
-    return typeof value === "string" && KNOWN_EFFORTS.includes(value);
+/** 安全取自有属性（策略名源自用户配置，可能是 `constructor` / `__proto__` 等） */
+function own(bag, key) {
+    if (!bag || !Object.prototype.hasOwnProperty.call(bag, key))
+        return undefined;
+    return bag[key];
 }
-/** 模型的能力声明（缺省 = 不可调档） */
-export function capabilityOf(model) {
-    return model?.reasoning;
+/** 结构化相等 —— 补丁是纯 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]));
 }
 /**
- * 模型可调的档位（不含 `off`）。
+ * 模型关联的策略（未声明 `reasoningPreset`、或名字在表里不存在 → `undefined`）。
  *
- * 未声明能力的模型返回空数组 —— 不猜、不给默认值，避免把非法参数发给服务端。
+ * 名字不存在时**不猜、不兜底**：宁可视作不可调档，也不把来路不明的参数发给服务端。
  */
-export function modelEfforts(model) {
-    return [...(capabilityOf(model)?.efforts ?? [])];
+export function presetOf(model, presets) {
+    const name = model?.reasoningPreset;
+    if (!name)
+        return undefined;
+    return own(presets ?? undefined, name);
 }
 /**
- * 模型允许的全部取值（含 `off`）。
+ * 模型可选的全部档位（顺序 = 策略表声明顺序）。
  *
- * `off` 只在声明了 `disable` 方式时出现：没有合法表达式时，「关闭思考」这个选项
- * 本身就不该出现在菜单里。
+ * 不再区分「档位」与「关闭」：表里的键就是菜单里的项。未关联策略 → 空数组。
  */
-export function modelAllowedEfforts(model) {
-    const capability = capabilityOf(model);
-    if (!capability)
+export function modelLevels(model, presets) {
+    const preset = presetOf(model, presets);
+    if (!preset)
         return [];
-    return capability.disable ? ["off", ...capability.efforts] : [...capability.efforts];
+    return Object.keys(preset.levels ?? {});
 }
-function thinkingType(params) {
-    const thinking = params?.[THINKING_KEY];
-    if (typeof thinking !== "object" || thinking === null)
-        return undefined;
-    const type = thinking.type;
-    return typeof type === "string" ? type : undefined;
+/**
+ * 「思考参数键」的全集 —— **整张策略表**里任何补丁出现过的键。
+ *
+ * 用整张表而非单个策略，是为了让换策略时不留残渣：模型从 `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;
 }
 /**
- * 从 `defaultParams` 读当前档位。
+ * 反查当前档位：参数里命中哪个补丁的键值，就是哪一档。
  *
- * 返回 `undefined` 表示「没有显式档位」：可能是模型默认开思考但没写 effort
- * （DeepSeek 出厂配置就是 `{thinking:{type:"enabled"}}`），也可能压根没有思考参数。
- * 展示层要区分这两种情况，请配合 `capabilityOf()` 判断。
+ * 与 `applyReasoningEffort()` 互为逆运算，两边共用同一张表。
+ * 多张补丁同时命中时取**最具体**的那个（键最多的），键数相同取先声明的。
+ *
+ * 返回 `undefined` = 参数不完整匹配任何档位（例如 DeepSeek 出厂只写了
+ * `thinking: { type: "enabled" }` 而没写 effort），展示层应视为「跟随模型默认」。
  */
-export function readReasoningEffort(params) {
-    if (thinkingType(params) === "disabled")
-        return "off";
-    const raw = params?.[EFFORT_KEY];
-    if (typeof raw !== "string")
+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;
-    // `none` 与 `off` 语义一致（都表示不思考），统一归一为 off，避免菜单里出现两个「关」
-    if (raw === "none")
-        return "off";
-    return isReasoningEffort(raw) ? raw : 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;
 }
 /**
- * 按档位生成新的 `defaultParams`（不改入参）。
+ * 把档位写成请求参数（不改入参）。
  *
- * 三种写入形态，取决于模型声明：
- * - `disable: "thinking"` → 同时维护 `thinking.type` 与 `reasoning_effort`
- * - `disable: "effort-none"` → 只写 `reasoning_effort`（OpenAI 不认 `thinking` 键，
- *   对它写 `thinking` 会被当作未知参数拒绝）
- * - 未声明 `disable`（如 GLM-5.3 系）→ 只写 `reasoning_effort`，传 `off` 直接抛错
+ * 写入方式 = **先剔除思考参数键的旧值，再合并新补丁**。这样 `max` → `off` 不会残留
+ * 上一档的 `reasoning_effort`，模型换策略也不会反刍旧策略的参数，而「哪些键属于思考」
+ * 由策略表自己声明，代码零硬编码。
  *
- * @throws 当档位为 `off` 而模型不支持关闭思考，或档位不在模型能力范围内
+ * @throws 模型未关联策略、或策略里没有该档位（绝不静默降级：档位写错必须当场发现）
  */
-export function applyReasoningEffort(params, model, effort) {
-    const capability = capabilityOf(model);
-    const next = { ...(params ?? {}) };
-    if (effort === "off") {
-        if (capability?.disable === "thinking") {
-            next[THINKING_KEY] = { type: "disabled" };
-            delete next[EFFORT_KEY];
-            return next;
-        }
-        if (capability?.disable === "effort-none") {
-            next[EFFORT_KEY] = "none";
-            // 不在 OpenAI 的请求里塞 thinking：那是未知参数
-            delete next[THINKING_KEY];
-            return next;
-        }
-        throw new Error(`模型 "${model?.id ?? "(未知)"}" 不支持关闭思考`);
+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），无法设置档位`);
     }
-    if (!capability) {
-        throw new Error(`模型 "${model?.id ?? "(未知)"}" 未声明思考能力，无法设置档位`);
+    const patch = own(preset.levels, level);
+    if (!patch) {
+        throw new Error(`策略 "${name}" 没有档位 "${level}"（可选：${Object.keys(preset.levels).join(" / ")}）`);
     }
-    if (!capability.efforts.includes(effort)) {
-        throw new Error(`模型 "${model?.id ?? "(未知)"}" 不支持档位 "${effort}"（可选：${capability.efforts.join(" / ")}）`);
-    }
-    if (capability.disable === "thinking") {
-        next[THINKING_KEY] = { type: "enabled" };
-    }
-    next[EFFORT_KEY] = effort;
-    return next;
+    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 声明优先，否则看模型默认参数。
+ * 解析某 Agent 的实际档位：Agent 声明优先，否则反查模型默认参数。
+ *
+ * 声明了但策略里没有这一档 → 退化为模型默认（宁可忽略设置，也不发非法参数）。
  */
-export function resolveReasoningEffort(model, definition) {
+export function resolveReasoningEffort(model, presets, definition) {
     const declared = definition?.reasoningEffort;
-    if (declared) {
-        // 声明了但模型不支持 → 退化为模型默认，避免把非法值发给服务端
-        const allowed = modelAllowedEfforts(model);
-        if (allowed.length === 0 || allowed.includes(declared))
-            return declared;
-    }
-    return readReasoningEffort(model?.defaultParams);
+    if (declared && modelLevels(model, presets).includes(declared))
+        return declared;
+    return readReasoningEffort(model, presets);
 }
 /**
  * 把 Agent 的档位覆盖应用到模型参数上（`createModel` 用）。
  *
  * 未声明 `reasoningEffort` 时原样返回模型参数，保证既有行为不变。
  */
-export function resolveModelParams(model, definition) {
+export function resolveModelParams(model, presets, definition) {
     const declared = definition?.reasoningEffort;
     if (!declared)
         return model?.defaultParams;
-    const allowed = modelAllowedEfforts(model);
-    // 模型不支持声明值：宁可保持模型默认，也不发非法参数
-    if (allowed.length === 0 || !allowed.includes(declared))
+    // 模型没关联策略、或策略里没这一档：保持模型默认，绝不发非法参数
+    if (!modelLevels(model, presets).includes(declared))
         return model?.defaultParams;
-    return applyReasoningEffort(model?.defaultParams, model, declared);
+    return applyReasoningEffort(model, presets, declared);
 }

package/dist/types/index.d.ts

@@ -26,34 +26,34 @@ export interface EndpointCapabilities {
     filesApi?: boolean;
 }
 /**
- * 思考强度档位 —— 各端点官方枚举的**并集**，不含各家不认的值。
+ * 单个档位的请求参数补丁 —— 原样合并进模型请求参数。
  *
- * OpenAI（`openai-node` 的 `Shared.ReasoningEffort`）：`none | minimal | low | medium | high | xhigh | max`
- * DeepSeek（`/guides/thinking_mode`）：`low | high | max`（另接受 minimal/medium/xhigh/ultra 并做映射）
- * 智谱 GLM-5.3 系（`/cn/guide/capabilities/thinking`）：`low | high | max`，**其余值直接报错**
- * 智谱 GLM-5.2：`none | minimal | low | medium | high | xhigh | max`
- *
- * `off` 是本 SDK 的语义值（「关闭思考」），对接时按 `ReasoningCapability.disable` 选择表达方式。
- * 它与 `none` 不重复：`none` 是端点自己认的档位值，`off` 是「没有档位、彻底不思考」。
+ * 各家协议差异全部关在补丁里，SDK 不解释、不硬编码任何键名：
+ *   OpenAI   → `{ reasoning_effort: "high" }`（没有 `thinking` 参数）
+ *   DeepSeek → `{ thinking: { type: "enabled" }, reasoning_effort: "high" }`
+ *   关闭     → `{ reasoning_effort: "none" }` 或 `{ thinking: { type: "disabled" } }`
  */
-export type ReasoningEffort = "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type ReasoningPatch = Record<string, unknown>;
 /**
- * 模型/端点的思考能力声明（**物理上限**，来自厂商官方文档）。
+ * 一个具名思考策略：档位名 → 参数补丁。
  *
- * 刻意不推断、不猜：未声明的模型视为「不可调档」，`/think` 不会列任何选项——
- * 发一个端点不认的值会被直接报错（智谱 5.3 系原文「其余输入将报错」）。
+ * `levels` 的键集合**就是**该策略的全部可选档位 —— 没有单独的「能否关闭思考」字段：
+ * 表里有 `off` 键就能关，没有就不能（如智谱 GLM-5.3 系，官方原文「其余输入将报错」）。
  */
-export interface ReasoningCapability {
-    /** 型号真实接受的档位（不含 `off`）；空数组 = 支持思考但不可调档 */
-    efforts: ReasoningEffort[];
-    /**
-     * 关闭思考的表达方式：
-     * - `thinking` → `thinking: { type: "disabled" }`（DeepSeek / GLM-5.2）
-     * - `effort-none` → `reasoning_effort: "none"`（OpenAI / GLM-5.2）
-     * - 缺省 → 不支持关闭（如 GLM-5.3 系，传 disabled 会报错）
-     */
-    disable?: "thinking" | "effort-none";
+export interface ReasoningPreset {
+    /** 用户改过 → SDK 初始化不再覆盖该策略（与 `Model.custom` 同构） */
+    custom?: boolean;
+    /** 档位名 → 参数补丁 */
+    levels: Record<string, ReasoningPatch>;
 }
+/**
+ * 思考策略表 —— `<basePath>/reasoning-presets.json` 的结构，出厂内容见
+ * `config/reasoning-presets.ts`。
+ *
+ * 键是策略名，由 `Model.reasoningPreset` 引用。**策略名一旦发布即视为稳定标识**
+ * （用户配置文件里写着它），改名等同破坏性变更。
+ */
+export type ReasoningPresets = Record<string, ReasoningPreset>;
 /** API 端点 */
 export interface Endpoint {
     id: string;
@@ -96,12 +96,13 @@ export interface Model {
     tokenThresholds: TokenThresholds;
     defaultParams?: Record<string, unknown>;
     /**
-     * 思考强度能力（按厂商官方文档声明）。缺省视为不可调档。
+     * 思考策略名，引用 `reasoning-presets.json` 里的键。缺省视为不可调档。
      *
-     * Agent 用 `AgentDefinition.reasoningEffort` 在这个范围内选一档；
-     * 超出范围的值不会发给服务端（`resolveModelParams()` 会退回模型默认）。
+     * 为什么只存名字不存整张表：档位细节属于**厂商协议知识**，跟 SDK 版本一起演进；
+     * 配置只需要记录「这个型号套用哪套协议」。名字指向同目录下的策略表文件，
+     * 用户看得见、改得动，不必等 SDK 发版。
      */
-    reasoning?: ReasoningCapability;
+    reasoningPreset?: string;
     /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
@@ -122,12 +123,15 @@ export interface AgentDefinition {
     messages: AgentNS.Message[];
     modelId?: string;
     /**
-     * 该 Agent 的思考档位（可选），覆盖模型 `defaultParams` 里的对应参数。
+     * 该 Agent 的思考档位（可选），必须是该模型策略表 `levels` 里的键。
      *
      * 有了它，同一个模型可以给不同 Agent 配不同强度（编程 Agent `max`、闲聊 Agent `low`），
      * 而模型本身的默认参数保持不变。未声明时沿用模型默认。
+     *
+     * 类型是 `string` 而非联合类型：档位名由策略表定义，各家本就不同名，
+     * 用一个全局枚举假装统一只会把厂商差异藏进字段里。合法性在运行时按表校验。
      */
-    reasoningEffort?: ReasoningEffort;
+    reasoningEffort?: string;
     permissions?: AgentPermissions;
     function?: AgentNS.FunctionDefine;
     createdAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.14",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",