描述

修复切换分支编译时闭源二进制包（bundle）始终固定拉取 master 分支包的问题。

OAM_BUNDLE_BRANCH 由硬编码 master 改为三级决策：显式指定 > git 探测 > master 兜底，并对结果做白名单硬校验（OBS 上无对应包的分支在配置阶段即报错，而非下载到 403 空包后把失败推迟到 install 阶段）。

取包的三条入口（已就绪的 bundle/ 目录、本地预置 tar、OBS 下载）都要核对分支——只修下载路径不够，因为切分支后最常走的恰恰是前两条。

主要改动

• build.sh 新增 --bundle_branch=<NAME>：解析后存入 BUNDLE_BRANCH，仅在用户显式指定时透传 -DOAM_BUNDLE_BRANCH 给 CMake；不传则由 CMake 配置期自行探测。取值做字符白名单校验（[A-Za-z0-9._/-]），拒绝含空格或 shell 元字符的分支名。BUNDLE_BRANCH 在 checkopts() 解析选项前显式清空，避免环境里的同名变量被当成"用户显式指定"——那样既盖掉自动探测，又绕过上述字符校验（校验只在 --bundle_branch 分支里跑）。

• cmake/install_bundle.cmake 新增 oam_resolve_bundle_branch()：实现三级决策。git 探测按模式枚举远端发布线分支（git for-each-ref refs/remotes + 正则 ^[0-9]+\.[0-9]+\.[0-9]+(-beta\.[0-9]+)?$），去掉 -beta.N 后缀归一化为 OBS 路径名（9.1.0-beta.3 → 9.1.0），取领先提交数最小者（血缘最近）。不硬编码任何具体 ref——同一发布线并存 9.1.0、9.1.0-beta.1/2/3 等多个分支，硬编码任一个都会让其余分支探测不到而静默回退 master。不限定 origin，fork 场景下发布线常只在 upstream。

• 已就绪的 bundle/ 目录也校验分支：bundle/ 非空即跳过下载，是切分支后最常命中的路径；不校验就会静默复用上一条线的闭源包（连显式 --bundle_branch 也无效）。取包成功后在 bundle/.bundle_branch 落分支元数据（解压产物本身不含分支信息），复用前读取比对，不一致则 FATAL_ERROR 并提示 --make_clean 刷新或 --bundle_branch=<现有分支> 沿用现包。本改动之前拉下的 bundle 无元数据，降级为告警而非报错，避免既有工作目录必须先重下闭源包才能构建。

• 离线预置包按分支校验：预置包文件名不含分支信息（各分支同名），命中后直接复用会静默混入其它分支的闭源包。cmake/download_libs.py 下载后在包旁写 <tar>.branch 元数据；install_bundle.cmake 命中预置包时读取并与目标分支比对，不一致则配置阶段 FATAL_ERROR。无元数据的既有包按旧约定放行并告警。

• cmake/download_libs.py 支持 --bundle_branch，且元数据只反映本轮实际结果：分支解析规则与白名单与 install_bundle.cmake 完全一致，使联网机器预置与离线机器联编两端对齐。元数据只写本轮确实下载成功的 tar（原先按"文件是否存在"写，会把目录里残留的旧分支包贴上本轮标签，联编时反而错误校验通过——比没有元数据更糟）；本轮未取到的包会清掉其陈旧元数据，让联编侧如实走"无元数据"告警分支；bundle 一个都没取到时以非零码退出；wget -O 失败时删除残留的半截文件，避免被后续误当作可用预置包。

• 中英文档同步：README.md / docs/zh/quick_install.md 与 README_en.md / docs/en/quick_install.md 四处改动一一对应，均说明按分支拉取规则、--bundle_branch 用法、离线预置须与联编分支一致，闭源包表格表头由「版本」改为「分支」。

