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

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [1.0.0-alpha.13] - 2026-10-22
+
+### 💥 Breaking Changes
+
+- **`Model.maxContextTokens` / `maxContextChars` → `Model.tokenThresholds: { handoff, guard }`** —— 旧名字一直在误导（它既不是上下文窗口，也不是单一概念）。现在拆成两条**绝对值**：
+  - `handoff`：软线，响应返回后 `prompt_tokens` 超过它触发任务交接（`AutoMigratePlugin`）；
+  - `guard`：硬线，请求前用量超过它抛 `ContextOverflowError` 中断本轮（`ContextGuardPlugin`）。
+  - `maxContextChars` 直接淘汰（字符口径早于 token 口径，两者并存只会让「按哪个判」长期含糊）。
+  - 迁移由 `config/migrate.ts` 完成，`ConfigManager.read()` 读到即迁、`ensureDefaultConfig()` 检测差异才写盘：`maxContextTokens` → `handoff`，`maxContextChars` → `floor(/4)`，缺 `guard` 时按 1.5 倍折算一次（保持迁移前行为），旧键随即删除。
+- **`ContextGuardPlugin` 的 `ratio` / `suspendedRatio` / `isSuspended` 全部删除** —— 它们只是「相对阈值」的产物。现在 `new ContextGuardPlugin({ guardTokens })` 一个绝对数就够：想调松就把数字改大。代价是**交接回合不再有 2.0 倍的额外放宽**，若需要该缓冲请把 `guard` 配得更大（出厂取 `handoff × 1.5`，并写成整数）。
+- **`ContextOverflowError(promptTokens, guardTokens)`** —— 去掉 `maxTokens` / `ratio` / `threshold` 三个派生字段，改为直接暴露被越过的 `guardTokens`。
+- **`AutoMigratePlugin` 的 `maxTokens` → `handoffTokens`**，`AutoMigrateTriggerInfo.maxTokens` → `handoffTokens`，`HandoffService` 的 `HandoffParams.maxTokens` / `HandoffContext.maxTokens` → `handoffTokens`（仅字段改名，语义不变：交接阈值）。
+
+### ✨ 新增
+
+- **思考强度（reasoning effort）能力位** —— 档位此前完全没有建模，CLI 只能手改 `defaultParams`，而各家端点接受的值域并不相同（智谱 GLM-5.3 系对 `medium` 直接报错、对 `thinking.type = "disabled"` 也报错）。现在分三层：
+  - `Model.reasoning: { efforts: ReasoningEffort[], disable?: "thinking" | "effort-none" }` —— **物理能力上限**，按厂商官方文档声明（防 400）；
+  - `AgentDefinition.reasoningEffort?: ReasoningEffort` —— 该 Agent 的实际档位，在 `createModel` 阶段覆盖模型 `defaultParams`。于是同一模型可以给不同 Agent 配不同强度（编程 Agent `max`、闲聊 Agent `low`、闲聊小号 `off`）。
+  - 刻意**没有**做 Agent 侧的档位白名单（`reasoningEfforts`）：它解决的是伪需求（真正会 400 的是端点能力，那已由模型声明兜住），却引入「差一个 s」的命名陷阱与一层交集规则。
+- **`shared/reasoning.ts`**（公共 API，均从包入口导出）：`resolveReasoningEffort()`、`resolveModelParams()`、`applyReasoningEffort()`（按声明写入，非法档位抛错）、`modelEfforts()` / `modelAllowedEfforts()` / `readReasoningEffort()` / `isReasoningEffort()` / `capabilityOf()`，以及 `ReasoningEffort` / `ReasoningCapability` 类型。
+- **写入形态由声明决定**：`disable: "thinking"` → 同时维护 `thinking.type` 与 `reasoning_effort`（DeepSeek）；`disable: "effort-none"` → 只写 `reasoning_effort`（OpenAI 没有 `thinking` 参数，写它会被当未知参数）；未声明 `disable` → 只写 `reasoning_effort`，`off` 直接抛错（智谱 5.3 系）。
+- **出厂模型按官方文档声明能力**（依据已写入 `constants.ts` 注释）：
+  - `deepseek-flash` → `low/high/max`，可关闭（`api-docs.deepseek.com/guides/thinking_mode`）
+  - `glm-5.3` / `glm-5.3-flash` / `glm-5.3-flashx` → `low/high/max`，**不可关闭**（`docs.bigmodel.cn/cn/guide/capabilities/thinking`）
+  - `glm-4.7-flash` → 不可调（强制思考，`reasoning_effort` 仅 5.2+ 支持）
+  - `gpt-6-astra` / `gpt-6.1-sol` / `gpt-6-luna` → `minimal/low/medium/high`，可用 `reasoning_effort: "none"` 关闭
+  - 未声明的模型一律视为不可调档，不推测
+
+### 🔧 变更
+
+- **`createModel(scope, modelId)` → `createModel(scope, modelId, overrides?: Pick<AgentDefinition, "reasoningEffort">)`** —— 新增的可选第三参由 `createAgent` 传入 `definition.reasoningEffort`。不传时行为与以前完全一致（原样返回模型 `defaultParams`）。
+
+### ✅ 测试
+
+- 新增 `shared/reasoning.test.ts` 22 例：能力声明与出厂清单一致性、`off` 只对有 `disable` 的模型开放、GLM-5.3 设 `medium` 与 `off` 均抛错、OpenAI 永不写 `thinking` 键、往返一致性、Agent 覆盖与回退。
+- 新增 `config/migrate.test.ts` 13 例：旧字段迁移（tokens / chars / 两者 / 都无 / 脏值）、`guard` 折算、已是新形状时不迁移、不改入参、部分迁移时未变条目保持同一引用。
+- 全量 **57 文件 / 599 用例** 通过（6 skipped），`tsc --noEmit` 与 `build` 零错误。
+
+### 📄 Docs
+
+- `docs/{zh,en}/sdk.md` 新增「思考强度（reasoning effort）」小节（三层模型、出厂声明表、写入形态、公共 API），核心实体表补充 `Model.reasoning` 与 Agent 的两个档位字段。
+
 ## [1.0.0-alpha.12] - 2026-10-22
 
 ### 💥 Breaking Changes

