部署站点
将 Next.js 营销站点 (web/site/) 部署到 Vercel 生产环境,但将其视为一个目标,而非单一命令:将所有站点相关的修复合并到 main 分支,进行部署,在生产环境中证明它在所有页面以及桌面端和移动端的邮件捕获流程中都能正常工作,并不断修复和重新部署,直到一切正常。
目标合约
以闭环方式运行此技能。不要仅凭 Vercel 部署成功就宣布胜利;部署可以成功,但某个页面可能返回 500 错误、布局在移动端断裂、或者等待列表写入静默失败。
- 完成条件:所有站点相关修复已提交并推送到
main分支,生产部署成功,以下每个路由在桌面端和移动端上均返回 200 并正确渲染,且无控制台/网络错误,邮件捕获流程接受提交并持久化(通过管理员读取验证),且不留下测试行。 - 未完成(再次循环):当任何路由渲染失败、布局在某个视口断裂、控制台显示错误或邮件捕获无法完整往返时。在源代码中修复,重新合并,重新部署,重新验证。
- 阻塞(停止并报告):当修复需要你无法获得的凭据/决策(例如 KV 存储宕机、缺少管理员令牌、Vercel 认证过期),或者同一失败在 3 次修复尝试后仍然存在时。报告确切的失败信息以及你尝试过的方法;不要永远循环。
记录每次迭代的简短运行日志(失败内容、更改内容、重新验证结果),以便循环过程可审计。如果用户希望将其作为持久的 /goal,请将目标指向此技能,并使用相同的完成/阻塞条件。
循环
Phase 0 范围界定与合并 收集站点修复 -> 本地验证 -> 提交 -> 推送到 main
Phase 1 部署 构建 -> npx vercel@latest --prod (从仓库根目录运行)
Phase 2 验证(生产环境) 工作流扇出:路由 x 视口 + 邮件捕获
Phase 3 分类 任何红色?在源代码中修复 -> 返回 Phase 0
全部绿色? -> 完成
上下文
- 项目:Vercel 上的
opentraces(scopejayfareis-projects) - 框架:Next.js 16 (App Router)
- 根目录:Vercel 配置的根目录为
web/site/ - 域名:opentraces.ai(生产环境:https://opentraces.ai)
- 构建:
next build(从web/site/运行) - 版本:构建时通过
next.config.ts自动从src/opentraces/__init__.py读取 - 邮件捕获:
EarlyAccessForm提交到/api/waitlist(生产中使用 Upstash/KV)。在/(通过HubTeaser)和/hub上渲染。请参阅参考部分了解选择器和管理员读取。
Phase 0 — 范围界定与合并站点修复
-
查找哪些是站点相关且尚未合并的更改。 工作树中通常混合了站点和非站点更改。仅在此处合并站点修复(其余部分属于其他关注点)。
git status --short web/site/ git status --short -- ':!web/site/' # 非站点更改,通常保留这些 git log --oneline origin/main..HEAD -- web/site/ # 尚未推送的站点提交 -
在合并前进行本地验证(门禁)。 针对正在运行的开发服务器运行站点,并使用 agent-browser 检查更改的表面:浅色 + 深色模式,桌面端 + 移动端,你更改的特定交互,以及控制台/网络是否干净。这是合并前的门禁;不要提交视觉退化。(如果没有开发服务器在运行,使用
cd web/site && npm run dev在一个空闲端口上启动,验证后停止。) -
本地构建(捕获开发服务器隐藏的类型/构建错误):
cd web/site && npm run build在继续之前修复任何构建失败。
-
提交到 main 并推送。 根据项目惯例,直接提交到
main(除非要求,否则不要自动创建功能分支)。保持提交范围限定于站点修复;根据仓库页脚规则添加共同作者。git add web/site/ # 暂存你已验证的站点修复 git commit -m "fix(site): <更改内容>" git push origin main
Phase 1 — 构建与部署
从仓库根目录(而不是 web/site/)部署,因为 Vercel 从其项目设置(rootDirectory=web/site)解析根目录。从 web/site/ 内部运行会导致路径双重嵌套。始终固定使用最新 CLI(npx vercel@latest)。
cd /path/to/repo/root
rm -rf web/site/.next kb/app/.next # 过时的构建输出;会使上传臃肿
npx vercel@latest --prod --yes
不要使用 --archive=tgz(测量于 2026-06-26,CLI 54.x 版本)。--archive=tgz 会对整个工作树进行 tar 打包并绕过 .vercelignore,因此它会包含 .git(多出不少内容)以及 kb/、.otbox/、web/site/.next-test/ 等 —— 一个约 3 GB / 1998 个文件 的上传,需要数分钟,并且曾经在构建机器上在“Extracting deployment files”阶段卡住约 20 分钟(我们遇到过的真实生产环境停滞)。而 vercel@latest 上的默认逐文件路径则:
- 遵守
.vercelignore→ 约 628 个文件 / 约 40 MB, - 上传约 2 秒,端到端在 约 60 秒内达到 READY 状态,
- 不会遇到
--archive=tgz最初为了规避的Error: Upload aborted(那是一个 brew 41.x 的端点 bug;vercel@latest已修复它,因此该变通方案现在是净损耗)。
如果未来的 CLI 在逐文件路径上出现退化,你必须回退到 --archive=tgz,请预期约 3 GB 的存档和多分钟(偶尔会卡住)的解压 —— 如果部署在提取阶段挂起,请重试。
从输出中捕获部署 URL/ID,你将在验证报告中引用它。
提示:你可以先验证一个 Vercel 预览部署(省略
--prod)并针对预览 URL 运行 Phase 2,然后再进行推广。这可以使邮件捕获测试完全不触及生产列表。
Phase 2 — 在生产环境中验证(通过 Workflow / ultracode 的即时测试装备)
验证直播站点是否正常工作。此阶段是一个即时测试装备:你(规划者)为这次部署界定运行范围,Workflow 工具(确定性运行时)执行它,而临时浏览器工作进程各自根据类型化模式返回结果。中间状态存在于测试装备的变量中,而不在您的上下文中,因此完整的矩阵运行不会填满您的窗口。此技能明确选择使用 Workflow 编排(ultracode)。
该测试装备已捆绑并冻结在此技能旁边:verify-site-deploy.workflow.js。不要内联粘贴脚本;直接运行该文件。
检查内容
- 路由(每个必须返回 200 并渲染,无控制台/网络错误):
/、/explorer、/hub、/schema、/docs,加上深度页面的抽查:/schema/0.6.0、/docs/getting-started/installation、/docs/cli/commands、/docs/schema/trace-record。 - 视口:桌面端
1440x900和移动端390x844(iPhone 级别)。如果修复涉及主题,还需检查浅色和深色模式。 - 每页:HTTP 200 状态码、主要内容可见、在视口处无布局溢出/裁剪、控制台干净、无失败的网络请求、导航正常工作。
- 邮件捕获(其自己的代理,见下文)。
邮件捕获验证(不要污染生产列表)
/api/waitlist 写入实时存储且没有 DELETE 端点,因此请谨慎操作:
- 真实往返(一次,桌面端):提交一个标记地址,如
deploy-verify-<timestamp>@opentraces.ai。期望返回 HTTP 200{ok:true}并且按钮翻转到成功状态。通过管理员读取(GET /api/waitlist+Authorization: Bearer $WAITLIST_ADMIN_TOKEN)确认它已持久化,注意前后的计数。然后清理它,从存储中删除该行(UpstashZREM),并重新读取以确认计数已恢复。保持列表原始状态。 - 去重路径:两次提交相同的地址,期望看到“您已在该列表中”,计数不变。
- 移动端 + 无需写入的重复 UI 检查:在提交时填写隐藏的蜜罐字段(
input[name=company])。端点会返回一个静默的假成功并且从不存储该行,因此您可以在移动端确认成功 UI 而不添加垃圾数据。(如果您看到“成功”但计数没有变化,那是蜜罐的正常工作,而非错误。) - 如果端点返回 503(“waitlist is not configured”),则说明 KV 存储未在该部署上连接:那是 阻塞(环境/存储问题),而不是代码修复。报告它。
运行测试装备
使用 Workflow 工具调用捆绑的工件。使用 args 按部署范围界定(这是 JIT“规划者”步骤):
Workflow({
scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
args: {
baseUrl: "https://www.opentraces.ai", // 标准主机;或预览 URL 以使邮件脱离生产
changed: ["/hub", "/"], // 此部署触及的路由 -> 深度检查;其余快速检查
pagesOnly: false // true = 跳过邮件写入(只进行只读验证)
}
})
它返回 { base, scoped, failures, allGreen }。allGreen: true 表示 Phase 2 通过;否则 failures 列出 Phase 3 需要修复的内容。
测试装备如何应用 JIT 原语(请参阅 kb/docs/concept-jit-harnesses-generic.md):
- 分类和路由:如果您传递了
changed,这些路由将获得完整的浏览器检查(控制台、溢出、截图);每个其他路由仅进行廉价的curl状态检查。由运行时拥有的纯 JS 控制流,在接缝处没有模型,因此范围界定的部署仍保持低成本。 - 每个视口一个确定性扫描工作进程(2 个工作进程,而非约 18 个):每个在廉价模型(
haiku)上运行单个固定的 bash 批处理(每个路由的curl+ 一组有边界的 agent-browser 调用),并返回解析后的 JSON。没有开放式的“验证一切”提示,因此模型不会循环;每个批处理打开一个浏览器会话并close --all关闭它,因此 Chrome 进程不会堆积。(验证于 2026-06-09:完整深度视口扫描约 16 秒,1 个残留进程,而原始的逐单元设计是 54 个进程 / 15 分钟以上。) - 独立的对抗性确认:扫描标志为失败的任何路由将由一个具有干净会话(默认模型)的独立工作进程重新检查,该进程尝试重现失败;仅当确认也失败时,失败才持续存在,因此 agent-browser 的失误不会伪装成站点错误。
- 类型化契约:每个工作进程针对
PAGE_VERDICT/EMAIL_VERDICT返回结果,因此结果机械地合并。 - 邮件捕获拥有自己的工作进程,通过独立的管理员读取证明写入,并清理测试行(请参阅上述无污染规则)。
要更改矩阵、深度策略或判定模式,请编辑该 .js 文件,它是唯一的事实来源。如果更改仅涉及一个页面且您不想进行编排,您仍然可以在主会话中使用 agent-browser 技能顺序运行该页面的检查。
Phase 3 — 分类与迭代
读取工作流的 failures:
- 空 -> 目标已达成。报告:部署 ID/URL、已验证的路由、视口、邮件往返已证明并清理完成。完成。
- 非空 -> 对于每个失败,在
web/site/源代码中找到根本原因,修复它,然后返回 Phase 0(本地验证 -> 提交 -> 推送 -> 部署 -> 重新验证)。首先针对失败的路由重新运行验证,然后在它们变绿后进行完整扫描。 - 在针对同一失败的 3 次不成功尝试后,或遇到凭据/存储/认证阻塞时,停止并报告为阻塞,附带确切错误以及您尝试过的方法。
记录每次迭代到运行日志中,以便循环可审计。
.vercelignore
位置至关重要:有效的文件是仓库根目录下的 .vercelignore。 即使项目的根目录是 web/site,整个仓库也会被上传(构建会读取 ../../src/opentraces/__init__.py 和 ../../skill/SKILL.md),而逐文件上传所遵守的唯一 .vercelignore 是位于仓库根目录的那个 —— 模式匹配是相对于仓库根目录的。web/site/.vercelignore 会被忽略;不要添加一个(已验证于 2026-06-26,通过 npx vercel@latest --debug)。
它是一个正向忽略列表(明确枚举的目录,不是带有 ! 否定通配符的 * 捕获全部 —— 否定模式很脆弱,会在不同的 CLI 版本中失效)。没有它,上传将包含庞大的仓库树。它必须排除的大文件(每个都是我们修复过的真实泄露):
kb/(约 2.4 G)、.claude/(约 1.5 G)、tests/(约 1.4 G)、.venv*/(约 0.8 G).otbox/(约 613 M 快照压缩包)web/site/.next-test/(约 98 M / 1000+ 文件 — 注意**/.next/并不匹配-test后缀,因此.next-test/需要自己的规则)web/viewer/、web/coming-soon/、web/metrics-worker/
注意:
.vercelignore仅过滤逐文件上传路径。--archive=tgz标志会绕过它(请参阅 Phase 1 —— 另一个不使用它的原因)。
要验证编辑 .vercelignore 后的上传内容,请从仓库根目录运行 npx vercel@latest --debug 并读取 Found N files … M required to upload 行,然后按 Ctrl-C —— 无需完整部署。健康的站点部署约为 628 个文件,而非约 2000 个。
不得被忽略的文件(构建时读取它们):
| 文件 | 被谁读取 | 用途 |
|---|---|---|
src/opentraces/__init__.py | next.config.ts | 为 version.json 检测版本 |
skill/SKILL.md | lib/docs.ts (getSkillContent()) | 文档页面上的机器查看内容 |
如果您添加了站点在构建时通过诸如 ../../foo 的相对路径读取的新文件,请确保它不被 .vercelignore 排除。
参考
路由(Phase 2 矩阵):/、/explorer、/hub、/schema、
/schema/[version]、/docs、/docs/[[...slug]](来自 lib/doc-nav.ts 的约 36 个文档路径)。API:/api/waitlist(POST 添加,GET 管理员读取)、
/api/stars。
邮件表单选择器(EarlyAccessForm.tsx):电子邮件输入
input[type=email] / aria-label="email address" / .ea-input;提交按钮
button.ea-btn("get early access" -> 加载中 -> 成功);隐藏蜜罐
input[name=company](填写它 -> 静默假成功,永不存储)。
等待列表管理员读取:GET /api/waitlist 包含
Authorization: Bearer $WAITLIST_ADMIN_TOKEN。