用途：把 Dynamo 部署的失败转化为清晰的问题分类、最强信号与下一步操作。强调从只读证据入手，避免接触机密，一次只修复一层。
前置条件：操作机需 Python 3.10+；kubectl 已配置且对目标命名空间有读权限；可读取 pods、events、jobs、PVCs 和 DynamoGraphDeployment 资源（不读取 secrets）；能访问集群 API server。
使用方法：
- 收集只读调试包：
python3 scripts/collect_dynamo_debug_bundle.py
--namespace "${NAMESPACE}"
若指定部署，可加 --deployment-name <deployment-name>。不要收集 Kubernetes secrets，不要打印 Hugging Face token。
-
用 references/failure-decision-tree.md 将故障归类为以下主桶之一：集群/平台、命名空间/secret、模型缓存/PVC/下载、镜像拉取/运行时镜像、GPU 调度/资源、operator/DynamoGraphDeployment 协调、前端/路由器、worker/后端、endpoint/API、benchmark/性能任务。
-
自上而下排查：命名空间、存储类、GPU 节点、HF secret 是否存在；PVC 与模型下载任务；DynamoGraphDeployment 状态与事件；pod 状态、describe 与容器日志；前端服务与端口转发；再依次验证 /v1/models 与 /v1/chat/completions；endpoint 冒烟测试通过后才做 benchmark。
-
一次修复一层，优先最小可逆改动：创建缺失的命名空间或 HF secret；patch storageClassName；patch 镜像 tag 或 image pull secret；仅在 recipe 仍有效时降低 GPU 请求；仅当 workers 不发布事件时把 KV router 切到 approximate 模式；修复底层配置后重启失败任务。每次修复后先重跑相关就绪检查再深入。
脚本：scripts/collect_dynamo_debug_bundle.py 用于收集只读调试包（pods、events、jobs、PVCs、CR 状态），参数 --namespace、--deployment-name、--output-dir。也可通过 agentskills.io 的 run_script() 协议调用，例如 run_script("scripts/collect_dynamo_debug_bundle.py", args=["--namespace", "dynamo-demo"])。
输出约定：返回问题分类、已检查证据、最强信号、可能原因、确切的下一步命令或 patch、已排除项、以及是否可安全继续部署或 benchmark。
限制：只读，绝不修改集群，修复命令只返回不执行；不收集 secrets；大型命名空间建议用 --deployment-name 缩小范围；不验证 disaggregated transport，需配合 dynamo-interconnect-check；若 auth 类故障可能需用户自行检查。
常见排查：kubectl 对 events/pods 返回 Forbidden 通常是 service account 缺少读 RBAC；缺少 DynamoGraphDeployment 状态可能是 operator 未安装或命名空间不匹配；模型下载任务 Pending 多为 PVC 未绑定或 HF secret 缺失；worker pods CrashLoopBackOff 多为镜像/运行时不一致或 GPU 不可用。