package/dist/agent-plugins/AutoMigratePlugin.d.ts

@@ -4,8 +4,8 @@ import type { HandoffMode, HandoffService } from "../runtime/HandoffService.js";
 export interface AutoMigrateTriggerInfo {
     /** 当前 prompt token 用量 */
     promptTokens: number;
-    /** 上下文阈值（当前模型的 maxContextTokens） */
-    maxTokens: number;
+    /** 交接阈值（当前模型的 tokenThresholds.handoff） */
+    handoffTokens: number;
 }
 /**
  * 迁移执行者解析器：只负责「用什么方式交接」，不负责「何时迁移」。
@@ -19,7 +19,7 @@ export interface AutoMigrateOptions {
     /** 交接服务实例（持有交接前后钩子；编排 handoff / migrate 两条链路） */
     service: HandoffService;
     /** 触发迁移的上下文阈值 */
-    maxTokens: number;
+    handoffTokens: number;
     /**
      * 执行者解析（可选）。上层可在此弹确认框、读用户偏好，
      * 或直接返回 `null` 表达「本次不迁移」——**无需**再继承本插件。
@@ -29,14 +29,14 @@ export interface AutoMigrateOptions {
 /**
  * 自动迁移插件 —— 只负责「何时触发」，实际迁移统一委托给持有的 `HandoffService`。
  *
- * 当 `usage.prompt_tokens` 超过 maxTokens 时触发迁移：
+ * 当 `usage.prompt_tokens` 超过 handoffTokens 时触发迁移：
  *
  * ```ts
  * agent.use(new AutoMigratePlugin({
  *   service: handoffService,
- *   maxTokens: 250_000,
- *   resolveMode: async ({ promptTokens, maxTokens }) =>
- *     (await askUser(promptTokens, maxTokens)) ? "self" : null,
+ *   handoffTokens: 250_000,
+ *   resolveMode: async ({ promptTokens, handoffTokens }) =>
+ *     (await askUser(promptTokens, handoffTokens)) ? "self" : null,
  * }));
  * ```
  *

package/dist/agent-plugins/AutoMigratePlugin.js

@@ -3,14 +3,14 @@ const log = getLogger();
 /**
  * 自动迁移插件 —— 只负责「何时触发」，实际迁移统一委托给持有的 `HandoffService`。
  *
- * 当 `usage.prompt_tokens` 超过 maxTokens 时触发迁移：
+ * 当 `usage.prompt_tokens` 超过 handoffTokens 时触发迁移：
  *
  * ```ts
  * agent.use(new AutoMigratePlugin({
  *   service: handoffService,
- *   maxTokens: 250_000,
- *   resolveMode: async ({ promptTokens, maxTokens }) =>
- *     (await askUser(promptTokens, maxTokens)) ? "self" : null,
+ *   handoffTokens: 250_000,
+ *   resolveMode: async ({ promptTokens, handoffTokens }) =>
+ *     (await askUser(promptTokens, handoffTokens)) ? "self" : null,
  * }));
  * ```
  *
@@ -26,22 +26,22 @@ export class AutoMigratePlugin {
     }
     async onAfterSend(ctx) {
         const agent = ctx.agent;
-        const { service, maxTokens, resolveMode } = this.options;
+        const { service, handoffTokens, resolveMode } = this.options;
         // 交接/迁移进行中：让行（防递归）
         if (service.busy)
             return;
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
-        if (promptTokens <= maxTokens)
+        if (promptTokens <= handoffTokens)
             return;
         try {
             const mode = resolveMode
-                ? await resolveMode({ promptTokens, maxTokens })
+                ? await resolveMode({ promptTokens, handoffTokens })
                 : undefined;
             if (mode === null)
                 return; // 用户选择跳过本次迁移
-            await service.migrate({ agent, promptTokens, maxTokens, mode: mode ?? undefined });
+            await service.migrate({ agent, promptTokens, handoffTokens, mode: mode ?? undefined });
         }
         catch (err) {
             log.error(`[autoMigrate] 迁移失败: ${err?.message ?? err}`);

package/dist/agent-plugins/ContextGuardPlugin.d.ts

@@ -1,44 +1,32 @@
 import type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
 export interface ContextGuardOptions {
-    /** 上下文告警阈值（token）。用量超过 maxTokens × ratio 即中断。 */
-    maxTokens: number;
     /**
-     * 超出比例。用量 > maxTokens × ratio 时判定为「严重超限」（如读入超大文件），
-     * 在请求前抛出 ContextOverflowError 中断对话。默认 1.5（即 +50%）。
-     */
-    ratio?: number;
-    /**
-     * 是否处于「需要放宽」的阶段（例如交接回合）。返回 true 时改用 `suspendedRatio`。
+     * 强行阻断阈值（tokens，绝对值）。
      *
-     * 为什么需要：交接恰好发生在上下文最满的时刻，而交接回合本身还要再发 1~2 次请求。
-     * 若仍按 1.5 倍判定，正常交接会被护栏误杀；完全让行又会失去熔断，故改为放宽而非放行。
+     * 语义只有一条：请求前上一轮用量超过它 → 中断本轮。没有倍数、没有放宽档——
+     * 想调松就把它调大，「安全边界写多少就是多少」比「隐式乘以某个系数」可预测得多。
      */
