xuyanwen2012/humanize

humanize (hmz)

humanize (hmz, https://github.com/humanfia/humanize, docs https://docs.humanfia.ai/humanize/) lässt Coding-Agenten-CLIs (claude, codex, agy, …) innerhalb von Flows laufen: Schleifen, die entscheiden, wer arbeitet, wer prüft und wann der Lauf endet. Es ist ein uv-Werkzeug von PyPI (uv tool install hmz, ~/.local/bin/hmz); hmz update aktualisiert es. Ein bloßes hmz öffnet eine TUI für das aktuelle Verzeichnis, hmz exec führt einen Flow headless aus, hmz web stellt die Läufe jedes Arbeitsbereichs in einem Browser dar. Geschrieben gegen Version 0.2.2; diese Alpha ändert sich häufig, also vertrauen Sie hmz exec --help mehr als dieser Datei.

Standardeinstellungen des Benutzers (für Ihre Konfiguration anpassen)

Einstellung	Standard
Flow	rlar: Claude implementiert, Codex prüft
Actor	claude/claude-opus-5-5:high
Reviewer	codex/gpt-6.1-sol:high (manchmal :ultra)
Budget	budget.duration=1d, ohne Kosten- oder Token-Obergrenze

Verwenden Sie diese, sofern der Benutzer nichts anderes sagt oder der Arbeitsbereich gespeicherte Standardeinstellungen hat (siehe unten). Fragen Sie nicht nach dem 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

Arbeitsablauf

1. Vorbereitung.
   • Schlagen Sie das Verzeichnis in ~/.hmz/settings.yaml unter workspaces: nach. Wenn es einen Eintrag hat, bevorzugen Sie dessen Flow, Agenten, Umgebungen und Budget gegenüber den obigen Standardeinstellungen.
   • Überprüfen Sie, ob jedes von Ihnen übergebene Modell und jeder Aufwand in ~/.hmz/models/<cli>.json existiert. hmz validiert Spezifikationen nicht im Voraus: Ein schlechtes Modell schlägt erst beim ersten Zug, der es verwendet, fehl, sodass ein falsches Reviewer-Modell in rlar erst nach dem gesamten ersten Zug des Actors sichtbar wird.
   • Überprüfen Sie git status. hmz-Agenten laufen mit umgangenen Genehmigungen. Wenn das Repository unbestätigte Arbeit enthält, die Sie nicht erstellt haben, oder es lebende Systeme ändern kann (Infrastruktur, Bereitstellungsskripte, Anmeldedaten), sagen Sie dies und schlagen Sie einen git-Worktree vor, bevor Sie beginnen.
2. Schreiben Sie die Aufgabendatei (nächster Abschnitt) in den Notizblock und zeigen Sie sie dem Benutzer, wenn die Aufgabe nicht trivial oder nur locker vorgegeben wurde.
3. Starten Sie im Hintergrund mit run_in_background und --json, umgeleitet in ein Log im Notizblock. Läufe dauern Stunden bis Tage. Berichten Sie den Befehl, die Aufgabendatei, den Log-Pfad und wie Sie ihn beobachten können: hmz in diesem Verzeichnis öffnet die TUI für den Lauf, oder hmz web.
4. Lesen Sie das Ergebnis (siehe Ergebnisse), überprüfen Sie dann den Repo-Diff und führen Sie die Projektprüfungen selbst durch, bevor Sie die Aufgabe als erledigt betrachten. Das „Erledigt" des Reviewers ist ein Hinweis, kein Beweis.
5. Stoppen. Stoppen Sie den von Ihnen gestarteten Hintergrundprozess. Nie bloß pkill hmz, da der Benutzer oft andere Läufe laufen hat. Untersuchen Sie pgrep -af hmz und stoppen Sie nur Ihre PID.
6. Fortsetzen. --resume mit dem gleichen -f im gleichen Verzeichnis (Einschränkungen unten).

Schreiben der Aufgabe

Der Actor sieht nur die Aufgabe, und in rlar bewertet der Reviewer das Repository anhand dieser, sodass vage Aufgaben zu endlosen Prüfrunden oder einem vorzeitigen „Erledigt" führen. Fügen Sie hinzu:

• Ziel: das Ergebnis in ein oder zwei Sätzen, nicht die Schritte.
• Zuerst lesen: die Dateien, Spezifikationen oder Dokumente, die die Arbeit definieren (z.B. eine OpenSpec-Änderung, ein Issue, eine Designnotiz), damit der Agent sie nicht neu entdeckt.
• Erledigt, wenn: konkrete Abnahmekriterien, die der Reviewer überprüfen kann: Befehle, die bestehen müssen, Verhalten, das gelten muss, zu erreichende Zahlen.
• Nicht im Umfang: was nicht berührt werden soll, und alle Aktionen, die einen Menschen erfordern (Bereitstellungen, Pushes, Löschungen, kostenpflichtige Dienste, Änderungen an Live-Systemen).
• Konventionen: Commit-Richtlinie (committen oder uncommitted lassen, Nachrichtenstil), wo Logs und Artefakte abgelegt werden.

Schreiben Sie es in eine Datei und übergeben Sie "$(cat "$TASK")", oder sagen Sie dem Agenten, er solle die Datei zuerst lesen. Eine Aufgabe, die mit - beginnt, kommt nach --.

Befehlsstruktur

hmz exec -f FLOW -a ROLLE=SPEZ[,...] [-e ROLLE=SPEZ[,...]] -p SCHLÜSSEL=WERT[,...] [Optionen] aufgabe

• -f: ein Flow-Name. Eingebaute sind nackt (rlar); eigene des Benutzers sind @benutzer/NAME (aus ~/.hmz/flows/NAME/) und die des Projekts @lokal/NAME. Auch ein Pfad, der mit ., / oder ~ beginnt, git+URL#unterverzeichnis, oder NAME:ANDERER für einen anderen Flow im selben Modul. Ein nackter Name wird zuerst am nächsten aufgelöst, sodass ein Benutzer-Flow einen eingebauten überschatten kann.
• -a: ROLLE=CLI[@PROVIDER]/MODELL[:AUFWAND], eine pro Agentenrolle, die der Flow definiert. Wiederholen Sie das Flag oder trennen Sie mit Kommas.
• -e: ROLLE=BACKEND[@PROVIDER][/ARBEITSVERZEICHNIS] für Flows mit Umgebungsrollen. PROVIDER ist eine in den Einstellungen gespeicherte Laufzeit oder, nur für SSH, ein Host in eckigen Klammern: box=ssh@[benutzer@host:22]/abs/pfad. Ohne Provider ist es diese Maschine.
• -p: Flow-Parameter, analysiert als der Parametertyp oder als JSON. Jeder Flow außer chat benötigt ein Budget: budget.duration (1d, 2h30m, PT1H), budget.cost (USD), budget.output_tokens. budget.graceful=true lässt den letzten Zug beenden (oder budget.graceful.<limit> für ein Limit).
• --json: NDJSON-Ereignisse auf stdout. Verwenden Sie es, wenn Sie das Ergebnis lesen müssen.
• --resume: setzt den neuesten Lauf dieses Flows hier fort, wenn der Flow fortgesetzt werden kann (ralph_loop und continue_loop können das nicht). Das Fortsetzen von rlar übergibt einem frischen Actor nur die letzte Überprüfung, nicht die alte Actor-Sitzung.
• --backup NAME: sichert das Epos auf ein in den Einstellungen gespeichertes Backup-Ziel (none deaktiviert es).
• --profile-flow / --profile-environment: fügt Sampling zur Spur des Laufs hinzu. Verwenden Sie sie nur, wenn Sie einen langsamen Lauf diagnostizieren.
• Ein fehlgeschlagener Zug beendet den Lauf in jedem eingebauten Loop-Flow, zählen Sie also nicht darauf, dass eine Schleife ihn wiederholt.

Auswahl eines Flows

Flow	Rollen	Verwenden, wenn
rlar	actor, reviewer	Standard. Arbeit, die eine separate Prüfung erfordert. Der Actor arbeitet in einer Sitzung, ein frischer Reviewer überprüft das Repository anhand der Behauptungen des Actors in jeder Runde, und es endet, wenn der Reviewer „Erledigt" sagt.
chat	assistant	Ein Agent, ein Durchlauf, keine Schleife und kein Budget. Fragen und kleine Änderungen.
goal	worker	Eine /goal <task>-Sitzung, die läuft, bis das Modell sagt, dass das Ziel erreicht ist. Selbstprüfende Arbeit mit klaren Kriterien.
continue_loop	agent	Sendet die Aufgabe einmal und sendet dann weiter „continue“. Lange Bearbeitungen in einem Kontext.
ralph_loop	agent	Jede Runde frische Sitzung mit derselben Aufgabe. Der Fortschritt lebt im Repository, nicht im Kontext.
stateful_ralph	agent	Eine Sitzung, die Aufgabe wird jede Runde erneut gesendet.
flame_chase	first_chaser, second_chaser	Zwei Agenten wechseln sich in frischen Sitzungen ab.

Benutzer-Flows befinden sich in ~/.hmz/flows/<name>/__init__.py. Listen Sie sie mit ls ~/.hmz/flows/ auf und lesen Sie den Docstring für Rollen und Parameter, bevor Sie einen verwenden. Um den vollständigen Vertrag eines beliebigen Flows zu erhalten: ~/.local/share/uv/tools/hmz/bin/python -c "import hmz.flows.builtin.rlar as m; print(m.__doc__)".

Ergebnisse

• Jeder Lauf ist ein Epos unter ~/.hmz/epics/<cwd-mit-slashes-als-striche>/<zeitstempel>/, und epic.jsonl enthält die Zusammenfassungsereignisse: began (Flow, Aufgabe), opened (jede Agentensitzung), usage (Kosten, output_tokens, Sekunden) und ended mit einem how-Feld: done, wenn die eigene Stoppbedingung des Flows erfüllt wurde, sonst stopped (andere Werte können vorkommen).
• Das --json-Log enthält den vollständigen Ereignisstrom, einschließlich Fehler wie HarnessUnrecoverable, wenn ein Zug fehlschlägt. Lesen Sie sein Ende, um zu erfahren, warum der Lauf endete.
• Berichten Sie das Ergebnis, die Kosten und die Dauer aus usage sowie Ihre eigene Diff-Prüfung.

Einstellungshinweise

• Gespeicherte Laufzeiten sagen, wo die Agenten-CLI mit harness: läuft (affinity: ist der alte Name und wird noch gelesen). Eine Laufzeit auf einer anderen Maschine ohne gesetzte Harness fällt nicht darauf zurück, die CLI hier auszuführen. Setzen Sie also harness: local, wenn der entfernte Host die CLI nicht hat.
• /btw-Seitenfragen zum Epos funktionieren nur, wenn die btw-Einstellung einen Agenten benennt (Einstellungen › Allgemein).
• hmz web-Laufseiten sind unter #/epics/.