@ai-zen/agents-sdk 0.2.0-alpha.3 → 0.2.1

package/dist/capabilities/Capabilities.d.ts

@@ -67,5 +67,7 @@ export declare class Capabilities {
     /**
      * 重新执行全局发现（重新扫描文件系统）。
      */
-    refresh(): void;
+    refresh(options?: {
+        silent?: boolean;
+    }): void;
 }

package/dist/capabilities/Capabilities.js

@@ -138,12 +138,13 @@ export class Capabilities {
     /**
      * 重新执行全局发现（重新扫描文件系统）。
      */
-    refresh() {
+    refresh(options) {
+        const silent = options?.silent ?? false;
         const provider = this.provider;
         this.builtinInstances = discoverBuiltinTools(provider.config);
-        this.userInstances = discoverUserTools(provider.toolsPaths);
+        this.userInstances = discoverUserTools(provider.toolsPaths, { silent });
         this.subagentDefs = discoverSubAgents(provider.subAgentsPaths);
-        this.skills = discoverSkills(provider.skillsPaths);
+        this.skills = discoverSkills(provider.skillsPaths, { silent });
         this.mcps = discoverMcpServers(provider.mcpPaths);
     }
 }

package/dist/capabilities/discovery/skills.d.ts

@@ -30,13 +30,17 @@ export interface SkillInfo {
  * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
  * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
  */
-export declare function discoverSkills(paths: string[]): SkillInfo[];
+export declare function discoverSkills(paths: string[], options?: {
+    silent?: boolean;
+}): SkillInfo[];
 /**
  * 读取单个 Skill 的完整内容与元数据。
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
  * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
  */
-export declare function readSkill(skillDirs: string[], skillId: string): SkillInfo | null;
+export declare function readSkill(skillDirs: string[], skillId: string, options?: {
+    silent?: boolean;
+}): SkillInfo | null;
 /** @internal */
 export declare function parseFrontmatter(content: string): Frontmatter;
 /** @internal */

package/dist/capabilities/discovery/skills.js

@@ -8,7 +8,8 @@ const log = createLogger();
  * 按优先级从高到低传入路径列表，同名 skill 靠前的路径优先（先到先得）。
  * 解析 YAML frontmatter 中的 name 和 description，同时校验合规。
  */
-export function discoverSkills(paths) {
+export function discoverSkills(paths, options) {
+    const silent = options?.silent ?? false;
     const seen = new Set();
     const items = [];
     for (const dir of paths) {
@@ -29,7 +30,7 @@ export function discoverSkills(paths) {
             const skillMdPath = join(dir, entry.name, "SKILL.md");
             if (!existsSync(skillMdPath))
                 continue;
-            const skill = readSkillFromPath(entry.name, skillMdPath);
+            const skill = readSkillFromPath(entry.name, skillMdPath, silent);
             if (skill) {
                 seen.add(entry.name);
                 items.push(skill);
@@ -44,26 +45,29 @@ export function discoverSkills(paths) {
  * 按优先级从高到低传入路径列表，靠前的路径优先（先到先得）。
  * 返回 null 如果 skill 在所有目录中都不存在或 SKILL.md 不可读。
  */
-export function readSkill(skillDirs, skillId) {
+export function readSkill(skillDirs, skillId, options) {
+    const silent = options?.silent ?? false;
     for (const dir of skillDirs) {
         const candidate = join(dir, skillId, "SKILL.md");
         if (existsSync(candidate)) {
-            return readSkillFromPath(skillId, candidate);
+            return readSkillFromPath(skillId, candidate, silent);
         }
     }
     return null;
 }
 // ---- 内部 ----
-function readSkillFromPath(skillId, skillMdPath) {
+function readSkillFromPath(skillId, skillMdPath, silent) {
     try {
         const content = readFileSync(skillMdPath, "utf-8");
         const fm = parseFrontmatter(content);
         if (!fm.name)
             return null;
         // 规范合规校验
-        const errors = validateSkill(skillId, fm);
-        for (const err of errors) {
-            log.warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
+        if (!silent) {
+            const errors = validateSkill(skillId, fm);
+            for (const err of errors) {
+                log.warn(`[skills] ${err.skillId}: ${err.field} — ${err.message}`);
+            }
         }
         return {
             id: skillId,

package/dist/capabilities/discovery/usertools.d.ts

@@ -10,4 +10,6 @@ import { Tool } from "@ai-zen/agents-core";
  * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
  * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
  */
-export declare function discoverUserTools(paths: string[]): Tool[];
+export declare function discoverUserTools(paths: string[], options?: {
+    silent?: boolean;
+}): Tool[];

package/dist/capabilities/discovery/usertools.js

@@ -13,7 +13,8 @@ import { Tool, CallbackTool } from "@ai-zen/agents-core";
  * 3. 支持直接导出 { function, exec } 格式的对象（自动适配为 Tool）
  * 4. 支持导出 CallbackTool 兼容的 { function, callback } 格式
  */
-export function discoverUserTools(paths) {
+export function discoverUserTools(paths, options) {
+    const silent = options?.silent ?? false;
     const seen = new Set();
     const tools = [];
     for (const dir of paths) {
@@ -28,7 +29,7 @@ export function discoverUserTools(paths) {
                 if (!seen.has(name)) {
                     seen.add(name);
                     try {
-                        const tool = loadToolFile(join(dir, name + ".js"));
+                        const tool = loadToolFile(join(dir, name + ".js"), silent);
                         if (tool) {
                             tools.push(tool);
                         }
@@ -51,7 +52,7 @@ export function discoverUserTools(paths) {
  * 使用 vm.compileFunction 创建沙箱执行环境，避免污染全局作用域。
  * 注入有限的全局 API（console, setTimeout 等），不暴露 process/require。
  */
-function loadToolFile(filepath) {
+function loadToolFile(filepath, silent) {
     const code = readFileSync(filepath, "utf-8");
     // 构造沙箱上下文
     const sandbox = {
@@ -83,17 +84,19 @@ function loadToolFile(filepath) {
             return null;
         }
         // 适配不同导出格式
-        return normalizeToolExport(exported, filepath);
+        return normalizeToolExport(exported, filepath, silent);
     }
     catch (err) {
-        console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+        if (!silent) {
+            console.error(`[usertools] 加载工具文件失败: ${filepath} — ${err?.message ?? err}`);
+        }
         return null;
     }
 }
 /**
  * 统一各种导出格式为 Tool 实例。
  */
-function normalizeToolExport(exported, filepath) {
+function normalizeToolExport(exported, filepath, silent) {
     // 情况 1：直接是 Tool 实例
     if (exported instanceof Tool) {
         return exported;
@@ -114,7 +117,9 @@ function normalizeToolExport(exported, filepath) {
             callback: target.callback,
         });
     }
-    console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+    if (!silent) {
+        console.error(`[usertools] 无法识别的工具格式: ${filepath}`);
+    }
     return null;
 }
 /**

package/dist/capabilities/implements/builtin/execAsync.js

@@ -94,7 +94,7 @@ export const execAsyncTool = new CallbackTool({
                 resolve(JSON.stringify({
                     success: false,
                     pid: null,
-                    error: `启动失败: ${err.message}`,
+                    message: `启动失败: ${err.message}`,
                 }));
             });
             child.on("spawn", () => {

package/dist/capabilities/implements/skillTools.js

@@ -12,6 +12,11 @@ const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";
 export function createLoadSkillTool(skillDirs, filteredSkills) {
     const ids = filteredSkills.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 Skill", EMPTY_HINT);
+    // 拼接各 skill 的描述供 LLM 参考
+    const skillDescriptions = filteredSkills
+        .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
+        .join("\n");
+    const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
     return new CallbackTool({
         function: {
             name: "load_skill",
@@ -21,7 +26,7 @@ export function createLoadSkillTool(skillDirs, filteredSkills) {
                 properties: {
                     skill_id: {
                         type: "string",
-                        description: param.description,
+                        description: skillIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
                 },
@@ -57,6 +62,11 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
     const subAgentSkills = filteredSkills.filter((s) => s.subAgent);
     const ids = subAgentSkills.map((s) => s.id);
     const param = createDisclosureParam(ids, "选择一个 Skill（支持子 Agent）", EMPTY_HINT);
+    // 拼接各 skill 的描述供 LLM 参考
+    const skillDescriptions = subAgentSkills
+        .map((s) => `  - ${s.id}: ${s.description || "无描述"}`)
+        .join("\n");
+    const skillIdDescription = `${param.description}\n\n各 Skill 说明：\n${skillDescriptions || "  无可用 Skill"}`;
     return new CallbackTool({
         function: {
             name: "call_skill_sub_agent",
@@ -66,7 +76,7 @@ export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
                 properties: {
                     skill_id: {
                         type: "string",
-                        description: param.description,
+                        description: skillIdDescription,
                         ...(param.enum ? { enum: param.enum } : {}),
                     },
                     task: {

package/dist/plugin/AutoRefreshToolsPlugin.js

@@ -11,7 +11,7 @@ export class AutoRefreshToolsPlugin {
         const { agent } = ctx;
         if (!agent.caps)
             return;
-        agent.caps.refresh();
+        agent.caps.refresh({ silent: true });
         agent.tools = agent.caps.buildTools(agent.permissions ?? {}, {
             exclude: {
                 subagents: agent.definition.function?.name

package/package.json

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