@ai-zen/agents-sdk 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.0] - 2026-07-29
+
+### 💥 破坏性变更
+
+- **`load_mcp` 返回值从纯文本改为结构化 JSON** — 现在返回 `{ tools, resources }`，其中 tools 包含完整的 `inputSchema`（参数 JSON Schema），resources 包含 `uri`、`name`、`description`、`mimeType`。LLM 可获得精确的参数结构信息，不再需要靠描述文字猜测参数格式
+- **`load_mcp` 不再返回 `prompts` 字段** — prompts 属于 UI 层用途，不对 Agent 暴露
+- **`createLogger()` 替换为全局单例 `getLogger()` / `setLogger()`** — 日志不再支持多例，SDK 内部所有模块统一通过 `getLogger()` 获取同一实例
+- **`index.ts` 导出变更** — `createLogger` → `getLogger` / `setLogger`
+
+### 🎯 优化
+
+- **`load_mcp` 连接成功后在日志中打印完整 manifest** — 包含 tools、resources、prompts 的完整 JSON，便于调试排查
+- **SDK 内部日志统一** — `mcps.ts`、`skills.ts`、`usertools.ts`、`McpConnectionManager.ts` 中的 `console.warn`/`console.error` 全部改为 `getLogger().warn`/`getLogger().error`
+
 ## [0.3.4] - 2026-07-27
 
 ### 🎯 优化

package/dist/capabilities/discovery/mcp.js

@@ -1,4 +1,5 @@
 import { promises as fs } from "node:fs";
