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

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

@@ -3,7 +3,7 @@ import { SdkCallbackTool } from "./SdkCallbackTool.js";
 /**
  * 根据文字描述生成图片。**统一返回字符串**（JSON，含图片 URL 列表）：
  * 生成结果如何处理（查看/下载/转发）由模型与上层自由决定——
- * 需要让模型看图时，模型可主动调用 viewImage(URL)；需要保存时用 downloadFile。
+ * 需要让模型看图时，模型可主动调用 view_image(URL)；需要保存时用 download_file。
  *
  * 依赖 AppConfig 中的 imageModels 和 defaultImageModel 配置（isAvailable 声明），
  * 未配置时由 buildTools 过滤，不暴露给 Agent。
@@ -14,8 +14,8 @@ export class GenerateImageTool extends SdkCallbackTool {
         return !!config.defaultImageModel;
     }
     function = {
-        name: "generateImage",
-        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 viewImage 工具（传入图片 URL）；如需保存到本地，用 downloadFile 下载。",
+        name: "generate_image",
+        description: "根据文字描述生成图片，返回图片 URL 列表（JSON）。如需查看图片内容，请用 view_image 工具（传入图片 URL）；如需保存到本地，用 download_file 下载。",
         parameters: {
             type: "object",
             properties: {
@@ -25,7 +25,7 @@ export class GenerateImageTool extends SdkCallbackTool {
                 },
                 model: {
                     type: "string",
-                    description: "图片模型 ID，不指定则使用配置中的默认图片模型。配置中的图片模型可通过 'aiz config show' 查看。",
+                    description: "图片模型 ID，不指定则使用配置中的默认图片模型；若指定的模型不存在，本工具会返回当前可用的模型列表。",
                 },
                 size: {
                     type: "string",
@@ -99,15 +99,15 @@ export class GenerateImageTool extends SdkCallbackTool {
                 .map((img) => img.url)
                 .filter((url) => !!url);
             // 统一返回字符串（JSON）：生成结果如何处理（查看/下载/转发）由模型与上层自由决定，
-            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 viewImage(URL)；
-            // 需要保存 → downloadFile 下载。
+            // 不替模型做「看或不看」的假设。需要让模型看图 → 模型可主动调用 view_image(URL)；
+            // 需要保存 → download_file 下载。
             return JSON.stringify({
                 success: true,
                 model: imageModel.name,
                 modelId: imageModel.id,
                 created: result.created,
                 images: urls.map((url, i) => ({ index: i, url })),
-                note: "图片临时链接有效期为30天。如需查看图片内容，可用 viewImage 工具（传入图片 URL）；如需保存，可用 downloadFile 下载。",
+                note: "图片临时链接有效期为30天。如需查看图片内容，可用 view_image 工具（传入图片 URL）；如需保存，可用 download_file 下载。",
             }, null, 2);
         }
         catch (error) {

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

@@ -69,7 +69,7 @@ export class GlobTool extends SdkCallbackTool {
                 return JSON.stringify({
                     outputTooLarge: true,
                     warning: `输出过大：匹配结果共 ${json.length} 字符，超过上限 ${limit} 字符。` +
-                        `完整结果已落盘（result.json），可用 readFile 分批读取；` +
+                        `完整结果已落盘（result.json），可用 read 分批读取；` +
                         `也可用更精确的 pattern 或 exclude 缩小范围后重新查找。`,
                     files: ctx.files,
                     chars: json.length,

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

@@ -4,8 +4,8 @@ import type { AgentNS } from "@ai-zen/agents-core";
 /**
  * 勘察文件结构概况（行数、每行列数等），不做内容读取。
  *
- * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
- * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ * 定位与 read 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 read 的读取范围。流式扫描，故不受 read 的 300KB 读取阈值限制。
  */
 export declare class InspectFileTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;

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

