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

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.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Skills 核心类型定义
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 类型定义清晰，职责单一
+ * - 模块化: 类型独立，易于维护和扩展
+ */
+/**
+ * Skill 元数据
+ */
+export interface SkillMetadata {
+    /** skill名称 */
+    name: string;
+    /** skill描述 */
+    description: string;
+    /** SKILL.md文件路径 */
+    path: string;
+    /** skill根目录（用于解析references等） */
+    baseDir: string;
+}
+/**
+ * Skill 完整内容
+ */
+export interface SkillContent {
+    /** 元数据 */
+    metadata: SkillMetadata;
+    /** SKILL.md的markdown内容 */
+    content: string;
+    /** references目录下的文件列表 */
+    references: string[];
+    /** scripts目录下的文件列表 */
+    scripts: string[];
+    /** assets目录下的文件列表 */
+    assets: string[];
+}
+/**
+ * Sandbox 配置
+ * 参考 docs/sandbox-support-evaluation.md 中的设计
+ */
+export interface SandboxConfig {
+    /** 是否启用sandbox隔离（默认false，本地开发直接执行） */
+    enabled: boolean;
+    /** 工作目录 */
+    workDir?: string;
+    /** 是否强制边界检查 */
+    enforceBoundary?: boolean;
+    /** 允许访问的路径白名单 */
+    allowPaths?: string[];
+}
+/**
+ * 技能基本信息
+ */
+export interface SkillInfo {
+    /** 技能名称 */
+    name: string;
+    /** 技能描述 */
+    description: string;
+    /** SKILL.md路径 */
+    path: string;
+    /** 技能根目录 */
+    baseDir: string;
+    /** 创建时间 */
+    createdAt?: string;
+    /** 更新时间 */
+    updatedAt?: string;
+}
+/**
+ * 技能详细信息
+ */
+export interface SkillDetail extends SkillInfo {
+    /** 文件树结构 */
+    files: SkillFileTree;
+    /** references目录文件 */
+    references: string[];
+    /** scripts目录文件 */
+    scripts: string[];
+    /** assets目录文件 */
+    assets: string[];
+}
+/**
+ * 文件树节点
+ */
+export interface SkillFileTree {
+    /** 文件/目录名 */
+    name: string;
+    /** 类型 */
+    type: 'file' | 'dir';
+    /** 相对于技能根目录的路径 */
+    path: string;
+    /** 文件大小（字节） */
+    size?: number;
+    /** 修改时间 */
+    modifiedTime?: string;
+    /** 子节点（目录） */
+    children?: SkillFileTree[];
+}
+/**
+ * 创建技能选项
+ */
+export interface CreateSkillOptions {
+    /** 技能名称（必须与目录名一致） */
+    name: string;
+    /** 技能描述 */
+    description?: string;
+    /** 模板类型 */
+    template?: 'basic' | 'advanced';
+}
+/**
+ * Archived技能信息
+ */
+export interface ArchivedSkillInfo {
+    /** 原始技能名称 */
+    originalName: string;
+    /** archived目录中的名称（含时间戳） */
+    archivedName: string;
+    /** archived目录中的完整路径 */
+    archivedPath: string;
+    /** 归档时间 */
+    archivedAt: string;
+}

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.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Skills 元数据XML生成器
+ *
+ * 设计原则 (UNIX哲学):
+ * - 简洁: 只负责生成XML格式的skills元数据
+ * - 模块化: 单一职责，易于测试和维护
+ * - 兼容: 完全兼容openskills项目的XML格式
+ */
+import type { SkillMetadata } from './types';
+/**
+ * 生成skills元数据XML格式（参考openskills）
+ */
+export declare function generateSkillsMetadataXml(skills: SkillMetadata[]): string;

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.d.ts

@@ -0,0 +1,57 @@
+import { Hooks } from './hooks';
+export type PermissionDecisionMode = 'auto' | 'approval' | 'readonly' | (string & {});
+export interface PermissionConfig {
+    mode: PermissionDecisionMode;
+    requireApprovalTools?: string[];
+    allowTools?: string[];
+    denyTools?: string[];
+    metadata?: Record<string, any>;
+}
+export interface SubAgentConfig {
+    templates?: string[];
+    depth: number;
+    inheritConfig?: boolean;
+    overrides?: {
+        permission?: PermissionConfig;
+        todo?: TodoConfig;
+    };
+}
+export interface TodoConfig {
+    enabled: boolean;
+    remindIntervalSteps?: number;
+    storagePath?: string;
+    reminderOnStart?: boolean;
+}
+export interface AgentTemplateDefinition {
+    id: string;
+    name?: string;
+    desc?: string;
+    version?: string;
+    systemPrompt: string;
+    model?: string;
+    sandbox?: Record<string, any>;
+    tools?: '*' | string[];
+    permission?: PermissionConfig;
+    runtime?: TemplateRuntimeConfig;
+    hooks?: Hooks;
+    metadata?: Record<string, any>;
+}
+export interface TemplateRuntimeConfig {
+    exposeThinking?: boolean;
+    retainThinking?: boolean;
+    multimodalContinuation?: 'history';
+    multimodalRetention?: {
+        keepRecent?: number;
+    };
+    todo?: TodoConfig;
+    subagents?: SubAgentConfig;
+    metadata?: Record<string, any>;
+}
+export declare class AgentTemplateRegistry {
+    private templates;
+    register(template: AgentTemplateDefinition): void;
+    bulkRegister(templates: AgentTemplateDefinition[]): void;
+    has(id: string): boolean;
+    get(id: string): AgentTemplateDefinition;
+    list(): AgentTemplateDefinition[];
+}

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;