• 新增测试 test/ut/asys/testcase/common/test_bundle_branch.py：32 条用例。cmake 部分不做字符串匹配，而是在临时 git 仓／预置的 bundle 目录里真正跑 cmake 求值，覆盖：显式指定优先、9.1.0 线各分支（参数化 4 个）、master 探测、ref 均不存在回退、git 不可用回退、非 origin remote、OBS 无包发布线被忽略、已有 bundle 分支一致则复用 / 不一致则报错 / 无元数据则告警、预置包分支校验、元数据只给本轮下载成功者、两端白名单同步。

变更类型

请选择本次引入的变更类型（勾选对应项）：

• 🐛 Bug 修复
• ✨ 新功能
• 💄 代码风格更新（格式化，局部变量）
• ♻️ 重构（既不修复错误也不增加功能的代码变动）
• 📦 构建过程或辅助工具的变动
• 📝 文档内容更新

关联的Issue

关联 Issue #169

如何测试

# 1) 自动探测（不传参数）：从 9.1.0 线分支编译应拉 9.1.0 包，从 master 拉 master 包
bash build.sh

# 2) 显式指定
bash build.sh --bundle_branch=9.1.0

# 3) 非法分支应在配置阶段报错并提示可用取值
bash build.sh --bundle_branch=nonexistent

# 4) 非法字符应被入口校验拒绝
bash build.sh --bundle_branch='bad name'

# 5) 切分支场景：master 构建后切到 9.1.0 直接构建，应报错提示 --make_clean 而非静默复用
bash build.sh                        # 在 master 上
git checkout 9.1.0-beta.3
bash build.sh                        # 应因 bundle/ 分支不符而报错

# 6) 离线预置两端一致
python cmake/download_libs.py --bundle_branch=9.1.0
bash build.sh --cann_3rd_lib_path=<预置目录> --bundle_branch=9.1.0

# 7) 单元测试
python3 -m pytest test/ut/asys/testcase/common/test_bundle_branch.py -v

本地验证：

• 新增用例 32 passed。其中本轮新增的 7 条已逐条确认修复前失败、修复后通过（把 pre-fix 的三个文件单独取出跑同一份测试：7 failed）。
• test/ut/asys/ 全量 536 passed。
• test/ut/asys/ + test/ut/msaicerr/ 合计 1155 passed / 15 skipped，唯一失败 test_compile_op_ascend950.py::test_get_ub_size_not_tbe 为存量失败——把本 PR 全部改动 stash 后该用例同样失败，与本改动无关。
• cmake/download_libs.py 与新增测试跑过增量 codecheck 规则（E501/T201/S607/PLR0915/PLR6301/PLR1722），无告警。
• msprof gtest 需编译，本地未覆盖，依赖云端 UT_Test。

核对清单

• 我的代码遵循了项目的代码风格
• 我已对代码进行了自测
• 我已更新了相关的文档
• 我在标题中使用了合适的类型标签（如：feat:, fix:）
• 我已经详细阅读了贡献指南（CONTRIBUTING.md）

其他信息

历轮评审共修复了六个实际缺陷：

1. -DOAM_BUNDLE_BRANCH=\"${BUNDLE_BRANCH}\" 的转义引号在 cmake ${cmake_args} .. 非引号展开时作为字面量传入 CMake，白名单比对必然失配，--bundle_branch 功能不可用（jinyingqi 指出，已实测复现）。
2. 硬编码 origin/9.1.0-beta.2 漏掉同一发布线的其它分支，从 9.1.0/beta.1/beta.3 编译都会静默回退 master（newstarzj 指出方向）。
3. cmake 中 --format=%(refname:short) 未加引号时括号被当作参数分隔符，git 只输出 %，探测全部失效（新增测试时发现）。
4. bundle/ 非空即 return，完全跳过分支解析与校验——切分支后最常走这条路径，旧闭源包被静默复用，PR 修复目标在主场景下失效（jinyingqi 指出）。
5. BUNDLE_BRANCH 未在 checkopts() 初始化，环境变量可绕过字符校验并覆盖自动探测（jinyingqi 指出）。
6. 离线预置元数据按"文件是否存在"写入，会把目录里残留的旧分支包标记为本轮分支，使联编侧错误校验通过（jinyingqi 指出）。