@shareai-lab/kode-sdk 2.7.2 → 2.7.4

package/README.md

@@ -10,7 +10,7 @@
 - **Long-Running & Resumable** - Seven-stage checkpoints with Safe-Fork-Point for crash recovery
 - **Multi-Agent Collaboration** - AgentPool, Room messaging, and task delegation
 - **Enterprise Persistence** - SQLite/PostgreSQL support with unified WAL
-- **Cloud Sandbox** - [E2B](https://e2b.dev) integration for isolated remote code execution
+- **Cloud Sandbox** - [E2B](https://e2b.dev) and OpenSandbox integration for isolated remote code execution
 - **Extensible Ecosystem** - MCP tools, custom Providers, Skills system
 
 ## Quick Start
@@ -79,6 +79,15 @@ npm run example:getting-started    # Minimal chat
 npm run example:agent-inbox        # Event-driven inbox
 npm run example:approval           # Tool approval workflow
 npm run example:room               # Multi-agent collaboration
+npm run example:opensandbox        # OpenSandbox basic usage
+```
+
+OpenSandbox quick config:
+
+```bash
+export OPEN_SANDBOX_API_KEY=...                      # optional (required only when auth is enabled)
+export OPEN_SANDBOX_ENDPOINT=http://127.0.0.1:8080  # optional
+export OPEN_SANDBOX_IMAGE=ubuntu                     # optional
 ```
 
 ## Architecture for Scale
@@ -142,9 +151,14 @@ See [docs/en/guides/architecture.md](./docs/en/guides/architecture.md) for detai
 | **Guides** | |
 | [Events](./docs/en/guides/events.md) | Three-channel event system |
 | [Tools](./docs/en/guides/tools.md) | Built-in tools & custom tools |
+| [E2B Sandbox](./docs/en/guides/e2b-sandbox.md) | E2B cloud sandbox integration |
+| [OpenSandbox](./docs/en/guides/opensandbox-sandbox.md) | OpenSandbox self-hosted sandbox integration |
+| [Skills](./docs/en/guides/skills.md) | Skills system for reusable prompts |
 | [Providers](./docs/en/guides/providers.md) | Model provider configuration |
 | [Database](./docs/en/guides/database.md) | SQLite/PostgreSQL persistence |
 | [Resume & Fork](./docs/en/guides/resume-fork.md) | Crash recovery & branching |
+| **Project** | |
+| [Contribution Guide](./docs/en/contribution.md) | How to contribute |
 | **Reference** | |
 | [API Reference](./docs/en/reference/api.md) | Complete API documentation |
 | [Examples](./docs/en/examples/playbooks.md) | All examples explained |

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 - **长时运行与恢复** - 七段断点机制，支持 Safe-Fork-Point 崩溃恢复
 - **多 Agent 协作** - AgentPool、Room 消息、任务委派
 - **企业级持久化** - 支持 SQLite/PostgreSQL，统一 WAL 日志
-- **云端沙箱** - 集成 [E2B](https://e2b.dev)，提供隔离的远程代码执行环境
+- **云端沙箱** - 集成 [E2B](https://e2b.dev) 与 OpenSandbox，提供隔离的远程代码执行环境
 - **可扩展生态** - MCP 工具、自定义 Provider、Skills 系统
 
 ## 快速开始
@@ -79,6 +79,15 @@ npm run example:getting-started    # 最简对话
 npm run example:agent-inbox        # 事件驱动收件箱
 npm run example:approval           # 工具审批流程
 npm run example:room               # 多Agent协作
+npm run example:opensandbox        # OpenSandbox 基础使用
+```
+
+OpenSandbox 快速配置：
+
+```bash
+export OPEN_SANDBOX_API_KEY=...                      # 可选（仅在服务开启鉴权时需要）
+export OPEN_SANDBOX_ENDPOINT=http://127.0.0.1:8080  # 可选
+export OPEN_SANDBOX_IMAGE=ubuntu                     # 可选
 ```
 
 ## 支持的 Provider
@@ -102,9 +111,14 @@ npm run example:room               # 多Agent协作
 | **使用指南** | |
 | [事件系统](./docs/zh-CN/guides/events.md) | 三通道事件系统 |
 | [工具系统](./docs/zh-CN/guides/tools.md) | 内置工具与自定义工具 |
+| [E2B 沙箱](./docs/zh-CN/guides/e2b-sandbox.md) | E2B 云端沙箱接入 |
+| [OpenSandbox 沙箱](./docs/zh-CN/guides/opensandbox-sandbox.md) | OpenSandbox 自托管沙箱接入 |
+| [Skills 系统](./docs/zh-CN/guides/skills.md) | Skills 可复用提示词系统 |
 | [Provider 配置](./docs/zh-CN/guides/providers.md) | 模型 Provider 配置 |
 | [数据库存储](./docs/zh-CN/guides/database.md) | SQLite/PostgreSQL 持久化 |
 | [恢复与分叉](./docs/zh-CN/guides/resume-fork.md) | 崩溃恢复与分支 |
+| **项目** | |
+| [贡献指南](./docs/zh-CN/contribution.md) | 提交 PR 的要求与流程 |
 | **参考** | |
 | [API 参考](./docs/zh-CN/reference/api.md) | 完整 API 文档 |
 | [示例集](./docs/zh-CN/examples/playbooks.md) | 所有示例详解 |

package/dist/core/agent.d.ts

@@ -9,6 +9,7 @@ import { SandboxFactory } from '../infra/sandbox-factory';
 import { ModelProvider, ModelConfig } from '../infra/provider';
 import { ToolRegistry, ToolInstance, ToolDescriptor } from '../tools/registry';
 import { ContextManagerOptions } from './context-manager';
+import { ResumeError } from './errors';
 import { SendOptions as QueueSendOptions } from './agent/message-queue';
 export interface ModelFactory {
     (config: ModelConfig): ModelProvider;
@@ -180,6 +181,12 @@ export declare class Agent {
         strategy?: ResumeStrategy;
         overrides?: Partial<AgentConfig>;
     }): Promise<Agent>;
+    static resumeOrCreate(agentId: string, config: AgentConfig, deps: AgentDependencies, opts?: {
+        autoRun?: boolean;
+        strategy?: ResumeStrategy;
+        overrides?: Partial<AgentConfig>;
+        onCorrupted?: (agentId: string, error: ResumeError) => Promise<void> | void;
+    }): Promise<Agent>;
     private ensureProcessing;
     private runStep;
     private executeTools;

package/dist/core/agent.js

@@ -195,12 +195,22 @@ class Agent {
             config.agentId = Agent.generateAgentId();
         }
         const template = deps.templateRegistry.get(config.templateId);
-        const sandboxConfig = config.sandbox && 'kind' in config.sandbox
+        const sandboxConfigSource = config.sandbox && 'kind' in config.sandbox
             ? config.sandbox
             : template.sandbox;
+        const sandboxConfig = sandboxConfigSource
+            ? { ...sandboxConfigSource }
+            : undefined;
         const sandbox = typeof config.sandbox === 'object' && 'exec' in config.sandbox
             ? config.sandbox
-            : deps.sandboxFactory.create(sandboxConfig || { kind: 'local', workDir: process.cwd() });
+            : await deps.sandboxFactory.createAsync(sandboxConfig || { kind: 'local', workDir: process.cwd() });
+        // OpenSandbox creates sandbox id at runtime; persist it for strict resume.
+        if (sandboxConfig?.kind === 'opensandbox' && typeof sandbox.getSandboxId === 'function') {
+            const sandboxId = sandbox.getSandboxId();
+            if (sandboxId) {
+                sandboxConfig.sandboxId = sandboxId;
+            }
+        }
         const model = config.model
             ? config.model
             : config.modelConfig
@@ -541,7 +551,7 @@ class Agent {
         }
         let sandbox;
         try {
-            sandbox = deps.sandboxFactory.create(metadata.sandboxConfig || { kind: 'local', workDir: process.cwd() });
+            sandbox = await deps.sandboxFactory.createAsync(metadata.sandboxConfig || { kind: 'local', workDir: process.cwd() });
         }
         catch (error) {
             throw new errors_1.ResumeError('SANDBOX_INIT_FAILED', error?.message || 'Failed to create sandbox');
@@ -653,6 +663,30 @@ class Agent {
         const overrides = opts?.overrides ?? {};
         return Agent.resume(agentId, { ...baseConfig, ...overrides }, deps, opts);
     }
+    static async resumeOrCreate(agentId, config, deps, opts) {
+        try {
+            return await Agent.resumeFromStore(agentId, deps, opts);
+        }
+        catch (error) {
+            if (!(error instanceof errors_1.ResumeError)) {
+                throw error;
+            }
+            switch (error.code) {
+                case 'AGENT_NOT_FOUND':
+                    return Agent.create({ ...config, agentId }, deps);
+                case 'CORRUPTED_DATA': {
+                    if (opts?.onCorrupted) {
+                        await opts.onCorrupted(agentId, error);
+                    }
+                    const store = Agent.requireStore(deps);
+                    await store.delete(agentId);
+                    return Agent.create({ ...config, agentId }, deps);
+                }
+                default:
+                    throw error;
+            }
+        }
+    }
     ensureProcessing() {
         // 检查是否超时
         if (this.processingPromise) {
@@ -1231,7 +1265,7 @@ class Agent {
             'application/pdf',
         ];
         for (const block of blocks) {
-            if (block.type === 'image' || block.type === 'audio' || block.type === 'file') {
+            if (block.type === 'image' || block.type === 'audio' || block.type === 'video' || block.type === 'file') {
                 const url = block.url;
                 const fileId = block.file_id;
                 const base64 = block.base64;
@@ -1277,12 +1311,81 @@ class Agent {
     }
     async resolveMultimodalBlocks(blocks) {
         const model = this.model;
-        if (typeof model.uploadFile !== 'function') {
-            return blocks;
-        }
-        const provider = this.model.toConfig().provider;
+        const config = this.model.toConfig();
+        const provider = config.provider;
+        const multimodal = config.multimodal || {};
+        // Check provider capabilities for audio/video
+        const supportsAudio = provider === 'gemini' || provider === 'openai';
+        const supportsVideo = provider === 'gemini';
         const resolved = [];
         for (const block of blocks) {
+            // Handle audio block with callback fallback
+            if (block.type === 'audio') {
+                if (!supportsAudio && multimodal.audio?.customTranscriber) {
+                    try {
+                        const transcript = await multimodal.audio.customTranscriber({
+                            base64: block.base64,
+                            url: block.url,
+                            mimeType: block.mime_type,
+                        });
+                        resolved.push({ type: 'text', text: `[Audio Transcript]: ${transcript}` });
+                        continue;
+                    }
+                    catch (error) {
+                        this.events.emitMonitor({
+                            channel: 'monitor',
+                            type: 'error',
+                            severity: 'warn',
+                            phase: 'system',
+                            message: 'audio transcription failed, falling back to placeholder',
+                            detail: { error: error?.message || String(error) },
+                        });
+                    }
+                }
+                // If supported or no callback, pass through (provider will handle or degrade)
+                resolved.push(block);
+                continue;
+            }
+            // Handle video block with callback fallback
+            if (block.type === 'video') {
+                if (!supportsVideo && multimodal.video?.customFrameExtractor) {
+                    try {
+                        const frames = await multimodal.video.customFrameExtractor({
+                            base64: block.base64,
+                            url: block.url,
+                            mimeType: block.mime_type,
+                        });
+                        // Add all extracted frames as image blocks
+                        for (const frame of frames) {
+                            resolved.push({
+                                type: 'image',
+                                base64: frame.base64,
+                                mime_type: frame.mimeType,
+                            });
+                        }
+                        resolved.push({ type: 'text', text: `[Video: ${frames.length} frames extracted]` });
+                        continue;
+                    }
+                    catch (error) {
+                        this.events.emitMonitor({
+                            channel: 'monitor',
+                            type: 'error',
+                            severity: 'warn',
+                            phase: 'system',
+                            message: 'video frame extraction failed, falling back to placeholder',
+                            detail: { error: error?.message || String(error) },
+                        });
+                    }
+                }
+                // If supported or no callback, pass through (provider will handle or degrade)
+                resolved.push(block);
+                continue;
+            }
+            // Handle image and file uploads (existing logic)
+            if (typeof model.uploadFile !== 'function') {
+                resolved.push(block);
+                continue;
+            }
             if ((block.type === 'image' || block.type === 'file') &&
                 block.base64 &&
                 block.mime_type &&

package/dist/core/skills/management-manager.d.ts

@@ -1,120 +1,144 @@
 /**
- * 技能管理器模块（路径1 - 技能管理）
+ * 技能管理器模块(路径1 - 技能管理)
  *
  * 设计原则 (UNIX哲学):
- * - 简洁: 只负责技能文件系统的CRUD操作
- * - 模块化: 协调OperationQueue、SandboxFileManager进行文件系统操作
- * - 隔离: 与Agent运行时完全隔离，不参与Agent使用
+ * - 简洁: 只负责技能文件系统的管理操作
+ * - 模块化: 单一职责,易于测试和维护
+ * - 隔离: 与Agent运行时完全隔离,不参与Agent使用
  *
  * ⚠️ 重要说明:
- * - 此模块专门用于路径1（技能管理）
- * - 与路径2（Agent运行时）完全独立
+ * - 此模块专门用于路径1(技能管理)
+ * - 与路径2(Agent运行时)完全独立
  * - 请勿与SkillsManager混淆
+ *
+ * @see docs/skills-management-implementation-plan.md
  */
-import { OperationTask } from './operation-queue';
-import type { SkillInfo, SkillDetail, SkillFileTree, CreateSkillOptions, ArchivedSkillInfo } from './types';
-import { SandboxFactory } from '../../infra/sandbox-factory';
+import type { SkillInfo, ArchivedSkillInfo } from './types';
 /**
  * 技能管理器类
  *
  * 职责:
- * - 提供所有技能管理操作的统一接口（CRUD操作）
- * - 协调OperationQueue、SandboxFileManager进行文件系统操作
+ * - 提供所有技能管理操作的统一接口(导入、复制、重命名、归档、导出)
  * - 处理业务逻辑和权限验证
+ * - 所有操作严格遵循Specification.md规范
  * - ❌ 不参与Agent运行时
  * - ❌ 不提供技能加载、扫描等Agent使用的功能
  */
 export declare class SkillsManagementManager {
-    private skillsManager;
-    private operationQueue;
-    private sandboxFileManager;
     private skillsDir;
     private archivedDir;
-    constructor(skillsDir: string, sandboxFactory?: SandboxFactory, archivedDir?: string);
+    constructor(skillsDir: string, archivedDir?: string);
     /**
-     * 获取所有在线技能列表（不包含archived技能）
+     * 1. 列出在线技能
+     * 扫描skills目录,排除.archived子目录
+     * 返回技能清单及其元数据信息
      */
     listSkills(): Promise<SkillInfo[]>;
     /**
-     * 获取单个在线技能详细信息
-     * @param skillName 技能名称
+     * 2. 安装新技能
+     * @param source 技能来源(名称/GitHub仓库/Git URL/本地路径)
+     * @param onProgress 可选的进度回调函数，用于实时传递安装日志
+     * 执行命令: npx -y ai-agent-skills install --agent project [source]
+     * 直接安装到.skills目录
      */
-    getSkillInfo(skillName: string): Promise<SkillDetail | null>;
+    installSkill(source: string, onProgress?: (data: {
+        type: 'log' | 'error';
+        message: string;
+    }) => void): Promise<void>;
     /**
-     * 获取已归档技能列表（只读，不支持修改）
+     * 3. 列出归档技能
+     * 扫描.archived目录
+     * 返回归档技能清单及其元数据信息
      */
     listArchivedSkills(): Promise<ArchivedSkillInfo[]>;
     /**
-     * 创建新技能
+     * 4. 导入技能
+     * @param zipFilePath zip文件路径
+     * @param originalFileName 原始上传文件名（可选，用于无嵌套目录时的技能命名）
+     * 验证SKILL.md格式,解压并放置在在线技能目录中
+     *
+     * 检测逻辑：
+     * - 如果解压后根目录直接包含SKILL.md，视为无嵌套目录，使用originalFileName作为技能名称
+     * - 如果根目录不包含SKILL.md但包含多个子目录，每个子目录都有SKILL.md，则批量导入
+     */
+    importSkill(zipFilePath: string, originalFileName?: string): Promise<void>;
+    /**
+     * 5. 复制技能
      * @param skillName 技能名称
-     * @param options 技能配置（名称、描述等）
+     * 新技能名称: {原技能名称}-{XXXXXXXX}
      */
-    createSkill(skillName: string, options: CreateSkillOptions): Promise<SkillDetail>;
+    copySkill(skillName: string): Promise<string>;
     /**
-     * 重命名技能
-     * @param oldName 旧技能名称
-     * @param newName 新技能名称
+     * 6. 重命名技能
+     * @param oldName 旧技能文件夹名称
+     * @param newName 新技能文件夹名称
+     * 不支持操作归档技能
      */
     renameSkill(oldName: string, newName: string): Promise<void>;
     /**
-     * 编辑技能文件
+     * 7. 在线技能转归档
      * @param skillName 技能名称
-     * @param filePath 文件路径（相对于技能根目录，如"SKILL.md"）
-     * @param content 文件内容
-     * @param useSandbox 是否使用sandbox（默认true）
+     * 归档名称: {原技能名称}-{XXXXXXXX}
+     */
+    archiveSkill(skillName: string): Promise<void>;
+    /**
+     * 8. 归档技能转在线
+     * @param archivedSkillName archived中的技能名称(含后缀)
+     * 移入前检测重名
      */
-    editSkillFile(skillName: string, filePath: string, content: string, useSandbox?: boolean): Promise<void>;
+    unarchiveSkill(archivedSkillName: string): Promise<void>;
     /**
-     * 删除技能（移动到archived）
+     * 9. 查看在线技能内容
      * @param skillName 技能名称
+     * 返回SKILL.md完整内容(包含frontmatter和正文)
      */
-    deleteSkill(skillName: string): Promise<void>;
+    getOnlineSkillContent(skillName: string): Promise<string>;
     /**
-     * 恢复已删除的技能
-     * @param archivedSkillName archived中的技能名称（含时间戳）
+     * 10. 查看归档技能内容
+     * @param archivedSkillName 归档技能名称(含8位后缀)
+     * 返回SKILL.md完整内容(包含frontmatter和正文)
      */
-    restoreSkill(archivedSkillName: string): Promise<void>;
+    getArchivedSkillContent(archivedSkillName: string): Promise<string>;
     /**
-     * 获取技能文件树（仅在线技能）
+     * 11. 查看在线技能文件目录结构
      * @param skillName 技能名称
+     * 返回JSON格式的目录树结构
      */
-    getSkillFileTree(skillName: string): Promise<SkillFileTree>;
+    getOnlineSkillStructure(skillName: string): Promise<object>;
     /**
-     * 获取队列状态
+     * 12. 查看归档技能文件目录结构
+     * @param archivedSkillName 归档技能名称(含8位后缀)
+     * 返回JSON格式的目录树结构
      */
-    getQueueStatus(): {
-        length: number;
-        processing: boolean;
-        tasks: OperationTask[];
-    };
+    getArchivedSkillStructure(archivedSkillName: string): Promise<object>;
     /**
-     * 执行创建技能
+     * 13. 导出技能
+     * @param skillName 技能名称(在线或归档)
+     * @param isArchived 是否为归档技能
+     * 使用系统zip命令打包,放入临时目录
      */
-    private doCreateSkill;
+    exportSkill(skillName: string, isArchived: boolean): Promise<string>;
     /**
-     * 执行重命名技能
+     * 递归构建目录树
      */
-    private doRenameSkill;
+    private buildDirectoryTree;
     /**
-     * 执行编辑技能文件
+     * 解析SKILL.md的YAML frontmatter
      */
-    private doEditSkillFile;
+    private parseSkillMd;
     /**
-     * 执行删除技能
+     * 验证SKILL.md格式(遵循Specification.md规范)
      */
-    private doDeleteSkill;
+    private validateSkillMd;
     /**
-     * 执行恢复技能
+     * 生成8位随机后缀
+     * 规则: uuidv4 → sha256 → 全小写 → 取前8位
      */
-    private doRestoreSkill;
+    private generateRandomSuffix;
     /**
      * 验证技能名称
      */
     private isValidSkillName;
-    /**
-     * 生成SKILL.md内容
-     */
-    private generateSkillMd;
     /**
      * 检查文件是否存在
      */
@@ -124,7 +148,16 @@ export declare class SkillsManagementManager {
      */
     private safeGetFileStat;
     /**
-     * 等待任务完成
+     * 解压zip文件
+     */
+    private extractZip;
+    /**
+     * 跨平台的安全重命名方法
+     * Windows上使用"复制-删除"方式避免EPERM错误
+     */
+    private safeRename;
+    /**
+     * 创建zip文件
      */
-    private waitForTask;
+    private createZip;
 }