docs: 沉淀v0与Vercel接口控制经验

03_卡木（木）/木果_项目模板/v0前端生成与预览交付/SKILL.md

@@ -5,7 +5,7 @@ triggers: Vercel部署/v0部署/部署到v0/上帝之眼部署/Vercel v0/威宁
 owner: 木果
 group: 木
 version: "3.0"
-updated: "2026-07-22"
+updated: "2026-07-24"
 ---
 
 > **执行规则**：见 `运营中枢/技能路由/SKILL_RULES.md`。执行前必须：思考→拆解→读取本 Skill 与 references→按步执行→校验 v0 项目正确→**执行完成后将结果反馈给卡若**。
@@ -154,3 +154,60 @@ node scripts/sync-to-v0.js
 - Word/docx 先提取页面清单、用户流程、字段、视觉规范和验收条件，生成 `开发文档/需求文档.md`。
 - 将结构化需求连同截图发送给同一 v0 chat；v0 输出页面后按 Word 验收表逐项核对。
 - Word 仅作需求输入和验收依据，GitHub 仍是代码真源。
+
+## 八、API 全自动控制铁律（2026-07-24）
+
+### 8.1 默认通道
+
+以后 v0、Vercel、GitHub 项目控制固定采用：
+
+`本地脚本/CLI → 官方 API → 状态回读 → GitHub 真源校验 → 生产 URL 验收`
+
+- 默认不点击网页，不依赖页面文字、坐标、标签页或浏览器当前项目。
+- 浏览器仅用于首次人工授权或官方 API 明确缺少能力的账号级动作；使用后必须立即回到 API 回读，页面显示不作为完成证据。
+- 凭证只从项目 `.env`、Skill `.env.private` 或账号索引引用位置读取；日志、文档、聊天不得输出明文。
+
+### 8.2 开工前自动发现
+
+每次执行前必须先用 API 自动补齐并确认：
+
+1. `GET /v2/user` 验证 Vercel Token 与账号。
+2. `GET /v9/projects?limit=100` 按 GitHub `owner/repo`、项目名、项目 ID 三重匹配。
+3. `GET /v1/projects/{projectId}` 与 `GET /v1/chats/{chatId}` 回读 v0 项目、对话、最新版。
+4. 对 GitHub 回读仓库、默认分支、最新提交；GitHub 仓库是唯一源码真源。
+5. 把 `repo/defaultBranch/v0ProjectId/v0ChatId/vercelProjectId/productionUrl` 保存到项目内非敏感绑定状态文件。
+
+### 8.3 自动纠错与防重复
+
+- **凭证 401**：依次检查项目 `.env`、Skill `.env.private`、账号索引引用的私有环境文件；只输出文件路径与状态码。
+- **同名项目多个**：优先选择 `link.repo == 目标仓库` 的 Vercel 项目；其次选择绑定状态文件中的项目 ID；禁止按浏览器当前页猜测。
+- **v0 页面创建项目自动加后缀**：视为重复风险，停止页面创建；回到 API 按 ID 处理。
+- **v0 PATCH 返回 200 但未持久化 `vercelProjectId`**：必须再次 GET 回读；字段未出现即判定未绑定，不得继续调用部署接口或宣称完成。
+- **v0 部署 409 `Project has no Vercel project ID`**：保留原项目和对话，不自动新建第二个 v0 项目；输出结构化缺口并继续完成 GitHub、Vercel、生产部署等独立环节。
+- **地址栏、坐标、标签页误操作**：不再重试页面点击，直接切回 API/CLI。
+- **根目录错误**：Vercel monorepo 项目若命令已带 `--prefix`，不要再设置错误的 `rootDirectory`；创建/更新后回读项目配置。
+
+### 8.4 聊天窗口直接控制 v0
+
+卡若AI/Codex 在当前聊天直接控制 v0 的固定闭环：
+
+1. 读取项目绑定状态文件，锁定唯一 `v0ProjectId + v0ChatId`。
+2. `GET /v1/chats/{chatId}` 取得 `latestVersion.id/status/demoUrl/screenshotUrl`。
+3. 通过 v0 官方 API/MCP 向同一 chat 发送增量需求；不新建重复 chat。
+4. 轮询最新版本，直到 `completed` 或返回结构化错误。
+5. 回传 demo、截图、版本 ID 与变更摘要。
+6. v0 生成代码写入 Git 分支后，GitHub 合并/推送触发 Vercel；再回读部署、生产 URL、HTTP 状态与页面标题。
+
+### 8.5 完成判定
+
+以下证据全部存在才写 100%：
+
+- GitHub 仓库、默认分支、目标提交可回读；
+- Vercel 项目 ID 与 `link.repo` 指向目标仓库；
+- Vercel 最新生产部署为 `READY`；
+- 生产 URL HTTP 200 且页面标题正确；
+- v0 项目、同一 chat、最新版状态可回读；
+- v0 项目 API 回读的 `vercelProjectId` 与目标 Vercel 项目一致；
+- 项目交付记录和非敏感绑定状态文件已更新。
+
+任何一项缺失均按实际比例汇报，不用页面“Connected”代替 API 证据。