Cloud IDE Theia 插件系统拓展探索

Theia 插件系统功能非常强大，这么大的工程，依然能保持高质量的代码和清晰的架构，值得思考和学习
VSCode Extension API 和配置的定义规范且抽象

Eclipse Theia 是一个可扩展的平台，可以利用最先进的 Web 技术开发多语言的 Cloud & Desktop IDE。

名词解释

Theia：可拓展的 Cloud & Desktop IDE 平台。
Theia Extension：Theia 是由一系列 Extension 组成，Extension 提供了处理 widgets, commands, handlers 等的能力，在编译时加载。
Theia Plugin：概念上类似于 VSCode Extension，由 Theia 的其中一个 Extension ：theia/packages/plugin-ext 定义了加载机制、运行环境及 API 等。兼容 VSCode Extension ，功能更为强大，运行时加载。
VSCode Extension：VSCode 运行时加载的 extensions，基于 VSCode Extension API 实现，概念上类似于 Theia 的 Plugin，运行时加载。

VSCode Extension 可以看成是 Theia Plugin 的子集。
Theia Extension 与 Plugin 的界线：核心的、抽象的、编译时加载的采用 Extension；业务的、具体的、运行时加载的采用 Plugin。

Theia Plugin 类型分为前端和后端（VSCode 只有后端），其中后端运行在独立的插件进程；前端运行在 Web Worker 上，通过 postMessage 和 Browser 主进程通信。这里的 Web Worker 有点像微信小程序架构里面的 App Service。

概述

拓展 Theia Plugin 能力，让业务方简单、灵活地深度定制 IDE 的功能和界面。

动机

Theia Plugin 拓展方式和能力和 VSCode Extension 类似，并不满足我们的需求：

UI 定制能力非常薄弱：主界面仅提供了少量的按钮与菜单支持自定义。但很多实际场景都有非常强烈的 UI 需求以满足不同的业务能力。如：例如 Taro IDE 主界面需要大量的按钮菜单注入以及模拟器、调试器等预览面板。
配置化的 UI 定制方式无法满足定制需求：Theia Plugin 基于 Phosphor.js 实现布局系统，将定制能力限定在了 配置化 这一层，随着 IDE Core 不同场景的业务方越来越多，容易形成「配置地狱」，因此在保留配置化的同时，最好提供布局相关 API ，让业务方使用 JSX 自定义布局。（参考开天）
与内部业务、场景对接：如 ERP 登录认证、gitlab 仓库对接、团队协作与工作空间、监控/运营系统集成等。（参考开天 + Eclipse Che）

因此，需要拓展 Theia 的插件系统。

原则

屏蔽 IoC/布局系统/Widgt 等复杂概念，让用户只需要拥有 VS Code 插件开发经验就能够开发 Tide 插件。
尽可能复用 VS Code Extension 相关的设计和 API ，尽可能参照 VS Code Extension API 现有的接口或规范进行拓展。
用户只需要拥有 React 开发经验就可以定制布局系统。

设计概览

设计总结

通过独立的 Extension 包拓展插件系统。
- 参考 eclipse-che-theia-plugin-ext，提供 tide-theia-plugin-ext 。
- 用户只需要加载 tide-theia-plugin-ext，就可以使用拓展的 API 及配置等。
提案参考 VS Code Extension 的拓展接口及规范，从配置、Command 、VS Code API 等方面拓展插件系统。
- 用户无额外学习成本，拥有 VS Code 插件开发经验就能够开发 Tide 插件。
- 拓展 VS Code API ，通过 tide namespace 暴露的方法和 interface 等。
- 拓展 package.json 配置，其中主要是 Contribution Points
- 拓展 Command ，包括 built-in advanced commands api 和 keyboard shortcuts
- 如有需要，拓展 task。
相对于 theia/vscode Namespace，提供 tide 的 Namespace 访问 Tide API。
- 和 Theia Plugin 解耦

整体设计图示

tide 项目结构

IDE Core 和 Taro IDE 暂时放在同一个项目 tide 里，建议参考：che-theia。

