vercel-optimize

Vercel Optimize

Exécutez un audit d'optimisation Vercel axé sur l'observabilité. N'inspectez pas les fichiers source tant que signals.json n'existe pas et qu'une porte déterministe ne pointe pas vers une route, un fichier ou un paramètre de projet.

Doctrine de base : lisez references/doctrine.md si une règle n'est pas claire.

• Métriques d'abord. Les recommandations partent des signaux de production Vercel, pas d'une recherche grep à l'échelle du dépôt.
• Portes déterministes. scripts/gate-investigations.mjs décide ce qui mérite une investigation.
• Périmètre lié au candidat. Lisez uniquement les fichiers nommés par un candidat ou une chaîne d'import locale à la route.
• Citations tenant compte de la version. Utilisez uniquement references/docs-library.json ; les citations invalides ou avec une version incompatible sont supprimées.
• Ton client. Lisez references/voice.md avant d'écrire le texte du rapport ou la sortie du chat.

Prérequis

• Vercel CLI v53+ avec vercel metrics, vercel usage, vercel contract et vercel api.
• Session CLI authentifiée : vercel login.
• Répertoire d'application lié : vercel link. VERCEL_PROJECT_ID peut aider à résoudre la configuration du projet, mais vercel metrics nécessite toujours une liaison de répertoire. Le lien ou l'environnement doit inclure le périmètre org/équipe/utilisateur prévu afin que le collecteur puisse résoudre un --scope sûr pour le CLI et garder vercel metrics, vercel usage et vercel contract sur le même compte.
• Node.js 20+.
• Observability Plus pour des recommandations basées sur des métriques au niveau des routes.

Ne mettez jamais de jetons d'authentification dans les commandes shell. Ne tapez pas VERCEL_TOKEN=..., --token ..., ou Authorization: Bearer ... dans des commandes qui pourraient être répétées dans le chat.

Support des Frameworks

Le pré-contrôle lit package.json et définit les attentes avant le déploiement des métriques.

Framework	Statut	Notes
Next.js App Router	pris en charge	correspondance de route la plus forte, scanners, playbooks, citations
Next.js Pages Router	pris en charge	limité aux idiomes du Pages Router lorsqu'il est détecté
SvelteKit	pris en charge	correspondance de route pour les fichiers src/routes et scanner SvelteKit
Nuxt	pris en charge	correspondance de route et vérifications génériques/plateforme ; moins de recommandations spécifiques au framework
Astro	limité	correspondance de route et vérifications génériques ; moins de recommandations spécifiques au framework
Hono / Remix / inconnu	bloqué par défaut	continuez seulement si l'utilisateur accepte un audit de plateforme/code limité

Si non pris en charge, arrêtez-vous et demandez avant de scanner ou de passer les portes :

Ce projet utilise <framework>. Vercel Optimize prend en charge les recommandations de code basées sur les métriques pour Next.js, SvelteKit et Nuxt. Le support d'Astro est limité. Pour <framework>, je peux toujours exécuter un audit de plateforme/scanner limité, mais les métriques Vercel au niveau des routes peuvent ne pas correspondre aux fichiers source.

Voulez-vous que je continue avec l'audit limité, ou que je m'arrête là ?

Si l'utilisateur continue, relancez la collecte avec --continue-unsupported-framework.

Répertoire d'exécution

Utilisez un nouveau répertoire d'exécution pour chaque audit. Ne réutilisez pas les briefs, les sorties de sous-agents ou les rapports entre les exécutions.

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

Pipeline

1. Collecter, scanner et fusionner les signaux

Exécutez à partir du répertoire d'application lié ou passez --cwd là où un script le prend en charge. Gardez le JSON de stdout séparé des journaux de stderr. Ne combinez pas les flux.

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"

Les détails de collecte, les schémas, les ID de métriques et le comportement de dégradation se trouvent dans references/data-collection.md. Le registre des métriques est lib/queries.mjs ; gardez toutes les requêtes sur la fenêtre partagée de 14 jours.

collect-signals.mjs résout le propriétaire du projet lié en commandScope.cliScope et vérifie que le compte résolu peut lire le projet résolu avant de vérifier Observability Plus. Les scripts en aval réutilisent cette portée pour chaque commande Vercel CLI qui accepte --scope. N'exécutez pas vercel usage, vercel metrics ou vercel contract manuellement sans la même portée ; une utilisation sans portée peut signaler l'organisation personnelle de l'utilisateur tandis que les métriques de route proviennent du projet d'équipe.

