robbin/grokbot-local-agent

Aufruf des Pi Agent auf dem Bot-Computer

Pi ist ein Kommandozeilen-Coding-Agent, der auf dem Bot-Computer installiert ist. Das Standardmodell ist DeepSeek Flash, Denkstufe hoch. Er kann Dateien lesen und schreiben, Befehle ausführen und das Internet durchsuchen. Detaillierte Installations- und Konfigurationsanweisungen findest du in der Datei docs/setup-guide.md im Repository. Die Skripte befinden sich in ~/tools/pi-call/ (dem bin/-Verzeichnis des Repos).

Nutzungsstrategie

Die Modellnutzung des Bots selbst ist begrenzt. Pi verwendet das eigene Modellkonto des Benutzers (standardmäßig DeepSeek) und hat ein separates Kontingent. Daher werden schwere Aufgaben standardmäßig an Pi delegiert, während der Bot nur die Koordination und Qualitätskontrolle übernimmt.

An Pi delegieren:

• Batch-Dateiverarbeitung: Massenänderungen an Dateien, Daten organisieren, Formatkonvertierungen.
• Coden: Skripte, kleine Tools, Tests, Debugging.
• Lange Recherchen und Internetsuche.
• Lange Rohtexte: Erste Versionen von Dokumenten, Berichten, Artikeln.
• Wenn der Benutzer explizit möchte, dass Pi etwas macht, eine Zweitmeinung einholt oder einen Vergleich zum gleichen Thema anfordert.

Der Bot erledigt selbst:

• Kurze Gespräche und Fragen, die in ein oder zwei Schritten beantwortet werden können.
• Connector-Operationen (Gmail, X, GitHub usw.), auf die Pi keinen Zugriff hat.
• Bestätigungen vor dem Senden, Veröffentlichen, Pushen oder Bereitstellen sowie die Berichterstattung an den Benutzer.

Vorgehensweise:

• Halte die Anweisungen kurz: Gib klar das Ziel an, wo die Eingabe liegt, in welche Datei die Ausgabe geschrieben werden soll und was die Erfolgskriterien sind. Ein paar Zeilen reichen. Füge keine langen Textpassagen in den Prompt ein; lass Pi die Datei selbst lesen.
• Ergebnisse direkt als Datei speichern: Gib im Prompt den Ausgabepfad an, damit Pi die Datei schreibt. Der Bot prüft das Ergebnis und liefert die Datei direkt aus, ohne sie noch einmal neu zu schreiben. Wenn Änderungen nötig sind, rufe Pi mit derselben Sitzung auf, damit es die Änderungen vornimmt.
• Wichtige Schlussfolgerungen festhalten: Wichtige Schlussfolgerungen, Entscheidungen oder Daten aus der Aufgabe werden vom Bot aktiv im Gedächtnis oder in relevanten Dokumenten gespeichert und nicht nur in der Sitzung von Pi belassen.

Schritte

