前言¶
項目已經部署到 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
