[001] 实现 TerminalProfile API

[bytemain]

相关 PR: #92
相关 Issue: #34

摘要

本文主要会讲一下现在的 Terminal 启动设计，以及变更后的启动设计，其中会讲述变更关键点，变更原因。

本次变更属于 Breaking Change，会影响终端启动流程，启动终端的方法/参数，从同步启动变更为异步启动等的变更。

理由

这是 VS Code 插件 API 1.60.0 迭代 的其中一项任务。

新增 VSCode Contributions（点击展开）

    export interface ITerminalContributions {
      profiles?: ITerminalProfileContribution[];
    }
    
    export interface ITerminalProfileContribution {
      title: string;
      id: string;
      icon?: URI | { light: URI; dark: URI } | string;
      color?: string;
    }

新增 VSCode API 接口声明（点击展开）

该 API 的主要功能是：插件可以向 VSCode 注册一个 Terminal Profile，用户可以在 启动终端时的下拉框 中选择要启动的配置。

同时 VSCode 内部也将各种启动终端的逻辑收敛到了 Terminal Profile 内，比如说启动终端前检测用户本地可用的 Profiles 并保存下来：

// _detectWindowsProfiles
     detectedProfiles.set('PowerShell', {
        source: ProfileSource.Pwsh,
        isAutoDetected: true,
      });
      ...
      detectedProfiles.set('Command Prompt', {
        path: `${system32Path}\\cmd.exe`,
        isAutoDetected: true,
      });
// _detectUnixProfiles
      const contents = (await readFile('/etc/shells')).toString();
      const profiles = contents.split('\n').filter((e) => e.trim().indexOf('#') !== 0 && e.trim().length > 0);
      const counts: Map<string, number> = new Map();
      for (const profile of profiles) {
          ...
      }

目前 VSCode 还没有把所有启动流程迁往 Terminal Profile，如果用户在设置中什么都没设置的话，VSCode 会读取用户的旧配置或者自动检测可用 Shell 然后生成一个 Generated Profile 并启动它。

整体调用流程

插件注册 TerminalProfile 流程

贡献点 terminal

首先插件需要在自己的 contributions 里声明 terminal.profiles：

这里只是对启动的 Terminal 的一些描述（标题，icon）和 ID，还不需要填写要启动的 Shell 的路径等。

这里的 ID 需要全局唯一，之后需要通过插件 API 注册该 ID 要使用的 Profile（后文会详细描述 API）。

VSCode 将该贡献点保存到 TerminalContributionService 中，会在 TerminalProfileService._updateContributedProfiles 时保存这些贡献进来的 Terminal Profile 描述，然后其他类可以通过 TerminalProfileService.contributedProfiles 拿到贡献进来的 Terminal Profile 描述列表用以展示。

API

import * as vscode from 'vscode';

vscode.window.registerTerminalProfileProvider('extension.js-debug.debugTerminal', {
  provideTerminalProfile: () =>
    new Promise<vscode.TerminalProfile>(resolve =>
      // ...
    ),
});

API 为 vscode.window.registerTerminalProfileProvider。
参数1 为 Provider 的 id，要全局唯一，对应在 contributions.terminal.profiles 中声明的 ID。
参数2 为 该 Provider 模式的 interface 声明，要实现一个 provideTerminalProfile 方法，该方法返回一个启动 Terminal 的配置。其中 TerminalProfile 是一个从内部暴露的 Class，入参是 TerminalOptions，用以声明 shellPath, args, env 等启动终端所需的信息。

然后 VSCode 会将这个 Provider 保存下来，一路保存的调用路径为：

extHostTerminalService.ts#L658 -> mainThreadTerminalService.ts#L231 -> terminalProfileService.ts#L166

注意，这里的 Provider 不会被立刻调用获取里面的所有值。

当我们想启动一个由插件贡献的终端时，比如执行命令：workbench.action.terminal.newWithProfile 时：

