Vercel Optimize

Vercel Optimize 是做什么的？

运行一个以可观测性为先的 Vercel 优化审计。在 signals.json 文件创建完成并且确定性门控指向某个路由、文件或项目设置之前，不要检查源代码文件。

核心原则：如果任何规则不明确，请阅读 references/doctrine.md。

• 指标优先。 建议从 Vercel 生产信号出发，而不是全仓库的 grep。
• 确定性门控。 scripts/gate-investigations.mjs 决定哪些内容值得调查。
• 候选约束范围。 只读取候选者或路由本地导入链所指定的文件。
• 版本感知引用。 仅使用 references/docs-library.json；无效或版本不匹配的引用将被剔除。
• 客户语气。 在撰写报告文本或聊天输出之前，请阅读 references/voice.md。

前提条件

• Vercel CLI v53+，包含 vercel metrics、vercel usage、vercel contract 和 vercel api 命令。
• 已认证的 CLI 会话：vercel login。
• 已链接的应用目录：vercel link。VERCEL_PROJECT_ID 有助于解析项目配置，但 vercel metrics 仍然需要目录链接。该链接或环境必须包含预期的项目组织/团队/用户范围，以便收集器能够解析出 CLI 安全的 --scope，并确保 vercel metrics、vercel usage 和 vercel contract 在同一个账户下运行。
• Node.js 20+。
• Observability Plus 用于获取路由级别的指标支持建议。

切勿将身份验证令牌放入 shell 命令中。不要将 VERCEL_TOKEN=...、--token ... 或 Authorization: Bearer ... 输入到可能会在聊天中回显的命令中。

框架支持

预检步骤会读取 package.json 并设置指标分发前的期望。

框架	状态	备注
Next.js App Router	支持	最强的路由映射、扫描器、操作手册、引用
Next.js Pages Router	支持	检测到 Pages Router 时，作用域限定为 Pages Router 模式
SvelteKit	支持	针对 src/routes 文件和 SvelteKit 扫描器的路由映射
Nuxt	支持	路由映射加上通用/平台检查；框架特定建议较少
Astro	有限支持	路由映射加上通用检查；框架特定建议较少
Hono / Remix / 未知	默认阻止	仅当用户接受有限的平台/纯代码审计时才继续

如果框架不受支持，请在扫描或门控之前停止并询问：

该项目使用 <framework>。Vercel Optimize 支持基于指标的代码建议，适用于 Next.js、SvelteKit 和 Nuxt。Astro 支持有限。对于 <framework>，我仍然可以运行有限的平台/扫描器审计，但路由级别的 Vercel 指标可能无法映射回源文件。

您希望我继续执行有限的审计，还是就此停止？

如果用户继续，请使用 --continue-unsupported-framework 重新运行收集。

运行目录

为每次审计使用一个全新的运行目录。请勿跨运行重复使用简报、子代理输出或报告。

RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"

管道

1. 收集、扫描和合并信号

从链接的应用目录运行，或者在脚本支持的情况下传递 --cwd。将 stdout JSON 与 stderr 日志分开。不要合并流。

node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$RUN_DIR/vercel-signals.json"

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"

收集详情、模式、指标 ID 和降级行为请参考 references/data-collection.md。指标注册表位于 lib/queries.mjs；所有查询都使用共享的 14 天窗口。

collect-signals.mjs 将链接的项目所有者解析为 commandScope.cliScope，并在检查 Observability Plus 之前验证解析后的账户是否可以读取解析后的项目。下游脚本会为每个接受 --scope 的 Vercel CLI 命令重用该范围。请勿在没有相同范围的情况下手动运行 vercel usage、vercel metrics 或 vercel contract；未限定范围的用量报告可能会显示用户的个人组织，而路由指标则来自团队项目。

如果项目或范围解析不明确，请停止并向用户询问他们希望审计哪个 Vercel 项目和团队/个人范围。不要从当前的 vercel whoami 团队推断预期的范围，并且在链接、.vercel/repo.json 中的精确项目匹配或 VERCEL_PROJECT_ID + VERCEL_ORG_ID 标识出预期账户之前，不要继续收集指标、用量或合同。

