@ai-zen/agents-sdk 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [0.9.0] - 2026-08-28
+
+### 🎯 Optimized
+
+- **`TaskMigrationService.migrate` gains a `strategy` switch** — controls how history is handled after migration:
+  - **`omit` (default)**: history messages are marked `omit: true` (kept in `agent.messages` for audit/replay, but `Agent.formatHistory()` filters them out), and a "conversation breakpoint" message (handoff doc + handover instructions, role=user) is appended as the new context start. The sequence sent to the model becomes `[definition.messages, breakpoint message]`. Reuses Core's existing `omit` mechanism — no Core changes needed.
+  - **`prune`**: physically drops history, keeping only `definition.messages` + breakpoint message (the previous replace behavior).
+  - The default can be set via `strategy` when constructing `TaskMigrationService`, and overridden per `migrate()` call (`MigrationStrategy` type is exported).
+  - `agent.messages` is rebuilt via a **shallow copy** to avoid mutating objects referenced by `definition.messages` (prevents polluting the template).
+  - `historyText` (fed to the model to generate the handoff doc) now **filters omitted history**, so repeated migrations don't re-feed old omitted history to the model.
+  - `AutoMigratePlugin` still only decides *when* to trigger — no changes needed.
+
+### ✅ Tests
+
+- `TaskMigrationService` / `AutoMigratePlugin` assertions updated to the omit semantics (history marked omit + trailing breakpoint + system prompt preserved).
+- New case: `historyText` filters already-omitted history.
+- New case: `strategy=prune` (constructor default + `migrate` param override) physically drops history.
+
+## [0.8.0] - 2026-08-24
+
+### ⚠️ Breaking
+
+- **`TaskMigrationService` is now an instantiated, self-contained migration service** — it holds no model call of its own: `migrate()` reuses the passed `agent`'s own `client` / `model` / `modelConfig` to generate the handoff document, so it needs no `Provider` and no standalone "migration Agent" object (and no duplicated `config + modelId` model wiring). `migrate()` is an instance method that serializes history, calls the model to generate the handoff document, and replaces `agent.messages`.
+  - `TaskMigrationServiceOptions` = `{ client?, model?, modelConfig?, onBeforeMigrate?, onMigrated?, logger? }` — pass `client`/`model`/`modelConfig` to override the model call used for the handoff; when omitted, `migrate()` falls back to the passed `agent`'s own config
+  - `migrate({ agent, promptTokens?, maxTokens? })` — `agent` is the only runtime param (its `client`/`model`/`modelConfig` back the model call); the migration hooks are flat on the service instance (no `hooks` wrapper)
+- **`AutoMigratePlugin` narrowed to a trigger-only role** — constructor takes `{ service, maxTokens }`; it only detects token overflow in `onAfterSend` and delegates to `service.migrate({ agent, promptTokens, maxTokens })`. No hooks on the plugin.
+- **Removed** — `TaskMigrationService.createAgentDefinition` (the service calls the model directly, so a standalone migration Agent definition is unnecessary) and `BuildMigrationAgentOptions`; `MigrationContext` no longer carries `migrationAgent` (records `model` instead).
+- **New exports** — `MigrationContext`, `TaskMigrationServiceOptions`.
+
+### 🛠 Optimized
+
+- `serializeMessages` moved from `AutoMigratePlugin` private to `TaskMigrationService` public static.
+- The pure-tool statics (`createPrompt` / `createPostMessages` / `serializeMessages`) remain `static`; the instance `migrate()` reuses the passed `agent`'s model client. The "should migrate" check (`promptTokens > maxTokens`) lives in `AutoMigratePlugin` (the trigger side), not on the service.
+- Migration failure still leaves `agent.messages` unchanged (atomic); hook errors are caught and logged, never interrupting the migration flow.
+
+### ✅ Tests
+
+- `TaskMigrationService`: statics (`createPrompt` / `createPostMessages` / `serializeMessages`) + `migrate` (model call, hook contexts, failure atomicity) — all green.
+- `AutoMigratePlugin`: trigger-only behavior (overflow → `service.migrate`; below threshold / no usage → no model call).
+
 ## [0.7.1] - 2026-08-25
 
 ### 🚀 New Features

