功能：完善云管助手与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 账号生成“撤销桌面授权”方案并执行，再生成“分配桌面”方案恢复原授权；重复提交同一方案返回已执行结果，没有重复写入。