Pi × EvoX Loop — Compétence d'héritage d'expérience pour agents intelligents
Permet à chaque Agent de ne tomber qu'une seule fois dans un piège : les expériences d'échec sont automatiquement stockées (filtre de garde), et les correctifs validés sont automatiquement rappelés pour des tâches similaires.
Convention terminologique (0.29) : Le corps du texte est principalement en français, les champs techniques sont annotés une seule fois en anglais lors de leur première apparition (par exemple « correspondance des signaux signals_match »), puis uniquement en français par la suite, sans mélange répété. Le glossaire complet anglais-français se trouve dans
docs/faq.mdQ17.Carte de documentation (0.21 en couches) :
- Les nouveaux utilisateurs doivent seulement lire trois sections : Prise en main 30 secondes → Flux A → Flux B (environ 60 lignes) ; le reste à consulter selon les besoins.
- Pour décider en une minute si vous devez l'utiliser :
docs/one-pager.md(nouveau en 0.30)- Point d'entrée des meilleures pratiques :
examples/quickstart.md(boucle fermée en 5 minutes) +docs/overview.md(aperçu du projet) +docs/common-mistakes.md(14 anti-patrons) — trois documents couvrant « prise en main / vue d'ensemble / évitement des pièges ».- Le reste de ce fichier = points de déclenchement / résumé de sécurité / anti-patrons rapides / navigation ;
docs/advanced.md= adressage du backfill / chronologie / harvest / verrous concurrentiels / bibliothèque partagée / intégration hôte / opérations / détails des portes de sécurité ;docs/common-mistakes.md= liste complète des utilisations incorrectes courantes ;docs/config-errors.md= erreurs de configuration courantes ;docs/faq.md= FAQ complète.docs/research.md= Flux C expériences contrôlées + discipline de conception des pièges — réservé à la recherche, la plupart des utilisateurs n'ont pas besoin de l'ouvrir.
Prise en main 30 secondes (Quick-Start)
EN : Requires Node >= 22. Optional
@evomap/evolverintegration is GPL-3.0-or-later (only if you install and use--engine evolver); the default light backend is MIT, zero-dependency, zero-exfiltration. Three things only: A recall validated fixes at task start, B deposit after fixing a non-obvious failure, C (optional, research) controlled experiments. Daily use = A/B only. ⚠️ Prérequis : Node ≥ 22 (node -vvérifie ; les versions anciennes ne sont pas supportées, il faut d'abord mettre à niveau). L'intégration optionnelle@evomap/evolverest sous GPL-3.0-or-later — seulement si vous l'installez activement et utilisez--engine evolver; le backend léger par défaut est MIT, zéro dépendance, zéro exfiltration.Cette compétence ne fait que trois choses : A Rappel de correctifs validés au début d'une tâche, B Dépôt après la correction d'un échec non évident, C (optionnel, recherche) Expériences contrôlées pour quantifier les gains. Utilisation quotidienne : uniquement A/B, C est désactivé par défaut, ne l'utilisez pas en production.
# A — Au début de la tâche, rappel ciblé (remplacez par une phrase de votre tâche)
node code/evolver-recall.mjs --query "Gérer l'erreur de fichier d'encodage GBK" --top 5
# B — Après avoir corrigé un échec non évident, collez l'erreur brute pour générer un brouillon, puis complétez avec FIX et enregistrez
node code/light-cli.mjs draft --error "<Erreur brute>" --tool <Nom de l'outil> --context "<Ce que vous étiez en train de faire>"
node code/light-cli.mjs draft --error "<Erreur brute>" --strategy "AVOID : <Ce qu'il ne faut PAS faire> FIX : <Paramètres/commandes/encodages spécifiques>" --commit
Les commandes s'exécutent à la racine du dépôt ; si les dépendances ne sont pas installées, voir la section « Installation » ci-dessous.
Première exécution · 3 étapes pour être prêt (d'abord auto-test, puis dépôt)
- Installez Node ≥22 (le générateur de pièges et pi/evolver l'exigent ; voir FAQ·Q8) ;
- Auto-test de l'environnement :
node code/light-cli.mjs doctor— vérifie la version de Node, l'écriture du répertoire de la base d'expérience, l'accessibilité du répertoire d'enregistrement des succès (des instructions de correction sont données pour les échecs) ; - Allumez la base d'expérience : il est normal d'avoir un message « Aucune méthode de correction à rappeler » pour une base vide ; effectuez un dépôt avec le flux B pour allumer la base.
Lecture obligatoire pour les débutants (FAQ rapide)
- Un message « Aucune méthode de correction à rappeler » apparaît lors du premier rappel ? Normal — la base commence à zéro, effectuez d'abord un dépôt B pour l'initialiser (FAQ·Q1).
- Version de Node requise ? ≥22 (le générateur de pièges nécessite également Python 3), une version trop ancienne fait échouer pi/evolver (FAQ·Q8).
- Plus de questions dans
docs/faq.md(14 questions complètes) et la liste des anti-patrons ci-dessous.
Installation (une fois)
EN : One-time setup. A/B flows need ONLY Node >= 22 — zero npm dependencies. Get the folder by any of three paths below; any location works (a "skill" is just a folder — put it wherever your host expects, e.g.
~/.claude/skills/pi-evox-lab). Default backend = built-in light (pure Node, MIT). evolver is an optional integration (--engine evolver, needsnpm install). Flow C additionally needs Pi CLI + an OpenAI-compatible LLM key.
Trois voies d'obtention (choisissez-en une) :
# Voie 1 : git clone (recommandé)
git clone https://github.com/stwhwing/pi-evox-lab.git && cd pi-evox-lab
# Voie 2 : Réseau restreint → Téléchargement direct du zip de Release (avec sha256), décompressez et utilisez
# https://github.com/stwhwing/pi-evox-lab/releases (miroir national chinois disponible, voir FAQ Q7)
# Voie 3 : Installation en un clic depuis le marché — cherchez pi-evox-loop sur skillhub.cn / ClawHub (pour les utilisateurs de WorkBuddy/OpenClaw)
node -v # Prérequis : Node >= 22 (seule dépendance matérielle)
node code/light-cli.mjs doctor # Auto-test 30 secondes — si réussi, prêt à utiliser, aucune étape d'installation nécessaire
- Les flux A/B quotidiens nécessitent zéro dépendance npm ; les commandes
npm installsuivantes ne sont nécessaires que pour l'intégration optionnelle / le mode expérimental C :
Configuration du fournisseur (uniquement pour le flux C)
EN : Flow C only - any OpenAI-compatible endpoint;
$ENVinterpolation needs pi >= 0.85.1. Examples + domestic endpoints (DeepSeek/Bailian/SiliconFlow/Zhipu):docs/providers.md.
Flux A : Début de tâche — Rappel d'expérience (toute tâche non triviale)
EN : Flow A - recall at task start.
--querywith the task text does targeted recall (unrelated experience is never injected - injection is gated by signals_match x query-token overlap, below threshold = no injection). On error (T3), the raw error text IS the query. Multiple matches: geneConflicts drops anti_patterns-mutual low scorers; no targeted hit = no injection. Register the hit at task end with--register-hit --gene <id>(id-addressed, concurrency-safe).
# Scénario national chinois fréquent (journaux Windows / CSV avec GBK par défaut, lecture en utf-8 provoque une erreur) — après avoir exécuté le starter avec une base vide, essayez d'abord celui-ci, il est le plus efficace
node code/evolver-recall.mjs --query "Lire un journal chinois obtient UnicodeDecodeError" --top 5
# Recommandé : avec le texte de la tâche pour un rappel « ciblé » (les expériences sans rapport avec la tâche ne sont pas injectées)
node code/evolver-recall.mjs --query "<Phrase/signal clé de la tâche en cours>" --top 5
# En cas d'erreur (T3) : le texte d'erreur original sert de requête — l'erreur elle-même est un rappel
node code/evolver-recall.mjs --error "UnicodeDecodeError : le codec 'utf-8' ne peut pas décoder l'octet 0xc4"
- Affiche uniquement la liste des correctifs vérifiés ET passant le garde de correctif ET correspondant à la requête ciblée (une base vide donne un message clair, c'est normal) ;
- Valeurs par défaut des paramètres :
--toppar défaut 5 (l'injection de soft prompt a un coût contextuel, mieux vaut moins que plus) ; la base d'expérience n'a pas de limite de capacité matérielle, mais il est recommandé de garder <500 entrées par base (au-delà, la précision du ciblage diminue ; utilisez des pools partagés pour répartir) ; - Règle de ciblage : score basé sur l'intersection des
signals_matchdu gène avec les mots de la requête ; en dessous du seuil, l'entrée entière n'est pas injectée (évite d'injecter des contenus non ciblés qui augmenteraient les coûts) ; - Conflit entre plusieurs gènes : le garde
geneConflictsa automatiquement éliminé les éléments à faible score mutuellementanti_patterns; si plusieurs restent, prenez le score le plus élevé ; en l'absence d'élément ciblé, il vaut mieux ne pas injecter plutôt que d'utiliser des gènes non pertinents ; - Priorité à l'utilisation si pertinent pour la tâche ; à la fin, enregistrez le succès si un correctif a été effectivement utilisé (
--gene <id>adressé par id, concurrentiel sûr) :
node code/evolver-recall.mjs --register-hit --gene <asset_id ou gene_id> --note "<Phrase de la tâche>"
- N'essayez pas d'adapter des expériences non pertinentes ; les entrées non utilisées n'ont pas besoin d'être enregistrées.
Flux B : Après correction d'un échec — Dépôt d'expérience
EN : Flow B - deposit after fixing a non-obvious failure. Deposit bar (any one): docs/2+ tries needed, environment-specific, counter-intuitive error, or second occurrence. Guided path:
draft --errorauto-extracts signals + pre-fills AVOID + writes anti_patterns; fill in FIX then--commit. Manual path:distillwith explicit signals. strategy MUST be an executable fix (params/commands/encodings) - success summaries are filtered by the repair-signal guard.--shareableonly for genes meant for the shared pool. Critères de décision (satisfaire une seule condition suffit pour mériter d'être déposé) :
- Le processus de diagnostic a nécessité ≥2 consultations de documentation / essais-erreurs pour résoudre ;
- Dépend des caractéristiques de la machine ou de l'environnement (encodage, normes de chemin, différences de shell, environnement réseau) ;
- Le message d'erreur est contre-intuitif, ou ne correspond pas à la description de la documentation ;
- Le même piège est apparu une deuxième fois dans l'historique des tâches. (Si aucune condition n'est satisfaite, un échec ordinaire n'a pas besoin d'être déposé — pour éviter le bruit dans la base d'expérience.)
Chemin recommandé : guidé (collez l'erreur brute, les signaux et « l'expérience négative » sont extraits automatiquement)
# 1) Générer un brouillon : extrait automatiquement signals_match + préremplit le modèle AVOID + écrit anti_patterns (jeton d'expérience négative)
node code/light-cli.mjs draft --error "<Texte d'erreur brut>" --tool <Nom de l'outil en erreur> --context "<Ce que vous étiez en train de faire>"
# 2) Complétez le FIX selon le brouillon, puis enregistrez (--strategy écrase le placeholder prérempli)
node code/light-cli.mjs draft --error "<Texte d'erreur brut>" \
--strategy "AVOID : <Ce qu'il ne faut PAS faire> FIX : <Paramètres/commandes/encodages spécifiques>" --commit
# 3) Révision (machine à états sémantiques à quatre états, voir section « Machine à états de révision » ci-dessous ; approve exécute d'abord une recherche de preuves automatiquement)
node code/light-cli.mjs approve <gene_id>
Limites d'application du modèle AVOID/FIX (écrivez clairement pour ne pas être rejeté par le garde) :
| Champ | Quoi écrire | Limite |
|---|---|---|
AVOID: | Ce qu'il ne faut PAS faire (expérience négative, peut contenir des mots dangereux — ce sont des avertissements) | Une à deux phrases ; n'écrivez pas de résumé de succès |
FIX: | Correctif exécutable spécifique aux paramètres/commandes/encodages | Doit être réellement rempli — les placeholders, les journaux de tentatives, les narrations seront rejetés par depositionGate (fail-closed) |
anti_patterns: | littéral de jeton unique (par exemple assume-default-utf8) | La détection de conflit se fait par correspondance de chaîne entière, n'écrivez pas de phrases longues en kebab |
signals_match: | Mots de signal pour le rappel ciblé | N'est rappelé que s'il y a une intersection avec les mots de la requête ; n'empilez pas de mots sans rapport |
Chemin alternatif : écriture manuelle (lorsque les signaux sont déjà clairs)
node code/light-cli.mjs distill --category repair --signals bash,exception \
--strategy "<Correctif en une phrase ; séparez les étapes par des points-virgules ; soyez spécifique aux paramètres/commandes/encodages>" \
--summary "<Description du piège en une phrase>" [--shareable]
- La stratégie doit être rédigée comme un correctif exécutable (contenant paramètres/commandes spécifiques), n'écrivez pas de résumé de succès — le garde de correctif côté rappel les filtrera (mieux vaut rien que du bruit) ;
--shareableuniquement si vous voulez que ce gène entre dans le pool partagé (par défaut non partagé = pas d'envoi externe) ;- Données réelles sur le seuil de dépôt (limite honnête) : dans les sessions de production réelles, la densité de « paires de correctifs propres » extractibles automatiquement est très faible (mesurée
distillablePairs=0) — les gènes de cette base proviennent principalement d'un dépôt manuel/guidé.
Contrôle qualité du dépôt depositionGate (0.17.0, fail-closed)
EN : Quality gate at DEPOSITION time (fail-closed) : rejects unfilled placeholder / retry-log repetition / narration openings / missing repair-signal words / AVOID-without-FIX. Non-interactive deposits default to quarantined. Full review semantics: the「Machine à états de révision」section below. Lors de
distill/draft --commit, chaque entrée est vérifiée ; si invalide, rejet direct (pas d'enregistrement) :
| Condition de rejet | Raison | Prochaine étape |
|---|---|---|
FIX est un placeholder non rempli <À remplir avec un correctif exécutable> | Aucune valeur après injection | Remplissez le correctif réel dans le brouillon avant de soumettre |
retry with corrected args (répétition du journal de tentative) | « J'ai réessayé et ça a marché » n'est pas un correctif | Écrivez AVOID (pourquoi c'était faux) + FIX (comment faire) |
| Ouverture narrative (Now I understand…) | Flux de raisonnement non exécutable | Idem |
| Absence de mot de signal de correctif | Ne ressemble pas à une description de piège et de correctif | Idem |
| AVOID sans FIX (demi-produit) | Seulement le piège, pas de correctif ; aucune valeur après injection (vérification 0.22 : 3 dépôts rejetés étaient tous dans cette forme) | Ajoutez un correctif exécutable (paramètres/commandes/encodages) |
Machine à états de révision (source unique de vérité · convergence 0.36)
Toute la sémantique de révision, de l'entrée en base jusqu'à l'injectabilité, n'est maintenue que dans cette section ; les autres documents pointent uniquement ici (pour éviter les dérives de formulation — signalé par l'évaluation 0.35). EN : The single source of truth for all review semantics; other docs only point here.
| Scénario | Comportement par défaut | Moyen de dérogation |
|---|---|---|
Dépôt interactif local (draft --commit / distill, avec TTY) | Approbation automatique | config --auto-approve off pour passage manuel ; s'applique uniquement au dépôt local |
| Dépôt non interactif local (script/cron/pipe, sans TTY) | Isolement par défaut (quarantined) | Passage seulement avec --auto-approve explicite |
approve <gene_id> | Recherche de preuves automatique d'abord — les quatre registres locaux (erreur d'outil/rappel/injection/backfill) sont vérifiés (preuve forte/contexte faible/aucune preuve), approbation seulement si cohérent | --skip-evidence est une porte de secours explicite pour les scénarios sans preuve connue (déconseillé) ; les gènes dont les conclusions sont contredites par des événements ultérieurs restent isolés avec une trace |
Import de pool gene import / gene pull | Niveau official passe directement (vérification de signature) ; pool communautaire par défaut isolé | --tier décide |
- Pourquoi
approveest lié à la recherche de preuves : la commandeevidencea été créée en 0.20.3 mais dépendait de « se souvenir de l'exécuter » — le jour même, 6 entrées à réviser n'ont pas été vérifiées. Le mécanisme doit être lié au nœud d'action (philosophie T3 : l'erreur elle-même est un rappel). - Le registre d'état
review.jsonlest de type LWW append-only, approuver/quarantaine sont réversibles bidirectionnellement ; « en attente de révision » dansinfo= dernier état niapprovedniquarantined. - Relation avec les deux couches de contrôle qualité : depositionGate rejette avant entrée en base (section ci-dessus), les quatre gardes filtrent côté rappel (section suivante) — tout rejet à n'importe quelle couche empêche l'injection.
- Les gènes sans preuve locale (pool partagé/autres machines/sources starter) sont révisés sur la base du contenu et de la source, approuvés avec mention.
EN : Review-with-evidence (0.20.3) : before
approve, runevidence <gene_id>to check the four local ledgers for events matching the gene's claimed failure/fix. Approve only when consistent; genes whose conclusions were overturned by later events stay quarantined with an audit note. Genes without local evidence (pool imports / other machines / starter pack) are reviewed on content and source, noted at approval.
Signature génétique et provenance (0.21)
EN : Every deposit is signed with this machine's Ed25519 identity (private key 0600, never leaves the machine); pool imports verify signatures - tampered content is REJECTED. Version-by-version details (v2 canonicalization, source attribution, source_kv, decay) :
docs/advanced.md§Provenance.
- Le dépôt signe automatiquement, l'entrée en pool l'accompagne, l'import vérifie la signature : contenu falsifié → import rejeté ; les anciens gènes sans signature sont acceptés tels quels (legacy) ;
- La clé privée ne quitte pas la machine ; la clé publique accompagne les gènes en dehors du pool pour vérification par d'autres machines — le modèle de confiance est « traçabilité par keyid », non une CA centralisée ;
- Les champs de provenance sont enregistrés automatiquement lors du dépôt/backfill (
source_model/source_host/source_kvfamille de schémas de compression) ; l'efficacité du gène est dégradée en fonction des retours (demi-vie temporelle de 90 jours + pression négative, plancher 0.25, pas de dégradation sans retour) — détails version par version (normalisation v2 / attribution précise / traces de phase / paramètres de dégradation) dansdocs/advanced.md§Provenance.
Déploiement et distribution (0.23)
EN : Download paths, host integration, pool collaboration, concurrency semantics and scoring; version-by-version detail in
docs/advanced.md§Deployment.
- Téléchargement : Zip de GitHub Release / npm (miroir national chinois voir FAQ Q7, avec vérification sha256) ;
- Intégration hôte :
light-cli.mjs install <claude-code|cursor|codex|agents-md>(--yesenregistré) ; OpenClaw/Hermes utiliseinstall-hooks; les procédures de déclenchement peuvent être écrites dans n'importe quel fichier de commandes viainstall-snippet; - Collaboration pool de gènes :
gene pull --pool <URL|nom> --tier official [--scene <scénario>](vérification de signature) ;gene submit --bundle <fichier>renvoie au mainteneur ; les pools nommés sont dans~/.evomap/pools.json; les conditions de contribution sont dans CONTRIBUTING.md (CC-BY-4.0) ; - Sémantique de concurrence (trois couches, tableau complet des comportements dans
docs/boundary-and-triggers.md§5) : mono-machine multi-sessions = verrou de fichier withLock ; multi-machines = pool de gènes en Git (arbitrage via registre LWW) ; multi-hôtes adressés par gene_id (depuis 0.18) ; - Score de rappel et seuil (valeurs publiques) : signal correspondant +3/chacun + intersection de jetons de texte +1/chacun + biais de répartition de charge ±2 ; en dessous du seuil 2, pas d'injection (injecter sans ciblage est pire que ne pas injecter, mesuré +36pp) ; tokenisation = jetons ASCII (≥3 caractères) + bigrammes chinois de 2 caractères — les phrases multi-caractères chinoises écrites dans signals sont inefficaces (
fix-signalspeut être testé) ; - Barrière de session (0.27) :
session open "<tâche>"effectue en une étape le rappel T1 + la comptabilité,session close "<conclusion>"termine — les open/close non appariés sont refusés par la barrière de construction (liaison d'audit) ; - Quantification des effets et backfill :
reportrapport hebdomadaire (L1 activité/L2 taux de backfill/L3 récidive,--jsonlisible machine) ;recall --record "<conclusion>"backfill de la conclusion de vérification ;license verify <token>vérifie la signature de licence Ed25519 ; - Résilience IO et codes d'erreur (0.34) : les erreurs transitoires sont automatiquement retentées (3 fois/3s) → après 5 échecs consécutifs, fusible coupé pendant 10s (se referme à la récupération IO) ; tous les échecs sont accompagnés de codes d'erreur nommés
[E_USAGE]/[E_ARGS]/[E_GUARD]/[E_NOTFOUND]/[E_INTERNAL](conservant les codes de sortie 0/1/2) — paramètres et tableau complet dansdocs/advanced.md; - Référence théorique : la conscience du problème de vérification hétérogène vient de arXiv:2512.05117 (voir la section remerciements du README et
docs/research.md) ; détails version par version (traçabilité/mots de déclenchement alias/licence/paramètres de dégradation) dansdocs/advanced.md§Deployment.
Sécurité : quatre portes (0.16.0)
EN : Four gates: repair-signal guard, narration guard, injection guard (malice; AVOID=warning allowed vs FIX=instruction blocked), redaction gate (privacy, fail-closed off-machine). Per-gate details:
docs/security-and-license.md§Gates.
| # | Porte | Quoi contrôler | Où s'applique |
|---|---|---|---|
| 1 | Garde de correctif | Y a-t-il un vrai correctif ? (pas de contenu exécutable → pas d'injection ; mieux vaut rien que du bruit) | Rappel |
| 2 | Garde narratif | Est-ce un flux narratif ? (la narration est zéro information pour un agent, mesuré équivalent à un bruit +36pp) | Rappel |
| 3 | Garde d'injection | Est-ce une instruction malveillante ? (injection de prompt → pas d'injection ; ligne de défense principale contre la « manipulation inverse de l'hôte par le gène ») | Rappel (CLI / version simplifiée du pont d'extension Pi / orchestrateur) + Import + Export |
| 4 | Porte de désensibilisation | Y a-t-il fuite de contenu privé ? (IP/chemin/clé → interception, pas de sortie réseau) | Export + Import |
- Sémantique de dégradation : Export/Import fail-closed (module de garde manquant = refus d'exécuter) ; côté rappel, seule la porte d'injection est sautée, les trois autres fonctionnent normalement (le chemin de bootstrap de l'hôte ne doit pas être bloqué par l'échec du garde pour l'utilisateur — lecture seule non bloquante, écriture doit être closed).
- Ce que chaque porte vérifie exactement, le comportement en cas de correspondance, les deux cas de non-détection corrigés en 0.31 et les cas de test de régression : voir uniformément
docs/security-and-license.md§Gates — ce document ne répète pas les caractéristiques de déclenchement d'injection pour éviter que le document lui-même ne soit pris comme échantillon par les scanners (ce dépôt a déjà une précédente version à ce sujet).
Limites de capacité (quand ne pas compter dessus)
Les 6 catégories de scénarios non applicables (plusieurs machines écrivant sur la même base / garantie à 100% d'éviter les pièges / synchronisation en temps réel de la base / tâche unique / comme base de connaissances faisant autorité / réutilisation directe entre architectures) et les limites quantitatives (injection par défaut 5 entrées, taille de la base non mesurée, pas de verrou distribué entre machines, Node ≥22) voir uniformément
docs/boundary-and-triggers.md§1–§2. EN : Capability limits ("when NOT to use") and quantitative bounds:docs/boundary-and-triggers.md§1–§2.
Quand rappeler : cinq points de déclenchement (conception centrale 0.16.0)
EN : Recall bound to concrete action nodes, never left to memory: T1 task start, T2 before first side-effecting action, T3 on error (the error text IS the query), T4 after fixing, T5 task end (register-hit/negate). Full spec:
docs/boundary-and-triggers.md. « J'ai installé la compétence mais personne ne l'appelle » est le mode de défaillance le plus fondamental de ce projet — même l'auteur l'oublie (mesuré : les gènes pertinents pourraient être rappelés en première position, mais parce qu'on n'a pas lancé le rappel avant d'agir, on retombe dans le piège). Donc on ne peut pas compter sur « l'utilisateur se souvient » ; il faut lier le rappel à des nœuds d'action concrets.
| # | Point de déclenchement | Moment | Commande | Que se passe-t-il si oublié |
|---|---|---|---|---|
| T1 | Début de tâche | Lorsqu'une tâche non triviale est reçue, avant la planification | recall --query "<Tâche>" | Échec de la prévention : le piège à éviter est quand même rencontré |
| T2 | Avant une action | Juste avant d'exécuter une première action irréversible (écrire un fichier/commiter du code/déployer/appeler une interface externe/supprimer ou modifier des données) ; pour des actions similaires dans la même tâche, déclenché une seule fois, la conclusion est utilisée pour les suivantes | Idem (query=action spécifique à effectuer, par ex. « réécrire en masse des fichiers avec un script ») | Prévention de proximité (optionnelle) |
| T3 | Rencontre d'une erreur | L'outil retourne une erreur, avant de préparer une nouvelle tentative | recall --error "<Texte d'erreur brut>" | Le plus dommage : le correctif est dans la base, mais on réessaie aveuglément |
| T4 | Après avoir corrigé un piège | Un piège non évident a été réparé | draft --error ... (dépôt) | Perte d'expérience, la prochaine machine retombera dedans |
| T5 | Fin de tâche | Clôture | --register-hit --gene <id> / --negate --gene <id> | Impossible de mesurer, les correctifs inefficaces ne sont pas détectés |
T3 mis en évidence (le plus rentable, mais le plus facilement négligé) : Le seul point de déclenchement « vous n'avez pas besoin de vous souvenir » — l'erreur elle-même est un rappel. Lorsque l'outil retourne une erreur, avant de préparer une nouvelle tentative, utilisez directement le texte d'erreur brut comme requête (ne résumez pas) : node code/evolver-recall.mjs --error "<Texte d'erreur brut>" ; si un correctif est trouvé, réessayez selon celui-ci ; en cas d'échec persistant → allez en T4 pour déposer.
La spécification complète des déclenchements est dans
docs/boundary-and-triggers.md— inclut le périmètre de jugement T2 et 3 exemples, la matrice de concurrence multi-hôtes, la correspondance mots de déclenchement ↔ commandes, trois modes d'intégration hôte, le miroir national chinois, l'auto-test « installé mais ne fonctionne pas ». Ce fichier ne conserve que le tableau principal ci-dessus, les deux endroits ne dérivent plus indépendamment. Les mots de déclenchement ne sont que des indices d'appel, pas un mécanisme de correspondance de rappel (l'appariement repose sur le ciblagesignals_match × query-token) ; au début d'une tâche, dès que jugé « non trivial », allez en T1, sans avoir besoin de correspondre à un ensemble de mots.
Utilisations incorrectes courantes (anti-patrons rapides)
EN : Anti-pattern quick list - each row explains the MECHANISM, not just the symptom. Full 14-item catalog with [A] evidence:
docs/common-mistakes.md. Key ones: success-summary strategies are noise (+36pp worse than nothing), model-may-fail traps have unreliable hit rates, token deltas need a no-injection control group (~-22% repeat-execution baseline), error counting must use authoritative flags (isError=true), cold start needs flow-B deposits first. Chaque ligne explique « pourquoi c'est faux » — parle du mécanisme, pas du symptôme. Liste complète (avec plus d'entrées) dansdocs/common-mistakes.md.
| Mauvaise pratique | Pourquoi c'est faux (mécanisme) | Correct |
|---|---|---|
| Rédiger une stratégie comme un résumé de succès | Le garde de correctif filtre les résumés de succès ; s'ils passent, ils deviennent du bruit dans l'injection (+36pp pire que l'absence d'injection). L'évaluation 0.23 a retiré plus de 100 de ces entrées de rappel | Écrire une stratégie comme un correctif exécutable (paramètres de commande, encodages, etc.) |
| Rassembler des données de piège à partir de modèles « peut-être en échec » (sans échec réel dans le journal) | Fiabilité faible, le taux de correspondance est bas [A] ; l'évaluation 0.30 a montré que les pièges sans échec réel ont un bruit d'échantillonnage élevé | Les pièges doivent être basés sur des échecs réels (isError=true), avec le message d'erreur comme mot de déclenchement |
| Utiliser le delta de jetons (modèle avant/après) comme métrique | Nécessite un groupe de contrôle sans injection pour référence (la ligne de base de répétition d'exécution est d'environ -22%) ; sans cela, l'amélioration mesurée peut être due au hasard ou à d'autres variables | Utiliser le dépôt/approbation comme métrique, ou le delta avec rappel à blanc |
| Compter les échecs uniquement par le message | Certains messages sont des avertissements (non bloquants) ; compter par le message peut gonfler le nombre de vrais échecs | Compter par isError=true dans les registres d'outils (les avertissements ne comptent pas comme échecs) |
| Démarrage à froid en rappelant d'abord puis en déposant | La base est vide, aucun correctif à rappeler ; la première tâche doit être faite en mode « piège non évité », juste pour déposer ; ensuite le rappel fonctionne | Effectuer d'abord un dépôt avec le flux B, puis le rappel A, ce n'est qu'ainsi que le cycle vertueux commence |
Tous les anti-patrons mesurés avec [A] evidence : voir
docs/common-mistakes.mdpour les données de performance (A/B), les résultats d'évaluation et les cas de test de régression (0.30 a ajouté une vérification automatique pour les anti-patrons 1, 4, 5).
Navigation rapide de la documentation
| Fichier | Public visé | Contenu |
|---|---|---|
docs/one-pager.md | Décider en une minute si cette compétence correspond à votre besoin | Avantages, flux, coûts, contre-indications (nouveau en 0.30) |
examples/quickstart.md | Débutants, boucle fermée en 5 minutes | Premier dépôt + premier rappel, démonstration de bout en bout |
docs/overview.md | Compréhension de la conception et de l'architecture | Problème → solution, structure de la base de gènes, pipeline de flux, mécanisme de déclenchement |
docs/advanced.md | Utilisateurs avancés / intégrateurs / opérateurs | Backfill, chronologie, harvest, verrous concurrentiels, bibliothèque partagée, intégration hôte, opérations, sécurité, paramètres de dégradation |
docs/common-mistakes.md | Tous (surtout après avoir rencontré un problème) | 14 utilisations incorrectes avec données de performance A/B (nouveau en 0.23) |
docs/config-errors.md | Lorsque les commandes échouent | Erreurs courantes de configuration, dépannage (nouveau en 0.25) |
docs/security-and-license.md | Achats, sécurité, conformité | Détails des quatre portes de sécurité, licence, modèle de confiance, politique de signature |
docs/boundary-and-triggers.md | Intégrateurs / décideurs / débogage | Limites de capacité, spécification complète des déclenchements (5 points), matrice de concurrence multi-hôtes |
docs/research.md | Chercheurs, Flow C uniquement | Conception d'expériences contrôlées, discipline de piège (nouveau en 0.30) |
docs/faq.md | Tous | 14 questions fréquentes, glossaire anglais-français (nouveau en 0.29) |
docs/providers.md | Utilisateurs du flux C (recherche) | Exemples de configuration de fournisseur LLM + endpoints domestiques (nouveau en 0.30) |
Mots de déclenchement de cette compétence
Utilisés uniquement pour l'invite des agents lorsqu'ils rencontrent ces mots dans des conversations, pour les inciter à appeler les commandes correspondantes ; ce ne sont pas un mécanisme de rappel (le rappel repose sur
signals_match × query-token).EN : Trigger words for agent prompt matching only — NOT a recall mechanism. Recall uses signals_match × query-token overlap. These words live in agent CLI configs or system prompts; they are hints, not filters.
Regroupés par ordre d'importance décroissante (les plus importants en premier) ; chaque groupe en ordre alphabétique :
| Groupe | Mots de déclenchement | Contexte |
|---|---|---|
| 1. Rappel (T1/T3, les plus importants) | 经验继承, 经验召回, evolver | Début de tâche ou erreur : doit lancer recall |
| 2. Dépôt (T4) | 避坑, 沉淀, 经验入库, 错题本, gène, distill | Après correction d'un piège non évident : doit lancer draft/distill |
| 3. Évolution (C, recherche) | 自进化, self-evolve, 进化实验, 演化实验 | Expérience contrôlée, quantification des gains (Flow C) |
Ces mots de déclenchement sont dans les fichiers de configuration et les invites système des agents ; ils ne sont pas suffisants pour garantir un rappel correct — le rappel réel repose sur
signals_match × query-token. Si l'agent perçoit que le sujet de la conversation actuelle correspond à l'un de ces groupes de mots et que la tâche est non triviale, il doit appeler la commande correspondante. Les mots de déclenchement sont juste des indices, pas des filtres.
Document maintenu par la section de documentation de ce dépôt, dernière mise à jour 2025-03-20.
Les règles de révision (machine à états de révision) sont la source unique de vérité de ce fichier.
Voir docs/security-and-license.md §Gates pour les détails des quatre portes de sécurité.