vercel-optimize

Vercel Optimize

Führe ein beobachtungsbasiertes Vercel-Optimierungs-Audit durch. Untersuche keine Quelldateien, bevor nicht signals.json existiert und eine deterministische Prüfung auf eine Route, Datei oder Projekteinstellung verweist.

Kernregel: Lies references/doctrine.md, falls eine Regel unklar ist.

• Metriken zuerst. Empfehlungen basieren auf Vercel-Produktionssignalen, nicht auf einem Repo-weiten Grep.
• Deterministische Prüfungen. scripts/gate-investigations.mjs entscheidet, was untersucht wird.
• Kandidatenbezogener Umfang. Lies nur Dateien, die von einem Kandidaten oder einer routenlokalen Importkette benannt werden.
• Versionsbewusste Quellenangaben. Verwende ausschließlich references/docs-library.json; ungültige oder versionsinkonsistente Zitate werden entfernt.
• Kundennahe Ausgabe. Lies references/voice.md, bevor du Berichtstexte oder Chat-Ausgaben verfasst.

Voraussetzungen

• Vercel CLI v53+ mit vercel metrics, vercel usage, vercel contract und vercel api.
• Authentifizierte CLI-Sitzung: vercel login.
• Verknüpftes App-Verzeichnis: vercel link. VERCEL_PROJECT_ID kann bei der Projektkonfiguration helfen, aber vercel metrics benötigt weiterhin eine Verzeichnisverknüpfung. Die Verknüpfung oder Umgebung muss den beabsichtigten Projekt-Organisations-/Team-/Benutzerbereich umfassen, damit der Collector ein CLI-sicheres --scope auflösen und vercel metrics, vercel usage und vercel contract im selben Konto halten kann.
• Node.js 20+.
• Observability Plus für routenbezogene, metrikgestützte Empfehlungen.

Setze niemals Authentifizierungstoken in Shell-Befehle ein. Gib VERCEL_TOKEN=..., --token ... oder Authorization: Bearer ... nicht in Befehle ein, die möglicherweise im Chat angezeigt werden.

Framework-Unterstützung

Der Preflight liest package.json und setzt Erwartungen vor der Metrikausbreitung.

Framework	Status	Hinweise
Next.js App Router	unterstützt	Stärkste Routenzuordnung, Scanner, Playbooks, Zitate
Next.js Pages Router	unterstützt	Auf Pages-Router-Idiome beschränkt, wenn erkannt
SvelteKit	unterstützt	Routenzuordnung für src/routes Dateien und SvelteKit-Scanner
Nuxt	unterstützt	Routenzuordnung sowie generische/Plattformprüfungen; weniger frameworkspezifische Empfehlungen
Astro	eingeschränkt	Routenzuordnung sowie generische Prüfungen; weniger frameworkspezifische Empfehlungen
Hono / Remix / unbekannt	standardmäßig blockiert	Nur fortfahren, wenn der Benutzer ein eingeschränktes Plattform-/Code-Audit akzeptiert

Wenn nicht unterstützt, anhalten und vor dem Scannen oder Prüfen fragen:

Dieses Projekt verwendet <Framework>. Vercel Optimize unterstützt metrikgestützte Codeempfehlungen für Next.js, SvelteKit und Nuxt. Astro-Unterstützung ist eingeschränkt. Für <Framework> kann ich dennoch ein eingeschränktes Plattform-/Scanner-Audit durchführen, aber die routenbezogenen Vercel-Metriken lassen sich möglicherweise nicht auf Quelldateien abbilden.

Möchten Sie mit dem eingeschränkten Audit fortfahren oder hier anhalten?

Wenn der Benutzer fortfährt, die Sammlung mit --continue-unsupported-framework erneut ausführen.

Ausführungsverzeichnis

Für jedes Audit ein neues Ausführungsverzeichnis verwenden. Keine Briefings, Sub-Agent-Ausgaben oder Berichte wiederverwenden.

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

Pipeline

