chsrc 项目工具集完全指南：跨平台安装器、Shell 自动补全与维护脚本详解

本文围绕开源仓库 chsrc 的 tool 目录展开，系统讲解 chsrc 在安装分发、命令行体验与日常维护三个环节所依赖的配套工具：POSIX 平台的 installer.sh、Windows 平台的 installer.ps1、批量拉取 pre 版附件的 download-pre-on-GitHub.ps1、Bash 自动补全脚本 completion/bash_completion.sh，以及面向开发者日常维护的 git-ignore-vscode-settings.ps1 与 C 语言字符串生成工具 rawstr4c。读完本文，你将掌握每个工具的参数用法、底层实现逻辑与适用场景，并能结合源码独立使用或二次开发。

tool 目录总览

tool/ 目录是 chsrc 的"运维与体验工具箱"，承担着让用户"装得上、用得顺、维护得了"的职责。按照 tool/README.md 的官方说明，该目录包含四类内容：

文件/目录	类型	核心用途
installer.sh	Bash 脚本	在类 Unix 系统（Linux、macOS）上一键安装 chsrc
installer.ps1	PowerShell 脚本	在 Windows 上一键安装 chsrc
download-pre-on-GitHub.ps1	PowerShell 脚本	从项目 pre release 批量下载全部平台附件
completion/	目录	Shell 自动补全文件（Bash 自动补全脚本）

此外，tool/ 下还包含一个开发辅助脚本 git-ignore-vscode-settings.ps1，而文档中特别提到的 rawstr4c（C 语言字符串生成工具）原本是本仓库内的一个完整子项目，后为便于维护而拆分到了独立仓库。

installer.sh：类 Unix 平台的一键安装器

installer.sh 是 chsrc 在 Linux、macOS 等 POSIX 平台的主要安装入口，其官方一键命令为 curl https://chsrc.run/posix | bash（对应仓库内的 installer.sh 文件本体，也支持以 bash -s -- 传参）。该脚本支持 -h、-d、-v、-l 四个命令行选项：

选项	作用	默认值
-h	打印帮助信息（支持中英文）	—
-d <dir>	指定安装目录，目录不存在时会自动创建	root 用户默认 /usr/local/bin，非 root 用户默认 ~/.local/bin
-v <version>	指定 chsrc 版本号，合法值须匹配 0.x.y（且 >=0.1.4）或 pre	pre
-l <lang>	指定输出语言，仅支持 zh 与 en	zh

参数解析通过 getopts ":hd:v:l:" 完成，并在进入安装流程前校验 -l 取值、依据 -h 提前退出（见 installer.sh）。若用户传入了非法版本号（例如不满足 ^(pre|0\.([1-9])\.([0-9]))$ 正则的字符串），脚本会直接报错退出；合法的 0.x.y 版本会在构造下载地址前自动加上 v 前缀，而 pre 保持原样（见 set_binary_version()）。

安装流程：从探测环境到落盘执行

整个安装过程由 install() 主函数串联四个步骤（installer.sh）：

1. set_binary_version：校验并规范化用户指定的版本号；
2. set_arch：通过 uname -m 探测 CPU 架构，并做映射——x86_64 → x64，aarch64/arm64 → aarch64，riscv64 → riscv64，armv7* → armv7；不在预编译支持列表中的架构会提示改用 chsrc-bootstrap 或自行编译；
3. set_platform：通过 uname -s 与 uname -o 探测平台——Linux 下若检测到 android 系统标识，会直接改走 Termux bootstrap 流程；darwin 映射为 macos；bsd/dragonfly 与未知平台同样提示自行编译；
4. set_install_dir：按优先级确定安装位置——用户显式指定（-d，且会自动扩展 ~、自动 mkdir -p）> 已存在的 chsrc 可执行文件所在目录（实现"就地更新"）> 两个默认目录中可写者。

随后脚本构造预编译二进制下载地址（命名规则为 chsrc-<arch>-<platform>），调用 download() 函数用 curl 或 wget 静默下载到目标路径，chmod +x 赋予执行权限后即完成安装。download() 优先使用 curl -sL，缺失时回退 wget -qO，两者都不可用时直接报错退出。

目录创建失败后的回滚机制