在遇到 PROJECT_SCOPE_UNRESOLVED、SCOPE_UNRESOLVED 或 PROJECT_SCOPE_MISMATCH 时，使用以下提示：

我还无法安全地识别此次审计的 Vercel 项目和账户。

请确认 Vercel 项目名称或 ID 以及团队 slug/名称，或者告知该项目属于您的个人账户。确认后，我将在检查指标之前重新链接或针对该确切范围重新运行收集。

1.1 遇阻则停

在门控之前检查阻止项：

jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"

必需的操作：

• frameworkSupportBlocker === "unsupported_framework"：使用上面的不受支持框架提示。
• PROJECT_SCOPE_UNRESOLVED、SCOPE_UNRESOLVED 或 PROJECT_SCOPE_MISMATCH：停止并向用户询问他们希望审计哪个 Vercel 项目和团队/个人范围。对于团队项目，在 vercel link --yes --project <project-name-or-id> --team <team-slug> 之后重新运行；对于个人项目，在链接到预期的用户账户之后或同时设置 VERCEL_PROJECT_ID 和 VERCEL_ORG_ID 之后重新运行。
• observabilityPlusBlocker === null：继续。
• no_traffic：告知用户路由指标稀疏；仅在他们接受有限输出的情况下继续。
• payment_required 或 no_oplus_probe：逐字渲染 references/observability-plus.md 并询问。
• project_disabled：告知用户为项目启用 Observability Plus 或接受有限审计。
• daily_quota_exceeded：停止并告知用户 Observability 查询配额已耗尽；在下一个 UTC 午夜重置后重试，或询问是否要继续进行有限的纯代码审计。
• not_linked：链接应用目录，然后重新运行步骤 1。如果已知应用路径和项目：

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# 已知时添加 --team <team-id-or-slug>

• forbidden 或 project_not_found：修复身份验证/团队范围。不要推销 Observability Plus。
• all_failed_other：显示原始错误代码，并询问是否要继续以有限的纯代码模式运行。

不要静默地回退到纯代码模式。如果用户接受有限审计，请使用以下命令重新运行收集：

node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"

然后重新扫描和合并。

2. 门控候选

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"

输出结构：

• toLaunch：代码范围的候选者，需要进一步调查。
• platform：项目/账户范围的建议。
• gated：被跳过、覆盖或取消资格的候选者，但仍必须出现在报告中。
• budget：候选者预算和选择模式。

默认预算为 6 个代码范围候选者，并带有多样性防护措施。要扩展：

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates 12 > "$RUN_DIR/gate.json"
node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates all > "$RUN_DIR/gate.json"

生成的候选者文档：references/candidates.md。

2.1 必要时询问审计范围

在深入调查之前，运行：

node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"

如果 shouldAsk 为 false，则继续。

如果 shouldAsk 为 true：

1. 完全按照原样打印 exactChatMessage.body。不要总结、截断、重新排序或重写它。
2. 然后，当主机支持结构化问题时，使用 questionPayload 询问 questionText。
3. 如果用户选择了不同的数字，则使用 --max-candidates <choice> 重新运行门控。

切勿将长预览放在问题字段内。预览和问题是独立的表面。

2.2 深入调查与协调

node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <project-dir> > "$RUN_DIR/investigation-evidence.json"

node scripts/reconcile-candidates.mjs "$RUN_DIR/investigation-evidence.json" \
  --gate "$RUN_DIR/gate.json" \
  --out "$RUN_DIR/reconciled-investigation.json"

--cwd 必须是已链接的项目目录，以便 deep-dive.mjs 可以验证相同的项目链接，并为任何后续的 vercel metrics 调用重用 signals.json.commandScope.cliScope。

协调过程以确定性方式将证伪的候选者转换为观察结果，然后再进行任何源代码调查：

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 生成简报并调查

列出工作项：

node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" --list > "$RUN_DIR/briefs-manifest.json"

