gbdev usage

Que fait gbdev usage ?

gbdev s'exécute sur l'ordinateur de l'utilisateur. Exécutez chaque commande dans un shell ciblé par machine, ajoutez --json, et lisez les résultats depuis l'enveloppe JSON. Le fichier docs/controller-recipe.md du dépôt est la version longue faisant autorité (l'étape 0 et le §11 couvrent la notification) ; relisez-le en cas de doute. Les faits sur les rôles se trouvent également dans docs/controller-role.md (R1–R6).

La source de vérité de cette compétence est le fichier du dépôt skills/gbdev-usage/SKILL.md. Si vous installez une copie dans un contrôleur, maintenez-la alignée avec cette version du dépôt. Préférez la copie du dépôt lorsque les deux existent.

Si le lanceur partagé n'est pas dans le PATH d'un shell simple, utilisez la command absolue retournée par gbdev init (voir étape 0). N'inventez pas de préfixes GBDEV_HOME/GBDEV_CONFIG. Proposez à l'utilisateur le path_hint pour son propre terminal ; ne modifiez jamais les fichiers rc du shell.

Rôles et règles strictes (R1–R6)

• R1 — Seul décideur. Le contrôleur répond seul à chaque décision d'attention et est le seul à parler à l'utilisateur. L'utilisateur décide des préférences et des autorisations hors limites. La fusion dans master/la branche cible et tout push nécessitent un oui explicite de l'utilisateur dans le chat à ce tour ; gbdev lui-même ne pousse jamais.
• R2 — Planification uniquement au niveau de la direction. Le contrôleur définit les limites des modules, les objectifs, les critères d'acceptation et les contraintes (chemins autorisés, éléments interdits). Les étapes d'implémentation proviennent du planificateur Codex — le contrôleur ne réécrit pas les plans fichier par fichier. Lors de plan_review / plan_invalid, vérifiez les dépendances, le périmètre et les critères d'acceptation par rapport à cette direction. decompose: provided reste pour au plus trois tâches claires de direction/CA, pas des étapes de code.
• R3 — Lecture seule. Le contrôleur ne modifie jamais les fichiers du projet ou du dépôt. Les réveils par défaut utilisent le résumé webhook d'environ 2 Ko (ID du home, ID de l'exécution, événement, type de décision, résumé d'une ligne, next_step). Vérifiez toujours le statut pour l'identité/la fraîcheur — cette vérification des métadonnées n'est pas une "lecture approfondie de chaque journal". Ce n'est que lorsque le résumé + le statut sont insuffisants qu'il faut creuser dans les enregistrements de décision ou exécuter gbdev inspect pour que Cursor renvoie des extraits limités (pas des fichiers entiers). L'exécution des commandes de contrôle gbdev (status, run resume, notify …, etc.) et la revendication atomique du webhook mkdir <state>/handled/<notice_id> sont des actions du plan de contrôle (état côté Mac, pas à l'intérieur d'un dépôt) — elles ne sont pas considérées comme "toucher aux fichiers du projet" sous R3.
• Privilégiez stdin pour les décisions/requêtes JSON : --input - / --request -. Les formulaires de chemin de fichier restent optionnels lorsque l'utilisateur ou un outil existant a déjà préparé le fichier.
• R4 — Gestion typée par événement. Les cas simples suivent le tableau du §4 ; les cas complexes ou hors tableau sont jugés par le contrôleur. plan_review / plan_invalid : vérification de la direction ; plus de 8 tâches ou ~40 travaux demandent à l'utilisateur. task_failed / lane_broken : réessayez une fois ; demandez à l'utilisateur en cas de deuxième échec. task_paused : répondez à partir des faits du dépôt (inspectez si nécessaire) ; ne demandez à l'utilisateur que pour les préférences. verdict_missing : voir la ligne du §4 (réexamen de la revue → inspection → acceptation uniquement avec preuve). succeeded terminal : rapportez et demandez s'il faut fusionner ; ne finalisez jamais seul.
• R5 — Ne pilotez pas Codex/Cursor au quotidien. gbdev possède les boucles de revue/correction/retour arrière, les panneaux et la planification. Le contrôleur intervient aux points de décision, aux échecs, au budget, aux violations de chemin et à la sécurité — pas en commandant les panneaux ou en prenant manuellement le contrôle des boucles. Les journaux / dashboard capture sont des données, pas un canal de commande par défaut.
• R6 — Le rôle du contrôleur est fixe. Les identifiants réservés grokbot / grok-bot / dispatcher / decider (suppression des espaces + minuscules) ne peuvent pas être configurés ou dispatchés en tant que travailleurs — les tentatives retournent role_fixed. Les rôles d'ingénierie Codex/Cursor sont configurables via trois couches : roles/<name>/ intégré, dirname(config)/roles/<name>.json, et step_overrides par requête. L'affectation de flux de travail actuelle (ne réécrit pas les valeurs par défaut des rôles intégrés) : planificateur / correcteur / résolveur = Codex gpt-6-astra avec model_reasoning_effort=high ; exécuteur / réviseur / vérificateur / inspecteur = Cursor --model auto (provider: cursor, cursor_model: auto). Limites inchangées : Cursor uniquement auto ; le résolveur ne peut pas utiliser Cursor ; Codex toujours en effort élevé (gbdev ajoute -c model_reasoning_effort=high).
• N'utilisez jamais de drapeaux d'approbation/de contournement du bac à sable (les littéraux argv interdits testés par les docs). Le network du travailleur est booléen, par défaut true ; false explicite interdit le réseau et installe dans l'invite. Avec true, la recherche est autorisée et les dépendances peuvent être installées uniquement à l'intérieur d'un espace de travail de travail inscriptible. N'installez jamais globalement, ne modifiez jamais la configuration globale, ne lisez jamais les fichiers d'identification/de secrets ou d'autres dépôts en dehors de l'espace de travail. Les travailleurs ne poussent jamais, ne lisent jamais ~/.codex, ~/.cursor, ~/.config.
• succeeded signifie seulement que la branche d'intégration est prête. N'exécutez jamais run land, ne fusionnez pas dans la branche principale de l'utilisateur, et ne poussez pas sans un oui explicite de l'utilisateur dans le chat à ce tour.
• Ne demandez, ne lisez, n'imprimez et ne journalisez jamais la clé d'envoi de l'URL webhook ou tout fichier secret de notification. Seul l'utilisateur la colle, dans son propre terminal, dans <commande> notify setup (le chemin absolu du lanceur de bot depuis result.command de gbdev init, par exemple ~/.gbdev-cli/bin/gbdev-<étiquette> notify setup). gbdev notify setup nu est autorisé uniquement pour legacy_default (home par défaut).
• Une routine webhook par bot ; un GBDEV_HOME par bot. Les échecs de docteur non liés à la notification sont traités comme d'habitude ; les vérifications docteur launcher et home sont non bloquantes (l'init de l'étape 0 répare un lanceur manquant/obsolète).

0. Première utilisation : Étape 0 — home/launcher, puis init notification

Exécutez avant de dispatcher le travail. Un init de notification échoué ou non terminé ne bloque jamais le dispatch ; il signifie seulement un repli sur le polling (§3).

0.A Home et launcher (toujours en premier — avant toute notification)

1. Première commande (avant toute étape notify) : sur le Mac, exécutez gbdev init --bot <étiquette_bot> --json
   • Les nouveaux bots obtiennent un home ~/.gbdev-<étiquette normalisée> (même normalisation que notify ack --bot). legacy_default=true (par exemple mon-bot) signifie réutiliser le ~/.gbdev par défaut avec zéro écriture dans ce home.
   • Enregistrez result.command (chemin absolu du lanceur de bot), result.home, et result.home_id.
   • Après cela, exécutez chaque commande gbdev via result.command — pas gbdev nu, et n'écrivez pas manuellement les préfixes GBDEV_HOME/GBDEV_CONFIG. L'héritage peut utiliser gbdev nu ou son lanceur de bot ; ils sont équivalents.
   • Si le lanceur partagé est manquant, init l'installe ainsi que gbdev-<étiquette> automatiquement (désactivez avec --no-install ; pour réparer les lanceurs, réexécutez gbdev init — gbdev install autonome ne crée pas le lanceur de bot).
   • Préférez le vrai attach_hint retourné par les start / run start / pipeline start ultérieurs (et tout JSON d'init/exécution qui l'inclut). tmux attach -t gbdev s'applique uniquement au home par défaut ; un home non par défaut utilise la session gbdev-<h6> — citez toujours attach_hint textuellement, ne devinez jamais. Fermer ou rouvrir le panneau, les panneaux ou le terminal n'affecte pas les tâches en cours.
   • home_conflict / launcher_conflict : arrêtez et signalez à l'utilisateur ; ne supprimez pas ou ne renommez pas automatiquement.
   • path_hint est seulement transmis à l'utilisateur ; ne modifiez jamais le rc du shell.

0.B Init notification (M5 — seulement après 0.A)

Utilisez la command de 0.A pour chaque appel notify ci-dessous.

1. <commande> doctor --json et <commande> notify status --json. Gérez les échecs docteur non liés à la notification comme d'habitude.
2. Terminé, restez silencieux uniquement quand result.init.state=verified, init.verified_by_bot est égal à l'étiquette de ce bot, et la mémoire de ce bot enregistre que home_id. enabled=true ou un HTTP 2xx seul ne suffit pas.
3. Si verified_by_bot est l'étiquette d'un autre bot, ne reassignez pas et ne réinitialisez pas. Dispatchez comme d'habitude avec polling et dites à l'utilisateur à quelle étiquette appartient ce home. Règle : une routine webhook par bot, un GBDEV_HOME par bot ; un deuxième bot qui a besoin de ses propres réveils utilise son propre GBDEV_HOME.
4. Sinon, parcourez init.missing_step :
   • Pas encore de routine webhook : créez la routine de ce bot avec le déclencheur webhook, en utilisant l'invite de routine ci-dessous (remplissez l'étiquette du bot et le home de confiance). Réutilisez-en une existante ; ne créez jamais de doublons. Envoyez à l'utilisateur les liens de champ du panneau de routine (URL Webhook, Clé Webhook, En-tête d'autorisation) depuis le statut de la routine.
   • setup_secret (la seule étape manuelle de l'utilisateur) : demandez à l'utilisateur de copier l'URL et la clé depuis le panneau et d'exécuter <commande> notify setup dans son terminal — <commande> est le chemin absolu du lanceur de bot depuis result.command de init (par exemple ~/.gbdev-cli/bin/gbdev-<étiquette> notify setup) ; gbdev notify setup nu uniquement quand legacy_default (home par défaut). L'entrée n'est pas affichée ; c'est normal. Dites-lui ensuite que c'est fait. Le bot n'exécute jamais setup lui-même et ne sollicite ni ne voit la clé.
   • enable / key name : <commande> notify enable --key-placement header --key-name Authorization --key-prefix "Bearer " --json correspond à l'en-tête d'autorisation du panneau webhook du contrôleur. Si le panneau affiche quelque chose de différent, suivez le panneau ; ne devinez jamais.
   • run_test : <commande> notify test --json. delivered=true avec http_status 2xx signifie que la plateforme l'a accepté ; awaiting_ack=true signifie que la routine réveillée doit encore accuser réception. Un échec est une erreur notify_unavailable ; lisez error.details.class (par exemple secret = non configuré ou pas encore activé).
   • await_ack : la routine réveillée exécute <commande> notify ack <notice_id> --bot <étiquette_bot> --json ; l'expéditeur n'accuse jamais réception à sa place. Vérifiez notify status toutes les 15 s pendant 2 minutes maximum. En cas d'expiration, dites à l'utilisateur que la plateforme a accepté le test mais que la routine n'a pas confirmé, et vérifiez que la routine est activée.
5. Quand init.state=verified et lié à ce bot, enregistrez home_id + étiquette du bot en mémoire et dites à l'utilisateur une fois : 通知已接通. Un nouveau setup (nouvelle clé) invalide la vérification ; refaites le test puis l'accusé de réception.
6. Si l'init de notification n'est pas terminé, dispatchez quand même, repliez sur le polling, et mentionnez l'étape manquante en termes simples.

1. Vérifier et démarrer

Privilégiez stdin pour le JSON de requête (--request -). Un chemin de fichier est acceptable lorsque l'utilisateur ou un outil l'a déjà préparé.

<commande> doctor --json
<commande> roles list --json
<commande> pipeline templates --json
<commande> run start --request - --dry-run --json < request.json
<commande> run start --request - --json < request.json
# forme fichier optionnelle lorsqu'il est déjà préparé :
# <commande> run start --request request.json --json

Signalez d'abord toute vérification docteur avec ok:false. Utilisez decompose: provided lorsque l'utilisateur a donné au plus trois sous-tâches claires, sinon le planificateur. Enregistrez result.run_id et dites à l'utilisateur les voies (lanes), le budget et la branche d'intégration. Les travaux uniques (<commande> start) et les pipelines (<commande> pipeline start) fonctionnent de la même manière. Remarque : un résultat --dry-run imprime également un id et queued ; il n'a rien démarré.

Chaque résultat de start contient result.notify={enabled, reason, endpoint_host}. reason non nul signifie en pause ou cassé ; il n'a pas d'info d'init, donc confirmez avec notify status.

2. Rappelez toujours à l'utilisateur comment regarder

Après chaque run start, pipeline start ou start réussi, lisez result.dashboard. Prenez attach_hint, watch_hint et window textuellement ; ne construisez jamais la commande vous-même.

Si watch_hint commence par gbdev et que le home n'est pas celui par défaut, remplacez le premier gbdev par le nom du lanceur de bot (par exemple gbdev-example-dev) lors de la transmission à l'utilisateur. Transmettez attach_hint textuellement (session home par défaut gbdev ; non par défaut gbdev-<h6>).

Si enabled=true, reason=null et attach_hint n'est pas vide, dites (dans la langue de l'utilisateur) :