./
├── configs
├── examples
│   ├── browser-app
│   └── electron-app
├── extensions
│   ├── tide-theia-about
│   ├── tide-theia-plugin // Tide API 接口规范定义
│   ├── tide-theia-plugin-ext // 插件系统拓展实现
│   ├── tide-theia-user-preferences // 用户信息相关
│   ├──  ...
└──  plugins
    ├── dashboard-plugin
    ├── test-plugin
    ├── deploy-plugin
    ├── setting-plugin
    └── ...

npm 包发布在 @tide Scope 下。

VS Code Extension（概念上等同于 Theia 的 Plugin）能力是以下三种方式拓展：

详细设计

项目将参考 VS Code Extension 的拓展接口及规范，从配置、Command 、VS Code API 等方面拓展插件系统，其中，VSCode 最具代表性的拓展例子应该是 Tree View API，兼具以上三者方式。

Contribution Points 配置拓展

Contribution Points 是 package.json 中 contributes 字段的一系列 JSON 声明，插件通过注册 Contribution Points 来拓展 VSCode 的功能。

contributes 配置的处理可以分为配置扫描（scanner）和配置处理（handler）。主要在 plugin-ext 里实现。

scanner

plugin-ext/src/hosted/node/scanners/scanner-theia.ts 里的 TheiaPluginScanner 类实现了所有 package.json 配置的读取方法，包括 contribution 配置、activationEvents 配置等。

我们应该是不需要添加新的配置读取，所以不需要修改这里。

handler

contribution 最终配置的 handle 都是在 PluginContributionHandler 里注入实际 handler 类统筹处理的。

// packages/plugin-ext/src/main/browser/plugin-contribution-handler.ts
export class PluginContributionHandler {
    @inject(MenusContributionPointHandler) // 注入 Menu 相关 handler 
    private readonly menusContributionHandler: MenusContributionPointHandler;
    @inject(KeybindingsContributionPointHandler) // 注入 Keybindings 相关 handler 
    private readonly keybindingsContributionHandler: KeybindingsContributionPointHandler;
    // ...

    handleContributions(clientId: string, plugin: DeployedPlugin): Disposable {
     // ...
        pushContribution('commands', () => this.registerCommands(contributions));
        pushContribution('menus', () => this.menusContributionHandler.handle(plugin));
        pushContribution('keybindings', () => this.keybindingsContributionHandler.handle(contributions));

        if (contributions.views) {
            for (const location in contributions.views) {
                for (const view of contributions.views[location]) {
                    pushContribution(`views.${view.id}`,
                        () => this.viewRegistry.registerView(location, view) // 注册页面配置
                    );
                }
            }
        }
     // ...
    }
    registerCommandHandler(id: string, execute: CommandHandler['execute']): Disposable {}
    registerCommand(command: Command): Disposable {}
     // ...
}

拓展

和 API 拓展不同专门预留了拓展注入点 ExtPluginApiProvider 不同，Theia 代码里类似的并没有预留专门的接口，暂时采用以下步骤拓展：

定义 TidePluginContributionHandler 继承 PluginContributionHandler 类
重写 handleContributions 方法
在 ContainerModule 里 rebind(TidePluginContributionHandler).to(PluginContributionHandler).inSingletonScope();

如果有更好的方式，请指正。

Command 拓展

Commands 触发 Theia/VSCode 的 actions。VSCode 代码里包含大量 built-in commands，你可以使用这些命令与编辑器交互、控制用户界面或执行后台操作。

Command 拓展可以参考：packages/plugin-ext-vscode/src/browser/plugin-vscode-commands-contribution.ts

首先定义 XXXCommandsContribution 类实现 CommandContribution，并注入对应的服务，如然后在 XXXCommandsContribution 中通过 commands.registerCommand 进行 Command 拓展，如：

// packages/plugin-ext-vscode/src/browser/plugin-vscode-commands-contribution.ts
export class PluginVscodeCommandsContribution implements CommandContribution {
    @inject(ContextKeyService)
    protected readonly contextKeyService: ContextKeyService;
    @inject(WorkspaceService)
    protected readonly workspaceService: WorkspaceService;
    