为 briefs-manifest.json.briefs 中的每个条目生成一份简报。group 可以是 toLaunch 或 platform；不要只生成 toLaunch 简报。

mkdir -p "$RUN_DIR/briefs" "$RUN_DIR/sub-agent-outputs"
node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" \
  --group <brief.group> --index <brief.index> --out "$RUN_DIR/briefs/<brief.group>-<brief.index>.md"

使用 briefs-manifest.json.briefs[].label 作为可见的工作者名称，例如 /docs/llm-digest/[...slug] 上的低缓存命中率路由，而不是 toLaunch-7。

扇出规则：

• 1-2 份简报：直接内联调查。
• 3 份或更多简报：如果主机支持，为每份简报生成一个子代理。
• 不支持子代理的主机：串行内联运行。

子代理契约：

• 简报就是完整的提示。
• 仅读取简报中列出的文件，以及必要时路由本地的导入。
• 使用 references/recommendations.md 发射一个 JSON 建议或一个 JSON 无变更发现。
• 不要引用提供的引用子集之外的 URL。
• 不要建议已检测框架/版本中不可用的功能。

如果子代理试图进行全仓库 grep，则该候选者格式错误；应放弃或保留意见，而不是扩大范围。

2.4 收集输出

将每个原始调查结果保存到 $RUN_DIR/sub-agent-outputs/，然后收集：

node scripts/collect-sub-agent-outputs.mjs \
  --manifest "$RUN_DIR/briefs-manifest.json" \
  --out "$RUN_DIR/recommendations.json" \
  "$RUN_DIR/sub-agent-outputs/"

收集器提取 JSON，前置预解析的记录，强制执行清单顺序，并在遇到缺失、重复、未知或 candidateRef 不匹配的值时失败。

3. 验证建议

node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
  --signals "$RUN_DIR/signals.json" \
  --repo-root <project-dir> \
  --out "$RUN_DIR/verify.json"

该脚本提取声明、验证文件/引用/版本匹配度、评级质量、应用清理器、输出 verifiedRecommendations、withheldRecommendations、renderableRecommendations，并为失败或不安全的建议创建 regenPlan。

建议模式、编写规则、清理器顺序和评级规则：references/recommendations.md。验证规则：references/verification.md。

对于每个 regenPlan 条目，使用 Previous attempt failed these checks 部分（列出 topFailures）重新运行相同的简报。仅当验证结果有所改善且不削弱引用时，才保留重新生成的输出。

4. 渲染报告和最终消息

node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
  --project <name> \
  --out "$RUN_DIR/report.md" \
  --message-out "$RUN_DIR/final-message.json"

仅在开发技能时使用 --debug-out "$RUN_DIR/debug.json"。客户 Markdown 和聊天输出不得暴露 passRate、quality、清理器追踪、原始子代理名称或其他实现字段。

渲染后，逐字打印 final-message.json.body 并停止。不要添加高亮、调试说明、原始计数、子代理摘要或额外解释。渲染时的去重、平台上限和硬安全性丢弃可能会改变客户可见的计数，因此切勿从原始的 verify.json 进行总结。

报告结构和影响框架：references/scoring.md。

建议规则

每条建议必须：

• 追踪到已启动的候选者、平台候选者、预解析的观察结果或已验证的、与流量无关的扫描器发现。
• 包含来自 signals.json 或 evidence.deepDive 的观察到的指标证据。
• 引用包含行号的已验证文件（如果涉及代码）。
• 至少包含一条适用于已检测框架/版本的允许引用。
• 使用精确的观察到的性能数字。
• 仅使用成本量级短语；切勿向客户展示 $N 的节省金额。
• 不要为 Vercel Workflow 运行时端点 (/.well-known/workflow/v1/*) 建议减少持续时间。这些是持久化步骤/流程执行的生成编排路由，应在调查之前硬性门控。
• 工作流建议必须指明正在更改的边界。有效示例：将持久化工作入队并在等待完成之前返回一个运行 ID，修复流的重放/关闭/锁，或减少已验证的过度工作流步骤数。

... [已截断以进行翻译]