@ai-zen/agents-sdk 0.9.3 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.10.0] - 2026-09-28
+
+### 🚀 New Features
+
+- **`load_mcp` 新增 `include_manifest` 开关（可选布尔，默认 `true`）** — 默认行为逐字不变（返回 `{ tools, resources }` 完整清单，tools 含完整 `inputSchema`）；显式传 `false` 时仅建立连接并返回摘要 `{ server, connected, tools: 数量, resources: 数量 }`，不返回任何工具/资源定义。用于「进程重启后连接已失效、但上文中已存在该清单」的场景：只重建连接，不重复向上下文灌入数十 KB 的工具定义，节省 token。完整清单仍留在 `McpConnectionManager` 内，`call_mcp_tool` / `read_mcp_resource` 行为不变；`server` 参数枚举、工具名表与 `DYNAMIC_TOOL_NAMES` 均未变动（前缀缓存结构不变）。失败路径与已连接路径的语义在两种模式下一致；`docs/sdk-design.md` §9 同步更新
+
+### 🛠 Optimized
+
+- **依赖 `@ai-zen/agents-core` 升至 `^4.2.0`** — 依赖声明保持 `workspace:^`，由 pnpm 在发布时展开为 `^4.2.0`。core 4.2.0 新增子 Agent 委派阻塞钩子 `onSubAgentStart` / `onSubAgentEnd`，并将原有事件 `sub-agent` 更名为 `sub-agent-start`（core 侧破坏性变更）；SDK 内部不监听该事件，源码无需适配。监听该事件的消费方需同步更名
+
+### ✅ Tests
+
+- `mcpTools.test.ts` 新增 4 个用例：静默 + 未连接、静默 + 已连接、显式 `true`、静默 + 连接失败；SDK 全量 **461 passed / 6 skipped**
+
+## [0.9.4] - 2026-09-20
+
+### 🔧 Fixed
+
+- **MCP `sse` transport 改为真正的 SSE 连接（`SSEClientTransport`）** — 此前 `http` 与 `sse` 合并处理，统一使用 `StreamableHTTPClientTransport`（Streamable HTTP：POST 发送消息 + 可选 SSE 流），使配置声明 `type: "sse"` 的旧版 HTTP+SSE 服务器（GET 建立 SSE 流、POST 到 endpoint 发送消息）实际运行在不匹配的协议栈上。现按 transport 拆分：`http` → `StreamableHTTPClientTransport`，`sse` → `SSEClientTransport`（均为官方 SDK 内置实现）。`headers` 仍经 `requestInit` 透传，由 SDK 统一应用于 SSE 建流（GET）与消息发送（POST）请求；缺少 `url` 时的报错行为保持不变。`McpServerConfig.transport` 注释与 `docs/sdk-design.md` §10/§11 同步更新
+
+### ✅ Tests
+
+- 针对真实 MCP 服务器（`packages/test-project/mcp-servers/sse-server.mjs`，旧版 HTTP+SSE 协议）验证通过：建立连接、工具发现（`echo` / `add`）、工具调用、断开重连；并确认运行时 transport 实例为 `SSEClientTransport`
+
 ## [0.9.3] - 2026-09-01
 
 ### 🔧 Fixed

package/README.md

@@ -19,7 +19,7 @@ Desktop ──┘                    │
 
 ```
 types        ← pure types, zero business dependencies (incl. ToolEnv)
-config       ← read/write config.json + migration + in-memory cache + atomic writes
+config       ← ConfigManager + constants: config.json read/write + directory setup + factory defaults
 crud         ← capability-entity CRUD (Agent definitions, etc.; conversations/drafts are persisted by each consumer)
 capabilities ← capability discovery & assembly (built-in + user + MCP + Skill + SubAgent)
 runtime      ← Provider + model factory + Agent assembly + MCP connection management + task migration + SdkCallbackTool base
@@ -37,7 +37,7 @@ Dependency direction: `plugin → runtime → capabilities → crud → config
 | **ToolEnv** | Tool environment `{ cwd, config }`; injected when the Provider instantiates built-in tools, serving as the base for relative path resolution and config reads |
 | **SdkCallbackTool** | Abstract base for built-in tools: `env` constructor injection + subclass `call()` + `resolve()` relative path resolution |
 | **SdkAgent** | Extends the Core Agent, carries SDK metadata, supports `use()` plugin registration |
-| **AgentPlugin** | Plugin interface (`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`) |
+| **AgentPlugin** | Plugin interface (`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`, `onInnerLoopsStart`, `onInnerLoopsEnd`, `onToolCall`, `onUnknownTool`, `onSubAgentStart`, `onSubAgentEnd`) |
 | **Endpoint** | API endpoint (baseUrl + apiKey) |
 | **Model** | Model config, bound to an Endpoint |
 | **SubAgent** | An Agent with a `function` field, callable by other Agents as a tool |
