@ai-zen/agents-sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

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.10.0",
+  "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.2.0",
+    "@ai-zen/agents-core": "^4.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
     "openai": "^7.5.0"