@ai-zen/agents-sdk 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.4] - 2026-07-27
+
+### 🎯 优化
+
+- **`AutoMigratePlugin` 钩子重命名** — `onHandoff` → `onMigrated`，语义更清晰：迁移前用 `onBeforeMigrate`（此时 `agent.messages` 仍是完整旧历史），迁移完成后用 `onMigrated`（交接文档已注入）
+- **`conversation-runner.ts` 保存逻辑修正** — 将保存旧对话从 `onMigrated`（原 `onHandoff`）移至 `onBeforeMigrate`，确保保存的是完整的旧对话历史，而非迁移后的新消息
+
 ## [0.3.3] - 2026-07-27
 
 ### 🎯 优化

package/dist/plugin/AutoMigratePlugin.d.ts

@@ -3,10 +3,10 @@ import { SdkAgent } from "../runtime/SdkAgent.js";
 export interface AutoMigrateOptions {
     maxTokens: number;
     migrationAgent: SdkAgent;
-    /** 迁移开始前触发（promptTokens 刚超限时），可在此向用户展示迁移提示 */
+    /** 迁移开始前触发（promptTokens 刚超限时），此时 agent.messages 还是完整旧历史。适用于保存旧对话或向用户展示迁移提示。 */
     onBeforeMigrate?: (promptTokens: number, maxTokens: number, agent: SdkAgent) => void;
-    /** 迁移完成后触发（交接文档已注入 agent.messages），可在此保存对话等 */
-    onHandoff?: (handoffDoc: string, agent: SdkAgent) => void;
+    /** 迁移完成后触发，此时交接文档已注入 agent.messages。适用于 UI 更新等后处理。 */
+    onMigrated?: (handoffDoc: string, agent: SdkAgent) => void;
 }
 /**
  * 自动迁移插件。
@@ -18,7 +18,7 @@ export interface AutoMigrateOptions {
  * agent.use(new AutoMigratePlugin({
  *   maxTokens: 250_000,
  *   migrationAgent: anotherAgent,
- *   onHandoff: (doc, agent) => { ... },
+ *   onMigrated: (doc, agent) => { ... },
  * }));
  * ```
  */

package/dist/plugin/AutoMigratePlugin.js

@@ -12,7 +12,7 @@ const log = createLogger();
  * agent.use(new AutoMigratePlugin({
  *   maxTokens: 250_000,
  *   migrationAgent: anotherAgent,
- *   onHandoff: (doc, agent) => { ... },
+ *   onMigrated: (doc, agent) => { ... },
  * }));
  * ```
  */
@@ -23,7 +23,7 @@ export class AutoMigratePlugin {
     }
     async onAfterSend(ctx) {
         const { agent } = ctx;
-        const { maxTokens, migrationAgent, onBeforeMigrate, onHandoff } = this.options;
+        const { maxTokens, migrationAgent, onBeforeMigrate, onMigrated } = this.options;
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
@@ -47,12 +47,12 @@ export class AutoMigratePlugin {
             // 仅替换消息列表，不重建 agent，保留所有引用和插件绑定
             agent.messages.length = 0;
             agent.messages.push(...agent.definition.messages, ...TaskMigrationService.createPostMessages(handoffDoc));
-            if (onHandoff) {
+            if (onMigrated) {
                 try {
-                    await onHandoff(handoffDoc, agent);
+                    await onMigrated(handoffDoc, agent);
                 }
                 catch (err) {
-                    log.error(`[autoMigrate] onHandoff 回调失败: ${err?.message ?? err}`);
+                    log.error(`[autoMigrate] onMigrated 回调失败: ${err?.message ?? err}`);
                 }
             }
         }

package/package.json

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