@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,
  ConversationsAPI,
  MessageEvent,

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

API 参考

ElevoPluginSDK

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

| 属性 | 类型 | 描述 | |------|------|------| | auth | AuthAPI | 认证 API，如退出登录 | | workspace | WorkspaceAPI | 工作空间 API | | conversation | ConversationAPI | 对话 API | | conversations | ConversationsAPI | 会话历史 API | | hostBar | HostBarAPI | 运行时顶部扩展栏状态 API | | config | PluginConfig | 插件配置 |

WorkspaceAPI

工作空间相关操作：

| 属性/方法 | 描述 | |----------|------| | id | 当前工作空间 ID | | openSettings(section?) | 打开宿主工作空间/应用设置弹窗 | | members | 成员管理 API | | envVars | 环境变量 API | | plugins | 应用/插件管理 API | | files | 文件管理 API | | connectors | 连接器 API | | dataSources | 数据源 API |

如果应用通过 runtime_shell.topbar.visible: false 隐藏宿主顶部栏，可以选择：

• 调用 sdk.workspace.openSettings(section) 复用宿主设置弹窗
• 使用 sdk.workspace.members/envVars/plugins/connectors/dataSources 自建设置页
• 调用 sdk.auth.logout() 自建退出登录入口

如果只需要在部分页面隐藏顶部栏，可以在 runtime_shell.topbar 中配置 hidden_paths 或 hidden_query_params：

{
  "version": 1,
  "hidden_paths": ["/embedded", "/fullscreen/*"],
  "hidden_query_params": {
    "embed": true,
    "mode": "fullscreen"
  },
  "items": []
}

hidden_paths 匹配应用相对路径，支持精确路径和 /prefix/* 前缀；hidden_query_params 中的 true 表示参数存在即隐藏，字符串表示参数值必须相等。注意：true 只检查参数是否存在，不检查参数值；?embed=false、?embed=0、?embed= 也会隐藏顶部栏。如需只在值为 true 时隐藏，请使用字符串 "true"。

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}
      model="claude-sonnet-4"
      showModelSelector={false}
      promptAllowlist={[
        { kind: 'skill', name: 'summarize' },
        { kind: 'command', pluginName: 'shared-tools', name: 'translate' },
      ]}
      enableSlashCommands={false}
    />
  );
}

ConversationPanel 默认显示名称为 Elevo AI。传入 title 可覆盖面板标题和空态名称；传入 welcomeDescription 和 welcomeSuggestions 可覆盖空会话状态下的欢迎说明和示例问题；传入 showShare={false} 可隐藏对话分享按钮。传入 model 可固定该面板中所有会话使用的模型，传入 showModelSelector={false} 可隐藏输入框右下角的模型选择/显示按钮。传入 promptAllowlist 可限制当前会话只使用指定的 skill/command，其中 pluginName 可省略，省略时默认使用当前插件的技术名称。传入 enableSessionFileMentions 后，@ 文件候选会优先来自当前会话的 .session/{conversationId}/ 目录。传入 enableSlashCommands={false} 后，会隐藏 / 快捷按钮，并且用户输入 / 时不会打开 slash command 候选。

如果一个插件应用在同一工作空间内挂载多个 AI 对话框，可以给每个面板传入不同的 conversationTag。新建会话会写入这个标签，历史记录默认按同一标签过滤；也可以用 historyFilterTag 或 historyFilterUserId 单独控制历史列表：

<ConversationPanel
  workspaceId={sdk.workspace.id}
  conversationTag="settings-assistant"
  historyFilterUserId={currentUserId}
/>

直接使用 sdk.conversations 时，create({ tag }) 会创建带标签的会话；list({ tag, initiatorUserId }) 可以按标签和发起人过滤历史。

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