@elevo-ai/plugin-sdk

Elevo Plugin SDK - 用于构建 Elevo 平台插件的开发工具包。

安装

npm install @elevo-ai/plugin-sdk

维护与发布流程

更新 SDK 包时，需要同步维护包内容、类型测试和 docs-website：

1. 更新 packages/plugin-sdk/package.json 的 version，并同步 packages/plugin-sdk/package-lock.json。
2. SDK 类型或组件 props 变化时更新 packages/plugin-sdk/index.d.ts 和 packages/plugin-sdk/type-tests/*。
3. SDK 运行时导出变化时同步更新 packages/plugin-sdk/index.esm.js 和 packages/plugin-sdk/index.cjs.js。
4. 更新本 README，以及 docs-website/docs/plugins/sdk-reference/plugin-sdk.md 和 docs-website/i18n/en/docusaurus-plugin-content-docs/current/plugins/sdk-reference/plugin-sdk.md。
5. 发布前运行相关类型测试、前端测试、cd docs-website && npm run check:i18n，依赖已安装时再运行 npm run build。

发布到公网 npm：

cd packages/plugin-sdk
npm pkg get name version
npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/
npm pack --dry-run --registry=https://registry.npmjs.org/
npm publish --access public --registry=https://registry.npmjs.org/
npm view @elevo-ai/plugin-sdk dist-tags --registry=https://registry.npmjs.org/

@elevo-ai/plugin-sdk 是 scoped 公网包，发布时需要 --access public。已发布到 npm 的版本不可覆盖；如果发现问题，升级到新的版本号后重新发布。

使用

运行时 SDK

该包的运行时代码只会从 window.__ELEVO_PLUGIN_API__ 读取 SDK 实例和宿主组件，主应用负责注入。

在插件应用中使用

import { usePluginSDK } from '@elevo-ai/plugin-sdk';

// 插件应用组件
export default function MyPluginApp() {
  const sdk = usePluginSDK();

  const handleSetInput = async () => {
    await sdk.conversation.setInput({
      content: '/my-command',
    });
  };

  const handleSendMessage = async () => {
    await sdk.conversation.sendMessage({
      role: 'user',
      content: '执行某个操作',
    });
  };

  const handleListFiles = async () => {
    const files = await sdk.workspace.files.list();
    console.log('Files:', files);
  };

  return (
    <div>
      <h1>我的插件</h1>
      <button onClick={handleSetInput}>填入输入框</button>
      <button onClick={handleSendMessage}>发送消息</button>
      <button onClick={handleListFiles}>列出文件</button>
    </div>
  );
}

类型定义

SDK 导出了完整的 TypeScript 类型定义：

import type {
  PluginConfig,

  // Workspace API
  WorkspaceAPI,
  FilesAPI,
  WorkspaceFile,

  // Conversation API
  ConversationAPI,
  MessageEvent,
  SendMessageInput,

  // 错误类型
  PluginSDKError,
} from '@elevo-ai/plugin-sdk';

API 参考

ElevoPluginSDK

主 SDK 接口，包含以下属性：

| 属性 | 类型 | 描述 | |------|------|------| | workspace | WorkspaceAPI | 工作空间 API | | conversation | ConversationAPI | 对话 API | | hostBar | HostBarAPI | 运行时顶部扩展栏状态 API | | config | PluginConfig | 插件配置 |

WorkspaceAPI

工作空间相关操作：

| 属性/方法 | 描述 | |----------|------| | id | 当前工作空间 ID | | files | 文件管理 API |

FilesAPI

文件管理操作：

| 方法 | 描述 | |------|------| | list(dirPath?, pattern?) | 列出目录中的文件 | | read(filePath) | 读取文件内容 | | write(filePath, content) | 写入文件内容 | | delete(filePath) | 删除文件 |

ConversationAPI

对话操作：

| 方法 | 描述 | |------|------| | setInput(input) | 将内容填入当前对话输入框，但不发送 | | sendMessage(message) | 发送消息给 Agent | | onMessage(callback) | 订阅对话消息 |

Runtime Host Bar

静态顶部结构定义在插件能力（capabilities.runtime_shell.topbar）中，运行时动态状态通过 sdk.hostBar 推送：

sdk.hostBar.patch({
  items: {
    publish: { disabled: false },
  },
});

HostBarAPI：

| 方法 | 描述 | |------|------| | replace(state) | 替换整个运行时状态 | | patch(state) | 增量更新运行时状态 | | reset() | 重置为宿主默认状态 |

ConversationPanel

插件应用可以直接引用宿主提供的对话面板：

import { ConversationPanel, usePluginSDK } from '@elevo-ai/plugin-sdk';

function App() {
  const sdk = usePluginSDK();

  return (
    <ConversationPanel
      workspaceId={sdk.workspace.id}
      title="Workspace Helper"
      welcomeDescription="你可以问我关于这个插件工作空间的问题。"
      welcomeSuggestions={[
        '帮我快速了解当前插件',
        '列出可以执行的操作',
      ]}
      showShare={false}
    />
  );
}

ConversationPanel 默认显示名称为 Elevo AI。传入 title 可覆盖面板标题和空态名称；传入 welcomeDescription 和 welcomeSuggestions 可覆盖空会话状态下的欢迎说明和示例问题；传入 showShare={false} 可隐藏对话分享按钮。

Vite 配置

如果你使用 Vite 构建插件应用，请使用以下配置：

// 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