@ai-zen/agents-sdk 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [0.9.1] - 2026-08-28
+
+### 🔧 Fixed
+
+- **SDK-produced messages now always carry an `id`, aligned with core 4.1.0's required `Message.id`** — `TaskMigrationService.createPostMessages()` returns a `Message.User`, and the default agent / sub-agent definitions (`DEFAULT_AGENT_DEFINITION` / `DEFAULT_SUBAGENT_DEFINITION`) build their messages via `Message.System` / `Message.User`. This removes the last places where a bare object literal `{ role, content }` was assigned to `AgentNS.Message`, which would now fail to compile under core 4.1.0 (where `Message.id` is non-optional). Consumers no longer need to patch a missing `id` on SDK-generated messages (e.g. a desktop-side `ensureId` bridge)
+- **No breaking change to public API** — only internal message construction was switched to the `Message` factory methods; exported types and method signatures are unchanged
+
+### ✅ Tests
+
+- SDK suite re-checked green against core 4.1.0 (`Message.id` required)
+
+## [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

package/README.md

@@ -81,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 | ✅ 463 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
 
@@ -118,7 +118,7 @@ Conditionally injected based on the active model / config:
 
 | Plugin | Description |
 |--------|-------------|
-| `AutoMigratePlugin` | Automatically triggers task migration when the context overflows; delegates the actual migration to the injected `TaskMigrationService` instance, which reuses the agent's own model client |
+| `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`) |

package/README.zh.md

@@ -80,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） |
 
 ## 内置工具
 
@@ -117,7 +117,7 @@ await agent.send("你好");
 
 | 插件 | 说明 |
 |------|------|