此时会调用 terminalService.showProfileQuickPick，然后在内部通过 TerminalProfileQuickpick._createAndShow获取 TerminalProfileService.availableProfiles 和 TerminalProfileService.contributedProfiles 并展示，当我们选中某一项的时候，如果这一项为 Contributed Terminal，则调用 TerminalService.createContributedTerminalProfile，同时会发出一个插件激活事件：onTerminalProfile:${id}。该函数中查询该 ID 注册的 provideTerminalProfile 回调函数，调用后拿到 Terminal Profile，然后启动。

主要变更点

在前面的一些 PR 中，我们已经将内部启动 Terminal 的配置都收敛到了 IShellLaunchConfig 中，所以现在内部的启动流程如下：

用户按下终端 Tab，最后会通过 TerminalController._createClient 来启动，在这里我们引入了一个新的 ITerminalClientFactory2：

- export const ITerminalClientFactory = Symbol('ITerminalClientFactory');
- export type ITerminalClientFactory = (
  widget: IWidget,
-  options?: TerminalOptions,
  disposable?: IDisposable,
) => Promise<ITerminalClient>;

+ export const ITerminalClientFactory2 = Symbol('ITerminalClientFactory2');
+ export type ITerminalClientFactory2 = (
  widget: IWidget,
+  options?: ICreateTerminalOptions,
  disposable?: IDisposable,
) => Promise<ITerminalClient>;

主要变更点1为同步函数转为异步函数。
主要变更点2为 options 参数，ITerminalClientFactory2 中需要传入一个 ICreateTerminalOptions，类型定义如下：

export interface ICreateTerminalOptions {
  /**
   * The shell launch config or profile to launch with, when not specified the default terminal
   * profile will be used.
   */
  config?: IShellLaunchConfig | ITerminalProfile;
  /**
   * The current working directory to start with, this will override IShellLaunchConfig.cwd if
   * specified.
   */
  cwd?: string | Uri;
  /**
   * The terminal's resource, passed when the terminal has moved windows.
   */
  resource?: Uri;
  /**
   * The terminal's location (editor or panel), it's terminal parent (split to the right), or editor group
   */
  location?: ITerminalLocationOptions;
}

该 options 描述了创建终端需要的信息，所有参数都为可选，如果 object 为空，则在之后的逻辑会自动获取默认 Profile。

然后通过 TerminalClientFactory.createClient2 创建终端，在 TerminalClient.init2 中获取：

if (!options || Object.keys(options).length === 0) {
  // 应该是必定能 resolve 到 profile 的
  const defaultProfile = await this.terminalProfileInternalService.resolveDefaultProfile();
  options = {
    config: defaultProfile,
  };
}

然后通过 const launchConfig = this.convertProfileToLaunchConfig(options.config, this._workspacePath); 将 Profile 转换为 LaunchConfig，随后启动。

// 待补充

由主要变更引起的其他变更请看代码。

主要变更时间

某些 Deprecated 的时间：
暂定 2.17.0 后

尚未实现的点

1. 终端 icon
   需要我们自己绘制一些常用终端的图标。
2. 终端下拉框选择器
3. 终端分栏 可选择
4. 实现创建 Contributed Terminal 的部分
   1. 发送 onTerminalProfile 激活事件
   2. 根据选择器结果创建 Terminal

[Aaaaash]

这个功能是不是还需要UI做适配？

[bytemain]

之后再实现那个选取某个 Profile 的功能吧

[erha19]

终端 icon

目前有一批 icon 在 https://opensumi.github.io/core/ , 可能需要进一步归类一下，之前有建过一个 Issue #216

终端下拉框选择器

这个看了一下我们界面可以在 ... 菜单里面加的感觉

[bytemain]

#92 带来的变更：

feat:
支持展示终端启动失败的原因。
支持配置 TerminalProfile 配置项。
支持插件 API： vscode.window.registerTerminalProfileProvider

breaking change:
异步启动终端。
启动终端的一些方法、接口改变，均已做了兼容。