@ai-zen/agents-sdk 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/config/constants.js

@@ -4,11 +4,20 @@ import { Message } from "@ai-zen/agents-core";
 // ---------------------------------------------------------------------------
 /** 默认 Agent ID */
 export const DEFAULT_AGENT_ID = "default";
+/**
+ * 出厂默认模型 id。
+ *
+ * 模型的**唯一真相源是 `AgentDefinition.modelId`**：配置里不再有 `defaultModel`，
+ * 会话存档里也不记模型。这个常量只用于给出厂默认 Agent 填一个初始值。
+ */
+export const DEFAULT_MODEL_ID = "deepseek-flash";
 /** 默认 Agent 定义（不含时间戳） */
 export const DEFAULT_AGENT_DEFINITION = {
     id: DEFAULT_AGENT_ID,
     name: "默认助手",
     description: "默认的 AI 助手，适用于日常问答和任务执行。",
+    // 模型写在 Agent 定义上，是运行期唯一真相源（无 config.defaultModel 兜底）
+    modelId: DEFAULT_MODEL_ID,
     messages: [
         Message.System(`你是一个幽默风趣、严谨可靠的智能助手，请用中文回复。当前操作系统：${process.platform}。
 
@@ -82,7 +91,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 +107,16 @@ 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：应用层元数据，**SDK 不解释**（既不参与请求参数生成，也不影响运行行为）。
+    // 它由客户端（如 CLI）自己定义含义：指向哪张思考档位表、`/think` 能选哪几档。
+    // 之所以留在出厂定义里：字段声明与行为消费是两件事，出厂模型需要把它带上，
+    // 否则 `syncManagedModels` 会用出厂定义整块覆盖并抹掉应用声明的值。
+    // 不写这个字段 = 应用层视作「不可调档」（如 GLM-4.7 强制思考且无 reasoning_effort 参数）。
     models: [
         // ---------- OpenAI ----------
         {
@@ -105,9 +124,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）：高级分析、软件工程、深度研究与科学工作",
         },
         {
@@ -115,9 +135,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、计算机操作与文档密集型专业任务",
         },
         {
@@ -125,9 +146,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 ----------
@@ -136,8 +158,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 上下文）",
         },
         {
@@ -145,9 +168,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 上下文",
         },
         {
@@ -155,9 +179,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），原生多模态",
         },
         {
@@ -166,7 +191,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 上下文，适合轻量任务",
         },
@@ -176,9 +201,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 上下文",
         },
     ],
@@ -206,7 +232,6 @@ export const DEFAULT_APP_CONFIG = {
             defaultSize: "1024x1024",
         },
     ],
-    defaultModel: "deepseek-flash",
     defaultImageModel: "cogview-4",
     defaultAgent: "default",
     defaultMigrationModel: "deepseek-flash",

package/dist/config/factory-skills.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 出厂 Skill 资产 —— 随 SDK 版本释放到 `<basePath>/skills/<id>/SKILL.md`。
+ *
+ * 为什么以 TS 字符串常量内联、而不是独立 .md 文件：
+ * SDK 用 `tsc` 直接编译，不拷贝非 TS 资源；内容内联后 `dist/` 天然携带，
+ * 无需额外打包步骤，也不依赖包内相对资源路径。
+ *
+ * 覆盖策略（与 `syncManagedModels` 同构）：
+ *   - 磁盘上的 SKILL.md frontmatter 里写了 `custom: "true"` → 视为用户自有，永不被覆盖；
+ *   - 否则每次 `ConfigManager.bootstrap()` 同步为当前版本内容（模板属于产品行为，
+ *     改进了就要让老用户吃到）。
+ */
+/** 交接 Skill 的 id（目录名 = frontmatter name） */
+export declare const HANDOFF_SKILL_ID = "handoff";
+/**
+ * 交接文档兜底模板。
+ *
+ * 仅在磁盘上读不到 `handoff` Skill 时使用（用户删除 / 目录不可读）。
+ * 它是**保险丝**，不是第二真相源：正常路径下模板一律来自 SKILL.md。
+ */
+export declare const FALLBACK_HANDOFF_TEMPLATE: string;
+/** 全部出厂 Skill（顺序无意义，按 id 去重） */
+export declare const FACTORY_SKILLS: readonly {
+    id: string;
+    content: string;
+}[];
+/**
+ * 判断一份 SKILL.md 是否被用户声明为自有。
+ *
+ * 只检查 frontmatter 区块内的 `custom: true`（允许带引号），
+ * 正文里出现同样的字样不生效——避免误判导致模板停止更新。
+ */
+export declare function isCustomSkill(content: string): boolean;

package/dist/config/factory-skills.js

@@ -0,0 +1,126 @@
+/**
+ * 出厂 Skill 资产 —— 随 SDK 版本释放到 `<basePath>/skills/<id>/SKILL.md`。
+ *
+ * 为什么以 TS 字符串常量内联、而不是独立 .md 文件：
+ * SDK 用 `tsc` 直接编译，不拷贝非 TS 资源；内容内联后 `dist/` 天然携带，
+ * 无需额外打包步骤，也不依赖包内相对资源路径。
+ *
+ * 覆盖策略（与 `syncManagedModels` 同构）：
+ *   - 磁盘上的 SKILL.md frontmatter 里写了 `custom: "true"` → 视为用户自有，永不被覆盖；
+ *   - 否则每次 `ConfigManager.bootstrap()` 同步为当前版本内容（模板属于产品行为，
+ *     改进了就要让老用户吃到）。
+ */
+/** 交接 Skill 的 id（目录名 = frontmatter name） */
+export const HANDOFF_SKILL_ID = "handoff";
+/**
+ * 交接文档兜底模板。
+ *
+ * 仅在磁盘上读不到 `handoff` Skill 时使用（用户删除 / 目录不可读）。
+ * 它是**保险丝**，不是第二真相源：正常路径下模板一律来自 SKILL.md。
+ */
+export const FALLBACK_HANDOFF_TEMPLATE = [
+    "# 交接文档",
+    "",
+    "立即停工：不再实现任何功能、不继续未完成任务、不向用户提问。",
+    "唯一任务是：核实当前真实状态 → 把交接文档写到「本次交接参数」给出的路径。",
+    "",
+    "## 💬 对话断点",
+    "## 🎯 任务目标",
+    "## 📊 当前状态",
+    "## ✅ 已完成",
+    "## 📋 未完成",
+    "## 🧠 关键决策",
+    "## ⚠️ 约束与偏好",
+    "## 📁 文件索引",
+    "## 🔔 接手第一步",
+    "",
+    "无法核实的信息写「⚠️ 未核实」，禁止推测。",
+].join("\n");
+/** 出厂 Skill：交接（handoff） */
+const HANDOFF_SKILL = `---
+name: handoff
+description: 编写任务交接文档——对话停手离场时，把任务目标、当前真实状态、关键决策与下一步写成一份可被他人直接接手的文档。
+metadata:
+  custom: "false"
+---
+
+# 交接文档书写规范
+
+## 何时适用
+
+上下文即将超限触发任务迁移、用户明确要求「写交接文档」、或你被要求「交班」时。
+
+## 铁律（违反即视为失败）
+
+1. **立即停工**：不再实现任何功能、不继续未完成的任务、不顺手修 bug、不做重构。
+2. **不向用户提问**，不做方案讨论，不征求确认。
+3. 只做两件事：**核实当前真实状态** → **写文档**。
+4. 允许读取类操作（read / ls / glob / find_text / inspect_file / cwd，以及 git status、git diff、git log 等只读命令）。
+   禁止修改工作区：不改源码、不 npm install、不 commit、不 push。唯一允许写入的文件是交接文档本身。
+5. **一次性写完**，不要反复重写；不要读大文件；不要把长代码贴进文档。
+
+## 落盘
+
+路径由「本次交接参数」给出，**原样使用**，不得改名、不得换目录、不得省略。
+用 write 工具写入后，用 read 回读一次，确认内容完整（无 read 能力时跳过此步）。
+
+## 文档结构（按序书写，标题保持原样）
+
+## 💬 对话断点
+用户最后要求了什么、你最后回复/交付了什么。各一段，不要复述整段对话。
+
+## 🎯 任务目标
+用户到底想要什么（意图与验收标准），而不是你执行过的步骤清单。
+
+## 📊 当前状态
+分支与 commit、未提交改动、测试是否通过、有无进程/端口在跑、依赖是否装好。
+
+## ✅ 已完成
+每项写：做了什么 + 产出路径（文件/目录） + 怎么验证它确实生效。
+
+## 📋 未完成
+按优先级排列；每项写「下一步最小动作」，具体到文件或可执行命令。
+
+## 🧠 关键决策
+为什么这样做（取舍理由）；以及走过的死路——防止接手者重蹈覆辙。
+
+## ⚠️ 约束与偏好
+用户强调过的规矩、项目约定、不可改动的部分、必须遵守的风格。
+
+## 📁 文件索引
+路径 + 作用 + 本次是否改动（新增 / 修改 / 仅阅读）。
+
+## 🔔 接手第一步
+3 条以内可直接执行的命令或动作，让接手者立刻能开工。
+
+## 状态核实清单
+
+- \`git status\` / \`git diff --stat\`：当前分支、是否有未提交改动
+- 最近一次测试结果：跑过就写结果摘要；没跑就写「未运行」，**不要写「应该能过」**
+- 交接涉及的关键文件：用 ls / read 确认确实存在于磁盘
+- 正在运行的服务与端口：\`ps\` / \`lsof -i\` 或项目自带的启动脚本
+
+> ⚠️ 若「本次交接参数」声明工具不可用：以上每一项都写「⚠️ 未核实」，**禁止推测**具体路径、进度与测试状态。
+
+## 写作要求
+
+- 每句话都要让接手者能「立刻开始干活」；禁止「继续开发」「完善功能」「优化一下」这类空话。
+- 已无法在当前上下文中确定的信息，写「需向用户确认 XXX」，不要编造。
+- 全文控制在 300 行以内。
+`;
+/** 全部出厂 Skill（顺序无意义，按 id 去重） */
+export const FACTORY_SKILLS = [
+    { id: HANDOFF_SKILL_ID, content: HANDOFF_SKILL },
+];
+/**
+ * 判断一份 SKILL.md 是否被用户声明为自有。
+ *
+ * 只检查 frontmatter 区块内的 `custom: true`（允许带引号），
+ * 正文里出现同样的字样不生效——避免误判导致模板停止更新。
+ */
+export function isCustomSkill(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return false;
+    return /^\s*custom:\s*["']?true["']?\s*$/m.test(match[1]);
+}

package/dist/config/migrate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 配置字段迁移 —— 历史形状升级到当前形状
+ *
+ * 三条遗留字段被淘汰：
+ *
+ * 1. `Model.maxContextTokens` / `Model.maxContextChars` → **`Model.tokenThresholds`**
+ *    旧名字一直在误导：它既不是「模型的真实上下文窗口」，也不是单一概念。现在拆成两条线：
+ *    `handoff`（交接阈值，软线）与 `guard`（强行阻断阈值，硬线）。
+ *    `maxContextChars` 是 token 口径之前的历史遗留，按 `floor(chars / 4)` 折成 tokens
+ *    （与旧代码的回退算法一致）后并入 `handoff`。
+ * 2. **`Model.reasoning` → `Model.reasoningPreset`**
+ *    alpha.13 曾用 `reasoning: { efforts, disable? }` 在模型上声明思考能力，后来改成
+ *    「引用策略表里的名字」。未标 `custom` 的模型会被出厂定义整块覆盖，但**标了 `custom`
+ *    的模型会原地保留**，于是留下一个无人认识的 `reasoning` 死字段，同时因为缺
+ *    `reasoningPreset` 而默默失去调档能力。这里删掉旧字段，并按**同 id 的出厂模型**
+ *    补上正确的策略名（同一 id 即同一厂商型号，协议能力不会因用户改过参数而变）。
+ *
+ * 迁移时机：`ConfigManager.read()` 读出即迁（内存里永远是当前形状）；
+ * 落盘由 `ensureDefaultConfig()` 负责 —— 它比较迁移结果与磁盘原文，不同才写回，
+ * 因此迁移只发生一次，且不会在每次启动时无谓地改写文件。
+ */
+import 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";
+export declare const LEGACY_REASONING_FIELD = "reasoning";
+/**
+ * 旧数据缺失阈值时的交接阈值兜底。
+ *
+ * 与 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;
+};
+/**
+ * 迁移单个模型的思考能力声明：`reasoning` → `reasoningPreset`。
+ *
+ * 只处理「旧字段存在」这一种情况：字段一旦落盘消失，用户后续主动删掉
+ * `reasoningPreset`（表示「这个模型我不想调档」）就不会被反复补回来。
+ */
+export declare function migrateModelReasoning(model: Model): {
+    model: Model;
+    changed: boolean;
+};
+/**
+ * 迁移整个配置。只处理对话模型（`models`）——
+ * 图片模型（`imageModels`）既没有上下文阈值、也没有思考概念。
+ *
+ * 同时清除已废弃的 `defaultModel`：模型的真相源已改为 `AgentDefinition.modelId`，
+ * 配置级默认值连同字段一起消失（旧值先由 `ConfigManager.bootstrap()` 搬到默认 Agent 上）。
+ */
+export declare function migrateConfig(config: AppConfig): {
+    config: AppConfig;
+    changed: boolean;
+};

package/dist/config/migrate.js

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

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

@@ -0,0 +1,37 @@
+/**
+ * 思考预设 —— 出厂内容 + 策略表文件名
+ *
+ * 这里的内容只是**初始值**：`ConfigManager.ensureReasoningPresets()` 在首次运行时把它
+ * 写到 `<basePath>/reasoning-presets.json`，之后以磁盘文件为准（用户可改、可加）。
+ * 与 `DEFAULT_APP_CONFIG` 写进 `config.json` 完全同一个套路。
+ *
+ * ## 为什么这份数据在 SDK
+ *
+ * 它是**跨客户端共享的资产**：CLI 用它决定 `/think` 能选哪几档，桌面端同理；两端不该
+ * 各维护一份「智谱 5.3 只认 low/high/max」的知识。所以**定义、出厂内容、读写**都在 SDK。
+ *
+ * ## 但 SDK 不拿它生成请求参数
+ *
+ * 参数合并只有一条路：`{ ...model.defaultParams, ...agent.modelParams }`（见 `createModel`）。
+ * 客户端读表 → 限制可选强度 → 把选中档位的补丁**写进** `AgentDefinition.modelParams`，
+ * 于是配置本身就是事实，运行期不再查表。
+ *
+ * ## 为什么每张表长这样（**全部来自官方文档，不要凭印象改**）
+ *
+ * | 端点 | 官方依据 | 若写错会怎样 |
+ * |------|---------|-------------|
+ * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort`（`none/minimal/low/medium/high/xhigh/max`） | 无 `thinking` 参数，写了会被当未知参数拒绝 → 表里干脆不出现该键 |
+ * | DeepSeek | `api-docs.deepseek.com/guides/thinking_mode` | 可调 `low/high/max`；关闭用 `thinking.type = "disabled"` |
+ * | 智谱 GLM-5.3 系 | `docs.bigmodel.cn/cn/guide/capabilities/thinking` | **只认** `low/high/max`，其余输入报错；**不再支持关闭**（传 disabled 也报错）→ 表里没有 `off` |
+ * | 智谱 GLM-4.7 | 同上 | 强制思考且无 `reasoning_effort` 参数 → 不给它挂策略 |
+ *
+ * 三个结构性保证，都是「表的形状」带来的，不需要任何代码分支：
+ *   1. 可选档位 = `Object.keys(levels)`，不会有「菜单里有、发出去报错」的档位；
+ *   2. 能否关闭思考 = 表里有没有 `off` 键；
+ *   3. 某个键属于思考参数 = 它在表里出现过 —— 写入时按此剔除旧值，不需要硬编码键名。
+ */
+import type { ReasoningPresets } from "../types/index.js";
+/** 策略表文件名（位于 `<basePath>/` 下，与 `config.json` 同级） */
+export declare const REASONING_PRESETS_FILE = "reasoning-presets.json";
+/** 出厂策略表 */
+export declare const FACTORY_REASONING_PRESETS: ReasoningPresets;

package/dist/config/reasoning-presets.js

@@ -0,0 +1,64 @@
+/**
+ * 思考预设 —— 出厂内容 + 策略表文件名
+ *
+ * 这里的内容只是**初始值**：`ConfigManager.ensureReasoningPresets()` 在首次运行时把它
+ * 写到 `<basePath>/reasoning-presets.json`，之后以磁盘文件为准（用户可改、可加）。
+ * 与 `DEFAULT_APP_CONFIG` 写进 `config.json` 完全同一个套路。
+ *
+ * ## 为什么这份数据在 SDK
+ *
+ * 它是**跨客户端共享的资产**：CLI 用它决定 `/think` 能选哪几档，桌面端同理；两端不该
+ * 各维护一份「智谱 5.3 只认 low/high/max」的知识。所以**定义、出厂内容、读写**都在 SDK。
+ *
+ * ## 但 SDK 不拿它生成请求参数
+ *
+ * 参数合并只有一条路：`{ ...model.defaultParams, ...agent.modelParams }`（见 `createModel`）。
+ * 客户端读表 → 限制可选强度 → 把选中档位的补丁**写进** `AgentDefinition.modelParams`，
+ * 于是配置本身就是事实，运行期不再查表。
+ *
+ * ## 为什么每张表长这样（**全部来自官方文档，不要凭印象改**）
+ *
+ * | 端点 | 官方依据 | 若写错会怎样 |
+ * |------|---------|-------------|
+ * | OpenAI | `openai-node` 的 `Shared.ReasoningEffort`（`none/minimal/low/medium/high/xhigh/max`） | 无 `thinking` 参数，写了会被当未知参数拒绝 → 表里干脆不出现该键 |
+ * | DeepSeek | `api-docs.deepseek.com/guides/thinking_mode` | 可调 `low/high/max`；关闭用 `thinking.type = "disabled"` |
+ * | 智谱 GLM-5.3 系 | `docs.bigmodel.cn/cn/guide/capabilities/thinking` | **只认** `low/high/max`，其余输入报错；**不再支持关闭**（传 disabled 也报错）→ 表里没有 `off` |
+ * | 智谱 GLM-4.7 | 同上 | 强制思考且无 `reasoning_effort` 参数 → 不给它挂策略 |
+ *
+ * 三个结构性保证，都是「表的形状」带来的，不需要任何代码分支：
+ *   1. 可选档位 = `Object.keys(levels)`，不会有「菜单里有、发出去报错」的档位；
+ *   2. 能否关闭思考 = 表里有没有 `off` 键；
+ *   3. 某个键属于思考参数 = 它在表里出现过 —— 写入时按此剔除旧值，不需要硬编码键名。
+ */
+/** 策略表文件名（位于 `<basePath>/` 下，与 `config.json` 同级） */
+export const REASONING_PRESETS_FILE = "reasoning-presets.json";
+/** 出厂策略表 */
+export const FACTORY_REASONING_PRESETS = {
+    /** OpenAI 系：只认 `reasoning_effort`；关闭思考 = `"none"` */
+    openai: {
+        levels: {
+            minimal: { reasoning_effort: "minimal" },
+            low: { reasoning_effort: "low" },
+            medium: { reasoning_effort: "medium" },
+            high: { reasoning_effort: "high" },
+            off: { reasoning_effort: "none" },
+        },
+    },
+    /** 智谱 GLM-5.3 / 5.3-Flash / 5.3-FlashX：只认三档，且**不能关闭思考** */
+    "zhipu-5.3": {
+        levels: {
+            low: { thinking: { type: "enabled" }, reasoning_effort: "low" },
+            high: { thinking: { type: "enabled" }, reasoning_effort: "high" },
+            max: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+        },
+    },
+    /** DeepSeek：`thinking` 开关 + `reasoning_effort`，可关闭 */
+    deepseek: {
+        levels: {
+            low: { thinking: { type: "enabled" }, reasoning_effort: "low" },
+            high: { thinking: { type: "enabled" }, reasoning_effort: "high" },
+            max: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+            off: { thinking: { type: "disabled" } },
+        },
+    },
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { PermissionPolicy, AgentPermissions, Endpoint, Model, ImageModel, AgentDefinition, AppConfig, ToolEnv, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
+export type { PermissionPolicy, AgentPermissions, Endpoint, EndpointCapabilities, Model, TokenThresholds, ModelParams, ReasoningPatch, ReasoningPreset, ReasoningPresets, ImageModel, AgentDefinition, AppConfig, ToolEnv, McpIcon, McpAnnotations, McpToolDef, McpResourceDef, McpPromptDef, McpServerManifest, McpServerConfig, McpConnectionState, } from "./types/index.js";
 export { PermissionEvaluator } from "./scope/PermissionEvaluator.js";
 export type { CandidateSets } from "./scope/PermissionEvaluator.js";
 export { createDisclosureParam } from "./scope/disclosure.js";
@@ -20,26 +20,32 @@ export { SubAgentsScopePlugin } from "./scope/plugins/subagents/SubAgentsScopePl
 export { allInOne } from "./scope/plugins/allInOne.js";
 export type { AllInOneOptions } from "./scope/plugins/allInOne.js";
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
+export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
+export { FACTORY_REASONING_PRESETS, REASONING_PRESETS_FILE, } from "./config/reasoning-presets.js";
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
+export { fileToContentSection, resolveModelAndEndpoint, supportsFilesApi, mimeOf, toDataUrl, base64ByteLength, contentHash, clearUploadCache, MIME_BY_EXT, DEFAULT_MAX_INLINE_BYTES, } from "./shared/content-blocks.js";
+export type { FileSource, FileToSectionInput, FileToSectionResult, ContentTransport, UploadFn, } from "./shared/content-blocks.js";
 export { createModel } from "./runtime/createModel.js";
 export { SdkAgent } from "./runtime/SdkAgent.js";
 export type { AgentPlugin, SendContext } from "./runtime/SdkAgent.js";
 export { createAgent } from "./runtime/createAgent.js";
+export type { CreateAgentOptions } from "./runtime/createAgent.js";
 export { McpConnectionManager } from "./scope/plugins/mcp/McpConnectionManager.js";
 export type { McpConnectOptions } from "./scope/plugins/mcp/McpConnectionManager.js";
 export { SdkCallbackTool } from "./scope/plugins/builtin/SdkCallbackTool.js";
 export type { SdkCallbackToolOptions } from "./scope/plugins/builtin/SdkCallbackTool.js";
-export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
-export type { MigrationContext, MigrationStrategy, TaskMigrationServiceOptions, } from "./runtime/TaskMigrationService.js";
+export { HandoffAbortedError, HandoffService } from "./runtime/HandoffService.js";
+export type { HandoffContext, HandoffMode, HandoffParams, HandoffServiceOptions, MigrateParams, MigrationStrategy, } from "./runtime/HandoffService.js";
+export { HandoffGuardPlugin } from "./runtime/HandoffGuardPlugin.js";
 export { AutoMigratePlugin } from "./agent-plugins/AutoMigratePlugin.js";
-export type { AutoMigrateOptions } from "./agent-plugins/AutoMigratePlugin.js";
+export type { AutoMigrateOptions, AutoMigrateTriggerInfo, AutoMigrateModeResolver, } from "./agent-plugins/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./agent-plugins/AutoRefreshToolsPlugin.js";
 export { ContextGuardPlugin } from "./agent-plugins/ContextGuardPlugin.js";
 export type { ContextGuardOptions } from "./agent-plugins/ContextGuardPlugin.js";
 export { UnknownToolHintPlugin } from "./agent-plugins/UnknownToolHintPlugin.js";
 export { BUILTIN_TOOL_CLASSES } from "./scope/plugins/builtin/index.js";
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./scope/plugins/builtin/index.js";
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, } from "./scope/plugins/builtin/index.js";
 export { GenerateImageTool } from "./scope/plugins/builtin/GenerateImageTool.js";
 export { ViewImageTool } from "./scope/plugins/builtin/ViewImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./scope/plugins/skills/skillTools.js";