1. Signale sammeln, scannen und zusammenführen

Vom verknüpften App-Verzeichnis aus ausführen oder --cwd übergeben, falls ein Skript dies unterstützt. stdout-JSON getrennt von stderr-Logs halten. Streams nicht zusammenführen.

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"

Details zur Sammlung, Schemas, Metrik-IDs und Degradationsverhalten finden sich in references/data-collection.md. Das Metrikregister ist lib/queries.mjs; alle Abfragen im gemeinsamen 14-Tage-Fenster halten.

collect-signals.mjs löst den verknüpften Projektbesitzer zu commandScope.cliScope auf und verifiziert, dass das aufgelöste Konto das aufgelöste Projekt lesen kann, bevor es Observability Plus prüft. Nachgelagerte Skripte verwenden diesen Bereich für jeden Vercel-CLI-Befehl, der --scope akzeptiert. vercel usage, vercel metrics oder vercel contract nicht manuell ohne denselben Bereich ausführen; unbereinigte Nutzung kann die persönliche Organisation des Benutzers melden, während Routenmetriken vom Teamprojekt stammen.

Wenn die Projekt- oder Bereichsauflösung mehrdeutig ist, anhalten und den Benutzer fragen, welches Vercel-Projekt und welcher Team-/Persönlicher Bereich auditiert werden soll. Nicht den beabsichtigten Bereich aus dem aktuellen vercel whoami-Team ableiten und nicht mit der Sammlung von Metriken, Nutzung oder Vertrag fortfahren, bis die Verknüpfung (link), eine genaue Projektübereinstimmung in .vercel/repo.json oder VERCEL_PROJECT_ID + VERCEL_ORG_ID das beabsichtigte Konto identifizieren.

Diese Eingabeaufforderung für PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED oder PROJECT_SCOPE_MISMATCH verwenden:

Ich kann das Vercel-Projekt und -Konto für dieses Audit noch nicht sicher identifizieren.

Bitte bestätigen Sie den Vercel-Projektnamen oder die ID und den Team-Slug/Namen, oder teilen Sie mir mit, dass es sich unter Ihrem persönlichen Konto befindet. Nach der Bestätigung verknüpfe ich neu oder führe die Sammlung erneut für diesen genauen Bereich aus, bevor ich die Metriken prüfe.

1.1 Bei Blockern anhalten

Blocker vor der Prüfung überprüfen:

jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"

Erforderliche Aktionen:

• frameworkSupportBlocker === "unsupported_framework": Die Eingabeaufforderung für nicht unterstützte Frameworks oben verwenden.
• PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED oder PROJECT_SCOPE_MISMATCH: Anhalten und fragen, welches Vercel-Projekt und welcher Team-/Persönlicher Bereich auditiert werden soll. Für Teamprojekte nach vercel link --yes --project <project-name-or-id> --team <team-slug> erneut ausführen; für persönliche Projekte nach der Verknüpfung unter dem beabsichtigten Benutzerkonto oder nach Setzen von VERCEL_PROJECT_ID und VERCEL_ORG_ID erneut ausführen.
• observabilityPlusBlocker === null: Fortfahren.
• no_traffic: Dem Benutzer mitteilen, dass Routenmetriken spärlich sind; nur fortfahren, wenn der Benutzer eine eingeschränkte Ausgabe akzeptiert.
• payment_required oder no_oplus_probe: references/observability-plus.md wörtlich wiedergeben und fragen.
• project_disabled: Dem Benutzer mitteilen, Observability Plus für das Projekt zu aktivieren oder ein eingeschränktes Audit zu akzeptieren.
• daily_quota_exceeded: Anhalten und dem Benutzer mitteilen, dass das Observability-Abfragekontingent erschöpft ist; nach dem nächsten UTC-Mitternacht-Reset erneut versuchen oder fragen, ob mit einem eingeschränkten Code-Only-Audit fortgefahren werden soll.
• not_linked: Das App-Verzeichnis verknüpfen, dann Schritt 1 erneut ausführen. Wenn App-Pfad und Projekt bekannt sind:

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# add --team <team-id-or-slug> when known

