vercel-optimize

Vercel 优化

开展以可观测性为先的 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 / 未知	默认阻止	仅在用户接受有限的平台／代码审计后继续

如果不受支持，请停止操作，并在扫描或门控之前征求用户同意：

This project uses <framework>. Vercel Optimize supports metric-backed code recommendations for Next.js, SvelteKit, and Nuxt. Astro support is limited. For <framework>, I can still run a limited platform/scanner audit, but route-level Vercel metrics may not map back to source files.

Do you want me to continue with the limited audit, or stop here?

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

运行目录

每次审计都使用新的运行目录。不要在不同运行中重复使用简报、子 Agent 输出或报告。

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

流水线

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

在已关联的应用目录中运行，或在脚本支持时传入 --cwd。将标准输出中的 JSON 与标准错误中的日志分开。不要合并这两个流。

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，使用此提示词：

I can't safely identify the Vercel project and account for this audit yet.

Please confirm the Vercel project name or ID and the team slug/name, or tell me it's under your personal account. Once confirmed, I'll relink or rerun collection against that exact scope before checking metrics.

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>
# add --team <team-id-or-slug> when known

• 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 作为工作者的可见名称，例如 Low cache-hit route on /docs/llm-digest/[...slug]，而不是 toLaunch-7。

分派规则：

• 1-2 份简报：在当前上下文中调查。
• 3 份或更多简报：宿主支持时，为每份简报启动一个子 Agent。
• 不支持子 Agent 的宿主：在当前上下文中按顺序逐一运行。

子 Agent 要求：

• 简报就是完整提示词。
• 仅阅读简报中列出的文件；必要时可以阅读路由本地导入的文件。
• 使用 references/recommendations.md 输出一条 JSON 建议或一条 JSON 无变更结论。
• 不得引用所提供引用范围之外的 URL。
• 不得建议检测到的版本不支持的框架功能。

如果子 Agent 尝试对整个仓库执行 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 条目，使用一个列出 topFailures 的 Previous attempt failed these checks 部分，重新运行同一份简报。只有在验证结果有所改善且未大幅删减引用时，才保留重新生成的输出。

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、清理器轨迹、原始子 Agent 名称或其他实现字段。

呈现完成后，逐字打印 final-message.json.body 并停止。不要添加重点摘要、调试说明、原始计数、子 Agent 摘要或额外说明。呈现时的去重、平台上限和硬性安全丢弃都可能改变客户可见的数量，因此切勿根据原始 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 已启用”。

扫描器规则

扫描器发现仅作补充。除非扫描器声明 metadata.trafficIndependent === true，否则舍弃标注了 COLD-PATH 或 NO-ROUTE-MAPPING 的发现。

流量无关的示例：中间件匹配器、源映射、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 中很常见。我已列出能够匹配的内容；其余内容会显示在“本次运行中未调查”部分。