package/README.md

@@ -63,7 +63,8 @@ const provider = await Provider.create({
   ...paths,
 });
 const agent = createAgent(provider, "my-agent");
-agent.use(new AutoMigratePlugin({ maxTokens, migrationAgent, onMigrated }));
+const migrationService = new TaskMigrationService({ onMigrated }); // migrates via the agent's own model client
+agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
 await agent.init();
 await agent.send("Hello");
@@ -80,7 +81,7 @@ await agent.send("Hello");
 | `runtime` | ✅ Implemented — Provider, Capabilities, createAgent, MCP connection management, task migration |
 | `plugin` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ Implemented — SdkError + injectable Logger |
-| Tests | ✅ 445 passing, 51 files, all green (incl. real-API chat & viewImage e2e) |
+| Tests | ✅ 452 passing, 51 files, all green (incl. real-API chat & viewImage e2e) |
 
 ## Built-in Tools
 
@@ -117,7 +118,7 @@ Conditionally injected based on the active model / config:
 
 | Plugin | Description |
 |--------|-------------|
-| `AutoMigratePlugin` | Automatically triggers task migration when the context overflows, generates a handoff document, and transparently replaces the Agent |
+| `AutoMigratePlugin` | Automatically triggers task migration when the context overflows; delegates the actual migration to the injected `TaskMigrationService` instance (history handled per `strategy`: default `omit` keeps it auditable, optional `prune` drops it), which reuses the agent's own model client |
 | `AutoRefreshToolsPlugin` | Re-scans the file system before each `send()` to refresh the tool list |
 | `ContextGuardPlugin` | Context safety guard — before each request, throws `ContextOverflowError` (interrupting the conversation) when the previous round's `usage.prompt_tokens` exceeds `maxTokens × ratio` (default 1.5), preventing context runaway from reading oversized files |
 | `UnknownToolHintPlugin` | Smarter unknown-tool hints — when the LLM calls a nonexistent tool, guides it to `call_mcp_tool` / points out permission issues based on MCP config (opt-in via `agent.use`) |
@@ -133,3 +134,4 @@ See the project-root [`PRINCIPLES.md`](../../PRINCIPLES.md):
 5. Occam's razor
 6. Refactor as you go; keep clean layering
 7. Tests are the foundation
+he foundation

package/README.zh.md

@@ -62,7 +62,8 @@ const provider = await Provider.create({
   ...paths,
 });
 const agent = createAgent(provider, "my-agent");
-agent.use(new AutoMigratePlugin({ maxTokens, migrationAgent, onMigrated }));
+const migrationService = new TaskMigrationService({ onMigrated }); // 迁移复用传入 agent 自身的模型调用
+agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
 await agent.init();
 await agent.send("你好");
@@ -79,7 +80,7 @@ await agent.send("你好");
 | `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
 | `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
-| 测试 | ✅ 445 通过，51 个文件，全绿（含真实 API 聊天与 viewImage e2e） |
+| 测试 | ✅ 452 通过，51 个文件，全绿（含真实 API 聊天与 viewImage e2e） |
 
 ## 内置工具
 
@@ -116,7 +117,7 @@ await agent.send("你好");
 
 | 插件 | 说明 |
 |------|------|
-| `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档，透明替换 Agent |
+| `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档并追加对话断点（历史按 `strategy` 处理：默认 `omit` 标记保留可审计，可选 `prune` 物理剔除；委托注入的 `TaskMigrationService`，复用 Agent 自身的模型调用） |
 | `AutoRefreshToolsPlugin` | 每次 `send()` 前重新扫描文件系统，刷新工具列表 |
 | `ContextGuardPlugin` | 上下文安全护栏 — 每轮发请求前检测上一轮 `usage.prompt_tokens`，超过 `maxTokens × ratio`（默认 1.5，即 +50%）时抛 `ContextOverflowError` 中断对话，防止读入超大文件导致上下文失控 |
 | `UnknownToolHintPlugin` | 未知工具智能提示 — LLM 调用不存在的工具时，根据 MCP 配置引导使用 `call_mcp_tool` / 提示权限问题（调用方显式 `agent.use` 注册） |

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { McpConnectOptions } from "./runtime/McpConnectionManager.js";
 export { SdkCallbackTool } from "./runtime/SdkCallbackTool.js";
 export type { SdkCallbackToolOptions } from "./runtime/SdkCallbackTool.js";
 export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
