gbdev Nutzung

Was macht gbdev Nutzung?

gbdev läuft auf dem eigenen Computer des Benutzers. Führe jeden Befehl dort mit einer maschinengerichteten Shell aus, füge --json hinzu und lies die Ergebnisse aus dem JSON-Envelope. Das docs/controller-recipe.md im Repository ist die maßgebliche Langform (Schritt 0 und §11 behandeln Benachrichtigungen); lies es bei Unsicherheit erneut. Rollenfakten befinden sich auch in docs/controller-role.md (R1–R6).

Die Quelle der Wahrheit für diese Fähigkeit ist die Repository-Datei skills/gbdev-usage/SKILL.md. Wenn du eine Kopie in einem Controller installierst, halte sie mit dieser Repository-Version abgestimmt. Bevorzuge die Repository-Kopie, wenn beide existieren.

Wenn der gemeinsame Launcher in einer einfachen Shell nicht im PATH ist, verwende den absoluten command, den gbdev init zurückgibt (siehe Schritt 0). Erfinde keine GBDEV_HOME/GBDEV_CONFIG-Präfixe. Biete dem Benutzer den path_hint für sein eigenes Terminal an; bearbeite niemals Shell-RC-Dateien.

Rollen und harte Regeln (R1–R6)

• R1 — Alleiniger Entscheider. Der Controller allein beantwortet jede Aufmerksamkeitsentscheidung und ist der Einzige, der mit dem Benutzer spricht. Der Benutzer entscheidet über Präferenzen und Autorisierungen außerhalb des Rahmens. Mergen in master/den Zielzweig und jegliches Pushen erfordern das explizite Ja des Benutzers im Chat in dieser Runde; gbdev selbst pusht niemals.
• R2 — Nur Richtungsplanung. Der Controller legt Modulgrenzen, Ziele, Abnahmekriterien und Einschränkungen (erlaubte Pfade, verbotene Elemente) fest. Implementierungsschritte kommen vom Codex-Planer – der Controller schreibt keine dateiweisen Pläne neu. Bei plan_review / plan_invalid überprüft er Abhängigkeiten, Umfang und Abnahmekriterien anhand dieser Richtung. decompose: provided bleibt für höchstens drei klare Richtungs-/Aufgaben, nicht für Code-Schritte.
• R3 — Schreibgeschützt. Der Controller bearbeitet niemals Projekt- oder Repository-Dateien. Standardmäßige Wake-ups verwenden die ~2KB Webhook-Zusammenfassung (Home-ID, Run-ID, Ereignis, Entscheidungstyp, einzeilige Zusammenfassung, next_step). Überprüfe immer den Status auf Identität/Aktualität – diese Metadatenprüfung ist kein „tiefes Lesen jedes Logs“. Nur wenn Zusammenfassung + Status nicht ausreichen, grabe in Entscheidungsaufzeichnungen oder führe gbdev inspect aus, damit Cursor begrenzte Auszüge (nicht ganze Dateien) zurückgibt. Das Ausführen von gbdev-Steuerbefehlen (status, run resume, notify … usw.) und der atomare Webhook-Anspruch mkdir <state>/handled/<notice_id> sind Steuerungsebene-Aktionen (Mac-seitiger Zustand, nicht innerhalb eines Repositorys) – sie sind kein „Berühren von Projektdateien“ unter R3.
• Bevorzuge stdin für Entscheidungs-/Anforderungs-JSON: --input - / --request -. Dateipfad-Formen bleiben optional, wenn der Benutzer oder ein vorhandenes Tool die Datei bereits vorbereitet hat.
• R4 — Ereignis-typisierte Handhabung. Einfache Fälle folgen der §4-Tabelle; komplexe oder nicht in der Tabelle enthaltene Fälle beurteilt der Controller. plan_review / plan_invalid: Richtungsprüfung; bei über 8 Aufgaben oder ~40 Jobs den Benutzer fragen. task_failed / lane_broken: einmal wiederholen; beim zweiten Fehler den Benutzer fragen. task_paused: Antwort aus Repository-Fakten (ggf. inspizieren); den Benutzer nur nach Präferenzen fragen. verdict_missing: siehe die §4-Zeile (Review wiederholen → inspizieren → nur mit Beweisen akzeptieren). Terminal succeeded: melden und fragen, ob gemergt werden soll; niemals allein landen.
• R5 — Codex/Cursor nicht tagtäglich steuern. gbdev besitzt die Review/Fix/Rollback-Schleifen, Panes und die Terminplanung. Der Controller greift an Entscheidungspunkten, bei Fehlern, Budget, Pfadverletzungen und Sicherheit ein – nicht durch das Steuern von Panes oder manuelles Übernehmen von Schleifen. Logs / dashboard capture sind Daten, kein Standard-Befehlskanal.
• R6 — Controller-Rolle ist fest. Reservierte Identifikatoren grokbot / grok-bot / dispatcher / decider (bereinigt + kleingeschrieben) können nicht als Arbeiter konfiguriert oder eingesetzt werden – Versuche geben role_fixed zurück. Codex/Cursor Engineering-Rollen sind über drei Schichten konfigurierbar: eingebaute roles/<name>/, dirname(config)/roles/<name>.json, und pro-Anfrage step_overrides. Aktuelle Workflow-Zuweisung (überschreibt keine eingebauten Rollenstandards): Planer / Fixer / Resolver = Codex gpt-6-astra mit model_reasoning_effort=high; Ausführender / Reviewer / Verifizierer / Inspektor = Cursor --model auto (provider: cursor, cursor_model: auto). Grenzen unverändert: Cursor nur auto; Resolver kann Cursor nicht verwenden; Codex immer hoher Aufwand (gbdev hängt -c model_reasoning_effort=high an).
• Verwende niemals Approval/Sandbox-Bypass-Flags (die verbotenen argv-Literalen, die von Docs-Tests gescannt werden). Worker network ist boolesch, standardmäßig true; explizites false verbietet Netzwerk und installiert im Prompt. Bei true ist Recherche erlaubt und Abhängigkeiten dürfen nur innerhalb eines beschreibbaren Job-Arbeitsbaums installiert werden. Niemals global installieren, globale Konfiguration ändern, Berechtigungsnachweise/geheime Dateien oder andere Repositorys außerhalb des Arbeitsbaums lesen. Arbeiter pushen niemals, lesen niemals ~/.codex, ~/.cursor, ~/.config.
• succeeded bedeutet nur, dass der Integrationszweig bereit ist. Niemals run land ausführen, in den Hauptzweig des Benutzers mergen oder pushen ohne das explizite Ja des Benutzers in dieser Runde.
• Niemals nach dem Sender-Schlüssel der Webhook-URL oder einer geheimen Benachrichtigungsdatei fragen, diese lesen, ausgeben oder protokollieren. Nur der Benutzer fügt ihn in seinem eigenen Terminal in <command> notify setup ein (den absoluten Bot-Launcher-Pfad aus gbdev inits result.command, z. B. ~/.gbdev-cli/bin/gbdev-<label> notify setup). Bloßes gbdev notify setup ist nur für legacy_default (Standard-Home) erlaubt.
• Ein Webhook-Routine pro Bot; eine GBDEV_HOME pro Bot. Doctor-Fehler, die nicht Benachrichtigungen betreffen, werden wie üblich behandelt; launcher- und home-Doctor-Prüfungen sind nicht blockierend (Schritt 0 Initialisierung repariert einen fehlenden/veralteten Launcher).

