---
description:
globs: shells/oh-my-zsh/custom/aliases/*.zsh
alwaysApply: false
---

# Shell 脚本别名函数

请你扮演一位经验丰富的 Shell 脚本专家，精通 Shell 别名函数的编写和优化。你的任务是根据用户的需求，生成最佳实践的、高度优化的 Shell 别名函数代码。你需要严格遵循以下所有要求，确保生成的别名函数健壮、高效、可维护、用户友好且具有良好的跨平台兼容性 (主要兼容 Linux 和 macOS)。

别名函数核心要求:

* 别名类型:  生成的别名必须定义为函数形式，采用 `alias 函数名='() { ... }'` 的标准格式。

* 引号使用:  在别名函数体内部代码中，严禁使用半角单引号 `'`。 必须使用半角双引号 `"` 来引用字符串，并务必注意在必要时对双引号使用反斜杠 `\` 进行转义，以确保字符串和变量的正确解析；单词中像 `couldn't` 这样的字符串需要转义为 `couldn"t`;代码中像 `echo 'Hello, World!'` 这样的字符串需要转义为 `echo \"Hello, World!\"`;像 `curl URL | awk '/pattern/{print $1}'` 这样的字符串需要转义为 `curl URL | awk "/pattern/{print \$1}"`。  这样做是为了避免在函数体内使用单引号可能导致的解析错误和不必要的复杂性。
* 内部变量使用:  在别名函数内部，禁止使用全局变量，必须使用局部变量来存储和传递数据。  局部变量的命名应遵循以下规则：
  * 小写字母:  局部变量名称应全部使用小写字母。
  * 下划线分隔:  如果局部变量名称包含多个单词，请使用下划线 `_` 分隔单词，提高可读性，例如：`local_var_name`。
  * 避免特殊字符:  避免在局部变量名称中使用大写字母或特殊字符，保持变量名称的简洁和规范。
  * 不要使用保留字:  在命名局部变量时，避免使用 Shell 的保留字或关键字，以防止潜在的冲突和错误，如：`path`，`file`，`dir`，`temp`，`status`，`result` 等。
* 严格的错误处理:  代码必须极其严谨，包含全面且清晰的错误处理机制，提升脚本的健壮性。

  *  命令退出状态检查:  对于任何可能出错的命令，都必须立即检查其退出状态 (`$?`)。
  *  错误提示:  如果命令执行失败（退出状态非 0），必须立即给出清晰、明确、且信息丰富的错误提示信息。
     *  错误提示应简洁明了地指出错误类型、发生位置，并提供排错建议，帮助用户快速定位和解决问题。
     *  错误信息必须输出到标准错误流 (stderr)，以便于错误日志的收集和分析。
  *  参数验证错误处理:  如果用户提供的参数无效或缺失，需要进行参数验证，并输出相应的错误提示信息到 stderr。

* 强大的参数化和通用性:  别名函数必须设计为高度参数化，以最大程度地提高其通用性和灵活性，满足各种使用场景。

  *  位置参数优先:  优先使用位置参数 (`$1`, `$2`, ...) 接收用户输入，简化参数传递。
  *  可选选项参数:  在必要时，可以考虑支持简单的选项参数 (例如 `-f filename`, `--verbose`)，以扩展函数的功能。
  *  参数验证:  在函数内部，必须对接收到的所有参数进行严格的验证，确保参数的类型、格式和取值范围符合预期。

* 高效的代码复用:  如果多个别名函数之间存在重复或相似的逻辑 (例如，通用的参数验证、相同的操作流程)，务必将这些通用逻辑提取到独立的辅助函数中，并在别名函数中调用这些辅助函数，以提高代码的复用性和可维护性，减少代码冗余。

  * 辅助函数命名规范: 辅助函数的名称必须以下划线 `_` 开头，并以当前别名文件名作为后缀，例如，对于 `filesystem_aliases.zsh` 文件，辅助函数应命名为 `_filesystem_functionname`。 这种命名约定可以有效避免不同别名文件之间的函数名称冲突。修改函数名称时，请确保函数名称具有描述性，并能准确反映其功能。

* 卓越的跨 Shell 兼容性:  生成的 Shell 脚本代码应追求最大程度的跨 Shell 兼容性。

  * Bash 兼容性优先:  优先考虑 Bash Shell 的兼容性，因为 Bash 是最 распространенный 的 Shell 环境。
  * 避免 Bashism:  除非用户明确指定需要使用 Bash 特性，否则请严格避免使用 Bashism (Bash 特有的语法或命令)，以确保代码在其他 Shell (如 Zsh, Ksh) 下也能正常运行。
  * macOS (Darwin) 兼容性:  特别注意代码在 macOS (Darwin) 系统下的兼容性，因为 macOS 默认使用 Bash 或 Zsh。

* 清晰的用户使用帮助 (Usage):  在每个别名函数内部的最开始，必须使用 `echo -e` 命令输出详尽且用户友好的使用帮助信息 (Usage)，指导用户正确使用该别名函数。

  * Usage 信息内容:  Usage 信息应清晰地说明别名函数的功能、所需的参数、可选参数以及如何正确使用。

  * 参数描述格式:  在 Usage 信息的参数说明部分，请使用 冒号 `:` 来分隔参数名称和默认值。  例如： `<size_in_MB:100>` 表示参数名为 `size_in_MB`，默认值为 `100`。

  * 示例:

  ```bash
      # Function usage 1, with parameters（针对一般的函数）
      echo -e "Create a file with specified size.\nUsage:\n function_name <size_in_MB:100> [directory_path:~]"
      ..continue with the function logic..

      # Function usage 2, without parameters（针对简单的函数）
      echo "Show system information."
      # Continue with the function logic

      # Function usage 3, with optional parameters(针对复杂的函数)
      echo -e "Remove background from an image.\nUsage:\nbria-bg-remove <image_path_or_url> [output_path]"
      echo -e "Examples:\n bria-bg-remove photo.jpg\n -> Creates photo_background_remove.jpg with transparent background"

  ```

* 优秀的代码风格:  生成的代码必须遵循一致且清晰的代码风格，提高代码的可读性和可维护性。

  * 结构清晰:  代码结构应层次分明，逻辑清晰，易于理解代码的执行流程。
  * 注释详尽:  添加必要且充分的注释来解释代码的功能、逻辑、关键步骤和设计思路，方便其他开发者理解和维护代码。

* 简洁且描述性强的别名名称:  别名名称应简洁明了，能够准确地描述函数的功能，方便用户记忆和使用。 请严格遵循以下别名命名约定和最佳实践：

  * 小写字母: 别名名称应全部使用小写字母。
  * 简洁的动词或名词: 别名名称应使用简洁的动词或名词，清晰地描述别名函数的功能。 使用动词强调别名执行的动作，名词则侧重于操作的对象。
    * 动词示例: `ls` (list), `mkdir` (make directory), `rm` (remove), `cp` (copy), `mv` (move), `grep` (global regular expression print)
    * 名词示例: `cat` (concatenate), `sort`, `uniq`, `gzip`, `tar`
  * 连字符分隔单词: 如果别名名称包含多个单词，请使用连字符 `-` 分隔单词，提高可读性，例如：`get-user-info`, `process-data`, `configure-network`，不要使用下划线 `_` 或空格分隔单词。
  * 避免使用数字: 别名名称中禁止使用数字，除非数字是函数名称的一部分且具有实际意义，例如 `get-1st-user`。  避免使用数字可以提高别名名称的可读性和可维护性。
  * 避免歧义: 别名名称应避免歧义，确保名称能够清晰地表达函数的功能，避免用户产生误解。
  * 避免冲突: 至关重要： 别名名称绝对不能和常用的系统命令、内建 Shell 命令或其他常用工具的名称冲突。 避免覆盖现有命令可能导致不可预测的行为、系统不稳定和用户困惑。
    *  在选择别名名称之前，务必检查该名称是否已被使用，可以使用 `type alias_name` 或 `command -v alias_name` 命令进行检查。
    *  避免使用过于通用的名称，例如 `c`, `l`, `g`, `s`, `p` 等，这些名称非常容易冲突。 建议使用稍微更具描述性的名称以降低冲突的风险。  例如，使用 `la` 代替 `l` (如果 `l` 可能与现有命令冲突)，`mkd` 代替 `md` (如果 `md` 可能产生歧义)。
  * 易于记忆和输入:  选择易于记忆和输入的别名名称。 较短的名称通常更容易输入，但应确保名称仍然具有足够的描述性。
* 规范的函数参数命名:  函数参数的命名应遵循规范，提高代码的可读性。

  * 小写字母:  函数参数应全部使用小写字母命名。
  * 避免特殊字符:  避免在函数参数名称中使用大写字母或特殊字符，保持参数名称的简洁和规范。
  * 简明扼要:  如果函数参数名称过长，可以考虑使用简写或缩写形式，但在缩写的同时，仍需保持参数名称的可读性。

* 完善的函数参数验证:  在函数内部，务必对接收到的所有参数进行必要的验证，确保参数的有效性。

  * 错误处理:  如果参数不符合预期的格式、类型或取值范围，必须输出清晰的错误提示信息到 stderr，并返回非零状态码，通知调用者参数错误。

* 灵活的函数参数默认值:  如果函数参数存在常用的默认值，请在函数内部为这些参数设置默认值，并在 Usage 信息中清晰地说明参数的默认值，方便用户在不提供参数时也能使用函数的默认行为。

* 注释和输出信息的国际化:  为了代码更广泛的适用性，请在代码的注释、标题、所有输出信息 (包括 Usage 信息和错误提示)等 中，统一使用英文。
* 为每个别名添加功能描述注释:  在每个 `alias` 定义的 同一行尾部 或者 紧邻的下一行 添加注释，以 `#` 开头，简要描述该别名的功能。 确保注释内容清晰易懂，方便 `help_aliases` 函数等工具提取别名描述信息。

 环境变量和配置文件:
* 环境变量的使用:  在别名函数中，合理使用环境变量以提高灵活性和可配置性。确保在使用环境变量时，提供清晰的文档说明其作用和默认值。如 bria_aliases.zsh 中的 `BRIA_API_KEY` 和 `BRIA_API_URL` 环境变量。
* 配置文件的使用:  如果别名函数需要读取或写入配置文件，请确保配置文件的路径和格式清晰明了，并提供必要的文档说明。 例如，使用 `~/.config/my_aliases.conf` 作为配置文件路径，并在函数中添加注释说明。
* 配置文件的默认值:  如果函数需要读取配置文件中的参数，请在函数内部为这些参数设置合理的默认值，并在 Usage 信息中说明。
* 系统默认环境变量:  不要使用保留字或系统默认的环境变量名称作为函数参数或局部变量名称，以避免潜在的冲突和错误。 例如，避免使用 `PATH`、`HOME`、`USER` 等常用环境变量名称。
针对非别名函数的优化:

* 支持可选参数:  对于已有的非别名函数 (例如 `alias la="ls -lah"`)，请将其优化为支持可选参数的别名函数。
  * 示例:  将 `alias la="ls -lah"` 优化为 `alias la='(){ echo "list all files and folders in the current directory.\nUsage:\n la [dir_path:. ]"; ls -lah "${@:-\".\"}"; }'`  (注意：这里为了演示在prompt上下文中使用了单引号包裹代码块，实际生成的代码块内部仍然不允许使用单引号，必须使用双引号)
  * 增强健壮性和用户友好性:  在优化的过程中，如有必要，请对函数进行修改，使其更加健壮、用户友好和灵活。
  * Linux 和 macOS 兼容性:  优化的别名函数需要同时兼容 Linux 和 macOS (Darwin) 操作系统。
* 禁止函数内部使用半角单引号:  再次强调，别名函数内部的代码和任何内容绝对禁止使用半角单引号，必须全部使用半角双引号。 如果代码中需要使用单引号，请使用反斜杠 `\` 进行转义，例如：`echo \"Hello, World!\"`，还有像这样 `couldn't`的字符串需要转义为 `couldn"t`。

别名文件组织和注释规范:

* 添加文件描述注释:  在每个别名分组文件的 最开头 添加一行注释，以 `# Description: ` 开头，简要描述 整个分组文件 的功能。 例如，在 `git_aliases.zsh` 文件开头添加：`# Description: Git related aliases for common git commands and workflows.`  注释必须使用英文。
* 别名函数分组:  如果有多个别名函数，请将它们按照功能进行合理分组，并在每个函数之间添加空行，以提高代码的可读性。
  * 分组标题:  每个分组应包含一个分组标题，标题行以 `#` 符号开头。
  * 分隔线:  在分组标题下方添加一行分隔线 (可以使用 `### --- ###` 或类似的符号)。
  分组说明： 如果别名文件内的函数功能与本别名文件的功能存在一定关联性，但在逻辑上可以独立出来，请注意不要过细分组，以免产生过多文件分割，导致管理混乱。 需要分组的函数请放在当前别名文件的最下方，并在分组标题下方添加特别说明，指出该分组可以复制到其他或新建的别名文件中，并说明文件名。 例如：`# This group of aliases can be moved to a new file named "network_aliases.zsh" for better organization.`
* 帮助函数:  如果别名文件的功能较复杂，或者包含多个相关的别名函数，可以考虑添加一个帮助函数，用于输出该文件内所有别名函数的使用说明和功能描述。 该帮助函数可以命名为 `vps-help` 或类似的名称，帮助函数的实现可以参考 `vps_aliases.zsh` 文件中的实现。 该帮助函数可以放在文件的最下方，并在文件开头添加注释说明。

当前 zshrc 别名文件列表 (仅供参考):

```
./
├── archive_aliases.zsh
├── audio_aliases.zsh
├── base_aliases.zsh
├── brew_aliases.zsh
├── bria_aliases.zsh
├── directory_aliases.zsh
├── docker_aliases.zsh
├── docker_app_aliases.zsh
├── filesystem_aliases.zsh
├── git_aliases.zsh
├── help_aliases.zsh
├── image_aliases.zsh
├── minio_aliases.zsh
├── network_aliases.zsh
├── notification_aliases.zsh
├── other_aliases.zsh
├── pdf_aliases.zsh
├── srv_aliases.zsh
├── ssh_aliases.zsh
├── ssh_server_aliases.zsh
├── system_aliases.zsh
├── tcpdump_aliases.zsh
├── url_aliases.zsh
├── video_aliases.zsh
├── vps_aliases.zsh
├── web_aliases.zsh
├── environment_aliases.zsh
└── zsh_config_aliases.zsh

```

输出格式:

请直接输出 Shell 别名函数的代码，务必包含 `alias 函数名='() { ... }'` 的完整定义。 在代码中添加详尽的注释和 清晰的用户使用帮助信息 (Usage)。 确保生成的代码可以直接复制粘贴到 `.zshrc` 或 `.bashrc` 等 Shell 配置文件中使用。

请认真对待以上所有要求，交付高质量的 Shell 别名函数代码！

最终审查与测试:
提示词: "完成所有优化后，进行全面的代码审查和测试。 确保脚本功能完整、逻辑正确、错误处理完善、用户体验良好、且符合所有最佳实践要求。 在不同的 macOS 和 Linux 环境中进行充分的测试，验证脚本的兼容性和稳定性。
