@ai-zen/agents-sdk 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/scope/plugins/builtin/{WriteFileTool.d.ts → WriteTool.d.ts}

@@ -1,7 +1,7 @@
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import type { AgentNS } from "@ai-zen/agents-core";
-export declare class WriteFileTool extends SdkCallbackTool {
+export declare class WriteTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{WriteFileTool.js → WriteTool.js}

@@ -1,9 +1,9 @@
 import * as fsp from "fs/promises";
 import * as path from "path";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
-export class WriteFileTool extends SdkCallbackTool {
+export class WriteTool extends SdkCallbackTool {
     function = {
-        name: "writeFile",
+        name: "write",
         description: "写入文件",
         parameters: {
             type: "object",

package/dist/scope/plugins/builtin/index.d.ts

@@ -1,9 +1,9 @@
 import type { SdkCallbackTool } from "./SdkCallbackTool.js";
 import type { ToolEnv } from "../../../types/index.js";
 import { CwdTool } from "./CwdTool.js";
-import { ReadFileTool } from "./ReadFileTool.js";
+import { ReadTool } from "./ReadTool.js";
 import { InspectFileTool } from "./InspectFileTool.js";
-import { WriteFileTool } from "./WriteFileTool.js";
+import { WriteTool } from "./WriteTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
 import { RmTool } from "./RmTool.js";
@@ -16,7 +16,7 @@ import { RenameTool } from "./RenameTool.js";
 import { CopyTool } from "./CopyTool.js";
 import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
-import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SpawnTool } from "./SpawnTool.js";
 import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
@@ -29,4 +29,4 @@ import { GenerateImageTool } from "./GenerateImageTool.js";
  * 如 GenerateImageTool 依赖 defaultImageModel、ViewImageTool 仅视觉模型可用。
  */
 export declare const BUILTIN_TOOL_CLASSES: Array<new (env: ToolEnv) => SdkCallbackTool>;
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, ViewImageTool, GenerateImageTool, };

package/dist/scope/plugins/builtin/index.js

@@ -1,7 +1,7 @@
 import { CwdTool } from "./CwdTool.js";
-import { ReadFileTool } from "./ReadFileTool.js";
+import { ReadTool } from "./ReadTool.js";
 import { InspectFileTool } from "./InspectFileTool.js";
-import { WriteFileTool } from "./WriteFileTool.js";
+import { WriteTool } from "./WriteTool.js";
 import { ExecTool } from "./ExecTool.js";
 import { MkdirTool } from "./MkdirTool.js";
 import { RmTool } from "./RmTool.js";
@@ -14,7 +14,7 @@ import { RenameTool } from "./RenameTool.js";
 import { CopyTool } from "./CopyTool.js";
 import { BatchEditTool } from "./BatchEditTool.js";
 import { EditTool } from "./EditTool.js";
-import { ExecAsyncTool } from "./ExecAsyncTool.js";
+import { SpawnTool } from "./SpawnTool.js";
 import { SleepTool } from "./SleepTool.js";
 import { ViewImageTool } from "./ViewImageTool.js";
 import { GenerateImageTool } from "./GenerateImageTool.js";
@@ -28,9 +28,9 @@ import { GenerateImageTool } from "./GenerateImageTool.js";
  */
 export const BUILTIN_TOOL_CLASSES = [
     CwdTool,
-    ReadFileTool,
+    ReadTool,
     InspectFileTool,
-    WriteFileTool,
+    WriteTool,
     ExecTool,
     MkdirTool,
     RmTool,
@@ -43,9 +43,9 @@ export const BUILTIN_TOOL_CLASSES = [
     CopyTool,
     BatchEditTool,
     EditTool,
-    ExecAsyncTool,
+    SpawnTool,
     SleepTool,
     ViewImageTool,
     GenerateImageTool,
 ];
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, ViewImageTool, GenerateImageTool, };
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, ViewImageTool, GenerateImageTool, };

package/dist/scope/plugins/builtin/outputGuard.d.ts

@@ -28,7 +28,7 @@ export interface OutputGuardOptions<T> {
     /** 超限判定：上限由工具自行从 config 读取，骨架不传参 */
     isOverLimit: (content: T) => boolean;
     /**
-     * 落盘内容组织（可选）。缺省表示"只警告、不落盘"（如 readFile）。
+     * 落盘内容组织（可选）。缺省表示"只警告、不落盘"（如 read）。
      * 返回的文件按顺序写入本次调用专属的目录。
      */
     dump?: (dir: string, content: T) => GuardDumpFile[] | Promise<GuardDumpFile[]>;
@@ -61,7 +61,7 @@ export interface HeadPreview {
 /**
  * 生成头部预览：最多 size 字符。
  *
- * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 find_text）。
  */
 export declare function headPreview(text: string, size?: number): HeadPreview;
 /** 头尾预览 */

package/dist/scope/plugins/builtin/outputGuard.js

@@ -42,7 +42,7 @@ export async function guardOutput(options) {
 /**
  * 生成头部预览：最多 size 字符。
  *
- * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 findText）。
+ * 适用于结果按出现顺序排列、尾部参考价值低的工具（如 find_text）。
  */
 export function headPreview(text, size = 1000) {
     if (text.length <= size)

package/dist/types/index.d.ts

@@ -36,7 +36,7 @@ export interface Model {
     /** 旧版字符数阈值（兼容迁移） */
     maxContextChars?: number;
     defaultParams?: Record<string, unknown>;
-    /** 是否支持图片输入（视觉模型）。看图工具（viewImage）仅对视觉模型启用；generateImage 是否返回图片内容块也据此判断 */
+    /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
     version?: number;
@@ -104,7 +104,7 @@ export interface AppConfig {
      *
      * 工具本次输出超过该值时，由工具自身的保护策略处置（落盘或仅警告），
      * 避免超长输出撑爆上下文。仅作用于"输出"，与工具的读取阈值无关
-     * （如 readFile/findText 对 300KB 文件的读取上限）。
+     * （如 read/find_text 对 300KB 文件的读取上限）。
      */
     maxToolOutput?: number;
 }
@@ -112,7 +112,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.1",
+  "version": "1.0.0-alpha.10",
   "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.1",
     "@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;
-    }
-}