boshu2/using-gc

Utilisation de GC

N'utilisez Gas City que lorsque l'appelant la sélectionne explicitement. Traitez-la comme un adaptateur d'exécution remplaçable, et non comme une limite de correction ou d'achèvement. L'adaptateur ne peut pas sélectionner la sémantique AgentOps, émettre un verdict contraignant, ou transformer l'achèvement de l'usine en preuve de livraison ou de validation.

Choisir d'abord l'usine

AgentOps prend en charge à la fois Gas City et le Flywheel de codage agentique en tant que runtimes d'usine logicielle externes. Utilisez ce skill uniquement pour Gas City. Si l'appelant sélectionne le Flywheel, passez à using-flywheel et son workflow natif au lieu de l'envelopper dans Gas City.

AgentOps fournit des skills et des contrats de preuve aux deux usines. Elle n'a pas besoin de sa propre formule ou pack de rôles Gas City. Installez ou liez les skills AgentOps dans le runtime du fournisseur avant de démarrer les workers ; le Maire amont, le coordinateur et les workers peuvent alors découvrir et sélectionner plan, implement, test, validate et autres skills AgentOps normalement.

Modèle opérationnel de Gas City 1.4

Gas City 1.4 est centré sur les exécutions. Le superviseur sert le tableau de bord et des API d'exécution/session typées et paginées. Chaque périmètre de ville ou de chantier possédant un graphe besoin de son propre core.control-dispatcher ; ce worker déterministe fait avancer les perles de contrôle de la formule. Les workers agents réclament le travail acheminé. Le skill amont gc.mayor est le coordinateur guidé ; gc.run-operator lance et supervise les formules.

Le chemin normal d'AgentOps est :

1. Installez et épinglez le workflow amont gascity et les imports de rôle de chantier.
2. Ajoutez le projet en tant que chantier, préparez son runtime mainteneur de stock, et rendez les skills AgentOps visibles pour ses sessions de fournisseur.
3. Créez une perle d'intention source appartenant à l'appelant et donnez son identifiant au Maire, qui rédige les perles du workflow et distribue la formule build-basic amont, de continuation, de révision ou d'implémentation qui correspond aux artefacts disponibles.
4. Lisez l'état des exécutions, sessions, perles, artefacts et verdicts. L'achèvement n'est jamais déduit du texte du chat ou du volet.

Préparez et qualifiez un chantier avant sa première construction avec l'interface CLI AgentOps fournie (aucun checkout de dépôt requis) :

ao gc prepare --city /chemin/vers/la-ville --rig /chemin/vers/le-chantier
ao gc check --city /chemin/vers/la-ville --rig /chemin/vers/le-chantier

La commande vérifie les épingles exactes du workflow et du rôle officiels, prend un instantané des scripts de validation amont et des schémas inchangés dans le répertoire .gc du chantier, installe uniquement de petits wrappers appartenant à AgentOps aux chemins de vérification de la formule, sélectionne un Python existant pouvant importer PyYAML, et lie les skills AgentOps dans les puits Codex de la ville et du chantier. Les skills proviennent du dépôt AgentOps englobant lorsqu'il est présent, sinon de la racine des skills installés ; passez --skills-source pour épingler un répertoire différent. Cela ne modifie jamais le binaire GC, le cache, les formules, les rôles ou le pack amont. check émet uniquement des commandes d'inspection natives, n'écrit aucun fichier d'adaptateur, et échoue avant toute dépense de modèle lorsque ce contrat d'exécution est manquant ou a dérivé.

prepare pré-ensemence également la confiance Codex pour chaque répertoire de session qui existe lorsqu'il s'exécute — les racines de la ville et du chantier, chaque dossier d'accueil .gc/agents/** et chaque racine d'arbre de travail du chantier — de sorte qu'une session Codex dans l'un de ces répertoires ne bloque pas sur la boîte de dialogue de confiance interactive. Les deux couches persistées sont ensemencées dans $CODEX_HOME/config.toml : la confiance de l'espace de travail ([projects."<dir>"] trust_level = "trusted"), sans quoi Codex signale silencieusement que ce répertoire n'a aucun hook, et la confiance par hook ([hooks.state."<hooks.json>:<event>:<m>:<h>"] trusted_hash = "sha256:..."), ce que le .codex/hooks.json du pack par fournisseur demanderait autrement. Les digests de hook sont lus depuis hooks/list de Codex lui-même, jamais recalculés.

