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

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/scope/plugins/mcp/McpScopePlugin.d.ts

@@ -24,6 +24,6 @@ export declare class McpScopePlugin implements ScopePlugin {
     /** 是否配置了 MCP（供外部代码判定，如 UnknownToolHintPlugin） */
     hasConfig(): boolean;
     candidates(): ScopeCandidates;
-    instantiate(_scope: Scope, filtered: FilterOutput): Tool[];
+    instantiate(scope: Scope, filtered: FilterOutput): Tool[];
     dispose(): Promise<void>;
 }

package/dist/scope/plugins/mcp/McpScopePlugin.js

@@ -37,7 +37,7 @@ export class McpScopePlugin {
             tools: ["load_mcp", "call_mcp_tool", "read_mcp_resource"],
         };
     }
-    instantiate(_scope, filtered) {
+    instantiate(scope, filtered) {
         const allow = new Set(filtered.tools);
         const allowedMcps = new Set(filtered.mcps);
         const filteredMcps = this.servers.filter((s) => allowedMcps.has(s.id));
@@ -47,7 +47,8 @@ export class McpScopePlugin {
             result.push(createLoadMcpTool(m, filteredMcps));
         }
         if (allow.has("call_mcp_tool") && m) {
-            result.push(createCallMcpTool(m));
+            // env 供 call_mcp_tool 读取 maxToolOutput，与内置工具共用同一上限口径
+            result.push(createCallMcpTool(m, scope.env));
         }
         if (allow.has("read_mcp_resource") && m) {
             result.push(createReadMcpResourceTool(m));

package/dist/scope/plugins/mcp/mcpTools.d.ts

@@ -1,6 +1,6 @@
 import { CallbackTool } from "@ai-zen/agents-core";
 import type { McpConnectionManager } from "./McpConnectionManager.js";
-import type { McpServerConfig } from "../../../types/index.js";
+import type { McpServerConfig, ToolEnv } from "../../../types/index.js";
 /**
  * 创建 load_mcp 工具。
  * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导，
@@ -10,8 +10,14 @@ export declare function createLoadMcpTool(mcpManager: McpConnectionManager, filt
 /**
  * 创建 call_mcp_tool 工具。
  * 通过官方 Client.callTool() API 调用 MCP 服务器上的工具。
+ *
+ * 返回形态：
+ *   - 仅文本 → 纯字符串（与历史行为一致）；
+ *   - 含媒体 → 内容块数组：首块为受保护的文本，其后原样透传 image / file 块。
+ *
+ * env 仅用于读取 maxToolOutput（文本输出保护上限），与内置工具口径一致。
  */
-export declare function createCallMcpTool(mcpManager: McpConnectionManager): CallbackTool;
+export declare function createCallMcpTool(mcpManager: McpConnectionManager, env: ToolEnv): CallbackTool;
 /**
  * 创建 read_mcp_resource 工具。
  */

package/dist/scope/plugins/mcp/mcpTools.js

@@ -1,5 +1,6 @@
 import { CallbackTool } from "@ai-zen/agents-core";
 import { createDisclosureParam } from "../../disclosure.js";
+import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput, headTailPreview } from "../builtin/outputGuard.js";
 import { getLogger } from "../../../shared/logger.js";
 const EMPTY_HINT = "（当前没有可用的 MCP 服务器，请联系用户添加）";
 const log = getLogger();
@@ -81,15 +82,130 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
         },
     });
 }
