uclash - mihomo(Clash) 代理管理工具 使用教程
================================================

uclash 在 Ubuntu 上管理 mihomo(Clash) 内核与系统代理：一条命令开关代理、
切换节点、管理订阅、下载/升级内核，并支持自身更新。

依赖：bash、systemctl、curl（或 wget）、python3。
安装/卸载脚本可在 Bash、Zsh 中执行；uclash 本体以 Bash 运行。


一、安装
--------

1) 在线安装（推荐）

   curl -fsSL https://files.tymler.work/clash/ubuntu-clash/unix/install.sh | bash
   curl -fsSL https://files.tymler.work/clash/ubuntu-clash/unix/install.sh | zsh

2) 常用选项

   ... | bash -s -- --prefix "$HOME/.local"   指定安装前缀（命令进 DIR/bin）
   ... | bash -s -- --shell bash|zsh|both     指定要配置的 shell（默认 auto）
   ... | bash -s -- --reinstall               完全重装（先清理旧版本）
   ... | bash -s -- --insecure                跳过 TLS 校验（自签/私有 CA）

   自签证书环境引导下载也要跳过校验：
   curl -kfsSL https://files.tymler.work/clash/ubuntu-clash/unix/install.sh | bash -s -- --insecure

3) 离线安装

   wget https://files.tymler.work/clash/ubuntu-clash/unix/uclash-unix.tar.gz
   tar -xzf uclash-unix.tar.gz
   ./uclash-unix/install.sh

   校验归档（可选）：
   curl -fsSLO https://files.tymler.work/clash/ubuntu-clash/unix/uclash-unix.tar.gz.sha256
   sha256sum -c uclash-unix.tar.gz.sha256

安装完成后执行 source ~/.bashrc、source ~/.zshrc 或重开终端生效。


二、配置文件
------------

配置文件路径：~/.config/uclash/config（UCLASH_CONFIG_FILE 可覆盖）
语法：KEY=VALUE，每行一个，# 开头为注释。安装时生成，更新不会覆盖。

  # 默认代理组；留空则自动识别（优先 Proxy 的 select 组）
  CLASH_DEFAULT_GROUP=

  # 下载/更新基地址；下载根为其后的 ubuntu-clash/unix/
  update_base_url=https://files.tymler.work/clash

组名解析优先级：命令行参数 > CLASH_DEFAULT_GROUP 环境变量 > 配置文件 > 自动识别。


三、常用命令
------------

  uclash on                     启动 mihomo 并设置系统代理
  uclash off                    解除系统代理并停止 mihomo
  uclash status                 查看服务、代理与节点状态
  uclash node groups            列出代理组及编号
  uclash node list [组|编号]    列出节点
  uclash node use <节点|编号>   切换节点
  uclash doctor                 校验内核版本兼容性
  uclash core install [版本]    下载并安装 mihomo 内核
  uclash core list              列出可安装的内核版本
  uclash core version           查看当前内核版本
  uclash sub add <URL>          新增订阅
  uclash sub list               列出订阅
  uclash sub update [名称]      重新拉取订阅
  uclash sub status [名称]      查看订阅状态
  uclash sub nodes <名称>       列出订阅节点
  uclash version                查看 uclash 版本
  uclash update                 更新 uclash 本体
  uclash help                   查看帮助


四、更新
--------

  uclash update                 检查并更新到最新版本
  uclash update --check         只检查，不下载不安装
  uclash update --dry-run       只显示更新计划
  uclash update -y              跳过确认（非交互环境必须）
  uclash update --force         允许降级或同版本重装
  uclash update --base-url URL  覆盖基地址
  uclash update --insecure      跳过 TLS 校验

更新流程：拉取更新清单 -> 展示更新日期与更新说明 -> 下载带版本号的归档 ->
sha256 校验 -> 解压并复用安装脚本整包更新 -> 清理旧版本废弃文件。

更新源：<update_base_url>/ubuntu-clash/unix/
地址优先级：--base-url > UCLASH_BASE_URL > 配置文件 update_base_url >
构建期内嵌地址 > 状态文件 ~/.local/share/uclash/base_url。


五、卸载
--------

  curl -fsSL https://files.tymler.work/clash/ubuntu-clash/unix/uninstall.sh | bash
  curl -fsSL https://files.tymler.work/clash/ubuntu-clash/unix/uninstall.sh | zsh

或使用离线包中的 uninstall.sh。卸载会移除命令、补全、shell 注入段、
版本/清单状态与用户配置；不会删除 mihomo 内核与 mihomo 配置。


六、常见问题
------------

- 命令找不到：确认 ~/.local/bin 在 PATH 中，或重开终端。
- 补全不生效：Bash 需系统启用 bash-completion；Zsh 需 ~/.zfunc 在 fpath 中。
- 内核版本不兼容：uclash doctor 查看，必要时 uclash core install 升级内核。
- 证书校验失败：确认系统的 CA 配置，或临时使用 --insecure（有风险）。
- 更新失败：更新过程任一步失败都会中止且不替换现有安装；按提示排查网络、
  校验或权限问题后重试。