    registerCommands(commands: CommandRegistry): void {
            commands.registerCommand({ id: 'openInTerminal' }, { // 注册命令
            execute: (resource: URI) => this.terminalContribution.openInTerminal(new TheiaURI(resource.toString()))
        });
    }
}

然后 bind 到 container 即可：

bind(XXXCommandsContribution).toSelf().inSingletonScope();
bind(CommandContribution).toService(XXXCommandsContribution);

XXXCommandsContribution 会被注入到对应的 ContributionProvider，然后进行处理：

constructor(
        @inject(ContributionProvider) @named(CommandContribution)
        protected readonly contributionProvider: ContributionProvider
) { }

Command 可以传入对象作为参数，无法暴露接口和组件。

API 拓展

相对上面两种拓展方式，API 的拓展方式比较复杂。

方式一：plugin-ext-vscode 的方式

这种方式是 VSCode 采用的方式，通过修改 PluginLifecycle 里面的 backendInitPath 或 frontendInitPath，这两个脚本类似于 preload 脚本，在插件加载前进行预加载，初始化插件环境。

具体是 VsCodePluginScanner 类里的 getLifecycle() 方法的 backendInitPath。在这里 backendInitPath 被初始化为： backendInitPath: __dirname + '/plugin-vscode-init.js'

/**
 * This interface describes a plugin lifecycle object.
 */
export interface PluginLifecycle {
    startMethod: string;
    stopMethod: string;
    /**
     * Frontend module name, frontend plugin should expose this name.
     */
    frontendModuleName?: string; 
    /**
     * Path to the script which should do some initialization before frontend plugin is loaded.
     */
    frontendInitPath?: string;   // 插件前端 preload
    /**
     * Path to the script which should do some initialization before backend plugin is loaded.
     */
    backendInitPath?: string;  // 插件后端 preload
}

然后在 PluginHostRPC 类里 new PluginManagerExtImpl() 实例时，在传入的 init 钩子中调用的 initContext 中通过 require() 方法加载。

注意：initContext 里面的 backendInitPath 来自于 PluginLifecycle，并不是 ExtPluginApiProvider。

// packages/plugin-ext/src/hosted/node/plugin-host-rpc.ts
/**
 * Handle the RPC calls.
 */
export class PluginHostRPC {
    private apiFactory: PluginAPIFactory;

    private pluginManager: PluginManagerExtImpl;

    initialize(): void {
        this.pluginManager = this.createPluginManager(envExt, storageProxy, preferenceRegistryExt, webviewExt, this.rpc);
    }

    initContext(contextPath: string, plugin: Plugin): any {
        const { name, version } = plugin.rawModel;
        console.log('PLUGIN_HOST(' + process.pid + '): initializing(' + name + '@' + version + ' with ' + contextPath + ')');
        const backendInit = require(contextPath);  // 加载 PluginLifecycle 的 backendInitPath
        backendInit.doInitialization(this.apiFactory, plugin);  // 调用 backendInitPath 脚本暴露的 doInitialization 方法
    }

    createPluginManager(){
        const pluginManager = new PluginManagerExtImpl({
            loadPlugin(plugin: Plugin): any {},
            async init(raw: PluginMetadata[]): Promise<[Plugin[], Plugin[]]> {
                            let backendInitPath = pluginLifecycle.backendInitPath;
                            // if no init path, try to init as regular Theia plugin
                            if (!backendInitPath) {
                                backendInitPath = __dirname + '/scanners/backend-init-theia.js';
                            }
                            self.initContext(backendInitPath, plugin);  // backendInitPath 来自于 pluginLifecycle
            },
            initExtApi(extApi: ExtPluginApi[]): void {
                            const extApiInit = require(api.backendInitPath); // 加载 ExtPluginApiProvider 注入的 backendInitPath
                            extApiInit.provideApi(rpc, pluginManager);
            },
            loadTests: extensionTestsPath ? async () => {}
        })
    }
}