1. Bestimme das Arbeitsverzeichnis: Gib Pi nur das Verzeichnis, das für die Aufgabe benötigt wird (das Repository oder /tmp/<Aufgabe>). Gib nicht / oder das gesamte Heimatverzeichnis.
2. Sitzungsnamen vergeben: Verwende kurze englische kebab-case-Namen, eine Aufgabe ein Name (z. B. news-i18n). Nachfolgende Änderungen an derselben Aufgabe verwenden denselben Namen; wenn du von vorne beginnen möchtest, verwende einen neuen Namen.
3. Ausgabeposition festlegen: Wenn es keinen passenderen Zielort gibt, verwende /tmp/pi-out/<Sitzungsname>/. Ergebnisse, die aufbewahrt oder synchronisiert werden sollen, schreibe direkt an den Ort, an den sie gehören (das entsprechende Repository, Dokumenten- oder Notizverzeichnis).
4. Prompt schreiben: Kurz und vollständig. Erkläre das Ziel, die Einschränkungen, den Pfad der Ausgabedatei und die Erfolgskriterien. Lasse Pi am Ende melden, welche Dateien es geschrieben hat und eine einzeilige Zusammenfassung. Pi sieht den Chatverlauf nicht. Gib notwendigen Hintergrund in ein oder zwei Sätzen; für langes Material gib den Dateipfad an.
5. Aufruf. Verwende für Aufgaben, die länger als ein oder zwei Minuten dauern, immer pi-task. Es vergibt eine Aufgaben-ID und zeichnet den Status und den Verlauf auf. Die Ergebnisse werden in einer Datei gespeichert:

   ~/tools/pi-call/pi-task run <Arbeitsverzeichnis> "<Prompt>" --session <Sitzungsname> --owner <deine-agenten-id> [--timeout Sekunden] [--no-write] [--no-web]
   

   --owner ist erforderlich: Es kennzeichnet die Aufgabe für den Bot, der sie vergeben hat, damit die Benachrichtigung bei Abschluss den richtigen Bot findet. pending/ack verwenden es auch, um zu verhindern, dass verschiedene Bots sich gegenseitig die Ergebnisse stehlen oder Aufgaben für andere bestätigen. Ohne Angabe läuft die Aufgabe trotzdem (owner wird auf null gesetzt, stderr gibt eine Warnung aus), aber die Benachrichtigung kann nicht zurückgeleitet werden. (Die Umgebungsvariable PI_TASK_OWNER kann einen Standardwert bereitstellen, aber die explizite Übergabe ist sicherer.) Die eigene Agenten-ID befindet sich im eigenen Profilpfad (z. B. /home/box/agent-data/agents/<deine-agenten-id>/profile.json). Verwende den Hintergrundausführungsmodus des Shell-Tools (blockiert nicht). Verwende kein nohup, & oder setsid. Die erste Ausgabezeile ist TASK <Aufgaben-ID>; am Ende werden der Status und der Pfad zu result.md ausgegeben. Exit-Codes: 0 erfolgreich, 1 fehlgeschlagen, 124 Zeitüberschreitung, 130 abgebrochen. Andere Unterbefehle: status <ID> (Status, Owner, verstrichene Zeit, letzte Ereignisse), log <ID> [-n 30], list [--all] [--owner <id>|none], cancel <ID>, pending [--owner <id>|none] (abgeschlossene, aber noch nicht gemeldete Aufgaben), ack <ID> [--owner <id>|none] (als gemeldet markieren; bei nicht übereinstimmendem Owner wird abgelehnt, Exit-Code 1). Aufgabendaten befinden sich in ~/.pi/tasks/<Aufgaben-ID>/: status.json, events.jsonl, result.md, prompt-<n>.txt. Nach einem Neustart des Bot-Computers werden noch laufende Aufgaben als interrupted markiert; der Benutzer wird gefragt, ob sie erneut ausgeführt werden sollen. Abschlussbenachrichtigung: Wenn die Umgebungsvariablen PI_NOTIFY_URL und PI_NOTIFY_SECRET gesetzt sind (als Umgebungsvariablen auf dem Bot-Computer gespeichert, nicht in Dateien), sendet pi-task nach Abschluss einer Aufgabe eine {source, id, owner, state, exit_code}-Nachricht an diesen Webhook (ohne Aufgabeninhalt). Der empfangende Routine-Agent wacht auf, führt pending --owner <eigene-id> aus, prüft, meldet und bestätigt mit ack --owner <eigene-id>. Er verarbeitet nur Aufgaben, deren Owner er selbst ist; Aufgaben anderer Bots werden nicht geprüft oder bestätigt, sondern per SendToAgent (priority true) an den Owner-Bot weitergeleitet. Wenn die Routine-Aufgabenumgebung keine Nachrichten senden kann, wird die Weiterleitung an den Bot selbst übergeben. Aufgaben ohne Owner werden nur dem Benutzer gemeldet, nicht bestätigt. Ohne Konfiguration wird die Benachrichtigung automatisch übersprungen; das Sendeergebnis wird im notify-Ereignis von events.jsonl festgehalten. Mit PI_NOTIFY_OFF=1 kann die Benachrichtigung vorübergehend deaktiviert werden. Fallback-Berichterstattung: Es kann vorkommen, dass Abschlussbenachrichtigungen nicht ankommen. Daher sollte jeder Agent bei jedem Aufwachen (durch Benutzernachricht, Routineaufgabe usw.) und wenn Pi-Aufgaben anstehen, zuerst pi-task pending --owner <eigene-id> ausführen, um nur seine eigenen Aufgaben zu prüfen, abgeschlossene, aber noch nicht gemeldete Aufgaben zu prüfen, auszuliefern und dann mit ack <ID> --owner <eigene-id> zu bestätigen. Bestätige nur deine eigenen Aufgaben; die Aufgaben anderer überlasse dem Bot, der sie vergeben hat. Für kurze Frage-Antwort-Aufgaben, die in einigen zehn Sekunden erledigt werden können, kann ein synchroner Aufruf verwendet werden:

   ~/tools/pi-call/pi-run <Arbeitsverzeichnis> "<Prompt>" --session <Sitzungsname> [--timeout Sekunden]
   

   Für reinen Lesezugriff oder wenn ein anderes Modell benötigt wird, verwende das zugrunde liegende Skript:

   ~/tools/pi-call/pi-call.mjs <Arbeitsverzeichnis> deepseek/deepseek-flash "<Prompt>" --thinking high [--allow-write] [--no-web] [--session <Sitzungsname>] [--timeout Sekunden]
   

   Bei pi-run und pi-call.mjs besteht die Standardausgabe nur aus der letzten Antwort von Pi; das Standard-Timeout beträgt 300 Sekunden; Exit-Code 0 erfolgreich, 1 Fehler, 124 Zeitüberschreitung, 127 Pi nicht gefunden. Berechtigungen: pi-task run und pi-run gewähren standardmäßig Zugriff auf alle Tools (Lesen, Suchen, Befehle ausführen, Dateien schreiben, Internetsuche); pi-call.mjs hat ohne --allow-write nur Lese-Tools.
