为跨平台 CLI 下载器添加工具，并检查每个二进制文件

## 确认工具提供静态二进制文件，并列出目标平台 添加以可直接执行的静态二进制文件形式分发的命令行工具时，请使用此工作流。 应将系统软件包、容器镜像提取、集群插件和由运行时管理的应用程序分别交给各自的安装路径。 修改代码前，请确认提议的工具具有预编译的发布资产。 应拒绝需要解释器、软件包管理器、安装器脚本或未声明运行时依赖项的软件包。 除非项目明确允许更大范围的批量变更，否则请确认此次贡献只改动一个工具。 如果项目设有特定的设计审批或议题审批关卡，必须在实现前取得相应审批。 按照仓库的命名约定创建范围集中的分支。 确定安装器命令、工具的对外名称及其上游所有者和仓库。 列出安装器预期支持的每一种平台组合。 除非项目定义了其他矩阵，否则使用以下基准目标： - Linux（x86-64）。 - Linux（ARM64）。 - macOS（x86-64）。 - macOS（ARM64）。 - Windows（x86-64）。 除非安装器明确包含32位x86或ARMv6，否则不得声称支持它们。 记录不可用的组合，不得悄悄替换为其他平台的制品。 ## 编码前，查清每个系统和架构的发布文件名 编写下载模板前，检查上游最新的稳定版本。 优先向上游最新版本端点发送仅检查重定向的请求，以便通过Location标头获得版本标签。 如果所需结果就是标签本身，则不得跟随重定向。 检查完整展开的资产列表，或针对该确切标签的其他权威发布页面。 如果有同等的公开发布元数据可用，应避免调用受速率限制的API。 列举所有已发布的文件名、归档格式、操作系统和体系结构。 精确保留上游术语，包括amd64与x86_64、arm64与aarch64等区别。 对于每个预期目标，记录： - 是否存在相应资产。 - 资产的确切文件名。 - 归档类型（如果有）。 - 归档内的二进制文件名（如果不同）。 - 会改变兼容性的任何libc或工具链变体。 如果项目支持且选择合适，应优先采用musl等可移植静态变体。 如果包含unknown等词的Rust文件名与上游版本匹配，应将其视为有效。 将收集到的矩阵作为模板、测试和拉取请求证据的事实依据。 ## 把每个平台映射到真实的下载 URL，不用其他文件代替 使用安装器既有的定义结构添加工具，并遵循附近可正常工作的示例。 提供必需的标识字段：工具名称、上游所有者、仓库和简要说明。 如果发布资产本身就是可执行文件，应为这种普通二进制文件使用二进制文件名模板。 如果资产位置需要自定义路径逻辑，请使用完整URL模板。 将每个受支持的操作系统和体系结构映射到实际上游文件名。 将安装器体系结构常量与上游文件名术语分开。 使用与运行时所采用的操作系统表示方式相匹配的显式Windows检测。 受支持的归档形式必须符合安装器的解压能力。 通常接受的形式包括tar.gz、tgz、zip、bz2和tar.xz。 平台组合不可用时，其生成的URL必须明确失败，例如返回未找到响应。 它绝不能回退到Linux资产、其他体系结构或其他工具。 明确说明版本标签转换，尤其是在同时使用带前缀的标签和纯数字版本时。 对操作系统、体系结构、名称、版本、所有者和仓库使用现有模板变量。 如果安装器支持版本替换，不得在生产定义中硬编码当前版本。 依赖测试前，应审查矩阵每一行的最终URL。 ## 分开写归档文件名和其中的可执行文件名 将发布资产名称与归档内部的可执行文件名视为两项独立事实。 如果归档包含带平台后缀的可执行文件，请同时定义： - URL模板，用于指定包含扩展名的可下载归档。 - 二进制模板，用于指定不含归档扩展名的已提取可执行文件。 不得只把带扩展名的归档文件名放入二进制模板。 许多解压器使用二进制模板来定位已提取的文件。 该字段中的归档扩展名可能触发向通用工具名称的回退。 如果归档包含平台专用的二进制文件名，这种回退就会失败。 对于未压缩的普通可执行文件，通常只需要二进制模板。 应检查归档来确认这种区别，不得根据文件名猜测。 检查归档是否在可执行文件外增加了目录前缀。 检查Windows可执行文件是否在映射和提取时都需要exe后缀。 使校验和、签名及可执行权限处理与现有安装器保持一致。 如果提取过程报告文件缺失，请比较以下三个名称： - 下载的资产。 - 提取出的归档成员。 - 安装器请求的名称。 应在定义边界修正映射，而不是添加宽泛的回退。 ## 用固定版本测试每个平台的下载 URL 在现有下载器测试旁添加范围集中的单元测试。 使用固定的上游版本；绝不能以最新版测试URL生成。 为每个已发布且受支持的操作系统和体系结构组合创建测试用例。 断言完整的预期URL，包括所有者、仓库、标签、文件名、分隔符和归档扩展名。 按照上游发布的确切形式包含平台专用体系结构别名。 如果存在特殊的版本转换和Windows后缀，应对其进行测试。 对于不可用的组合，如果框架支持此类情况，应测试安装器预期的失败行为。 使测试不依赖于可变的发布元数据。 使用实现前收集的同一资产矩阵。 先运行范围集中的软件包测试。 然后在适用时运行项目要求的更广泛测试目标。 URL测试通过只能证明字符串构造正确，不能证明下载的文件就是正确的二进制文件。 ## 下载每个平台的二进制文件，检查格式和架构 跨平台验证前先构建安装器。 首先下载当前平台的制品，不使用覆盖标志。 检查生成的文件，以发现HTML错误页面、被误认作可执行文件的压缩数据和空文件。 为该工具运行仓库的平台矩阵验证脚本。 验证每个受支持的组合，而不只是运行测试的机器。 使用文件识别工具或等效的二进制解析器确认格式和体系结构。 常见的预期证据包括： - Linux x86-64：64位ELF可执行文件，面向x86-64。 - Linux ARM64：64位ELF可执行文件，面向AArch64。 - macOS x86-64：64位Mach-O可执行文件，面向x86-64。 - macOS ARM64：64位Mach-O可执行文件，面向ARM64。 - Windows x86-64：PE32+控制台可执行文件，面向x86-64。 HTTP响应成功并不足够，因为模板可能会下载错误平台的文件。 成功解压同样不足够，因为内部可执行文件可能面向错误的体系结构。 捕获完整的矩阵输出，不得通过编辑掩盖失败或警告。 如果上游没有某个目标，请验证安装器会针对该目标失败，而不是提供不兼容的二进制文件。 在文档编写或审批前解决所有不匹配。 ## 重新生成 CLI 目录，并在 PR 中写明检查结果 按照仓库中记录的流程重新生成CLI目录。 从安装器生成目录，不得手工编造一行。 仅在安全替换确有需要时使用临时工作区文件。 精确保留目录的开始标记和结束标记。 只替换这些标记之间生成表格的内容和相关工具数量。 不得移除周围的说明文字或无关条目。 确认新工具只出现一次，并带有预期说明。 更新后删除临时生成文件。 准备一份拉取请求说明，其中陈述： - 可用和不可用的平台组合。 - 所用的权威发布标签和命名模式。 - 完整的平台验证输出，包括二进制格式。 - 适用时所需的端到端测试或更广泛测试输出。 确保每次提交都带有仓库要求的签署信息。 通过注明命令和固定版本，使证据可以复现。 不得在摘要中掩盖缺失的平台、失败的下载或体系结构不匹配。 ## 审查改动，排查下载或解压失败的原因 将资格、映射、测试、文档和证据作为独立关卡审查。 确认工具是静态二进制文件，并且变更仅限于获批范围。 检查必需的标识字段，并确保至少存在一个有效下载映射。 将每个模板分支与权威资产矩阵进行比较。 验证不受支持的组合无法收到其他平台的二进制文件。 确认单元测试使用固定版本并覆盖所有受支持目标。 审批前，应要求为每个声称支持的目标提供二进制格式证据。 确认生成文档包含该工具并保留其边界标记。 通过比较确切的上游文件名和标签转换来调查URL不匹配。 分别跟踪操作系统分支和体系结构分支，以调查错误的体系结构。 通过比较归档名、归档成员和已配置的内部二进制文件名来调查提取失败。 重新检查项目是否确实发布了自包含静态二进制文件，以调查运行时失败。 不得使用不兼容的替代品来规避上游资产缺失。 在拉取请求中记录合理的上游缺口。 只有在代码、测试、下载的制品、文档和报告的证据一致时才能批准。