@ai-zen/agents-sdk 0.9.4 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.11.0] - 2026-09-28
+
+### 💥 Breaking Changes
+
+- **`createCallSkillSubAgentTool` 移除第三参 `provider`** — Skill 子 Agent 不再经 `provider.buildTools(parent.definition, …)` 重新解析工具集，改为**直接沿用父 Agent 的工具集**（`ctx.agent.tools`），仅剔除 `call_skill_sub_agent` 自身：Skill 子 Agent 作为一次性对话分身，沿用调用者的能力而不再走第二遍权限过滤，同时避免 skill 链式自递归。传入 `Provider` 的调用方需删除该实参
+
+### 🚀 New Features
+
+- **Skill 子 Agent 纳入统一委派边界** — `call_skill_sub_agent` 由 `AgentToolLazy` 承载（原为就地实现的 `CallbackTool`），因此与常规 SubAgent 工具共享同一套 `onSubAgentStart` / `onSubAgentEnd` 插件钩子与 `sub-agent-start` / `sub-agent-end` 事件。将护栏装配到 `ctx.subAgent` 的消费方（如上下文护栏）与渲染子 Agent 流式输出的消费方（如 CLI），自此均覆盖该路径
+
+### 🛠 Optimized
+
+- **Skill 子 Agent 的构建收敛到 `buildAgent`** — 子 Agent 的初始消息（`System(SKILL.md 内容)` + `User(task)`）改由 `buildAgent` 决定（依托 core 4.3.0 的 `messages` 可选），原先手写的 abort 联动与返回值处理一并删除，交由工具基类统一实现
+- **校验失败改为抛错** — `skill_id` 不存在、或 Skill 未声明 `sub-agent: true` 时抛出错误（原为返回提示文本）；正常路径由 `skill_id` 枚举限定，不触发
+- **依赖 `@ai-zen/agents-core` 升至 `^4.3.0`** — 依赖声明保持 `workspace:^`，由 pnpm 在发布时展开为 `^4.3.0`。core 4.3.0 使 `AgentToolLazy.messages` 变为可选
+
+### ✅ Tests
+
+- `skillTools.test.ts` 中 `createCallSkillSubAgentTool` 用例重写为围绕 `AgentToolLazy`：工具契约不变、未知 Skill 抛错、非子 Agent Skill 抛错、委派边界（`onSubAgentStart` 与 `sub-agent-start` 分发、子 Agent 沿用父工具集且剔除自身、初始消息取自 SKILL.md 与 `task`）；SDK 全量 **463 passed / 6 skipped**
+
+## [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

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

@@ -1,6 +1,5 @@
-import { CallbackTool } from "@ai-zen/agents-core";
+import { CallbackTool, AgentToolLazy } from "@ai-zen/agents-core";
 import type { SkillInfo } from "../discovery/skills.js";
-import type { Provider } from "../../runtime/Provider.js";
 /**
  * 创建 load_skill 工具。
  * 枚举所有允许的 skill（不限是否支持子 Agent），由 filteredSkills 提供完整信息。
@@ -10,6 +9,9 @@ export declare function createLoadSkillTool(skillDirs: string[], filteredSkills:
  * 创建 call_skill_sub_agent 工具。
  * 只展示 subAgent: true 的 Skill，枚举中自动排除不支持子 Agent 模式的 skill。
  *
- * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
+ * 工具由 AgentToolLazy 承载：子 Agent 在 exec 时构建，从而复用统一的委派边界
+ * （onSubAgentStart / onSubAgentEnd 钩子与 sub-agent-start / sub-agent-end 事件）。
+ * 子 Agent 沿用父 Agent 的工具能力（不做权限过滤），但剔除 call_skill_sub_agent 自身，
+ * 避免 skill 链式自递归。
  */
-export declare function createCallSkillSubAgentTool(skillDirs: string[], filteredSkills: SkillInfo[], provider?: Provider): CallbackTool;
+export declare function createCallSkillSubAgentTool(skillDirs: string[], filteredSkills: SkillInfo[]): AgentToolLazy;

package/dist/capabilities/implements/skillTools.js

@@ -1,5 +1,4 @@
-import { CallbackTool, Agent, Message } from "@ai-zen/agents-core";
-import { SdkAgent } from "../../runtime/SdkAgent.js";
+import { CallbackTool, Agent, AgentToolLazy, Message } from "@ai-zen/agents-core";
 import { createDisclosureParam } from "../disclosure.js";
 import { readSkill } from "../discovery/skills.js";
 import { getLogger } from "../../shared/logger.js";