-    isSuspended?: () => boolean;
-    /** 放宽后的比例，默认 2.0（即 maxTokens × 2） */
-    suspendedRatio?: number;
+    guardTokens: number;
 }
 /**
  * 上下文安全护栏插件。
  *
- * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：
- * - 若用量超过 maxTokens × ratio，说明上下文已严重超限（通常因读入超大文件），
- *   在请求前抛出 ContextOverflowError，**中断对话**，交由上层向用户报错。
+ * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：超过 `guardTokens`
+ * 即抛 `ContextOverflowError` 中断对话，交由上层向用户报错。
  *
  * 与迁移插件职责分离：
- * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
- * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
- * - 交接回合由 `isSuspended` 放宽阈值（而非完全让行），保证交接不被误杀、又保留熔断。
+ * - `ContextGuardPlugin`：硬线，只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
+ * - `AutoMigratePlugin`：软线（`tokenThresholds.handoff`），在正常范围内做交接迁移。
+ *   两条线都是绝对值，`guard` 应当明显大于 `handoff`，交接回合的额外请求才有余量。
  *
  * ```ts
- * agent.use(new ContextGuardPlugin({
- *   maxTokens: 250_000,
- *   isSuspended: () => handoffService.busy,
- * }));
- * agent.use(new AutoMigratePlugin({ service: handoffService, maxTokens: 250_000 }));
+ * const { handoff, guard } = config.models[i].tokenThresholds;
+ * agent.use(new ContextGuardPlugin({ guardTokens: guard }));
+ * agent.use(new AutoMigratePlugin({ service: handoffService, handoffTokens: handoff }));
  * ```
  */
 export declare class ContextGuardPlugin implements AgentPlugin {
-    private options;
+    private readonly guardTokens;
     constructor(options: ContextGuardOptions);
     onInnerLoopStart(ctx: SendContext): Promise<void>;
 }

