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

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [1.0.0-alpha.15] - 2026-10-22
+
+### 🔧 行为变更（不兼容）
+
+- **SDK 不再「消费」思考档位，只保留表本身** —— alpha.14 把「档位 → 请求参数」的整套解析塞进了 SDK 运行时：`applyReasoningEffort` / `modelLevels` / `resolveReasoningEffort` / `resolveModelParams`，还要 `Scope.reasoningPresets` 注入、Agent 上存档位名、运行时查表拼参数。但 `low` / `high` / `max` / `off` 是**产品语义，不是协议事实**，SDK 唯一客观知道的是「请求参数长什么样」——那本来就由 `defaultParams` 承载。现在：
+  - **删除 `shared/reasoning.ts` 的全部 API**（`applyReasoningEffort` / `modelLevels` / `presetOf` / `readReasoningEffort` / `resolveReasoningEffort` / `resolveModelParams`）以及 `Scope.reasoningPresets`；
+  - **保留**思考预设的**定义与出厂内容**（`ReasoningPresets` / `ReasoningPreset` / `ReasoningPatch` 类型、`config/reasoning-presets.ts`、`ConfigManager.readReasoningPresets()` / `ensureReasoningPresets()`）—— 它是 CLI / 桌面端等客户端**共享的资产**（「智谱 5.3 只认 low/high/max」这种知识不该被每个客户端各写一遍），但那只是**数据**，SDK 不拿它生成请求参数。
+- **`AgentDefinition.reasoningEffort` → `AgentDefinition.modelParams?: ModelParams`** —— Agent 级覆盖从「档位名」变成「具体参数」。客户端读到表、拿档位补丁，在**写入配置时**就把它展开存进 `modelParams` 里。于是**配置即事实**：运行期不查表、不推导。
+- **`createModel(scope, modelId, overrides?: ModelParams)`** —— 第三参从 `Pick<AgentDefinition, "reasoningEffort">` 变成裸的参数对象，内部只有一行：
+  ```ts
+  modelConfig = { ...model.defaultParams, ...overrides };
+  ```
+  浅合并（嵌套对象整体替换），没有覆盖时原样返回 `defaultParams`。SDK 从此不解释任何键名，也不知道 `thinking` / `reasoning_effort` 是什么。SubAgent 指定独立 `modelId` 时同样应用自己的 `modelParams`。
+- **`Model.reasoningPreset` 保留**，语义改为「引用策略表的键」，供客户端判断该模型能选哪几档；SDK 只保证它能随模型配置一起读写与出厂同步，不消费。
+
+### 🐛 修复
+
+- **迁移 `Model.reasoning` 旧字段（alpha.13 遗留）** —— 未标 `custom` 的模型会被出厂定义整块覆盖，但**标了 `custom: true` 的会原地保留**，于是留下一个无人认识的 `reasoning`，同时因为缺 `reasoningPreset` 而被客户端判定为「不可调档」。`ConfigManager.read()` 现在会删掉该旧字段，并按同 id 的出厂模型补回 `reasoningPreset`；id 不在出厂清单的（真·自建模型）只删不补。只处理「旧字段存在」这一种情况，用户后续主动删掉 `reasoningPreset` 不会被反复补回来。
+
+### ✅ 测试
+
+- `src/runtime/createModel.test.ts` 新增 6 例锁住合并语义：无覆盖原样返回、空覆盖等同无覆盖、同名键覆盖而其它键保留、模型无 `defaultParams` 时覆盖即全部、**浅合并不做深合并**（换档位不残留旧子键）、两个 Agent 各配一套互不影响。
+- `src/config/migrate.test.ts` 新增 6 例（19 例合计）。
+- 删除 `src/shared/reasoning.test.ts`（26 例，运行时解析已移除）；`src/config/reasoning-presets.test.ts`（11 例）保留 —— 表还在 SDK。
+- 全量 **57 文件 / 600 例通过**（6 skipped）。
+
+## [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,11 @@ 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：应用层元数据，**SDK 不解释**（既不参与请求参数生成，也不影响运行行为）。
+    // 它由客户端（如 CLI）自己定义含义：指向哪张思考档位表、`/think` 能选哪几档。
+    // 之所以留在出厂定义里：字段声明与行为消费是两件事，出厂模型需要把它带上，
+    // 否则 `syncManagedModels` 会用出厂定义整块覆盖并抹掉应用声明的值。
+    // 不写这个字段 = 应用层视作「不可调档」（如 GLM-4.7 强制思考且无 reasoning_effort 参数）。
     models: [
         // ---------- OpenAI ----------
         {
@@ -122,7 +118,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 +129,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 +140,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 +151,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 +162,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 +173,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 +184,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 +195,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/migrate.d.ts

@@ -8,6 +8,12 @@
  *    `handoff`（交接阈值，软线）与 `guard`（强行阻断阈值，硬线）。
  *    `maxContextChars` 是 token 口径之前的历史遗留，按 `floor(chars / 4)` 折成 tokens
  *    （与旧代码的回退算法一致）后并入 `handoff`。
+ * 2. **`Model.reasoning` → `Model.reasoningPreset`**
+ *    alpha.13 曾用 `reasoning: { efforts, disable? }` 在模型上声明思考能力，后来改成
+ *    「引用策略表里的名字」。未标 `custom` 的模型会被出厂定义整块覆盖，但**标了 `custom`
+ *    的模型会原地保留**，于是留下一个无人认识的 `reasoning` 死字段，同时因为缺
+ *    `reasoningPreset` 而默默失去调档能力。这里删掉旧字段，并按**同 id 的出厂模型**
+ *    补上正确的策略名（同一 id 即同一厂商型号，协议能力不会因用户改过参数而变）。
  *
  * 迁移时机：`ConfigManager.read()` 读出即迁（内存里永远是当前形状）；
  * 落盘由 `ensureDefaultConfig()` 负责 —— 它比较迁移结果与磁盘原文，不同才写回，
@@ -19,6 +25,7 @@ export declare const TOKEN_THRESHOLDS_KEY = "tokenThresholds";
 /** 已淘汰的旧字段名（仅迁移代码认识它们） */
 export declare const LEGACY_TOKEN_FIELD = "maxContextTokens";
 export declare const LEGACY_CHARS_FIELD = "maxContextChars";
+export declare const LEGACY_REASONING_FIELD = "reasoning";
 /**
  * 旧数据缺失阈值时的交接阈值兜底。
  *
@@ -37,9 +44,19 @@ export declare function migrateModelThresholds(model: Model): {
     model: Model;
     changed: boolean;
 };
+/**
+ * 迁移单个模型的思考能力声明：`reasoning` → `reasoningPreset`。
+ *
+ * 只处理「旧字段存在」这一种情况：字段一旦落盘消失，用户后续主动删掉
+ * `reasoningPreset`（表示「这个模型我不想调档」）就不会被反复补回来。
+ */
+export declare function migrateModelReasoning(model: Model): {
+    model: Model;
+    changed: boolean;
+};
 /**
  * 迁移整个配置。只处理对话模型（`models`）——
- * 图片模型（`imageModels`）从来没有上下文阈值概念。
+ * 图片模型（`imageModels`）既没有上下文阈值、也没有思考概念。
  */
 export declare function migrateConfig(config: AppConfig): {
     config: AppConfig;

package/dist/config/migrate.js

@@ -8,16 +8,24 @@
  *    `handoff`（交接阈值，软线）与 `guard`（强行阻断阈值，硬线）。
  *    `maxContextChars` 是 token 口径之前的历史遗留，按 `floor(chars / 4)` 折成 tokens
  *    （与旧代码的回退算法一致）后并入 `handoff`。
+ * 2. **`Model.reasoning` → `Model.reasoningPreset`**
+ *    alpha.13 曾用 `reasoning: { efforts, disable? }` 在模型上声明思考能力，后来改成
+ *    「引用策略表里的名字」。未标 `custom` 的模型会被出厂定义整块覆盖，但**标了 `custom`
+ *    的模型会原地保留**，于是留下一个无人认识的 `reasoning` 死字段，同时因为缺
+ *    `reasoningPreset` 而默默失去调档能力。这里删掉旧字段，并按**同 id 的出厂模型**
+ *    补上正确的策略名（同一 id 即同一厂商型号，协议能力不会因用户改过参数而变）。
  *
  * 迁移时机：`ConfigManager.read()` 读出即迁（内存里永远是当前形状）；
  * 落盘由 `ensureDefaultConfig()` 负责 —— 它比较迁移结果与磁盘原文，不同才写回，
  * 因此迁移只发生一次，且不会在每次启动时无谓地改写文件。
  */
+import { DEFAULT_APP_CONFIG } from "./constants.js";
 /** 当前字段名 */
 export const TOKEN_THRESHOLDS_KEY = "tokenThresholds";
 /** 已淘汰的旧字段名（仅迁移代码认识它们） */
 export const LEGACY_TOKEN_FIELD = "maxContextTokens";
 export const LEGACY_CHARS_FIELD = "maxContextChars";
+export const LEGACY_REASONING_FIELD = "reasoning";
 /**
  * 旧数据缺失阈值时的交接阈值兜底。
  *
@@ -71,17 +79,38 @@ export function migrateModelThresholds(model) {
     next[TOKEN_THRESHOLDS_KEY] = { handoff, guard };
     return { model: next, changed: true };
 }
+/**
+ * 迁移单个模型的思考能力声明：`reasoning` → `reasoningPreset`。
+ *
+ * 只处理「旧字段存在」这一种情况：字段一旦落盘消失，用户后续主动删掉
+ * `reasoningPreset`（表示「这个模型我不想调档」）就不会被反复补回来。
+ */
+export function migrateModelReasoning(model) {
+    const source = model;
+    if (!(LEGACY_REASONING_FIELD in source))
+        return { model, changed: false };
+    const next = { ...source };
+    delete next[LEGACY_REASONING_FIELD];
+    // 同 id 的出厂模型能告诉我们「这个型号属于哪套协议」
+    if (next.reasoningPreset === undefined) {
+        const factory = (DEFAULT_APP_CONFIG.models ?? []).find((item) => item.id === model.id);
+        if (factory?.reasoningPreset)
+            next.reasoningPreset = factory.reasoningPreset;
+    }
+    return { model: next, changed: true };
+}
 /**
  * 迁移整个配置。只处理对话模型（`models`）——
- * 图片模型（`imageModels`）从来没有上下文阈值概念。
+ * 图片模型（`imageModels`）既没有上下文阈值、也没有思考概念。
  */
 export function migrateConfig(config) {
     let changed = false;
     const models = (config.models ?? []).map((model) => {
-        const result = migrateModelThresholds(model);
-        if (result.changed)
+        const thresholds = migrateModelThresholds(model);
+        const reasoning = migrateModelReasoning(thresholds.model);
+        if (thresholds.changed || reasoning.changed)
             changed = true;
-        return result.model;
+        return reasoning.model;
     });
     if (!changed)
         return { config, changed };

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

@@ -0,0 +1,37 @@
+/**
+ * 思考预设 —— 出厂内容 + 策略表文件名
+ *
+ * 这里的内容只是**初始值**：`ConfigManager.ensureReasoningPresets()` 在首次运行时把它
+ * 写到 `<basePath>/reasoning-presets.json`，之后以磁盘文件为准（用户可改、可加）。
+ * 与 `DEFAULT_APP_CONFIG` 写进 `config.json` 完全同一个套路。
+ *
+ * ## 为什么这份数据在 SDK
+ *
+ * 它是**跨客户端共享的资产**：CLI 用它决定 `/think` 能选哪几档，桌面端同理；两端不该
+ * 各维护一份「智谱 5.3 只认 low/high/max」的知识。所以**定义、出厂内容、读写**都在 SDK。
+ *
+ * ## 但 SDK 不拿它生成请求参数
+ *
+ * 参数合并只有一条路：`{ ...model.defaultParams, ...agent.modelParams }`（见 `createModel`）。
+ * 客户端读表 → 限制可选强度 → 把选中档位的补丁**写进** `AgentDefinition.modelParams`，
+ * 于是配置本身就是事实，运行期不再查表。
+ *
+ * ## 为什么每张表长这样（**全部来自官方文档，不要凭印象改**）
+ *
+ * | 端点 | 官方依据 | 若写错会怎样 |
+ * |------|---------|-------------|
+ * | 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,64 @@
+/**
+ * 思考预设 —— 出厂内容 + 策略表文件名
+ *
+ * 这里的内容只是**初始值**：`ConfigManager.ensureReasoningPresets()` 在首次运行时把它
+ * 写到 `<basePath>/reasoning-presets.json`，之后以磁盘文件为准（用户可改、可加）。
+ * 与 `DEFAULT_APP_CONFIG` 写进 `config.json` 完全同一个套路。
+ *
+ * ## 为什么这份数据在 SDK
+ *
+ * 它是**跨客户端共享的资产**：CLI 用它决定 `/think` 能选哪几档，桌面端同理；两端不该
+ * 各维护一份「智谱 5.3 只认 low/high/max」的知识。所以**定义、出厂内容、读写**都在 SDK。
+ *
+ * ## 但 SDK 不拿它生成请求参数
+ *
+ * 参数合并只有一条路：`{ ...model.defaultParams, ...agent.modelParams }`（见 `createModel`）。
+ * 客户端读表 → 限制可选强度 → 把选中档位的补丁**写进** `AgentDefinition.modelParams`，
+ * 于是配置本身就是事实，运行期不再查表。
+ *
+ * ## 为什么每张表长这样（**全部来自官方文档，不要凭印象改**）
+ *
+ * | 端点 | 官方依据 | 若写错会怎样 |
+ * |------|---------|-------------|
+ * | 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, ModelParams, 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,11 @@ 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 { 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,14 @@ 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）
+// 表是跨客户端共享的「定义 + 出厂默认」，SDK 不拿它生成请求参数
+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";
 // 运行时
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";

package/dist/runtime/createAgent.js

@@ -18,10 +18,7 @@ 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, {
-        // Agent 级思考档位覆盖（未声明时为 undefined，行为与以前一致）
-        reasoningEffort: definition.reasoningEffort,
-    });
+    const { client, model, modelConfig } = createModel(scope, modelId, definition.modelParams);
     const tools = scope.buildTools(definition, {
         exclude: {
             subagents: definition.function?.name

package/dist/runtime/createModel.d.ts

@@ -1,17 +1,17 @@
 import OpenAI from "openai";
 import type { Scope } from "../scope/Scope.js";
-import type { AgentDefinition } from "../types/index.js";
+import type { ModelParams } from "../types/index.js";
 /**
  * Agent 模型装配结果：openai SDK client + 模型名 + 模型参数。
  * Agent 构造时直接消费此结构。
  */
 export interface AgentModel {
-    /** openai 官方 SDK 客户端 */
+    /** openai SDK 客户端 */
     client: OpenAI;
     /** 发送给 API 的模型名 */
     model: string;
-    /** 模型参数（defaultParams），透传给 API（可含厂商特有字段，如 DeepSeek thinking） */
-    modelConfig?: Record<string, unknown>;
+    /** 模型参数，透传给 API（可含厂商特有字段，如 DeepSeek thinking） */
+    modelConfig?: ModelParams;
 }
 /**
  * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
@@ -19,8 +19,7 @@ export interface AgentModel {
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
  *
- * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
- * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
- * 写入方式按模型的 `reasoning` 能力声明决定（见 `shared/reasoning.ts`）。
+ * `overrides` 是 **Agent 级参数覆盖**（`AgentDefinition.modelParams`）：
+ * 同一个模型可以给不同 Agent 配不同参数，而模型自身的 `defaultParams` 保持不变。
  */
-export declare function createModel(scope: Scope, modelId: string, overrides?: Pick<AgentDefinition, "reasoningEffort">): AgentModel;
+export declare function createModel(scope: Scope, modelId: string, overrides?: ModelParams): AgentModel;

package/dist/runtime/createModel.js

@@ -1,14 +1,26 @@
 import OpenAI from "openai";
-import { resolveModelParams } from "../shared/reasoning.js";
+/**
+ * 参数覆盖 —— 浅合并，一行。
+ *
+ * 这是 SDK 对「模型参数」的唯一处理逻辑：不解释键名、不做档位推导、不知道厂商差异。
+ * 需要多层次语义（如「思考档位」）的应用，应该在**写配置时**就把档位展开成具体参数，
+ * 存进 `Model.defaultParams` / `AgentDefinition.modelParams`，运行期不再查表。
+ *
+ * 没有覆盖时返回原对象（保持 `undefined` 语义，避免凭空塞一个空对象）。
+ */
+function mergeParams(base, overrides) {
+    if (!overrides || Object.keys(overrides).length === 0)
+        return base;
+    return { ...base, ...overrides };
+}
 /**
  * 模型工厂 — 根据 modelId 和 Scope 装配 openai SDK client。
  *
  * 端点（baseUrl / apiKey）来自 config.endpoints，发送给 API 的模型名 = modelName || id。
  * 任何 OpenAI 兼容端点（OpenAI / 智谱 BigModel / DeepSeek 等）均可通过 baseURL 接入。
  *
- * `overrides.reasoningEffort` 是 **Agent 级覆盖**（`AgentDefinition.reasoningEffort`）：
- * 同一个模型可以给不同 Agent 配不同思考强度，而模型自身的 `defaultParams` 不变。
- * 写入方式按模型的 `reasoning` 能力声明决定（见 `shared/reasoning.ts`）。
+ * `overrides` 是 **Agent 级参数覆盖**（`AgentDefinition.modelParams`）：
+ * 同一个模型可以给不同 Agent 配不同参数，而模型自身的 `defaultParams` 保持不变。
  */
 export function createModel(scope, modelId, overrides) {
     const config = scope.config;
@@ -30,7 +42,6 @@ export function createModel(scope, modelId, overrides) {
     return {
         client,
         model: apiModelName,
-        // 档位覆盖在这里生效：未声明 reasoningEffort 时原样返回模型 defaultParams
-        modelConfig: resolveModelParams(modelConfig, overrides),
+        modelConfig: mergeParams(modelConfig.defaultParams, overrides),
     };
 }

package/dist/scope/plugins/subagents/subAgentTools.js

@@ -24,7 +24,8 @@ export function createSubAgentTool(def, scope) {
             let model;
             let modelConfig;
             if (def.modelId) {
-                const m = createModel(scope, def.modelId);
+                // SubAgent 可声明自己的模型与参数覆盖（与主 Agent 同一套规则：直接合并）
+                const m = createModel(scope, def.modelId, def.modelParams);
                 client = m.client;
                 model = m.model;
                 modelConfig = m.modelConfig;

package/dist/types/index.d.ts

@@ -26,34 +26,44 @@ export interface EndpointCapabilities {
     filesApi?: boolean;
 }
 /**
- * 思考强度档位 —— 各端点官方枚举的**并集**，不含各家不认的值。
+ * 模型请求参数（`defaultParams` / `modelParams` 的形状）。
  *
- * 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`
+ * 含厂商特有字段（`thinking` / `reasoning_effort` 等），SDK **原样透传**、不解释。
+ */
+export type ModelParams = Record<string, unknown>;
+/**
+ * 单个档位的请求参数补丁。
  *
- * `off` 是本 SDK 的语义值（「关闭思考」），对接时按 `ReasoningCapability.disable` 选择表达方式。
- * 它与 `none` 不重复：`none` 是端点自己认的档位值，`off` 是「没有档位、彻底不思考」。
+ * 各家协议差异全部关在补丁里，不硬编码任何键名：
+ *   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 = ModelParams;
 /**
- * 模型/端点的思考能力声明（**物理上限**，来自厂商官方文档）。
+ * 一个具名思考策略：档位名 → 参数补丁。
  *
- * 刻意不推断、不猜：未声明的模型视为「不可调档」，`/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`。
+ *
+ * 这份表是 **CLI / 桌面端等客户端共享的资产**：它定义「有哪些档位、每档写什么参数」，
+ * 由 `Model.reasoningPreset` 引用。客户端据此限制可选强度、把选中的档位展开成参数
+ * 写进 `AgentDefinition.modelParams`。
+ *
+ * **SDK 自身不消费它生成请求参数**：参数合并只是 `{...defaultParams, ...modelParams}`
+ * 一次浅合并（见 `createModel`）。表在这里只负责「定义 + 出厂默认 + 读写」。
+ */
+export type ReasoningPresets = Record<string, ReasoningPreset>;
 /** API 端点 */
 export interface Endpoint {
     id: string;
@@ -96,12 +106,13 @@ export interface Model {
     tokenThresholds: TokenThresholds;
     defaultParams?: Record<string, unknown>;
     /**
-     * 思考强度能力（按厂商官方文档声明）。缺省视为不可调档。
+     * 思考策略名，引用 `reasoning-presets.json` 里的键。
      *
-     * Agent 用 `AgentDefinition.reasoningEffort` 在这个范围内选一档；
-     * 超出范围的值不会发给服务端（`resolveModelParams()` 会退回模型默认）。
+     * 它是**跨客户端共享的元数据**：CLI / 桌面端据此判断这个模型能选哪几档。
+     * SDK 不拿它去生成请求参数（那条路只有 `defaultParams` + `modelParams` 浅合并），
+     * 只保证该字段能随模型配置一起读写与出厂同步。
      */
-    reasoning?: ReasoningCapability;
+    reasoningPreset?: string;
     /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
@@ -122,12 +133,16 @@ export interface AgentDefinition {
     messages: AgentNS.Message[];
     modelId?: string;
     /**
-     * 该 Agent 的思考档位（可选），覆盖模型 `defaultParams` 里的对应参数。
+     * Agent 级模型参数覆盖，浅合并进模型的 `defaultParams`。
+     *
+     * SDK 只做 `{ ...model.defaultParams, ...modelParams }`，不解释任何键名、不做
+     * 档位推导、不知道厂商差异。於是「配置即事实」：应用（如 CLI）在**写入配置时**就把
+     * 档位展开成具体参数存在这里，运行时不再查表。
      *
-     * 有了它，同一个模型可以给不同 Agent 配不同强度（编程 Agent `max`、闲聊 Agent `low`），
-     * 而模型本身的默认参数保持不变。未声明时沿用模型默认。
+     * 于是同一个模型可以给不同 Agent 配不同强度（编程 Agent `reasoning_effort: "max"`、
+     * 闲聊 Agent `{ thinking: { type: "disabled" } }`），而模型自身的 `defaultParams` 不动。
      */
-    reasoningEffort?: ReasoningEffort;
+    modelParams?: ModelParams;
     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.15",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/shared/reasoning.d.ts

@@ -1,64 +0,0 @@
-/**
- * 思考强度（reasoning effort）—— 能力声明、可用档位与参数写入的唯一实现
- *
- * 为什么要有这一层：档位不是全局统一枚举，各端点接受的值域**互不相同**，而且
- * 同一家不同型号也不同（智谱文档原文）：
- *
- * | 端点 | 官方依据 | 可调档位 | 能否关闭 |
- * |------|---------|---------|---------|
- * | 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"` |
- *
- * 所以「能力声明在模型上，Agent 只能收窄」，写入时按声明选择表达方式，
- * 绝不把端点不认的值发出去。
- */
-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;
-/**
- * 模型可调的档位（不含 `off`）。
- *
- * 未声明能力的模型返回空数组 —— 不猜、不给默认值，避免把非法参数发给服务端。
- */
-export declare function modelEfforts(model?: Model | null): ReasoningEffort[];
-/**
- * 模型允许的全部取值（含 `off`）。
- *
- * `off` 只在声明了 `disable` 方式时出现：没有合法表达式时，「关闭思考」这个选项
- * 本身就不该出现在菜单里。
- */
-export declare function modelAllowedEfforts(model?: Model | null): ReasoningEffort[];
-/**
- * 从 `defaultParams` 读当前档位。
- *
- * 返回 `undefined` 表示「没有显式档位」：可能是模型默认开思考但没写 effort
- * （DeepSeek 出厂配置就是 `{thinking:{type:"enabled"}}`），也可能压根没有思考参数。
- * 展示层要区分这两种情况，请配合 `capabilityOf()` 判断。
- */
-export declare function readReasoningEffort(params?: Record<string, unknown> | null): ReasoningEffort | undefined;
-/**
- * 按档位生成新的 `defaultParams`（不改入参）。
- *
- * 三种写入形态，取决于模型声明：
- * - `disable: "thinking"` → 同时维护 `thinking.type` 与 `reasoning_effort`
- * - `disable: "effort-none"` → 只写 `reasoning_effort`（OpenAI 不认 `thinking` 键，
- *   对它写 `thinking` 会被当作未知参数拒绝）
- * - 未声明 `disable`（如 GLM-5.3 系）→ 只写 `reasoning_effort`，传 `off` 直接抛错
- *
- * @throws 当档位为 `off` 而模型不支持关闭思考，或档位不在模型能力范围内
- */
-export declare function applyReasoningEffort(params: Record<string, unknown> | undefined | null, model: Model | null | undefined, effort: ReasoningEffort): Record<string, unknown>;
-/**
- * 解析某 Agent 的实际档位：Agent 声明优先，否则看模型默认参数。
- */
-export declare function resolveReasoningEffort(model?: Model | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): ReasoningEffort | undefined;
-/**
- * 把 Agent 的档位覆盖应用到模型参数上（`createModel` 用）。
- *
- * 未声明 `reasoningEffort` 时原样返回模型参数，保证既有行为不变。
- */
-export declare function resolveModelParams(model?: Model | null, definition?: Pick<AgentDefinition, "reasoningEffort"> | null): Record<string, unknown> | undefined;

package/dist/shared/reasoning.js

@@ -1,151 +0,0 @@
-/**
- * 思考强度（reasoning effort）—— 能力声明、可用档位与参数写入的唯一实现
- *
- * 为什么要有这一层：档位不是全局统一枚举，各端点接受的值域**互不相同**，而且
- * 同一家不同型号也不同（智谱文档原文）：
- *
- * | 端点 | 官方依据 | 可调档位 | 能否关闭 |
- * |------|---------|---------|---------|
- * | 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"` |
- *
- * 所以「能力声明在模型上，Agent 只能收窄」，写入时按声明选择表达方式，
- * 绝不把端点不认的值发出去。
- */
-/** `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);
-}
-/** 模型的能力声明（缺省 = 不可调档） */
-export function capabilityOf(model) {
-    return model?.reasoning;
-}
-/**
- * 模型可调的档位（不含 `off`）。
- *
- * 未声明能力的模型返回空数组 —— 不猜、不给默认值，避免把非法参数发给服务端。
- */
-export function modelEfforts(model) {
-    return [...(capabilityOf(model)?.efforts ?? [])];
-}
-/**
- * 模型允许的全部取值（含 `off`）。
- *
- * `off` 只在声明了 `disable` 方式时出现：没有合法表达式时，「关闭思考」这个选项
- * 本身就不该出现在菜单里。
- */
-export function modelAllowedEfforts(model) {
-    const capability = capabilityOf(model);
-    if (!capability)
-        return [];
-    return capability.disable ? ["off", ...capability.efforts] : [...capability.efforts];
-}
-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;
-}
-/**
- * 从 `defaultParams` 读当前档位。
- *
- * 返回 `undefined` 表示「没有显式档位」：可能是模型默认开思考但没写 effort
- * （DeepSeek 出厂配置就是 `{thinking:{type:"enabled"}}`），也可能压根没有思考参数。
- * 展示层要区分这两种情况，请配合 `capabilityOf()` 判断。
- */
-export function readReasoningEffort(params) {
-    if (thinkingType(params) === "disabled")
-        return "off";
-    const raw = params?.[EFFORT_KEY];
-    if (typeof raw !== "string")
-        return undefined;
-    // `none` 与 `off` 语义一致（都表示不思考），统一归一为 off，避免菜单里出现两个「关」
-    if (raw === "none")
-        return "off";
-    return isReasoningEffort(raw) ? raw : undefined;
-}
-/**
- * 按档位生成新的 `defaultParams`（不改入参）。
- *
- * 三种写入形态，取决于模型声明：
- * - `disable: "thinking"` → 同时维护 `thinking.type` 与 `reasoning_effort`
- * - `disable: "effort-none"` → 只写 `reasoning_effort`（OpenAI 不认 `thinking` 键，
- *   对它写 `thinking` 会被当作未知参数拒绝）
- * - 未声明 `disable`（如 GLM-5.3 系）→ 只写 `reasoning_effort`，传 `off` 直接抛错
- *
- * @throws 当档位为 `off` 而模型不支持关闭思考，或档位不在模型能力范围内
- */
-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 ?? "(未知)"}" 不支持关闭思考`);
-    }
-    if (!capability) {
-        throw new Error(`模型 "${model?.id ?? "(未知)"}" 未声明思考能力，无法设置档位`);
-    }
-    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;
-}
-/**
- * 解析某 Agent 的实际档位：Agent 声明优先，否则看模型默认参数。
- */
-export function resolveReasoningEffort(model, definition) {
-    const declared = definition?.reasoningEffort;
-    if (declared) {
-        // 声明了但模型不支持 → 退化为模型默认，避免把非法值发给服务端
-        const allowed = modelAllowedEfforts(model);
-        if (allowed.length === 0 || allowed.includes(declared))
-            return declared;
-    }
-    return readReasoningEffort(model?.defaultParams);
-}
-/**
- * 把 Agent 的档位覆盖应用到模型参数上（`createModel` 用）。
- *
- * 未声明 `reasoningEffort` 时原样返回模型参数，保证既有行为不变。
- */
-export function resolveModelParams(model, definition) {
-    const declared = definition?.reasoningEffort;
-    if (!declared)
-        return model?.defaultParams;
-    const allowed = modelAllowedEfforts(model);
-    // 模型不支持声明值：宁可保持模型默认，也不发非法参数
-    if (allowed.length === 0 || !allowed.includes(declared))
-        return model?.defaultParams;
-    return applyReasoningEffort(model?.defaultParams, model, declared);
-}