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 惯用法
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 可以验证相同的项目链接，并重用 signals.json.commandScope.cliScope 进行任何后续的 vercel metrics 调用。

协调确定性地将已被证伪的候选方案转换为观察结果，然后再进行任何源文件调查：

• 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 作为可见的工作者名称，例如 Low cache-hit route on /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/*）建议缩短持续时间。这些是用于持久化步骤/流程执行的生成编排路由，应在调查前硬门控。
• Workflow 建议必须命名正在更改的边界。有效示例：将持久化工作入队并返回运行 ID 而不是等待完成，修复流重放/关闭/锁定，或减少已验证的多余 Workflow Steps/Storage。不要从 Workflow 端点挂钟持续时间推断成本节省。
• 对于流式、SSE、可恢复聊天或其他有意长寿命的路由，不要将挂钟函数持续时间本身视为问题。需要证据表明存在可避免的首字节前工作、高活跃 CPU、重复调用或可移出用户可见路径的后响应工作。
• 在建议缓存时，命名具体的缓存策略。
• 保持不安全的响应动态，除非有证据证明它们可以安全缓存：认证敏感路径、错误、回退响应、缺失内容、无效请求、地理位置/设备变化的输出以及未版本化的动态 URL。

对于 signals.project 中已存在的事实（包括 Fluid compute 状态、内存层级、区域、函数内并发和超时），切勿建议“验证 X 已开启”。

扫描器规则

扫描器发现是补充性的。丢弃标注为 COLD-PATH 或 NO-ROUTE-MAPPING 的发现，除非扫描器声明 metadata.trafficIndependent === true。

流量无关示例：中间件匹配器、source maps、React Compiler 配置、构建设置。路由本地缓存或数据获取模式需要路由级别的流量证据。

扫描器文档：references/scanner-patterns.md。

最终客户术语

使用：

• recommendations ready
• observations from investigation
• investigated, no change recommended
• not investigated in this run

避免：

• sub-agent
• abstention
• passRate
• quality score
• gate
• LLM

失败文案

使用以下消息，不要添加销售文案或流程细节。

过去 14 天无流量：

该项目在过去 14 天内没有有意义的流量，因此路由级别指标稀疏。我仍然可以检查流量无关的扫描器发现和项目设置，但在流量积累之前，我无法对路由修复进行排序。

路由级别指标不可用：

使用 references/observability-plus.md 中的逐字选择模板。不要静默回退到纯代码模式；呈现两条路径的选择：启用 Observability Plus 并重新运行基于指标的审计，或接受有限的纯代码运行。

项目未链接：

此工作树未链接到 Vercel 项目。运行 vercel link --yes --project <project-name-or-id> --cwd <app-dir> 并重新运行审计。如果团队已知，添加 --team <team-id-or-slug>。

大多数路由到文件映射失败：

路由清单匹配的可观测性路由不到一半。这在具有自定义路由的 monorepo 中很常见。我已呈现我能匹配的内容；其余内容出现在“本次运行未调查”部分。