Si la résolution du projet ou de la portée est ambiguë, arrêtez-vous et demandez à l'utilisateur quel projet Vercel et quelle portée équipe/personnelle il souhaite auditer. N'inférez pas la portée prévue de l'équipe vercel whoami actuelle, et ne procédez pas à la collecte de métriques, d'utilisation ou de contrat tant que le lien, une correspondance exacte du projet dans .vercel/repo.json, ou VERCEL_PROJECT_ID + VERCEL_ORG_ID n'identifie pas le compte prévu.

Utilisez cette invite pour PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED, ou PROJECT_SCOPE_MISMATCH :

Je ne peux pas identifier de manière fiable le projet Vercel et le compte pour cet audit pour l'instant.

Veuillez confirmer le nom ou l'ID du projet Vercel et le slug/nom de l'équipe, ou dites-moi s'il s'agit de votre compte personnel. Une fois confirmé, je relierai ou relancerai la collecte par rapport à cette portée exacte avant de vérifier les métriques.

1.1 Arrêt sur les bloqueurs

Vérifiez les bloqueurs avant de passer les portes :

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

Actions requises :

• frameworkSupportBlocker === "unsupported_framework" : utilisez l'invite pour framework non pris en charge ci-dessus.
• PROJECT_SCOPE_UNRESOLVED, SCOPE_UNRESOLVED, ou PROJECT_SCOPE_MISMATCH : arrêtez-vous et demandez quel projet Vercel et quelle portée équipe/personnelle l'utilisateur souhaite auditer. Pour les projets d'équipe, relancez après vercel link --yes --project <nom-ou-id-du-projet> --team <slug-de-l'équipe> ; pour les projets personnels, relancez après avoir lié sous le compte utilisateur prévu ou après avoir défini à la fois VERCEL_PROJECT_ID et VERCEL_ORG_ID.
• observabilityPlusBlocker === null : continuez.
• no_traffic : dites à l'utilisateur que les métriques de route sont rares ; continuez seulement s'il accepte une sortie limitée.
• payment_required ou no_oplus_probe : affichez references/observability-plus.md textuellement et demandez.
• project_disabled : dites à l'utilisateur d'activer Observability Plus pour le projet ou d'accepter un audit limité.
• daily_quota_exceeded : arrêtez-vous et dites à l'utilisateur que le quota de requêtes d'observabilité est épuisé ; réessayez après la réinitialisation à minuit UTC suivante, ou demandez s'il souhaite continuer avec un audit de code uniquement limité.
• not_linked : liez le répertoire de l'application, puis relancez l'étape 1. Si le chemin de l'application et le projet sont connus :

vercel link --yes --project <nom-ou-id-du-projet> --cwd <répertoire-app>
# ajoutez --team <id-ou-slug-de-l'équipe> si connu

• forbidden ou project_not_found : corrigez la portée d'authentification/équipe. Ne vendez pas Observability Plus.
• all_failed_other : affichez le code d'erreur brut et demandez s'il faut continuer en mode code uniquement limité.

Ne basculez pas silencieusement en mode code uniquement. Si l'utilisateur accepte un audit limité, relancez la collecte avec :

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

Scannez et fusionnez à nouveau.

2. Passer les portes des candidats

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

Forme de la sortie :

• toLaunch : candidats de portée de code à investiguer.
• platform : recommandations de portée projet/compte.
• gated : candidats ignorés, couverts ou disqualifiés qui doivent toujours apparaître dans le rapport.
• budget : budget des candidats et mode de sélection.

Le budget par défaut est de 6 candidats de portée de code avec une barrière de diversité. Pour l'étendre :

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"

Documents générés sur les candidats : references/candidates.md.

2.1 Demander le périmètre de l'audit si nécessaire

Avant l'analyse approfondie, exécutez :

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

Si shouldAsk est false, continuez.

Si shouldAsk est true :

1. Imprimez exactChatMessage.body exactement comme retourné. Ne résumez pas, ne tronquez pas, ne réordonnez pas et ne réécrivez pas.
2. Puis demandez questionText en utilisant questionPayload lorsque l'hôte prend en charge les questions structurées.
3. Si l'utilisateur choisit un nombre différent, relancez la porte avec --max-candidates <choix>.

Ne mettez jamais la longue prévisualisation dans le champ de question. La prévisualisation et la question sont des surfaces séparées.

2.2 Analyse approfondie et réconciliation

node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <répertoire-projet> > "$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 doit être le répertoire du projet lié afin que deep-dive.mjs puisse vérifier le même lien de projet et réutiliser signals.json.commandScope.cliScope pour tout appel vercel metrics de suivi.

La réconciliation convertit de manière déterministe les candidats réfutés en observations avant toute investigation du code source :

