@lcap/wave-sandbox-sdk 0.0.1

package/src/modules/file-system.ts

@@ -0,0 +1,212 @@
+import type { Socket } from 'socket.io-client';
+import { createSocketHandler, onSocketEvent } from '../utils/socket.js';
+import type { FileStat, DirectoryItem, FileChangeEvent, HttpResponse } from '../types/index.js';
+
+/**
+ * 文件系统模块
+ */
+export class FileSystemModule {
+  constructor(
+    private socket: Socket,
+    private baseUrl: string,
+    private projectId?: string
+  ) {}
+
+  /**
+   * 获取查询参数
+   */
+  private getQueryParams(filePath: string): string {
+    const params = new URLSearchParams({ filePath });
+    if (this.projectId) {
+      params.set('projectId', this.projectId);
+    }
+    return params.toString();
+  }
+
+  /**
+   * 获取文件状态
+   */
+  async stat(filePath: string): Promise<FileStat> {
+    const url = `${this.baseUrl}/api/fs/stat?${this.getQueryParams(filePath)}`;
+    const response = await fetch(url);
+    const result: HttpResponse<FileStat> = await response.json();
+
+    if (result.status === 'error') {
+      throw new Error(result.message);
+    }
+
+    return result.data;
+  }
+
+  /**
+   * 读取文件
+   * @param filePath 文件路径
+   * @param asText 是否以文本形式读取，默认 false（返回 Blob）
+   * @returns Promise<string | Blob> 文件内容
+   */
+  async read(filePath: string, asText: false): Promise<Blob>;
+  async read(filePath: string, asText: true): Promise<string>;
+  async read(filePath: string, asText: boolean = false): Promise<string | Blob> {
+    if (asText) {
+      // 使用 readFile 端点获取文本内容
+      const url = `${this.baseUrl}/api/fs/readFile?${this.getQueryParams(filePath)}`;
+      const response = await fetch(url);
+      const result: HttpResponse<string> = await response.json();
+
+      if (result.status === 'error') {
+        throw new Error(result.message);
+      }
+
+      return result.data;
+    } else {
+      // 使用 read 端点获取原始文件（支持二进制）
+      const url = `${this.baseUrl}/api/fs/read?${this.getQueryParams(filePath)}`;
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Failed to read file: ${response.statusText}`);
+      }
+      return response.blob();
+    }
+  }
+
+  /**
+   * 读取文件内容（文本形式）
+   * @param filePath 文件路径
+   * @returns Promise<string> 文件文本内容
+   */
+  async readFile(filePath: string): Promise<string> {
+    return this.read(filePath, true);
+  }
+
+  /**
+   * 读取目录
+   */
+  async readdir(filePath: string): Promise<DirectoryItem[]> {
+    const url = `${this.baseUrl}/api/fs/readdir?${this.getQueryParams(filePath)}`;
+    const response = await fetch(url);
+    const result: HttpResponse<DirectoryItem[]> = await response.json();
+
+    if (result.status === 'error') {
+      throw new Error(result.message);
+    }
+
+    return result.data;
+  }
+
+  /**
+   * 写入文件（流式）
+   * @param filePath 文件路径
+   * @param data 文件数据（可以是字符串、Blob、ArrayBuffer 或 Buffer）
+   * @param chunkSize 分块大小（字节），默认 64KB
+   */
+  async writeFile(
+    filePath: string,
+    data: string | Blob | ArrayBuffer | Uint8Array,
+    chunkSize: number = 64 * 1024
+  ): Promise<void> {
+    // 开始写入
+    const { taskId } = await createSocketHandler<{ filePath: string }, { taskId: string }>(
+      this.socket,
+      'fs:writeFileStart',
+      () => ({ filePath })
+    );
+
+    try {
+      // 将数据转换为 Uint8Array
+      let buffer: Uint8Array;
+      if (typeof data === 'string') {
+        buffer = new TextEncoder().encode(data);
+      } else if (data instanceof Blob) {
+        const arrayBuffer = await data.arrayBuffer();
+        buffer = new Uint8Array(arrayBuffer);
+      } else if (data instanceof ArrayBuffer) {
+        buffer = new Uint8Array(data);
+      } else {
+        buffer = data;
+      }
+
+      // 分块发送数据
+      for (let i = 0; i < buffer.length; i += chunkSize) {
+        const chunk = buffer.slice(i, i + chunkSize);
+        // 将 Uint8Array 转换为 ArrayBuffer，Socket.IO 会自动处理
+        await createSocketHandler<{ taskId: string; chunk: Uint8Array }, void>(
+          this.socket,
+          'fs:writeFileChunk',
+          () => ({ taskId, chunk })
+        );
+      }
+
+      // 结束写入
+      await createSocketHandler<{ taskId: string }, void>(this.socket, 'fs:writeFileEnd', () => ({ taskId }));
+    } catch (error) {
+      // 如果出错，尝试结束写入以清理资源
+      try {
+        await createSocketHandler<{ taskId: string }, void>(this.socket, 'fs:writeFileEnd', () => ({ taskId }));
+      } catch {
+        // 忽略清理错误
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * 创建目录
+   */
+  async mkdir(filePath: string): Promise<string | undefined> {
+    return createSocketHandler<{ filePath: string }, string | undefined>(this.socket, 'fs:mkdir', () => ({ filePath }));
+  }
+
+  /**
+   * 重命名文件或目录
+   */
+  async rename(oldPath: string, newPath: string): Promise<void> {
+    return createSocketHandler<{ oldPath: string; newPath: string }, void>(this.socket, 'fs:rename', () => ({
+      oldPath,
+      newPath,
+    }));
+  }
+
+  /**
+   * 删除文件或目录
+   */
+  async rm(filePath: string): Promise<void> {
+    return createSocketHandler<{ filePath: string }, void>(this.socket, 'fs:rm', () => ({ filePath }));
+  }
+
+  /**
+   * 监听文件变化
+   * @param paths 要监听的文件路径数组
+   * @param ignored 要忽略的文件路径数组
+   * @param callback 文件变化回调函数
+   * @returns 取消监听的函数
+   */
+  watch(paths: string[], ignored: string[] = [], callback: (event: FileChangeEvent) => void): () => void {
+    let taskId: string | null = null;
+
+    // 启动监听
+    createSocketHandler<{ paths: string[]; ignored: string[] }, { taskId: string }>(this.socket, 'fs:watch', () => ({
+      paths,
+      ignored,
+    }))
+      .then((result) => {
+        taskId = result.taskId;
+        // 监听文件变化事件
+        const eventName = `fs:file-change:${taskId}`;
+        onSocketEvent<FileChangeEvent>(this.socket, eventName, callback);
+      })
+      .catch((error) => {
+        console.error('Failed to start file watch:', error);
+      });
+
+    // 返回取消监听的函数
+    return () => {
+      if (taskId) {
+        createSocketHandler<{ taskId: string }, void>(this.socket, 'fs:unwatch', () => ({ taskId: taskId! })).catch(
+          (error) => {
+            console.error('Failed to stop file watch:', error);
+          }
+        );
+      }
+    };
+  }
+}

package/src/modules/port.ts

@@ -0,0 +1,47 @@
+import type { Socket } from 'socket.io-client';
+import { createSocketHandler, onSocketEvent } from '../utils/socket.js';
+import type { PortStatusChangedEvent } from '../types/index.js';
+
+/**
+ * 端口监听模块
+ */
+export class PortModule {
+  constructor(private socket: Socket) {}
+
+  /**
+   * 获取可用端口
+   * @param count 需要获取的端口数量，默认 2
+   * @returns Promise<number[]> 可用端口数组
+   */
+  async getPorts(count: number = 2): Promise<number[]> {
+    const result = await createSocketHandler<{ count?: number }, { ports: number[] }>(this.socket, 'port:find', () => ({
+      count,
+    }));
+
+    return result.ports;
+  }
+
+  /**
+   * 开始监听端口状态
+   * @param ports 要监听的端口数组
+   */
+  async startWatch(ports: number[]): Promise<void> {
+    return createSocketHandler<{ ports: number[] }, void>(this.socket, 'port:watch', () => ({ ports }));
+  }
+
+  /**
+   * 停止监听端口状态
+   */
+  async stopWatch(): Promise<void> {
+    return createSocketHandler<void, void>(this.socket, 'port:unwatch', () => undefined);
+  }
+
+  /**
+   * 监听端口状态变化
+   * @param callback 端口状态变化回调函数
+   * @returns 取消监听的函数
+   */
+  onStatusChanged(callback: (event: PortStatusChangedEvent) => void): () => void {
+    return onSocketEvent<PortStatusChangedEvent>(this.socket, 'portStatusChanged', callback);
+  }
+}

package/src/modules/project.ts

@@ -0,0 +1,77 @@
+import type { Socket } from 'socket.io-client';
+import { createSocketHandler, onSocketEvent } from '../utils/socket.js';
+import type { ProjectInfo, ProjectFile, HttpResponse, FileChangeEvent } from '../types/index.js';
+
+/**
+ * 项目模块
+ */
+export class ProjectModule {
+  constructor(
+    private socket: Socket,
+    private baseUrl: string,
+    private projectId?: string
+  ) {}
+
+  /**
+   * 获取查询参数
+   */
+  private getQueryParams(): string {
+    if (this.projectId) {
+      return `projectId=${encodeURIComponent(this.projectId)}`;
+    }
+    return '';
+  }
+
+  /**
+   * 获取项目信息
+   */
+  async getInfo(): Promise<ProjectInfo> {
+    const url = `${this.baseUrl}/project/info${this.projectId ? `?${this.getQueryParams()}` : ''}`;
+    const response = await fetch(url);
+    const result: HttpResponse<ProjectInfo> = await response.json();
+
+    if (result.status === 'error') {
+      throw new Error(result.message);
+    }
+
+    return result.data;
+  }
+
+  /**
+   * 获取项目文件列表
+   */
+  async getFiles(): Promise<ProjectFile[]> {
+    const url = `${this.baseUrl}/project/files${this.projectId ? `?${this.getQueryParams()}` : ''}`;
+    const response = await fetch(url);
+    const result: HttpResponse<{ files: ProjectFile[] }> = await response.json();
+
+    if (result.status === 'error') {
+      throw new Error(result.message);
+    }
+
+    return result.data.files;
+  }
+
+  /**
+   * 开始监听项目变化
+   */
+  async watch(): Promise<void> {
+    return createSocketHandler<void, void>(this.socket, 'project:watch', () => undefined);
+  }
+
+  /**
+   * 停止监听项目变化
+   */
+  async unwatch(): Promise<void> {
+    return createSocketHandler<void, void>(this.socket, 'project:unwatch', () => undefined);
+  }
+
+  /**
+   * 监听项目文件变化
+   * @param callback 文件变化回调函数
+   * @returns 取消监听的函数
+   */
+  onFileChange(callback: (event: FileChangeEvent) => void): () => void {
+    return onSocketEvent<FileChangeEvent>(this.socket, 'project:file-change', callback);
+  }
+}

package/src/types/agent-types.ts

@@ -0,0 +1,140 @@
+/**
+ * Agent 消息块类型
+ * 这些类型原本来自 wave-agent-sdk，现在复制到项目中以避免外部依赖
+ */
+
+/**
+ * 文本块
+ */
+export interface TextBlock {
+  type: 'text';
+  content: string;
+  customCommandContent?: string;
+  source?: 'user' | 'hook';
+}
+
+/**
+ * 工具块
+ */
+export interface ToolBlock {
+  type: 'tool';
+  parameters?: string;
+  result?: string;
+  shortResult?: string;
+  images?: Array<{
+    data: string;
+    mediaType?: string;
+  }>;
+  id?: string;
+  name?: string;
+  /**
+   * Tool execution stage:
+   * - 'start': Tool call initiated (from AI service streaming)
+   * - 'streaming': Tool parameters being streamed (from AI service)
+   * - 'running': Tool execution in progress (from AI manager)
+   * - 'end': Tool execution completed (from AI manager)
+   */
+  stage: 'start' | 'streaming' | 'running' | 'end';
+  success?: boolean;
+  error?: string | Error;
+  compactParams?: string;
+  parametersChunk?: string;
+}
+
+/**
+ * 错误块
+ */
+export interface ErrorBlock {
+  type: 'error';
+  content: string;
+}
+
+export interface SubagentConfiguration {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  systemPrompt: string;
+  filePath: string;
+  scope: 'project' | 'user';
+  priority: number;
+}
+
+/**
+ * 子代理块
+ */
+export interface SubagentBlock {
+  type: 'subagent';
+  subagentId: string;
+  subagentName: string;
+  status: 'active' | 'completed' | 'error' | 'aborted';
+  configuration: SubagentConfiguration;
+  blocks: AssistantBlock[];
+}
+
+/**
+ * MCP 服务器配置
+ */
+export interface McpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+/**
+ * MCP 服务器状态
+ */
+export interface McpServerStatus {
+  name: string;
+  config: McpServerConfig;
+  status: 'disconnected' | 'connected' | 'connecting' | 'error';
+  tools?: Array<{
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+  }>;
+  toolCount?: number;
+  capabilities?: string[];
+  lastConnected?: number;
+  error?: string;
+}
+
+/**
+ * 附件接口
+ */
+export interface Attachment {
+  url?: string;
+  path?: string;
+  mimeType: string;
+  content?: string;
+}
+
+/**
+ * 发送消息选项
+ */
+export interface SendMessageOptions {
+  id: string;
+  sessionId: string;
+  message: string;
+  attachments?: Attachment[];
+}
+
+export interface UserMessage {
+  role: 'user';
+  id: string;
+  content: string;
+  attachments?: Attachment[];
+  lastModified?: number;
+}
+
+export type AssistantBlock = TextBlock | ToolBlock | ErrorBlock | SubagentBlock;
+
+export interface AssistantMessage {
+  role: 'assistant';
+  id: string;
+  blocks: AssistantBlock[];
+  status: 'pending' | 'running' | 'finished' | 'error' | 'aborted';
+  lastModified?: number;
+}
+
+export type ChatMessage = UserMessage | AssistantMessage;

package/src/types/index.ts

@@ -0,0 +1,136 @@
+/**
+ * HTTP API 响应类型
+ */
+export interface HttpSuccessResponse<T = unknown> {
+  status: 'ok';
+  data: T;
+}
+
+export interface HttpErrorResponse {
+  status: 'error';
+  message: string;
+}
+
+export type HttpResponse<T = unknown> = HttpSuccessResponse<T> | HttpErrorResponse;
+
+/**
+ * Socket API 响应类型
+ */
+export interface SocketSuccessResponse<T = unknown> {
+  success: true;
+  data: T;
+}
+
+export interface SocketErrorResponse {
+  success: false;
+  errorMessage: string;
+}
+
+export type SocketResponse<T = unknown> = SocketSuccessResponse<T> | SocketErrorResponse;
+
+/**
+ * 文件类型
+ */
+export enum FileType {
+  Unknown = 0,
+  File = 1,
+  Directory = 2,
+  SymbolicLink = 64,
+}
+
+/**
+ * 文件状态信息
+ */
+export interface FileStat {
+  type: FileType;
+  size: number;
+  ctime: number;
+  mtime: number;
+}
+
+/**
+ * 目录项
+ */
+export type DirectoryItem = [string, FileType];
+
+/**
+ * 文件变化事件类型
+ */
+export type FileChangeType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir';
+
+/**
+ * 文件变化事件
+ */
+export interface FileChangeEvent {
+  type: FileChangeType;
+  path: string;
+  /** 是否为二进制文件（仅在 add 和 change 事件中存在） */
+  isBinary?: boolean;
+}
+
+/**
+ * 端口状态类型
+ */
+export type PortStatusType = 'open' | 'close';
+
+/**
+ * 端口状态变化事件
+ */
+export interface PortStatusChangedEvent {
+  port: number;
+  type: PortStatusType;
+}
+
+/**
+ * 项目信息
+ */
+export interface ProjectInfo {
+  projectId: string;
+  workdir: string;
+  workspace: boolean;
+}
+
+/**
+ * 项目文件信息
+ */
+export interface ProjectFile {
+  path: string;
+  // 可以根据实际需要添加更多字段
+}
+
+/**
+ * SDK 配置选项
+ */
+export interface SDKOptions {
+  /** 服务器地址，例如 'http://localhost:3030' */
+  url: string;
+  /** 项目 ID（可选，用于工作空间模式） */
+  projectId?: string;
+  /** 连接选项 */
+  options?: {
+    /** 自动连接 */
+    autoConnect?: boolean;
+    /** 重连选项 */
+    reconnection?: boolean;
+    /** 重连延迟 */
+    reconnectionDelay?: number;
+    /** 最大重连次数 */
+    reconnectionAttempts?: number;
+  };
+}
+
+// 导出 Agent 相关类型
+export type {
+  TextBlock,
+  ToolBlock,
+  ErrorBlock,
+  SubagentBlock,
+  McpServerConfig,
+  McpServerStatus,
+  Attachment,
+  SendMessageOptions,
+  UserMessage,
+  AssistantBlock,
+  AssistantMessage,
+  ChatMessage,
+} from './agent-types.js';

package/src/utils/socket.ts

@@ -0,0 +1,34 @@
+import type { Socket } from 'socket.io-client';
+import type { SocketResponse } from '../types/index.js';
+
+/**
+ * Socket 事件处理器包装器
+ * 发送事件并等待响应
+ */
+export function createSocketHandler<P, R>(
+  socket: Socket,
+  eventName: string,
+  getPayload: () => Promise<P> | P
+): Promise<R> {
+  return Promise.resolve(getPayload()).then((payload) => {
+    return new Promise<R>((resolve, reject) => {
+      socket.emit(eventName, payload, (response: SocketResponse<R>) => {
+        if (response.success) {
+          resolve(response.data);
+        } else {
+          reject(new Error(response.errorMessage));
+        }
+      });
+    });
+  });
+}
+
+/**
+ * 监听 Socket 事件
+ */
+export function onSocketEvent<T>(socket: Socket, eventName: string, callback: (data: T) => void): () => void {
+  socket.on(eventName, callback);
+  return () => {
+    socket.off(eventName, callback);
+  };
+}