robbin/grokbot-local-agent

Appeler l'agent Pi sur le PC du bot

Pi est un agent de codage en ligne de commande installé sur le PC du bot, avec le modèle par défaut DeepSeek Flash, niveau de réflexion élevé. Il peut lire et écrire des fichiers, exécuter des commandes et effectuer des recherches web. Les détails d'installation et de configuration se trouvent dans docs/setup-guide.md du dépôt. Les scripts sont installés dans ~/tools/pi-call/ (répertoire bin/ du dépôt).

Stratégie d'utilisation

Les quotas de modèles du bot lui-même sont limités ; Pi utilise le propre compte de modèle de l'utilisateur (DeepSeek par défaut), avec des quotas séparés de ceux du bot. Ainsi, les tâches lourdes sont confiées par défaut à Pi, le bot ne faisant que l'ordonnancement et la vérification.

Confier à Pi :

• Traitement par lots de fichiers : modification en masse, organisation de données, conversion de formats.
• Écriture de code : scripts, petits outils, tests, débogage.
• Recherche approfondie et recherche web.
• Brouillons longs : première version de documents, rapports, articles.
• Lorsque l'utilisateur demande explicitement à Pi de faire quelque chose, souhaite un second avis ou une comparaison sur le même sujet.

Le bot garde pour lui :

• Les conversations courtes et les questions auxquelles on peut répondre en une ou deux étapes.
• Les opérations sur les connecteurs (Gmail, X, GitHub, etc.) : Pi n'a pas accès à ces connecteurs.
• La confirmation avant d'envoyer, publier, pousser ou déployer, et les rapports à l'utilisateur.

Directives :

• Les instructions doivent être courtes : précisez l'objectif, l'entrée, l'emplacement de sortie (fichier), les critères de réussite. Quelques lignes suffisent ; ne copiez pas de longs passages dans le prompt, laissez Pi lire les fichiers directement.
• Écrire les résultats directement dans des fichiers : spécifiez le chemin de sortie dans le prompt, laissez Pi écrire le fichier ; après vérification par le bot, livrez ce fichier directement sans le réécrire. Si des modifications sont nécessaires, utilisez la même session pour que Pi les effectue.
• Les conclusions clés doivent être matérialisées : le bot doit écrire activement les conclusions, décisions ou données importantes issues de la tâche dans la mémoire ou les documents pertinents, sans les laisser uniquement dans la session de Pi.

Étapes

