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

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # 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
+
+- **`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

@@ -1,4 +1,4 @@
-import type { AppConfig, AgentDefinition } from "../types/index.js";
+import type { AppConfig, AgentDefinition, ReasoningPresets } from "../types/index.js";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
@@ -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>;
     /**
      * 确保基础目录结构存在。
@@ -52,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,8 @@ 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";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
@@ -17,13 +19,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 +73,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;
@@ -180,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

@@ -98,9 +98,15 @@ 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。
+    //
+    // reasoningPreset：思考策略名，引用 `<basePath>/reasoning-presets.json` 里的键
+    // （出厂内容见 `config/reasoning-presets.ts`，档位的协议差异全部写在表里）。
+    // 不写这个字段 = 不可调档（如 GLM-4.7 强制思考且无 reasoning_effort 参数）。
+    // 新接入端点时先在策略表里加一张表，再在这里引用它的名字。
     models: [
         // ---------- OpenAI ----------
         {
@@ -108,9 +114,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,
+            reasoningPreset: "openai",
             description: "OpenAI 最强旗舰（2026-09）：高级分析、软件工程、深度研究与科学工作",
         },
         {
@@ -118,9 +125,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,
+            reasoningPreset: "openai",
             description: "OpenAI 最新旗舰（2026-09-29）：Agentic Coding、计算机操作与文档密集型专业任务",
         },
         {
@@ -128,9 +136,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,
+            reasoningPreset: "openai",
             description: "OpenAI GPT-6 系列快速低成本模型：适合高吞吐、低延迟场景",
         },
         // ---------- 智谱 BigModel ----------
@@ -139,8 +148,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" },
+            reasoningPreset: "zhipu-5.3",
             description: "智谱最新旗舰：复杂软件工程与长程 Agent 任务（强制开启思考，1M 上下文）",
         },
         {
@@ -148,9 +158,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,
+            reasoningPreset: "zhipu-5.3",
             description: "智谱原生多模态模型（图片/视频/文件）：视觉 Coding，1M 上下文",
         },
         {
@@ -158,9 +169,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,
+            reasoningPreset: "zhipu-5.3",
             description: "GLM-5.3-Flash 高速版（200 tokens/s），原生多模态",
         },
         {
@@ -169,7 +181,7 @@ 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: {},
             description: "智谱免费文本模型：200K 上下文，适合轻量任务",
         },
@@ -179,9 +191,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,
+            reasoningPreset: "deepseek",
             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;
+};