@elevo-ai/plugin-sdk 0.4.0

package/README.md

@@ -0,0 +1,144 @@
+# @elevo/plugin-sdk
+
+Elevo Plugin SDK - 用于构建 Elevo 平台插件的开发工具包。
+
+## 安装
+
+```bash
+npm install @elevo/plugin-sdk
+```
+
+## 使用
+
+### 运行时 SDK
+
+该包的运行时代码只会从 `window.ElevoPluginSDK` 读取 SDK 实例，主应用负责注入。插件代码通常仅导入类型。
+
+### 在插件应用中使用
+
+```tsx
+import sdk from '@elevo/plugin-sdk';
+
+// 插件应用组件
+export default function MyPluginApp() {
+  const handleSendMessage = async () => {
+    await sdk.conversation.sendMessage({
+      role: 'user',
+      content: '执行某个操作',
+    });
+  };
+
+  const handleListArtifacts = async () => {
+    const artifacts = await sdk.workspace.artifacts.list();
+    console.log('Artifacts:', artifacts);
+  };
+
+  return (
+    <div>
+      <h1>我的插件</h1>
+      <button onClick={handleSendMessage}>发送消息</button>
+      <button onClick={handleListArtifacts}>列出制品</button>
+    </div>
+  );
+}
+```
+
+### 类型定义
+
+SDK 导出了完整的 TypeScript 类型定义：
+
+```typescript
+import type {
+  PluginConfig,
+
+  // Workspace API
+  WorkspaceAPI,
+  ArtifactsAPI,
+  Artifact,
+  ArtifactContent,
+
+  // Conversation API
+  ConversationAPI,
+  MessageEvent,
+  SendMessageInput,
+
+  // 错误类型
+  PluginSDKError,
+} from '@elevo/plugin-sdk';
+```
+
+## API 参考
+
+### ElevoPluginSDK
+
+主 SDK 接口，包含以下属性：
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `workspace` | `WorkspaceAPI` | 工作空间 API |
+| `conversation` | `ConversationAPI` | 对话 API |
+| `config` | `PluginConfig` | 插件配置 |
+
+### WorkspaceAPI
+
+工作空间相关操作：
+
+| 属性/方法 | 描述 |
+|----------|------|
+| `id` | 当前工作空间 ID |
+| `artifacts` | 制品管理 API |
+
+### ArtifactsAPI
+
+制品管理操作：
+
+| 方法 | 描述 |
+|------|------|
+| `list(options?)` | 列出工作空间制品 |
+| `upload(file, options?)` | 上传文件作为制品 |
+| `download(artifactId)` | 下载制品 |
+| `getContent(artifactId)` | 获取制品内容（预览） |
+
+### ConversationAPI
+
+对话操作：
+
+| 方法 | 描述 |
+|------|------|
+| `sendMessage(message)` | 发送消息给 Agent |
+| `onMessage(callback)` | 订阅对话消息 |
+
+## Vite 配置
+
+如果你使用 Vite 构建插件应用，请使用以下配置：
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: 'src/App.tsx',
+      name: 'MyPluginApp', // 必须与 plugin.json 中的 entry 一致
+      fileName: 'app',
+      formats: ['umd'],
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom'],
+      output: {
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+        },
+      },
+    },
+  },
+});
+```
+
+## 许可证
+
+MIT

package/index.cjs.js

@@ -0,0 +1,9 @@
+"use strict";
+
+var _a = window.__ELEVO_PLUGIN_API__ || {};
+
+Object.defineProperty(exports, "__esModule", { value: true });
+
+exports.usePluginSDK = _a.usePluginSDK;
+exports.useInjectCSS = _a.useInjectCSS;
+exports.CopilotPanel = _a.CopilotPanel;

package/index.d.ts

@@ -0,0 +1,275 @@
+import React from 'react';
+
+/**
+ * Workspace artifact (file or document)
+ */
+export interface Artifact {
+  id: string;
+  workspace_id: string;
+  conversation_id: string | null;
+  file_path: string;
+  file_size: number;
+  mime_type: string;
+  created_at: string;
+  created_by_agent: string | null;
+  tags: string[];
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Artifact content response
+ */
+export interface ArtifactContent {
+  artifact_id: string;
+  content: string;
+  encoding: 'utf-8' | 'base64';
+  is_preview: boolean;
+  preview_size?: number;
+}
+
+/**
+ * Workspace file information
+ */
+export interface WorkspaceFile {
+  path: string;
+  name: string;
+  size: number;
+  mime_type: string;
+  is_dir: boolean;
+  mod_time: string;
+  permission: 'readonly' | 'readwrite';
+}
+
+/**
+ * Conversation message event
+ */
+export interface MessageEvent {
+  type: 'message' | 'status' | 'error';
+  role?: 'user' | 'assistant';
+  content?: string;
+  status?: string;
+  error?: string;
+}
+
+/**
+ * Plugin configuration
+ */
+export type PluginConfig = Record<string, unknown>;
+
+/**
+ * ChatPanel component props
+ */
+export interface ChatPanelProps {
+  workspaceId: string;
+  className?: string;
+  options?: {
+    showHistory?: boolean;
+    showQuickActions?: boolean;
+    placeholder?: string;
+  };
+}
+
+// ==================== SDK 接口 ====================
+
+/**
+ * Workspace artifacts API
+ */
+export interface ArtifactsAPI {
+  /**
+   * List workspace artifacts
+   * @param options - Optional filters (conversationId)
+   */
+  list(options?: { conversationId?: string }): Promise<Artifact[]>;
+
+  /**
+   * Upload a file as artifact
+   * @param file - File to upload
+   * @param options - Optional metadata (filePath, conversationId, tags)
+   */
+  upload(
+    file: File,
+    options?: {
+      filePath?: string;
+      conversationId?: string;
+      tags?: string[];
+      metadata?: Record<string, unknown>;
+    }
+  ): Promise<Artifact>;
+
+  /**
+   * Download an artifact
+   * @param artifactId - Artifact ID
+   */
+  download(artifactId: string): Promise<Blob>;
+
+  /**
+   * Get artifact content (text or base64)
+   * @param artifactId - Artifact ID
+   */
+  getContent(artifactId: string): Promise<ArtifactContent>;
+}
+
+/**
+ * Workspace files API - Read/write files in the workspace directory
+ */
+export interface FilesAPI {
+  /**
+   * List files in a directory
+   * @param dirPath - Directory path (empty string for root)
+   * @param pattern - Optional glob pattern to filter files
+   */
+  list(dirPath?: string, pattern?: string): Promise<WorkspaceFile[]>;
+
+  /**
+   * Read file content
+   * @param filePath - File path relative to workspace root
+   */
+  read(filePath: string): Promise<string>;
+
+  /**
+   * Write content to a file
+   * @param filePath - File path relative to workspace root
+   * @param content - File content
+   */
+  write(filePath: string, content: string): Promise<void>;
+
+  /**
+   * Delete a file
+   * @param filePath - File path relative to workspace root
+   */
+  delete(filePath: string): Promise<void>;
+}
+
+/**
+ * Conversation API
+ */
+export interface ConversationAPI {
+  /**
+   * Send a message to the agent
+   * @param message - Message object
+   */
+  sendMessage(message: { role: 'user'; content: string }): Promise<void>;
+
+  /**
+   * Subscribe to conversation messages
+   * @param callback - Message event handler
+   * @returns Unsubscribe function
+   */
+  onMessage(callback: (event: MessageEvent) => void): () => void;
+}
+
+/**
+ * Workspace API
+ */
+export interface WorkspaceAPI {
+  id: string;
+  artifacts: ArtifactsAPI;
+  files: FilesAPI;
+}
+
+export interface ElevoPluginContributes {
+  sidebar?: ElevoPluginSidebarContributes;
+}
+
+export interface ElevoPluginSidebarContributes {
+  menuItems?: ElevoPluginSidebarMenuItem[];
+  menuItemOverrides?: ElevoPluginSidebarMenuItemOverride[];
+}
+
+export type MenuItemPosition = 'first' | 'last' | 'before' | 'after';
+
+export interface MenuItemPlacement {
+  position: MenuItemPosition;
+  anchorId?: string;
+}
+
+export interface ElevoPluginSidebarMenuItem {
+  id: string;
+  labelKey: string;
+  defaultLabel: string;
+  icon: React.ComponentType<{ className?: string }>;
+  view: React.ComponentType<any>;
+  placement?: MenuItemPlacement;
+  order?: number;
+}
+
+export interface ElevoPluginSidebarMenuItemOverride {
+  id: string;
+  visible?: boolean;
+  placement?: MenuItemPlacement;
+  labelKey?: string;
+  defaultLabel?: string;
+  icon?: React.ComponentType<{ className?: string }>;
+}
+
+export interface ElevoPluginWithContributes {
+  contributes?: ElevoPluginContributes;
+}
+
+/**
+ * Routing API - URL parameter management for plugins
+ */
+export interface RoutingAPI {
+  /**
+   * Get current URL search parameters
+   * @returns URLSearchParams object
+   */
+  getSearchParams(): URLSearchParams;
+
+  /**
+   * Update search parameters (merge mode)
+   * @param params - Parameters to update
+   * @example
+   * sdk.routing.updateSearchParams({ filter: 'open', page: '2' });
+   */
+  updateSearchParams(params: Record<string, string>): void;
+
+  /**
+   * Replace search parameters (override mode)
+   * @param params - New parameters
+   */
+  setSearchParams(params: Record<string, string>): void;
+
+  /**
+   * Navigate to another view
+   * @param viewId - Target view ID (plugin prefix will be added automatically)
+   * @param params - Optional query parameters
+   * @example
+   * sdk.routing.navigate('main-view', { branch: 'main' });
+   */
+  navigate(viewId: string, params?: Record<string, string>): void;
+
+  /**
+   * Get current view ID (without plugin prefix)
+   * @returns Current view ID
+   * @example
+   * // URL: ?view=git-assistant:main-view
+   * sdk.routing.getCurrentView() // returns 'main-view'
+   */
+  getCurrentView(): string | null;
+}
+
+/**
+ * Elevo Plugin SDK
+ */
+export interface ElevoPluginSDK {
+  workspace: WorkspaceAPI;
+  conversation: ConversationAPI;
+  config: PluginConfig;
+  contributes?: ElevoPluginContributes;
+  routing: RoutingAPI;
+  /**
+   * Plugin name (used internally for namespacing view IDs)
+   * @internal
+   */
+  pluginName?: string;
+  /**
+   * TODO: UI Components that plugins can use
+   * Note: Some components may require specific context providers
+   */
+  // components: PluginUIComponents;
+}
+
+export declare function usePluginSDK(): ElevoPluginSDK;
+export declare function useInjectCSS(cssText: string): void;
+export declare function CopilotPanel(): React.ReactElement;

package/index.esm.js

@@ -0,0 +1,5 @@
+var _a = window.__ELEVO_PLUGIN_API__ || {};
+
+export const usePluginSDK = _a.usePluginSDK;
+export const useInjectCSS = _a.useInjectCSS;
+export const CopilotPanel = _a.CopilotPanel;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@elevo-ai/plugin-sdk",
+  "version": "0.4.0",
+  "description": "Elevo Plugin SDK - Build plugins for the Elevo platform",
+  "type": "module",
+  "main": "./index.cjs.js",
+  "module": "./index.esm.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.esm.js",
+      "require": "./index.cjs.js"
+    }
+  },
+  "files": [
+    "index.d.ts",
+    "index.esm.js",
+    "index.cjs.js",
+    "README.md"
+  ],
+  "keywords": [
+    "elevo",
+    "plugin",
+    "sdk",
+    "ai",
+    "workspace"
+  ],
+  "author": {
+    "name": "Elevo Team",
+    "email": "dev@elevo.vip"
+  },
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "react": "^19.0.0"
+  }
+}