@ai-zen/agents-sdk 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.2.2] - 2026-07-20
+
+### 🔧 修复
+
+- **`SdkAgent.send()` — `ctx.messages` 不再直接引用 `this.messages`** — 改为浅拷贝快照，确保消息数组仅由 agent 作为唯一维护者
+- **`AutoMigratePlugin` — 不再创建新 Agent 实例** — 直接替换 `agent.messages` 数组，保留所有引用、插件绑定和事件监听
+- **`AutoMigratePlugin` — 迁移前增加日志提示** — 使用 `log.warn` 输出迁移开始通知
+
+### 🎯 优化
+
+- **`AutoMigratePlugin` — `onHandoff` 签名简化** — 从 `(doc, oldAgent, newAgent)` 改为 `(doc, agent)`，因为 agent 是同一对象
+- **`TaskMigrationService.createPrompt()` — 精简提示词** — 明确要求只输出交接文档，不做任何解释
+
+### ✅ 测试
+
+- 补充迁移前后消息数组**长度精确断言**（迁移前 3 条 → 迁移后 2 条）
+- 补充迁移失败时消息数组**长度和内容不变**的断言

package/dist/capabilities/Capabilities.js

@@ -116,14 +116,15 @@ export class Capabilities {
         if (allowedToolNames.has("call_skill_sub_agent") && hasSubAgentSkills) {
             result.push(createCallSkillSubAgentTool(provider.skillsPaths, filteredSkills, this));
         }
-        if (allowedToolNames.has("load_mcp") && provider.mcpManager && provider.mcpConfigs && filteredMcps.length > 0) {
-            result.push(createLoadMcpTool(provider.mcpManager, provider.mcpConfigs, filteredMcps));
+        const mcpManager = provider.getMcpManager();
+        if (allowedToolNames.has("load_mcp") && mcpManager && filteredMcps.length > 0) {
+            result.push(createLoadMcpTool(mcpManager, filteredMcps));
         }
-        if (allowedToolNames.has("call_mcp_tool") && provider.mcpManager) {
-            result.push(createCallMcpTool(provider.mcpManager));
+        if (allowedToolNames.has("call_mcp_tool") && mcpManager) {
+            result.push(createCallMcpTool(mcpManager));
         }
-        if (allowedToolNames.has("read_mcp_resource") && provider.mcpManager) {
-            result.push(createReadMcpResourceTool(provider.mcpManager));
+        if (allowedToolNames.has("read_mcp_resource") && mcpManager) {
+            result.push(createReadMcpResourceTool(mcpManager));
         }
         // 4. SubAgent
         const allowedSubagentSet = new Set(filtered.subagents);

package/dist/capabilities/discovery/mcp.d.ts

@@ -1,7 +1,12 @@
 import type { McpServerConfig } from "../../types/index.js";
 /**
  * 从 mcp.json 文件列表中发现所有 MCP server 配置。
+ *
+ * 遵循业界标准格式：
+ * ```json
+ * { "mcpServers": { "server-id": { "type": "stdio", "command": "npx", ... } } }
+ * ```
+ *
  * 按优先级从高到低传入路径列表，同名 server 靠前的文件优先（先到先得）。
- * 返回完整配置，不再丢失信息。
  */
 export declare function discoverMcpServers(paths: string[]): McpServerConfig[];

package/dist/capabilities/discovery/mcp.js

@@ -1,8 +1,55 @@
 import { existsSync, readFileSync } from "node:fs";
+/**
+ * 归一化原始 MCP server 配置为内部 McpServerConfig。
+ * 处理业界标准中的字段别名差异。
+ */
+function normalizeConfig(id, raw) {
+    // disabled 处理
+    if (raw.disabled === true)
+        return null;
+    // transport 类型：优先取 type，兼容 transport/transportType
+    const transportRaw = (raw.type ?? raw.transport ?? raw.transportType ?? "");
+    const transport = normalizeTransport(transportRaw, raw);
+    if (!transport)
+        return null;
+    const config = {
+        id,
+        transport,
+        command: raw.command,
+        args: raw.args,
+        env: raw.env,
+        url: raw.url,
+        headers: raw.headers,
+    };
+    return config;
+}
+/**
+ * 归一化 transport 取值。
+ * 不填时自动推断：有 command→stdio，有 url→http。
+ */
+function normalizeTransport(type, raw) {
+    if (type === "stdio")
+        return "stdio";
+    if (type === "http")
+        return "http";
+    if (type === "sse")
+        return "sse";
+    // 自动推断
+    if (raw.command)
+        return "stdio";
+    if (raw.url)
+        return "http";
+    return null;
+}
 /**
  * 从 mcp.json 文件列表中发现所有 MCP server 配置。
+ *
+ * 遵循业界标准格式：
+ * ```json
+ * { "mcpServers": { "server-id": { "type": "stdio", "command": "npx", ... } } }
+ * ```
+ *
  * 按优先级从高到低传入路径列表，同名 server 靠前的文件优先（先到先得）。
- * 返回完整配置，不再丢失信息。
  */
 export function discoverMcpServers(paths) {
     const seen = new Set();
@@ -13,16 +60,23 @@ export function discoverMcpServers(paths) {
         try {
             const raw = readFileSync(path, "utf-8");
             const config = JSON.parse(raw);
-            const servers = config.servers ?? {};
+            // 业界标准使用 mcpServers 顶层字段
+            const servers = config.mcpServers ?? {};
             for (const id of Object.keys(servers)) {
-                if (!seen.has(id)) {
-                    seen.add(id);
-                    items.push({ id, ...servers[id] });
-                }
+                if (seen.has(id))
+                    continue;
+                const rawServer = servers[id];
+                if (!rawServer || typeof rawServer !== "object")
+                    continue;
+                const normalized = normalizeConfig(id, rawServer);
+                if (!normalized)
+                    continue;
+                seen.add(id);
+                items.push(normalized);
             }
         }
-        catch {
-            // 跳过解析失败
+        catch (err) {
+            console.warn(`[sdk] 解析 MCP 配置失败: ${path}`, err);
         }
     }
     return items;

package/dist/capabilities/implements/mcpTools.d.ts

@@ -3,12 +3,10 @@ import type { McpConnectionManager } from "../../runtime/McpConnectionManager.js
 import type { McpServerConfig } from "../../types/index.js";
 /**
  * 创建 load_mcp 工具。
- * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导。
+ * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导，
+ * 查找配置也直接使用 filteredMcps，与枚举来源一致。
  */
-export declare function createLoadMcpTool(mcpManager: McpConnectionManager, mcpConfigs: Map<string, {
-    name: string;
-    config: McpServerConfig;
-}>, filteredMcps: McpServerConfig[]): CallbackTool;
+export declare function createLoadMcpTool(mcpManager: McpConnectionManager, filteredMcps: McpServerConfig[]): CallbackTool;
 /**
  * 创建 call_mcp_tool 工具。
  * 通过官方 Client.callTool() API 调用 MCP 服务器上的工具。

package/dist/capabilities/implements/mcpTools.js

@@ -3,9 +3,15 @@ import { createDisclosureParam } from "../disclosure.js";
 const EMPTY_HINT = "（当前没有可用的 MCP 服务器，请联系用户添加）";
 /**
  * 创建 load_mcp 工具。
- * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导。
+ * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导，
+ * 查找配置也直接使用 filteredMcps，与枚举来源一致。
  */
-export function createLoadMcpTool(mcpManager, mcpConfigs, filteredMcps) {
+export function createLoadMcpTool(mcpManager, filteredMcps) {
+    // 构建 id→config 查找表
+    const configMap = new Map();
+    for (const s of filteredMcps) {
+        configMap.set(s.id, s);
+    }
     const ids = filteredMcps.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 MCP 服务器", EMPTY_HINT);
     return new CallbackTool({
@@ -27,8 +33,8 @@ export function createLoadMcpTool(mcpManager, mcpConfigs, filteredMcps) {
         },
         callback: async (input) => {
             const serverName = input.server;
-            const serverConfig = mcpConfigs.get(serverName);
-            if (!serverConfig) {
+            const config = configMap.get(serverName);
+            if (!config) {
                 return `❌ MCP 服务器 "${serverName}" 不存在`;
             }
             const existingManifest = mcpManager.getManifest(serverName);
@@ -38,7 +44,7 @@ export function createLoadMcpTool(mcpManager, mcpConfigs, filteredMcps) {
                 return `✅ MCP 服务器 "${serverName}" 已连接 (${existingManifest.tools.length} 个工具):\n${toolList}`;
             }
             try {
-                const manifest = await mcpManager.connect(serverName, serverConfig.config);
+                const manifest = await mcpManager.connect(serverName, config);
                 const toolList = manifest.tools.map((t) => `- ${t.name}: ${t.description}`).join("\n");
                 return `✅ MCP 服务器 "${serverName}" 已连接 (${manifest.tools.length} 个工具):\n${toolList}`;
             }

package/dist/plugin/AutoMigratePlugin.d.ts

@@ -1,18 +1,24 @@
-import { SdkAgent } from "../runtime/SdkAgent.js";
 import type { AgentPlugin, SendContext } from "../runtime/SdkAgent.js";
+import { SdkAgent } from "../runtime/SdkAgent.js";
 export interface AutoMigrateOptions {
     maxTokens: number;
     migrationAgent: SdkAgent;
-    onHandoff?: (handoffDoc: string, oldAgent: SdkAgent, newAgent: SdkAgent) => void;
+    /** 迁移开始前触发（promptTokens 刚超限时），可在此向用户展示迁移提示 */
+    onBeforeMigrate?: (promptTokens: number, maxTokens: number, agent: SdkAgent) => void;
+    /** 迁移完成后触发（交接文档已注入 agent.messages），可在此保存对话等 */
+    onHandoff?: (handoffDoc: string, agent: SdkAgent) => void;
 }
 /**
  * 自动迁移插件。
  *
+ * 当 token 使用量超过 maxTokens 时，自动将对话历史交给 migrationAgent 生成交接文档，
+ * 然后用交接文档替换当前 agent 的消息列表，实现无缝迁移。
+ *
  * ```ts
  * agent.use(new AutoMigratePlugin({
  *   maxTokens: 250_000,
- *   migrationAgent,
- *   onHandoff: (doc, old, next) => { ... },
+ *   migrationAgent: anotherAgent,
+ *   onHandoff: (doc, agent) => { ... },
  * }));
  * ```
  */

package/dist/plugin/AutoMigratePlugin.js

@@ -1,16 +1,18 @@
 import { AgentNS } from "@ai-zen/agents-core";
-import { SdkAgent } from "../runtime/SdkAgent.js";
 import { TaskMigrationService } from "../runtime/TaskMigrationService.js";
 import { createLogger } from "../shared/logger.js";
 const log = createLogger();
 /**
  * 自动迁移插件。
  *
+ * 当 token 使用量超过 maxTokens 时，自动将对话历史交给 migrationAgent 生成交接文档，
+ * 然后用交接文档替换当前 agent 的消息列表，实现无缝迁移。
+ *
  * ```ts
  * agent.use(new AutoMigratePlugin({
  *   maxTokens: 250_000,
- *   migrationAgent,
- *   onHandoff: (doc, old, next) => { ... },
+ *   migrationAgent: anotherAgent,
+ *   onHandoff: (doc, agent) => { ... },
  * }));
  * ```
  */
@@ -21,27 +23,33 @@ export class AutoMigratePlugin {
     }
     async onAfterSend(ctx) {
         const { agent } = ctx;
-        const { maxTokens, migrationAgent, onHandoff } = this.options;
+        const { maxTokens, migrationAgent, onBeforeMigrate, onHandoff } = this.options;
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
         if (!TaskMigrationService.shouldMigrate(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;
-            const newMessages = [
-                ...agent.definition.messages,
-                ...TaskMigrationService.createPostMessages(handoffDoc),
-            ];
-            const newAgent = new SdkAgent({ ...agent, messages: newMessages });
-            ctx.agent = newAgent;
+            // 仅替换消息列表，不重建 agent，保留所有引用和插件绑定
+            agent.messages.length = 0;
+            agent.messages.push(...agent.definition.messages, ...TaskMigrationService.createPostMessages(handoffDoc));
             if (onHandoff) {
                 try {
-                    await onHandoff(handoffDoc, agent, newAgent);
+                    await onHandoff(handoffDoc, agent);
                 }
                 catch (err) {
                     log.error(`[autoMigrate] onHandoff 回调失败: ${err?.message ?? err}`);

package/dist/runtime/McpConnectionManager.js

@@ -4,6 +4,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 const DEFAULT_IDLE_TIMEOUT = {
     stdio: 30 * 60 * 1000,
     http: 5 * 60 * 1000,
+    sse: 5 * 60 * 1000,
 };
 /** 指数退避: 1s → 2s → 4s → 8s → 16s → 30s（封顶） */
 function backoff(attempt) {
@@ -169,9 +170,10 @@ export class McpConnectionManager {
                 env: config.env,
             });
         }
-        if (config.transport === "http") {
+        // http 和 sse 都使用 StreamableHTTPClientTransport
+        if (config.transport === "http" || config.transport === "sse") {
             if (!config.url) {
-                throw new Error(`MCP HTTP server 缺少 url`);
+                throw new Error(`MCP ${config.transport} server 缺少 url`);
             }
             return new StreamableHTTPClientTransport(new URL(config.url), {
                 requestInit: config.headers ? { headers: config.headers } : undefined,

package/dist/runtime/Provider.d.ts

@@ -1,5 +1,5 @@
-import type { AppConfig, McpServerConfig } from "../types/index.js";
-import type { McpConnectionManager } from "./McpConnectionManager.js";
+import type { AppConfig } from "../types/index.js";
+import { McpConnectionManager } from "./McpConnectionManager.js";
 /**
  * Provider — 全局上下文实例。
  *
@@ -19,13 +19,7 @@ export declare class Provider {
     readonly skillsPaths: string[];
     readonly toolsPaths: string[];
     readonly mcpPaths: string[];
-    readonly conversationsDir: string;
-    readonly draftsDir: string;
-    readonly mcpManager?: McpConnectionManager;
-    readonly mcpConfigs?: Map<string, {
-        name: string;
-        config: McpServerConfig;
-    }>;
+    private _mcpManager?;
     constructor(options: {
         config: AppConfig;
         agentsDir: string;
@@ -33,12 +27,10 @@ export declare class Provider {
         skillsPaths?: string[];
         toolsPaths?: string[];
         mcpPaths?: string[];
-        conversationsDir: string;
-        draftsDir: string;
-        mcpManager?: McpConnectionManager;
-        mcpConfigs?: Map<string, {
-            name: string;
-            config: McpServerConfig;
-        }>;
     });
+    /**
+     * 获取 McpConnectionManager，有 mcpPaths 时延迟创建。
+     * 首次访问时创建，后续复用同一实例。
+     */
+    getMcpManager(): McpConnectionManager | undefined;
 }

package/dist/runtime/Provider.js

@@ -1,3 +1,4 @@
+import { McpConnectionManager } from "./McpConnectionManager.js";
 /**
  * Provider — 全局上下文实例。
  *
@@ -18,11 +19,8 @@ export class Provider {
     skillsPaths;
     toolsPaths;
     mcpPaths;
-    conversationsDir;
-    draftsDir;
     // ---- MCP ----
-    mcpManager;
-    mcpConfigs;
+    _mcpManager;
     constructor(options) {
         this.config = options.config;
         this.agentsDir = options.agentsDir;
@@ -30,9 +28,15 @@ export class Provider {
         this.skillsPaths = options.skillsPaths ?? [];
         this.toolsPaths = options.toolsPaths ?? [];
         this.mcpPaths = options.mcpPaths ?? [];
-        this.conversationsDir = options.conversationsDir;
-        this.draftsDir = options.draftsDir;
-        this.mcpManager = options.mcpManager;
-        this.mcpConfigs = options.mcpConfigs;
+    }
+    /**
+     * 获取 McpConnectionManager，有 mcpPaths 时延迟创建。
+     * 首次访问时创建，后续复用同一实例。
+     */
+    getMcpManager() {
+        if (!this._mcpManager && this.mcpPaths.length > 0) {
+            this._mcpManager = new McpConnectionManager();
+        }
+        return this._mcpManager;
     }
 }

package/dist/runtime/SdkAgent.d.ts

@@ -5,10 +5,16 @@ import type { Capabilities } from "../capabilities/Capabilities.js";
 import type { Provider } from "./Provider.js";
 /**
  * Agent 插件上下文：当前 SdkAgent + 发送内容 + 消息列表。
+ *
+ * 注意：
+ * - messages 是当前 agent 消息数组的**快照**（浅拷贝），插件不应直接修改它。
+ *   所有消息变更应通过 agent 上的方法进行。
+ * - 如果 onAfterSend 替换了 ctx.agent，send() 方法会使用新 agent 的消息作为返回值。
  */
 export interface SendContext {
     agent: SdkAgent;
     content: string;
+    /** 当前 agent 消息数组的浅拷贝快照，仅供读取，不应直接修改 */
     messages: AgentNS.Message[];
 }
 /**
@@ -95,6 +101,10 @@ export declare class SdkAgent extends Agent {
      *   1. onBeforeSend — send 外部准备（刷新工具等）
      *   2. super.send()  — 委托 Core Agent，内含内循环及其钩子
      *   3. onAfterSend  — send 外部后处理（保存草稿、迁移等）
+     *
+     * 注意：
+     * - ctx.messages 是当前 agent 消息的**浅拷贝快照**，仅供读取，不应直接修改。
+     *   所有消息变更应通过 agent 上的方法进行（如 agent.messages.push 等）。
      */
     send(content: string): Promise<AgentNS.Message[]>;
 }

package/dist/runtime/SdkAgent.js

@@ -72,12 +72,16 @@ export class SdkAgent extends Agent {
      *   1. onBeforeSend — send 外部准备（刷新工具等）
      *   2. super.send()  — 委托 Core Agent，内含内循环及其钩子
      *   3. onAfterSend  — send 外部后处理（保存草稿、迁移等）
+     *
+     * 注意：
+     * - ctx.messages 是当前 agent 消息的**浅拷贝快照**，仅供读取，不应直接修改。
+     *   所有消息变更应通过 agent 上的方法进行（如 agent.messages.push 等）。
      */
     async send(content) {
         const ctx = {
             agent: this,
             content,
-            messages: this.messages,
+            messages: [...this.messages],
         };
         for (const plugin of this._plugins) {
             await plugin.onBeforeSend?.(ctx);
@@ -92,12 +96,12 @@ export class SdkAgent extends Agent {
                 await plugin.onInnerLoopEnd?.(ctx);
             }
         };
-        const messages = await super.send(content);
+        await super.send(content);
         this.onInnerLoopStart = undefined;
         this.onInnerLoopEnd = undefined;
         for (const plugin of this._plugins) {
             await plugin.onAfterSend?.(ctx);
         }
-        return messages;
+        return this.messages;
     }
 }

package/dist/runtime/TaskMigrationService.js

@@ -16,7 +16,7 @@ export class TaskMigrationService {
     }
     static createPrompt() {
         return [
-            "你是一个任务交接助手。请根据以下对话历史，生成一份结构化交接文档。",
+            "根据以下对话历史，生成一篇结构化交接文档。不要做任何解释，只输出交接文档。",
             "",
             `文档必须包含以下章节：`,
             `${TaskMigrationService.HANDOFF_SECTIONS.breakpoint}`,
@@ -36,8 +36,6 @@ export class TaskMigrationService {
             "",
             `${TaskMigrationService.HANDOFF_SECTIONS.instructions}`,
             `- 接手后建议的操作步骤`,
-            "",
-            "只输出交接文档本身，不要加额外说明。",
         ].join("\n");
     }
     static createAgentDefinition(options = {}) {

package/dist/types/index.d.ts

@@ -92,13 +92,13 @@ export interface AppConfig {
 }
 /** MCP 连接状态 */
 export type McpConnectionState = "disconnected" | "connecting" | "connected" | "error";
-/** MCP 服务器配置（含 CLI/Desktop 需要的额外字段） */
+/** MCP 服务器配置 */
 export interface McpServerConfig {
     id: string;
-    name: string;
+    /** transport 类型，内部统一使用 "stdio" | "http" | "sse" */
     transport: "stdio" | "http" | "sse";
-    /** 是否启用 */
-    enabled?: boolean;
+    /** 是否禁用，默认为 false */
+    disabled?: boolean;
     command?: string;
     args?: string[];
     env?: Record<string, string>;

package/package.json

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