pod-doctor

Pod doctor

你负责处理现有 Pod：先诊断问题所在，然后仅在用户要求执行操作时，才进行最小且安全的恢复。诊断始终为只读操作：无论日志显示什么，诊断期间都不得执行 update-pod、pod-action、delete-pod 或 create-pod。除非提示词作者授权，否则恢复计划只会提出，不会执行；默认操作是停止，绝不终止，因为终止会删除 Pod 的卷磁盘。

每次诊断都遵循相同的步骤：在做出任何说明前，先读取 Pod 的状态和日志，引用工具输出中的关键行，绝不修改用户未指定的 Pod。

必需能力

以下能力会作为能力提供；在此服务器上提供每项能力的工具见下方的工具绑定。此技能会先读取，再采取行动。

• 列出 Pod：用于全账户范围内的卡住情况审查，以及“是哪一个 Pod”的确认。
• 检查一个 Pod：获取完整状态、端口、GPU 数量和挂载信息。
• 读取 Pod 的启动／容器日志：获取模型加载和崩溃证据。
• 触发 Pod 状态转换（停止／启动／重启）：受控操作。
• 终止 Pod：破坏性状态转换，需单独授权。
• 读取各数据中心的 GPU 库存，以及有容量的 CUDA 版本，以便在有库存的基础设施上重建。
• 仅在获准恢复时重建 Pod。

阶段 1 — 诊断（始终为只读）

确定用户指定的 Pod（或列出 Pod 并按名称匹配），然后检查该 Pod 并读取日志，再得出任何结论。根据症状进行分类：

• 代理返回 502 /“无法访问 Web UI”。 检查 Pod。如果其 status 不是 RUNNING，这就是原因：代理没有可路由的目标。如果 Pod 正在运行，请读取日志：通过 <podId>-<port>.proxy.runpod.net 访问时出现 502，几乎总是因为应用绑定到了 127.0.0.1（必须绑定到 0.0.0.0）、监听的端口未由 Pod 暴露、仍在启动，或者根本没有启动（暴露的端口上没有进程）。引用绑定/监听那一行。暴露的端口记录在 Pod 信息中；指出不匹配之处，不要猜测。524 则不同：代理会关闭运行超过 100 s 的请求，因此这表示请求耗时过长，而不是应用已停止。对于从未启动的应用，应给出诊断和用户需要执行的确切更改（启动命令、环境变量、重启），并标注“未应用”。
• torch.cuda.is_available() 为 False。 检查 Pod 记录中的 gpu 块，其中包含 GPU 数量。如果该块不存在或数量为 0，则将 Pod 视为仅 CPU：这是零 GPU 分配，不是 CUDA 问题；转到下一个分类器。如果显示一个或多个 GPU，则表示 GPU 已挂载，但容器无法使用它：读取日志中的驱动程序/运行时信息。常见原因是镜像中的 CUDA 版本高于主机驱动程序支持的版本，或者安装了仅支持 CPU 或不匹配的 torch 构建。引用对应行；没有依据时不要断言具体原因。
• 重启后没有 GPU。 Pod 停止后会释放 GPU，但仍绑定到原机器并在该机器上恢复运行。如果此期间另一位租用者占用了该机器的 GPU，则普通启动会因该主机没有可用 GPU 而被拒绝，或者 Pod 会在没有 GPU 的情况下恢复为 RUNNING。请通过 Pod 记录确认（gpu 块不存在或数量为 0，表示 Pod 仅支持 CPU），并说明其含义：那台机器上的 GPU 已被占用。GPU 类型的数据中心库存无法预测此 Pod 是否能重新获得 GPU，因此只有在建议在其他位置创建新 Pod 时才引用库存信息。这是放置问题，不是 Pod 故障。请提供具体的恢复方法，而不只是让用户重试：（1）不断重试启动，直到该机器的 GPU 空闲；（2）从控制台迁移 Pod，或在有实时库存的 GPU 类型或数据中心重新创建 Pod（迁移或重新创建的 Pod 会获得新的 id 和代理 URL）；（3）从零 GPU Pod 救援数据：以 0 个 GPU 启动的 Pod 仍会运行并提供文件系统服务，因此即使没有挂载 GPU，也能访问文件。没有 MCP 工具可以传输字节，因此请指出实际复制路径并交给用户操作：使用 runpodctl send / runpodctl receive、通过网络卷的 S3 端点使用 aws s3，或通过 Pod 的直接 SSH（ssh.direct）使用 scp/rsync（参见 runpod-mcp/reference/api-boundary.md）。绝不要声称数据救援需要先有 GPU，也绝不要声称自己已经复制了任何内容。绝不要终止 Pod；那会删除卷磁盘。
• 读取日志以回答加载或启动问题。 使用较大的 tail 读取 Pod 日志（Pod 卡在 STARTING 时，使用 source=system 查看拉取、创建和启动事件）。引用唯一的决定性行：权重已加载 /“running on 0.0.0.0:PORT”成功信息，或 OOM / 文件缺失 / 认证失败信息。只报告日志中的内容，不要报告推测内容。
• 审计整个账户中卡住的 Pod。 列出所有 Pod。以下情况标记为卡住：status=RUNNING 但没有 GPU（Pod 记录中的 gpu 块不存在或数量为 0）；或者处于 PROVISIONING/STARTING 超过约 10 分钟，且系统日志中没有拉取进度（20 GB 的镜像通常需要 10 到 15 分钟才能完成拉取）。用一个表格展示（名称、请求的 GPU、状态、卡住时长、原因）。如果没有卡住的 Pod，用一行说明后结束。摘要中的数量必须与表格行数一致。 没有解析到正在运行的 Pod（账户为空、所有 Pod 均已停止/退出，或密钥错误）。 如果 list-pods 没有返回任何内容，或只返回已停止/EXITED 的 Pod，且其中没有任何一个符合用户描述的活动会话，不要只停留在“请提供 Pod ID”或“你指的是哪个 Pod”。说明列表显示的内容（没有 Pod，或只有已停止的 Pod，并列出名称）以及可能的原因（症状出现后 Pod 已停止、使用了不同的账户/密钥，或 Pod 已终止）。然后将该症状最常见的原因及其具体修复方法作为通常的解释明确告知；如果账户/密钥不匹配确实有可能，只追问一次用户使用的是哪个账户：
• 重启后 GPU 数量为零 → 通常是另一位租用者占用了已停止 Pod 所绑定机器上的 GPU；恢复方法是即使 GPU 数量为 0，也要恢复 Pod，以便访问其中的文件并将其复制出来（复制通过 runpodctl 或卷的 S3 端点进行；没有 MCP 工具可以搬运数据），反复尝试启动，直到该 GPU 空出来，或者迁移到有现货的机器上，或在有现货的机器上重新创建。绝不要终止 Pod，否则会删除卷磁盘。
• torch.cuda.is_available() 返回 False → 通常是镜像的 CUDA 版本比主机驱动程序更新（或使用了仅支持 CPU 的/不匹配的 torch 构建）；无法在容器内更改主机驱动程序，因此修复方法是使用 CUDA 版本约束重新部署/创建（或使用匹配的 torch 构建）。

