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

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # 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
+
+- **`createReadMcpResourceTool(mcpManager)` → `createReadMcpResourceTool(mcpManager, env: ToolEnv)`** —— 与 alpha.11 的 `createCallMcpTool` 对齐：`env` 用于读取 `maxToolOutput` 并解析当前模型绑定的端点。直接调用该工厂的下游需补第二参。
+- **`view_image` 不再依赖 `deepseek` 端点** —— 此前本地图片固定上传到 `id === "deepseek"` 的端点，未配置时直接报「未配置 deepseek 端点，无法上传本地图片」。现在按能力位决定：声明 `capabilities.filesApi` 的端点走上传，其余走 base64 内联，没有 deepseek 也能查看本地图片。返回文案随之变化（含传输方式与降级说明）。
+- **`Endpoint` 新增可选字段 `capabilities`** —— 类型层面非破坏性（可选），但语义重要：缺省视为「无特殊能力」，即不做上传。
+
+### ✨ 新增
+
+- **「本地文件 → 内容块」统一入口 `shared/content-blocks.ts`**。这段逻辑此前散落三处各自为政（`ViewImageTool` 硬编码端点 id、MCP 媒体块归一、CLI 侧再实现一遍），现在收敛为一处：
+  - `fileToContentSection({ source, endpoint, model, signal, maxInlineBytes, deps })` → `{ section, transport, bytes, warning? }`；`source` 支持 `path` / `url` / `data`（`Uint8Array`）/ `base64` 四种来源。
+  - 决策链：http(s) URL → `image_url`；端点有 Files API → 上传得 `file_id`（失败**自动降级**为内联）；其余端点 + 图片 → `image_url` + base64 data URL；其余端点 + 非图片 → `file` 块 + `file_data`；非视觉模型 + 图片 → 文本提示；内联超限且无法上传 → 抛错（不静默塞进请求体）。
+  - 配套：`resolveModelAndEndpoint()`（按发给 API 的模型名反查模型与端点）、`supportsFilesApi()`、`mimeOf()` / `toDataUrl()` / `base64ByteLength()` / `contentHash()`、`clearUploadCache()`、`DEFAULT_MAX_INLINE_BYTES`（8 MiB）。
+  - **已从包入口 `src/index.ts` 导出为公共 API**（`fileToContentSection` / `resolveModelAndEndpoint` / `supportsFilesApi` / `mimeOf` / `toDataUrl` / `base64ByteLength` / `contentHash` / `clearUploadCache` / `MIME_BY_EXT` / `DEFAULT_MAX_INLINE_BYTES`，以及 `FileSource` / `FileToSectionInput` / `FileToSectionResult` / `ContentTransport` / `UploadFn` / `EndpointCapabilities` 类型）。上层应用构造媒体消息时直接复用，不要各自再实现一遍「上传 or 内联」。
+  - 上传缓存：路径来源用「端点 id + 绝对路径 + mtime + size」，内存来源用内容 sha256（同一张图不重复上传），上限 200 条。
+  - `deps.upload` 可注入，便于测试与替换上传实现。
+- **`Endpoint.capabilities.filesApi` 能力位** —— 出厂仅 `deepseek` 标记为 `true`（description 同步说明）。判据从「端点 id 是不是 deepseek」改为能力位，用户自建端点只要声明即可享受上传。
+
+### 🔧 修复
+
+- **MCP 媒体不再一律 base64 内联**：`call_mcp_tool` 的 `image` / `audio` / `resource.blob` 改走统一入口，端点有 Files API 能力时上传后以 `file_id` 发送，请求体不再随历史反复膨胀；转换失败**不丢块**，退化为一条文本说明，避免整个工具调用因媒体问题失败。
+- **`read_mcp_resource` 的二进制资源被静默丢弃**：此前只拼 `contents[].text`，图片 / PDF 等 `blob` 内容直接消失。新增 `resourceToMessageSection()`——注意 `readResource` 的 contents 形如 `{ uri, mimeType?, text|blob }`，**没有 `type` 判别字段**，不能复用 `toMessageSection`（否则文本资源会被 JSON 化）；`blob` 交给统一入口。
+- **`read_mcp_resource` 接入输出保护**：与 `call_mcp_tool` 共用同一套口径——文本超限落盘 `result.txt` 并返回头尾预览，媒体块原位保留；返回形态同样是「仅文本 → 字符串 / 含媒体 → 内容块数组」。
+- **非视觉模型退化**：`Model.vision !== true` 时图片退化为一行文本提示（本地路径来源与 MCP 内存 base64 来源均生效），避免 `image_url` 被服务端 4xx 拒掉。
+- **`edit` 并发护栏**：`edit` / `batch_edit` 工具描述明确「同一文件禁止并行 `edit`，多处修改改用 `batch_edit`，只有不同文件才能并行」——描述层劝阻（不引入运行时锁）。
+
+### ✅ 测试
+
+- 新增 `shared/content-blocks.test.ts` 16 例；`mcpTools.test.ts` 扩展覆盖媒体统一入口、非视觉退化、`read` 超限落盘与混排保序；`ViewImageTool` / `EditTool` / `BatchEditTool` 断言同步到新语义。
+- 全量 **55 文件 / 569 用例**通过（6 skipped），`tsc --noEmit` 与 `build` 零错误。
+
+### 📄 Docs
+
+- `docs/{zh,en}/sdk.md` 新增「本地文件 → 内容块（统一入口）」小节、`Endpoint` 能力位与 MCP 媒体 / 退化 / 输出保护说明。
+- `docs/{zh,en}/mcp.md` 同步 `call_mcp_tool` / `read_mcp_resource` 的媒体传输方式与输出保护口径。
+
+
 ## [1.0.0-alpha.11] - 2026-10-20
 
 ### 💥 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

@@ -82,7 +82,10 @@ export const DEFAULT_APP_CONFIG = {
             name: "DeepSeek",
             apiKey: "",
             baseUrl: "https://api.deepseek.com/v1",
-            description: "DeepSeek API 端点",
+            description: "DeepSeek API 端点（支持 Files API：本地文件上传后以 file_id 引用）",
+            // 唯一声明了 Files API 能力的出厂端点；其余端点本地文件走 base64 内联。
+            // 判断依据是能力位而非端点 id，用户自建端点只要声明即可享受上传。
+            capabilities: { filesApi: true },
         },
     ],
     // 模型清单（2026-10-03 依据各厂商官方来源核对）：
@@ -95,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 ----------
         {
@@ -105,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）：高级分析、软件工程、深度研究与科学工作",
         },
         {
@@ -115,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、计算机操作与文档密集型专业任务",
         },
         {
@@ -125,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 ----------
@@ -136,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 上下文）",
         },
         {
@@ -145,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 上下文",
         },
         {
@@ -155,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），原生多模态",
         },
         {
@@ -166,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 ----------
@@ -176,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 };
+}