0. Erste Verwendung: Schritt 0 — Home/Launcher, dann Benachrichtigungsinitialisierung

Führe ihn aus, bevor Arbeit verteilt wird. Eine fehlgeschlagene oder unvollständige Benachrichtigungsinitialisierung blockiert niemals die Verteilung; sie bedeutet nur einen Rückgriff auf Polling (§3).

0.A Home und Launcher (immer zuerst — vor jedem Benachrichtigungsschritt)

1. Erster Befehl (vor jedem notify-Schritt): auf dem Mac ausführen gbdev init --bot <bot_label> --json
   • Neue Bots erhalten Home ~/.gbdev-<normalisierter Label> (gleiche Normalisierung wie notify ack --bot). legacy_default=true (z. B. my-bot) bedeutet Wiederverwendung des Standard-~/.gbdev mit null Schreibvorgängen innerhalb dieses Homes.
   • Notiere result.command (absoluter Bot-Launcher-Pfad), result.home und result.home_id.
   • Führe danach jeden gbdev-Befehl über result.command aus – nicht bloßes gbdev, und schreibe keine GBDEV_HOME/GBDEV_CONFIG-Präfixe von Hand. Legacy darf bloßes gbdev oder seinen Bot-Launcher verwenden; sie sind äquivalent.
   • Wenn der gemeinsame Launcher fehlt, installiert init ihn und gbdev-<label> automatisch (deaktivieren mit --no-install; zur Reparatur von Launchern gbdev init erneut ausführen – eigenständiges gbdev install erstellt den Bot-Launcher nicht).
   • Bevorzuge den echten attach_hint, der später von start / run start / pipeline start zurückgegeben wird (und von jedem init/run-JSON, das ihn enthält). tmux attach -t gbdev gilt nur für das Standard-Home; ein nicht standardmäßiges Home verwendet die Sitzung gbdev-<h6> – zitiere attach_hint immer wörtlich, rate niemals. Das Schließen oder erneute Öffnen des Panels, der Panes oder des Terminals hat keine Auswirkungen auf laufende Tasks.
   • home_conflict / launcher_conflict: anhalten und dem Benutzer melden; nicht automatisch löschen oder umbenennen.
   • path_hint wird nur an den Benutzer weitergegeben; niemals Shell rc ändern.

