@shareai-lab/kode-sdk 1.0.0-beta.8 → 2.7.0

package/dist/tools/mcp.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMCPTools = getMCPTools;
+exports.disconnectMCP = disconnectMCP;
+exports.disconnectAllMCP = disconnectAllMCP;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const registry_1 = require("./registry");
+/**
+ * MCP Client 管理器
+ *
+ * 维护 MCP 客户端连接，支持多种传输方式
+ */
+class MCPClientManager {
+    constructor() {
+        this.clients = new Map();
+        this.transports = new Map();
+    }
+    async connect(serverName, config) {
+        // 如果已连接，返回现有客户端
+        if (this.clients.has(serverName)) {
+            return this.clients.get(serverName);
+        }
+        // 创建 transport
+        let transport;
+        if (config.transport === 'stdio') {
+            if (!config.command) {
+                throw new Error('command is required for stdio transport');
+            }
+            transport = new stdio_js_1.StdioClientTransport({
+                command: config.command,
+                args: config.args || [],
+                env: config.env,
+            });
+        }
+        else if (config.transport === 'sse' || config.transport === 'http') {
+            if (!config.url) {
+                throw new Error('url is required for sse/http transport');
+            }
+            transport = new sse_js_1.SSEClientTransport(new URL(config.url));
+        }
+        else {
+            throw new Error(`Unsupported transport type: ${config.transport}`);
+        }
+        // 创建客户端
+        const client = new index_js_1.Client({
+            name: 'kode-sdk',
+            version: '2.0.0',
+        }, {
+            capabilities: {},
+        });
+        // 连接
+        await client.connect(transport);
+        // 缓存
+        this.clients.set(serverName, client);
+        this.transports.set(serverName, transport);
+        return client;
+    }
+    async disconnect(serverName) {
+        const client = this.clients.get(serverName);
+        if (client) {
+            await client.close();
+            this.clients.delete(serverName);
+        }
+        const transport = this.transports.get(serverName);
+        if (transport) {
+            await transport.close();
+            this.transports.delete(serverName);
+        }
+    }
+    async disconnectAll() {
+        const servers = Array.from(this.clients.keys());
+        await Promise.all(servers.map((name) => this.disconnect(name)));
+    }
+    getClient(serverName) {
+        return this.clients.get(serverName);
+    }
+}
+const mcpManager = new MCPClientManager();
+/**
+ * 获取 MCP 工具
+ *
+ * 连接到 MCP 服务器并将其工具转换为 ToolInstance[]
+ *
+ * @example
+ * ```ts
+ * // Stdio transport
+ * const tools = await getMCPTools({
+ *   transport: 'stdio',
+ *   command: 'uvx',
+ *   args: ['mcp-server-git'],
+ *   serverName: 'git'
+ * });
+ *
+ * // HTTP/SSE transport
+ * const tools = await getMCPTools({
+ *   transport: 'sse',
+ *   url: 'http://localhost:3000/mcp',
+ *   serverName: 'company',
+ *   include: ['search', 'summarize']
+ * });
+ * ```
+ */
+async function getMCPTools(config) {
+    const serverName = config.serverName || 'default';
+    // 连接到 MCP 服务器
+    const client = await mcpManager.connect(serverName, config);
+    // 列出可用工具
+    const toolsResponse = await client.listTools();
+    const mcpTools = toolsResponse.tools;
+    // 过滤工具
+    let filtered = mcpTools;
+    if (config.include) {
+        filtered = filtered.filter((tool) => config.include.includes(tool.name));
+    }
+    if (config.exclude) {
+        filtered = filtered.filter((tool) => !config.exclude.includes(tool.name));
+    }
+    // 转换为 ToolInstance[]
+    const toolInstances = filtered.map((mcpTool) => {
+        // 生成命名空间化的工具名：mcp__serverName__toolName
+        const toolName = `mcp__${serverName}__${mcpTool.name}`;
+        const toolInstance = {
+            name: toolName,
+            description: mcpTool.description || `MCP tool: ${mcpTool.name}`,
+            input_schema: mcpTool.inputSchema,
+            async exec(args, _ctx) {
+                try {
+                    // 调用 MCP 工具
+                    const result = await client.callTool({
+                        name: mcpTool.name,
+                        arguments: args,
+                    });
+                    // 返回结果
+                    return {
+                        content: result.content,
+                        isError: result.isError,
+                    };
+                }
+                catch (error) {
+                    throw new Error(`MCP tool execution failed: ${error}`);
+                }
+            },
+            toDescriptor() {
+                return {
+                    source: 'mcp',
+                    name: toolName,
+                    registryId: toolName,
+                    metadata: {
+                        mcpServer: serverName,
+                        mcpToolName: mcpTool.name,
+                        transport: config.transport,
+                    },
+                    config: {
+                        serverName,
+                        transport: config.transport,
+                        url: config.url,
+                        command: config.command,
+                        args: config.args,
+                    },
+                };
+            },
+        };
+        // 自动注册到 global registry（支持 Resume）
+        registry_1.globalToolRegistry.register(toolName, (_registryConfig) => {
+            // Resume 时重建 MCP 连接
+            return toolInstance;
+        });
+        return toolInstance;
+    });
+    return toolInstances;
+}
+/**
+ * 断开 MCP 服务器连接
+ */
+async function disconnectMCP(serverName) {
+    await mcpManager.disconnect(serverName);
+}
+/**
+ * 断开所有 MCP 服务器连接
+ */
+async function disconnectAllMCP() {
+    await mcpManager.disconnectAll();
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,29 @@
+import { Hooks } from '../core/hooks';
+import { ToolContext } from '../core/types';
+export type ToolSource = 'builtin' | 'registered' | 'mcp';
+export interface ToolDescriptor {
+    source: ToolSource;
+    name: string;
+    registryId?: string;
+    config?: Record<string, any>;
+    metadata?: Record<string, any>;
+}
+export interface ToolInstance {
+    name: string;
+    description: string;
+    input_schema: any;
+    hooks?: Hooks;
+    permissionDetails?: (call: any, ctx: ToolContext) => any;
+    exec(args: any, ctx: ToolContext): Promise<any>;
+    prompt?: string | ((ctx: ToolContext) => string | Promise<string>);
+    toDescriptor(): ToolDescriptor;
+}
+export type ToolFactory = (config?: Record<string, any>) => ToolInstance;
+export declare class ToolRegistry {
+    private factories;
+    register(id: string, factory: ToolFactory): void;
+    has(id: string): boolean;
+    create(id: string, config?: Record<string, any>): ToolInstance;
+    list(): string[];
+}
+export declare const globalToolRegistry: ToolRegistry;

package/dist/tools/registry.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalToolRegistry = exports.ToolRegistry = void 0;
+class ToolRegistry {
+    constructor() {
+        this.factories = new Map();
+    }
+    register(id, factory) {
+        this.factories.set(id, factory);
+    }
+    has(id) {
+        return this.factories.has(id);
+    }
+    create(id, config) {
+        const factory = this.factories.get(id);
+        if (!factory) {
+            throw new Error(`Tool not registered: ${id}`);
+        }
+        return factory(config);
+    }
+    list() {
+        return Array.from(this.factories.keys());
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+exports.globalToolRegistry = new ToolRegistry();

package/dist/tools/scripts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Scripts 执行工具
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责执行scripts，支持双模式（直接执行/sandbox隔离）
+ * - 安全: 支持sandbox隔离执行，拦截危险命令
+ * - 跨平台: 自动适配Windows、Linux、MacOS
+ */
+import type { SkillsManager } from '../core/skills/manager';
+import type { SandboxFactory } from '../infra/sandbox-factory';
+/**
+ * 创建Scripts工具
+ *
+ * @param skillsManager Skills管理器实例
+ * @param sandboxFactory Sandbox工厂（可选）
+ * @returns ToolInstance
+ */
+export declare function createScriptsTool(skillsManager: SkillsManager, sandboxFactory?: SandboxFactory): import("./registry").ToolInstance;
+/**
+ * 导出工具创建函数
+ */
+export default createScriptsTool;

package/dist/tools/scripts.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Scripts 执行工具
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责执行scripts，支持双模式（直接执行/sandbox隔离）
+ * - 安全: 支持sandbox隔离执行，拦截危险命令
+ * - 跨平台: 自动适配Windows、Linux、MacOS
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createScriptsTool = createScriptsTool;
+const tool_1 = require("../tools/tool");
+const zod_1 = require("zod");
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+/**
+ * Scripts 工具描述
+ */
+const DESCRIPTION = `执行skill中的scripts脚本。
+
+支持两种执行模式:
+- 直接执行模式（默认）: 本地开发时使用，直接在当前环境执行
+- Sandbox隔离模式: 生产环境使用，在安全隔离环境中执行
+
+支持的脚本类型:
+- Node.js脚本 (.js, .ts): 跨平台兼容
+- Shell脚本 (.sh): Linux/MacOS
+- Batch脚本 (.bat): Windows
+
+注意: 危险命令会被自动拦截（如rm -rf /、sudo等）`;
+/**
+ * 检测平台
+ */
+function detectPlatform() {
+    const platform = os.platform();
+    if (platform === 'win32')
+        return 'windows';
+    if (platform === 'darwin')
+        return 'macos';
+    return 'linux';
+}
+/**
+ * 获取脚本执行命令
+ */
+function getScriptCommand(scriptPath, platform) {
+    const ext = path.extname(scriptPath).toLowerCase();
+    switch (ext) {
+        case '.js':
+            return `node "${scriptPath}"`;
+        case '.ts':
+            return `ts-node "${scriptPath}"`;
+        case '.sh':
+            if (platform === 'windows') {
+                // Windows下需要Git Bash或WSL来执行.sh
+                return `bash "${scriptPath}"`;
+            }
+            return `sh "${scriptPath}"`;
+        case '.bat':
+        case '.cmd':
+            if (platform !== 'windows') {
+                throw new Error(`Batch scripts (.bat/.cmd) are only supported on Windows`);
+            }
+            return `"${scriptPath}"`;
+        default:
+            throw new Error(`Unsupported script type: ${ext}`);
+    }
+}
+/**
+ * 创建Scripts工具
+ *
+ * @param skillsManager Skills管理器实例
+ * @param sandboxFactory Sandbox工厂（可选）
+ * @returns ToolInstance
+ */
+function createScriptsTool(skillsManager, sandboxFactory) {
+    const scriptsTool = (0, tool_1.tool)({
+        name: 'execute_script',
+        description: DESCRIPTION,
+        parameters: zod_1.z.object({
+            skill_name: zod_1.z.string().describe('技能名称'),
+            script_name: zod_1.z.string().describe('脚本文件名（如"script.js"）'),
+            use_sandbox: zod_1.z.boolean().optional().default(true).describe('是否使用sandbox隔离执行'),
+            args: zod_1.z.array(zod_1.z.string()).optional().describe('脚本参数（可选）'),
+        }),
+        async execute(args, ctx) {
+            const { skill_name, script_name, use_sandbox, args: scriptArgs = [] } = args;
+            // 加载skill内容
+            const skillContent = await skillsManager.loadSkillContent(skill_name);
+            if (!skillContent) {
+                return {
+                    ok: false,
+                    error: `Skill '${skill_name}' not found`,
+                };
+            }
+            // 查找脚本文件
+            const scriptPath = skillContent.scripts.find(p => path.basename(p) === script_name);
+            if (!scriptPath) {
+                return {
+                    ok: false,
+                    error: `Script '${script_name}' not found in skill '${skill_name}'. Available scripts: ${skillContent.scripts.map(p => path.basename(p)).join(', ')}`,
+                };
+            }
+            const platform = detectPlatform();
+            let result;
+            try {
+                if (use_sandbox && sandboxFactory) {
+                    // 使用sandbox隔离执行
+                    const sandbox = sandboxFactory.create({
+                        kind: 'local',
+                        workDir: skillContent.metadata.baseDir,
+                    });
+                    const cmd = getScriptCommand(scriptPath, platform);
+                    const cmdWithArgs = `${cmd} ${scriptArgs.join(' ')}`;
+                    result = await sandbox.exec(cmdWithArgs, { timeoutMs: 60000 });
+                }
+                else {
+                    // 直接执行（本地开发模式）
+                    const cmd = getScriptCommand(scriptPath, platform);
+                    const cmdWithArgs = `${cmd} ${scriptArgs.join(' ')}`;
+                    const stdout = (0, child_process_1.execSync)(cmdWithArgs, {
+                        cwd: skillContent.metadata.baseDir,
+                        encoding: 'utf-8',
+                        stdio: ['ignore', 'pipe', 'pipe'],
+                        timeout: 60000,
+                    });
+                    result = {
+                        code: 0,
+                        stdout: stdout || '',
+                        stderr: '',
+                    };
+                }
+                if (result.code !== 0) {
+                    return {
+                        ok: false,
+                        error: `Script execution failed with code ${result.code}`,
+                        data: {
+                            stdout: result.stdout,
+                            stderr: result.stderr,
+                        },
+                    };
+                }
+                return {
+                    ok: true,
+                    data: {
+                        stdout: result.stdout,
+                        stderr: result.stderr,
+                    },
+                };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: error.message || 'Script execution failed',
+                    data: {
+                        stdout: error.stdout || '',
+                        stderr: error.stderr || '',
+                    },
+                };
+            }
+        },
+        metadata: {
+            readonly: false,
+            version: '1.0',
+        },
+    });
+    return scriptsTool;
+}
+/**
+ * 导出工具创建函数
+ */
+exports.default = createScriptsTool;

package/dist/tools/skills.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Skills 工具
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责列出和加载skills，不处理业务逻辑
+ * - 模块化: 复用SkillsManager进行实际操作
+ * - 组合: 与SDK工具系统无缝集成
+ */
+import type { SkillsManager } from '../core/skills/manager';
+/**
+ * 创建Skills工具
+ *
+ * @param skillsManager Skills管理器实例
+ * @returns ToolInstance
+ */
+export declare function createSkillsTool(skillsManager: SkillsManager): import("./registry").ToolInstance;
+/**
+ * 导出工具创建函数
+ */
+export default createSkillsTool;

package/dist/tools/skills.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Skills 工具
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责列出和加载skills，不处理业务逻辑
+ * - 模块化: 复用SkillsManager进行实际操作
+ * - 组合: 与SDK工具系统无缝集成
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSkillsTool = createSkillsTool;
+const tool_1 = require("../tools/tool");
+const zod_1 = require("zod");
+/**
+ * Skills 工具描述
+ *
+ * 原始描述（已备份，list操作已临时禁用）:
+ * const ORIGINAL_DESCRIPTION = `管理和加载skills。
+ *
+ * 使用此工具来:
+ * - 列出所有可用的skills（获取元数据列表）
+ * - 加载特定skill的详细内容（包含指令、references、scripts、assets）
+ *
+ * Skills是可重用的能力单元，可以扩展Agent的功能。`;
+ */
+const DESCRIPTION = `加载特定skill的详细内容。
+
+使用此工具来:
+- 加载特定skill的详细内容（包含指令、references、scripts、assets）
+- 需要提供skill_name参数来指定要加载的技能
+
+Skills是可重用的能力单元，可以扩展Agent的功能。`;
+/**
+ * 创建Skills工具
+ *
+ * @param skillsManager Skills管理器实例
+ * @returns ToolInstance
+ */
+function createSkillsTool(skillsManager) {
+    // 临时禁用 list 操作，只保留 load 操作
+    // const actionSchema = z.enum(['list', 'load']).describe('操作类型');
+    const actionSchema = zod_1.z.enum(['load']).describe('操作类型');
+    const skillsTool = (0, tool_1.tool)({
+        name: 'skills',
+        description: DESCRIPTION,
+        parameters: zod_1.z.object({
+            action: actionSchema,
+            skill_name: zod_1.z.string().optional().describe('技能名称（当action=load时必需）'),
+        }),
+        async execute(args, ctx) {
+            const { action, skill_name } = args;
+            // 注释掉 list 操作的代码
+            // if (action === 'list') {
+            //   // 列出所有skills
+            //   const skills = await skillsManager.getSkillsMetadata();
+            //
+            //   const skillsList = skills.map(s => ({
+            //     name: s.name,
+            //     description: s.description,
+            //   }));
+            //
+            //   return {
+            //     ok: true,
+            //     data: {
+            //       count: skillsList.length,
+            //       skills: skillsList,
+            //     },
+            //   };
+            // } else if (action === 'load') {
+            if (action === 'load') {
+                // 加载特定skill内容
+                if (!skill_name) {
+                    return {
+                        ok: false,
+                        error: 'skill_name is required when action=load',
+                    };
+                }
+                const content = await skillsManager.loadSkillContent(skill_name);
+                if (!content) {
+                    return {
+                        ok: false,
+                        error: `Skill '${skill_name}' not found`,
+                    };
+                }
+                return {
+                    ok: true,
+                    data: {
+                        name: content.metadata.name,
+                        description: content.metadata.description,
+                        content: content.content,
+                        base_dir: content.metadata.baseDir,
+                        references: content.references,
+                        scripts: content.scripts,
+                        assets: content.assets,
+                    },
+                };
+            }
+            else {
+                return {
+                    ok: false,
+                    error: `Unknown action: ${action}`,
+                };
+            }
+        },
+        metadata: {
+            readonly: true,
+            version: '1.0',
+        },
+    });
+    return skillsTool;
+}
+/**
+ * 导出工具创建函数
+ */
+exports.default = createSkillsTool;

package/dist/tools/task_run/index.d.ts

@@ -0,0 +1,7 @@
+export interface AgentTemplate {
+    id: string;
+    system?: string;
+    tools?: string[];
+    whenToUse?: string;
+}
+export declare function createTaskRunTool(templates: AgentTemplate[]): import("..").ToolInstance;

package/dist/tools/task_run/index.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskRunTool = createTaskRunTool;
+const tool_1 = require("../tool");
+const zod_1 = require("zod");
+const prompt_1 = require("./prompt");
+function createTaskRunTool(templates) {
+    if (!templates || templates.length === 0) {
+        throw new Error('Cannot create task_run tool: no agent templates provided');
+    }
+    const TaskRun = (0, tool_1.tool)({
+        name: 'task_run',
+        description: prompt_1.DESCRIPTION,
+        parameters: zod_1.z.object({
+            description: zod_1.z.string().describe('Short description of the task (3-5 words)'),
+            prompt: zod_1.z.string().describe('Detailed instructions for the sub-agent'),
+            agentTemplateId: zod_1.z.string().describe('Agent template ID to use for this task'),
+            context: zod_1.z.string().optional().describe('Additional context to append'),
+        }),
+        async execute(args, ctx) {
+            const { description, prompt, agentTemplateId, context } = args;
+            const template = templates.find((tpl) => tpl.id === agentTemplateId);
+            if (!template) {
+                const availableTemplates = templates
+                    .map((tpl) => `  - ${tpl.id}: ${tpl.whenToUse || 'General purpose agent'}`)
+                    .join('\n');
+                throw new Error(`Agent template '${agentTemplateId}' not found.\n\nAvailable templates:\n${availableTemplates}\n\nPlease choose one of the available template IDs.`);
+            }
+            const detailedPrompt = [
+                `# Task: ${description}`,
+                prompt,
+                context ? `\n# Additional Context\n${context}` : undefined,
+            ]
+                .filter(Boolean)
+                .join('\n\n');
+            if (!ctx.agent?.delegateTask) {
+                throw new Error('Task delegation not supported by this agent version');
+            }
+            const result = await ctx.agent.delegateTask({
+                templateId: template.id,
+                prompt: detailedPrompt,
+                tools: template.tools,
+            });
+            return {
+                status: result.status,
+                template: template.id,
+                text: result.text,
+                permissionIds: result.permissionIds,
+            };
+        },
+        metadata: {
+            readonly: false,
+            version: '1.0',
+        },
+    });
+    TaskRun.prompt = (0, prompt_1.generatePrompt)(templates);
+    return TaskRun;
+}

package/dist/tools/task_run/prompt.d.ts

@@ -0,0 +1,5 @@
+export declare const DESCRIPTION = "Delegate a task to a specialized sub-agent";
+export declare function generatePrompt(templates: Array<{
+    id: string;
+    whenToUse?: string;
+}>): string;