对于RISC-V开发者而言，ruyi包管理器能让我们告别手动管理工具链的繁琐与不确定性。它通过一个统一的软件源和简洁的命令，让你能轻松、准确地获取所需工具（如镜像和烧录开发板），无需在不同官网间搜寻版本。
ruyi自动处理了跨平台兼容性和安全校验，确保了安装的可重复性与环境的一致性，这对于团队协作和CI/CD流程挺有帮助的，而手工下载/解包缺少统一的安装状态记录，升级和卸载容易出错。它提供了清晰的安装记录和完整的生命周期管理，使得软件版本的追踪、升级和卸载变得简单可靠，让你能专注于开发本身，而非环境配置的琐碎事务。
一、概览
-
命令：
ruyi install/i <atom> [<atom> ...] -
作用：从配置的 packages-index 下载并安装一个或多个包，或仅下载分发文件用于离线或审查。
-
-f, --fetch-only：只下载 distfiles（分发文件），不解包、不写安装状态。适用于离线准备或仅取文件审查。 -
--host HOST：指定目标主机（如riscv64、linux/x86_64等）。若只写 arch，默认会补上linux作为 OS。使用ruyi.ruyipkg.host.canonicalize_host_str正规化。 -
--reinstall强制重装：若包已被标记为已安装，则先移除再重新安装。
已安装判断：默认情况下若安装记录存在或安装目录存在，
ruyi会跳过重复安装；使用--reinstall可覆盖。
--fetch-only不会写入安装状态；若需要在另一台机器安装，推荐先--fetch-only并搬运 distfiles，再在目标机进行解包/安装。找不到包：先运行
ruyi update，确认config.toml中repo.remote指向正确的 packages-index安装状态与目录不一致：状态存储可能丢失或被手动修改；若目录存在但未被识别为已安装，
ruyi在卸载时会拒绝自动删除以避免误删用户数据。可用--reinstall恢复或手动清理后重新安装。
四、示例
- 安装最新版本（按 repo 索引）
ruyi install emulator/qemu-user-riscv-xthead
- 指定 target host 并只下载（不安装）
ruyi install emulator/qemu-user-riscv-xthead --host riscv64 --fetch-only
- 强制重装
ruyi install emulator/qemu-user-riscv-xthead --reinstall
- 批量安装（多个 atom）
ruyi install pkgA pkgB category/pkgC
五、QEMU 场景
- 同步索引（保证能看到最新包）
ruyi update
- 查找 QEMU 相关包
ruyi list --name-contains qemu
- 安装 qemu-user-riscv-xthead 模拟器
ruyi install emulator/qemu-user-riscv-xthead
- 若用于交叉运行（如 binfmt），将下载的二进制解包到目标目录并配置
binfmt_misc或使用ruyi提供的 wrapper（参见mux/venv/maker.py中关于ruyi-qemu的逻辑）。
CLI 与参数：
ruyi/ruyipkg/install_cli.py安装实现：
ruyi/ruyipkg/install.pyAtom 解析：
ruyi/ruyipkg/atom.pyhost canonicalize：
ruyi/ruyipkg/host.py