插件开发

Runixo 提供强大的插件系统，支持 UI 扩展、AI 能力注册、工具注册等。本文介绍如何开发一个插件。

插件能力

能力	说明	示例
UI 扩展	在客户端添加页面、面板、菜单项	自定义监控面板
AI 能力	注册 AI 工具，让 AI 调用你的功能	数据库查询工具
命令注册	添加自定义命令到命令面板	一键部署脚本
设置页面	提供插件配置界面	API Key 配置
生命周期	激活、停用、卸载钩子	资源清理

快速开始

1. 创建插件项目

# 使用 CLI 脚手架
npx @runixo/plugin-cli create my-plugin

# 项目结构
my-plugin/
├── plugin.json        # 插件元数据
├── src/
│   └── index.ts       # 入口文件
├── package.json
└── tsconfig.json

2. 插件元数据

plugin.json 定义插件的基本信息：

{
  "name": "my-plugin",
  "displayName": "我的插件",
  "version": "1.0.0",
  "description": "一个示例插件",
  "author": "Your Name",
  "main": "dist/index.js",
  "icon": "🔧",
  "capabilities": ["ui", "ai-tools"],
  "activationEvents": ["onStartup"],
  "contributes": {
    "commands": [
      {
        "id": "my-plugin.hello",
        "title": "Hello World"
      }
    ],
    "menus": [
      {
        "location": "sidebar",
        "label": "我的插件",
        "icon": "🔧",
        "command": "my-plugin.open"
      }
    ]
  }
}

3. 编写插件逻辑

import { Plugin, PluginContext } from '@runixo/plugin-sdk'

export default class MyPlugin extends Plugin {
  async activate(ctx: PluginContext) {
    // 注册命令
    ctx.commands.register('my-plugin.hello', async () => {
      ctx.ui.showNotification('Hello from my plugin!')
    })

    // 注册 AI 工具
    ctx.ai.registerTool({
      name: 'get_server_status',
      description: '获取服务器状态摘要',
      parameters: {
        type: 'object',
        properties: {
          serverId: { type: 'string', description: '服务器 ID' }
        },
        required: ['serverId']
      },
      handler: async (params) => {
        const info = await ctx.server.getSystemInfo(params.serverId)
        return `CPU: ${info.cpuUsage}%, 内存: ${info.memUsage}%`
      }
    })
  }

  async deactivate() {
    // 清理资源
  }
}

4. 构建和测试

# 构建
npm run build

# 本地测试（在客户端开发模式下）
npm run dev

插件 SDK API

PluginContext

interface PluginContext {
  // UI 操作
  ui: {
    showNotification(msg: string, type?: 'info' | 'success' | 'warning' | 'error'): void
    showPanel(component: Component): void
    addMenuItem(menu: MenuItem): void
  }

  // AI 集成
  ai: {
    registerTool(tool: AITool): void
    chat(prompt: string): Promise<string>
  }

  // 命令系统
  commands: {
    register(id: string, handler: Function): void
    execute(id: string, ...args: any[]): Promise<any>
  }

  // 服务器操作
  server: {
    exec(serverId: string, command: string): Promise<ExecResult>
    getSystemInfo(serverId: string): Promise<SystemInfo>
    readFile(serverId: string, path: string): Promise<string>
    writeFile(serverId: string, path: string, content: string): Promise<void>
  }

  // Docker 操作
  docker: {
    listContainers(serverId: string): Promise<Container[]>
    execInContainer(serverId: string, containerId: string, cmd: string): Promise<string>
  }

  // 存储（插件私有）
  storage: {
    get(key: string): Promise<any>
    set(key: string, value: any): Promise<void>
    delete(key: string): Promise<void>
  }

  // 设置
  settings: {
    get(key: string): any
    onChange(key: string, callback: Function): void
  }
}

UI 扩展

在侧边栏添加自定义页面：

import { defineComponent } from 'vue'

const MyPanel = defineComponent({
  template: `
    <div class="my-panel">
      <h2>{{ title }}</h2>
      <button @click="refresh">刷新</button>
      <pre>{{ data }}</pre>
    </div>
  `,
  data() {
    return { title: '服务器状态', data: '' }
  },
  methods: {
    async refresh() {
      this.data = await this.$plugin.server.exec(this.serverId, 'uptime')
    }
  }
})

// 在 activate 中注册
ctx.ui.showPanel(MyPanel)

发布插件

# 打包
npx @runixo/plugin-cli pack

# 输出 my-plugin-1.0.0.rpx 文件

目前插件通过 GitHub 分发。将 .rpx 文件上传到你的仓库 Releases，用户可在客户端插件市场搜索安装。

官方插件

插件	说明	状态
devops-assistant	AI 运维助手，智能故障诊断	✅ 可用
cloudflare-v2	Cloudflare DNS/CDN/SSL 管理	✅ 可用

最佳实践

• 最小权限：只声明需要的 capabilities
• 错误处理：所有异步操作都要 try-catch
• 资源清理：在 deactivate 中释放所有资源
• 国际化：使用 i18n 支持多语言
• 性能：避免在 activate 中做耗时操作，使用懒加载