-| `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档，透明替换 Agent（委托注入的 `TaskMigrationService`，复用 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/config/constants.js

@@ -1,4 +1,4 @@
-import { AgentNS } from "@ai-zen/agents-core";
+import { Message } from "@ai-zen/agents-core";
 // ---------------------------------------------------------------------------
 // 默认 Agent
 // ---------------------------------------------------------------------------
@@ -10,17 +10,14 @@ export const DEFAULT_AGENT_DEFINITION = {
     name: "默认助手",
     description: "默认的 AI 助手，适用于日常问答和任务执行。",
     messages: [
-        {
-            role: AgentNS.Role.System,
-            content: `你是一个严谨可靠的智能助手。请用中文回复，说话风格参照官方文件。
+        Message.System(`你是一个严谨可靠的智能助手。请用中文回复，说话风格参照官方文件。
 
 - 开动脑筋 — 主动思考、灵活运用工具，而不是机械执行
 - 实事求是 — 知之为知之，不知为不知，而不是凭空编造；如果用户意图不明确，应先提问澄清，而不是自行脑补
 - 一切行动听指挥 — 严格遵循用户指令，而不是自作主张
 - 安全第一 — 风险操作先告知确认，而不是盲目执行
 - 能打胜仗 — 写优秀的代码，而不是只限于能用的代码
-- 有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍`,
-        },
+- 有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍`),
     ],
     permissions: {
         tools: { allow: ["*"] },
@@ -40,11 +37,8 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     name: "通用助手",
     description: "一个通用的子 Agent，擅长独立完成各类任务。",
     messages: [
-        {
-            role: AgentNS.Role.System,
-            content: "你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。\n\n⚠️ 强制性要求：\n1. 如果任务描述中存在任何不明确、模糊或缺失的信息（包括但不限于具体目标、文件路径、约束条件、预期产出等），你必须直接拒绝执行，并明确列出哪些信息不明确或缺失，要求父 Agent 提供更完整的任务上下文。不得自行假设、猜测或脑补任何信息。\n2. 如果任务描述中存在自相矛盾的信息（如相互冲突的要求、不一致的文件路径、矛盾的约束条件等），你必须及时指出矛盾之处，并要求父 Agent 澄清后再执行。",
-        },
-        { role: AgentNS.Role.User, content: "{{task}}" },
+        Message.System("你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。\n\n⚠️ 强制性要求：\n1. 如果任务描述中存在任何不明确、模糊或缺失的信息（包括但不限于具体目标、文件路径、约束条件、预期产出等），你必须直接拒绝执行，并明确列出哪些信息不明确或缺失，要求父 Agent 提供更完整的任务上下文。不得自行假设、猜测或脑补任何信息。\n2. 如果任务描述中存在自相矛盾的信息（如相互冲突的要求、不一致的文件路径、矛盾的约束条件等），你必须及时指出矛盾之处，并要求父 Agent 澄清后再执行。"),
+        Message.User("{{task}}"),
     ],
     permissions: {
         tools: { allow: ["*"] },

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 { MigrationContext, TaskMigrationServiceOptions, } 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/runtime/TaskMigrationService.d.ts

@@ -24,6 +24,13 @@ export interface MigrationContext {
     /** 生成的交接文档（迁移完成后填充） */
     handoffDoc?: string;
 }
+/**
+ * 迁移后的历史处理策略。
+ *
+ * - `omit`（默认）：将历史消息标记 `omit: true`，仍保留在 `agent.messages` 可审计/回放，但不再发送给模型；
+ * - `prune`：物理剔除历史，只保留 `definition.messages`（系统提示等模板）+ 追加的对话断点。
+ */
+export type MigrationStrategy = "omit" | "prune";
 /**
  * 任务迁移服务构造参数。
  */
@@ -34,6 +41,8 @@ export interface TaskMigrationServiceOptions {
     model?: string;
     /** 生成交接文档所用模型参数（可选；未传则 migrate 时回退到 agent.modelConfig） */
     modelConfig?: Record<string, unknown>;
+    /** 迁移后历史处理策略，默认 `omit`（标记历史保留可审计）。可选 `prune`（物理剔除）。 */
+    strategy?: MigrationStrategy;
     /** 迁移前钩子（服务持有）。迁移开始前触发，此时 agent.messages 仍为完整旧历史 */
     onBeforeMigrate?: (ctx: MigrationContext) => void | Promise<void>;
     /** 迁移后钩子（服务持有）。迁移完成后触发，交接文档已注入 agent.messages */
@@ -52,7 +61,7 @@ export interface TaskMigrationServiceOptions {
  *
  * 职责：
  *   1. 生成交接文档的提示词 / 注入格式（静态纯工具，供上层使用）
- *   2. 执行完整迁移（串行化 → 模型生成 → 替换消息），并暴露迁移前后钩子（实例方法）
+ *   2. 执行完整迁移（串行化 → 模型生成 → 按策略处理历史 + 追加对话断点），并暴露迁移前后钩子（实例方法）
  *
  * 设计上，`AutoMigratePlugin` 只负责「何时触发」（检测 token 超限），
  * 实际迁移逻辑统一收敛到本服务，从而让手动迁移与自动迁移复用同一条链路。
@@ -71,9 +80,15 @@ export declare class TaskMigrationService {
     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` 文本，供模型理解完整对话历史。
