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

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

@@ -12,6 +12,58 @@ export interface AgentPermissions {
     mcps?: PermissionPolicy;
     subagents?: PermissionPolicy;
 }
+/**
+ * 端点能力声明 —— 决定「本地文件 → 内容块」时走哪条传输路径。
+ *
+ * 之前这段判断硬编码在 ViewImageTool 里（`endpoint.id === "deepseek"`），
+ * 用户改一下端点 id 就失效；改为显式能力位后，新端点只要声明能力即可享受上传。
+ */
+export interface EndpointCapabilities {
+    /**
+     * 是否支持 OpenAI 兼容的 Files API（`POST {baseUrl}/files`，`purpose=user_data`）。
+     * 为 true 时本地文件优先上传并以 `file` 块（file_id）发送；否则走 base64 内联。
+     */
+    filesApi?: boolean;
+}
+/**
+ * 模型请求参数（`defaultParams` / `modelParams` 的形状）。
+ *
+ * 含厂商特有字段（`thinking` / `reasoning_effort` 等），SDK **原样透传**、不解释。
+ */
+export type ModelParams = Record<string, unknown>;
+/**
+ * 单个档位的请求参数补丁。
+ *
+ * 各家协议差异全部关在补丁里，不硬编码任何键名：
+ *   OpenAI   → `{ reasoning_effort: "high" }`（没有 `thinking` 参数）
+ *   DeepSeek → `{ thinking: { type: "enabled" }, reasoning_effort: "high" }`
+ *   关闭     → `{ reasoning_effort: "none" }` 或 `{ thinking: { type: "disabled" } }`
+ */
+export type ReasoningPatch = ModelParams;
+/**
+ * 一个具名思考策略：档位名 → 参数补丁。
+ *
+ * `levels` 的键集合**就是**该策略的全部可选档位 —— 没有单独的「能否关闭思考」字段：
+ * 表里有 `off` 键就能关，没有就不能（如智谱 GLM-5.3 系，官方原文「其余输入将报错」）。
+ */
+export interface ReasoningPreset {
+    /** 用户改过 → SDK 初始化不再覆盖该策略（与 `Model.custom` 同构） */
+    custom?: boolean;
+    /** 档位名 → 参数补丁 */
+    levels: Record<string, ReasoningPatch>;
+}
+/**
+ * 思考策略表 —— `<basePath>/reasoning-presets.json` 的结构，出厂内容见
+ * `config/reasoning-presets.ts`。
+ *
+ * 这份表是 **CLI / 桌面端等客户端共享的资产**：它定义「有哪些档位、每档写什么参数」，
+ * 由 `Model.reasoningPreset` 引用。客户端据此限制可选强度、把选中的档位展开成参数
+ * 写进 `AgentDefinition.modelParams`。
+ *
+ * **SDK 自身不消费它生成请求参数**：参数合并只是 `{...defaultParams, ...modelParams}`
+ * 一次浅合并（见 `createModel`）。表在这里只负责「定义 + 出厂默认 + 读写」。
+ */
+export type ReasoningPresets = Record<string, ReasoningPreset>;
 /** API 端点 */
 export interface Endpoint {
     id: string;
@@ -19,6 +71,25 @@ export interface Endpoint {
     baseUrl: string;
     apiKey: string;
     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 {
@@ -27,16 +98,22 @@ 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>;
-    /** 是否支持图片输入（视觉模型）。看图工具（viewImage）仅对视觉模型启用；generateImage 是否返回图片内容块也据此判断 */
+    /**
+     * 思考策略名，引用 `reasoning-presets.json` 里的键。
+     *
+     * 它是**跨客户端共享的元数据**：CLI / 桌面端据此判断这个模型能选哪几档。
+     * SDK 不拿它去生成请求参数（那条路只有 `defaultParams` + `modelParams` 浅合并），
+     * 只保证该字段能随模型配置一起读写与出厂同步。
+     */
+    reasoningPreset?: string;
+    /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
     version?: number;
@@ -54,7 +131,24 @@ export interface AgentDefinition {
     name: string;
     description?: string;
     messages: AgentNS.Message[];
+    /**
+     * 绑定模型 id —— **运行期唯一真相源**。
+     *
+     * 缺省即「无模型可用」，`createAgent` 会直接报错；不存在配置层的 `defaultModel`
+     * 兜底，也不存在会话级的模型记录。要换模型就改这里（`/model` 写的就是它）。
+     */
     modelId?: string;
+    /**
+     * Agent 级模型参数覆盖，浅合并进模型的 `defaultParams`。
+     *
+     * SDK 只做 `{ ...model.defaultParams, ...modelParams }`，不解释任何键名、不做
+     * 档位推导、不知道厂商差异。於是「配置即事实」：应用（如 CLI）在**写入配置时**就把
+     * 档位展开成具体参数存在这里，运行时不再查表。
+     *
+     * 于是同一个模型可以给不同 Agent 配不同强度（编程 Agent `reasoning_effort: "max"`、
+     * 闲聊 Agent `{ thinking: { type: "disabled" } }`），而模型自身的 `defaultParams` 不动。
+     */
+    modelParams?: ModelParams;
     permissions?: AgentPermissions;
     function?: AgentNS.FunctionDefine;
     createdAt: string;
@@ -88,7 +182,6 @@ export interface ImageModel {
 }
 /** config.json 结构 */
 export interface AppConfig {
-    defaultModel?: string;
     endpoints: Endpoint[];
     models: Model[];
     /** 图片生成模型列表 */
@@ -104,7 +197,7 @@ export interface AppConfig {
      *
      * 工具本次输出超过该值时，由工具自身的保护策略处置（落盘或仅警告），
      * 避免超长输出撑爆上下文。仅作用于"输出"，与工具的读取阈值无关
-     * （如 readFile/findText 对 300KB 文件的读取上限）。
+     * （如 read/find_text 对 300KB 文件的读取上限）。
      */
     maxToolOutput?: number;
 }
@@ -112,7 +205,7 @@ export interface AppConfig {
  * 工具环境 — Scope 的能力插件在实例化内置工具时注入的环境信息。
  *
  * cwd 是相对路径解析的基准（每个 Scope 对应一个工作目录）；
- * config 供需要模型/端点配置的工具（如 generateImage）使用。
+ * config 供需要模型/端点配置的工具（如 generate_image）使用。
  */
 export interface ToolEnv {
     /** 当前工作目录 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.21",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,10 +16,10 @@
   "author": "LZQCN",
   "license": "MIT",
   "dependencies": {
+    "@ai-zen/agents-core": "^4.5.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
-    "openai": "^7.5.0",
-    "@ai-zen/agents-core": "^4.3.0"
+    "openai": "^7.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",

package/dist/runtime/TaskMigrationService.d.ts

@@ -1,128 +0,0 @@
-import { AgentNS } from "@ai-zen/agents-core";
-import type OpenAI from "openai";
-import { type Logger } from "../shared/logger.js";
-import type { SdkAgent } from "./SdkAgent.js";
-/**
- * 迁移上下文 — 贯穿「迁移前 → 生成交接文档 → 迁移后」的结构化数据。
- *
- * 供 `TaskMigrationService.migrate` 与钩子（`onBeforeMigrate` / `onMigrated`）使用。
- * 手动迁移与自动迁移共用同一上下文结构，保证上层（CLI）行为一致。
- */
-export interface MigrationContext {
-    /** 当前对话 Agent（引用不变，仅替换消息列表） */
-    agent: SdkAgent;
-    /** 生成交接文档所用模型名 */
-    model: string;
-    /** 当前 prompt token 用量（自动迁移时由 AutoMigratePlugin 提供；手动迁移可省略） */
-    promptTokens?: number;
-    /** 上下文阈值（自动迁移时由 AutoMigratePlugin 提供；手动迁移可省略） */
-    maxTokens?: number;
-    /** 序列化后的完整对话历史（迁移输入） */
-    historyText: string;
-    /** 迁移前消息总数 */
-    messageCountBefore: number;
-    /** 生成的交接文档（迁移完成后填充） */
-    handoffDoc?: string;
-}
-/**
- * 迁移后的历史处理策略。
- *
- * - `omit`（默认）：将历史消息标记 `omit: true`，仍保留在 `agent.messages` 可审计/回放，但不再发送给模型；
- * - `prune`：物理剔除历史，只保留 `definition.messages`（系统提示等模板）+ 追加的对话断点。
- */
-export type MigrationStrategy = "omit" | "prune";
-/**
- * 任务迁移服务构造参数。
- */
-export interface TaskMigrationServiceOptions {
-    /** 生成交接文档所用客户端（可选；未传则 migrate 时回退到 agent.client） */
-    client?: OpenAI;
-    /** 生成交接文档所用模型名（可选；未传则 migrate 时回退到 agent.model） */
-    model?: string;
-    /** 生成交接文档所用模型参数（可选；未传则 migrate 时回退到 agent.modelConfig） */
-    modelConfig?: Record<string, unknown>;
-    /** 迁移后历史处理策略，默认 `omit`（标记历史保留可审计）。可选 `prune`（物理剔除）。 */
-    strategy?: MigrationStrategy;
-    /** 迁移前钩子（服务持有）。迁移开始前触发，此时 agent.messages 仍为完整旧历史 */
-    onBeforeMigrate?: (ctx: MigrationContext) => void | Promise<void>;
-    /** 迁移后钩子（服务持有）。迁移完成后触发，交接文档已注入 agent.messages */
-    onMigrated?: (ctx: MigrationContext) => void | Promise<void>;
-    /** 可注入日志（可选，默认使用全局单例） */
-    logger?: Logger;
-}
-/**
- * 任务迁移服务。
- *
- * 一个服务实例对应一次迁移上下文。它**不持有**任何模型调用——生成交接文档时
- * 默认复用传入 `agent`（`SdkAgent`）自身的 `client` / `model` / `modelConfig`，
- * 因此无需 Scope、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
- * 如需用不同模型生成交接文档，可在构造时显式传入 `client` / `model` / `modelConfig`，
- * 未传则 migrate 时回退到 agent 自带的配置。
- *
- * 职责：
- *   1. 生成交接文档的提示词 / 注入格式（静态纯工具，供上层使用）
- *   2. 执行完整迁移（串行化 → 模型生成 → 按策略处理历史 + 追加对话断点），并暴露迁移前后钩子（实例方法）
- *
- * 设计上，`AutoMigratePlugin` 只负责「何时触发」（检测 token 超限），
- * 实际迁移逻辑统一收敛到本服务，从而让手动迁移与自动迁移复用同一条链路。
- */
-export declare class TaskMigrationService {
-    static readonly HANDOFF_SECTIONS: {
-        readonly breakpoint: "## 💬 对话断点";
-        readonly completed: "## ✅ 已完成的任务";
-        readonly pending: "## 📋 未完成的任务";
-        readonly memory: "## 🧠 重要记忆";
-        readonly files: "## 📁 文件索引";
-        readonly instructions: "## 🔔 接手指令";
-    };
-    private onBeforeMigrate?;
-    private onMigrated?;
-    private client?;
-    private model?;
-    private modelConfig?;
-    private strategy;
-    private logger;
-    constructor(options?: TaskMigrationServiceOptions);
-    static createPrompt(): string;
-    /**
-     * 生成迁移后追加的「对话断点」消息（role=user）：交接文档 + 接手指令。
-     * 该消息是 omit 迁移方案中新上下文的起点，模型看到的序列为
-     * `[definition.messages, 断点消息]`（历史消息已被标记 omit，不再发送）。
-     */
-    static createPostMessages(handoffDoc: string): AgentNS.Message[];
-    /**
-     * 序列化消息为 `[role]: content` 文本，供模型理解完整对话历史。
-     */
-    static serializeMessages(messages: AgentNS.Message[]): string;
-    /**
-     * 生成交接文档：使用指定的 client / model / modelConfig 带交接 prompt 生成结构化文档。
-     */
-    private generateHandoff;
-    /**
-     * 执行完整迁移：序列化历史 → 模型生成交接文档 → 按策略处理历史并追加对话断点 → 触发钩子。
-     *
-     * 策略（`strategy`，构造函数默认 / 本参数可覆盖）：
-     *   - `omit`（默认）：`agent.definition.messages`（模板）保留，其余既有历史标记 `omit: true`（仍存于
-     *     `agent.messages` 可审计/回放但不再发送给模型），末尾追加「对话断点」消息。因此 `formatHistory()`
-     *     发送给模型的是 `[definition.messages, 断点消息]` —— 历史被压缩但并不删除。
-     *   - `prune`：物理剔除历史，只保留 `definition.messages` + 断点消息（即原先的替换行为）。
-     *
-     * 设计约束：
-     *   - 不重建 Agent，保留所有引用与插件绑定（仅重建消息列表）
-     *   - 钩子（onBeforeMigrate / onMigrated）抛错会被捕获并记录，**不中断**迁移流程
-     *   - 生成失败 / 未取到交接文档时抛错，此时 `agent.messages` 保持原样（不会被部分修改）
-     *
-     * @param params.agent        当前对话 Agent
-     * @param params.promptTokens 当前 prompt token 用量（可选）
-     * @param params.maxTokens    上下文阈值（可选）
-     * @param params.strategy     本次迁移的历史处理策略（可选，覆盖构造时的默认值）
-     * @returns 完整的迁移上下文（含生成的交接文档）
-     */
-    migrate(params: {
-        agent: SdkAgent;
-        promptTokens?: number;
-        maxTokens?: number;
-        /** 本次迁移的历史处理策略（可选，覆盖构造时的默认值） */
-        strategy?: MigrationStrategy;
-    }): Promise<MigrationContext>;
-}

package/dist/runtime/TaskMigrationService.js

@@ -1,211 +0,0 @@
-import { Message } from "@ai-zen/agents-core";
-import { getLogger } from "../shared/logger.js";
-/**
- * 任务迁移服务。
- *
- * 一个服务实例对应一次迁移上下文。它**不持有**任何模型调用——生成交接文档时
- * 默认复用传入 `agent`（`SdkAgent`）自身的 `client` / `model` / `modelConfig`，
- * 因此无需 Scope、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
- * 如需用不同模型生成交接文档，可在构造时显式传入 `client` / `model` / `modelConfig`，
- * 未传则 migrate 时回退到 agent 自带的配置。
- *
- * 职责：
- *   1. 生成交接文档的提示词 / 注入格式（静态纯工具，供上层使用）
- *   2. 执行完整迁移（串行化 → 模型生成 → 按策略处理历史 + 追加对话断点），并暴露迁移前后钩子（实例方法）
- *
- * 设计上，`AutoMigratePlugin` 只负责「何时触发」（检测 token 超限），
- * 实际迁移逻辑统一收敛到本服务，从而让手动迁移与自动迁移复用同一条链路。
- */
-export class TaskMigrationService {
-    static HANDOFF_SECTIONS = {
-        breakpoint: "## 💬 对话断点",
-        completed: "## ✅ 已完成的任务",
-        pending: "## 📋 未完成的任务",
-        memory: "## 🧠 重要记忆",
-        files: "## 📁 文件索引",
-        instructions: "## 🔔 接手指令",
-    };
-    onBeforeMigrate;
-    onMigrated;
-    client;
-    model;
-    modelConfig;
-    strategy;
-    logger;
-    constructor(options = {}) {
-        const { onBeforeMigrate, onMigrated, logger, client, model, modelConfig, strategy } = options;
-        this.onBeforeMigrate = onBeforeMigrate;
-        this.onMigrated = onMigrated;
-        this.client = client;
-        this.model = model;
-        this.modelConfig = modelConfig;
-        this.strategy = strategy ?? "omit";
-        this.logger = logger ?? getLogger();
-    }
-    static createPrompt() {
-        return [
-            "根据以下对话历史，生成一篇结构化交接文档。不要做任何解释，只输出交接文档。",
-            "",
-            `文档必须包含以下章节：`,
-            `${TaskMigrationService.HANDOFF_SECTIONS.breakpoint}`,
-            `- 用户最后说了什么，AI 最后回复了什么`,
-            "",
-            `${TaskMigrationService.HANDOFF_SECTIONS.completed}`,
-            `- 列出已完成的每项任务及其关键产出`,
-            "",
-            `${TaskMigrationService.HANDOFF_SECTIONS.pending}`,
-            `- 按优先级列出未完成的任务、当前进度、下一步`,
-            "",
-            `${TaskMigrationService.HANDOFF_SECTIONS.memory}`,
-            `- 需要新 Agent 记住的关键信息（设计决策、偏好、约定等）`,
-            "",
-            `${TaskMigrationService.HANDOFF_SECTIONS.files}`,
-            `- 涉及的文件及其用途`,
-            "",
-            `${TaskMigrationService.HANDOFF_SECTIONS.instructions}`,
-            `- 接手后建议的操作步骤`,
-        ].join("\n");
-    }
-    /**
-     * 生成迁移后追加的「对话断点」消息（role=user）：交接文档 + 接手指令。
-     * 该消息是 omit 迁移方案中新上下文的起点，模型看到的序列为
-     * `[definition.messages, 断点消息]`（历史消息已被标记 omit，不再发送）。
-     */
-    static createPostMessages(handoffDoc) {
-        const content = [
-            "这是上一轮对话的任务交接文档。请先阅读交接文档，理解上下文后再继续协助用户完成任务。",
-            "",
-            "---",
-            "",
-            handoffDoc,
-            "",
-            "---",
-            "",
-            "请确认你已理解以上内容，然后询问用户接下来需要什么帮助。",
-        ].join("\n");
-        return [Message.User(content)];
-    }
-    /**
-     * 序列化消息为 `[role]: content` 文本，供模型理解完整对话历史。
-     */
-    static serializeMessages(messages) {
-        return messages
-            .map((m) => {
-            const role = m.role ?? "unknown";
-            const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
-            return `[${role}]: ${content}`;
-        })
-            .join("\n\n");
-    }
-    /**
-     * 生成交接文档：使用指定的 client / model / modelConfig 带交接 prompt 生成结构化文档。
-     */
-    async generateHandoff(client, model, modelConfig, historyText) {
-        const response = await client.chat.completions.create({
-            model,
-            ...(modelConfig ?? {}),
-            messages: [
-                { role: "system", content: TaskMigrationService.createPrompt() },
-                { role: "user", content: historyText },
-            ],
-        });
-        const handoffDoc = response.choices[0]?.message?.content;
-        if (!handoffDoc) {
-            throw new Error("未能生成任务交接文档");
-        }
-        return handoffDoc;
-    }
-    /**
-     * 执行完整迁移：序列化历史 → 模型生成交接文档 → 按策略处理历史并追加对话断点 → 触发钩子。
-     *
-     * 策略（`strategy`，构造函数默认 / 本参数可覆盖）：
-     *   - `omit`（默认）：`agent.definition.messages`（模板）保留，其余既有历史标记 `omit: true`（仍存于
-     *     `agent.messages` 可审计/回放但不再发送给模型），末尾追加「对话断点」消息。因此 `formatHistory()`
-     *     发送给模型的是 `[definition.messages, 断点消息]` —— 历史被压缩但并不删除。
-     *   - `prune`：物理剔除历史，只保留 `definition.messages` + 断点消息（即原先的替换行为）。
-     *
-     * 设计约束：
-     *   - 不重建 Agent，保留所有引用与插件绑定（仅重建消息列表）
-     *   - 钩子（onBeforeMigrate / onMigrated）抛错会被捕获并记录，**不中断**迁移流程
-     *   - 生成失败 / 未取到交接文档时抛错，此时 `agent.messages` 保持原样（不会被部分修改）
-     *
-     * @param params.agent        当前对话 Agent
-     * @param params.promptTokens 当前 prompt token 用量（可选）
-     * @param params.maxTokens    上下文阈值（可选）
-     * @param params.strategy     本次迁移的历史处理策略（可选，覆盖构造时的默认值）
-     * @returns 完整的迁移上下文（含生成的交接文档）
-     */
-    async migrate(params) {
-        const { agent, promptTokens, maxTokens, strategy: overrideStrategy } = params;
-        const strategy = overrideStrategy ?? this.strategy;
-        // 序列化有效上下文：过滤已标记 omit 的历史，避免重复迁移时把旧省略历史再次喂给模型。
-        // historyText 供模型生成交接文档，而 messageCountBefore 仍记录本次迁移前的消息总数。
-        const historyText = TaskMigrationService.serializeMessages(agent.messages.filter((m) => !m.omit));
-        const messageCountBefore = agent.messages.length;
-        // 生成交接文档所用模型调用：优先使用构造时传入的 client/model/modelConfig，
-        // 未传则回退到 agent 自带的（无需 Scope / 独立迁移 Agent）。
-        const client = this.client ?? agent.client;
-        const model = this.model ?? agent.model;
-        const modelConfig = this.modelConfig ?? agent.modelConfig;
-        // 迁移前上下文（不含 handoffDoc，独立对象，语义固定）
-        const beforeCtx = {
-            agent,
-            model,
-            maxTokens,
-            promptTokens,
-            historyText,
-            messageCountBefore,
-        };
-        // 迁移前钩子（容错，不中断）
-        if (this.onBeforeMigrate) {
-            try {
-                await this.onBeforeMigrate(beforeCtx);
-            }
-            catch (err) {
-                this.logger.error(`[migrate] onBeforeMigrate 回调失败: ${err?.message ?? err}`);
-            }
-        }
-        // 生成交接文档
-        const handoffDoc = await this.generateHandoff(client, model, modelConfig, historyText);
-        // 重建消息列表：按策略处理历史（omit 标记保留 / prune 物理剔除），并追加「对话断点」消息。
-        // 均用浅拷贝/新数组，避免直接修改 definition.messages 引用的对象（防止污染模板）。
-        const breakpointMessages = TaskMigrationService.createPostMessages(handoffDoc);
-        let nextMessages;
-        if (strategy === "prune") {
-            // 物理剔除：只保留模板消息 + 断点
-            nextMessages = [...agent.definition.messages, ...breakpointMessages];
-        }
-        else {
-            // omit（默认）：以 definition.messages 长度为界保留模板消息，其余历史统一标记 omit
-            const preserveCount = Math.min(agent.definition.messages.length, agent.messages.length);
-            nextMessages = [
-                ...agent.messages.map((m, i) => ({
-                    ...m,
-                    omit: i >= preserveCount ? true : m.omit,
-                })),
-                ...breakpointMessages,
-            ];
-        }
-        agent.messages = nextMessages;
-        // 迁移后上下文（含 handoffDoc，与迁移前上下文独立）
-        const afterCtx = {
-            agent,
-            model,
-            maxTokens,
-            promptTokens,
-            historyText,
-            messageCountBefore,
-            handoffDoc,
-        };
-        // 迁移后钩子（容错，不中断；此时交接文档已注入）
-        if (this.onMigrated) {
-            try {
-                await this.onMigrated(afterCtx);
-            }
-            catch (err) {
-                this.logger.error(`[migrate] onMigrated 回调失败: ${err?.message ?? err}`);
-            }
-        }
-        return afterCtx;
-    }
-}