@ai-zen/agents-sdk 0.2.0-alpha.2

package/dist/capabilities/implements/mcpTools.js

@@ -0,0 +1,147 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+import { createDisclosureParam } from "../disclosure.js";
+const EMPTY_HINT = "（当前没有可用的 MCP 服务器，请联系用户添加）";
+/**
+ * 创建 load_mcp 工具。
+ * server 枚举由 filteredMcps （完整 McpServerConfig[]）自动推导。
+ */
+export function createLoadMcpTool(mcpManager, mcpConfigs, filteredMcps) {
+    const ids = filteredMcps.map((s) => s.id);
+    const param = createDisclosureParam(ids, "选择一个 MCP 服务器", EMPTY_HINT);
+    return new CallbackTool({
+        function: {
+            name: "load_mcp",
+            description: "连接到指定 MCP 服务器，获取其可用工具和资源列表。",
+            parameters: {
+                type: "object",
+                properties: {
+                    server: {
+                        type: "string",
+                        description: param.description,
+                        ...(param.enum ? { enum: param.enum } : {}),
+                    },
+                },
+                required: ["server"],
+                additionalProperties: false,
+            },
+        },
+        callback: async (input) => {
+            const serverName = input.server;
+            const serverConfig = mcpConfigs.get(serverName);
+            if (!serverConfig) {
+                return `❌ MCP 服务器 "${serverName}" 不存在`;
+            }
+            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}`;
+            }
+            try {
+                const manifest = await mcpManager.connect(serverName, serverConfig.config);
+                const toolList = manifest.tools.map((t) => `- ${t.name}: ${t.description}`).join("\n");
+                return `✅ MCP 服务器 "${serverName}" 已连接 (${manifest.tools.length} 个工具):\n${toolList}`;
+            }
+            catch (error) {
+                return `无法连接到 "${serverName}": ${error?.message ?? error}`;
+            }
+        },
+    });
+}
+/**
+ * 创建 call_mcp_tool 工具。
+ * 通过官方 Client.callTool() API 调用 MCP 服务器上的工具。
+ */
+export function createCallMcpTool(mcpManager) {
+    return new CallbackTool({
+        function: {
+            name: "call_mcp_tool",
+            description: "调用已连接 MCP 服务器上的指定工具。需先通过 load_mcp 连接服务器。",
+            parameters: {
+                type: "object",
+                properties: {
+                    server: { type: "string", description: "MCP 服务器名称" },
+                    tool: { type: "string", description: "工具名称" },
+                    arguments: { type: "object", description: "工具参数" },
+                },
+                required: ["server", "tool", "arguments"],
+                additionalProperties: false,
+            },
+        },
+        callback: async (input) => {
+            const serverName = input.server;
+            const state = mcpManager.getState(serverName);
+            if (state !== "connected") {
+                return `请先使用 load_mcp 连接 "${serverName}"`;
+            }
+            const client = mcpManager.getClient(serverName);
+            if (!client) {
+                return `MCP 服务器 "${serverName}" 的客户端不可用`;
+            }
+            try {
+                mcpManager.touch(serverName);
+                const result = await client.callTool({
+                    name: input.tool,
+                    arguments: input.arguments,
+                });
+                const contents = result.content ?? [];
+                const textParts = contents
+                    .filter((c) => c.type === "text")
+                    .map((c) => c.text);
+                const text = textParts.join("\n");
+                if (result.isError) {
+                    return `❌ 工具执行出错:\n${text || JSON.stringify(result)}`;
+                }
+                return text || JSON.stringify(result);
+            }
+            catch (error) {
+                return `❌ 调用 "${input.tool}" 失败: ${error?.message ?? error}`;
+            }
+        },
+    });
+}
+/**
+ * 创建 read_mcp_resource 工具。
+ */
+export function createReadMcpResourceTool(mcpManager) {
+    return new CallbackTool({
+        function: {
+            name: "read_mcp_resource",
+            description: "读取已连接 MCP 服务器上的指定资源（文档、数据等）。",
+            parameters: {
+                type: "object",
+                properties: {
+                    server: { type: "string", description: "MCP 服务器名称" },
+                    uri: { type: "string", description: "资源 URI" },
+                },
+                required: ["server", "uri"],
+                additionalProperties: false,
+            },
+        },
+        callback: async (input) => {
+            const serverName = input.server;
+            const state = mcpManager.getState(serverName);
+            if (state !== "connected") {
+                return `请先使用 load_mcp 连接 "${serverName}"`;
+            }
+            const client = mcpManager.getClient(serverName);
+            if (!client) {
+                return `MCP 服务器 "${serverName}" 的客户端不可用`;
+            }
+            try {
+                mcpManager.touch(serverName);
+                const result = await client.readResource({
+                    uri: input.uri,
+                });
+                const contents = result?.contents ?? [];
+                const textParts = contents
+                    .filter((c) => c.text)
+                    .map((c) => c.text);
+                return textParts.join("\n") || JSON.stringify(result);
+            }
+            catch (error) {
+                return `❌ 读取资源 "${input.uri}" 失败: ${error?.message ?? error}`;
+            }
+        },
+    });
+}

package/dist/capabilities/implements/skillTools.d.ts

@@ -0,0 +1,15 @@
+import { CallbackTool } from "@ai-zen/agents-core";
+import type { SkillInfo } from "../discovery/skills.js";
+import type { Capabilities } from "../Capabilities.js";
+/**
+ * 创建 load_skill 工具。
+ * 枚举所有允许的 skill（不限是否支持子 Agent），由 filteredSkills 提供完整信息。
+ */
+export declare function createLoadSkillTool(skillDirs: string[], filteredSkills: SkillInfo[]): CallbackTool;
+/**
+ * 创建 call_skill_sub_agent 工具。
+ * 只展示 subAgent: true 的 Skill，枚举中自动排除不支持子 Agent 模式的 skill。
+ *
+ * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
+ */
+export declare function createCallSkillSubAgentTool(skillDirs: string[], filteredSkills: SkillInfo[], caps?: Capabilities): CallbackTool;

package/dist/capabilities/implements/skillTools.js

@@ -0,0 +1,113 @@
+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";
+const log = createLogger();
+const EMPTY_HINT = "（当前没有可用的 Skill，请联系用户添加）";
+/**
+ * 创建 load_skill 工具。
+ * 枚举所有允许的 skill（不限是否支持子 Agent），由 filteredSkills 提供完整信息。
+ */
+export function createLoadSkillTool(skillDirs, filteredSkills) {
+    const ids = filteredSkills.map((s) => s.id);
+    const param = createDisclosureParam(ids, "选择一个 Skill", EMPTY_HINT);
+    return new CallbackTool({
+        function: {
+            name: "load_skill",
+            description: "加载指定 Skill 的完整指导文档。Skill 是预制的专业指导，加载后展开到上下文中。",
+            parameters: {
+                type: "object",
+                properties: {
+                    skill_id: {
+                        type: "string",
+                        description: param.description,
+                        ...(param.enum ? { enum: param.enum } : {}),
+                    },
+                },
+                required: ["skill_id"],
+                additionalProperties: false,
+            },
+        },
+        callback: async function (input) {
+            const skillId = input.skill_id;
+            const skill = readSkill(skillDirs, skillId);
+            if (!skill) {
+                return `❌ Skill "${skillId}" 不存在，请确认名称是否正确`;
+            }
+            const alreadyLoaded = this.agent?.messages?.some((m) => String(m.content ?? "").includes(`Skill "${skillId}" 已加载`));
+            if (alreadyLoaded) {
+                return `Skill "${skillId}" 已加载`;
+            }
+            if (this.agent) {
+                this.agent.messages.push(Message.System(`以下是 Skill "${skillId}" 的内容，请按照其中的指导完成任务：\n\n${skill.content}`));
+            }
+            return `✅ Skill "${skillId}" 已加载，内容已附加到当前对话中`;
+        },
+    });
+}
+/**
+ * 创建 call_skill_sub_agent 工具。
+ * 只展示 subAgent: true 的 Skill，枚举中自动排除不支持子 Agent 模式的 skill。
+ *
+ * 回调中创建独立的 Skill 子 Agent，通过 caps 按父 Agent 权限独立解析工具集。
+ */
+export function createCallSkillSubAgentTool(skillDirs, filteredSkills, caps) {
+    // 只保留支持子 Agent 模式的 skill
+    const subAgentSkills = filteredSkills.filter((s) => s.subAgent);
+    const ids = subAgentSkills.map((s) => s.id);
+    const param = createDisclosureParam(ids, "选择一个 Skill（支持子 Agent）", EMPTY_HINT);
+    return new CallbackTool({
+        function: {
+            name: "call_skill_sub_agent",
+            description: "将任务委派给指定的 Skill 子 Agent，由其独立完成并返回结果。",
+            parameters: {
+                type: "object",
+                properties: {
+                    skill_id: {
+                        type: "string",
+                        description: param.description,
+                        ...(param.enum ? { enum: param.enum } : {}),
+                    },
+                    task: {
+                        type: "string",
+                        description: "要委派给子 Agent 完成的任务描述",
+                    },
+                },
+                required: ["skill_id", "task"],
+                additionalProperties: false,
+            },
+        },
+        async callback(input) {
+            const skillId = input.skill_id;
+            const task = input.task;
+            const skill = readSkill(skillDirs, skillId);
+            if (!skill) {
+                return `❌ Skill "${skillId}" 不存在，请确认名称是否正确`;
+            }
+            if (!skill.subAgent) {
+                return `Skill "${skillId}" 不支持子 Agent 模式，请使用 load_skill 加载指导后自行处理`;
+            }
+            const parentAgent = (this).agent;
+            const parentPermissions = parentAgent instanceof SdkAgent
+                ? parentAgent.permissions
+                : undefined;
+            const skillTools = caps && parentPermissions
+                ? caps.buildTools(parentPermissions, {
+                    exclude: { skills: [skillId] },
+                })
+                : [];
+            const subAgent = new Agent({
+                model: parentAgent.model,
+                messages: [
+                    Message.System(skill.content),
+                    Message.User(task),
+                ],
+                tools: skillTools,
+            });
+            await subAgent.run();
+            const lastMsg = subAgent.messages.at(-1);
+            return typeof lastMsg?.content === "string" ? lastMsg.content : "";
+        },
+    });
+}

package/dist/capabilities/implements/subAgentTools.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from "@ai-zen/agents-core";
+import type { AgentDefinition } from "../../types/index.js";
+import type { Provider } from "../../runtime/Provider.js";
+import type { Capabilities } from "../Capabilities.js";
+/**
+ * 创建 SubAgent 工具（AgentToolLazy）。
+ *
+ * SubAgent 是有 `function` 字段的 Agent，可被其他 Agent 作为工具调用。
+ * 使用延迟构建（AgentToolLazy）避免工具列表构建阶段的递归创建问题。
+ */
+export declare function createSubAgentTool(def: AgentDefinition, provider: Provider, caps?: Capabilities): Tool;

package/dist/capabilities/implements/subAgentTools.js

@@ -0,0 +1,53 @@
+import { Agent, AgentToolLazy } from "@ai-zen/agents-core";
+import { createModel } from "../../runtime/createModel.js";
+/**
+ * 创建 SubAgent 工具（AgentToolLazy）。
+ *
+ * SubAgent 是有 `function` 字段的 Agent，可被其他 Agent 作为工具调用。
+ * 使用延迟构建（AgentToolLazy）避免工具列表构建阶段的递归创建问题。
+ */
+export function createSubAgentTool(def, provider, caps) {
+    if (!def.function) {
+        throw new Error(`Agent "${def.id}" 没有 function 字段，不能作为 SubAgent 工具`);
+    }
+    const selfName = def.function.name;
+    const lazy = new AgentToolLazy({
+        function: {
+            name: selfName,
+            description: def.function.description || def.description || def.name,
+            parameters: def.function.parameters,
+        },
+        messages: def.messages,
+        buildAgent: function (_parsedArgs) {
+            if (!caps) {
+                throw new Error(`SubAgent "${selfName}" 缺少 Capabilities 引用。` +
+                    `请确保 Capabilities.instantiate() 传入了 caps（this）。`);
+            }
+            // 模型解析：SubAgent 可指定独立模型，否则复用父 Agent 的模型
+            let subModel;
+            if (def.modelId) {
+                subModel = createModel(provider.config, def.modelId);
+            }
+            else {
+                const parentModel = this.agent?.model;
+                if (!parentModel) {
+                    throw new Error(`SubAgent "${selfName}" 未指定 modelId，且父 Agent 没有可复用的模型`);
+                }
+                subModel = parentModel;
+            }
+            // SubAgent 独立解析自己的工具（排除自身，防止递归）
+            const subFiltered = caps.filter(def.permissions ?? {}, {
+                exclude: {
+                    subagents: def.function?.name ? [def.function.name] : undefined,
+                },
+            });
+            const tools = caps.instantiate(subFiltered);
+            const subAgent = new Agent({
+                model: subModel,
+                tools,
+            });
+            return subAgent;
+        },
+    });
+    return lazy;
+}

package/dist/config/ConfigManager.d.ts

@@ -0,0 +1,49 @@
+import type { AppConfig, AgentDefinition } from "../types/index.js";
+/**
+ * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
+ */
+export declare class ConfigManager {
+    readonly configPath: string;
+    readonly basePath: string;
+    constructor(configPath: string);
+    /**
+     * 读取配置。文件不存在时返回出厂默认配置。
+     */
+    read(): AppConfig;
+    write(config: AppConfig): void;
+    /**
+     * 确保基础目录结构存在。
+     * 创建 basePath 及所有标准共享子目录（agents/、sub-agents/、skills/ 等）。
+     */
+    ensureDirs(): void;
+    /**
+     * 确保 config.json 存在。不存在时写入出厂默认配置 DSL。
+     */
+    ensureDefaultConfig(): AppConfig;
+    /**
+     * 确保 basePath/agents/default.json 存在。
+     *
+     * - default.json 已存在 → 返回已有定义，不覆盖
+     * - agents/ 为空 → 写入默认 Agent
+     * - 已有其他 Agent → 返回 null
+     */
+    ensureDefaultAgent(): AgentDefinition | null;
+    /**
+     * 确保 basePath/sub-agents/{DEFAULT_SUBAGENT_ID}.json 存在。
+     *
+     * - 文件已存在 → 返回已有定义，不覆盖
+     * - sub-agents/ 为空 → 写入默认通用助手 SubAgent
+     * - 已有其他 SubAgent → 返回 null
+     */
+    ensureDefaultSubAgent(): AgentDefinition | null;
+    /**
+     * 一键初始化：目录 + config.json + 默认 Agent + 默认 SubAgent。
+     * 已有文件不会被覆盖。
+     */
+    bootstrap(): {
+        config: AppConfig;
+        agent: AgentDefinition | null;
+        subAgent: AgentDefinition | null;
+    };
+}
+export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";

package/dist/config/ConfigManager.js

@@ -0,0 +1,126 @@
+import { readFileSync, writeFileSync, existsSync, renameSync, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
+/**
+ * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
+ */
+export class ConfigManager {
+    configPath;
+    basePath;
+    constructor(configPath) {
+        this.configPath = configPath;
+        this.basePath = dirname(configPath);
+    }
+    // -----------------------------------------------------------------------
+    // config.json
+    // -----------------------------------------------------------------------
+    /**
+     * 读取配置。文件不存在时返回出厂默认配置。
+     */
+    read() {
+        if (!existsSync(this.configPath)) {
+            return { ...DEFAULT_APP_CONFIG };
+        }
+        const raw = readFileSync(this.configPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    write(config) {
+        const dir = dirname(this.configPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const tmpPath = this.configPath + ".tmp";
+        writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+        renameSync(tmpPath, this.configPath);
+    }
+    // -----------------------------------------------------------------------
+    // 目录 & 默认实体
+    // -----------------------------------------------------------------------
+    /**
+     * 确保基础目录结构存在。
+     * 创建 basePath 及所有标准共享子目录（agents/、sub-agents/、skills/ 等）。
+     */
+    ensureDirs() {
+        mkdirSync(this.basePath, { recursive: true });
+        for (const dir of CONFIG_SUB_DIRS) {
+            mkdirSync(join(this.basePath, dir), { recursive: true });
+        }
+    }
+    /**
+     * 确保 config.json 存在。不存在时写入出厂默认配置 DSL。
+     */
+    ensureDefaultConfig() {
+        if (existsSync(this.configPath)) {
+            return this.read();
+        }
+        this.ensureDirs();
+        this.write(DEFAULT_APP_CONFIG);
+        return { ...DEFAULT_APP_CONFIG };
+    }
+    /**
+     * 确保 basePath/agents/default.json 存在。
+     *
+     * - default.json 已存在 → 返回已有定义，不覆盖
+     * - agents/ 为空 → 写入默认 Agent
+     * - 已有其他 Agent → 返回 null
+     */
+    ensureDefaultAgent() {
+        const agentsDir = join(this.basePath, "agents");
+        const defaultPath = join(agentsDir, `${DEFAULT_AGENT_ID}.json`);
+        if (existsSync(defaultPath)) {
+            return JSON.parse(readFileSync(defaultPath, "utf-8"));
+        }
+        mkdirSync(agentsDir, { recursive: true });
+        const existing = readdirSync(agentsDir).filter((f) => f.endsWith(".json"));
+        if (existing.length > 0) {
+            return null;
+        }
+        const now = new Date().toISOString();
+        const definition = {
+            ...DEFAULT_AGENT_DEFINITION,
+            createdAt: now,
+            updatedAt: now,
+        };
+        writeFileSync(defaultPath, JSON.stringify(definition, null, 2), "utf-8");
+        return definition;
+    }
+    /**
+     * 确保 basePath/sub-agents/{DEFAULT_SUBAGENT_ID}.json 存在。
+     *
+     * - 文件已存在 → 返回已有定义，不覆盖
+     * - sub-agents/ 为空 → 写入默认通用助手 SubAgent
+     * - 已有其他 SubAgent → 返回 null
+     */
+    ensureDefaultSubAgent() {
+        const subDir = join(this.basePath, "sub-agents");
+        const defaultPath = join(subDir, `${DEFAULT_SUBAGENT_ID}.json`);
+        if (existsSync(defaultPath)) {
+            return JSON.parse(readFileSync(defaultPath, "utf-8"));
+        }
+        mkdirSync(subDir, { recursive: true });
+        const existing = readdirSync(subDir).filter((f) => f.endsWith(".json"));
+        if (existing.length > 0) {
+            return null;
+        }
+        const now = new Date().toISOString();
+        const definition = {
+            ...DEFAULT_SUBAGENT_DEFINITION,
+            createdAt: now,
+            updatedAt: now,
+        };
+        writeFileSync(defaultPath, JSON.stringify(definition, null, 2), "utf-8");
+        return definition;
+    }
+    /**
+     * 一键初始化：目录 + config.json + 默认 Agent + 默认 SubAgent。
+     * 已有文件不会被覆盖。
+     */
+    bootstrap() {
+        this.ensureDirs();
+        const config = this.ensureDefaultConfig();
+        const agent = this.ensureDefaultAgent();
+        const subAgent = this.ensureDefaultSubAgent();
+        return { config, agent, subAgent };
+    }
+}
+export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";

package/dist/config/constants.d.ts

@@ -0,0 +1,20 @@
+import type { AgentDefinition, AppConfig } from "../types/index.js";
+/** 默认 Agent ID */
+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";
+/** 默认 SubAgent 定义（不含时间戳） */
+export declare const DEFAULT_SUBAGENT_DEFINITION: Omit<AgentDefinition, "createdAt" | "updatedAt">;
+/** SDK 出厂默认 AppConfig。CLI/Desktop 首次初始化时使用。 */
+export declare const DEFAULT_APP_CONFIG: AppConfig;
+/**
+ * 标准共享子目录列表（不包含运行时目录）。
+ *
+ * 各客户端（CLI/Desktop）的运行时数据（config.json、conversations/、drafts/）
+ * 由客户端自行在各自目录下管理：
+ *   ~/.ai-zen/cli/          ← CLI 运行时
+ *   ~/.ai-zen/desktop/      ← Desktop 运行时（未来）
+ */
+export declare const CONFIG_SUB_DIRS: readonly ["agents", "sub-agents", "skills", "tools", "mcp-oauth"];