inspired-by-atmosphere/ops-troubleshooting-skills/cloud-dev-env-automation

配额受限云开发环境的自动化（抢位 → 跑完 → 拉回 → 关机）

When to Use

• 要在按卡时/核时计费、资源稀缺要抢的厂商云开发环境上干活（昇腾 CANNLab、云 GPU/Notebook/DSW 类）。
• 需求形如「抢到就跑、跑完拉回、用完关机」「无人值守把这一轮实验跑完」。
• 要给这类环境配「抢位 cron / 长流水线 / 结果播报 / 变化盯梢」四件套。

不适用：自有服务器/家庭主机运维（走 selfhosted-server-ops、home-server-deployment）；纯接口逆向手法（走 spa-api-recon）。平台专有接口与状态码记录见 references/。

铁律（比流程更重要）

1. 「受理」≠「分到」。 创建/启动接口回 200 + PENDING 只代表任务进队列；平台随后才真正分配资源，分不到就异步落到错误态。唯一可信的成功判据 = 终态为「运行中」且资源标识字段非空（如 status=RUNNING 且 npu_instance_id 非 null）。只判 HTTP 码会把失败当成功，等到跑一半才发现根本没卡。
2. 用「已关机」态探测可用性，不要反复建/删实例。 关机态通常不计费；启动请求本身就是最便宜的可用性探针：资源不足回业务错误（如 400 当前资源不足，请稍后重试），有空位才回 200。抢位循环 = 发这一个请求 → 验证终态 → 没分到就退回关机态等下一轮。
3. 结果先落持久盘，本地校验通过才关机。 拉回后本地确认产物非空（文件数 + 至少一个 >1KB 的日志/CSV），才发关机请求；校验不过不关机，留待人工。「卡时烧了、结果没拉回」比多花一卡时严重得多。
4. 长任务绝不挂在 cron 里。 定时器只做「触发」和「播报」两件短事；干活的长流程用脱离进程拉起（Windows DETACHED_PROCESS|CREATE_NEW_PROCESS_GROUP，POSIX setsid/nohup），自己写日志与结果 JSON。
5. 跑完即关。 平台的空闲自动关机（如 30 分钟无活动）是兜底、不是主力策略；开跑前先算清这一轮要花多少卡时。

流程

0. 先摸清接口（不要猜端点）

按 spa-api-recon 走：专用登录浏览器登录一次 + CDP 录网络 + grep 客户端/前端 JS。三条要点直接决定成败：

• 会话令牌直接从 cookie 里取出来当 Authorization: Bearer 打同一网关（实测省掉整套 OAuth 授权流）。
• 网关回应用层错误（带业务 error_code）说明路径与鉴权都对，只差前置条件（如实例未运行）——此时继续猜路径是走错方向。
• 网页按钮只拉起深链（vscode://厂商.插件/...）时，真接口在已装的客户端插件里，不在网页 JS 里。

1. 抢位脚本（cron 短任务，静默）

每 N 分钟一次，抢到才输出（no_agent 空 stdout = 不投递，天然防打扰）：

读出实例（用实例 key，不用显示名）→
  已 RUNNING 且资源非空 → 上报一次并退出（已抢到就别再抢）
  否则：先 stop 回「已关机」拿干净起点（错误态下 start 会被直接拒）
        → POST start
             400/资源不足 → 静默退出（常态，不打扰）
             200        → 轮询终态 ~90s（10~15s 一档、8 档封顶）
                            RUNNING + 资源非空 → 抢到：标记状态 → 脱离进程拉起流水线 → 打一行播报
                            错误态/关机        → 没抢到：stop 回关机态，静默退出

• 只认终态（铁律 1）。
• 抢到后停止继续抢（状态位）：否则平台空闲自动关机后脚本会反复重占、空烧卡时；要重新抢时用 --reset 显式恢复。

2. 流水线（脱离进程，带锁）

固定顺序：取连接凭据 → 上传工程 → 远端跑（带分钟预算）→ 拉回 → 本地校验 → 关机 → 写结果 JSON。

• 锁文件防重入：cron 每 N 分钟还会再喊一次，有活在跑就直接退。
• 每步成败写进结果 JSON（steps={"ssh":"ok","run":"fail",...}），播报时一并给出——失败能一眼定位卡在哪步。
• 远端编排脚本要自己带 deadline（收口分钟预算），别让它无限跑。

3. 结果播报（另一个 cron 短任务）

读结果 JSON + 指纹去重（同一个结果只播报一次），没有新结果就空 stdout。 分开的理由：长任务要跑几十分钟以上，定时器里等不起；短任务每 10 分钟看一眼结果文件即可。

4. 变化驱动的盯梢（只在数据变了才叫醒 agent）

盯榜/盯公告用 cron 的 monitor（变化探测），不要用定时摘要——否则天天发「没变化」。

• 探测脚本输出必须完全确定：不带时间戳、不带随机序、数值固定小数位。上线前连跑两次 diff 一遍；否则每次 tick 都被判「变了」，等于天天吵人。
• 只放真正要紧的几个数：别人的名次微动不该触发唤醒（粗粒度 = 低打扰）。
• 被唤醒之后才去查规则/公告/对手动态，并强制每条带可查来源。

Pitfalls

• 计费口径：错误态/关机态通常不计费（用「已用时长」字段对账），但开着就计费——跑完立刻关，别把「不计费」当成可以放任不管。
• 连接凭据类接口在非运行态回业务错误（如「开发环境实例未运行」）是预期，不是接口错——先把实例启起来再取。
• 实例标识一律用内部 key（存进状态文件复用）；平台显示名可能变、可能重名。
• 抢到卡那一刻起开始计费：播报里必须写清这一点，并给出「多久不操作会被平台自动关机」。
• 创建接口往往要一整套 code（goods/spec/template/image）——从平台自己的「创建配置」接口取，别硬编。

支持文件

• references/cannlab-huawei.md — 华为 CANNLab（昇腾 910B3）实测：控制面接口、鉴权、抢位/启停/连接凭据端点、状态码语义、计费口径、配套榜单接口。