• forbidden oder project_not_found: Authentifizierungs-/Team-Bereich korrigieren. Kein Observability Plus anpreisen.
• all_failed_other: Den rohen Fehlercode anzeigen und fragen, ob im eingeschränkten Code-Only-Modus fortgefahren werden soll.

Nicht stillschweigend in den Code-Only-Modus zurückfallen. Wenn der Benutzer ein eingeschränktes Audit akzeptiert, die Sammlung erneut ausführen mit:

node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"

Dann erneut scannen und zusammenführen.

2. Kandidaten prüfen

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"

Ausgabeform:

• toLaunch: Codebezogene Kandidaten zur Untersuchung.
• platform: Projekt-/Kontoübergreifende Empfehlungen.
• gated: Übersprungene, abgedeckte oder disqualifizierte Kandidaten, die dennoch im Bericht erscheinen müssen.
• budget: Kandidatenbudget und Auswahlmodus.

Standardbudget sind 6 Code-bezogene Kandidaten mit einer Diversitätsbegrenzung. Zum Erweitern:

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"

Generierte Kandidatendokumentation: references/candidates.md.

2.1 Bei Bedarf nach Audit-Umfang fragen

Vor der Tiefenanalyse ausführen:

node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"

Wenn shouldAsk false ist, fortfahren.

Wenn shouldAsk true ist:

1. exactChatMessage.body genau wie zurückgegeben ausgeben. Nicht zusammenfassen, kürzen, umstellen oder umschreiben.
2. Dann questionText mit questionPayload fragen, wenn der Host strukturierte Fragen unterstützt.
3. Wenn der Benutzer eine andere Anzahl wählt, das Gate mit --max-candidates <choice> erneut ausführen.

Die lange Vorschau niemals in das Fragefeld setzen. Die Vorschau und die Frage sind separate Oberflächen.

2.2 Tiefenanalyse und Abgleich

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 muss das verknüpfte Projektverzeichnis sein, damit deep-dive.mjs die gleiche Projektverknüpfung verifizieren und signals.json.commandScope.cliScope für nachfolgende vercel metrics-Aufrufe wiederverwenden kann.

Der Abgleich wandelt widerlegte Kandidaten deterministisch in Beobachtungen um, bevor eine Quellcode-Untersuchung stattfindet:

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 Briefings erstellen und untersuchen

Die Arbeit auflisten:

node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" --list > "$RUN_DIR/briefs-manifest.json"

Ein Briefing für jeden Eintrag in briefs-manifest.json.briefs erstellen. Die group kann toLaunch oder platform sein; nicht nur toLaunch-Briefings erstellen.

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 für sichtbare Workernamen verwenden, z. B. Low cache-hit route on /docs/llm-digest/[...slug], nicht toLaunch-7.

Faustregel:

• 1-2 Briefings: Inline untersuchen.
• 3+ Briefings: Pro Briefing einen Sub-Agenten starten, wenn der Host dies unterstützt.
• Hosts ohne Sub-Agenten: Inline seriell ausführen.

Sub-Agenten-Vertrag:

• Das Briefing ist die gesamte Eingabeaufforderung.
• Nur Dateien lesen, die im Briefing aufgeführt sind, sowie routenlokale Importe, wenn nötig.
• Eine JSON-Empfehlung oder einen JSON-Befund "Keine Änderung" ausgeben, unter Verwendung von references/recommendations.md.
• Keine URLs außerhalb des bereitgestellten Zitatbestands zitieren.
• Keine Framework-Funktionen empfehlen, die in der erkannten Version nicht verfügbar sind.

Wenn ein Sub-Agent zu einem Repo-weiten Grep greift, ist der Kandidat fehlerhaft; ablehnen oder enthalten, anstatt den Umfang zu erweitern.

2.4 Ausgaben sammeln