+/** base64 二进制转 data URL（image_url / file_data 均接受） */
+function toDataUrl(base64, mimeType) {
+    return `data:${mimeType};base64,${base64}`;
+}
+/**
+ * MCP content 块 → SDK 内容块。
+ *
+ * 文本类（text / resource.text / resource_link / 未知类型）归一为 `text` 块，
+ * 由调用方拼接成正文后进入输出保护；
+ * 媒体类（image / audio / resource.blob）归一为 `image_url` / `file` 块，
+ * 原样透传给模型——图片不进字符闸门，也不丢弃。
+ */
+function toMessageSection(block) {
+    switch (block?.type) {
+        case "image":
+            return {
+                type: "image_url",
+                image_url: { url: toDataUrl(block.data, block.mimeType ?? "image/png") },
+            };
+        case "audio":
+            // AgentNS 无独立音频块，以 Files API 的 file_data（base64 data URL）内联承载
+            return {
+                type: "file",
+                file_data: toDataUrl(block.data, block.mimeType ?? "audio/wav"),
+            };
+        case "resource": {
+            const r = block.resource ?? {};
+            // 内嵌文本资源：本质是纯文本，并入正文（同样受输出保护）
+            if (typeof r.text === "string")
+                return { type: "text", text: r.text };
+            // 内嵌二进制资源：按 mimeType 选块类型，不丢弃
+            if (typeof r.blob === "string") {
+                const mime = r.mimeType ?? "application/octet-stream";
+                return mime.startsWith("image/")
+                    ? { type: "image_url", image_url: { url: toDataUrl(r.blob, mime) } }
+                    : { type: "file", file_data: toDataUrl(r.blob, mime) };
+            }
+            return { type: "text", text: `[资源] ${r.uri ?? "(未知 URI)"}` };
+        }
+        case "resource_link": {
+            const parts = [block.name, block.uri, block.mimeType].filter(Boolean);
+            return { type: "text", text: `[资源链接] ${parts.join(" · ")}` };
+        }
+        case "text":
+            return { type: "text", text: block.text ?? "" };
+        default:
+            // 未知类型（如 tool_use）退化为 JSON 文本，仍受输出保护
+            return { type: "text", text: JSON.stringify(block) };
+    }
+}
+/**
+ * 文本输出保护（保序）：
+ *
+ * - **未超限**：原样返回映射后的块数组，不重排、不合并、不丢块；
+ *   纯文本时退化为单个字符串（历史行为）。
+ * - **超限**：全部文本落盘为 result.txt，只保留**一个**警告文本块占据
+ *   原首个文本块的位置，其余文本块丢弃（内容已落盘），媒体块原位不动。
+ *   这样即使文本夹在中间，媒体与位置的对应关系也不会被打乱。
+ *
+ * 判定用全部文本的字符总数——不能逐块判，否则 N 段各 3 万字符都不超限、合起来却能灌爆。
+ * 落盘只写文本正文，不写原始结果——后者可能含 image 的 base64，
+ * 落盘等于把几 MB 二进制再抄一遍磁盘。
+ */
+async function protectCallOutput(output, env) {
+    const limit = env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
+    const { sections, fullText, chars, isError } = output;
+    const guarded = await guardOutput({
+        tool: "call_mcp_tool",
+        content: output,
+        isOverLimit: (o) => o.chars > limit,
+        dump: (_dir, o) => [{ name: "result.txt", content: o.fullText }],
+        buildWarning: (ctx) => {
+            const preview = headTailPreview(fullText);
+            return JSON.stringify({
+                outputTooLarge: true,
+                isError: isError || undefined,
+                warning: `文本输出过大：共 ${chars} 字符，超过上限 ${limit} 字符。` +
+                    `完整文本已落盘（result.txt），可用 read 分批读取。`,
+                files: ctx.files,
+                chars,
+                ...preview,
+            });
+        },
+    });
+    // 超限：警告占据首个文本块的位置，其余文本块合并到它身上（内容已落盘），媒体原位
+    if (typeof guarded === "string") {
+        const collapsed = [];
+        let placed = false;
+        for (const section of sections) {
+            if (section.type === "text") {
+                if (!placed) {
+                    collapsed.push({ type: "text", text: guarded });
+                    placed = true;
+                }
+                continue;
+            }
+            collapsed.push(section);
+        }
+        // 仅一个文本块（无媒体）：退化为字符串，与历史行为一致
+        return collapsed.length === 1 ? collapsed[0].text : collapsed;
+    }
+    // 未超限：无媒体 → 纯字符串；有媒体 → 原序块数组
+    const hasMedia = sections.some((s) => s.type !== "text");
+    if (!hasMedia)
+        return isError ? `❌ 工具执行出错:\n${fullText}` : fullText;
+    return isError
+        ? [{ type: "text", text: "❌ 工具执行出错:" }, ...sections]
+        : sections;
+}
 /**
  * 创建 call_mcp_tool 工具。
  * 通过官方 Client.callTool() API 调用 MCP 服务器上的工具。
+ *
+ * 返回形态：
+ *   - 仅文本 → 纯字符串（与历史行为一致）；
+ *   - 含媒体 → 内容块数组：首块为受保护的文本，其后原样透传 image / file 块。
+ *
+ * env 仅用于读取 maxToolOutput（文本输出保护上限），与内置工具口径一致。
  */
-export function createCallMcpTool(mcpManager) {
+export function createCallMcpTool(mcpManager, env) {
     return new CallbackTool({
         function: {
             name: "call_mcp_tool",
-            description: "调用已连接 MCP 服务器上的指定工具。需先通过 load_mcp 连接服务器。",
+            description: "调用已连接 MCP 服务器上的指定工具。需先通过 load_mcp 连接服务器。文本输出过大时会落盘并只返回头尾预览；图片、音频等媒体原样返回。",
             parameters: {
                 type: "object",
                 properties: {
@@ -117,15 +233,19 @@ export function createCallMcpTool(mcpManager) {
                     name: input.tool,
                     arguments: input.arguments,
                 }, undefined, { signal: ctx?.signal });
+                // 按 MCP content 原始顺序映射，文本与媒体的相对位置完整保留
                 const contents = result.content ?? [];
-                const textParts = contents
-                    .filter((c) => c.type === "text")
-                    .map((c) => c.text);
-                const text = textParts.join("\n");
-                if (result.isError) {
-                    return `❌ 工具执行出错:\n${text || JSON.stringify(result)}`;
+                const isError = Boolean(result.isError);
+                // 没有 content 时退回原始 JSON（既有兜底）
+                if (contents.length === 0) {
+                    const json = JSON.stringify(result);
+                    return await protectCallOutput({ sections: [{ type: "text", text: json }], fullText: json, chars: json.length, isError }, env);
                 }
-                return text || JSON.stringify(result);
+                const sections = contents.map(toMessageSection);
+                const textSections = sections.filter((s) => s.type === "text");
+                const fullText = textSections.map((s) => s.text).join("\n");
+                const chars = textSections.reduce((n, s) => n + s.text.length, 0);
+                return await protectCallOutput({ sections, fullText, chars, isError }, env);
             }
             catch (error) {
                 return `❌ 调用 "${input.tool}" 失败: ${error?.message ?? error}`;

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.11",
   "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>;
-}