La confiance est jugée par la valeur, non par la présence d'une table. prepare n'ajoute que les entrées manquantes et refuse, en nommant l'entrée, lorsqu'une existe mais ne confère pas de confiance — un trust_level = "untrusted" explicite, un hook que Codex signale comme modifié depuis qu'il a été approuvé, un hook enregistré que Codex rejette encore, ou un hook enregistré enabled = false (un hook désactivé n'est pas un hook de travail approuvé). Il n'écrase jamais une décision d'opérateur, et la ré-exécution est sans effet. Il échoue également plutôt que de continuer si Codex renvoie une liste de hooks vide ou non reconnue. Le magasin de confiance lui-même n'est jamais édité en place : le contenu fusionné est d'abord analysé en mémoire, puis installé avec le dispositif d'écriture atomique durable de la CLI, ainsi aucun chemin d'échec ne peut laisser une configuration Codex partiellement écrite.

ao gc check vérifie le même pré-ensemencement à partir de l'état local uniquement — il n'exécute aucun sous-processus Codex et n'écrit rien, dérivant chaque clé de hook attendue du hooks.json propre au répertoire — et nomme le répertoire ou le hook spécifique déficient en utilisant la même règle que prepare ensemence.

Deux limitations nommées.

1. check ne peut pas détecter un hash périmé. Comme il ne demande jamais Codex, un trusted_hash enregistré qui ne correspond plus au contenu actuel du hook est considéré comme satisfait et soulève toujours la boîte de dialogue de confiance dans une session réelle. Seul prepare voit cela — Codex signale le hook comme modifié et prepare refuse. Un check vert signifie donc "la confiance est enregistrée", pas "la confiance est fraîche".
2. Les dossiers d'accueil créés après prepare ne sont pas couverts. La découverte se fait par marqueur de système de fichiers, donc la garantie couvre les répertoires de session qui existent au moment de prepare. Un dossier d'accueil de session que Gas City matérialise plus tard comporte toujours des hooks non approuvés lors de son premier lancement ; prepare nomme les agents configurés qui n'ont pas encore de dossier d'accueil.

La règle opérationnelle qui découle des deux : exécutez prepare, démarrez la ville, puis exécutez prepare à nouveau (il est idempotent) avant de distribuer.

Pack et registres préférés

Le registre main intégré catalogue les packs officiels. Le registre communautaire est une configuration optionnelle :

gc pack registry list
gc pack registry refresh
gc pack registry search --all
gc pack registry show main:gascity
gc pack registry add community https://registry.gascity.com/registry.toml
gc pack registry search --registry community --all

search lit le cache du registre local ; show rapporte la provenance de la version et les commandes d'import exactes. gc import add déclare une source/version, et gc import install la résout dans packs.lock. Préférez une version acceptée exacte pour des villes reproductibles.

AgentOps préfère le pack de construction gascity officiel, la famille de workflows visible dans l'usine publique Maintainer City. La référence acceptée actuelle est gascity 0.1.6 au commit 3b3b89f2011e06d84459aa7bea1552382f13930a :

• tableau de bord : https://factory.gascity.com;
• workflows : build-basic, build-from-*, implement, review, issue, et PR flows;
• rôles de chantier standard : gc.run-operator, gc.implementation-worker, planners, reviewers, et publisher;
• contrôle de formule au niveau du périmètre : core.control-dispatcher;
• coordination guidée : le skill amont gc.mayor.

Installez le pack de workflow au niveau de la ville et son pack de rôles frères sur chaque chantier qui exécute du travail, en suivant les commandes exactes renvoyées par gc pack registry show main:gascity. Conservez l'espace de noms gc.* standard ; ne imbriquez ni ne renommez les rôles derrière un pack AgentOps.