而 backendInitPath 配置的 plugin-vscode-init.ts 文件提供了 doInitialization 方法，在 doInitialization 方法中通过 Object.assign 合并 Theia API 到 vscode namespace，添加简单的 API 和字段。

// packages/plugin-ext-vscode/src/node/plugin-vscode-init.ts
export const doInitialization: BackendInitializationFn = (apiFactory: PluginAPIFactory, plugin: Plugin) => {
    const vscode = Object.assign(apiFactory(plugin), { ExtensionKind });  // 合并 API 

    // use Theia plugin api instead vscode extensions
    (vscode).extensions = {
        get all(): any[] {
            return vscode.plugins.all.map(p => asExtension(p));
        },
        getExtension(pluginId: string): any | undefined {
            return asExtension(vscode.plugins.getPlugin(pluginId));
        },
        get onDidChange(): theia.Event {
            return vscode.plugins.onDidChange;
        }
    };
}

这种方法本质是在插件加载前运行脚本，不涉及到 RPC，通过 Object.assign 合并简单的 API。

这种方式不如 ExtPluginApiProvider 的方式优雅，社区有人提里 PR 将其改成 ExtPluginApiProvider 的形式：Make "theia" and "vscode" contributed API's #8142，目前为止依然还没有被合并。

方式二：ExtPluginApiProvider 的方式

eclipse/che-theia 就是采用了这种方式，功能非常强大。具体可见：ChePluginApiProvider

Theia 官方文档没有提到这种方式，不过在 plugin-ext/doc 下倒是有一片简单的介绍文档：This document describes how to add new plugin api namespace

Che-Theia plug-in API 提供了 che 的 namespace。

首先声明 ExtPluginApiProvider 实现：

// extensions/eclipse-che-theia-plugin-ext/src/node/che-plugin-api-provider.ts
export class ChePluginApiProvider implements ExtPluginApiProvider {
    provideApi(): ExtPluginApi {
        return {
            frontendExtApi: {
                initPath: '/che/api/che-api-worker-provider.js',
                initFunction: 'initializeApi',
                initVariable: 'che_api_provider'
            },
            backendInitPath: path.join('@eclipse-che/theia-plugin-ext/lib/plugin/node/che-api-node-provider.js')
        };
    }
}

然后注入到 backend moudule：

    // extensions/eclipse-che-theia-plugin-ext/src/node/che-backend-module.ts
    bind(ChePluginApiProvider).toSelf().inSingletonScope();
    bind(Symbol.for(ExtPluginApiProvider)).toService(ChePluginApiProvider);

这样，前端及后台都有了插件拓展的入口。

createAPIFactory

createAPIFactory 用于定义 Client API 接口，然后分别挂载到前端及后端插件运行时的 namespace。

createAPIFactory 方法的实现，和 Theia 源码中 packages/plugin-ext/src/plugin/plugin-context.ts 里 createAPIFactory 的实现一致：

export function createAPIFactory(rpc: RPCProtocol): CheApiFactory {
    return function (plugin: Plugin): typeof che {}
}

前端入口 initializeApi

前端入口脚本 che-api-worker-provider.js ，实现并 export initializeApi 方法。在 initializeApi 中，传入 RPC，挂载到 che namespace。

