@ai-zen/agents-sdk 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.6] - 2026-07-20
+
+### 🔧 修复
+
+- **默认 SubAgent 函数名和描述不足以让 LLM 识别为子 Agent** — `function.name` 从 `general_assistant` 改为 `sub_agent_default`，`function.description` 重写为详细描述，明确子 Agent 身份和能力边界。参数名 `query` → `task` 与设计规范统一，system prompt 明确角色定位
+- **`DEFAULT_SUBAGENT_ID` 从 `general-assistant` 改为 `sub-agent-default`** — 文件名与函数名对应，便于识别
+
 ## [0.2.5] - 2026-07-20
 
 ### 🔧 修复

package/dist/config/constants.d.ts

@@ -4,7 +4,7 @@ export declare const DEFAULT_AGENT_ID = "default";
 /** 默认 Agent 定义（不含时间戳） */
 export declare const DEFAULT_AGENT_DEFINITION: Omit<AgentDefinition, "createdAt" | "updatedAt">;
 /** 默认 SubAgent ID */
-export declare const DEFAULT_SUBAGENT_ID = "general-assistant";
+export declare const DEFAULT_SUBAGENT_ID = "sub-agent-default";
 /** 默认 SubAgent 定义（不含时间戳） */
 export declare const DEFAULT_SUBAGENT_DEFINITION: Omit<AgentDefinition, "createdAt" | "updatedAt">;
 /** SDK 出厂默认 AppConfig。CLI/Desktop 首次初始化时使用。 */

package/dist/config/constants.js

@@ -26,7 +26,7 @@ export const DEFAULT_AGENT_DEFINITION = {
 // 默认 SubAgent
 // ---------------------------------------------------------------------------
 /** 默认 SubAgent ID */
-export const DEFAULT_SUBAGENT_ID = "general-assistant";
+export const DEFAULT_SUBAGENT_ID = "sub-agent-default";
 /** 默认 SubAgent 定义（不含时间戳） */
 export const DEFAULT_SUBAGENT_DEFINITION = {
     id: DEFAULT_SUBAGENT_ID,
@@ -35,9 +35,9 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     messages: [
         {
             role: AgentNS.Role.System,
-            content: "你是一个通用助手，擅长独立完成各类任务。请根据给定的任务描述，认真分析并完成任务。完成任务后直接返回结果，不要解释你的思考过程。",
+            content: "你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。",
         },
-        { role: AgentNS.Role.User, content: "{{query}}" },
+        { role: AgentNS.Role.User, content: "{{task}}" },
     ],
     permissions: {
         tools: { allow: ["*"] },
@@ -46,14 +46,14 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
         subagents: { deny: ["*"] },
     },
     function: {
-        name: "general_assistant",
-        description: "通用助手，可独立完成各类任务",
+        name: "sub_agent_default",
+        description: "通用子 Agent，可独立完成各类任务。将任务委派给它后，它会自主调用自身工具（文件读写、代码执行、搜索等）来完成任务并返回结果。适合处理需要多步骤执行、工具调用的复杂任务。",
         parameters: {
             type: "object",
             properties: {
-                query: { type: "string", description: "任务描述" },
+                task: { type: "string", description: "任务描述" },
             },
-            required: ["query"],
+            required: ["task"],
             additionalProperties: false,
         },
     },

package/dist/runtime/createAgent.js

@@ -29,7 +29,7 @@ export function createAgent(provider, agentId) {
                 : undefined,
         },
     });
-    return new SdkAgent({
+    const agent = new SdkAgent({
         provider,
         definition,
         model,
@@ -38,4 +38,18 @@ export function createAgent(provider, agentId) {
         permissions: definition.permissions,
         caps,
     });
+    // 设置 onUnknownTool 钩子：当 LLM 调用不存在的工具时，给出智能提示
+    agent.onUnknownTool = (ctx) => {
+        const toolName = ctx.toolCall.function?.name ?? "未知";
+        const hasMcpConfig = provider.mcpPaths.length > 0;
+        const hasCallMcpTool = tools.some((t) => t.function.name === "call_mcp_tool");
+        if (hasMcpConfig && !hasCallMcpTool) {
+            return `工具 "${toolName}" 不存在。当前有 MCP 服务器配置，但 call_mcp_tool 权限已被禁用，如需使用 MCP 工具请调整权限。`;
+        }
+        if (hasMcpConfig && hasCallMcpTool) {
+            return `工具 "${toolName}" 不存在。如果要调用 MCP 工具，请使用 call_mcp_tool。`;
+        }
+        return `工具 "${toolName}" 不存在。`;
+    };
+    return agent;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
-    "@ai-zen/agents-core": "3.0.0-alpha.2"
+    "@ai-zen/agents-core": "3.0.0-alpha.4"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",