# ubuntu-bootstrap **Repository Path**: djunxp/ubuntu-bootstrap ## Basic Information - **Project Name**: ubuntu-bootstrap - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-11-20 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Ubuntu 开荒工具箱 给新安装的 Ubuntu 准备开发环境、现代终端与常用桌面入口。统一菜单,功能独立选择,修改前备份,重复执行不会反复追加配置。 项目地址:[pig_tree/ubuntu-bootstrap](https://gitee.com/pig_tree/ubuntu-bootstrap)。当前版本 **0.1.28**。修复清单与验证范围见 [AUDIT.md](AUDIT.md)。 交互菜单启动时会显示柴犬头 + `ubuntuBoot` 启动画面(约 74 列宽,含版本、系统与终端信息);用 `--no-banner` 或 `UBUNTU_BOOTSTRAP_NO_BANNER=1` 关闭,终端过窄、非 TTY、`NO_COLOR` 时自动降级或跳过。 ## 菜单 | 一级菜单 | 功能 | | --- | --- | | 1. 安装软件与开发环境(含 Python 工具 / Miniconda) | VS Code、Node.js 与 npm、开发环境(uv / Miniconda / Rust / Go / Docker)、中文输入法与字体、全部 Agent CLI、ROS 2、基础及编译工具、Yazi | | 2. Shell 切换与配置(Zsh / Fish / Bash / 插件) | 安装并切换 Zsh / Fish,恢复 Bash。Fish 会改登录 Shell 和已安装的 Kitty / Ghostty 启动命令;插件、别名和 Starship 配置面向 Zsh;Miniconda 安装会初始化 Bash / Zsh | | 3. 安装终端(Ghostty / Kitty) | Ghostty / Kitty 独立安装,按系统版本给出推荐 | | 4. 美化终端(字体 / 主题 / 透明度 / Starship) | 从已安装的 GNOME Terminal / Ghostty / Kitty 中选择;字体、主题和背景不透明度可分开或一起设置;Starship 提示符可单独选择官方预设 | | 5. 系统字体与文字大小(中文字体 / 缩放 / 候选框) | GNOME 文字缩放、Fcitx 5 候选框字号、中文字体;新机器没有 Fcitx 时会先安装再设置 | | 6. 桌面与快捷键(Ctrl+Alt+T / 默认终端 / 右键菜单) | Ctrl+Alt+T 和默认终端要先选定已安装的终端;右键扩展和 Agent 别名可以直接配置 | | 7. 软件源与包下载镜像 | 查看软件源、Ubuntu 主源与开发工具(pip/npm/cargo/Go/conda)国内镜像、自动测速 | | 8. 检查安装状态与版本信息 | 只读诊断 | | 9. 安装记录与配置恢复 | 查看记录,按 ID / latest / all 恢复 | 子菜单执行完成后留在当前分类,输入 0 返回;安装软件、切换 Shell、安装终端和外观美化分别选择。Node.js 与 npm 通过 nvm 一起安装,避免系统 npm 与用户 Node 混用。切换 Fish 会同步当前用户登录 Shell,以及 Kitty 的 `shell`、Ghostty 的 `command` / `initial-command`。插件、别名、Conda、Starship、ROS 环境和 Agent 快捷指令仅集成 Bash / Zsh;Miniconda 的 Fish 初始化需另行执行 `~/miniconda3/bin/conda init fish`。 运行终端与配置目标分别显示;美化只列出检测到的已安装终端。Ubuntu 默认终端本次支持 **GNOME Terminal**,不将 GNOME Console、Ptyxis 或其他终端视为同一种软件。GNOME Terminal 默认修改其默认配置档,界面显示 UUID;多配置档用户可用 `--gnome-profile UUID` 指定目标。字体、颜色、16 色调色板、光标与选区均纳入恢复记录。 ```bash # 仅配置 Ghostty 字体和主题 python3 bootstrap.py --modules appearance --terminal ghostty --theme 'Dracula+' # 仅更换 GNOME Terminal 字体与字号 python3 bootstrap.py --modules terminal-font --terminal gnome-terminal --font-size 15 # 单独调整终端背景不透明度(默认 80%) python3 bootstrap.py --modules transparency --terminal ghostty --opacity 90 # 关闭 Ghostty 毛玻璃(背景模糊) python3 bootstrap.py --modules transparency --terminal ghostty --no-blur # GNOME Terminal 仅切换主题 python3 bootstrap.py --modules theme --terminal gnome-terminal --theme 'Catppuccin Mocha' # 系统文字缩放到 135%;恢复默认用 gsettings reset org.gnome.desktop.interface text-scaling-factor python3 bootstrap.py --modules text-scaling --text-scaling 1.35 # 候选框字号;没有 Fcitx 5 时会先安装。保持横向候选,只改字体大小 python3 bootstrap.py --modules candidate-font --candidate-font-size 16 # 安装并切换 Fish;或用 default-shell 切换 Zsh,用 bash-shell 恢复 Bash python3 bootstrap.py --modules fish-shell # 单独安装并启用 Zsh 插件 python3 bootstrap.py --modules plugins ``` 美化不修改默认 Shell、不安装 Shell 插件。字体使用内置的 JetBrains Maple Mono,默认 Medium 字重、14 号字号,可调整 6–48 号字号;已有字体直接沿用。字体随源码内置,美化时从 Gitee 按 SHA256 校验下载并安装整套字重。背景不透明度默认 80%,Ghostty 另默认开启背景模糊(毛玻璃);Kitty 用 background_opacity,GNOME Terminal 3.x 不支持则跳过。Ghostty 应用字体后校验 +show-config 与 +list-fonts。原有 CLI 套餐参数继续保留供熟悉范围的用户使用。 ## 一条命令打开菜单 在普通用户终端运行,不需要 `sudo` 启动: ```bash wget https://gitee.com/pig_tree/ubuntu-bootstrap/raw/main/install -O ub && bash ./ub ``` 也支持你习惯的 source 形式;使用 `./` 明确指定刚下载的文件: ```bash wget https://gitee.com/pig_tree/ubuntu-bootstrap/raw/main/install -O ub && . ./ub ``` 入口从固定版本 `v0.1.28` 标签下载工具箱压缩包与 SHA256 校验值,避免下载过程中代码版本混杂。Git 推送使用 SSH;公开下载使用 HTTPS,其他用户无需配置 Gitee 密钥。 启动时“准备工具箱”会**一次性下载一个压缩包**(`toolkit.tar.gz`,内含工具自身的 Python 代码、Shell/终端配置模板、主题和版本清单,约 50 KB),校验 SHA256 后解压,**不会安装任何应用软件**。固定版本缓存在 `${XDG_CACHE_HOME:-$HOME/.cache}/ubuntu-bootstrap/releases`:首次下载、校验、解压,之后直接读本地缓存校验后启动,无需联网取代码;缓存缺失或损坏时重新下载压缩包。每次运行 `wget` 仍会重新获取小型入口,软件安装阶段也可能访问上游。 需要强制重新获取工具箱代码时:`UB_REFRESH_TOOLS=1 bash ./ub`。重新下载 main 入口即可升级到新固定版本。 ## 启动自检与菜单状态 进入菜单前自动进行只读自检,列出基础工具、Node、uv、Rust、Go、Docker、终端、Shell、插件、字体、Starship、登录 Shell、桌面入口和 ROS。菜单 8 的完整自检再按组展开;中文输入法和中文字体在「桌面与输入法」。摘要按状态分开计数:**已就绪、未安装、待配置、待确认、异常**。没装过的项目记为未安装;已经安装但没有当作登录 Shell 的 Fish,以及不是当前 Shell 的「恢复 Bash」,记为未选用,不进待配置。不适用、可停用、已停用同样不计入。菜单徽章为 **已安装 / 已就绪 / 待配置 / 未安装 / 未选用 / 检测异常**。自检不会运行安装器或加载用户 rc 文件;每个版本命令有 2.5 秒超时,多个命令并行检查。终端是否一致以 `~/.config/ubuntu-bootstrap/shell.json` 里记下的 Shell 为准;没有这条记录时,以当前登录 Shell 为准,Bash、Zsh、Fish 都可以作为一致目标。 菜单 **1 → Agent CLI** 重新检测九种 Agent 的实际版本和异常入口,兼顾 PATH、用户本地目录和 nvm 中未激活的版本。菜单 **8. 自检与版本** 或 `bash ./ub --doctor` 可查看完整状态、版本和路径。重复选择已安装 Agent 会运行上游更新安装,并非检查时自动更新。 标题、编号和状态使用颜色与粗体;TTY 自动启用,重定向为日志时使用纯文本。支持 `--no-color`、`--color never`、`--color always` 和 `NO_COLOR=1`。配置状态来自静态检查,**不等于已经验证图形渲染、Agent 登录或 ROS 通信**;模拟 `--target-os` 不会把 Windows 上的软件当作目标 Ubuntu 状态。 有自己的域名后,可以缩短成: ```bash wget https://你的域名/install -O ub && bash ./ub ``` 域名与 HTTPS 跳转设置见 [Gitee 发布与短链](docs/PUBLISH.md)。Gitee 仓库地址本身不会自动变成独立短域名。 ## 功能 | 分类 | 内容 | | --- | --- | | 基础工具 | curl、wget、git、unzip、xz、证书、GPG、系统 Python 3;可选 C/C++ 编译工具 | | 软件源 | 查看已有源;Ubuntu 主源与 pip / npm / cargo / Go / conda 国内镜像,支持自动测速选最快 | | 开发环境 | VS Code 官方 APT 源;用户级 nvm、Node.js 24 LTS / 可选 22、npm | | 开发工具链 | uv(Python 包与项目管理工具)、Miniconda(独立 Python 3.12 + Conda)、Rust(rustup + 国内镜像)、Go(golang-go + GOPROXY)、Docker CE + Compose(国内源) | | 中文环境 | 雾凇拼音、Fcitx 5 拼音 + 维基/萌娘词库、搜狗 Linux 版;中文字体;用户配置可恢复 | | Shell | Zsh、历史建议、语法高亮;切换当前用户登录 Shell;恢复 Bash | | 终端 | Kitty;26.04 官方 Ghostty;24.04 固定版本社区 Ghostty | | 美化 | JetBrains Maple Mono(Medium / 14,Gitee 按需下载)、背景不透明度(默认 80%)、Ghostty 毛玻璃、Starship、独立主题切换、原生主题预览 | | 桌面入口 | Ctrl+Alt+T、自定义默认终端接口、Nautilus 右键菜单 | | 右键菜单 | 复制文件 / 文件夹 / 多选路径;在已安装的 Kitty / Ghostty 中打开 | | ROS 2 | 系统匹配版本、desktop / ros-base、国内 ROS / rosdep 镜像、装后自检、rosdep、colcon、Bash / Zsh 环境 | | 可选增强 | micro、fzf、仓库可用时安装 eza / zoxide;已有 Conda 的 Zsh 集成与关闭 base 自动激活。Zsh 插件同时启用 fzf 历史搜索和 zoxide | | Agent CLI | OpenCode v2、Claude Code、Grok Build、Pi、OmO、Copilot CLI、Crush、DeepSeek Harness、omp | | 快捷指令 | 自定义启动名称和参数,如 opc / claudeds;Bash、Zsh 持久化;查看、修改和删除 | | 检查与恢复 | 安装计划、自检、模块级安装记录、失败重试、配置恢复 | | 配置复现 | 把模块选择与选项导出为 profile 文件,在新机 `--import-profile` 一键复现 | 默认不执行整机升级、不清理已有第三方源、不修改 root 登录 Shell、不修改 `/bin/sh`。 ### 镜像与开发工具链 - **自动测速**:默认对清华(tuna)与中科大(ustc)做延迟测试,自动选最快;测速失败回退 `--mirror`。`--no-auto-mirror` 可关闭;`--mirror official` 保持上游。ROS 软件源、rosdep 源、Docker 源与 rustup 镜像都复用这次测速结果。 - **镜像全家桶**:Ubuntu 主源 + pip(`~/.config/pip/pip.conf`)+ npm(`~/.npmrc`,npmmirror)+ cargo(`~/.cargo/config.toml`,sparse 镜像)+ Go(`~/.config/go/env`,`GOPROXY=goproxy.cn`)+ conda(检测到才用 `conda config` 改默认频道)。全部走事务记录,可恢复;已有 Cargo source 配置不会被覆盖。 - **开发工具链**:`python-uv`(uv 官方安装器)、`rust`(rustup,`RUSTUP_DIST_SERVER` 指向镜像)、`go`(`golang-go` + GOPROXY)、`docker`(Docker CE 国内源 + 当前用户加入 docker 组,需重新登录生效)。 - **配置复现**:`--export-profile FILE` 把本次模块与选项写成 JSON;新机 `--import-profile FILE` 一键复现,模块名与选项都会校验。 ### Python、uv 与 Miniconda 入口运行使用 Ubuntu 系统的 `/usr/bin/python3`;“基础工具”安装的是 APT 的 `python3`。开发环境页单独显示系统 Python 的版本,uv 的“未安装”仅表示没有找到 uv。 - `python-uv`:安装 uv,管理 Python 包、项目和虚拟环境;此模块不额外下载 Python 解释器。 - `miniconda`:安装 Miniconda(独立 Python 3.12 + Conda)到 `~/miniconda3`,支持 amd64 / arm64。当前锁定 `py312_26.5.3-1`,使用官方索引提供的 SHA256 校验安装包;此版本已核对清华与中科大的镜像均可下载。 - 默认根据镜像测速结果从清华 / 中科大下载安装包,并配置 Conda 默认频道镜像。使用 `--no-auto-mirror --mirror tuna` 可固定清华;`--mirror official` 使用官方安装包并保留官方源或用户已有频道设置。自定义频道不自动改写。 - 初始化 Bash / Zsh,并关闭 base 自动激活。新开终端后使用 `conda activate base` 或 `conda activate 环境名` 激活;未激活时沿用原来的 Python 命令路径。Fish 可另行运行 `~/miniconda3/bin/conda init fish`。 - 重复运行沿用 `~/miniconda3` 中的 Conda,不自动升级。已有的不完整目录或符号链接会保留并报错;不覆盖其他 Conda 发行版。Shell 和 `.condarc` 配置纳入恢复记录;恢复配置不会删除 Miniconda 或其中的环境。 - `conda` 与 `conda-base` 仍是已有 Conda 的配置功能,不负责安装;Miniconda 是单独可选项,不默认加入开发环境套餐。 菜单路径:**1. 安装软件与开发环境 → 3. 开发环境 → 安装 Miniconda**。 ```bash # 源码目录运行;固定清华镜像 python3 bootstrap.py --modules miniconda --no-auto-mirror --mirror tuna # 仅预览安装计划 python3 bootstrap.py --modules miniconda --no-auto-mirror --mirror tuna --dry-run ``` 安装流程参考 [Anaconda Miniconda 文档](https://www.anaconda.com/docs/getting-started/miniconda/install) 与 [清华镜像说明](https://mirrors.tuna.tsinghua.edu.cn/help/anaconda/)。 ### 中文输入法与字体(可选) 菜单 **1 → 4 中文输入法(三选一)与中文字体**。Ubuntu **22.04 / 24.04 / 26.04** 的 GNOME 桌面提供以下独立方案,支持 amd64 / arm64。一次选择一种方案,可同时选择中文字体。 | 方案 | CLI 模块 | 安装与配置 | | --- | --- | --- | | 雾凇拼音 | `input-rime` | Fcitx 5 + Rime + Lua;锁定上游 2024.09.25 配置,在目标机编译部署,合并用户补丁、保留用户词频数据库 | | 拼音 + 中文维基 / 萌娘百科词库 | `input-pinyin` | Fcitx 5 拼音;下载固定版本文本词库,用系统 libime 编译以兼容 22.04;开启联想,云拼音由用户在配置工具中自行开启 | | 搜狗官方 Linux 版 | `input-sogou` | 官网 4.2.1.145 amd64 / arm64 包;**Fcitx 4 + Xorg**,校验 SHA256、包名、版本和架构 | ```bash # 三选一;不要把三个模块放在同一次安装中 bash ./ub --modules input-rime bash ./ub --modules input-pinyin bash ./ub --modules input-sogou # 可同时安装字体 bash ./ub --modules input-pinyin,chinese-font ``` **搜狗不是 Fcitx 5 插件。** 在 Wayland 会话会提示注销并选择「Ubuntu on Xorg」后再安装,不自动关闭 Wayland、不替换 GDM。没有 Xorg 登录选项的系统(包括只提供 Wayland 的较新 GNOME 环境)请选择前两种方案;不能将搜狗标为在所有 22.04+ 桌面上均可使用。搜狗为闭源软件,联网功能遵循其自身设置。 安装会暂时退出当前用户的 Fcitx,备份后更新环境变量、框架自启动配置、输入法列表和 `~/.xinputrc`,**完成后须注销重新登录**。Fcitx 5 方案使用 `fcitx5-configtool`,搜狗使用 `fcitx-configtool`;一般以 Ctrl+空格切换,Rime 可用 F4 选择雾凇拼音。若安装失败并恢复配置,也请重新登录以启动原输入法。 不卸载 IBus,不自动删除另一输入法框架或其他软件;APT 需要删除软件包时会停止并报告冲突。`--restore` 恢复本工具记录的用户配置和词库文件,保留已装软件包和用户学习数据库。部署期间不要同时编辑输入法配置。已有复杂 Rime 补丁可能导致部署失败,此时会报告错误而不会假称成功。 所有附加资源都按固定 URL/版本和 SHA256 校验。雾凇拼音固定兼容配置版本,不等同于自动跟随上游最新配置;词库需访问 GitHub,搜狗使用官网公开的动态下载地址,下载失败不会安装未校验文件。实际 Ubuntu 安装、候选窗和各应用中的输入仍需按 [测试说明](docs/TESTING.md) 验收。 旧模块 `input-method` 保留原有 Fcitx 5 + 基础 Rime 行为,不自动升级为雾凇拼音。`chinese-font` 安装 Noto CJK 与 Emoji;更纱黑体暂未加入。 菜单 **5. 字体设置** 可以单独调整,不依赖是否已经装过输入法: - `text-scaling` 写入当前用户的 `org.gnome.desktop.interface text-scaling-factor`,范围 0.5–3。`1` 是 100%,`1.35` 是 135%。只缩放界面文字,不改字体族,也不影响其他用户。改完后请在每个屏幕上看一下文字、按钮和界面有没有被挤出。恢复默认:`gsettings reset org.gnome.desktop.interface text-scaling-factor`。 - `candidate-font` 设置 Fcitx 5 经典界面的候选框字体,默认 `Noto Sans CJK SC`,字号 8–32。新机器没有 Fcitx 5 时会先安装框架和中文字体再写入 `~/.config/fcitx5/conf/classicui.conf`,并重启当前用户的 Fcitx 5。只替换 `Font=`,不改变候选条横竖方向。雾凇、拼音和搜狗的词库本身不能控制这个窗口。 ### ROS 2 安装加固 - **国内镜像**:ROS 软件源与 rosdep 源默认切换到你选的镜像(`--mirror tuna|ustc|official`),不再直连 `packages.ros.org` 与 `raw.githubusercontent.com`。 - **装后自检**:安装完成后检查 `/opt/ros/<版本>/setup.bash` 并实际执行 `ros2 --help`,不完整直接报错,而不是静默成功。 - **UTF-8 locale**:会话不是 UTF-8 时自动 `locale-gen` 并 `update-locale LANG=en_US.UTF-8`。 - **磁盘检查**:剩余空间不足会提示(桌面版建议约 8 GB),过小直接报错。 - **已有源**:检测到手工 ROS 软件源时报错,并可加 `--allow-existing-ros` 沿用;不静默覆盖,避免 Signed-By 冲突。 - **网络重试**:`apt update`、包安装、`rosdep update` 遇到瞬时失败会自动重试。 - 源包与密钥仍来自官方 `ros2-apt-source` 固定版本(HTTPS + SHA256 校验)。 ## 套餐与独立功能 下载入口后,可以直接传参;以下命令均在 Ubuntu 中运行: ```bash # 先预览完整开荒套餐(含开发工具镜像;这个套餐不自动安装 ROS 2) bash ./ub --profile full --dry-run # 基础开发环境:基础工具、编译工具链、VS Code、Node.js bash ./ub --profile basic # 现代终端:优先沿用已有终端,配置字体、Zsh、Starship、主题和桌面入口 bash ./ub --profile terminal # ROS 2 环境;服务器可选择 base bash ./ub --profile ros --ros-flavor base # ROS 2 使用清华/科大镜像,或沿用已有手工软件源 bash ./ub --profile ros --mirror ustc bash ./ub --modules ros2 --allow-existing-ros # 开发镜像与工具链 bash ./ub --profile dev bash ./ub --modules dev-mirrors,mirror --no-auto-mirror --mirror tuna # 导出当前选择,在新机复现 bash ./ub --profile dev --export-profile ~/dev.json bash ./ub --import-profile ~/dev.json # 中文输入法与中文字体 bash ./ub --modules input-method,chinese-font # Ubuntu 24.04:明确选择社区 Ghostty 路线 bash ./ub --profile terminal --terminal ghostty --community # 仅切换已安装终端的主题,不重新安装整套环境 bash ./ub --modules theme --terminal ghostty --theme 'Kanagawa Wave' # 仅安装所选模块,依赖自动补齐 bash ./ub --modules vscode,node,zsh # 显式确认的非交互安装 bash ./ub --profile basic --yes # 可选切换主源;执行前备份,保留 suites/components 和第三方源 bash ./ub --modules mirror --mirror tuna ``` **Kitty 和 Ghostty 安装项独立。** `--modules kitty` 只处理 Kitty,`--modules ghostty` 只处理 Ghostty。终端套餐的 `auto` 优先沿用唯一已有终端;两者都已安装时,在交互执行套餐前可选择使用哪个;均未安装时才选系统推荐路线。明确传入 `--terminal` 可覆盖选择,执行计划会交代目标与实际安装项。只有主动选择两个安装项时才处理两者。 Ubuntu 20.04 / 22.04 暂无本工具验证过的 Ghostty 全新安装路线;**已安装且可运行的 Ghostty 可以继续用于美化、主题、快捷键和 Shell 集成,不会为此附带安装 Kitty**。现有安装入口异常时会显示检测状态,避免默默换装另一款终端。 模块列表:`bash ./ub --list`。`--dry-run` 不写用户配置、不修改软件源、不运行安装命令;通过远程入口启动时首次仍需下载工具自身,后续使用完整缓存。完全离线预览可以从源码目录运行 `python3 bootstrap.py ... --dry-run`。 ## 八款主题 默认 **Catppuccin Mocha**。菜单可独立选择主题、预览与应用: | 菜单名称 | Ghostty 原生名称 | | --- | --- | | Catppuccin Mocha | Catppuccin Mocha | | Tokyo Night Night | TokyoNight Night(以本机列表为准) | | Kanagawa Wave | Kanagawa Wave | | Gruvbox Dark Hard | Gruvbox Dark Hard | | Nordfox | Nordfox | | Dracula+ | Dracula+ | | GitHub Dark Default | GitHub Dark Default | | Catppuccin Latte | Catppuccin Latte | Ghostty 直接使用原生 `theme = ...`,应用前检查本机主题列表。保留 Ghostty 窗口行为与其他渲染设置;终端美化(字体 + 主题)会一并设置背景不透明度(默认 80%)和背景模糊(毛玻璃,默认开启,可用 `--no-blur` 关闭)。背景模糊是否真正生效取决于合成器:Linux 官方明确支持 KDE Plasma(强度由 KWin 控制),macOS 需完全退出重开。终端美化只处理所选终端的字体、主题和不透明度;Zsh 插件、Starship 提示符和默认 Shell 均为独立模块。 ```bash # Ghostty 原生交互预览 bash ./ub --preview-themes --terminal ghostty # 随系统外观自动切换 Mocha / Latte bash ./ub --modules theme --terminal ghostty --theme system # Kitty 对应主题 bash ./ub --modules theme --terminal kitty --theme 'Tokyo Night Night' ``` Ghostty 的显式颜色配置会覆盖主题。切换时,主配置文件内的原有颜色行会保留为注释,并完整备份;通过 `config-file` 额外引入的颜色仍可能覆盖主题,工具会提示。修改后使用 Ghostty 原生重新加载配置或打开新窗口。 Kitty 的八款配色取自 Ghostty 相同的上游数据源,已随项目内置,无需联网下载主题。`system` 自动深浅色仅提供 Ghostty 原生路线。 ## Agent CLI 与自定义快捷指令 在菜单“Agent CLI 与快捷指令”里单独选择或多选安装。Agent 不自动加入 full 套餐,不代替用户登录、订阅或配置 API。 | Agent | 安装路线 | 启动命令 | | --- | --- | --- | | OpenCode v2 | `https://opencode.ai/v2/install` 官方脚本 | `opencode` | | Claude Code | `https://claude.ai/install.sh` 官方脚本 | `claude` | | Grok Build | `https://x.ai/cli/install.sh` 官方脚本 | `grok` | | Pi | npm:`@earendil-works/pi-coding-agent` | `pi` | | OmO | npm:`omo-ai`,需要 Node 24 | `omo` | | Copilot CLI | npm:`@github/copilot` | `copilot` | | Crush | npm:`@charmland/crush` | `crush` | | DeepSeek Harness | npm:`@deepseek-ai/dsh`,同时准备 pnpm | `dsh` / `dsh web` | | omp | npm:`@oh-my-pi/pi-coding-agent`,自动准备 Bun 1.3.14+ | `omp` | 官方脚本先下载到本地、检查 Shell 语法、记录 SHA256 后执行,不使用 sudo。npm 安装通过本工具准备的用户级 nvm 执行,检查 Node 引擎要求,并生成用户级启动器,使 CLI 不依赖已有 nvm default 恰好是同一个版本。默认按上游当前发布版本安装,可用 `--agent-version` 指定版本;上游支持的版本/通道以各项目文档为准。 ```bash # 安装三个原生 CLI bash ./ub --modules agent-opencode,agent-claude,agent-grok # 安装图片中的六种 CLI bash ./ub --modules agent-pi,agent-omo,agent-copilot,agent-crush,agent-dsh,agent-omp # 自定义启动快捷指令,可继续向后追加参数 bash ./ub --shortcut 'opc=opencode' \ --shortcut 'claudeds=claude --dangerously-skip-permissions' # 查看 / 删除;修改时再次使用同一个名字 bash ./ub --list-shortcuts bash ./ub --remove-shortcut opc ``` 快捷指令是 Shell alias,PATH 是环境变量。两者会持久化到 Bash 和 Zsh 配置,原来的 CLI 命令保留。`claudeds` 的参数只在用户明确配置并使用这个快捷指令时传递,不改变普通 `claude` 的默认启动参数。 使用 `. ./ub` 打开工具、配置后正常退出时,本工具生成的 Agent PATH/别名片段会加载到当前 Shell;用 `bash ./ub` 或 `python3 bootstrap.py` 运行,则新开终端或执行 `source ~/.zshrc` / `source ~/.bashrc` 生效。加载入口只 source 本工具的片段,不重跑整个用户 rc。 Ubuntu 是否能运行某个 Agent,还取决于其上游的 CPU、运行库、内存及平台要求。安装后的 `--version` 检查失败会报告该模块失败;四个版本的 Agent 实际安装仍待验收。 ## 兼容范围 目标系统为 **Ubuntu 20.04 / 22.04 / 24.04 / 26.04,amd64 / arm64**。首版桌面集成支持 Ubuntu 默认 **GNOME + Nautilus**;服务器仍可安装基础工具与开发环境,桌面模块会显示不可用。 | 系统 | 推荐终端 | Ghostty | ROS 2 | | --- | --- | --- | --- | | 20.04 | Kitty | 默认不提供自动路线 | Foxy,已结束维护,需 `--legacy-ros` | | 22.04 | Kitty | 默认不提供自动路线 | Humble | | 24.04 | Kitty | 1.3.1 固定社区包,需 `--community` | Jazzy | | 26.04 | Ghostty | 官方 APT 仓库,需有候选包 | Lyrical | 20.04 的兼容不代表所有最新版软件都可安装;本工具不会升级 GTK/glibc 来强装终端。APT 模块使用系统实际候选包;不同架构或镜像缺包时会报告失败。 Nautilus 实际检测 GI API 4.1 / 4.0 / 3.0,兼容新旧菜单参数。剪贴板按 Wayland / X11 使用 wl-copy / xclip。本地路径通过参数列表传递,包含中文、空格、单引号不会拼成 shell 命令;远程位置不提供本地终端菜单。 Ctrl+Alt+T 使用用户级 GNOME 自定义快捷键,记录并替换冲突绑定,保留其他快捷键。默认终端模块检测 `xdg-terminal-exec` 和已有 GNOME 接口;**不改变系统全局 alternatives**,因此读取 `x-terminal-emulator` 的旧程序可能仍使用系统默认终端。 **目前验证了本地逻辑、模拟安装计划、下载锁定与脚本结构;没有完成四个版本的 Ubuntu 实际安装/桌面验收。** 查看 [测试状态](docs/TESTING.md),不要将首版标为已全面实测。 ## 配置保护与恢复 `.bashrc`、`.zshrc`、Kitty / Ghostty 配置按管理块更新。提示符独立存放在 `~/.config/ubuntu-bootstrap/`,不覆盖用户的 `~/.config/starship.toml`。已有符号链接配置文件保留并报告,不自动改写其指向目标。 切换 Zsh、Fish 或恢复 Bash 时,会同时设置当前用户登录 Shell、Kitty 的 `shell`、Ghostty 的 `command` 与 `initial-command`,并纠正终端内的 `SHELL`。插件、别名、Conda、Starship、ROS 环境和 Agent 快捷指令仅集成 Bash / Zsh;Miniconda 的 Fish 初始化需另行执行 `~/miniconda3/bin/conda init fish`。Ctrl+Alt+T 和右键启动器显式执行所选 Shell;登录 Shell 已经是目标 Shell 时仍会修复残留的终端配置。之后安装的终端会沿用 `shell.json` 里保存的选择。菜单 6 中,右键扩展和 Agent 别名不要求先安装终端;Ctrl+Alt+T 和默认终端会先从已安装的 GNOME Terminal / Ghostty / Kitty 里选一个。 既有窗口的 Shell 进程不会被强行替换。改完后重新打开窗口;已有 Ghostty 进程应完整退出重开,使图标入口与新标签页加载新配置。Ghostty 桌面启动器使用 `-e` 打开新实例,避免旧单实例进程沿用 Bash。显式执行 `kitty bash` / `ghostty -e bash` 等用户指定命令仍按用户参数运行。 每个模块修改前创建备份,位置为: ```text ~/.local/state/ubuntu-bootstrap/runs/<记录ID>/ ├── journal.json 修改记录与恢复状态 ├── commands.log 执行命令和退出码 └── *.bak 原配置内容 ``` ```bash bash ./ub --doctor bash ./ub --history bash ./ub --restore latest bash ./ub --restore 记录ID bash ./ub --restore all ``` 恢复按新到旧处理,已有的后续手动修改会保留并报告冲突。恢复配置、快捷键、默认登录 Shell;**不会卸载软件、移除字体、删除 nvm 的 Node 安装、卸载 ROS 源包或清除 rosdep 数据**。软件卸载由用户通过包管理器单独处理。 一个模块失败后会保留记录,跳过依赖模块,继续其他独立功能。重新执行原命令可以重试;如需撤销部分配置,先查看记录再恢复。软件源更新失败时,本次源修改有备份,可直接恢复。 Node.js 的 nvm 是用户级环境,已有 `~/.nvm/nvm.sh` 时沿用,并保留已有 default 别名;新安装默认 Node 24。不自动使用 `sudo npm`,系统服务不会自动加载 nvm 环境。ROS 自动配置对应的 `setup.bash` / `setup.zsh`,不把 Bash 初始化文件 source 到 Zsh。 ## 开发与发布 ```bash python3 -m unittest discover -s tests -v python3 bootstrap.py --dry-run --target-os 26.04 --arch arm64 --profile full python3 tools/release.py --repo pig_tree/ubuntu-bootstrap --version 0.1.28 --zip ``` 运行时仅依赖 Python 标准库,支持 Python 3.8。Git 工作树文件必须使用 LF;项目已经设置 `.gitattributes`。 发布前请阅读 [Gitee 发布与短链](docs/PUBLISH.md)、[测试状态](docs/TESTING.md) 和 [第三方说明](THIRD_PARTY_NOTICES.md)。依赖的固定版本 URL / SHA256 见 `dependencies.lock.json` 与 `community.lock.json`。摘要用于固定内容、发现损坏和版本漂移,并不是独立的上游签名认证。 MIT License。 重新应用美化、主题或终端 Shell 时,相应管理块会移动到文件末尾,以覆盖此前追加的同名设置;原文件仍会备份。Ghostty 同时存在 `config.ghostty` 与 `config` 时,按此顺序读取,并写入后加载的 `config`。额外引入文件、命令行覆盖与自定义配置目录仍需实际核对。 ## Yazi 文件管理器 Ubuntu 22.04 / 24.04 / 26.04,amd64 / arm64:菜单「安装软件 → Yazi 文件管理器」。也支持无桌面的终端会话。 ```bash # 官方 stable 本体 + 必需的 file bash ./ub --modules yazi # 本体 + 常用增强:视频/PDF/JSON 预览、文件名/内容搜索、图形会话剪贴板 bash ./ub --modules yazi-extras ``` 按照 [Yazi 官方安装文档](https://yazi-rs.github.io/docs/installation/) 配置官方 APT 源。签名密钥固定 SHA256,源和密钥均纳入配置备份;从官方 stable 索引选择当前架构版本,APT 验证包签名链。已有其他 Yazi 源会停止并指出文件,请先合并或停用重复源,避免 Signed-By 或 nightly 冲突。安装使用 `--no-remove --no-install-recommends`,显式安装 `file`;不会隐式拉入整套 Recommends,也不会自动降级已有较新版本。 常用增强安装 `ffmpeg jq poppler-utils fd-find ripgrep`;Wayland 增加 `wl-clipboard`,X11 增加 `xclip`,无图形会话不装剪贴板。Yazi 可使用 Ubuntu 的 `fdfind`。运行 `yazi` 打开,按 `q` 退出。 这不是完整增强包:压缩包预览需要另备非 standalone 的 7-Zip,SVG 需要 resvg;fzf 要求 ≥ 0.53.0,zoxide 需要配合该版本的 fzf,ImageMagick 要求提供 `magick` 且版本 ≥ 7.1.1。常用增强完成后会检查已有 fzf/magick 版本并提示,不自动用发行版旧包代替。Nerd Font 可通过同菜单的终端字体选项单独安装;图片显示仍取决于终端支持。上述可选能力缺失不影响 Yazi 本体启动。 当前已验证官方两架构仓库元数据、密钥 SHA256、安装计划和模拟回归;尚未完成 Ubuntu 原生 APT 安装与交互预览验收。 Starship 样式与[官方预设](https://starship.rs/zh-CN/presets/)对应,使用固定版本 v1.23.0 的原始预设配置,不叠加自定义模块。入口为“美化终端 → Zsh 提示符(Starship)”;支持全部 12 种官方预设,旧 `plain` / `powerline` 参数分别映射到 `plain-text-symbols` / `pastel-powerline`。外观还取决于字体、终端配色和当前目录。 Rime(中州韵)的雾凇配置部署到 `$XDG_DATA_HOME/fcitx5/rime`(默认 `~/.local/share/fcitx5/rime`),默认选择雾凇并重置为简体。重装会迁移旧错误路径 `~/.config/fcitx5/rime` 的配置,实际数据目录内的用户补丁优先;用户词频数据库和同步目录保留。 Nautilus 安装时通过系统 Python 实际加载扩展、生成菜单并检查 helper。菜单中的“已安装”仅表示静态文件、权限与配置完整,不保证已有窗口已加载;“可停用”表示当前扩展配置存在,是可选操作而非故障。Nautilus 42 使用 API 3.0。