Remotion 仓库的 Vercel 部署监控实战SKILL.md 技能定义与 check-deployment.py 状态机实现解析【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion在 Remotion 开源仓库Make videos programmatically with React的 Agent 技能体系中Vercel Monitor 负责回答一个高频问题「我推上去的 PR 对应的 Vercel 部署到底 ready 了没有」本篇基于该技能目录下的 SKILL.md、check-deployment.py 与 openai.yaml完整拆解其监控原则、部署定位策略、状态判定流程与心跳监控的创建方式。读完你可以掌握「如何把一个会漂移的 Vercel 预览链接转化为一个可长期轮询、状态唯一可信的不可变部署引用」这一完整方案。技能定位什么时候会触发这个监控SKILL.md的 frontmatter 定义了触发条件当用户输入/vercel或$vercel、要求「监视/监控某个 Vercel 部署」「等待 Vercel 预览或 PR 预览就绪」「部署变成 READY 后同时告知 deployment URL 和 preview URL」时技能生效。它的核心承诺写在标题下方Monitor one immutable Vercel deployment for theremotionproject and notify the current task when that exact deployment becomes ready or fails.即只监控一个不可变的部署并且只关心这个精确部署的成败。配套的 openai.yaml 给出接口元信息interface: display_name: Vercel Monitor short_description: Monitor Vercel previews until ready default_prompt: Use $vercel to monitor the remotion Vercel deployment and tell me when the preview is ready.这说明该技能是面向 AgentCodex自动化的可执行指令集而不是给人阅读的流程手册——文中大量使用 must / never 的强约束语句来消除 Agent 的自由发挥空间。五条不可妥协的监控规则文档用 Non-negotiable rules 一节开宗明义列出了五条铁律这是整个技能的设计内核绝不从 HTTP 响应推断部署状态。分支预览别名branch preview alias可能在上一个部署上返回 200而新部署还在构建中——curl 一个 200 不能证明新部署已上线。绝不监控分支预览别名。别名是可移动的movable可能解析到更旧或更新的部署。监控必须钉死在不可变引用上Vercel 部署 IDdpl_...前缀或不可变的自动部署主机名project-random-scope.vercel.app。只读机器可读的部署状态不解析人类可读的 CLI 输出。默认项目与 scope 都是remotionbugs项目被明确排除除非用户点名要它。第 5 条与仓库现实对应本仓库同时部署了两个 Vercel 项目——文档站remotion与 packages/bugs 的 bug 复现服务。监控器必须锁定remotion否则会误报bugs项目的部署状态。定位精确部署四级优先来源部署引用不唯一——同一个 PR 可能反复触发部署所以第一步是「找到那个唯一的 deployment ID」。文档给出按优先级排列的四个来源优先级来源说明1用户直接提供的 Vercel 部署/dashboard URL最权威2活动 GitHub PR 上的Vercel – remotioncheckdashboard URL 形如https://vercel.com/remotion/remotion/deployment-id-suffix3Vercel bot 在 PR 评论中的remotion行与上一条互补4vercel list remotion --scope remotion --formatjson用.deployments[].meta精确匹配 PR、commit SHA 或分支两条关键换算与匹配规则dashboard URL → 部署 ID取 URL 最后一段路径加dpl_前缀。文档中的示例https://vercel.com/remotion/remotion/AbCd1234对应dpl_AbCd1234。vercel list匹配条件选取满足全部已知身份字段的新部署——.name remotion、已知 PR 时.meta.githubPrId PR 号、已知 commit 时.meta.githubCommitSha 完整 SHA。文档特别强调不要静默回退到另一个 commit若无法精确定位必须向用户索要 dashboard URL、PR 号或 commit SHA。同时提醒Vercel PR 评论里的Preview链接通常是分支别名可以保留到最终通知里展示但不得用于状态检查。读取状态check-deployment.py 检查器文档规定从仓库根目录运行捆绑的检查器python3 .agents/skills/vercel/scripts/check-deployment.py deployment-id-or-url检查器内部实际调用vercel inspect deployment-id-or-immutable-url \ --scope remotion \ --formatjson它对返回值做三件事校验项目归属、拒绝会移动的别名、输出归一化的 JSON。上层只消费其中的state字段其分类为state语义READY成功终态ERROR/CANCELED/CANCELLED失败终态BUILDING/QUEUED/INITIALIZING进行中UNKNOWN非终态仅当持续出现或阻碍建立可信监控时才上报诊断信息补充一条纪律HTTP 探测只允许在READY之后作为可选的可达性检查使用永远不能把一个非 ready 或 unknown 的部署提升为READY。源码级实现check-deployment.py 逐段解析check-deployment.py 只有约 170 行是理解上述规则的最好载体。1. 引用归一化normalize_reference。该函数接收三种输入L22-L44dashboard URLhost 为vercel.com或www.vercel.com时解析路径要求恰好三段/scope/project/deployment若 URL 中的 scope/project 与期望值默认remotion/remotion不一致直接抛错例如把bugs项目的 dashboard URL 传进来会被拒绝最后一段若未带dpl_前缀则自动补上。裸部署 ID以dpl_开头直接透传。不可变主机名以.vercel.app结尾的 hostname 直接使用。其余输入一律ValueErrorExpected a dpl_ deployment ID, dashboard URL, or vercel.app URL.2. 子进程调用与错误兜底。检查器以checkFalse运行vercel inspectL65-L97三种失败路径统一收敛为state: UNKNOWN且退出码为 2CLI 非零退出附带 stderr 诊断、stdout 不是合法 JSON、以及后续的归属校验失败。这保证了心跳轮询永远拿得到一份结构稳定的 JSON而不是面对 CLI 的五花八门的报错文本。3. 项目与 scope 归属校验L99-L110name deployment.get(name) context_name deployment.get(contextName) if name ! args.project or (context_name is not None and context_name ! args.scope): # state: UNKNOWN, error: Deployment belongs to a different Vercel project or scope.即便dpl_ID 是手敲的也会在这里被挡住——防止监控到别的项目的部署。4. 移动别名拒绝L112-L130。若用户传入的是.vercel.app主机名检查器会与vercel inspect返回的规范主机名deployment[url]比对两者不一致即判定为「会移动的别名」并拒绝输出{ state: UNKNOWN, error: Refusing to monitor a moving Vercel alias., alias: remotion-git-pr-1234.vercel.app, currently_resolves_to: remotion-abc123-vercel.vercel.app, deployment_id: dpl_... }注意错误信息里同时给出了当前实际解析到的不可变主机名方便调用方改用它重新发起监控。5. readyState 状态机L132-L144IN_PROGRESS_STATES {BUILDING, QUEUED, INITIALIZING} FAILURE_STATES {ERROR, CANCELED, CANCELLED} state str(deployment.get(readyState) or UNKNOWN).upper() if state READY: terminal, outcome True, success elif state in FAILURE_STATES: terminal, outcome True, failure elif state in IN_PROGRESS_STATES: terminal, outcome False, in_progress else: terminal, outcome False, unknown终态terminal: true分成功与失败两类注意失败集合同时容纳CANCELED和CANCELLED两种拼写这是对上游字段取值不统一的防御。6. 归一化输出。成功路径上检查器输出包含state、terminal、outcome、deployment_id、deployment_url由规范主机名拼出、dashboard_url若未随输入提供则按https://vercel.com/{scope}/{project}/{去掉 dpl_ 前缀的 ID}反推、preview_aliases由deployment[aliases]生成仅供最终通知展示、project、scope、created_at的 JSON。--scope与--project参数默认值均为remotion与 SKILL.md 的「默认 remotion 项目与 remotion scope」规则一一对应。创建监控一分钟心跳与自包含提示词模板文档的 Create the monitor 一节规定使用 Agent 的自动化能力创建一个一分钟一次、有次数上限通常 30 次即约 30 分钟窗口的心跳。心跳提示词必须自包含包含六个要素钉死的部署 ID 或不可变主机名、dashboard URL、已知的分支预览别名仅用于最终通知、项目/PR/分支/commit 上下文、精确的检查器命令、以及上文全部终态规则。文档给出了逐字模板Monitor this exact Vercel deployment until it reaches a terminal state. Pinned deployment: dpl_id_or_immutable_hostname Dashboard: dashboard_url Preview alias (reporting only; never use for state): preview_url_or_unknown Context: project/pr/branch/commit From the repository root, run: python3 .agents/skills/vercel/scripts/check-deployment.py pinned_deployment Only the JSON state is authoritative. - READY: reply Vercel deployment is ready and include Dashboard and Preview. - ERROR, CANCELED, or CANCELLED: reply with the failure state and include both links. - BUILDING, QUEUED, INITIALIZING, or UNKNOWN: stay quiet and check again next time. Never curl the preview URL to determine readiness. After reporting a terminal state, delete or pause this heartbeat if its automation ID is available.模板里几个值得注意的工程细节stay quiet是显式要求中间态不发消息避免每 30 秒轰炸用户一次「还在构建中」。终态后自我清理报告终态后应删除或暂停心跳若自动化 ID 可用防止僵尸监控。预览别名在模板中被标注 reporting only; never use for state把「不可变引用做状态、别名只做展示」的双轨制直接写进每次心跳的指令里。创建心跳前的最后一步先跑一次检查器文档结尾还有一条容易被忽略的流程约束Before creating a heartbeat, run the checker once. If the deployment is already terminal, report immediately instead. Otherwise, tell the user which exact deployment is being watched and the cadence.即建立心跳前先手动执行一次check-deployment.py。若部署已处于终态立刻报告结果根本不值得建心跳否则要向用户交代「正在监视哪个精确部署、轮询节奏是什么」。这既避免了对已完成部署做无意义的 30 分钟轮询也让监控行为对用户透明可审计。与仓库内其他 Vercel 工作流的衔接该技能并非孤立存在。pr 技能定义了 PR 创建后的预览链接流程最多轮询 60 秒等待 Vercel bot 评论间隔 5 秒从remotion项目行忽略bugs行提取Preview链接并写入 PR body 的## Preview小节且明确「只等 Vercel 评论出现不等待部署完成、不创建 Vercel 心跳、不探测预览页」。可以看到两者职责清晰分层pr 技能只负责拿到预览链接写进 PR而真正的部署就绪监控全部交给本技能——一旦需要「等到 READY」就走/vercel技能 check-deployment.py的不可变引用监控路径。小结这套方案的可迁移设计从 SKILL.md 到 check-deployment.py这个不到 200 行脚本加一篇规则文档的小技能示范了一套可迁移的「远程部署就绪监控」模式引用钉死一切状态查询只针对dpl_ID 或不可变主机名别名仅用于展示单一可信源状态判定只认vercel inspect --formatjson的机器可读输出state字段是唯一权威状态机显式化READY成功、ERROR/CANCELED/CANCELLED失败、BUILDING/QUEUED/INITIALIZING进行中、其余一律UNKNOWN且不当作终态失败收敛CLI 报错、坏 JSON、项目/scope 不符、移动别名全部归一为UNKNOWN 诊断信息 退出码 2让上层轮询逻辑永远面对同一种结构有限窗口轮询一分钟心跳 × 30 次上限终态即报即清理先探测后建心跳。对于任何在 CI 平台、边缘部署或 Serverless 环境需要「等某个精确构建就绪再通知」的 Agent 自动化场景这套「不可变引用 归一化状态 有界心跳」的写法都可直接借鉴。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考