--- title: L’outil en ligne de commande ia_request aliases: [] names: [] __au: FrViPofm __cr: CC-by-SA-NC 3.0 __dc: 20260902T114527 __dm: 20260909T095148 __id: EpA_/S/Site_web,_outil_ia_request __vs: 7 --- > [!introduction]- > Un outil majeur de dialogue homme-machine. > > `ia_request` prépare les informations nécessaires au démarrage d’une session de travail avec l’IA et permet, en cours de session, de rassembler des informations complémentaires. > > Cette note décrit les conventions permettant à une IA de proposer des presets ou des requêtes ponctuelles utilisables par `ia_request`. > [!note]- > **Convention générale** > > `config.yaml` est la racine du jeu de presets. > > Un preset descendant de `config.yaml` appartient au jeu et peut hériter des paramètres structurels du projet. > > Un fichier YAML qui n’est pas descendant de `config.yaml` est **hors jeu**. Il peut être signalé par `ia_request`, mais il ne participe pas à une requête valide et ne connaît pas les paramètres structurels du projet. # L’outil Les prompts très longs peuvent être refusés par l’interface de l’IA sans que la limite de longueur soit nécessairement connue. Les requêtes importantes peuvent donc être formulées en plusieurs parties. `ia_request` fournit des indications sur la taille des fichiers afin de faciliter cette répartition. Le globbing n’est pas prévu. Les presets sont stockés dans : ```text ~/.config/ia_request/ ``` La commande : ```text iar ``` est un alias shell de : ```text ~local/bin/ia_request ``` Un preset peut être appelé par exemple avec : ```bash iar -c preamble ``` Une requête ponctuelle peut être fournie directement : ```bash iar -r "{extend: 'collect', include: ['themes/epa/templates/evenement.html.twig']}" ``` # Deux modes `ia_request` distingue deux modes de fonctionnement. ## Mode préambule Le mode préambule constitue le contexte général d’une session. Il peut contenir : - des notes générales du projet ; - des notes spécialisées correspondant à l’objet de la session ; - une arborescence partiellement explorée ; - des fichiers sources intégrés intégralement. Le document produit commence notamment par : ```markdown # Préambule **Date de génération :** 2026-09-05 21:43:15 +0200 *–Début du préambule–* ``` et se termine par : ```markdown *–Fin du préambule–* # Demande ``` La section `# Demande` reste disponible pour compléter ou modifier manuellement la requête destinée à l’IA. ## Mode collecte Le mode collecte est destiné notamment aux besoins apparus en cours de session. Il permet de demander une série de fichiers sources ou une partie de l’arborescence sans reconstruire un préambule général. Le mode collecte est indiqué par : ```yaml preamble: null ``` Cette valeur est significative et ne doit pas être transformée en liste vide. La distinction est donc : ```yaml preamble: null ``` → **mode collecte** et : ```yaml preamble: [] ``` → **mode préambule sans note de préambule**. Une liste `preamble` non vide correspond également au mode préambule. # Deux méthodes ## L’appel d’un preset Un preset préconfiguré peut être passé à `ia_request` avec : ```bash iar -c nom_du_preset ``` Le nom peut être donné avec ou sans extension `.yaml`. ## La requête en ligne `ia_request` accepte également une configuration YAML directement avec `-r`. Exemple : ```bash iar -r "{extend: 'collect', explore: ['themes/epa/templates'], include: ['themes/epa/templates/evenement.html.twig', 'pages/04.evenements/20260621-fdm/retour/report.md']}" ``` La requête représente une configuration temporaire. Elle n’a pas besoin d’être enregistrée dans un fichier. Elle peut utiliser `extend` pour partir d’un preset existant et ne fournir que les paramètres spécifiques à la demande. # Structure d’un preset Un preset peut contenir notamment : ```yaml extend: root_dir: note_dir: preamble: create: explore: mention: avoid: include: ``` Tous les paramètres ne sont pas obligatoires. ## `config.yaml` `config.yaml` est la racine du jeu de presets. Il contient les paramètres structurels du projet, notamment : ```yaml root_dir: /var/www/grav/user note_dir: ~/Documents/Wikiss/EpA_/S ``` Il peut également contenir d’autres paramètres si nécessaire. **`config.yaml` est parsé comme n’importe quel autre YAML.** Sa particularité est uniquement d’être la racine à laquelle les autres presets doivent être rattachés par `extend`. Un preset sans `extend` n’est donc pas automatiquement un preset valide : hors `config.yaml`, il est hors jeu. ## `root_dir` `root_dir` désigne la racine du projet à explorer. Il est défini par `config.yaml` et constitue un paramètre structurel. Une configuration descendante ne doit pas le réécrire. Toute tentative de modification de `root_dir` par rapport à la configuration parente constitue une incohérence de configuration. Dans ce cas, `ia_request` doit : 1. produire un avertissement en console ; 2. intégrer l’avertissement à la sortie lorsqu’une sortie peut être constituée ; 3. interrompre l’exécution. ## `note_dir` `note_dir` désigne le dossier contenant les notes utilisées comme préambule. Les chemins indiqués dans `preamble` sont relatifs à `note_dir`, sauf s’ils commencent par `~` ou `/`. Comme `root_dir`, `note_dir` est un paramètre structurel défini par `config.yaml`. Une configuration descendante ne doit pas le réécrire. Toute tentative de modification provoque une incohérence et doit interrompre l’exécution. `note_dir` est requis lorsque des notes sont demandées, c’est-à-dire lorsque `preamble` n’est ni `null` ni `[]`. Si `note_dir` est requis et n’est pas correctement initialisé, l’outil doit également interrompre l’exécution. ## `preamble` `preamble` est à la fois une liste de notes et un indicateur de mode. Dans une configuration de préambule : ```yaml preamble: - Site_web.md - Site_web,_architecture.md ``` les fichiers sont ajoutés au préambule dans l’ordre indiqué. Dans une configuration de collecte : ```yaml preamble: null ``` le mode collecte est activé. ### Tolérance dans la désignation des notes La désignation des notes peut être tolérante lorsque la correspondance avec un fichier existant est non ambiguë. Ainsi, pour : ```text Site_web,_section_Evenements.md ``` les formes suivantes peuvent être acceptées : ```text Site_web,_section_Evenements.md Site_web,_section_Evenements section_Evenements section_Evenements.md ``` La tolérance peut également porter sur l’accentuation de `Evenements` / `événements` lorsque cela permet d’identifier sans ambiguïté la note existante. Cette tolérance vise notamment les requêtes produites rapidement au clavier ou proposées par une IA. Le document produit présente alors le nom réel de la note lorsqu’une correction non ambiguë a été effectuée. ### Verrou de mode `preamble: null` est un verrou de mode. Si un ancêtre de la chaîne `extend` contient : ```yaml preamble: null ``` un descendant ne peut pas transformer ce `null` en liste. Exemple incohérent : ```yaml # collect.yaml preamble: null ``` puis : ```yaml # actual_evenements.yaml extend: collect preamble: - Site_web,_section_Evenements.md ``` La configuration descendante ne change pas le mode. L’outil doit signaler l’incohérence et interrompre l’exécution. Cette règle empêche une chaîne d’héritage de mélanger accidentellement les familles *préambule* et *collecte*. Une liste `preamble` peut en revanche être enrichie par héritage tant qu’aucun ancêtre n’a fixé le mode collecte. ## `explore` `explore` contient les dossiers qui doivent être parcourus récursivement dans l’arborescence du projet. Exemple : ```yaml explore: - pages/04.evenements - themes/epa/templates ``` Les branches correspondant aux dossiers explorés sont développées. ## `mention` `mention` contient les chemins qui doivent apparaître dans l’arborescence sans être parcourus. Un dossier mentionné est affiché mais son contenu n’est pas détaillé. ## `include` `include` contient les fichiers dont le contenu doit être intégré à la sortie. Exemple : ```yaml include: - themes/epa/templates/evenement.html.twig - plugins/shortcode-core/classes/Shortcode.php ``` Le fichier apparaît dans l’arborescence puis son contenu est reproduit dans une section : ```markdown ### Fichier *chemin/du/fichier* *–Début du fichier–* ... *–Fin du fichier–* ``` Les dossiers parents nécessaires pour atteindre un fichier `include` sont automatiquement parcourus dans l’arborescence. ## `avoid` `avoid` contient les chemins qui doivent être complètement masqués. `avoid` est prioritaire sur les autres règles. Si un chemin est présent dans `avoid`, il ne doit être ni exploré, ni mentionné, ni inclus. Une valeur absente ou vide signifie qu’aucun chemin n’est masqué. # Héritage des presets Un preset peut étendre un autre preset avec : ```yaml extend: preamble ``` ou : ```yaml extend: collect ``` Le preset indiqué par `extend` est recherché dans : ```text ~/.config/ia_request/ ``` L’héritage peut être récursif. Exemple : ```text preamble_module_evenements.yaml │ └── extend: preamble_section_evenements │ └── extend: preamble │ └── extend: config ``` L’ordre réel dépend des `extend` présents dans les fichiers. L’arbre affiché par `iar -t` constitue la représentation des dépendances effectivement déclarées. ## Jeu de presets Un preset appartient au jeu s’il est descendant de `config.yaml`. Ainsi : ```text config ├── collect │ ├── collect_parts_shortcode │ └── collect_section_accueil └── preamble ├── preamble_section_accueil │ └── preamble_module_accueil ├── preamble_section_evenements │ └── preamble_module_evenements ├── preamble_section_journaux └── preamble_shortcode_evenements ``` Un fichier YAML sans `extend`, autre que `config.yaml`, ne peut pas être placé dans ce jeu par convention implicite. Il est signalé comme **preset hors jeu**. Un `extend` vers un parent inexistant constitue également une erreur. ## Règles de fusion Les paramètres structurels et les paramètres en liste ne sont pas fusionnés de la même manière. ### Paramètres structurels Les paramètres suivants sont fixes : ```text root_dir note_dir ``` Ils sont définis par `config.yaml` et transmis par héritage. Ils ne peuvent pas être réécrits par une configuration descendante. Toute divergence provoque une erreur et l’arrêt du programme. ### Paramètres en liste Les paramètres suivants sont augmentés par héritage : ```text preamble explore mention avoid include ``` Une liste définie par un descendant est ajoutée à celle de ses ancêtres. Les doublons sont supprimés en conservant l’ordre de première apparition. Exemple : ```yaml # parent include: - a.php - b.php ``` puis : ```yaml # enfant include: - b.php - c.php ``` produit : ```yaml include: - a.php - b.php - c.php ``` `preamble` obéit en outre à la règle particulière de verrouillage de mode décrite plus haut. # Sécurité de la chaîne `extend` La résolution de `extend` doit détecter les boucles. Par exemple : ```text A → B → C → A ``` constitue une boucle d’héritage. L’outil doit produire un avertissement du type : ```text AVERTISSEMENT : boucle d’extend trouvée sur extend: A ``` puis interrompre l’exécution. Une profondeur d’héritage supérieure à 5 niveaux est également considérée comme anormale. Dans ce cas : ```text AVERTISSEMENT : profondeur d’extend trop grande ``` puis interruption. La profondeur maximale admise est donc de 5 niveaux. # Arbre des presets La commande : ```bash iar -t ``` affiche l’arbre des dépendances entre presets. Elle ne représente pas l’arborescence du site. Exemple : ```text config/ (config, s: 107 o, m: 2026-09-06 13:51:43 +02:00) ├── collect, s: 158 o, m: 2026-09-06 12:47:29 +02:00 │ ├── collect_parts_shortcode, s: 98 o, m: 2026-09-02 22:52:38 +02:00 │ └── collect_section_accueil, s: 469 o, m: 2026-09-05 08:59:24 +02:00 └── preamble, s: 272 o, m: 2026-09-06 12:47:52 +02:00 ├── preamble_section_accueil, s: 574 o, m: 2026-09-05 09:19:54 +02:00 │ └── preamble_module_accueil, s: 366 o, m: 2026-09-06 13:52:44 +02:00 ├── preamble_section_evenements, s: 227 o, m: 2026-09-03 12:06:15 +02:00 │ └── preamble_module_evenements, s: 385 o, m: 2026-09-06 12:54:10 +02:00 ├── preamble_section_journaux, s: 407 o, m: 2026-09-02 16:10:09 +02:00 └── preamble_shortcode_evenements, s: 474 o, m: 2026-09-02 21:48:46 +02:00 ``` Chaque fichier est accompagné de sa taille et de sa date de modification. Les presets hors jeu ou présentant une erreur de dépendance sont signalés séparément. Cet arbre peut également être intégré dans les préambules produits. Il permet ainsi à l’IA de connaître les presets disponibles et leurs relations d’héritage. Lorsqu’une collecte complémentaire est nécessaire pendant une session, l’IA doit privilégier un preset de la branche `collect`. # Presets de base ## `preamble.yaml` `preamble.yaml` est un preset descendant de `config` destiné à constituer un préambule général. Exemple : ```yaml extend: config preamble: - Site_web.md - Site_web,_architecture.md - Site_web,_outil_ia_request.md - Site_web,_decisions.md - Site_web,_checklist.md explore: mention: avoid: include: ``` Une configuration spécialisée peut alors commencer par : ```yaml extend: preamble ``` et ne définir que les éléments spécifiques à la session. ## `collect.yaml` `collect.yaml` est un preset descendant de `config` destiné aux collectes. Exemple : ```yaml extend: config preamble: null explore: mention: avoid: include: ``` Une configuration spécialisée de collecte commence par : ```yaml extend: collect ``` Exemple : ```yaml extend: collect explore: - templates/partials include: - themes/epa/templates/evenements.html.twig ``` # Requête ponctuelle avec `-r` Une requête temporaire peut partir directement d’un preset existant. Exemple : ```bash iar -r "{extend: 'collect', explore: ['themes/epa/templates'], include: ['themes/epa/templates/evenement.html.twig']}" ``` Cette possibilité permet à l’IA de proposer directement une commande de collecte sans demander à l’utilisateur de créer préalablement un fichier YAML. Une requête temporaire doit elle-même appartenir au jeu des presets lorsqu’elle utilise `extend`. En pratique, une requête de collecte proposée par l’IA doit partir d’un preset de la branche `collect`. Une requête ne doit jamais tenter de transformer indirectement un `preamble: null` hérité en liste de fichiers. Une telle situation constitue une incohérence et doit être signalée à l’utilisateur plutôt que contournée automatiquement. ## `create` Une requête ponctuelle peut contenir, en plus des instructions d'un *preset* l'insrttuction `creat` `create` contient la liste des fichiers à créer. L'instruction `create` place `ia_request` en mode *collecte*. Elle est exécutée avant les instructions `explore` et `include` afin de retourner un état réel. # Sélection graphique Lorsqu’aucune configuration n’est fournie en ligne de commande, `ia_request` peut proposer une sélection graphique des presets disponibles. L’interface prévue est de type YAD. L’utilisateur peut lancer simplement : ```bash iar ``` puis sélectionner un preset parmi ceux disponibles dans : ```text ~/.config/ia_request/ ``` Les presets qui ne sont pas destinés à être exécutés directement peuvent éventuellement être masqués de la sélection. La sélection graphique constitue une facilité d’utilisation ; elle ne remplace pas l’utilisation en ligne de commande. # Priorité des modes de lancement Le fonctionnement prévu est : ```text iar -r "..." │ └── requête YAML ponctuelle iar -c │ └── preset nommé iar │ └── sélection YAD ``` # Sortie Le document généré est temporaire. Il est écrit dans : `/tmp/ia_session_YYYY-MM-DD_HH-MM-SS.md` puis ouvert dans `gedit`. En mode préambule, la sortie contient notamment : ```text Préambule │ ├── Notes de préambule ├── Autres notes du dossier ├── Arborescence des presets ├── Arborescence du projet ├── Fichiers inclus ├── Avertissements éventuels └── Demande ``` En mode collecte, la sortie doit être identifiée comme une collecte et ne doit pas être présentée artificiellement comme un préambule général. # Utilisation pendant une session IA L’intérêt particulier de `ia_request` est de pouvoir être utilisé à deux moments différents. ## Au début d’une session Un preset de type préambule permet de constituer le contexte général : - architecture du site ; - décisions de conception ; - conventions ; - notes générales ; - notes spécialisées ; - fichiers sources nécessaires. ## En cours de session Un preset de type collecte, ou une requête `-r`, permet de compléter ponctuellement les informations disponibles. Il n’est donc pas nécessaire de reconstruire le préambule initial lorsqu’une nouvelle question nécessite seulement quelques fichiers supplémentaires. ## Convention pour les requêtes proposées par l’IA Lorsqu’une IA souhaite demander une collecte complémentaire, elle doit privilégier le mode collecte. Exemple : ```bash iar -r "{extend: 'collect', explore: ['plugins/shortcode-core'], include: ['plugins/shortcode-core/classes/Shortcode.php', 'plugins/shortcode-core/shortcode-core.php']}" ``` Lorsqu’elle souhaite constituer un nouveau préambule, elle doit partir d’un preset de la branche `preamble`. Lorsqu’elle souhaite connaître les presets disponibles, elle peut demander l’arbre des presets avec : `iar -t` L’arbre peut être intégré au préambule afin de permettre à l’IA de choisir un preset existant plutôt que d’en reconstruire inutilement la logique. Lorsqu’elle souhaite demander une collecte complémentaire, elle doit privilégier `collect` ou un descendant approprié de `collect`. # Requêtes particulières Les possibilités suivantes sont prévues ou en cours d’évolution : * `iar -t`→ affiche l’arbre des presets et leurs métadonnées. * `iar -c preamble` → produit un préambule général basé sur `preamble.yaml`. * `iar -r "{extend: 'collect', ...}"` → produit une collecte temporaire à partir d’un preset de collecte. La syntaxe exacte d’éventuelles requêtes de consultation détaillée des presets reste à faire évoluer avec l’outil. # Évolution de l’outil ## Corrections - [ ] Affiner la tolérance dans la désignation des notes lorsque plusieurs correspondances sont possibles. - [ ] Harmoniser définitivement les messages d’erreur et d’avertissement. ## Développements [^projet]: actuellement le site web d’Ensemble pour Aixe. Voir [introduction](Site_web).