Jedes rohe Untersuchungsergebnis in $RUN_DIR/sub-agent-outputs/ speichern, dann sammeln:

node scripts/collect-sub-agent-outputs.mjs \
  --manifest "$RUN_DIR/briefs-manifest.json" \
  --out "$RUN_DIR/recommendations.json" \
  "$RUN_DIR/sub-agent-outputs/"

Der Collector extrahiert JSON, stellt vorab aufgelöste Datensätze voran, erzwingt die Manifest-Reihenfolge und schlägt bei fehlenden, doppelten, unbekannten oder falschen candidateRef-Werten fehl.

3. Empfehlungen verifizieren

node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
  --signals "$RUN_DIR/signals.json" \
  --repo-root <project-dir> \
  --out "$RUN_DIR/verify.json"

Dieses Skript extrahiert Behauptungen, überprüft Dateien/Zitate/Versionseignung, bewertet die Qualität, wendet Bereinigungen an, gibt verifiedRecommendations, withheldRecommendations, renderableRecommendations aus und erstellt regenPlan für fehlgeschlagene oder unsichere Empfehlungen.

Empfehlungsschema, Schreibregeln, Bereinigungsreihenfolge und Bewertungsregeln: references/recommendations.md. Verifizierungsregeln: references/verification.md.

Für jeden regenPlan-Eintrag das gleiche Briefing mit einem Abschnitt Previous attempt failed these checks und dem Feld topFailures erneut ausführen. Die regenerierte Ausgabe nur behalten, wenn die Verifizierung verbessert wird, ohne die Zitate zu entkernen.

4. Bericht und finale Nachricht rendern

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" nur bei der Entwicklung des Skills verwenden. Kunden-Markdown und Chat-Ausgabe dürfen passRate, quality, Bereinigungspfade, rohe Sub-Agent-Namen oder andere Implementierungsfelder nicht offenlegen.

Nach dem Rendern final-message.json.body wörtlich ausgeben und anhalten. Keine Highlights, Debug-Hinweise, rohe Zählungen, Sub-Agent-Zusammenfassungen oder zusätzliche Erklärungen hinzufügen. Renderzeit-Deduplizierung, Plattform-Obergrenzen und Härtungsaussetzer können die kundensichtbare Anzahl ändern, daher niemals aus rohem verify.json zusammenfassen.

Berichtsstruktur und Auswirkungsdarstellung: references/scoring.md.

Empfehlungsregeln

Jede Empfehlung muss:

• Auf einen gestarteten Kandidaten, Plattformkandidaten, vorab aufgelösten Beobachtung oder verifizierten verkehrsunabhängigen Scannerbefund zurückgehen.
• Nachgewiesene Metrikbeweise aus signals.json oder evidence.deepDive enthalten.
• Verifizierte Dateien mit Zeilennummern zitieren, wenn Code betroffen ist.
• Mindestens ein zulässiges Zitat enthalten, das auf das erkannte Framework/Version zutrifft.
• Präzise beobachtete Leistungszahlen verwenden.
• Nur Kostenmagnitude-Phrasen verwenden; niemals kundenseitige $N Einsparungen.
• Keine Dauerreduzierungen für Vercel Workflow-Laufzeitendpunkte (/.well-known/workflow/v1/*) empfehlen. Dies sind generierte Orchestrierungsrouten für dauerhafte Schritt-/Ablaufausführung und sollten vor der Untersuchung hart gesperrt werden.
• Workflow-Empfehlungen müssen die geänderte Grenze benennen. Gültige Beispiele: Enqueue dauerhafte Arbeit und eine Lauf-ID zurückgeben, anstatt auf die Fertigstellung zu warten; Stream-Wiederholung/-Schließung/-Sperren beheben; oder verifizierte übermäßige Workflow-Schritte/dauerhafte Ausführung möglicherweise verkürzen.

Beitragsanleitung

...

(Weitere Abschnitte bleiben in der deutschen Übersetzung erhalten, ohne neue Inhalte hinzuzufügen.)