@@ -62,7 +62,7 @@ const provider = await Provider.create({
   cwd: "/path/to/workspace", // one working directory per Provider; parallel sessions don't interfere
   ...paths,
 });
-const agent = createAgent(provider, "my-agent");
+const agent = await createAgent(provider, "my-agent");
 const migrationService = new TaskMigrationService({ onMigrated }); // migrates via the agent's own model client
 agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
@@ -78,10 +78,9 @@ await agent.send("Hello");
 | `config` | ✅ Implemented — ConfigManager + factory defaults + one-shot bootstrap |
 | `crud` | ✅ Implemented — capability-entity CRUD for Agents, etc. (conversations/drafts persisted by each consumer) |
 | `capabilities` | ✅ Implemented — discovery + permission filtering + safe pre-filtering + enumeration disclosure |
-| `runtime` | ✅ Implemented — Provider, Capabilities, createAgent, MCP connection management, task migration |
+| `runtime` | ✅ Implemented — Provider, createAgent, MCP connection management, task migration |
 | `plugin` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ Implemented — SdkError + injectable Logger |
-| Tests | ✅ 452 passing, 51 files, all green (incl. real-API chat & viewImage e2e) |
 
 ## Built-in Tools
 
@@ -134,4 +133,3 @@ 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

@@ -18,7 +18,7 @@ Desktop ──┘                    │
 
 ```
 types        ← 纯类型，零业务依赖（含 ToolEnv 工具环境）
-config       ← 读写 config.json + 迁移 + 内存缓存 + 原子写入
+config       ← ConfigManager + constants：读写 config.json + 目录初始化 + 出厂默认
 crud         ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
 capabilities ← 能力发现与装配（内置 + 用户 + MCP + Skill + SubAgent）
 runtime      ← Provider + 模型工厂 + Agent 组装 + MCP 连接管理 + 任务迁移 + SdkCallbackTool 工具基类
@@ -36,7 +36,7 @@ shared       ← 日志、错误
 | **ToolEnv** | 工具环境 `{ cwd, config }`，Provider 实例化内置工具时注入，作为相对路径解析与配置读取的基准 |
 | **SdkCallbackTool** | 内置工具抽象基类：`env` 构造注入 + 子类实现 `call()` + `resolve()` 相对路径解析 |
 | **SdkAgent** | 继承 Core Agent，携带 SDK 元数据，支持 `use()` 插件注册 |
-| **AgentPlugin** | 插件接口（`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`） |
+| **AgentPlugin** | 插件接口（`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`, `onInnerLoopsStart`, `onInnerLoopsEnd`, `onToolCall`, `onUnknownTool`, `onSubAgentStart`, `onSubAgentEnd`） |
 | **Endpoint** | API 端点（baseUrl + apiKey） |
 | **Model** | 模型配置，绑定 Endpoint |
 | **SubAgent** | 有 `function` 字段的 Agent，可被其他 Agent 作为工具调用 |
@@ -61,7 +61,7 @@ const provider = await Provider.create({
   cwd: "/path/to/workspace", // 每个 Provider 一个工作目录，多会话并行互不干扰
   ...paths,
 });
-const agent = createAgent(provider, "my-agent");
+const agent = await createAgent(provider, "my-agent");
 const migrationService = new TaskMigrationService({ onMigrated }); // 迁移复用传入 agent 自身的模型调用
 agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
@@ -77,10 +77,9 @@ await agent.send("你好");
 | `config` | ✅ 已实现 — ConfigManager + 出厂默认配置 + 一键 bootstrap |
 | `crud` | ✅ 已实现 — Agent 等能力实体 CRUD（会话/草稿由各端自行持久化） |
 | `capabilities` | ✅ 已实现 — 发现 + 权限过滤 + 安全预过滤 + 枚举披露 |
-| `runtime` | ✅ 已实现 — Provider、Capabilities、createAgent、MCP 连接管理、任务迁移 |
+| `runtime` | ✅ 已实现 — Provider、createAgent、MCP 连接管理、任务迁移 |
 | `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
-| 测试 | ✅ 452 通过，51 个文件，全绿（含真实 API 聊天与 viewImage e2e） |
 
 ## 内置工具
 

package/dist/capabilities/implements/mcpTools.js