package/dist/core/time-bridge.d.ts

@@ -0,0 +1,18 @@
+import { Scheduler } from './scheduler';
+export interface TimeBridgeOptions {
+    scheduler: Scheduler;
+    driftToleranceMs?: number;
+    logger?: (msg: string, meta?: Record<string, any>) => void;
+}
+export declare class TimeBridge {
+    private readonly scheduler;
+    private readonly driftTolerance;
+    private readonly logger?;
+    private readonly timers;
+    constructor(opts: TimeBridgeOptions);
+    everyMinutes(minutes: number, callback: () => void | Promise<void>): string;
+    cron(expr: string, callback: () => void | Promise<void>): string;
+    stop(timerId: string): void;
+    dispose(): void;
+    private generateId;
+}

package/dist/core/time-bridge.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeBridge = void 0;
+class TimeBridge {
+    constructor(opts) {
+        this.timers = new Map();
+        this.scheduler = opts.scheduler;
+        this.driftTolerance = opts.driftToleranceMs ?? 5000;
+        this.logger = opts.logger;
+    }
+    everyMinutes(minutes, callback) {
+        if (!Number.isFinite(minutes) || minutes <= 0) {
+            throw new Error('everyMinutes: interval must be positive');
+        }
+        const interval = minutes * 60 * 1000;
+        const id = this.generateId('minutes');
+        const scheduleNext = () => {
+            const due = Date.now() + interval;
+            const handle = setTimeout(() => tick(due), interval);
+            entry.cancel = () => clearTimeout(handle);
+        };
+        const spec = `every:${minutes}m`;
+        const tick = (due) => {
+            this.scheduler.enqueue(async () => {
+                const drift = Math.abs(Date.now() - due);
+                if (drift > this.driftTolerance) {
+                    this.logger?.('timebridge:drift', { id, drift, expectedInterval: interval });
+                }
+                await callback();
+                this.scheduler.notifyExternalTrigger({ taskId: id, spec, kind: 'time' });
+            });
+            scheduleNext();
+        };
+        const entry = {
+            id,
+            cancel: () => undefined,
+        };
+        this.timers.set(id, entry);
+        scheduleNext();
+        return id;
+    }
+    cron(expr, callback) {
+        const parts = expr.trim().split(/\s+/);
+        if (parts.length !== 5) {
+            throw new Error(`Unsupported cron expression: ${expr}`);
+        }
+        const minute = Number(parts[0]);
+        const hour = Number(parts[1]);
+        if (!Number.isInteger(minute) || !Number.isInteger(hour)) {
+            throw new Error(`Cron expression must be numeric minutes/hours: ${expr}`);
+        }
+        const id = this.generateId('cron');
+        const scheduleNext = () => {
+            const now = new Date();
+            const next = new Date(now.getFullYear(), now.getMonth(), now.getDate(), hour, minute, 0, 0);
+            if (next <= now) {
+                next.setDate(next.getDate() + 1);
+            }
+            const due = next.getTime();
+            const delay = Math.max(0, due - Date.now());
+            const handle = setTimeout(() => tick(due), delay);
+            entry.cancel = () => clearTimeout(handle);
+        };
+        const tick = (due) => {
+            this.scheduler.enqueue(async () => {
+                const drift = Math.abs(Date.now() - due);
+                if (drift > this.driftTolerance) {
+                    this.logger?.('timebridge:drift', { id, drift, spec: expr });
+                }
+                await callback();
+                this.scheduler.notifyExternalTrigger({ taskId: id, spec: expr, kind: 'cron' });
+            });
+            scheduleNext();
+        };
+        const entry = {
+            id,
+            cancel: () => undefined,
+        };
+        this.timers.set(id, entry);
+        scheduleNext();
+        return id;
+    }
+    stop(timerId) {
+        const entry = this.timers.get(timerId);
+        if (!entry)
+            return;
+        entry.cancel();
+        this.timers.delete(timerId);
+    }
+    dispose() {
+        for (const entry of this.timers.values()) {
+            entry.cancel();
+        }
+        this.timers.clear();
+    }
+    generateId(prefix) {
+        return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    }
+}
+exports.TimeBridge = TimeBridge;

package/dist/core/todo.d.ts

@@ -0,0 +1,34 @@
+import { Store } from '../infra/store';
+export type TodoStatus = 'pending' | 'in_progress' | 'completed';
+export interface TodoItem {
+    id: string;
+    title: string;
+    status: TodoStatus;
+    assignee?: string;
+    notes?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface TodoSnapshot {
+    todos: TodoItem[];
+    version: number;
+    updatedAt: number;
+}
+export type TodoInput = Omit<TodoItem, 'createdAt' | 'updatedAt'> & {
+    createdAt?: number;
+    updatedAt?: number;
+};
+export declare class TodoService {
+    private readonly store;
+    private readonly agentId;
+    private snapshot;
+    constructor(store: Store, agentId: string);
+    load(): Promise<void>;
+    list(): TodoItem[];
+    setTodos(todos: TodoInput[]): Promise<void>;
+    update(todo: TodoInput): Promise<void>;
+    delete(id: string): Promise<void>;
+    private validateTodos;
+    private persist;
+    private normalize;
+}