Ubuntu 用户开发环境配置脚本

这个脚本专门用于配置用户级的开发环境，无需管理员权限。适用于在已有的Ubuntu系统上快速配置开发工具和环境。

🎯 快速开始

配置用户开发环境（全部组件）

./setup.sh

交互式选择要安装的组件

./setup.sh --interactive

只装 Codex CLI / Claude Code 这类 AI 编程工具

./setup.sh --only codex,claude

用 Claude Code / Codex CLI 一键配置（无需记参数）

克隆本仓库后，在仓库根目录里打开 claude 或 codex，直接说"帮我初始化开发环境"， agent 会读取内置的 Skill / AGENTS.md， 询问你要装哪些组件后自动执行，详见下方"🤖 作为 Skill / Agent 使用"一节。

查看帮助

./setup.sh --help

🎯 功能特点

这个脚本专注于用户级配置，无需sudo权限，适用于在已有Ubuntu系统上设置个人开发环境。

配置内容

• chsrc 源切换工具: 用于后续可能的源切换需求
• Oh My Zsh: 美化和增强终端体验，维护 git、docker、kubectl、sudo、extract、z、 colored-man-pages、zsh-autosuggestions、zsh-syntax-highlighting
• Miniconda: Python环境管理
• GPU 监控工具: nvitop 和 gpustat
• Codex CLI: OpenAI Codex 命令行工具
• Claude Code: Anthropic Claude Code 命令行工具
• CC Switch CLI: Claude/Codex 等工具的供应商切换命令行工具
• 国内镜像动态选择: 安装 GitHub 工具时实时读取镜像状态；Docker 镜像可单独动态配置
• 优化配置: 包括shell配置和PATH设置

🏗️ 脚本架构

主脚本

• setup.sh - 主入口脚本，内置一份步骤注册表（id / 说明 / 对应脚本），支持全量执行、 --only/--skip 部分执行、--interactive 交互菜单、--list/--dry-run 预览

子脚本目录 (scripts/)

用户级配置脚本

• install_chsrc.sh - 安装 chsrc 源切换工具
• install_ohmyzsh.sh - 安装 Oh My Zsh 并维护常用插件列表
• install_miniconda.sh - 按系统/架构安装 Miniconda Python 环境
• configure_conda_source.sh - 配置 Conda 源为清华大学镜像
• install_gpu_tools.sh - 安装 GPU 监控工具
• install_codex.sh - 安装 OpenAI Codex CLI
• install_claude.sh - 安装 Claude Code
• install_claude_github.sh - Claude Code GitHub Releases 安装器（支持 FORCE=1 强制重装， 已是目标版本时自动跳过下载）
• install_cc_switch.sh - 安装 CC Switch CLI
• finalize_setup.sh - 完成设置（更改默认 shell 等）
• mirror_common.sh - 实时读取 GitHub/Docker 镜像检测接口的共享函数
• configure_docker_mirrors.sh - 动态选择并验证 Docker 镜像，写入用户级 daemon 配置

Agent 接入 (.claude/skills/, AGENTS.md)

• .claude/skills/easy-init/SKILL.md - Claude Code 项目 Skill，供 claude 在本仓库内自动发现
• AGENTS.md - 面向 Codex CLI 及其他支持 AGENTS.md 约定的 agent 的仓库级说明

🚀 使用方法

用户环境配置

# 进入脚本目录
cd easy-init