-export type { BuildMigrationAgentOptions } from "./runtime/TaskMigrationService.js";
+export type { MigrationContext, MigrationStrategy, TaskMigrationServiceOptions, } from "./runtime/TaskMigrationService.js";
 export { AutoMigratePlugin } from "./plugin/AutoMigratePlugin.js";
 export type { AutoMigrateOptions } from "./plugin/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./plugin/AutoRefreshToolsPlugin.js";

package/dist/plugin/AutoMigratePlugin.d.ts

@@ -1,24 +1,21 @@
 import type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
-import { SdkAgent } from "../runtime/SdkAgent.js";
+import { TaskMigrationService } from "../runtime/TaskMigrationService.js";
 export interface AutoMigrateOptions {
+    /** 迁移服务实例（持有迁移前后钩子；生成交接文档时复用传入 agent 的模型调用） */
+    service: TaskMigrationService;
+    /** 触发迁移的上下文阈值 */
     maxTokens: number;
-    migrationAgent: SdkAgent;
-    /** 迁移开始前触发（promptTokens 刚超限时），此时 agent.messages 还是完整旧历史。适用于保存旧对话或向用户展示迁移提示。 */
-    onBeforeMigrate?: (promptTokens: number, maxTokens: number, agent: SdkAgent) => void;
-    /** 迁移完成后触发，此时交接文档已注入 agent.messages。适用于 UI 更新等后处理。 */
-    onMigrated?: (handoffDoc: string, agent: SdkAgent) => void;
 }
 /**
- * 自动迁移插件。
+ * 自动迁移插件 — 只负责「触发」，实际迁移逻辑统一委托给持有的 `TaskMigrationService` 实例。
  *
- * 当 token 使用量超过 maxTokens 时，自动将对话历史交给 migrationAgent 生成交接文档，
- * 然后用交接文档替换当前 agent 的消息列表，实现无缝迁移。
+ * 当 token 使用量超过 maxTokens 时触发迁移。`service.migrate()` 需要 `agent`（当前对话）作为
+ * 唯一运行时参数，其余（模型、迁移前后钩子）已由服务在构造时持有。
  *
  * ```ts
  * agent.use(new AutoMigratePlugin({
+ *   service: new TaskMigrationService({ onMigrated }),
  *   maxTokens: 250_000,
- *   migrationAgent: anotherAgent,
- *   onMigrated: (doc, agent) => { ... },
  * }));
  * ```
  */
@@ -26,6 +23,4 @@ export declare class AutoMigratePlugin implements AgentPlugin {
     private options;
     constructor(options: AutoMigrateOptions);
     onAfterSend(ctx: SendContext): Promise<void>;
-    private serializeMessages;
-    private getLastAssistantContent;
 }

package/dist/plugin/AutoMigratePlugin.js

@@ -1,18 +1,15 @@
-import { AgentNS } from "@ai-zen/agents-core";
-import { TaskMigrationService } from "../runtime/TaskMigrationService.js";
 import { getLogger } from "../shared/logger.js";
 const log = getLogger();
 /**
- * 自动迁移插件。
+ * 自动迁移插件 — 只负责「触发」，实际迁移逻辑统一委托给持有的 `TaskMigrationService` 实例。
  *
- * 当 token 使用量超过 maxTokens 时，自动将对话历史交给 migrationAgent 生成交接文档，
- * 然后用交接文档替换当前 agent 的消息列表，实现无缝迁移。
+ * 当 token 使用量超过 maxTokens 时触发迁移。`service.migrate()` 需要 `agent`（当前对话）作为
+ * 唯一运行时参数，其余（模型、迁移前后钩子）已由服务在构造时持有。
  *
  * ```ts
  * agent.use(new AutoMigratePlugin({
+ *   service: new TaskMigrationService({ onMigrated }),
  *   maxTokens: 250_000,
- *   migrationAgent: anotherAgent,
- *   onMigrated: (doc, agent) => { ... },
  * }));
  * ```
  */