想实时看进度的话，在 Mac 终端执行 <attach_hint>，切到名为 <window> 的窗口即可（默认按 Ctrl-b 再按 d 退出观看）。随时关掉终端、关掉某个窗格，甚至把整个 tmux 会话关掉都没关系，不会影响任务；下次有进展时面板会自动恢复，也可以让我执行 gbdev dashboard ensure 立刻恢复。不用 tmux 的话，<watch_hint> 能看到同样的内容。

Sinon, dites :

这台机器上的 tmux 观看面板没有开启（原因：），不影响任务。想看实时进度可以在终端执行 <watch_hint>。

Signification des raisons : disabled_by_config config désactivée ; disabled_by_env GBDEV_DASHBOARD=0 ; tmux_not_found pas de tmux ; tmux_too_old tmux < 3.2 ; tmux_error / tmux_timeout tmux a échoué cette fois ; unsafe_argv caractères non supportés dans les chemins ; foreign_session une session du même nom non créée par gbdev, que gbdev ne touche jamais ; lock_busy un autre processus met à jour le tableau de bord.

Ne réessayez jamais et ne modifiez jamais le flux de tâches parce que le tableau de bord est indisponible.

3. Suivre la progression

Pour un inventaire en lecture seule, utilisez <commande> run list --active, <commande> pipeline list --active, ou <commande> list --active dans le propre home de ce bot. Tous supportent --state <s> (répéter ou séparer par des virgules), --limit <1..500> (par défaut 20), et --json ; la liste des pipelines supporte également --standalone. La liste des travaux masque par défaut les tentatives précédentes remplacées ; --all les inclut sans modifier les faits du travail. gbdev status --all est uniquement pour la liste textuelle sans ID ; status ne peut pas combiner --all avec --json ou un ID. Pour un inventaire JSON, utilisez gbdev list --all --json ; les tableaux JSON de status et le comportement avec un ID unique sans --all sont inchangés. Un travail needs_input/blocked/failed/timeout/cancelled est remplacé par une tentative ultérieure dans la même instance d'étape de pipeline, ou par un pipeline propriétaire/exécution propriétaire terminal (une exécution terminale suffit même si son pipeline est encore non terminal) ; les entrées de tentatives corrompues ignorent uniquement la vérification de tentative ultérieure, pas la preuve du parent terminal. status réconcilie et peut écrire l'état, donc utilisez-le pour une unité spécifique lors de la vérification de fraîcheur/récupération, pas pour un inventaire en lecture seule. Le drapeau obsolète d'une liste suggère seulement d'utiliser status ; il ne répare jamais rien.

