AGIROS 工具菜单是一个用于辅助 AGIROS 系统开发和打包构建的交互式命令行工具。用户通过文本菜单执行一系列与代码发布和软件包构建相关的操作，例如下载发布仓库、处理 tracks 文件、生成打包配置以及批量构建软件包等。该工具以 Python 编写，依赖 Rich 库提供美观的终端界面，并可选使用 Questionary 库提升交互体验。在使用前，请确保已经安装以下依赖：
· Python 3 运行环境；
· Rich（必须）：用于彩色输出、表格和面板显示；
· Questionary（可选）：用于菜单选择和输入的交互控件，如未安装则工具将自动使用文字方式提示输入；
· AGIROS Bloom 工具：提供 bloom-generate 等命令用于生成打包文件；
· Git-Buildpackage (gbp)：用于生成 Debian 软件包；
· RPM 构建工具：如 rpmbuild，用于生成 RPM 软件包。
在终端中运行 python3 agiros_tools_menu.py 即可启动 AGIROS 工具菜单。启动后，终端将显示一个菜单界面，并通过交互式提示让用户选择操作。若系统未安装 Questionary，菜单将以编号列表方式呈现，用户需根据提示输入相应编号或内容来选择。
**注意：首次运行前可通过设置相应环境变量来定制默认参数（详见下文“全局参数及其修改方式”部分）。工具启动时会读取这些环境变量，并在程序运行过程中同步更新环境变量保持配置一致。
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activatepip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt顺序很重要，先安装依赖模块（如 bloom），再安装主模块（agiros-tools）：
pip install bloom-0.13.0-py3-none-any.whl
pip install agiros_tools-0.1.0-py3-none-any.whlpip install bloom-0.13.0.tar.gz
pip install agiros_tools-0.1.0.tar.gzcp .env
# 或手动创建并配置内容激活环境变量（Linux）：
export $(grep -v '^#' .env | xargs)或直接通过 python-dotenv 自动加载，无需手动 export。
直接运行主程序：
python3 agiros_tools_menu.pypip list | grep agiros
# 应该看到 agiros-tools 和 bloom 都已安装启动后，主菜单提供以下选项：
1. 下载 release 仓库 – 下载发布仓库代码
2. 处理 tracks.yaml / 下载源码 – 处理 tracks 文件并下载源码
3. Bloom 打包 – 生成打包所需配置
4. 构建 (Build) – 管理构建任务队列并执行构建
5. 清理生成目录 – 清理生成的打包产物目录
6. 配置与状态 – 查看和修改全局配置
7. 查看日志 – 查看操作日志文件
8. 退出 – 退出工具
以下小节将详细介绍每个功能的用途、操作流程，以及相关的默认参数设置和注意事项。
**功能用途：从指定的 distribution.yaml 描述文件下载 release 仓库。该选项可自动读取 distribution.yaml 中定义的仓库列表并将其全部克隆/更新到本地。
调用方式：选择“下载 release 仓库”后，程序会提示输入 distribution.yaml URL 和 Release 仓库存放目录。默认情况下，URL 会预填为 state.distribution_url 的值，即默认的发布索引文件地址。在最新版本中，该默认地址为 http://1.94.193.239/yumrepo/agiros/agirosdep/loong/distribution.yaml（可通过环境变量 **AGIROS_RELEASE_DIR** 指定本地Release目录，**AGIROS_RELEASE_TARGET_DIR** 指定目标目录等，详见后述。Release 仓库存放目录默认为当前路径下的 “ros2_release_dir” 文件夹（可通过环境变量 AGIROS_RELEASE_DIR 修改）。用户可直接按默认值回车，或输入自定义的 URL 和目录路径。程序对输入进行如下处理：
· 若未输入 URL 或目录，工具将取消操作并以黄色警告提示缺少必要信息。
· 对于提供的目录路径，工具会自动创建不存在的目录。
· 工具将显示一个面板提示开始下载。随后调用内部模块 yaml_git_downloader_release.py，根据提供的 distribution.yaml URL 下载其中列出的所有仓库源码。下载日志将保存于目标目录下的 download_log.txt 文件。
默认参数：
- distribution.yaml 默认URL：http://1.94.193.239/yumrepo/agiros/agirosdep/loong/distribution.yaml（环境变量 **AGIROS_DISTRO**/**AGIROS_DISTRO** 也影响ROS发行版，详见配置部分）。
- Release 仓库默认目录：当前工作目录下的 “ros2_release_dir” 文件夹（可由环境变量 AGIROS_RELEASE_DIR 预先设定）。
参数修改渠道：上述参数可在启动工具前通过设置环境变量进行修改，或在运行过程中通过“配置与状态”菜单调整（参见配置部分）。例如，通过环境变量可以指定自定义 Release 路径：export AGIROS_RELEASE_DIR=/your/path。运行过程中，也可在“配置与状态”中选择“修改 Release 目录”来更新该路径。Distribution.yaml 的URL则可通过环境变量 AGIROS_DISTRIBUTION_URL 或AGIROS_DISTRO** (或通过配置菜单中“修改 distribution.yaml URL”) 来修改。
注意事项：
- 下载过程中请确保网络畅通且提供的 URL 有效；失败时工具会提示错误原因。
- 下载所得仓库将存放于指定的 Release 目录下，各仓库以文件夹区分。download_log.txt 记录了下载日志，可通过“查看日志”功能查看。
功能用途：根据 Release 仓库中的 tracks.yaml 文件下载对应的软件包源码。Tracks 文件通常定义了某发行版本下各软件包的来源（通常为特定版本的源码仓库）。本功能自动解析 tracks.yaml 并将所需源码仓库克隆到指定源码目录。
**调用方式：选择该功能后，系统依次提示输入以下信息：
· Release 仓库目录：tracks.yaml 所在的 Release 仓库路径，默认使用当前配置的 state.release_dir。该默认值继承自上一步或环境变量 AGIROS_RELEASE_DIR。
· 源码目录：下载源码的目标路径，默认值为当前配置的 state.code_dir。初始默认为 “ros2_code_dir” 文件夹（可通过环境变量 AGIROS_CODE_DIR 修改）。
· Tracks 发行版名称：要处理的 tracks.yaml 发布名称，一般对应 distribution 名称（如 “jazzy” 等）；默认值取自 state.ros2_distro（可通过环境变量 ROS2_DISTRO 预设）。
· 启用断点续传 (resume)?：布尔选项，默认 是（Y）。开启时，若下载中断可在后续运行中续传未完成部分（实现上将传递 --resume 标志给下载脚本）。
· **限制下载包数量：可选填写一个整数，以限制下载的软件包数量（用于调试或部分下载）。留空则表示下载全部包。
工具根据上述输入组装命令参数并调用内部脚本 oob_tracks_to_sources.py 来执行具体下载。执行前，界面会显示一个提示面板标明开始处理 tracks.yaml 并下载源码。关键参数传递如下：
· --release-dir=<Release仓库路径>
· --code-dir=<源码存放路径>
· --distro=<tracks发行版名称>
· 断点续传对应 --resume（仅当用户确认启用时添加）
· 包数量限制对应 --limit N（仅当用户输入数字时添加）
下载过程中的输出会实时打印到终端，完成后根据脚本返回码判断成功与否：若 exit_code != 0，工具将以红色字体提示处理失败及退出码。成功完成时，会更新内部态 state.release_dir 和 state.code_dir 为用户提供的新路径，并保存 tracks 发行版名称以供后续步骤使用。这些更新的参数也会通过 state.update_env() 写入环境变量，以便后续步骤或外部脚本获取。
默认参数：
- Release 仓库目录默认同上步下载路径（或环境变量 AGIROS_RELEASE_DIR），初始默认 “ros2_release_dir”。
- 源码目录默认 “ros2_code_dir”（环境变量 AGIROS_CODE_DIR 可覆盖）。
- Tracks 发行版默认 “jazzy”（环境变量 ROS2_DISTRO 可覆盖）。
**参数修改渠道：这些参数可通过环境变量在启动前设定，也可在运行过程中通过“配置与状态”菜单修改：例如选择“修改 源码目录”或“修改 ROS/Tracks 配置”来更新源码路径、ROS发行版和tracks名称等。
使用注意：
- 确保在运行此步骤前已正确执行“下载 release 仓库”，因为 tracks.yaml 文件通常位于 Release 仓库中。
- resume 功能对于大批量包下载很有用，失败后重新运行时建议保持启用以避免重复下载已完成部分。
- limit 参数适用于只想下载部分软件包的情况（通常调试用）。若提供非数字输入，工具会忽略该参数并给出提醒。
- 下载完成后，可在源码目录下看到各软件包源码仓库。Release 和源码目录会在屏幕底部状态面板中显示，以供随时参考。
**功能用途：**利用 ROS Bloom 工具为源码仓库生成打包所需的配置文件，包括 Debian 软件包的 debian/ 目录、RPM 软件包的 .spec 文件，以及批量生成 gbp.conf 等操作。Bloom 是 ROS 社区用于将源码转换为发行版包的工具。本菜单将 Bloom 的调用封装为单包或批量的操作，以便用户半自动地生成打包配置，并可选择将生成的包加入构建队列。
调用方式：选择“Bloom 打包”后，会首先要求选择操作类型：
· 生成 Debian 目录：**使用 Bloom 为指定软件包生成 debian/ 打包目录（Debian/Ubuntu 系发行版所需）
· 生成 spec 文件：**为指定软件包生成 RPM .spec 配置文件（openEuler/CentOS 等RPM系发行版所需）
· 生成 **debian+spec：同时生成 Debian 打包目录和 RPM spec 文件
· 生成 **gbp.conf：为批量构建生成 gbp.conf 配置文件（git-buildpackage 的批量配置）
· **返回：取消并回到主菜单
接下来，系统提示选择操作范围：
· **单包：对单个软件包执行上述所选操作
· **批量：对源码目录下所有符合条件的软件包批量执行上述操作
· **返回：取消操作范围选择
根据用户在这两个步骤的选择，后续流程有所不同：
在单包模式下，工具会提示用户选择或输入一个具体的软件包路径。用户可通过关键字查询或手动输入来定位源码包目录，或者直接从已识别的包列表中选择。AGIROS 工具提供了友好的包选择界面：当源码目录下包较多时，可输入关键字筛选。选定包目录后，按照之前的操作类型执行对应的 Bloom 操作：
· 生成 Debian 目录：**调用 Bloom 生成 debian/ 目录。在实现上，工具内部执行了 bloom-generate agirosdebian 命令（或使用用户自定义的 Bloom 命令和参数，见下文全局参数），并附加 --ros-distro <ROS发行版>、--os-name ubuntu、--os-version <Ubuntu版本> 等参数来指定生成目标为Ubuntu系。如果全局配置启用了 自动生成 gbp.conf 或用户在提示中确认要生成 gbp.conf，则还会附加 --generate-gbp 以及相应的 tracks 配置参数。生成完成后，若用户确认，将该包的 Debian 构建任务加入构建队列。
· 生成 spec 文件：**调用 Bloom 生成 RPM .spec 文件，方式类似但目标为 openEuler 系：执行诸如 bloom-generate agirosrpm 命令并附带 --ros-distro <ROS发行版>、--os-name openeuler、--os-version <默认openEuler版本> 参数。可选地附加 --generate-gbp（一般RPM模式不默认生成gbp.conf，除非全局开启）。完成后可将 RPM 构建任务加入队列。
· 生成 debian+spec：顺序执行生成 Debian目录和生成spec 文件两步，生成完成后分别询问是否将 Debian 任务和 RPM 任务加入构建队列。这一步相当于为同一包同时准备Debian与RPM的构建。
· 生成 gbp.conf：针对单个包生成 gbp.conf 文件。实现上相当于调用 Bloom 的 gbp.conf 生成模式。完成后可选择将对应Debian构建任务加入队列（RPM无需，因为gbp.conf主要用于Debian打包）。
批量模式： 批量模式下，不要求选择具体某个包，而是对源码目录下的所有软件包执行操作。工具将自动调用脚本 oob_builder_procedural.py 完成批量处理。执行前，会提示两个附加选项：
· 限制处理包数量： 可输入要处理的最大包数，留空则表示处理全部。这相当于给脚本传入 --limit N 参数。非数字输入将被忽略并警告。
· 启用 dry-run?： 询问是否以 dry-run 模式运行，默认否。dry-run模式下Bloom不会真正输出文件，仅模拟过程，用于验证流程。若选择是，则传入 --dry-run 参数给脚本。
随后工具根据最初选择的操作类型确定模式参数："生成 Debian 目录"对应 --mode debian，"生成 spec 文件"对应 --mode spec，"生成 debian+spec" 为 --mode both，"生成 gbp.conf" 则为 --mode gbp。同时，会根据全局配置附加以下参数传递给脚本：
· --release-dir <Release仓库目录>，--code-dir <源码目录>：来源于当前 state.release_dir 和 state.code_dir。
· --ros-distro <ROS发行版>：当前配置的 ROS 发行版。
· --ubuntu-default <Ubuntu版本>：Ubuntu 默认版本号。
· --openeuler-default <openEuler版本>：openEuler 默认版本号。
· --openeuler-fallback <版本列表>：openEuler 备用版本列表（若配置中有设置）。
· --bloom-bin <Bloom命令>：Bloom 可执行命令路径或名称，默认是 bloom-generate。
· （可选）--generate-gbp：如果全局 自动生成 gbp.conf 已开启，且模式不为单纯 "gbp.conf" 时，添加此参数使得在批量生成 Debian/RPM 时同时批量生成各包的 gbp.conf。
工具构建好上述命令后，将其传入 run_stream 执行。该脚本会对源码目录遍历处理：对于每个包，根据 --mode 要求生成对应的打包文件或配置。执行过程中输出会在终端打印，完成后可根据需要查看生成的结果（debian/目录、.spec 文件或 gbp.conf）。注：批量模式不会自动将包加入构建队列，因为其目的是生成配置文件。用户应在批量生成后使用构建*菜单的扫描功能将这些生成的包加入队列（见下节）。
默认参数：
- Bloom 命令默认使用 bloom-generate，可通过环境变量 AGIROS_BLOOM_BIN 指定其他可执行路径。
- Ubuntu 默认版本为 “jammy”，通过 AGIROS_UBUNTU_DEFAULT 修改。openEuler 默认版本 “24”，通过 AGIROS_OE_DEFAULT 修改，回退版本列表默认 “22,23”通过 AGIROS_OE_FALLBACK 修改（这些版本用于 Bloom 决定RPM打包基于哪个openEuler版本）。ROS 发行版默认 “loong”，通过 AGIROS_DISTRO 修改。Tracks 发行版同上默认 “jazzy”。
- 自动生成 gbp.conf 默认关闭（0），可通过环境变量 AGIROS_GENERATE_GBP=1 打开，或在菜单“编辑构建参数”中切换（后述）。
参数修改渠道： Bloom 相关参数可通过配置菜单“修改 ROS/Tracks 配置”、“修改 openEuler 参数”、“修改 Bloom 命令”等入口修改。例如在“配置与状态”中选择“修改 Bloom 命令”可更换 bloom 可执行程序名称或路径。Ubuntu/openEuler 版本等可通过环境或配置界面更新。自动生成 gbp.conf 切换可在“构建”子菜单的“编辑构建参数”里启用/禁用。
注意事项：
- 生成位置：Debian 打包目录会直接生成在相应源码包目录下的 debian/ 文件夹；RPM .spec 文件则生成在源码包目录下的 rpm/ 文件夹中。如果需要重新生成，建议在执行前使用“清理生成目录”功能清除旧的debian/和rpm/目录以避免冲突。
- 自动加入队列：在单包模式下，每次 Bloom 操作完成后系统会询问是否将相应构建任务加入队列，如不确定稍后构建顺序或想手动调整，可选择否，之后仍可通过构建菜单手动添加。
- 批量模式不会直接构建软件包，仅生成配置文件。批量完成后请留意终端输出，确保没有错误（如有错误，会在终端或fail.log中记录）。必要时，可用“查看日志”来查看 fail.log 或其他日志文件以了解详情。
- 批量模式在处理大量包时耗时可能较长，请耐心等待。期间如需要中止，可按 Ctrl+C 终止，但需注意部分包可能已生成部分文件。再次运行前建议执行“清理生成目录”。
功能用途： 管理和执行软件包的实际构建过程，包括将生成的打包配置构建出软件包文件（Debian .deb 或 RPM .rpm），以及维护一个构建任务队列。用户可以添加构建任务、批量执行构建、查看/修改构建参数等。本功能通过维护一个队列文件来记录待构建的软件包列表及其完成状态，实现了断点续建和状态跟踪。
选择“构建 (Build)”进入构建子菜单，提供如下选项：
· 查看队列： 查看当前构建任务队列内容
· 添加任务： 将新的软件包构建任务加入队列
· 执行队列： 按队列顺序依次构建所有任务
· 清空队列： 移除所有队列任务并重置队列文件
· 编辑构建参数： 调整构建相关的全局参数设置
· 返回： 返回上一级菜单
下面分别介绍各选项的具体功能和使用。
“查看队列”用于显示当前构建队列中的软件包列表及其状态。AGIROS 工具通过一个文本文件 (build_queue.txt) 持久化存储队列，每一行对应一个软件包名称，结尾带 “#” 符号表示该包已完成构建。在选择“查看队列”时，程序会首先从队列文件加载最新的队列内容，同步到内存中。如果当前队列为空（没有待构建包），将提示“队列为空”，并询问用户是否进行 **扫描并生成构建列表。选择“是”将调用扫描功能（等价于“添加任务”中的扫描，详见后述）自动检测源码目录下可构建的软件包并生成队列。
当队列不为空时，工具将逐行列出队列中的包名及状态。例如输出格式如：“1. package_name # (debian, rpm)”：序号1，包名，若已完成则带“#”标记，括号内列出该包在队列中包含的构建类型列表（debian和/或rpm）。类型信息来自内部为每个包记录的任务类型集合。例如，如果此前添加了某包的Debian和RPM构建任务，则括号中会显示“debian, rpm”；若仅有一种则只显示对应名称。状态标记“#”则表示该包的所有构建任务均已成功完成。
移除任务： 在查看列表后，如果队列非空，系统会询问是否要移除某个包。确认需要移除时，可输入要删除的序号编号，工具将从队列中删除对应的软件包及其所有构建任务，并更新队列文件。成功移除后，会以黄色文字提示哪个包已被移除。移除操作不会删除源码，仅影响构建列表。
“添加任务”用于向构建队列新增待构建的软件包。进入此菜单后，首先让用户选择添加方式：
· 手动选择源码包： 用户自行选择源码目录中的具体包；
· 扫描并生成构建列表： 自动扫描源码目录，一键将所有发现的可构建包批量加入队列；
· 返回： 取消添加任务。
如果选择“扫描并生成构建列表”，工具会执行自动扫描（具体见下文“扫描功能”），然后返回构建菜单，不再额外添加单个包。扫描完成后可以通过“查看队列”看到新增结果。下面重点介绍手动选择源码包和扫描功能：
手动添加单个包： 工具将调用与前述 Bloom 菜单相同的包选择界面 (prompt_package_path) 让用户定位一个源码包路径。选定包后，会提示选择构建类型，提供 “debian” 或 “rpm” 两种选项。用户选定后，系统会创建一个新的构建任务（BuildTask 对象）并加入队列。在代码实现上，每个 BuildTask 保存了 display_name（包名）、path（包路径）和 kind（构建类型：debian或rpm）。加入队列时，程序会将任务写入全局队列结构并保存到队列文件。默认情况下，新添加的任务包状态被标记为“未完成”（即未加“#”）。之后用户可继续添加其他任务或返回。
扫描功能（生成构建列表）： 无论从“查看队列”确认扫描，还是从“添加任务”选择扫描，均调用同一函数 handle_scan_and_generate 以自动发现源码目录下的包并加入队列。其工作流程如下：
1. 同步配置并加载队列： 扫描开始前，工具先刷新当前配置和环境变量确保使用最新路径，然后加载现有队列内容以避免重复添加已存在项。
2. 检测系统环境： 自动检测当前运行环境是 Ubuntu 还是 openEuler，以决定默认扫描目标。如果检测到 Ubuntu，提示用户选择目标环境是Ubuntu（Debian构建）还是切换为openEuler（RPM构建）；反之亦然。用户也可以在未检测出已知系统时手动选择目标。这一步确保扫描过程有明确的目标类型，因为不同发行版对应不同打包方式。
3. 扫描源码目录： 工具遍历源码根目录下的各软件包文件夹，搜索其中是否存在打包配置：
4. 若目标为 Ubuntu/Debian，则查找包目录下是否有 debian/ 子目录。有则认为该包可进行Debian构建。
5. 若目标为 openEuler/RPM，则查找包目录下是否有 rpm/ 子目录，且其中包含 .spec 文件。符合则认为该包可进行RPM构建。
扫描时采用一定的深度限制逻辑，仅识别源码根目录下首两级内含 package.xml 的文件夹作为有效包。如果未发现任何符合条件的包，则提示用户未找到已生成构建目录的包。
6. 生成任务列表并入队： 对每个匹配的包创建构建任务：目标为Ubuntu则任务类型为 “debian”，目标为openEuler则类型为 “rpm”。调用 state.add_tasks 批量将这些任务加入队列。该函数会避免重复添加已在队列中的包/类型组合，新检测到的包将计入 added 计数，已有的计入 existing。函数返回新增任务数与总识别任务数。
7. 报告扫描结果： 扫描完成后，工具显示总结信息，包括：共识别多少个包（总计），其中新增多少个包加入队列，多少个包已在队列中而被跳过（保持原状态）。例如：“扫描完成：共识别 10 个Ubuntu 构建包。新增 3 个包至构建列表。7 个包已存在于构建列表，保持原有状态。”。同时还会提示构建列表文件路径，便于用户了解队列保存位置。
“执行队列”用于实际构建队列中的软件包。选择该项后，系统会首先检查当前队列是否为空；若为空则直接提示无任务。如所有列出的包均已标记完成（即每个包名后都有“#”），也会提示队列中无待构建项，并建议如需重新构建可先移除或重新添加。确认有待构建任务后，程序将按照队列顺序逐个包地执行构建，每个包可能包含一个或多个构建任务（Debian和/或RPM）。构建过程及逻辑如下：
· 按包顺序迭代： 对于队列中的每个包（按加入顺序），如果该包已标记完成，将跳过构建并在终端输出提示（如 “package_name 已标记完成，跳过”）。这允许在中断后继续未完成的部分，无需重复已成功构建的包。
· 执行包内任务： 对于每个尚未完成的包，取出队列中属于此包的所有构建任务列表。任务是按类型区分的，例如一个包可能有两个任务（debian和rpm）。程序将按照添加时的顺序对这些任务逐一执行。执行前会在终端以面板形式打印正在构建的任务信息，包括包名和类型。
· Debian 构建任务： 调用内部函数 run_debian_build 进行构建。默认情况下，该函数直接使用 git-buildpackage (gbp) 工具执行构建：命令类似 gbp buildpackage <附加参数>，附加参数默认为全局配置的 Debian 构建参数列表（初始缺省为--git-ignore-branch --git-ignore-new -us -uc, 可在“编辑构建参数”中修改）。如有额外的构建参数（在任务对象中存储），也会一并加入命令。gbp 会利用源码包中的 debian/ 目录打包出 .deb 文件。
然而，由于本人为gbp流程自动化编写了 git_build_any.sh 脚本，则优先使用该脚本进行构建。这脚本可以包含自定义的构建流程（例如搭建特定环境后调用gbp等）。当检测到脚本存在时，程序会设置一些环境变量用于脚本使用，包括工作目录、源码目录、输出目录、发行版代号、并行线程数、Git用户名/邮箱等。然后在一个循环中执行脚本：
o 如果脚本返回码为0（成功），则跳出循环表示构建完成成功；
o 如果失败，工具将交互询问用户下一步操作：提供 “输入命令后重试” 和 “退出构建” 两个选项。用户可以选择退出以跳过该包构建，也可以输入一条自定义命令，工具会在包目录下执行该命令（使用 bash -lc 执行，允许shell命令）。执行完用户命令后，会再次尝试运行构建脚本，从而给予用户修复环境或问题的机会，然后重试构建。这个循环直到构建成功或用户选择退出。
如脚本不存在，则如前述使用 gbp 直接构建一次，无人工干预机制——失败则任务标记失败。
· RPM 构建任务： 通过 run_rpm_build 执行。默认采用 Linux rpm 工具链：由于本人编写了 rpmbuild_any.sh 脚本，则优先用该脚本类似地执行（设置环境变量 WORK_DIR/CODE_DIR 等用于脚本）。失败时提供同样交互让用户执行命令重试或跳过。若无脚本，则采用系统 rpmbuild 工具：函数检查包目录下 rpm/ 文件夹，搜集所有 .spec 文件。若找不到 spec则报黄字警告无法构建RPM。如有spec，则对每个spec执行命令：<RPM构建命令> <RPM参数> <spec文件>。默认RPM构建命令是 rpmbuild，参数默认为 -ba（编译二进制和源码包）；这些可在配置中修改（见后述编辑构建参数）。多个 spec 将依次构建，每个返回码检查，如有失败会中止余下spec的构建。
每个任务执行后，函数会返回 True/False 表示该任务成功与否。工具据此判定当前包是否全部成功：如果任一任务失败，则将该包标记为失败状态，不再继续构建其后续任务；若该包所有任务均成功，则标记包为完成。失败处理： 当某包失败时，系统会询问用户是否继续执行剩余队列中的包。选择否将中止整个构建流程（可以稍后重新尝试失败的包）；选择是则跳过失败包继续构建队列中后续包。所有包处理完毕后，工具会更新队列文件以保存最新的完成状态，并给出汇总：列出失败的包名清单，以及如果全部成功构建则输出祝贺消息。
执行完“执行队列”后，用户可以通过“查看队列”再次查看各包状态，“#”标记的包即已成功完成。注意：已完成的包若需要重新构建，可先在“查看队列”中将其移除然后重新添加，因为工具跳过已标记完成的包。
选择“清空队列”将删除队列中的所有条目并重置状态。实现上，它会清空队列文件和元数据文件的内容。执行后，内存中的 state.queue_packages、state.package_status 和 state.build_queue 也被清空。终端会以黄色提示 “构建队列已清空” 。此操作不可逆，清空后需重新添加任务。一般在希望重新开始整个构建列表时使用，操作时需要谨慎。
“编辑构建参数”允许用户在运行过程中调整与构建相关的一些全局参数配置，从而影响构建行为。进入该菜单后，有以下子选项：
· Debian 构建参数： 设置 gbp buildpackage 的附加参数。初始默认参数为 --git-ignore-branch --git-ignore-new -us -uc（忽略 git 分支和未提交更改，不签名源码包和更改日志）。选择该项后，当前参数将以字符串形式显示，用户可以直接编辑修改。留空则表示不设置额外参数。更新后，内部将把字符串按空白拆分保存到 state.debian_build_args 列表。后续 Debian 构建将使用新的参数。
· RPM 构建命令： 设置 RPM 构建所使用的命令和参数。进入该项后，首先提示输入 rpmbuild 命令（可包括路径）；默认为当前 state.rpm_build_base（默认值 "rpmbuild"）。可将其修改为特定环境下的自定义脚本或其他构建工具名称。随后提示输入 rpmbuild 参数列表，默认显示当前 state.rpm_build_args 拼接的字符串（默认 -ba）。用户可修改为需要的选项，例如 -bb 仅构建二进制包等。确认后，程序更新内部配置 rpm_build_base 和 rpm_build_args。这些更改会影响后续 RPM 构建步骤。
· 切换自动生成 gbp.conf： 此选项用于开启或关闭 批量 Bloom 操作时自动为每个包生成 gbp.conf 的功能。根据当前状态，选择后会将 state.auto_generate_gbp 布尔值取反。开启时，批量 Bloom（“生成 Debian 目录”或“双生成”）将附加 --generate-gbp 参数，单包 Bloom 生成 Debian 也会询问生成 gbp.conf。切换后终端会提示当前状态已启用或关闭。
每当用户修改任一构建参数并退出子菜单，工具都会调用 state.update_env() 将最新配置写入环境变量。例如 Debian 参数更新会影响环境变量 DEFAULT_REL_INC、PARALLEL 等（如果涉及），RPM命令更新会影响 AGIROS_RPMBUILD_BIN 等。因此在外部调用构建脚本时也可获取这些更新值。
· Debian 构建参数 (gbp)：默认 --git-ignore-branch --git-ignore-new -us -uc。无直接环境变量，但可在界面修改。
· RPM 构建命令：默认命令 rpmbuild，默认参数 -ba。环境变量 AGIROS_RPMBUILD_BIN 可指定命令名称/路径，RPMBUILD 参数无直接环境变量（通过界面配置）。
· 自动生成 gbp.conf：默认关闭（false，对应环境变量 AGIROS_GENERATE_GBP=0），可切换启用。
使用注意： 调整构建参数后建议对新的参数进行一次测试，比如修改 rpmbuild 参数后，可以对单个RPM包执行构建以确保参数正确有效。大部分参数修改立即生效，且会在配置与状态的状态面板中反映出来，以便核对。
功能用途： 清除源码目录下已生成的打包配置目录，以便重新生成或避免旧配置干扰。具体而言，会删除源码目录下所有名为 “debian” 或 “rpm” 的子目录。这在多次运行 Bloom 打包或切换发行版时非常有用，保证每次生成干净的构建配置。
调用方式： 选择“清理生成目录”后，工具将尝试执行仓库根目录下的脚本 clean_generated.sh。如果该脚本不存在，则提示错误“未找到 clean_generated.sh”。默认情况下 AGIROS_TOOLS 仓库自带此脚本。在执行前，程序会设置环境变量 CODE_DIR 为当前配置的源码目录路径（默认如 /opt/code_dir 或用户指定目录），并调用 bash clean_generated.sh。
注意事项：
- 清理操作不可恢复，会永久删除debian和rpm目录，请确认源码中无其他重要内容放在同名目录下（一般没有，因为debian和rpm目录特指打包配置）。
- 此操作不会删除已构建生成的包文件（如 .deb 或 .rpm），因为这些通常存放在输出目录如 deb_out，而非源码目录内部。若需清理输出包，请手动删除输出目录内容。
- 建议在重新运行 Bloom 打包前执行清理，确保旧的打包配置不影响新的生成结果。清理完成后，下次运行 oob_builder_procedural.py 或 Bloom 将重新生成debian/rpm目录。
功能用途： 展示当前工具的全局配置参数，并提供界面修改这些参数的入口。进入“配置与状态”菜单后，首先会再次打印当前配置的状态面板。面板内容包括Release仓库目录、源码目录、distribution.yaml URL、Tracks发行版、ROS发行版、Ubuntu版本、openEuler默认及回退版本、bloom命令、批量生成gbp.conf开关、Debian参数、RPM命令、Debian输出目录、Debian发行版代号、release_inc、并行线程数、Git用户名邮箱、队列文件路径、队列元数据路径、当前队列包数量等。这些信息方便用户总览系统状态。
随后可选择以下配置项进行修改：
· 修改 Release 目录： 更改 Release 仓库路径。输入新的路径后，state.release_dir 将更新为该目录（会自动expand用户符号并resolve绝对路径)。如为空则保持原值。修改后应确保该目录存在有效的Release仓库内容（可通过重新下载Release仓库获得）。
· 修改 源码目录： 更改源码存放路径。后续的tracks下载、扫描构建等都将使用新目录。更改后如果目录不存在，建议手动创建或通过前述下载源码步骤获取内容。
· 修改 distribution.yaml ** URL：**更新发布仓库索引文件URL。输入新URL后将影响“下载 release 仓库”功能使用该地址。可用于切换不同版本的distribution.yaml源。
· 修改 ROS/Tracks 配置： 批量修改ROS发行版、Tracks发行版和Ubuntu版本。选择该项后依次提示：新的 ROS 发行版名称（如 foxy 或内部代号，如当前默认 “loong”）、新的 Tracks 发行版名称（如 “jazzy” 等）、新的 Ubuntu 版本（如 “jammy” 等）。用户可选择其中某一项留空表示不变。更改这些参数会影响 Bloom 打包时的参数（ROS发行版决定bloom生成内容，Ubuntu版本影响bloom和Open Build Farm行为）以及 tracks 下载时所选发行版。
· 修改 openEuler 参数： 设置 openEuler 相关版本信息。首先提示输入新的 openEuler 默认版本号（默认 “24”），然后提示输入新的 openEuler 回退版本列表（以逗号分隔，默认 “22,23”）。留空表示使用原值，输入将按逗号拆分存储为列表。这些参数供 Bloom 打包生成 RPM 时使用：默认版本用于 Bloom 的 --os-version 参数，回退列表可能用于 Bloom 的 --openeuler-fallback 参数（当打包需要尝试兼容多个openEuler版本时）。
· 修改 Bloom 命令： 更改 Bloom 工具可执行命令名称或路径。默认是 “bloom-generate”，用户可将其改为自定义脚本或不同版本的 Bloom 程序路径。修改后，将直接影响 Bloom 打包过程中使用的命令。
· 修改 构建队列文件路径： 自定义构建队列文件及元数据文件的存储位置。默认为工具所在目录下的 build_queue.txt 和 build_queue.txt.meta.json（或由环境变量 AGIROS_QUEUE_FILE 和 AGIROS_QUEUE_META 指定）。修改时，提示输入新的队列文件路径和元数据文件路径。队列文件用于存储队列包名清单，元数据文件存储每个包的路径和构建类型等详情。如果元数据路径留空，工具会使用队列文件名加“.meta.json”作为默认。更改路径后，程序会调用 state.ensure_queue_file() 创建新文件（若不存在），并载入其中内容。这对于在不同项目或多人协作时分开队列管理很有用。
· 修改 Debian 构建配置： 这一项汇总修改与Debian打包相关的一系列设置：
· 源码前缀标签 (code_label)：用于在界面显示中标识源码目录别名，默认 “code_dir”，可以改成如项目代号等，主要用于美观，不影响功能。
· Debian 输出目录 (deb_out_dir)：即 .deb 文件输出路径，默认是用户主目录下的 deb_out/_。可改为自定义路径，Bloom/gbp 将把构建的包输出到此目录。
· Debian DISTRO：Debian构建的发行版代号。默认 “loong”（通过环境变量 DISTRO 设定）。gbp 在生成更改日志或release tag时会用到该名称。
· 默认 release_inc：Debian打包的 release 号增量，默认 “1”（环境变量 DEFAULT_REL_INC）。即DEB包版本中的发行版本号，如无特殊需要通常为1。
· 并行线程数 (PARALLEL)：构建Debian包时使用的并行编译线程数，默认等于 CPU 核心数或4（环境变量 PARALLEL）。可根据机器性能调整。
· Git 提交用户名/邮箱：用于 gbp commit 等场景，默认从环境变量 GIT_USER_NAME 和 GIT_USER_EMAIL 获取（初始默认值为仓库本人信息）。可修改为当前操作者的信息以确保构建产物上的元信息正确。
修改这些值后按提示确认。任一项留空则保持原值。修改将立即应用并更新环境变量（如 GIT_USER_NAME 等）供后续构建脚本使用。
修改完成后，工具会将新配置写入环境并返回上级菜单。用户可以通过再次进入“配置与状态”核实修改结果在状态面板中的反映。
注意事项： 配置修改是临时生效的，即对当前运行的工具进程有效。若退出工具后重新运行，参数会恢复默认或取决于环境变量。为保持配置持久化，可考虑在shell环境中导出相应环境变量，或每次运行后在配置菜单中再次设定。此外，修改某些关键路径（如源码目录、队列文件路径）后，务必保证相关资源存在，否则后续功能可能提示错误（例如更改源码目录后若该目录无内容，执行扫描会提示不存在包）。
功能用途： 快速查看工具在执行各操作时生成的日志文件内容，方便用户排查问题或了解执行结果。该功能提供了查看默认已知日志和自定义日志两种方式。
调用方式： 选择“查看日志”后，工具会先搜集常用日志文件路径构成选项列表。默认包括：
· Release 仓库目录下的 download_log.txt（下载 release 仓库日志）
· Release 仓库目录下的 failed_repos.txt（下载 release 仓库时失败的仓库列表，若有）[[
· 工具根目录下的 fail.log（一般用于记录批量Bloom过程中的失败信息，如 oob_builder_procedural.py 可能输出此文件）
上述文件存在时将作为可选项列出，然后附加 “自定义路径” 以及 “返回” 选项。用户可通过光标选择或输入编号选择：
· 选择某一日志文件时，如果文件存在则读取并显示其内容；如文件大小超过约4000字符，仅显示末尾部分（以避免终端输出过长）。日志内容以 Rich 面板形式显示，标题为文件路径，内容为白色等宽字体。
· 选择“自定义路径”时，系统会提示输入一个日志文件的路径。用户输入路径后，程序检查该路径文件是否存在；如果存在则如上读取显示，否则将提示红色错误“未找到 <路径>”。支持输入绝对路径或相对路径（会自动expand ~符号）。
· 选择“返回”或直接回车取消，则不作任何操作返回上级菜单。
注意事项：
- 只有在之前执行过相关操作并生成了日志文件后，这些日志才会存在。例如未执行过下载 release 仓库就不会有 download_log.txt。工具仅列出当前实际存在的日志文件。
- fail.log 通常由批量Bloom脚本在出错时生成，内容可能包含失败包的名称、错误信息等。如果进行批量打包时发生错误，建议查看该文件。
- 日志内容为只读，在面板中显示，不会打开外部编辑器。如需详细分析或另存，可手动在shell中查看这些文件。
- 查看日志不会改变任何状态，纯属辅助功能。
AGIROS 工具菜单涉及众多全局参数，它们既决定了各功能的默认行为，也可被用户定制。下表汇总了主要配置项、默认值、对应环境变量及可修改途径：
| 参数名称 | 默认值/说明 | 环境变量 | 菜单修改入口 |
| Release 仓库目录 | ros2_release_dir | AGIROS_RELEASE_DIR | 配置与状态→修改 Release 目录 |
| 源码目录 | ros2_code_dir[[ | AGIROS_CODE_DIR | 配置与状态→修改 源码目录 |
| distribution.yaml URL | http://1.94.193.239/.../distribution.yaml | (无直接变量) | 配置与状态→修改 distribution.yaml URL |
| Tracks 发行版 | jazzy | ROS2_DISTRO | 配置与状态→修改 ROS/Tracks 配置 |
| ROS 发行版 | loong | AGIROS_DISTRO/AGIROS_DISTR | 配置与状态→修改 ROS/Tracks 配置 |
| Ubuntu 版本 | jammy | AGIROS_UBUNTU_DEFAULT | 配置与状态→修改 ROS/Tracks 配置 |
| openEuler 默认版本 | 24 | AGIROS_OE_DEFAULT | 配置与状态→修改 openEuler 参数 |
| openEuler 回退版本列表 | 22,23 | AGIROS_OE_FALLBACK | 配置与状态→修改 openEuler 参数 |
| Bloom 命令 | bloom-generate | AGIROS_BLOOM_BIN | 配置与状态→修改 Bloom 命令 |
| 自动生成 gbp.conf | 关闭 (0/False) | AGIROS_GENERATE_GBP | 构建→编辑构建参数→切换自动生成 gbp.conf |
| Debian 构建参数 | --git-ignore-branch --git-ignore-new -us -uc | (无直接变量) | 构建→编辑构建参数→Debian 构建参数 |
| RPM 构建命令/参数 | rpmbuild / -ba | AGIROS_RPMBUILD_BIN (命令) | 构建→编辑构建参数→RPM 构建命令 |
| Debian 输出目录 | ~/deb_out (用户主目录下) | DEB_OUT | 配置与状态→修改 Debian 构建配置 |
| Debian 发行版(DISTRO) | loong | DISTRO | 配置与状态→修改 Debian 构建配置 |
| 默认 release_inc | 1 | DEFAULT_REL_INC | 配置与状态→修改 Debian 构建配置 |
| 并行线程数 | CPU核数或4 | PARALLEL | 配置与状态→修改 Debian 构建配置 |
| Git 用户名/邮箱 | / | GIT_USER_NAME/GIT_USER_EMAIL | 配置与状态→修改 Debian 构建配置 |
| 队列文件路径 | ./build_queue.txt | AGIROS_QUEUE_FILE | 配置与状态→修改 构建队列文件路径 |
| 队列元数据路径 | ./build_queue.txt.meta.json（自动派生） | AGIROS_QUEUE_META | 配置与状态→修改 构建队列文件路径 |
以上参数的默认值均可通过环境变量在运行前进行配置，从而在启动工具时即体现在状态面板中。在工具运行过程中，通过“配置与状态”菜单修改参数会即时生效，并调用 MenuState.update_env() 同步更新到环境变量。这一机制保证后续调用的脚本（如构建脚本）或工具自身的其他部分能够获取最新配置。例如，当修改并行线程数时，会更新环境变量 PARALLEL供 git_build_any.sh 使用；修改 Bloom 命令时更新 AGIROS_BLOOM_BIN供 oob_builder_procedural.py 使用，等等。
· 确保环境一致： 由于工具通过环境变量传递配置信息，建议在同一shell会话中执行所有步骤。如果中途开启新的终端窗口，需要重新设置相应环境变量或在工具内重新配置。工具启动时也会根据已有环境变量初始化内部状态。
· 工具依赖目录结构： 默认情况下，AGIROS_TOOLS 仓库的根目录下应包含 agiros_tools_menu.py 以及上述提到的辅助脚本（如 yaml_git_downloader_release.py、oob_tracks_to_sources.py、oob_builder_procedural.py 等）和shell脚本（clean_generated.sh、git_build_any.sh、rpmbuild_any.sh）。请勿随意移动这些文件，否则在调用功能时可能提示找不到脚本。
· 问题排查： 如果某步操作出现异常（如脚本错误、权限不足等），可通过“查看日志”调阅相关日志文件，辅助诊断问题来源。构建失败时的交互命令输入可以用来安装缺少的依赖或修正配置后再重试构建。对于复杂错误，可考虑在独立环境手工执行相同命令来调试。
· 退出和状态保存： 用户可以随时通过选择“退出”离开工具，工具退出不会主动清理或重置队列等状态，队列文件和配置仍保留在磁盘和环境中。下次启动工具，将读取之前的环境变量和队列文件继续使用。但需注意：当前版本在重启后不会自动恢复具体构建任务详情（只保留包名和完成标记），因此建议在单次会话内完成添加任务和构建流程；重启后如果需要接续先前队列，可能需要重新执行扫描或确保包的打包目录仍存在。未来版本可能改进此机制。