@shareai-lab/kode-sdk 2.7.1 → 2.7.2

package/dist/core/skills/manager.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Skills 管理器
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责扫描和加载skills，不处理业务逻辑
+ * - 模块化: 单一职责，易于测试和维护
+ * - 热更新: 每次调用都重新扫描文件系统，确保数据最新
+ */
+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.SkillsManager = void 0;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const logger_1 = require("../../utils/logger");
+/**
+ * Skills 管理器
+ */
+class SkillsManager {
+    constructor(skillsDir, allowedSkills) {
+        this.cache = new Map();
+        // 优先使用传入的路径，其次使用环境变量，最后使用默认路径
+        // 默认路径：程序当前工作目录下的 skills/
+        const envSkillsDir = process.env.SKILLS_DIR;
+        const defaultSkillsDir = path.join(process.cwd(), 'skills');
+        this.skillsDir = path.resolve(skillsDir ||
+            envSkillsDir ||
+            defaultSkillsDir);
+        // 设置允许加载的 skills 白名单
+        this.allowedSkills = allowedSkills;
+        logger_1.logger.log(`[SkillsManager] Initialized with skills directory: ${this.skillsDir}`);
+        if (this.allowedSkills) {
+            logger_1.logger.log(`[SkillsManager] Allowed skills whitelist: ${this.allowedSkills.join(', ')}`);
+        }
+    }
+    /**
+     * 扫描skills目录（支持热更新）
+     * 每次调用时重新扫描，确保读取最新数据
+     */
+    async scan() {
+        // 清空缓存
+        this.cache.clear();
+        try {
+            // 检查目录是否存在
+            const exists = await this.fileExists(this.skillsDir);
+            if (!exists) {
+                logger_1.logger.log(`[SkillsManager] Skills directory does not exist: ${this.skillsDir}`);
+                return [];
+            }
+            // 递归扫描skills目录
+            const entries = await this.scanDirectory(this.skillsDir);
+            // 提取每个skill的元数据
+            for (const entry of entries) {
+                const metadata = await this.parseSkillMetadata(entry);
+                if (metadata) {
+                    // 如果设置了白名单，只加载白名单中的 skills
+                    if (this.allowedSkills) {
+                        if (this.allowedSkills.includes(metadata.name)) {
+                            this.cache.set(metadata.name, metadata);
+                        }
+                        else {
+                            logger_1.logger.log(`[SkillsManager] Skipping skill not in whitelist: ${metadata.name}`);
+                        }
+                    }
+                    else {
+                        // 没有设置白名单，加载所有 skills
+                        this.cache.set(metadata.name, metadata);
+                    }
+                }
+            }
+            logger_1.logger.log(`[SkillsManager] Scanned ${this.cache.size} skill(s)`);
+            return Array.from(this.cache.values());
+        }
+        catch (error) {
+            logger_1.logger.error(`[SkillsManager] Error scanning skills directory:`, error.message);
+            return [];
+        }
+    }
+    /**
+     * 获取所有skills的元数据列表（供LLM选择）
+     */
+    async getSkillsMetadata() {
+        // 每次调用时重新扫描，支持热更新
+        return await this.scan();
+    }
+    /**
+     * 加载指定skill的完整内容
+     */
+    async loadSkillContent(skillName) {
+        // 先扫描确保元数据最新
+        await this.scan();
+        const metadata = this.cache.get(skillName);
+        if (!metadata) {
+            return null;
+        }
+        try {
+            // 读取SKILL.md内容
+            const content = await fs.readFile(metadata.path, 'utf-8');
+            // 扫描子目录
+            const references = await this.listSubdirectory(metadata.baseDir, 'references');
+            const scripts = await this.listSubdirectory(metadata.baseDir, 'scripts');
+            const assets = await this.listSubdirectory(metadata.baseDir, 'assets');
+            return {
+                metadata,
+                content,
+                references,
+                scripts,
+                assets,
+            };
+        }
+        catch (error) {
+            logger_1.logger.error(`[SkillsManager] Error loading skill content:`, error.message);
+            return null;
+        }
+    }
+    /**
+     * 递归扫描目录，查找所有SKILL.md
+     */
+    async scanDirectory(dir) {
+        const skillFiles = [];
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    // 检查是否有SKILL.md
+                    const skillMdPath = path.join(fullPath, 'SKILL.md');
+                    if (await this.fileExists(skillMdPath)) {
+                        skillFiles.push(skillMdPath);
+                    }
+                    else {
+                        // 递归扫描子目录
+                        const subSkills = await this.scanDirectory(fullPath);
+                        skillFiles.push(...subSkills);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            logger_1.logger.warn(`[SkillsManager] Error reading directory ${dir}:`, error.message);
+        }
+        return skillFiles;
+    }
+    /**
+     * 解析SKILL.md，提取元数据
+     */
+    async parseSkillMetadata(skillMdPath) {
+        try {
+            const content = await fs.readFile(skillMdPath, 'utf-8');
+            // 提取YAML frontmatter
+            const match = content.match(/^---\n([\s\S]+?)\n---/);
+            if (!match) {
+                logger_1.logger.warn(`[SkillsManager] Invalid SKILL.md (missing YAML frontmatter): ${skillMdPath}`);
+                return null;
+            }
+            const yaml = match[1];
+            const nameMatch = yaml.match(/^name:\s*(.+)$/m);
+            const descMatch = yaml.match(/^description:\s*(.+)$/m);
+            if (!nameMatch) {
+                logger_1.logger.warn(`[SkillsManager] Invalid SKILL.md (missing name): ${skillMdPath}`);
+                return null;
+            }
+            return {
+                name: nameMatch[1].trim(),
+                description: descMatch ? descMatch[1].trim() : '',
+                path: skillMdPath,
+                baseDir: path.dirname(skillMdPath),
+            };
+        }
+        catch (error) {
+            logger_1.logger.warn(`[SkillsManager] Error parsing ${skillMdPath}:`, error.message);
+            return null;
+        }
+    }
+    /**
+     * 列出子目录下的文件
+     */
+    async listSubdirectory(baseDir, subdir) {
+        const fullPath = path.join(baseDir, subdir);
+        if (!(await this.fileExists(fullPath))) {
+            return [];
+        }
+        const files = [];
+        try {
+            const entries = await fs.readdir(fullPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile()) {
+                    files.push(path.join(fullPath, entry.name));
+                }
+            }
+        }
+        catch (error) {
+            // 目录不存在或无权限访问，返回空数组
+            logger_1.logger.debug(`[SkillsManager] Subdirectory not accessible: ${fullPath}`);
+        }
+        return files;
+    }
+    /**
+     * 检查文件是否存在
+     */
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.SkillsManager = SkillsManager;

