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：

完全按照回傳內容印出 exactChatMessage.body。請勿摘要、截斷、重新排序或改寫。
然後使用 questionPayload 詢問 questionText（當主機支援結構化問題時）。
若使用者選擇不同數量，使用 --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 份以上簡報：若主機支援，為每份簡報產生一個子代理。
不支援子代理的主機：依序內聯執行。

子代理合約：

簡報即為完整提示。
僅讀取簡報中列出的檔案，以及必要時的路由本地匯入。
使用 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 已啟用」。

掃描器規則

掃描器發現為輔助性質。除非掃描器宣告 metadata.trafficIndependent === true，否則丟棄標註為 COLD-PATH 或 NO-ROUTE-MAPPING 的發現。

流量獨立範例：中介軟體匹配器、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 中很常見。我已呈現我能匹配的部分；其餘出現在「本次執行未調查」區段中。

您可能也喜歡

django-security

230Ksecurity

Django security best practices, authentication, authorization, CSRF protection, SQL injection prevention, XSS prevention, and secure deployment configurations.

affaan-m

獲取

security-and-hardening

77Ksecurity

強化程式碼以抵禦漏洞。在處理使用者輸入、驗證、資料儲存或外部整合時使用。在建立任何接受不受信任資料、管理使用者工作階段或與第三方服務互動的功能時使用。

addyosmani

獲取

api-security-best-practices

43Ksecurity

Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities