用途
vercel-seat-saver 用于帮助用户搭建一套 GitHub Actions 工作流，把应用部署到 Vercel。它的特点是把 postagent 作为本地配置阶段和 CI 运行时阶段的统一工具：本地用 postagent 做 API 发现、参数收集和凭据保存，CI 中用 postagent 执行部署，从而避免依赖 Vercel CLI 或 Vercel 内置的 GitHub 连接器。
该技能适合以下情形：
- 用户希望从 GitHub Actions 触发对 Vercel 的 CI/CD 部署；
- 用户希望用统一的一个 API 令牌来集中管理部署，而不是依赖每个人的 Git 集成；
- 用户正在从 Vercel 内置的 GitHub 连接器迁移到自管理的流水线。
主要能力与工具
postagent 是本地和 CI 中唯一的 API 操作工具，关键命令包括：
postagent manual <site>—— 渐进式 API 发现（site → group → action → full schema）；postagent send <curl-style request>—— 执行 API 调用，$POSTAGENT.VERCEL.API_KEY之类的凭据占位符会自动解析；postagent auth <site>—— 交互式保存凭据；postagent auth <site> --token <TOKEN>—— 非交互式保存凭据（CI 中使用）。
可用的 site 为 vercel 和 github。资料要求始终先用 postagent manual 发现端点和参数，不要猜测。
前置条件
开始前需在本地确保：
- 已安装 postagent：
npm i -g postagent@latest； - 已保存 Vercel API 令牌：
postagent auth vercel。令牌获取路径为 Vercel Dashboard → 点击头像 → Settings → Tokens。令牌需通过安全输入路径收集，不要要求用户粘贴到普通聊天中； - 已保存 GitHub 个人访问令牌：
postagent auth github。获取路径为 GitHub → 点击头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)，至少选择 repo 权限范围。
如果缺少认证，应先引导用户完成 postagent auth。
规则约束
- 所有 Vercel 和 GitHub 操作都使用 postagent，不要在 postagent 能直接完成时额外添加 Python、Node.js 或 shell 包装脚本来发送 API 请求；
- 不要在同一个项目上同时保留 Vercel Git 自动部署和 GitHub Actions 部署，必须只有一条激活的部署触发路径；
- 不要替用户决定 Vercel 的切换方式（
vercel.json还是面板断开连接），始终让用户自己选择； - 如果仓库已有部署工作流，应更新它而不是新增第二个；
- 工作流应遵循仓库已有的 CI 约定；
- 如果团队已有 postagent 的标准 action 或 bootstrap 脚本，应复用而不是另造安装器。
使用方式（工作流）
第 1 步：本地收集 Vercel 项目信息。 用 postagent 发现并调用 Vercel 的 teams 和 projects API，收集所有静态参数：teamId、projectId、projectName、GitHub org / repo 名称。这些值后续会注入 GitHub secrets 或工作流环境变量，供 CI 运行时直接引用。如果用户还没有 Vercel 项目，用 postagent 创建。
第 2 步：检查已有 Git 集成。 添加 GitHub Actions 之前，检查项目是否已经启用了 Vercel 内置的 GitHub 连接器，避免两套系统触发重复部署。用 postagent 查看项目详情的关键字段：link（如有值表示项目已连接 Git）、connectBuildsEnabled（为 true 时 Git 推送会触发 Vercel 构建）。如果已连接 Git，应警告用户会出现重复部署，并让用户二选一：
- 方案 A（推荐）：完全断开 Git 集成——用 postagent 通过 Vercel projects API 移除项目的 Git 链接，或在 Vercel 面板中手动操作：Project → Settings → Git → Disconnect；
- 方案 B：保留 Git 连接但禁用 Git 触发的部署——在项目的 vercel.json 中添加
"git": { "deploymentEnabled": false }。这样保留 Git 链接但阻止 Vercel 在推送时自动部署。
需要把两个方案都呈现给用户，由用户决定，不要代替用户选择。
第 3 步：把收集到的信息注入 GitHub。 把第 1 步的静态参数存入 GitHub 仓库，供工作流运行时引用：敏感值（如 VERCEL_TOKEN）存为 GitHub Actions secrets；非敏感值（如 teamId、projectId、projectName）根据用户偏好存为 secrets，或直接写在工作流的 env 块中。用 postagent 发现 GitHub 的 secrets API 并以编程方式设置密钥。注意 GitHub 的 secret API 需要用仓库公钥（libsodium sealed box）加密值——如果当前环境处理起来过于复杂，可退回为提示用户在 GitHub UI 中手动添加。
第 4 步：创建 GitHub Actions 工作流文件。 在用户仓库中写入 .github/workflows/vercel-deploy.yml。如已存在部署工作流则更新它，不要新建第二个。工作流分两个阶段：
- 阶段 1——在 CI 中安装并认证 postagent：在 runner 中安装 postagent（若团队已有 bootstrap 方式则复用）；用注入的 secret 通过
--token标志认证 postagent。完成后工作流中的所有postagent send命令即可像本地一样使用$POSTAGENT.VERCEL.API_KEY。 - 阶段 2——部署：用 postagent 创建部署。Vercel 异步处理构建，简单的部署创建调用即可；状态轮询是可选的，如果团队希望工作流等待构建结果可后续添加。部署请求需要两类参数：静态参数（第 1 步收集、第 3 步注入的 teamId、projectId、projectName 等，从 secrets 或环境变量引用）；动态参数（每次推送/PR 变化的 git ref、sha、commit message、actor，从 GitHub Actions 上下文变量读取，如
${{ github.sha }}）。用 postagent 查阅 Vercel 部署 API 文档，了解哪些参数必填，并用静态值和动态值组装请求。
坑点——gitSource 格式： Vercel API 文档把 gitSource.type 标注为 [const: vercel]，但这具有误导性。对 GitHub 仓库，正确的最小 gitSource 应为：type 必须为 "github"（不是 "vercel"）；repoId 是 GitHub 仓库的数字 ID（不是仓库名）；ref 是要部署的 commit SHA。使用 type: "vercel" 会导致 500 错误。GitHub 仓库 ID 可通过 postagent 调用 GitHub repos API 获取。
第 5 步：把工作流推送到 GitHub。 用标准 git 命令（git add、git commit、git push）提交并推送工作流文件。不要用 postagent 做 git 操作。
第 6 步：验证。 推送后工作流会自动触发。用 postagent 验证两侧：确认 GitHub Actions 触发了预期的 Vercel 部署；确认部署达到 READY 状态并产生预期 URL。如果有多个部署，识别哪一个属于该 GitHub Actions 运行。如果部署失败，检查失败详情并核对项目环境变量和团队范围。
验收标准
- 仓库的
.github/workflows/中恰好只有一个部署工作流； - Vercel 令牌通过安全输入路径收集，而不是在普通聊天中粘贴；
- GitHub Actions secret 通过 postagent 创建（或记录回退到手动 UI 的方式）；
- 工作流通过
--token标志和注入的 secret 认证 postagent； - 工作流使用 postagent 创建部署和检查状态，不使用自定义请求脚本；
- Vercel Git 自动部署已禁用（通过 vercel.json），或 Git 集成已断开；
- 不存在双重部署路径。
安全规则
- 绝不在工作流文件或提交的代码中硬编码令牌，始终使用 GitHub Actions secrets；
- 本地操作使用
postagent auth，令牌保留在 postagent 的凭据存储中； - CI 中通过
--token标志配合 secrets 注入认证 postagent，令牌不会出现在日志中； - 初次测试建议优先使用 preview 目标，再部署到生产环境。
限制
资料未提供具体的价格、收费方式、平台兼容性范围、性能或效果数据；上述内容均以资料明确描述为准，未提及的部分暂未提供。