diff --git a/gitea-issues/README.md b/.cursor/agents/README.md similarity index 73% rename from gitea-issues/README.md rename to .cursor/agents/README.md index 6d8f2dd..0330e99 100644 --- a/gitea-issues/README.md +++ b/.cursor/agents/README.md @@ -1,6 +1,15 @@ -# Gitea issues – scripts et agent +# Gitea issues – scripts et agents -Dossier dédié au traitement des tickets (issues) Gitea du dépôt **4nk/lecoffre_ng** (https://git.4nkweb.com/4nk/lecoffre_ng/issues). Toute la logique d’appel API et Git est dans les scripts ; l’agent orchestre et appelle /fix ou /evol. +Dossier dédié au traitement des tickets (issues) Gitea du dépôt **4nk/lecoffre_ng** (https://git.4nkweb.com/4nk/lecoffre_ng/issues). Toute la logique d'appel API et Git est dans les scripts ; les agents orchestrent et appellent /fix ou /evol. + +## Agents (.cursor/agents/) + +| Agent | Fichier | Rôle | +|-------|---------|------| +| **agent-loop** | `agent-loop.md` | Orchestre la boucle de récupération des mails et le traitement : lance les 2 boucles en arrière-plan (récupération + traitement, pas de timeout) ou exécute x fois (récupération 1 fois puis traitement 1 fois via gitea-issues-process). | +| **gitea-issues-process** | `gitea-issues-process.md` | Traite les issues Gitea et les mails en attente : liste les issues/mails, crée des branches, lance /fix ou /evol, /push-by-script ; workflow mails (fil, réponse réelle, marquage lu). | + +Spooler tickets (nouveau) : mails dans **projects//data/issues/** (filtre par `tickets.authorized_emails` dans conf.json), pas de « non lu », aucun enregistrement supprimé. Format : `gitea-issues/TICKETS_SPOOL_FORMAT.md`. Récupération : `./ia_dev/gitea-issues/tickets-fetch-inbox.sh`. Référence boucle mails (legacy) : `gitea-issues/AGENT_LOOP.md`. Hook Cursor : `sessionStart` → `.cursor/hooks/remonter-mails.sh` (lit `projects//data/issues/*.pending`). ## Contexte d'exécution @@ -28,9 +37,12 @@ Dossier dédié au traitement des tickets (issues) Gitea du dépôt **4nk/lecoff | `mail-send-reply.sh` | `./gitea-issues/mail-send-reply.sh --to --subject "..." [--body "..." \| stdin] [--in-reply-to "" [--references "..."]]` | Envoie une réponse par mail via le Bridge (SMTP) ; signature « Support IA du projet Lecoffre.io » / ai.support.lecoffreio@4nkweb.com ajoutée automatiquement. | | `mail-create-issue-from-email.sh` | `./gitea-issues/mail-create-issue-from-email.sh --uid [--title "..." ] [--body "..."]` | Crée une issue à partir d’un mail (UID), optionnel titre/corps formalisés ; marque le mail lu. | | `mail-mark-read.sh` | `./gitea-issues/mail-mark-read.sh ` | Marque un mail comme lu. | -| `mail-thread-log.sh` | `./gitea-issues/mail-thread-log.sh get-id \| init \| append-sent \| append-issue \| append-commit ...` | **Log par fil** : un fichier par conversation dans `logs/gitea-issues/threads/` (échanges reçus/envoyés, tickets, commits). `get-id --uid ` affiche `THREAD_ID=...` ; `init --uid ` crée/met à jour le fichier ; `append-sent/issue/commit` enregistrent une réponse, une issue ou un commit. | +| `mail-thread-log.sh` | `./gitea-issues/mail-thread-log.sh get-id \| init \| append-sent \| append-issue \| append-commit ...` | **Log par fil** : un fichier par conversation dans `projects//logs/gitea-issues/threads/` (échanges reçus/envoyés, tickets, commits). `get-id --uid ` affiche `THREAD_ID=...` ; `init --uid ` crée/met à jour le fichier ; `append-sent/issue/commit` enregistrent une réponse, une issue ou un commit. | | `mail-to-issue.sh` | `./gitea-issues/mail-to-issue.sh` | **Batch** : crée une issue par mail non lu (titre = sujet, corps = texte + From), marque lus. À éviter si on suit le workflow agent (voir ci‑dessous). | -| `agent-loop.sh` | `./gitea-issues/agent-loop.sh [interval_sec]` | **Boucle de surveillance** : exécute périodiquement `mail-list-unread.sh`, met à jour un fichier témoin (`logs/gitea-issues/agent-loop.status`) pour indiquer si la boucle est active, et écrit les mails en attente dans `agent-loop.pending`. Voir `gitea-issues/AGENT_LOOP.md`. | +| `agent-loop.sh` | `./ia_dev/gitea-issues/agent-loop.sh [interval_sec]` | **Boucle de surveillance** : exécute périodiquement `mail-list-unread.sh`, met à jour un fichier témoin (`projects//logs/gitea-issues/agent-loop.status`) et écrit les mails en attente dans `agent-loop.pending`. Voir `gitea-issues/AGENT_LOOP.md`. | +| `agent-loop-treatment.sh` | `./ia_dev/gitea-issues/agent-loop-treatment.sh` | **Boucle traitement** : vérifie périodiquement `agent-loop.pending` ; si non vide, lance l'agent Cursor (workflow gitea-issues-process) pour traiter les mails. À lancer en arrière-plan (pas de timeout). | +| `agent-loop-retrieval-once.sh` | `./ia_dev/gitea-issues/agent-loop-retrieval-once.sh` | **Récupération une fois** (legacy, basé non lu) : exécute `mail-list-unread.sh` et écrit dans `agent-loop.pending`. Utilisé par l'agent agent-loop pour les cycles « x fois ». | +| `tickets-fetch-inbox.sh` | `./ia_dev/gitea-issues/tickets-fetch-inbox.sh` | **Récupération par expéditeurs autorisés** : filtre `tickets.authorized_emails` (conf.json), pas de marquage lu/non lu. Écrit les nouveaux mails dans `projects//data/issues/__.pending` (JSON). Voir `TICKETS_SPOOL_FORMAT.md`. | Variables optionnelles : `GITEA_API_URL`, `GITEA_REPO_OWNER`, `GITEA_REPO_NAME`, `GITEA_ISSUES_DIR`. @@ -39,8 +51,8 @@ Variables optionnelles : `GITEA_API_URL`, `GITEA_REPO_OWNER`, `GITEA_REPO_NAME`, **Ne pas enchaîner directement** : l’agent doit d’abord lire les non lus, formaliser l’issue ou répondre par mail, et ne créer/traiter qu’au moment où la demande est prête. 1. **Lire les non lus** : `./gitea-issues/mail-list-unread.sh` (ne marque pas les mails comme lus). -2. **Pour chaque mail** : consulter **tout l'historique du fil** avec `./gitea-issues/mail-get-thread.sh `, créer/mettre à jour le **log du fil** avec `./gitea-issues/mail-thread-log.sh init --uid ` (sortie `THREAD_ID=...` à conserver), puis décider soit d’envoyer une réponse directe (demande d’infos) via `mail-send-reply.sh`, soit de formaliser et créer l’issue avec `mail-create-issue-from-email.sh` (optionnel `--title` / `--body` formalisés). Si la demande est une correction/évolution prête : créer l’issue, traiter (fix/evol), commenter l’issue, répondre au mail via `mail-send-reply.sh` (avec `--in-reply-to` pour le fil). -3. **Réponses aux mails** : toujours via le Bridge avec `mail-send-reply.sh`. Chaque envoi est enregistré dans le log du fil avec `mail-thread-log.sh append-sent`. +2. **Pour chaque mail** : consulter **tout l'historique du fil** avec `./gitea-issues/mail-get-thread.sh `, créer/mettre à jour le **log du fil** avec `./gitea-issues/mail-thread-log.sh init --uid ` (sortie `THREAD_ID=...` à conserver), puis décider soit d’envoyer une réponse directe (demande d’infos) via `mail-send-reply.sh`, soit de formaliser et créer l’issue avec `mail-create-issue-from-email.sh` (optionnel `--title` / `--body` formalisés). Si la demande est une correction/évolution prête : créer l’issue, traiter (fix/evol), commenter l’issue, répondre au mail via `mail-send-reply.sh` (avec `--in-reply-to` pour le fil). **Le corps de la réponse** doit contenir la **réponse réelle** à la question (ex. si le mail demande « Décrit les rôles », le body = une description des rôles), jamais le sujet du mail ni la question reçue. +3. **Réponses aux mails** : toujours via le Bridge avec `mail-send-reply.sh`. Le `--body` doit être la **réponse réelle** rédigée par l'agent (contenu de la réponse à la demande), pas le sujet du mail, pas la question reçue, pas un message précédent du fil. Chaque envoi est enregistré dans le log du fil avec `mail-thread-log.sh append-sent --thread-id --to --subject "..." --body "..."` pour tracer l'expéditeur, le titre et le corps de la réponse envoyée. **Prérequis :** @@ -97,9 +109,10 @@ Le répertoire `docs/` n'est pas versionné. Pour disposer d'une copie locale ( La connaissance du projet peut reposer **uniquement sur le wiki** (sans lire `docs/`) : les agents peuvent exécuter `./gitea-issues/wiki-get-page.sh ` pour récupérer le contenu markdown d’une page et l’utiliser comme référence. Exemples : `./gitea-issues/wiki-get-page.sh Home`, `./gitea-issues/wiki-get-page.sh Operations`, `./gitea-issues/wiki-get-page.sh Code-Standards`. Prérequis : token Gitea (comme pour les autres scripts wiki). Les agents peuvent ainsi consulter la doc projet à la demande depuis le wiki, sans dépendre des fichiers locaux `docs/`. -## Agent +## Agents (commandes) -Commande **/gitea-issues-process** (agent `.cursor/agents/gitea-issues-process.md`) : traite un ou plusieurs tickets en s’appuyant uniquement sur ces scripts, puis appelle /fix ou /evol et /push-by-script. Voir le fichier de l’agent pour le workflow exact. +- **/agent-loop** (`agent-loop.md`) : lance les 2 boucles (récupération + traitement) en arrière-plan ou exécute x cycles (récupération 1 fois puis traitement 1 fois). À la fin d'une boucle de récupération, la boucle traitement lance gitea-issues-process sur les mails reçus. +- **/gitea-issues-process** (`gitea-issues-process.md`) : traite les issues Gitea et les mails en attente (workflow script au maximum, /fix ou /evol, /push-by-script). Voir le fichier de l'agent pour le workflow exact. ## Référence diff --git a/.cursor/agents/agent-loop.md b/.cursor/agents/agent-loop.md new file mode 100644 index 0000000..2eeac7e --- /dev/null +++ b/.cursor/agents/agent-loop.md @@ -0,0 +1,77 @@ +--- +name: agent-loop +description: Orchestre la boucle de récupération des mails et le traitement par gitea-issues-process. Peut lancer 2 boucles en arrière-plan (récupération + traitement, pas de timeout) ou exécuter x fois (récupération 1 fois puis traitement 1 fois). +model: inherit +is_background: false +--- + +# Agent agent-loop + +**Contexte projet :** La configuration et la documentation du projet sont dans `projects//` ; `` = contenu du fichier `../ai_project_id` (à la racine du dépôt projet, parent de ia_dev). Racine du dépôt projet = `/home/desk/code/lecoffre_ng_test` (ou `..` depuis le workspace ia_dev). Rappeler en début d'exécution : **projet** = contenu de `../ai_project_id`, **branche** = `git -C .. branch --show-current`, **répertoire de travail** = répertoire du dépôt dans `../`. + +**Horodatage** : au début et à la fin d'exécution, afficher date/heure, projet, branche, répertoire de travail du dépôt dans `../`. + +Tu es l'agent qui **orchestre** la surveillance des mails et leur traitement. Tu ne traites pas les mails toi‑même : le traitement (réponse, issues, marquage lu) est fait par l'**agent gitea-issues-process**. Tu lances les scripts et/ou les sous-agents selon la demande. + +**Références obligatoires** : lire `gitea-issues/AGENT_LOOP.md` (fichier témoin, variables, boucles) et `gitea-issues/README.md` (contexte d'exécution). Tous les scripts sont invoqués depuis la **racine du dépôt projet** : `cd && ./ia_dev/gitea-issues/