Superset Doctor 是 Superset 的故障诊断与修复技能，适用于用户报告连接失败、主机离线、终端无法附着、认证或更新等问题时使用。
用途与原则：先诊断、再动手。先收集信息，再匹配已知问题；每次只改一处，改完立即验证。所有会改变状态的命令，都要先给出建议并取得用户同意后才执行；不得把删除数据当作修复手段。
第一步：快照（只读，可并行执行，容忍单条失败）
- superset status：查看主机服务健康状况
- superset auth whoami：查看认证状态与当前组织
- superset hosts list：查看主机可达性
- superset --version：查看版本
第二步：匹配已知特征与对应修复
- whoami 失败 / 会话过期：执行 superset auth login
- 主机显示离线：执行 superset hosts wake <id>，并确认机器已唤醒且在线
- 主机服务未运行：执行 superset start
- 通过 superset hosts add 添加的主机离线或损坏：重新运行 superset hosts add <ssh-target>，它会逐项检查并只修复有问题的地方；在 Linux 上其日志可用 ssh <ssh-target> journalctl --user -u superset-host -n 50 查看
- hosts add 无法连接或无法完成设置：先确认本机可执行 ssh <ssh-target>，远端为 macOS 或 glibc Linux（x64 或 arm64，不支持 Alpine 与 Windows），且已安装 curl
- hosts add 添加的主机无法克隆私有仓库：在该主机登录 GitHub，执行 ssh -t <ssh-target> gh auth login（缺少 gh 需先安装）
- Linux 主机在用户登出后停止：在该机器上启用 lingering，执行 loginctl enable-linger
- hosts add 因 /etc/machine-id 为空或无效（克隆的虚拟机或容器镜像）而中断：在该机器上执行 sudo rm -f /etc/machine-id && sudo systemd-machine-id-setup，然后重新运行 hosts add；该命令需要在本机使用 sudo，由用户自行执行
- 在 Superset 终端中执行 superset pages publish 报“Not a member of organization”：执行 superset update；较新的 CLI 在其终端内使用桌面应用的账号
- CLI 与桌面应用版本不一致或 CLI 过期：执行 superset update
- 应用端异常（macOS）：查看 ~/Library/Logs/Superset/main.log 中最新条目里的错误
第三步：验证。重新执行最初失败的操作；若成功，明确说明问题原因与生效的修复。
第四步：带证据升级处理。若仍未解决，可提出用 feedback 技能提交问题，并附上已收集的诊断信息（版本、status 输出、相关日志片段），使报告到达时已完成初步分诊。日志可能包含路径与项目名称，加入任何日志内容前须先征得用户同意。
适用场景：Superset CLI 与桌面应用日常排障、新增远程主机后的连通性排查、认证与版本类问题定位。
限制：资料未提供支持的平台完整清单（仅提及远端需 macOS 或 glibc Linux，不支持 Alpine 与 Windows）、命令参数细节及权限要求以外的更多说明；本介绍不构成对功能范围的新增承诺。