前言¶
项目已经部署到 Vercel 之后，常见的麻烦往往不是「能不能上线」，而是账单里 Function Invocations、Build Minutes、Fast Data Transfer 突然变高，或者某几条路由明显变慢。这时候如果让 Agent 直接在仓库里搜 cache、revalidate、force-dynamic，很容易得到一堆和真实流量无关的建议：冷路径被改了，热路径反而没动。
vercel-optimize 要解决的就是这件事。它是 Vercel 官方实验室仓库里的一份 Agent Skill：先用 Vercel CLI 拉生产指标和用量，再用确定性脚本决定该看哪些路由和文件，最后才给出带出处的优化建议。装好之后，在已关联的项目目录里对 Agent 说「optimize this Vercel project」即可触发。
这是什么¶
vercel-optimize 收录在 vercel-labs/agent-skills 中，目录为 skills/vercel-optimize/。仓库遵循 Agent Skills 通用格式（SKILL.md + 可选 scripts/、references/），因此 Cursor、Claude Code、Codex CLI 等支持该格式的工具都可以使用。当前 SKILL.md 的 metadata.version 为 1.2.0。
官方 README 的定位是：为已经部署在 Vercel 上、且受支持的项目做成本和性能优化。每一条建议都要同时满足三件事：能在观测数据里找到对应信号、能在限定范围内核对到源码、引用的文档要匹配当前框架版本。
它针对的是「已经上线、已经有流量」的项目，而不是从零写一个 Next.js 应用。触发场景包括：降低 Vercel 账单、排查又慢又贵的路由、找缓存 / ISR / Middleware / 图片优化 / 构建分钟数问题，以及产出一份按优先级排列的成本和性能报告。
核心能力¶
根据仓库中的 SKILL.md、README.md 和 references/doctrine.md，这套 Skill 的工作方式可以概括成四条硬规则。
-
先观测，再读代码
在signals.json生成之前，不允许翻源码。推荐从 Vercel 生产信号出发，而不是全仓库 grep。指标窗口统一为最近 14 天。 -
用确定性脚本决定调查范围
scripts/gate-investigations.mjs是纯 JavaScript 阈值，不靠大模型判断「这条路由值不值得看」。默认每次最多选出 6 个代码侧候选，并带多样性约束。被跳过的候选仍会出现在报告的「Not investigated in this run」里，并写明原因。 -
调查范围绑在候选上
门控给出src/app/api/products/route.ts这类文件后，Agent 只读该文件及其路由内 import 链，禁止扩大成全仓审查。静态扫描（AST-grep）可以并行跑，但标注为COLD-PATH或NO-ROUTE-MAPPING的发现默认丢弃；只有构建配置、middleware matcher、生产环境 source map、React Compiler 这类与流量无关的项才会保留。 -
建议必须有版本匹配的文档出处
引用只能来自references/docs-library.json的允许列表。未知 URL、和当前package.json里框架版本对不上的文档会被剥离。例如不会把 Next.js 15 的特性推荐给 Next.js 13 项目。
框架覆盖以 preflight 读取 package.json 为准：
| 框架 | 状态 | 说明 |
|---|---|---|
| Next.js App Router | 支持 | 路由映射、扫描器、playbook、文档引用最完整 |
| Next.js Pages Router | 支持 | 检测到后按 Pages Router 习惯处理 |
| SvelteKit | 支持 | 映射 src/routes，带 SvelteKit 扫描器 |
| Nuxt | 支持 | 有路由映射和通用/平台检查，框架专用建议较少 |
| Astro | 有限 | 有路由映射和通用检查，框架专用建议较少 |
| Hono / Remix / 未知 | 默认拦截 | 需用户明确接受后，才做有限的平台/代码审计 |
README 里已经标为 Supported 的信号包括：Function 调用量、时长、TTFB、冷启动、CPU/内存/GB-hours、请求量与缓存命中率、HTTP 状态与方法分布、Fast Data Transfer 与机器人流量、ISR 读写、Routing Middleware、外部 API 延迟、Speed Insights 的 Core Web Vitals、Image Optimization、Build Minutes、计费服务用量尖峰、Bot Protection / BotID、Fluid Compute、区域固定与项目配置不一致、Observability Events 成本归属等。Hono/Remix 的路由到文件映射，以及 AI Gateway、Sandbox、Blob、Edge Config、Workflows、Queues 等计费维度，README 仍标为 Planned。
一次完整运行后，用户侧会拿到：按观测数据排序的建议、有依据时给出的路由和文件位置、可落地建议的修改前后代码、来自允许列表的文档引用、证据不够强因而暂扣的发现，以及一段简短的最终说明加一份完整 Markdown 报告。
安装与启用¶
这份 Skill 不只是一份说明文档，还带有 scripts/、lib/、references/。安装时必须拷贝整个 skills/vercel-optimize 目录，只放一个 SKILL.md 跑不起来。
用 skills CLI 安装¶
Vercel 在 2026 年 1 月 20 日的 changelog 里发布了开源的 skills CLI，用来给各类 Agent 安装 Skill 包。只装这一份：
npx skills add vercel-labs/agent-skills --skill vercel-optimize
也可以装整个官方仓库：
npx skills add vercel-labs/agent-skills
指定工具时加 -a。例如只给 Claude Code 装到当前项目：
npx skills add vercel-labs/agent-skills --skill vercel-optimize -a claude-code
Cursor 对应 -a cursor，Codex CLI 对应 -a codex。加 -g 则装到用户全局目录。CLI 会按工具写入不同路径，官方对照如下：
| 工具 | 项目目录 | 全局目录 |
|---|---|---|
| Cursor | .agents/skills/ |
~/.cursor/skills/ |
| Claude Code | .claude/skills/ |
~/.claude/skills/ |
| Codex CLI | .agents/skills/ |
~/.codex/skills/ |
Cursor 文档 还会额外扫描 .cursor/skills/、~/.agents/skills/，并兼容 .claude/skills/、.codex/skills/。装好后，在 Agent 对话里输入 /vercel-optimize 可显式调用；描述匹配时 Agent 也会自动选用。
手动安装¶
官方 README 的手动方式是：把 skills/vercel-optimize 复制到 .agents/skills/vercel-optimize，并在项目的 AGENTS.md 里引用 SKILL.md。目录结构应类似：
.agents/skills/vercel-optimize/
├── SKILL.md
├── scripts/
├── references/
└── lib/
运行前的环境要求¶
Skill 本身写明了这些前置条件，缺一项就会在收集阶段停下：
- Node.js 20+
- Vercel CLI v53+，且支持
vercel metrics、vercel usage、vercel contract、vercel api（可用npm i -g vercel@latest） - 已登录：
vercel login - 当前应用目录已
vercel link。VERCEL_PROJECT_ID只能辅助解析项目配置，不能替代目录关联；vercel metrics仍然要求 link。项目、team/personal scope 必须一致，否则用量和路由指标可能跑到不同账号上 - 要做「按路由排序、有指标支撑」的建议，需要 Observability Plus
Vercel 文档说明：所有套餐都有基础 Observability；Observability Plus 面向付费 Pro 和 Enterprise，提供按路径拆分的延迟、缓存、ISR 等更细数据。Skill 把这项当成数据依赖，而不是推销升级：没有路由级指标时，它会停下来让你选择「先开通再重跑」或「接受有限的 scanner-only 审计」，不会偷偷退化成全仓扫代码。
另外，Skill 明确要求：不要把认证 token 写进可能被聊天记录回显的命令里，不要手打 VERCEL_TOKEN=...、--token ... 或 Authorization: Bearer ...。
典型用法¶
下面步骤均来自官方 README 和 SKILL.md，可以按这个顺序复现。
1. 确认项目已关联¶
在应用根目录：
vercel login
vercel link
如果已经知道项目名和目录，也可以：
vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# 团队项目再加上 --team <team-id-or-slug>
团队项目和个人项目的 scope 对不上时，Skill 会停下来问你要审计哪一个，而不会用当前 vercel whoami 的 team 去猜。
2. 对 Agent 发出优化请求¶
进入已 link 的 Vercel 项目目录，对编码 Agent 说：
optimize this Vercel project
官方验收标准很直接：Agent 应先收集指标。如果它一上来就读源码，或者只根据 vercel.json 猜问题，说明 Skill 没有被正确加载。
也可以说「帮我降低 Vercel 账单」「查一下又慢又贵的路由」「看看有没有缓存机会」，这些都写在 SKILL.md 的 description 触发条件里。
3. Agent 实际会跑的流水线¶
用户一般不用自己敲这些命令；了解流水线有助于判断 Agent 有没有按 Skill 执行。每次审计使用独立的运行目录，不复用上次的 brief、子任务输出和报告：
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"
默认预算是 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"
之后会做 deep-dive、核对候选、生成 brief、核实建议，最后渲染报告：
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"
渲染完成后，Agent 应原样输出 final-message.json.body，再附上完整 Markdown 报告。不要在面向用户的文案里暴露 passRate、quality 分数、sanitizer 轨迹、子 Agent 名称等实现细节。
4. 建议长什么样¶
doctrine.md 给出的合格形态是：一次运行大约 5–15 条建议；每条都对应具体路由或文件，以及具体指标；涉及代码时带修改前后示例，并至少有一条匹配当前框架版本的文档引用。
性能数字必须来自观测值，例如把 /api/products 的 95 分位耗时从 850ms 降到与同类已缓存路由接近的区间。成本只能用量级措辞（对照 vercel usage 映射成「以当前流量看，大约每月数百美元量级」这类说法），禁止写 $340/mo 这种精确节省额。输出阶段有 sanitizer 会剥掉面向用户字段里的 $N 字面量。
适用场景与注意事项¶
适合这些情况：
- 项目已经部署在 Vercel，并且最近 14 天有可观流量
- 技术栈是 Next.js、SvelteKit，或可以接受 Nuxt / 有限 Astro 覆盖
- 本机已登录 Vercel CLI，目录已
vercel link，需要按真实用量排优先级 - 希望拿到「建议 + 证据 + 暂不调查项」的完整报告，而不是一份反模式清单
使用前需要注意：
- 没有 Observability Plus，就没有按路由排序的完整审计。 基础 Observability 不够支撑
slow_route、uncached_route、cold_start、isr_overrevalidation这类门控。Skill 会停下来让你选择开通后重跑，或接受只能抓「与流量无关」代码问题的有限审计。 - 最近 14 天几乎没有流量时，路由指标会很稀疏。 官方失败文案会说明：仍可检查与流量无关的扫描项和项目设置，但无法给路由修复排序。
- Hono、Remix 以及未知框架默认不会继续。 用户确认后才能做有限的平台/代码审计，且路由级指标未必能映射回源文件。
- 不要把墙钟时间当成唯一问题。 对 Vercel Workflow 运行时端点（
/.well-known/workflow/v1/*），以及 SSE、流式、可恢复聊天这类故意长连接的路由，Skill 禁止仅因 duration 高就建议「缩短耗时」；必须有可避免的首字节前工作、高 CPU、重复调用或可移出用户路径的响应后工作。 - 鉴权、错误页、按地理位置变化的响应等，默认保持动态。 没有证据证明可安全缓存时，不会建议给这些路径加缓存。
- 已经在项目配置里的事实，不会再建议你「确认一下有没有开」。 例如 Fluid Compute 已经开启时，核实器会挡住「请启用 Fluid Compute」这类建议。
- 明确不在范围内的事： 单纯的产物体积（除非表现为冷启动、Fast Data Transfer 或 LCP/INP）、没有打到 Build Minutes 账单的构建变慢、安全漏洞与凭据轮换、合同折扣和席位对账。安全设置只有在同时也是成本杠杆时才会进入（例如 BotID 与机器人流量带来的边缘成本）。
小结¶
vercel-optimize 把「看 Vercel 账单和 Observability，再决定改哪条路由」写成了可在 Cursor、Claude Code、Codex CLI 等工具里复用的 Skill。它真正约束的是调查顺序：指标 → 确定性门控 → 限定文件 → 版本匹配的文档引用，避免 Agent 在仓库里凭反模式清单改一圈。
项目已部署、有流量、CLI 已关联时，在应用目录里说一句 optimize this Vercel project 即可。官方仓库与 Skill 目录：
https://github.com/vercel-labs/agent-skills/tree/main/skills/vercel-optimize
