fnvtk/karuo-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
265dd459a398ad5b6e6e1393a8c0d95937ae48e0
karuo-ai/03_卡木（木）/木果_项目模板/v0前端生成与预览交付/SKILL.md
Manus AI 265dd459a3 docs: 补全 V0 前端绑定回流经验
2026-07-31 17:22:03 +08:00

20 KiB
Raw Blame History

name, description, triggers, owner, group, version, updated
name description triggers owner group version updated
v0前端生成与预览交付 负责部署到 Vercel 的对接（主要是前端界面）；v0 优化完成后同步到 GitHub、Vercel、本地协同，确保全部确定；任务完成反馈写入项目并反馈卡若。项目/对话名中文。 Vercel部署/v0部署/部署到v0/上帝之眼部署/Vercel v0/威宁 v0/部署流水线 卡前 木 3.1 2026-07-31

体验负责人：卡前负责用户旅程、交互状态、视觉规范、无障碍与最终体验验收；木果保留项目模板、内容与设计资产协同。

执行规则：见 运营中枢/技能路由/SKILL_RULES.md。执行前必须：思考→拆解→读取本 Skill 与 references→按步执行→校验 v0 项目正确→执行完成后将结果反馈给卡若。

一、技能概述

统一前端基线：新建或重构任意 Web 项目时，先读 参考资料/v0通用前端基线.md。默认以 v0 当前可原生导入、运行、预览、Git 协作和 Vercel 部署的 Next.js 前端为基础；存客宝只作结构样例，不继承其业务和宽松构建配置。

属性 内容
负责人 木果（木）
职责 部署到 Vercel 的对接（主要是前端界面）；Vercel 部署 + v0 项目/对话整条流水线；v0 优化完成后同步到 GitHub、Vercel、本地协同，确保全部确定
承接 以后「部署到 v0」一律走本链路
前提 先确保 v0 项目、项目页正确，再做其它优化
命名 v0 项目名与对话名均使用中文（如项目「上帝之眼」、对话「前端优化计划」），不得使用英文项目/对话名
本地前端位置 固定为 项目根/frontend，不要搞错；v0 改完代码落回此处再同步
反馈 执行完成后将结果反馈给卡若；做完任务同步后更新「同步与反馈记录」（开发文档/8、部署/同步与反馈记录.md），项目状态可查
开发文档 开发文档/00_汇总索引.md：功能迭代、需求、汇总入口

二、完整链路（顺序不可颠倒）

1. 需求结构化 → 2. GitHub真源 → 3. v0导入/创建 → 4. Sandbox构建 → 5. Preview验收 → 6. 分支/PR → 7. Vercel部署 → 8. 卡若AI持续发消息

通用新项目默认规则

  • 默认栈：Next.js App Router + React + TypeScript + Tailwind CSS + shadcn/ui；按项目需要增加 Radix、表单、表格、图表和 AI SDK。
  • 版本由创建当日 v0 官方运行环境与项目锁文件确定，不复用 Skill 中过期的固定小版本。
  • 新项目先建/确认 GitHub 真源再进入持续迭代；v0 每个任务使用 chat 对应的 Git 分支和 PR。
  • 禁止以 ignoreBuildErrors、ignoreDuringBuilds、空 Preview 或 localhost 文案作为完成依据。
  • 创建时就完成 GitHub、VM、Preview、Vercel 与持续消息链路，不把这些留到项目末尾补做。
步骤 动作 脚本/接口 凭证
1 确认 .env 有 VERCEL_TOKEN、V0_API_KEY 可从账号与API索引读取；金盾仅协同凭证 木果
2 部署到 Vercel（创建项目/设生产公开/触发部署） 上帝之眼/scripts/deploy-vercel.js VERCEL_TOKEN
3 校验生产 URL 可访问 脚本内 fetch godeye-lime.vercel.app -
4 在 v0 上创建或关联「上帝之眼」项目 上帝之眼/scripts/sync-to-v0.js V0_API_KEY
5 校验 v0 项目 id/name/webUrl/vercelProjectId GET /v1/projects 或 references 内校验命令 V0_API_KEY
6 打开/创建「前端优化」对话（先检查再创建，中文名） scripts/create-v0-optimization-chat.js [--open] V0_API_KEY
7 整理多条对话：保留最完善 1 条、改中文名、删其余并反馈 scripts/consolidate-v0-chats.js V0_API_KEY
8 v0 优化后同步 GitHub → Vercel → 本地拉齐，并写入任务反馈 scripts/sync-after-v0.js [备注] VERCEL_TOKEN