+import { getLogger } from "../../shared/logger.js";
 /**
  * 归一化原始 MCP server 配置为内部 McpServerConfig。
  * 处理业界标准中的字段别名差异。
@@ -80,7 +81,7 @@ export async function discoverMcpServers(paths) {
             }
         }
         catch (err) {
-            console.warn(`[sdk] 解析 MCP 配置失败: ${path}`, err);
+            getLogger().warn(`[sdk] 解析 MCP 配置失败: ${path} — ${err?.message ?? err}`);
         }
     }
     return items;

package/dist/capabilities/discovery/skills.js

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
-import { createLogger } from "../../shared/logger.js";
-const log = createLogger();
+import { getLogger } from "../../shared/logger.js";
+const log = getLogger();
 // ---- 发现（返回完整 SkillInfo，不再丢失 subAgent 等信息）----
 /**
  * 扫描多个目录中发现的所有 Skill（含 SKILL.md 的子目录）。

package/dist/capabilities/discovery/usertools.js

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { Tool, CallbackTool } from "@ai-zen/agents-core";
+import { getLogger } from "../../shared/logger.js";
 /**
  * 扫描多个 tools/ 目录，发现所有 .js / .mjs 文件，动态加载为 Tool 实例。
  * 使用原生 dynamic import() 加载（在 "type": "module" 下 .js 也是 ESM），
@@ -73,7 +74,7 @@ async function loadToolFile(filepath, silent) {
     }
     catch (err) {
         if (!silent) {
-            console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+            getLogger().error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
         }
         return null;
     }
@@ -109,7 +110,7 @@ function normalizeToolExport(exported, filepath, silent) {
         });
     }
     if (!silent) {
-        console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+        getLogger().error(`[usertools] 无法识别的工具格式: ${filepath}`);
     }
     return null;
 }

package/dist/capabilities/implements/mcpTools.js

@@ -1,6 +1,8 @@
 import { CallbackTool } from "@ai-zen/agents-core";
 import { createDisclosureParam } from "../disclosure.js";
+import { getLogger } from "../../shared/logger.js";
 const EMPTY_HINT = "（当前没有可用的 MCP 服务器，请联系用户添加）";
+const log = getLogger();
 /**
  * 创建 load_mcp 工具。
  * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导，
@@ -40,13 +42,13 @@ export function createLoadMcpTool(mcpManager, filteredMcps) {
             const existingManifest = mcpManager.getManifest(serverName);
             if (existingManifest && mcpManager.getState(serverName) === "connected") {
                 mcpManager.touch(serverName);
-                const toolList = existingManifest.tools.map((t) => `- ${t.name}: ${t.description}`).join("\n");
-                return `✅ MCP 服务器 "${serverName}" 已连接 (${existingManifest.tools.length} 个工具):\n${toolList}`;
+                log.info(`[load_mcp] ${serverName}:\n${JSON.stringify(existingManifest, null, 2)}`);
+                return JSON.stringify({ tools: existingManifest.tools, resources: existingManifest.resources });
             }
             try {
                 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}`;
+                log.info(`[load_mcp] ${serverName}:\n${JSON.stringify(manifest, null, 2)}`);
+                return JSON.stringify({ tools: manifest.tools, resources: manifest.resources });
             }
             catch (error) {
                 return `无法连接到 "${serverName}": ${error?.message ?? error}`;

package/dist/capabilities/implements/skillTools.js

@@ -2,9 +2,9 @@ import { CallbackTool, Agent, Message } from "@ai-zen/agents-core";
 import { SdkAgent } from "../../runtime/SdkAgent.js";
 import { createDisclosureParam } from "../disclosure.js";
 import { readSkill } from "../discovery/skills.js";
-import { createLogger } from "../../shared/logger.js";
+import { getLogger } from "../../shared/logger.js";
 import { promises as fs } from "node:fs";
-const log = createLogger();
+const log = getLogger();
 const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";
 /**
  * 创建 load_skill 工具。

package/dist/index.d.ts

@@ -36,6 +36,6 @@ export { sleepTool } from "./capabilities/implements/builtin/sleep.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities/implements/skillTools.js";
 export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./capabilities/implements/mcpTools.js";
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";
-export { createLogger } from "./shared/logger.js";
+export { getLogger, setLogger } from "./shared/logger.js";
 export type { Logger, LogFunctions } from "./shared/logger.js";
 export { SdkError } from "./shared/errors.js";

package/dist/index.js

@@ -34,5 +34,5 @@ export { createLoadSkillTool, createCallSkillSubAgentTool } from "./capabilities
 export { createLoadMcpTool, createCallMcpTool, createReadMcpResourceTool } from "./capabilities/implements/mcpTools.js";
 export { createSubAgentTool } from "./capabilities/implements/subAgentTools.js";
 // 共享
-export { createLogger } from "./shared/logger.js";
+export { getLogger, setLogger } from "./shared/logger.js";
 export { SdkError } from "./shared/errors.js";

package/dist/plugin/AutoDraftPlugin.js

@@ -1,9 +1,9 @@
 import { DraftRepository } from "../crud/DraftRepository.js";
-import { createLogger } from "../shared/logger.js";
+import { getLogger } from "../shared/logger.js";
 import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import dayjs from "dayjs";
-const log = createLogger();
+const log = getLogger();
 const CURRENT_DRAFT = "_current.json";
 const EXPIRE_DAYS = 7;
 /**

package/dist/plugin/AutoMigratePlugin.js

@@ -1,7 +1,7 @@
 import { AgentNS } from "@ai-zen/agents-core";
 import { TaskMigrationService } from "../runtime/TaskMigrationService.js";
-import { createLogger } from "../shared/logger.js";
-const log = createLogger();
+import { getLogger } from "../shared/logger.js";
+const log = getLogger();
 /**
  * 自动迁移插件。
  *

package/dist/runtime/McpConnectionManager.js

@@ -1,6 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { getLogger } from "../shared/logger.js";
 const DEFAULT_IDLE_TIMEOUT = {
     stdio: 30 * 60 * 1000,
     http: 5 * 60 * 1000,
@@ -139,7 +140,7 @@ export class McpConnectionManager {
                 }));
             }
             catch (err) {
-                console.error(`[McpConnectionManager] 获取 "${name}" 工具列表失败:`, err);
+                getLogger().error(`[McpConnectionManager] 获取 "${name}" 工具列表失败: ${err?.message ?? err}`);
             }
         }
         if (serverCaps?.resources) {
@@ -153,7 +154,7 @@ export class McpConnectionManager {
                 }));
             }
             catch (err) {
-                console.error(`[McpConnectionManager] 获取 "${name}" 资源列表失败:`, err);
+                getLogger().error(`[McpConnectionManager] 获取 "${name}" 资源列表失败: ${err?.message ?? err}`);
             }
         }
         if (serverCaps?.prompts) {
@@ -165,7 +166,7 @@ export class McpConnectionManager {
                 }));
             }
             catch (err) {
-                console.error(`[McpConnectionManager] 获取 "${name}" 提示列表失败:`, err);
+                getLogger().error(`[McpConnectionManager] 获取 "${name}" 提示列表失败: ${err?.message ?? err}`);
             }
         }
         const entry = this.servers.get(name) ?? { state: "connecting" };

package/dist/shared/logger.d.ts

@@ -5,6 +5,10 @@ export interface LogFunctions {
 }
 export type Logger = LogFunctions;
 /**
- * 创建可注入的 Logger，默认使用 console。
+ * 获取全局 Logger 实例。
  */
-export declare function createLogger(log?: Partial<LogFunctions>): Logger;
+export declare function getLogger(): Logger;
+/**
+ * 设置全局 Logger 实例，替换默认的 console 输出。
+ */
+export declare function setLogger(log: Logger): void;

package/dist/shared/logger.js

@@ -1,10 +1,17 @@
+let currentLogger = {
+    info: console.log,
+    warn: console.warn,
+    error: console.error,
+};
 /**
- * 创建可注入的 Logger，默认使用 console。
+ * 获取全局 Logger 实例。
  */
-export function createLogger(log) {
-    return {
-        info: log?.info ?? console.log,
-        warn: log?.warn ?? console.warn,
-        error: log?.error ?? console.error,
-    };
+export function getLogger() {
+    return currentLogger;
+}
+/**
+ * 设置全局 Logger 实例，替换默认的 console 输出。
+ */
+export function setLogger(log) {
+    currentLogger = log;
 }

package/package.json

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