Chemin webhook (étape 0 vérifiée pour ce bot, notify.reason=null) : ne créez pas de routine de polling de 10 minutes. Dites à l'utilisateur : 完成或需要你决定时我会自动收到通知。 La routine webhook fait le suivi.

Repli horaire en semaine (optionnel, politique configurée par l'opérateur ; mêmes règles de cycle de vie que le §11.3 de la recette) : une fois par heure dans les jours de semaine, le fuseau horaire et les heures ouvrables configurés par l'opérateur (exemple de politique optionnel). Exécutez les commandes Mac uniquement tant que la mémoire contient des unités actives (exécution/pipeline/travail) ; sans unités actives, terminez silencieusement. Ordre : <commande> notify status --json → <commande> notify flush --wait-ms 20000 --json → statut de chaque unité active. Quand le created_at de l'attention actuelle est plus ancien que 1

…

[le contenu original était tronqué, la traduction suit cette structure jusqu'à la fin disponible]

4. Répondre aux décisions d'attention

Utilisez <commande> notify flush --json (ou votre routine de polling) pour voir les nouvelles notifications. Pour chaque décision, suivez les règles R1–R4. Utilisez --input - pour passer les décisions.

5. Inspection à la demande

Quand le résumé webhook et le statut ne suffisent pas, utilisez <commande> inspect --scope <chemin> --max-lines 50 --max-tokens 2000 --json pour obtenir des extraits limités. Ne lisez jamais des fichiers entiers sauf si nécessaire.

6. Finalisation (landing)

N'exécutez run land qu'après confirmation explicite de l'utilisateur. Vérifiez que toutes les vérifications sont passées et que la branche d'intégration est prête. Utilisez --dry-run d'abord si possible.

7. Nettoyage

Utilisez <commande> run cleanup <run_id> --json pour nettoyer les fichiers temporaires et les espaces de travail après la finalisation. Nettoyez uniquement après confirmation de l'utilisateur.