• metric_mismatch
• error_storm
• deployment_regression
• scanner_only_no_metric

2.3 Générer des briefs et investiguer

Listez le travail :

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

Générez un brief pour chaque entrée dans briefs-manifest.json.briefs. Le group peut être toLaunch ou platform ; ne générez pas uniquement les briefs 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"

Utilisez briefs-manifest.json.briefs[].label pour les noms de workers visibles, par exemple Route à faible taux de cache sur /docs/llm-digest/[...slug], pas toLaunch-7.

Règle de déploiement :

• 1-2 briefs : investiguez en ligne.
• 3+ briefs : générez un sous-agent par brief lorsque l'hôte le prend en charge.
• Hôtes sans sous-agents : exécutez en série en ligne.

Contrat du sous-agent :

• Le brief est l'intégralité de l'invite.
• Lisez uniquement les fichiers listés dans le brief, plus les imports locaux à la route si nécessaire.
• Émettez une recommandation JSON ou un constat JSON de non-modification en utilisant references/recommendations.md.
• Ne citez pas d'URL en dehors du sous-ensemble de citations fourni.
• Ne recommandez pas de fonctionnalités de framework indisponibles dans la version détectée.

Si un sous-agent cherche à faire une recherche grep à l'échelle du dépôt, le candidat est mal formé ; abandonnez ou abstenez-vous plutôt que d'élargir le périmètre.

2.4 Collecter les sorties

Enregistrez chaque résultat d'investigation brut dans $RUN_DIR/sub-agent-outputs/, puis collectez :

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

Le collecteur extrait le JSON, préfixe les enregistrements pré-résolus, applique l'ordre du manifeste et échoue en cas de valeurs candidateRef manquantes, en double, inconnues ou non concordantes.

3. Vérifier les recommandations

node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
  --signals "$RUN_DIR/signals.json" \
  --repo-root <répertoire-projet> \
  --out "$RUN_DIR/verify.json"

Ce script extrait les affirmations, vérifie l'adéquation des fichiers/citations/versions, note la qualité, applique les correctifs, émet verifiedRecommendations, withheldRecommendations, renderableRecommendations, et crée regenPlan pour les recommandations ayant échoué ou non sécurisées.

Schéma des recommandations, règles d'écriture, ordre des correctifs et règles de notation : references/recommendations.md. Règles de vérification : references/verification.md.

Pour chaque entrée de regenPlan, relancez le même brief avec une section La tentative précédente a échoué à ces vérifications listant topFailures. Ne conservez la sortie régénérée que si la vérification s'améliore sans vider les citations.

4. Rendre le rapport et le message final

node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
  --project <nom> \
  --out "$RUN_DIR/report.md" \
  --message-out "$RUN_DIR/final-message.json"

Utilisez --debug-out "$RUN_DIR/debug.json" uniquement lors du développement de la compétence. Le Markdown client et la sortie du chat ne doivent pas exposer passRate, quality, les pistes de correctifs, les noms bruts des sous-agents ou d'autres champs d'implémentation.

Après le rendu, imprimez final-message.json.body textuellement et arrêtez-vous. N'ajoutez pas de points forts, de notes de débogage, de décomptes bruts, de résumés de sous-agents ou d'explications supplémentaires. La déduplication au moment du rendu, les limites de plateforme et les suppressions de sécurité dures peuvent modifier le nombre visible par le client, donc ne résumez jamais à partir du verify.json brut.

Structure du rapport et cadrage de l'impact : references/scoring.md.

Règles de recommandation

Chaque recommandation doit :

• Remonter à un candidat lancé, un candidat de plateforme, une observation pré-résolue ou un résultat de scanner vérifié indépendant du trafic.
• Inclure les preuves métriques observées de signals.json ou evidence.deepDive.
• Citer des fichiers vérifiés avec des numéros de ligne lorsque du code est impliqué.
• Inclure au moins une citation autorisée qui s'applique au framework/version détecté.
• Utiliser des nombres de performance observés précis.
• Utiliser des phrases de magnitude de coût uniquement ; jamais d'économies $N visibles par le client.
• Ne pas recommander de réductions de durée pour les points de terminaison d'exécution de workflow Vercel (/.well-known/workflow/v1/*). Ce sont des routes d'orchestration générées pour l'exécution durable d'étapes/flux et doivent être bloquées avant l'investigation.
• Les recommandations de workflow doivent nommer la limite modifiée. Exemples valides : mettre en file d'attente un travail durable et retourner un ID d'exécution au lieu d'attendre la fin, corriger la relecture/fermeture/verrous du flux, ou réduire les étapes/exécutions de workflow excédentaires vérifiées.