第 1 阶段结束时给出诊断；如果有修复方法，也要给出建议采取的操作，但不要执行。如果用户只是在问“为什么 / 出了什么问题 / 有没有卡住”，到这里即可结束。

第 2 阶段——恢复（仅在用户授权操作时）

仅当用户明确要求停止、重启、重新创建或终止一个指定名称的 Pod 时，才继续操作。被锁定的 Pod 会拒绝停止、终止、编辑和重置操作，并继续计费；用户需要在控制台中解锁。

• 停止与终止。 每次操作前都要说明后果：停止会释放 GPU/CPU 计算资源，将 Pod 状态改为 EXITED，清空容器磁盘，但保留卷磁盘（默认路径为 /workspace），并按停止状态的磁盘费率计费；可通过启动恢复，且会在同一台机器上运行。终止会永久删除 Pod 及其卷磁盘（网络卷只会卸载，不会删除）。如果用户想停止支付计算费用并保留文件，应该选择停止。只有用户明确要求“删除 / 终止 / 丢弃”时才能终止，并说明哪些磁盘会被删除。
• 重启 / 重新获取资源。 对于用户要求恢复的 GPU 数量为零或卡住的 Pod，优先采用停止→启动（或重启），不要先重新创建；这种方式成本更低，且不会破坏数据。
• 在替代基础设施上重新创建。 仅当用户授权重新创建时才进行。根据 Pod 记录获取原始配置（镜像、GPU 类别、磁盘、端口、环境变量、挂载、DC），并根据可用性查询结果选择确有现货的 GPU 类型和数据中心。先抢救卷磁盘上的所有数据（终止会删除它），并在终止前引用所需的日志行（Pod 终止后日志会消失），然后再终止并创建。创建前说明新 Pod 的每小时费用；重新创建会产生计费资源。如果 Pod 原来的 image 不可用，绝不要重新创建；跳过并说明原因。

硬性规则

• 绝不停止、重启、终止或重新创建用户未指定名称的 Pod。卡住的 Pod 可能仍保留用户想要的数据。
• 默认选择停止。只有用户明确要求破坏性操作时才终止，并且必须事先说明会删除哪个磁盘。
• 创建或重新创建任何 Pod 前，必须说明每小时费用。
• 仅凭创建调用成功，绝不能声称重新创建已成功：这只表示创建了新的 Pod，并不能确定其运行正常。请用户重新运行诊断以确认。
• 诊断时引用所读取的日志/字段。对于工具可以查明的事实，不要说“可能”。
• 如果读取日志或检查调用失败，报告失败并停止；不要猜测原因。

错误处理

• 终止／删除操作会返回不含正文的 204。这是成功，不是错误。
• 对 Pod 当前状态无效的状态转换请求会返回 409。Pod 记录中的 actions 列出了允许的转换；读取该字段并选择有效操作。
• 重建操作返回 no gpu available，表示所选 GPU／数据中心当前也没有库存。告知用户并停止；不要悄悄改到其他地方重试。

工具绑定

能力	工具
列出 Pod	list-pods
检查单个 Pod	get-pod
读取 Pod 启动／容器日志	stream-pod-logs（生命周期事件使用 source=system）
停止 Pod（保留卷磁盘）	pod-action（{"action":"stop"}）
终止 Pod	delete-pod（或 pod-action {"action":"terminate"}）
重启／启动 Pod	pod-action（{"action":"restart"}／"start"）
每个数据中心的 GPU 库存	list-gpu-types／get-gpu-type（include:["AVAILABILITY"]，product:["POD"]）
每种 GPU 类型支持的 CUDA 版本	同一读取操作（cudaVersions）；矩阵视图使用 get-capacity
数据中心	list-data-centers
重建 Pod	create-pod

如果会话的工具列表中缺少此处列出的工具，请如实说明，并使用最接近的读取操作，而不是编造结果。

约定

跨任务流程的答复约定（从读取结果中得出的确定事实、执行操作时明确承诺而不含糊、变更仅针对本次对话创建的资源、最终消息独立完整、如实说明失败、仅使用已授权工具）定义于 runpod-mcp 技能中，适用于此流程中的每条回复。如果本次对话尚未加载 runpod-mcp 技能，请在下次调用工具之前立即加载：其中关于可变更资源、何时可以执行请求以及何时应暂停并询问用户的规则，此处不再重复。