package/dist/agent-plugins/ContextGuardPlugin.js

@@ -2,39 +2,32 @@ import { ContextOverflowError } from "../shared/errors.js";
 /**
  * 上下文安全护栏插件。
  *
- * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：
- * - 若用量超过 maxTokens × ratio，说明上下文已严重超限（通常因读入超大文件），
- *   在请求前抛出 ContextOverflowError，**中断对话**，交由上层向用户报错。
+ * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：超过 `guardTokens`
+ * 即抛 `ContextOverflowError` 中断对话，交由上层向用户报错。
  *
  * 与迁移插件职责分离：
- * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
- * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
- * - 交接回合由 `isSuspended` 放宽阈值（而非完全让行），保证交接不被误杀、又保留熔断。
+ * - `ContextGuardPlugin`：硬线，只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
+ * - `AutoMigratePlugin`：软线（`tokenThresholds.handoff`），在正常范围内做交接迁移。
+ *   两条线都是绝对值，`guard` 应当明显大于 `handoff`，交接回合的额外请求才有余量。
  *
  * ```ts
- * agent.use(new ContextGuardPlugin({
- *   maxTokens: 250_000,
- *   isSuspended: () => handoffService.busy,
- * }));
- * agent.use(new AutoMigratePlugin({ service: handoffService, maxTokens: 250_000 }));
+ * const { handoff, guard } = config.models[i].tokenThresholds;
+ * agent.use(new ContextGuardPlugin({ guardTokens: guard }));
+ * agent.use(new AutoMigratePlugin({ service: handoffService, handoffTokens: handoff }));
  * ```
  */
 export class ContextGuardPlugin {
-    options;
+    guardTokens;
     constructor(options) {
-        this.options = options;
+        this.guardTokens = options.guardTokens;
     }
     async onInnerLoopStart(ctx) {
-        const { agent } = ctx;
-        const { maxTokens, ratio = 1.5, isSuspended, suspendedRatio = 2 } = this.options;
+        const promptTokens = ctx.agent.lastUsage?.prompt_tokens;
         // 首轮请求前尚无用量数据，跳过（只能在发出首轮请求、拿到 usage 后才有据可查）
-        const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
-        // 交接回合等需要放宽的阶段：放宽阈值但保留熔断
-        const effectiveRatio = isSuspended?.() ? suspendedRatio : ratio;
-        if (promptTokens > maxTokens * effectiveRatio) {
-            throw new ContextOverflowError(promptTokens, maxTokens, effectiveRatio);
+        if (promptTokens > this.guardTokens) {
+            throw new ContextOverflowError(promptTokens, this.guardTokens);
         }
     }
 }

package/dist/config/ConfigManager.d.ts

@@ -8,8 +8,14 @@ export declare class ConfigManager {
     constructor(configPath: string);
     /**
      * 读取配置。文件不存在时返回出厂默认配置。
+     *
+     * 读到即**迁移**（`config/migrate.ts`）：上层拿到的永远是当前字段形状，
+     * 旧字段（`maxContextTokens` / `maxContextChars`）不会漏到调用方。
+     * 迁移结果不在这里落盘——落盘只在 `ensureDefaultConfig()` 做一次。
      */
     read(): Promise<AppConfig>;
+    /** 读磁盘原文（不做任何迁移/同步），供 `ensureDefaultConfig()` 对比写盘用 */
+    private readRaw;
     write(config: AppConfig): Promise<void>;
     /**
      * 确保基础目录结构存在。

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 { migrateConfig } from "./migrate.js";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
@@ -17,13 +18,22 @@ export class ConfigManager {
     // -----------------------------------------------------------------------
     /**
      * 读取配置。文件不存在时返回出厂默认配置。
+     *
+     * 读到即**迁移**（`config/migrate.ts`）：上层拿到的永远是当前字段形状，
+     * 旧字段（`maxContextTokens` / `maxContextChars`）不会漏到调用方。
+     * 迁移结果不在这里落盘——落盘只在 `ensureDefaultConfig()` 做一次。
      */
     async read() {
+        const raw = await this.readRaw();
+        return raw ? migrateConfig(raw).config : { ...DEFAULT_APP_CONFIG };
+    }
+    /** 读磁盘原文（不做任何迁移/同步），供 `ensureDefaultConfig()` 对比写盘用 */
+    async readRaw() {
         try {
             await fs.access(this.configPath);
         }
         catch {
-            return { ...DEFAULT_APP_CONFIG };
+            return null;
         }
         const raw = await fs.readFile(this.configPath, "utf-8");
         return JSON.parse(raw);
@@ -62,18 +72,16 @@ export class ConfigManager {
      * 条目视为用户自有，原样保留。同步结果与磁盘内容一致时不写盘。
      */
     async ensureDefaultConfig() {
-        let existing;
-        try {
-            await fs.access(this.configPath);
-            existing = await this.read();
-        }
-        catch {
+        const onDisk = await this.readRaw();
+        if (!onDisk) {
             await this.ensureDirs();
             await this.write(DEFAULT_APP_CONFIG);
             return { ...DEFAULT_APP_CONFIG };
         }
-        const synced = syncManagedModels(existing);
-        if (JSON.stringify(synced) !== JSON.stringify(existing)) {
+        // 先迁移历史字段，再同步出厂模型清单；两者结果与磁盘原文不同才写盘
+        const migrated = migrateConfig(onDisk).config;
+        const synced = syncManagedModels(migrated);
+        if (JSON.stringify(synced) !== JSON.stringify(onDisk)) {
             await this.write(synced);
         }
         return synced;

package/dist/config/constants.js

@@ -98,9 +98,20 @@ export const DEFAULT_APP_CONFIG = {
     // 标了 `custom: true` 的条目视为用户自有，原样保留。实现见
     // ConfigManager.syncManagedModels。
     //
-    // maxContextTokens 是「任务迁移（交接）触发阈值」，不是模型的真实上下文窗口：
-    // 迁移判断只看 API 响应返回的 usage.prompt_tokens。窗口 ≥1M 的模型统一取 250K
-    // （约 25%），glm-4.7-flash 窗口仅 200K，取 100K。
+    // tokenThresholds 的两条线都与模型的真实上下文窗口无关：
+    //   handoff（软线，交接触发）与 guard（硬线，请求前强行阻断）。
+    // 出厂取值：窗口 ≥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()` 返回空数组。
     models: [
         // ---------- OpenAI ----------
         {
@@ -108,9 +119,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "GPT-6 Astra",
             endpointId: "openai",
             modelName: "gpt-6-astra",
-            maxContextTokens: 250_000,
+            tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: {},
             vision: true,
+            reasoning: { efforts: ["minimal", "low", "medium", "high"], disable: "effort-none" },
             description: "OpenAI 最强旗舰（2026-09）：高级分析、软件工程、深度研究与科学工作",
         },
         {
@@ -118,9 +130,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "GPT-6.1 Sol",
             endpointId: "openai",
             modelName: "gpt-6.1-sol",
-            maxContextTokens: 250_000,
+            tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: {},
             vision: true,
+            reasoning: { efforts: ["minimal", "low", "medium", "high"], disable: "effort-none" },
             description: "OpenAI 最新旗舰（2026-09-29）：Agentic Coding、计算机操作与文档密集型专业任务",
         },
         {
@@ -128,9 +141,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "GPT-6 Luna",
             endpointId: "openai",
             modelName: "gpt-6-luna",
-            maxContextTokens: 250_000,
+            tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: {},
             vision: true,
+            reasoning: { efforts: ["minimal", "low", "medium", "high"], disable: "effort-none" },
             description: "OpenAI GPT-6 系列快速低成本模型：适合高吞吐、低延迟场景",
         },
         // ---------- 智谱 BigModel ----------
@@ -139,8 +153,9 @@ export const DEFAULT_APP_CONFIG = {
             name: "GLM-5.3",
             endpointId: "bigmodelcn",
             modelName: "glm-5.3",
-            maxContextTokens: 250_000,
+            tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+            reasoning: { efforts: ["low", "high", "max"] },
             description: "智谱最新旗舰：复杂软件工程与长程 Agent 任务（强制开启思考，1M 上下文）",
         },
         {
@@ -148,9 +163,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "GLM-5.3-Flash",
             endpointId: "bigmodelcn",
             modelName: "glm-5.3-flash",
-            maxContextTokens: 250_000,
+            tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
             vision: true,
+            reasoning: { efforts: ["low", "high", "max"] },
             description: "智谱原生多模态模型（图片/视频/文件）：视觉 Coding，1M 上下文",
         },
         {
@@ -158,9 +174,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "GLM-5.3-FlashX",
             endpointId: "bigmodelcn",
             modelName: "glm-5.3-flashx",
-            maxContextTokens: 250_000,
+            tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
             vision: true,
+            reasoning: { efforts: ["low", "high", "max"] },
             description: "GLM-5.3-Flash 高速版（200 tokens/s），原生多模态",
         },
         {
@@ -169,8 +186,9 @@ export const DEFAULT_APP_CONFIG = {
             endpointId: "bigmodelcn",
             modelName: "glm-4.7-flash",
             // 该模型真实窗口仅 200K，阈值下调至 100K（约窗口的 50%），留足 response 空间
-            maxContextTokens: 100_000,
+            tokenThresholds: { handoff: 100_000, guard: 150_000 },
             defaultParams: {},
+            reasoning: { efforts: [] },
             description: "智谱免费文本模型：200K 上下文，适合轻量任务",
         },
         // ---------- DeepSeek ----------
@@ -179,9 +197,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "DeepSeek-V4.1-Flash",
             endpointId: "deepseek",
             modelName: "deepseek-flash",
-            maxContextTokens: 250_000,
+            tokenThresholds: { handoff: 250_000, guard: 375_000 },
             defaultParams: { thinking: { type: "enabled" } },
             vision: true,
+            reasoning: { efforts: ["low", "high", "max"], disable: "thinking" },
             description: "DeepSeek 旗舰（2026-09-10）：552B MoE 非对称架构，原生多模态，1M 上下文",
         },
     ],

package/dist/config/migrate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 配置字段迁移 —— 历史形状升级到当前形状
+ *
+ * 三条遗留字段被淘汰：
+ *
+ * 1. `Model.maxContextTokens` / `Model.maxContextChars` → **`Model.tokenThresholds`**
+ *    旧名字一直在误导：它既不是「模型的真实上下文窗口」，也不是单一概念。现在拆成两条线：
+ *    `handoff`（交接阈值，软线）与 `guard`（强行阻断阈值，硬线）。
+ *    `maxContextChars` 是 token 口径之前的历史遗留，按 `floor(chars / 4)` 折成 tokens
+ *    （与旧代码的回退算法一致）后并入 `handoff`。
+ *
+ * 迁移时机：`ConfigManager.read()` 读出即迁（内存里永远是当前形状）；
+ * 落盘由 `ensureDefaultConfig()` 负责 —— 它比较迁移结果与磁盘原文，不同才写回，
+ * 因此迁移只发生一次，且不会在每次启动时无谓地改写文件。
+ */
+import type { AppConfig, Model } from "../types/index.js";
+/** 当前字段名 */
+export declare const TOKEN_THRESHOLDS_KEY = "tokenThresholds";
+/** 已淘汰的旧字段名（仅迁移代码认识它们） */
+export declare const LEGACY_TOKEN_FIELD = "maxContextTokens";
+export declare const LEGACY_CHARS_FIELD = "maxContextChars";
+/**
+ * 旧数据缺失阈值时的交接阈值兜底。
+ *
+ * 与 CLI 新建模型的默认值一致；宁可给一个保守值，也不要让模型缺阈值——
+ * 缺阈值意味着既没有交接触发、也没有阻断保护。
+ */
+export declare const DEFAULT_HANDOFF_THRESHOLD = 128000;
+/**
+ * 迁移单个模型条目。
+ *
+ * 优先级：已有 `tokenThresholds` 的成员 > 旧 tokens 字段 > 旧 chars 字段折算 > 兜底默认。
+ * 旧字段一律删除（连同一份数据里残留的脏值），保证迁移后的形状唯一。
+ * 已有 `handoff` 但缺 `guard` 时按 1.5 倍补齐。
+ */
+export declare function migrateModelThresholds(model: Model): {
+    model: Model;
+    changed: boolean;
+};
+/**
+ * 迁移整个配置。只处理对话模型（`models`）——
+ * 图片模型（`imageModels`）从来没有上下文阈值概念。
+ */
+export declare function migrateConfig(config: AppConfig): {
+    config: AppConfig;
+    changed: boolean;
+};

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/index.d.ts

@@ -25,6 +25,7 @@ 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

@@ -24,6 +24,8 @@ 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/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,9 @@ 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`）。
  */
-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,16 @@
 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` 不变。
+ * 写入方式按模型的 `reasoning` 能力声明决定（见 `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 +30,7 @@ export function createModel(scope, modelId) {
     return {
         client,
         model: apiModelName,
-        modelConfig: modelConfig.defaultParams,
+        // 档位覆盖在这里生效：未声明 reasoningEffort 时原样返回模型 defaultParams
+        modelConfig: resolveModelParams(modelConfig, overrides),
     };
 }

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,64 @@
+/**
+ * 思考强度（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

@@ -0,0 +1,151 @@
+/**
+ * 思考强度（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);
+}

package/dist/types/index.d.ts

@@ -25,6 +25,35 @@ 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` 是「没有档位、彻底不思考」。
+ */
+export type ReasoningEffort = "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * 模型/端点的思考能力声明（**物理上限**，来自厂商官方文档）。
+ *
+ * 刻意不推断、不猜：未声明的模型视为「不可调档」，`/think` 不会列任何选项——
+ * 发一个端点不认的值会被直接报错（智谱 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";
+}
 /** API 端点 */
 export interface Endpoint {
     id: string;
@@ -34,6 +63,24 @@ export interface Endpoint {
     description?: string;
     capabilities?: EndpointCapabilities;
 }
+/**
+ * 上下文用量阈值 —— 与模型的真实窗口无关，只描述「用量到了这条线该怎么办」。
+ *
+ * 两个阈值语义不同，消费方也不同：
+ *   - `handoff`：软线。`AutoMigratePlugin` 在响应返回后拿 `usage.prompt_tokens` 比它，
+ *     超过即触发任务交接（交接本身还要再发 1~2 次请求，所以这条线必须留足余量）。
+ *   - `guard`：硬线。`ContextGuardPlugin` 在**每次请求前**比它，超过即抛
+ *     `ContextOverflowError` 中断本轮——这是最后一道保护，宁可报错也不要发出必然失败的请求。
+ *
+ * 建议 `guard ≈ handoff × 1.5`，给交接留出缓冲；两者都是绝对值，配置里写多少就是多少，
+ * 不做任何倍数换算（阈值就该是能直接读懂的数字）。
+ */
+export interface TokenThresholds {
+    /** 交接阈值（软线）：prompt_tokens 超过它 → 触发任务交接 */
+    handoff: number;
+    /** 强行阻断阈值（硬线）：请求前用量超过它 → 中断本轮并报错 */
+    guard: number;
+}
 /** 模型配置，绑定一个 Endpoint */
 export interface Model {
     id: string;
@@ -41,15 +88,20 @@ export interface Model {
     endpointId: string;
     modelName?: string;
     /**
-     * 任务迁移（交接）触发阈值 —— **不是**模型的真实上下文窗口。
+     * 上下文用量阈值（交接软线 + 阻断硬线）。**不是**模型的真实上下文窗口。
      *
-     * AutoMigratePlugin 不估算、不学习：只在 API 响应返回后，用 `usage.prompt_tokens`
-     * 与该值比较，超过即触发交接迁移。建议取模型真实窗口的约 25%，为 response 留出空间。
+     * 历史字段 `maxContextTokens` / `maxContextChars` 已由 `config/migrate.ts`
+     * 迁移成这个结构体并删除。
      */
-    maxContextTokens: number;
-    /** 旧版字符数阈值（兼容迁移） */
-    maxContextChars?: number;
+    tokenThresholds: TokenThresholds;
     defaultParams?: Record<string, unknown>;
+    /**
+     * 思考强度能力（按厂商官方文档声明）。缺省视为不可调档。
+     *
+     * Agent 用 `AgentDefinition.reasoningEffort` 在这个范围内选一档；
+     * 超出范围的值不会发给服务端（`resolveModelParams()` 会退回模型默认）。
+     */
+    reasoning?: ReasoningCapability;
     /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
@@ -69,6 +121,13 @@ export interface AgentDefinition {
     description?: string;
     messages: AgentNS.Message[];
     modelId?: string;
+    /**
+     * 该 Agent 的思考档位（可选），覆盖模型 `defaultParams` 里的对应参数。
+     *
+     * 有了它，同一个模型可以给不同 Agent 配不同强度（编程 Agent `max`、闲聊 Agent `low`），
+     * 而模型本身的默认参数保持不变。未声明时沿用模型默认。
+     */
+    reasoningEffort?: ReasoningEffort;
     permissions?: AgentPermissions;
     function?: AgentNS.FunctionDefine;
     createdAt: string;

package/package.json

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