refactor🎨: (阅读代码)：mananger.ts关联文件增加注释

src/config.ts

@@ -454,27 +454,53 @@ export async function deleteConfig(config: FileSystemConfig) {
  * Otherwise, if it contains a `@`, we parse it as a connection string.
  * If this results in no (valid) configuration, `undefined` is returned.
  */
+/**
+ * 根据输入的字符串获取文件系统配置。
+ * 如果输入的字符串是一个已存在的配置名称（不区分大小写），则返回该配置。
+ * 如果输入的字符串包含 '@' 符号，则尝试将其解析为一个连接字符串，并返回相应的配置。
+ * 如果解析后的配置中的主机名与已存在的配置名称匹配，则返回该配置。
+ * 如果没有找到匹配的配置，则返回解析后的配置。
+ * 如果解析后的配置是一个即时连接字符串，则将主机名替换为会话名称，并标记该配置为合并配置。
+ * @param input - 要查找的配置的名称或连接字符串。
+ * @returns 找到的文件系统配置或 undefined，如果没有找到匹配的配置。
+ */
 export function getConfig(input: string): FileSystemConfig | undefined {
+  // 将输入字符串转换为小写，以便进行不区分大小写的比较
   const lower = input.toLowerCase();
+  // 查找已加载的配置中是否存在名称与输入字符串匹配的配置
   const loaded = getConfigs().find(c => c.name.toLowerCase() === lower);
+  // 如果找到匹配的配置，则直接返回该配置
   if (loaded) return loaded;
+  // 如果输入字符串不包含 '@' 符号，则返回 undefined
   if (!input.includes('@')) return undefined;
+  // 尝试解析输入字符串为连接字符串
   const parseString = parseConnectionString(input);
+  // 如果解析失败（返回类型为字符串），则返回 undefined
   if (typeof parseString === 'string') return undefined;
+  // 从解析结果中提取第一个配置对象
   const [parsed] = parseString;
   // If we're using the instant connection string, the host name might be a config name
+  // 如果我们使用的是即时连接字符串，主机名可能是一个配置名称，我们需要将其替换为会话名称，并标记该配置为合并配置
   const existing = getConfigs().find(c => c.name.toLowerCase() === parsed.host!.toLowerCase());
+  // 如果找到匹配的配置
   if (existing) {
+    // 记录日志，说明 getConfig 函数的调用导致了一个配置名称与现有配置名称相匹配
     Logging.info`getConfig('${input}') led to '${parsed.name}' which matches config '${existing.name}'`;
     // Take the existing config, but (more or less) override it with the values present in `parsed`
     // `name` be the same as in `parsed`, meaning it can be reused with `getConfig` on window reload.
+    // 合并现有配置和解析后的配置，优先使用解析后的配置中的值
     return {
+      // 复制现有配置的所有属性，复制解析后的配置的所有属性
       ...existing, ...parsed,
+      // 如果现有配置中存在 host 属性，则使用现有配置的 host 属性，否则使用解析后的配置的 host 属性
       host: existing.host || parsed.host, // `parsed.host` is the session name, which might not be the actual hostname
+      // 由于这是一个合并配置，我们将 _location 属性标记为 undefined
       _location: undefined, // Since this is a merged config, we have to flag it as such
+      // 合并现有配置和解析后的配置的 _locations 属性
       _locations: [...existing._locations, ...parsed._locations], // Merge locations
     };
   }
+  // 如果没有找到匹配的配置，则直接返回解析后的配置
   return parsed;
 }
 

src/connection.ts

@@ -11,20 +11,35 @@ import { calculateShellConfig, KNOWN_SHELL_CONFIGS, ShellConfig, tryCommand, try
 import type { SSHFileSystem } from './sshFileSystem';
 import { mergeEnvironment, toPromise } from './utils';
 
+/**
+ * 表示一个 SSH 连接的配置和状态。
+ */
 export interface Connection {
+    // 文件系统的配置。
     config: FileSystemConfig;
+    // 实际使用的文件系统配置。
     actualConfig: FileSystemConfig;
+    // SSH 客户端实例。
     client: Client;
+    // 用户的主目录。
     home: string;
+    // Shell 配置。
     shellConfig: ShellConfig;
+    // 环境变量。
     environment: EnvironmentVariable[];
+    // 伪终端列表
     terminals: SSHPseudoTerminal[];
+    // 文件系统列表。
     filesystems: SSHFileSystem[];
+    // 缓存数据。
     cache: Record<string, any>;
+    // 等待连接的用户数量。
     pendingUserCount: number;
+    //空闲计时器。
     idleTimer: NodeJS.Timeout;
 }
 
+
 export class ConnectionManager {
     protected onConnectionAddedEmitter = new vscode.EventEmitter<Connection>();
     protected onConnectionRemovedEmitter = new vscode.EventEmitter<Connection>();

src/extension.ts

@@ -77,6 +77,35 @@ export let MANAGER: Manager | undefined;
  * 
  * @param context - 扩展上下文，包含扩展的各种资源和服务。
  */
+/** 流程图
+ * @startuml
+ * start
+ * :记录接收到的配置命令信息;
+ * if (目标是一个对象) then (是)
+ *   :检查对象是否有 _location 或 _locations 属性;
+ *   if (没有) then (是)
+ *     :显示错误信息;
+ *     :结束;
+ *   else (否)
+ *     :打开设置界面，导航到编辑配置页面;
+ *     :结束;
+ *   endif
+ * else (否)
+ *   :将目标字符串转换为小写;
+ *   :加载所有配置;
+ *   :过滤出名称与目标匹配的配置;
+ *   if (没有找到匹配的配置) then (是)
+ *     :显示错误信息;
+ *     :记录错误信息;
+ *     :结束;
+ *   else (否)
+ *     :如果只有一个匹配的配置，直接使用它;
+ *     :打开设置界面，导航到编辑配置页面;
+ *   endif
+ * endif
+ * stop
+ * @enduml
+ */
 export function activate(context: vscode.ExtensionContext) {
   // 通过 VS Code API 获取名为 'Kelvin.vscode-sshfs' 的扩展实例
   const extension = vscode.extensions.getExtension('Kelvin.vscode-sshfs');
@@ -132,7 +161,26 @@ export function activate(context: vscode.ExtensionContext) {
   // I really don't like having to pass context to *everything*, so let's do it this way
   // 真的很糟糕，我们确实需要扩展上下文（ExtensionContext）来获取相对资源。
   // 我真的不喜欢必须将上下文传递给所有东西，所以让我们这样做吧。  
-  // 将 context.asAbsolutePath 方法绑定到当前上下文中，并赋值给 setAsAbsolutePath 变量
+  // 将 context.asAbsolutePath 方法绑定到当前上下文中，并赋值给 asAbsolutePath 变量
+  // 这样，我们就可以在代码中使用 asAbsolutePath 变量来获取相对路径的绝对路径
+  /** Function 实例的 bind() 方法创建一个新函数，当调用该新函数时，它会调用原始函数并将其 this 关键字设置为给定的值，
+    * 同时，还可以传入一系列指定的参数，这些参数会插入到调用新函数时传入的参数的前面。
+    * 示例
+    * const module = {
+    *   x: 42,
+    *   getX: function () {
+    *     return this.x;
+    *   },
+    * };
+    * 
+    * const unboundGetX = module.getX;
+    * console.log(unboundGetX()); // The function gets invoked at the global scope
+    * // Expected output: undefined
+    *  
+    * const boundGetX = unboundGetX.bind(module);
+    * console.log(boundGetX());
+    * // Expected output: 42
+   */
   setAsAbsolutePath(context.asAbsolutePath.bind(context));
 
   // 创建一个 Manager 实例，并将其赋值给全局变量 MANAGER

src/manager.ts

@@ -107,6 +107,74 @@ export class Manager implements vscode.TaskProvider, vscode.TerminalLinkProvider
    * @param {FileSystemConfig} config - 文件系统的配置
    * @returns {Promise<SSHFileSystem>} - 当文件系统创建完成时解析的 Promise
    */
+  /** 类图
+   * @startuml
+   * class SSHFileSystemManager {
+   *   + createFileSystem(name: string, config?: FileSystemConfig): Promise<SSHFileSystem>
+   *   + createTerminal(name: string, config?: FileSystemConfig | Connection, uri?: vscode.Uri): Promise<void>
+   *   + getActiveFileSystems(): readonly SSHFileSystem[]
+   *   + getFs(uri: vscode.Uri): SSHFileSystem | null
+   *   + promptReconnect(name: string): Promise<void>
+   * }
+   * class SSHFileSystem {
+   *   + onClose(handler: () => void): void
+   * }
+   * class Connection {
+   *   + actualConfig: FileSystemConfig
+   *   + filesystems: SSHFileSystem[]
+   *   + pendingUserCount: number
+   *   + home: string
+   *   + client: any
+   * }
+   * class FileSystemConfig {
+   *   + flags: any
+   * }
+   * SSHFileSystemManager --> Connection : uses
+   * SSHFileSystemManager --> SSHFileSystem : creates
+   * SSHFileSystem --> Connection : belongs to
+   * Connection --> FileSystemConfig : has
+   * @enduml
+   */
+  /** 流程图
+   * @startuml
+   * start
+   * :防止启动时的竞态条件，并等待当前配置重载完成;
+   * if (检查是否已经存在一个具有指定名称的 SSHFileSystem 实例?) then (yes)
+   *   :如果存在，则直接返回该实例;
+   * else (no)
+   *   :声明一个名为 con 的变量，用于存储即将创建的 Connection 实例;
+   *   :尝试从 creatingFileSystems 中获取已存在的 Promise，如果不存在则创建一个新的 Promise;
+   *   :获取文件系统配置;
+   *   if (如果没有提供配置?) then (yes)
+   *     :如果没有找到配置，则抛出错误;
+   *   else (no)
+   *   :创建一个新的连接;
+   *   :更新连接管理器中的连接信息;
+   *   :获取连接的实际配置;
+   *   :导入 getSFTP 和 SSHFileSystem 模块;
+   *   :使用连接的实际配置创建 SFTP 会话;
+   *   :创建一个新的 SSH 文件系统实例;
+   *   :记录日志，表示已创建 SSH 文件系统并正在读取根目录;
+   *   :添加文件系统到连接管理器，更新连接管理器中的文件系统列表;
+   *   :将新创建的文件系统添加到 fileSystems 数组中;
+   *   :从 creatingFileSystems 中删除该文件系统的 Promise;
+   *   :监听文件系统的关闭事件，当文件系统关闭时，从 fileSystems 数组中删除该文件系统，并更新连接管理器中的文件系统列表;
+   *   :刷新文件资源管理器，以显示新创建的文件系统;
+   *   :更新连接管理器中的连接信息;
+   *   if (检查是否可以访问主目录?) then (yes)
+   *     :解决 Promise，返回创建的文件系统实例;
+   *   else (no)
+   *     :show error message and options;
+   *     if (如果用户选择停止?) then (yes)
+   *       :则拒绝 Promise 并抛出错误;
+   *     else (no)
+   *       :解决 Promise，返回创建的文件系统实例;
+   *     endif
+   *   endif
+   * endif
+   * stop
+   * @enduml
+   */
   public async createFileSystem(name: string, config?: FileSystemConfig): Promise<SSHFileSystem> {
     await LOADING_CONFIGS; // Prevent race condition on startup, and wait for any current config reload to finish 防止启动时的竞态条件，并等待当前配置重载完成
     // 检查是否已经存在一个具有指定名称的 SSHFileSystem 实例
@@ -117,7 +185,7 @@ export class Manager implements vscode.TaskProvider, vscode.TerminalLinkProvider
     let con: Connection | undefined;
     // 尝试从 creatingFileSystems 中获取已存在的 Promise，如果不存在则创建一个新的 Promise
     return this.creatingFileSystems[name] ||= catchingPromise<SSHFileSystem>(async (resolve, reject) => {
-      // 如果没有提供配置，则从默认配置中获取
+      // 获取文件系统配置，如果没有提供配置，则尝试从配置管理器中获取
       config ||= getConfig(name);
       // 如果没有找到配置，则抛出错误
       if (!config) throw new Error(`Couldn't find a configuration with the name '${name}'`);
@@ -221,6 +289,21 @@ export class Manager implements vscode.TaskProvider, vscode.TerminalLinkProvider
    * @param {vscode.Uri} uri - URI 对象，指定终端的工作目录
    * @returns {Promise<void>} - 当终端创建完成时解析的 Promise
    */
+  /** 流程图
+   * @startuml
+   * start
+   * :导入 createTerminal 模块;
+   * :创建连接（如果配置中没有提供连接）;
+   * :更新连接管理器中的连接信息（pendingUserCount 加 1）;
+   * :创建伪终端实例;
+   * :监听伪终端关闭事件;
+   * :更新连接管理器中的连接信息（移除已关闭的伪终端，pendingUserCount 减 1）;
+   * :创建并显示图形终端;
+   * :将伪终端实例与图形终端关联;
+   * :显示图形终端;
+   * end
+   * @enduml
+   */
   public async createTerminal(name: string, config?: FileSystemConfig | Connection, uri?: vscode.Uri): Promise<void> {
     const { createTerminal } = await import('./pseudoTerminal');
     // Create connection (early so we have .actualConfig.root)
@@ -421,6 +504,24 @@ export class Manager implements vscode.TaskProvider, vscode.TerminalLinkProvider
    * @param {FileSystemConfig} config - 文件系统的配置
    * @returns {Promise<void>} - 当连接完成时解析的 Promise
    */
+  /** 流程图
+   * @startuml
+   * start
+   * :记录接收到的连接命令信息;
+   * :获取当前工作区的文件夹;
+   * :在工作区文件夹中查找是否已经存在指定名称的 SSH 文件系统;
+   * if (已经存在) then (是)
+   *   :刷新文件资源管理器;
+   *   :结束;
+   * else (否)
+   *   :获取文件系统的根目录，默认值为 '/';
+   *   :如果根目录以 '~' 开头，则将其替换为连接的主目录;
+   *   :如果根目录以 '/' 开头，则去除开头的 '/';
+   *   :更新工作区文件夹，添加新的 SSH 文件系统;
+   * endif
+   * stop
+   * @enduml
+   */
   public async commandConnect(config: FileSystemConfig) {
     // 记录接收到的连接命令信息
     Logging.info`Command received to connect ${config.name}`;
@@ -452,6 +553,27 @@ export class Manager implements vscode.TaskProvider, vscode.TerminalLinkProvider
    * @param target - 要断开连接的文件系统的名称或连接对象
    * @returns {Promise<void>} - 当断开连接完成时解析的 Promise
    */
+  /** 流程图
+   * @startuml
+   * start
+   * :记录接收到的断开连接命令信息;
+   * :初始化一个数组来存储要断开连接的连接对象;
+   * if (目标是一个对象并且包含 'client' 属性) then (是)
+   *   :将目标连接对象添加到数组中;
+   *   :获取目标连接对象的实际配置名称;
+   * else (否)
+   *   :获取所有活动连接中名称与目标匹配的连接对象;
+   * endif
+   * :遍历所有要断开连接的连接对象，调用连接管理器的 closeConnection 方法来关闭它们;
+   * :获取所有活动连接中名称与目标相同的其他连接对象;
+   * if (没有其他相同名称的文件系统连接) then (是)
+   *   :直接返回;
+   * else (否)
+   *   :移除所有相关的工作区文件夹;
+   * endif
+   * stop
+   * @enduml
+   */
   public commandDisconnect(target: string | Connection) {
     // 记录接收到的断开连接命令信息
     Logging.info`Command received to disconnect ${commandArgumentToName(target)}`;
@@ -503,6 +625,24 @@ export class Manager implements vscode.TaskProvider, vscode.TerminalLinkProvider
    * @param uri - 可选的 URI 对象，指定终端的工作目录
    * @returns {Promise<void>} - 当终端创建完成时解析的 Promise
    */
+  /** 流程图
+   * @startuml
+   * start
+   * :记录接收到的连接命令信息;
+   * :获取当前工作区的文件夹;
+   * :在工作区文件夹中查找是否已经存在指定名称的 SSH 文件系统;
+   * if (已经存在) then (是)
+   *   :刷新文件资源管理器;
+   *   :结束;
+   * else (否)
+   *   :获取文件系统的根目录，默认值为 '/';
+   *   :如果根目录以 '~' 开头，则将其替换为连接的主目录;
+   *   :如果根目录以 '/' 开头，则去除开头的 '/';
+   *   :更新工作区文件夹，添加新的 SSH 文件系统;
+   * endif
+   * stop
+   * @enduml
+   */
   public async commandTerminal(target: FileSystemConfig | Connection, uri?: vscode.Uri) {
     // 记录接收到的打开终端命令信息
     Logging.info`Command received to open a terminal for ${commandArgumentToName(target)}${uri ? ` in ${uri}` : ''}`;
@@ -527,6 +667,35 @@ export class Manager implements vscode.TaskProvider, vscode.TerminalLinkProvider
    * @param target - 要配置的文件系统的名称或配置对象
    * @returns {Promise<void>} - 当配置完成时解析的 Promise
    */
+  /** 流程图
+   * @startuml
+   * start
+   * :记录接收到的配置命令信息;
+   * if (目标是一个对象) then (是)
+   *   :检查对象是否有 _location 或 _locations 属性;
+   *   if (没有) then (是)
+   *     :显示错误信息;
+   *     stop
+   *   else (否)
+   *     :打开设置界面，导航到编辑配置页面;
+   *     stop
+   *   endif
+   * else (否)
+   *   :将目标字符串转换为小写;
+   *   :加载所有配置;
+   *   :过滤出名称与目标匹配的配置;
+   *   if (没有找到匹配的配置) then (是)
+   *     :显示错误信息;
+   *     :记录错误信息;
+   *     :结束;
+   *   else (否)
+   *     :如果只有一个匹配的配置，直接使用它;
+   *     :打开设置界面，导航到编辑配置页面;
+   *   endif
+   * endif
+   * stop
+   * @enduml
+   */
   public async commandConfigure(target: string | FileSystemConfig) {
     // 记录接收到的配置命令信息
     Logging.info`Command received to configure ${typeof target === 'string' ? target : target.name}`;

src/utils.ts

@@ -17,40 +17,67 @@ function trimError(error: Error, depth: number): [string[], Error] {
     Error.prepareStackTrace = pst;
     return [trimmed.split('\n').slice(1), error];
 }
+/**
+ * 捕获 Promise 执行过程中的错误，并在错误堆栈中添加额外信息
+ * @param executor - 执行器函数，接受 resolve 和 reject 函数作为参数
+ * @param trimStack - 堆栈跟踪中要修剪的帧数
+ * @param causeName - 附加到错误对象的名称
+ * @returns 一个 Promise，成功时返回执行器函数的结果，失败时返回带有额外信息的错误
+ */
 /** Wrapper around async callback-based functions */
 export async function catchingPromise<T>(executor: (resolve: (value?: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => any, trimStack = 0, causeName = 'catchingPromise'): Promise<T> {
+    // 声明一个包含两个元素的数组，其中第一个元素是一个字符串数组，第二个元素是一个错误对象
     let [trimmed, promiseCause]: [string[], Error] = [] as any;
     return new Promise<T>((resolve, reject) => {
+        // 使用 trimError 函数处理新创建的错误对象，并设置要修剪的堆栈帧数
         [trimmed, promiseCause] = trimError(new Error(), trimStack + 2);
+        // 如果 DEBUG 模式开启，则修改 promiseCause 的堆栈跟踪信息
         if (DEBUG) promiseCause.stack = promiseCause.stack!.split('\n', 2)[0] + trimmed.map(l => l.replace('at', '~at')).join('\n') + '\n' + promiseCause.stack!.split('\n').slice(1).join('\n');
         try {
+            // 执行传入的执行器函数，并获取其返回的 Promise
             const p = executor(resolve, reject);
+            // 如果返回的是 Promise，则捕获其拒绝事件
             if (p instanceof Promise) {
                 p.catch(reject);
             }
         } catch (e) {
+            // 如果执行器函数抛出异常，则拒绝 Promise，并将错误对象传递给 reject 函数
             reject(e);
         }
     }).catch(e => {
+        // 检查捕获的异常是否为 Error 类型的实例
         if (e instanceof Error) {
+            // 获取异常的堆栈跟踪信息
             let stack = e.stack;
+            // 如果堆栈跟踪信息存在
             if (stack) {
+                // 将堆栈跟踪信息分割成行
                 const lines = stack.split('\n');
+                // 查找修剪后的堆栈跟踪信息的第三行在原始堆栈跟踪信息中的索引
                 let index = lines.indexOf(trimmed[3]);
+                // 如果找到了
                 if (index !== -1) {
+                    // 计算新的索引，减去 2 是因为要跳过前两行，trimStack 是用户指定的修剪帧数
                     index -= 2 + trimStack;
+                    // 更新异常的堆栈跟踪信息，只保留前 index 行
                     e.stack = lines[0] + '\n' + lines.slice(1, index).join('\n');
+                    // 如果 DEBUG 模式开启，则在堆栈跟踪信息后面添加修剪后的堆栈跟踪信息，并将 'at' 替换为 '~at'
                     if (DEBUG) e.stack += '\n' + lines.slice(index).map(l => l.replace('at', '~at')).join('\n');
                 }
             }
+            // 尝试获取异常对象的 promiseCause 属性
             let t = (e as any).promiseCause;
+            // 如果 promiseCause 属性不存在或者不是 Error 类型
             if (!(t instanceof Error)) t = e;
+            // 如果异常对象没有 promiseCause 属性
             if (!('promiseCause' in t)) {
+                // 为异常对象定义一个 promiseCause 属性，其值为 promiseCause 变量的值
                 Object.defineProperty(t, 'promiseCause', {
                     value: promiseCause,
                     configurable: true,
                     enumerable: false,
                 });
+                // 为异常对象定义一个 promiseCauseName 属性，其值为 causeName 变量的值
                 Object.defineProperty(t, 'promiseCauseName', {
                     value: causeName,
                     configurable: true,