doctor

用途

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 查看日志
  • 私有仓库无法克隆：在目标主机执行 ssh -t <ssh-target> gh auth login
  • Linux 主机在用户登出后停止：执行 loginctl enable-linger
  • 因空的或无效的 /etc/machine-id 导致 hosts add 中断：先执行 sudo rm -f /etc/machine-id && sudo systemd-machine-id-setup 再重跑
  • 终端内发布页面提示不在组织中：superset update
  • CLI 与桌面应用版本不一致或 CLI 过期：superset update
  • macOS 应用异常：查看 ~/Library/Logs/Superset/main.log 最新条目
• 修复后验证：重新执行最初失败的操作；成功后说明问题原因与修复方式。
• 无法解决时，可借助反馈技能提交报告，并携带已收集的诊断信息（版本、状态输出、相关日志片段），提交前会征求是否包含日志内容。

使用方式

1. 先做只读快照诊断。
2. 对照已知特征提出修复方案，涉及改变状态的操作需用户同意后再执行。
3. 一次只改一处，改后验证。
4. 未解决则带证据上报。

适用场景

使用 Superset 命令行管理远程开发主机的开发者或运维人员，在遇到连接、认证、主机唤醒、服务启动、版本更新等故障时使用。

限制

• 该技能不将删除数据作为修复手段。
• hosts add 要求远程为 macOS 或 glibc Linux（x64 或 arm64），不支持 Alpine 与 Windows，且需要 curl。
• 涉及 sudo 的操作（如修复 /etc/machine-id）需由用户在其机器上执行。
• 日志可能包含路径和项目名称，提交前需征得用户同意。