二-A、前端新建强制交付门（2026-07-22）

以后只要任务包含“用 v0 新建前端、导入前端、优化前端、生成网站”，创建聊天或生成代码不算完成，必须同时通过以下验收：

  1. GitHub 真源存在：先查当前 GitHub 账号下是否已有同项目仓库；没有则创建中文业务对应的规范仓库名，初始化 README、.gitignore、许可证按项目规则处理，并推送可启动源码。
  2. v0 已连接 GitHub：v0 Settings → GitHub 不得出现 No GitHub repository connected；必须记录 owner/repo、默认分支、绑定结果。
  3. 运行入口可用：识别真实前端目录、包管理器、dev/build/start；monorepo 必须补最小根启动脚本，不得只给 localhost 文本却没有可见 Preview。
  4. Preview 真验收：预览区必须显示实际页面；检查首页、核心路由、图片、按钮、Tab、弹窗和响应式。Not found、白屏、无限加载、资源 404 均视为未交付。
  5. 旧 VM 自动升级：出现 Upgrade this chat to continue 或 Duplicate and Upgrade 时，立即复制升级到最新 VM；升级后重新绑定仓库、重新启动、重新验收，旧对话只留作归档。
  6. Vercel 预览可访问：需要外部预览时发布 Preview Deployment，回读 HTTP 状态和页面标题；不把本地端口当外部交付地址。
  7. 卡若AI可持续沟通：记录 chatId/chatUrl/projectId/vercelProjectId/repo/defaultBranch；后续卡若AI/Codex 优先通过 v0 MCP 的“向已有 chat 发送消息”继续同一对话，API 兜底，网页最后兜底。
  8. 交付记录完整：写入项目 开发文档/8、部署/同步与反馈记录.md；缺少仓库链接、v0 对话、Preview/Vercel 链接或验收结果任一项，达成率不得写 100%。

禁止假完成

  • 只创建 v0 chat，未绑定 GitHub。
  • 只输出 localhost:5173/3000，预览区实际空白。
  • Preview 显示 Not found、No preview available 或升级提示仍宣称完成。
  • 新建多个重复 chat/repo，却没有确定唯一真源。
  • 只在 v0 修改，未说明代码是否写回 GitHub。

GitHub 自动创建/绑定策略

  • 用户说“新建项目”且没有现成仓库：默认创建 GitHub 仓库并绑定 v0；仓库可见性沿用当前项目/组织默认策略。
  • 已有仓库：先复用，不重复创建；默认分支作为源码真源。
  • GitHub 授权失效：直接进入 v0 GitHub Connect 完成授权，再继续绑定；授权完成前不进入 UI 优化。
  • v0 自动生成分支不等于主分支；写回前明确 PR 或直接合并策略并记录提交。

三、执行命令（上帝之眼项目）

cd "/Users/karuo/Documents/开发/3、自营项目/上帝之眼"
node scripts/deploy-vercel.js
node scripts/sync-to-v0.js
  • 若 v0 已有关联项目，sync-to-v0 会直接提示已关联并输出 webUrl。
  • 执行后必须做步骤 5：确认 v0 项目页、名称、vercelProjectId 正确。
  • 在 v0 里做前端优化对话：运行 node scripts/create-v0-optimization-chat.js [--open]。脚本会先检查项目下是否已有「前端优化计划」对话，有则直接返回链接（不循环创建），无则新建且使用中文名称；打开后按对话内首条消息执行优化。
  • v0 优化完成后同步（丝滑一条龙）：代码落回本地 frontend（位置固定：项目根/frontend）→ 运行 node scripts/sync-after-v0.js "本次说明" → 自动 push GitHub、触发 Vercel、本地 pull 拉齐 → 结果写入 开发文档/8、部署/同步与反馈记录.md，做完任务即反馈到项目。

四、关键路径与 ID（上帝之眼）