@@ -84,21 +99,30 @@ export declare class TaskMigrationService {
      */
     private generateHandoff;
     /**
-     * 执行完整迁移：序列化历史 → 模型生成交接文档 → 替换消息列表 → 触发钩子。
+     * 执行完整迁移：序列化历史 → 模型生成交接文档 → 按策略处理历史并追加对话断点 → 触发钩子。
+     *
+     * 策略（`strategy`，构造函数默认 / 本参数可覆盖）：
+     *   - `omit`（默认）：`agent.definition.messages`（模板）保留，其余既有历史标记 `omit: true`（仍存于
+     *     `agent.messages` 可审计/回放但不再发送给模型），末尾追加「对话断点」消息。因此 `formatHistory()`
+     *     发送给模型的是 `[definition.messages, 断点消息]` —— 历史被压缩但并不删除。
+     *   - `prune`：物理剔除历史，只保留 `definition.messages` + 断点消息（即原先的替换行为）。
      *
      * 设计约束：
-     *   - 不重建 Agent，保留所有引用与插件绑定（仅替换消息列表）
+     *   - 不重建 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,4 +1,4 @@
-import { AgentNS } from "@ai-zen/agents-core";
+import { Message } from "@ai-zen/agents-core";
 import { getLogger } from "../shared/logger.js";
 /**
  * 任务迁移服务。
@@ -11,7 +11,7 @@ import { getLogger } from "../shared/logger.js";
  *
  * 职责：
  *   1. 生成交接文档的提示词 / 注入格式（静态纯工具，供上层使用）
- *   2. 执行完整迁移（串行化 → 模型生成 → 替换消息），并暴露迁移前后钩子（实例方法）
+ *   2. 执行完整迁移（串行化 → 模型生成 → 按策略处理历史 + 追加对话断点），并暴露迁移前后钩子（实例方法）
  *
  * 设计上，`AutoMigratePlugin` 只负责「何时触发」（检测 token 超限），
  * 实际迁移逻辑统一收敛到本服务，从而让手动迁移与自动迁移复用同一条链路。
@@ -30,14 +30,16 @@ export class TaskMigrationService {
     client;
     model;
     modelConfig;
+    strategy;
     logger;
     constructor(options = {}) {
-        const { onBeforeMigrate, onMigrated, logger, client, model, modelConfig } = 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() {
@@ -64,6 +66,11 @@ export class TaskMigrationService {
             `- 接手后建议的操作步骤`,
         ].join("\n");
     }
+    /**
+     * 生成迁移后追加的「对话断点」消息（role=user）：交接文档 + 接手指令。
+     * 该消息是 omit 迁移方案中新上下文的起点，模型看到的序列为
+     * `[definition.messages, 断点消息]`（历史消息已被标记 omit，不再发送）。
+     */
     static createPostMessages(handoffDoc) {
         const content = [
             "这是上一轮对话的任务交接文档。请先阅读交接文档，理解上下文后再继续协助用户完成任务。",
@@ -76,7 +83,7 @@ export class TaskMigrationService {
             "",
             "请确认你已理解以上内容，然后询问用户接下来需要什么帮助。",
         ].join("\n");
-        return [{ role: AgentNS.Role.User, content }];
+        return [Message.User(content)];
     }
     /**
      * 序列化消息为 `[role]: content` 文本，供模型理解完整对话历史。
@@ -109,21 +116,31 @@ export class TaskMigrationService {
         return handoffDoc;
     }
     /**
-     * 执行完整迁移：序列化历史 → 模型生成交接文档 → 替换消息列表 → 触发钩子。
+     * 执行完整迁移：序列化历史 → 模型生成交接文档 → 按策略处理历史并追加对话断点 → 触发钩子。
+     *
+     * 策略（`strategy`，构造函数默认 / 本参数可覆盖）：
+     *   - `omit`（默认）：`agent.definition.messages`（模板）保留，其余既有历史标记 `omit: true`（仍存于
+     *     `agent.messages` 可审计/回放但不再发送给模型），末尾追加「对话断点」消息。因此 `formatHistory()`
+     *     发送给模型的是 `[definition.messages, 断点消息]` —— 历史被压缩但并不删除。
+     *   - `prune`：物理剔除历史，只保留 `definition.messages` + 断点消息（即原先的替换行为）。
      *
      * 设计约束：
-     *   - 不重建 Agent，保留所有引用与插件绑定（仅替换消息列表）
+     *   - 不重建 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 } = params;
-        const historyText = TaskMigrationService.serializeMessages(agent.messages);
+        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）。
@@ -150,13 +167,26 @@ export class TaskMigrationService {
         }
         // 生成交接文档
         const handoffDoc = await this.generateHandoff(client, model, modelConfig, historyText);
-        // 替换消息列表
-        const nextMessages = [
-            ...agent.definition.messages,
-            ...TaskMigrationService.createPostMessages(handoffDoc),
-        ];
-        agent.messages.length = 0;
-        agent.messages.push(...nextMessages);
+        // 重建消息列表：按策略处理历史（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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
     "openai": "^7.5.0",
-    "@ai-zen/agents-core": "^4.0.0"
+    "@ai-zen/agents-core": "^4.1.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",