Le travail entre dans la ville par le Maire. L'appelant rédige UNE perle d'intention source avec acceptation, puis remet son identifiant au Maire — le Maire décompose, rédige les perles du workflow et distribue. L'appelant n'exécute jamais gc sling lui-même ; une exécution lancée par un opérateur contourne le coordinateur qui possède les reprises, la redistribution et le maintien pour ce workflow.

gc bd create "Ajouter un drapeau --json à la commande export"
gc mail send mayor -s "Construire ago-XXXX" \
  -m "Décomposer et lancer build-basic pour la perle ago-XXXX avec push=true open_pr=true." --notify

Ou, dans une session interactive du Maire :

Utiliser le skill gc.mayor

gc sling direct reste un outil de débogage pour une ville sans Maire actif ; une exécution démarrée de cette façon n'a pas de coordinateur et l'opérateur hérite de son maintien.

Les skills AgentOps sont des outils à la disposition de ces agents d'usine, non un workflow de remplacement. Nommez explicitement un skill dans la perle ou l'invite lorsque son comportement est requis. La décomposition amont actuelle ne propage pas automatiquement une section Required Skills libre depuis la perle source appartenant à l'appelant dans chaque élément de travail généré. Inspectez la décomposition avant l'implémentation ; mettez un nom de skill requis sur l'élément de travail réel ou l'invite du worker lorsque son utilisation est une condition d'acceptation. La présence d'un skill et l'invocation d'un skill sont des faits différents.

Mettre à niveau une ville existante vers la version 1.4

Avant de démarrer son orchestrateur, exécutez une fois par ville :

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOS lorsqu'un superviseur direct plus ancien persiste
gc start

Confirmez ensuite :

• gc version rapporte 1.4.0 depuis le chemin prévu ;
• gc doctor n'a pas d'échecs bloquants ;
• chaque chantier possédant un graphe a un core.control-dispatcher non suspendu ;
• les imports et packs.lock résolvent ;
• ao gc check accepte le runtime mainteneur contenu et les liens de skill AgentOps ;
• sur macOS, le LaunchAgent du superviseur résout au même exécutable que le binaire gc sélectionné ;
• les anciens signets de tableau de bord autonome ou proxys inversés sont supprimés.

Une ville enregistrée périmée peut bloquer chaque démarrage. Réparez cette ville avec gc doctor --fix, ou désenregistrez-la explicitement si elle est intentionnellement mise hors service.

Retirez une ancienne ville HQ/canary par son nom ou chemin enregistré exact, sans arrêter le superviseur à l'échelle de la machine nécessaire à son remplacement :

gc cities --json
gc stop /chemin/vers/ancienne-ville --timeout 45s
gc unregister /chemin/vers/ancienne-ville
gc cities --json

unregister échoue plutôt que d'accepter silencieusement une cible inconnue. Conservez le répertoire de la ville jusqu'à ce que son état Beads soit sauvegardé ou confirmé comme jetable. Créez le remplacement à partir du modèle amont Gas City, installez ses imports épinglés, et vérifiez-le avec gc cities --json, gc --city <nouvelle-ville> status, et gc --city <nouvelle-ville> doctor --json.

Orchestration via le Maire : la boucle de maintien

Après avoir remis l'intention au Maire, l'orchestrateur exécute cinq verbes. Chaque verbe a un propriétaire ; franchir les propriétaires est la classe de défaillance récurrente que cette section existe pour arrêter.