@@ -70,9 +69,12 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
  * 创建 call_skill_sub_agent 工具。
  * 只展示 subAgent: true 的 Skill，枚举中自动排除不支持子 Agent 模式的 skill。
  *
- * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
+ * 工具由 AgentToolLazy 承载：子 Agent 在 exec 时构建，从而复用统一的委派边界
+ * （onSubAgentStart / onSubAgentEnd 钩子与 sub-agent-start / sub-agent-end 事件）。
+ * 子 Agent 沿用父 Agent 的工具能力（不做权限过滤），但剔除 call_skill_sub_agent 自身，
+ * 避免 skill 链式自递归。
  */
-export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider) {
+export function createCallSkillSubAgentTool(skillDirs, filteredSkills) {
     // 只保留支持子 Agent 模式的 skill
     const subAgentSkills = filteredSkills.filter((s) => s.subAgent);
     const ids = subAgentSkills.map((s) => s.id);
@@ -82,7 +84,7 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider)
         .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
         .join("\n");
     const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
-    return new CallbackTool({
+    return new AgentToolLazy({
         function: {
             name: "call_skill_sub_agent",
             description: "将任务委派给指定的 Skill 子 Agent，由其独立完成并返回结果。",
@@ -103,46 +105,28 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, provider)
                 additionalProperties: false,
             },
         },
-        async callback(input, ctx) {
-            const skillId = input.skill_id;
-            const task = input.task;
+        // 初始消息依赖运行时参数（skill_id → SKILL.md 内容），故不传 messages 模板，
+        // 由 buildAgent 读取 SKILL.md 后自行决定；abort 联动与委派边界由 AgentToolLazy 统一处理
+        buildAgent: async (parsedArgs, ctx) => {
+            const skillId = parsedArgs.skill_id;
+            const task = parsedArgs.task;
             const skill = await readSkill(skillDirs, skillId);
             if (!skill) {
-                return `❌ Skill "${skillId}" 不存在，请确认名称是否正确`;
+                throw new Error(`❌ Skill "${skillId}" 不存在，请确认名称是否正确`);
             }
             if (!skill.subAgent) {
-                return `Skill "${skillId}" 不支持子 Agent 模式，请使用 load_skill 加载指导后自行处理`;
+                throw new Error(`Skill "${skillId}" 不支持子 Agent 模式，请使用 load_skill 加载指导后自行处理`);
             }
-            // 临时 Skill 子 Agent 复用父 Agent 定义（权限 + 模型），排除当前 Skill 防自调用
+            // 沿用父 Agent 的工具能力（不做权限过滤），剔除自身以防自递归
             const parentAgent = ctx.agent;
-            const skillTools = provider && parentAgent instanceof SdkAgent
-                ? provider.buildTools(parentAgent.definition, {
-                    exclude: { skills: [skillId] },
-                })
-                : [];
-            const subAgent = new Agent({
+            const tools = parentAgent.tools.filter((t) => t.function.name !== "call_skill_sub_agent");
+            return new Agent({
                 client: parentAgent.client,
                 model: parentAgent.model,
                 modelConfig: parentAgent.modelConfig,
-                messages: [
-                    Message.System(skill.content),
-                    Message.User(task),
-                ],
-                tools: skillTools,
+                messages: [Message.System(skill.content), Message.User(task)],
+                tools,
             });
-            // 子 Agent 中断联动：外层 abort → subAgent.abort()
-            const onAbort = () => subAgent.abort();
-            if (ctx.signal) {
-                ctx.signal.addEventListener("abort", onAbort, { once: true });
-            }
-            try {
-                await subAgent.run();
-            }
-            finally {
-                ctx.signal?.removeEventListener("abort", onAbort);
-            }
-            const lastMsg = subAgent.messages.at(-1);
-            return typeof lastMsg?.content === "string" ? lastMsg.content : "";
         },
     });
 }

package/dist/runtime/Provider.js

@@ -170,7 +170,7 @@ export class Provider {
         // call_skill_sub_agent：只要有支持子 Agent 的 skill 就注册
         const hasSubAgentSkills = filteredSkills.some((s) => s.subAgent);
         if (allowedToolNames.has("call_skill_sub_agent") && hasSubAgentSkills) {
-            result.push(createCallSkillSubAgentTool(this.skillsPaths, filteredSkills, this));
+            result.push(createCallSkillSubAgentTool(this.skillsPaths, filteredSkills));
         }
         const mcpManager = this.mcpManager;
         if (allowedToolNames.has("load_mcp") && mcpManager && filteredMcps.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.9.4",
+  "version": "0.11.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.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
     "openai": "^7.5.0"