# 给所有脚本添加执行权限
chmod +x setup.sh
chmod +x scripts/*.sh

# 运行用户环境配置
./setup.sh

单独运行某个步骤

# 例如，只运行 chsrc 安装
./scripts/install_chsrc.sh

# 例如，只运行Oh My Zsh安装
./scripts/install_ohmyzsh.sh

# 例如，只运行Miniconda安装
./scripts/install_miniconda.sh

# 例如，只安装 Codex CLI
./scripts/install_codex.sh

# 例如，只安装 Claude Code
./scripts/install_claude.sh

# 例如，只安装 CC Switch CLI
./scripts/install_cc_switch.sh

通过 setup.sh 参数选择部分步骤

setup.sh 内置了一份步骤注册表（id: chsrc ohmyzsh miniconda condasource gputools codex claude ccswitch finalize），除了逐个运行子脚本，也可以用参数选择子集：

./setup.sh --list                          # 列出所有步骤 id 及说明
./setup.sh --interactive                   # 交互式菜单，输入编号选择要执行的步骤
./setup.sh --only codex,claude             # 只执行指定步骤
./setup.sh --skip ohmyzsh,miniconda        # 执行除指定步骤外的全部步骤
./setup.sh --dry-run --only codex,claude   # 预览将要执行的步骤，不实际运行

动态配置 Docker 镜像

GitHub 相关安装脚本（Codex、Claude Code、CC Switch）在未显式设置 GH_PROXY 时，会在每次运行时 读取镜像检测接口并选择当前可用的镜像；接口不可用时才回退到 gh-proxy.com。

Docker 镜像配置需要显式执行，默认写入 rootless Docker 的用户级配置，不会修改 /etc/docker：

bash scripts/configure_docker_mirrors.sh

脚本会实时读取 Docker 镜像列表，并用 alpine manifest 二次验证后再写入 ~/.config/docker/daemon.json；已有配置会备份为 .easy-init.bak。可通过以下变量调整：

MIRROR_DAYS=30 bash scripts/configure_docker_mirrors.sh
DOCKER_DAEMON_CONFIG="$HOME/.config/docker/daemon.json" bash scripts/configure_docker_mirrors.sh

🤖 作为 Skill / Agent 使用

本仓库内置了 Claude Code Skill 与 Codex/通用 agent 的说明文件，clone 到目标机器后可以直接让 agent 帮你跑，不用自己记参数：

• Claude Code: 在仓库根目录运行 claude，Claude 会自动发现 .claude/skills/easy-init/SKILL.md 这个项目 Skill。 跟它说"帮我初始化开发环境"之类的话，它会用交互式提问（多选）确认你要装哪些组件， 然后调用 setup.sh --only ... 执行。
• Codex CLI（或其他遵循 AGENTS.md 约定的 agent）: 在仓库根目录运行 codex，它会读取根目录的 AGENTS.md，按同样的方式先询问再执行。

两者都只是在对话里帮你拼好 setup.sh 的参数并执行，遇到 finalize 步骤的 chsh 密码提示、 或修改 ~/.zshrc/~/.condarc 之类的动作时会提前告知你。如果你更喜欢完全手动控制，直接用上面的 命令行参数或 --interactive 菜单即可，不需要 agent 参与。

🚀 配置流程

用户环境配置流程

第1步: 工具准备

• chsrc 安装: 安装源切换工具到 ~/.local/bin

第2步: 终端美化

• Oh My Zsh 安装: 从Gitee镜像安装，避免网络问题
• 插件配置: 维护 git、docker、kubectl、sudo、extract、z、colored-man-pages，并安装 zsh-autosuggestions、zsh-syntax-highlighting

第3步: Python 环境

• Miniconda 安装: 根据 Linux/macOS 和 CPU 架构选择安装包，安装到用户目录
• 初始化配置: 自动配置Zsh集成

第4步: 源优化

• Conda 源配置: 配置清华大学镜像，写入前自动备份已有配置
• 缓存策略: 默认不清理 Conda 缓存，避免误删离线包；需要时设置 CLEAN_CONDA_CACHE=1

第5步: GPU 工具

• GPU 监控工具安装: 在 Miniconda base 环境中安装 nvitop 和 gpustat

第6步: AI 编程工具

• Codex CLI 安装: 使用 OpenAI 官方 standalone installer
• Claude Code 安装: 使用 GitHub Releases 安装脚本，支持 CLAUDE_VERSION=版本号 指定版本，运行时动态选择 GitHub 镜像
• CC Switch CLI 安装: 下载 SaladDay/cc-switch-cli 对应平台的 tarball 到用户目录，运行时动态选择 GitHub 镜像

第7步: 最终配置

• Shell 设置: 设置 Zsh 为默认 shell
• PATH 优化: 添加 ~/.local/bin 到环境变量
• 当前终端: 默认不强制替换当前 shell；需要立即进入 Zsh 时设置 EXEC_ZSH=1

自定义修改

由于脚本被拆分为多个子脚本，您可以轻松修改特定步骤：

• 修改chsrc配置: 编辑 install_chsrc.sh 更改安装方式
• 自定义Oh My Zsh: 编辑 install_ohmyzsh.sh 添加更多插件或主题
• 调整Miniconda: 修改 install_miniconda.sh 更改版本或安装位置
• 更改Conda配置: 修改 configure_conda_source.sh 中的源配置
• 调整AI工具安装: 修改 install_codex.sh、install_claude.sh 或 install_cc_switch.sh
• 调整Shell配置: 编辑 finalize_setup.sh 中的配置
• 跳过/只执行部分步骤: 用 ./setup.sh --skip <id列表> 或 ./setup.sh --only <id列表>， 无需修改脚本本身（步骤 id 见 ./setup.sh --list）
• 调整 Skill / Agent 行为: 编辑 .claude/skills/easy-init/SKILL.md（Claude Code）或 AGENTS.md（Codex CLI 等）

常用环境变量

# 指定 Miniconda 安装目录和版本；默认使用清华镜像的 latest 包
CONDA_DIR="$HOME/miniconda3" MINICONDA_VERSION=latest ./scripts/install_miniconda.sh

# 允许清理 Conda 缓存
CLEAN_CONDA_CACHE=1 ./scripts/configure_conda_source.sh

# 跳过 chsh，适合自动化或无密码交互环境
SKIP_CHSH=1 ./scripts/finalize_setup.sh

# 手动固定 GitHub 镜像；不设置时由检测接口实时选择
GH_PROXY=https://ghproxy.net/ ./scripts/install_claude.sh

🐛 故障排除

常见问题

网络连接问题:

# 如果下载失败，检查网络连接
curl -I https://gitee.com
curl -I https://mirrors.tuna.tsinghua.edu.cn
curl -I https://chatgpt.com/codex/install.sh
curl -I https://github.com/SaladDay/cc-switch-cli/releases/latest

权限问题:

• 脚本不需要sudo权限
• 如果提示权限不足，检查是否在用户主目录下运行

Shell配置问题:

# 如果shell没有切换成功，手动执行
chsh -s $(which zsh) $USER

Conda环境问题:

# 如果Conda没有正确初始化，重新初始化
~/miniconda3/bin/conda init zsh

调试方法

如果某个步骤失败：

1. 查看具体的错误信息
2. 可以单独运行失败的子脚本进行调试
3. 检查网络连接和磁盘空间
4. 使用 ./setup.sh --help 查看帮助信息

重置方法

如果需要完全重新开始：

# 删除相关目录和配置
rm -rf ~/.oh-my-zsh
rm -rf ~/miniconda3
rm -f ~/.condarc ~/miniconda3/.condarc
rm -f ~/.zshrc.easy-init.bak ~/miniconda3/.condarc.easy-init.bak
rm -f ~/.local/bin/chsrc
rm -f ~/.local/bin/codex
rm -f ~/.local/bin/claude
rm -f ~/.local/bin/cc-switch
rm -rf ~/.local/opt/cc-switch-cli

# 重新运行配置脚本
./setup.sh