docs: 补全 V0 前端绑定回流经验

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

@@ -4,8 +4,8 @@ description: 负责部署到 Vercel 的对接（主要是前端界面）；v0
 triggers: Vercel部署/v0部署/部署到v0/上帝之眼部署/Vercel v0/威宁 v0/部署流水线
 owner: 卡前
 group: 木
-version: "3.0"
+version: "3.1"
-updated: "2026-07-24"
+updated: "2026-07-31"
 ---
 
 > **体验负责人**：卡前负责用户旅程、交互状态、视觉规范、无障碍与最终体验验收；木果保留项目模板、内容与设计资产协同。
@@ -222,3 +222,93 @@ node scripts/sync-to-v0.js
 - 项目交付记录和非敏感绑定状态文件已更新。
 
 任何一项缺失均按实际比例汇报，不用页面“Connected”代替 API 证据。
+
+
+---
+
+## 九、V0 对话—GitHub—本地前端受保护回流（2026-07-31）
+
+### 9.1 适用场景与唯一真源
+
+当用户提供既有 v0 对话、要求“绑定前端、拉取 v0 更新、持续回流本地/通知完成”时，执行以下闭环：
+
+`同一 v0 chat → v0/* Git 分支 → GitHub 回读 → 本地前端契约校验 → 构建/视觉验收 → 合并发布 → 进度反馈`
+
+- v0 chat 是**前端协作入口**，GitHub 目标分支是**源码真源**，本地前端目录是**构建与验收真源**。
+- 每个项目必须有一个非敏感绑定清单，例如 `.v0-frontend-binding.json`，记录：`chatUrl/chatId/githubRepository/githubRemote/v0Branches/localFrontend/canonicalLocalBranch/requiredContracts`。
+- 不把 v0 临时 VM、截图、聊天文本或浏览器当前页面当成源码真源。
+- 一个业务只保留一个持续对话；新对话仅用于已归档需求或官方要求 fork 的分支问题。
+
+### 9.2 绑定前先做的六项真实回读
+
+1. 读取 chat URL，提取 `chatId`，同时从项目文档、非敏感绑定清单和 Git remote 交叉核对。
+2. 使用 v0 官方 API/MCP 回读 chat、project、latestVersion、repo、branch 和 Preview；每个字段都须有回读结果。
+3. 使用 GitHub API/CLI 列出 `v0/*` 分支、默认分支、最新 SHA 与关联 PR；分支名不等于当前完整前端。
+4. 用 `git diff --name-status 本地基线...v0分支 -- 前端目录` 先看文件范围，再决定是否进入合并。
+5. 明确本地唯一发布源，例如 monorepo 中的 `soul-admin/`；根目录旧前端、历史 dist 和旧部署脚本只作兼容入口，不可反向覆盖发布源。
+6. 把回读证据、分支 SHA、差异范围和下一动作写入项目 `开发文档/10、项目管理/开发进度/`。
+
+### 9.3 合并前的“回流守卫”
+
+v0 代码进入本地前，必须先运行项目级巡检脚本；脚本至少输出：
+
+```json
+{
+  "branch": "v0/example",
+  "tip": "commit-sha",
+  "files": ["变更文件"],
+  "outsideFrontend": ["越界文件"],
+  "missingContracts": ["缺失契约"],
+  "status": "READY_TO_MERGE | GUARDED | NO_CHANGE"
+}
+```
+
+- `READY_TO_MERGE`：仅改前端或允许的文档，且所有关键页面、接口标识与路由契约均存在；再执行构建、接口、视觉验收与合并。
+- `GUARDED`：改动混入后端/部署文件、删除关键能力、缺少契约或基线不一致；保留分支与差异证据，当前完整版本继续作为发布基线。
+- `NO_CHANGE`：记录检查时间，不重复构建、上传或发布。
+- 契约按项目实际功能配置，至少覆盖：主导航入口、核心页面文件、关键 API 标识、登录/权限入口、构建命令和部署入口。
+
+### 9.4 Soul 永平真实案例：防止 V0 旧快照回退
+
+项目：`一场soul的创业实验-永平`。
+
+- 绑定对话：`https://v0.app/fnvtk/chat/DP5UbRseedV`。
+- 唯一管理端发布源：`soul-admin/`。
+- 关键契约：找伙伴页面、行为推送配置组件、`behavior-webhook-config` 接口标识。
+- 回读发现：`v0/fnvtk-c51fcbc7` 的 `UsersPage.tsx` 仍是旧规则页，同时混入后端变更，并缺少新版行为推送配置；`v0/fnvtk-c514d0d7` 为早期初始化线。
+- 处置：建立 `.v0-frontend-binding.json`、`scripts/sync_v0_frontend.py` 与开发进度记录；旧快照被 `GUARDED` 拦截，找伙伴、推广中心、规则配置三项保持完整发布基线。
+- 结论：**“v0 有新提交”只代表有候选变更，不代表可以覆盖当前前端。**
+
+### 9.5 官方 API、GitHub CLI 与架构问题排障
+
+| 现象 | 判断 | 固定处置 |
+|:---|:---|:---|
+| v0 `GET /v1/chats/{chatId}` 返回 500 | 旧 chat ID、账号范围或平台服务异常均可能触发；Bearer 鉴权已受理不等于 chat 已可回读 | 记录 HTTP 状态、chatId、时间和请求通道；以 GitHub `v0/*` 分支作为代码回读通道；不重复建 chat、不把 500 写成完成。 |
+| v0 API 401 | 密钥格式或所属账号不匹配 | 仅从权限 600 的私有环境文件/账号索引引用位置读取；日志只记录状态与文件路径。 |
+| Git CLI 在 macOS 报 `xcrun` 架构错配 | 调用进程架构与 Command Line Tools 不一致 | 先 `uname -m`、`file "$(command -v git)"`；必要时采用系统匹配架构的 `arch -arm64 git`，Python 子进程也须显式使用同一 Git 命令。 |
+| `git push` 没有远端回执或远端分支不存在 | origin 未含凭证、HTTPS 凭证链路未生效或终端未回传 | 先 `gh auth status`，再用 `gh api` 回读仓库与分支；GitHub CLI 已授权时可用 API 创建分支、写入文件、回读 SHA。每次以 GitHub API 的 SHA 为最终依据。 |
+| v0 分支混入 API/部署变更 | V0 工作区不是纯前端分支 | `outsideFrontend` 非空即 `GUARDED`；拆出前端提交或建立 PR 后再审查，不整体合并。 |
+
+### 9.6 持续对话和自动通知
+
+- v0 完成后的可靠触发是**提交 GitHub `v0/*` 分支**；本地终端退出时不可能直接接收浏览器聊天事件。
+- 使用 Codex heartbeat/自动化每 30 分钟执行项目巡检脚本；结果写入项目开发进度并在同一任务反馈。
+- 自动化只做“拉取、比对、契约检查、记录”；发现 `READY_TO_MERGE` 后继续执行构建、视觉验收和受保护合并。发现 `GUARDED` 时保留完整现场，不覆盖当前发布基线。
+- v0 提示“完成”后仍需回读：GitHub SHA、变更文件、构建结果、Preview/生产 URL HTTP 状态与页面关键路由。
+
+### 9.7 最小模板
+
+```json
+{
+  "v0ChatUrl": "https://v0.app/<team>/chat/<chatId>",
+  "githubRepository": "owner/repo",
+  "githubRemote": "github",
+  "v0Branches": ["v0/<branch>"],
+  "localFrontend": "frontend-or-admin-dir",
+  "canonicalLocalBranch": "release-or-feature-branch",
+  "syncMode": "guarded-github-return",
+  "requiredContracts": ["关键页面文件", "关键接口标识", "关键导航入口"]
+}
+```
+
+**验收口径**：绑定文件、v0 chat 回读或 Git 分支兜底回读、GitHub SHA、巡检结论、构建/视觉结果、项目进度记录六项齐全，才算完成可持续绑定。