6. Ergebnisse prüfen: Die Antwort von Pi ist nur seine Behauptung. Verwende git diff, führe Tests aus oder lies die Dateien, um sicherzustellen, dass es die Arbeit tatsächlich erledigt hat, bevor du sie an den Benutzer weitergibst. Gib ungeprüfte Schlussfolgerungen nicht als Tatsachen wieder.
7. Weitere Änderungen: Für Aufgaben von pi-task verwende pi-task reply <Aufgaben-ID> "<Was geändert werden soll>" (dieselbe Sitzung, dasselbe Verzeichnis, übernimmt den Owner der ursprünglichen Aufgabe; wird abgelehnt, wenn die Aufgabe noch läuft). Für Aufgaben von pi-run rufe es mit demselben --session erneut auf. Die Sitzungen beider werden getrennt gespeichert und können nicht aneinander angeschlossen werden.

Regeln

• Es wird das eigene Modellkontingent des Benutzers verwendet (Internetsuche verwendet das eigene Suchdienstkontingent des Benutzers). Rufe nach Bedarf auf, keine sinnlosen Wiederholungen oder massenhaften Leerläufe.
• Code pushen, Bereitstellungen, DNS- oder Online-Dienste ändern, Nachrichten oder E-Mails senden, wichtige Dateien löschen – all das wird nicht an Pi delegiert; dies erledigt der Bot selbst und holt vorher die Zustimmung des Benutzers ein.
• Pi darf keine ~/.pi/agent/auth.json, keine Schlüsseldateien und keine Schlüssel aus Umgebungsvariablen lesen oder ausgeben.
• Keine Aufgaben anderer bestätigen: pending/ack immer mit --owner <eigene-id> verwenden. Wenn der Owner nicht übereinstimmt, leite die Aufgabe an den vergebenden Bot weiter.
• Gib in der für den Benutzer sichtbaren Antwort an, dass „Pi X gemacht hat“ und erkläre, was du geprüft hast.

Fehlerbehebung

• pi: command not found: Zuerst export PATH=$HOME/.local/bin:$HOME/.node22/bin:$PATH ausführen.
• Kein verfügbares Modell: Die DeepSeek-Anmeldung ist abgelaufen. Der Benutzer muss auf dem Desktop-Terminal pi ausführen und mit /login neu anmelden; der Bot kann den Benutzer nicht anmelden.
• Zeitüberschreitung: Teile die Aufgabe in kleinere Teile auf oder erhöhe --timeout.
• Fehler oder falsches Ergebnis: Überprüfe zuerst den Exit-Code und die --verbose-Protokolle. Wenn die Aufgabe selbst falsch ist, rufe Pi mit derselben Sitzung auf und weise auf das Problem hin, damit es die Aufgabe wiederholt – maximal ein- oder zweimal. Wenn es immer noch nicht funktioniert, übernimmt der Bot selbst und teilt dem Benutzer mit, was Pi nicht richtig gemacht hat. Führe keine wiederholten, sinnlosen Durchläufe durch.