1. Déterminer le répertoire de travail : donnez à Pi uniquement le répertoire nécessaire pour la tâche (dépôt ou /tmp/<tâche>), pas / ni tout le répertoire personnel.
2. Nommer la session : utilisez un court kebab-case en anglais, un nom par tâche (ex. news-i18n). Les modifications ultérieures d'une même tâche réutilisent le même nom ; pour repartir de zéro, changez de nom.
3. Définir l'emplacement de sortie : s'il n'y a pas de meilleure destination, utilisez /tmp/pi-out/<nom-de-session>/ ; pour des livrables à conserver ou synchroniser, écrivez-les directement là où ils doivent aller (dépôt, documentation ou répertoire de notes correspondant).
4. Rédiger le prompt : court mais complet, décrivez l'objectif, les contraintes, le chemin du fichier de sortie, les critères de réussite. Terminez en demandant à Pi de rapporter les fichiers écrits et une conclusion en une phrase. Pi ne voit pas l'historique de la conversation ; donnez le contexte nécessaire en une ou deux phrases, et pour les longs documents, fournissez le chemin du fichier.
5. Appeler. Pour les tâches de plus d'une ou deux minutes, utilisez toujours pi-task : il attribue un identifiant, enregistre l'état et la progression, et sauvegarde les résultats dans un fichier.

   ~/tools/pi-call/pi-task run <répertoire-de-travail> "<prompt>" --session <nom-de-session> --owner <votre-id-agent> [--timeout secondes] [--no-write] [--no-web]
   

   --owner est obligatoire : il associe la tâche au bot qui l'a assignée, ce qui permet de retrouver le bot pour la notification et empêche les conflits (pending/ack entre différents bots). Si omis, la tâche s'exécute quand même (owner = null, un avertissement sur stderr), mais les notifications ne seront pas routées correctement. (La variable d'environnement PI_TASK_OWNER peut fournir une valeur par défaut, mais un passage explicite est plus fiable.) Votre propre ID d'agent se trouve dans votre profil (ex. /home/box/agent-data/agents/<votre-id-agent>/profile.json). Utilisez l'exécution en arrière-plan intégrée à l'outil Shell (non bloquante), n'utilisez pas nohup, & ou setsid. La première ligne de sortie est TASK <ID-TÂCHE> ; à la fin, l'état et le chemin de result.md sont affichés. Codes de sortie : 0 terminé, 1 échec, 124 timeout, 130 annulé. Autres sous-commandes : status <ID> (état, owner, durée, événements récents), log <ID> [-n 30], list [--all] [--owner <id>|none], cancel <ID>, pending [--owner <id>|none] (tâches terminées mais non signalées), ack <ID> [--owner <id>|none] (marque comme signalé ; refuse si l'owner ne correspond pas, code de sortie 1). Données des tâches dans ~/.pi/tasks/<ID-TÂCHE>/ : status.json, events.jsonl, result.md, prompt-<n>.txt. Après un redémarrage du PC du bot, les tâches encore en cours sont marquées interrupted ; demandez à l'utilisateur s'il faut relancer. Notification de fin : Si les variables d'environnement PI_NOTIFY_URL et PI_NOTIFY_SECRET sont définies (en tant que variables d'environnement du PC du bot, non écrites dans un fichier), pi-task envoie un webhook {source, id, owner, state, exit_code} (sans le contenu de la tâche) à la fin de chaque tâche. La tâche récurrente réceptrice, une fois réveillée, exécute pending --owner <son propre id>, vérifie, signale et ack --owner <son propre id>. Ne traitez que les tâches dont vous êtes l'owner ; les tâches des autres bots ne sont ni vérifiées ni ackées : utilisez SendToAgent (priority true) pour les transférer au bot propriétaire ; si l'environnement de la tâche récurrente ne peut pas envoyer de message, passez au bot lui-même pour le transfert ; les tâches sans owner se contentent d'avertir l'utilisateur, sans ack. Si le webhook n'est pas configuré, il est ignoré et l'événement de notification est enregistré dans events.jsonl ; définissez PI_NOTIFY_OFF=1 pour le désactiver temporairement. Rapport de secours : Les notifications de fin peuvent ne pas arriver. Donc, à chaque réveil (message utilisateur, tâche récurrente, etc.) avec des tâches confiées à Pi, exécutez d'abord pi-task pending --owner <son propre id> pour ne voir que vos propres tâches. Vérifiez et livrez les tâches terminées mais non signalées, puis ack <ID> --owner <son propre id> ; n'ackez que les vôtres, laissez les tâches des autres bots à leur propriétaire. Pour les questions-réponses courtes qui peuvent être terminées en quelques dizaines de secondes, vous pouvez appeler en avant-plan :

   ~/tools/pi-call/pi-run <répertoire-de-travail> "<prompt>" --session <nom-de-session> [--timeout secondes]
   

   Pour un accès en lecture seule ou un changement de modèle, utilisez le script de bas niveau :

   ~/tools/pi-call/pi-call.mjs <répertoire-de-travail> deepseek/deepseek-flash "<prompt>" --thinking high [--allow-write] [--no-web] [--session <nom-de-session>] [--timeout secondes]
   

   pi-run et pi-call.mjs : la sortie standard contient uniquement la dernière réponse de Pi ; timeout par défaut 300 secondes ; code de sortie 0 succès, 1 erreur, 124 timeout, 127 Pi introuvable. Permissions : pi-task run et pi-run donnent accès à tous les outils par défaut (lecture, recherche, exécution de commandes, écriture de fichiers, recherche web) ; pi-call.mjs sans --allow-write n'a que les outils en lecture seule.
6. Vérifier les résultats : la réponse de Pi n'est que son affirmation. Utilisez git diff, exécutez des tests ou lisez les fichiers pour confirmer qu'il a vraiment fait le travail, puis rapportez à l'utilisateur ; ne prenez pas des conclusions non vérifiées pour des faits.
7. Modifications itératives : pour les tâches pi-task, utilisez pi-task reply <ID-TÂCHE> "<quoi modifier>" (même session, même répertoire, reprend l'owner de la tâche d'origine ; refusé si la tâche est encore en cours) ; pour les tâches pi-run, rappelez avec le même --session. Les sessions des deux sont séparées et ne peuvent pas être enchaînées.

Règles

• Utilisez le quota de modèle de l'utilisateur (la recherche web utilise ses propres services de recherche), appelez selon les besoins, sans exécutions répétées inutiles ou en masse à vide.
• Ne jamais confier à Pi : le push de code, le déploiement, la modification de DNS ou de services en ligne, l'envoi d'e-mails ou de messages, ou la suppression de fichiers importants. Ces actions sont effectuées par le bot lui-même, après accord de l'utilisateur.
• Ne laissez pas Pi lire ou écrire ~/.pi/agent/auth.json, les fichiers de clés ou les clés dans les variables d'environnement.
• N'ackez pas les tâches des autres : pending/ack incluent toujours --owner <votre propre id> ; si l'owner ne correspond pas, transférez au bot qui a assigné la tâche.
• Dans les réponses visibles par l'utilisateur, dites "j'ai demandé à Pi de faire X", précisez ce que vous avez vérifié.

Dépannage

• pi: command not found : exécutez d'abord export PATH=$HOME/.local/bin:$HOME/.node22/bin:$PATH.
• Pas de modèle disponible : la session DeepSeek a expiré, l'utilisateur doit exécuter pi dans un terminal de bureau et /login pour se reconnecter ; le bot ne peut pas se connecter à la place de l'utilisateur.
• Timeout : divisez la tâche en sous-tâches plus petites ou augmentez --timeout.
• Erreur ou résultat incorrect : vérifiez d'abord le code de sortie et les logs --verbose ; si la tâche elle-même est erronée, utilisez la même session pour indiquer le problème et demandez à Pi de refaire la tâche, avec un maximum d'une ou deux tentatives. Si cela ne fonctionne toujours pas, reprenez la tâche avec le bot lui-même et informez l'utilisateur que Pi n'a pas réussi, sans relancer Pi en boucle.