package/dist/core/skills/operation-queue.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * 操作队列模块
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责队列管理，单一职责
+ * - 模块化: 独立的队列逻辑，易于测试和维护
+ * - 隔离: 与技能管理逻辑分离，专注于并发控制
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperationQueue = exports.OperationStatus = exports.OperationType = void 0;
+const logger_1 = require("../../utils/logger");
+/**
+ * 操作类型枚举
+ */
+var OperationType;
+(function (OperationType) {
+    OperationType["CREATE"] = "create";
+    OperationType["RENAME"] = "rename";
+    OperationType["EDIT"] = "edit";
+    OperationType["DELETE"] = "delete";
+    OperationType["RESTORE"] = "restore";
+})(OperationType || (exports.OperationType = OperationType = {}));
+/**
+ * 操作状态枚举
+ */
+var OperationStatus;
+(function (OperationStatus) {
+    OperationStatus["PENDING"] = "pending";
+    OperationStatus["PROCESSING"] = "processing";
+    OperationStatus["COMPLETED"] = "completed";
+    OperationStatus["FAILED"] = "failed";
+})(OperationStatus || (exports.OperationStatus = OperationStatus = {}));
+/**
+ * 操作队列类
+ *
+ * 职责:
+ * - 管理技能管理操作的并发执行
+ * - 按FIFO顺序处理操作
+ * - 防止操作冲突
+ */
+class OperationQueue {
+    constructor() {
+        this.queue = [];
+        this.processing = false;
+        this.maxConcurrent = 1; // 串行执行，避免冲突
+    }
+    /**
+     * 入队操作
+     */
+    async enqueue(task) {
+        this.queue.push(task);
+        logger_1.logger.log(`[OperationQueue] 操作已入队: ${task.type} - ${task.targetSkill}`);
+        // 如果没有正在处理，启动处理（不等待，异步执行）
+        if (!this.processing) {
+            // 不使用await，让队列异步处理
+            this.processQueue().catch(error => {
+                logger_1.logger.error('[OperationQueue] Queue processing error:', error);
+            });
+        }
+    }
+    /**
+     * 出队操作
+     */
+    dequeue() {
+        return this.queue.shift() || null;
+    }
+    /**
+     * 处理队列
+     */
+    async processQueue() {
+        this.processing = true;
+        while (this.queue.length > 0) {
+            const task = this.dequeue();
+            if (!task)
+                break;
+            task.status = OperationStatus.PROCESSING;
+            task.startedAt = new Date();
+            try {
+                logger_1.logger.log(`[OperationQueue] 开始处理: ${task.type} - ${task.targetSkill}`);
+                await task.execute();
+                task.status = OperationStatus.COMPLETED;
+                task.completedAt = new Date();
+                logger_1.logger.log(`[OperationQueue] 操作完成: ${task.type} - ${task.targetSkill}`);
+            }
+            catch (error) {
+                task.status = OperationStatus.FAILED;
+                task.completedAt = new Date();
+                task.error = error;
+                logger_1.logger.error(`[OperationQueue] 操作失败: ${task.type} - ${task.targetSkill}`, error);
+            }
+        }
+        this.processing = false;
+    }
+    /**
+     * 获取队列状态
+     */
+    getQueueStatus() {
+        return {
+            length: this.queue.length,
+            processing: this.processing,
+            tasks: [...this.queue],
+        };
+    }
+    /**
+     * 清空队列
+     */
+    clear() {
+        this.queue = [];
+        logger_1.logger.log('[OperationQueue] 队列已清空');
+    }
+}
+exports.OperationQueue = OperationQueue;