@@ -23,60 +20,17 @@ export class AutoMigratePlugin {
     }
     async onAfterSend(ctx) {
         const agent = ctx.agent;
-        const { maxTokens, migrationAgent, onBeforeMigrate, onMigrated } = this.options;
+        const { service, maxTokens } = this.options;
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
-        if (!TaskMigrationService.shouldMigrate(promptTokens, maxTokens))
+        if (promptTokens <= maxTokens)
             return;
-        // 迁移前钩子：由上层（CLI）处理用户提示
-        if (onBeforeMigrate) {
-            try {
-                await onBeforeMigrate(promptTokens, maxTokens, agent);
-            }
-            catch (err) {
-                log.error(`[autoMigrate] onBeforeMigrate 回调失败: ${err?.message ?? err}`);
-            }
-        }
         try {
-            const historyText = this.serializeMessages(agent.messages);
-            const migrationResult = await migrationAgent.send(historyText);
-            const handoffDoc = this.getLastAssistantContent(migrationResult);
-            if (!handoffDoc)
-                return;
-            // 仅替换消息列表，不重建 agent，保留所有引用和插件绑定
-            agent.messages.length = 0;
-            agent.messages.push(...agent.definition.messages, ...TaskMigrationService.createPostMessages(handoffDoc));
-            if (onMigrated) {
-                try {
-                    await onMigrated(handoffDoc, agent);
-                }
-                catch (err) {
-                    log.error(`[autoMigrate] onMigrated 回调失败: ${err?.message ?? err}`);
-                }
-            }
+            await service.migrate({ agent, promptTokens, maxTokens });
         }
         catch (err) {
             log.error(`[autoMigrate] 迁移失败: ${err?.message ?? err}`);
         }
     }
-    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");
-    }
-    getLastAssistantContent(messages) {
-        for (let i = messages.length - 1; i >= 0; i--) {
-            if (messages[i].role === AgentNS.Role.Assistant && messages[i].content) {
-                return typeof messages[i].content === "string"
-                    ? messages[i].content
-                    : null;
-            }
-        }
-        return null;
-    }
 }

package/dist/plugin/ContextGuardPlugin.d.ts