Verbe	Propriétaire	Surface
Surveiller	orchestrateur	$API/runs/census et $API/runs/<run-id> à une cadence fixe, plus gc mail inbox pour les réponses du Maire. failed > 0 dans le recensement, une exécution en échec (failed/canceled) ou un courrier non lu du Maire est le signal d'action ; tout le reste est un battement (tick).
Observer	orchestrateur	Sur un signal d'action, parcourez les couches de visibilité dans l'ordre — recensement, détail d'exécution, graphe de perles, liste de sessions, vérité des volets — et arrêtez-vous à la première couche qui explique. Ne commencez pas par la vérité des volets.
Ajuster	orchestrateur, une fois	Une perle ready : distribuez-la une fois à son gc.run_target. Une perle acheminée avec une session active : gc session wake <run_target> une fois. Un deuxième ajustement sur le même sujet signifie que le diagnostic est erroné — envoyez un courrier au Maire à la place.
Rediriger	Maire	Les changements de priorité, de périmètre, d'annulation ou de modèle/fournisseur voyagent par courrier avec les identifiants de perle/d'exécution. L'orchestrateur ne relance jamais, n'édite pas les perles de workflow ou ne corrige pas une exécution en cours.
Reprendre	GC d'abord, puis Maire	Les résultats de révision échoués rentrent dans l'exécution via sa boucle de correction native (review_fix_formula, par défaut fix-loop-base) ; les reprises limitées et contrôlées sont des boucles gc converge. Seule une exécution failed/canceled TERMINALE — ou une exécution terminée dont le résultat manque l'acceptation de l'appelant — retourne en arrière : envoyez un courrier au Maire avec l'identifiant d'exécution et la preuve d'échec pour une redécomposition et un relancement.

La reprise effectuée manuellement par l'orchestrateur (éditer l'arbre de travail d'une exécution échouée, relancer sa formule, fermer ses perles) crée un second auteur non coordonné pour la même intention ; le relancement du Maire entre alors en compétition avec lui.

Protocole de blocage

Classifiez d'abord la perle.

• Encore ready : distribuez-la une fois à son gc.run_target, puis arrêtez-vous et inspectez.

• Déjà acheminée/en cours : relancer est une OPÉRATION NULLE. Réveillez son worker propriétaire une fois :

  gc session wake <run_target>
  

Capturez ensuite le volet tmux exact nommé par l'état de la session et exécutez gc doctor. Ne réparez jamais une ville depuis l'intérieur de cette ville.

Ne créez jamais de sessions appartenant à un pack manuellement. gc session new pour un agent unique ou mis à l'échelle (core.control-dispatcher, workers de rôle) crée une session mal dimensionnée qui accapare le nom canonique en start-pending et bloque le réconciliateur pour générer la véritable session — prolongeant exactement le blocage en cours de réparation. Le cycle de vie des sessions appartient au réconciliateur et à la mise à l'échelle à la demande. Lorsque la ville elle-même a besoin d'être entretenue (un réconciliateur bloqué, des sessions qui ne quittent jamais l'état de drainage, un recâblage du modèle ou du fournisseur), envoyez la demande au Maire :

gc mail send mayor -s "<sujet>" -m "<demande avec identifiants de perle>" --notify

Le pack amont peut laisser une future étape liée par affinité assignée à une session qui a déjà acquitté un drain. Diagnostiquez cela uniquement depuis l'extérieur de la ville :

ao gc recover-affinity --city /chemin/vers/la-ville --rig /chemin/vers/le-chantier

La valeur par défaut est un test à blanc. Si chaque assignation listée est correcte, répétez avec --apply. La réparation limitée efface uniquement le cessionnaire sur une perle de formule actuellement prête (ready) dont la session gc.session_affinity=require n'est plus active. Elle ne relance pas, ne réessaie pas, ne ferme pas, ne redémarre pas et ne sélectionne pas de travail.

Visibilité : quatre couches

