用途：当用户在基于 Replicated 的 VM 自托管 OpenHands Enterprise（OHE）上报告问题时，用该技能做分诊、引导恢复、生成支持包与升级交接。
诊断流程：先收集症状（现象、报错信息、起始时间），再匹配到常见故障模式，运行 references/diagnostics.md 中的定向命令，逐一执行恢复步骤，最后验证原始症状消失（而非仅上一条命令成功）。恢复一次只走一步：执行前说明会改变什么、预期看到什么，执行后先跑验证再继续；若验证失败或出现异常，停下来重新诊断，避免在失败步骤上叠加操作而掩盖证据。重启、回滚、改配置等破坏性步骤需先取得用户同意并记录，以便交接时说明改过什么。
常见故障模式：1）沙箱启动失败或超时，报 Sandbox failed to start，需查沙箱服务状态、sysbox-runc RuntimeClass 及其 containerd runtime、资源；注意 runtime-api 的超时可配置且与 Kubernetes 客户端和应用中不同，不要套用固定值。2）Git 提供商认证失败，无法克隆/推送。GitHub、GitLab、Bitbucket Data Center、Azure DevOps 分别配置，需先确认用户实际使用哪一家。3）证书错误：过期或自签名、TLS 握手失败、浏览器不安全警告，查有效期、证书链、ingress。4）LLM 连通失败：端点不可达、API 认证失败、会话无法启动，查端点 URL、API key secret、网络策略。5）Keycloak 登录问题：管理台进不去、登录循环、pod 报错，查 pod 状态、数据库连通、realm 配置。6）Replicated 管理台不可达，查 operator pod、ingress、service endpoint。7）升级卡住或失败：状态 failed、pod crash loop、迁移任务失败，查失败 job 日志、资源、pre-flight。8）OOM/资源耗尽：OOMKilled、Too many open files、服务无响应，查内存、磁盘、文件描述符。
常用命令（在 VM 上运行）：kubectl get deploy,statefulset -n openhands 看 READY（空 pod 列表不等于健康）；kubectl get pods -n openhands；kubectl logs -n openhands POD_NAME（可加 --previous）；kubectl describe pod -n openhands POD_NAME；kubectl top nodes、kubectl top pods -n openhands；echo | openssl s_client -connect HOST:443 2>/dev/null | openssl x509 -noout -dates；Replicated 组件在 Embedded Cluster 下为 kotsadm、embedded-cluster 与 openhands 中 app.kubernetes.io/name=replicated，已无 replicated 命名空间（属旧 kURL 拓扑）。
支持包：SSH 到 VM，在安装程序目录执行 sudo ./openhands support-bundle（需在 controller 节点，否则无法采集集群级信息）；Embedded Cluster 1.17.0 之前改用 sudo ./openhands shell 后执行 kubectl support-bundle --load-cluster-specs /var/lib/embedded-cluster/support/host-support-bundle.yaml。产物为 support-bundle-<UTC 时间戳>.tar.gz。支持包含敏感数据，redactor 以 HIDDEN 遮蔽常见密钥但不保证彻底，应视为机密，仅通过 OpenHands 团队给的渠道发送。
支持包分析：先解压，可运行 python3 scripts/bundle_triage.py <bundle 目录> 做首轮分诊（仅标准库；它只读 pod 对象、分析器结论、节点状况与资源总量，不读应用日志）。关键查看位置：analysis.json（预计算结论）、cluster-resources/pods/<namespace>.json、cluster-resources/pods/logs/<ns>/<pod>/<container>.log、kots/admin_console/app-info.json。四个坑：不要用文件 mtime 计时（取目录名的 UTC 采集时间）；日志文件名是容器名而非 pod 名，init 容器（migrate-db、wait-for-db）失败对 kubectl logs <pod> 不可见；HIDDEN 表示被遮蔽而非未设置；过滤前先看格式，多数日志是纯文本，直接 jq 会在首行非 JSON 处中止，可先 grep '^{'。
根因判断顺序：从症状与时间线出发，先读 analysis.json（非通过项都归入 FAIL，含 warn，需核对 severity；按族合并，[x12] 表示 12 个对象受影响，引用前直接打开文件）；按解释症状的直接程度排序（CrashLoopBackOff/正在 OOM > 从未启动的 Pending、CreateContainerConfigError、未完成的 init 容器 > Running 但 Not Ready > 节点状况 > 资源压力）；优先最接近症状的原因；说明排除了什么。结论要给出证据、来源对象或分析器及置信度，给出两三个候选排序比单一确定猜测更有用。
升级交接：未解决时按模板汇总问题、时长、影响、观察到症状、已做步骤、日志证据、尝试及结果、可能根因。
其他资源：references/diagnostics.md（各故障模式命令与日志解读）、references/support-bundle-analysis.md（离线读包、文件地图、解读陷阱与已知缺口）、scripts/bundle_triage.py（离线首轮分诊）。
维护：现场发现新故障模式时补充到本技能，更新 references/diagnostics.md 的模式与恢复步骤，并在可从支持包诊断时同步到 references/support-bundle-analysis.md。