@ai-zen/agents-sdk 0.2.0-alpha.3 → 0.2.2

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.d.ts

@@ -67,5 +67,7 @@ export declare class Capabilities {
     /**
      * 重新执行全局发现（重新扫描文件系统）。
      */
-    refresh(): void;
+    refresh(options?: {
+        silent?: boolean;
+    }): void;
 }

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);
@@ -138,12 +139,13 @@ export class Capabilities {
     /**
      * 重新执行全局发现（重新扫描文件系统）。
      */
-    refresh() {
+    refresh(options) {
+        const silent = options?.silent ?? false;
         const provider = this.provider;
         this.builtinInstances = discoverBuiltinTools(provider.config);
-        this.userInstances = discoverUserTools(provider.toolsPaths);
+        this.userInstances = discoverUserTools(provider.toolsPaths, { silent });
         this.subagentDefs = discoverSubAgents(provider.subAgentsPaths);
-        this.skills = discoverSkills(provider.skillsPaths);
+        this.skills = discoverSkills(provider.skillsPaths, { silent });
         this.mcps = discoverMcpServers(provider.mcpPaths);
     }
 }

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/discovery/skills.d.ts

@@ -30,13 +30,17 @@ export interface SkillInfo {
  * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
  * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
  */
-export declare function discoverSkills(paths: string[]): SkillInfo[];
+export declare function discoverSkills(paths: string[], options?: {
+    silent?: boolean;
+}): SkillInfo[];
 /**
  * 读取单个 Skill 的完整内容与元数据。
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
  * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
  */
-export declare function readSkill(skillDirs: string[], skillId: string): SkillInfo | null;
+export declare function readSkill(skillDirs: string[], skillId: string, options?: {
+    silent?: boolean;
+}): SkillInfo | null;
 /** @internal */
 export declare function parseFrontmatter(content: string): Frontmatter;
 /** @internal */

package/dist/capabilities/discovery/skills.js

@@ -8,7 +8,8 @@ const log = createLogger();
  * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
  * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
  */
-export function discoverSkills(paths) {
+export function discoverSkills(paths, options) {
+    const silent = options?.silent ?? false;
     const seen = new Set();
     const items = [];
     for (const dir of paths) {
@@ -29,7 +30,7 @@ export function discoverSkills(paths) {
             const skillMdPath = join(dir, entry.name, "SKILL.md");
             if (!existsSync(skillMdPath))
                 continue;
-            const skill = readSkillFromPath(entry.name, skillMdPath);
+            const skill = readSkillFromPath(entry.name, skillMdPath, silent);
             if (skill) {
                 seen.add(entry.name);
                 items.push(skill);
@@ -44,26 +45,29 @@ export function discoverSkills(paths) {
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
  * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
  */
-export function readSkill(skillDirs, skillId) {
+export function readSkill(skillDirs, skillId, options) {
+    const silent = options?.silent ?? false;
     for (const dir of skillDirs) {
         const candidate = join(dir, skillId, "SKILL.md");
         if (existsSync(candidate)) {
-            return readSkillFromPath(skillId, candidate);
+            return readSkillFromPath(skillId, candidate, silent);
         }
     }
     return null;
 }
 // ---- 内部 ----
-function readSkillFromPath(skillId, skillMdPath) {
+function readSkillFromPath(skillId, skillMdPath, silent) {
     try {
         const content = readFileSync(skillMdPath, "utf-8");
         const fm = parseFrontmatter(content);
         if (!fm.name)
             return null;
         // 规范合规校验
-        const errors = validateSkill(skillId, fm);
-        for (const err of errors) {
-            log.warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
+        if (!silent) {
+            const errors = validateSkill(skillId, fm);
+            for (const err of errors) {
+                log.warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
+            }
         }
         return {
             id: skillId,

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

@@ -10,4 +10,6 @@ import { Tool } from "@ai-zen/agents-core";
  * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
  * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
  */
-export declare function discoverUserTools(paths: string[]): Tool[];
+export declare function discoverUserTools(paths: string[], options?: {
+    silent?: boolean;
+}): Tool[];

package/dist/capabilities/discovery/usertools.js

@@ -13,7 +13,8 @@ import { Tool, CallbackTool } from "@ai-zen/agents-core";
  * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
  * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
  */
-export function discoverUserTools(paths) {
+export function discoverUserTools(paths, options) {
+    const silent = options?.silent ?? false;
     const seen = new Set();
     const tools = [];
     for (const dir of paths) {
@@ -28,7 +29,7 @@ export function discoverUserTools(paths) {
                 if (!seen.has(name)) {
                     seen.add(name);
                     try {
-                        const tool = loadToolFile(join(dir, name + ".js"));
+                        const tool = loadToolFile(join(dir, name + ".js"), silent);
                         if (tool) {
                             tools.push(tool);
                         }
@@ -51,7 +52,7 @@ export function discoverUserTools(paths) {
  * 使用 vm.compileFunction 创建沙箱执行环境，避免污染全局作用域。
  * 注入有限的全局 API（console, setTimeout 等），不暴露 process/require。
  */
-function loadToolFile(filepath) {
+function loadToolFile(filepath, silent) {
     const code = readFileSync(filepath, "utf-8");
     // 构造沙箱上下文
     const sandbox = {
@@ -83,17 +84,19 @@ function loadToolFile(filepath) {
             return null;
         }
         // 适配不同导出格式
-        return normalizeToolExport(exported, filepath);
+        return normalizeToolExport(exported, filepath, silent);
     }
     catch (err) {
-        console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+        if (!silent) {
+            console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+        }
         return null;
     }
 }
 /**
  * 统一各种导出格式为 Tool 实例。
  */
-function normalizeToolExport(exported, filepath) {
+function normalizeToolExport(exported, filepath, silent) {
     // 情况 1：直接是 Tool 实例
     if (exported instanceof Tool) {
         return exported;
@@ -114,7 +117,9 @@ function normalizeToolExport(exported, filepath) {
             callback: target.callback,
         });
     }
-    console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+    if (!silent) {
+        console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+    }
     return null;
 }
 /**

package/dist/capabilities/implements/builtin/execAsync.js

@@ -94,7 +94,7 @@ export const execAsyncTool = new CallbackTool({
                 resolve(JSON.stringify({
                     success: false,
                     pid: null,
-                    error: `启动失败: ${err.message}`,
+                    message: `启动失败: ${err.message}`,
                 }));
             });
             child.on("spawn", () => {

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/capabilities/implements/skillTools.js

@@ -12,6 +12,11 @@ const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";
 export function createLoadSkillTool(skillDirs, filteredSkills) {
     const ids = filteredSkills.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 Skill", EMPTY_HINT);
+    // 拼接各 skill 的描述供 LLM 参考
+    const skillDescriptions = filteredSkills
+        .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
+        .join("\n");
+    const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
     return new CallbackTool({
         function: {
             name: "load_skill",
@@ -21,7 +26,7 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
                 properties: {
                     skill_id: {
                         type: "string",
-                        description: param.description,
+                        description: skillIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
                 },
@@ -57,6 +62,11 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
     const subAgentSkills = filteredSkills.filter((s) => s.subAgent);
     const ids = subAgentSkills.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 Skill（支持子 Agent）", EMPTY_HINT);
+    // 拼接各 skill 的描述供 LLM 参考
+    const skillDescriptions = subAgentSkills
+        .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
+        .join("\n");
+    const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
     return new CallbackTool({
         function: {
             name: "call_skill_sub_agent",
@@ -66,7 +76,7 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
                 properties: {
                     skill_id: {
                         type: "string",
-                        description: param.description,
+                        description: skillIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
                     task: {

package/dist/plugin/AutoMigratePlugin.d.ts

@@ -1,18 +1,21 @@
-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;
+    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) => { ... },
  * }));
  * ```
  */
@@ -27,21 +29,19 @@ export class AutoMigratePlugin {
             return;
         if (!TaskMigrationService.shouldMigrate(promptTokens, maxTokens))
             return;
+        log.warn(`[autoMigrate] Token 使用量已达 ${promptTokens}，超出限制 ${maxTokens}，开始自动迁移……`);
         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/plugin/AutoRefreshToolsPlugin.js

@@ -11,7 +11,7 @@ export class AutoRefreshToolsPlugin {
         const { agent } = ctx;
         if (!agent.caps)
             return;
-        agent.caps.refresh();
+        agent.caps.refresh({ silent: true });
         agent.tools = agent.caps.buildTools(agent.permissions ?? {}, {
             exclude: {
                 subagents: agent.definition.function?.name

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.0-alpha.3",
+  "version": "0.2.2",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",