update / doctor / skills

update — CLI 自更新

命令	功能
supsub update	检查并更新到最新版本，并顺带同步本地 skills
supsub update --check	只检查是否有新版本，输出 current / latest / hasUpdate，不实际更新（不动 skills）
supsub update --force	即使已是最新也重新下载安装（修复损坏的 binary），并重新同步 skills
supsub update --skip-skills	本次更新不同步本地 skills
supsub update --rollback	回滚到上一个留存版本（仅 native 安装，重指 symlink，不重新下载）

说明：

• 更新完成后，下次运行即是新版本。
• native 安装：新版本下载到 ~/.local/share/supsub/versions/<版本>/ 并原子切换 symlink，旧版本保留最近 3 个可回滚，装在用户目录不需要 sudo。
• npm 安装：原地替换 binary；若全局目录无写权限（如需 sudo 的路径），会以退出码 1 报错并提示改用 npm i -g @supsub/cli@latest 或加 sudo 重试。
• manual（手装）安装：doctor 报 manual 的独立二进制（多为 0.4.0 之前 curl … | bash 装下的普通文件）。若它正好位于 native 的 symlink 位（默认 ~/.local/bin/supsub），只需跑一次 supsub update 就会自动迁移到 native 布局：下载到 versions/ 后用 symlink 原子替换那个普通文件，一次收敛，此后拥有版本并存、回滚与后台自动更新（下次启动生效）。即使当前已是最新版本也会迁移，无需 --force（此时输出如实说明「已是最新，且已迁移到 native 布局」——JSON 里 updated=false、migrated=true，两者含义独立）。手动 cp 到别处（如 /usr/local/bin）的独立二进制维持原地覆盖，不迁移；npm 包（node_modules 内）也一律不迁移。
• 更新过程只访问 registry.npmjs.org 与 github.com，不读取 / 不发送任何凭证。

native 安装会后台静默自动更新

native 安装（curl … | bash）会在后台定期检查并升级，新版本下次启动才生效，不打断当前命令。-o json 与 CI 环境下永不自动更新；设 SUPSUB_DISABLE_AUTOUPDATER=1 可完全关闭后台检查。npm 安装保持手动更新（supsub update 或 npm i -g @supsub/cli@latest）。

可在 ~/.supsub/config.json 配置 autoUpdateChannel（latest 默认 / stable 只自动升 patch）与 minimumVersion（自动更新不会低于此版本）。

doctor — 安装 / 更新自检

supsub doctor          # 人类可读表格
supsub doctor -o json  # 供 agent / 脚本解析

输出：当前版本与真实路径、安装方式（native / npm / manual / dev）、symlink 指向哪个版本、本地留存的版本列表、上次后台更新检查的时间与结果（含失败原因）、~/.local/bin 是否在 PATH、以及本地 skills 同步状态。静默自动更新出问题时，这里是第一查证入口。

安装方式档位：native（~/.local 版本并存 + symlink，自动更新）；npm（包管理器全局目录，手动更新）；manual（手装独立二进制——若在 native symlink 位，下次 supsub update 会自动迁到 native）；dev（bun 跑源码）。

skills — Agent Skills 同步

命令	功能
supsub skills sync	用 npx skills add 把仓库 skills 同步到本地 agent 配置，默认仅装到当前项目 ./.agents/skills，成功后记录同步版本
supsub skills sync --global	改装到全局 ~/.claude/skills（对所有项目可见；全局侵入性强，需显式指定）
supsub skills sync --force	即使本地已是当前版本也重新同步
supsub skills status	查看本地 skills 版本 vs 当前 CLI 版本、是否漂移
supsub skills list	列出仓库提供的 skills

说明：

• CLI 自更新只换二进制，本地 skills 不会自动跟着升级。
• 检测到本地 skills 落后于当前 CLI 版本时，在 stderr 提示运行 supsub skills sync（skills / update / --help 等命令不重复打扰）。
• 从未通过 supsub 同步过、CI 环境、以及 SUPSUB_NO_SKILLS_NOTIFIER 为真值时不提示。

完整说明见升级与 Skills 同步。