installer.sh 在安装结束后通过 trap cleanup EXIT 注册了清理钩子：如果脚本运行期间为用户创建过安装目录（记录在 tmp_created_install_dir 变量），退出时会将这个临时目录删除，避免在用户系统上留下半成品目录（见 installer.sh）。

无预编译二进制时的兜底路径

当用户架构或平台没有预编译版本时，脚本会依次引导两条路径（let_user_use_bootstrap 与 let_user_compile）：

• 优先提示参考仓库 bootstrap/ 目录，查找是否已有现成的 bootstrapper 脚本（例如 Termux.bash）；
• 否则引导用户通过 git clone（或 curl/wget 下载源码 zip）获取源码后自行编译，编译命令为 cc/gcc/clang -Iinclude -Ilib src/chsrc-main.c -o chsrc。若系统存在 GNU make，则提示直接 make（installer.sh）。

installer.ps1：Windows 平台的一键安装器

installer.ps1 是 installer.sh 在 Windows 生态的对应实现，仅面向 Windows 系统——脚本开头会检查 $IsMacOS/$IsLinux，若在非 Windows 平台运行则直接提示并退出（installer.ps1）。它同样支持三个参数：

参数	作用	默认值
-h	打印帮助信息	—
-d <dir>	指定安装目录	自动检测系统"下载"目录，失败时回退为当前目录
-v <version>	指定版本号，同样须匹配 0.x.y (>=0.1.4) 或 pre	pre

与 Bash 版相比，它有几点值得注意的实现差异：

• 安装目录的智能检测：未指定 -d 时，脚本会通过注册表键 HKCU:\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders 中 {374DE290-123F-4565-9164-39C4925E467B} 对应的 GUID 读取系统真实的"下载"目录，并展开 %USERPROFILE% 等环境变量；注册表读取失败或目录不存在时回退到当前工作目录（见 Get_System_Downloads_Dir 与 installer.ps1）；
• 架构探测：通过 Get-WmiObject Win32_Processor 读取 CPU 的 Architecture 属性做映射——0 对应 x86、9 根据操作系统位数在 x64/x86 间选择、12 对应 arm64，其余值直接报错退出（installer.ps1）；
• 下载与校验：安装前先强制启用 TLS 1.2，并用 Invoke-WebRequest -Method Head 预检下载地址可达性，通过后才实际下载；下载文件名固定为 chsrc.exe；
• 失败回滚：脚本通过 Register-EngineEvent PowerShell.Exiting 注册清理逻辑，若安装目录是由脚本新建的（create_dir_flag），进程退出时会将其连同内容一并删除。

download-pre-on-GitHub.ps1：批量拉取 pre 版发行附件

download-pre-on-GitHub.ps1 是一个面向维护者与测试者的批量下载工具：它将项目 pre release 下全部平台/架构的发行附件一次性拉到 ~\Desktop\chsrc-pre-on-GitHub（download-pre-on-GitHub.ps1）。

脚本内置了一份完整的附件清单，恰好勾勒出 chsrc 当前预编译二进制覆盖的全貌：

• Windows：chsrc-x64-windows.exe、chsrc-x86-windows.exe、chsrc-arm64-windows.exe；
• macOS：chsrc-aarch64-macos、chsrc-x64-macos；
• Linux：chsrc-x64-linux、chsrc-aarch64-linux、chsrc-riscv64-linux、chsrc-armv7-linux，以及 deb 包 chsrc_latest-1_amd64.deb；
• Android：chsrc-arm64-android。

下载逻辑使用 PowerShell 的 ForEach-Object -Parallel 对附件名列表做并行遍历，并设置 -ThrottleLimit 5 将同时下载数限制为 5，避免瞬时带宽打满；每条下载通过 curl -s -LO --output-dir 完成（-s 用于抑制并行输出下的混乱）。该脚本同样印证了 installer.sh 中架构映射（x64/aarch64/riscv64/armv7）与平台命名（linux/macos/windows/android）的一致性。

completion/bash_completion.sh：Bash 自动补全

completion/ 目录当前收录了 bash_completion.sh，为 chsrc 提供 Bash 命令行补全，目前在 Ubuntu 上测试通过（Zsh 尚未测试）。

补全范围

脚本内置了三组可补全的"菜品"关键词，与 src/recipe/ 目录下真实存在的换源实现一一对应：