// extensions/eclipse-che-theia-plugin-ext/src/plugin/webworker/che-api-worker-provider.ts
export const initializeApi: ExtPluginApiFrontendInitializationFn = (rpc: RPCProtocol, plugins: Map) => {
    const cheApiFactory = createAPIFactory(rpc);  // 核心在于 createAPIFactory
    const handler = {
        get: (target: any, name: string) => {
            const plugin = plugins.get(name);
            if (plugin) {
                let apiImpl = pluginsApiImpl.get(plugin.model.id);
                if (!apiImpl) {
                    apiImpl = cheApiFactory(plugin);
                    pluginsApiImpl.set(plugin.model.id, apiImpl);
                }
                return apiImpl;
            };MainPluginApiProvider
        }
        ctx['che'] = new Proxy(Object.create(null), handler); // 直接挂载到 che namespace
    };

后端入口 provideApi

后端入口脚本 che-api-node-provider.js，代码里需要暴露 export provideApi()。

后端也是通过 createAPIFactory 定义 Client API 接口。

export const provideApi: ExtPluginApiBackendInitializationFn = (rpc: RPCProtocol, pluginManager: PluginManager) => {
    cheApiFactory = createAPIFactory(rpc);
    plugins = pluginManager;

    if (!isLoadOverride) {
        overrideInternalLoad();
        isLoadOverride = true;
    }
};

然后在 overrideInternalLoad() 方法中改写 module._load，使 require('@eclipse-che/plugin') 返回定义的 Client API。

function overrideInternalLoad(): void {
    const module = require('module');
    // save original load method
    const internalLoad = module._load;

    // if we try to resolve che module, return the filename entry to use cache.
    module._load = function (request: string, parent: any, isMain: {}): any {
        if (request !== '@eclipse-che/plugin') {
            return internalLoad.apply(this, arguments);
        }

        apiImpl = cheApiFactory(plugin);
        return apiImpl;
    }
}

前后端 Client API 注入

Client API 可以看成是接口的定义，暴露到前后端运行时中，供插件调用。

new PluginManagerExtImpl() 传入的第一个参数 host 是 PluginHost 类型，其中的 initExtApi 等方法前端后台分别实现：

export interface PluginHost {

    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    loadPlugin(plugin: Plugin): any;

    init(data: PluginMetadata[]): Promise<[Plugin[], Plugin[]]> | [Plugin[], Plugin[]]; // 初始化插件

    initExtApi(extApi: ExtPluginApi[]): void;  // 初始化从外部引入的前后端 API，ExtPluginApi 包含 frontendExtApi 或 backendInitPath

    loadTests?(): Promise;
}

initExtApi 前端，挂在 window 下。

initExtApi(extApi: ExtPluginApi[]): void {
    if (api.frontendExtApi) {
        ctx.importScripts(api.frontendExtApi.initPath);
        ctx[api.frontendExtApi.initVariable][api.frontendExtApi.initFunction](rpc, pluginsModulesNames);
    }
}

其中 const pluginsModulesNames = new Map(); 插件的集合。

initExtApi 后端，直接 require，并运行 provideApi()

initExtApi(extApi: ExtPluginApi[]): void {
    if (api.backendInitPath) {
        const extApiInit = require(api.backendInitPath);
        extApiInit.provideApi(rpc, pluginManager);  // 调用 provideAp
    }
}

Server API 的注入

Server API 可以看成是接口的实现，通过 MainPluginApiProvider 注入到 browser，监听 Client API 的 RPC 消息并触发对应处理方法。

MainPluginApiProvider 的实现应该包含新命名空间的 Plugin API 的 main（接口实现）部分。

/**
 * Implementation should contains main(Theia) part of new namespace in Plugin API.
 * [initialize](#initialize) will be called once per plugin runtime
 */
export interface MainPluginApiProvider {
    initialize(rpc: RPCProtocol, container: interfaces.Container): void;
}

注入到浏览器的 HostedPluginSupport 中，然后在 initRpc方法一次调用注入 MainPluginApiProvider 的 initialize 方法进行初始化。

// packages/plugin-ext/src/hosted/browser/hosted-plugin.ts
@injectable()
export class HostedPluginSupport {

    @inject(ContributionProvider)
    @named(MainPluginApiProvider)
    protected readonly mainPluginApiProviders: ContributionProvider;
    
    protected initRpc(host: PluginHost, pluginId: string): RPCProtocol {
        const rpc = host === 'frontend' ? new PluginWorker().rpc : this.createServerRpc(pluginId, host); 
        setUpPluginApi(rpc, this.container); // 初始化 VScode API 的 Server 端实现
        this.mainPluginApiProviders.getContributions().forEach(p => p.initialize(rpc, this.container)); // 初始化外部注入的接口实现
        return rpc;
    }

}

简化的 API 通信架构图大致如下：

ExtPluginApiProvider 的拓展方式非常成熟优雅且功能强大，建议采用这一种。

Demo

见 Tide 项目 master 分支 extension/tide-theia-plugin-ext 模块。