vercel-optimize

用途

Vercel Optimize 用于对已部署的 Vercel 项目执行以可观测性为先的成本与性能优化审计。它不先检查源码，而是在生成 signals.json 且确定性闸门指向某个路由、文件或项目设置后，才进行源码调查。

主要能力

• 指标优先：建议从 Vercel 生产信号出发，而非全仓库 grep。
• 确定性闸门：由 scripts/gate-investigations.mjs 决定哪些候选值得调查。
• 候选约束范围：只读取候选或路由局部导入链命名的文件。
• 版本感知引用：仅使用 references/docs-library.json，无效或版本不匹配的引用会被剔除。
• 流程化管线：收集、扫描、合并信号 → 闸门候选 → 深度调查与对账 → 生成简报并分发 → 校验建议 → 渲染报告与最终消息。

使用方式

前置条件包括：Vercel CLI v53+（含 vercel metrics、vercel usage、vercel contract、vercel api）、已认证的 CLI 会话（vercel login）、已链接的应用目录（vercel link）、Node.js 20+，以及用于路由级指标建议的 Observability Plus。命令示例：

RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"
node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"

深度调查、对账、简报生成、输出收集、校验与渲染报告均有对应脚本（deep-dive.mjs、reconcile-candidates.mjs、prepare-investigation-brief.mjs、collect-sub-agent-outputs.mjs、verify-and-regen.mjs、render-report.mjs）。默认候选预算为 6 个代码范围候选，可通过 --max-candidates 调整。

适用场景

适用于已部署的 Vercel 项目的成本与性能优化，尤其针对 Next.js、SvelteKit、Nuxt，并对 Astro 应用提供有限支持。

限制

• Hono / Remix / 未知框架默认阻断，需用户接受有限平台/代码审计后才继续。
• 需 Observability Plus 才能获得路由级指标支撑的建议；缺少时需用户选择启用后重跑或接受有限审计。
• 无流量（14 天内无有意义流量）时路由级指标稀疏，无法排序路由修复。
• 禁止在可能被回显的命令中放置认证令牌。
• 未链接项目需先 vercel link 再重跑。
• 不建议对 Vercel Workflow 运行时端点（/.well-known/workflow/v1/*）做时长削减建议。
• 成本以量级措辞表达，不面向客户给出具体金额节省。