@@ -6,13 +6,13 @@ import { DEFAULT_MAX_TOOL_OUTPUT } from "./outputGuard.js";
 /**
  * 勘察文件结构概况（行数、每行列数等），不做内容读取。
  *
- * 定位与 readFile 的 range 配套：大文件先看结构（有多少行、每行多长），
- * 再决定 readFile 的读取范围。流式扫描，故不受 readFile 的 300KB 读取阈值限制。
+ * 定位与 read 的 range 配套：大文件先看结构（有多少行、每行多长），
+ * 再决定 read 的读取范围。流式扫描，故不受 read 的 300KB 读取阈值限制。
  */
 export class InspectFileTool extends SdkCallbackTool {
     function = {
-        name: "inspectFile",
-        description: "勘察文件的结构概况：总行数、总字符数、最长行的列数及其行索引、平均列数、行尾类型（LF/CRLF）。可选返回每行的列数映射。适用于在 readFile 之前先了解文件规模，再决定用 range 读取哪一段。仅做流式扫描，不受 readFile 的 300KB 读取阈值限制。",
+        name: "inspect_file",
+        description: "勘察文件的结构概况：总行数、总字符数、最长行的列数及其行索引、平均列数、行尾类型（LF/CRLF）。可选返回每行的列数映射。适用于在 read 之前先了解文件规模，再决定用 range 读取哪一段。仅做流式扫描，不受 read 的 300KB 读取阈值限制。",
         parameters: {
             type: "object",
             properties: {
@@ -63,7 +63,7 @@ export class InspectFileTool extends SdkCallbackTool {
                     colCountMapOmitted: true,
                     warning: `行长度明细过大：概况与 colCountMap 合计 ${payload.length} 字符，` +
                         `超过上限 ${limit} 字符，未落盘返回。文件规模超出可处理范围，` +
-                        `建议改用 findText 定位后再按 range 分段读取。`,
+                        `建议改用 find_text 定位后再按 range 分段读取。`,
                 });
             }
             return payload;

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

@@ -36,7 +36,7 @@ export class LsTool extends SdkCallbackTool {
                     return JSON.stringify({
                         outputTooLarge: true,
                         warning: `输出过大：目录条目共 ${entries.length} 项、${json.length} 字符，超过上限 ${limit} 字符。` +
-                            `完整列表已落盘（result.json），可用 readFile 分批读取；` +
+                            `完整列表已落盘（result.json），可用 read 分批读取；` +
                             `也可改用 glob 按模式筛选。`,
                         files: ctx.files,
                         chars: json.length,

package/dist/scope/plugins/builtin/{ReadFileTool.d.ts → ReadTool.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 ReadFileTool extends SdkCallbackTool {
+export declare class ReadTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{ReadFileTool.js → ReadTool.js}

@@ -1,9 +1,9 @@
 import * as fsp from "fs/promises";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
 import { DEFAULT_MAX_TOOL_OUTPUT, guardOutput } from "./outputGuard.js";
-export class ReadFileTool extends SdkCallbackTool {
+export class ReadTool extends SdkCallbackTool {
     function = {
-        name: "readFile",
+        name: "read",
         description: "读取文件",
         parameters: {
             type: "object",
@@ -41,7 +41,7 @@ export class ReadFileTool extends SdkCallbackTool {
             // 输出保护：本次返回内容超过上限时只警告、不落盘，并提示用 range 分批读取
             const limit = this.env.config.maxToolOutput ?? DEFAULT_MAX_TOOL_OUTPUT;
             return await guardOutput({
-                tool: "readFile",
+                tool: "read",
                 content: output,
                 isOverLimit: (text) => text.length > limit,
                 buildWarning: () => `读取内容过大：本次输出 ${output.length} 字符，超过上限 ${limit} 字符，未落盘。` +

package/dist/scope/plugins/builtin/{ExecAsyncTool.d.ts → SpawnTool.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 ExecAsyncTool extends SdkCallbackTool {
+export declare class SpawnTool extends SdkCallbackTool {
     function: AgentNS.FunctionDefine;
     constructor(env: ToolEnv);
     call(input: {

package/dist/scope/plugins/builtin/{ExecAsyncTool.js → SpawnTool.js}

@@ -1,8 +1,8 @@
 import { spawn } from "child_process";
 import { SdkCallbackTool } from "./SdkCallbackTool.js";
-export class ExecAsyncTool extends SdkCallbackTool {
+export class SpawnTool extends SdkCallbackTool {
     function = {
-        name: "exec_async",
+        name: "spawn",
         description: "异步执行命令，启动程序后立即返回，不等待执行结果。适用于启动长期运行的进程（如服务器、监听程序、GUI应用等）或不需要等待结果的命令。注意：该工具本身不捕获命令的输出；若需获取/留存输出，可在命令中使用 shell 重定向写入文件（如 `> /path/file`，支持 `>>` 追加、`|` 管道）。命令经 shell 解析执行。",
         parameters: {
             type: "object",

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

@@ -33,7 +33,7 @@ export class ViewImageTool extends SdkCallbackTool {
         return model?.vision === true;
     }
     function = {
-        name: "viewImage",
+        name: "view_image",
         description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片会自动上传（Files API）后引用，网络图片直接引用。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。适合识别图片文字、描述图片内容、分析图表等。",
         parameters: {
             type: "object",
@@ -54,7 +54,7 @@ export class ViewImageTool extends SdkCallbackTool {
         const signal = ctx?.signal;
         const target = input?.path_or_url;
         if (!target || !target.trim()) {
-            return "viewImage 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
+            return "view_image 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
         }
         const value = target.trim();
         // 拒绝服务商无法访问的"本地 URL"：file:// 等本地协议，或指向本机回环地址（localhost/127.0.0.1/[::1]/0.0.0.0）的 http(s) 地址

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

@@ -26,13 +26,27 @@ export interface Model {
     name: string;
     endpointId: string;
     modelName?: string;
+    /**
+     * 任务迁移（交接）触发阈值 —— **不是**模型的真实上下文窗口。
+     *
+     * AutoMigratePlugin 不估算、不学习：只在 API 响应返回后，用 `usage.prompt_tokens`
+     * 与该值比较，超过即触发交接迁移。建议取模型真实窗口的约 25%，为 response 留出空间。
+     */
     maxContextTokens: number;
+    /** 旧版字符数阈值（兼容迁移） */
     maxContextChars?: number;
     defaultParams?: Record<string, unknown>;
-    /** 是否支持图片输入（视觉模型）。看图工具（viewImage）仅对视觉模型启用；generateImage 是否返回图片内容块也据此判断 */
+    /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
     version?: number;
+    /**
+     * 是否用户自定义。
+     *
+     * 为 true 时 SDK 初始化不会用出厂定义替换该模型；缺省（或 false）视为出厂托管，
+     * 初始化时会与 DEFAULT_APP_CONFIG.models 同步（出厂清单为准）。
+     */
+    custom?: boolean;
 }
 /** Agent 定义，有 function 字段时为 SubAgent */
 export interface AgentDefinition {
@@ -64,6 +78,13 @@ export interface ImageModel {
     defaultSize?: string;
     defaultQuality?: string;
     version?: number;
+    /**
+     * 是否用户自定义。
+     *
+     * 为 true 时 SDK 初始化不会用出厂定义替换该模型；缺省（或 false）视为出厂托管，
+     * 初始化时会与 DEFAULT_APP_CONFIG.imageModels 同步（出厂清单为准）。
+     */
+    custom?: boolean;
 }
 /** config.json 结构 */
 export interface AppConfig {
@@ -83,7 +104,7 @@ export interface AppConfig {
      *
      * 工具本次输出超过该值时，由工具自身的保护策略处置（落盘或仅警告），
      * 避免超长输出撑爆上下文。仅作用于"输出"，与工具的读取阈值无关
-     * （如 readFile/findText 对 300KB 文件的读取上限）。
+     * （如 read/find_text 对 300KB 文件的读取上限）。
      */
     maxToolOutput?: number;
 }
@@ -91,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.0",
+  "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>;
-}