@@ -22,8 +22,8 @@ export interface ContextGuardOptions {
  * ```ts
  * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
  * agent.use(new AutoMigratePlugin({
+ *   service: new TaskMigrationService({ onMigrated }),
  *   maxTokens: 250_000,
- *   migrationAgent,
  * }));
  * ```
  */

package/dist/plugin/ContextGuardPlugin.js

@@ -13,8 +13,8 @@ import { ContextOverflowError } from "../shared/errors.js";
  * ```ts
  * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
  * agent.use(new AutoMigratePlugin({
+ *   service: new TaskMigrationService({ onMigrated }),
  *   maxTokens: 250_000,
- *   migrationAgent,
  * }));
  * ```
  */

package/dist/runtime/TaskMigrationService.d.ts

@@ -1,7 +1,70 @@
 import { AgentNS } from "@ai-zen/agents-core";
-import type { AgentDefinition } from "../types/index.js";
+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`，
+ * 因此无需 Provider、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
+ * 如需用不同模型生成交接文档，可在构造时显式传入 `client` / `model` / `modelConfig`，
+ * 未传则 migrate 时回退到 agent 自带的配置。
+ *
+ * 职责：
+ *   1. 生成交接文档的提示词 / 注入格式（静态纯工具，供上层使用）
+ *   2. 执行完整迁移（串行化 → 模型生成 → 按策略处理历史 + 追加对话断点），并暴露迁移前后钩子（实例方法）
+ *
+ * 设计上，`AutoMigratePlugin` 只负责「何时触发」（检测 token 超限），
+ * 实际迁移逻辑统一收敛到本服务，从而让手动迁移与自动迁移复用同一条链路。
  */
 export declare class TaskMigrationService {
     static readonly HANDOFF_SECTIONS: {
@@ -12,13 +75,54 @@ export declare class TaskMigrationService {
         readonly files: "## 📁 文件索引";
         readonly instructions: "## 🔔 接手指令";
     };
-    static shouldMigrate(promptTokens: number, maxTokens: number): boolean;
+    private onBeforeMigrate?;
+    private onMigrated?;
+    private client?;
+    private model?;
+    private modelConfig?;
+    private strategy;
+    private logger;
+    constructor(options?: TaskMigrationServiceOptions);
     static createPrompt(): string;
-    static createAgentDefinition(options?: {
-        modelId?: string;
-    }): AgentDefinition;
+    /**
+     * 生成迁移后追加的「对话断点」消息（role=user）：交接文档 + 接手指令。
+     * 该消息是 omit 迁移方案中新上下文的起点，模型看到的序列为
+     * `[definition.messages, 断点消息]`（历史消息已被标记 omit，不再发送）。
+     */
     static createPostMessages(handoffDoc: string): AgentNS.Message[];
-}
-export interface BuildMigrationAgentOptions {
-    modelId?: string;
+    /**
+     * 序列化消息为 `[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,6 +1,20 @@
 import { AgentNS } from "@ai-zen/agents-core";
+import { getLogger } from "../shared/logger.js";
 /**
  * 任务迁移服务。
+ *
+ * 一个服务实例对应一次迁移上下文。它**不持有**任何模型调用——生成交接文档时
+ * 默认复用传入 `agent`（`SdkAgent`）自身的 `client` / `model` / `modelConfig`，
+ * 因此无需 Provider、无需独立「迁移 Agent」对象，也无需自建 OpenAI 客户端。
+ * 如需用不同模型生成交接文档，可在构造时显式传入 `client` / `model` / `modelConfig`，
+ * 未传则 migrate 时回退到 agent 自带的配置。
+ *
+ * 职责：
+ *   1. 生成交接文档的提示词 / 注入格式（静态纯工具，供上层使用）
+ *   2. 执行完整迁移（串行化 → 模型生成 → 按策略处理历史 + 追加对话断点），并暴露迁移前后钩子（实例方法）
+ *
+ * 设计上，`AutoMigratePlugin` 只负责「何时触发」（检测 token 超限），
+ * 实际迁移逻辑统一收敛到本服务，从而让手动迁移与自动迁移复用同一条链路。
  */
 export class TaskMigrationService {
     static HANDOFF_SECTIONS = {
@@ -11,8 +25,22 @@ export class TaskMigrationService {
         files: "## 📁 文件索引",
         instructions: "## 🔔 接手指令",
     };
-    static shouldMigrate(promptTokens, maxTokens) {
-        return promptTokens > maxTokens;
+    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 [
@@ -38,20 +66,11 @@ export class TaskMigrationService {
             `- 接手后建议的操作步骤`,
         ].join("\n");
     }
-    static createAgentDefinition(options = {}) {
-        const now = new Date().toISOString();
-        return {
-            id: "task-migration",
-            name: "任务交接助手",
-            description: "专用迁移 Agent：分析对话历史并生成结构化交接文档",
-            messages: [
-                { role: AgentNS.Role.System, content: TaskMigrationService.createPrompt() },
-            ],
-            modelId: options.modelId,
-            createdAt: now,
-            updatedAt: now,
-        };
-    }
+    /**
+     * 生成迁移后追加的「对话断点」消息（role=user）：交接文档 + 接手指令。
+     * 该消息是 omit 迁移方案中新上下文的起点，模型看到的序列为
+     * `[definition.messages, 断点消息]`（历史消息已被标记 omit，不再发送）。
+     */
     static createPostMessages(handoffDoc) {
         const content = [
             "这是上一轮对话的任务交接文档。请先阅读交接文档，理解上下文后再继续协助用户完成任务。",
@@ -66,4 +85,127 @@ export class TaskMigrationService {
         ].join("\n");
         return [{ role: AgentNS.Role.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 自带的（无需 Provider / 独立迁移 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;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",