1. État du superviseur/de l'exécution — gc dashboard, détail d'exécution, gc status, et gc session list --json. Le détail d'exécution unifie l'échelle des étapes, les transcriptions structurées, le taux de jetons et le taux de dépense estimé. Une liste peut encore signaler active alors qu'un fournisseur est coincé.

   L'état d'exécution programmatique provient de l'API d'exécution typée du superviseur — les mêmes données que le tableau de bord affiche. gc status affiche la base de l'API ; ni gc status --json ni aucune autre sous-commande CLI ne transporte d'objets d'exécution.

   API="http://127.0.0.1:<port>/v0/city/<nom-ville>"
   curl -s "$API/runs/<run-id>"   # {run_id, title, status, target, scope, started_at, updated_at}
   curl -s "$API/runs/census"     # {status_counts: {pending, active, completed, failed, canceled}}
   

   Lorsque l'état de l'exécution failed/completed est exact, arrêtez-vous ici. Lisez les perles, les artefacts et les sessions uniquement lorsqu'un active ou pending est suspect ou que le résultat affiché est insuffisant.

2. Graphe de perles — Le détail d'exécution inclut toutes les perles de sa portée. Inspectez type, state (ready, routed, done), text, def (routine de travail : formula, prompt, target, integration-point), gc.run_strategy (dispatch ou loop), gc.session_affinity, et les périls. Les perles de formule de continuation et de révision sont des perles de routine de travail ; attendez-vous à voir au moins une perle ready avec une routine de travail formula et une gc.run_strategy=dispatch.

3. Liste des sessions — gc session list --json rapporte les sessions actives, en drainage, en attente (pending) et en vidange (draining), avec run_target, model, session_state, et provider. Une session dans un état autre qu'active n'est pas un échec tant que son remplacement arrive. La session que vous observez peut être un vestige — lisez session_state, started_at/updated_at, et l'ID du modèle.

4. Vérité des volets — Les transcriptions visibles (app.com) ou tmux qui défilent. Un worker bloqué (idle, pas de perle chargée, pas de panne de modèle) réclame une perle à travers le dispatcher approximativement toutes les 2 à 4 secondes ; un intervalle plus long signifie que le dispatcher voit un goulot d'étranglement ou que la file d'attente est vide. Une session bloquée sur une invite spécifique voit sa dernière ligne de transcription inchangée et un état available ou busy. Une session qui n'a pas encore été affectée à une perle est available et idle.

   Ne corrigez jamais une perle en tapant dans le volet d'un worker. Chaque perle a un text exact qui lui a été assigné à son origine ; taper dans le volet ajoute un texte non assigné. Redirigez au lieu de cela via le Maire si la perle a besoin d'être modifiée.

Travail à session unique et à session de travailleur unique

Chaque chantier a un dispatcher de session — le core.control-dispatcher — qui est un travailleur sans garde-boue qui ne peut pas être redimensionné. Il réclame les perles prêtes (formule) et les achemine vers la bonne session. Il doit être non suspendu. C'est la seule session que vous créez ou inspectez manuellement hors du code de gc run-operator.

Un gc run-operator peut gérer n'importe quel nombre de sessions de travailleurs. Ne créez pas de sessions agents explicitement ; les travailleurs sont lancés par le réconciliateur qui lit packs.lock et les rôles installés. Les sessions dupliquées start-pending signalent que le réconciliateur est absent ou que son diagnostic est erroné.

gc session wake force un travailleur inactif à réclamer une perle s'il en a une qui l'attend ; si le travailleur a une perle mais est bloqué sur un fournisseur, wake est sans effet.

Éléments connus et travail en cours

L'équipe Gas City discute de l'opportunité de traiter les perles ready comme un pool de devoirs distribué aux travailleurs qui les réclament, plutôt que de les associer de manière fixe à une session avant la distribution. La relation entre la stratégie d'affinité de session et l'évitement de session est un sujet actif. Consultez les sections susmentionnées pour le statut actuel.

Les emplacements globaux de configuration sont plus difficiles à maintenir avec chaque version du pack Gas City. Les commandes gc config visent à stocker la configuration sur une base par ville, par session et par travailleur ; les ordres de priorité et la fusion ne sont pas encore stabilisés. Consultez la documentation de la ville pour les détails actuels.

Le processus de construction actuel charge la configuration plus tard, de sorte qu'une ville fraîchement créée peut avoir des fichiers de configuration présents mais encore avoir besoin d'un gc start pour que des commandes comme gc config et d'autres utilitaires puissent fonctionner à partir de zéro.