Vercel 優化

Vercel 優化 是做什麼的？

執行以可觀測性為優先的 Vercel 優化審計。在 signals.json 存在且確定性門控指向路由、檔案或專案設定之前，請勿檢查原始碼檔案。

核心原則：若任何規則不明確，請參閱 references/doctrine.md。

• 指標優先：建議來自 Vercel 生產訊號，而非整個儲存庫的搜尋。
• 確定性門控：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 優化支援 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. 然後使用 questionText 提問，若主機支援結構化問題，則使用 questionPayload。
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 作為可見的工作者名稱，例如「/docs/llm-digest/[...slug] 路由的低快取命中率」，而非 toLaunch-7。

並行規則：

• 1-2 個簡報：直接內聯調查。
• 3 個以上簡報：若主機支援，則為每個簡報啟動一個子代理。
• 不支援子代理的主機：循序內聯執行。

子代理契約：

• 簡報即為完整的提示。
• 僅讀取簡報中列出的檔案，以及必要時的路由區域內匯入項。
• 使用 references/recommendations.md 輸出一個 JSON 建議或一個 JSON「無變更」發現。
• 請勿引用提供的引用子集之外的 URL。
• 請勿建議偵測到的版本中不可用的框架功能。

如果子代理試圖對整個儲存庫進行搜尋，則表示該候選項目格式錯誤；應放棄或棄權，而非擴大範圍。

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/秒。