package/dist/core/skills/sandbox-file-manager.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Sandbox文件管理器模块
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责sandbox中的文件操作
+ * - 模块化: 独立的文件操作逻辑
+ * - 安全: 强制边界控制，确保只能访问技能目录内文件
+ */
+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.SandboxFileManager = void 0;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * Sandbox文件管理器类
+ *
+ * 职责:
+ * - 在sandbox隔离环境中执行文件操作
+ * - 确保文件访问边界在技能目录内
+ * - 提供read、write、delete、list等基础文件操作
+ */
+class SandboxFileManager {
+    constructor(sandboxFactory) {
+        this.sandboxFactory = sandboxFactory;
+    }
+    /**
+     * 在sandbox中读取文件
+     * @param skillBaseDir 技能根目录
+     * @param relativePath 相对路径
+     */
+    async readFile(skillBaseDir, relativePath) {
+        const sandbox = this.createSkillSandbox(skillBaseDir);
+        // 使用sandbox的fs接口读取文件（自动边界检查）
+        const content = await sandbox.fs.read(relativePath);
+        return content;
+    }
+    /**
+     * 在sandbox中写入文件
+     * @param skillBaseDir 技能根目录
+     * @param relativePath 相对路径
+     * @param content 文件内容
+     */
+    async writeFile(skillBaseDir, relativePath, content) {
+        const sandbox = this.createSkillSandbox(skillBaseDir);
+        // 使用sandbox的fs接口写入文件（自动边界检查）
+        await sandbox.fs.write(relativePath, content);
+    }
+    /**
+     * 在sandbox中删除文件
+     * @param skillBaseDir 技能根目录
+     * @param relativePath 相对路径
+     */
+    async deleteFile(skillBaseDir, relativePath) {
+        const sandbox = this.createSkillSandbox(skillBaseDir);
+        // 注意：sandbox.fs没有直接删除接口，需要通过exec执行
+        const cmd = this.getDeleteCommand(relativePath);
+        await sandbox.exec(cmd, { timeoutMs: 5000 });
+    }
+    /**
+     * 在sandbox中列出目录
+     * @param skillBaseDir 技能根目录
+     * @param relativePath 相对路径
+     */
+    async listFiles(skillBaseDir, relativePath = '.') {
+        const sandbox = this.createSkillSandbox(skillBaseDir);
+        // 使用glob获取文件列表
+        const pattern = path.join(relativePath, '**/*').replace(/\\/g, '/');
+        const files = await sandbox.fs.glob(pattern, {
+            absolute: true,
+        });
+        // 构建文件树
+        return this.buildFileTree(files, skillBaseDir, relativePath);
+    }
+    /**
+     * 在sandbox中创建目录
+     * @param skillBaseDir 技能根目录
+     * @param relativePath 相对路径
+     */
+    async createDir(skillBaseDir, relativePath) {
+        const sandbox = this.createSkillSandbox(skillBaseDir);
+        // 使用write创建一个临时文件来创建目录（sandbox.fs.write会自动创建目录）
+        const tempFile = path.join(relativePath, '.gitkeep');
+        await sandbox.fs.write(tempFile, '');
+    }
+    /**
+     * 创建技能的sandbox实例
+     * 关键：设置enforceBoundary=true，确保只能在技能目录内操作
+     */
+    createSkillSandbox(skillBaseDir) {
+        const config = {
+            kind: 'local',
+            workDir: skillBaseDir, // 工作目录为技能根目录
+            baseDir: skillBaseDir, // 基础目录为技能根目录
+            enforceBoundary: true, // 强制边界检查
+            allowPaths: [], // 不允许访问额外路径
+        };
+        return this.sandboxFactory.create(config);
+    }
+    /**
+     * 获取删除命令（跨平台）
+     */
+    getDeleteCommand(filePath) {
+        const platform = os.platform();
+        if (platform === 'win32') {
+            return `del /F /Q "${filePath}"`;
+        }
+        return `rm -f "${filePath}"`;
+    }
+    /**
+     * 构建文件树
+     */
+    buildFileTree(files, basePath, relativePath) {
+        const fs = require('fs');
+        const path = require('path');
+        // 递归构建树结构
+        const buildNode = (dirPath, name) => {
+            const fullPath = path.join(dirPath, name);
+            const relative = path.relative(basePath, fullPath);
+            const stat = fs.statSync(fullPath);
+            const node = {
+                name,
+                type: stat.isDirectory() ? 'dir' : 'file',
+                path: relative.replace(/\\/g, '/'),
+                size: stat.size,
+                modifiedTime: stat.mtime.toISOString(),
+            };
+            if (stat.isDirectory()) {
+                try {
+                    const entries = fs.readdirSync(fullPath);
+                    node.children = entries
+                        .filter((entry) => !entry.startsWith('.'))
+                        .map((entry) => buildNode(fullPath, entry))
+                        .sort((a, b) => {
+                        // 目录优先，然后按名称排序
+                        if (a.type !== b.type) {
+                            return a.type === 'dir' ? -1 : 1;
+                        }
+                        return a.name.localeCompare(b.name);
+                    });
+                }
+                catch (error) {
+                    node.children = [];
+                }
+            }
+            return node;
+        };
+        return buildNode(basePath, relativePath);
+    }
+}
+exports.SandboxFileManager = SandboxFileManager;