@@ -24,7 +24,7 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
     return new CallbackTool({
         function: {
             name: "load_mcp",
-            description: "连接到指定 MCP 服务器，获取其可用工具和资源列表。",
+            description: "连接到指定 MCP 服务器，获取其可用工具和资源列表。可用 include_manifest=false 仅建立连接、不返回清单（适用于上文中已有该清单的场景）。",
             parameters: {
                 type: "object",
                 properties: {
@@ -33,6 +33,11 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
                         description: serverIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
+                    include_manifest: {
+                        type: "boolean",
+                        description: "是否返回该服务器的完整能力清单（工具与资源）。可选，默认 true。若你的上文中已存在该清单（例如本会话早前加载过，而进程重启后连接已失效），可设为 false 仅建立连接、只返回摘要，以节省上下文 token",
+                        default: true,
+                    },
                 },
                 required: ["server"],
                 additionalProperties: false,
@@ -44,20 +49,35 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
             if (!config) {
                 return `❌ MCP 服务器 "${serverName}" 不存在`;
             }
+            // 披露开关：默认返回完整清单；显式传 false 时仅建立连接、只返回摘要
+            const includeManifest = input.include_manifest !== false;
+            // 获取清单：已连接 → 复用缓存（touch 续期）；未连接 → 建连并发现
+            let manifest;
             const existingManifest = mcpManager.getManifest(serverName);
             if (existingManifest && mcpManager.getState(serverName) === "connected") {
                 mcpManager.touch(serverName);
-                log.info(`[load_mcp] ${serverName}:\n${JSON.stringify(existingManifest, null, 2)}`);
-                return JSON.stringify({ tools: existingManifest.tools, resources: existingManifest.resources });
+                manifest = existingManifest;
             }
-            try {
-                const manifest = await mcpManager.connect(serverName, config);
-                log.info(`[load_mcp] ${serverName}:\n${JSON.stringify(manifest, null, 2)}`);
-                return JSON.stringify({ tools: manifest.tools, resources: manifest.resources });
+            else {
+                try {
+                    manifest = await mcpManager.connect(serverName, config);
+                }
+                catch (error) {
+                    return `无法连接到 "${serverName}": ${error?.message ?? error}`;
+                }
             }
-            catch (error) {
-                return `无法连接到 "${serverName}": ${error?.message ?? error}`;
+            // 静默模式：只回吐摘要（清单仍留在管理器内，供 call_mcp_tool 使用）
+            if (!includeManifest) {
+                log.info(`[load_mcp] ${serverName}: 已连接（未披露清单：工具 ${manifest.tools.length} 个，资源 ${manifest.resources.length} 个）`);
+                return JSON.stringify({
+                    server: serverName,
+                    connected: true,
+                    tools: manifest.tools.length,
+                    resources: manifest.resources.length,
+                });
             }
+            log.info(`[load_mcp] ${serverName}:\n${JSON.stringify(manifest, null, 2)}`);
+            return JSON.stringify({ tools: manifest.tools, resources: manifest.resources });
         },
     });
 }

package/dist/runtime/McpConnectionManager.js

@@ -1,4 +1,5 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { getLogger } from "../shared/logger.js";
@@ -197,15 +198,24 @@ export class McpConnectionManager {
                 env: config.env,
             });
         }
-        // http 和 sse 都使用 StreamableHTTPClientTransport
-        if (config.transport === "http" || config.transport === "sse") {
+        // http 使用 Streamable HTTP 传输（POST + 可选 SSE 流）
+        if (config.transport === "http") {
             if (!config.url) {
-                throw new Error(`MCP ${config.transport} server 缺少 url`);
+                throw new Error(`MCP http server 缺少 url`);
             }
             return new StreamableHTTPClientTransport(new URL(config.url), {
                 requestInit: config.headers ? { headers: config.headers } : undefined,
             });
         }
+        // sse 使用旧版 HTTP+SSE 传输（GET 建立 SSE 流，POST 发送消息）
+        if (config.transport === "sse") {
+            if (!config.url) {
+                throw new Error(`MCP sse server 缺少 url`);
+            }
+            return new SSEClientTransport(new URL(config.url), {
+                requestInit: config.headers ? { headers: config.headers } : undefined,
+            });
+        }
         throw new Error(`不支持的 MCP transport 类型: ${config.transport}`);
     }
     // ---- 断开 ----

package/dist/types/index.d.ts

@@ -111,8 +111,9 @@ export interface McpServerConfig {
 /**
  * MCP 底层传输适配器（已废弃）。
  *
- * 现在由 @modelcontextprotocol/sdk 内置的 StdioClientTransport 和
- * StreamableHTTPClientTransport 实现，不再需要外部注入。
+ * 现在由 @modelcontextprotocol/sdk 内置的 StdioClientTransport、
+ * StreamableHTTPClientTransport（http）和 SSEClientTransport（sse）实现，
+ * 不再需要外部注入。
  *
  * McpConnectionManager 内部使用官方 SDK 的 Transport 接口，
  * 上层无需关心 transport 实现细节。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
   "author": "LZQCN",
   "license": "MIT",
   "dependencies": {
-    "@ai-zen/agents-core": "^4.1.0",
+    "@ai-zen/agents-core": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
     "openai": "^7.5.0"