JuliusBrussee/caveman-discover

Vous étiquetez les flux de travail LLM de ce dépôt pour Caveman Cloud. Un flux de travail est un job effectué par le code — « répondre à un ticket de support », « générer le résumé nocturne », « exécuter la suite d'évaluation » — pas une technologie. Chaque requête vers la passerelle peut porter une étiquette de flux de travail ; le trafic non étiqueté atterrit dans un seul seau unlabeled-workflow. Votre tâche : trouver les flux de travail, bien les nommer, câbler les étiquettes et vérifier que rien n'est cassé.

Cela modifie le code, donc cela passe par la revue normale de l'utilisateur : proposez d'abord le tableau, appliquez après accord de l'utilisateur. Relancer sur un dépôt déjà étiqueté ne doit rien changer (idempotent).

Cette compétence est invoquée par l'opérateur. Une observation unlabeled-traffic du Plan Cave est en lecture seule et ne crée pas de fichier d'avis, de proposition ou de PR en brouillon. Ne déduisez pas que la télémétrie a sélectionné un site d'appel ou autorisé une modification. Inventoriez le dépôt de manière indépendante, présentez le tableau d'étiquetage et attendez l'approbation de l'utilisateur avant de modifier le code.

Étape 1 — Inventorier les flux de travail

Parcourez le dépôt depuis ses points d'entrée, pas depuis ses imports :

• Gestionnaires HTTP/RPC qui appellent un LLM (directement ou via des couches)
• Tâches planifiées : définitions cron, consommateurs de files d'attente, workers, actions GitHub qui invoquent du code LLM
• Commandes CLI et scripts (scripts/, bin/, scripts package.json)
• Harnesses d'évaluation / de test qui consomment de vrais tokens
• Agents ou chaînes distincts dans un framework (chaque graphe LangGraph, chaque équipage, chaque définition d'agent est généralement son propre flux de travail)

Un flux de travail = un job qu'un humain nommerait. Dix sites d'appel dans le même gestionnaire de requête sont un seul flux de travail ; un helper llm.ts partagé utilisé par trois jobs est trois flux de travail (étiquetez chez les appelants, jamais dans le helper partagé).

Étape 2 — Les nommer

Grammaire du slug (la passerelle l'applique) : minuscule [a-z0-9_-], 1 à 96 caractères. Nommez le job, pas la technologie :

• Bon : support-reply, nightly-digest, pr-review, eval-suite, onboarding-email
• Mauvais : openai-calls (technologie), main (ne dit rien), SupportReply (invalide), johns-test-3 (ne vieillit pas)

Les noms sont presque permanents — les renommer plus tard divise l'historique des dépenses. Lorsque le but d'un job n'est pas clair à partir du code, déduisez le slug du nom de fichier et marquez-le review dans le tableau plutôt que d'inventer un but.

Étape 3 — Proposer, puis appliquer

Présentez ce tableau et demandez à continuer :

| workflow | job | où | comment il est étiqueté |
|---|---|---|---|
| support-reply | répond aux tickets entrants | src/bot/reply.ts:41 | defaultHeaders sur le client reply |
| nightly-digest | job de résumé à 02:00 | jobs/digest.ts:12 | en-tête sur le client digest |
| eval-suite (review) | scripts/eval.ts:8 — but déduit du nom de fichier | scripts/eval.ts:8 | variable d'environnement au moment de l'invocation |

Ensuite, câblez chaque étiquette avec le mécanisme le plus léger disponible à ce site d'appel :

• @caveman-ai/sdk / SDK caveman_cloud : option workflow par trace, ou defaultWorkflow sur le client qu'un service à job unique construit.
• SDKs de fournisseurs bruts (OpenAI/Anthropic/LangChain/LiteLLM/Vercel) : ajoutez "x-cave-workflow": "<slug>" au même bloc defaultHeaders / default_headers / extra_headers qui porte déjà x-cave-api-key. Client partagé utilisé par plusieurs jobs → passez l'en-tête par appel (chaque SDK ci-dessus accepte les surcharges d'en-tête par requête), ou donnez à chaque job son propre client léger.
• Agents de codage encapsulés (caveman wrap) : indicateur --workflow <slug> ou variable d'environnement CAVE_WORKFLOW=<slug> au site d'invocation (ligne cron, étape CI).
• HTTP brut : ajoutez l'en-tête x-cave-workflow à la requête.

Étiquetez les appelants, gardez le diff minimal, respectez le style du dépôt. Si un site d'appel n'est pas routé par la passerelle Caveman du tout, ne l'étiquetez pas — listez-le sous « non câblé » dans le rapport (les étiquettes ne voyagent que sur le trafic de la passerelle ; le câblage est le travail de la compétence caveman-setup).

Étape 4 — Vérifier

Exécutez ce que le dépôt utilise déjà pour exercer un chemin étiqueté (un test, un script de dev, une seule commande curl). Confirmez ensuite : la requête réussit toujours (la passerelle rejette une étiquette invalide avec le code 400 cave_invalid_request_header — corrigez le slug si c'est le cas). Les dépenses étiquetées apparaissent sur le tableau de bord à /activity?tab=workflows lorsque chaque flux de travail s'exécute ; les jobs planifiés s'affichent lorsque la planification se déclenche, et cela vaut la peine de le mentionner dans le rapport plutôt que de faire semblant qu'ils sont actifs.

Étape 5 — Rapport

## Flux de travail étiquetés

| workflow | job | où |
|---|---|---|
| support-reply | répond aux tickets entrants | src/bot/reply.ts:41 |
| nightly-digest | job de résumé à 02:00 | jobs/digest.ts:12 |

Vérifié : <le chemin étiqueté que vous avez réellement exercé, et ce que vous avez observé>
Atterrit sur : <TABLEAU_DE_BORD>/activity?tab=workflows — chaque ligne apparaît lorsque ce flux de travail s'exécute. Tout ce qui reste non étiqueté s'affiche comme `unlabeled-workflow`.
Non câblé (pas de routage par la passerelle, donc pas d'étiquette) : <liste ou « aucun »>
Marqué review : <slugs dont le but a été déduit des noms de fichiers, ou « aucun »>

Si vous n'avez trouvé aucun point d'entrée LLM : dites exactement cela et dirigez vers la compétence de configuration (<origine de la doc>/docs/agent-setup.md) au lieu de fabriquer un tableau.