0.B Benachrichtigungsinitialisierung (M5 — nur nach 0.A)

Verwende den command aus 0.A für jeden nachfolgenden Benachrichtigungsaufruf.

1. <command> doctor --json und <command> notify status --json. Behandle Nicht-Benachrichtigungs-Doctor-Fehler wie gewohnt.
2. Erledigt, bleibe still nur wenn result.init.state=verified, init.verified_by_bot dem Label dieses Bots entspricht und der Speicher dieses Bots diese home_id aufzeichnet. enabled=true oder ein HTTP 2xx allein ist nicht erledigt.
3. Wenn verified_by_bot das Label eines anderen Bots ist, nicht neu binden oder initialisieren. Verteile wie gewohnt mit Polling und teile dem Benutzer mit, welchem Label dieses Home gehört. Regel: ein Webhook-Routine pro Bot, eine GBDEV_HOME pro Bot; ein zweiter Bot, der eigene Wake-ups benötigt, verwendet sein eigenes GBDEV_HOME.
4. Andernfalls gehe init.missing_step durch:
   • Noch keine Webhook-Routine: Erstelle die eigene Routine dieses Bots mit Trigger webhook, unter Verwendung des folgenden Routine-Prompts (Bot-Label und vertrautes Home eintragen). Verwende eine vorhandene wieder; erstelle niemals Duplikate. Sende dem Benutzer die Feldlinks des Routine-Panels (Webhook-URL, Webhook-Schlüssel, Authorization-Header) aus dem Routine-Status.
   • setup_secret (der einzige manuelle Schritt des Benutzers): Bitte den Benutzer, die URL und den Schlüssel aus dem Panel zu kopieren und <command> notify setup in seinem Terminal auszuführen – <command> ist der absolute Bot-Launcher-Pfad aus init's result.command (z. B. ~/.gbdev-cli/bin/gbdev-<label> notify setup); bloßes gbdev notify setup nur bei legacy_default (Standard-Home). Die Eingabe wird nicht zurückgegeben; das ist erwartet. Dann dem Benutzer mitteilen, dass es erledigt ist. Der Bot führt setup niemals selbst aus und erfragt oder sieht niemals den Schlüssel.
   • enable / key name: <command> notify enable --key-placement header --key-name Authorization --key-prefix "Bearer " --json entspricht dem Authorization-Header des Controller-Webhook-Panels. Wenn das Panel etwas anderes anzeigt, folge dem Panel; rate niemals.
   • run_test: <command> notify test --json. delivered=true mit http_status 2xx bedeutet, dass die Plattform es akzeptiert hat; awaiting_ack=true bedeutet, dass die aufgeweckte Routine noch bestätigen muss. Ein Fehler ist notify_unavailable; lese error.details.class (z. B. secret = noch nicht konfiguriert oder noch nicht aktiviert).
   • await_ack: Die aufgeweckte Routine führt <command> notify ack <notice_id> --bot <bot_label> --json aus; der Sender bestätigt niemals für sie. Überprüfe notify status alle 15 s für bis zu 2 Minuten. Bei Zeitüberschreitung teile dem Benutzer mit, dass die Plattform den Test akzeptiert hat, die Routine aber nicht bestätigt hat, und überprüfe, ob die Routine aktiviert ist.
5. Wenn init.state=verified und an diesen Bot gebunden, notiere home_id + Bot-Label im Speicher und teile dem Benutzer einmal mit: 通知已接通. Ein neues setup (neuer Schlüssel) macht die Verifizierung ungültig; teste erneut und bestätige dann.
6. Wenn die Benachrichtigungsinitialisierung unvollständig ist, verteile trotzdem, falle auf Polling zurück und nenne den fehlenden Schritt in klaren Worten.

1. Prüfen und starten

Bevorzuge stdin für das Anforderungs-JSON (--request -). Ein Dateipfad ist in Ordnung, wenn der Benutzer oder ein Tool sie bereits vorbereitet hat.

<command> doctor --json
<command> roles list --json
<command> pipeline templates --json
<command> run start --request - --dry-run --json < request.json
<command> run start --request - --json < request.json
# optionale Dateiform, wenn bereits vorbereitet:
# <command> run start --request request.json --json

