功能：完善云管助手与GPU故障恢复核对

docs/cloud-common-assistant-20261113.md

@@ -0,0 +1,30 @@
+# 通用版固定场景助手
+
+通用版助手面向非技术用户，使用“自然语言输入 + 受控业务脚本 + 确认执行”的方式工作。当前不依赖 AI 模型；后端先用固定场景解析，后续可以只替换解析层接入模型。
+
+## 当前脚本
+
+- 分配已有桌面
+- 撤销桌面授权
+- 桌面连接问题处理
+- 设备与桌面状态查询入口
+
+分配和撤销会先生成方案，要求员工和桌面唯一匹配；没有明确桌面时展示候选项，不再自动选择第一台空闲桌面。方案有效期 5 分钟，确认执行时后端会重新检查用户、桌面、授权、权限和并发状态。
+
+## 后端接口
+
+- `POST /api/v1/assistant/plan`：根据一句话生成方案
+- `POST /api/v1/assistant/execute`：确认并执行方案
+- `GET /api/v1/assistant/runs/{id}`：查看方案和执行结果
+
+方案记录写入 `assistant_runs`，包含原始输入、结构化意图、状态、有效期、执行结果和操作者。执行沿用授权锁和审计日志；同一个方案重复提交会返回已保存结果，不会重复修改授权。
+
+## 安全边界
+
+助手只产生允许的业务动作，不能执行任意 Shell、SQL 或 PVE 命令。AI 接入后也只能输出受限结构化意图，最终权限判断和资源变更仍由平台后端完成。
+
+## 验证
+
+- Go 全量测试通过，包含缺少桌面时展示候选、明确方案执行、状态重新校验和重复确认幂等测试。
+- 前端 typecheck、lint 和生产构建通过。
+- 真实环境已验证：root 账号生成“撤销桌面授权”方案并执行，再生成“分配桌面”方案恢复原授权；重复提交同一方案返回已执行结果，没有重复写入。

docs/cloud-gpu-health-exclusive-logs-20261112.md

@@ -2,9 +2,9 @@
 
 ## 已实现
 
-- `GET /api/v1/resources/gpus?node=...` 在每个 GPU 上返回 `health`：PVE PCI 清单中的驱动字段、驱动绑定状态、来源和采集时间。标准 PVE PCI 接口没有温度、利用率、显存指标时返回 `status=not_collected` 和空值，不把 VM 配置引用当作健康数据。
+- `GET /api/v1/resources/gpus?node=...` 在每个 GPU 上返回 `health`：PVE PCI 清单中的驱动字段、驱动绑定状态、来源和采集时间。标准 PVE PCI 接口没有温度、利用率、显存指标；配置 `VDI_GPU_AGENT_TOKEN` 后，节点采集器通过 `POST /api/v1/gpu-agent/health` 上报近 10 分钟的真实指标，页面才显示 `status=collected`，没有上报时保持 `not_collected`。
 - `GET /api/v1/resources/gpu-exclusive?node=...` 提供独占组分配前检查：advisory lock、成员完整性、PVE 实际电源、活跃终端会话、未完成任务、冲突原因、`allocationReady` 和 `releaseReady`。接口只读，不会关机、切换显卡或重放任务。
-- 终端成功回传 `collect-logs` 后，日志写入 `terminal_log_archives`，按终端和时间建立索引，保留 30 天，并通过 `GET /api/v1/terminal-logs` 支持终端、时间范围和关键词检索。沿用诊断脱敏；这是回传快照归档，不是实时日志流。
+- 终端成功回传 `collect-logs` 后，日志写入 `terminal_log_archives`；终端正常运行时可通过设备令牌调用 `POST /api/v1/terminal/logs` 持续上报小批量事件，写入 `terminal_log_entries`。两类记录在 `GET /api/v1/terminal-logs` 统一检索，均按终端和时间建立索引、保留 30 天并执行脱敏。
 - 高级版 GPU 页面显示健康状态、驱动绑定、独占资源冲突和释放条件；日志与诊断页面增加持续归档检索区。
 
 ## 真实边界

docs/cloud-gpu-recovery-20261113.md

@@ -0,0 +1,24 @@
+# GPU 切换偶发超时的自动核对
+
+## 原因
+
+2026-11-13 16:02（北京时间），Windows 10（VMID 100）的启动请求已被 PVE 接受，但查询原任务状态时 HTTP 超时。原任务实际以 `exitstatus=OK` 结束；旧逻辑把一次读取失败升级成持续阻塞，需要管理员手动核对。
+
+## 行为
+
+- PVE 任务状态和实际电源的 GET 查询，对网络暂时性故障及 HTTP 408/429/500/502/503/504 最多读取 3 次，间隔 250/500 毫秒，并遵守调用方取消和超时。权限错误不重试。
+- 电源 POST 不自动重发。拿不到原任务 UPID 时保留阻塞，需要核查，避免重复关机或显卡争用。
+- 后台在没有进行中的 GPU/创建操作时，间隔至少 15 秒选择一条待核对任务；恢复过程中仍持有独占组锁。每次核对最长 60 秒。
+- 已知原任务结束后，检查独占组配置、全部成员电源、员工/终端授权和 Sunshine 响应。只有这些条件全部满足才自动完成为成功，并更新桌面状态、记录系统审计。
+- 任务已结束但准备流程未完成，自动结束为失败并解除该任务的阻塞，用户可以重新选择桌面；后台不会补发后续电源操作。
+- 仍无法确认电源、原任务未结束或发现多台成员同时运行时保持阻塞。最近 24 小时内具有 UPID 的不确定任务继续后台核对，过期任务保留供管理员处理。
+- API 重启后发现的运行中 GPU 任务只恢复观察，不重放命令。尚未提交电源操作的任务结束为可重试失败。
+- 前 5 分钟内，设备查询可自动核对任务时返回 `running`，让现有终端继续轮询。同一终端重新准备同一桌面复用原任务，不重复创建。
+
+## 验证方式
+
+测试使用独立 Docker PostgreSQL（`vdi-cloud-gpu-recovery-test-db`），不连接业务库；PVE 和 Sunshine 均使用测试 HTTP 服务。覆盖读取失败后恢复、不确定 POST 不重放、实际多 VM 冲突、原任务失败、连接服务未启动、授权撤销、配置变化、API 重启、同一任务复用和有限等待。
+
+现场部署仅更新 API，无 VM 电源操作、终端重启或 GPU 重新绑定。回退镜像为 `vdi-cloud-live-api:before-gpu-recovery-20261113`。
+
+验证结果：带专用数据库的 `go test ./... -count=1` 和 `go vet ./...` 均通过；GPU 故障注入及重启恢复用例通过。部署后真实 `/healthz` 返回生产模式 `ok`，独占组冲突为空，VM 100 保持运行，101/102 保持关机。临时测试数据库容器已清理。