• 语言类 dishes_lang：ruby、python/pip/poetry/pdm/rye/uv、npm/yarn/pnpm/nvm/bun、cargo/rustup、go、maven/gradle、clojure、dart/pub/flutter、nuget、haskell、ocaml/opam、r/cran、julia 等（对应 src/recipe/lang 目录）；
• 系统类 dishes_os：ubuntu、linuxmint、debian、fedora、opensuse、arch、manjaro、gentoo、alpine、termux、freebsd、openbsd 等（对应 src/recipe/os 目录）；
• 软件类 dishes_ware：winget、homebrew、cocoapods、docker、flatpak、nix、guix、emacs、tex/texlive、conda/anaconda 等（对应 src/recipe/ware 目录）。

同时还会补全 commands（help、issue、list/ls、measure/cesu、get、set、reset）和 options（-dry、-scope=、-ipv6、-english/-en、-no-color、-h/--help），与 README.md 中 chsrc 的命令行帮助完全吻合。

补全逻辑

脚本通过 COMP_LINE/COMP_POINT 解析当前输入，跳过 - 开头的选项词，取出第一个非选项词作为子命令 cmd，再依据命令分派补全策略：

• 尚未输入命令时，补全"命令 + 选项"；
• list/ls 的第二参数补全 mirror dish os lang ware 等分类词；
• measure、get、set、reset 的第一参数补全全部菜品名；
• set 的第二参数补全 first（对应 chsrc set <dish> first 的"使用维护团队测速第一的源"语义）；
• 选项补全对 -scope=* 做了特殊处理：先补全出 -scope=（通过 compopt -o nospace 禁止尾部空格），让用户继续输入 project/user/system 三个作用域值。

该补全脚本被 Makefile 的 install target 一并安装到系统的 bash-completion 目录（/usr/share/bash-completion/completions/chsrc），也就是说通过 make install 安装的 chsrc 会自动获得 Bash 补全能力；手动使用时仅需 source completion.sh 即可在当前终端立即生效。

开发辅助脚本：git-ignore-vscode-settings.ps1 与 rawstr4c

除面向用户的工具外，tool/ 还包含两个开发者导向的辅助工具：

• git-ignore-vscode-settings.ps1：解决 VS Code 插件频繁改动 .vscode/settings.json 而该文件又需要纳入仓库的问题。脚本通过 git update-index --skip-worktree .\.vscode\settings.json 让 git 忽略该文件的本地变化；需要恢复跟踪时执行 git update-index --no-skip-worktree .\.vscode\settings.json（见 git-ignore-vscode-settings.ps1）。
• rawstr4c：按 tool/README.md 的说明，这是为 chsrc 项目开发的一款 C 语言字符串生成工具，最初作为仓库内的完整子项目存在，后为维护便利拆分至独立仓库继续演进。它是 chsrc 生态中"用生成代替手写字符串"的配套工具，与 doc/10-如何编写recipe.md 中描述的 recipe 编写流程相关。

与仓库其他模块的协作关系

tool/ 并非孤立存在，它与 chsrc 的构建、分发体系紧密协作：

• 构建链路：当预编译二进制缺失、用户选择自行编译时，Makefile 提供了 build-in-dev-mode（产出 chsrc）、build-in-debug-mode（产出 chsrc-debug）、build-in-release-mode（产出 chsrc-release）、build-in-ci-release-mode（产出 chsrc-ci-release）四种编译模式，installer.sh 与 Termux bootstrap 均会引导到这一链路；
• bootstrap 链路：对于没有预编译二进制的平台（如 BSD、Android 的某些架构），bootstrap/ 下的 bootstrapper 脚本（以 Termux.bash 为范例）负责"先换源、再装依赖、最后编译 chsrc"，installer.sh 在检测到 Android 平台时也会自动切换到这一流程；
• 安装链路：make install 会把二进制、man 手册（doc/chsrc.1）与本文所述的补全脚本统一安装到系统路径，形成"二进制 + 文档 + 补全"的完整交付。

综上，chsrc 的 tool/ 目录用少量、轻依赖的脚本（Bash、PowerShell）覆盖了从"下载安装"到"命令行体验"再到"开发者维护"的完整工具链，与 README、bootstrap、Makefile 等模块共同构成一个可独立交付、也支持任意平台自举编译的分发体系。