项 值
Vercel 项目 ID prj_7Icpm7qR1hc6X61ydY1bzxAsjLVz
生产地址 https://godeye-lime.vercel.app
v0 项目页 https://v0.app/chat/projects/MvSR6KzOHAn
本地前端目录（固定） 项目根/frontend（勿搞错）
同步与反馈记录 上帝之眼 开发文档/8、部署/同步与反馈记录.md
完整流程与问题 本目录 references/完整流程与问题手册.md
Token 管理 金盾 账号密码与资料管理/Vercel_Token管理与API部署.md

五、常见问题（速查）

现象 处理
未设置 VERCEL_TOKEN / V0_API_KEY 从 账号与API索引 取并写入 上帝之眼/.env
Vercel 创建项目失败 / Git 在 Vercel 后台用 GitHub 连接仓库（一次性）
预览/生产需登录 脚本已设 ssoProtection 为 preview；仍异常则检查项目设置
v0 401 确认 V0_API_KEY 为 v0 Platform API Key 或索引中 v0 Secret

详细列表与校验命令见 references/完整流程与问题手册.md。

六、协同与反馈

  • 火眸：上帝之眼业务与前端；需部署到 v0 时由本 Skill 承接，木果执行；金盾只在凭证与数据安全环节协同。
  • 账号与API索引：VercEL_TOKEN、V0_API_KEY 由木果协同金仓维护，部署前从索引或 .env 确认。
  • 结果反馈：每次执行部署/同步/整理 v0 对话后，将结果汇总反馈给卡若；v0 优化后执行 sync-after-v0 的，结果自动写入项目内「同步与反馈记录」，确保整个项目协同、确定、可查。

七-A、卡若AI、v0、Codex/Worktree 与 Word 协同

卡若AI直接向 v0 发送信息

固定顺序：

  1. 从交付记录或 v0 MCP 搜索唯一 chatId。
  2. 读取 chat 最新状态，确认 repo、branch、VM 和 Preview。
  3. 通过 v0 MCP 向该 chat 发送增量任务；保持同一 chat，不重复建对话。
  4. 回读最新消息、版本、Preview 和报错；任务未运行成功则继续发送修复指令。
  5. 需要写回源码时，同步 GitHub 后再触发 Vercel，并让本地/Worktree 拉齐。

与 Codex Worktree/工作区结合

  • GitHub 默认分支是共享真源；Codex Worktree 负责代码修改、测试和提交，v0 负责前端生成与可视化预览。
  • v0 变更先落分支/提交，再由 Codex Worktree 拉取、审查、构建；Codex 变更推送后，v0 刷新同一仓库和分支。
  • 禁止把 v0 VM 临时文件当唯一源码。

与 Word 需求文档结合

  • 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.4-A 分支问题一键修复（新增）

  • 当出现 Create a Branch、continue 被拦截等提示时，不点页面：
    1. POST /v1/chats/{chatId}/fork 创建分支 chat（返回新 chatId）。
    2. 将新 chatId 写回 sdk/config/v0_vercel_binding.json 的 v0.chatId 与 v0.chatUrl，避免反复操作旧会话。
    3. 后续都使用新 chatId 继续 send/status，旧 chat 只留归档。
  • 规则：一个主问题不再创建新分支，若同一目标 1h 内重复 fork 先复用同一 chat。
  • 示例命令：node sdk/scripts/v0_control.mjs fork / node sdk/scripts/v0_control.mjs switch <chatId>。

8.5 完成判定

以下证据全部存在才写 100%：

  • GitHub 仓库、默认分支、目标提交可回读；
  • Vercel 项目 ID 与 link.repo 指向目标仓库；
  • Vercel 最新生产部署为 READY；
  • 生产 URL HTTP 200 且页面标题正确；
  • v0 项目、同一 chat、最新版状态可回读；
  • v0 项目 API 回读的 vercelProjectId 与目标 Vercel 项目一致；
  • 项目交付记录和非敏感绑定状态文件已更新。

任何一项缺失均按实际比例汇报，不用页面“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 代码进入本地前，必须先运行项目级巡检脚本；脚本至少输出：

{
  "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 最小模板

{
  "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、巡检结论、构建/视觉结果、项目进度记录六项齐全，才算完成可持续绑定。