xuyanwen2012/humanize

humanize (hmz)

humanize (hmz, https://github.com/humanfia/humanize, docs https://docs.humanfia.ai/humanize/) exécute des CLI d'agents de codage (claude, codex, agy, …) dans des flux : des boucles qui décident qui travaille, qui révise et quand l'exécution s'arrête. C'est un outil uv de PyPI (uv tool install hmz, ~/.local/bin/hmz) ; hmz update le met à jour. hmz seul ouvre un TUI pour le répertoire courant, hmz exec exécute un flux en mode headless, hmz web sert les exécutions de tous les espaces de travail dans un navigateur. Écrit pour la version 0.2.2 ; cette version alpha change souvent, donc fiez-vous à hmz exec --help plutôt qu'à ce fichier.

Paramètres par défaut de l'utilisateur (modifiez pour votre configuration)

Paramètre	Valeur par défaut
Flux	rlar : Claude implémente, Codex révise
Acteur	claude/claude-opus-5-5:high
Relecteur	codex/gpt-6.1-sol:high (parfois :ultra)
Budget	budget.duration=1d, sans plafond de coût ou de tokens

Utilisez ces valeurs sauf indication contraire de l'utilisateur, ou si l'espace de travail a des valeurs par défaut sauvegardées (ci-dessous). Ne demandez pas le budget.

hmz exec -f rlar \
  -a actor=claude/claude-opus-5-5:high \
  -a reviewer=codex/gpt-6.1-sol:high \
  -p budget.duration=1d \
  --json "$(cat "$TASK")" > "$LOG" 2>&1

Flux de travail

1. Pré-vol.
   • Recherchez le répertoire dans ~/.hmz/settings.yaml sous workspaces:. S'il a une entrée, préférez son flux, ses agents, ses environnements et son budget aux valeurs par défaut ci-dessus.
   • Vérifiez que chaque modèle et effort que vous passez existe dans ~/.hmz/models/<cli>.json. hmz ne valide pas les spécifications à l'avance : un modèle erroné échoue seulement au premier tour qui l'utilise, donc un mauvais modèle de relecteur dans rlar apparaît après tout le premier tour de l'acteur.
   • Vérifiez git status. Les agents hmz sont exécutés sans approbation. Si le dépôt contient du travail non commité que vous n'avez pas créé, ou s'il peut modifier des systèmes en production (infrastructure, scripts de déploiement, identifiants), mentionnez-le et suggérez un git worktree avant de commencer.
2. Rédigez le fichier de tâche (section suivante) dans le bloc-notes et montrez-le à l'utilisateur si la tâche est non triviale ou a été donnée de manière vague.
3. Lancez en arrière-plan avec run_in_background et --json redirigé vers un journal dans le bloc-notes. Les exécutions durent de quelques heures à plusieurs jours. Signalez la commande, le fichier de tâche, le chemin du journal et comment le surveiller : hmz dans ce répertoire ouvre le TUI sur l'exécution, ou hmz web.
4. Lisez le résultat (voir Résultats), puis vérifiez le diff du dépôt et exécutez les tests du projet vous-même avant de déclarer la tâche terminée. Le verdict « fait » du relecteur est une preuve, pas une garantie.
5. Arrêt. Arrêtez la tâche en arrière-plan que vous avez lancée. N'utilisez jamais pkill hmz brut, car l'utilisateur a souvent d'autres exécutions en cours. Inspectez pgrep -af hmz et arrêtez uniquement votre PID.
6. Reprise. --resume avec le même -f dans le même répertoire (limites ci-dessous).

Rédaction de la tâche

L'acteur ne voit que la tâche, et dans rlar, le relecteur juge le dépôt par rapport à celle-ci. Des tâches vagues entraînent donc des cycles de révision infinis ou un verdict « fait » prématuré. Incluez :

• Objectif : le résultat en une ou deux phrases, pas les étapes.
• À lire d'abord : les fichiers, spécifications ou documentations qui définissent le travail (par exemple, une modification OpenSpec, un ticket, une note de conception), pour que l'agent ne les redécouvre pas.
• Fait quand : des critères d'acceptation concrets que le relecteur peut vérifier : commandes qui doivent réussir, comportement qui doit être vérifié, chiffres à atteindre.
• Hors de portée : ce qu'il ne faut pas toucher, et toute action nécessitant un humain (déploiements, push, suppressions, services payants, modifications de systèmes en production).
• Conventions : politique de commit (commiter ou laisser non commité, style de message), emplacement des journaux et artefacts.

Écrivez-la dans un fichier et passez "$(cat "$TASK")", ou dites à l'agent de lire le fichier d'abord. Une tâche commençant par - se place après --.

Syntaxe de la commande

hmz exec -f FLUX -a RÔLE=SPÉC[,...] [-e RÔLE=SPÉC[,...]] -p CLÉ=VALEUR[,...] [options] tâche

• -f : un nom de flux. Les flux intégrés sont nus (rlar) ; les flux personnels sont @utilisateur/NOM (depuis ~/.hmz/flows/NOM/) et ceux du projet @local/NOM. Également un chemin commençant par ., / ou ~, git+URL#sous-répertoire, ou NOM:AUTRE pour un autre flux dans le même module. Un nom simple est résolu d'abord au plus proche, donc un flux utilisateur peut masquer un flux intégré.
• -a : RÔLE=CLI[@FOURNISSEUR]/MODÈLE[:EFFORT], un par rôle d'agent défini par le flux. Répétez le drapeau ou séparez par des virgules.
• -e : RÔLE=ENVIRONNEMENT[@FOURNISSEUR][/RÉPERTOIRE_DE_TRAVAIL] pour les flux avec des rôles d'environnement. FOURNISSEUR est un environnement d'exécution enregistré dans les paramètres ou, pour ssh uniquement, un hôte entre crochets : box=ssh@[utilisateur@hôte:22]/chemin/absolu. Sans fournisseur, c'est la machine locale.
• -p : paramètres de flux, analysés selon le type du paramètre ou en JSON. Tout flux sauf chat a besoin d'un budget : budget.duration (1d, 2h30m, PT1H), budget.cost (USD), budget.output_tokens. budget.graceful=true laisse le dernier tour se terminer (ou budget.graceful.<limite> pour une limite spécifique).
• --json : événements NDJSON sur la sortie standard. Utilisez-le lorsque vous devez lire le résultat.
• --resume : reprend la dernière exécution de ce flux ici, si le flux peut être repris (ralph_loop et continue_loop ne le peuvent pas). La reprise de rlar donne un nouvel acteur uniquement avec la dernière révision, pas l'ancienne session de l'acteur.
• --backup NOM : sauvegarder l'épopée vers une cible de sauvegarde enregistrée dans les paramètres (none la désactive).
• --profile-flow / --profile-environment : ajouter un échantillonnage à la trace de l'exécution. Utilisez-les uniquement pour diagnostiquer une exécution lente.
• Un tour échoué termine l'exécution dans tous les flux en boucle intégrés, donc ne comptez pas sur une boucle pour réessayer.

Choix d'un flux

Flux	Rôles	Quand l'utiliser
rlar	acteur, relecteur	Par défaut. Travail nécessitant une vérification séparée. L'acteur travaille en une session, un nouveau relecteur vérifie le dépôt par rapport aux affirmations de l'acteur à chaque tour, et cela se termine lorsque le relecteur dit « fait ».
chat	assistant	Un agent, un coup, pas de boucle ni de budget. Questions et petites modifications.
goal	travailleur	Une session /goal <tâche> qui s'exécute jusqu'à ce que le modèle dise que l'objectif est atteint. Travail avec auto-vérification et critères clairs.
continue_loop	agent	Envoie la tâche une fois, puis continue d'envoyer « continue ». Longs travaux dans un seul contexte.
ralph_loop	agent	Nouvelle session à chaque tour avec la même tâche. Le progrès vit dans le dépôt, pas dans le contexte.
stateful_ralph	agent	Une session, la tâche est renvoyée à chaque tour.
flame_chase	premier_poursuiveur, deuxième_poursuiveur	Deux agents alternent dans des sessions fraîches.

Les flux utilisateur se trouvent dans ~/.hmz/flows/<nom>/__init__.py. Listez-les avec ls ~/.hmz/flows/ et lisez la docstring pour les rôles et paramètres avant d'en utiliser un. Pour obtenir le contrat complet d'un flux : ~/.local/share/uv/tools/hmz/bin/python -c "import hmz.flows.builtin.rlar as m; print(m.__doc__)".

Résultats

• Chaque exécution est une épopée sous ~/.hmz/epics/<chemin-courant-avec-slashs-en-tirets>/<horodatage>/, et epic.jsonl contient les événements de résumé : began (flux, tâche), opened (chaque session d'agent), usage (coût, output_tokens, secondes), et ended avec un champ how : done lorsque la condition d'arrêt propre au flux a été remplie, stopped sinon (d'autres valeurs peuvent exister).
• Le journal --json contient le flux complet d'événements, y compris les erreurs comme HarnessUnrecoverable lorsqu'un tour échoue. Lisez sa fin pour comprendre pourquoi l'exécution s'est terminée.
• Rapportez le résultat, le coût et la durée de usage, et votre propre vérification du diff.

Notes sur les paramètres

• Les environnements d'exécution enregistrés indiquent où la CLI de l'agent s'exécute avec harness: (affinity: est l'ancien nom et est toujours lu). Un environnement d'exécution sur une autre machine sans harness défini ne revient pas à exécuter la CLI ici, donc définissez harness: local lorsque l'hôte distant n'a pas la CLI.
• Les questions /btw à l'épopée fonctionnent uniquement une fois que le paramètre btw nomme un agent (Paramètres › Général).
• Les pages d'exécution de hmz web sont sous #/epics/.