故障排查
先运行 shine --version 记录版本，再使用 shine list、shine info <TARGET> 或对应命令的 --dry-run 收集状态。
安装后找不到命令
Shell 预设的命令入口位于 ~/.shine/bin/。安装完成后需要打开新终端，或重新加载 shell profile：
source ~/.zshrc
# 或 source ~/.bashrc
然后检查：
shine list
shine info shell/proxy
命令入口缺失时，先用 shine info shell/<CATEGORY> 检查详情。确认本地修改后，执行
shine shell install <CATEGORY> --replace-managed 重建受管文件和命令入口。
应用配置显示为用户修改
Shine 默认保留安装后被修改过的文件。先查看差异：
shine info app/starship --diff
需要采用预设版本时运行 shine app install starship --replace-managed。卸载时，只有明确要删除这些本地修改才使用 shine app uninstall starship --force；先运行相同命令并加上 --dry-run。
使用的不是预期预设
外部目录、项目配置和环境变量可能改变当前来源。检查命令输出中的 Preset Source 与
Presets Overlay，并按配置参考核对优先级。
如果只想检查账户配置，请先切换到没有 shine.config.toml 的项目之外，再查看来源。
SHINE_CONFIG_DIR 只切换账户配置与状态目录，不会关闭当前项目配置的查找。
修改 env 后配置没有变化
shine env set 更新变量，但已安装模板不会自动重写。运行：
| 操作 | 命令 |
|---|---|
| 详细检查待更新内容 | shine update --verbose |
| 更新配置并显示详细输出 | shine upgrade --verbose |
如果使用项目 shine.config.toml、项目 shine.env.toml 或 overlay，请确认当前工作目录和覆盖优先级。
如果问题表现为私有域名或 192.168.x.x 地址仍然被终端代理接管，可继续参考知识库中的
终端代理误拦截 ZeroTier 私有域名的排查与修复。
升级到 0.40 后提示旧配置文件
项目中的 config.toml 和 .env.toml 已不再作为 Shine 配置读取，请分别改名为 shine.config.toml 和 shine.env.toml。
若提示检测到全局 ~/.shine/env.toml，不要直接删除仍在使用的值。将它移动为 ~/.shine/shine.env.toml；若新文件已经存在，先手动合并并检查重复键。也可以在升级前先用 v0.39 运行一次配置加载，让旧版本完成自动迁移。
生成式 App 文件刷新失败
先确认类别已经安装、选择器使用 [[files]].source 的相对路径，并满足 generator 的 env 前提：
shine app info surge
shine env list
shine app refresh surge subscription-proxies.conf
按以下顺序检查：
- 安装 Bun，并确认
SURGE_SUBSCRIPTION_URL或W_GET_CLOUD_SURGE_SUBSCRIPTION_URL为 HTTPS 订阅地址。 - 如果报错为 HTTP 状态、超时、响应过大或无兼容节点，检查订阅服务。服务商返回完整 Surge 托管配置时，请改用通用 URI/Base64 订阅地址；Shine 不会从完整配置中截取代理部分。
- 如果目标文件已被修改，先查看差异；只有确定要覆盖本地修改时才加
--force。
刷新失败会保留上次成功生成的文件。日常 shine update 和 shine upgrade 不会刷新这类手动订阅，
需要显式运行 shine app refresh。报错会隐去订阅 URL、响应正文和节点内容；提交问题时仍请检查
输出，避免附上秘密。
shine preset pull 拒绝更新来源
先区分来源类型：通过 shine preset overlay link --git 创建的覆盖层是 Shine 管理的镜像，
拉取时会丢弃镜像内的本地修改和额外文件。请在上游仓库修改，不要直接编辑本机镜像；
详见Git 覆盖层。
对于自己维护的外部来源或手动链接的覆盖层，shine preset pull 只对干净、已设置 upstream
的普通分支执行快进更新。进入错误信息显示的仓库并检查：
git status
git branch --show-current
git branch -vv
git pull --ff-only
请自行提交、stash 或处理本地改动和分支分歧，再重新运行 shine preset pull。对于这些手动维护的来源，Shine 不会自动丢弃改动或解决冲突。若提示找不到 Git，请先安装 Git 并确认 git 在 PATH 中；非 Git 预设目录被跳过属于正常行为。
系统初始化前想确认影响
shine sys info <ITEM>
shine sys bootstrap --dry-run
shine sys uninstall <ITEM> --dry-run
使用 shine sys list 和 shine sys info 确认当前版本提供的项目及安装要求。
若旧版本在 shell profile 中留下冲突标记，请先手动处理，再运行
shine sys bootstrap --dry-run 或对应的 upgrade。
任务运行结果和手动执行不同
保存的任务需要管道、重定向、变量展开或通配符时，请显式调用 Shell：
shine task save kill-port -- sh -c 'lsof -ti :3000 | xargs kill'
额外参数会追加到已保存命令末尾：
shine task run my-task -- --verbose
SSH 文件传输不可用
shine local 只能在 shine ssh 打开的远端 shell 中使用。若提示缺少 SHINE_SSH_SESSION、SHINE_SSH_TOKEN 或 SHINE_SSH_REMOTE_SOCK，请退出后重新用 shine ssh <HOST> 进入。
远端也需要能运行兼容的 shine local。先检查：
shine local status
which shine
shine --version
传输前优先预览路径和覆盖行为：
shine local download ./remote.log ./remote.log --dry-run
shine local upload ./local.log /tmp/local.log --dry-run
使用 rsync 时默认跳过已有文件，添加 --force 后才允许覆盖；目录目标已存在时，--force 表示合并写入。
SCP（包括自动回退）即使不带 --force 也可能覆盖文件。传输前请预览路径，并备份目标中需要保留的文件。
没有显示维护提醒
对于需要手动处理的维护提醒，可运行 shine state check。系统服务检查通常在后台完成，并在
后续交互调用时显示结果；重定向或自动化命令会跳过自动维护检查。若检查无法完成，请确认当前
用户能够访问系统服务管理器后重试。清理旧 HTTP 服务使用 shine clear serve。
自动更新检查失败
网络或 GitHub API 不可用时，Shine 会跳过版本检查并继续执行原命令。恢复网络后可绕过 24 小时缓存重新检查：
shine update --refresh-release