first
This commit is contained in:
Gilles Soulier
@@ -0,0 +1,306 @@
|
||||
# Livrables — Agent Rust
|
||||
|
||||
Ce document contient :
|
||||
|
||||
1. le fichier `agent/CLAUDE.md`
|
||||
2. un prompt Codex initial pour générer le squelette compilable de `agent/`
|
||||
|
||||
---
|
||||
|
||||
## 1) `agent/CLAUDE.md`
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md — Mesh Agent (Rust)
|
||||
|
||||
## Portée
|
||||
Ce fichier s’applique **uniquement** au code situé dans `agent/`.
|
||||
Il complète le `CLAUDE.md` racine (vision/architecture). En cas de conflit, le `CLAUDE.md` racine prime.
|
||||
|
||||
---
|
||||
|
||||
## Objectifs de l’agent
|
||||
- Multi-OS (Linux, Windows, macOS)
|
||||
- Faible charge serveur : le serveur ne transporte pas de flux lourds
|
||||
- Data-plane performant :
|
||||
- **QUIC (TLS 1.3)** pour fichiers/dossiers/terminal
|
||||
- fallback HTTP temporaire (exceptionnel)
|
||||
- Terminal share robuste via PTY (preview par défaut)
|
||||
- Notifications directes Gotify
|
||||
|
||||
---
|
||||
|
||||
## Rappels d’architecture
|
||||
- Control plane : Mesh Server (REST + WS)
|
||||
- auth, rooms, ACL
|
||||
- capability tokens TTL court
|
||||
- orchestration des sessions P2P
|
||||
- Data plane : agent ↔ agent
|
||||
- QUIC via `quinn`
|
||||
- handshake applicatif obligatoire `P2P_HELLO`
|
||||
|
||||
---
|
||||
|
||||
## Règles de sécurité (non négociables)
|
||||
- Aucun contournement des capability tokens.
|
||||
- Terminal : **preview-only** par défaut.
|
||||
- Input distant uniquement si :
|
||||
1) serveur a accordé `terminal:control`
|
||||
2) l’agent propriétaire confirme/maintient le contrôleur actif
|
||||
- Ne jamais exfiltrer : clés SSH, mots de passe, variables secrètes.
|
||||
- Logs sans contenu sensible (pas de contenu de terminal en clair dans les logs).
|
||||
|
||||
---
|
||||
|
||||
## Contraintes de code Rust
|
||||
- Rust stable
|
||||
- Async : `tokio`
|
||||
- HTTP : `reqwest`
|
||||
- WebSocket : `tokio-tungstenite`
|
||||
- QUIC : `quinn`
|
||||
- Config : `serde` + `toml` (ou yaml)
|
||||
- Logs : `tracing`
|
||||
|
||||
Qualité :
|
||||
- Interdiction de `unwrap()` / `expect()` en code final
|
||||
- Erreurs explicites (`Result`) + `thiserror` recommandé
|
||||
- Tests stubs acceptés, mais structure prête
|
||||
|
||||
---
|
||||
|
||||
## Structure obligatoire du dossier
|
||||
Ne pas renommer arbitrairement.
|
||||
|
||||
```
|
||||
|
||||
agent/ Cargo.toml src/ main.rs config/ mesh/ p2p/ quic/ share/ terminal/ notifications/ os/ tests/
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Développement : ordre recommandé
|
||||
1) **Squelette compilable** + config + logs
|
||||
2) Client Mesh (REST + WS)
|
||||
3) Notifications Gotify (agent → gotify)
|
||||
4) Terminal preview via PTY (local) + stream (transport abstrait)
|
||||
5) QUIC : endpoint + handshake `P2P_HELLO`
|
||||
6) Terminal preview sur QUIC
|
||||
7) File transfer sur QUIC
|
||||
8) Folder zip sur QUIC
|
||||
9) Terminal take-control (arbitrage via serveur)
|
||||
|
||||
---
|
||||
|
||||
## Consigne de suivi d’avancement
|
||||
À chaque jalon significatif **ou** vers ~80 % d’une session de travail, produire :
|
||||
|
||||
```
|
||||
|
||||
ÉTAT D’AVANCEMENT – Mesh Agent ✔ Terminé :
|
||||
|
||||
- ... ◻ En cours :
|
||||
- ... ✖ À faire :
|
||||
- ... Risques / points bloquants :
|
||||
- ... Prochaine action recommandée :
|
||||
- ...
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gestion du contexte (pour Claude)
|
||||
- Utiliser `/clear` entre tâches distinctes.
|
||||
- Pour revue sécurité/perf : utiliser un sous-agent.
|
||||
|
||||
Le contexte durable doit rester dans :
|
||||
- `CLAUDE.md` (racine)
|
||||
- ce `agent/CLAUDE.md`
|
||||
- `docs/`.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2) Prompt Codex initial — squelette compilable `agent/`
|
||||
|
||||
```markdown
|
||||
# Codex Prompt — Mesh Agent (Rust) : Skeleton compilable (étape 1)
|
||||
|
||||
Contexte
|
||||
- Projet Mesh : server Python (control plane), client web, agent Rust (data plane QUIC).
|
||||
- Références : `CLAUDE.md` racine + `agent.md` + `agent/CLAUDE.md`.
|
||||
|
||||
Objectif
|
||||
- Générer un squelette **compilable** du dossier `agent/` (Rust stable) avec la structure imposée.
|
||||
- Aucun code “tout-en-un”. Travail en modules minimalistes.
|
||||
|
||||
Règles
|
||||
- Rust stable, tokio, tracing.
|
||||
- Pas de unwrap/expect dans le code final.
|
||||
- Erreurs via Result + thiserror.
|
||||
- Config via serde + toml.
|
||||
|
||||
Livrables attendus
|
||||
1) `agent/Cargo.toml` avec dépendances minimales : tokio, tracing, tracing-subscriber, serde, toml, reqwest, tokio-tungstenite, thiserror.
|
||||
2) Arborescence `src/` avec modules vides mais raccordés :
|
||||
- config/
|
||||
- mesh/ (rest.rs, ws.rs, types.rs)
|
||||
- notifications/ (gotify.rs, router.rs)
|
||||
- terminal/ (mod.rs, stream.rs)
|
||||
- p2p/quic/ (endpoint.rs, protocol.rs)
|
||||
- share/ (file_send.rs, folder_zip.rs)
|
||||
- os/ (autostart.rs, tray.rs)
|
||||
3) `src/main.rs` :
|
||||
- charge config
|
||||
- init tracing
|
||||
- démarre runtime tokio
|
||||
- affiche un log “agent started”
|
||||
4) `agent/README.md` : commandes build/run
|
||||
5) `agent/.env.example` (si utile) + `config.example.toml`
|
||||
|
||||
Ne pas implémenter la logique QUIC/WS complète maintenant : uniquement les stubs d’API et la compilation.
|
||||
|
||||
Stop
|
||||
- Quand tout compile (`cargo build`), terminer et fournir un court résumé des fichiers créés.
|
||||
- Si tu estimes être à ~80 % de l’objectif, produire un état d’avancement au format imposé avant d’aller plus loin.
|
||||
```
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Traçabilité des modifications de code (obligatoire)
|
||||
|
||||
Chaque **agent (Claude principal, sous-agent, Codex, ou autre)** qui **crée ou modifie du code** doit **explicitement l’indiquer dans les fichiers concernés**.
|
||||
|
||||
### Règles de traçabilité
|
||||
|
||||
- **Tout fichier créé** doit contenir un commentaire en **début de fichier** indiquant :
|
||||
|
||||
- l’agent auteur,
|
||||
- la date,
|
||||
- l’objectif de la création.
|
||||
|
||||
- **Toute modification d’un fichier existant** doit être signalée :
|
||||
|
||||
- soit par un commentaire en **début de fichier** (si modification importante),
|
||||
- soit par un commentaire **en fin de ligne** ou à proximité immédiate du changement (si modification ponctuelle).
|
||||
|
||||
### Format imposé des commentaires
|
||||
|
||||
#### Création de fichier
|
||||
|
||||
```text
|
||||
// Created by: <agent_name>
|
||||
// Date: YYYY-MM-DD
|
||||
// Purpose: <short description>
|
||||
```
|
||||
|
||||
#### Modification de fichier
|
||||
|
||||
```text
|
||||
// Modified by: <agent_name> — YYYY-MM-DD — <reason>
|
||||
```
|
||||
|
||||
Le format exact peut être adapté au langage (Rust, Python, TypeScript…), mais **les informations doivent toujours être présentes**.
|
||||
|
||||
### Agents concernés
|
||||
|
||||
Cette règle s’applique à :
|
||||
|
||||
- Claude (agent principal),
|
||||
- tous les **sous-agents**,
|
||||
- **Codex** ou tout autre générateur de code,
|
||||
- toute automatisation produisant ou modifiant des fichiers.
|
||||
|
||||
### Objectif
|
||||
|
||||
- garantir une **traçabilité claire** des décisions et des changements,
|
||||
- faciliter les revues (sécurité, performance, architecture),
|
||||
- permettre de comprendre rapidement **qui a fait quoi et pourquoi**.
|
||||
|
||||
Cette consigne est **obligatoire et non optionnelle** pour le projet Mesh.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Traçabilité des modifications de code (obligatoire)
|
||||
|
||||
Toute **création ou modification de code** réalisée pour l’agent Mesh doit indiquer **explicitement l’agent auteur**.
|
||||
|
||||
### Règles
|
||||
|
||||
- **Création de fichier** : commentaire en début de fichier.
|
||||
- **Modification importante** : commentaire en début de fichier.
|
||||
- **Modification ponctuelle** : commentaire en fin de ligne ou à proximité immédiate.
|
||||
|
||||
### Formats imposés (à adapter au langage)
|
||||
|
||||
**Création**
|
||||
|
||||
```text
|
||||
// Created by: <agent_name>
|
||||
// Date: YYYY-MM-DD
|
||||
// Purpose: <short description>
|
||||
```
|
||||
|
||||
**Modification**
|
||||
|
||||
```text
|
||||
// Modified by: <agent_name> — YYYY-MM-DD — <reason>
|
||||
```
|
||||
|
||||
### Agents concernés
|
||||
|
||||
- Claude (principal)
|
||||
- Sous-agents
|
||||
- Codex / générateurs de code
|
||||
|
||||
### Objectif
|
||||
|
||||
Garantir une **traçabilité claire** (qui / quand / pourquoi) pour les revues sécurité, performance et maintenance.
|
||||
|
||||
Cette règle est **non optionnelle** pour l’agent Mesh.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Traçabilité des modifications de code (obligatoire — Agent)
|
||||
|
||||
Cette règle s’applique **spécifiquement au dossier **`` et est prioritaire pour Codex.
|
||||
|
||||
### Exigences
|
||||
|
||||
- Chaque agent (Claude, sous-agent, Codex) doit **signer ses créations et modifications**.
|
||||
- Aucune PR ou génération de code n’est valide sans cette signature.
|
||||
|
||||
### Formats
|
||||
|
||||
**Création de fichier**
|
||||
|
||||
```text
|
||||
// Created by: <agent_name>
|
||||
// Date: YYYY-MM-DD
|
||||
// Purpose: <short description>
|
||||
```
|
||||
|
||||
**Modification**
|
||||
|
||||
```text
|
||||
// Modified by: <agent_name> — YYYY-MM-DD — <reason>
|
||||
```
|
||||
|
||||
### Placement
|
||||
|
||||
- Début de fichier : création ou refactor majeur.
|
||||
- Fin de ligne / bloc : correction ponctuelle.
|
||||
|
||||
### Objectif
|
||||
|
||||
- Auditabilité
|
||||
- Revue facilitée
|
||||
- Historique lisible sans dépendre des commits
|
||||
|
||||
Cette consigne est **obligatoire** pour toute génération de code dans `agent/`.
|
||||
|
||||
Reference in New Issue
Block a user