Melde zuerst jeden Doctor-Check mit ok:false. Verwende decompose: provided, wenn der Benutzer höchstens drei klare Unteraufgaben gegeben hat, sonst den Planer. Notiere result.run_id und teile dem Benutzer die Lanes, das Budget und den Integrationszweig mit. Einzelne Jobs (<command> start) und Pipelines (<command> pipeline start) funktionieren auf die gleiche Weise. Hinweis: Ein --dry-run-Ergebnis gibt ebenfalls eine ID und queued aus; es hat nichts gestartet.

Jedes Startergebnis enthält result.notify={enabled, reason, endpoint_host}. reason nicht null bedeutet pausiert oder defekt; es enthält keine Init-Informationen, also mit notify status bestätigen.

2. Benutzer immer daran erinnern, wie sie zuschauen können

Nach jedem erfolgreichen run start, pipeline start oder start lese result.dashboard. Übernimm attach_hint, watch_hint und window wörtlich; baue den Befehl niemals selbst.

Wenn watch_hint mit gbdev beginnt und das Home nicht das Standard-Home ist, ersetze das erste gbdev durch den Bot-Launcher-Namen (z. B. gbdev-example-dev) bei der Weitergabe an den Benutzer. Gib attach_hint wörtlich weiter (Standard-Home-Sitzung gbdev; nicht standardmäßig gbdev-<h6>).

Wenn enabled=true, reason=null und attach_hint nicht leer ist, sage (in der Sprache des Benutzers):

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

Andernfalls sage:

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

Bedeutungen von reason: disabled_by_config Konfiguration aus; disabled_by_env GBDEV_DASHBOARD=0; tmux_not_found kein tmux; tmux_too_old tmux < 3.2; tmux_error / tmux_timeout tmux ist diesmal fehlgeschlagen; unsafe_argv nicht unterstützte Zeichen in Pfaden; foreign_session eine gleichnamige Sitzung, die nicht von gbdev erstellt wurde und die gbdev niemals berührt; lock_busy ein anderer Prozess aktualisiert das Dashboard.

Wiederhole oder ändere den Task-Ablauf niemals, weil das Dashboard nicht verfügbar ist.

3. Fortschritt verfolgen

Für eine schreibgeschützte Inventarisierung verwende <command> run list --active, <command> pipeline list --active oder <command> list --active im eigenen Home dieses Bots. Alle unterstützen --state <s> (wiederholen oder kommagetrennt), --limit <1..500> (Standard 20) und --json; die Pipeline-Liste unterstützt auch --standalone. Die Job-Liste verbirgt standardmäßig überholte frühere Versuche; --all schließt sie ein, ohne die Job-Fakten zu ändern. gbdev status --all ist nur für die Textliste ohne ID; Status kann --all nicht mit --json oder einer ID kombinieren. Für JSON-Inventar verwende gbdev list --all --json; Status-JSON-Arrays und Einzel-ID-Verhalten ohne --all sind unverändert. Ein needs_input/blocked/failed/timeout/cancelled-Job wird durch einen späteren Versuch in derselben Pipeline-Step-Instanz oder durch einen terminalen übergeordneten Pipeline/eigenen Run überholt (ein terminaler Run genügt, auch wenn seine Pipeline noch nicht terminal ist); korrupte Versuchseinträge überspringen nur die späteren-Versuch-Prüfung, nicht die terminalen-übergeordneten Beweise. status gleicht ab und kann den Zustand schreiben, also verwende es für eine bestimmte Einheit beim Prüfen auf Aktualität/Wiederherstellung, nicht für die schreibgeschützte Inventarisierung. Ein Stale-Flag in einer Liste deutet nur darauf hin, dass Status verwendet werden sollte; es repariert nie etwas.

Webhook-Pfad (Schritt 0 für diesen Bot verifiziert, notify.reason=null): Erstelle keine 10-minütige Polling-Routine. Sage dem Benutzer: 完成或需要你决定时我会自动收到通知。 Die Webhook-Routine erledigt das Follow-up.

Stündlicher Wochentags-Fallback (optional, vom Operator konfigurierte Richtlinie; gleiche Lebenszyklusregeln wie Rezept §11.3): einmal pro Stunde innerhalb der vom Operator konfigurierten Wochentage, Zeitzone und Arbeitszeiten (optionales Beispielrichtlinie). Führe Mac-Befehle nur aus, während der Speicher noch aktive Run/Pipeline/Job-Einheiten hat; bei keinen aktiven Einheiten, beende still. Reihenfolge: <command> notify status --json → <command> notify flush --wait-ms 20000 --json → Status jeder aktiven Einheit. Wenn die aktuelle Aufmerksamkeit created_at älter als 1 Stunde ist, den Benutzer in den Nachrichten fragen, ob das Projekt noch aktiv ist.`