package/dist/core/skills/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Skills 核心类型定义
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 类型定义清晰，职责单一
+ * - 模块化: 类型独立，易于维护和扩展
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/core/skills/xml-generator.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Skills 元数据XML生成器
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责生成XML格式的skills元数据
+ * - 模块化: 单一职责，易于测试和维护
+ * - 兼容: 完全兼容openskills项目的XML格式
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSkillsMetadataXml = generateSkillsMetadataXml;
+/**
+ * 生成skills元数据XML格式（参考openskills）
+ */
+function generateSkillsMetadataXml(skills) {
+    if (skills.length === 0) {
+        return '';
+    }
+    const skillTags = skills
+        .map(s => `<skill>
+<name>${escapeXml(s.name)}</name>
+<description>${escapeXml(s.description)}</description>
+<location>project</location>
+</skill>`)
+        .join('\n\n');
+    return `
+<skills_system priority="1">
+
+## Available Skills
+
+<!-- SKILLS_TABLE_START -->
+<usage>
+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+How to use skills:
+- Invoke: skills(action="load", skill_name="<skill-name>")
+- The skill content will load with detailed instructions on how to complete the task
+- Base directory provided in output for resolving bundled resources (references/, scripts/, assets/)
+
+Hot Reload:
+- Each time you reload a known skill, it will load the latest state of the skill information
+- To load a skill, invoke: skills(action="load", skill_name="<skill-name>")
+- The skill content will be loaded with the latest state from the skills directory
+
+Usage notes:
+- Only use skills listed in <available_skills> below
+- Do not invoke a skill that is already loaded in your context
+- Each skill invocation is stateless
+</usage>
+
+<available_skills>
+
+${skillTags}
+
+</available_skills>
+<!-- SKILLS_TABLE_END -->
+
+</skills_system>`;
+}
+/**
+ * 转义XML特殊字符
+ */
+function escapeXml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}

package/dist/core/template.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTemplateRegistry = void 0;
+class AgentTemplateRegistry {
+    constructor() {
+        this.templates = new Map();
+    }
+    register(template) {
+        if (!template.id)
+            throw new Error('Template id is required');
+        if (!template.systemPrompt || !template.systemPrompt.trim()) {
+            throw new Error(`Template ${template.id} must provide a non-empty systemPrompt`);
+        }
+        this.templates.set(template.id, template);
+    }
+    bulkRegister(templates) {
+        for (const tpl of templates) {
+            this.register(tpl);
+        }
+    }
+    has(id) {
+        return this.templates.has(id);
+    }
+    get(id) {
+        const tpl = this.templates.get(id);
+        if (!tpl) {
+            throw new Error(`Template not found: ${id}`);
+        }
+        return tpl;
+    }
+    list() {
+        return Array.from(this.templates.values());
+    }
+}
+exports.AgentTemplateRegistry = AgentTemplateRegistry;