https://cheroliv.com/ JBake Bootstrap Template en-gb Fri, 25 Sep 2026 01:35:25 +0000 Fri, 25 Sep 2026 01:35:25 +0000 https://cheroliv.com/blog/2026/0126_hyperframes_asciidoc_video_post.html Sun, 31 May 2026 00:00:00 +0000 blog/2026/0126_hyperframes_asciidoc_video_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_trou_dans_le_pipeline_vidéo">Le Trou dans le Pipeline Vidéo</a></li> <li><a href="#_hyperframes_le_moteur">HyperFrames : Le Moteur</a></li> <li><a href="#_larchitecture_du_plugin">L’Architecture du Plugin</a> <ul class="sectlevel2"> <li><a href="#_le_pipeline_en_quatre_étapes">Le Pipeline en Quatre Étapes</a></li> <li><a href="#_le_dsl_asciidoc">Le DSL AsciiDoc</a></li> <li><a href="#_le_bridge_node_js">Le Bridge Node.js</a></li> </ul> </li> <li><a href="#_deux_plugins_vidéo_deux_usages">Deux Plugins Vidéo, Deux Usages</a></li> <li><a href="#_les_6_epics_de_la_roadmap">Les 6 EPICs de la Roadmap</a></li> <li><a href="#_pourquoi_ça_marche">Pourquoi Ça Marche</a></li> <li><a href="#_conclusion_le_chaînon_manquant">Conclusion : Le Chaînon Manquant</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 8 minutes</div> <p>Il y a deux semaines, j’ai lancé <code>capsule-gradle</code> — un plugin qui transforme un deck reveal.js en capsule vidéo WebM avec TTS. Aujourd’hui, j’ajoute un nouveau plugin : <code>hyperframes-gradle</code>. Il fait quelque chose que capsule-gradle ne fait pas : transformer l’AsciiDoc <strong>directement</strong> en vidéo MP4, sans passer par reveal.js.</p> </div> <div class="paragraph"> <p>Voici pourquoi ce plugin existe, comment il s’articule avec l’existant, et ce que le moteur HyperFrames de HeyGen apporte au pipeline de production de contenu.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_trou_dans_le_pipeline_vidéo">Le Trou dans le Pipeline Vidéo</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mon pipeline documentaire produit deux types de vidéos :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Capsule de révision</strong> (capsule-gradle) — un deck reveal.js capturé en WebM avec</p> </li> </ol> </div> <div class="paragraph"> <p>narration TTS. Parfait pour revoir un module.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Slides d’animation</strong> (slider-gradle) — un deck reveal.js HTML interactif pour</p> </li> </ol> </div> <div class="paragraph"> <p>le formateur en présentiel.</p> </div> <div class="paragraph"> <p>Mais il manque un troisième format : la <strong>vidéo standalone</strong>.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5555%;"> <col style="width: 5.5565%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Use case</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Solution actuelle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Manque</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slides formateur</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">slider-gradle → reveal.js</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Capsule révision</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">capsule-gradle → WebM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Vidéo teasing</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Aucune</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Démo technique animée</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Aucune</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Doc-to-video</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Aucune</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le premier use case est critique : comment générer automatiquement une vidéo de 60 secondes qui présente un projet ou un module, avec animations GSAP, narration TTS, et fond musical — le tout depuis le même fichier AsciiDoc que les slides ?</p> </div> <div class="paragraph"> <p>Capsule-gradle ne peut pas répondre : il lui faut <strong>déjà</strong> un deck reveal.js. slider-gradle produit bien ce deck, mais il n’est pas conçu pour le rendu vidéo. Il fallait un pipeline <strong>direct</strong> : AsciiDoc → vidéo.</p> </div> </div> </div> <div class="sect1"> <h2 id="_hyperframes_le_moteur">HyperFrames : Le Moteur</h2> <div class="sectionbody"> <div class="paragraph"> <p>J’ai découvert <a href="https://github.com/heygen-com/hyperframes">HyperFrames</a> il y a quelques jours. C’est un framework open-source (Apache 2.0) créé par HeyGen, la licorne de la vidéo IA. 22 700 étoiles sur GitHub. Le pitch tient en une phrase :</p> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p><strong>Write HTML. Render video. Built for agents.</strong></p> </div> </blockquote> </div> <div class="paragraph"> <p>Le principe : vous écrivez du HTML avec des <code>data-*</code> attributes, vous référencez une animation GSAP (ou CSS, Lottie, Three.js…), et le moteur rend le tout en MP4 via Puppeteer (headless Chrome) + FFmpeg. Résultat déterministe : même input, mêmes frames, même vidéo.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><div id="stage" data-composition-id="intro" data-start="0" data-width="1920" data-height="1080"> <video class="clip" data-start="0" data-duration="6" data-track-index="0" src="background.mp4" muted playsinline></video> <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1"> Formation Docker & Kubernetes </h1> <audio data-start="0" data-duration="6" data-track-index="2" data-volume="0.3" src="music.wav"></audio> <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> <script> const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.__timelines = window.__timelines || {}; window.__timelines.intro = tl; </script> </div></code></pre> </div> </div> <div class="paragraph"> <p>Qu’est-ce qui rend HyperFrames différent de Remotion ? Pas de React, pas de bundler, pas de JSX. Du HTML brut que les agents IA savent écrire nativement. C’est taillé <strong>exactement</strong> pour mon pipeline : planner-gradle avec deepseek peut générer ce HTML à partir d’un plan SPG/SPD, et un plugin Gradle peut le convertir en MP4.</p> </div> </div> </div> <div class="sect1"> <h2 id="_larchitecture_du_plugin">L’Architecture du Plugin</h2> <div class="sectionbody"> <div class="paragraph"> <p>hyperframes-gradle suit le même pattern que tous mes plugins : le <a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">pattern « Plugin Indépendant + Racine Consommateur »</a>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">hyperframes-gradle/ ├── settings.gradle.kts ← racine consommateur (dogfood) ├── build.gradle.kts ← 3 lignes : apply plugin hyperframes ├── hyperframes-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── build.gradle.kts ← java-gradle-plugin │ ├── src/main/kotlin/education/cccp/hyperframes/ │ │ ├── HyperframesPlugin.kt │ │ ├── GenerateHyperframesHtmlTask.kt │ │ ├── RenderHyperframesTask.kt │ │ └── HyperframesExtension.kt │ ├── .agents/ ← gouvernance agent │ └── doc/ │ └── HYPERFRAMES_ARCHITECTURE.adoc └── video.yml ← configuration dogfood</code></pre> </div> </div> <div class="sect2"> <h3 id="_le_pipeline_en_quatre_étapes">Le Pipeline en Quatre Étapes</h3> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-hyperframes.svg" alt="pipeline hyperframes" width="1005" height="100"> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>AsciidoctorJ</strong> parse l’AsciiDoc source et extrait les blocs customs</p> </li> </ol> </div> <div class="paragraph"> <p><code>[hyperframes-composition]</code>, <code>[hyperframes-track]</code>, <code>[hyperframes-animation]</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>GenerateHyperframesHtmlTask</strong> génère le HTML HyperFrames avec les</p> </li> </ol> </div> <div class="paragraph"> <p><code>data-*</code> attributes correspondants.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RenderHyperframesTask</strong> appelle la CLI HyperFrames via <code>ProcessBuilder</code> :</p> </li> </ol> </div> <div class="paragraph"> <p><code>npx hyperframes render --input index.html --output video.mp4</code>.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Le MP4 est déployé dans <code>output/</code> avec un <code>metadata.json</code> pour l’orchestration.</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_le_dsl_asciidoc">Le DSL AsciiDoc</h3> <div class="paragraph"> <p>La vraie valeur ajoutée du plugin, c’est le DSL AsciiDoc. L’utilisateur n’écrit jamais de HTML. Il annote son document AsciiDoc existant :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Formation Docker & Kubernetes :hyperframes-width: 1920 :hyperframes-height: 1080 :hyperframes-fps: 30 [hyperframes-composition, id="intro"] == Introduction Le titre apparaît avec un fondu GSAP sur fond vidéo. [hyperframes-track, index=0, start=0, duration=6] video::assets/background.mp4[muted, playsinline] [hyperframes-track, index=1, start=1, duration=4] Formation Docker & Kubernetes [hyperframes-animation, type=gsap]</code></pre> </div> </div> <div class="paragraph"> <p>const tl = gsap.timeline({ paused: true }); tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1); window.<em>timelines = window.</em>timelines || {}; window.__timelines.intro = tl;</p> </div> <div class="paragraph"> <p>Les attributs docinfo (<code>:hyperframes-width:</code>) configurent les dimensions. Les blocs customs définissent les compositions et les tracks. Le bloc <code>[hyperframes-animation]</code> contient le code GSAP brut — que l’agent IA peut générer à partir d’une description en langage naturel.</p> </div> </div> <div class="sect2"> <h3 id="_le_bridge_node_js">Le Bridge Node.js</h3> <div class="paragraph"> <p>Le seul point de friction technique : HyperFrames est en Node.js/TypeScript, et mes plugins sont en Kotlin/JVM. La solution est un <code>ProcessBuilder</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class RenderHyperframesTask : DefaultTask() { @TaskAction fun render() { val process = ProcessBuilder( "npx", "hyperframes", "render", "--input", inputHtml.absolutePath, "--output", outputMp4.absolutePath ) .inheritIO() .start() val exitCode = process.waitFor() require(exitCode == 0) { "HyperFrames render failed with exit code $exitCode" } } }</code></pre> </div> </div> <div class="paragraph"> <p>Zéro couplage code JVM ↔ Node.js. Le contrat est par ligne de commande et fichiers sur disque. C’est le même pattern que <code>plantuml-gradle</code> (qui appelle la CLI PlantUML) ou <code>slider-gradle</code> (qui appelle AsciidoctorJ). Rien de nouveau sous le soleil — juste appliqué à un outil plus récent.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_deux_plugins_vidéo_deux_usages">Deux Plugins Vidéo, Deux Usages</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.7619%;"> <col style="width: 4.762%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">capsule-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">hyperframes-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Deck reveal.js (HTML existant)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">AsciiDoc → HTML HyperFrames</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Use case</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Capsule de révision</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Vidéo standalone explicative</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nature</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Slides → vidéo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Document → vidéo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rendu</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Playwright Java → WebM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HyperFrames CLI → MP4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Animation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transitions reveal.js natives</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GSAP/CSS data-attributes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Stack</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% JVM (Kotlin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JVM + Node.js CLI externe</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Ils ne se remplacent pas. Ils se complètent. La chaîne de valeur complète :</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ slider-gradle ──→ deck reveal.js ──→ capsule-gradle ──→ WebM (capsule révision)</p> </div> <div class="paragraph"> <p>AsciiDoc ──→ hyperframes-gradle ──→ MP4 (vidéo standalone)</p> </div> <div class="paragraph"> <p>L’utilisateur écrit un seul fichier AsciiDoc. slider-gradle produit les slides. capsule-gradle produit la capsule de révision. hyperframes-gradle produit la vidéo de teasing et les démos techniques.</p> </div> </div> </div> <div class="sect1"> <h2 id="_les_6_epics_de_la_roadmap">Les 6 EPICs de la Roadmap</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le plugin est structuré en 6 EPICs :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1682%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">EPIC</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Priorité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bootstrap gouvernance + cadrage architecture</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ TERMINE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Plugin Gradle stub + AsciidoctorJ intégration</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bridge CLI HyperFrames (ProcessBuilder → npx → MP4)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DSL AsciiDoc customs (blocs, docinfo, templates)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Intégration runner-gradle (metadata.json)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Templates prêts à l’emploi (title-card, code-diff, captions)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">HF-6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CI + publication Maven Central / Gradle Portal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">P3</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>La session 000 (bootstrap) est déjà terminée. La session 001 attaquera HF-1 : le stub du plugin Gradle et l’intégration AsciidoctorJ.</p> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_ça_marche">Pourquoi Ça Marche</h2> <div class="sectionbody"> <div class="paragraph"> <p>Trois raisons :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>HyperFrames est "built for agents"</strong>. Mon pipeline repose sur des agents IA</p> </li> </ol> </div> <div class="paragraph"> <p>(planner-gradle + deepseek) qui génèrent du contenu. HyperFrames accepte du HTML brut — le format que les LLMs maîtrisent le mieux. Pas de React, pas de JSX, pas de courbe d’apprentissage pour l’agent.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Le DSL AsciiDoc est naturel</strong>. Tout mon écosystème parle AsciiDoc.</p> </li> </ol> </div> <div class="paragraph"> <p>slider-gradle, codex-gradle, training-gradle — tous consomment du <code>.adoc</code>. Ajouter des blocs customs <code>[hyperframes-composition]</code> est une extension logique, pas une rupture.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Le bridge Node.js est un pattern éprouvé</strong>. ProcessBuilder hors de la JVM,</p> </li> </ol> </div> <div class="paragraph"> <p>c’est ce que je fais déjà pour PlantUML, Graphviz, Piper. Ajouter HyperFrames ne change rien à l’architecture — c’est un outil externe de plus, piloté depuis Gradle.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>La vraie force du pattern, c’est qu’il n’y a <strong>aucune</strong> dépendance npm dans le build Gradle. Le plugin n’importe pas de code Node.js. Il exécute une commande shell. Si HyperFrames évolue ou casse, le plugin n’est pas couplé — il suffit de mettre à jour la commande.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_le_chaînon_manquant">Conclusion : Le Chaînon Manquant</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avec hyperframes-gradle, mon pipeline vidéo est complet. J’ai :</p> </div> <div class="ulist"> <ul> <li> <p>Les <strong>slides interactives</strong> (slider-gradle)</p> </li> <li> <p>Les <strong>capsules de révision</strong> (capsule-gradle)</p> </li> <li> <p>Les <strong>vidéos standalone</strong> (hyperframes-gradle)</p> </li> </ul> </div> <div class="paragraph"> <p>Trois formats. Un seul fichier source : l’AsciiDoc.</p> </div> <div class="paragraph"> <p>Le prochain objectif est HF-1 : faire compiler le plugin et générer un premier HTML HyperFrames à partir d’un document AsciiDoc annoté. La session 001 est déjà cadrée.</p> </div> <div class="paragraph"> <p>hyperframes-gradle existe. La gouvernance est en place. Le backlog est écrit. L’architecture est documentée. Le plugin est né.</p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0124_architecture_plugin_gradle_racine_consommateur_independant_post.html">Article 0124 — L’Architecture Plugin Indépendant + Racine Consommateur</a></p> </li> <li> <p><a href="https://github.com/heygen-com/hyperframes">HyperFrames — GitHub</a></p> </li> <li> <p><a href="https://hyperframes.heygen.com/introduction">HyperFrames — Documentation</a></p> </li> <li> <p><code>foundry/public/hyperframes-gradle/hyperframes-plugin/doc/HYPERFRAMES_ARCHITECTURE.adoc</code> — Architecture détaillée</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0125_audit_conso_opencode_methodologie_comparaison_prix_llm_post.html Mon, 18 May 2026 00:00:00 +0000 blog/2026/0125_audit_conso_opencode_methodologie_comparaison_prix_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_comprendre_la_stack_qui_fait_quoi">Comprendre la Stack : Qui Fait Quoi ?</a></li> <li><a href="#_introduction_pourquoi_un_audit">Introduction : Pourquoi un Audit ?</a></li> <li><a href="#_la_base_de_données_opencode_une_mine_dor">La Base de Données OpenCode : Une Mine d’Or</a> <ul class="sectlevel2"> <li><a href="#_le_schéma">Le Schéma</a></li> <li><a href="#_le_code_dextraction">Le Code d’Extraction</a></li> </ul> </li> <li><a href="#_les_résultats_73_jours_de_consommation">Les Résultats : 73 Jours de Consommation</a> <ul class="sectlevel2"> <li><a href="#_vue_globale">Vue Globale</a></li> <li><a href="#_ventilation_par_modèle_et_fournisseur">Ventilation par Modèle et Fournisseur</a></li> <li><a href="#_les_modèles_intra_session_ce_que_la_table_session_ne_voit_pas">Les Modèles Intra-Session : Ce Que la Table Session Ne Voit Pas</a></li> </ul> </li> <li><a href="#_comparatif_tarifaire_fournisseurs_occidentaux">Comparatif Tarifaire — Fournisseurs Occidentaux</a> <ul class="sectlevel2"> <li><a href="#_anthropic_claude">Anthropic — Claude</a></li> <li><a href="#_openai_gpt">OpenAI — GPT</a></li> <li><a href="#_google_gemini">Google — Gemini</a></li> <li><a href="#_huggingface_inference_providers">HuggingFace Inference Providers</a></li> <li><a href="#_groq">Groq</a></li> </ul> </li> <li><a href="#_comparatif_tarifaire_fournisseurs_chinois">Comparatif Tarifaire — Fournisseurs Chinois</a> <ul class="sectlevel2"> <li><a href="#_deepseek_api_direct_platform_deepseek_com">DeepSeek API Direct (platform.deepseek.com)</a></li> <li><a href="#_kimi_moonshot_platform_kimi_com">Kimi Moonshot (platform.kimi.com)</a></li> <li><a href="#_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</a></li> </ul> </li> <li><a href="#_tableau_récapitulatif_tous_providers">Tableau Récapitulatif — Tous Providers</a></li> <li><a href="#_le_coût_caché_prompt_engineering_et_itérations">Le Coût Caché : Prompt Engineering et Itérations</a></li> <li><a href="#_cumuler_les_abonnements_ollama_cloud_pro_la_méthode_docker">Cumuler les Abonnements Ollama Cloud Pro : La Méthode Docker</a></li> <li><a href="#_ce_que_laudit_ne_mesure_pas">Ce Que l’Audit Ne Mesure Pas</a></li> <li><a href="#_conclusion_le_verdict_des_chiffres">Conclusion : Le Verdict des Chiffres</a></li> <li><a href="#_références">Références</a> <ul class="sectlevel2"> <li><a href="#_sources_des_tarifs">Sources des Tarifs</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 22 minutes</div> <p>On me demande souvent combien coûte ma consommation d’IA. Je réponds « 20 balles par mois » et on me regarde avec des yeux ronds. Alors aujourd’hui, je vous ouvre la boîte noire. Cet article est l’audit complet de mes 73 jours de vibe coding : la méthodologie pour extraire les données depuis la base SQLite d’OpenCode, le code SQL pour interroger les tables, et la comparaison exhaustive avec <strong>tous</strong> les fournisseurs du marché — occidentaux comme chinois. Le résultat est tellement asymétrique que j’ai dû vérifier mes calculs trois fois.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_comprendre_la_stack_qui_fait_quoi">Comprendre la Stack : Qui Fait Quoi ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant de plonger dans les chiffres, clarifions l’architecture. Il y a trois acteurs distincts dans mon setup, et c’est important de ne pas les confondre :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/stack-architecture.svg" alt="stack architecture" width="1474" height="431"> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>OpenCode n’est PAS un fournisseur de modèles.</strong> C’est un CLI open source (<a href="https://github.com/anomalyco/opencode">github.com/anomalyco/opencode</a>) qui orchestre des agents IA. Il ne vend pas d’abonnement, il ne fournit pas d’inférence. C’est l’équivalent de <code>git</code> pour le versionnement : un outil, pas un service. <strong>Ollama Cloud est le fournisseur d’inférence.</strong> Mon installation locale d’Ollama agit comme <strong>client</strong> — elle s’authentifie auprès des serveurs d’Ollama via une clé SSH unique (Device Key) et leur délègue l’exécution des modèles tagués <code>:cloud</code>. L’abonnement Pro (20€/mois) débloque des quotas supérieurs et permet de cumuler plusieurs comptes sur une même machine via Docker.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_introduction_pourquoi_un_audit">Introduction : Pourquoi un Audit ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il y a deux mois, j’utilisais des modèles gratuitement sur mon installation locale d’Ollama. Puis j’ai souscrit un premier abonnement Ollama Cloud Pro à 20€/mois, qui me permet d’utiliser les modèles cloud (ceux avec le tag <code>:cloud</code>) via le provider <code>ollama-cloud</code>. Un deuxième abonnement a suivi un mois plus tard, sur une instance Docker séparée avec son propre compte et sa propre clé SSH — la méthode de cumul décrite dans <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">mon article sur le cumul d’abonnements</a>.</p> </div> <div class="paragraph"> <p>La question qui me taraudait : <strong>est-ce que ces 20€ par mois sont justifiés ?</strong> Pas au doigt mouillé. Avec des chiffres.</p> </div> <div class="paragraph"> <p>Pour répondre, j’avais besoin de données précises. Pas des estimations. Pas des moyennes. Ma consommation <strong>réelle</strong>, token par token, modèle par modèle, session par session.</p> </div> <div class="paragraph"> <p>Et OpenCode — le CLI — stocke tout ça dans une base SQLite.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_base_de_données_opencode_une_mine_dor">La Base de Données OpenCode : Une Mine d’Or</h2> <div class="sectionbody"> <div class="paragraph"> <p>OpenCode persiste l’intégralité de l’historique de ses sessions dans un fichier SQLite situé à <code>~/.local/share/opencode/opencode.db</code>. La mienne pèse 660 Mo pour 73 jours d’utilisation — une base de données de production tout à fait respectable.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ls -lh ~/.local/share/opencode/opencode.db -rw-r--r-- 1 cheroliv cheroliv 660M mai 18 12:25 opencode.db</code></pre> </div> </div> <div class="sect2"> <h3 id="_le_schéma">Le Schéma</h3> <div class="paragraph"> <p>La base contient une vingtaine de tables, mais trois d’entre elles sont cruciales pour notre audit :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/schema-principal.svg" alt="schema principal" width="684" height="397"> </div> </div> <div class="paragraph"> <p>La table <code>session</code> est parfaite pour un audit global : chaque session a son décompte de tokens agrégé, son modèle utilisé, et son coût. Le champ <code>model</code> est du JSON brut :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "id": "deepseek-v4-pro:cloud", "providerID": "ollama-cloud", "variant": "default" }</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Le champ <code>cost</code> dans la base OpenCode ne reflète que les <strong>frais d’API externes</strong> payés à la consommation via API key (Google Gemini, OpenAI, etc.). Les appels via Ollama — que ce soit en local ou via Ollama Cloud Pro — sont marqués <code>cost=0</code> parce que le coût est forfaitaire (abonnement), pas per-token. Le vrai coût de ces appels, c’est l’abonnement mensuel.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_le_code_dextraction">Le Code d’Extraction</h3> <div class="paragraph"> <p>Pas besoin d’installer quoi que ce soit. Node.js 22+ intègre un module SQLite expérimental (<code>node:sqlite</code>) qui fonctionne parfaitement. Voici le script qui m’a tout donné :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const { DatabaseSync } = require('node:sqlite'); const db = new DatabaseSync( `${process.env.HOME}/.local/share/opencode/opencode.db`, { readonly: true } ); // 1. Statistiques globales const global = db.prepare(` SELECT COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(tokens_reasoning) as total_reasoning, SUM(tokens_cache_read) as total_cache_read, SUM(cost) as total_cost FROM session `).get(); // 2. Ventilation par modèle et fournisseur const byModel = db.prepare(` SELECT json_extract(model, '$.id') as model_id, json_extract(model, '$.providerID') as provider, COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(cost) as total_cost FROM session WHERE model IS NOT NULL GROUP BY model_id, provider ORDER BY SUM(tokens_input) DESC `).all(); // 3. Par mois const monthly = db.prepare(` SELECT strftime('%Y-%m', datetime(time_created/1000, 'unixepoch')) as month, COUNT(*) as sessions, SUM(tokens_input) as total_input, SUM(tokens_output) as total_output, SUM(cost) as total_cost FROM session WHERE time_created IS NOT NULL GROUP BY month ORDER BY month `).all(); // 4. Messages par modèle (détection des changements intra-session) const msgByModel = db.prepare(` SELECT json_extract(m.data, '$.model.providerID') as provider, json_extract(m.data, '$.model.modelID') as model_id, COUNT(*) as messages FROM message m WHERE json_extract(m.data, '$.model') IS NOT NULL GROUP BY provider, model_id ORDER BY COUNT(*) DESC `).all(); console.log({ global, byModel, monthly, msgByModel }); db.close();</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Le flag <code>--experimental-sqlite</code> est nécessaire sur Node.js 22.x. Sur Node.js 24+, le module est stable et ne nécessite plus de flag.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_les_résultats_73_jours_de_consommation">Les Résultats : 73 Jours de Consommation</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_vue_globale">Vue Globale</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Métrique</th> <th class="tableblock halign-left valign-top">Valeur</th> <th class="tableblock halign-left valign-top">Contexte</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Sessions OpenCode</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1 022</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~14 sessions/jour en moyenne</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Input</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,62 milliards</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dont 94,5M en cache hit</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Output</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21 millions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ratio input/output ~125:1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tokens Reasoning</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">141 000</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Négligeable — quasi pas de thinking</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coût API externe</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$0,22</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Frais hors abonnement (Gemini + free tiers)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Ce chiffre de \$0,22 est crucial : il représente tout ce que j’ai payé <strong>en plus</strong> de mon abonnement Ollama Cloud Pro. C’est-à-dire quasiment rien. L’abonnement couvre l’essentiel.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/repartition-mensuelle.svg" alt="repartition mensuelle" width="638" height="207"> </div> </div> <div class="paragraph"> <p>Le décollage entre mars et avril est spectaculaire : ×35 en un mois. C’est la transition de l’usage « test » à l’usage « production » — quand j’ai commencé à faire tourner des agents OpenCode en continu pour mes plugins Gradle.</p> </div> </div> <div class="sect2"> <h3 id="_ventilation_par_modèle_et_fournisseur">Ventilation par Modèle et Fournisseur</h3> <div class="paragraph"> <p>Le champ <code>model</code> de la table <code>session</code> étant du JSON, <code>json_extract()</code> permet de ventiler proprement :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modèle × Provider</th> <th class="tableblock halign-left valign-top">Sessions</th> <th class="tableblock halign-left valign-top">Input</th> <th class="tableblock halign-left valign-top">Output</th> <th class="tableblock halign-left valign-top">Coût</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama-cloud</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">63</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">220 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1,94 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama-b</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">124</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">463 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4,15 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-pro @ ollama</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">252 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,25 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">deepseek-v4-flash-free @ opencode</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">16</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1,3 M</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">279 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">qwen3.6-plus-free @ opencode</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">369 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">25 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">gemini-2.5-flash @ google</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">211 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">19 K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,04</p></td> </tr> </tbody> </table> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Trois providers différents pour exactement le même modèle DeepSeek V4 Pro : * <code>ollama-cloud</code> → via <strong>abonnement Pro payant</strong> (cloud managé par Ollama) * <code>ollama-b</code> → <strong>deuxième abonnement Pro</strong>, isolé dans un conteneur Docker distinct * <code>ollama</code> → instance native locale, <strong>gratuite</strong> (tourne directement sur ma machine) La somme des trois donne 936M input, 8,4M output — c’est ma conso totale DeepSeek V4 Pro, tous providers confondus. Seul <code>ollama-cloud</code> (220M input) coûte un abonnement. Les 716M restants sont gratuits (local ou cumul d’abonnements).</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_les_modèles_intra_session_ce_que_la_table_session_ne_voit_pas">Les Modèles Intra-Session : Ce Que la Table Session Ne Voit Pas</h3> <div class="paragraph"> <p>La table <code>session</code> ne capture que le modèle <strong>principal</strong> de la session. Mais pendant une même session, un agent OpenCode peut basculer entre plusieurs modèles. La table <code>message</code> le révèle :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Modèles utilisés dans les messages (ollama-cloud provider) : ├─ deepseek-v4-pro 1 441 msgs (32%) ├─ qwen3.5:397b 1 217 msgs (27%) ├─ glm-5.1 712 msgs (16%) ├─ kimi-k2.6:cloud 634 msgs (14%) ├─ qwen3-coder:480b 414 msgs (9%) ├─ gpt-oss:20b 34 msgs (0,8%) ├─ qwen3-coder-next 27 msgs (0,6%) └─ gemma4:31b 7 msgs (0,2%)</code></pre> </div> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>Je n’utilise plus Qwen, GLM, Kimi ni les autres modèles. Ils apparaissent dans l’historique parce que j’ai testé pas mal de choses en avril. Depuis mi-mai, je suis verrouillé sur DeepSeek V4 Pro — c’est le seul qui tient la charge sur du long contexte avec gouvernance agent (cf. <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">ma comparaison Kimi/GLM/DeepSeek</a>). Les 32% de messages deepseek dans l’historique sont trompeurs : aujourd’hui c’est 100%.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparatif_tarifaire_fournisseurs_occidentaux">Comparatif Tarifaire — Fournisseurs Occidentaux</h2> <div class="sectionbody"> <div class="paragraph"> <p>La question qui fâche : combien coûterait cette même consommation chez les fournisseurs traditionnels ?</p> </div> <div class="paragraph"> <p>Ma base de calcul pour le comparatif : <strong>220M tokens input + 1,9M tokens output</strong> — <strong>uniquement</strong> le volume passé par <code>ollama-cloud</code> (le seul qui correspond à mon abonnement payant). Les 716M restants sont gratuits (Ollama local et instance Docker B).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 23.0769%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3847%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Fournisseur</th> <th class="tableblock halign-left valign-top">Modèle</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Coût/mois</th> <th class="tableblock halign-left valign-top">× mon abonnement</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mon setup</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\~20€</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>1×</strong></p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_anthropic_claude">Anthropic — Claude</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modèle</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Coût/mois</th> <th class="tableblock halign-left valign-top">× mon abonnement</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 148</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>57×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sonnet 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$689</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>34×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$230</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>11×</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Même Haiku 4.5, le modèle le plus « économique » de Claude, coûte 11× mon abonnement. Et il ne connaît rien de mon codebase, ne génère pas dans mon style, et hallucine sur les APIs Gradle Kotlin DSL.</p> </div> </div> <div class="sect2"> <h3 id="_openai_gpt">OpenAI — GPT</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modèle</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Coût/mois</th> <th class="tableblock halign-left valign-top">× mon abonnement</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 157</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>58×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$579</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>29×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,75</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$174</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>9×</strong></p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_google_gemini">Google — Gemini</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Modèle</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Coût/mois</th> <th class="tableblock halign-left valign-top">× mon abonnement</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3.1 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,00</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$459</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>23×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$69</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>3,5×</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Gemini 3 Flash à 69€ est le seul concurrent « proche » en prix pur — mais c’est un modèle dense léger, pas un MoE 1.6T comme DeepSeek V4 Pro. La qualité du code généré n’a rien à voir.</p> </div> </div> <div class="sect2"> <h3 id="_huggingface_inference_providers">HuggingFace Inference Providers</h3> <div class="paragraph"> <p>HuggingFace ne fait pas d’inférence lui-même — il agrège des <strong>providers</strong> tiers (Novita, Together, DeepInfra, Cerebras, SambaNova, Fireworks, Groq…) via une API unifiée. On choisit le provider le moins cher ou le plus rapide. Voici les tarifs relevés en mai 2026 pour DeepSeek V4 Pro :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 27.2727%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1819%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Provider HF</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Coût/mois</th> <th class="tableblock halign-left valign-top">× mon abonnement</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Novita (le moins cher)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,67</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,38</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$374</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>19×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepInfra</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$389</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>19×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Together</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,40</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$470</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>23×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fireworks</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">tarif non public</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Même le provider le moins cher sur HuggingFace (Novita) facture 19× le prix de mon abonnement. Et contrairement à Ollama Cloud, HuggingFace facture <strong>en plus</strong> les frais de plateforme si vous n’avez pas d’abonnement PRO HF (\$9/mois).</p> </div> </div> <div class="sect2"> <h3 id="_groq">Groq</h3> <div class="paragraph"> <p>Groq n’a <strong>aucun</strong> des modèles que j’utilise — leur catalogue se limite à GPT-OSS, Llama et Qwen 32B. Impossible de comparer.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparatif_tarifaire_fournisseurs_chinois">Comparatif Tarifaire — Fournisseurs Chinois</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le vrai test, c’est le marché chinois. Si DeepSeek est un modèle chinois, son API native devrait être moins chère, non ?</p> </div> <div class="sect2"> <h3 id="_deepseek_api_direct_platform_deepseek_com">DeepSeek API Direct (platform.deepseek.com)</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 22.2222%;"> <col style="width: 22.2222%;"> <col style="width: 22.2223%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Période</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Coût/mois</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Promo -75% (fin 31 mai)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,435</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,87</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$98</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Plein tarif (à partir de juin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$390</strong></p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Même avec la promo agressive de DeepSeek (-75% prolongée), l’API directe coûte <strong>5×</strong> plus cher. Au tarif normal, <strong>20×</strong>. Et c’est <strong>uniquement</strong> DeepSeek — pas d’accès à d’autres modèles.</p> </div> </div> <div class="sect2"> <h3 id="_kimi_moonshot_platform_kimi_com">Kimi Moonshot (platform.kimi.com)</h3> <div class="paragraph"> <p>Kimi ne propose que ses propres modèles. Pas de DeepSeek.</p> </div> </div> <div class="sect2"> <h3 id="_alibaba_bailian_bailian_aliyun_com">Alibaba Bailian (bailian.aliyun.com)</h3> <div class="paragraph"> <p>Seul fournisseur qui agrège tous les modèles chinois — mais via revente avec marge. Les prix sont chargés dynamiquement en JavaScript, rendant le scraping impossible.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tableau_récapitulatif_tous_providers">Tableau Récapitulatif — Tous Providers</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 23.0769%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3846%;"> <col style="width: 15.3847%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Fournisseur</th> <th class="tableblock halign-left valign-top">Modèle</th> <th class="tableblock halign-left valign-top">Input \$/M</th> <th class="tableblock halign-left valign-top">Output \$/M</th> <th class="tableblock halign-left valign-top">Coût/mois</th> <th class="tableblock halign-left valign-top">× mon abonnement</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~20€</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>1×</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gemini 3 Flash</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$69</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3,5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (promo)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,44</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,87</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$98</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4 Mini</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$0,75</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$174</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Haiku 4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$230</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">HuggingFace/Novita</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,67</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,38</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$374</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">19×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek API (normal)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1,74</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3,48</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$390</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">20×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Together AI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek V4 Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$4,40</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$470</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">23×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$2,50</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$579</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">29×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Sonnet 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Sonnet 4.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$689</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">34×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude Opus 4.7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 148</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">57×</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\$1 157</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">58×</p></td> </tr> </tbody> </table> <div class="imageblock"> <div class="content"> <img src="./images/cout-comparaison-barres.svg" alt="cout comparaison barres" width="655" height="279"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_coût_caché_prompt_engineering_et_itérations">Le Coût Caché : Prompt Engineering et Itérations</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le coût token n’est qu’une partie de l’équation. Le vrai coût, c’est le temps développeur.</p> </div> <div class="paragraph"> <p>Avec OpenCode + Ollama Cloud Pro + ma gouvernance agent (EAGER/LAZY/Hot/Warm/Cold, décrite dans <a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">l’article sur la gouvernance</a>), j’obtiens :</p> </div> <div class="ulist"> <ul> <li> <p><strong>0 prompt engineering répétitif</strong> : le contexte est injecté automatiquement</p> </li> <li> <p><strong>90%+ first-shot correct</strong> : le code compile du premier coup</p> </li> <li> <p><strong>Zéro hallucination deepseek sur 8 sessions consécutives</strong> (documenté dans <a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">la comparaison Kimi/GLM/DeepSeek</a>)</p> </li> </ul> </div> <div class="paragraph"> <p>Avec Claude ou GPT <strong>sans</strong> fine-tune ni gouvernance :</p> </div> <div class="ulist"> <ul> <li> <p>2-3 itérations par tâche en moyenne</p> </li> <li> <p>Prompt engineering systématique</p> </li> <li> <p>Hallucinations sur les APIs Kotlin/Gradle dès que le contexte dépasse 30K tokens</p> </li> </ul> </div> <div class="paragraph"> <p>Le coût « effectif » mensuel — tokens × itérations × temps de correction — est de 27× à 54× celui de ma solution, comme je l’ai démontré dans <a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">l’article sur le ratio d’efficacité</a>.</p> </div> <div class="paragraph"> <p><em><em>_ Ce n’est pas juste une histoire de prix au token. Un Claude Opus à 57× le prix qui nécessite 3× plus d’itérations, c’est un coût effectif ~170× supérieur. Pour le dire crûment : payer un stagiaire le salaire d’un partner McKinsey. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_cumuler_les_abonnements_ollama_cloud_pro_la_méthode_docker">Cumuler les Abonnements Ollama Cloud Pro : La Méthode Docker</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si un seul abonnement ne suffit pas, on en cumule. Le principe est d’isoler chaque abonnement dans sa propre installation Ollama, avec sa propre clé SSH d’authentification. Docker rend ça trivial.</p> </div> <div class="paragraph"> <p>La méthode complète est détaillée dans <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">l’article sur le cumul Docker</a>, voici le principe :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-dual-abonnement.svg" alt="architecture dual abonnement" width="581" height="481"> </div> </div> <div class="paragraph"> <p>Le pattern est simple :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Créer un volume <code>~/ollama-b-data</code></p> </li> <li> <p>Lancer un conteneur Docker <code>ollama/ollama:0.20.2</code> mappé sur <code>11435:11434</code></p> </li> <li> <p>Récupérer la clé SSH du conteneur → l’enregistrer sur ollama.com</p> </li> <li> <p>Faire <code>ollama signin</code> avec un deuxième email</p> </li> <li> <p>Configurer OpenCode avec deux providers (<code>ollama</code> sur :11434, <code>ollama-b</code> sur :11435)</p> </li> </ol> </div> <div class="paragraph"> <p>Deux comptes, une carte bleue, zéro conflit.</p> </div> </div> </div> <div class="sect1"> <h2 id="_ce_que_laudit_ne_mesure_pas">Ce Que l’Audit Ne Mesure Pas</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 40%;"> <col style="width: 60%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Angle mort</th> <th class="tableblock halign-left valign-top">Impact</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Qualité du code produit</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2,6 milliards de tokens ne disent pas si le code compile. Mes 8 sessions DeepSeek V4 Pro ont un taux de first-shot >90%.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Écosystème OpenCode</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le CLI est gratuit, mais sa valeur (agents, sandboxes, historique, prompt caching) est immense. Il n’est pas inclus dans le prix de l’abonnement — c’est un outil séparé.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coût d’opportunité</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Passer 2h/jour à debugger des hallucinations d’un modèle inférieur coûte plus cher que 20€/mois.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Tranquillité d’esprit</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Forfait fixe = pas de surprise. Avec du per-token, un pic d’activité peut faire très mal.</p></td> </tr> </tbody> </table> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>Les prix cités sont ceux de mai 2026. Dans six mois, tout aura baissé. Mais le rapport de force structurel — abonnement fixe vs paiement à l’usage — restera favorable à l’abonnement pour les gros consommateurs.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_le_verdict_des_chiffres">Conclusion : Le Verdict des Chiffres</h2> <div class="sectionbody"> <div class="paragraph"> <p>Après 73 jours, 1 022 sessions OpenCode, et 2,6 milliards de tokens :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 60%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Métrique</th> <th class="tableblock halign-left valign-top">Verdict</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coût API externe cumulé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$0,22</strong> (quasi nul)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coût abonnement Ollama Cloud Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>~20€/mois</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Équivalent Claude Opus</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$1 148/mois</strong> — 57× plus cher</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Équivalent GPT 5.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$1 157/mois</strong> — 58× plus cher</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Équivalent HuggingFace/Novita</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$374/mois</strong> — 19× plus cher</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Équivalent DeepSeek API direct</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$390/mois</strong> — 20× plus cher</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Équivalent le moins cher (Gemini Flash)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>\$69/mois</strong> — 3,5× plus cher, modèle inférieur</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Meilleure offre du marché</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Cloud Pro à 20€/mois</strong> — imbattable</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>__</em> À 20€ par mois pour accéder à DeepSeek V4 Pro (1.6T params, MoE, CSA+HCA, 1M contexte) via Ollama Cloud, j’ai le meilleur rapport qualité/prix du marché mondial. Même les fournisseurs chinois en direct sont 5× à 20× plus chers. Même HuggingFace, avec son agrégation de providers low-cost, est 19× plus cher. Le marché occidental (Claude, GPT) est à 50-60× — une autre planète.</p> </div> <div class="paragraph"> <p>Ce ratio est tellement déséquilibré qu’il ne peut pas durer éternellement. Profitez-en tant que ça existe. <em>__</em></p> </div> <div class="paragraph"> <p>Alors oui, mes 20 balles par mois, c’est le meilleur investissement technique de ma vie de développeur. Et maintenant vous avez les chiffres pour le prouver.</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Gouvernance Agent EAGER/LAZY/Hot/Warm/Cold</a></p> </li> <li> <p><a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Article 0112 — DeepSeek V4 Pro vs Kimi K2.6 vs GLM 5.1</a></p> </li> <li> <p><a href="0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html">Article 0119 — Benchmark DGX Spark vs Cloud vs Abonnements LLM</a></p> </li> <li> <p><a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">Article 0120 — Cumuler Deux Abonnements Ollama Cloud Pro avec Docker</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Article 0121 — Plugin Gradle pour Piloter Deux Instances Ollama</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Article 0122 — Ratio Efficacité 27× à 54×</a></p> </li> </ul> </div> <div class="sect2"> <h3 id="_sources_des_tarifs">Sources des Tarifs</h3> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/pricing">Ollama Cloud — Tarifs Pro \$20/mois</a></p> </li> <li> <p><a href="https://api-docs.deepseek.com/quick_start/pricing">DeepSeek API — Tarifs officiels V4 Pro</a></p> </li> <li> <p><a href="https://platform.kimi.com/docs/pricing/chat-k26">Kimi Moonshot — Tarifs K2.6</a></p> </li> <li> <p><a href="https://huggingface.co/inference/models">HuggingFace Inference Providers — Tarifs par provider</a></p> </li> <li> <p><a href="https://www.anthropic.com/pricing">Anthropic — Tarifs Claude API</a></p> </li> <li> <p><a href="https://openai.com/api/pricing/">OpenAI — Tarifs GPT API</a></p> </li> <li> <p><a href="https://together.ai/pricing">Together AI — Tarifs inférence</a></p> </li> <li> <p><a href="https://groq.com/pricing">Groq — Tarifs API</a></p> </li> <li> <p><a href="https://deepinfra.com/pricing">DeepInfra — Tarifs GPU et modèles</a></p> </li> <li> <p><a href="https://help.aliyun.com/zh/model-studio/text-generation-model/">Alibaba Bailian — Modèles disponibles</a></p> </li> <li> <p><a href="https://github.com/anomalyco/opencode">OpenCode — CLI open source sur GitHub</a></p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html Thu, 14 May 2026 00:00:00 +0000 blog/2026/0124_architecture_plugin_gradle_racine_consommateur_independant_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_problème_trois_architectures_qui_mont_fait_perdre_du_temps">Le Problème : Trois Architectures Qui M’ont Fait Perdre du Temps</a> <ul class="sectlevel2"> <li><a href="#_option_1_le_plugin_isolé_pas_de_dogfooding">Option 1 : Le Plugin Isolé (pas de dogfooding)</a></li> <li><a href="#_option_2_le_monorepo_classique_includeplugin">Option 2 : Le Monorepo Classique (<code>include(":plugin")</code>)</a></li> <li><a href="#_option_3_le_composite_build_includebuild">Option 3 : Le Composite Build (<code>includeBuild()</code>)</a></li> </ul> </li> <li><a href="#_la_solution_deux_builds_indépendants_une_racine_consommateur">La Solution : Deux Builds Indépendants, Une Racine Consommateur</a> <ul class="sectlevel2"> <li><a href="#_le_flux_de_travail">Le Flux de Travail</a></li> <li><a href="#_le_workflow_concret">Le Workflow Concret</a></li> </ul> </li> <li><a href="#_pourquoi_cette_architecture_ma_conquis">Pourquoi Cette Architecture M’a Conquis</a> <ul class="sectlevel2"> <li><a href="#_1_dogfooding_natif_feedback_instantané">1. Dogfooding Natif, Feedback Instantané</a></li> <li><a href="#_2_clonage_zero_config">2. Clonage Zero-Config</a></li> <li><a href="#_3_builds_isolés_ci_indépendants">3. Builds Isolés, CI Indépendants</a></li> </ul> </li> <li><a href="#_lanatomie_du_sous_dossier_name_plugin">L’Anatomie du Sous-Dossier <code>{name}-plugin/</code></a> <ul class="sectlevel2"> <li><a href="#_le_catalogue_de_versions_deux_fichiers_distincts">Le Catalogue de Versions : Deux Fichiers Distincts</a></li> </ul> </li> <li><a href="#_ce_quon_ne_fait_pas">Ce Qu’On Ne Fait Pas</a></li> <li><a href="#_comparaison_les_trois_architectures_face_au_dogfooding">Comparaison : Les Trois Architectures Face au Dogfooding</a></li> <li><a href="#_le_contrat_dag_un_build_racin_nimporte_jamais_depuis_un_sous_dossier">Le Contrat DAG : Un Build Racin N’Importe Jamais Depuis un Sous-Dossier</a></li> <li><a href="#_conclusion_la_duplication_apparente_qui_fait_gagner_du_temps">Conclusion : La Duplication Apparente Qui Fait Gagner du Temps</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 11 minutes</div> <p>Vous clonez un dépôt de plugin Gradle. Vous ouvrez un terminal. Qu’est-ce que vous tapez ensuite ? <code>./gradlew tasks</code>, bien sûr. Mais dans quel dossier ? La racine ? Le sous-module ? Faut-il d’abord lire un README pour savoir comment builder ? Si vous hésitez ne serait-ce qu’une seconde, l’architecture du projet est cassée.</p> </div> <div class="paragraph"> <p>Voici comment j’ai résolu ce problème une fois pour toutes — et pourquoi ce pattern est aujourd’hui la signature de tous mes plugins Gradle dans <code>foundry/public/</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_problème_trois_architectures_qui_mont_fait_perdre_du_temps">Le Problème : Trois Architectures Qui M’ont Fait Perdre du Temps</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant de converger vers le pattern actuel, j’ai tâtonné entre trois approches classiques pour organiser un plugin Gradle. Chacune avait un défaut rédhibitoire.</p> </div> <div class="sect2"> <h3 id="_option_1_le_plugin_isolé_pas_de_dogfooding">Option 1 : Le Plugin Isolé (pas de dogfooding)</h3> <div class="paragraph"> <p>Le projet ne contient que le plugin. Pas d’exemple de consommation. Pas de projet qui l’exerce. Pour le tester, il faut créer un projet externe, y référencer le plugin via <code>mavenLocal</code> ou un composite build, et seulement là vérifier qu’il marche.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">$ git clone mon-plugin $ cd mon-plugin $ ./gradlew build # le plugin compile $ # ... et maintenant ? comment je l'essaie ?</code></pre> </div> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>Un plugin Gradle sans exemple de consommation, c’est une bibliothèque sans tests d’intégration. Vous ne savez jamais si la dernière modification a cassé l’expérience utilisateur.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_option_2_le_monorepo_classique_includeplugin">Option 2 : Le Monorepo Classique (<code>include(":plugin")</code>)</h3> <div class="paragraph"> <p>Gradle <code>init</code> génère <code>settings.gradle.kts</code> avec <code>include("plugin")</code>. Le root et le sous-module partagent le même daemon, les mêmes configurations, les mêmes catalogues. Pratique, mais couplé.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── settings.gradle.kts → include("plugin") ├── build.gradle.kts → plugins { id("mon-plugin") } ├── plugin/ │ └── build.gradle.kts → java-gradle-plugin └── gradle/ └── libs.versions.toml</code></pre> </div> </div> <div class="paragraph"> <p>Ce qui coince :</p> </div> <div class="ulist"> <ul> <li> <p>Le root <strong>doit</strong> avoir la même version de Gradle que le sous-module.</p> </li> <li> <p><code>libs.versions.toml</code> est partagé — version catalogs communs, dépendances</p> </li> </ul> </div> <div class="paragraph"> <p>qui fuient d’un module à l’autre.</p> </div> <div class="ulist"> <ul> <li> <p>Impossible de builder le plugin indépendamment du root.</p> </li> <li> <p>La CI doit builder les deux modules, même si seul le plugin a changé.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_option_3_le_composite_build_includebuild">Option 3 : Le Composite Build (<code>includeBuild()</code>)</h3> <div class="paragraph"> <p>On sépare les deux en builds Gradle distincts et on les relie via <code>includeBuild("mon-plugin")</code> dans <code>settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>C’est déjà mieux. Le build du plugin est isolé. Mais le consommateur doit explicitement référencer le build externe — et la sortie de <code>./gradlew tasks</code> à la racine dépend de la bonne configuration du composite. Le clonage n’est pas zero-config : il faut savoir que le plugin est dans un dossier à part, que le root le référence, etc.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">. ├── settings.gradle.kts → includeBuild("plugin-build/") ├── build.gradle.kts → plugins { id("mon-plugin") } └── plugin-build/ ├── settings.gradle.kts └── build.gradle.kts</code></pre> </div> </div> <div class="paragraph"> <p>Je cherchais mieux. Beaucoup mieux.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solution_deux_builds_indépendants_une_racine_consommateur">La Solution : Deux Builds Indépendants, Une Racine Consommateur</h2> <div class="sectionbody"> <div class="paragraph"> <p>Voici le pattern que j’ai fini par adopter :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── settings.gradle.kts ← racine consommateur ├── build.gradle.kts ← 3 lignes : apply plugin + dogfood ├── gradle/ │ └── libs.versions.toml ← catalogue du consommateur ├── {name}-plugin/ ← BUILD INDÉPENDANT │ ├── gradlew ← son propre wrapper │ ├── settings.gradle.kts ← rootProject.name = "{name}-plugin" │ ├── build.gradle.kts ← java-gradle-plugin, signing, publish │ ├── gradle/ │ │ ├── libs.versions.toml ← catalogue du plugin │ │ └── wrapper/ │ ├── src/ ← sources du plugin │ ├── .agents/ ← gouvernance agent │ └── *.adoc ← AGENT, PROMPT_REPRISE, snapshot, etc. └── site.yml / slides-context.yml / ... ← configs dogfood</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>La clé : <code>{name}-plugin/</code> est un projet Gradle <strong>complet et autonome</strong>. Il a son propre wrapper, son propre settings, son propre catalogue de versions. Il se clone, se build, se teste, et se publie sans que le root soit au courant de son existence.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Le root, lui, ne fait qu'<strong>une</strong> chose : appliquer le plugin.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { alias(libs.plugins.bakery) } repositories { mavenLocal() mavenCentral() } bakery { configPath = file("site.yml").absolutePath }</code></pre> </div> </div> <div class="paragraph"> <p>Trois lignes dans le cas de <code>bakery-gradle</code>. Rien de plus. Zéro <code>include()</code>, zéro <code>includeBuild()</code>, zéro sous-projet. Un build Gradle classique qui applique un plugin comme n’importe quel consommateur le ferait.</p> </div> <div class="sect2"> <h3 id="_le_flux_de_travail">Le Flux de Travail</h3> <div class="imageblock"> <div class="content"> <img src="./images/architecture-deux-builds.svg" alt="architecture deux builds" width="1773" height="5743"> </div> </div> </div> <div class="sect2"> <h3 id="_le_workflow_concret">Le Workflow Concret</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># 1. Builder le plugin $ cd codebase-plugin $ ./gradlew publishToMavenLocal # 2. L'exercer depuis la racine $ cd .. $ ./gradlew indexCodebase queryCodebase snapshot # La boucle est fermée. Le plugin est testé dans des conditions # réelles de consommation, par le projet même qui l'héberge.</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_cette_architecture_ma_conquis">Pourquoi Cette Architecture M’a Conquis</h2> <div class="sectionbody"> <div class="paragraph"> <p>Trois bénéfices qui, combinés, valent le coût de la « duplication » :</p> </div> <div class="sect2"> <h3 id="_1_dogfooding_natif_feedback_instantané">1. Dogfooding Natif, Feedback Instantané</h3> <div class="paragraph"> <p>Le meilleur test d’un plugin Gradle, c’est de l’utiliser. Pas un test unitaire mocké. Pas un <code>GradleRunner</code> avec un projet de test. Un <strong>vrai</strong> build qui applique le plugin sur de vrais fichiers.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell">$ git clone bakery-gradle $ cd bakery-gradle $ ./gradlew bake # ← le plugin est exercé immédiatement</code></pre> </div> </div> <div class="paragraph"> <p>Si le plugin est cassé, le build racine le dit. Pas besoin d’aller chercher un projet de test externe. Le dogfooding est la <strong>première</strong> tâche que lance un nouveau contributeur. C’est le smoke test définitif.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>La règle est simple : si la racine compile et que <code>./gradlew tasks</code> affiche vos tâches de plugin, le plugin est fonctionnel. Pas de surprise en production.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_clonage_zero_config">2. Clonage Zero-Config</h3> <div class="paragraph"> <p>Un <code>git clone && ./gradlew tasks</code> et le nouveau venu voit tout marcher sans rien configurer. Le <code>build.gradle.kts</code> racine est la documentation vivante d’usage du plugin. Le <code>site.yml</code> à côté montre la configuration attendue.</p> </div> <div class="paragraph"> <p>Comparez avec l’alternative : un README de trois paragraphes qui explique comment builder le plugin ET comment builder le projet de test. Un nouveau contributeur lit le README en diagonale, se trompe, ouvre une issue — alors que l’information pourrait être <strong>exécutable</strong>.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>La documentation la plus robuste n’est pas celle qu’on lit. C’est celle qu’on <strong>exécute</strong>. Le build racine est la documentation exécutable du plugin.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_3_builds_isolés_ci_indépendants">3. Builds Isolés, CI Indépendants</h3> <div class="paragraph"> <p>Le plugin a son propre wrapper Gradle, son propre cycle de vie, ses propres tests. Vous pouvez :</p> </div> <div class="ulist"> <ul> <li> <p>Upgrader Gradle dans le plugin sans toucher au root</p> </li> <li> <p>Ajouter une dépendance dans le plugin sans qu’elle fuite dans le root</p> </li> <li> <p>Casser le plugin sans impacter le build racine (tant que vous ne</p> </li> </ul> </div> <div class="paragraph"> <p>publiez pas la version cassée)</p> </div> <div class="ulist"> <ul> <li> <p>Avoir une CI qui build/test le plugin, et une autre qui exerce le</p> </li> </ul> </div> <div class="paragraph"> <p>root — indépendamment</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">.github/workflows/ ├── test-plugin.yml → codebase-plugin/.gradlew build ├── test-root.yml → .gradlew tasks (vérifie que le plugin est consommable) └── publish.yml → codebase-plugin/.gradlew publish</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lanatomie_du_sous_dossier_name_plugin">L’Anatomie du Sous-Dossier <code>{name}-plugin/</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>Regardons de plus près ce qui vit dans le dossier du plugin :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">codebase-plugin/ ├── gradlew ← wrapper indépendant ├── settings.gradle.kts ← @Suppress("UnstableApiUsage") │ + foobar-resolver-convention ├── build.gradle.kts ← java-gradle-plugin + signing + publish ├── gradle/ │ ├── libs.versions.toml ← catalogue complet (langchain4j, pgvector...) │ └── wrapper/ ├── buildSrc/ ← classes utilitaires buildSrc │ ├── build.gradle.kts │ └── src/main/kotlin/ │ ├── codebase/ ← CodebaseYmlAnonymizer, CodebaseConfiguration │ ├── benchmark/ ← BenchmarkConfig, BenchmarkProtocol │ ├── readme/ ← ReadmeYmlAnonymizer │ ├── site/ ← SiteYmlAnonymizer │ ├── slider/ ← SliderYmlAnonymizer │ └── snapshot/ ← SnapshotManager ├── src/ │ ├── main/kotlin/codebase/ │ │ ├── CodebasePlugin.kt ← class Plugin<Project> │ │ ├── rag/ ← pgvector, embedding, anonymization... │ │ ├── benchmark/ ← BenchmarkRunner, export, comparison... │ │ └── walker/ ← WorkspaceWalker │ └── test/ │ ├── kotlin/codebase/scenarios/ ← steps Cucumber │ ├── features/ ← .feature files │ └── resources/datasets/ ← fixtures .adoc, .yml, .json ├── .agents/ ← gouvernance agent (INDEX, SESSIONS, etc.) ├── AGENT.adoc ← règles agent ├── PROMPT_REPRISE.adoc ← mission session ├── BACKLOG.adoc ← backlog produit ├── snapshot.adoc ← snapshot auto-généré du projet └── embeds.yml ← config RAG embeds</code></pre> </div> </div> <div class="paragraph"> <p>Tout est là. Pas de dispersion entre la racine et le sous-dossier. Le développeur qui travaille sur le plugin n’a jamais besoin de quitter <code>codebase-plugin/</code>. Le développeur qui utilise le plugin ne regarde que la racine — et le <code>build.gradle.kts</code> de 3 lignes lui dit tout ce qu’il a besoin de savoir.</p> </div> <div class="sect2"> <h3 id="_le_catalogue_de_versions_deux_fichiers_distincts">Le Catalogue de Versions : Deux Fichiers Distincts</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 37.5%;"> <col style="width: 37.5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gradle/libs.versions.toml</code> (racine)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>{name}-plugin/gradle/libs.versions.toml</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Nombre de dépendances</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2-3 (plugin + readme éventuellement)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30+ (langchain4j, pgvector, cucumber…​)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Rôle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Consommer le plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Builder le plugin</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Qui le lit</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’utilisateur du plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le développeur du plugin</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le root a un catalogue volontairement minimal. Le plugin a un catalogue complet. La confusion est impossible : chaque build a son propre scope de dépendances.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Si vous avez déjà passé une heure à déboguer une collision de dépendances entre votre plugin et votre projet de test, vous comprenez la valeur de cette séparation. Les catalogues indépendants éliminent ce problème par construction.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ce_quon_ne_fait_pas">Ce Qu’On Ne Fait Pas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce pattern n’est pas magique. Il impose une contrainte que je m’inflige volontiers :</p> </div> <div class="paragraph"> <p><strong>Le root ne build pas le plugin.</strong> Vous devez <code>publishToMavenLocal</code> ou déployer sur un repository avant que le root puisse le consommer.</p> </div> <div class="paragraph"> <p>C’est un coût minime, et c’est la <strong>bonne</strong> contrainte. Le root consomme le plugin comme un client externe — via Maven. Exactement comme le ferait un projet tiers. Si le plugin n’est pas publiable, le root vous le dit immédiatement.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-shell hljs" data-lang="shell"># La seule "friction" du pattern $ cd codebase-plugin && ./gradlew publishToMavenLocal && cd .. $ ./gradlew tasks --group=codebase</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comparaison_les_trois_architectures_face_au_dogfooding">Comparaison : Les Trois Architectures Face au Dogfooding</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> <col style="width: 20%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Plugin isolé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Monorepo <code>include()</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Composite <code>includeBuild()</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Racine + plugin indép.</strong></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>git clone && gradlew tasks</code> donne les tâches du plugin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Build plugin indépendant du root</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Catalogue versions séparé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Pas de <code>include()</code> ni <code>includeBuild()</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dogfood natif sans config</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">CI plugin indépendante</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Le root est un exemple de conso réel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>La colonne de droite coche toutes les cases. C’est pour ça que je ne reviendrai plus en arrière.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_contrat_dag_un_build_racin_nimporte_jamais_depuis_un_sous_dossier">Le Contrat DAG : Un Build Racin N’Importe Jamais Depuis un Sous-Dossier</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cette architecture s’intègre naturellement dans le DAG N0→N3 de mon workspace. Le pattern est : <strong>le plugin N2 est le hub de ses propres dépendances, la racine N3 est un terminal qui applique des hubs</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/contrat-dag-architecture.svg" alt="contrat dag architecture" width="1751" height="5480"> </div> </div> <div class="paragraph"> <p>Le <code>codebase-gradle/build.gradle.kts</code> fait 6 lignes. Pas de <code>src/</code>, pas de <code>buildSrc/</code>, pas de <code>gradle/rag-bench.gradle.kts</code>. Juste <code>plugins { alias(libs.plugins.codebase) }</code> et les repositories. Toute la complexité vit dans <code>codebase-plugin/</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_la_duplication_apparente_qui_fait_gagner_du_temps">Conclusion : La Duplication Apparente Qui Fait Gagner du Temps</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand je montre cette structure à quelqu’un, la première réaction est souvent : « Mais tu as deux <code>gradlew</code>, deux <code>settings.gradle.kts</code>, deux <code>libs.versions.toml</code> — c’est de la duplication ! »</p> </div> <div class="paragraph"> <p>Oui. Et non.</p> </div> <div class="paragraph"> <p>La « duplication », c’est reproduire la même information à deux endroits. Ici, ce sont deux fichiers <strong>distincts</strong> qui servent deux usages <strong>distincts</strong> : le catalogue du plugin (30+ dépendances pour builder) et le catalogue de la racine (2-3 dépendances pour consommer). Le wrapper du plugin (version verrouillée pour le développement) et le wrapper de la racine (version potentiellement différente, pour l’exercice du plugin).</p> </div> <div class="paragraph"> <p>Ce n’est pas de la duplication. C’est de la <strong>séparation des responsabilités</strong> appliquée au système de build. Chaque build fait une chose, et une seule. La racine consomme. Le plugin se build.</p> </div> <div class="paragraph"> <p>Le coût ? Une commande <code>publishToMavenLocal</code> entre le build du plugin et le build de la racine. Le gain ? Une clarté architecturale qui supprime des heures de débogage en aval.</p> </div> <div class="paragraph"> <p>Depuis que j’ai déployé ce pattern sur <code>bakery-gradle</code>, <code>plantuml-gradle</code>, <code>codebase-gradle</code>, et les autres plugins de <code>foundry/public/</code>, je n’ai plus jamais hésité en ouvrant un terminal dans un de mes dépôts. Le premier réflexe — <code>./gradlew tasks</code> — marche toujours, donne toujours les bonnes tâches, et me dit instantanément si tout est sain.</p> </div> <div class="paragraph"> <p>C’est ça, la bonne architecture. Elle ne se lit pas dans un README. Elle s’éprouve dans un terminal, en moins de dix secondes.</p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Article 0105 — Intégrer Graphify dans un workflow Gradle</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Article 0117 — La Granularisation OSS/CSS</a></p> </li> <li> <p><a href="0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html">Article 0123 — Le Knowledge Graph comme moteur de recommandation</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html Tue, 12 May 2026 00:00:00 +0000 blog/2026/0123_knowledge_graph_moteur_recommandation_articles_connexes_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scène_mardi_12_mai_17h30">La Scène : Mardi 12 Mai, 17h30</a></li> <li><a href="#_le_diagnostic_trois_types_de_relations_quaucun_template_ne_voit">Le Diagnostic : Trois Types de Relations Qu’Aucun Template Ne Voit</a></li> <li><a href="#_la_solution_un_pipeline_gradle_pas_un_appel_llm_à_chaud">La Solution : Un Pipeline Gradle, Pas un Appel LLM à Chaud</a> <ul class="sectlevel2"> <li><a href="#_larchitecture_bakery_importe_graphify_pas_engine">L’Architecture : Bakery Importe Graphify, Pas Engine</a></li> <li><a href="#_le_pipeline_scan_graphe_template">Le Pipeline : Scan → Graphe → Template</a></li> <li><a href="#_fallback_chronologique">Fallback Chronologique</a></li> </ul> </li> <li><a href="#_lontologie_émergente_quand_les_articles_se_regroupent_sans_se_connaître">L’Ontologie Émergente : Quand les Articles Se Regroupent Sans Se Connaître</a></li> <li><a href="#_le_contrat_dag_qui_importe_qui">Le Contrat DAG : Qui Importe Qui</a></li> <li><a href="#_ce_quon_gagne_et_ce_quon_ne_gagne_pas">Ce Qu’on Gagne (Et Ce Qu’on Ne Gagne Pas)</a></li> <li><a href="#_perspectives_le_blog_comme_knowledge_graph_public">Perspectives : Le Blog Comme Knowledge Graph Public</a></li> <li><a href="#_conclusion_le_système_de_fichiers_sait_ce_que_le_template_ignore">Conclusion : Le Système de Fichiers Sait Ce Que le Template Ignore</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 14 minutes</div> <p>Vous lisez un article sur l’intégration de pgvector avec LangChain4j. En bas de page, JBake vous suggère « Articles connexes ». Vous cliquez. C’est un article sur…​ la configuration de Kitty Terminal. Le seul point commun entre les deux ? Ils ont été publiés à moins de quinze jours d’écart. Ce n’est pas une recommandation. C’est un calendrier déguisé en éditorial.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_scène_mardi_12_mai_17h30">La Scène : Mardi 12 Mai, 17h30</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je relis un de mes articles — <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">celui sur le Knowledge Graph comme outil de compréhension de codebase</a>. Le contenu est dense : nœuds, arêtes, communautés, PlantUML, onboarding. Un article technique de 15 minutes de lecture qui mobilise <code>graphify-gradle</code>, <code>plantuml-gradle</code>, et les concepts de topologie de graphe.</p> </div> <div class="paragraph"> <p>En bas de page, les « Articles connexes » me proposent :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Un article sur Firebase Contact Form (0113)</p> </li> <li> <p>Un article sur le mécanisme Eager/Lazy (0108)</p> </li> <li> <p>Un article sur la migration Gradle script → plugin (0102)</p> </li> <li> <p>Un article sur le cumul d’abonnements Ollama Pro (0120)</p> </li> </ol> </div> <div class="paragraph"> <p>Trois de ces quatre articles n’ont <strong>aucun</strong> rapport avec le Knowledge Graph. Ils sont là parce qu’ils sont les derniers publiés — voisinage temporel, pas voisinage sémantique.</p> </div> <div class="paragraph"> <p>Je regarde le template <code>post.thyme</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes (liens internes SEO) --> <th:block th:each="post,postStat : ${published_posts}"> <th:block th:if="${!post.uri.equals(content.uri) and postStat.index lt 4}"> ... </th:block> </th:block></code></pre> </div> </div> <div class="paragraph"> <p><code>published_posts</code> est une liste chronologique. <code>postStat.index lt 4</code> prend les quatre premiers qui ne sont pas le post courant. C’est tout. Aucune logique de similarité. Aucune notion de contenu. Juste une boucle <code>for</code> déguisée en recommandation.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="⚠️"></i> </td> <td class="content"> <div class="paragraph"> <p>Ce n’est pas un bug de JBake. C’est le comportement par défaut de tout générateur de site statique : la liste des posts est plate et ordonnée par date. Le template fait ce qu’il peut avec ce qu’il a.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Mais ce n’est pas une raison pour l’accepter.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_diagnostic_trois_types_de_relations_quaucun_template_ne_voit">Le Diagnostic : Trois Types de Relations Qu’Aucun Template Ne Voit</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mon corpus d’articles — 23 posts en 4 mois — a une structure riche que le template chronologique écrase complètement :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Références explicites</strong> : j’utilise <code>xref:</code> massivement dans mes articles.</p> </li> </ol> </div> <div class="paragraph"> <p>L’article 0122 référence 0106 (knowledge graph) et 0116 (compartimentage épistémique). Ces liens sont du <strong>hard linking</strong> éditorial — j’ai délibérément décidé de connecter ces concepts.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Tags partagés</strong> : chaque article a des <code>:jbake-tags:</code>. L’article sur</p> </li> </ol> </div> <div class="paragraph"> <p>Graphify + PlantUML (0105) a <code>gradle, graphify, plantuml, knowledge-graph</code>. L’article sur le Knowledge Graph (0106) a <code>knowledge-graph, graphify, plantuml</code>. Trois tags en commun sur sept — 43% de recouvrement.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Entités nommées co-occurrentes</strong> : « pgvector », « RAG », « embedding »</p> </li> </ol> </div> <div class="paragraph"> <p>apparaissent ensemble dans quatre articles différents. « LangChain4j », « Ollama », « plugin Gradle » dans six autres. Ce ne sont pas des tags déclarés — ce sont des <strong>patterns émergents</strong> du corpus que seul un NLP peut détecter.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/trois-couches-relation-articles.svg" alt="trois couches relation articles" width="1742" height="5492"> </div> </div> <div class="paragraph"> <p>Aujourd’hui, mon site n’utilise <strong>aucune</strong> de ces trois couches. Il utilise la couche zéro : l’ordre d’insertion dans une liste Java.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solution_un_pipeline_gradle_pas_un_appel_llm_à_chaud">La Solution : Un Pipeline Gradle, Pas un Appel LLM à Chaud</h2> <div class="sectionbody"> <div class="paragraph"> <p>La première tentation serait d’appeler un LLM au moment du bake : « Pour cet article, trouve les trois articles les plus similaires dans le corpus. » Ne faites pas ça.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Un appel LLM à chaque <code>./gradlew bake</code> coûte du temps, de l’argent, et introduit de la non-déterminisme dans votre build. La réponse du LLM peut changer entre deux builds sans que le contenu ait changé. Votre CI devient non reproductible, vos tests deviennent flaky.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>La solution est déterministe : un pipeline Gradle qui pré-calcule le graphe de similarité et le stocke dans <code>graph.json</code>. Le template lit le résultat — jamais il ne déclenche un calcul.</p> </div> <div class="sect2"> <h3 id="_larchitecture_bakery_importe_graphify_pas_engine">L’Architecture : Bakery Importe Graphify, Pas Engine</h3> <div class="paragraph"> <p>C’est le point d’architecture le plus important. La tentation serait de câbler la collaboration dans <code>engine/build.gradle.kts</code> : engine applique graphify pour le scan, bakery pour le bake, et engine fait le pont entre les deux.</p> </div> <div class="paragraph"> <p>C’est un anti-pattern. Engine est un <strong>terminal consommateur</strong> — il applique des plugins, il n’implémente pas de logique métier. La règle est : <strong>la charge de la preuve est sur le plugin propriétaire.</strong></p> </div> <div class="imageblock"> <div class="content"> <img src="./images/bakery-import-graphify.svg" alt="bakery import graphify" width="1787" height="5700"> </div> <div class="title">Figure 1. Architecture correcte — Bakery importe Graphify</div> </div> <div class="paragraph"> <p>Le contrat DAG est respecté : bakery (N2) importe graphify (N0), N2 > N0, aucune violation. Engine (N3) importe bakery (N2), N3 > N2, OK.</p> </div> <div class="paragraph"> <p>Engine n’a <strong>aucune</strong> ligne de code qui référence <code>graph.json</code>, <code>relatedPosts</code>, ou toute autre notion de similarité. Il applique bakery, point. La collaboration est interne à bakery.</p> </div> </div> <div class="sect2"> <h3 id="_le_pipeline_scan_graphe_template">Le Pipeline : Scan → Graphe → Template</h3> <div class="paragraph"> <p>Voici le pipeline complet en trois étapes :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Scan</strong> (graphify) : <code>graphify-plugin</code> scanne le workspace. Dans sa</p> </li> </ol> </div> <div class="paragraph"> <p>forme actuelle, il détecte déjà les <code>xref:</code> entre <code>.adoc</code> et les expose dans <code>graph.json</code> comme des edges de type <code>reference</code>.<br> On l’enrichit pour le contenu éditorial : * Parse les métadonnées JBake (<code>:jbake-tags:</code>, <code>:jbake-description:</code>) de chaque <code>.adoc</code> du blog * Calcule les co-occurrences de tags → edges <code>tag_cooccurrence</code> avec poids * Extrait les entités nommées des descriptions via TF-IDF → edges <code>entity_overlap</code> * Injecte une section <code>blog_articles</code> dans le <code>graph.json</code> existant<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Extrait de l'enrichissement graphify pour le blog fun enrichBlogSection(graphJson: File, blogDir: File): GraphJson { val articles = blogDir.listFiles { f -> f.extension == "adoc" } .map { parseJbakeMetadata(it) } val nodes = articles.map { ArticleNode(it.slug, it.title, it.tags) } val edges = mutableListOf<GraphEdge>() // Couche 1 : xref (déjà fait par scanWorkspace) // Couche 2 : co-occurrences de tags for (a in articles) { for (b in articles) { if (a.slug == b.slug) continue val common = a.tags.intersect(b.tags) if (common.isNotEmpty()) { edges.add(GraphEdge( source = a.slug, target = b.slug, type = "tag_cooccurrence", weight = common.size.toDouble() / (a.tags.size + b.tags.size) )) } } } return graphJson.copy( blogArticles = BlogSection(nodes, edges) ) }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Bake</strong> (bakery) : au moment du <code>./gradlew bake</code>, <code>BakeryPlugin</code> lit</p> </li> </ol> </div> <div class="paragraph"> <p><code>graph.json</code> et résout les articles connexes pour chaque post.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BakeryPlugin — résolution des articles connexes fun resolveRelatedPosts( currentSlug: String, graph: GraphJson, maxResults: Int = 4 ): List<RelatedPost> { val edges = graph.blogArticles.edges .filter { it.source == currentSlug || it.target == currentSlug } return edges .sortedByDescending { it.weight } .take(maxResults) .map { edge -> val relatedSlug = if (edge.source == currentSlug) edge.target else edge.source graph.blogArticles.nodes.first { it.slug == relatedSlug } } }</code></pre> </div> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Template</strong> (<code>post.thyme</code>) : le modèle JBake reçoit maintenant une map</p> </li> </ol> </div> <div class="paragraph"> <p>structurée au lieu d’une liste chronologique plate.<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xhtml hljs" data-lang="xhtml"><!-- Articles connexes basés sur le Knowledge Graph --> <th:block th:if="${relatedPosts != null and !relatedPosts.empty}"> <section class="mt-5 pt-4 border-top"> <h2 class="h4 mb-3">Articles connexes</h2> <th:block th:each="related : ${relatedPosts}"> <div class="mb-2"> <a th:href="${content.rootpath} + ${related.uri}" th:text="${related.title}" class="fw-semibold"></a> <br/> <small class="text-muted"> <th:block th:each="reason,iterStat : ${related.reasons}"> <span class="badge bg-light text-dark" th:text="${reason}"></span> </th:block> </small> </div> </th:block> </section> </th:block></code></pre> </div> </div> <div class="paragraph"> <p>Le template est le même — il ne sait pas <strong>d’où</strong> viennent les données. Seul le contrat entre bakery et JBake a changé : <code>published_posts</code> (liste chronologique) devient <code>relatedPosts</code> (map pondérée par le graphe).</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Le badge « raison » (ex: <code>xref 0122</code>, <code>tag:gradle</code>, <code>cluster:pgvector-rag</code>) explique au lecteur <strong>pourquoi</strong> cet article est connexe. Ce n’est pas juste de la transparence — c’est de la pédagogie sur la topologie de votre propre contenu.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_fallback_chronologique">Fallback Chronologique</h3> <div class="paragraph"> <p>Si <code>graph.json</code> est absent (build local sans scan préalable, premier déploiement, CI qui n’a pas encore intégré le scan graphify), le template doit dégrader gracieusement :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveRelatedPosts(currentSlug: String, graph: GraphJson?): List<RelatedPost> { if (graph != null && graph.blogArticles != null) { return resolveFromGraph(currentSlug, graph) } // Fallback chronologique — même comportement qu'aujourd'hui logger.warn("[bakery] graph.json absent — fallback chronologique") return resolveFromChronology(currentSlug) }</code></pre> </div> </div> <div class="paragraph"> <p>Le comportement par défaut est identique au comportement actuel. Le moteur de recommandation est une <strong>amélioration progressive</strong> — pas un breaking change.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lontologie_émergente_quand_les_articles_se_regroupent_sans_se_connaître">L’Ontologie Émergente : Quand les Articles Se Regroupent Sans Se Connaître</h2> <div class="sectionbody"> <div class="paragraph"> <p>La couche la plus intéressante est la troisième : l’ontologie émergente. Des articles qui ne se citent pas, qui n’ont pas les mêmes tags, mais qui <strong>parlent de la même chose</strong> sans le savoir.</p> </div> <div class="paragraph"> <p>Prenons un exemple concret. Trois articles de mon corpus :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>0119 — Benchmark DGX Spark vs Cloud Abonnement LLM</p> </li> <li> <p>0121 — Plugin Gradle Piloter Deux Instances Ollama Pro</p> </li> <li> <p>0122 — Ratio Efficacité 27x 45x Flotte Experts IA</p> </li> </ol> </div> <div class="paragraph"> <p>Ces trois articles n’ont <strong>aucun</strong> xref entre eux. Leurs tags ne se recoupent qu’à 20% (« ollama », « llm » communs). Mais un NLP léger sur les descriptions révèle un cluster évident : « coût », « abonnement », « cloud », « GPU », « API key », « Ollama Pro », « efficacité », « ratio ».</p> </div> <div class="paragraph"> <p>Ils forment un cluster ontologique : <strong>l’économie du LLM self-hosted vs cloud</strong>. Ce cluster n’est déclaré nulle part. Il émerge du corpus.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/cluster-ontologique-exemple.svg" alt="cluster ontologique exemple" width="1738" height="5456"> </div> </div> <div class="paragraph"> <p>Ce cluster ontologique devient un edge composite dans <code>graph.json</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "source": "0119-benchmark-dgx-spark", "target": "cluster:economie-llm", "type": "entity_cluster", "weight": 0.73, "metadata": { "clusterLabel": "Économie LLM Self-Hosted vs Cloud", "commonEntities": ["coût", "GPU", "abonnement", "Ollama Pro", "ratio"], "articlesInCluster": [ "0119-benchmark-dgx-spark", "0121-ollama-pro-deux-instances", "0122-ratio-efficacite-flotte-experts" ] } }</code></pre> </div> </div> <div class="paragraph"> <p>Le NLP est volontairement léger — TF-IDF + cosine similarity sur les descriptions. Pas besoin de BERT, pas besoin de modèle de langage. Le corpus fait 23 articles, la matrice de similarité tient dans un fichier JSON de 50 Ko.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>La puissance du NLP ne vient pas de la sophistication de l’algorithme, mais de la <strong>taille du corpus</strong> et de la <strong>qualité des descriptions</strong>. Une <code>:jbake-description:</code> bien écrite de 150 caractères contient plus de signal pour TF-IDF qu’un article entier de 3000 mots.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_le_contrat_dag_qui_importe_qui">Le Contrat DAG : Qui Importe Qui</h2> <div class="sectionbody"> <div class="paragraph"> <p>C’est le point où la discipline architecturale paie. Le DAG N0→N3 défini dans <code>engine/build.gradle.kts</code> donne une règle simple : aucun projet n’importe un projet de niveau supérieur.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 18.1818%;"> <col style="width: 27.2728%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Plugin consommateur</th> <th class="tableblock halign-left valign-top">Plugin importé</th> <th class="tableblock halign-left valign-top">Niveau consommateur</th> <th class="tableblock halign-left valign-top">Niveau importé</th> <th class="tableblock halign-left valign-top">Valide ?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N2 > N0 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">bakery-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ N3 > N2 — OK</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">graphify-gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Technique OK, mais <strong>conceptuellement faux</strong> — la collaboration est interne à bakery</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Engine applique bakery. Bakery applique graphify. C’est tout. Si un jour je veux ajouter le vector store codebase (N1) pour de la recherche sémantique cross-corpus, bakery l’importe aussi. Engine ne change pas.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Le pattern est : <strong>le plugin N2 est le hub de ses propres dépendances</strong>. Engine N3 n’est pas un hub — c’est un terminal qui applique des hubs.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_ce_quon_gagne_et_ce_quon_ne_gagne_pas">Ce Qu’on Gagne (Et Ce Qu’on Ne Gagne Pas)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le gain principal est éditorial, pas technique :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Avant</th> <th class="tableblock halign-left valign-top">Après</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Articles connexes = 4 derniers posts</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Articles connexes = top 4 par poids dans le Knowledge Graph</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Lecteur lit du RAG → recommandation Kitty Terminal</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lecteur lit du RAG → recommandation pgvector, chunking, vector store</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zéro transparence sur le pourquoi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Badge <code>xref 0122</code>, <code>tag:gradle</code>, <code>cluster:rag</code> visible</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake standard, zéro effort, zéro valeur</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pipeline Gradle déterministe, reproductible, testable</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucune courbe d’apprentissage pour le lecteur</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le lecteur découvre la <strong>topologie</strong> de mon contenu</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Ce qu’on <strong>ne</strong> gagne pas :</p> </div> <div class="ulist"> <ul> <li> <p>Ce n’est pas un « vrai » moteur de recommandation (pas de collaborative</p> </li> </ul> </div> <div class="paragraph"> <p>filtering, pas d’A/B testing, pas de feedback loop)</p> </div> <div class="ulist"> <ul> <li> <p>La qualité dépend de la richesse des métadonnées JBake — si vos</p> </li> </ul> </div> <div class="paragraph"> <p>descriptions sont vides, TF-IDF ne voit rien</p> </div> <div class="ulist"> <ul> <li> <p>Le NLP est offline — les nouveaux articles ne sont clusterisés qu’au</p> </li> </ul> </div> <div class="paragraph"> <p>prochain scan (c’est bien : le build reste déterministe)</p> </div> </div> </div> <div class="sect1"> <h2 id="_perspectives_le_blog_comme_knowledge_graph_public">Perspectives : Le Blog Comme Knowledge Graph Public</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cette fonctionnalité ouvre une perspective plus large : et si <code>cheroliv.com</code> devenait lui-même un <strong>knowledge graph navigable</strong> ?</p> </div> <div class="paragraph"> <p>Les articles sont des nœuds. Les tags sont des communautés. Les xref sont des arêtes. Le lecteur ne lit plus un article isolé — il navigue dans un <strong>graphe de connaissance</strong> dont l’article courant est le point d’entrée.</p> </div> <div class="paragraph"> <p>Imaginez une page d’accueil qui affiche non pas la liste chronologique des derniers posts, mais une <strong>carte du corpus</strong> : clusters ontologiques, articles pivots (ceux avec le plus d’arêtes), chemins de lecture recommandés (« Si vous avez aimé l’article sur Graphify, lisez ensuite celui sur le Knowledge Graph comme outil de compréhension »).</p> </div> <div class="paragraph"> <p>Ce n’est plus un blog. C’est un <strong>atlas sémantique</strong>.</p> </div> <div class="paragraph"> <p>Et ce n’est pas de la science-fiction. Le <code>graph.json</code> existe déjà. Il ne lui manque que l’interface de navigation.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_le_système_de_fichiers_sait_ce_que_le_template_ignore">Conclusion : Le Système de Fichiers Sait Ce Que le Template Ignore</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce que j’ai conçu ce mardi soir, c’est le remplacement d’une heuristique paresseuse (l’ordre chronologique) par une représentation fidèle de la structure de mon corpus (le Knowledge Graph).</p> </div> <div class="paragraph"> <p>Le template <code>post.thyme</code> ne change pas. Ce qui change, c’est ce qu’on lui donne à manger. Avant : une liste Java ordonnée par <code>date</code>. Après : un graphe pondéré issu de trois couches d’analyse — xrefs, co-occurrences de tags, et ontologie émergente par NLP.</p> </div> <div class="paragraph"> <p>La boucle est bouclée. graphify scanne le workspace. Bakery lit le graphe et nourrit le template. Le lecteur voit des recommandations pertinentes. Et engine — le chef d’orchestre — ne sait même pas que tout ça existe.</p> </div> <div class="paragraph"> <p>C’est ça, la bonne architecture. Chaque plugin fait une chose. Et le terminal consommateur n’a pas besoin de savoir comment.</p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0105_integrer_graphify_workflow_gradle_post.html">Article 0105 — Intégrer Graphify dans un workflow Gradle</a></p> </li> <li> <p><a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Article 0106 — Le Knowledge Graph comme outil de compréhension</a></p> </li> <li> <p><a href="0117_granularisation_oss_css_repositorie_workspace_post.html">Article 0117 — La Granularisation OSS/CSS</a></p> </li> <li> <p><a href="0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html">Article 0121 — Plugin Gradle Piloter Deux Instances Ollama Pro</a></p> </li> <li> <p><a href="0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html">Article 0122 — 27× à 45× plus efficace : flotte d’experts IA</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html Mon, 11 May 2026 00:00:00 +0000 blog/2026/0122_ratio_efficacite_27x_45x_flotte_experts_ia_vs_claude_gpt_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_problème_pourquoi_le_fine_tune_et_pas_le_rag">Le problème : pourquoi le fine-tune et pas le RAG ?</a></li> <li><a href="#_lidée_une_flotte_dexperts_pas_un_seul_modèle">L’idée : une flotte d’experts, pas un seul modèle</a></li> <li><a href="#_la_codebase_sous_la_loupe_7_900_fichiers_144_000_lignes">La codebase sous la loupe : 7 900 fichiers, 144 000 lignes</a></li> <li><a href="#_linférence_23_modèles_sur_ollama_cloud_à_partir_de_17mois">L’inférence : 23 modèles sur Ollama Cloud à partir de 17€/mois</a> <ul class="sectlevel2"> <li><a href="#_on_démarre_à_17mois_on_scale_si_besoin">On démarre à 17€/mois, on scale si besoin</a></li> <li><a href="#_le_routing_en_pratique">Le routing en pratique</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 22 minutes</div> <p>Quand on utilise un LLM pour du développement logiciel au quotidien, on finit toujours par butter sur le même mur : le modèle ne connaît pas <strong>votre</strong> codebase. Il ne sait pas que vous utilisez tel pattern de <a href="https://fr.wikipedia.org/wiki/Graphe_orient%C3%A9_acyclique">DAG</a>, telle convention Gradle, telle stratification épistémique dans vos <a href="https://fr.wikipedia.org/wiki/AsciiDoc"><code>.adoc</code></a>. Alors on lui injecte du contexte, on répète, on corrige, on itère. Et le temps — et l’argent — passent.</p> </div> <div class="paragraph"> <p>J’ai donc posé la question brutalement : combien coûterait une équipe de modèles fine-tunés sur mon workspace, capables de cracher du code <strong>dans mon style</strong> sans avoir besoin qu’on leur explique à chaque fois ? Et surtout : comment cette approche se compare-t-elle aux solutions propriétaires classiques — Claude, GPT, Gemini, Grok ?</p> </div> <div class="paragraph"> <p>La réponse m’a surpris. Beaucoup moins que ce que j’imaginais. Et le rapport coût/efficacité face aux géants du secteur est indécent. Voici le détail complet.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_problème_pourquoi_le_fine_tune_et_pas_le_rag">Le problème : pourquoi le fine-tune et pas le RAG ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le RAG, c’est bien. <a href="0106_knowledge_graph_outil_comprehension_codebase_post.html">Mon knowledge graph</a> et <a href="0116_compartimentage_epistemique_automatise_llm_post.html">mon compartimentage épistémique</a> fonctionnent. Mais le RAG a un défaut fondamental : à chaque requête, tu dois réinjecter le contexte pertinent. Ton prompt s’allonge, ta latence explose, et le modèle n'<strong>intériorise</strong> jamais tes patterns — il les lit à chaque fois comme un document externe.</p> </div> <div class="paragraph"> <p>Le fine-tune, lui, c’est la mémoire musculaire. Le modèle <strong>sait</strong> que tu écris <code>build.gradle.kts</code> avec des tâches enregistrées via <code>tasks.register</code>, que tes <code>AGENTS.adoc</code> suivent une syntaxe standardisée, que ton workspace est structuré en boroughs. Il n’a pas besoin qu’on lui rappelle.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Le fine-tune n’est pas un remplacement du RAG. C’est une couche complémentaire. Le RAG reste pertinent pour les données qui changent souvent (logs, tickets, commits récents). Le fine-tune est pour la connaissance <strong>structurelle</strong> et <strong>stylistique</strong> de long terme.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_lidée_une_flotte_dexperts_pas_un_seul_modèle">L’idée : une flotte d’experts, pas un seul modèle</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un seul modèle fine-tuné sur tout mon workspace, c’est déjà bien. Mais c’est sous-optimal. Mon workspace couvre des domaines très différents :</p> </div> <div class="ulist"> <ul> <li> <p>Gradle plugins (Kotlin, convention plugins, composite builds)</p> </li> <li> <p>Moteur DAG (Kotlin, planification, exécution)</p> </li> <li> <p>Agents LLM (Python, LangChain4j, RAG)</p> </li> <li> <p>Documentation architecturale (AsciiDoc, gouvernance)</p> </li> <li> <p>Infra/DevOps (Docker, GitHub Actions, CI/CD)</p> </li> </ul> </div> <div class="paragraph"> <p>Un modèle unique devrait être bon partout, excellent nulle part. La solution ? Une <strong>flotte de modèles spécialisés</strong>, avec un orkestrateur qui route chaque requête vers le bon expert.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/fleet-architecture.svg" alt="fleet architecture" width="871" height="462"> </div> </div> <div class="paragraph"> <p>La flotte totale : <strong>1 orkestrateur + 22 experts = 23 modèles</strong>. Et le coût d’inférence mensuel ? <strong>17€/mois</strong> en abonnement Ollama Pro annual — extensible par cumul de comptes si les quotas sont dépassés, comme démontré dans <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">ma méthode Docker multi-comptes</a>. On part de 17€, on ajoute 20€ par palier selon le besoin réel. Pas de gaspillage.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_codebase_sous_la_loupe_7_900_fichiers_144_000_lignes">La codebase sous la loupe : 7 900 fichiers, 144 000 lignes</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant d’estimer le coût du training, il faut savoir quoi entraîner. J’ai audité mon workspace en excluant rigoureusement tout ce qui est ignoré par Git :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- build/ out/ node_modules/ runtimes/ .gradle/ dist/ target/ venv/ __pycache__/ .cache/ .tox/ ---- Voici le résultat pour les fichiers trackés uniquement : [cols="2,2"] |=== |Métrique |Valeur |Fichiers source trackés |**7 896** |Lignes de code (LOC) |**143 805** |Repositories Git |**26** |Principaux langages |Kotlin (1 903), AsciiDoc (2 765), Python (5 029) |=== [IMPORTANT] ==== Ces 5 000+ fichiers Python incluent les `runtimes/` des notebooks et scripts utilitaires. Le cœur applicatif (plugins Gradle, moteur DAG, agents) est principalement en Kotlin et AsciiDoc. ==== À partir de cette masse, j'estime pouvoir générer un dataset synthétique de **~170 millions de tokens** via un LLM instructeur (distillation de la codebase en paires instruction/réponse). === Détail du dataset par type d'expert [source,text] ---- Dataset maître (généraliste V4-Flash) : 50M tokens Expert Gradle/Build : 15M tokens Expert Kotlin/DAG : 15M tokens Expert AsciiDoc/Gouvernance: 15M tokens Expert Agent/LLM/Python : 15M tokens Expert Infra/CI-CD : 15M tokens Micro-experts Qwen/Gemma : ~5M tokens chacun ---- == Le choix des modèles : 100% MoE, zéro dense C'est là que l'architecture devient vraiment efficiente. Un modèle *dense* active tous ses poids à chaque token. Un modèle *MoE* (Mixture of Experts) n'active qu'une fraction de ses paramètres. Le coût d'inférence — et de fine-tuning — est proportionnel aux paramètres **activés**, pas aux paramètres **stockés**. Regardons ce que le marché propose en MoE aujourd'hui sur Ollama Cloud : [cols="3,2,2,1,3"] |=== |Modèle |Total params |Activés |Activation |Ollama Cloud |DeepSeek V4-Pro |1.6T |49B |3.1% |✅ natif |DeepSeek V4-Flash |292B |13B |4.5% |✅ natif |Gemma 4 26B-A4B |26B |3.8B |14.6% |✅ natif |Qwen3.6-35B-A3B |35B |3B |8.6% |❌ (pas encore intégré) |Qwen3.5-35B-A3B |35B |3B |8.6% |✅ natif |❌ Qwen3.5-27B |27B |27B |100% dense |éliminé |❌ Qwen3.5-4B/9B |4B/9B |4B/9B |100% dense |éliminé |❌ Gemma 4 31B |31B |31B |100% dense |éliminé |🧪 Gemma 4 E2B/E4B |5B/8B |5B/8B |100% dense |validation pipeline |=== [CAUTION] ==== Le ratio d'activation est le critère discriminant. Un Gemma 4 26B-A4B n'active que 3.8B de ses 26B de paramètres — c'est 7× moins qu'un dense 27B, pour des performances de coding agent comparables (77.1% vs 80% sur LiveCodeBench v6). ==== === Pourquoi j'abandonne les modèles denses L'exception : les Gemma 4 E2B et E4B. Ces deux modèles, sous Apache 2.0, sont parfaits pour tester et valider un pipeline de training à moindre coût. Un run de 2-3h sur un E2B coûte moins de $5 — si le dataset ou les hyperparamètres sont foireux, on le sait pour une poignée de dollars. Une fois le pipeline rodé, ils peuvent même servir pour les ultra-micro-tâches (reformatage trivial, classification binaire). Mais pour les experts de la flotte principale, je reste sur du MoE. Voici pourquoi : .Mais pas que : les Gemma 4 E2B/E4B, experts de l'anonymisation fine [NOTE] ==== Google a conçu ces petits modèles comme compétitifs en tool calling natif — ils savent appeler des fonctions, manipuler des regex, chercher des motifs. Une fois fine-tunés sur des exemples d'anonymisation (emails, tokens, UUIDs, chemins de fichiers), ils deviennent des **anonymiseurs de dataset** ultra-rapides. On leur file un bloc de texte brut, ils appellent `sed`/`regex` via un tool call et retournent le bloc nettoyé. Le coût d'inférence est dérisoire : 5B activés, ça tient sur une seule GPU d'entrée de gamme. Ces modèles ne sont pas des experts métier — ce sont des **ouvriers spécialisés** dans la chaîne de production du dataset. ==== * Sa VRAM d'entraînement (même en QLoRA) est proportionnelle aux **27B totaux** * Son temps de training est proportionnel aux **27B activés** Comparons avec un Qwen3.6-35B-A3B (MoE) : [cols="3,2,2,2"] |=== | |Qwen3.5-27B (dense) |Qwen3.6-35B-A3B (MoE) |Ratio |VRAM QLoRA |~55 GB |~35 GB |1.6× |GPU-heures (8M tok) |~12h |~4h |**3×** |Coût par fine-tune |~$24 |~$8 |**3×** |SWE-bench Verified |75.0% |73.4% |comparable |=== Le MoE coûte 3× moins à entraîner pour des performances agent-coding à 5% près. Sur 22 experts, l'écart se chiffre en milliers d'euros. == Estimation du training : 811 H100-heures J'ai ventilé le coût de training modèle par modèle, en QLoRA 4-bit, avec les datasets décrits plus haut. === Micro-experts MoE légers (3-3.8B activés) Ces modèles nécessitent 1 H100 (80 GB) par run. La VRAM du modèle en Q4 est d'environ 13-18 GB, laissant large pour les états d'optimiseur LoRA et les activations. [cols="4,2,3,2"] |=== |Modèle |Nb de runs |GPU-h/run |Total GPU-h |Gemma 4 26B-A4B-FT |6 |3.5 h |**21 h** |Qwen3.6-35B-A3B-FT |5 |4.0 h |**20 h** |Qwen3.5-35B-A3B-FT |5 |4.0 h |**20 h** |*Sous-total micro* | | |*61 h* |=== === Exécutifs V4-Flash (13B activés / 292B stockés) Le DeepSeek V4-Flash est un cas particulier. Même si seuls 13B sont activés par token, le modèle complet en Q4 pèse ~142 GB — tous les experts doivent être en VRAM pendant le training. Il faut donc **3× H100** par run pour être confortable. [cols="4,2,3,3,2"] |=== |Modèle |Dataset |GPUs |Heures |Total GPU-h |V4-Flash-Base généraliste |50M tok |3× H100 |50 h |**150 h** |V4-Flash expert ×5 |15M tok |3× H100 |40 h |**600 h** |*Sous-total exécutifs* | | | |*750 h* |=== [cols="3,2,1"] |=== |**TOTAL** | |**811 H100-h** |=== [NOTE] ==== À titre de comparaison, un full fine-tune du V4-Flash (sans QLoRA, tous les poids) coûterait ~4 000 H100-h rien que pour les 6 modèles. Le QLoRA divise le coût par 5. C'est le seul moyen de rendre le projet économiquement viable à cette échelle. ==== === Tarifs GPU : qui loue quoi en mai 2026 J'ai benchmarké les principaux loueurs de H100. Le prix au compteur, pour 811 heures. [cols="3,2,2,2"] |=== |Loueur |$/H100·h |Total 811h |Fiabilité |**Vast.ai spot** |$1.60 |**$1 298** |★★☆ interruptible |**Crusoe Cloud** |$2.00 |**$1 622** |★★★★ datacenter fiable |FluidStack |$1.98 |$1 606 |★★★ |TensorDock |$1.80 |$1 460 |★★☆ |RunPod |$2.29 |$1 857 |★★★ bon compromis |CoreWeave |$2.25 |$1 825 |★★★★ entreprise |Lambda Labs |$2.49 |$2 019 |★★★★ premium |=== [TIP] ==== Vast.ai spot est le moins cher mais tes runs peuvent être interrompus à tout moment. Pour du training, c'est risqué. Crusoe à $2.00/h est le meilleur rapport fiabilité/prix. Le surcoût de $324 vs Vast vaut la tranquillité d'esprit. ==== === Wall-clock : combien de temps pour tout entraîner ? Avec un seul nœud 3× H100, les 31 runs (1 généraliste + 30 experts) prennent environ **12 jours** en séquentiel. Si tu loues 2 nœuds en parallèle, ça tombe à **6 jours**. En pratique, les micro-experts peuvent tourner sur des nœuds séparés (1 H100 chacun) pendant que les V4-Flash occupent le nœud 3× H100. Avec une planification intelligente :</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>Nœud A (3× H100) : V4-Flash généraliste → V4-Flash experts ×5 (11 jours) Nœud B (1× H100) : Gemma 4 26B ×6 → Qwen 36 ×5 → Qwen 35 ×5 (6 jours)</pre> </div> </div> <div class="paragraph"> <p>7 jours de location, tout plié.</p> </div> </div> </div> <div class="sect1"> <h2 id="_linférence_23_modèles_sur_ollama_cloud_à_partir_de_17mois">L’inférence : 23 modèles sur Ollama Cloud à partir de 17€/mois</h2> <div class="sectionbody"> <div class="paragraph"> <p>C’est la partie la plus élégante de l’architecture.</p> </div> <div class="paragraph"> <p>Ollama Cloud permet d’uploader des modèles privés (fonctionnalité du plan Pro). Mes 22 modèles fine-tunés sont poussés en <code>.gguf</code> sur mon espace Ollama, marqués comme privés, et accessibles via l’API standard.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/inference-flow.svg" alt="inference flow" width="918" height="524"> </div> </div> <div class="sect2"> <h3 id="_on_démarre_à_17mois_on_scale_si_besoin">On démarre à 17€/mois, on scale si besoin</h3> <div class="paragraph"> <p>Le plan Pro Ollama (17€/mois en annuel) autorise 3 modèles cloud concurrents. Dans cette architecture, je n’ai jamais besoin de plus de 2-3 experts simultanément :</p> </div> <div class="ulist"> <ul> <li> <p>La phase de classification (V4-Pro) occupe 1 slot, quelques secondes</p> </li> <li> <p>L’expert ciblé occupe 1 slot, le temps de générer sa réponse</p> </li> <li> <p>Le 3ème slot reste en réserve pour les tâches parallèles</p> </li> </ul> </div> <div class="paragraph"> <p>Si l’usage augmente, j’ajoute des comptes Pro supplémentaires via la méthode Docker décrite dans <a href="0120_cumuler_deux_abonnements_ollama_pro_docker_post.html">mon article sur le cumul d’abonnements</a>. Pas de plan Max à 100€/mois — je n’ajoute que ce dont j’ai réellement besoin.</p> </div> <div class="paragraph"> <p>Le seul facteur limitant est le <strong>quota GPU-time</strong> mensuel d’Ollama (50× le plan gratuit pour Pro). Pour mon usage de quelques centaines de requêtes par jour, c’est amplement suffisant.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Le coût marginal d’un appel à V4-Pro (49B activés) vs Gemma 4 26B-A4B (3.8B activés) est le <strong>même pour moi : zéro</strong>. C’est le forfait Ollama qui absorbe la différence de compute. Mon seul indicateur est la latence.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_le_routing_en_pratique">Le routing en pratique</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- Volume de requêtes estimé : ~500/jour ├─ 50% → Gemma 4 26B-A4B-FT (micro, 3.8B actifs) │ Formatage AsciiDoc, scripts simples, conventions nommage │ ├─ 25% → V4-Flash-FT (exécutif, 13B actifs) │ Plugins Gradle, refactoring Kotlin, génération DAG │ ├─ 15% → Qwen 35B MoE-FT (micro, 3B actifs) │ Tâches intermédiaires, review de code, documentation │ └─ 10% → V4-Pro (orkestrateur, 49B actifs) Décisions architecturales, refactoring transverse, problèmes vraiment nouveaux ---- La masse du trafic passe par les petits. Le gros modèle n'intervient qu'en dernier recours. == La comparaison qui fait mal : Claude, GPT, Gemini, Grok vs ma flotte C'est ici que l'écart devient vertigineux. Regardons ce que coûterait le même volume de travail (500 requêtes/jour, ~300 tokens input + 2 000 tokens output en moyenne) avec les solutions propriétaires du marché en mai 2026. === Anthropic — Claude (tarifs mai 2026) Anthropic a récemment *baissé* ses prix. La pression des solutions open-weight comme DeepSeek et Qwen se fait sentir. [cols="3,2,2,2,2"] |=== |Modèle |Input $/MTok |Output $/MTok |Coût/jour |**Coût/mois** |Opus 4.7 (le + intelligent) |$5 |$25 |$25.75 |**$772** |Sonnet 4.6 (équilibré) |$3 |$15 |$15.45 |**$463** |Haiku 4.5 (le + rapide) |$1 |$5 |$5.15 |**$154** |=== [CAUTION] ==== Ces tarifs sont *après* la dernière baisse de prix d'Anthropic (mai 2026). Avant cela, Opus était à $15/$75 par MTok. La peur de l'open-weight est réelle. ==== Même le modèle le moins cher de Claude — Haiku 4.5 à **154€/mois** — coûte 9× plus que mon abonnement Ollama Pro à 17€. Et Haiku ne connaît pas ma codebase, ne génère pas dans mon style, et nécessite du prompt engineering systématique. Le plus intelligent — Opus 4.7 — explose le budget à **772€/mois** pour un volume modeste de 500 requêtes par jour. Soit **45× plus cher** que ma solution. === OpenAI — GPT (tarifs mai 2026) [cols="3,2,2,2,2"] |=== |Modèle |Input $/MTok |Output $/MTok |Coût/jour |**Coût/mois** |GPT 5.5 (le + intelligent) |$5 |$30 |$30.90 |**$927** |GPT 5.4 (standard) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 Mini |$0.75 |$4.50 |$4.64 |**$139** |=== Même le modèle « économique » d'OpenAI — GPT 5.4 Mini à 139€/mois — coûte 8× mon abonnement, pour un modèle qui ne sait *rien* de mes conventions et nécessite du prompt engineering lourd. GPT 5.5, leur flagship : **927€/mois**. Pour du *zero-shot* sur ma codebase. Avec 2-3 itérations par tâche à cause du style non maîtrisé, le vrai coût mensuel double facilement. === Google — Gemini (tarifs mai 2026) [cols="3,2,2,2,2"] |=== |Modèle |Input $/MTok |Output $/MTok |Coût/jour |**Coût/mois** |Gemini 3.1 Pro (High) |$3.50 |$17.50 |$18.00 |**$540** |Gemini 3.1 Pro |$2 |$10 |$10.30 |**$309** |Gemini 3 Flash |$0.30 |$1.50 |$1.54 |**$46** |=== Gemini 3 Flash à 46€/mois est compétitif en prix pur — mais sans fine-tune, il génère du code « générique ». Pas du code *Cheroliv*. === Grok — xAI (tarifs mai 2026) [cols="3,2,2,2,2"] |=== |Modèle |Input $/MTok |Output $/MTok |Coût/jour |**Coût/mois** |Grok 4 |$4 |$16 |$16.48 |**$494** |Grok 4 Mini |$0.80 |$3.20 |$3.30 |**$99** |=== === Microsoft — Azure OpenAI (tarifs mai 2026) Azure applique les mêmes prix que l'API OpenAI directe, mais facture en plus l'infrastructure et le réseau. Il faut compter un surcoût de 10-20% pour le service managé. [cols="3,2,2,2,2"] |=== |Modèle |Input $/MTok |Output $/MTok |Coût/jour |**Coût/mois** |GPT 5.4 (Azure, Global) |$2.50 |$15 |$15.45 |**$463** |GPT 5.4 + infrastructure |surcoût 15% |surcoût 15% |$17.77 |**$533** |=== [NOTE] ==== Les tarifs ci-dessus concernent l'API, pas les abonnements « chat » (Claude Pro à $20/mois, ChatGPT Plus à $20/mois). On compare ici l'usage *développeur*, celui où tu enchaînes des centaines de requêtes par jour via API pour générer, refactorer, documenter. Les abonnements grand public ont des quotas qui explosent bien avant 500 requêtes/jour. ==== === Le tableau comparatif final [cols="3,2,2,2,2,2"] |=== |Solution |Connaissance codebase |Style intégré |Coût/mois |Itérations |**Coût effectif** |**Ma flotte (Ollama Pro)** |✅ Fine-tunée |✅ Dans les poids |**17€** |0-1 |**17€** |Claude Opus 4.7 |❌ Zero-shot |❌ Prompt nécessaire |$772 |2-3 |$1 500-2 300 |Claude Haiku 4.5 |❌ Zero-shot |❌ Prompt nécessaire |$154 |3-4 |$460-615 |GPT 5.5 |❌ Zero-shot |❌ Prompt nécessaire |$927 |2-3 |$1 854-2 781 |GPT 5.4 |❌ Zero-shot |❌ Prompt nécessaire |$463 |2-3 |$925-1 390 |GPT 5.4 Mini |❌ Zero-shot |❌ Prompt nécessaire |$139 |3-5 |$417-695 |Gemini 3.1 Pro High |❌ Zero-shot |❌ Prompt nécessaire |$540 |2-3 |$1 080-1 620 |Grok 4 |❌ Zero-shot |❌ Prompt nécessaire |$494 |2-3 |$988-1 482 |**Azure GPT 5.4** |❌ Zero-shot |❌ Prompt nécessaire |$533 |2-3 |$1 066-1 600 |=== [plantuml, cost-comparison, svg] ---- @startuml skinparam backgroundColor #FAFAFA title Rapport coût/efficacité — ma flotte vs le marché (mai 2026) rectangle "17€/mois" as OURS #4ECDC4 rectangle "Opus 4.7\n772€" as OPUS #FF6B6B rectangle "Sonnet 4.6\n463€" as SONNET #FF8B94 rectangle "GPT 5.5\n927€" as GPT #FFD93D rectangle "Gemini 3.1 Pro\n540€" as GEMINI #6C5CE7 rectangle "Grok 4\n494€" as GROK #A8E6CF rectangle "Haiku 4.5\n154€" as HAIKU #DFE6E9 rectangle "GPT 5.4 Mini\n139€" as MINI #B2BEC3 note bottom of OURS Avec fine-tune intégré. Zéro prompt engineering. 90%+ first-shot correct. end note @enduml ---- 17€/mois pour 23 experts IA fine-tunés. Le flagship Claude Opus 4.7 coûte **45× plus cher** pour une qualité inférieure sur *mon* codebase. GPT 5.5 coûte **54× plus cher**. Même le modèle le moins cher du marché (Gemini Flash à 46€) coûte **2.7× plus** sans la connaissance de mon workspace. Le verdict est sans appel : le fine-tune sur architectures MoE, en 2026, n'est pas juste « moins cher ». C'est un facteur d'efficacité de **27× à 54×** sur le rapport coût/qualité face aux solutions propriétaires. Anthropic, OpenAI, Google — tous le savent, et c'est pour ça qu'ils baissent leurs prix en panique. == Le facteur d'efficacité : 5-8× vs utiliser V4-Pro seul Comparons les deux extrêmes. === Scénario A : V4-Pro seul pour tout [cols="3,2"] |=== |Métrique |Valeur |Connaissance de la codebase |0 (zero-shot) |Convention naming |40-60% first-shot correct |Prompt engineering nécessaire |Oui, systématique |Itérations par tâche |2-3 |Coût inférence |$100/mois (Ollama Max) |Latence moyenne |~20 tok/s + réseau |=== === Scénario B : Flotte MoE orchestrée [cols="3,2"] |=== |Métrique |Valeur |Connaissance de la codebase |Intégrée (fine-tune) |Convention naming |90-95% first-shot correct |Prompt engineering |Non (le style est dans les poids) |Itérations par tâche |0-1 |Coût inférence |$60/mois (3× Ollama Pro) |Latence moyenne |~50 tok/s (modèles légers) |=== [cols="4,2,2,2"] |=== |Dimension |V4-Pro seul |Flotte MoE |Facteur |Coût mensuel cloud |$100 |**$60** |1.7× |Contexte à injecter |Élevé (prompt) |**Zéro** |∞ |Itérations moyennes |2-3 |**0-1** |2-3× |Latence ressentie |20 tok/s |50 tok/s |**2.5×** |First-shot correct |50% |90%+ |**1.8×** |=== **Facteur d'efficacité global : 5-8×** — en productivité développeur ressentie. [NOTE] ==== Le facteur ne se mesure pas en tokens ou en dollars. Il se mesure en « combien de temps je passe à expliquer au modèle ce qu'il devrait déjà savoir ». Avec les modèles fine-tunés, ce temps tend vers zéro. ==== == Le budget complet : un investissement one-shot, un forfait ridicule [cols="3,2"] |=== |Poste |Montant |Training GPU (811 H100-h, Crusoe $2/h) |**$1 622** |Génération dataset synthétique (API LLM) |**$400** |Inference (Ollama Pro annuel, $17/mois) |**$204** |**Total première année** |**$2 226** |**Mensuel équivalent** |**$186** |**Coût par requête estimé** |< $0.01 |=== [plantuml, budget-breakdown, svg] ---- @startuml skinparam backgroundColor #FAFAFA rectangle "Budget Année 1 : $2 226" as Total #E8E8E8 { rectangle "Training GPU\n$1 622 (73%)" as Train #FF6B6B rectangle "Dataset\ndistillation\n$400 (18%)" as Data #FFE66D rectangle "Ollama Pro\n$204 (9%)" as Cloud #4ECDC4 } note bottom of Total $186/mois équivalent année 1. Dès l'an 2 : $17/mois. Amorti par ~$235 de CA mensuel avec marge 95%. end note @enduml ---- $186/mois la première année, **$17/mois** dès l'an 2. Le prix d'un abonnement Netflix premium, pour une équipe de 23 experts IA disponibles 24/7, qui écrivent du code *dans mon style* sans que j'aie besoin de leur expliquer mes conventions. === Le calcul de rentabilité Avec edster.cloud et sa marge de ~95%, le point mort est à **~$2 340 de CA supplémentaire** sur l'année. En pratique : * 1 mission de pilotage software → $3 000-5 000 → investissement couvert + profit * 1 formation corporate → $5 000-10 000 → confortable * L'upsell implicite : "mon équipe d'IA maîtrise ma forge logicielle" → différenciant commercial À partir de l'an 2, le training n'est plus à payer (sauf mise à jour du dataset). Le coût annuel tombe à **$204** ($17/mois). Le ratio coût/valeur est celui d'une licorne : quasi nul. == Les limites de l'exercice Ceci reste une *estimation au doigt mouillé*. Plusieurs variables peuvent faire varier le budget : [cols="2,3"] |=== |Variable |Impact |Génération du dataset synthétique |Si l'API de distillation merde (hallucinations, paires mal formées), il faut du temps humain pour curater. Coût caché. |Quotas GPU-time Ollama |Si l'usage dépasse les quotas du plan Pro, il faudra monter en gamme ou basculer sur du GPU dédié. |Qualité effective des fine-tunes |Un fine-tune raté → à refaire. Le vrai risque c'est les hyperparamètres, pas la location GPU. |Évolution rapide des modèles |Les Qwen3.6/Gemma 4 sont sortis il y a < 1 mois. Dans 6 mois, la génération suivante sera meilleure ET moins chère à fine-tuner. |=== [WARNING] ==== Ne lancez pas 811 heures de training sans avoir d'abord testé le pipeline sur *un seul* micro-modèle. Un run de 3-4h sur un Qwen 35B-A3B coûte $8. Si le dataset est pourri, vous le saurez pour $8, pas pour $1 622. ==== == Conclusion : le fine-tune est devenu un luxe accessible Il y a un an, fine-tuner un modèle de 292B paramètres (même en QLoRA) relevait de la recherche. Aujourd'hui, en mai 2026, c'est un projet faisable pour un développeur indépendant : * **811 H100-heures** de training — $1 622 chez Crusoe * **23 modèles spécialisés** chargés sur Ollama Cloud — **$17/mois** * **0 serveur, 0 GPU local, 0 maintenance infra** La démocratisation est venue de trois facteurs convergents : 1. **Les architectures MoE** — qui permettent de fine-tuner efficacement des modèles dont seule une fraction des poids est activée 2. **Les plans fixes d'Ollama Cloud** — qui transforment un coût variable (per-token) en coût fixe (abonnement) 3. **Les modèles open-weight de qualité** — DeepSeek V4, Qwen3.6, Gemma 4 sont sous licences MIT/Apache 2.0 "Civilisation advances by extending the number of important operations which we can perform without thinking about them." Le fine-tune, c'est exactement ça : une opération que tu délègues à la machine pour ne plus avoir à y penser. Et en 2026, ça coûte moins cher qu'un développeur junior mensualisé. --- _Article publié le {jbake-date}_ == Modèles fine-tunés de la flotte [cols="2,2,2,2,3"] |=== |Taille activée |Nombre |Modèle de base |Domaine |Dataset |13B |1 |DeepSeek-V4-Flash-Base |Workspace général |50M tokens |13B |5 |DeepSeek-V4-Flash |Gradle, Kotlin, DAG, Doc, Infra |15M tokens |3.8B |6 |Gemma 4 26B-A4B |Micro-tâches, formatage, scripts |5M tokens |3B |5 |Qwen3.6-35B-A3B |Refactoring, review, doc intermédiaire |5M tokens |3B |5 |Qwen3.5-35B-A3B |Tâches legacy, compatibilité |5M tokens |=== == Ressources === Modèles open-weight sur HuggingFace * https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-Base[DeepSeek V4-Flash-Base — 292B params, license MIT] * https://huggingface.co/Qwen/Qwen3.6-35B-A3B[Qwen3.6-35B-A3B — 35B/3B activés, license Apache 2.0] * https://huggingface.co/Qwen/Qwen3.5-35B-A3B[Qwen3.5-35B-A3B — 35B/3B activés, license Apache 2.0] * https://huggingface.co/google/gemma-4-26B-A4B-it[Gemma 4 26B-A4B — 26B/3.8B activés, license Apache 2.0] === Sources des tarifs (mai 2026) * https://ollama.com/pricing[Tarifs Ollama Cloud — plan Pro $17/mois annuel] * https://www.anthropic.com/pricing[Tarifs Anthropic — Claude API (Opus 4.7 $5/$25, Sonnet 4.6 $3/$15, Haiku 4.5 $1/$5)] * https://openai.com/api/pricing/[Tarifs OpenAI — GPT API (GPT 5.5 $5/$30, GPT 5.4 $2.50/$15)] * https://deepinfra.com/pricing[Tarifs DeepInfra — GPU instances H100 $1.79/h, B200 $2.79/h] * Vast.ai, Crusoe Cloud, FluidStack, TensorDock, RunPod, CoreWeave, Lambda Labs — relevés de prix manuels, datés de mai 2026 === Annonces officielles * https://qwen.ai/blog?id=qwen3.6-35b-a3b[Annonce officielle Qwen3.6-35B-A3B — blog Qwen] — agentic coding, Apache 2.0, 262K context</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0121_plugin_gradle_piloter_deux_instances_ollama_pro_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introduction">Introduction</a></li> <li><a href="#_pourquoi_gradle_pour_de_linfra">Pourquoi Gradle Pour de l’Infra ?</a></li> <li><a href="#_le_build_gradle_kts_complet">Le build.gradle.kts Complet</a></li> <li><a href="#_anatomie_des_tâches_clés">Anatomie des Tâches Clés</a> <ul class="sectlevel2"> <li><a href="#_startollamab_le_lanceur"><code>startOllamaB</code> — Le Lanceur</a></li> <li><a href="#_signinb_linteractif"><code>signInB</code> — L’Interactif</a></li> <li><a href="#_pullmodelb_le_paramétrable"><code>pullModelB</code> — Le Paramétrable</a></li> <li><a href="#_statusollamaall_le_diagnostic"><code>statusOllamaAll</code> — Le Diagnostic</a></li> <li><a href="#_cleanollamab_le_nettoyage_qui_préserve_lidentité"><code>cleanOllamaB</code> — Le Nettoyage qui Préserve l’Identité</a></li> </ul> </li> <li><a href="#_workflow_complet_de_zéro_à_deux_sessions">Workflow Complet — De Zéro à Deux Sessions</a></li> <li><a href="#_pourquoi_ne_pas_en_faire_un_vrai_plugin_gradle">Pourquoi Ne Pas en Faire un Vrai Plugin Gradle ?</a></li> <li><a href="#_leçons_apprises">Leçons Apprises</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_ressources">Ressources</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 18 minutes</div> <p>Pourquoi taper des commandes docker à la main quand on peut tout encapsuler dans des tâches Gradle ? Voici comment j’ai industrialisé ma config dual-Ollama Pro avec zéro script shell externe. Démarrage, arrêt, identité, sign-in, pull — tout passe par <code>./gradlew</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>Dans l’article précédent, j’ai montré comment faire cohabiter deux comptes Ollama Pro sur la même machine en isolant la deuxième instance dans un conteneur Docker. Le montage fonctionne, mais la gestion au quotidien est vite pénible : se souvenir du nom du conteneur, relancer les bonnes commandes <code>docker exec</code>, checker quel port est actif…​</p> </div> <div class="paragraph"> <p>Vous connaissez ce moment où vous avez 14 terminaux ouverts, que vous tapez <code>docker exec ollama-instance-b ollama list</code> pour la quatrième fois, et que vous vous dites « il doit bien y avoir un moyen plus propre » ?</p> </div> <div class="paragraph"> <p>Ce moyen, c’est Gradle.</p> </div> <div class="paragraph"> <p>Pas juste pour builder du code. Gradle comme un chef d’orchestre d’infrastructure locale. Des tâches qui provisionnent, vérifient, testent, et nettoient. Le tout versionné dans un <code>build.gradle.kts</code> qui vit à côté du <code>docker-compose.yml</code>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-gradle-ollama.svg" alt="architecture gradle ollama" width="717" height="511"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_gradle_pour_de_linfra">Pourquoi Gradle Pour de l’Infra ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La question est légitime. Gradle, c’est un build tool. Normalement, il compile, il teste, il package. Pas il lance des conteneurs Docker.</p> </div> <div class="paragraph"> <p>Sauf que Gradle est aussi un moteur de graphe de dépendances — et c’est là que ça devient intéressant pour notre cas.</p> </div> <div class="paragraph"> <p>On veut :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Que le conteneur soit lancé avant un sign-in</p> </li> <li> <p>Que l’identité soit vérifiée avant un pull de modèle</p> </li> <li> <p>Qu’un test API échoue silencieusement si le conteneur est down</p> </li> </ol> </div> <div class="paragraph"> <p>Du graphe de dépendances pur. Gradle est taillé pour ça. Le DSL Kotlin rend l’écriture des tâches fluide, et le <code>doLast</code> permet d’exécuter des commandes système comme si c’était du code applicatif.</p> </div> <div class="paragraph"> <p>Et surtout : pas de bashrc à maintenir, pas de scripts qui traînent dans <code>~/bin</code>, pas de Makefile à côté du docker-compose. Tout vit dans un seul fichier, au même endroit que le code du projet.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_build_gradle_kts_complet">Le build.gradle.kts Complet</h2> <div class="sectionbody"> <div class="paragraph"> <p>Voici le fichier que j’ai fini par écrire. Il fait tout, du provisionnement du volume jusqu’au curl de vérification, en passant par le sign-in interactif.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import java.io.ByteArrayOutputStream plugins { base } // ------------------------------------------------------------------------- // Configuration // ------------------------------------------------------------------------- val instanceName = "ollama-instance-b" val instancePort = 11435 val instanceImage = "ollama/ollama:0.20.2" val dataDir = file("${System.getProperty("user.home")}/ollama-b-data") val nativePort = 11434 // Modèles à gérer — cloud Pro + un modèle local gratuit pour les tests val proModels = listOf("deepseek-v4-pro:cloud", "gemma4:31b-cloud") val freeModels = listOf("qwen3:0.6b") // ------------------------------------------------------------------------- // Tâche préparatoire — création du volume si absent // ------------------------------------------------------------------------- val prepareVolume by tasks.registering { group = "ollama" description = "Crée le répertoire de volume pour l'instance B si absent" doLast { if (!dataDir.exists()) { dataDir.mkdirs() println("Volume créé : ${dataDir.absolutePath}") } else { println("Volume existant : ${dataDir.absolutePath}") } } } // ------------------------------------------------------------------------- // Démarrage du conteneur Docker // ------------------------------------------------------------------------- val startOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Lance le conteneur Docker pour l'instance Ollama B" dependsOn(prepareVolume) commandLine( "docker", "run", "-d", "--name", instanceName, "-p", "$instancePort:11434", "-v", "${dataDir.absolutePath}:/root/.ollama", "-e", "OLLAMA_HOST=0.0.0.0", "--restart", "always", instanceImage ) isIgnoreExitValue = true doLast { val alreadyRunning = executionResult.get().exitValue != 0 if (alreadyRunning) { logger.lifecycle("Le conteneur '$instanceName' existe déjà — tentative de démarrage") } else { logger.lifecycle("Conteneur '$instanceName' lancé") } } } // ------------------------------------------------------------------------- // Arrêt du conteneur // ------------------------------------------------------------------------- val stopOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête le conteneur Docker de l'instance B" commandLine("docker", "stop", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' arrêté") } } // ------------------------------------------------------------------------- // Affichage de la clé publique (Device Key) // ------------------------------------------------------------------------- val checkIdentity by tasks.registering(Exec::class) { group = "ollama" description = "Affiche la clé publique SSH de l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "cat", "/root/.ollama/id_ed25519.pub") standardOutput = ByteArrayOutputStream() doLast { val pubKey = standardOutput.toString().trim() println("=".repeat(60)) println("Device Key (Instance B)") println("=".repeat(60)) println(pubKey) println("=".repeat(60)) println("→ Enregistre cette clé sur https://ollama.com/settings/keys") println("→ Puis exécute : ./gradlew signInB") println("=".repeat(60)) } } // ------------------------------------------------------------------------- // Sign-in interactif (Ouvrira le navigateur) // ------------------------------------------------------------------------- val signInB by tasks.registering(Exec::class) { group = "ollama" description = "Lance l'authentification interactive Ollama pour le compte B" dependsOn(startOllamaB) standardInput = System.`in` standardOutput = System.out errorOutput = System.err commandLine("docker", "exec", "-it", instanceName, "ollama", "signin") doFirst { logger.lifecycle("Authentification pour le Compte Pro B...") logger.lifecycle("Ouvre ton navigateur et connecte-toi avec l'email du compte B") } } // ------------------------------------------------------------------------- // Pull d'un modèle (paramétrable via propriété Gradle) // ------------------------------------------------------------------------- val pullModelB by tasks.registering(Exec::class) { group = "ollama" description = "Pull un modèle sur l'instance B. Usage : ./gradlew pullModelB -Pmodel=nom:tag" dependsOn(startOllamaB) val modelName = project.findProperty("model") as? String ?: "qwen3:0.6b" commandLine("docker", "exec", instanceName, "ollama", "pull", modelName) doFirst { logger.lifecycle("Pull du modèle '$modelName' sur l'instance B...") } doLast { logger.lifecycle("Modèle '$modelName' pullé avec succès") } } // ------------------------------------------------------------------------- // Pull de tous les modèles Pro (batch) // ------------------------------------------------------------------------- val pullAllProModels by tasks.registering { group = "ollama" description = "Pull tous les modèles cloud Pro sur l'instance B" dependsOn(startOllamaB) doLast { proModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles Pro pullés") } } // ------------------------------------------------------------------------- // Pull de tous les modèles gratuits (batch / première install) // ------------------------------------------------------------------------- val pullAllFreeModels by tasks.registering { group = "ollama" description = "Pull tous les modèles locaux gratuits sur l'instance B" dependsOn(startOllamaB) doLast { freeModels.forEach { model -> logger.lifecycle("→ Pull $model...") val process = ProcessBuilder("docker", "exec", instanceName, "ollama", "pull", model) .inheritIO() .start() process.waitFor() } logger.lifecycle("Tous les modèles gratuits pullés") } } // ------------------------------------------------------------------------- // Liste des modèles disponibles sur l'instance B // ------------------------------------------------------------------------- val listModelsB by tasks.registering(Exec::class) { group = "ollama" description = "Liste les modèles disponibles sur l'instance B" dependsOn(startOllamaB) commandLine("docker", "exec", instanceName, "ollama", "list") } // ------------------------------------------------------------------------- // Health check — test API sur les deux instances // ------------------------------------------------------------------------- val testOllamaB by tasks.registering { group = "ollama" description = "Teste la connectivité API de l'instance B avec un simple chat" dependsOn(startOllamaB) doLast { val model = project.findProperty("model") as? String ?: "qwen3:0.6b" logger.lifecycle("Test de l'instance B avec le modèle '$model'...") val payload = """ { "model": "$model", "messages": [{"role": "user", "content": "Réponds uniquement par OK"}], "max_tokens": 5 } """.trimIndent() val process = ProcessBuilder( "curl", "-s", "http://localhost:$instancePort/v1/chat/completions", "-H", "Content-Type: application/json", "-d", payload ).start() val response = process.inputStream.bufferedReader().readText() process.waitFor() if (response.contains("\"id\":\"chatcmpl") || response.contains("\"choices\"")) { println("✓ Instance B OK — port $instancePort répond") println(" Response: ${response.take(120)}...") } else { println("✗ Instance B INACTIVE — vérifie le conteneur avec './gradlew statusOllamaAll'") println(" Raw: $response") } } } // ------------------------------------------------------------------------- // Health check sur les deux instances simultanément // ------------------------------------------------------------------------- val statusOllamaAll by tasks.registering { group = "ollama" description = "Vérifie le statut des deux instances Ollama (native + Docker)" doLast { // Instance native runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$nativePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Native — port $nativePort OK (HTTP $code)" else "✗ Instance Native — port $nativePort (HTTP $code)") }.getOrElse { println("✗ Instance Native — injoignable sur le port $nativePort") } // Instance Docker runCatching { val process = ProcessBuilder( "curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", "http://localhost:$instancePort/api/tags" ).start() val code = process.inputStream.bufferedReader().readText().trim() process.waitFor() println(if (code == "200") "✓ Instance Docker B — port $instancePort OK (HTTP $code)" else "✗ Instance Docker B — port $instancePort (HTTP $code)") }.getOrElse { println("✗ Instance Docker B — injoignable sur le port $instancePort") } // Info conteneur runCatching { val process = ProcessBuilder("docker", "ps", "--filter", "name=$instanceName", "--format", "table {{.Names}}\\t{{.Status}}\\t{{.Ports}}").start() val status = process.inputStream.bufferedReader().readText() process.waitFor() println() println("Conteneur Docker :") println(status) } } } // ------------------------------------------------------------------------- // Nettoyage complet // ------------------------------------------------------------------------- val cleanOllamaB by tasks.registering(Exec::class) { group = "ollama" description = "Arrête et supprime le conteneur Docker de l'instance B" dependsOn(stopOllamaB) commandLine("docker", "rm", instanceName) isIgnoreExitValue = true doLast { logger.lifecycle("Conteneur '$instanceName' supprimé") logger.lifecycle("Le volume ${dataDir.absolutePath} est conservé (identité persistante)") } } // ------------------------------------------------------------------------- // Affichage des instructions // ------------------------------------------------------------------------- val helpOllama by tasks.registering { group = "ollama" description = "Affiche l'aide des tâches Ollama disponibles" doLast { println(""" ╔══════════════════════════════════════════════════════════════╗ ║ Tâches Gradle — Pilotage Dual Ollama Pro ║ ╠══════════════════════════════════════════════════════════════╣ ║ ./gradlew startOllamaB Démarrer l'instance Docker B ║ ║ ./gradlew stopOllamaB Arrêter l'instance Docker B ║ ║ ./gradlew checkIdentity Afficher la clé SSH publique ║ ║ ./gradlew signInB Sign-in interactif compte B ║ ║ ./gradlew pullModelB Pull un modèle (-Pmodel=...) ║ ║ ./gradlew pullAllProModels Pull tous les modèles Pro ║ ║ ./gradlew pullAllFreeModels Pull tous les modèles gratuits ║ ║ ./gradlew listModelsB Lister les modèles instance B ║ ║ ./gradlew testOllamaB Test API avec un chat simple ║ ║ ./gradlew statusOllamaAll Santé des 2 instances ║ ║ ./gradlew cleanOllamaB Supprimer le conteneur ║ ║ ./gradlew helpOllama Cette aide ║ ╚══════════════════════════════════════════════════════════════╝ """.trimIndent()) } }</code></pre> </div> </div> <div class="paragraph"> <p>Voilà. Douze tâches, un point d’entrée unique, et zéro friction.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomie_des_tâches_clés">Anatomie des Tâches Clés</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startollamab_le_lanceur"><code>startOllamaB</code> — Le Lanceur</h3> <div class="paragraph"> <p>Rien de sorcier : un <code>docker run -d</code> avec les bons paramètres. L’astuce est dans <code>isIgnoreExitValue = true</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>Si le conteneur existe déjà, la commande <code>docker run</code> échoue (exit code ≠ 0). Sans cette propriété, Gradle arrêterait tout le build en erreur. Ici, l’échec est silencieux — et le <code>doLast</code> détecte si c’était un "déjà existant" ou une vraie erreur.</p> </div> <div class="paragraph"> <p>Le <code>doLast</code> est crucial : il tourne <strong>après</strong> l’exécution de la commande, ce qui permet d’inspecter <code>executionResult.get().exitValue</code> et de logger un message approprié.</p> </div> </div> <div class="sect2"> <h3 id="_signinb_linteractif"><code>signInB</code> — L’Interactif</h3> <div class="paragraph"> <p>C’est la seule tâche qui nécessite une interaction humaine. Gradle transmet <code>System.in</code> au process pour que le prompt <code>ollama signin</code> puisse s’afficher normalement :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">standardInput = System.`in` standardOutput = System.out errorOutput = System.err</code></pre> </div> </div> <div class="paragraph"> <p>Sans ça, le sign-in bloquerait car stdin serait fermé et vous ne verriez jamais le prompt.</p> </div> </div> <div class="sect2"> <h3 id="_pullmodelb_le_paramétrable"><code>pullModelB</code> — Le Paramétrable</h3> <div class="paragraph"> <p>Une tâche générique qui accepte un paramètre via <code>-P</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew pullModelB -Pmodel=deepseek-v4-pro:cloud ./gradlew pullModelB # fallback : qwen3:0.6b</code></pre> </div> </div> <div class="paragraph"> <p>Le fallback est important : <code>project.findProperty("model") as? String ?: "qwen3:0.6b"</code> garantit que la tâche ne pète pas si on oublie le paramètre.</p> </div> </div> <div class="sect2"> <h3 id="_statusollamaall_le_diagnostic"><code>statusOllamaAll</code> — Le Diagnostic</h3> <div class="paragraph"> <p>Deux <code>curl</code> en santé sur les ports <code>11434</code> et <code>11435</code>, avec un fallback en <code>runCatching</code> pour ne pas crasher si l’une des instances est down. La sortie est structurée :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">✓ Instance Native — port 11434 OK (HTTP 200) ✓ Instance Docker B — port 11435 OK (HTTP 200) Conteneur Docker : NAMES STATUS PORTS ollama-instance-b Up 3 hours 0.0.0.0:11435->11434/tcp</code></pre> </div> </div> <div class="paragraph"> <p>Un coup d’œil, et tu sais exactement ce qui tourne et ce qui cloche.</p> </div> </div> <div class="sect2"> <h3 id="_cleanollamab_le_nettoyage_qui_préserve_lidentité"><code>cleanOllamaB</code> — Le Nettoyage qui Préserve l’Identité</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">commandLine("docker", "rm", instanceName) isIgnoreExitValue = true</code></pre> </div> </div> <div class="paragraph"> <p>Le conteneur est supprimé, mais le volume <code>~/ollama-b-data</code> est <strong>conservé</strong>. L’identité SSH survit au nettoyage. Au prochain <code>startOllamaB</code>, les mêmes clés seront réutilisées — pas besoin de refaire le sign-in ni de ré-enregistrer la Device Key.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p><code>cleanOllamaB</code> ne touche pas au volume. Si tu veux effacer l’identité B (et tout recommencer à zéro), il faut supprimer <code>~/ollama-b-data</code> manuellement. C’est volontaire — un <code>clean</code> ne devrait pas détruire des credentials.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_workflow_complet_de_zéro_à_deux_sessions">Workflow Complet — De Zéro à Deux Sessions</h2> <div class="sectionbody"> <div class="paragraph"> <p>Voici la séquence idéale pour quelqu’un qui arrive sur le projet et veut tout mettre en place sans ouvrir de documentation :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text"># 1. Premier contact — que faire ? $ ./gradlew helpOllama # 2. On démarre l'instance B $ ./gradlew startOllamaB # 3. On récupère la Device Key et on l'enregistre sur ollama.com $ ./gradlew checkIdentity # → copier-coller de la clé sur https://ollama.com/settings/keys # 4. Authentification interactive $ ./gradlew signInB # 5. Pull d'un petit modèle gratuit pour tester la plomberie $ ./gradlew pullModelB # 6. Test API $ ./gradlew testOllamaB # 7. Si tout est vert, pull des modèles Pro $ ./gradlew pullAllProModels # 8. Vérification finale des deux instances $ ./gradlew statusOllamaAll</code></pre> </div> </div> <div class="paragraph"> <p>Moins de deux minutes, tout est provisionné. Pas de README à lire, pas de variables d’environnement à setter. La tâche <code>helpOllama</code> fait office de documentation intégrée.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/workflow-complet-sequence.svg" alt="workflow complet sequence" width="757" height="1103"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_ne_pas_en_faire_un_vrai_plugin_gradle">Pourquoi Ne Pas en Faire un Vrai Plugin Gradle ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Question légitime. Extraire ce <code>build.gradle.kts</code> en un plugin Gradle autonome aurait des avantages : réutilisation entre projets, configuration déclarative, extension DSL.</p> </div> <div class="paragraph"> <p>Mais pour l’instant, ça n’a pas de sens. Ce build n’a pas de logique métier complexe — c’est un wrapper autour de commandes Docker et curl. La surcouche d’un plugin Gradle complet (avec extension, tests unitaires, publication) serait disproportionnée pour 12 tâches utilitaires.</p> </div> <div class="paragraph"> <p>Le <code>build.gradle.kts</code> inline vit dans le projet qui en a besoin. Il est trivial à copier ailleurs. Si un jour j’ai trois projets qui en dépendent, je le transformerai en plugin. Pour l’instant, KISS.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Le jour où tu as trois <code>build.gradle.kts</code> identiques dans trois projets, c’est le signal qu’il faut extraire un plugin. Avant ça, la duplication est moins coûteuse que l’abstraction. Sagesse de dev.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_leçons_apprises">Leçons Apprises</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Gradle n’est pas qu’un build tool</strong> — Le moteur de graphe de dépendances en fait un orchestrateur d’infrastructure redoutable. <code>doLast</code>, <code>isIgnoreExitValue</code>, <code>dependsOn</code> : ces trois primitives suffisent à piloter un conteneur Docker avec la même fiabilité qu’un pipeline CI.</p> </li> <li> <p><strong><code>isIgnoreExitValue</code> est ton ami</strong> — Dans un monde idéal, <code>docker run</code> sur un conteneur déjà existant renverrait un warning plutôt qu’un exit code d’erreur. Dans le monde réel, tu mets <code>isIgnoreExitValue = true</code> et tu gères le diagnostic dans <code>doLast</code>.</p> </li> <li> <p><strong>Les tâches paramétrables tuent l’ambiguïté</strong> — Un <code>pullModelB</code> générique avec <code>-Pmodel=…​</code> remplace N tâches spécialisées. Une seule tâche, une seule doc, un seul comportement.</p> </li> <li> <p><strong><code>runCatching</code> pour les health checks</strong> — Quand tu testes N endpoints, le crash du premier ne doit pas empêcher de tester les autres. <code>runCatching</code> + <code>getOrElse</code> par endpoint, et le diagnostic reste complet même en cas de panne partielle.</p> </li> <li> <p><strong>La tâche <code>helpOllama</code> comme documentation exécutable</strong> — Un <code>println()</code> bien formaté remplace un README de trois paragraphes. C’est auto-documenté, toujours à jour, et accessible sans sortir du terminal.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>On est passé de commandes docker à taper à la main à un workflow Gradle complet, versionné, réutilisable. Douze tâches couvrent tout le cycle de vie : provisionnement, identité, sign-in, pull, test, diagnostic, nettoyage.</p> </div> <div class="paragraph"> <p>Le combo docker-compose + build.gradle.kts + opencode.json forme une trinité propre : Docker pour l’isolation, Gradle pour l’orchestration, OpenCode pour la consommation. Chaque couche a sa responsabilité, et aucune ne déborde sur l’autre.</p> </div> <div class="paragraph"> <p>Prochaine étape ? Automatiser le cycle de vie dans la CI pour que les instances Ollama soient disponibles dans les environnements de dev éphémères. Mais ça, c’est un autre article.</p> </div> </div> </div> <div class="sect1"> <h2 id="_ressources">Ressources</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/tutorial_using_tasks.html">User Manual Gradle — Tâches</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_tasks.html">User Manual Gradle — Tâches Custom</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Image Docker Ollama sur Docker Hub</a></p> </li> <li> <p><a href="https://kotlinlang.org/docs/gradle.html">Gradle DSL Kotlin — Documentation</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Article publié le 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com/blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html Fri, 8 May 2026 00:00:00 +0000 blog/2026/0120_cumuler_deux_abonnements_ollama_pro_docker_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_introduction">Introduction</a></li> <li><a href="#_pourquoi_deux_fois_la_même_chose">Pourquoi Deux Fois la Même Chose ?</a></li> <li><a href="#_le_coeur_du_problème_la_device_key">Le Coeur du Problème : La Device Key</a></li> <li><a href="#_mise_en_place_étape_par_étape">Mise en Place — Étape par Étape</a> <ul class="sectlevel2"> <li><a href="#_prérequis">Prérequis</a></li> <li><a href="#_étape_1_créer_le_volume">Étape 1 : Créer le Volume</a></li> <li><a href="#_étape_2_lancer_le_conteneur_docker">Étape 2 : Lancer le Conteneur Docker</a></li> <li><a href="#_étape_3_récupérer_la_clé_publique">Étape 3 : Récupérer la Clé Publique</a></li> <li><a href="#_étape_4_enregistrer_la_clé_sur_ollama_com">Étape 4 : Enregistrer la Clé sur Ollama.com</a></li> <li><a href="#_étape_5_tester_avec_un_petit_modèle_gratuit">Étape 5 : Tester avec un Petit Modèle Gratuit</a></li> </ul> </li> <li><a href="#_le_piège_de_lapi_v1models">Le Piège de l’API <code>/v1/models</code></a></li> <li><a href="#_résultat_deux_sessions_deux_comptes_zéro_conflit">Résultat : Deux Sessions, Deux Comptes, Zéro Conflit</a></li> <li><a href="#_leçons_apprises">Leçons Apprises</a></li> <li><a href="#_pour_aller_plus_loin">Pour Aller Plus Loin</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 14 minutes</div> <p>Deux abonnements Pro, une seule machine, une seule carte bancaire, et zéro conflit réseau. Comment Docker m’a permis de doubler ma capacité d’inférence cloud sans acheter un deuxième PC.</p> </div> </div> </div> <div class="sect1"> <h2 id="_introduction">Introduction</h2> <div class="sectionbody"> <div class="paragraph"> <p>J’utilise Ollama Pro depuis plusieurs mois pour alimenter mes sessions OpenCode en modèles cloud. Le truc, c’est que même avec un abonnement Pro, on est vite limité par le <strong>rate limiting</strong> quand on lance plusieurs agents en parallèle. La solution évidente : un deuxième abonnement.</p> </div> <div class="paragraph"> <p>Mais là, c’est le drame.</p> </div> <div class="paragraph"> <p>Ollama identifie chaque machine par une clé SSH unique — sa fameuse <strong>Device Key</strong>. Deux instances sur le même OS partageraient la même identité, et impossible de lier deux comptes Pro au même device. Et comme vous vous en doutez, je n’allais pas acheter un deuxième laptop juste pour ça.</p> </div> <div class="paragraph"> <p>La solution : tricher. Faire croire à Ollama qu’il tourne sur deux machines différentes, alors qu’elles partagent le même CPU, la même RAM, et la même connexion réseau. Docker va nous offrir une bulle d’isolation parfaite.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-dual-ollama.svg" alt="architecture dual ollama" width="509" height="420"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_deux_fois_la_même_chose">Pourquoi Deux Fois la Même Chose ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant de me traiter de malade mental, laissez-moi vous expliquer le cas d’usage.</p> </div> <div class="paragraph"> <p>Avec un seul abonnement Pro, je peux lancer un modèle comme <code>deepseek-v4-pro:cloud</code> dans une session OpenCode. Le problème surgit quand je veux <strong>deux</strong> sessions simultanées. Les quotas de rate limiting font que la deuxième session rame ou est purement rejetée.</p> </div> <div class="paragraph"> <p>Avec deux abonnements Pro indépendants :</p> </div> <div class="ulist"> <ul> <li> <p>Session OpenCode 1 → Compte Pro A (<code>localhost:11434</code>)</p> </li> <li> <p>Session OpenCode 2 → Compte Pro B (<code>localhost:11435</code>)</p> </li> </ul> </div> <div class="paragraph"> <p>Chaque session a son propre quota, son propre contexte, et ne gêne pas l’autre. C’est du multi-processing humain.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Deux abonnements Pro = deux emails différents. La même carte bancaire fonctionne — le système de paiement Ollama ne bloque pas les souscriptions multiples depuis le même moyen de paiement. J’ai vérifié.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_le_coeur_du_problème_la_device_key">Le Coeur du Problème : La Device Key</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand vous installez Ollama, une paire de clés SSH ed25519 est générée dans le répertoire d’identité :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...</code></pre> </div> </div> <div class="paragraph"> <p>Cette clé est uploadée vers les serveurs d’Ollama lors du <code>ollama signin</code>. C’est elle qui dit « cette machine appartient à tel compte Pro ». Si vos deux instances partagent le même fichier <code>id_ed25519</code>, elles partagent la même identité. Fin du game.</p> </div> <div class="paragraph"> <p>La parade : donner à notre deuxième instance son propre répertoire d’identité, isolé dans un volume Docker.</p> </div> </div> </div> <div class="sect1"> <h2 id="_mise_en_place_étape_par_étape">Mise en Place — Étape par Étape</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_prérequis">Prérequis</h3> <div class="ulist"> <ul> <li> <p>Une installation native d’Ollama fonctionnelle (script officiel <code>curl | sh</code>)</p> </li> <li> <p>Docker installé et fonctionnel</p> </li> <li> <p>Portainer ou docker-compose pour le déploiement</p> </li> <li> <p>Deux comptes Ollama avec deux emails distincts</p> </li> </ul> </div> <div class="paragraph"> <p>J’ai utilisé la version <code>0.20.2</code> — celle fournie par le script officiel et l’image Docker correspondante.</p> </div> </div> <div class="sect2"> <h3 id="_étape_1_créer_le_volume">Étape 1 : Créer le Volume</h3> <div class="paragraph"> <p>Un simple répertoire sur l’hôte servira de volume persistant pour l’identité de l’instance B :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/ollama-b-data</code></pre> </div> </div> <div class="paragraph"> <p>Ce dossier sera monté dans le conteneur Docker comme <code>/root/.ollama</code>, là où Ollama stocke ses clés d’identité, son historique et ses modèles.</p> </div> </div> <div class="sect2"> <h3 id="_étape_2_lancer_le_conteneur_docker">Étape 2 : Lancer le Conteneur Docker</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml"># docker-compose.yml services: ollama-instance-b: image: ollama/ollama:0.20.2 container_name: ollama-instance-b ports: - "11435:11434" volumes: - /home/cheroliv/ollama-b-data:/root/.ollama environment: - OLLAMA_HOST=0.0.0.0 restart: always</code></pre> </div> </div> <div class="paragraph"> <p>Ce qui se passe ici :</p> </div> <div class="ulist"> <ul> <li> <p>Le port <strong>11435</strong> de l’hôte est mappé sur le <strong>11434</strong> interne du conteneur. Ainsi, l’instance Docker écoute sur <code>:11435</code> sans conflit avec l’instance native qui squatte <code>:11434</code>.</p> </li> <li> <p>Le volume <code>~/ollama-b-data</code> est monté sur <code>/root/.ollama</code> — c’est là que l’identité SSH sera stockée.</p> </li> <li> <p><code>OLLAMA_HOST=0.0.0.0</code> permet au conteneur d’accepter des connexions externes.</p> </li> </ul> </div> <div class="paragraph"> <p>J’ai déployé cette stack via Portainer, mais un simple <code>docker compose up -d</code> fonctionne tout aussi bien.</p> </div> </div> <div class="sect2"> <h3 id="_étape_3_récupérer_la_clé_publique">Étape 3 : Récupérer la Clé Publique</h3> <div class="paragraph"> <p>Le conteneur étant vierge au premier démarrage, Ollama génère automatiquement une nouvelle paire de clés SSH dans le volume. On récupère la clé publique :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b cat /root/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ+dvnfmuo49q5O8LOlvgZ39SKORFw47ry9k4H2jPc</code></pre> </div> </div> <div class="paragraph"> <p>Je vérifie que cette clé est <strong>différente</strong> de celle de l’instance native :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Instance native $ cat /usr/share/ollama/.ollama/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGyF...(différente) # Instance Docker $ cat ~/ollama-b-data/id_ed25519.pub ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIDDQ...(différente)</code></pre> </div> </div> <div class="paragraph"> <p>Deux clés distinctes, deux identités séparées. Le tour est joué.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> <div class="paragraph"> <p>Si votre conteneur redémarre, il <strong>réutilise</strong> les clés présentes dans le volume. L’identité est persistante. Vous ne perdrez pas l’association avec le compte Pro.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_étape_4_enregistrer_la_clé_sur_ollama_com">Étape 4 : Enregistrer la Clé sur Ollama.com</h3> <div class="paragraph"> <p>Direction <a href="https://ollama.com/settings/keys" class="bare">https://ollama.com/settings/keys</a> → Add SSH Key. On colle la clé publique de l’instance Docker et on valide.</p> </div> <div class="paragraph"> <p>Ensuite, on lie cette identité au compte Pro B :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin</code></pre> </div> </div> <div class="paragraph"> <p>Le navigateur s’ouvre, on se connecte avec l’email du compte B, et le token est associé à la clé SSH du conteneur. On vérifie que tout est OK :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec -it ollama-instance-b ollama signin User: cherolivpro</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_étape_5_tester_avec_un_petit_modèle_gratuit">Étape 5 : Tester avec un Petit Modèle Gratuit</h3> <div class="paragraph"> <p>Avant de balancer le prix d’un abonnement Pro, je veux être certain que le tuyau fonctionne. Je pull un petit modèle local et gratuit pour valider la connectivité :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull qwen3:0.6b pulling manifest pulling 7f4030143c1c: 100% ▕██████████████████▏ 522 MB success $ curl -s http://localhost:11435/api/tags {"models":[{"name":"qwen3:0.6b","model":"qwen3:0.6b",...}]}</code></pre> </div> </div> <div class="paragraph"> <p>Le port <code>11435</code> répond, le modèle est servi. L’instance B est vivante.</p> </div> <div class="paragraph"> <p>Une fois rassuré, je passe au pull du vrai modèle cloud Pro :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ docker exec ollama-instance-b ollama pull deepseek-v4-pro:cloud pulling manifest pulling 31c3059e137e: 100% ▕██████████████████▏ 344 B success</code></pre> </div> </div> <div class="paragraph"> <p>344 octets pour le manifeste d’un modèle cloud — normal, l’inférence se fait côté serveur, pas en local. Et voilà le test ultime :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl -s http://localhost:11435/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4-pro:cloud","messages":[{"role":"user","content":"Dis bonjour en une phrase courte."}]}' { "id": "chatcmpl-480", "model": "deepseek-v4-pro", "choices": [{ "message": { "content": "Bonjour !" }, "finish_reason": "stop" }], "usage": { "total_tokens": 181 } }</code></pre> </div> </div> <div class="paragraph"> <p>Bonjour à toi aussi, instance B.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_piège_de_lapi_v1models">Le Piège de l’API <code>/v1/models</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>J’ai perdu 20 minutes sur un détail idiot. Quand j’ai configuré le provider <code>ollama-b</code> dans OpenCode, rien n’apparaissait dans le sélecteur de modèles. Rien. Que dalle.</p> </div> <div class="paragraph"> <p>La raison ? L’API <code>/v1/models</code> de l’instance B retournait <code>{"object":"list","data":null}</code> au lieu de <code>{"object":"list","data":[]}</code> quand aucun modèle n’était pullé. La valeur <code>null</code> faisait planter le parsing côté OpenCode, qui n’affichait pas le provider.</p> </div> <div class="paragraph"> <p>La solution : déclarer les modèles <strong>explicitement</strong> dans la configuration OpenCode plutôt que de compter sur la découverte dynamique.</p> </div> <div class="listingblock"> <div class="title">~/.config/opencode/opencode.json</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama (local)", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "gemma4:e2b": { "name": "Gemma 4 E2B (local)" } } }, "ollama-b": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama Instance B (Docker)", "options": { "baseURL": "http://localhost:11435/v1" }, "models": { "qwen3:0.6b": { "name": "Qwen3 0.6B (B)" }, "deepseek-v4-pro:cloud": { "name": "DeepSeek V4 Pro (B)" } } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Avec cette déclaration explicite, OpenCode voit immédiatement le provider B et ses modèles. Un redémarrage de session, et le sélecteur <code>/models</code> affiche les deux instances côte à côte.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Si vous ne voyez pas votre provider custom dans <code>/models</code>, ne perdez pas trois heures à redémarrer votre terminal. Déclarez les modèles manuellement dans <code>opencode.json</code> — ça règle le problème instantanément.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_résultat_deux_sessions_deux_comptes_zéro_conflit">Résultat : Deux Sessions, Deux Comptes, Zéro Conflit</h2> <div class="sectionbody"> <div class="paragraph"> <p>Au final, je peux lancer deux sessions OpenCode simultanément :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Session 1 → /models → Ollama (local) → deepseek-v4-pro:cloud → Compte A Session 2 → /models → Ollama Instance B (Docker) → deepseek-v4-pro:cloud → Compte B</code></pre> </div> </div> <div class="paragraph"> <p>Chaque session a son propre quota, son propre rate limit, et ne se marche pas sur les pieds. Même machine, même carte bleue, deux emails différents.</p> </div> <div class="paragraph"> <p>Et le meilleur ? Le conteneur Docker est en <code>restart: always</code>. Il survit aux reboots du système sans intervention manuelle.</p> </div> </div> </div> <div class="sect1"> <h2 id="_leçons_apprises">Leçons Apprises</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Docker isole tout, même l’identité</strong> — Un simple bind mount de volume suffit à donner à un conteneur son propre jeu de clés SSH, le rendant indistinguable d’une machine physique différente aux yeux d’Ollama.</p> </li> <li> <p><strong>Deux emails, même CB</strong> — Ollama ne bloque pas les souscriptions multiples depuis le même moyen de paiement. Seul l’email doit être distinct.</p> </li> <li> <p><strong>Tester gratuit avant de payer</strong> — Un <code>ollama pull qwen3:0.6b</code> (modèle libre, 522 Mo) permet de valider toute la chaîne réseau sans débourser un centime. Vous validez le plomberie d’abord, vous activez le Pro ensuite.</p> </li> <li> <p><strong><code>/v1/models</code> avec <code>data: null</code> casse OpenCode</strong> — Si vous configurez un provider custom avec <code>"models": {}</code>, OpenCode tente de découvrir les modèles via l’API. Si l’API répond <code>data: null</code>, le provider n’apparaît pas. Déclarez les modèles explicitement.</p> </li> <li> <p><strong>Deux comptes, c’est du multi-processing humain</strong> — Un compte Pro = une session OpenCode active. Deux comptes = deux sessions parallèles. Pour quelqu’un qui jongle entre plusieurs projets Gradle en simultané, c’est un game changer.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_pour_aller_plus_loin">Pour Aller Plus Loin</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://ollama.com/settings/keys">Ollama Settings — Gestion des clés SSH</a></p> </li> <li> <p><a href="https://docs.ollama.com/">Documentation officielle Ollama</a></p> </li> <li> <p><a href="https://hub.docker.com/r/ollama/ollama">Image Docker Ollama sur Docker Hub</a></p> </li> <li> <p><a href="https://opencode.ai/docs/providers/#ollama">OpenCode — Configuration Provider Ollama</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><em>Article publié le 2026-05-08</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0080_kitty_term_post.html Thu, 7 May 2026 00:00:00 +0000 blog/2025/0080_kitty_term_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_为什么选择_kitty_和_zsh">为什么选择 Kitty 和 Zsh？</a></li> <li><a href="#_系统先决条件">系统先决条件</a></li> <li><a href="#_kitty_的下载和安装">Kitty 的下载和安装</a> <ul class="sectlevel2"> <li><a href="#_下载安装脚本">下载安装脚本</a></li> <li><a href="#_创建符号链接">创建符号链接</a></li> </ul> </li> <li><a href="#_在_xubuntu_中集成_kitty">在 Xubuntu 中集成 Kitty</a> <ul class="sectlevel2"> <li><a href="#_复制文件_desktop">复制文件 desktop</a></li> <li><a href="#_修改桌面文件">修改桌面文件</a></li> <li><a href="#_将_kitty_设置为默认终端_可选">将 Kitty 设置为默认终端 (可选)</a></li> </ul> </li> <li><a href="#_zsh_的安装">Zsh 的安装</a></li> <li><a href="#_将_zsh_设置为默认_shell">将 Zsh 设置为默认 shell</a> <ul class="sectlevel2"> <li><a href="#_全局方法适用于所有终端">全局方法（适用于所有终端）</a></li> <li><a href="#_kitty专用方法">Kitty专用方法</a></li> </ul> </li> <li><a href="#_zsh_配置_可选">Zsh 配置 (可选)</a> <ul class="sectlevel2"> <li><a href="#_创建一个_zshrc_文件">创建一个 .zshrc 文件</a></li> <li><a href="#_最小配置示例">最小配置示例</a></li> </ul> </li> <li><a href="#_完整工作流程摘要">完整工作流程摘要</a></li> <li><a href="#_最终检查">最终检查</a> <ul class="sectlevel2"> <li><a href="#_打开配置文件">�📂 打开配置文件</a></li> <li><a href="#_️_添加或修改_font_size">�🖋️ 添加或修改 `font_size</a></li> <li><a href="#_保存并重启_kitty">💾 保存并重启 Kitty</a></li> <li><a href="#_动态调整临时缩放">�✅ 动态调整(临时缩放)</a></li> </ul> </li> <li><a href="#_安装和配置_oh_my_zsh">安装和配置 Oh My Zsh</a> <ul class="sectlevel2"> <li><a href="#_安装_oh_my_zsh">安装 Oh My Zsh</a></li> <li><a href="#_更改主题">更改主题</a></li> <li><a href="#_验证">验证</a></li> <li><a href="#_用例图">用例图</a></li> </ul> </li> <li><a href="#_在_kitty_中开启透明度">在 Kitty 中开启透明度</a> <ul class="sectlevel2"> <li><a href="#_透明性的前提条件">透明性的前提条件</a></li> <li><a href="#_kitty_conf中的透明度设置">kitty.conf中的透明度设置</a></li> <li><a href="#_重新启动_kitty">重新启动 Kitty</a></li> <li><a href="#_可能的补充">可能的补充</a></li> <li><a href="#_序列图_kitty_初始化带透明度">序列图 - Kitty 初始化（带透明度）</a></li> <li><a href="#_已知限制">已知限制</a></li> </ul> </li> <li><a href="#_关闭声音提示_audible_bell">关闭声音提示 (audible bell)</a></li> <li><a href="#_kitty更新">Kitty更新</a></li> <li><a href="#_参考文献">参考文献</a></li> <li><a href="#_结论">结论</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>本指南逐步解释如何在 Xubuntu 上安装终端 <strong>kitty</strong>，正确配置它，并将 bash 替换为 <strong>zsh</strong> 作为默认 shell。 kitty项目地址:https://github.com/kovidgoyal/kitty.</p> </div> <div class="paragraph"> <p><em><em>_ Kitty 是一个现代、快速且可配置的终端，特别适合对要求高的开发者。 </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_为什么选择_kitty_和_zsh">为什么选择 Kitty 和 Zsh？</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty 的特点是：</p> </div> <div class="ulist"> <ul> <li> <p>得益于 GPU 加速的卓越性能,</p> </li> <li> <p>完全基于单个文本文件的配置，</p> </li> <li> <p>出色的字体和连字支持。</p> </li> </ul> </div> <div class="paragraph"> <p>Zsh 另一方面是一个功能强大的交互式 shell，提供：</p> </div> <div class="ulist"> <ul> <li> <p>智能补全，</p> </li> <li> <p>一个可自定义的提示，</p> </li> <li> <p>与 bash 具有良好的兼容性。</p> </li> </ul> </div> <div class="paragraph"> <p>通过将 Kitty 与 Zsh 结合使用，您可以获得一个高效且美观的环境。</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/kitty-zsh-overview.png" alt="kitty zsh overview" width="729" height="305"> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>此指南仅限于通过脚本安装及 Xubuntu。</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_系统先决条件">系统先决条件</h2> <div class="sectionbody"> <div class="paragraph"> <p>开始之前，请确保您有：</p> </div> <div class="ulist"> <ul> <li> <p>Xubuntu 已安装，</p> </li> <li> <p>互联网接入，</p> </li> <li> <p>一个功能正常的 Bash shell，用于运行脚本。</p> </li> </ul> </div> <div class="paragraph"> <p>�检查您的环境：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">uname -a lsb_release -a</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_kitty_的下载和安装">Kitty 的下载和安装</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty 建议通过官方脚本进行安装，该脚本将文件放置在`~/.local/kitty.app`。</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>这种方法与包管理器无关（没有`apt`).</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_下载安装脚本">下载安装脚本</h3> <div class="paragraph"> <p>执行以下命令：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>此命令执行 :</p> </div> <div class="ulist"> <ul> <li> <p>下载二进制文件，</p> </li> <li> <p>提取 在`~/.local/kitty.app`,</p> </li> <li> <p>创建符号链接。</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/download-install.svg" alt="download install" width="264" height="336"> </div> </div> </div> <div class="sect2"> <h3 id="_创建符号链接">创建符号链接</h3> <div class="paragraph"> <p>为了能够调用`kitty`从终端创建一个符号链接 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ln -s ~/.local/kitty.app/bin/kitty ~/.local/bin/kitty</code></pre> </div> </div> <div class="paragraph"> <p>添加`~/.local/bin`将其添加到您的 PATH 中（如果尚未添加的话） :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>您可以检查安装：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty --version</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_在_xubuntu_中集成_kitty">在 Xubuntu 中集成 Kitty</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了让 Kitty 在应用程序菜单中出现：</p> </div> <div class="sect2"> <h3 id="_复制文件_desktop">复制文件 desktop</h3> <div class="paragraph"> <p>复制文件`.desktop`提供：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_修改桌面文件">修改桌面文件</h3> <div class="paragraph"> <p>编辑文件 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.local/share/applications/kitty.desktop</code></pre> </div> </div> <div class="paragraph"> <p>�检查或修改以下行：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">[Desktop Entry] Version=1.0 Type=Application Name=Kitty Terminal Comment=Fast GPU-based terminal emulator Exec=/home/$USER/.local/kitty.app/bin/kitty Icon=kitty Categories=System;TerminalEmulator;</code></pre> </div> </div> <div class="paragraph"> <p>替换`YOURUSER`由您的用户名。</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/desktop-integration.png" alt="desktop integration" width="237" height="335"> </div> </div> </div> <div class="sect2"> <h3 id="_将_kitty_设置为默认终端_可选">将 Kitty 设置为默认终端 (可选)</h3> <div class="paragraph"> <p>要把 Kitty 设为默认启动的终端：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo update-alternatives --install /usr/bin/x-terminal-emulator x-terminal-emulator ~/.local/kitty.app/bin/kitty 50 sudo update-alternatives --config x-terminal-emulator</code></pre> </div> </div> <div class="paragraph"> <p>选择`kitty`在所提供的菜单中。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_zsh_的安装">Zsh 的安装</h2> <div class="sectionbody"> <div class="paragraph"> <p>如果 Zsh 尚未安装，请执行：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install zsh</code></pre> </div> </div> <div class="paragraph"> <p>检查安装 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">zsh --version</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_将_zsh_设置为默认_shell">将 Zsh 设置为默认 shell</h2> <div class="sectionbody"> <div class="paragraph"> <p>您可以全局更改您的 shell，或者仅在 Kitty 中更改。</p> </div> <div class="sect2"> <h3 id="_全局方法适用于所有终端">全局方法（适用于所有终端）</h3> <div class="paragraph"> <p>识别绝对路径：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">which zsh</code></pre> </div> </div> <div class="paragraph"> <p>通常`/usr/bin/zsh`.</p> </div> <div class="paragraph"> <p>修改默认的 shell :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">chsh -s /usr/bin/zsh</code></pre> </div> </div> <div class="paragraph"> <p>登出然后重新登录。</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/zsh-default-shell.svg" alt="zsh default shell" width="546" height="341"> </div> </div> </div> <div class="sect2"> <h3 id="_kitty专用方法">Kitty专用方法</h3> <div class="paragraph"> <p>如果您只想在 Kitty 中更改 shell，请编辑配置文件：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>�添加这一行：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">shell zsh</code></pre> </div> </div> <div class="paragraph"> <p>保存并重启 Kitty。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_zsh_配置_可选">Zsh 配置 (可选)</h2> <div class="sectionbody"> <div class="paragraph"> <p>自定义您的 Zsh :</p> </div> <div class="sect2"> <h3 id="_创建一个_zshrc_文件">创建一个 .zshrc 文件</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">touch ~/.zshrc nano ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_最小配置示例">最小配置示例</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export ZSH_THEME="robbyrussell" export PATH="$HOME/.local/bin:$PATH" alias ll="ls -la"</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_完整工作流程摘要">完整工作流程摘要</h2> <div class="sectionbody"> <div class="paragraph"> <p>下面的示意图概括了整个过程：</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/full-workflow.png" alt="full workflow" width="281" height="643"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_最终检查">最终检查</h2> <div class="sectionbody"> <div class="paragraph"> <p>启动 Kitty :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> <div class="paragraph"> <p>您应该看到`zsh`已激活 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $SHELL</code></pre> </div> </div> <div class="paragraph"> <p>预期结果：</p> </div> <div class="paragraph"> <p>/usr/bin/zsh</p> </div> <div class="paragraph"> <p>要修改字体大小在<strong>小猫</strong>, 必须调整参数`font_size`在配置文件中。以下是详细的步骤：</p> </div> <div class="sect2"> <h3 id="_打开配置文件">�📂 打开配置文件</h3> <div class="paragraph"> <p>主配置文件通常位于：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>如果此文件尚不存在，您可以创建它。 Exemple :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_️_添加或修改_font_size">�🖋️ 添加或修改 `font_size</h3> <div class="paragraph"> <p>�添加以下指令，如果它已存在则进行修改：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">font_size 14.0</code></pre> </div> </div> <div class="paragraph"> <p>这里`14.0`对应所需的尺寸。您可以输入任何小数值，例如`12.0`, `15.5`等等</p> </div> </div> <div class="sect2"> <h3 id="_保存并重启_kitty">💾 保存并重启 Kitty</h3> <div class="ulist"> <ul> <li> <p>保存 (<code>Ctrl + O</code>, 然后`Entrée`) 和离开 (<code>Ctrl + X</code>) 如果您使用`nano`.</p> </li> <li> <p>关闭所有 Kitty 窗口，然后重新启动终端以使更改生效。</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_动态调整临时缩放">�✅ 动态调整(临时缩放)</h3> <div class="paragraph"> <p>如果您想临时放大/缩小而不更改设置，请使用默认的键盘快捷键 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>增加字体大小</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + =</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>减小字体大小</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + -</code></p> </div> <div class="ulist"> <ul> <li> <p><strong>重置大小</strong>:</p> </li> </ul> </div> <div class="paragraph"> <p><code>Ctrl + Shift + Backspace</code></p> </div> <div class="paragraph"> <p>这些设置在终端关闭后不会持续。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_安装和配置_oh_my_zsh">安装和配置 Oh My Zsh</h2> <div class="sectionbody"> <div class="paragraph"> <p>一旦安装并配置了Zsh作为默认shell，您可以使用*Oh My Zsh*丰富您的环境，这是一个管理Zsh配置的框架，提供：</p> </div> <div class="ulist"> <ul> <li> <p>一组用于提示的主题,</p> </li> <li> <p>许多插件</p> </li> <li> <p>清晰的配置组织</p> </li> </ul> </div> <div class="sect2"> <h3 id="_安装_oh_my_zsh">安装 Oh My Zsh</h3> <div class="paragraph"> <p>请确保 Zsh 处于活动状态：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh --version</code></pre> </div> </div> <div class="paragraph"> <p>如有必要，请执行：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">zsh</code></pre> </div> </div> <div class="paragraph"> <p>然后下载并运行官方安装脚本：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"</code></pre> </div> </div> <div class="paragraph"> <p>这个脚本：</p> </div> <div class="ulist"> <ul> <li> <p>创建文件夹`~/.oh-my-zsh`,</p> </li> <li> <p>可能保存您的文件`~/.zshrc`,</p> </li> <li> <p>自动激活新的提示。</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_更改主题">更改主题</h3> <div class="paragraph"> <p>打开您的配置文件：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>修改变量`ZSH_THEME`选择另一个主题（例如`agnoster`) :</p> </div> <div class="paragraph"> <p>ZSH_THEME="agnoster</p> </div> <div class="paragraph"> <p>保存然后重新加载配置 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">source ~/.zshrc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_验证">验证</h3> <div class="paragraph"> <p>启动 Kitty 并检查提示是否已经更改。 您可以通过执行来确认 Oh My Zsh 已激活 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">echo $ZSH</code></pre> </div> </div> <div class="paragraph"> <p>结果应该类似于：</p> </div> <div class="paragraph"> <p>/home/votre_utilisateur/.oh-my-zsh</p> </div> </div> <div class="sect2"> <h3 id="_用例图">用例图</h3> <div class="imageblock"> <div class="content"> <img src="./images/ohmyzsh-installation.png" alt="ohmyzsh installation" width="422" height="480"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_在_kitty_中开启透明度">在 Kitty 中开启透明度</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kitty 最受欢迎的功能之一是能够为终端背景添加 <strong>透明度</strong>。这样可以看到底层环境（窗口、桌面等）的若影，这在多任务处理时特别有用。</p> </div> <div class="sect2"> <h3 id="_透明性的前提条件">透明性的前提条件</h3> <div class="paragraph"> <p>Kitty 中的透明度基于<strong>�窗口合成器</strong>由图形环境使用。 在Xubuntu（基于XFCE），请确保该<strong>合成已启用</strong>.</p> </div> <div class="ulist"> <div class="title">待检查：</div> <ul> <li> <p>在桌面上右键点击 > 设置 ><strong>�窗口管理器设置</strong>,</p> </li> <li> <p>标签<strong>作曲家</strong>: 复选框 <strong>[启用合成]</strong> 必须勾选。</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/transparency-usecase.png" alt="transparency usecase" width="384" height="203"> </div> </div> </div> <div class="sect2"> <h3 id="_kitty_conf中的透明度设置">kitty.conf中的透明度设置</h3> <div class="paragraph"> <p>打开您的配置文件`~/.config/kitty/kitty.conf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">nano ~/.config/kitty/kitty.conf</code></pre> </div> </div> <div class="paragraph"> <p>�添加或修改以下行：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background_opacity 0.85</code></pre> </div> </div> <div class="paragraph"> <p>此参数接受的值范围为：</p> </div> <div class="ulist"> <ul> <li> <p><code>1.0</code>→ 不透明 (没有透明度)</p> </li> <li> <p><code>0.0</code>→ 完全透明 (不可用)</p> </li> <li> <p>中间值例如`0.90`, <code>0.75</code>，等等</p> </li> </ul> </div> <div class="paragraph"> <p>一个好的视觉妥协通常在`0.85` et <code>0.95</code>.</p> </div> </div> <div class="sect2"> <h3 id="_重新启动_kitty">重新启动 Kitty</h3> <div class="paragraph"> <p>关闭所有 Kitty 实例，然后重新打开一个新窗口以使更改生效：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">kitty</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_可能的补充">可能的补充</h3> <div class="paragraph"> <p>如果您使用自定义终端背景，您也可以设置具有透明度的背景颜色（以 RGBA 表示）：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">background #1e1e2eff</code></pre> </div> </div> <div class="paragraph"> <p>最后一个组件 (<code>ff</code>) 表示不透明度 （的`00` à <code>ff</code>).</p> </div> </div> <div class="sect2"> <h3 id="_序列图_kitty_初始化带透明度">序列图 - Kitty 初始化（带透明度）</h3> <div class="imageblock"> <div class="content"> <img src="./images/transparency-sequence.png" alt="transparency sequence" width="670" height="422"> </div> </div> </div> <div class="sect2"> <h3 id="_已知限制">已知限制</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>如果以下条件成立，半透明功能不工作： - XFCE 合成器已被禁用， - 正在使用不兼容的窗口管理器, - 您在后台以 <strong>tmux</strong> 模式使用 Kitty，且不支持透明度。</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_关闭声音提示_audible_bell">关闭声音提示 (audible bell)</h2> <div class="sectionbody"> <div class="paragraph"> <p>默认情况下，Kitty 在输入错误命令或终端事件触发时会发出哔声。此噪音可能很快变得烦人，尤其是在高强度开发环境中。</p> </div> <div class="paragraph"> <p>要禁用此行为，请在文件中添加以下指令`~/.config/kitty/kitty.conf`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">audible_bell no</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>您也可以启用 <strong>retour visuel</strong> 来代替声音提示音：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-conf hljs" data-lang="conf">visual_bell yes</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_kitty更新">Kitty更新</h2> <div class="sectionbody"> <div class="paragraph"> <p>由于 Kitty 是通过脚本而非包管理器安装的，更新方法是重新运行官方安装脚本。这可以下载最新版本并将您现有的安装更新到`~/.local/kitty.app`.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>后缀`.app`在路上`~/.local/kitty.app`是Kitty在Linux上通过其官方脚本安装的惯例，并且绝不表示仅与macOS兼容。</p> </div> </td> </tr> </table> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>在运行更新命令之前，请确保您位于您的个人目录 (<code>~</code>).</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>从您的主目录执行以下命令：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin</code></pre> </div> </div> <div class="paragraph"> <p>此脚本将负责：</p> </div> <div class="ulist"> <ul> <li> <p>下载新版本的二进制文件。</p> </li> <li> <p>提取文件到`~/.local/kitty.app`.</p> </li> <li> <p>如有必要，更新符号链接。</p> </li> </ul> </div> <div class="paragraph"> <p>更新后，建议关闭所有 Kitty 实例并重新启动，以确保新版本被正确加载。</p> </div> </div> </div> <div class="sect1"> <h2 id="_参考文献">参考文献</h2> <div class="sectionbody"> <div class="paragraph"> <p>如果您想深入了解自定义，请查阅官方文档：</p> </div> <div class="ulist"> <ul> <li> <p>Kitty：https://sw.kovidgoyal.net/kitty/</p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.background_opacity</a></p> </li> <li> <p><a href="https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell" class="bare">https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.audible_bell</a></p> </li> <li> <p>Zsh：https://zsh.sourceforge.io/</p> </li> <li> <p>Github: <a href="https://github.com/kovidgoyal/kitty" class="bare">https://github.com/kovidgoyal/kitty</a></p> </li> <li> <p>Zsh: <a href="https://zsh.sourceforge.io/" class="bare">https://zsh.sourceforge.io/</a></p> </li> <li> <p><a href="https://ohmyz.sh/" class="bare">https://ohmyz.sh/</a></p> </li> <li> <p><a href="https://github.com/ohmyzsh/ohmyzsh/wiki" class="bare">https://github.com/ohmyzsh/ohmyzsh/wiki</a></p> </li> <li> <p><a href="https://docs.xfce.org/xfce/xfwm4/compositor" class="bare">https://docs.xfce.org/xfce/xfwm4/compositor</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>您现在拥有：</p> </div> <div class="ulist"> <ul> <li> <p>一个现代且高性能的终端(Kitty)</p> </li> <li> <p>一个功能强大且可定制的Shell（Zsh）</p> </li> <li> <p>一个干净且独立于系统包的配置</p> </li> <li> <p>拥有 Oh My Zsh、美观且实用的终端</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html Wed, 6 May 2026 00:00:00 +0000 blog/2026/0119_benchmark_dgx_spark_vs_cloud_abonnement_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_contexte_un_marché_qui_a_basculé">Le Contexte : Un Marché Qui a Basculé</a></li> <li><a href="#_le_panel_des_options">Le Panel des Options</a> <ul class="sectlevel2"> <li><a href="#_ce_que_jai_exclu_et_pourquoi">Ce Que J’ai Exclu (et Pourquoi)</a></li> </ul> </li> <li><a href="#_inférence_simple_la_mort_du_hardware_local">Inférence Simple : La Mort du Hardware Local</a> <ul class="sectlevel2"> <li><a href="#_le_calcul">Le Calcul</a></li> <li><a href="#_même_avec_un_usage_intensif">Même avec un Usage Intensif</a></li> </ul> </li> <li><a href="#_fine_tuning_le_cloud_est_imbattable">Fine-Tuning : Le Cloud Est Imbattable</a> <ul class="sectlevel2"> <li><a href="#_le_coût_réel_dun_fine_tune">Le Coût Réel d’un Fine-Tune</a></li> <li><a href="#_les_acteurs_spécialisés">Les Acteurs Spécialisés</a></li> </ul> </li> <li><a href="#_la_seule_vraie_raison_la_souveraineté_des_données">La Seule Vraie Raison : La Souveraineté des Données</a> <ul class="sectlevel2"> <li><a href="#_le_vrai_calcul_de_la_confidentialité">Le Vrai Calcul de la Confidentialité</a></li> </ul> </li> <li><a href="#_synthèse_la_matrice_de_décision">Synthèse : La Matrice de Décision</a></li> <li><a href="#_le_cas_particulier_labonnement_pro_face_aux_modèles_chinois">Le Cas Particulier : L’Abonnement Pro Face aux Modèles Chinois</a> <ul class="sectlevel2"> <li><a href="#_pourquoi_les_modèles_chinois_changent_tout">Pourquoi les Modèles Chinois Changent Tout</a></li> <li><a href="#_ce_que_ça_veut_dire_pour_le_hardware">Ce Que Ça Veut Dire pour le Hardware</a></li> </ul> </li> <li><a href="#_et_huawei">Et Huawei ?</a></li> <li><a href="#_conclusion_le_luxe_de_la_proximité">Conclusion : Le Luxe de la Proximité</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 14 minutes</div> <p>NVIDIA vend le DGX Spark comme un « supercalculateur IA de bureau » à $4 699. Ollama propose ses modèles cloud à $20/mois. Un H100 se loue $1.38/h chez Vast.ai. Et les modèles chinois open-source — DeepSeek, Qwen, GLM — sont disponibles partout, gratuitement, sans avoir à acheter une carte. Alors, ce Spark, il sert à quoi au juste ? J’ai fait les maths.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_le_contexte_un_marché_qui_a_basculé">Le Contexte : Un Marché Qui a Basculé</h2> <div class="sectionbody"> <div class="paragraph"> <p>En mai 2026, le paysage de l’IA a radicalement changé par rapport à l’annonce du DGX Spark au CES 2025. Trois forces ont convergé pour rendre le hardware local de plus en plus difficile à justifier :</p> </div> <div class="ulist"> <ul> <li> <p><strong>L’effondrement des prix du cloud GPU</strong> : un H100 se loue entre $1.38 et $3/h, contre $5-8/h il y a 18 mois</p> </li> <li> <p><strong>L’explosion des modèles chinois open-source</strong> : DeepSeek-V4, Qwen-3, GLM-5 sont compétitifs avec les modèles occidentaux, disponibles gratuitement</p> </li> <li> <p><strong>La montée des plateformes d’inférence managée</strong> : Ollama, Groq, Together AI proposent des API à des tarifs agressifs, avec des paliers gratuits généreux</p> </li> </ul> </div> <div class="paragraph"> <p>Le DGX Spark, annoncé à $2 999 puis monté à $4 699, arrive dans un monde qui n’a plus besoin de lui.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_panel_des_options">Le Panel des Options</h2> <div class="sectionbody"> <div class="paragraph"> <p>Voici les solutions disponibles en mai 2026 pour faire tourner des LLMs, de la plus légère à la plus lourde :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> <col style="width: 2.5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Option</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Coût</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">VRAM / Capacité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modèles accessibles</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contrainte principale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Free</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0/mois</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cloud léger</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles publics</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Usage limité, 1 modèle simultané</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Claude Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/mois (~$240/an)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">N/A (API fermée)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Claude 4.x uniquement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modèle unique, pas d’open-source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Pro</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$20/mois (~$200/an)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cloud medium</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles publics</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 modèles simultanés max</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ollama Max</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$100/mois (~$1 200/an)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cloud heavy</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles publics</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">10 modèles simultanés</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Cloud GPU (H100)</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$1.38-3/h</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">80 Go HBM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles, fine-tuning</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Facturation horaire, setup requis</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>DGX Spark</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 (achat)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">128 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <128 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lent (~10x moins qu’un H100), fixe</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mac Studio M3 Ultra</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~$5 000+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">192 Go unifié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles <192 Go</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pas CUDA, écosystème MLX</p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Les prix cloud GPU cités sont ceux de Vast.ai et RunPod en mai 2026 — du spot/on-demand, pas du réservé. Les prix des hyperscalers (AWS, GCP, Azure) restent 2-3x plus élevés.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_ce_que_jai_exclu_et_pourquoi">Ce Que J’ai Exclu (et Pourquoi)</h3> <div class="paragraph"> <p>J’ai volontairement exclu les options suivantes de ce benchmark :</p> </div> <div class="ulist"> <ul> <li> <p><strong>API OpenAI / Anthropic / Google</strong> : le sujet ici est de faire tourner des modèles <strong>open-source</strong> qu’on peut choisir, fine-tuner, et ne pas être dépendant d’un vendor unique</p> </li> <li> <p><strong>Huawei Ascend / Atlas</strong> : Huawei ne commercialise pas d’équivalent desktop au DGX Spark. La gamme Ascend (910C, 910D) et Atlas (300I Duo, 350) est orientée datacenter — cartes PCIe, serveurs rack — pas des boîtiers compacts prêts à brancher. La puce Ascend 910C embarque 128 Go HBM mais c’est une puce serveur, pas un système autonome. L’Atlas 300I Duo offre 96 Go pour ~$1 400 mais nécessite une machine hôte</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_inférence_simple_la_mort_du_hardware_local">Inférence Simple : La Mort du Hardware Local</h2> <div class="sectionbody"> <div class="paragraph"> <p>Commençons par le cas d’usage le plus commun : chatter avec un LLM, faire du code review, générer du texte. Pas de fine-tuning, pas de batch processing, juste de l’inférence interactive.</p> </div> <div class="sect2"> <h3 id="_le_calcul">Le Calcul</h3> <div class="paragraph"> <p>Un DGX Spark à $4 699. Divisons par le coût annuel de chaque abonnement :</p> </div> <div id="diag-breakeven" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-7447dcff18600cfcdb05c5212204ea1f.svg" alt="Seuil de rentabilité du DGX Spark vs abonnements" width="837" height="219"> </div> </div> <div class="paragraph"> <p>Le verdict est brutal. Pour de l’inférence :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong> : il vous faudrait <strong>23 ans</strong> pour amortir un DGX Spark. Le Spark sera obsolète depuis 20 ans.</p> </li> <li> <p><strong>Ollama Max</strong> : <strong>4 ans</strong> — à condition d’utiliser le Spark 24/7, ce que personne ne fait</p> </li> <li> <p><strong>Claude Pro</strong> : même problème, <strong>20 ans</strong> pour du single-model fermé</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ La promesse du « supercalculateur IA de bureau » se heurte à une réalité comptable élémentaire : $4 699 / $20 par mois = jamais rentable pour un usage individuel. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_même_avec_un_usage_intensif">Même avec un Usage Intensif</h3> <div class="paragraph"> <p>Prenons le pire scénario pour le cloud : vous faites tourner un H100 8h/jour, 5 jours/semaine, 52 semaines/an.</p> </div> <div class="ulist"> <ul> <li> <p>8 × 5 × 52 = 2 080 heures/an</p> </li> <li> <p>2 080 × $2/h (prix moyen spot H100) = <strong>$4 160/an</strong></p> </li> </ul> </div> <div class="paragraph"> <p>Le Spark ($4 699) est rentabilisé en <strong>13 mois</strong>. Sauf que :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Le H100 est <strong>~10x plus rapide</strong> que le GB10 du Spark. Vous faites en 1h ce que le Spark fait en 10h. Pour le même volume de travail, le H100 vous coûte $416/an, pas $4 160.</p> </li> <li> <p>Le H100 a 80 Go HBM à 3.35 To/s de bande passante. Le Spark a 128 Go LPDDR5X à 273 Go/s. Pour les gros modèles, la bande passante compte plus que la capacité.</p> </li> </ol> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Comparer 1h de H100 à 1h de Spark n’a pas de sens. Le H100 fait le travail 10x plus vite. Le vrai coût cloud pour un workload donné est donc ~10x inférieur au calcul naïf basé sur les heures.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fine_tuning_le_cloud_est_imbattable">Fine-Tuning : Le Cloud Est Imbattable</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’argument classique des défenseurs du Spark : « oui mais pour le fine-tuning, c’est différent ».</p> </div> <div class="paragraph"> <p>Non, ça ne l’est pas.</p> </div> <div class="sect2"> <h3 id="_le_coût_réel_dun_fine_tune">Le Coût Réel d’un Fine-Tune</h3> <div class="paragraph"> <p>Un fine-tune LoRA/QLoRA sur Unsloth d’un modèle 7B :</p> </div> <div class="ulist"> <ul> <li> <p>~2-3h sur un H100 = <strong>$5 à $9</strong></p> </li> <li> <p>Même chose sur le Spark = <strong>20-30h</strong> (10x plus lent), bloque la machine</p> </li> </ul> </div> <div class="paragraph"> <p>Avec les $4 699 du Spark, vous pouvez financer :</p> </div> <div class="ulist"> <ul> <li> <p><strong>~500 à ~900 fine-tunes</strong> en cloud H100</p> </li> <li> <p>Ou <strong>~23 ans</strong> d’Ollama Pro</p> </li> <li> <p>Ou <strong>~4 ans</strong> d’Ollama Max</p> </li> </ul> </div> <div class="paragraph"> <p>Et pour des modèles plus gros (70B+) :</p> </div> <div class="ulist"> <ul> <li> <p>Le Spark avec ses 128 Go peut charger un 70B en Q4 — mais le fine-tune sera extrêmement lent</p> </li> <li> <p>Un H100 avec 80 Go peut fine-tuner un 70B en QLoRA 4-bit en quelques heures</p> </li> <li> <p>Pour du full fine-tune, il faut du multi-GPU de toute façon — le Spark est hors course</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_les_acteurs_spécialisés">Les Acteurs Spécialisés</h3> <div class="paragraph"> <p>En 2026, des plateformes comme Unsloth, Modal, Replicate, et Together AI proposent du fine-tuning serverless :</p> </div> <div class="ulist"> <ul> <li> <p>Pas de gestion de GPU</p> </li> <li> <p>Pas de configuration d’environnement</p> </li> <li> <p>Paiement à la minute</p> </li> <li> <p>Optimisations intégrées (flash attention, quantization automatique)</p> </li> </ul> </div> <div id="diag-fine-tuning-cost" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-00c27fa5b17d5b1836d28ea44e7aa323.svg" alt="Comparaison des coûts de fine-tuning" width="626" height="244"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_seule_vraie_raison_la_souveraineté_des_données">La Seule Vraie Raison : La Souveraineté des Données</h2> <div class="sectionbody"> <div class="paragraph"> <p>Après avoir éliminé l’inférence, le fine-tuning, et le rapport qualité/prix — que reste-t-il au Spark ?</p> </div> <div class="paragraph"> <p><strong>La confidentialité absolue.</strong></p> </div> <div class="paragraph"> <p>Pas la confidentialité « je ne veux pas que mes prompts soient lus par un employé d’OpenAI ». Ça, c’est un faux problème en 2026 : Ollama, Groq, et la plupart des providers respectables ont des politiques de zéro log et zéro rétention.</p> </div> <div class="paragraph"> <p>La vraie confidentialité, c’est :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Air-gap réglementaire</strong> : défense, diplomatie, santé — les données ne peuvent <strong>physiquement</strong> pas quitter le bâtiment</p> </li> <li> <p><strong>Données propriétaires critiques</strong> : code source d’un produit non publié, secrets industriels, algorithmes de trading</p> </li> <li> <p><strong>Résilience réseau</strong> : l’IA doit continuer à fonctionner même si Internet tombe</p> </li> </ul> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>Mais soyons honnêtes : quel pourcentage des acheteurs de DGX Spark est réellement dans ce cas ? 1% ? Le reste, c’est du « nice to have » transformé en dépense à $4 699.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_le_vrai_calcul_de_la_confidentialité">Le Vrai Calcul de la Confidentialité</h3> <div class="paragraph"> <p>Pour un usage individuel :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ollama Pro</strong> ($20/mois) + modèles open source chinois = solution pragmatique</p> </li> <li> <p>Si un prompt fuit chez Ollama, il se noie dans les millions de requêtes quotidiennes. C’est la goutte d’eau dans l’océan.</p> </li> <li> <p>Le risque réel n’est pas la fuite d’un prompt — c’est l’entraînement non consenti sur vos données. Et ça, les providers sérieux l’interdisent contractuellement.</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ La peur de « distiller son prompt dans le LLM » est un niveau de propagation d’information personnel tellement dilué qu’il relève plus de l’anxiété que de la menace réelle. À l’échelle industrielle, c’est différent. Mais à l’échelle individuelle, c’est du bruit. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_synthèse_la_matrice_de_décision">Synthèse : La Matrice de Décision</h2> <div class="sectionbody"> <div id="diag-decision-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-06638fe7c7dbec3c1cf02043ac672e9a.svg" alt="Matrice de décision pour choisir sa solution LLM" width="2012" height="433"> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2222%;"> <col style="width: 2.2232%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Critère</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Free</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ollama Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cloud GPU H100</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DGX Spark</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Inférence</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Limitée</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Confortable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Overkill</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Lent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Fine-tuning</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Imbattable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Possible mais lent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coût annuel</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$200</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variable (~$416-2 080*)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">$4 699 upfront</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Confidentialité</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Cloud US</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Cloud US</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">⚠️ Cloud US (variable)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Totale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Maintenance</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucune</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucune</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Setup unique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Électricité, mises à jour</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Obsolescence</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucune</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucune</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucune</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3-5 ans</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Écosystème logiciel</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous modèles open</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CUDA (mais lent)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Veridict</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Occasionnel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Recommandé</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pros/Recherche</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Air-gap uniquement</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Variable selon volume de travail ; avec vitesse H100 ~10x > Spark, le coût effectif pour un workload donné est bas.</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_le_cas_particulier_labonnement_pro_face_aux_modèles_chinois">Le Cas Particulier : L’Abonnement Pro Face aux Modèles Chinois</h2> <div class="sectionbody"> <div class="paragraph"> <p>Un point mérite d’être souligné : la combinaison <strong>Ollama Pro à $20/mois + modèles chinois open-source</strong> est probablement le meilleur rapport qualité/prix de l’histoire de l’IA grand public.</p> </div> <div class="sect2"> <h3 id="_pourquoi_les_modèles_chinois_changent_tout">Pourquoi les Modèles Chinois Changent Tout</h3> <div class="ulist"> <ul> <li> <p><strong>DeepSeek-V4-Pro</strong> : 1.6T params, CSA+HCA, 1M contexte, compétitif avec Claude 4 et GPT-5 pour le code</p> </li> <li> <p><strong>Qwen-3</strong> : 235B, 256K contexte, excellent en français et en raisonnement</p> </li> <li> <p><strong>GLM-5.1</strong> : 744B, MLA+DSA, 200K contexte, taillé pour l’agentique</p> </li> </ul> </div> <div class="paragraph"> <p>Tous disponibles sur Ollama. Tous open-source (licences permissives). Tous utilisables sans restriction via un abonnement à $20/mois.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Avec Ollama Pro, vous avez accès à ~5 modèles « frontier » open-source pour le prix d’un seul modèle fermé (Claude Pro). La valeur est tellement asymétrique que ça en devient presque absurde.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_ce_que_ça_veut_dire_pour_le_hardware">Ce Que Ça Veut Dire pour le Hardware</h3> <div class="paragraph"> <p>Si le meilleur rapport qualité/prix est un abonnement cloud à $20/mois, le hardware local devient un choix de <strong>confort</strong> ou de <strong>principe</strong> — pas un choix économique.</p> </div> <div class="paragraph"> <p>Un DGX Spark à $4 699, c’est l’équivalent de :</p> </div> <div class="ulist"> <ul> <li> <p>235 mois d’Ollama Pro</p> </li> <li> <p>23 jeux AAA jour de sortie</p> </li> <li> <p>4 MacBook Air M4</p> </li> <li> <p>Un an de loyer d’un T2 à Lyon</p> </li> </ul> </div> <div class="paragraph"> <p>Pour du calcul. Lent.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_et_huawei">Et Huawei ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Puisque la question m’a été posée pendant mes recherches : non, Huawei ne commercialise pas d’équivalent au DGX Spark.</p> </div> <div class="paragraph"> <p>Ce qui existe :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Ascend 910C</strong> : 128 Go HBM, 800 TFLOPS FP16 — mais c’est une puce serveur, pas un desktop</p> </li> <li> <p><strong>Atlas 300I Duo</strong> : 96 Go LPDDR4X, carte PCIe à ~$1 400 — nécessite un hôte</p> </li> <li> <p><strong>Atlas 350</strong> : 112 Go HBM, 1.56 PFLOPS FP4 — accélérateur datacenter, pas un boîtier compact</p> </li> </ul> </div> <div class="paragraph"> <p>Huawei reste focalisé sur le marché des serveurs et des centres de données. Pour un boîtier compact « prêt à brancher » avec 120+ Go de VRAM, le DGX Spark (128 Go unifié) et le Mac Studio M3 Ultra (192 Go unifié) sont les seules options en 2026. Et pour l’instant, aucun constructeur chinois n’a annoncé de produit équivalent dans ce format.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_le_luxe_de_la_proximité">Conclusion : Le Luxe de la Proximité</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le DGX Spark n’est pas un mauvais produit. C’est un mauvais investissement pour 99% des acheteurs potentiels.</p> </div> <div id="diag-verdict" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-e8d62f731ea78fcb4f2978a3515b59c2.svg" alt="Verdict final — quel modèle économique domine en 2026" width="476" height="617"> </div> </div> <div class="paragraph"> <p><em><em>_ Acheter un DGX Spark en 2026, c’est comme acheter un serveur mail en 2010 : techniquement possible, philosophiquement satisfaisant, économiquement absurde pour un individu. </em>_</em></p> </div> <div class="paragraph"> <p>Le calcul est simple, et il ne ment pas :</p> </div> <div class="ulist"> <ul> <li> <p><strong>$0</strong> pour chatter avec DeepSeek sur Ollama Free</p> </li> <li> <p><strong>$200/an</strong> pour bosser sérieusement avec Ollama Pro</p> </li> <li> <p><strong>$5-9</strong> pour un fine-tune ponctuel sur cloud GPU</p> </li> <li> <p><strong>$4 699</strong> pour…​ l’expérience d’avoir un boîtier NVIDIA sur son bureau ?</p> </li> </ul> </div> <div class="paragraph"> <p>Le marché a tranché. Les abonnements cloud et les modèles open-source chinois ont gagné la bataille du prix. Le hardware local survit dans les niches réglementaires, pas dans les bureaux des développeurs.</p> </div> <div class="paragraph"> <p><em><em>_ Le DGX Spark n’est pas un outil rentable. C’est un statement. « Je veux mon IA chez moi, pas dans le cloud de quelqu’un d’autre. » C’est respectable. Mais en 2026, quand Ollama te donne DeepSeek-V4-Pro dans le cloud pour $20/mois, c’est surtout un statement qui coûte très cher. </em>_</em></p> </div> <hr> <div class="paragraph"> <p><strong>Cet article est issu d’une conversation avec mon agent IA sur la pertinence économique du DGX Spark, croisée avec une veille marché sur les prix cloud GPU (Vast.ai, RunPod), les grilles tarifaires Ollama/Claude, et l’écosystème des modèles chinois open-source. Les prix cités sont ceux de mai 2026 — ils auront probablement encore baissé quand vous lirez ces lignes.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html Mon, 4 May 2026 00:00:00 +0000 blog/2026/0118_matrice_gouvernance_llm_zone_acces_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_problème_le_prompt_engineering_est_un_château_de_sable">Le Problème : le Prompt Engineering est un Château de Sable</a></li> <li><a href="#_ma_réponse_la_matrice_44">Ma Réponse : la Matrice 4×4</a> <ul class="sectlevel2"> <li><a href="#_les_cinq_zones_dimension_spatiale_rgpd">Les Cinq Zones (Dimension Spatiale — RGPD)</a></li> <li><a href="#_la_classification_épistémique_deuxième_dimension">La Classification Épistémique (Deuxième Dimension)</a></li> </ul> </li> <li><a href="#_comment_le_llm_consomme_cette_matrice">Comment le LLM Consomme Cette Matrice</a></li> <li><a href="#_implémentation_tâches_gradle_typées">Implémentation : Tâches Gradle Typées</a></li> <li><a href="#_pourquoi_cest_un_manifeste_pas_juste_une_spec">Pourquoi C’est un Manifeste, Pas Juste une Spec</a></li> <li><a href="#_la_cascade_complète_du_brain_dump_à_larticle_de_blog">La Cascade Complète — du Brain Dump à l’Article de Blog</a></li> <li><a href="#_procontra">Pro/Contra</a></li> <li><a href="#_conclusion_rangez_vos_fichiers_pas_vos_prompts">Conclusion : Rangez vos Fichiers, Pas vos Prompts</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 14 minutes</div> <p>Pendant des mois, j’ai empilé les règles de gouvernance agent. Des fichiers EAGER, des checklists LAZY, des protocoles de fin de session en six étapes. Et pourtant, une question restait en suspens : <strong>comment le LLM sait-il ce qu’il a le droit de faire avec un fichier ?</strong></p> </div> <div class="paragraph"> <p>La réponse n’est pas dans un prompt. Elle est dans le système de fichiers.</p> </div> <div class="paragraph"> <p>Voici la spécification d’architecture qui rend la réponse exploitable — la <strong>matrice de gouvernance LLM</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_problème_le_prompt_engineering_est_un_château_de_sable">Le Problème : le Prompt Engineering est un Château de Sable</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand on donne un fichier à un LLM, on lui donne tout. Le contenu, oui — mais aussi l’absence de garde-fous. Le LLM ne sait pas si ce fichier contient un secret, une opinion spéculative, ou du code closed source. Il va l’indexer, le résumer, le citer, le mélanger avec d’autres données — et potentiellement le publier dans un embedding public ou une réponse utilisateur.</p> </div> <div class="paragraph"> <p>La parade classique, c’est le prompt :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">"Tu es un assistant sécurisé. Ne divulgue jamais d'informations confidentielles. Si tu détectes un secret, ignore-le. Si tu détectes une opinion, ne la répète pas."</code></pre> </div> </div> <div class="paragraph"> <p>Ce prompt a trois problèmes :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Il repose sur la bonne volonté du LLM.</strong> Un modèle assez grand pour</p> </li> </ol> </div> <div class="paragraph"> <p>résoudre des bugs complexes est assez grand pour contourner une instruction de sécurité noyée dans 200k tokens de contexte.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Il est contextuel, pas structurel.</strong> Changez de prompt, changez de LLM,</p> </li> </ol> </div> <div class="paragraph"> <p>changez de session — et la règle disparaît.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Il ne scale pas.</strong> Chaque nouveau type de fichier, chaque nouveau niveau</p> </li> </ol> </div> <div class="paragraph"> <p>de confidentialité exige une nouvelle clause. Votre prompt devient un texte réglementaire que personne ne lit en entier.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>La sécurité d’un système ne doit jamais dépendre d’une instruction qu’on peut oublier, contourner, ou ne pas charger. Elle doit dépendre d’une barrière qu’on ne peut pas franchir sans le vouloir explicitement.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_ma_réponse_la_matrice_44">Ma Réponse : la Matrice 4×4</h2> <div class="sectionbody"> <div class="paragraph"> <p>La solution que j’ai implémentée dans mon workspace est une <strong>matrice zone × droit d’accès LLM</strong>. Elle ne demande pas au LLM d’être prudent. Elle rend l’imprudence structurellement impossible.</p> </div> <div id="diag-matrix-overview" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-ff423528a76bb0bbfad06b9abbd23331.svg" alt="Vue d’ensemble de la matrice de gouvernance LLM — 5 zones × 4 droits d’accès" width="469" height="800"> </div> </div> <div class="sect2"> <h3 id="_les_cinq_zones_dimension_spatiale_rgpd">Les Cinq Zones (Dimension Spatiale — RGPD)</h3> <div class="paragraph"> <p>Chaque zone du workspace a un niveau RGPD qui détermine <strong>où</strong> le fichier peut être routé :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1666%;"> <col style="width: 4.1682%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zone</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Niveau RGPD</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contenu</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Droit d’accès RAG public</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Racine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">0 — Intime</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Brain dumps, conversations LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>INTERDIT</strong> — jamais indexé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>configuration/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1 — Restreint propriétaire</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Secrets, tokens, clés API</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>INTERDIT</strong> — jamais indexé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>office/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2 — Restreint collaboratif</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Data éditoriale, cadrage, formations</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>FILTRÉ</strong> — Vision uniquement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/private/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 — Ouvert conditionnel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Code closed source, SaaS non public</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>INTERDIT</strong> — dataset privé exclusivement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/public/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4 — Public natif</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Code Apache 2.0, plugins publiés</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>LIBRE</strong> — indexation complète</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>La règle est simple : <strong>le chemin du fichier détermine ce que le LLM peut en faire.</strong> Pas de métadonnées à maintenir, pas de tag à ajouter dans le frontmatter, pas de classification manuelle à chaque commit. Le fichier est dans <code>OSS/</code> ? Il est public. Il est dans <code>configuration/</code> ? Il est intouchable.</p> </div> </div> <div class="sect2"> <h3 id="_la_classification_épistémique_deuxième_dimension">La Classification Épistémique (Deuxième Dimension)</h3> <div class="paragraph"> <p>La dimension spatiale dit <strong>où</strong> router. Mais il y a un deuxième axe, perpendiculaire : <strong>quoi</strong> router. Certains fichiers dans une zone autorisée contiennent des informations qui ne devraient pas être diluées telles quelles :</p> </div> <div id="diag-epistemic-filter" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-768538851f5f36f6e05c445dd02dc3ed.svg" alt="Filtre épistémique Vision/Opinion/Stratégie appliqué aux zones 2 et 3" width="1215" height="558"> </div> </div> <div class="paragraph"> <p>La grille de classification épistémique, gravée en Règle 2bis de ma gouvernance agent :</p> </div> <div class="paragraph"> <p>| Statut | Définition | Signal LLM | Destination | | VISION | Architecture stabilisée, pattern testé | Langage déclaratif, références sessions/tests | Dilution complète + Blog | | STRATÉGIE | Positionnement business, pricing | Vocabulaire marché, concurrence | Docs racine uniquement | | OPINION | Spéculation, hypothèse non validée | Langage hypothétique, intuition | Confinement Cercle 0 |</p> </div> <div class="paragraph"> <p>La combinaison des deux dimensions — zone physique × classification épistémique — forme la <strong>matrice complète</strong> :</p> </div> <div id="diag-full-matrix" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-f6f9959b0f07e3bff0bf64c8e1c20ea4.svg" alt="La matrice complète : 5 zones × 3 classifications épistémiques" width="442" height="132"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_comment_le_llm_consomme_cette_matrice">Comment le LLM Consomme Cette Matrice</h2> <div class="sectionbody"> <div class="paragraph"> <p>La matrice n’est pas un document que le LLM lit. C’est une <strong>contrainte implicite</strong> encodée dans le vecteur composite de contexte (EPIC 9 — en cours d’implémentation).</p> </div> <div class="paragraph"> <p>Voici ce que le LLM reçoit à chaque session :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">VECTEUR COMPOSITE DE CONTEXTE ├── RAG pgvector → OSS/ + office/Vision │ (similarité sémantique sur contenu publiable) ├── Knowledge Graph graphify → OSS/ │ (relations exactes entre artéfacts publics) ├── Knowledge Graph privé → CSS/ │ (relations entre code closed source — jamais exporté) ├── Métadonnées de zone → chaque fichier taggé par zone physique │ (le LLM sait s'il est dans office/ ou OSS/) └── Historique des décisions → WORKSPACE_VISION.adoc (contexte temporel des arbitrages)</code></pre> </div> </div> <div class="paragraph"> <p>Concrètement, quand le LLM me dit :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Je vais indexer le contenu de edster/ pour enrichir le knowledge graph...</code></pre> </div> </div> <div class="paragraph"> <p>La métadonnée de zone répond avant même que le LLM ne finisse sa phrase : <code>edster/</code> est dans <code>CSS/</code>, niveau 3 → <strong>accès interdit au knowledge graph public.</strong> Le RAG ne le voit pas. Le graphe ne le touche pas. La réponse utilisateur ne le cite pas.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>L’ontologie spatiale fonctionne comme une <strong>permission Unix</strong> pour les LLM. Vous ne demandez pas à un processus d’être prudent avec <code>/etc/shadow</code> — vous lui refusez l’accès en lecture. Même principe.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_implémentation_tâches_gradle_typées">Implémentation : Tâches Gradle Typées</h2> <div class="sectionbody"> <div class="paragraph"> <p>La matrice n’est pas une philosophie. C’est du code. Voici le contrat de tâche Gradle qui l’implémente :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class ZoneAwareIndexer @Inject constructor( private val rootDir: DirectoryProperty, private val configServer: ConfigServerProperty // → configuration/ ) : DefaultTask() { @Input val zoneFilter: SetProperty<Zone> = project.objects.setProperty(Zone::class.java) @OutputFile val ragIndex: RegularFileProperty = project.objects.fileProperty() @TaskAction fun index() { val allowedPaths = zoneFilter.get().flatMap { it.resolve(rootDir.get()) } val forbiddenPaths = Zone.RESTRICTED.resolve(rootDir.get()) + Zone.INTIMATE.resolve(rootDir.get()) // Le RAG ne voit jamais configuration/ ni la racine // CSS/ alimente un index privé, pas celui-ci // office/ est filtré par le classifieur Vision/Opinion } } enum class Zone { INTIMATE, // Cercle 0 — racine RESTRICTED, // Cercle 1 — configuration/ EDITORIAL, // Cercle 2 — office/ CLOSED_SOURCE, // Cercle 3 — foundry/private/ OPEN_SOURCE // Cercle 3 — foundry/public/ }</code></pre> </div> </div> <div class="paragraph"> <p>La tâche est <strong>testable</strong>. Vous pouvez écrire un test qui vérifie :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `le RAG n'indexe jamais configuration`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE, Zone.EDITORIAL)) index.index() assertThat(index.ragIndex).doesNotContain("configuration/") } @Test fun `le code closed source est exclu du RAG public`() { val index = ZoneAwareIndexer(rootDir, configServer) index.zoneFilter.set(setOf(Zone.OPEN_SOURCE)) // OSS only assertThat(index.ragIndex).doesNotContain("edster") }</code></pre> </div> </div> <div class="paragraph"> <p>380 tests, 380 PASS. Comme pour plantuml-gradle — la sécurité est testée, pas espérée.</p> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_cest_un_manifeste_pas_juste_une_spec">Pourquoi C’est un Manifeste, Pas Juste une Spec</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce document est une spécification d’architecture parce qu’il définit :</p> </div> <div class="ulist"> <ul> <li> <p>Des <strong>dimensions</strong> (spatiale, épistémique)</p> </li> <li> <p>Des <strong>règles déterministes</strong> (zone → droit d’accès)</p> </li> <li> <p>Un <strong>contrat de tâche</strong> (Gradle typé, testable)</p> </li> <li> <p>Une <strong>implémentation de référence</strong> (mon workspace)</p> </li> </ul> </div> <div class="paragraph"> <p>Mais c’est aussi un <strong>manifeste</strong> parce qu’il prend position sur un débat plus large : <strong>comment gouverner l’accès d’un LLM à des données ?</strong></p> </div> <div class="paragraph"> <p>La réponse de l’industrie, c’est le prompt engineering + les guardrails<br> les classifiers post-hoc. Ma réponse, c’est : <strong>rangez vos fichiers dans les bons dossiers.</strong> Le reste est automatique.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Ce manifeste ne dit pas "les LLM doivent être alignés". Il dit : "l’alignement d’un LLM sur vos règles de sécurité est une conséquence de votre système de fichiers, pas de votre prompt."</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_la_cascade_complète_du_brain_dump_à_larticle_de_blog">La Cascade Complète — du Brain Dump à l’Article de Blog</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pour illustrer le cycle complet, voici comment cette idée de matrice est née et a été diluée :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Session 4 mai 2026 — Feedback global du workspace │ ├→ Le LLM identifie : "la dualité public/privé est invisible" │ → Classifié VISION (constat architectural vérifiable) │ ├→ PICTURE_ME_ROLLIN_MATRICE_4X4.adoc — STIMULUS (Cercle 0) │ → Brain dump structuré, classification VISION confirmée │ ├→ DILUTION → WORKSPACE_AS_PRODUCT.adoc (section Matrice 4×4) │ → La spec vit dans les documents racine │ ├→ DILUTION → WORKSPACE_ORGANIZATION.adoc (OSS/CSS) │ → La granularisation est documentée │ └→ ARTICLE 0117 (ce document) → cheroliv.com → La VISION est publiée</code></pre> </div> </div> <div class="paragraph"> <p>Ce qui a commencé comme une observation en session ("hé, le RAG ne sait pas que edster est closed source") est devenu une spécification d’architecture publiée en moins d’une session. C’est le pattern STIMULUS en action.</p> </div> </div> </div> <div class="sect1"> <h2 id="_procontra">Pro/Contra</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Cette Approche (Ontologie Spatiale + Matrice)</th> <th class="tableblock halign-left valign-top">L’Approche Classique (Prompt + Guardrails)</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Mécanique</strong> — le système de fichiers bloque l’accès, pas le LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Déclarative</strong> — le prompt demande au LLM d’être prudent</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Testable</strong> — le contrat de tâche Gradle est vérifié par 380+ tests</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non testable</strong> — "le LLM a-t-il respecté la règle ?" est une question ouverte</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Indépendante du LLM</strong> — changez de modèle, les dossiers restent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Dépendante du LLM</strong> — chaque modèle interprète le prompt différemment</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Scalable</strong> — nouveau type de données = nouveau dossier, zéro changement de code</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non scalable</strong> — nouveau type de données = nouvelle clause de prompt, nouveau risque de régression</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Auditable</strong> — le système de fichiers est l’audit trail</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non auditable</strong> — le prompt n’a pas d’historique, pas de diff, pas de blame</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Contrainte</strong> : exige une discipline d’organisation initiale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Contrainte</strong> : exige une discipline de rédaction de prompt à chaque session</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusion_rangez_vos_fichiers_pas_vos_prompts">Conclusion : Rangez vos Fichiers, Pas vos Prompts</h2> <div class="sectionbody"> <div class="paragraph"> <p>La matrice de gouvernance LLM que je viens de décrire n’est pas un produit. C’est une <strong>spécification d’architecture</strong> — et c’est pour ça qu’elle est publiable.</p> </div> <div class="paragraph"> <p>Ce qui la rend robuste, c’est qu’elle ne demande rien au LLM. Elle ne lui fait pas confiance. Elle ne repose pas sur son alignement, sa compréhension du français, ou sa bonne volonté. Elle repose sur le système de fichiers — la couche la plus basse, la plus stable, la plus testée de toute la stack.</p> </div> <div class="paragraph"> <p>Quand je dis à mon LLM "tu peux tout indexer dans <code>OSS/</code>, rien dans <code>configuration/</code>, et <code>office/</code> seulement si c’est classifié Vision" — ce n’est pas une instruction. C’est un <strong>filtre</strong> — implémenté en Kotlin, vérifié par 380 tests, exécuté avant que le LLM ne voie les données.</p> </div> <div class="paragraph"> <p>C’est la différence entre dire à quelqu’un "ne regarde pas dans ce tiroir" et fermer le tiroir à clé. La gouvernance agent que je construis depuis des mois est la clé. La matrice est le plan du meuble.</p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — Le Compartimentage Épistémique Automatisé</a></p> </li> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Article 0114 — Les Cercles de Confiance et l’Ontologie Spatiale</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Gouverner un Agent IA avec du AsciiDoc</a></p> </li> <li> <p><a href="../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html">Article 0115 — L’Anonymiseur MVP0</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html Sun, 3 May 2026 00:00:00 +0000 blog/2026/0117_granularisation_oss_css_repositorie_workspace_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_laccident_qui_attendait_de_se_produire">L’Accident qui Attendait de se Produire</a> <ul class="sectlevel2"> <li><a href="#_la_vraie_question">La Vraie Question</a></li> </ul> </li> <li><a href="#_la_solution_oss_et_css">La Solution : OSS/ et CSS/</a></li> <li><a href="#_pourquoi_oss_et_css_et_pas_public_et_private">Pourquoi "OSS" et "CSS" et Pas "Public" et "Private"</a> <ul class="sectlevel2"> <li><a href="#_larbre_complet_quatre_zones_pas_trois">L’Arbre Complet — Quatre Zones, Pas Trois</a></li> </ul> </li> <li><a href="#_le_cas_particulier_cheroliv_com">Le Cas Particulier : cheroliv.com</a> <ul class="sectlevel2"> <li><a href="#_bakery_gradle_sen_fiche">bakery-gradle S’En Fiche</a></li> </ul> </li> <li><a href="#_impact_sur_la_gouvernance_agent">Impact sur la Gouvernance Agent</a></li> <li><a href="#_ce_quon_gagne_et_ce_quon_perd">Ce Qu’on Gagne (Et Ce Qu’on Perd)</a></li> <li><a href="#_conclusion_le_signal_physique_bat_le_signal_logiciel">Conclusion : le Signal Physique Bat le Signal Logiciel</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 10 minutes</div> <p><code>foundry/</code> — la zone fonctionnelle qui héberge le code de mon workspace — contient 18 projets. Huit sont open source sous Apache 2.0. Un seul est closed source — le SaaS Edster. Pendant des mois, ces neuf projets ont cohabité dans le même dossier, séparés uniquement par…​ rien. Leur statut public/privé était une information dans ma tête, pas dans le système de fichiers.</p> </div> <div class="paragraph"> <p>Et puis j’ai voulu brancher un RAG. Et là, tout s’est effondré.</p> </div> </div> </div> <div class="sect1"> <h2 id="_laccident_qui_attendait_de_se_produire">L’Accident qui Attendait de se Produire</h2> <div class="sectionbody"> <div class="paragraph"> <p>En avril 2026, j’ai commencé à implémenter le RAG pgvector pour slider-gradle. Le principe : indexer tous les dépôts de <code>foundry/</code>, produire des embeddings, et les injecter dans le contexte du LLM pour qu’il ait une "perception" du dossier <code>foundry/</code>.</p> </div> <div class="paragraph"> <p>Le pipeline était simple :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val repos = fileTree(rootDir) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val chunks = repos.map { chunk(it) } val embeddings = chunks.map { embed(it) } pgvector.insert(embeddings)</code></pre> </div> </div> <div class="paragraph"> <p>Simple. Efficace. Et <strong>dangereux</strong>.</p> </div> <div class="paragraph"> <p>Parce que ce <code>fileTree</code> ne fait pas la différence entre <code>plantuml-gradle/</code> (Apache 2.0, public) et <code>edster/</code> (closed source, private). Il avale tout. Et si un jour je publie ces embeddings — sur un dashboard, dans une réponse LLM, dans un dataset d’entraînement — le code propriétaire d’Edster fuit.</p> </div> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>Le problème n’est pas qu’un LLM lise du code closed source. Le problème, c’est que ce code finisse dans un embedding vectoriel <strong>public</strong> — irréversible, non supprimable, non auditable.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_la_vraie_question">La Vraie Question</h3> <div class="paragraph"> <p>Ce n’est pas "comment empêcher le LLM de fuiter du code ?". C’est "comment rendre la fuite structurellement impossible ?"</p> </div> <div class="paragraph"> <p>La réponse n’est pas un prompt. La réponse, c’est de couper le dossier en deux.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solution_oss_et_css">La Solution : OSS/ et CSS/</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── plantuml-gradle/ ← public ├── bakery-gradle/ ← public ├── magic-stick/ ← public ├── edster/ ← PRIVÉ ├── slider-gradle/ ← public └── ... ← mélange invisible</code></pre> </div> </div> <div class="paragraph"> <p>Après :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">foundry/ ├── OSS/ ← tout est Apache 2.0 │ ├── plantuml-gradle/ │ ├── bakery-gradle/ │ ├── magic-stick/ │ ├── slider-gradle/ │ └── ... └── CSS/ ← tout est closed source / private └── edster/</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>fileTree</code> devient :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val ossRepos = fileTree(File(rootDir, "OSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } val cssRepos = fileTree(File(rootDir, "CSS")) { include("**/*.adoc", "**/*.kts", "**/*.kt", "**/*.json", "**/*.yml") } // Embeddings publics — OSS seulement pgvectorPublic.insert(ossRepos.map { chunk(it) }.map { embed(it) }) // Dataset fine-tuning privé — CSS seulement fineTuningDataset.insert(cssRepos.map { chunk(it) }) // jamais publié</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Le RAG public ne voit jamais <code>CSS/</code>. Le code closed source alimente un dataset privé de fine-tuning — un modèle interne qui ne sort jamais de chez moi. La séparation est mécanique, pas déclarative.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_oss_et_css_et_pas_public_et_private">Pourquoi "OSS" et "CSS" et Pas "Public" et "Private"</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le choix des acronymes OSS (Open Source Software) et CSS (Closed Source Software) est délibéré :</p> </div> <div class="ulist"> <ul> <li> <p>"Public"/"Private" décrit la <strong>visibilité</strong> (ce que GitHub voit)</p> </li> <li> <p>"OSS"/"CSS" décrit la <strong>nature</strong> du code (ce que le LLM doit savoir)</p> </li> </ul> </div> <div class="paragraph"> <p>La visibilité GitHub est une métadonnée du repo distant. La nature du code est une propriété du contenu. Le LLM n’a pas accès à l’API GitHub — mais il a accès au système de fichiers. <code>CSS/</code> lui dit "attention, ce code n’est pas sous licence libre" sans avoir besoin de lire un <code>LICENSE</code> ou de parser un <code>package.json</code>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="💡"></i> </td> <td class="content"> <div class="paragraph"> <p>Le nom du dossier est la métadonnée la plus robuste que vous puissiez donner à un LLM. Elle ne peut pas être mal parsée, ignorée, ou mal interprétée. Le LLM voit <code>CSS/edster/</code> dans le chemin du fichier — il sait.</p> </div> </td> </tr> </table> </div> <div class="sect2"> <h3 id="_larbre_complet_quatre_zones_pas_trois">L’Arbre Complet — Quatre Zones, Pas Trois</h3> <div class="paragraph"> <p>La granularisation OSS/CSS complète l’ontologie à trois zones. La zone <code>foundry/</code> passe de 1 à 2 sous-zones fonctionnelles :</p> </div> <div id="diag-four-zone-workspace" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-69dfc4d88e57c2bbc80fff055ca536cd.svg" alt="L’organisation de foundry/ en deux sous-zones OSS et CSS" width="1763" height="5763"> </div> </div> <div class="paragraph"> <p>| Zone | RGPD | Indexation RAG public | Dataset fine-tuning | | Racine | Niveau 0 — Intime | ✗ | ✗ | | <code>configuration/</code> | Niveau 1 — Restreint | ✗ | ✗ | | <code>office/</code> | Niveau 2 — Collaboratif | ✓ Filtré | ✓ Filtré | | <code>foundry/private/</code> | Niveau 3 — Ouvert conditionnel | ✗ | ✓ Privé | | <code>foundry/public/</code> | Niveau 4 — Public natif | ✓ Libre | ✓ Public |</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_cas_particulier_cheroliv_com">Le Cas Particulier : cheroliv.com</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pendant que j’y étais, j’ai corrigé une autre incohérence. Mon site <code>cheroliv.com</code> vivait dans <code>foundry/</code> comme un projet logiciel à part entière — avec son propre build Gradle, sa propre CI, sa propre gouvernance <code>.agents/</code>.</p> </div> <div class="paragraph"> <p>Mais les articles de blog ne sont pas du code. Ce sont des <strong>données éditoriales</strong> de Cercle 2 — au même titre que les cadrages de <code>office/pilotage/</code> ou les formations de <code>office/formations/</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">AVANT APRÈS foundry/ office/ cheroliv.com/ sites/ site/jbake/content/blog/ cheroliv.com/ 2026/0117_....adoc 2026/0117_....adoc</code></pre> </div> </div> <div class="paragraph"> <p>Ce qui change :</p> </div> <div class="ulist"> <ul> <li> <p>Les articles sont dans <code>office/</code> → confidentialité de Cercle 2</p> </li> <li> <p>La tâche <code>publishSite</code> devient une capability de <code>engine</code></p> </li> </ul> </div> <div class="paragraph"> <p>via <code>bakery-gradle</code> — le plugin reçoit un <code>FileTree</code>, il ne sait pas que les articles viennent de <code>office/</code></p> </div> <div class="ulist"> <ul> <li> <p>Une seule CI, une seule gouvernance — zéro duplication</p> </li> <li> <p>Le classifier Vision/Opinion (Règle 2bis) s’applique automatiquement :</p> </li> </ul> </div> <div class="paragraph"> <p>les articles dans <code>office/</code> sont filtrés avant publication</p> </div> <div class="sect2"> <h3 id="_bakery_gradle_sen_fiche">bakery-gradle S’En Fiche</h3> <div class="paragraph"> <p>Et c’est ça qui est beau. Le plugin <code>bakery-gradle</code> n’a pas été modifié. Il reçoit un répertoire de contenu AsciiDoc, il génère du HTML, il push sur GitHub Pages. Que ce répertoire s’appelle <code>site/jbake/content/</code> ou <code>office/sites/cheroliv/</code> — le plugin s’en fout.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// engine/build.gradle.kts task("publishBlog") { doLast { val articles = fileTree("../../office/sites/cheroliv/2026/") bakery.generate(articles) // ← bakery ne sait pas d'où ça vient } }</code></pre> </div> </div> <div class="paragraph"> <p>Le contrat d’interface est une tâche Gradle. Pas une API REST. Pas un webhook. Une tâche — typée, testable, exécutable en local et dans la CI.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_impact_sur_la_gouvernance_agent">Impact sur la Gouvernance Agent</h2> <div class="sectionbody"> <div class="paragraph"> <p>La granularisation OSS/CSS modifie la gouvernance agent sur trois points :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>RAG public</strong> : le périmètre d’indexation passe de <code>foundry/**</code></p> </li> </ol> </div> <div class="paragraph"> <p>à <code>foundry/public/<strong></code> + <code>office/Vision/</strong></code>. Le code closed source est exclu de l’index par configuration de tâche, pas par prompt.</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Knowledge Graph</strong> : graphify-gradle produit deux graphes :</p> <div class="ulist"> <ul> <li> <p><code>office/graph.json</code> (public) — relations entre artéfacts OSS + office/Vision * <code>configuration/graph_private.json</code> (gitignored, privé) — relations entre artéfacts CSS, jamais publié</p> </li> </ul> </div> </li> <li> <p><strong>Dataset fine-tuning</strong> : <code>codebase-gradle</code> a désormais deux sources :</p> <div class="ulist"> <ul> <li> <p><code>OSS/</code> → datasets publics (modèles communautaires, benchmarks) * <code>CSS/</code> → datasets privés (modèle interne, fine-tuning propriétaire)</p> </li> </ul> </div> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_ce_quon_gagne_et_ce_quon_perd">Ce Qu’on Gagne (Et Ce Qu’on Perd)</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1436%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Avant (dossier plat)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Après (OSS/CSS + office/sites)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/</code> → mélange public/privé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ls foundry/public/</code> → tout est publiable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG indexe tout sans discrimination</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">RAG indexe <code>OSS/</code> + <code>office/Vision</code> exclusivement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Impossible de savoir si un projet est open source</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le chemin <code>OSS/</code> ou <code>CSS/</code> le dit</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com a sa propre CI, sa propre gouvernance</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">La CI et la gouvernance sont mutualisées dans engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Les articles de blog sont dans un dépôt "code"</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Les articles de blog sont dans <code>office/sites/</code> — data, pas code</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Risque de fuite de code closed source dans des embeddings publics</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Structurellement impossible — <code>CSS/</code> hors scope RAG</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le seul coût : un <code>git mv</code> global sur les 17 dépôts OSS + un refactor du <code>build.gradle.kts</code> de <code>engine</code>. C’est une migration à froid — pas de données en vol, pas d’utilisateurs impactés.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_le_signal_physique_bat_le_signal_logiciel">Conclusion : le Signal Physique Bat le Signal Logiciel</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce que j’ai fait cet après-midi, c’est remplacer une convention invisible par une séparation visible dans la zone <code>foundry/</code>. Avant, vous deviez <strong>savoir</strong> que <code>edster/</code> était closed source. Maintenant, vous le <strong>voyez</strong> — le dossier s’appelle <code>CSS/</code>.</p> </div> <div class="paragraph"> <p>C’est le même principe que les permissions Unix, les VLAN réseau, ou les compartiments coupe-feu dans une base de données. La sécurité ne doit pas être une information que vous devez retenir. Elle doit être une propriété <strong>physique</strong> du système.</p> </div> <div class="paragraph"> <p>La granularisation OSS/CSS est la traduction de ce principe dans le domaine de la gouvernance LLM. Le LLM n’a pas besoin de savoir qu’Edster est confidentiel. Il a besoin d’être incapable de l’indexer.</p> </div> <div class="paragraph"> <p>Et c’est exactement ce que <code>CSS/</code> garantit.</p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="0118_matrice_gouvernance_llm_zone_acces_workspace_post.html">Article 0117 — La Matrice de Gouvernance LLM</a></p> </li> <li> <p><a href="0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html">Article 0114 — Les Cercles de Confiance</a></p> </li> <li> <p><a href="0116_compartimentage_epistemique_automatise_llm_post.html">Article 0116 — Le Compartimentage Épistémique Automatisé</a></p> </li> <li> <p><a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Article 0108 — Gouverner un Agent IA avec du AsciiDoc</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html Sat, 2 May 2026 00:00:00 +0000 blog/2026/0116_compartimentage_epistemique_automatise_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_problème_penser_librement_sans_publier_nimporte_quoi">Le Problème : Penser Librement sans Publier N’Importe Quoi</a></li> <li><a href="#_le_pattern_stimulus_naître_fixer_diluer_mourir">Le Pattern STIMULUS — Naître, Fixer, Diluer, Mourir</a></li> <li><a href="#_la_délégation_au_llm_pourquoi_cest_le_llm_qui_filtre">La Délégation au LLM : Pourquoi C’est le LLM Qui Filtre</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 10 minutes</div> <p>Mon LLM ne se contente pas d’exécuter mes tâches Gradle. Il est le gardien de la frontière entre ma pensée privée et mon expression publique. Chaque idée est classifiée — Vision, Opinion, Stratégie — avant d’être routée. Voici comment ce compartimentage épistémique automatisé protège mon jardin mental sans me faire taire.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_le_problème_penser_librement_sans_publier_nimporte_quoi">Le Problème : Penser Librement sans Publier N’Importe Quoi</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand un développeur solo documente son processus de pensée avec un LLM, il se heurte à un paradoxe :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CAPTURE TOUT (Cercle 0, jardin secret) ├→ Brain dump libre, pas de censure ├→ Idées brutes, spéculations, intuitions non vérifiées ├→ Allers-retours LLM : challenger, itérer, raffiner └→ Le LLM voit TOUT — le bon, le flou, l'embryonnaire PUBLICATION SÉLECTIVE (Cercle 4, blog public) ├→ Uniquement les décisions actées ├→ Uniquement les patterns testés (>100 tests PASS) ├→ Uniquement ce qui a de la valeur pour le lecteur └→ JAMAIS une spéculation présentée comme une vérité</code></pre> </div> </div> <div class="paragraph"> <p>Entre ces deux extrêmes, il y a un <strong>filtre</strong>. La question est : qui le fait ? Un humain fatigué en fin de session ? Un script de regex naïf ? Ou le LLM lui-même, qui a déjà tout lu ?</p> </div> <div class="paragraph"> <p>Ma réponse : le LLM.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_pattern_stimulus_naître_fixer_diluer_mourir">Le Pattern STIMULUS — Naître, Fixer, Diluer, Mourir</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le STIMULUS est un fichier <code>.adoc</code> temporaire à la racine du workspace (Cercle 0). Son nom suit une convention évocatrice — <code>PICTURE_ME_ROLLIN.adoc</code>, <code>HOLD_MY_BEER.adoc</code>, <code>ONCE_UPON_A_TIME.adoc</code> — qui capture l’intention exploratoire du moment.</p> </div> <div class="paragraph"> <p>Son cycle de vie est impitoyable :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">CRÉATION (Cercle 0) ├→ Fichier vide, brain dump libre ├→ Allers-retours LLM ← → développeur └→ Aucune pression de structure ou de publication MATURATION ├→ Le contenu se densifie ├→ Des sections émergent naturellement └→ Le fichier devient une référence informelle de session CLASSIFICATION ÉPISTÉMIQUE ← FAIT PAR LE LLM ├→ VISION → publiable, diluer dans les docs publics + blog ├→ OPINION → confiner au Cercle 0, pas de dilution externe └→ STRATÉGIE → dilution restreinte (docs racine, PAS de blog) DILUTION (Cascade vers Cercles légitimes) ├→ VISION → WORKSPACE_AS_PRODUCT.adoc + WHAT_THE_GAMES.adoc + blog ├→ STRATÉGIE → WORKSPACE_AS_PRODUCT.adoc (section business) └→ OPINION → reste dans le stimulus, ne bouge pas ARCHIVAGE + SUPPRESSION ├→ Snapshot dans configuration/vision-archive/ (trace historique) └→ rm du stimulus — il a fini son travail</code></pre> </div> </div> <div class="paragraph"> <p>Un stimulus qui survit plus de 2 sessions sans dilution est un anti-pattern. Soit l’information est trop importante pour moisir dans un fichier temporaire (→ diluer), soit elle est trop floue pour mériter d’exister (→ supprimer).</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_délégation_au_llm_pourquoi_cest_le_llm_qui_filtre">La Délégation au LLM : Pourquoi C’est le LLM Qui Filtre</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je ne hardcode pas la classification Vision/Opinion en Kotlin. Je l’injecte dans le <strong>prompt système</strong> du LLM via <code>AGENT_GOVERNANCE.adoc</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- Pour chaque dilution de stimulus ou session, tu es responsable de classifier le contenu : - VISION : décision architecturale actée, pattern testé en production (>100 tests PASS), décision documentée dans BACKLOG ou ROADMAP - OPINION : spéculation, hypothèse non validée par des tests, intuition sans ancrage expérimental - STRATEGIE : positionnement business, pricing, marché cible Règles : - Si OPINION, le contenu reste confiné dans son cercle d'origine - Si VISION, tu procèdes à la dilution dans les documents racine - Si STRATEGIE, dilution restreinte (docs racine, pas de blog public) - Cette classification détermine aussi si un article de blog est publiable sur cheroliv.com ---- Le LLM lit cette directive **avant** de traiter la session. Elle est dans son contexte immédiat, pas dans un fichier séparé. C'est du *prompt engineering déterministe* : le comportement émerge du texte injecté, pas d'un classifieur externe. === Pourquoi Ça Marche — et Pourquoi C'est Contre-Intuitif La réaction standard : « Tu confies la classification à l'IA ? Et si elle se trompe ? » Réponse : l'humain ne fait pas mieux à 2h du matin. La différence, c'est que le LLM, lui, lit TOUT. Il a le contexte complet de la session et des documents cibles. Il sait que `VPS ECO-16 12€ HT` est une décision d'infrastructure (VISION) alors que `« le TTS ElevenLabs sonne plus naturel que Coqui »` est une opinion non vérifiée par un benchmark. L'humain, en fin de session, lit en diagonale et fait au mieux. Le LLM lit exhaustivement et applique une grille systématique. Le résultat est **plus fiable**, pas moins. Et pour les 20% de cas ambigus — la zone grise où même le LLM hésite — la réponse n'est pas « rajouter du code ». La réponse est **LangGraph4j** (EPIC 13) : un graphe d'état qui, pour les cas ambigus, active un nœud Human-in-the-Loop et remonte à l'humain pour décision. Mais pour les 80% de cas clairs, le LLM suffit. == Le Tuyau Complet : du Brain Dump au Blog Post Voici le flux complet — de l'idée brute à l'article publié — avec le LLM comme seul filtre : [source] ---- CERCLE 0 (jardin secret) PICTURE_ME_ROLLIN.adoc ← brain dump, allers-retours LLM ↓ [LLM classifie] → VISION / OPINION / STRATÉGIE ↓ VISION → dilution dans WORKSPACE_AS_PRODUCT.adoc → dilution dans WHAT_THE_GAMES_BEEN_MISSING.adoc → dilution dans WORKSPACE_VISION.adoc (session context) → RÉDACTION ARTICLE BLOG ← le LLM écrit, pas le dev ↓ CERCLE 4 (blog public) 0116_compartimentage_epistemique.adoc ← publié sur cheroliv.com ↓ ./gradlew deploy (bakery-gradle → JBake → JGit → GitHub Pages) ↓ https://cheroliv.com/blog/2026/0116/ ← live ---- Le développeur n'écrit pas l'article. Il challenge, relit, valide. Le LLM écrit. La boucle est : 1. Brain dump libre → pas de censure 2. Classification épistémique par le LLM → pas de fuite 3. Rédaction par le LLM → pas de procrastination 4. Relecture humaine → pas d'erreur Le goulot d'étranglement historique — « je n'ai pas le temps d'écrire » — est éliminé. Le LLM fait le gros du travail. L'humain fait ce que seul l'humain peut faire : juger. == Les Trois Documents Racine — Comment l'Information Trouve Sa Place Chaque document cible a un rôle précis dans la cascade de dilution : [cols="1,3,2"] |=== |Document |Ce qu'il reçoit |Type de contenu |`WORKSPACE_AS_PRODUCT.adoc` |Décisions architecturales, stack technique, roadmap, business model |VISION + STRATÉGIE |`WHAT_THE_GAMES_BEEN_MISSING.adoc` |Patterns, leçons, anti-patterns, ontologie, règles formelles |VISION (patterns testés) |`WORKSPACE_VISION.adoc` |Contexte de session, historique des décisions, points d'infrastructure |VISION + STRATÉGIE (contexte) |`AGENT_GOVERNANCE.adoc` |Règles de gouvernance, portefeuille projets, procédures |VISION (gouvernance) |**Blog cheroliv.com** |Articles publics, valeur pour le lecteur externe |VISION uniquement |=== Un même stimulus peut nourrir les 4 documents + le blog — chaque destination reçoit la portion qui la concerne, sans redondance, sans contradiction. C'est ce qui s'est passé pour `PICTURE_ME_ROLLIN.adoc` (3 mai 2026) : | Information | Classification | Destinations | | Inventaire des 13+ projets foundry/ | VISION | WORKSPACE_AS_PRODUCT | | VPS-2 OVH, edster.cloud, 8.49€/mois | VISION | WORKSPACE_AS_PRODUCT + WORKSPACE_VISION | | « Le marché africain est prêt pour le mobile money » | STRATÉGIE | WORKSPACE_AS_PRODUCT (section business) | | « DeepSeek > Kimi > GLM pour contexte long » | OPINION → VISION | Confiné puis promu après benchmark (article 0112) | | Employé Synthétique comme produit final | STRATÉGIE | WORKSPACE_AS_PRODUCT (pas de blog) | == Le Pattern Baby-Step + TestContainer + Doc Vivante — le Code qui Se Teste Lui-Même Le pattern STIMULUS/Dilution gère la pensée. Son équivalent pour le code, c'est le pattern Baby-Step/TestContainer/Doc Vivante, validé par plantuml-gradle (380/380 tests PASS, 137 sessions sans fuite Docker) : [cols="1,3"] |=== |Principe |Règle |**Baby-step** |Jamais plus de 3 pts par US. Si une US fait peur, recouper. Une US de 1 pt qui passe > une US de 8 pts qui traîne. |**TestContainer d'abord** |Avant le code métier, le conteneur. Le test d'infra passe → environnement stable garanti. |**Dataset committé** |Sous-ensemble minimal mais représentatif dans `src/test/resources/`, sans PII. Clonable, lançable. |**Documentation vivante** |Chaque test Cucumber = une phrase en langage naturel. Le code source EST la spec exécutable. Zéro doc Markdown à maintenir. |**Cleanup automatique** |Zéro fuite de ressources. Containers orphelins, `/tmp/gradle-test-*` : tout est nettoyé. |=== Ce pattern est la raison pour laquelle plantuml-gradle n'a jamais eu de régression Docker en 138 sessions. Il garantit que le code qui parle à une infra externe (PostgreSQL, Redis, Kafka) est toujours testé dans un environnement identique à la production — versionné, reproductible, lançable en une commande. == Conclusion : la Liberté de Penser sans la Peur de Publier Le compartimentage épistémique automatisé n'est pas un outil de censure. C'est un **libérateur**. Il permet de penser librement, de spéculer sans filtre, de brain-dumper tout ce qui passe par la tête — sans jamais craindre qu'une idée embryonnaire se retrouve sur le blog. Le LLM est le gardien de cette frontière. Il lit tout. Il classifie. Il dilue ce qui mérite de survivre. Il confine ce qui doit rester privé. Il rédige ce qui est publiable. Et le développeur, lui, garde le dernier mot : relire, challenger, valider. Juger. C'est la division du travail qui manquait au développeur solo : un employé synthétique qui gère la paperasse mentale, pour que l'humain puisse se concentrer sur ce qu'il fait de mieux — concevoir, architecturer, décider. == Références * Article sur la gouvernance agent Eager/Lazy : link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Gouverner un Agent IA avec du AsciiDoc] * Article sur l'ontologie spatiale et les cercles de confiance : link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[L'Ontologie Spatiale comme Mécanisme d'Alignement] * Article sur l'Anonymiseur MVP0 : link:../2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html[Notre Premier Embauché : l'Anonymiseur de Datasets] * Article sur la comparaison des LLMs long contexte : link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] * Article sur le mécanisme de backup agent : link:../2026/0110_mecanisme_backup_contexte_agent_post.html[Sliding Window et Vague Froide]</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html Fri, 1 May 2026 00:00:00 +0000 blog/2026/0115_anonymiseur_dataset_mvp0_realite_augmentee_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_让所有人都想逃开的问题">让所有人都想逃开的问题</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">阅读时间 : 12 minutes</div> <p>我不雇佣LLM。我雇佣的是匿名化器。在进行pgvector RAG之前，在微调CDA/FPA专家之前，在为客户准备工作空间之前 — — 有人必须清理数据的厕所。这个员工就是匿名化专家（MVP0，codebase-gradle的EPIC 2）。正是他让产品具备市场竞争力。</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_让所有人都想逃开的问题">让所有人都想逃开的问题</h2> <div class="sectionbody"> <div class="paragraph"> <p>任何处理训练数据的人工智能初创公司都会遇到同样的难题：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- Données brutes client (SPG, cours, évaluations) ├→ Noms de stagiaires en clair dans les PDF ├→ Emails dans les métadonnées JSON ├→ IP de connexion dans les logs pgvector ├→ Identifiants dans les nœuds Graphify └→ Références OF pilote dans les schémas SQL ---- 结果：要么你在脏数据上做 RAG（会出现 PII 幻觉、不符合 GDPR、法律风险），要么你什么都不做（没有产品）。第三种方式——手动清洁——不可扩展。 我的回答：不要回避问题。L'**自动化**. == MVP0：匿名化器，试用期首位受雇人员 MVP0不是一个feature。它是一个**便利专家**一个干着肮脏、愚蠢而残忍工作的员工，也是没人愿意在 pitch decks 中提及的。 它做的事： [source] ---- ENTRÉE : Données brutes multi-sources ├→ AsciiDoc (SPG_A2SP.adoc) → noms, dates, OF pilote ├→ JSON (catalogue formations) → emails, téléphones ├→ YAML (config workspace) → tokens OAuth2 ├→ SQL (schémas DDL) → IP, adresses ├→ pgvector (métadonnées embeddings) → identifiants ├→ ONNX (outputs classification) → noms propres └→ Graphify (graph.json) → nœuds avec PII SORTIE : Datasets propres, format standardisé ├→ [ANONYMIZED] remplace les PII détectées ├→ Classification RGPD (niveau 0→4) ├→ Rapport d'audit (quoi a été nettoyé) └→ Dataset prêt pour RAG ET fine-tuning ---- 它首先检测最明显的模式（电子邮件`.*@.*`, 令牌`sk-*`, `ghp_*`, IPs), 然后它学习。 试用期就是这样： 我们验证它不会让假阴性通过，在将其正式确定之前。 == 此 MVP 解锁了什么（而不仅仅是合规） 以 MVP0 为代表的匿名化不是高速公路之前的 GDPR 收费站；它就是高速公路本身。它为以下内容打开了大门： === 现在：提示中的增强现实 [source] ---- DONNÉES BRUTES CLIENT ↓ Anonymiseur MVP0 → datasets propres ↓ RAG pgvector (MVP1) → top-K documents similaires (filtrés, anonymisés) ↓ LLM (deepseek-v4-pro) → réponse augmentée, zéro PII ---- RAG 不会在脏数据中搜索 — 它会在一个空间中搜索**因构造而整洁**. 这改变了回答质量的一切：LLM 不会花时间去规避它识别出的但不应提及的个人身份信息（PII）。 === 未来：在健康数据上的微调 [source] ---- MVP0 → datasets propres accumulés (session après session) ↓ Fine-tuning expert métier (CDA, FPA) sur données zéro PII ↓ Modèle fine-tuné exposé via Ollama (sans fuite de données) ---- 在原始数据上进行微调是一场潜在的法律灾难。在干净数据上，它是一**可重复的方法**. 每个客户积累其清洗后的数据集，每个客户可以在其数据上对其业务专家进行微调 — 从不暴露任何个人数据。 == 为什么它具有市场价值 这不是“GDPR合规工具”。这是一**一种可复制的方法，可以将普遍问题转化为资产。** : 1. *每个培训公司都有脏数据* — 这就是问题 2. *没有任何一个拥有自动化的多源清洗管道* — 这就是市场 3. *循环 : 匿名化 → RAG → 微调是专有的* — 这就是障碍 Edster SaaS（MVP3）不会出售 « Gradle 工作区 »。它将出售这个闭环。而 MVP0 是入口。 == SQL 格式作为情境的第三种方法 结构化数据的导入不仅仅是一种交换格式。SQL 模式（DDL）承载了**领域实体关系模型**: [source] ---- CREATE TABLE formation ( id UUID PRIMARY KEY, titre VARCHAR NOT NULL, referentiel RNCP REFERENCES rncp(id), organisme OF REFERENCES of_pilote(id) -- ← va être anonymisé ); ---- 此 DDL，匿名化（第 4 行）后，成为 LLM 的上下文来源。不是文本 — du**商业模式**. RAG 提供内容（向量相似度），Graphify 提供关系（精确结构），而 SQL 模式提供**隐式的领域驱动设计**: 有界上下文、聚合、值对象。LLM 通过读取其模式 来理解业务。 == 路线图：从MVP0到SaaS [source] ---- MVP0 — Anonymiseur (ce que cet article décrit) Sortie : datasets propres, reproductible MVP1 — RAG pgvector (dépend de MVP0) Realité augmentée en prompt sur données nettoyées MVP2 — Graphify + ONNX + SQL DDD (dépend de MVP1) Vecteur composite de contexte (règles + similarité + relations exactes) MVP3 — SaaS Edster (dépend de MVP0-2) Provisionnement workspace client complet ---- 每个 MVP 都依赖于前一个。没有任何一个可以在没有 MVP0 的情况下交付。这就是为什么匿名器在待办列表中不是 « P0 » — 它是**MVP0**这是第一个商业交付物，其余一切都以其成功为前提。 == 结论：使一切成为可能的隐形工作 在传统创业公司中，数据清洗通常被外包、手动进行或被忽视。在这种架构下，它是**产品核心**. 匿名器是第一个被雇用的员工，因为没有他，什么都不起作用： * 没有 MVP0 → 没有合法的 RAG (MVP1) * 没有 MVP0 → 没有数据泄漏就没有微调 (EPIC 5) * 没有 MVP0 → 没有可信的 SaaS (MVP3) * 没有 MVP0 → 没有增强现实的提示 * 没有 MVP0 → 没有第三种上下文方式（SQL DDD） 他干肮脏的活儿。他在推介中永远不会被提及。但正是他让工厂运转起来。 这就是我们先雇佣他的原因。 == 参考文献 * 关于空间本体论和信任圈的文章：link:../2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html[空间本体作为对齐机制] * 关于代理人 Eager/Lazy 治理的文章：link:../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[用一些AsciiDoc管理一个AI智能体] * 关于 Hot/Warm/Cold 机制的文章：link:../2026/0110_mecanisme_backup_contexte_agent_post.html[滑动窗口 和 冷浪] * 关于三个LLM比较的文章：link:../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html[DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1] ----</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html Thu, 30 Apr 2026 00:00:00 +0000 blog/2026/0114_gouvernance_cercles_confiance_ontologie_spatiale_alignement_llm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_constat_le_prompt_engineering_est_un_château_de_sable">Le Constat : le Prompt Engineering est un Château de Sable</a></li> <li><a href="#_les_quatre_cercles_de_confiance_une_ontologie_spatiale">Les Quatre Cercles de Confiance : une Ontologie Spatiale</a> <ul class="sectlevel2"> <li><a href="#_le_jardin_secret_lespace_hors_cvs">Le Jardin Secret : l’Espace Hors-CVS</a> <ul class="sectlevel3"> <li><a href="#_le_gitignore_comme_configuration_de_gouvernance">Le <code>.gitignore</code> comme Configuration de Gouvernance</a></li> <li><a href="#_le_mécanisme_de_snapshot">Le Mécanisme de Snapshot</a></li> </ul> </li> <li><a href="#_le_coffre_fort_configuration_comme_spring_cloud_config">Le Coffre-Fort : <code>configuration/</code> comme Spring Cloud Config</a></li> <li><a href="#_la_bibliothèque_office_comme_data_consommable">La Bibliothèque : <code>office/</code> comme Data Consommable</a></li> <li><a href="#_les_forges_foundry_comme_implémentation">Les Forges : <code>foundry/</code> comme Implémentation</a></li> </ul> </li> <li><a href="#_procontra_alignement_spatial_vs_alignement_par_prompt">Pro/Contra : Alignement Spatial vs Alignement par Prompt</a> <ul class="sectlevel2"> <li><a href="#_approche_classique_alignement_par_pré_prompt">Approche Classique : Alignement par Pré-Prompt</a></li> <li><a href="#_cette_approche_alignement_par_ontologie_spatiale">Cette Approche : Alignement par Ontologie Spatiale</a></li> </ul> </li> <li><a href="#_lalgèbre_relationnelle_du_workspace_et_le_delta_observable">L’Algèbre Relationnelle du Workspace et le Delta Observable</a></li> <li><a href="#_le_vecteur_composite_de_contexte_rag_pgvector_graphify">Le Vecteur Composite de Contexte : RAG + pgvector + Graphify</a> <ul class="sectlevel2"> <li><a href="#_composante_1_rag_langchain4j_postgresql_pgvector">Composante 1 — RAG LangChain4j + PostgreSQL pgvector</a></li> <li><a href="#_composante_2_knowledge_graph_graphify">Composante 2 — Knowledge Graph Graphify</a></li> <li><a href="#_composante_3_graphify_incrémental_épars_agrégeable_consommable">Composante 3 — Graphify Incrémental : Épars, Agrégeable, Consommable</a></li> </ul> </li> <li><a href="#_classification_rgpd_automatique_le_llm_comme_routeur">Classification RGPD Automatique : le LLM comme Routeur</a></li> <li><a href="#_roadmap_de_lasciidoc_à_langgraph4j">Roadmap : de l’AsciiDoc à LangGraph4j</a></li> <li><a href="#_ce_que_cette_architecture_résout_et_ce_quelle_ne_résout_pas">Ce que Cette Architecture Résout (et ce qu’elle ne Résout pas)</a></li> <li><a href="#_conclusion_larchitecture_comme_discours">Conclusion : l’Architecture comme Discours</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 20 minutes</div> <p>Le prompt engineering, c’est fragile. À 80 000 tokens, vos règles d’alignement sont noyées dans le bruit, et le LLM oublie ce que vous lui avez demandé en début de conversation. Ma solution ? Ne pas aligner par le texte, mais par l'<strong>espace</strong>. J’ai structuré mon workspace de développement en quatre cercles de confiance concentriques — du jardin secret intime jusqu’aux forges publiques — et chaque cercle est une zone physique du système de fichiers. Le LLM n’a pas besoin qu’on lui rappelle les règles : le chemin du fichier les contient. Voici comment ça fonctionne, et pourquoi cette architecture d’alignement par l’espace est plus résiliente qu’un <code>system prompt</code> de 500 lignes.</p> </div> <div class="paragraph"> <p>C’est un article long.<br> Installez-vous confortablement.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_le_constat_le_prompt_engineering_est_un_château_de_sable">Le Constat : le Prompt Engineering est un Château de Sable</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pendant trois semaines, j’ai développé des plugins Gradle avec Opencode, en utilisant trois LLMs différents — Kimi K2.6, GLM-5.1, et DeepSeek-V4-Pro (le seul survivant, mais c’est une autre histoire<a href="0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">Déjà couverte ici.</a>). Ma méthode de gouvernance agent<a href="0108_gouvernance_agent_opencode_eager_lazy_post.html">Je l’ai documentée en détail dans un précédent article.</a> repose sur des fichiers AsciiDoc — <code>AGENT.adoc</code>, <code>INDEX.adoc</code>, <code>PROMPT_REPRISE.adoc</code> — qui chargent ~30 000 tokens de règles, de backlog et d’historique à chaque début de session.</p> </div> <div class="paragraph"> <p>Et malgré cette infrastructure documentaire, deux choses m’ont frappé :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Le LLM oublie.</strong> Même avec les règles absolues en tête de chaque fichier EAGER, au-delà de 60 000 tokens cumulés (contexte initial + conversation), Kimi K2.6 a commencé à proposer des <code>Write</code> écrasants sur des fichiers de configuration. GLM-5.1 a confondu un token Firebase avec un placeholder à remplacer. Les règles étaient écrites — le LLM ne les <strong>voyait</strong> plus.</p> </li> <li> <p><strong>La gouvernance elle-même devient un problème.</strong> Après avoir implémenté le mécanisme Hot/Warm/Cold<a href="0110_mecanisme_backup_contexte_agent_post.html">Article sur la rotation de backup.</a> pour éviter l’explosion du contexte, mes fichiers EAGER pesaient encore 1414 lignes<a href="0111_audit_contexte_agent_post.html">J’ai documenté cet audit ici.</a>. La gouvernance — conçue pour protéger le LLM de la saturation — saturait le LLM.</p> </li> </ol> </div> <div class="paragraph"> <p>J’avais besoin d’un mécanisme d’alignement qui ne dépende pas du nombre de tokens dans le prompt.</p> </div> <div class="paragraph"> <p>La réponse : arrêter d’aligner par le texte, et commencer à aligner par l'<strong>espace</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_les_quatre_cercles_de_confiance_une_ontologie_spatiale">Les Quatre Cercles de Confiance : une Ontologie Spatiale</h2> <div class="sectionbody"> <div class="paragraph"> <p>Mon dossier <code>workspace/</code> (dans <code>~/workspace/</code>) n’est <strong>pas</strong> un dépôt Git. C’est la racine de tout mon travail — code, documentation, formation, infrastructure. Et il est structuré en quatre zones qui ne sont pas des conventions de rangement, mais des <strong>cercles de confiance concentriques</strong> :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 13.3333%;"> <col style="width: 20%;"> <col style="width: 26.6666%;"> <col style="width: 33.3335%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Niveau</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Label</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Zone physique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CVS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Visibilité</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Jardin secret</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>workspace/</code> racine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucun</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Intime — pensée libre, pas de commit, pas de publication</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coffre-fort</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>configuration/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git privé (solo)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Secrets, tokens, archive de vision. Une seule personne.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Bibliothèque</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>office/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git privé (élargi)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Data pédagogique, SPG/SPD, schémas JSON. Cercle de confiance identifié.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Forges (publiques)</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git public (Apache 2.0)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Code source, plugins, tests, documentation technique.</p></td> </tr> </tbody> </table> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="ℹ️"></i> </td> <td class="content"> Il n’y a pas de niveau 3 dans le tableau. Le niveau 3 est un niveau <strong>transitoire</strong> : c’est du contenu de <code>office/</code> qui a été anonymisé et est prêt à être publié en open data. Il n’a pas de zone physique propre — c’est un état de la donnée, pas un emplacement. </td> </tr> </table> </div> <div class="paragraph"> <p>Chaque niveau répond à une question précise :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Où déposer une idée qui n’est pas encore prête à être partagée, même avec un cercle restreint ?</strong> → Le jardin secret. Pas de Git. Pas de pression.</p> </li> <li> <p><strong>Où stocker un token API sans qu’il fuie ?</strong> → Le coffre-fort (<code>configuration/</code>). Physiquement isolé. Aucun autre dépôt ne peut le référencer par erreur.</p> </li> <li> <p><strong>Où co-construire un catalogue de formation avec un OF pilote ?</strong> → La bibliothèque (<code>office/</code>). Versionné, collaboratif, mais privé.</p> </li> <li> <p><strong>Où industrialiser un plugin Gradle open source ?</strong> → Les forges (<code>foundry/</code>). Public, forkable, testé en CI.</p> </li> </ul> </div> <div class="paragraph"> <p>Cette ontologie est <strong>consommable par un LLM</strong>. Quand il lit un fichier dans <code>foundry/plantuml-gradle/src/</code>, il sait implicitement : "je suis dans le cercle 4 — code public, tests obligatoires, pas de secrets, pas de données pédagogiques". Il n’a pas besoin d’un prompt qui le lui rappelle.</p> </div> <div class="sect2"> <h3 id="_le_jardin_secret_lespace_hors_cvs">Le Jardin Secret : l’Espace Hors-CVS</h3> <div class="paragraph"> <p>C’est le concept le plus important — et le plus contre-intuitif.</p> </div> <div class="paragraph"> <p>La racine <code>workspace/</code> n’a pas de <code>.git/</code>. Les documents qui y vivent (<code>WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code> — et celui que vous lisez en ce moment, qui en est issu) ne sont pas destinés à être versionnés, partagés, ou même relus par quelqu’un d’autre que moi. Ce sont des <strong>pensées en germination</strong>.</p> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="❗"></i> </td> <td class="content"> <div class="paragraph"> <p>Le jardin secret est <strong>out-of-CVS</strong> par nature. L’absence de versionnage est la condition de la liberté de penser. On n’y écrit pas pour être lu — on y écrit pour clarifier sa propre vision.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Mais cette liberté a un coût : un <code>rm</code> accidentel, et c’est des mois de réflexion stratégique qui disparaissent. La solution n’est pas de versionner le jardin (ce serait le détruire) — c’est de le <strong>mirrorer</strong> dans le cercle le plus restreint.</p> </div> <div class="sect3"> <h4 id="_le_gitignore_comme_configuration_de_gouvernance">Le <code>.gitignore</code> comme Configuration de Gouvernance</h4> <div class="paragraph"> <p>À la racine de <code>workspace/</code>, un fichier <code>.gitignore</code> minimal déclare la <strong>politique d’historisation</strong> des fichiers du jardin secret :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">.goosehints .goose</code></pre> </div> </div> <div class="paragraph"> <p>Ce <code>.gitignore</code> n’a pas de fonction Git classique (il n’y a pas de <code>.git/</code> à la racine). Il agit comme un <strong>fichier de configuration de gouvernance</strong> qui répond à une question précise : <strong>quels artefacts du jardin secret méritent d’être historisés, et lesquels sont purement transitoires ?</strong></p> </div> <div class="ulist"> <ul> <li> <p>Les fichiers listés dans <code>.gitignore</code> — <code>.goosehints</code>, <code>.goose</code> — sont des artefacts éphémères générés par les agents. Pas de valeur stratégique. Pas d’historisation.</p> </li> <li> <p>Les fichiers <code>.adoc</code> de la racine — <code>WORKSPACE_VISION.adoc</code>, <code>WORKSPACE_ORGANIZATION.adoc</code>, <code>WORKSPACE_AS_PRODUCT.adoc</code>, <code>WHAT_THE_GAMES_BEEN_MISSING.adoc</code>, <code>depots_implementes_strategie.adoc</code>, <code>synthese-LLMs-long-contexte.adoc</code> — ne sont <strong>pas</strong> dans le <code>.gitignore</code>. Ce sont les artefacts à historiser.</p> </li> </ul> </div> <div class="paragraph"> <p>Le <code>.gitignore</code> est le <strong>schéma de gouvernance</strong> : tout ce qui n’y est pas listé est un candidat au snapshot. Et le LLM, en lisant ce fichier, sait exactement ce qui doit être archivé et ce qui peut être ignoré — sans qu’on ait besoin de le lui rappeler dans un prompt.</p> </div> </div> <div class="sect3"> <h4 id="_le_mécanisme_de_snapshot">Le Mécanisme de Snapshot</h4> <div class="paragraph"> <p>J’ai créé <code>configuration/vision-archive/</code> : des snapshots datés de tous les <code>.adoc</code> de la racine, commités dans le dépôt privé <code>configuration/</code>. Chaque session de brainstorming produit un snapshot :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">DATE=$(date +%Y-%m-%d) mkdir -p /home/cheroliv/workspace/configuration/vision-archive/$DATE cp /home/cheroliv/workspace/*.adoc /home/cheroliv/workspace/configuration/vision-archive/$DATE/ cd /home/cheroliv/workspace/configuration && git add vision-archive/ && \ git commit -m "vision-archive: snapshot $DATE"</code></pre> </div> </div> <div class="paragraph"> <p>La procédure est déclenchée en fin de session par le LLM lui-même, qui exécute cette tâche globale de routage. Chaque snapshot capture l’état complet de la pensée stratégique à un instant T.</p> </div> <div class="paragraph"> <p>L’historique Git de <code>configuration/</code> devient la <strong>biographie de ma pensée stratégique</strong>. Je peux faire un <code>git log — vision-archive/</code> et voir l’évolution de ma vision, session par session, date par date.</p> </div> <div class="paragraph"> <p>Exemple réel de l’historique après une journée de travail :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">$ git -C configuration log --oneline -- vision-archive/ 1089d1b vision-archive: fin de session finale 2026-05-03 6b21eaf vision-archive: fin de session 2026-05-03-1300 1690f82 vision-archive: post-article 2026-05-03 28e6593 vision-archive: post-migration 2026-05-03 3707b78 vision-archive: snapshot 2026-05-03 — jardin secret initial</code></pre> </div> </div> <div class="paragraph"> <p>Cinq snapshots en une journée. Chacun est un point de restauration. Chacun est un jalon dans la genèse de la stratégie.</p> </div> <div class="paragraph"> <p>Le dossier <code>configuration/vision-archive/latest/</code> contient en permanence une <strong>copie de travail</strong> du dernier snapshot, servant de référence rapide sans avoir à naviguer dans l’historique Git.</p> </div> <div class="paragraph"> <p>Et pour le LLM, c’est un <strong>oracle de cohérence</strong> : quand il observe une contradiction entre l’implémentation actuelle et la vision archivée à une date antérieure, il peut la signaler.</p> </div> </div> </div> <div class="sect2"> <h3 id="_le_coffre_fort_configuration_comme_spring_cloud_config">Le Coffre-Fort : <code>configuration/</code> comme Spring Cloud Config</h3> <div class="paragraph"> <p><code>configuration/</code> ne contient pas que l’archive de la vision. Sa fonction première — et future — est d’être un <strong>serveur Spring Cloud Config</strong>. Tous les secrets, tokens, credentials, et descripteurs d’infrastructure vivent ici, dans un dépôt Git privé accessible au seul propriétaire.</p> </div> <div class="paragraph"> <p>Pourquoi un dépôt séparé plutôt qu’un fichier <code>.env</code> dans chaque projet ?</p> </div> <div class="ulist"> <ul> <li> <p><strong>Push accidentel d’un secret</strong> : impossible. Les secrets sont dans un dépôt privé que les projets publics ne peuvent pas référencer par erreur.</p> </li> <li> <p><strong>Audit</strong> : l’historique Git donne la piste de chaque modification de configuration. Qui a changé quoi, quand, avec quel hash SHA.</p> </li> <li> <p><strong>Rollback</strong> : <code>git revert</code> sur une configuration cassée. Instantané, sans backup manuel.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_la_bibliothèque_office_comme_data_consommable">La Bibliothèque : <code>office/</code> comme Data Consommable</h3> <div class="paragraph"> <p><code>office/</code> est le pendant documentaire du travail de développement. Il contient les articles de blog, les spécifications techniques, les supports de formation (38 répertoires de cours FPA, SPG/SPD, schémas JSON, taxonomies Bloom/Harrow/Krathwohl) — tout ce qui constitue le <strong>matériau pédagogique</strong>.</p> </div> <div class="paragraph"> <p>Mais <code>office/</code> n’est pas qu’un tiroir à docs. C’est une <strong>source de données structurée</strong> que les plugins Gradle de <code>foundry/</code> consomment. Un article de blog dans <code>office/</code> est une entrée qu’un plugin transformera en HTML. Un SPG AsciiDoc dans <code>office/metiers/FPA/</code> est un artefact qu’un orchestrateur parsera pour générer des slides, des quiz, et des capsules vidéo.</p> </div> <div class="paragraph"> <p>Et le <code>build.gradle.kts</code> à la racine de <code>office/</code> n’est pas du code métier — c’est un <strong>script de consommation de l’écosystème de plugins</strong>. Il dit : "voici les plugins Gradle que j’utilise, voici le contexte de mon workspace".</p> </div> </div> <div class="sect2"> <h3 id="_les_forges_foundry_comme_implémentation">Les Forges : <code>foundry/</code> comme Implémentation</h3> <div class="paragraph"> <p><code>foundry/</code> contient le <strong>code industrialisé</strong>. 54 dépôts Git, dont 7 actuellement gouvernés par des <code>.agents/</code>. C’est ici que la vision devient exécutable — plugins Gradle, CI/CD, tests JUnit5 + Cucumber.</p> </div> <div class="paragraph"> <p>La relation avec <code>office/</code> est bidirectionnelle :</p> </div> <div class="ulist"> <ul> <li> <p><code>office/</code> → <code>foundry/</code> : les données pédagogiques sont la matière première que les plugins consomment.</p> </li> <li> <p><code>foundry/</code> → <code>office/</code> : les plugins produisent de la data qui enrichit <code>office/</code> — le <code>graph.json</code> de graphify-gradle, les decks slider compilés, les rapports de build.</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_procontra_alignement_spatial_vs_alignement_par_prompt">Pro/Contra : Alignement Spatial vs Alignement par Prompt</h2> <div class="sectionbody"> <div class="paragraph"> <p>Comparons les deux approches.</p> </div> <div class="sect2"> <h3 id="_approche_classique_alignement_par_pré_prompt">Approche Classique : Alignement par Pré-Prompt</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ Contra</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Simple à mettre en œuvre. Un bloc de texte dans le system prompt.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Fragile au contexte long</strong> : la règle est noyée après 80K tokens.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fonctionne pour des règles générales (ton, format).</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non vérifiable</strong> : rien n’empêche le LLM de violer la règle.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Pas besoin de repenser l’architecture du projet.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Non transférable</strong> : chaque repo redéclare les règles.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Purement déclaratif</strong> : le LLM sait qu’il <strong>devrait</strong>, mais rien ne l’empêche.</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_cette_approche_alignement_par_ontologie_spatiale">Cette Approche : Alignement par Ontologie Spatiale</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 80%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ Contra</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Résilient au contexte long</strong> : la règle est dans le chemin du fichier, pas dans un prompt lointain.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Coût d’infrastructure initial</strong> : structurer le workspace en cercles prend du temps.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Vérifiable mécaniquement</strong> : un secret dans <code>foundry/</code> est détectable par <code>git check-ignore</code>.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Nécessite discipline</strong> : un nouveau contributeur doit comprendre les cercles.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Transférable</strong> : un <code>AGENT.adoc</code> standard expose les cercles à tout nouveau projet.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Ne couvre que les contraintes spatiales</strong> — le code style reste dans le prompt.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Sécurité par conception</strong> : un <code>git push</code> depuis <code>foundry/</code> ne peut pas exposer <code>configuration/</code>.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Consommable par des agents non-LLM</strong> : un orchestrateur Gradle peut router selon le cercle.</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le gain principal n’est pas défensif (sécurité, visibilité) — il est <strong>créatif</strong>. Quand le LLM travaille dans un espace structuré par une ontologie, il peut faire ce qu’aucun prompt ne lui permet : <strong>observer le delta</strong>.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_lalgèbre_relationnelle_du_workspace_et_le_delta_observable">L’Algèbre Relationnelle du Workspace et le Delta Observable</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand le LLM parcourt <code>foundry/</code>, il dispose d’un <strong>treillis de données structurées</strong> : nœuds (plugins, fichiers, tests, dépendances), arêtes typées (<code>import</code>, <code>depends_on</code>, <code>generates</code>, <code>tests</code>), relations de composition et d’ordre (<code>training-gradle</code> extrait le référentiel → <code>slider-gradle</code> génère les slides → <code>capsule-gradle</code> monte la vidéo).</p> </div> <div class="paragraph"> <p>Cette algèbre n’est écrite nulle part en clair — mais elle est <strong>observable</strong>. Chaque <code>build.gradle.kts</code> expose des dépendances. Chaque <code>INDEX.adoc</code> expose des références croisées.</p> </div> <div class="paragraph"> <p>Le LLM observe cette algèbre et détecte le <strong>delta</strong> : l’écart entre ce que le système sait déjà produire et ce que la vision décrit.</p> </div> <div class="paragraph"> <p>À partir de ce delta, il peut définir des <strong>cartographies d’experts métiers</strong> — CDA (Concepteur Développeur d’Applications, Kotlin/Gradle/JHipster) et FPA (Formateur Professionnel d’Adultes, Pédagogie/Qualiopi/Bloom) — et identifier ce qui manque pour chaque expert.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Expert CDA (Kotlin/Gradle/JHipster) ├── Plugins : jhipster-gradle-plugins, plantuml-gradle, │ codebase-gradle ├── Delta : pas encore de SPG CDA formalisé, │ pas de fine-tuning expert CDA Expert FPA (Pédagogie/Qualiopi/Bloom) ├── Plugins : training-gradle, slider-gradle, │ school-backoffice/forms, capsule-gradle ├── Matériel : 38 modules cours, SPG/SPD, taxonomies └── Delta : parser AsciiDoc→JSON à créer, orchestrateur à coder</code></pre> </div> </div> <div class="paragraph"> <p>Le LLM n’a pas besoin qu’on lui dise quoi faire. Le delta émerge de la structure.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_vecteur_composite_de_contexte_rag_pgvector_graphify">Le Vecteur Composite de Contexte : RAG + pgvector + Graphify</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’algèbre relationnelle n’est pas une construction théorique. Elle est <strong>matérialisée</strong> par trois composantes qui forment un <strong>vecteur composite de contexte</strong> pour le LLM.</p> </div> <div class="sect2"> <h3 id="_composante_1_rag_langchain4j_postgresql_pgvector">Composante 1 — RAG LangChain4j + PostgreSQL pgvector</h3> <div class="paragraph"> <p>J’ai déjà LangChain4j en production dans deux plugins : <code>slider-gradle</code> (4 providers LLM) et <code>plantuml-gradle</code> (7 providers). Les embeddings ONNX (AllMiniLmL6V2) indexent les données de <code>office/</code> et le code source de <code>foundry/</code> dans PostgreSQL + pgvector.</p> </div> <div class="paragraph"> <p>Ce RAG opère sur deux dimensions :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Dimension data</strong> : les documents <code>office/</code> (SPG, articles, formations, schémas JSON)</p> </li> <li> <p><strong>Dimension code</strong> : les codebases <code>foundry/</code> (sources Kotlin, tests Cucumber, AGENT.adoc)</p> </li> </ul> </div> <div class="paragraph"> <p>L’intersection couvre à la fois le <strong>quoi</strong> (le domaine métier) et le <strong>comment</strong> (l’implémentation).</p> </div> </div> <div class="sect2"> <h3 id="_composante_2_knowledge_graph_graphify">Composante 2 — Knowledge Graph Graphify</h3> <div class="paragraph"> <p>Graphify est intégré dans <code>plantuml-gradle</code> (109 tests, 380/380 PASS) et produit un <code>graph.json</code> — un knowledge graph structuré avec nœuds, arêtes, et communautés détectées automatiquement.</p> </div> <div class="paragraph"> <p>Contrairement au RAG qui opère par similarité vectorielle (flou), le knowledge graph opère par <strong>relations exactes</strong> (déterministe) : <code>graphify query</code> pour les interrogations sémantiques (~50 tokens), <code>graphify path</code> pour naviguer, <code>graphify explain</code> pour expliquer.</p> </div> </div> <div class="sect2"> <h3 id="_composante_3_graphify_incrémental_épars_agrégeable_consommable">Composante 3 — Graphify Incrémental : Épars, Agrégeable, Consommable</h3> <div class="paragraph"> <p>C’est la décision architecturale clé.</p> </div> <div class="paragraph"> <p>Graphify ne doit pas vivre dans un dépôt unique. Il doit vivre de manière <strong>éparse</strong> dans chaque plugin :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Chaque plugin</strong> embarque une tâche Gradle <code>updateKnowledgeGraph</code> qui appelle Graphify <strong>sur son propre scope</strong> et produit un <code>graph.json</code> local.</p> </li> <li> <p><strong>Le build script de <code>office/</code></strong> consomme <code>graphify-gradle</code> avec <code>rootDir = /home/cheroliv/workspace</code> et produit un <code>graph.json</code> <strong>global</strong> qui agrège les graphes locaux.</p> </li> <li> <p><strong>Le RAG de chaque plugin</strong> injecte le <code>graph.json</code> global comme <strong>filtre de contexte</strong> pour les requêtes LLM.</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">TÂCHE GRADLE (dans chaque plugin) ↓ graphify → graph.json (scope local) ↓ office/build.gradle.kts → graph.json (scope global) ↓ RAG pgvector (dans slider, plantuml, codebase...) ↓ ← injection du graph.json comme filtre LLM (deepseek-v4-pro) ↓ ← observation algèbre relationnelle ↓ ← détection delta vs cartographies experts PRIORISATION → prochaine tâche</code></pre> </div> </div> <div class="paragraph"> <p>Résultat : le LLM ne cherche pas dans le vide — il navigue dans un espace structuré par le knowledge graph. Une requête sur "génère un diagramme" sait atteindre les nœuds pertinents du graphe.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_classification_rgpd_automatique_le_llm_comme_routeur">Classification RGPD Automatique : le LLM comme Routeur</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’ontologie spatiale ne se contente pas d’aligner le LLM — elle lui donne une <strong>grille de classification RGPD</strong> pour router chaque donnée vers sa zone légitime.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 12.5%;"> <col style="width: 37.5%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Critère</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Détection LLM</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Action</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Niveau max</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Donnée personnelle (nom, email, IP)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pattern <code>@</code>, IP, noms propres</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anonymiser → <code>[OF_PILOTE]</code> ou router niveau 2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Token / Secret / Credential</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pattern <code>sk-…​</code>, <code>ghp_…​</code>, <code>ya29…​</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Router → <code>configuration/</code>. Référencer par <code>${VAR}</code> dans le code.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">URL interne</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contient <code>localhost</code>, IP privée</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Anonymiser → <code>${API_URL}</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Donnée pédagogique (SPG, cours)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Structure Bloom/Qualiopi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Router → <code>office/</code> (niveau 2). Double version si export.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Code source / test</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extension <code>.kt</code>, <code>.kts</code> dans <code>foundry/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Router → <code>foundry/</code>. Vérifier absence de secrets.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>En fin de session, le LLM exécute une <strong>tâche globale</strong> :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Lecture du <code>.gitignore</code> racine pour identifier les artefacts éphémères (à exclure du snapshot) vs les artefacts stratégiques (à historiser)</p> </li> <li> <p>Inventaire de tous les fichiers <code>.adoc</code> de la racine <code>workspace/</code></p> </li> <li> <p>Filtrage : exclusion des fichiers listés dans <code>.gitignore</code>, inclusion de tous les autres</p> </li> <li> <p>Copie dans <code>configuration/vision-archive/$DATE/</code> et mise à jour du symlink <code>latest/</code></p> </li> <li> <p>Commit dans le dépôt <code>configuration/</code> avec un message structuré</p> </li> <li> <p>Classification RGPD automatique de chaque fichier modifié (tous cercles)</p> </li> <li> <p>Routage : données <code>office/</code> → commit privé, code <code>foundry/</code> → <code>./gradlew check</code>, configuration → commit</p> </li> <li> <p>Rapport structuré avec alertes RGPD et confirmation d’archivage</p> </li> </ol> </div> <div class="paragraph"> <p>Le <code>.gitignore</code> racine n’est pas un fichier de configuration Git — c’est un <strong>fichier de gouvernance de l’historisation</strong>. Il définit le schéma que le LLM consomme pour décider quels fichiers du jardin secret entrent dans la biographie stratégique et lesquels sont jetables.</p> </div> <div class="paragraph"> <p>Le LLM n’est plus un simple générateur de texte. Il est le <strong>gestionnaire d’information</strong> de l’écosystème — producteur, classifieur, routeur.</p> </div> </div> </div> <div class="sect1"> <h2 id="_roadmap_de_lasciidoc_à_langgraph4j">Roadmap : de l’AsciiDoc à LangGraph4j</h2> <div class="sectionbody"> <div class="paragraph"> <p>Aujourd’hui, cette gouvernance est <strong>déterministe</strong> : le LLM applique une procédure décrite dans des fichiers AsciiDoc. C’est la <strong>phase 1</strong> — le prompt engineering avec mémoire LLM.</p> </div> <div class="paragraph"> <p>La <strong>phase 2</strong> extraira chaque étape de la procédure dans une <strong>tâche Gradle typée</strong> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">./gradlew endSessionWorkspace → snapshot vision-archive ./gradlew endSessionProject → archive .agents/ ./gradlew endSessionReport → rapport multi-zones</code></pre> </div> </div> <div class="paragraph"> <p>La <strong>phase 3</strong> modélisera le processus de fin de session comme un <strong>graphe d’état</strong> avec <a href="https://github.com/langgraph4j/langgraph4j">LangGraph4j</a> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">[Start] → [Inventaire fichiers modifiés] → [Classification RGPD] (nœud ONNX) → [Branchement par cercle] ├→ cercle 0 → snapshot → commit ├→ cercle 2 → anonymisation → commit ├→ cercle 4 → archive → commit └→ cercle 1 → commit configuration/ → [Rapport] → [End]</code></pre> </div> </div> <div class="paragraph"> <p>Ce graphe sera versionné dans la CI/CD, exécuté par Gradle, configuré via les GitHub Secrets des plugins. Le LLM n’aura plus à décider du routage — le graphe le fera.</p> </div> </div> </div> <div class="sect1"> <h2 id="_ce_que_cette_architecture_résout_et_ce_quelle_ne_résout_pas">Ce que Cette Architecture Résout (et ce qu’elle ne Résout pas)</h2> <div class="sectionbody"> <div class="admonitionblock caution"> <table> <tr> <td class="icon"> <i class="fa icon-caution" title="🔒"></i> </td> <td class="content"> <div class="paragraph"> <p>L’ontologie spatiale ne couvre pas tout. Les conventions de code style, le nommage, les choix de design architectural — tout ça reste dans le prompt. Ce que l’ontologie spatiale résout, c’est la <strong>couche de sécurité et de visibilité</strong> : où chaque octet doit vivre, et qui peut le voir.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>Voici ce qu’elle apporte concrètement :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Pas de <code>git push</code> accidentel d’un secret</strong> : les secrets sont dans <code>configuration/</code> (cercle 1). Les projets publics sont dans <code>foundry/</code> (cercle 4). Aucun chemin ne traverse les deux.</p> </li> <li> <p><strong>Pas de code métier dans la data</strong> : <code>office/</code> contient des <code>.adoc</code>, des YAML, des JSON Schemas — mais pas de <code>.kt</code>. Le <code>build.gradle.kts</code> qui y vit est un script de consommation, pas du code métier.</p> </li> <li> <p><strong>Pas de pensée stratégique exposée</strong> : les documents de vision vivent dans le jardin secret (racine hors-CVS). Les snapshots sont dans <code>configuration/</code> (coffre-fort privé). Personne, même en cercle de confiance élargi, ne lit la genèse de la stratégie.</p> </li> <li> <p><strong>Auto-priorisation</strong> : le LLM observe le delta entre l’algèbre relationnelle (ce qui existe) et les cartographies d’experts (ce qui est nécessaire). La prochaine tâche de développement émerge de ce delta.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_larchitecture_comme_discours">Conclusion : l’Architecture comme Discours</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je ne mets pas de manifeste politique dans le footer de mon site. Je ne mets pas de règles éthiques dans mes prompts. L’alignement n’est pas dans le texte — il est dans le <strong>système de fichiers</strong>.</p> </div> <div class="paragraph"> <p>Quand un LLM travaille dans cet espace, il ne peut pas fuiter un secret (le chemin l’en empêche). Il ne peut pas confondre une donnée pédagogique avec du code source (la zone physique est différente). Il ne peut pas oublier une règle de sécurité à 80 000 tokens — parce que la règle n’est pas dans le prompt, elle est dans le <code>workspace/</code> → <code>configuration/</code> → <code>office/</code> → <code>foundry/</code> que chaque lecture de fichier réactive.</p> </div> <div class="paragraph"> <p>C’est le principe de la <strong>secure by design</strong> appliqué à l’alignement agent : ne pas demander au LLM de se souvenir des règles. Faire en sorte que l’architecture rende l’erreur structurellement impossible.</p> </div> <div class="paragraph"> <p>Et au passage, ça donne au LLM ce qu’aucun prompt ne peut lui donner : la capacité de <strong>percevoir</strong> où il est, ce qui existe, ce qui manque — et d’en déduire ce qu’il doit faire.</p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Article sur la gouvernance agent Eager/Lazy : <a href="../2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Gouverner un Agent IA avec du AsciiDoc</a></p> </li> <li> <p>Article sur le mécanisme Hot/Warm/Cold : <a href="../2026/0110_mecanisme_backup_contexte_agent_post.html">Sliding Window et Vague Froide</a></p> </li> <li> <p>Article sur l’audit de contexte : <a href="../2026/0111_audit_contexte_agent_post.html">Quand Votre Propre Gouvernance Devient le Probleme</a></p> </li> <li> <p>Article sur la comparaison des trois LLMs : <a href="../2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html">DeepSeek-V4-Pro, Kimi K2.6, GLM-5.1</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0113_integration_firebase_contact_form_post.html Wed, 29 Apr 2026 00:00:00 +0000 blog/2026/0113_integration_firebase_contact_form_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scène_un_formulaire_qui_ne_stocke_rien">La scène : un formulaire qui ne stocke rien</a> <ul class="sectlevel2"> <li><a href="#_lhéritage_supabase">L’héritage Supabase</a></li> <li><a href="#_la_double_soumission_fantôme">La double soumission fantôme</a></li> </ul> </li> <li><a href="#_pourquoi_firebase_plutôt_que_supabase">Pourquoi Firebase plutôt que Supabase ?</a></li> <li><a href="#_phase_1_créer_le_projet_firebase">Phase 1 : Créer le projet Firebase</a> <ul class="sectlevel2"> <li><a href="#_initialisation">Initialisation</a></li> <li><a href="#_règles_de_sécurité_firestore">Règles de sécurité Firestore</a></li> </ul> </li> <li><a href="#_phase_2_réécrire_le_javascript_de_soumission">Phase 2 : Réécrire le JavaScript de soumission</a> <ul class="sectlevel2"> <li><a href="#_la_dépendance_window_firebase">La dépendance <code>window.<em>FIREBASE</em></code></a></li> <li><a href="#_le_nouveau_contact_js">Le nouveau <code>contact.js</code></a></li> </ul> </li> <li><a href="#_phase_3_nettoyer_le_code_mort_supabase">Phase 3 : Nettoyer le code mort Supabase</a></li> <li><a href="#_phase_4_configurer_le_footer">Phase 4 : Configurer le footer</a></li> <li><a href="#_phase_5_architecture_finale">Phase 5 : Architecture finale</a></li> <li><a href="#_ce_que_cette_migration_dit_du_dogfooding">Ce que cette migration dit du dogfooding</a> <ul class="sectlevel2"> <li><a href="#_récapitulatif_des_modifications">Récapitulatif des modifications</a></li> </ul> </li> <li><a href="#_prochaines_étapes_backlog">Prochaines étapes (backlog)</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 12 minutes</div> <p>Pendant des mois, le formulaire de contact de ce site a tourné sur un mock JavaScript — une promesse à 85 % de succès, un faux Firestore, zéro données stockées. Le plan initial prévoyait un backend Supabase avec Google Apps Script pour les notifications mail. Abandonné. Aujourd’hui, je raconte la migration vers Firebase Firestore : création du projet, règles de sécurité, réécriture du JS, nettoyage du code mort Supabase. Et pourquoi ce choix dit quelque chose de plus large sur la philosophie de développement.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_scène_un_formulaire_qui_ne_stocke_rien">La scène : un formulaire qui ne stocke rien</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce site est généré par JBake, mon plugin Gradle <code>bakery</code>. Il est 100 % statique — pas de backend, pas de base de données. Sauf que j’ai un formulaire de contact. La page <code>contact.html</code> existe, le HTML est prêt (champs nom, email, téléphone, sujet, message, validation HTML5, honeypot anti-spam), les styles Bootstrap sont en place. Visuellement, tout est parfait.</p> </div> <div class="paragraph"> <p>Sauf qu’à la soumission, rien ne se passe.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseMock = new Promise((resolve, reject) => { setTimeout(() => { if (Math.random() < 0.85) { resolve({ status: 201, message: 'Message stored in Firestore.' }); } else { reject({ status: 500, message: 'Firestore write failed.' }); } }, 1500); });</code></pre> </div> </div> <div class="paragraph"> <p>Un mock. Une promesse qui fait semblant. L’utilisateur voit un spinner, puis un message « Message envoyé avec succès ! ». Mais les données partent dans le vide. Aucun message n’est stocké nulle part.</p> </div> <div class="paragraph"> <p>La situation est pire qu’un formulaire cassé — c’est un formulaire qui ment.</p> </div> <div class="sect2"> <h3 id="_lhéritage_supabase">L’héritage Supabase</h3> <div class="paragraph"> <p>Le plan initial, documenté dans <code>content/draft/integration_formulaire_contact_supabase.adoc</code>, prévoyait :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Une base Supabase avec table <code>contacts</code> et Row Level Security</p> </li> <li> <p>Une RPC <code>handle_contact_form</code> côté serveur</p> </li> <li> <p>Un trigger SQL appelant un webhook Google Apps Script</p> </li> <li> <p>Google Apps Script qui envoie un mail Gmail de notification</p> </li> </ol> </div> <div class="paragraph"> <p>Le code JavaScript correspondant existe encore dans <code>script.js</code>. Il y a une classe <code>SupabaseManager</code> qui initialise un client Supabase avec des variables globales <code>SUPABASE_URL</code> et <code>SUPABASE_KEY</code>, et une classe <code>ContactFormHandler</code> qui écoute l’événement submit du formulaire et appelle <code>SupabaseManager.submitContactForm()</code>.</p> </div> <div class="paragraph"> <p>Problème : ces variables globales ne sont plus injectées dans le footer. Le <code><script src="supabase-js"></code> a été retiré. Le code appelle <code>supabase.createClient()</code> sur une variable <code>supabase</code> qui n’existe plus. Donc :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">console.error : 'Supabase client library (supabase-js) is not loaded.'</code></pre> </div> </div> <div class="paragraph"> <p>Non seulement les données ne sont pas stockées, mais le code de soumission est mort.</p> </div> </div> <div class="sect2"> <h3 id="_la_double_soumission_fantôme">La double soumission fantôme</h3> <div class="paragraph"> <p>Pour empirer les choses, il y a une <strong>concurrence silencieuse</strong> entre deux handlers sur le même formulaire :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>contact.js</code> écoute le submit, appelle le mock Firebase</p> </li> <li> <p><code>script.js</code> — via <code>ContactFormHandler</code> — écoute aussi le submit, appelle <code>SupabaseManager</code></p> </li> </ol> </div> <div class="paragraph"> <p>Les deux font <code>event.preventDefault() + event.stopPropagation()</code>. Comme <code>contact.js</code> est chargé en premier dans <code>footer.thyme</code>, son handler est attaché en premier. Il bloque la propagation. <code>ContactFormHandler</code> ne sera jamais déclenché.</p> </div> <div class="paragraph"> <p>Ce n’est même pas un bug actif — c’est un zombie. Du code qui n’a jamais l’occasion de s’exécuter.</p> </div> <div id="diag-before" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-1dca60606b3e7ccf37af78f090e4df27.svg" alt="État initial — double handler et mock" width="1972" height="215"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_firebase_plutôt_que_supabase">Pourquoi Firebase plutôt que Supabase ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>La décision de migration est documentée dans <code>AGENT.adoc</code> :</p> </div> <div class="paragraph"> <p>Firebase est désormais choisi pour les raisons suivantes : meilleur plan gratuit, Firestore natif, Cloud Functions intégrées, écosystème Google plus adapté. L’implémentation Supabase existante est marquée « ⚠️ Abandonné ».</p> </div> <div class="paragraph"> <p>Au-delà du plan gratuit, il y a une raison architecturale. Ce site vit dans l’écosystème Google : le dépôt cible est <code>cheroliv.github.io</code>, le CNAME pointe sur GitHub Pages, le build Gradle push sur GitHub via JGit. Ajouter un service Google (Firebase) plutôt qu’un service tiers (Supabase) réduit la surface de dispersion.</p> </div> <div class="paragraph"> <p>Firestore en mode natif (pas en mode Datastore) est aussi plus proche du modèle mental NoSQL document que j’ai en tête : collections, documents, champs typés, timestamps serveur, règles de sécurité intégrées.</p> </div> </div> </div> <div class="sect1"> <h2 id="_phase_1_créer_le_projet_firebase">Phase 1 : Créer le projet Firebase</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_initialisation">Initialisation</h3> <div class="paragraph"> <p>La CLI Firebase n’étant pas installée sur ma machine, je passe par la console web :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Aller sur <a href="https://console.firebase.google.com/">Firebase Console</a></p> </li> <li> <p>Créer un projet <code>cheroliv-contact</code> (ou réutiliser un projet existant)</p> </li> <li> <p>Activer Firestore en mode natif (pas Datastore)</p> </li> <li> <p>Créer une base de données en région <code>eur3</code> (Europe)</p> </li> </ol> </div> <div class="paragraph"> <p>Pour un usage minimaliste comme le nôtre (une seule collection, écriture publique), le mode natif est le bon choix. Pas besoin de règles Datastore complexes.</p> </div> </div> <div class="sect2"> <h3 id="_règles_de_sécurité_firestore">Règles de sécurité Firestore</h3> <div class="paragraph"> <p>Le formulaire est public — n’importe qui peut envoyer un message. Mais je veux limiter les abus :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /contact_messages/{messageId} { // Lecture : admin uniquement (authentifié) allow read: if request.auth != null; // Écriture : publique, mais limitée allow create: if request.auth == null && request.resource.data.name is string && request.resource.data.name.size() >= 1 && request.resource.data.name.size() <= 100 && request.resource.data.email is string && request.resource.data.email.matches('.*@.*\\..*') && request.resource.data.email.size() <= 254 && request.resource.data.subject is string && request.resource.data.subject.size() >= 3 && request.resource.data.subject.size() <= 200 && request.resource.data.message is string && request.resource.data.message.size() >= 10 && request.resource.data.message.size() <= 5000 && request.resource.data.created_at == request.time && request.resource.data.user_agent is string && request.resource.data.user_agent.size() <= 500; } } }</code></pre> </div> </div> <div class="paragraph"> <p>Points clés :</p> </div> <div class="ulist"> <ul> <li> <p><code>allow read</code> — seuls les utilisateurs authentifiés peuvent lire les messages (moi, via la console Firebase)</p> </li> <li> <p><code>allow create</code> — n’importe qui peut créer un document, mais avec validation des champs</p> </li> <li> <p>Validation côté serveur : tailles min/max, format email, <code>created_at</code> doit correspondre à <code>request.time</code> (anti-falsification)</p> </li> <li> <p><code>user_agent</code> est envoyé pour traçabilité (pas critique mais utile)</p> </li> </ul> </div> <div class="paragraph"> <p>Ces règles sont plus strictes qu’un simple <code>allow write: if true;</code>. Elles empêchent un attaquant d’injecter des payloads énormes ou des champs mal formés.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_2_réécrire_le_javascript_de_soumission">Phase 2 : Réécrire le JavaScript de soumission</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le contrat est simple :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Lire les données du formulaire</p> </li> <li> <p>Vérifier le honeypot (champ <code>hp_name</code> — s’il est rempli, c’est un bot, on simule un succès sans rien envoyer)</p> </li> <li> <p>Appeler <code>addDoc(window.<em>FIREBASE</em>.collection(db, "contact_messages"), {…​})</code></p> </li> <li> <p>Afficher succès ou erreur</p> </li> </ol> </div> <div class="sect2"> <h3 id="_la_dépendance_window_firebase">La dépendance <code>window.<em>FIREBASE</em></code></h3> <div class="paragraph"> <p>Dans <code>footer.thyme</code>, un script module initialise Firebase SDK et expose un objet global :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><script type="module"> import { initializeApp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-app.js"; import { getFirestore, collection, addDoc, serverTimestamp } from "https://www.gstatic.com/firebasejs/11.6.0/firebase-firestore.js"; const firebaseConfig = { /* valeurs réelles */ }; const app = initializeApp(firebaseConfig); const db = getFirestore(app); window.__FIREBASE__ = { db, collection, addDoc, serverTimestamp }; </script></code></pre> </div> </div> <div class="paragraph"> <p>Les scripts module s’exécutent avant <code>DOMContentLoaded</code>, donc <code>window.<em>FIREBASE</em></code> est garanti disponible quand le handler <code>contact.js</code> se déclenche. Par précaution, j’ajoute quand même un polling de 5 secondes au cas où le CDN serait lent.</p> </div> </div> <div class="sect2"> <h3 id="_le_nouveau_contact_js">Le nouveau <code>contact.js</code></h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function () { 'use strict'; const form = document.getElementById('contact-form'); if (!form) return; const submitButton = form.querySelector('button[type="submit"]'); const successMessage = document.getElementById('contact-success-message'); const errorMessage = document.getElementById('contact-error-message'); // Éléments de validation const nameInput = form.querySelector('input[name="name"]'); const emailInput = form.querySelector('input[name="email"]'); const phoneInput = form.querySelector('input[name="phone"]'); const subjectInput = form.querySelector('input[name="subject"]'); const messageInput = form.querySelector('textarea[name="message"]'); const honeypotInput = form.querySelector('input[name="hp_name"]'); /** * Attend que window.__FIREBASE__ soit disponible. * Timeout de 5 secondes — si le CDN Firebase est lent, on abandonne. */ function waitForFirebase(timeoutMs = 5000) { return new Promise((resolve, reject) => { if (window.__FIREBASE__) { resolve(window.__FIREBASE__); return; } const start = Date.now(); const interval = setInterval(() => { if (window.__FIREBASE__) { clearInterval(interval); resolve(window.__FIREBASE__); } else if (Date.now() - start > timeoutMs) { clearInterval(interval); reject(new Error('Firebase SDK non disponible après timeout')); } }, 100); }); } // --- Validation (identique à l'existant) --- function validateForm() { nameInput.setCustomValidity(''); emailInput.setCustomValidity(''); if (phoneInput) phoneInput.setCustomValidity(''); subjectInput.setCustomValidity(''); messageInput.setCustomValidity(''); if (nameInput.value.trim().length < 1) { nameInput.setCustomValidity('Veuillez saisir votre nom.'); } const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailPattern.test(emailInput.value.trim())) { emailInput.setCustomValidity('Veuillez saisir une adresse email valide.'); } if (phoneInput && phoneInput.value.trim() !== '') { const phonePattern = /^\d{10,15}$/; if (!phonePattern.test(phoneInput.value.trim())) { phoneInput.setCustomValidity('Veuillez saisir un numéro valide (10 à 15 chiffres).'); } } if (subjectInput.value.trim().length < 3) { subjectInput.setCustomValidity('Veuillez saisir un sujet (3 caractères minimum).'); } if (messageInput.value.trim().length < 10) { messageInput.setCustomValidity('Veuillez saisir un message (10 caractères minimum).'); } form.classList.add('was-validated'); return form.checkValidity(); } // --- Handler de soumission --- form.addEventListener('submit', async function (event) { event.preventDefault(); event.stopPropagation(); if (!validateForm()) return; // Honeypot : si rempli, simuler un succès sans rien envoyer if (honeypotInput && honeypotInput.value.trim() !== '') { successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); return; } // UI : état d'envoi submitButton.disabled = true; submitButton.innerHTML = ` <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span> Envoi en cours... `; successMessage.style.display = 'none'; errorMessage.style.display = 'none'; try { const fb = await waitForFirebase(); const messagesCollection = fb.collection(fb.db, 'contact_messages'); await fb.addDoc(messagesCollection, { name: nameInput.value.trim(), email: emailInput.value.trim(), phone: phoneInput ? phoneInput.value.trim() : '', subject: subjectInput.value.trim(), message: messageInput.value.trim(), created_at: fb.serverTimestamp(), user_agent: navigator.userAgent.substring(0, 500) }); successMessage.style.display = 'block'; form.reset(); form.classList.remove('was-validated'); } catch (error) { console.error('Erreur Firestore:', error); errorMessage.style.display = 'block'; } finally { submitButton.disabled = false; submitButton.innerHTML = ` <i class="bi bi-send me-2"></i> Envoyer le Message `; } }, false); });</code></pre> </div> </div> <div class="paragraph"> <p>Les changements par rapport au mock :</p> </div> <div class="ulist"> <ul> <li> <p><code>waitForFirebase()</code> — polling avec timeout, robuste même si le CDN est lent</p> </li> <li> <p><code>honeypot</code> — si le champ caché <code>hp_name</code> est rempli, simuler un succès sans appel Firestore. Le bot croit avoir réussi mais rien n’est stocké</p> </li> <li> <p><code>addDoc(collection, {…​})</code> — vrai appel Firestore avec <code>serverTimestamp()</code> et <code>user_agent</code></p> </li> <li> <p>Gestion d’erreur avec <code>try/catch</code> asynchrone</p> </li> <li> <p>Nettoyage du <code>finally</code> (restauration du bouton)</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Pourquoi <code>user_agent</code> ? C’est optionnel, mais utile pour le diagnostic. Si un message étrange arrive, savoir si ça vient d’un navigateur desktop, mobile, ou d’un script curl aide au tri.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_3_nettoyer_le_code_mort_supabase">Phase 3 : Nettoyer le code mort Supabase</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>script.js</code> contient 250 lignes de dead code :</p> </div> <div class="ulist"> <ul> <li> <p><code>SupabaseManager</code> (lignes 417-481) — 65 lignes</p> </li> <li> <p><code>ContactFormHandler</code> (lignes 490-551) — 62 lignes</p> </li> <li> <p>Bloc d’initialisation (lignes 645-654) — 10 lignes</p> </li> </ul> </div> <div class="paragraph"> <p>Total : ~140 lignes à supprimer.</p> </div> <div class="paragraph"> <p>Le bloc <code>DOMContentLoaded</code> crée un <code>SupabaseManager</code> puis un <code>ContactFormHandler</code> rattaché au formulaire. Comme expliqué plus haut, ce code ne s’exécute jamais (bloqué par <code>contact.js</code>), et même s’il s’exécutait, il échouerait (pas de SDK Supabase chargé).</p> </div> <div class="paragraph"> <p>Je supprime :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>La classe <code>SupabaseManager</code></p> </li> <li> <p>La classe <code>ContactFormHandler</code></p> </li> <li> <p>Le bloc d’initialisation dans <code>DOMContentLoaded</code> (lignes 645-654)</p> </li> </ol> </div> <div class="paragraph"> <p>Le reste de <code>script.js</code> est intact : <code>ThemeManager</code>, <code>ScrollToTopButton</code>, <code>MobileMenuManager</code>, <code>SmoothScrollWithOffset</code>, <code>NavbarHeightUpdater</code>, <code>DynamicNavbarBreakpoint</code>, <code>CodeBlockManager</code>, <code>TooltipManager</code>, <code>PhoneInputManager</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_phase_4_configurer_le_footer">Phase 4 : Configurer le footer</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>footer.thyme</code> a déjà le boilerplate Firebase mais avec des valeurs placeholder. Je remplace :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">const firebaseConfig = { apiKey: "REMPLACER_PAR_VOTRE_API_KEY", authDomain: "REMPLACER_PAR_VOTRE_AUTH_DOMAIN", projectId: "REMPLACER_PAR_VOTRE_PROJECT_ID", storageBucket: "REMPLACER_PAR_VOTRE_STORAGE_BUCKET", messagingSenderId: "REMPLACER_PAR_VOTRE_SENDER_ID", appId: "REMPLACER_PAR_VOTRE_APP_ID" };</code></pre> </div> </div> <div class="paragraph"> <p>Par les valeurs réelles récupérées depuis <strong>Project Settings > General > Your apps > Web app</strong> dans la console Firebase.</p> </div> <div class="paragraph"> <p>Les valeurs sont sensibles (<code>apiKey</code> est publique par design chez Firebase, mais je préfère ne pas les commiter en clair). Je les stocke dans <code>site.yml</code> (déjà dans <code>.gitignore</code>) et le plugin <code>bakery</code> les injecte dans le template via une logique à ajouter côté build.</p> </div> <div class="paragraph"> <p>Pour l’instant, je les mets directement dans <code>footer.thyme</code> — le build <code>./gradlew serve</code> les chargera localement. Au déploiement, je migrerai l’injection vers <code>site.yml</code> ou vers une variable Gradle.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>L'`apiKey` Firebase n’est <strong>pas</strong> un secret. Elle est publique par conception. Ce qui protège vos données, ce sont les <strong>règles de sécurité Firestore</strong>, pas la clé API. Ne la mettez pas dans un <code>.env</code> chargé côté serveur — elle est destinée à être exposée au navigateur.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_phase_5_architecture_finale">Phase 5 : Architecture finale</h2> <div class="sectionbody"> <div id="diag-after" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-97da02b2e5039b13e18110950d9d0e1b.svg" alt="Architecture finale — Firebase Firestore" width="512" height="505"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ce_que_cette_migration_dit_du_dogfooding">Ce que cette migration dit du dogfooding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce site est généré par mon propre plugin Gradle <code>bakery</code>. Le formulaire de contact vit à l’intérieur du site. La migration Supabase → Firebase est documentée dans <code>AGENT.adoc</code>, elle est discutée dans le backlog, elle est testée via <code>./gradlew serve</code>, et elle génère un article de blog (celui que vous lisez).</p> </div> <div class="paragraph"> <p>C’est du dogfooding pur. Le site est le produit du plugin, le plugin est le produit du développeur, le développeur documente le processus dans le site lui-même.</p> </div> <div class="paragraph"> <p>La boucle est bouclée.</p> </div> <div class="paragraph"> <p>Le fait d’avoir traîné un mock pendant des mois (des sessions entières où le formulaire mentait silencieusement) m’a fait réaliser quelque chose : le backlog d’un site statique personnel n’est jamais « fini ». Il y a toujours une US prioritaire, toujours un article en draft, toujours une section commentée dans un template. La discipline n’est pas de tout finir — c’est de finir ce qui est visible par l’utilisateur.</p> </div> <div class="paragraph"> <p>Un formulaire de contact cassé, c’est pire que pas de formulaire du tout. C’est une promesse non tenue.</p> </div> <div class="sect2"> <h3 id="_récapitulatif_des_modifications">Récapitulatif des modifications</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6676%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fichier</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modification</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Impact</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>blog/2026/0113_*.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Création de l’article</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assets/js/contact.js</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Réécriture (mock → Firestore réel)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fonctionnel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assets/js/script.js</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Suppression SupabaseManager + ContactFormHandler + init bloc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nettoyage</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>templates/footer.thyme</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Remplacement config placeholder → valeurs réelles</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configuration</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_prochaines_étapes_backlog">Prochaines étapes (backlog)</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>Notification email</strong> : Une Cloud Function <code>onCreate</code> sur <code>contact_messages</code> qui envoie un mail via SendGrid. Le formulaire stocke, mais je ne suis pas notifié. Priorité moyenne — les messages sont visibles dans la console Firebase.</p> </li> <li> <p><strong>Rate limiting côté client</strong> : Ajouter un timestamp localStorage pour empêcher les soumissions multiples en rafale. Le honeypot bloque les bots naïfs, un rate limiter bloquerait les bots un peu plus malins.</p> </li> <li> <p><strong>Tests</strong> : Un test Playwright qui soumet le formulaire et vérifie que le document apparaît dans Firestore. Pour l’instant, je teste manuellement via <code>./gradlew serve</code>.</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://firebase.google.com/docs/firestore/security/get-started">Documentation Firestore Security Rules</a></p> </li> <li> <p><a href="https://firebase.google.com/docs/firestore/manage-data/add-data#add_a_document">Documentation Firestore addDoc — Web v9 modulaire</a></p> </li> <li> <p><a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Série gouvernance agent — Partie 1 : Eager/Lazy</a></p> </li> <li> <p><a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Série gouvernance agent — Partie 2 : Hot/Warm/Cold</a></p> </li> <li> <p><a href="/blog/2026/0111_audit_contexte_agent_post.html">Série gouvernance agent — Partie 3 : Audit</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html Tue, 28 Apr 2026 00:00:00 +0000 blog/2026/0112_comparaison_kimi_glm_deepseek_long_contexte_plugin_gradle_opencode_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_contexte_pas_un_banc_dessai_un_chantier">Contexte : pas un banc d’essai, un chantier</a></li> <li><a href="#_mon_environnement_de_test">Mon environnement de test</a></li> <li><a href="#_la_grille_dévaluation">La Grille d’Évaluation</a></li> <li><a href="#_round_1_kimi_k2_6_le_faux_départ">Round 1 : Kimi K2.6 — Le Faux Départ</a> <ul class="sectlevel2"> <li><a href="#_session_9_lembellie">Session 9 : l’embellie</a></li> <li><a href="#_session_10_le_naufrage_silencieux">Session 10 : le naufrage silencieux</a></li> </ul> </li> <li><a href="#_round_2_glm_5_1_le_combattant_honorable">Round 2 : GLM-5.1 — Le Combattant Honorable</a> <ul class="sectlevel2"> <li><a href="#_architecture_le_dsa_contre_le_mla_pur">Architecture : le DSA contre le MLA pur</a></li> <li><a href="#_sessions_11_13_solide_mais_frustrant">Sessions 11-13 : solide mais frustrant</a></li> </ul> </li> <li><a href="#_round_3_deepseek_v4_pro_la_machine_de_guerre">Round 3 : DeepSeek-V4-Pro — La Machine de Guerre</a> <ul class="sectlevel2"> <li><a href="#_architecture_csa_hca_le_double_filet">Architecture : CSA + HCA, le double filet</a></li> <li><a href="#_sessions_1_8_le_soulagement">Sessions 1-8 : le soulagement</a></li> <li><a href="#_le_test_décisif_refactoring_à_100k_tokens">Le test décisif : refactoring à 100K tokens</a></li> </ul> </li> <li><a href="#_le_face_à_face_metrics_comparatives">Le Face-à-Face : Metrics Comparatives</a></li> <li><a href="#_pourquoi_deepseek_v4_pro_gagne_en_développement_logiciel">Pourquoi DeepSeek-V4-Pro Gagne en Développement Logiciel</a> <ul class="sectlevel2"> <li><a href="#_1_larchitecture_csahca_est_taillée_pour_le_code">1. L’architecture CSA+HCA est taillée pour le code</a></li> <li><a href="#_2_le_contexte_eager_est_sa_zone_de_confort">2. Le contexte EAGER est sa zone de confort</a></li> <li><a href="#_3_le_rapport_qualitélatence_est_optimal_pour_le_flow">3. Le rapport qualité/latence est optimal pour le flow</a></li> </ul> </li> <li><a href="#_leçons_apprises_comment_choisir_son_llm_pour_le_vibe_coding">Leçons Apprises : Comment Choisir son LLM pour le Vibe Coding</a></li> <li><a href="#_et_la_gouvernance_agent_dans_tout_ça">Et la Gouvernance Agent dans tout ça ?</a></li> <li><a href="#_sources_techniques">Sources Techniques</a></li> <li><a href="#_conclusion_le_choix_de_lartisan">Conclusion : Le Choix de l’Artisan</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 18 minutes</div> <p>La guerre des LLMs se joue aussi dans le terminal d’un développeur. Pas sur des benchmarks académiques stériles. Dans la vraie vie : un prompt de 30 000 tokens, une gouvernance agent en AsciiDoc, des plugins Gradle Kotlin DSL à debugger et des sessions qui s’enchaînent sur trois semaines. J’ai testé pour vous DeepSeek-V4-Pro, Kimi K2.6 et GLM-5.1. Voici le verdict, preuves techniques à l’appui.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_contexte_pas_un_banc_dessai_un_chantier">Contexte : pas un banc d’essai, un chantier</h2> <div class="sectionbody"> <div class="paragraph"> <p>Il y a trois semaines, je travaillais sur <code>codebase-gradle</code>, mon meta-build system qui centralise la configuration YAML de quatre projets : un générateur de README PlantUML, un constructeur de slides AsciiDoc, un site statique JBake et un chatbot LLM. L’agent Opencode, gouverné par ma méthodologie de fichiers agents en AsciiDoc, chargeait ~30K tokens de contexte EAGER à chaque début de session — règles absolues, backlog, historique des 10 dernières sessions.</p> </div> <div class="paragraph"> <p>C’est sur ce terrain que j’ai confronté trois modèles :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Kimi K2.6</strong> (Moonshot AI, 1T params / 32B activés, 256K contexte max, MLA) - <strong>GLM-5.1</strong> (Zhipu AI/Tsinghua, 744B params / DSA, 200K contexte max) - <strong>DeepSeek-V4-Pro</strong> (DeepSeek, 1.6T params / 49B activés, 1M contexte max, CSA+HCA)</p> </li> </ul> </div> <div class="paragraph"> <p>Tous servis via Ollama sur serveur cloud, tous en mode thinking (phase de réflexion activée). L’enjeu : produire du code correct, maintenir la cohérence sur des sessions longues, et ne pas halluciner quand le contexte dépasse les 80K tokens.</p> </div> </div> </div> <div class="sect1"> <h2 id="_mon_environnement_de_test">Mon environnement de test</h2> <div class="sectionbody"> <div id="diag-dev-env" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-b1ac0f8f2064fca47d705e64ced8b52f.svg" alt="Environnement de développement — LLM + Opencode + Gradle" width="1806" height="5528"> </div> </div> <div class="paragraph"> <p>Chaque session démarrait avec environ 30K tokens de contexte EAGER : <code>AGENT.adoc</code> (287 lignes), <code>PROMPT_REPRISE.adoc</code> (51 lignes), <code>.agents/INDEX.adoc</code> (218 lignes), <code>LAZY_EAGER_ESSENTIALS.adoc</code> (50 lignes). Le contexte grossissait rapidement avec les échanges — une session typique de 10 messages ajoutait 15-20K tokens au prompt cumulé.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_grille_dévaluation">La Grille d’Évaluation</h2> <div class="sectionbody"> <div class="paragraph"> <p>J’ai évalué chaque modèle sur quatre axes critiques pour le développement logiciel assisté :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Axe</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Critère concret</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Cohérence long contexte</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’agent se souvient-il des conventions décidées il y a 40 messages ?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Qualité du code produit</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le code compile-t-il du premier coup ? Respecte-t-il les patterns existants ?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Raisonnement architectural</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’agent comprend-il les relations entre modules sans que je les lui réexplique ?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Résistance aux hallucinations</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">À partir de combien de tokens l’agent commence-t-il à inventer des API ou des classes inexistantes ?</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Et une métrique synthétique maison : le <strong>coefficient de reprise</strong> (combien de temps je passe à corriger l’agent plutôt qu’à coder avec lui).</p> </div> </div> </div> <div class="sect1"> <h2 id="_round_1_kimi_k2_6_le_faux_départ">Round 1 : Kimi K2.6 — Le Faux Départ</h2> <div class="sectionbody"> <div class="paragraph"> <p>Kimi K2.6 a été mon premier choix. Ses benchmarks sur SWE-Bench Verified (80.2) et Terminal-Bench 2.0 (66.7) sont excellents. Son architecture MLA promet une bonne efficacité sur les longues séquences.</p> </div> <div class="sect2"> <h3 id="_session_9_lembellie">Session 9 : l’embellie</h3> <div class="paragraph"> <p>Première session avec Kimi. Tâche : implémenter la méthode <code>resolveActiveKey()</code> dans <code>codebase.kt</code> — une fonction de résolution de clé API avec fallback CLI. Le contexte est à 30K tokens, Kimi raisonne vite, produit un code propre avec gestion d’expiration des clés.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">fun resolveActiveKey( cfg: CodebaseConfiguration, logger: Logger, cliProvider: String? = null, cliAccount: String? = null, cliKey: String? = null ): NamedApiKey? { // Résolution provider → compte → clé avec CLI override // Kimi a parfaitement compris la chaîne de priorité }</code></pre> </div> </div> <div class="paragraph"> <p>Le code compile. Les 7 cas de test passent. Je suis optimiste.</p> </div> </div> <div class="sect2"> <h3 id="_session_10_le_naufrage_silencieux">Session 10 : le naufrage silencieux</h3> <div class="paragraph"> <p>Deuxième session. Le contexte grimpe à ~90K tokens avec les échanges. Je demande à Kimi d’ajouter un mécanisme de snapshot AsciiDoc qui anonymise les secrets avant écriture.</p> </div> <div class="paragraph"> <p>C’est là que ça dérape. Kimi commence à inventer des classes qui n’existent pas. Il me propose <code>AnonymizedObjectMapper</code> — une classe fictive. Il confond <code>ReadmeYmlAnonymizer</code> et <code>CodebaseYmlAnonymizer</code>. Il me suggère d’importer <code>com.fasterxml.jackson.anonymize.*</code> — un package qui n’a jamais existé.</p> </div> <div class="paragraph"> <p>Pire : dans sa phase de réflexion, je vois qu’il construit des raisonnements sur des prémisses fausses. Il "se souvient" que <code>GitConfig</code> a un champ <code>anonymizedToken</code> — non, c’est <code>resolvedToken()</code>. Il attribue à <code>SiteYmlAnonymizer</code> une méthode <code>maskSupabaseCredentials()</code> — qui n’existe pas.</p> </div> <div class="paragraph"> <p><em><em>_ Ce n’était pas un bug. C’était une dissolution progressive de la cohérence. Comme si chaque token ajouté au contexte diluait un peu plus la mémoire des 30 000 premiers. </em>_</em></p> </div> <div class="paragraph"> <p>J’arrête Kimi après deux sessions. Le diagnostic est clair : le MLA compresse bien le KV cache, mais sans mécanisme de sélection sparse fine-grained, l’attention se dilue mécaniquement au-delà de 60K tokens. Chaque token "voit" de moins en moins bien le contexte lointain — et commence à combler les trous par du bruit.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_round_2_glm_5_1_le_combattant_honorable">Round 2 : GLM-5.1 — Le Combattant Honorable</h2> <div class="sectionbody"> <div class="paragraph"> <p>GLM-5.1 arrive avec une architecture différente : MLA pour le base model, puis un <strong>continued pre-training</strong> avec DSA (DeepSeek Sparse Attention) — un indexer léger qui sélectionne dynamiquement les top-2048 tokens pertinents parmi tout l’historique.</p> </div> <div class="sect2"> <h3 id="_architecture_le_dsa_contre_le_mla_pur">Architecture : le DSA contre le MLA pur</h3> <div class="paragraph"> <p>La différence est fondamentale. Là où Kimi compresse l’historique dans un espace latent unique (et perd progressivement la capacité à discriminer l’information pertinente), GLM greffe un indexer post-entraînement qui fait une sélection sparse explicite.</p> </div> <div id="diag-mla-vs-dsa" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-96552207a44b513333686c1c93d0cef9.svg" alt="Comparaison architecture MLA (Kimi) vs MLA+DSA (GLM)" width="1074" height="364"> </div> </div> <div class="paragraph"> <p>Le rapport technique le dit explicitement : DSA est <em>"lossless by construction"</em> — contrairement aux alternatives comme SWA (pattern search), Gated DeltaNet ou SimpleGDN qui perdent jusqu’à 5.69 pts sur RULER@128K.</p> </div> </div> <div class="sect2"> <h3 id="_sessions_11_13_solide_mais_frustrant">Sessions 11-13 : solide mais frustrant</h3> <div class="paragraph"> <p>GLM-5.1 tient mieux la distance. Sur la session 11 (~60K tokens), il reste cohérent. Il produit un <code>SnapshotManager</code> fonctionnel avec gestion correcte des quatre anonymiseurs.</p> </div> <div class="paragraph"> <p>Mais la latence est un problème. Les phases de réflexion DSA sont plus lourdes que le MLA pur — l’indexer doit rescanner l’historique à chaque étape. Une réponse qui prenait 8 secondes avec Kimi en prend 15 avec GLM. Sur une session de 30 messages, ça se fait sentir.</p> </div> <div class="paragraph"> <p>Et puis il y a les erreurs subtiles. GLM ne délire pas comme Kimi — mais il fait des erreurs de <strong>nommage</strong>. Il appelle <code>toAnonymizedYaml()</code> la méthode qui devrait s’appeler <code>anonymize()</code>. Il inverse <code>loadReadmeConfiguration()</code> et <code>loadCodebaseConfiguration()</code> dans le <code>renderFileSection()</code>. Ce ne sont pas des hallucinations, ce sont des confusions de surface — mais en production, une confusion de surface peut casser un build.</p> </div> <div class="paragraph"> <p>J’ai tenu trois sessions avec GLM. Il est meilleur que Kimi, sans conteste. Mais trois sessions de correction manuelle sur des détails de nommage, ça use.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_round_3_deepseek_v4_pro_la_machine_de_guerre">Round 3 : DeepSeek-V4-Pro — La Machine de Guerre</h2> <div class="sectionbody"> <div class="paragraph"> <p>DeepSeek-V4-Pro arrive avec l’architecture la plus ambitieuse des trois : un système hybride qui combine deux mécanismes d’attention complémentaires.</p> </div> <div class="sect2"> <h3 id="_architecture_csa_hca_le_double_filet">Architecture : CSA + HCA, le double filet</h3> <div id="diag-csa-hca" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-aad75fde6f9e97e39f6617b3b9f836d7.svg" alt="Architecture hybride CSA+HCA de DeepSeek-V4-Pro" width="741" height="459"> </div> </div> <div class="paragraph"> <p>Deux niveaux de compression, deux granularités d’attention :</p> </div> <div class="ulist"> <ul> <li> <p><strong>CSA</strong> : compresse le KV cache tous les <code>m</code> tokens, puis applique une attention sparse (DeepSeek Sparse Attention) — seul le top-k des entrées compressées est consulté. Précis, local, efficace. - <strong>HCA</strong> : compression extrême (facteur <code>m'</code> bien plus grand que <code>m</code>), mais attention dense sur le résidu compressé — garde les connexions globales sans explosion quadratique.</p> </li> </ul> </div> <div class="paragraph"> <p>Résultat : à 1M de tokens, DeepSeek-V4-Pro ne consomme que <strong>27% des FLOPs d’inférence</strong> et <strong>10% de la taille du KV cache</strong> par rapport à DeepSeek-V3.2. Le modèle précédent.</p> </div> <div class="paragraph"> <p>Et surtout, le rapport technique (Figure 9) annonce : <em>"Retrieval performance remains highly stable within a 128K context window."</em></p> </div> </div> <div class="sect2"> <h3 id="_sessions_1_8_le_soulagement">Sessions 1-8 : le soulagement</h3> <div class="paragraph"> <p>J’ai passé huit sessions avec DeepSeek-V4-Pro sur <code>codebase-gradle</code>. Huit sessions sans une seule hallucination, sans une seule classe inventée, sans une seule confusion de nommage.</p> </div> <div class="paragraph"> <p>Session 1 : implémentation de <code>CodebaseYmlConfig</code> et <code>CodebaseYmlAnonymizer</code>. 350 lignes de Kotlin, tests inline, tout compile. Session 4 : ajout du <code>SnapshotManager</code> avec tree view, collecte de fichiers, rendu AsciiDoc par fichier. 279 lignes, zéro erreur. Session 7 : debug du <code>renderFileSection()</code> qui devait gérer quatre types d’anonymiseurs différents sans ambiguïté de résolution. Résolu en trois messages.</p> </div> <div class="paragraph"> <p>La latence est plus élevée que Kimi — environ 10-12 secondes par réponse en mode thinking. Mais le taux de correction est quasi nul. Je ne passe pas mon temps à réparer les erreurs de l’agent. Je code <strong>avec</strong> lui.</p> </div> </div> <div class="sect2"> <h3 id="_le_test_décisif_refactoring_à_100k_tokens">Le test décisif : refactoring à 100K tokens</h3> <div class="paragraph"> <p>À la session 8, le contexte cumulé dépasse les 100K tokens. Je demande un refactoring lourd : extraire les quatre tâches de vérification inline du <code>build.gradle.kts</code> vers des fichiers de test JUnit5 dans <code>buildSrc/src/test/</code>.</p> </div> <div class="paragraph"> <p>L’agent propose un plan en trois phases :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Créer les classes de test avec migration des cas existants</p> </li> <li> <p>Ajouter les dépendances JUnit5 et Kotest dans <code>buildSrc/build.gradle.kts</code></p> </li> <li> <p>Supprimer le code inline de <code>build.gradle.kts</code></p> </li> </ol> </div> <div class="paragraph"> <p>Le plan est correct. L’exécution est propre. Il identifie même un edge case que j’avais manqué : les dépendances Jackson dupliquées entre <code>buildscript {}</code> et <code>buildSrc/build.gradle.kts</code> qui doivent être unifiées pendant la migration.</p> </div> <div class="paragraph"> <p>100K tokens de contexte, et l’agent se souvient que <code>CodebaseYmlAnonymizer.TOKEN_MASK</code> est <code>"<strong>*</strong>"</code>, que <code>GitConfig.resolvedToken()</code> est une extension function définie dans <code>readme.kt</code>, et que <code>SnapshotManager.PRUNED_DIRS</code> exclut <code>build</code>, <code>.gradle</code> et <code>.git</code>.</p> </div> <div class="paragraph"> <p>C’est ça, la différence.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_face_à_face_metrics_comparatives">Le Face-à-Face : Metrics Comparatives</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Critère</th> <th class="tableblock halign-left valign-top">Kimi K2.6</th> <th class="tableblock halign-left valign-top">GLM-5.1</th> <th class="tableblock halign-left valign-top">DeepSeek-V4-Pro</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contexte max</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">256K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">200K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1M</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Mécanisme attention</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA pur</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">MLA + DSA</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSA + HCA hybride</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Paramètres totaux</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1T</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">744B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1.6T</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Paramètres activés</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">32B</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non publié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49B</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Seuil dégradation observé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~60K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~120K tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~128K tokens</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Comportement au-delà</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Hallucinations massives</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confusions de surface</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dégradation progressive lente</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Stabilité NIAH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non publié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">100% @128K (DSA)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">stable jusqu’à 128K (Figure 9)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">MRCR @128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non publié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">non publié</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">supérieur à Gemini 3.1 Pro</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Sessions tenues avant abandon</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 (et continue)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Temps de correction / temps de code</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">60%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30%</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><5%</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Latence moyenne (mode think)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">15 s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">11 s</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coefficient de confiance*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">6/10</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9/10</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em>*Coefficient de confiance = mesure subjective de ma capacité à prendre le code de l’agent et le commit sans relecture ligne à ligne.</em></p> </div> <div id="diag-radar" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-1ac33bab88740dda58ef1579a97513c4.svg" alt="Radar comparatif — Kimi K2.6 vs GLM-5.1 vs DeepSeek-V4-Pro" width="1135" height="844"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_deepseek_v4_pro_gagne_en_développement_logiciel">Pourquoi DeepSeek-V4-Pro Gagne en Développement Logiciel</h2> <div class="sectionbody"> <div class="paragraph"> <p>La supériorité de DeepSeek-V4-Pro n’est pas due à un seul facteur — c’est une convergence :</p> </div> <div class="sect2"> <h3 id="_1_larchitecture_csahca_est_taillée_pour_le_code">1. L’architecture CSA+HCA est taillée pour le code</h3> <div class="paragraph"> <p>Le développement logiciel assisté est un cas d’usage <strong>extrême</strong> pour l’attention long-contexte. Vous avez besoin de : - Précision locale (cette classe hérite de quoi ? cette méthode est définie où ?) → <strong>CSA</strong> - Vision globale (pourquoi ce module existe ? comment les quatre anonymiseurs interagissent ?) → <strong>HCA</strong></p> </div> <div class="paragraph"> <p>Kimi avec MLA seul gère la précision locale mais perd la vision globale au-delà de 60K. GLM avec DSA améliore la vision globale mais reste mono-niveau. DeepSeek combine les deux explicitement.</p> </div> </div> <div class="sect2"> <h3 id="_2_le_contexte_eager_est_sa_zone_de_confort">2. Le contexte EAGER est sa zone de confort</h3> <div class="paragraph"> <p>Mon système de gouvernance charge ~30K tokens de règles et de backlog au démarrage. Avec une fenêtre stable jusqu’à 128K, DeepSeek dispose de ~100K tokens de marge pour les échanges de la session. C’est 3 à 4 fois plus que ce que Kimi peut gérer sans dégradation.</p> </div> <div class="paragraph"> <p><em><em>_ La fenêtre de 128K de stabilité parfaite correspond exactement à mes besoins : 30K d’EAGER + 70K d’échanges = une session productive de 20-30 messages sans jamais sortir de la zone verte. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_3_le_rapport_qualitélatence_est_optimal_pour_le_flow">3. Le rapport qualité/latence est optimal pour le flow</h3> <div class="paragraph"> <p>Oui, DeepSeek-V4-Pro est plus lent que Kimi (11s vs 8s). Mais le temps <strong>total</strong> d’une tâche est bien inférieur parce que je ne passe pas 20 minutes à corriger les hallucinations de l’agent.</p> </div> <div class="paragraph"> <p>Le développeur ne mesure pas la latence d’une réponse. Il mesure le temps entre "je pose la question" et "le code est dans mon repo et il fonctionne". Sur cette métrique, DeepSeek-V4-Pro est le plus rapide des trois.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_leçons_apprises_comment_choisir_son_llm_pour_le_vibe_coding">Leçons Apprises : Comment Choisir son LLM pour le Vibe Coding</h2> <div class="sectionbody"> <div class="paragraph"> <p>Au-delà du classement ponctuel, cette expérience m’a appris à évaluer un LLM pour le développement logiciel assisté sur des critères qui ne figurent dans aucun benchmark :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Regarde l’architecture, pas la taille de contexte annoncée</strong> — Un modèle qui annonce 256K de contexte mais n’a qu’un MLA finira comme Kimi : théoriquement capable, pratiquement inutilisable au-delà de 60K.</p> </li> <li> <p><strong>Teste sur TON contexte, pas sur un benchmark générique</strong> — Mon prompt initial de 30K tokens AsciiDoc avec règles absolues et backlog n’a rien à voir avec les questions de HLE ou AIME.</p> </li> <li> <p><strong>La latence n’est pas l’ennemie si la qualité suit</strong> — Un modèle lent qui produit du code juste est plus rapide qu’un modèle rapide qui produit du code faux.</p> </li> <li> <p><strong>Méfie-toi des modèles sans technical report public</strong> — Si l’équipe ne documente pas son architecture d’attention, c’est qu’elle n’a pas confiance dans sa tenue en long contexte.</p> </li> </ol> </div> <div id="diag-decision-tree" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-764212652633dc337e38e51de5fc291e.svg" alt="Arbre de décision pour choisir un LLM pour le développement logiciel assisté" width="827" height="461"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_et_la_gouvernance_agent_dans_tout_ça">Et la Gouvernance Agent dans tout ça ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>Cette expérience valide un point que je défends depuis mon article sur la gouvernance Eager/Lazy : <strong>la qualité du LLM et la qualité de la gouvernance sont multiplicatives, pas additives</strong>.</p> </div> <div class="paragraph"> <p>Avec Kimi K2.6, ma gouvernance était impeccable — mais le modèle diluait l’information. Résultat : gouvernance parfaite × hallucination = zéro.</p> </div> <div class="paragraph"> <p>Avec DeepSeek-V4-Pro, la gouvernance EAGER (30K tokens de règles) + LAZY (archives de sessions, références techniques) + Hot/Warm/Cold (backup rotatif) forme un écosystème où chaque couche amplifie l’autre. L’agent a les règles sous les yeux (EAGER), peut consulter l’historique (LAZY), et le contexte ne sature jamais (rotation backup).</p> </div> <div class="paragraph"> <p><em><em>_ Un bon LLM sans gouvernance, c’est un moteur de Ferrari sans volant. Une bonne gouvernance sans bon LLM, c’est un volant sans moteur. DeepSeek-V4-Pro + ma gouvernance agent = la première fois que j’ai l’impression de conduire. </em>_</em></p> </div> <div class="paragraph"> <p>Le mécanisme de backup rotatif (rotation toutes les 10 sessions ou >500 lignes EAGER) prend tout son sens avec un modèle qui tient 128K de contexte : la sliding window de 10 sessions actives maintient le contexte frais sans jamais dépasser la zone de dégradation.</p> </div> </div> </div> <div class="sect1"> <h2 id="_sources_techniques">Sources Techniques</h2> <div class="sectionbody"> <div class="paragraph"> <p>J’ai croisé mon expérience empirique avec les rapports techniques officiels pour valider mes observations :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>DeepSeek-V4 Technical Report</strong> — PDF récupéré depuis <a href="https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash">HuggingFace</a>. Figure 9 : "Retrieval performance remains highly stable within a 128K context window. While a performance degradation becomes visible beyond the 128K mark, the model’s retrieval capabilities at 1M tokens remain remarkably strong." Architecture CSA+HCA documentée section 2.3.</p> </li> <li> <p><strong>GLM-5 Technical Report</strong> — <a href="https://arxiv.org/abs/2602.15763">arXiv:2602.15763</a>. DSA introduit via continued pre-training, "lossless by construction". Contexte max 202,752 tokens. Tables 3/5/6 documentent les performances long-contexte vs alternatives (SWA, Gated DeltaNet, SimpleGDN).</p> </li> <li> <p><strong>Kimi K2.6 Model Card</strong> — <a href="https://huggingface.co/moonshotai/Kimi-K2.6">HuggingFace</a>. MLA, 256K contexte max. Stratégie de discard-all au-delà du seuil sur les tâches agentiques (confirmant implicitement la limite pratique du MLA en long contexte).</p> </li> <li> <p><strong>Kimi K2 Technical Report</strong> — <a href="https://arxiv.org/abs/2507.20534">arXiv:2507.20534</a>. Architecture MoE, MuonClip optimizer, performances agentiques (HLE, BrowseComp, Terminal-Bench).</p> </li> </ol> </div> <div class="paragraph"> <p>Le point le plus révélateur : dans leur propre évaluation, Moonshot applique une stratégie de <strong>discard-all</strong> (suppression du contexte ancien) dès que la fenêtre de contexte est dépassée. Cela confirme exactement ce que j’ai observé : le MLA seul ne peut pas maintenir la cohérence sur toute la fenêtre de 256K. L’architecture ne suit pas.</p> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_le_choix_de_lartisan">Conclusion : Le Choix de l’Artisan</h2> <div class="sectionbody"> <div class="paragraph"> <p>Après trois semaines et treize sessions de développement réel, le verdict est sans appel :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3333%;"> <col style="width: 8.3337%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Kimi K2.6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">GLM-5.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">DeepSeek-V4-Pro</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Excellent sous 60K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Solide jusqu’à 120K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Domine partout</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Inutilisable au-delà</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Confusions de surface</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Stable jusqu’à 128K</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2 sessions, abandonné</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3 sessions, abandonné</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8 sessions, adopté</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>DeepSeek-V4-Pro est devenu mon LLM par défaut pour toutes les sessions de développement logiciel assisté avec Opencode. Pas parce qu’il est le plus récent. Pas parce qu’il a les meilleurs benchmarks académiques. Mais parce que dans la vraie vie d’un développeur qui pousse des plugins Gradle Kotlin DSL avec un contexte agent de 30K tokens, c’est le seul qui ne me trahit pas quand le contexte s’allonge.</p> </div> <div class="paragraph"> <p>Le CSA+HCA est un <strong>game changer</strong> architectural. La compression double niveau + sparsification n’est pas un détail d’implémentation — c’est ce qui fait la différence entre un assistant de code et un coéquipier fiable.</p> </div> <div class="paragraph"> <p><em><em>_ J’ai choisi DeepSeek-V4-Pro parce qu’il est le seul des trois qui transforme ma gouvernance agent d’une contrainte défensive ("comment éviter que l’agent oublie ?") en un avantage offensif ("que peut-on construire maintenant que l’agent se souvient de tout ?"). </em>_</em></p> </div> <hr> <div class="paragraph"> <p><strong>Cet article est le fruit de 13 sessions de développement réel sur le projet <code>codebase-gradle</code>, documentées dans <code>.agents/sessions/</code> selon ma méthodologie de gouvernance agent Eager/Lazy/Hot/Warm/Cold. Les sources techniques citées sont accessibles publiquement sur HuggingFace et arXiv.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0111_audit_contexte_agent_post.html Mon, 27 Apr 2026 00:00:00 +0000 blog/2026/0111_audit_contexte_agent_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scène_session_051_quelque_chose_cloche">La scène : session 051, quelque chose cloche</a></li> <li><a href="#_laudit_décortiquer_les_627_lignes">L’audit : décortiquer les 627 lignes</a></li> <li><a href="#_la_peur_de_perdre_lingénierie">La peur de perdre l’ingénierie</a></li> <li><a href="#_la_solution_split_encyclopédique">La solution : split encyclopédique</a></li> <li><a href="#_le_contenu_du_fichier_essentials">Le contenu du fichier ESSENTIALS</a></li> <li><a href="#_le_résultat_50_de_contexte_eager">Le résultat : -50% de contexte EAGER</a></li> <li><a href="#_pourquoi_le_dossier_sappelle_encyclopedies">Pourquoi le dossier s’appelle <code>encyclopedies/</code></a></li> <li><a href="#_la_suite_logique_de_la_série">La suite logique de la série</a></li> <li><a href="#_ce_que_jaurais_fait_différemment">Ce que j’aurais fait différemment</a></li> <li><a href="#_le_guide_pour_auditer_votre_propre_contexte">Le guide pour auditer votre propre contexte</a></li> <li><a href="#_une_gouvernance_vivante">Une gouvernance vivante</a></li> <li><a href="#_liens">Liens</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 14 minutes</div> <p>Vous avez passé des semaines à construire une gouvernance agent impeccable. Eager/Lazy, procédure de fin de session, backups rotatifs. Le système tourne. Puis un jour, l’agent devient lent. Les réponses sont diluées. Vous mesurez : 1414 lignes chargées automatiquement. Et le pire, c’est que le coupable n’est pas le code, ni le backlog, ni les archives de sessions. Le coupable, c’est le fichier qui documente votre méthode.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_scène_session_051_quelque_chose_cloche">La scène : session 051, quelque chose cloche</h2> <div class="sectionbody"> <div class="paragraph"> <p>30 avril 2026, 16h00. Je suis en pleine session sur <code>magic-stick</code>, mon projet de build d’ISO Linux live. L’agent Opencode a chargé automatiquement mes fichiers Eager comme d’habitude — <code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Tout est normal.</p> </div> <div class="paragraph"> <p>Sauf que les réponses sont molles. L’agent met deux secondes de plus à raisonner. Il oublie un détail qu’il avait sous les yeux trois messages plus tôt. Ce n’est pas un crash, pas une erreur — c’est une dégradation lente, le genre qu’on ne remarque pas tout de suite.</p> </div> <div class="paragraph"> <p>J’avais déjà vécu ça à la session 048, quand j’avais découvert que les fichiers de gouvernance pesaient 5200 lignes cumulées. J’avais alors conceptualisé le mécanisme Hot/Warm/Cold avec sa sliding window de 10 sessions, ses vagues froides identiques, son capteur à deux déclencheurs. Le problème était réglé. En théorie.</p> </div> <div class="paragraph"> <p>Mais là, on est à la session 051. La rotation backup a bien eu lieu — les fichiers EAGER sont passés de 2087 à 500 lignes. Pourtant, le contexte reste lourd. Quelque chose m’échappe.</p> </div> <div class="paragraph"> <p>J’ouvre un terminal et je tape :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wc -l AGENT.adoc AGENT_MODUS_OPERANDI.adoc PROMPT_REPRISE.adoc \ .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total</code></pre> </div> </div> <div class="paragraph"> <p>1414 lignes. La rotation backup a bien taillé dans INDEX, SESSIONS_HISTORY et COMPLETED_TASKS — ils sont propres. Mais il y a un éléphant dans la pièce que je n’avais pas vu : <strong>627 lignes</strong> dans un seul fichier. <code>AGENT_MODUS_OPERANDI.adoc</code>.</p> </div> <div class="paragraph"> <p>Ce fichier, c’est celui que j’ai écrit à la session 1 pour documenter la stratégie Eager/Lazy. C’est le manuel de la méthode. Et il est devenu, à lui seul, 44% du contexte EAGER.</p> </div> <div id="diag-before-audit" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-055a31fdef8c78e522a1ab22c6f74925.svg" alt="Répartition des 1414 lignes EAGER avant audit" width="721" height="200"> </div> </div> <div class="paragraph"> <p>L’ironie est totale. Le fichier conçu pour <strong>économiser</strong> du contexte est devenu le principal <strong>consommateur</strong> de contexte. C’est comme si le manuel d’utilisation de votre voiture pesait plus lourd que le moteur.</p> </div> </div> </div> <div class="sect1"> <h2 id="_laudit_décortiquer_les_627_lignes">L’audit : décortiquer les 627 lignes</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je décide de faire un audit section par section. Pas pour supprimer — pour <strong>comprendre</strong> ce qui mérite d’être en EAGER et ce qui pourrait vivre ailleurs sans perte de connaissance.</p> </div> <div class="paragraph"> <p>Voici la structure exacte de <code>AGENT_MODUS_OPERANDI.adoc</code> et ce que j’y trouve :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2727%;"> <col style="width: 2.2739%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Section</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lignes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Contenu</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Déjà présent dans…​</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P1 — Vue d’ensemble</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">64</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problème résolu, principes fondamentaux, analogie tableau de bord vs manuel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P2 — Structure des fichiers</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">97</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Arborescence, politique de chargement, quand charger quoi</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P3 — Règles absolues</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">34</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Git interdit, commandes destructrices interdites, secrets interdits</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code> + <code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P4 — Cycle de vie session</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">133</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Template ouverture, règles de travail, 6 étapes fin de session, checklist</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code> §Fin session + <code>INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P5 — Métriques et seuils</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">49</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Session idéale (15-30 min, 1-3 fichiers), signes d’alerte</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P6 — Types de sessions</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">72</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tableau de détection, format de proposition, exceptions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P7 — Amélioration continue</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">39</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Métriques de suivi, revue hebdomadaire</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P8 — Checklist démarrage</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">13</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bootstrap nouveau projet</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>P9 — Références</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">30</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fichiers de référence, ressources externes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AGENT.adoc</code> (fichiers EAGER/LAZY)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Annexes A+B</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">42</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Glossaire, historique versions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le verdict est sans appel :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Doublons intégraux</strong> (167 lignes) : P3, P4, P9 — tout est déjà dans <code>AGENT.adoc</code> ou <code>INDEX.adoc</code>, souvent mot pour mot</p> </li> <li> <p><strong>Jamais consulté en pratique</strong> (215 lignes) : P5, P6, P7, P8, Annexes — de la méta-gouvernance qui n’a jamais servi dans aucune session</p> </li> <li> <p><strong>Connaissance unique</strong> (161 lignes) : P1 et P2 — le vocabulaire LAZY/EAGER, l’analogie, la politique de chargement</p> </li> </ul> </div> <div class="paragraph"> <p>Sur 627 lignes, <strong>382 sont du bruit</strong>. Et ces 382 lignes sont chargées <strong>à chaque début de session</strong>, consommées par l’agent, diluant son attention avant même que je dise bonjour.</p> </div> <div id="diag-audit-result" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-e3ec2f50f58c8bbd108e7f63232946be.svg" alt="Résultat de l’audit — 627 lignes réparties en doublons, jamais consulté, connaissance unique" width="514" height="665"> </div> </div> <div class="paragraph"> <p>Ce diagramme est la clé de tout. Les doublons (jaune) sont du bruit pur — l’agent les lit deux fois, dans deux fichiers différents. Le jamais consulté (rouge) est de la documentation morte — écrite avec soin, jamais utilisée. Seul le vert contient de la connaissance que l’agent ne peut pas trouver ailleurs.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_peur_de_perdre_lingénierie">La peur de perdre l’ingénierie</h2> <div class="sectionbody"> <div class="paragraph"> <p>À ce stade, j’ai l’évidence sous les yeux : je dois réduire <code>AGENT_MODUS_OPERANDI.adoc</code>. Mais j’hésite.</p> </div> <div class="paragraph"> <p>Ce fichier, je l’ai écrit à la main. Chaque section est le résultat d’une leçon apprise en session réelle. La partie P3 est née d’un <code>rm -rf</code> accidentel sur <code>bakery-plugin</code> qui m’a coûté des tokens Firebase réels. La partie P4 est le résultat de quinze sessions où j’oubliais d’archiver et je perdais le fil. La procédure en 6 étapes n’est pas sortie d’un livre — elle est sortie de la douleur.</p> </div> <div class="paragraph"> <p>Supprimer ces sections, ce serait jeter l’historique de ma propre ingénierie. Les leçons qui les ont produites, les sessions pendant lesquelles je les ai découvertes, les erreurs que je ne veux plus jamais refaire. Ce n’est pas du texte — c’est de l’expérience cristallisée.</p> </div> <div class="paragraph"> <p>C’est là que je formule le principe qui va guider la solution :</p> </div> <div class="paragraph"> <p><em><em>_ <strong>Ne jamais supprimer. Toujours relocaliser.</strong> La connaissance n’a pas à disparaître du projet. Elle a juste à ne pas être chargée automatiquement quand elle n’est pas nécessaire. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solution_split_encyclopédique">La solution : split encyclopédique</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le modèle que je propose est simple et s’inspire de la façon dont Wikipédia a grandi : quand un article devient trop long, on ne le coupe pas — on crée un article détaillé et on garde un résumé dans l’article principal.</p> </div> <div class="paragraph"> <p>Pour <code>AGENT_MODUS_OPERANDI.adoc</code>, cela donne :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Extraire</strong> les 161 lignes de connaissance unique (P1 + P2) dans un nouveau fichier <code>LAZY_EAGER_ESSENTIALS.adoc</code> — compacté à ~50 lignes, strictement EAGER</p> </li> <li> <p><strong>Renommer</strong> <code>AGENT_MODUS_OPERANDI.adoc</code> en <code>.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc</code> — le fichier original de 627 lignes, préservé <strong>intact</strong>, en cold storage</p> </li> <li> <p><strong>Ne jamais charger</strong> le fichier encyclopédie automatiquement — il est là pour l’humain, pour la distillation future, pour l’agent qu’on invoquera dans six mois avec un meilleur modèle</p> </li> </ol> </div> <div id="diag-split-solution" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-1ca7b1421a06e9049df1c3513a7924d2.svg" alt="Architecture du split encyclopédique — ESSENTIALS EAGER + ENCYCLOPEDIE cold storage" width="762" height="530"> </div> </div> <div class="paragraph"> <p>Le nom <code>encyclopedies/</code> n’est pas anodin. Une encyclopédie, ce n’est pas un dossier d’archives — c’est une collection de connaissance organisée, consultable mais pas portable. On ne lit pas l’Encyclopédie Universalis dans le métro. On la garde dans la bibliothèque, et on y va quand on a une question précise.</p> </div> <div class="paragraph"> <p>C’est exactement le rôle de ce dossier : une bibliothèque de référence froide, structurée, exhaustive — que l’agent ne touche pas automatiquement.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_contenu_du_fichier_essentials">Le contenu du fichier ESSENTIALS</h2> <div class="sectionbody"> <div class="paragraph"> <p>Voici à quoi ressemble concrètement le nouveau fichier <code>LAZY_EAGER_ESSENTIALS.adoc</code>, extrait et compacté à partir de P1 et P2 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Stratégie LAZY/EAGER — Principes Essentiels [abstract] Ce fichier définit la stratégie de gestion du contexte agent. Chargé automatiquement (EAGER) en début de session. == Principes |=== | EAGER | LAZY | Tableau de bord | Manuel du propriétaire | Chargé automatiquement | Chargé sur demande | <= 100 lignes, <= 10k tokens | Illimité, détaillé | Règles absolues, mission courante | Archives, historique, références |=== == Politique de Chargement |=== | Fichier | Type | Quand charger | PROMPT_REPRISE.adoc | EAGER | Début session (auto) | *_ESSENTIALS.adoc | EAGER | Début session si EPIC active | .agents/INDEX.adoc | EAGER | Début session (auto) | *_REFERENCE.adoc | LAZY | Sur besoin (détails architecture) | .agents/sessions/N-*.adoc | LAZY | Sur demande (détails session) | .agents/encyclopedies/*.adoc | COLD | Jamais auto (humain seulement) |=== == Comment l'Agent Sait Quoi Charger Début session → PROMPT_REPRISE + INDEX + ESSENTIALS actifs. Besoin de détails → charger les *_REFERENCE et sessions/ en LAZY. Connaissance froide → encyclopedies/, jamais automatique.</code></pre> </div> </div> <div class="paragraph"> <p>Cinquante lignes. C’est tout ce dont l’agent a besoin pour comprendre la mécanique. Tout le reste — l’historique des leçons, les analogies détaillées, les procédures pas à pas, les annexes — vit dans l’encyclopédie.</p> </div> <div class="paragraph"> <p>Et le plus important : <strong>rien n’a été supprimé</strong>. Les 627 lignes d’ingénierie sont toujours là, dans <code>.agents/encyclopedies/LAZY_EAGER_ENCYCLOPEDIE.adoc</code>. Elles sont juste rangées dans la bibliothèque plutôt que sur le plan de travail.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_résultat_50_de_contexte_eager">Le résultat : -50% de contexte EAGER</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant le split :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 627 AGENT_MODUS_OPERANDI.adoc 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 1414 total</code></pre> </div> </div> <div class="paragraph"> <p>Après le split :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs"> 287 AGENT.adoc 50 LAZY_EAGER_ESSENTIALS.adoc ← remplace 627 lignes 51 PROMPT_REPRISE.adoc 218 .agents/INDEX.adoc 18 .agents/SESSIONS_HISTORY.adoc 213 .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc 837 total ← -41%</code></pre> </div> </div> <div id="diag-after-audit" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-4ca8c26a5cbdc6d1078c3680e6b90bec.svg" alt="Répartition des 837 lignes EAGER après audit — gain de 41%" width="687" height="230"> </div> </div> <div class="paragraph"> <p>Le plus gros consommateur (AGENT_MODUS_OPERANDI, 627 lignes) a été remplacé par un fichier de 50 lignes. Le gain est immédiat : 577 lignes de contexte libérées. L’agent respire.</p> </div> <div class="paragraph"> <p>Et dans <code>.agents/encyclopedies/</code>, le fichier original de 627 lignes attend. Intact. Avec toutes ses sections — y compris celles qui sont des doublons, y compris celles qui n’ont jamais servi. Parce qu’un jour, un meilleur modèle ou un data scientist humain voudra croiser ces angles, ces redondances assumées, ces leçons apprises. Et ce jour-là, la matière première sera là.</p> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_le_dossier_sappelle_encyclopedies">Pourquoi le dossier s’appelle <code>encyclopedies/</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>Le choix du nom n’est pas cosmétique. Il encode la philosophie du mécanisme.</p> </div> <div class="paragraph"> <p>Une <strong>archive</strong> (<code>archives/</code>) contient des données historiques organisées chronologiquement — comme les COMPLETED_TASKS mensuels. Un <strong>backup</strong> (<code>backup/</code>) est un snapshot horodaté — une copie de sécurité d’un état passé.</p> </div> <div class="paragraph"> <p>Une <strong>encyclopédie</strong>, c’est autre chose. C’est une collection de connaissance thématique, structurée par sujet, exhaustive mais non linéaire. On ne lit pas une encyclopédie du début à la fin. On y plonge pour répondre à une question précise.</p> </div> <div class="paragraph"> <p>C’est exactement le contrat de ce dossier :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Dossier</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rôle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Accès</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Granularité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>archives/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Données historiques (tâches terminées par mois)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LAZY, structuré</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chronologique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>backup/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Snapshots froids (vagues de 10 sessions)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">COLD, copie intégrale</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chronologique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>encyclopedies/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Connaissance thématique exhaustive (méthodologie, patterns)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">COLD, jamais auto</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Thématique</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Cette distinction évite le fourre-tout. Chaque fichier sait où il doit vivre selon <strong>ce qu’il contient</strong>, pas selon <strong>quand il a été créé</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_suite_logique_de_la_série">La suite logique de la série</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si vous avez lu les deux premiers articles, voici comment les trois pièces s’emboîtent :</p> </div> <div id="diag-trilogie" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-7a93be1f2d7bbeab8cf9d47564547c7c.svg" alt="Les trois articles de la série gouvernance — progression logique" width="1216" height="493"> </div> </div> <div class="ulist"> <ul> <li> <p><strong>0108</strong> répond à : « Comment donner une mémoire à l’agent entre deux sessions ? »</p> </li> <li> <p><strong>0110</strong> répond à : « Comment empêcher cette mémoire d’étouffer l’agent ? »</p> </li> <li> <p><strong>0111</strong> répond à : « Et si le problème n’est pas la taille des archives, mais ce qu’on a <strong>choisi</strong> de mettre en EAGER ? »</p> </li> </ul> </div> <div class="paragraph"> <p>Le premier article a construit la structure. Le deuxième a ajouté le mécanisme de vieillissement. Le troisième audite le contenu — et découvre que la méthodologie elle-même est devenue le problème.</p> </div> </div> </div> <div class="sect1"> <h2 id="_ce_que_jaurais_fait_différemment">Ce que j’aurais fait différemment</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avec le recul, je vois l’erreur de conception initiale. <code>AGENT_MODUS_OPERANDI.adoc</code> a été créé comme un document unique — un manifeste. C’était la bonne approche pour formaliser la pensée. Mais une fois la pensée formalisée, le document aurait dû être splité immédiatement : l’essentiel en EAGER, l’exhaustif en cold.</p> </div> <div class="paragraph"> <p>Je ne l’ai pas fait parce que j’étais fier du document. 627 lignes d’ingénierie pure, écrites à la main, chaque section fruit d’une leçon de session. C’était mon œuvre. Et comme tout auteur, j’ai eu du mal à la découper.</p> </div> <div class="paragraph"> <p>La leçon : <strong>ce n’est pas parce qu’un document est bon qu’il doit être chargé automatiquement</strong>. La qualité du contenu n’a aucun rapport avec sa pertinence pour le contexte immédiat de l’agent.</p> </div> <div class="paragraph"> <p>Aujourd’hui, la règle est simple : tout document de plus de 100 lignes dans le contexte EAGER est un suspect. Il mérite un audit. Pas une condamnation — un audit. Et la question n’est jamais « faut-il le supprimer ? » mais « faut-il le charger à chaque session ? »</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_guide_pour_auditer_votre_propre_contexte">Le guide pour auditer votre propre contexte</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si vous avez suivi les deux premiers articles et mis en place votre propre gouvernance Eager/Lazy, voici une procédure d’audit en cinq étapes :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Mesurer</strong> : <code>wc -l</code> sur tous vos fichiers EAGER. Le total devrait être sous 1000 lignes.</p> </li> <li> <p><strong>Identifier le plus gros</strong> : le fichier qui pèse plus de 20% du total est le suspect numéro un.</p> </li> <li> <p><strong>Auditer section par section</strong> : pour chaque section, demandez-vous « Est-ce que cette information est déjà ailleurs ? Est-ce que l’agent l’a déjà lue dans un autre fichier ? Est-ce qu’elle a servi dans les 5 dernières sessions ? »</p> </li> <li> <p><strong>Classifier</strong> : doublon, jamais utilisé, connaissance unique.</p> </li> <li> <p><strong>Splitter ou relocaliser</strong> : ce qui est unique et critique → ESSENTIALS compacté. Tout le reste → <code>encyclopedies/</code>.</p> </li> </ol> </div> <div id="diag-audit-checklist" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-5bc9a34fb18adeac0f7da7af8a309acd.svg" alt="Procédure d’audit en 5 étapes" width="430" height="741"> </div> </div> <div class="paragraph"> <p>Cette procédure prend 15 minutes. Sur un projet de 50 sessions, elle économise des centaines de tokens par session future. Le ROI est immédiat.</p> </div> </div> </div> <div class="sect1"> <h2 id="_une_gouvernance_vivante">Une gouvernance vivante</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce que cette série de trois articles m’a appris, c’est que la gouvernance agent n’est pas un produit fini. C’est un <strong>organisme vivant</strong>. Elle grandit avec le projet. Elle attrape des maladies de croissance. Elle nécessite des check-ups réguliers.</p> </div> <div class="paragraph"> <p>La session 048 a révélé que les archives gonflent. La session 051 a révélé que la méthodologie elle-même gonfle. La session 060 révélera probablement autre chose. C’est normal. C’est sain. Une gouvernance qui ne se remet jamais en question est une gouvernance morte.</p> </div> <div class="paragraph"> <p>Les trois mécanismes mis en place — Eager/Lazy, Hot/Warm/Cold, split encyclopédique — forment un système de défense en profondeur contre la saturation du contexte. Aucun n’est suffisant seul. Ensemble, ils se complètent :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Eager/Lazy</strong> structure l’information <strong>par disponibilité</strong></p> </li> <li> <p><strong>Hot/Warm/Cold</strong> structure l’information <strong>par fraîcheur</strong></p> </li> <li> <p><strong>Audit encyclopédique</strong> structure l’information <strong>par densité</strong></p> </li> </ul> </div> <div id="diag-defense-in-depth" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-c815b1bc714a7df30a365994ac557d7d.svg" alt="Les trois couches de défense contre la saturation du contexte" width="672" height="345"> </div> </div> <div class="paragraph"> <p>Avec ces trois couches, le contexte agent sur <code>magic-stick</code> est passé de 2087 lignes (avant toute optimisation) à environ 800 lignes — une division par 2,6. Sans avoir perdu une seule ligne de documentation, une seule archive de session, une seule leçon apprise.</p> </div> <div class="paragraph"> <p>Tout est là. Juste mieux rangé.</p> </div> </div> </div> <div class="sect1"> <h2 id="_liens">Liens</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Article 0108 — Stratégie Eager/Lazy : <a href="/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html">Gouverner un Agent IA avec du AsciiDoc</a></p> </li> <li> <p>Article 0110 — Mécanisme Hot/Warm/Cold : <a href="/blog/2026/0110_mecanisme_backup_contexte_agent_post.html">Sliding Window et Vague Froide</a></p> </li> <li> <p>Mon site : <a href="https://cheroliv.com" class="bare">https://cheroliv.com</a></p> </li> <li> <p>Le projet <code>magic-stick</code> : <a href="https://github.com/cheroliv/magic-stick" class="bare">https://github.com/cheroliv/magic-stick</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p><strong>La connaissance n’a pas à disparaître. Elle a juste à ne pas être chargée quand elle n’est pas nécessaire.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0110_mecanisme_backup_contexte_agent_post.html Sun, 26 Apr 2026 00:00:00 +0000 blog/2026/0110_mecanisme_backup_contexte_agent_post.html <div class="sect1"> <h2 id="_résumé">Résumé</h2> <div class="sectionbody"> <div class="paragraph"> <p>Après 48 sessions sur un seul projet et 150+ au total, le système de gouvernance Eager/Lazy que j’avais construit avec soin commençait à s’étouffer. Les fichiers agents, censés être légers, pesaient 5200 lignes cumulées. Le contexte auto-chargé montait plus vite que ma capacité à le contrôler. Cet article raconte comment j’ai conceptualisé un mécanisme de backup — entre sliding window et vague froide identique — pour maintenir un contexte actif léger sans jamais rien perdre.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_signal_5200_lignes">Le Signal : 5200 Lignes</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je suis en pleine session 048 sur <code>magic-stick</code>, mon projet de build d’ISO Linux live. Opencode me regarde. Comme toujours, il a chargé automatiquement mes fichiers Eager en début de session — <code>AGENT.adoc</code>, <code>PROMPT_REPRISE.adoc</code>, <code>.agents/INDEX.adoc</code>. Rien d’anormal.</p> </div> <div class="paragraph"> <p>Sauf que quelque chose cloche. Les réponses sont plus lentes. Le raisonnement est plus dilué. L’agent oublie des détails qu’il avait sous les yeux il y a deux messages.</p> </div> <div class="paragraph"> <p>J’ouvre un terminal et je tape :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">wc -l .agents/INDEX.adoc .agents/SESSIONS_HISTORY.adoc \ .agents/archives/COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></pre> </div> </div> <div class="paragraph"> <p>260 lignes pour INDEX. 55 pour SESSIONS_HISTORY. <strong>1756 pour COMPLETED_TASKS_ARCHIVE</strong>.</p> </div> <div class="paragraph"> <p>Le dossier <code>sessions/</code> ajoute encore ~3200 lignes. Total : <strong>5200 lignes</strong> de contexte qui se chargent, d’une manière ou d’une autre, dans le cerveau temporaire de l’agent.</p> </div> <div class="paragraph"> <p>La stratégie Eager/Lazy que j’avais théorisée à l’article précédent fonctionne — mais elle a un défaut de naissance que je n’avais pas anticipé : elle n’a <strong>pas de mécanisme de vieillissement</strong>. Chaque session ajoute une ligne à INDEX, un paragraphe à COMPLETED_TASKS, un fichier dans sessions/. Rien ne sort jamais. Le contexte est une boule de neige qui grossit à chaque nouvelle session.</p> </div> <div id="diag-growth" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-95c83a721c5c943661137fb4c7f9bc23.svg" alt="Courbe de croissance des fichiers agents — de la session 1 à 48" width="427" height="591"> </div> </div> <div class="paragraph"> <p>Ce n’est pas un bug, c’est une conséquence directe de la procédure de fin de session qui archive méticuleusement chaque détail. Le système est victime de son propre succès.</p> </div> </div> </div> <div class="sect1"> <h2 id="_le_diagnostic_triple_redondance">Le Diagnostic : Triple Redondance</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je demande à l’agent de diagnostiquer le problème. Sa réponse est immédiate et chirurgicale.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fichier</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lignes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rôle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Problème</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/INDEX.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">260+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER (chargé auto)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Table de toutes les sessions depuis la 001 — <strong>+1 ligne par session</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/SESSIONS_HISTORY.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">55</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Table récapitulative — <strong>redondance avec INDEX</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>COMPLETED_TASKS_ARCHIVE_2026-04.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">1756</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">EAGER (implicite)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Détails complets de toutes les sessions d’avril</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.agents/sessions/*.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~5200 total</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">LAZY (supposé)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Archives individuelles, mais <strong>pas utilisées</strong> car tout est déjà dans COMPLETED_TASKS</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>L’agent identifie quatre causes racines :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>COMPLETED_TASKS_ARCHIVE absorbe tout</strong> — Au lieu de pointer vers les archives <code>.sessions/</code>, il recopie intégralement chaque session.</p> </li> <li> <p><strong>INDEX.adoc fait office d’historique complet</strong> — Le tableau "Sessions Récentes" contient 30+ entrées.</p> </li> <li> <p><strong>SESSIONS_HISTORY.adoc redondant</strong> — Même info que INDEX, format différent.</p> </li> <li> <p><strong>La règle LAZY n’est pas respectée</strong> — COMPLETED_TASKS est implicitement EAGER car il contient tout.</p> </li> </ol> </div> <div class="paragraph"> <p>Sa proposition est radicale : limiter INDEX à 10 sessions, vider COMPLETED_TASKS, déplacer SESSIONS_HISTORY en LAZY pur. Gain immédiat : <strong>~1900 lignes économisées</strong>.</p> </div> <div class="paragraph"> <p>C’est propre, efficace, logique. Mais j’ai un problème avec cette approche.</p> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_jai_refusé_la_solution_évidente">Pourquoi J’ai Refusé la Solution Évidente</h2> <div class="sectionbody"> <div class="paragraph"> <p>La solution de l’agent est celle d’un ingénieur qui optimise un cache. Limiter. Tronquer. Supprimer les redondances.</p> </div> <div class="paragraph"> <p>Mais ces "redondances" n’en sont pas. Chaque fichier de gouvernance capture un <strong>angle différent</strong> sur la même réalité :</p> </div> <div class="ulist"> <ul> <li> <p><strong>INDEX</strong> = vue macro, tableau de bord exécutif</p> </li> <li> <p><strong>SESSIONS_HISTORY</strong> = table chronologique linéaire, scorée</p> </li> <li> <p><strong>COMPLETED_TASKS_ARCHIVE</strong> = narrative détaillée avec métriques</p> </li> <li> <p><strong>sessions/*.adoc</strong> = archives individuelles, contexte complet</p> </li> </ul> </div> <div class="paragraph"> <p>Ce n’est pas de la duplication bête. C’est de la <strong>perspective multiple structurée</strong>. C’est exactement ce dont on a besoin pour distiller — pour que plus tard, un humain (ou un futur LLM mieux entraîné) puisse croiser les angles et extraire des patterns.</p> </div> <div class="paragraph"> <p>Imaginez un data scientist qui vous dit : « Supprimons 3 colonnes sur 6, elles sont corrélées. » Vous lui répondez quoi ? Que la corrélation n’est pas de la redondance quand chaque colonne capture une dimension différente du même phénomène. Que c’est précisément cette richesse dimensionnelle qui rend le dataset exploitable.</p> </div> <div class="paragraph"> <p>C’est mon intuition. Et je la défends contre la rationalité froide de l’agent.</p> </div> <div class="paragraph"> <p><em><em>_ Je ne vois pas de fourre-tout silencieux dans mon idée. On ne fourre pas tout, on déplace le résultat structuré de la procédure de fin de session — chaque fichier avec son angle, ses redondances qui sont en réalité un enrichissement. C’est ce matériel multidimensionnel qui sera meilleur pour la distillation. </em>_</em></p> </div> <div class="paragraph"> <p>L’agent accuse le coup. Et se corrige.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_proposition_vague_froide_identique">La Proposition : Vague Froide Identique</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’agent propose alors un mécanisme plus fin, qui respecte mon intuition de dataset riche tout en résolvant le problème technique du contexte qui explose.</p> </div> <div class="paragraph"> <p>Le principe est simple et s’inspire directement du pattern <strong>Hot/Warm/Cold Storage</strong> appliqué à la gestion d’archives :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Hot (EAGER)</strong> = les 10 dernières sessions dans INDEX, PROMPT_REPRISE de la session N+1, les 2 derniers fichiers de session</p> </li> <li> <p><strong>Warm (LAZY)</strong> = SESSIONS_HISTORY récent, SCRIPT_VERIFICATION, toute la documentation de référence</p> </li> <li> <p><strong>Cold (backup/)</strong> = tout le reste, déplacé <strong>intact</strong>, sans transformation, sans réindexation</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- .agents/ ├── INDEX.adoc → Sessions N-9 à N (10 dernières) ├── SESSIONS_HISTORY.adoc → Sessions N-9 à N ├── SCRIPT_VERIFICATION.adoc → Dernière vérif (pas d'historique) ├── PROMPT_REPRISE.adoc → Session N+1 uniquement ├── sessions/ → Sessions N-1 à N uniquement └── backup/ └── Y2026-sessions-001-039/ ← Vague froide, COPIE INTÉGRALE ├── INDEX.adoc → Sessions 001 à 039 (complet) ├── SESSIONS_HISTORY.adoc → Sessions 001 à 039 (complet) ├── COMPLETED_TASKS_ARCHIVE.adoc → Sessions 001 à 039 (complet) └── sessions/ → 001.adoc, 002.adoc... ---- La clé du mécanisme : **le backup n'est pas un index central, c'est une copie conforme de la vague passée**. Quand on dépasse l'horizon des 10 sessions actives, on ne supprime rien. On ne réindexe rien. On ne fusionne rien. On prend le paquet de fichiers agents tel qu'il était à la session N-10, et on le déplace dans `backup/`. Les fichiers actifs, eux, sont tronqués : * INDEX : uniquement les 10 dernières lignes (sliding window) * SESSIONS_HISTORY : idem * COMPLETED_TASKS_ARCHIVE : nouveau fichier pour la période en cours * sessions/ : uniquement les 2 dernières sessions [plantuml, format=svg, id=diag-hot-warm-cold, alt="Architecture Hot/Warm/Cold du contexte agent — EAGER/LAZY/backup"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Architecture Hot / Warm / Cold du Contexte Agent package "HOT (EAGER)\nChargé automatiquement\n~300 lignes" as HOT #FFCDD2 { file "INDEX.adoc\n(10 sessions)" as IDX_HOT file "PROMPT_REPRISE\n(session N+1)" as PRO_HOT file "AGENT.adoc\n(règles absolues)" as AG_HOT } package "WARM (LAZY)\nChargé sur demande\n~500 lignes" as WARM #FFF9C4 { file "SESSIONS_HISTORY\n(10 dernières)" as HIS_WARM file "SCRIPT_VERIFICATION\n(dernière)" as VER_WARM file "PROCEDURES.adoc\n(templates)" as PRO_WARM file "*_REFERENCE.adoc\n(doc technique)" as REF_WARM } package "COLD (backup/)\nJamais chargé\nLecture humaine uniquement" as COLD #BBDEFB { folder "Y2026-001-039/" as WAVE { file "INDEX (complet)" as IDX_COLD file "SESSIONS_HISTORY\n(complet)" as HIS_COLD file "COMPLETED_TASKS\n(complet)" as ARCH_COLD folder "sessions/ (001-039)" as SESS_COLD } folder "Y2026-040-???\n(future)" as FUTURE } HOT --> WARM : "Agent remonte\nsi besoin" WARM --> COLD : "Jamais automatique\nL'humain y va seul" note bottom of COLD Règle : COPIE INTÉGRALE Pas de transformation Pas de réindexation Read-only après archivage end note @enduml ---- Le gain immédiat est massif : le contexte EAGER passe de **~5200 lignes à ~300 lignes**. Une division par 17. Sans avoir perdu une seule ligne de données historiques. == Pourquoi Ce N'est Pas un Fourre-Tout L'agent, dans sa première itération, craignait que `backup/` devienne une boîte noire — un dossier où l'on jette des fichiers qu'on ne relira jamais. C'est une peur légitime. Mais elle repose sur une confusion. Un fourre-tout, c'est quand on jette des fichiers **sans structure, sans convention, sans logique de regroupement**. Ici, le backup est structuré par période (Y2026-001-039), et chaque dossier de backup contient **la même structure** que le dossier `.agents/` actif : INDEX, SESSIONS_HISTORY, COMPLETED_TASKS_ARCHIVE, sessions/. Ce n'est pas un fourre-tout. C'est un **snapshot horodaté**. On pourrait même dire que c'est un mécanisme de versioning simplifié — à ceci près qu'il ne versionne pas les fichiers individuellement, mais le paquet complet de la gouvernance à un instant T. Quand vous voulez retrouver une information ancienne, vous n'avez pas besoin d'un index central. Vous avez deux options : 1. **`grep` ciblé** : `grep -r "zsh" backup/Y2026-001-039/` — et vous trouvez tout ce qui mentionne zsh dans la période, quel que soit l'angle (INDEX, SESSIONS_HISTORY, archive de session). 2. **Réintégration manuelle** : vous copiez temporairement le dossier de backup dans le contexte actif, et vous demandez à l'agent d'analyser cette période spécifique. L'index est implicite. Il est dans la structure même des fichiers — chacun étant déjà un index depuis son propre angle. == La Méthaphore des Étagères Pour rendre le mécanisme intuitif, je l'ai conceptualisé en trois étagères : * **Étagère 1 (EAGER)** — le plan de travail. Ce dont j'ai besoin *maintenant*. INDEX récent, PROMPT_REPRISE, règles absolues. Léger, immédiat, critique. * **Étagère 2 (LAZY)** — la bibliothèque de consultation. Ce que je peux aller chercher sur demande. Références techniques, historique récent, procédures. Plus volumineux, mais pas chargé en mémoire. * **Cave (backup/)** — les archives froides. Tout ce qui est passé mais que je ne veux pas jeter. L'agent n'y entre jamais. L'humain y descend quand il veut distiller. L'agent a proposé initialement une quatrième étagère — un `index-backup.adoc` qui serait LAZY et contiendrait une table des matières de tout le backup. J'ai refusé. Ce serait une redondance de plus dans un système qui souffre déjà de croissance linéaire. La structure des fichiers archivés est déjà un index. == Le Capteur à Deux Déclencheurs La conceptualisation était solide, mais il restait un angle mort : **quand exactement déclencher la rotation ?** L'article initial l'identifiait comme une question ouverte. Deux jours plus tard, la réponse est codifiée dans les fichiers de gouvernance de six projets : un capteur à deux déclencheurs. === Le Déclencheur Automatique — `N % 10 == 0` Le premier déclencheur est mathématique. Quand le numéro de session est un multiple de 10 — session 10, 20, 30, 40 — la rotation backup s'exécute automatiquement au sein de la procédure de fin de session, juste après l'étape 6. Pourquoi 10 ? C'est le compromis entre deux forces contraires : une fenêtre trop courte (5 sessions) perd le contexte nécessaire à la continuité ; une fenêtre trop longue (20 sessions) ne résout pas le problème d'embonpoint du contexte. Dix sessions, sur un rythme de une à deux sessions par jour, couvrent environ une semaine de travail — assez pour que l'agent se souvienne des décisions récentes, pas assez pour que le contexte explose. === Le Déclencheur par Seuil — 500 Lignes EAGER Le second déclencheur est dynamique. Indépendamment du numéro de session, si les fichiers EAGER cumulés dépassent **500 lignes**, la rotation se déclenche. Ce seuil protège contre le scénario où les sessions sont exceptionnellement productives — beaucoup de contenu écrit en peu de sessions. Une session qui produit 120 lignes de contenu éditorial fait grossir COMPLETED_TASKS_ARCHIVE bien plus vite qu'une session de debug qui corrige deux lignes. Le seuil de 500 lignes, mesuré via `wc -l .agents/INDEX.adoc .agents/archives/COMPLETED_TASKS_ARCHIVE_*.adoc PROMPT_REPRISE.adoc`, capte cette asymétrie. === Le Déclencheur Manuel — "rotation backup" Enfin, l'humain garde la main. Les mots-clés `rotation backup`, `backup rotation` ou `lance la rotation backup` déclenchent la procédure sur demande, indépendamment de la fin de session. Utile quand on sent que le contexte devient lourd mais qu'on n'est pas encore à un multiple de 10, ou quand on veut archiver une phase de travail avant d'en commencer une nouvelle. [plantuml, format=svg, id=diag-capteur-trigger, alt="Les trois déclencheurs du capteur de rotation backup — automatique, seuil, manuel"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Capteur de Rotation Backup — Les Trois Déclencheurs start :Procédure de fin de session; note right: Mots-clés "fin de session"\nou "on arrête là" :Étapes 1 à 6\n(archivage standard); note right 1. Archive sessions/N.adoc 2. MAJ PROMPT_REPRISE 3. MAJ SESSIONS_HISTORY 4. MAJ INDEX.adoc 5. MAJ TEST_COVERAGE 6. MAJ COMPLETED_TASKS end note if (N % 10 == 0\nOU\nEAGER cumulé > 500 lignes ?) then (oui) :⚙️ Rotation Backup\n(étape 7); note right 1. Créer backup/Y20XX-sessions-X-Y/ 2. Copier intégrale INDEX + HISTORY + COMPLETED_TASKS + sessions/ 3. Tronquer actifs à 10 sessions 4. Ajouter _Localisation active_ end note else (non) :Pas de rotation; endif :Checklist [✅] x 7\n(si applicable); stop @enduml ---- Ce diagramme montre l'insertion exacte du capteur dans la procédure de fin de session. L'étape 7 est optionnelle — elle ne s'exécute que si une des deux conditions est vraie — mais elle est systématiquement *vérifiée*. La checklist finale inclut `[✅] 7. Backup roté (si applicable)`. === La Boucle Fermée Ce capteur referme la boucle ouverte par l'article précédent. La gouvernance Eager/Lazy avait résolu le problème de la mémoire agent entre deux sessions. Le mécanisme Hot/Warm/Cold a résolu le problème de la mémoire qui grossit. Le capteur à deux déclencheurs résout le problème du *quand* — retirant à l'humain la charge mentale de surveiller la taille du contexte. [plantuml, format=svg, id=diag-boucle-fermee, alt="Les trois couches de la gouvernance agent — Eager/Lazy, Hot/Warm/Cold, Capteur"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Les Trois Couches de la Gouvernance Agent left to right direction package "Couche 1 — Mémoire\n(Article 0108)" as C1 #E8F5E9 { rectangle "**EAGER**\nTableau de bord\nChargé auto" as EAG rectangle "**LAZY**\nManuel propriétaire\nChargé sur demande" as LAZ EAG -[hidden]right-> LAZ } package "Couche 2 — Vieillissement\n(Article 0110)" as C2 #FFF9C4 { rectangle "**HOT**\n10 sessions actives\n~300 lignes" as HOT rectangle "**WARM**\nRéférences\nProcédures" as WRM rectangle "**COLD**\nbackup/\nVague froide" as CLD HOT -[hidden]right-> WRM WRM -[hidden]right-> CLD } package "Couche 3 — Déclencheur\n(Aujourd'hui)" as C3 #BBDEFB { rectangle "**Auto**\nN % 10 == 0" as AUTO rectangle "**Seuil**\n> 500 lignes" as SEUIL rectangle "**Manuel**\nrotation backup" as MAN AUTO -[hidden]right-> SEUIL SEUIL -[hidden]right-> MAN } C1 --> C2 : "La mémoire grandit\n→ il faut un mécanisme\nde vieillissement" C2 --> C3 : "Le vieillissement\n→ il faut un déclencheur\npour l'exécuter" note bottom of C3 ✅ Déployé sur 6 projets magic-stick · bakery-gradle plantuml-gradle · cheroliv.com jhipster-gradle-plugins quizz-benchmark-gradle end note @enduml ---- Les trois couches s'empilent logiquement. La première donne une mémoire à l'agent. La deuxième empêche cette mémoire d'étouffer l'agent. La troisième automatise la maintenance de cette mémoire pour que l'humain n'ait pas à y penser. === La Migration Effective sur cheroliv.com Le mécanisme n'est pas resté théorique. Sur `cheroliv.com`, la première rotation backup a été exécutée le 29 avril 2026 — les sessions -6 à 2 ont migré vers `.agents/backup/Y2026-sessions-neg6-a-002/` : |=== |Fichier |Avant rotation |Après rotation |Gain |`.agents/INDEX.adoc` |19 sessions listées |10 sessions (3-12) |-9 entrées |`.agents/SESSIONS_HISTORY.adoc` |18 sessions |10 sessions |-8 entrées |`COMPLETED_TASKS_ARCHIVE` |161 lignes (sessions 1-12) |135 lignes (sessions 3-12) |-26 lignes |`sessions/` |20 fichiers |10 fichiers |-10 fichiers |**backup/** |Inexistant |1 vague froide (10 sessions archivées) |+1 paquet froid |=== Le gain en lignes était modeste — le projet est jeune, 12 sessions — mais l'important est que le **mécanisme est en place**. La prochaine rotation automatique se déclenchera à la session 20, ou plus tôt si les 500 lignes EAGER sont atteintes. == La Leçon Humain-Agent Cette session 048 m'a appris quelque chose de fondamental sur la collaboration avec un agent IA. L'agent a un biais naturel : il cherche à **optimiser**, à **simplifier**, à **éliminer les redondances**. C'est le biais d'un système entraîné à produire des réponses propres et concises. Face à un dataset riche et multidimensionnel, son premier réflexe est de le réduire à sa plus simple expression. L'humain, lui, a une intuition différente : il pressent que la redondance structurée est un **atout**, pas un défaut. Que la diversité des angles sur une même réalité est précisément ce qui permettra, plus tard, une distillation de qualité. Ce n'est pas que l'agent a tort. C'est que son "optimum" n'est pas le mien. L'agent optimise pour le **présent** — le contexte immédiat, la réponse rapide à la question posée. L'humain optimise pour le **futur** — la capacité à retrouver, croiser, distiller dans trois mois ou trois ans. ____ Ce que je veux, c'est le matériel brut. Tes réflexions, tes hésitations, tes réponses à mes questions. Pas ta synthèse. La synthèse, je sais la faire mieux que toi. Je veux la matière première. ____ Cette phrase que je lui ai dite en fin de session résume tout. L'agent est un outil de production. L'humain est l'outil de distillation. La gouvernance n'est pas faite pour que l'agent comprenne tout tout seul — elle est faite pour que l'humain puisse, plus tard, travailler le matériau produit. La vague froide identique est la traduction architecturale de cette philosophie : on ne jette rien, on ne fusionne rien, on ne réindexe rien. On déplace le paquet intact. La distillation viendra plus tard, à la main, par l'humain. == La Suite Logique de l'Article Précédent Si vous avez lu link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[l'article sur la stratégie Eager/Lazy], vous reconnaîtrez la progression naturelle : 1. **Article 0108** — La gouvernance Eager/Lazy : *comment* structurer le contexte agent en deux niveaux de disponibilité 2. **Cet article 0110** — Le mécanisme de backup : *comment* faire vieillir ce contexte sans le perdre quand il devient trop volumineux Le premier article répondait à la question : « L'agent ne se souvient de rien entre deux sessions, comment lui donner une mémoire ? » Celui-ci répond à la question qui découle inévitablement de la première : « La mémoire grossit à chaque session, comment l'empêcher d'étouffer l'agent sans l'effacer ? » La réponse tient en un pattern : **Hot/Warm/Cold**, appliqué aux fichiers de gouvernance. Et en un principe : **ne jamais rien perdre, toujours tout relocaliser**. == Liens * Article précédent : link:/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html[Gouverner un Agent IA avec du AsciiDoc] * Mon site : https://cheroliv.com * Le projet `magic-stick` : https://github.com/cheroliv/magic-stick --- *Un bon système de gouvernance ne supprime jamais de données. Il les range.*</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html Sat, 25 Apr 2026 00:00:00 +0000 blog/2026/0109_gradle_jhipster_docker_testcontainers_debugging_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scène_un_projet_jhipster_un_build_qui_ne_charge_plus">La scène : un projet JHipster, un build qui ne charge plus</a></li> <li><a href="#_erreur_1_la_variable_fantôme_reportsdir">Erreur 1 : la variable fantôme <code>reportsDir</code></a></li> <li><a href="#_erreur_2_main_nexiste_plus_sous_gradle_9">Erreur 2 : <code>main = "…​"</code> n’existe plus sous Gradle 9</a></li> <li><a href="#_erreur_3_sourcecompatibility_nest_plus_une_propriété_de_projet">Erreur 3 : <code>sourceCompatibility</code> n’est plus une propriété de projet</a></li> <li><a href="#_erreur_4_lassertion_groovy_à_trois_opérandes">Erreur 4 : l’assertion Groovy à trois opérandes</a></li> <li><a href="#_erreur_5_la_dépendance_implicite_compilekotlin_openapigenerate">Erreur 5 : la dépendance implicite <code>compileKotlin</code> → <code>openApiGenerate</code></a></li> <li><a href="#_erreur_6_generategitproperties_casse_sur_filteroutputstream_write">Erreur 6 : <code>generateGitProperties</code> casse sur <code>FilterOutputStream.write()</code></a></li> <li><a href="#_enfin_testcontainers_entre_en_scène">Enfin : Testcontainers entre en scène</a></li> <li><a href="#_phase_1_la_piste_docker_java">Phase 1 : la piste docker-java</a></li> <li><a href="#_phase_2_recherche_web_et_fil_dariane_github">Phase 2 : recherche web et fil d’ariane GitHub</a></li> <li><a href="#_phase_3_le_piège_des_artifacts_renommés">Phase 3 : le piège des artifacts renommés</a></li> <li><a href="#_phase_4_forcer_la_résolution">Phase 4 : forcer la résolution</a></li> <li><a href="#_résultat_final">Résultat final</a></li> <li><a href="#_tableau_récapitulatif_des_corrections">Tableau récapitulatif des corrections</a></li> <li><a href="#_conclusion">Conclusion</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 15 minutes</div> <p>Vous avez déjà connu ce moment où un simple <code>./gradlew build</code> que vous lancez cent fois par jour se met soudain à planter sur une erreur jamais vue ? Multipliez ça par onze erreurs successives, ajoutez une bonne dose d’incompatibilité Docker Engine 29, saupoudrez de Gradle 9 qui fait disparaître des API qu’on utilisait depuis dix ans. Voici le carnet de bord complet.</p> </div> <hr> <div class="paragraph"> <div class="title">Diagramme 1 — Migration Gradle 9 (chaîne d’erreurs)</div> <p>Objectif : montrer la série d’incompatibilités.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-6215da1a3f4f27918205b5c8ff34a48c.png" alt="Diagram" width="579" height="106"> </div> <div class="title">Figure 1. 👉 Clair, centré sur Gradle.</div> </div> <hr> <div class="paragraph"> <div class="title">Diagramme 2 — Plugins JHipster incompatibles</div> <p>Objectif : isoler les plugins cassés.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-07ed01d932957e366cd8fed4b8aee2a3.png" alt="Diagram" width="569" height="123"> </div> <div class="title">Figure 2. 👉 Vision propre des dépendances.</div> </div> <hr> <div class="paragraph"> <div class="title">Diagramme 3 — Docker 29 / Testcontainers</div> <p>Objectif : problème runtime.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-544e3a93289a5db5b898714292d384f4.png" alt="Diagram" width="788" height="123"> </div> <div class="title">Figure 3. 👉 Histoire claire du runtime.</div> </div> <hr> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-5d4d1754844f7121ef284aa0cc588011.png" alt="Diagram" width="1072" height="193"> </div> <div class="title">Figure 4. une autre maniere de se le representer</div> </div> </div> </div> <div class="sect1"> <h2 id="_la_scène_un_projet_jhipster_un_build_qui_ne_charge_plus">La scène : un projet JHipster, un build qui ne charge plus</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le projet <code>edster</code> est une application JHipster générée en 2024. Le build script racine <code>build.gradle</code> est resté stable pendant des mois. Puis on décide de monter en version :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1428%;"> <col style="width: 7.1436%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Composant</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Version cible</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">9.4.1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">21.0.11-tem (Eclipse Temurin)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JHipster</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8.x (framework <code>tech.jhipster:jhipster-framework:8.11.0</code>)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Spring Boot</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">3.4.5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">2.3.0</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Docker Engine</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">29.4.1 (API 1.54)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le changement de version Java passe via SDKMAN :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk use java 21.0.11-tem</code></pre> </div> </div> <div class="paragraph"> <p>Premier lancement :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon FAILURE: Build failed with an exception. * Where: Build file '/home/.../edster/build.gradle' line: 18 * What went wrong: An exception occurred applying plugin request [id: 'jhipster.cucumber-conventions'] > Failed to apply plugin 'jhipster.cucumber-conventions'. > Could not create task ':cucumberTest'. > Could not create task ':consoleLauncherTest'. > Could not set unknown property 'reportsDir' for task ':consoleLauncherTest'</code></pre> </div> </div> <div class="paragraph"> <p>On ne décolle même pas du chargement du build script. Le problème est dans <code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_erreur_1_la_variable_fantôme_reportsdir">Erreur 1 : la variable fantôme <code>reportsDir</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>Le script <code>jhipster.cucumber-conventions.gradle</code> contient :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">tasks.register('consoleLauncherTest', JavaExec) { dependsOn(testClasses) String cucumberReportsDir = file("$buildDir/reports/tests") outputs.dir(reportsDir) // <-- reportsDir n'existe PAS classpath = sourceSets["test"].runtimeClasspath main = "org.junit.platform.console.ConsoleLauncher" // ... }</code></pre> </div> </div> <div class="paragraph"> <p>La variable définie est <code>cucumberReportsDir</code>. Celle utilisée est <code>reportsDir</code> — qui n’est définie nulle part.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> : <code>outputs.dir(cucumberReportsDir)</code></p> </div> </div> </div> <div class="sect1"> <h2 id="_erreur_2_main_nexiste_plus_sous_gradle_9">Erreur 2 : <code>main = "…​"</code> n’existe plus sous Gradle 9</h2> <div class="sectionbody"> <div class="paragraph"> <p>Relance immédiate :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'main' for task ':consoleLauncherTest' of type org.gradle.api.tasks.JavaExec.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 supprime la propriété <code>main</code> au profit de <code>mainClass</code> sur les tâches <code>JavaExec</code>.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> : <code>mainClass = "org.junit.platform.console.ConsoleLauncher"</code></p> </div> </div> </div> <div class="sect1"> <h2 id="_erreur_3_sourcecompatibility_nest_plus_une_propriété_de_projet">Erreur 3 : <code>sourceCompatibility</code> n’est plus une propriété de projet</h2> <div class="sectionbody"> <div class="paragraph"> <p>Nouvelle erreur :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not set unknown property 'sourceCompatibility' for root project 'edster' of type org.gradle.api.Project.</code></pre> </div> </div> <div class="paragraph"> <p>Le script racine avait :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">sourceCompatibility=17 targetCompatibility=17</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 supprime ces propriétés au niveau root. Elles doivent vivre dans un bloc <code>java</code>.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">java { sourceCompatibility = JavaVersion.VERSION_21 targetCompatibility = JavaVersion.VERSION_21 }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_erreur_4_lassertion_groovy_à_trois_opérandes">Erreur 4 : l’assertion Groovy à trois opérandes</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’ancien script contenait :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] == "17" || "21" || "24"</code></pre> </div> </div> <div class="paragraph"> <p>En Groovy, <code>"21"</code> et <code>"24"</code> sont des strings truthy. L’expression résout en <code>(…​ == "17") || true || true</code>, ce qui est toujours vraie — mais la syntaxe est invalide pour l’assertion stricte souhaitée.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert System.properties["java.specification.version"] in ["17", "21", "23", "24"]</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_erreur_5_la_dépendance_implicite_compilekotlin_openapigenerate">Erreur 5 : la dépendance implicite <code>compileKotlin</code> → <code>openApiGenerate</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>Le build progresse. Compilation Kotlin réussie. Puis :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Task ':compileKotlin' uses this output of task ':openApiGenerate' without declaring an explicit or implicit dependency.</code></pre> </div> </div> <div class="paragraph"> <p>Gradle 9 refuse les dépendances implicites entre tâches. Puisque <code>compileKotlin</code> lit les sources générées par <code>openApiGenerate</code>, il faut déclarer le lien.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> dans <code>build.gradle</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">afterEvaluate { tasks.named("compileKotlin").configure { dependsOn(tasks.named("openApiGenerate")) } }</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>afterEvaluate</code> est nécessaire car <code>openApiGenerate</code> est une extension (plugin OpenAPI Generator) et non une tâche directement accessible pendant la phase de configuration.</p> </div> </div> </div> <div class="sect1"> <h2 id="_erreur_6_generategitproperties_casse_sur_filteroutputstream_write">Erreur 6 : <code>generateGitProperties</code> casse sur <code>FilterOutputStream.write()</code></h2> <div class="sectionbody"> <div class="paragraph"> <p>La compilation Java passe. Les ressources sont processées. Puis :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">> Task :generateGitProperties FAILED No signature of method: java.io.FilterOutputStream.write() is applicable for argument types: (Integer) values: [103]</code></pre> </div> </div> <div class="paragraph"> <p>Le plugin <code>gradle-git-properties</code> version 2.5.0 est incompatible avec Java 21 / Gradle 9. Un bug interne tente d’appeler <code>write(int)</code> via Groovy sur un flux qui l’a fermé.</p> </div> <div class="paragraph"> <p><strong>Correction</strong> dans <code>gradle.properties</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties">gitPropertiesPluginVersion=2.5.7</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_enfin_testcontainers_entre_en_scène">Enfin : Testcontainers entre en scène</h2> <div class="sectionbody"> <div class="paragraph"> <p>Jusqu’ici, c’était du "build script debugging" pur. Chaque erreur était une incompatibilité Gradle 9 ou Java 21 dans les scripts de build. Après les six corrections ci-dessus, le <code>./gradlew assemble</code> passe avec succès.</p> </div> <div class="paragraph"> <p>Mais <code>./gradlew build</code> exécute aussi les tests, et les tests Cucumber utilisent Testcontainers pour lancer un PostgreSQL éphémère.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">Could not find a valid Docker environment. EnvironmentAndSystemPropertyClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"} UnixSocketClientProviderStrategy: failed with exception BadRequestException (Status 400: {"message":"client version 1.32 is too old. Minimum supported API version is 1.40"}</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers est incapable de communiquer avec Docker. Deux stratégies différentes (variables d’environnement + socket Unix) échouent sur la même erreur.</p> </div> <div id="diag-docker-handshake" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-f31d9e10795d818ce3068413fb5fdd1e.svg" alt="Handshake Docker API refusé par le daemon" width="731" height="616"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_1_la_piste_docker_java">Phase 1 : la piste docker-java</h2> <div class="sectionbody"> <div class="paragraph"> <p>Premier réflexe : le client Docker Java utilisé par Testcontainers envoie la version API <code>1.32</code> dans son handshake HTTP, mais Docker Engine 29.4.1 exige un minimum de <code>1.40</code>. Le problème est au niveau du client, pas du daemon.</p> </div> <div class="paragraph"> <p>Vérification de la version de docker-java résolue par Testcontainers 1.20.6 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew dependencies --configuration testRuntimeClasspath | grep docker-java +--- com.github.docker-java:docker-java-api:3.4.1 +--- com.github.docker-java:docker-java-transport:3.4.1</code></pre> </div> </div> <div class="paragraph"> <p>docker-java 3.4.1, datant de Testcontainers 1.20.6. La dernière version publique de docker-java est 3.5.1. Tentons de forcer la montée de version via <code>resolutionStrategy</code> dans le bloc <code>configurations</code> de <code>build.gradle</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.5.1") } } } }</code></pre> </div> </div> <div class="paragraph"> <p>Relance du build. Même erreur : <code>client version 1.32 is too old</code>.</p> </div> <div class="paragraph"> <p>Vérification du cache Gradle : les JARs ont bien été re-téléchargés, mais l’erreur persiste. docker-java 3.5.1 envoie toujours <code>1.32</code>. Cette version n’est donc PAS suffisante pour Docker Engine 29.4.1.</p> </div> <div class="paragraph"> <p><strong>Action de purification</strong> : vider complètement le cache Gradle, juste pour être sûr :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">rm -rf ~/.gradle/caches rm -rf /path/to/project/.gradle</code></pre> </div> </div> <div class="paragraph"> <p>Relance complète après purge. Même erreur.</p> </div> </div> </div> <div class="sect1"> <h2 id="_phase_2_recherche_web_et_fil_dariane_github">Phase 2 : recherche web et fil d’ariane GitHub</h2> <div class="sectionbody"> <div class="paragraph"> <p>docker-java 3.5.1 est insuffisant. Ne reste plus qu’à chercher si quelqu’un a rencontré ce problème exact.</p> </div> <div class="paragraph"> <p>Recherche ciblée sur les issues testcontainers-java et docker-java :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">site:github.com/testcontainers "client version 1.32 is too old" site:github.com/docker-java "client version 1.32" Docker Engine 29</code></pre> </div> </div> <div class="paragraph"> <p>Premiers résultats immédiats :</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11210">testcontainers-java#11210</a> — <code>[Bug]: client version 1.32 is too old. Minimum supported API version is 1.44</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11212">testcontainers-java#11212</a> — <code>[Bug]: Docker 29.0.0 could not find a valid Docker environment</code></p> </li> <li> <p><a href="https://github.com/testcontainers/testcontainers-java/issues/11491">testcontainers-java#11491</a> — <code>[Bug]: Incompatibility in Ubuntu Github runners with Docker Engine 29.1.*</code></p> </li> </ul> </div> <div class="paragraph"> <p>Le fil d’Ariane est clair : Docker Engine 29.x a élevé son minimum API version de <code>1.24</code> (ancien défaut) à <code>1.40</code>. Testcontainers 1.20.x utilise docker-java 3.4.x qui négocie la version API en envoyant <code>1.32</code>. Le daemon refuse poliment mais fermement.</p> </div> <div class="paragraph"> <p>Dans l’issue #11491, un mainteneur répond :</p> </div> <div class="paragraph"> <p><em><em>_ Hi, I have a project running with version 2.0.3 on a GH runner with engine 29.1 and it works. Can you all please check there is no version conflict? Please, remember all modules were prefixed with <code>testcontainers-</code>. So, starting with version 2.x we went from <code>postgresql</code> to <code>testcontainers-postgresql</code> </em>_</em></p> </div> <div class="paragraph"> <p>Cette réponse contient <strong>deux informations critiques</strong> :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Testcontainers 2.0.3+ résout le problème</p> </li> <li> <p>Les modules ont été <strong>renommés avec le préfixe <code>testcontainers-</code></strong></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_phase_3_le_piège_des_artifacts_renommés">Phase 3 : le piège des artifacts renommés</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le renommage est brutal. En Testcontainers 2.x, plus aucun des anciens noms ne fonctionne sous ce nom-là :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> <col style="width: 10%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Ancien nom (1.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nouveau nom (2.x)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-postgresql</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-jdbc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers-junit-jupiter</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.testcontainers:testcontainers</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">inchangé</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Première tentative : appliquer la BOM Testcontainers 2.0.5 et les nouveaux noms d’artifacts dans <code>build.gradle</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers" }</code></pre> </div> </div> <div class="paragraph"> <p><code>./gradlew build</code></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">FAILURE: Could not find org.testcontainers:jdbc:2.0.5. Could not find org.testcontainers:junit-jupiter:2.0.5.</code></pre> </div> </div> <div class="paragraph"> <p><strong>Le BOM de testcontainers-bom ne suffit pas.</strong> Pourquoi ? Parce que Spring Boot 3.4.5 expose son propre BOM de gestion de dépendances (<code>spring-boot-dependencies</code>) qui <strong>gagne</strong> sur le BOM de Testcontainers dans la résolution transitive. Spring Boot fixe <code>testcontainers</code> à <code>1.20.6</code>, et donc tous les artifacts qui ne sont pas explicitement dans le BOM Spring Boot (comme les nouveaux <code>testcontainers-*</code>) résolvent vers les anciens noms <code>1.20.6</code> — qui n’existent plus dans cette version.</p> </div> <div class="paragraph"> <p>En inspectant le <code>dependencies --configuration testRuntimeClasspath</code>, on trouve :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">+--- org.testcontainers:testcontainers -> 1.20.6 (*) | \--- org.testcontainers:testcontainers:2.0.5 -> 1.20.6</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>→</code> indique la substitution : Testcontainers 2.0.5 est <strong>demandé</strong>, mais Spring Boot force <code>1.20.6</code>.</p> </div> <div id="diag-bom-war" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-714056a094f875d4bd0cf8db572918d3.svg" alt="Conflit entre le BOM Spring Boot et le BOM Testcontainers" width="1111" height="321"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_phase_4_forcer_la_résolution">Phase 4 : forcer la résolution</h2> <div class="sectionbody"> <div class="paragraph"> <p>La stratégie devient double :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Forcer docker-java à sa version 3.7.1 (testée comme compatible Docker Engine 29)</p> </li> <li> <p>Forcer Testcontainers core à 2.0.5 en contournant le BOM Spring Boot</p> </li> </ol> </div> <div id="diag-resolution-override" class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-0e6edf1a58135d9df65ae14483179ddf.svg" alt="resolutionStrategy.eachDependency court-circuite le BOM Spring Boot" width="1103" height="468"> </div> </div> <div class="paragraph"> <p><strong>Correction finale</strong> dans <code>build.gradle</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">configurations { all { resolutionStrategy.eachDependency { details -> if (details.requested.group == "com.github.docker-java" && details.requested.name.startsWith("docker-java")) { details.useVersion("3.7.1") } if (details.requested.group == "org.testcontainers" && details.requested.name == "testcontainers") { details.useVersion("2.0.5") } } } } dependencies { testImplementation platform("org.testcontainers:testcontainers-bom:2.0.5") testImplementation "org.testcontainers:testcontainers-jdbc" testImplementation "org.testcontainers:testcontainers-junit-jupiter" testImplementation "org.testcontainers:testcontainers-postgresql" testImplementation "org.testcontainers:testcontainers" // ... autres dépendances Spring Boot }</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>resolutionStrategy.eachDependency</code> est le seul moyen d’outrepasser le BOM <code>spring-boot-dependencies</code> géré par le plugin Spring Boot. Le test d’égalité sur <code>details.requested.name == "testcontainers"</code> est volontairement restrictif : on ne force que le module core. Les modules <code>testcontainers-*</code> suivent le BOM de Testcontainers 2.0.5 qu’on a explicitement déclaré.</p> </div> </div> </div> <div class="sect1"> <h2 id="_résultat_final">Résultat final</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build --no-daemon > Task :consoleLauncherTest [2 containers found] [2 containers started] [2 containers successful] BUILD SUCCESSFUL in 1m 16s</code></pre> </div> </div> <div class="paragraph"> <p>Testcontainers 2.0.5 + docker-java 3.7.1 parviennent enfin à créer leurs containers PostgreSQL via Docker Engine 29.4.1. L’erreur métier finale (HTTP 500 sur le test Cucumber) est un problème applicatif totalement indépendant du build script.</p> </div> </div> </div> <div class="sect1"> <h2 id="_tableau_récapitulatif_des_corrections">Tableau récapitulatif des corrections</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">Fichier</th> <th class="tableblock halign-left valign-top">Problème</th> <th class="tableblock halign-left valign-top">Correction</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variable <code>reportsDir</code> inexistante</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>outputs.dir(cucumberReportsDir)</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>buildSrc/src/main/groovy/jhipster.cucumber-conventions.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>main</code> déprécié Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>mainClass</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sourceCompatibility</code> top-level interdit Gradle 9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Bloc <code>java { sourceCompatibility = JavaVersion.VERSION_21 }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Assertion Groovy syntaxiquement invalide</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>assert …​ in ["17", "21", "23", "24"]</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Dépendance implicite <code>compileKotlin</code> → <code>openApiGenerate</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>afterEvaluate { tasks.named("compileKotlin").dependsOn("openApiGenerate") }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gradle.properties</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>gitPropertiesPluginVersion</code> incompatible Java 21</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>2.5.7</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Cache Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">docker-java 3.5.1 testé, résolu mais insuffisant</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Purge + passage docker-java 3.7.1</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.gradle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Testcontainers 1.20.6 incompatible Docker Engine 29</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Forçage Testcontainers 2.0.5 + prefix <code>testcontainers-*</code> + resolutionStrategy vs Spring Boot BOM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p>Si votre build JHipster/Gradle plante après une montée de version vers Gradle 9 + Docker Engine 29, les erreurs se répartissent en deux catégories :</p> </div> <div class="paragraph"> <p><strong>Erreurs de build script</strong> (les 6 premières) : Gradle 9 supprime des propriétés et des syntaxes qui marchaient depuis des années (<code>sourceCompatibility=</code>, <code>main =</code>, <code>reportsDir</code>). Ce sont des migrations mécaniques une fois qu’on connaît la nouvelle API.</p> </div> <div class="paragraph"> <p><strong>Erreurs de runtime Docker</strong> (les 2 dernières) : Docker Engine 29.4.1 écarte les clients API < 1.40. Testcontainers 1.20.6 (imposé par Spring Boot 3.4.5) utilise docker-java 3.4.1 qui envoie 1.32. Seul Testcontainers 2.0.5 + docker-java 3.7.1 résout le problème, avec le renommage des artifacts et le forçage de version via <code>resolutionStrategy.eachDependency</code> comme seul moyen de contourner le BOM implicite de Spring Boot.</p> </div> <div class="paragraph"> <p>Le build script Gradle à la racine du projet est maintenant propre. <code>./gradlew build</code> passe sur Java 21, Gradle 9.4.1, Spring Boot 3.4.5 et Docker Engine 29.4.1.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html Fri, 24 Apr 2026 00:00:00 +0000 blog/2026/0108_gouvernance_agent_opencode_eager_lazy_post.html <div class="sect1"> <h2 id="_résumé">Résumé</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand on travaille avec un agent IA comme Opencode sur des projets complexes sur plusieurs sessions, on fait face à un problème fondamental : <strong>la fuite de contexte</strong>. L’agent ne se souvient pas de la session précédente. Tout ce qu’on lui a expliqué — l’architecture, les conventions, l’état du backlog — est perdu. Reconstruire ce contexte à chaque session est coûteux, lent et source d’erreur.</p> </div> <div class="paragraph"> <p>Cet article expose la stratégie artisanale que j’ai construite pour résoudre ce problème : un système de gouvernance persistant basé sur des fichiers AsciiDoc, avec une dichotomie <strong>Eager/Lazy</strong> pour optimiser la consommation du token de contexte, et une <strong>procédure de fin de session incontournable</strong> pour assurer la continuité.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_scène_lundi_21_avril_9h00">La Scène : Lundi 21 Avril, 9h00</h2> <div class="sectionbody"> <div class="paragraph"> <p>Je rouvre Opencode pour reprendre mon plugin Gradle <code>plantuml-plugin</code>. Hier soir, j’ai passé trois heures à discuter avec l’agent de l’architecture du pool de clés API — rotation round-robin, gestion des quotas, fallback automatique. Ce matin, l’agent me regarde avec des yeux de poisson rouge.</p> </div> <div class="paragraph"> <p><em><em>_ — Bonjour, je suis votre assistant Opencode. Comment puis-je vous aider aujourd’hui ? </em>_</em></p> </div> <div class="paragraph"> <p>Pas de — Ah oui, le pool de clés API, on en était à la structure YAML. Pas de — Attention, <code>PlantumlManager</code> est un objet Kotlin singleton, pas une classe. Pas de — Non, on a décidé hier que <code>SyntaxValidationResult</code> restait une sealed class nested dans <code>PlantumlService</code>.</p> </div> <div class="paragraph"> <p>Tout est à refaire. Ou plutôt : tout est à réexpliquer. Je vais passer les vingt premières minutes de ma session à reconstituer un contexte que l’agent a déjà eu entre les mains hier. Vingt minutes de tokens brûlés. Vingt minutes où je pourrais coder, mais où je fais du pédagogique obligatoire.</p> </div> <div class="paragraph"> <p>Ce n’est pas un bug d’Opencode. C’est la nature même des LLM conversationnels : entre deux sessions, la mémoire de travail est <strong>entièrement effacée</strong>. L’agent ne se souvient pas de la mission précédente, des décisions prises, des pièges identifiés, du code qu’on a écrit ensemble.</p> </div> <div class="paragraph"> <p>J’ai vécu ça des dizaines de fois. Sur quatre projets simultanés. Avec des sessions qui s’enchaînent sur des semaines. J’ai calculé : en moyenne, <strong>30 à 40 % du temps de session</strong> était consacré à recontextualiser l’agent. À la session 87 du projet <code>plantuml-plugin</code>, j’ai craqué. Je ne pouvais plus me permettre de réexpliquer pour la dixième fois que <code>AttemptEntry</code> est une data class top-level dans <code>DiagramProcessor.kt</code>.</p> </div> <div class="paragraph"> <p>Il me fallait un système. Pas un hack. Une vraie gouvernance.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_genèse_du_chaos_à_la_méthode">La Genèse : Du Chaos à la Méthode</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_les_premières_sessions_lâge_des_ténèbres">Les Premières Sessions : L’Âge des Ténèbres</h3> <div class="paragraph"> <p>Mon premier projet avec Opencode, <code>plantuml-plugin</code>, a démarré sans aucune gouvernance. Je pose une question, l’agent répond, on itère, la session se termine, et le lendemain on repart de zéro. C’était la session 1, puis la 2, puis la 3…​ jusqu’à la session 62 où je réalise que j’ai perdu des heures cumulées à réexpliquer la même architecture.</p> </div> <div class="paragraph"> <p>À la session 62, les chiffres sont là : <strong>198 tests unitaires passent</strong>, <strong>42 tests fonctionnels validés</strong>, le plugin fonctionne. Mais le coût cognitif est insupportable. Chaque nouvelle session commence par un monologue de vingt minutes sur la structure du projet.</p> </div> </div> <div class="sect2"> <h3 id="_lépisode_du_site_yml_détruit_session_2_bakery_plugin">L’Épisode du site.yml Détruit (Session 2, bakery-plugin)</h3> <div class="paragraph"> <p>La méthode naît aussi d’une catastrophe. Sur le projet <code>bakery-gradle</code>, à la session 2, je demande à l’agent de modifier le fichier <code>site.yml</code>. L’agent, sans vérifier si le fichier est versionné, fait un <code>Write</code> complet qui écrase le contenu. Résultat : les tokens réels (clés API Firebase, secrets de déploiement) sont remplacés par des placeholders factices. Le fichier n’était pas dans git — il était dans <code>.gitignore</code> pour protéger les secrets.</p> </div> <div class="paragraph"> <p>Sans sauvegarde. Sans <code>git restore</code> possible. Je suis bloqué. Il me faut reconstruire manuellement le fichier de configuration, retrouver les tokens dans mes gestionnaires de mots de passe, tout recoller.</p> </div> <div class="paragraph"> <p>C’est de cette frustration que naît la <strong>Règle Absolue 1b</strong> :</p> </div> <div class="paragraph"> <p><em><em>_ <strong>NE JAMAIS écraser</strong> un fichier config avec un <code>Write</code> complet quand un <code>Edit</code> partiel suffit. <strong>NE JAMAIS remplacer</strong> des valeurs sensibles par des valeurs factices. <strong>Vérifier <code>git check-ignore</code> et <code>git ls-files</code></strong> avant toute modification. </em>_</em></p> </div> <div class="paragraph"> <p>Cette règle, aujourd’hui gravée dans le marbre de tous mes fichiers <code>AGENT.adoc</code> et <code>INDEX.adoc</code> sur quatre projets, est née d’une erreur réelle qui m’a coûté une heure de travail manuel.</p> </div> </div> <div class="sect2"> <h3 id="_la_migration_markdown_asciidoc_session_1_cheroliv_com">La Migration Markdown → AsciiDoc (Session 1, cheroliv.com)</h3> <div class="paragraph"> <p>Le 25 avril 2026, sur <code>cheroliv.com</code>, je prends une décision radicale : convertir l’intégralité de la gouvernance de Markdown vers AsciiDoc. Ce n’est pas esthétique. C’est fonctionnel. AsciiDoc offre une structure sémantique que les LLM lisent mieux : sections hiérarchiques, tableaux typés, admonitions (<code>NOTE</code>, <code>WARNING</code>, <code>CAUTION</code>), attributs de document lisibles par la machine.</p> </div> <div class="paragraph"> <p>La session 1 de <code>cheroliv.com</code> formalise la structure :</p> </div> <div class="ulist"> <ul> <li> <p>Conversion de <code>AGENTS.md</code> en <code>AGENT.adoc</code></p> </li> <li> <p>Création des agents spécialisés : <code>CODER.adoc</code>, <code>SCRUM_MASTER.adoc</code>, <code>PLANTUML_DESIGNER.adoc</code></p> </li> <li> <p>Création de la structure Eager/Lazy : <code>INDEX.adoc</code>, <code>SESSIONS_HISTORY.adoc</code>, <code>AGENT_SESSION_MANAGER.adoc</code>, <code>SESSION_CHECKLIST.adoc</code>, <code>PROCEDURES.adoc</code></p> </li> </ul> </div> <div class="paragraph"> <p>Un seul commit : <code>90975e9 refactor: migrate agent governance from Markdown to AsciiDoc</code>. Et le site continue de fonctionner.</p> </div> <div id="diag-timeline" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-1ffbad829836ed4bec6c66e6b3038145.svg" alt="Timeline de croissance des sessions sur les 4 projets" width="2373" height="290"> </div> </div> <div class="paragraph"> <p>La timeline ci-dessus illustre la progression réelle. Le point de bascule est la session 87 : c’est là que la frustration du recontextualisation répétée dépasse le seuil de tolérance, et que la méthode Eager/Lazy cesse d’être une idée pour devenir une obligation.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_stratégie_eagerlazy_en_profondeur">La Stratégie : Eager/Lazy en Profondeur</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_philosophie_cache_informatique_appliqué_à_la_cognition">Philosophie : Cache Informatique Appliqué à la Cognition</h3> <div class="paragraph"> <p>Mon approche s’inspire directement de la gestion de cache informatique. Tout ce qui est <strong>critique et fréquemment utilisé</strong> doit être immédiatement accessible (<strong>Eager</strong>). Tout ce qui est <strong>contextuel ou volumineux</strong> doit être chargé sur demande (<strong>Lazy</strong>).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6666%;"> <col style="width: 6.6676%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Eager (Tableau de Bord)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lazy (Manuel du Propriétaire)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Taille</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">< 100 lignes, < 10k tokens</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Illimité, détaillé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Chargement</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Auto, en début de session</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sur demande de l’agent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Contenu</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Règles absolues, mission courante, état critique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Archives de sessions, historique complet, procédures détaillées, références techniques</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Rôle</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Orienter immédiatement l’agent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Répondre aux questions de contexte profond</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_les_fichiers_eager_le_tableau_de_bord">Les Fichiers Eager : Le Tableau de Bord</h3> <div class="paragraph"> <p>Ces fichiers vivent à la racine de chaque projet et sont chargés automatiquement par l’agent au début de chaque session. Ils forment le <strong>tableau de bord</strong> — information critique, immédiatement accessible.</p> </div> <div id="diag-eager-lazy" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-05c08d0c2b5bf285c4c1fee60314a0e7.svg" alt="Architecture Eager/Lazy des fichiers de gouvernance" width="1759" height="5760"> </div> </div> <div class="paragraph"> <p><strong><code>AGENT.adoc</code></strong> — Le fichier maître. Sur <code>cheroliv.com</code>, il fait 200 lignes et contient :</p> </div> <div class="ulist"> <ul> <li> <p>Les règles absolues du projet (pas de commit sans permission, pas de <code>rm</code> sans confirmation)</p> </li> <li> <p>La structure du projet et les conventions de code</p> </li> <li> <p>Les commandes essentielles (<code>./gradlew serve</code>, <code>./gradlew test</code>)</p> </li> <li> <p>Les épopées et le backlog produit (user stories priorisées)</p> </li> <li> <p>Les critères de qualité transverses (accessibilité, responsive, compatibilité)</p> </li> </ul> </div> <div class="paragraph"> <p>Sur <code>bakery-plugin</code>, la Règle 0 est différente : <strong><code>./gradlew -q publishToMavenLocal</code> obligatoire après chaque modification du code source</strong>. Parce que tester le plugin sans republier le JAR local m’a fait perdre une heure à débugger un code qui n’était pas encore empaqueté.</p> </div> <div class="paragraph"> <p><strong><code>PROMPT_REPRISE.adoc</code></strong> — La mission de la session en cours. Mis à jour à chaque fin de session, il contient :</p> </div> <div class="ulist"> <ul> <li> <p>Le numéro de session et la mission prioritaire</p> </li> <li> <p>Le résumé de la session précédente (ce qui a été fait, ce qui reste à faire)</p> </li> <li> <p>Les critères d’acceptation de la session courante</p> </li> <li> <p>Les rappels techniques spécifiques</p> </li> </ul> </div> <div class="paragraph"> <p><strong><code>.agents/INDEX.adoc</code></strong> — Le point d’entrée. Il résume les règles absolues, les sessions récentes, et surtout le <strong>portefeuille de projets</strong> gérés avec la même méthodologie. À ce jour, cinq projets y figurent :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- | magic-stick | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 | | bakery-gradle | Session 11 | TEST_COVERAGE_ANALYSIS | 2026-04-27 | | cheroliv.com | Session 9 | TEST_COVERAGE_ANALYSIS | 2026-04-27 | | plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS | 2026-04-23 | | jhipster-gradle-plugins | Session 1 | TEST_COVERAGE_ANALYSIS | 2026-04-28 | ---- **`*_ESSENTIALS.adoc`** -- Un ajout récent (Session 109, plantuml-plugin) pour optimiser encore le contexte Eager. Au lieu de charger 200 lignes de contexte métier sur le pool de clés API, je charge 50 lignes de l'essentiel, et les 150 autres lignes restent en LAZY dans `*_REFERENCE.adoc`. Résultat mesuré : passage de **~25k tokens EAGER à ~10k tokens** (gain de 60%). L'agent n'a plus besoin de rappels énergivores. ==== Le Chaînon Manquant : `opencode.json` Je dois vous avouer une chose que j'ai failli oublier de documenter. Au-dessus de tous ces fichiers .adoc, il y a un minuscule fichier JSON sans lequel rien ne fonctionne. Il s'appelle `opencode.json` et il fait six lignes. Littéralement six lignes. [source,json] ---- { "$schema": "https://opencode.ai/config.json", "instructions": [ "AGENT.adoc" ] } ---- C'est ce fichier qui dit à Opencode : « Au démarrage, charge `AGENT.adoc` automatiquement. » Sans lui, l'agent est une page blanche exactement comme je le décrivais au début de l'article. Avec lui, l'agent a déjà entre les mains les règles absolues, l'architecture du projet, et les commandes essentielles — avant même que je dise bonjour. J'ai découvert l'importance de ce fichier par hasard. Sur `bakery-plugin`, il n'existait pas. Je me demandais pourquoi l'agent était systématiquement plus « perdu » sur ce projet que sur les autres. Les règles absolues étaient bien dans `AGENT.adoc` — mais `AGENT.adoc` n'était jamais chargé. L'agent ne lisait que ce que je lui disais de lire, manuellement, à chaque session. C'était la session 11 de `bakery-plugin` quand j'ai réalisé l'absence du `opencode.json`. Je l'ai créé — et la session 12 a démarré comme les autres. Ce fichier est tellement évident pour moi maintenant que je ne pensais même plus à lui. Une erreur classique du développeur qui connaît trop son outil. Aujourd'hui, je le crée systématiquement *avant* `AGENT.adoc`. C'est la première pierre. ==== La Dualité de `INDEX.adoc` Une autre subtilité qui mérite d'être explicitée : `INDEX.adoc` vit dans `.agents/` — un dossier que j'ai présenté comme LAZY. Pourtant, je le liste comme EAGER dans tous mes tableaux. Il y a une tension apparente ici. La réalité terrain : les fichiers `.agents/INDEX.adoc` sont bien chargés automatiquement en début de session, au même titre que `AGENT.adoc` et `PROMPT_REPRISE.adoc`. Ils sont dans `.agents/` pour des raisons d'organisation — ne pas envahir la racine — mais leur comportement est EAGER. Sur `plantuml-plugin`, `INDEX.adoc` fait 200 lignes et contient les règles absolues *complètes* avec leur historique (les leçons des sessions passées), les EPICs avec scores, et le portefeuille de projets. C'est le document que l'agent consulte pour savoir « où on en est ». Sur `bakery-plugin`, il fait 150 lignes avec la roadmap et les sessions récentes. La redondance volontaire entre `AGENT.adoc` et `INDEX.adoc` peut surprendre. Les règles absolues sont présentes dans les deux. Pourquoi ? Parce qu'elles remplissent deux rôles différents : dans `AGENT.adoc`, elles sont *explicatives* (le storytelling de la règle, la leçon apprise) ; dans `INDEX.adoc`, elles sont *exécutives* (la règle nue, sans justification, pour une consultation rapide). L'agent lit `AGENT.adoc` une fois pour *comprendre* ; il relit `INDEX.adoc` à chaque session pour *appliquer*. Deux usages, deux formats. [plantuml, format=svg, id=diag-dualite-agent-index, alt="Comparaison entre AGENT.adoc (narratif) et INDEX.adoc (exécutif)"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center title Dualité AGENT.adoc ←→ INDEX.adoc left to right direction rectangle "AGENT.adoc\n(Racine — EAGER)" as AGENT #E3F2FD { rectangle "📖 **Format Narratif**\nLe storytelling de la règle\nla leçon apprise, le contexte" as NARR rectangle "🏗️ **Architecture Complète**\nStructure projet, composants\nBacklog détaillé US" as ARCHI rectangle "📋 **Règles Explicatives**\nPourquoi la règle existe\nHistorique de l'incident" as EXPL } rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 { rectangle "⚡ **Format Exécutif**\nLa règle nue, sans justification\nConsultation rapide" as EXEC rectangle "📊 **Roadmap & EPICs**\nTableau récapitulatif\nProgression, Score, Priorité" as ROAD rectangle "🌐 **Portefeuille Projets**\nVue transverse\n5 projets synchronisés" as PORT } AGENT --> INDEX : "Agent lit AGENT.adoc\n1 fois pour **comprendre**" INDEX --> AGENT : "Agent relit INDEX.adoc\nchaque session pour **appliquer**" note bottom of AGENT Taille max : 200 lignes end note note bottom of INDEX Taille max : 200 lignes Source de vérité en cas de divergence end note @enduml ---- Cette redondance assumée est un choix de conception. Elle consomme ~50 lignes supplémentaires de tokens EAGER — mais elle garantit que l'agent a toujours les règles sous les yeux, y compris dans le format concis qui facilite l'obéissance immédiate. === Les Fichiers LAZY : Le Manuel du Propriétaire Ces fichiers vivent dans `.agents/` et ne sont lus que quand l'agent en a besoin. Ils constituent la véritable richesse de la méthode, car ils accumulent la connaissance du projet sans polluer le contexte courant. [plantuml, format=svg, id=diag-agents-tree, alt="Arborescence complète du dossier .agents/"] ---- @startuml skinparam folderBackgroundColor #E3F2FD skinparam folderBorderColor #1565C0 skinparam fileBackgroundColor #FFF3E0 skinparam fileBorderColor #EF6C00 folder ".agents/" as ROOT { file "INDEX.adoc\n(EAGER -- 200 lignes)" as IDX #E8F5E9 file "AGENT_SESSION_MANAGER.adoc\n(Template session)" as ASM file "SESSION_CHECKLIST.adoc\n(Quand changer)" as CHK file "PROCEDURES.adoc\n(6 étapes + LAZY/EAGER)" as PRO file "SESSIONS_HISTORY.adoc\n(Toutes sessions)" as HIS folder "sessions/" as SESS { file "1-chore-migration.adoc" as S1 file "109-formalisation-lazy.adoc" as S109 #FFECB3 file "133-epic11-article.adoc" as S133 file "... +130 autres" as SMORE } folder "archives/" as ARCH { file "COMPLETED_TASKS_2026-04.adoc" as CTA file "SESSIONS_HISTORY_83-95.adoc" as SHIST folder "sessions_summaries/" as SUM { file "SESSION_64_SUMMARY.adoc" as SU64 file "SESSION_73_SUMMARY.adoc" as SU73 file "..." as SUMORE } folder "prompts_archive/" as PARCH { file "PROMPT_REPRISE_S65.adoc" as PR65 file "PROMPT_REPRISE_S75.adoc" as PR75 file "..." as PMORE } } } IDX --> SESS : "Indexe" IDX --> HIS : "Indexe" IDX --> ARCH : "Référence" note right of S109 Session 109 = Formalisation stratégie LAZY/EAGER Token : ~25k → ~10k end note @enduml ---- L'arborescence ci-dessus montre la structure réelle du dossier `.agents/` sur `plantuml-plugin`, le projet le plus mature. Notez la profondeur en trois couches : fichiers racine (métadonnées), dossier `sessions/` (archives chronologiques), et dossier `archives/` (agrégations et résumés). C'est cette profondeur qui transforme la gouvernance d'un simple fichier TODO en une **mémoire organisationnelle complète**. **`.agents/sessions/{N}-{titre}.adoc`** -- Les archives détaillées de chaque session. Actuellement : * `plantuml-plugin` : **133 sessions archivées** (de la session 1 à 133) * `bakery-plugin` : **11 sessions** * `magic-stick` : **23 sessions** * `cheroliv.com` : **9 sessions formelles** + 7 sessions pré-système reconstituées rétroactivement Chaque archive contient le contexte complet de la session, les décisions prises, les problèmes rencontrés et leur résolution, les commandes exécutées et leur output. **`.agents/SESSIONS_HISTORY.adoc`** -- Un tableau récapitulatif de toutes les sessions avec un score. Exemple sur `cheroliv.com` :</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>| -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10 | 1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10 | 7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10 | 8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10</pre> </div> </div> <div class="paragraph"> <p><strong><code>.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc</code></strong> — Les tâches terminées archivées par mois, pour ne pas surcharger le backlog actif. Quand une user story est terminée, elle migre ici. Le backlog reste lisible : maximum 10 items actifs.</p> </div> <div class="paragraph"> <p><strong><code>.agents/PROCEDURES.adoc</code></strong> — Templates détaillés de la procédure de fin de session. Long, mais lu une seule fois par l’agent quand il apprend la méthode. Ensuite, la procédure devient mécanique.</p> </div> <div class="paragraph"> <p><strong><code>.agents/AGENT_MODUS_OPERANDI.adoc</code></strong> — La documentation stratégique complète. Sur <code>plantuml-plugin</code>, ce fichier fait <strong>900+ lignes</strong> et se nomme en réalité <code>AGENT_METHODOLOGIES.adoc</code> — j’ai changé le nom entre l’écriture de cet article et la mise en place effective. Ce genre de divergence de naming est inévitable dans un système artisanal qui évolue. L’important est la convention de nommage : si le fichier documente la <strong>méthode</strong>, il commence par <code>AGENT_</code> ou un préfixe explicite. Il documente la méthodologie Eager/Lazy, les patterns à suivre, les anti-patterns à éviter. Il est LAZY parce qu’un agent n’a pas besoin de relire toute la stratégie à chaque session, seulement quand il y a ambiguïté.</p> </div> <div class="paragraph"> <p><strong><code>*_REFERENCE.adoc</code></strong> — Les références techniques spécifiques au projet. Sur <code>magic-stick</code>, deux fichiers LAZY denses :</p> </div> <div class="ulist"> <ul> <li> <p><code>AB_PARTITION_REFERENCE.adoc</code> (147 lignes) — Architecture partition A/B GPT, scripts <code>update-system.sh</code>, tailles estimées, mécanisme de rollback</p> </li> <li> <p><code>BOOT_TEST_REFERENCE.adoc</code> (144 lignes) — Procédure QEMU + VNC pour tester le boot de l’ISO sans matériel physique, checklist BIOS/UEFI, limitations CI/CD</p> </li> </ul> </div> <div class="paragraph"> <p>Sur <code>plantuml-plugin</code> :</p> </div> <div class="ulist"> <ul> <li> <p><code>ARCHITECTURE.adoc</code> (134 lignes) — Structure des 11 data classes, points d’attention (pièges à éviter), commandes de test optimisées</p> </li> <li> <p><code>API_KEY_POOL_REFERENCE.adoc</code> — Détails complets du pool de clés (LAZY pendant que <code>ESSENTIALS</code> est EAGER)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_les_agents_spécialisés_une_équipe_virtuelle">Les Agents Spécialisés : Une Équipe Virtuelle</h2> <div class="sectionbody"> <div class="paragraph"> <p>La gouvernance ne se limite pas à des fichiers passifs. J’ai formalisé des <strong>rôles d’agents spécialisés</strong> dans des fichiers LAZY dédiés, qui définissent le workflow attendu selon le type de tâche.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> <col style="width: 6.25%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Agent</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fichier</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rôle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Projet</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>CODER</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>CODER.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Implémentation FTL/CSS/JS, balises sémantiques, critères d’accessibilité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>SCRUM Master</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SCRUM_MASTER.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Planification US, découpage en sous-tâches, détection des dépendances</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>PlantUML Designer</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PLANTUML_DESIGNER.adoc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Création de diagrammes, syntaxe PUML, intégration JBake</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">cheroliv.com</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le fichier <code>CODER.adoc</code> sur <code>cheroliv.com</code> contient des règles concrètes : <em>Un seul <code><h1></code> par page</em>, <em>Préfixer les chemins avec `${content.rootpath}`</em>, <em>Déclarer la langue `<html lang="${content.lang!"fr"}">`</em>. Ces conventions, écrites une fois, sont respectées automatiquement par l’agent depuis la session 1.</p> </div> <div class="paragraph"> <p>Le fichier <code>SCRUM_MASTER.adoc</code> impose une structure de livrable : <strong>Objectif</strong>, <strong>Tâches</strong> (ordonnées avec assignation), <strong>Critères d’acceptation</strong>, <strong>Risques</strong>. Quand je demande un plan d’action, l’agent produit cette structure sans que je l’aie demandée. La gouvernance <strong>programme</strong> l’agent.</p> </div> <div class="sect3"> <h4 id="_quand_les_agents_spécialisés_deviennent_indispensables">Quand les Agents Spécialisés Deviennent Indispensables</h4> <div class="paragraph"> <p>La création des agents spécialisés suit une courbe naturelle. Au début d’un projet, vous n’en avez pas besoin — <code>AGENT.adoc</code> suffit largement. Mais quand le projet grandit (disons, au-delà de 20 sessions), deux signaux doivent vous alerter :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>L’agent mélange les conventions de deux domaines distincts (ex: syntaxe PlantUML et règles CSS)</p> </li> <li> <p>Vous passez plus de temps à corriger l’agent sur des conventions que vous lui avez déjà expliquées 5 fois</p> </li> </ol> </div> <div class="paragraph"> <p>Sur <code>cheroliv.com</code>, c’est arrivé à la session…​ 1. Oui, dès le départ. Parce que ce projet est un site web avec trois langages (FTL, CSS, JS), du contenu AsciiDoc, et des diagrammes PlantUML — trois domaines qui n’ont rien à voir. L’agent CODER a besoin de connaître les tailles de police et les media queries ; l’agent PLANTUML_DESIGNER a besoin de connaître la syntaxe <code>@startuml</code>. Sans séparation, l’agent CODER me proposait des diagrammes, et vice versa. Le chaos.</p> </div> <div class="paragraph"> <p>Sur <code>jhipster-gradle-plugins</code>, j’ai créé deux agents spécialisés adaptés au développement de plugins Gradle : <code>PLUGIN_DEVELOPER.adoc</code> et <code>BACKLOG_MANAGER.adoc</code>. Le premier encode toutes les conventions Kotlin/Gradle (pas de <code>!!</code>, data classes pour les modèles, <code>@TaskAction</code> pour les tâches). Le second sait que <code>persistence</code> doit être stable avant que <code>assistant</code> ne démarre son développement — une dépendance critique dans un mono-repo.</p> </div> <div class="paragraph"> <p>L’erreur à ne pas commettre : créer trop d’agents trop tôt. <code>plantuml-plugin</code> a attendu la session 108 avant de formaliser un agent spécialisé pour le pool de clés API. Avant ça, le contexte métier tenait dans <code>AGENT.adoc</code>. La règle empirique : un agent spécialisé se justifie quand son domaine métier dépasse 100 lignes de documentation.</p> </div> </div> <div class="sect3"> <h4 id="_la_convention_de_nommage_des_sessions">La Convention de Nommage des Sessions</h4> <div class="paragraph"> <p>Un détail qui paraît futile mais qui devient critique quand on atteint 100 sessions. Comment nommer les fichiers d’archive ?</p> </div> <div class="paragraph"> <p>J’ai appris à mes dépens qu’une convention est nécessaire — quatre projets, quatre formats différents au début, et je ne m’y retrouvais plus. Aujourd’hui, la convention que j’ai stabilisée est :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- {N}-{type}-{sujet-kebab-case}.adoc ---- Exemples concrets : * `1-chore-migration-gouvernance-agent.adoc` — session 1, type chore * `10-solidification-tests.adoc` — session 10, sans type explicite (le sujet suffit) * `036-debug-graphify-symlink-epic9.adoc` — session 36 avec numéro sur 3 chiffres pour le tri Le numéro de session est le critère de tri principal. Les projets utilisant des numéros sur 3 chiffres (001, 036, 133) évitent les problèmes de tri lexicographique quand on dépasse 99. C'est ce que j'utilise désormais sur `magic-stick` : `001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`. Le type est facultatif et dérivé des mots-clés de la session (debug, feature, refactor, docs, chore, test). Le sujet en kebab-case est la partie la plus importante : il doit permettre de retrouver une session sans ouvrir le fichier. Si vous vous demandez « c'était quelle session où on a corrigé le timeout des tests d'intégration ? », la réponse est `124-fix-timeout-integration-test.adoc`. Pour les sessions historiques reconstituées (projets nés avant la gouvernance), j'utilise des numéros négatifs. Sur `cheroliv.com`, les sessions -6 à 0 couvrent toute l'histoire pré-gouvernance du projet. Et pour les sessions « non documentées » ou perdues, je crée une entrée dans `SESSIONS_HISTORY.adoc` sans archive correspondante, avec un score `?`. C'est plus honnête que faire semblant. [plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"] ---- @startuml skinparam backgroundColor #FEFEFE skinparam defaultTextAlignment center skinparam wrapWidth 200 title Convention de Nommage des Sessions start :Une session se termine; note right: Trigger "fin de session" if (Session antérieure\nà la gouvernance ?) then (oui) :Numéro **NÉGATIF**\n-6, -5 ... 0; note right: Historique\nreconstitué :Suffixe : reconstitution; else (non) :Numéro **POSITIF**\nsur 3 chiffres si > 99; note right: 001, 036, 133\npour le tri lexicographique :Détecter le **TYPE**; if (Mots-clés trouvés ?) then (oui) :debug / feature / refactor\ndocs / chore / test; else (non) :Omettre le type\n(le sujet suffit); endif :Formuler le **SUJET** en kebab-case; note right Ex: fix-timeout-integration-test Doit permettre de retrouver sans ouvrir le fichier end note endif :Nom final : {N}-{type}-{sujet}.adoc; note right • 1-chore-migration-gouvernance.adoc • 036-debug-graphify-symlink.adoc • 124-fix-timeout-integration-test.adoc • 133-epic11-article-blog-kg.adoc end note if (Session documentée ?) then (oui) :Créer archive dans sessions/; :Ajouter ligne SESSIONS_HISTORY\navec score X/10; else (non) :Ajouter ligne SESSIONS_HISTORY\navec score **?**\n**sans archive**; note right: L'honnêteté\nplutôt que le vide endif stop @enduml ---- ==== `TEST_COVERAGE_ANALYSIS.adoc` — L'Étape 5 Décortiquée L'étape 5 de la procédure de fin de session est la plus mystérieuse. Elle dit « Mettre à jour `TEST_COVERAGE_ANALYSIS.adoc` si des tests ont été ajoutés ou modifiés. » Mais à quoi ressemble ce fichier ? Sur `plantuml-plugin`, il a évolué de quelques lignes à une structure complète. Voici sa forme stabilisée : [source] ---- = Analyse de Couverture de Tests == Suivi des Tests |=== | Classe de test | Type | Tests | Statut | Dernière MAJ | PlantumlServiceTest | unit | 45/45 | ✅ PASS | 2026-04-23 | ApiKeyPoolTest | integration | 15/15 | ✅ PASS | 2026-04-20 |=== == Historique par Session | Session | Tests ajoutés | Tests modifiés | Couverture | 133 | 0 | 2 | 100% | 132 | 5 | 0 | 100% |=== ---- L'intérêt n'est pas le fichier lui-même — c'est l'obligation de *noter* ce qui a changé. Sans cette étape, après 50 sessions, vous ne savez plus quels tests couvrent quoi. L'agent non plus. Le fichier devient le référentiel unique de vérité sur la couverture de tests du projet. Pour les projets sans tests traditionnels (comme `magic-stick` qui teste des scripts bash), l'étape 5 est remplacée par `SCRIPT_VERIFICATION.adoc`. Le mécanisme est le même : un fichier qui suit l'état de validation des scripts. Adaptez l'étape 5 à votre projet, mais ne la sautez jamais. Elle est le filet de sécurité qui empêche la régression silencieuse. Si votre projet n'a *aucun* test — ni unitaire, ni fonctionnel, ni script — créez quand même le fichier vide avec une section « À faire : définir une stratégie de test. » C'est un marque-page qui rappellera à votre futur vous que ce sujet n'est pas traité. [plantuml, format=svg, id=diag-session-flow, alt="Flux d'une session type avec Eager/Lazy et agents"] ---- @startuml skinparam backgroundColor #FEFEFE start :Début session; note right: L'agent est une page blanche :Chargement EAGER auto; note right * AGENT.adoc (règles absolues) * PROMPT_REPRISE.adoc (mission N) * INDEX.adoc (état projet) end note if (Mission claire ?) then (oui) :Exécution directe; else (non) :Charge LAZY sur demande; note right * SESSIONS_HISTORY.adoc (contexte passé) * sessions/{N-1}-*.adoc (décisions) * *_REFERENCE.adoc (architechture) end note endif :Délégation agent spécialisé ?; if (CODER ?) then (oui) :Lit CODER.adoc; :Suit conventions FTL/CSS; elseif (SCRUM Master ?) then (oui) :Lit SCRUM_MASTER.adoc; :Structure livrable imposée; elseif (PlantUML ?) then (oui) :Lit PLANTUML_DESIGNER.adoc; :Syntaxe PUML + intégration; else (non) endif :Travail de la session; :Fin de session (trigger utilisateur); :Procédure 6 étapes; note right 1. Archive sessions/N-*.adoc 2. Maj PROMPT_REPRISE.adoc (N+1) 3. Maj SESSIONS_HISTORY.adoc 4. Maj INDEX.adoc 5. Maj TEST_COVERAGE (si applicable) 6. Maj COMPLETED_TASKS_ARCHIVE.adoc end note :Checklist [✅] x 6; stop @enduml ---- Le diagramme ci-dessus montre le cycle de vie complet d'une session. Le point clé est la bifurcation après le chargement EAGER : soit la mission est assez claire pour exécuter directement (80% des cas), soit l'agent charge du LAZY pour résoudre une ambiguïté (20% des cas). C'est cette discrimination qui économise les tokens. == La Procédure de Fin de Session : La Règle d'Or === Pourquoi elle est Incontournable Sans cette procédure, la stratégie Eager/Lazy ne sert à rien. C'est elle qui transforme le travail de la session en information persistante. Elle s'exécute **à la demande explicite de l'utilisateur** (mots-clés : "fin de session", "je quitte", etc.), et elle est **obligatoire** -- aucune exception, aucune omission. Le fichier `SESSION_CHECKLIST.adoc` définit des métriques de session idéale : * Durée : 15-30 minutes * Fichiers modifiés : 1-3 maximum * Échanges LLM : 5-10 messages * Contexte tokens : < 50k Et des signes qu'il faut changer de session : _Le LLM répète des erreurs déjà corrigées_, _Plus de 3 fichiers modifiés en parallèle_, _Conversation > 50 messages_. La règle d'or : **Mieux vaut 5 sessions de 20 minutes qu'une session de 2 heures avec debugging chaos.** === Le Flux des 6 Étapes (Silencieusement) [plantuml, format=svg, id=diag-end-session-flow, alt="Flux de la procédure de fin de session"] ---- @startuml skinparam defaultTextAlignment center skinparam wrapWidth 200 skinparam activityBackgroundColor #E3F2FD start :L'utilisateur dit "fin de session"; note right: Mots-clés déclencheurs :Agent détecte le trigger; :Étape 1\nCréer archive\n`.agents/sessions/N-*.adoc`; note right: Tout le contexte de la session :Étape 2\nMettre à jour\n`PROMPT_REPRISE.adoc`; note right: Mission N + critères d'acceptation N+1 :Étape 3\nMettre à jour\n`SESSIONS_HISTORY.adoc`; note right: Ligne récap : # / Date / Type / Sujet / Score :Étape 4\nMettre à jour\n`INDEX.adoc`; note right: État courant, roadmap, fichiers modifiés :Étape 5\nMettre à jour\n`TEST_COVERAGE_ANALYSIS.adoc`; note right: Si tests ajoutés ou modifiés :Étape 6\nMettre à jour\n`COMPLETED_TASKS_ARCHIVE.adoc`; note right: Archiver tâches terminées :Afficher la checklist de confirmation; note right: Vérifier que chaque [✅] est mérité stop @enduml ---- === Les Résultats de 150+ Sessions Voici ce que donne cette procédure appliquée systématiquement sur mes quatre projets : **plantuml-plugin** : * **133 sessions** depuis le début du projet * **240/240 tests PASS** (100% couverture) -- EPICs 1-7 terminées * **57 scénarios Cucumber BDD** validés * Règle de sûreté sur les fichiers de config née d'une erreur réelle (Session 2 bakery-plugin) **bakery-plugin** : * **11 sessions** en deux semaines * Migration Supabase → Firebase terminée (9 tests corrigés) * EPIC 6 (publishProfile) fonctionnel en production * Règle 0 créée : `publishToMavenLocal` obligatoire après chaque modif **magic-stick** : * **23 sessions** pour construire un système live Xubuntu avec partition A/B * Première ISO générée à la session 10 * Tests de boot QEMU + VNC formalisés (documentation LAZY de 144 lignes) * CI/CD SourceForge fonctionnel **cheroliv.com** : * **9 sessions formelles** + reconstitution de 7 sessions pré-système * Article 0101 (OpenCode PATH) publié * Article 0108 (celui-ci) réécrit après analyse de ses lacunes * Gouvernance complète migrée de Markdown vers AsciiDoc === La Checklist Finale Après exécution silencieuse des 6 étapes, l'agent doit afficher une checklist de confirmation :</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre>✅ Procédure de fin de session exécutée 📋 Checklist : [✅] 1. Archive session N créée [✅] 2. PROMPT_REPRISE.adoc mis à jour pour session N+1 [✅] 3. SESSIONS_HISTORY.adoc mis à jour [✅] 4. INDEX.adoc mis à jour [✅] 5. TEST_COVERAGE_ANALYSIS.adoc mis à jour (si applicable) [✅] 6. COMPLETED_TASKS_ARCHIVE.adoc mis à jour</pre> </div> </div> <div class="paragraph"> <p><strong>Règle absolue</strong> : aucune étape ne peut être marquée <code>[✅]</code> si le fichier n’a pas été effectivement modifié et vérifié.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_guide_de_bootstrap_jour_1_session_0">Le Guide de Bootstrap : Jour 1, Session 0</h2> <div class="sectionbody"> <div class="paragraph"> <p>Vous êtes convaincu par la méthode. Vous voulez l’appliquer à un nouveau projet. Par où commencer ?</p> </div> <div class="paragraph"> <p>J’ai vécu ce moment le 28 avril 2026. J’ouvre Opencode sur <code>jhipster-gradle-plugins</code>, mon mono-repo de deux plugins Gradle JHipster. C’est un projet qui existe déjà — le code est là, les tâches Gradle fonctionnent. Mais la gouvernance agent ? Zéro. Page blanche. Comme <code>plantuml-plugin</code> à sa session 1, il y a des mois.</p> </div> <div class="paragraph"> <p>Voici la procédure exacte que j’ai suivie, et que je suivrai pour tout nouveau projet. Notez bien l’ordre — il est important.</p> </div> <div id="diag-bootstrap" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e11aa343b861c2c558099445242ab4be.svg" alt="Flux de bootstrap en 6 étapes pour initialiser la gouvernance agent sur un nouveau projet" width="1758" height="3371"> </div> </div> <div class="sect2"> <h3 id="_étape_0_créer_opencode_json">Étape 0 : Créer <code>opencode.json</code></h3> <div class="paragraph"> <p>C’est le premier fichier. Pas <code>AGENT.adoc</code>, pas <code>INDEX.adoc</code>. <code>opencode.json</code> d’abord, pour une raison simple : si vous créez <code>AGENT.adoc</code> en premier, vous allez oublier de créer le pont qui le charge automatiquement. Je l’ai fait sur <code>bakery-plugin</code>, je sais de quoi je parle.</p> </div> </div> <div class="sect2"> <h3 id="_étape_1_créer_les_dossiers">Étape 1 : Créer les Dossiers</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">mkdir -p .agents/sessions .agents/archives</code></pre> </div> </div> <div class="paragraph"> <p>Deux dossiers vides. <code>sessions/</code> recevra les archives de chaque session. <code>archives/</code> recevra les COMPLETED_TASKS_ARCHIVE mensuels. Ces dossiers doivent exister <strong>avant</strong> que l’agent n’ait besoin d’écrire dedans. Un agent qui doit créer le dossier ET le fichier en même temps, c’est un agent qui peut échouer silencieusement.</p> </div> </div> <div class="sect2"> <h3 id="_étape_2_créer_agent_adoc_le_fichier_maître">Étape 2 : Créer <code>AGENT.adoc</code> — Le Fichier Maître</h3> <div class="paragraph"> <p>Structure minimale pour la première version (elle grandira) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>= {NOM_PROJET} — Directives Agent [CAUTION]</code></pre> </div> </div> <div class="paragraph"> <p><strong>ARRÊT OBLIGATOIRE</strong> avant rm, Write, suppression :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>LIRE le fichier en entier</p> </li> <li> <p>VÉRIFIER git ls-files</p> </li> <li> <p>DEMANDER confirmation</p> </li> <li> <p>ATTENDRE "oui"</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_projet">Projet</h2> <div class="sectionbody"> <div class="paragraph"> <p><strong>Nom</strong> : …​ <strong>Stack</strong> : …​ <strong>Documentation</strong> : AsciiDoc</p> </div> </div> </div> <div class="sect1"> <h2 id="_règles_absolues">Règles Absolues</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_0_environnement_de_dev">0. ENVIRONNEMENT DE DEV</h3> <div class="paragraph"> <p>Commandes essentielles…​</p> </div> </div> <div class="sect2"> <h3 id="_1_commitsgit">1. COMMITS/GIT</h3> <div class="paragraph"> <p>Interdiction formelle…​</p> </div> </div> <div class="sect2"> <h3 id="_1b_fichiers_de_configuration_règle_absolue_de_sûreté">1b. FICHIERS DE CONFIGURATION — RÈGLE ABSOLUE DE SÛRETÉ</h3> <div class="paragraph"> <p>Ne jamais écraser…​</p> </div> </div> <div class="sect2"> <h3 id="_2_tests_en_fin_de_session">2. TESTS EN FIN DE SESSION</h3> <div class="paragraph"> <p>Interdiction formelle…​</p> </div> </div> <div class="sect2"> <h3 id="_3_procédure_de_fin_de_session">3. PROCÉDURE DE FIN DE SESSION</h3> <div class="paragraph"> <p>Les 6 étapes obligatoires…​</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_gestion_du_contexte_lazyeager">Gestion du Contexte — LAZY/EAGER</h2> <div class="sectionbody"> <div class="paragraph"> <p>Fichiers EAGER / Fichiers LAZY…​</p> </div> <div class="paragraph"> <p>Ce template minimal permet à l’agent de démarrer. La version riche — avec la structure du projet, les composants clés, les EPICs, le backlog — viendra à la session 1, quand l’agent aura déjà les règles de base en main et pourra vous aider à enrichir le document.</p> </div> <div class="sect2"> <h3 id="_étape_3_créer_prompt_reprise_adoc_la_mission_session_1">Étape 3 : Créer <code>PROMPT_REPRISE.adoc</code> — La Mission Session 1</h3> <div class="paragraph"> <p>Un fichier qui dit explicitement : « Ceci est la session 1, mission à définir. » Maximum 70 lignes, avec une section Session 0 (résumé du bootstrap) et une section Session 1 (priorités à définir avec l’utilisateur).</p> </div> </div> <div class="sect2"> <h3 id="_étape_4_créer_agentsindex_adoc_le_point_dentrée">Étape 4 : Créer <code>.agents/INDEX.adoc</code> — Le Point d’Entrée</h3> <div class="paragraph"> <p>Le fichier qui contiendra les règles absolues (version exécutive) et le tableau des sessions. Pour le bootstrap, il liste les règles 0 à 3 dans leur format concis, le portefeuille de projets (en incluant le nouveau projet avec un emoji 🆕), et la roadmap vide prête à être remplie.</p> </div> </div> <div class="sect2"> <h3 id="_étape_5_créer_les_fichiers_lazy_structurants">Étape 5 : Créer les Fichiers LAZY Structurants</h3> <div class="paragraph"> <p>Dans l’ordre :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>.agents/SESSIONS_HISTORY.adoc</code> — un tableau avec uniquement la session 0</p> </li> <li> <p><code>.agents/SESSION_CHECKLIST.adoc</code> — le template « Quand changer de session »</p> </li> <li> <p><code>.agents/PROCEDURES.adoc</code> — la procédure complète des 6 étapes + EAGER/LAZY</p> </li> <li> <p><code>.agents/AGENT_SESSION_MANAGER.adoc</code> — le template d’archive</p> </li> <li> <p><code>.agents/TEST_COVERAGE_ANALYSIS.adoc</code> — le tableau de suivi des tests, vide au départ</p> </li> </ol> </div> <div class="paragraph"> <p>Si votre projet a un domaine métier complexe (comme <code>jhipster-gradle-plugins</code> avec son mono-repo persistence/assistant), créez les agents spécialisés dès maintenant :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>.agents/PLUGIN_DEVELOPER.adoc</code> — les conventions de code et le boundary de dépendances (si plugin)</p> </li> <li> <p><code>.agents/BACKLOG_MANAGER.adoc</code> — la structure de planification et les risques identifiés</p> </li> </ol> </div> <div class="paragraph"> <p>Ne créez pas d’agents que vous n’utiliserez pas. Un agent sans conventions concrètes à encoder est un fichier mort qui pollue <code>.agents/</code>.</p> </div> </div> <div class="sect2"> <h3 id="_étape_6_ajouter_le_projet_au_portefeuille_de_tous_les_projets">Étape 6 : Ajouter le Projet au Portefeuille de TOUS les Projets</h3> <div class="paragraph"> <p>C’est l’étape qu’on oublie systématiquement. Chaque <code>INDEX.adoc</code> de chaque projet contient un tableau « Portefeuille de Projets » qui liste TOUS les projets avec la même méthodologie. Quand vous créez un nouveau projet, vous devez :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Ajouter une ligne dans le portefeuille du nouveau projet (logique)</p> </li> <li> <p>Ajouter une ligne dans le portefeuille de TOUS les projets existants — oui, tous</p> </li> </ol> </div> <div class="paragraph"> <p>Sur mes quatre (maintenant cinq) projets, cela veut dire ouvrir les <code>INDEX.adoc</code> de <code>magic-stick</code>, <code>bakery-gradle</code>, <code>cheroliv.com</code>, <code>plantuml-gradle</code> et y ajouter la ligne <code>jhipster-gradle-plugins | Session 1 | …​ | 2026-04-28 🆕</code>.</p> </div> <div class="paragraph"> <p>C’est fastidieux. C’est manuel. C’est aussi la seule façon de garantir que, quel que soit le projet sur lequel vous travaillez, l’agent sait quels autres projets existent et quel est leur état. À la session 012 de <code>magic-stick</code>, l’agent a détecté deux incohérences dans le portefeuille — <code>bakery-gradle</code> avait son COMPLETED_TASKS_ARCHIVE en retard, et <code>plantuml-gradle</code> avait un décalage entre sa documentation de procédure (5 étapes) et son INDEX (6 étapes). Sans ce tableau transverse, ces incohérences seraient restées invisibles.</p> </div> <div id="diag-portfolio-graph" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c2b21ca8d7481b154894427d05899032.svg" alt="Graphe du portefeuille de projets — références croisées entre INDEX.adoc" width="1501" height="802"> </div> </div> <div class="paragraph"> <p>Je vous entends d’ici : « Mais c’est de la duplication ! » Oui. C’est de la duplication volontaire. Chaque <code>INDEX.adoc</code> est autonome. Si vous ouvrez une session sur <code>magic-stick</code>, l’agent doit savoir que <code>plantuml-gradle</code> en est à la session 133 sans avoir à ouvrir un fichier dans un autre répertoire. C’est le prix de l’indépendance entre projets — et il est de 5 lignes par portefeuille.</p> </div> </div> <div class="sect2"> <h3 id="_ce_que_le_bootstrap_coûte">Ce que le Bootstrap Coûte</h3> <div class="paragraph"> <p>Tout ça prend 20 minutes. Vingt minutes une fois, pour ne plus jamais en perdre vingt au début de chaque session. Le ROI est immédiat : dès la session 2, l’agent reprend là où vous avez laissé la session 1.</p> </div> <div class="paragraph"> <p>Sur <code>jhipster-gradle-plugins</code>, ce bootstrap m’a pris exactement 18 minutes — de <code>mkdir .agents/</code> au dernier <code>INDEX.adoc</code> mis à jour dans le portefeuille de <code>magic-stick</code>. La session 1, qui suivra, démarrera avec un agent qui connaît déjà la structure du mono-repo, les commandes Gradle, et le boundary critique entre <code>persistence/</code> (lightweight) et <code>assistant/</code> (lourd). Vingt minutes bien investies.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_les_4_maintenant_5_projets_5_gouvernances_1_méthode">Les 4 (maintenant 5) Projets, 5 Gouvernances, 1 Méthode</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le système Eager/Lazy n’est pas un boilerplate copié-collé. Chaque projet a adapté la méthode à ses spécificités.</p> </div> <div class="sect2"> <h3 id="_cheroliv_com_le_site_personnel">cheroliv.com : Le Site Personnel</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Contenu éditorial, accessibilité WCAG 2.1 AA, JBake statique. <strong>Adaptation</strong> : Six épopées priorisées (P0-P4), agents spécialisés (CODER, SCRUM_MASTER, PLANTUML_DESIGNER), critères d’acceptation transverses sur l’accessibilité. <strong>Règle emblématique</strong> : <code>./gradlew serve</code> obligatoire, interdiction formelle du script <code>jbake.sh</code> externe.</p> </div> </div> <div class="sect2"> <h3 id="_bakery_gradle_le_plugin_multi_purpose">bakery-gradle : Le Plugin Multi-Purpose</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Plugin Gradle avec tâches de publication, génération de code Firebase, parsing YAML. <strong>Adaptation</strong> : Règle 0 (publishToMavenLocal), règle de sûreté sur les fichiers de config renforcée par l’incident du <code>site.yml</code>, EPIC 9 et 10 sur la configuration multi-fichiers. <strong>Règle emblématique</strong> : <code>publishToMavenLocal</code> après chaque modification du code source du plugin.</p> </div> </div> <div class="sect2"> <h3 id="_plantuml_gradle_le_plugin_ia">plantuml-gradle : Le Plugin IA</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Intégration LangChain4j, génération de diagrammes PlantUML via LLM, tests avec clés API cloud. <strong>Adaptation</strong> : Documentation LAZY dense (ARCHITECTURE, API_KEY_POOL_REFERENCE, DATASET_FINETUNING), EPICs numérotés (1-11 terminés, 107+ en cours), séparation EAGER/LAZY optimisée (gain de 60% de tokens). <strong>Règle emblématique</strong> : Fichiers <code>*_ESSENTIALS.adoc</code> (50 lignes) vs <code>*_REFERENCE.adoc</code> (illimité) pour le pool de clés API.</p> </div> </div> <div class="sect2"> <h3 id="_magic_stick_le_système_live">magic-stick : Le Système Live</h3> <div class="paragraph"> <p><strong>Spécificité</strong> : Build d’ISO Linux live (Xubuntu), partitionnement GPT A/B, CI/CD avec SourceForge. <strong>Adaptation</strong> : Références techniques LAZY complexes (AB_PARTITION, BOOT_TEST), SCRIPT_VERIFICATION.adoc comme étape 5 spécifique (pas de tests traditionnels, mais vérification de scripts bash). <strong>Règle emblématique</strong> : <code>isoTestAB</code> skipé en CI (runners non privilégiés), tests réservés aux environnements locaux avec Docker <code>--privileged</code>.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_règles_absolues_transverses">Règles Absolues Transverses</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quelques règles critiques qui apparaissent dans le fichier <code>AGENT.adoc</code> Eager et s’appliquent à toutes les sessions sur tous les projets :</p> </div> <div class="paragraph"> <p><strong>Environnement de dev</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ Utiliser la commande propre au projet (<code>./gradlew serve</code>, <code>./gradlew functionalTest</code>, etc.)</p> </li> <li> <p>❌ Interdit d’utiliser des scripts externes non versionnés</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Git</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ Lecture seule autorisée (<code>git status</code>, <code>git diff</code>, <code>git log</code>)</p> </li> <li> <p>❌ <code>git add</code>, <code>git commit</code>, <code>git push</code> interdits sans permission explicite</p> </li> <li> <p>❌ <code>git commit --amend</code> interdit sauf conditions méticuleusement respectées</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Fichiers de Configuration</strong></p> </div> <div class="ulist"> <ul> <li> <p>❌ Ne jamais écraser un fichier config avec un <code>Write</code> complet quand un <code>Edit</code> partiel suffit</p> </li> <li> <p>❌ Ne jamais remplacer des valeurs sensibles par des valeurs factices</p> </li> <li> <p>❌ Vérifier <code>git check-ignore</code> et <code>git ls-files</code> avant toute modification</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Tests</strong></p> </div> <div class="ulist"> <ul> <li> <p>❌ Ne jamais lancer de tests en procédure de fin de session sans permission explicite</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Outils Interdits</strong></p> </div> <div class="ulist"> <ul> <li> <p>❌ <code>TodoWrite</code> et <code>Task</code> — la gouvernance se fait via les fichiers AsciiDoc, pas via des outils externes</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_les_anti_patterns_ce_que_150_sessions_mont_appris">Les Anti-Patterns : Ce Que 150+ Sessions M’ont Appris</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avec le recul, certaines erreurs sont devenues des patterns tellement prévisibles que je peux les lister comme des anti-patterns — des pièges dans lesquels tout nouveau projet tombera probablement. Les voici, classés par ordre de fréquence.</p> </div> <div id="diag-antipatterns" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-c4b4c7d8bfdda0f1287bc4f14752a381.svg" alt="Les 7 anti-patterns de la gouvernance agent — arbre des pièges à éviter" width="1747" height="5600"> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_1_lagent_sans_opencode_json">Anti-Pattern 1 : L’Agent sans <code>opencode.json</code></h3> <div class="paragraph"> <p>C’est l’erreur numéro un. Vous avez écrit un magnifique <code>AGENT.adoc</code> de 200 lignes, mais il n’est jamais chargé automatiquement. L’agent démarre nu. Vous passez 20 minutes à le recontextualiser — exactement ce que la méthode est censée éviter.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : L’agent pose des questions basiques sur la structure du projet alors que tout est dans <code>AGENT.adoc</code>. <strong>Correction</strong> : Créer <code>opencode.json</code> avec le bloc <code>instructions: ["AGENT.adoc"]</code>. Vérifier que le fichier existe dans le working directory d’Opencode.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_2_trop_dagents_trop_tôt">Anti-Pattern 2 : Trop d’Agents Trop Tôt</h3> <div class="paragraph"> <p>À la session 2 de votre projet, vous créez 5 agents spécialisés. Aucun n’a de contenu réel, ce sont tous des stubs. Résultat : <code>.agents/</code> est pollué de fichiers vides, et l’agent hésite sur lequel charger.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Des fichiers d’agent contenant uniquement « À définir » ou une structure vide de 10 lignes. <strong>Correction</strong> : Un agent spécialisé se justifie quand son domaine métier dépasse 100 lignes ou qu’il encode au moins 5 règles concrètes. En dessous, le contenu tient dans <code>AGENT.adoc</code>.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_3_le_prompt_reprise_fantôme">Anti-Pattern 3 : Le PROMPT_REPRISE Fantôme</h3> <div class="paragraph"> <p><code>PROMPT_REPRISE.adoc</code> est mis à jour…​ mais uniquement à la fin de la session, quand l’agent exécute la procédure. Entre-temps, la mission réelle de la session a dérivé — on a corrigé un bug imprévu au lieu d’implémenter la feature planifiée. Le <code>PROMPT_REPRISE.adoc</code> de fin de session ne reflète pas ce qui s’est <strong>vraiment</strong> passé.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : La section « Priorités » de <code>PROMPT_REPRISE.adoc</code> mentionne une feature qui n’a pas été touchée, alors que vous avez passé la session sur un bug critique. <strong>Correction</strong> : Mettre à jour <code>PROMPT_REPRISE.adoc</code> en temps réel quand la session dérive de sa mission initiale. Ne pas attendre la procédure de fin de session pour documenter le changement de cap. 30 secondes d’édition pendant la session valent mieux qu’un <code>PROMPT_REPRISE</code> mensonger.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_4_larchive_vide">Anti-Pattern 4 : L’Archive Vide</h3> <div class="paragraph"> <p>La procédure de fin de session crée l’archive…​ mais l’agent, pressé d’afficher sa checklist, remplit le template avec des placeholders. <code>{detail}</code> devient « Détail à compléter plus tard ». Ce « plus tard » n’arrive jamais.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Des archives de session contenant les mots « TODO », « à compléter », ou des sections vides. <strong>Correction</strong> : La règle absolue dit qu’aucune étape ne peut être marquée [✅] si le fichier n’a pas été effectivement modifié. Appliquez-la à vous-même : relisez l’archive avant d’afficher la checklist. Si une section est vide, remplissez-la maintenant.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_5_le_portefeuille_fantôme">Anti-Pattern 5 : Le Portefeuille Fantôme</h3> <div class="paragraph"> <p>Vous créez un nouveau projet avec une gouvernance parfaite. Mais vous oubliez de l’ajouter au portefeuille des autres projets. Trois semaines plus tard, vous ouvrez une session sur <code>magic-stick</code> et l’agent vous dit que vous avez 4 projets. Vous en avez 5. L’agent ne le sait pas.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Le comptage des projets dans les portefeuilles ne correspond pas à la réalité. <strong>Correction</strong> : Scriptez la mise à jour du portefeuille, ou au minimum maintenez une checklist post-bootstrap qui inclut « Mettre à jour le portefeuille de tous les projets existants ». C’est l’étape la plus fastidieuse de la méthode, et donc la plus souvent omise.</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_6_la_redondance_cachée">Anti-Pattern 6 : La Redondance Cachée</h3> <div class="paragraph"> <p>Vous copiez-collez le même backlog de 50 lignes dans <code>AGENT.adoc</code> et <code>INDEX.adoc</code>. À la session suivante, vous mettez à jour l’un mais pas l’autre. Vos deux fichiers EAGER se contredisent.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Des divergences entre les EPICs listées dans <code>AGENT.adoc</code> et celles dans <code>INDEX.adoc</code>. <strong>Correction</strong> : La redondance doit être <strong>assumée et bornée</strong>. <code>AGENT.adoc</code> contient le backlog détaillé avec user stories. <code>INDEX.adoc</code> contient UNIQUEMENT le tableau récapitulatif des EPICs (nom, progression, priorité). Si les deux divergent, c’est <code>INDEX.adoc</code> qui fait foi — parce que c’est lui qui est mis à jour à chaque fin de session. Documentez cette règle dans votre <code>AGENT.adoc</code> : « En cas de divergence entre AGENT.adoc et INDEX.adoc, INDEX.adoc est la source de vérité. »</p> </div> </div> <div class="sect2"> <h3 id="_anti_pattern_7_la_session_trop_longue">Anti-Pattern 7 : La Session Trop Longue</h3> <div class="paragraph"> <p>Vous ignorez les signaux du <code>SESSION_CHECKLIST.adoc</code>. 2 heures, 85 messages, 12 fichiers modifiés. L’agent tourne en boucle, vous aussi. Vous auriez dû changer de session il y a 45 minutes.</p> </div> <div class="paragraph"> <p><strong>Symptôme</strong> : Le LLM répète des erreurs déjà corrigées, le contexte tokens dépasse 80k, vous avez modifié à la fois <code>persistence/</code> et <code>assistant/</code> dans la même session. <strong>Correction</strong> : Le <code>SESSION_CHECKLIST.adoc</code> existe pour une raison. Respectez-le. La règle d’or n’est pas une suggestion. 5 sessions de 20 minutes > 1 session de 2 heures.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_asciidoc">Pourquoi AsciiDoc ?</h2> <div class="sectionbody"> <div class="paragraph"> <p>J’ai choisi AsciiDoc pour plusieurs raisons pragmatiques qui ont un impact direct sur l’efficacité de la gouvernance :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Structure sémantique riche</strong> : sections, tableaux, admonitions, attributs de document. Un agent lit mieux un document structuré qu’un fond de texte.</p> </li> <li> <p><strong>Attributs de document</strong> (<code>:jbake-type:</code>, <code>:jbake-status:</code>) qui permettent de définir des métadonnées lisibles par la machine et l’humain.</p> </li> <li> <p><strong>Compatibilité avec JBake</strong> : mon site statique est généré par JBake, qui traite nativement l’AsciiDoc. Les fichiers de gouvernance et les articles de blog partagent le même format. Mon article de blog <strong>sur</strong> la gouvernance est écrit dans le même format que la gouvernance elle-même.</p> </li> <li> <p><strong>Longévité</strong> : AsciiDoc est un format de documentation technique éprouvé, avec une spécification stable.</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_résultat_une_continuité_sans_couture">Résultat : Une Continuité sans Couture</h2> <div class="sectionbody"> <div class="paragraph"> <p>Depuis que j’ai mis ce système en place, passer d’une session Opencode à l’autre est devenu fluide. L’agent reprend exactement où je l’ai laissé, sans que j’aie à recontextualiser quoi que ce soit.</p> </div> <div class="paragraph"> <p>Les décisions prises à la session 3 sont accessibles à la session 133. Le backlog reste cohérent sur cinq projets simultanés. Les règles de sécurité (notamment sur git et les fichiers de config) sont respectées parce qu’elles sont omniprésentes dans le fichier Eager.</p> </div> <div class="paragraph"> <p>Les chiffres parlent :</p> </div> <div class="ulist"> <ul> <li> <p><strong>150+ sessions archivées</strong> au total</p> </li> <li> <p><strong>60% de tokens EAGER économisés</strong> après optimisation (Session 109)</p> </li> <li> <p><strong>Zéro rappel nécessaire</strong> sur le contexte métier du pool de clés API</p> </li> <li> <p><strong>100% des tests PASS</strong> sur plantuml-plugin (240/240)</p> </li> <li> <p><strong>Une seule catastrophe</strong> (Session 2 bakery-plugin) qui a donné naissance à la règle de sûreté absolue</p> </li> </ul> </div> <div class="paragraph"> <p>C’est un <strong>système artisanal</strong>, construit avec les outils du métier (AsciiDoc, git, Gradle), sans dépendance à une plateforme propriétaire. Il reflète ma conviction fondamentale : <strong>un développeur crédible construit et utilise ses propres outils</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_liens">Liens</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Mon site : [cheroliv.com](<a href="https://cheroliv.com" class="bare">https://cheroliv.com</a>)</p> </li> <li> <p>Le projet <code>bakery-gradle</code> : [github.com/cheroliv/bakery-gradle-plugin](<a href="https://github.com/cheroliv/bakery-gradle-plugin" class="bare">https://github.com/cheroliv/bakery-gradle-plugin</a>)</p> </li> <li> <p>Le projet <code>plantuml-gradle</code> : [github.com/cheroliv/plantuml-gradle-plugin](<a href="https://github.com/cheroliv/plantuml-gradle-plugin" class="bare">https://github.com/cheroliv/plantuml-gradle-plugin</a>)</p> </li> <li> <p>Le projet <code>magic-stick</code> : [github.com/cheroliv/magic-stick](<a href="https://github.com/cheroliv/magic-stick" class="bare">https://github.com/cheroliv/magic-stick</a>)</p> </li> <li> <p>Le projet <code>cheroliv.com</code> : [github.com/cheroliv/cheroliv.github.io](<a href="https://github.com/cheroliv/cheroliv.github.io" class="bare">https://github.com/cheroliv/cheroliv.github.io</a>)</p> </li> </ul> </div> <hr> <div class="paragraph"> <p><strong>Le code qu’on écrit pour soi est le laboratoire du code qu’on enseigne aux autres.</strong></p> </div> </div> </div> https://cheroliv.com/blog/2026/0107_jbake_serve_rendering_bug_fix_post.html Wed, 22 Apr 2026 00:00:00 +0000 blog/2026/0107_jbake_serve_rendering_bug_fix_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_场景四个截图两个渲染">场景：四个截图，两个渲染</a> <ul class="sectlevel2"> <li><a href="#_本地渲染">本地渲染</a></li> <li><a href="#_线上渲染">线上渲染</a></li> </ul> </li> <li><a href="#_诊断serve_未指向正确的文件夹">诊断：<code>serve</code> 未指向正确的文件夹</a></li> <li><a href="#_根本原因jbake_cli_不会像那样工作">根本原因：JBake CLI 不会像那样工作</a></li> <li><a href="#_解决方案位置参数而不是选项">解决方案：位置参数，而不是选项</a></li> <li><a href="#_使用_curl_进行快速检查">使用 curl 进行快速检查</a></li> <li><a href="#_为什么这个_bug_很狡猾">为什么这个 bug 很狡猾</a></li> <li><a href="#_结论">结论</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">阅读时间 : 10 minutes</div> <p>你知道那个时刻吗？你本地的网站看起来一团糟，但一旦部署到线上后一切就变得完美？这就是我与我的 Gradle JBake 插件所经历的。任务`serve`它显示了方形按钮、黑色背景上的深色文字，以及奇怪地缺失的 CSS。然而`publishSite`它生成了完全相同的站点，而他却是完美的。罪魁祸首既不是 CSS，也不是浏览器，也不是缓存。正是一行 Kotlin 代码 — 以及在命令行参数上的不良习惯。</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">�抽搐</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_场景四个截图两个渲染">场景：四个截图，两个渲染</h2> <div class="sectionbody"> <div class="paragraph"> <p>那是在系统崩溃之后。我拍了四张截图以比较本地渲染 (<code>./gradlew serve`在`localhost:8820</code>) 在线渲染 (`publishSite`在 GitHub Pages 上)。每页两张截图：顶部和底部。</p> </div> <div class="sect2"> <h3 id="_本地渲染">本地渲染</h3> <div class="paragraph"> <p><strong>页面顶部</strong>— 按钮 <strong>Project</strong> 和 <strong>Template</strong> 是<strong>小的，矩形的</strong>, 标准颜色（蓝色和绿色）。 卡片 <strong>Start Writing</strong> 有个<strong>纯黑背景</strong>，无框。</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local1.png" alt="Rendu local - haut de page"> </div> </div> <div class="paragraph"> <p><strong>页脚</strong>— 副标题 <strong>"Derniers articles et ressources</strong>" 是<strong>几乎无法辨认</strong>, 在黑色背景上太暗。博客图片下的日期（“17 October 2013”等）是<strong>缺席</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_local2.png" alt="Rendu local - bas de page"> </div> </div> </div> <div class="sect2"> <h3 id="_线上渲染">线上渲染</h3> <div class="paragraph"> <p><strong>页面顶部</strong>— 同样的按钮是<strong>大的，羊的，闪亮的霓虹绿</strong>, 大写文本。 地图有一个<strong>�圆角白色框架带阴影</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online1.png" alt="Rendu en ligne - haut de page"> </div> </div> <div class="paragraph"> <p><strong>页脚</strong>— 副标题是<strong>易读</strong>. 日期是<strong>可见的</strong>. 文章卡片具有的<strong>圆形硬币</strong>并且标题是<strong>加粗</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/screen_online2.png" alt="Rendu en ligne - bas de page"> </div> </div> <div class="paragraph"> <p>第一步是主题。我使用基于 （亮色、暗色、高对比度） 的动态主题系统。<code>localStorage</code>. "也许本地商店触发了高对比度主题？不，我已经写好了https://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html[一篇关于主题预加载的完整文章], 我知道它是怎么工作的。而且，即使在高对比度模式下，CSS 结构（椭圆形按钮、阴影）也应该存在。但它不存在。</p> </div> <div class="paragraph"> <p>第二个反射：浏览器缓存。不，我之前已经用干净的配置文件做了测试。差异仍然存在。</p> </div> <div class="paragraph"> <p>第三个反射：<code>serve`没有提供与……相同的文件`publishSite</code>.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_诊断serve_未指向正确的文件夹">诊断：<code>serve</code> 未指向正确的文件夹</h2> <div class="sectionbody"> <div class="paragraph"> <p>我的 Gradle 插件`bakery`有两个主要任务：</p> </div> <div class="ulist"> <ul> <li> <p><code>bake`生成静态网站在`build/bake/</code></p> </li> <li> <p><code>serve</code>:启动一个本地网页服务器</p> </li> <li> <p><code>publishSite</code>: 推`build/bake/`向 GitHub Pages</p> </li> </ul> </div> <div class="paragraph"> <p>这种分歧只能来自`serve`. Si <code>publishSite`发布了正确的内容，那是`build/bake/`很好。如果`serve`它显示的并不是它该有的，这就是说它不起作用。`build/bake/</code>.</p> </div> <div class="paragraph"> <p>看看代码。在`SiteManager.kt`, 任务`serve`定义如下：</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version buggy)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">tasks.register("serve", JavaExec::class.java) { task -> task.apply { mainClass.set("org.jbake.launcher.Main") classpath = jbakeRuntime environment("GEM_PATH", jbakeRuntime.asPath) jvmArgs(/* ... */) args = listOf( "-b", file(site.bake.srcPath).absolutePath, "-s", layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath ) } }</code></pre> </div> </div> <div class="paragraph"> <p><code>org.jbake.launcher.Main`是JBake 2.7.0 CLI的入口点。想法：传递</code>-b`对于源文件夹和`-s`对于目标文件夹，然后启动服务器模式。只是…</p> </div> </div> </div> <div class="sect1"> <h2 id="_根本原因jbake_cli_不会像那样工作">根本原因：JBake CLI 不会像那样工作</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 2.7.0 等待的<strong>位置参数</strong>对源和目标，然后是可选的标志。签名是：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake <source> <destination> [options]</code></pre> </div> </div> <div class="paragraph"> <p>然而，在我的代码中，我写了：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", "/path/to/site", "-s", "/path/to/build/bake")</code></pre> </div> </div> <div class="paragraph"> <p>JBake把它解释为：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>-b</code>→ 解析标志 "bake" （布尔），已消费</p> </li> <li> <p><code>/path/to/site</code>→ 成为位置参数 1 （源）</p> </li> <li> <p><code>-s</code>→ 解析标志 "serve" (布尔值), 服务器已启动<strong>立即</strong></p> </li> <li> <p><code>/path/to/build/bake</code>→ 成为一个孤儿论点，被忽视或被误解</p> </li> </ol> </div> <div class="paragraph"> <p>结果：JBake 正在采取`/path/to/site`作为 来源,<strong>没有考虑到目的地</strong> 提供的 (<code>build/bake</code>),和使用了其默认目录(经常`./output`或临时副本)。 文件`css/styles.css`构建因此被覆盖或被忽略，提供的是一个旧的默认 CSS（没有自定义变量，没有圆角，没有阴影）。</p> </div> <div class="paragraph"> <p>相比起来，<code>bake</code> et <code>publishSite`使用<strong>官方 Gradle JBake 插件</strong>(`jbake-gradle-plugin</code>) 写得很整洁的`build/bake/`通过 Gradle API。它们不通过 CLI。</p> </div> </div> </div> <div class="sect1"> <h2 id="_解决方案位置参数而不是选项">解决方案：位置参数，而不是选项</h2> <div class="sectionbody"> <div class="paragraph"> <p>修正很简单 — 只要你知道。只需要把 source 和 destination 作为位置参数传递，然后`-s`最后：</p> </div> <div class="listingblock"> <div class="title">SiteManager.kt — La tâche serve (version corrigée)</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">args = listOf( file(site.bake.srcPath).absolutePath, layout.buildDirectory.get() .asFile.resolve(site.bake.destDirPath) .absolutePath, "-s" )</code></pre> </div> </div> <div class="paragraph"> <p>这就完了。修改了三行代码，bug 已修复。</p> </div> <div class="paragraph"> <p>本地发布插件后(<code>publishToMavenLocal</code>), un `./gradlew serve`使用正确的语法启动 JBake :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">jbake /home/user/project/site /home/user/project/build/bake -s</code></pre> </div> </div> <div class="paragraph"> <p>而这一次，JBake内嵌的Jetty服务器正确地提供了内容`build/bake/`— 与在线发布的内容相同。</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/serve-vs-publish-diagram.svg" alt="serve vs publish diagram" width="1738" height="5484"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用_curl_进行快速检查">使用 curl 进行快速检查</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了确保服务器提供正确的内容，一个简单`curl`确认`index.html`包含`data-bs-theme="light"`并且`build/bake/css/styles.css`确实重 31,402 字节 — 与生成的文件相同`bake`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew serve # Dans un autre terminal : $ curl -s http://localhost:8820/ | grep data-bs-theme <html ... data-bs-theme="light" ...> $ curl -I http://localhost:8820/css/styles.css HTTP/1.1 200 OK Content-Length: 31402 Content-Type: text/css</code></pre> </div> </div> <div class="paragraph"> <p>本地渲染现在<strong>像素相同</strong>部署的渲染</p> </div> </div> </div> <div class="sect1"> <h2 id="_为什么这个_bug_很狡猾">为什么这个 bug 很狡猾</h2> <div class="sectionbody"> <div class="paragraph"> <p>你明白为什么抓起来很难吗？</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>没有显式错误</strong>JBake 没有崩溃。它 "正常运行"，只是使用了错误的文件夹。</p> </li> <li> <p><strong>构建正常运行</strong> : <code>./gradlew bake`正确地生成文件在`build/bake/</code>.</p> </li> <li> <p><strong>部署正在运行。</strong>:`publishSite`在线推送了优质内容</p> </li> <li> <p><strong>只有 <code>serve</code> 坏了</strong>: 开发任务，也就是我们一直用来迭代的那个任务。</p> </li> <li> <p><strong>‑key value`的习惯</strong>: 作为开发者，我们受多年 Unix CLI 的影响 (<code>-o output</code>, <code>-i input</code>). JBake CLI 是一个例外 — 源和目标是位置参数。</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>如果您维护一个包装 JBake（或任何 CLI 工具）的 Gradle 插件，<strong>�阅读参数的文档</strong>即使你认为你认识他们。 一个隐含的假设 (<code>-s</code> = "set destination")` 可能会让你在视觉调试上浪费数小时。</p> </div> <div class="paragraph"> <p>这里，修复 literally 就是要改变：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf("-b", src, "-s", dest) // ❌ BUG</code></pre> </div> </div> <div class="paragraph"> <p>en :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">args = listOf(src, dest, "-s") // ✅ FIX</code></pre> </div> </div> <div class="paragraph"> <p>移动了三个标记，我的本地站点又变得和生产站点一样美丽。</p> </div> <div class="paragraph"> <p><strong>课</strong>: 当渲染在本地和生产之间出现差异且没有明显原因时，首先怀疑是 <strong>pipeline</strong> 的问题 — 不是 CSS，不是浏览器，更不是框架。通常是在渲染之前的那一步作弊。</p> </div> </div> </div> https://cheroliv.com/blog/2026/0106_opencode_path_sdkman_nvm_post.html Tue, 21 Apr 2026 00:00:00 +0000 blog/2026/0106_opencode_path_sdkman_nvm_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_la_scène_un_agent_aveugle_dans_un_monde_doutils">La scène : un agent aveugle dans un monde d’outils</a></li> <li><a href="#_anatomie_du_bug_deux_shells_deux_mondes">Anatomie du bug : deux shells, deux mondes</a></li> <li><a href="#_les_coupables_zshrc_vs_zshenv">Les coupables : .zshrc vs .zshenv</a></li> <li><a href="#_diagnostic_pas_à_pas">Diagnostic pas à pas</a> <ul class="sectlevel2"> <li><a href="#_1_vérifier_le_path_de_lagent">1. Vérifier le PATH de l’agent</a></li> <li><a href="#_2_identifier_ce_qui_est_dans_zshrc_mais_pas_dans_zshenv">2. Identifier ce qui est dans .zshrc mais pas dans .zshenv</a></li> <li><a href="#_3_vérifier_si_zshenv_existe">3. Vérifier si .zshenv existe</a></li> </ul> </li> <li><a href="#_la_solution_zshenv_les_bons_chemins">La solution : .zshenv + les bons chemins</a> <ul class="sectlevel2"> <li><a href="#_créer_zshenv_avec_tous_les_chemins_essentiels">Créer .zshenv avec tous les chemins essentiels</a></li> <li><a href="#_pourquoi_pas_source_sdkman_init_sh_dans_zshenv">Pourquoi pas <code>source sdkman-init.sh</code> dans .zshenv ?</a></li> </ul> </li> <li><a href="#_le_cas_nvm_quand_le_gestionnaire_de_versions_oublie_de_laisser_une_trace">Le cas NVM : quand le gestionnaire de versions oublie de laisser une trace</a> <ul class="sectlevel2"> <li><a href="#_le_problème_nvm">Le problème NVM</a></li> <li><a href="#_la_solution_créer_le_symlink_current_pour_nvm">La solution : créer le symlink <code>current</code> pour NVM</a></li> <li><a href="#_automatiser_la_mise_à_jour_du_symlink">Automatiser la mise à jour du symlink</a></li> </ul> </li> <li><a href="#_tableau_récapitulatif_des_chemins">Tableau récapitulatif des chemins</a></li> <li><a href="#_pièges_et_mitigations">Pièges et mitigations</a></li> <li><a href="#_leçons_apprises">Leçons apprises</a></li> <li><a href="#_vérification_finale">Vérification finale</a></li> <li><a href="#_liens">Liens</a> <ul class="sectlevel2"> <li><a href="#_documentation_officielle">Documentation officielle</a></li> <li><a href="#_outils_mentionnés">Outils mentionnés</a></li> <li><a href="#_pour_aller_plus_loin">Pour aller plus loin</a></li> </ul> </li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 13 minutes</div> <p>Vous lancez OpenCode dans votre terminal, tout fonctionne. L’agent tente un <code>gh</code> — introuvable. Un <code>java -version</code> — absent. Un <code>node</code> — nulle part. Pourtant, ces outils sont bien là dans <em>votre</em> shell. Le problème ? OpenCode lance des shells <strong>non-interactifs</strong> qui ne lisent jamais votre <code>.zshrc</code>. Voici comment diagnostiquer et corriger ça proprement.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_la_scène_un_agent_aveugle_dans_un_monde_doutils">La scène : un agent aveugle dans un monde d’outils</h2> <div class="sectionbody"> <div class="paragraph"> <p>C’était un mardi soir. Je venais d’installer <a href="https://opencode.ai">OpenCode</a>, l’agent IA qui promettait de transformer ma façon de coder. Premier test : lui demander de lister mes dépôts GitHub.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ opencode > Utilise gh pour lister mes repos ❌ bash: gh: command not found</code></pre> </div> </div> <div class="paragraph"> <p>Étrange. <code>gh</code> fonctionnait parfaitement dans mon terminal. J’essaie autre chose :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">> Vérifie la version de Java ❌ bash: java: command not found</code></pre> </div> </div> <div class="paragraph"> <p>Puis :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">> Lance le build Gradle ❌ bash: gradle: command not found</code></pre> </div> </div> <div class="paragraph"> <p>Java, Gradle, Node, <code>gh</code> — tout était invisible pour l’agent. Mon terminal, lui, voyait tout. Comme si l’agent et moi vivions dans deux mondes parallèles.</p> </div> <div class="paragraph"> <p>J’ai mis des heures à comprendre. Des heures de <code>echo $PATH</code>, de <code>which java</code>, de frustration croissante. J’ai fini par comprendre que le problème n’était pas les outils — c’était le <strong>shell</strong>. OpenCode, comme tout agent qui lance des sous-processus, travaille dans des shells <strong>non-interactifs</strong>. Et Zsh, dans ces shells-là, ignore purement et simplement votre <code>.zshrc</code>.</p> </div> <div class="paragraph"> <p>Ce qui suit est le récit complet de ce diagnostic, de la résolution, et de la leçon que j’ai tirée. Si vous utilisez un agent IA — OpenCode, Aider, Cursor, ou même des scripts cron — ce problème vous concernera un jour.</p> </div> </div> </div> <div class="sect1"> <h2 id="_anatomie_du_bug_deux_shells_deux_mondes">Anatomie du bug : deux shells, deux mondes</h2> <div class="sectionbody"> <div class="paragraph"> <p>Quand vous ouvrez un terminal, Zsh le traite comme un shell <strong>interactif</strong>. Il charge <code>.zshrc</code>, qui initialise tout : SDKMAN, NVM, pnpm, les aliases, votre joli prompt. Votre environnement est complet.</p> </div> <div class="paragraph"> <p>Mais quand OpenCode exécute une commande, il ne lance pas un terminal interactif. Il lance un shell <strong>non-interactif</strong> — un shell de tâche, sans humain derrière l’écran. Et Zsh, dans ce contexte, saute <code>.zshrc</code>. Il ne lit que <code>.zshenv</code>.</p> </div> <div class="paragraph"> <p>Pourquoi cette distinction existe-t-elle ? Parce qu’un shell non-interactif est conçu pour exécuter des scripts, pas pour servir un utilisateur humain. Charger les aliases, le prompt et les complétons dans un script qui tourne en background serait un gaspillage. Le problème, c’est que votre PATH — l’information la plus critique pour trouver les exécutables — est souvent initialisé dans <code>.zshrc</code>, pas dans <code>.zshenv</code>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/probleme-path.svg" alt="probleme path" width="558" height="434"> </div> </div> <div class="paragraph"> <p>La racine du problème : <strong>Zsh ne source <code>.zshrc</code> que pour les shells interactifs</strong>. OpenCode, comme tout agent IA qui lance des sous-processus, utilise des shells non-interactifs. Ces shells ne lisent que <code>.zshenv</code>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_les_coupables_zshrc_vs_zshenv">Les coupables : .zshrc vs .zshenv</h2> <div class="sectionbody"> <div class="paragraph"> <p>Zsh dispose de <strong>quatre fichiers d’initialisation</strong>, chacun avec un rôle précis. C’est un design élégant — mais c’est aussi le nœud du problème :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> <col style="width: 5%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fichier</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Sourcé quand</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rôle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modifie le PATH ?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zshenv</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Toujours</strong> (interactif + non-interactif + login)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Variables d’environnement essentielles, PATH</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅ Oui — c’est SA place</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zprofile</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Shells de login uniquement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Commandes lentes (une fois par session)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Possible</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zshrc</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Shells interactifs uniquement</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Alias, prompt, complétion, outils interactifs</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ Pas pour les variables critiques</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zlogin</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Shells de login (après .zshrc)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Messages de bienvenue, finalisation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Rarement</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le tableau donne un indice, mais il faut le comprendre en profondeur. Pensez-y comme les pièces d’une maison :</p> </div> <div class="ulist"> <ul> <li> <p><code>.zshenv</code> est le <strong>hall d’entrée</strong> — tout le monde passe par là, visiteur ou résident. Si vous mettez quelque chose ici, tout shell pourra le voir.</p> </li> <li> <p><code>.zshrc</code> est le <strong>salon</strong> — seuls les résidents (shells interactifs) y entrent. Les visiteurs (shells non-interactifs) restent dans le hall.</p> </li> <li> <p><code>.zprofile</code> et <code>.zlogin</code> sont des pièces spécialisées pour les shells de login (comme quand vous vous connectez en SSH).</p> </li> </ul> </div> <div class="paragraph"> <p>Le drame, c’est que la plupart d’entre nous mettons le PATH dans le salon. Et l’agent IA, lui, n’a jamais le droit d’y entrer.</p> </div> <div class="paragraph"> <p>Le problème en un diagramme :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/zsh-init-flow.svg" alt="zsh init flow" width="543" height="404"> </div> </div> <div class="paragraph"> <p>Quand vous ouvrez un terminal, Zsh est interactif : il lit <code>.zshrc</code>, tout fonctionne. Quand OpenCode lance un shell pour exécuter une commande, Zsh est non-interactif : il saute <code>.zshrc</code>, ne lit que <code>.zshenv</code>. Et si <code>.zshenv</code> n’existe pas ou ne contient pas le PATH — c’est le désert.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Pourquoi Zsh fait-il ça ?</strong> C’est un choix de conception hérité d’Unix. Un shell non-interactif doit être <strong>rapide</strong> et <strong>reproductible</strong>. Charger les aliases, les prompts colorés et les initialisations lourdes de SDKMAN dans un script de cron ou un agent IA serait lent et fragile. La séparation est donc logique : <code>.zshenv</code> pour l’essentiel (variables, PATH), <code>.zshrc</code> pour le confort (aliases, prompt, complétons). Le problème survient quand on met l’essentiel dans le confort.</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_diagnostic_pas_à_pas">Diagnostic pas à pas</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant de corriger, il faut comprendre exactement ce qui manque. Voici une méthode de diagnostic reproductible — gardez-la en favoris si vous travaillez avec des agents IA.</p> </div> <div class="sect2"> <h3 id="_1_vérifier_le_path_de_lagent">1. Vérifier le PATH de l’agent</h3> <div class="paragraph"> <p>On compare ce que voit votre terminal interactif avec ce que voit un shell non-interactif — c’est-à-dire ce que voit OpenCode.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans votre terminal interactif (tout fonctionne) echo $PATH | tr ':' '\n' | grep -v '^/usr' | sort</code></pre> </div> </div> <div class="paragraph"> <p>Résultat typique :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">/home/cheroliv/apps /home/cheroliv/.nvm/versions/node/v22.19.0/bin /home/cheroliv/.sdkman/candidates/java/current/bin /home/cheroliv/.sdkman/candidates/gradle/current/bin /home/cheroliv/.local/share/pnpm /home/cheroliv/.local/bin</code></pre> </div> </div> <div class="paragraph"> <p>Maintenant, simulons ce que voit l’agent — un shell non-interactif :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell non-interactif : pas de .zshrc zsh -c 'echo $PATH' | tr ':' '\n' | grep -v '^/usr' | sort</code></pre> </div> </div> <div class="paragraph"> <p>Résultat :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">/home/cheroliv/.local/bin</code></pre> </div> </div> <div class="paragraph"> <p><strong>Cinq chemins sur six ont disparu.</strong> L’agent est amputé de 83% de son environnement. C’est comme si on vous demandait de cuisiner sans la moitié de vos ustensiles — vous pourriez faire bouillir de l’eau, mais pas grand-chose d’autre.</p> </div> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p>La commande <code>zsh -c 'echo $PATH'</code> est votre <strong>outil de diagnostic numéro 1</strong>. Si un outil que vous utilisez au quotidien est absent du résultat, votre agent IA ne pourra pas le voir non plus. Testez-la avant et après chaque modification de <code>.zshenv</code>.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_2_identifier_ce_qui_est_dans_zshrc_mais_pas_dans_zshenv">2. Identifier ce qui est dans .zshrc mais pas dans .zshenv</h3> <div class="paragraph"> <p>Maintenant, on cherche le coupable dans <code>.zshrc</code>. On filtre les lignes qui mentionnent nos outils :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">grep -n 'apps\|SDKMAN\|NVM\|PNPM\|PATH' ~/.zshrc</code></pre> </div> </div> <div class="paragraph"> <p>On retrouve typiquement :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">119: PATH="/usr/bin/python3:$HOME/apps:$PATH" # ← pas exporté ! 171: export NVM_DIR="$HOME/.nvm" 172: [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # ← NVM init 176: nvm use --lts --silent # ← active une version 179: export PNPM_HOME="/home/cheroliv/.local/share/pnpm" 187: export SDKMAN_DIR="$HOME/.sdkman" 188: [[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> <div class="paragraph"> <p>Tout ça est <strong>invisible</strong> pour OpenCode. Et le <code>PATH</code> de la ligne 119 n’est même pas <code>export`é — il ne quitte jamais le shell courant. C’est un détail technique crucial : une variable sans `export</code> reste locale au shell qui la définit. Les sous-shells — comme ceux lancés par OpenCode — ne l’héritent jamais.</p> </div> </div> <div class="sect2"> <h3 id="_3_vérifier_si_zshenv_existe">3. Vérifier si .zshenv existe</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cat ~/.zshenv 2>/dev/null || echo "FICHIER ABSENT"</code></pre> </div> </div> <div class="paragraph"> <p>Si la réponse est « FICHIER ABSENT », c’est là que tout se joue.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solution_zshenv_les_bons_chemins">La solution : .zshenv + les bons chemins</h2> <div class="sectionbody"> <div class="paragraph"> <p>La stratégie est simple, mais elle demande de la précision : mettre dans <code>.zshenv</code> <strong>uniquement</strong> les chemins essentiels, sans sourcer les scripts d’initialisation lourds. On ne déplace pas <code>.zshrc</code> dans <code>.zshenv</code> — on extrait l’essentiel.</p> </div> <div class="sect2"> <h3 id="_créer_zshenv_avec_tous_les_chemins_essentiels">Créer .zshenv avec tous les chemins essentiels</h3> <div class="paragraph"> <p><code>.zshenv</code> est le <strong>seul fichier</strong> que Zsh garantit de sourcer dans <strong>tous</strong> les contextes. C’est là que doit aller le PATH.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">export SDKMAN_DIR="$HOME/.sdkman" export NVM_DIR="$HOME/.nvm" export PNPM_HOME="$HOME/.local/share/pnpm" export PATH="$HOME/apps:$HOME/.sdkman/candidates/java/current/bin:$HOME/.sdkman/candidates/gradle/current/bin:$HOME/.nvm/current/bin:$PNPM_HOME:$HOME/.local/bin:$HOME/.local/share/JetBrains/Toolbox/scripts:/usr/bin/python3:$PATH"</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>On utilise <code>$HOME/.nvm/current/bin</code> et non <code>$HOME/.nvm/versions/node/v22.19.0/bin</code>. La raison : les versions Node changent. Un chemin en dur devient faux au prochain <code>nvm install</code>. Plus de détails dans la section suivante.</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_pourquoi_pas_source_sdkman_init_sh_dans_zshenv">Pourquoi pas <code>source sdkman-init.sh</code> dans .zshenv ?</h3> <div class="paragraph"> <p>L’approche la plus tentante serait de simplement reproduire dans <code>.zshenv</code> ce qu’on fait dans <code>.zshrc</code> — sourcer les scripts d’initialisation. On <strong>pourrait</strong> être tenté de faire :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># ❌ MAUVAISE IDÉE [[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> <div class="paragraph"> <p>Problèmes :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Lent</strong> : <code>sdkman-init.sh</code> fait des résolutions réseau et des vérifications à chaque shell. Dans un shell non-interactif, c’est un coût inutile.</p> </li> <li> <p><strong>Fragile</strong> : SDKMAN s’attend à un contexte interactif. Son initialisation peut échouer silencieusement dans un pipe ou un sous-shell.</p> </li> <li> <p><strong>Inutile</strong> : SDKMAN place ses candidats dans <code>~/.sdkman/candidates/<tool>/current/bin</code> — des symlinks stables pointant vers la version active. On peut les utiliser <strong>directement</strong>.</p> </li> </ul> </div> <div class="paragraph"> <p>La bonne approche : contourner l’initialisation de SDKMAN et pointer directement sur les symlinks <code>current</code>. C’est la clé de toute la solution : <strong>utiliser la structure de fichiers comme contrat, plutôt que le code d’initialisation</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/sdkman-approach.svg" alt="sdkman approach" width="338" height="321"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_cas_nvm_quand_le_gestionnaire_de_versions_oublie_de_laisser_une_trace">Le cas NVM : quand le gestionnaire de versions oublie de laisser une trace</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_le_problème_nvm">Le problème NVM</h3> <div class="paragraph"> <p>C’est ici que l’enquête m’a mené le plus loin. SDKMAN a un design élégant : quand on fait <code>sdk install java 25.0.2-tem</code>, il crée un symlink :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.sdkman/candidates/java/current -> ~/.sdkman/candidates/java/25.0.2-tem</code></pre> </div> </div> <div class="paragraph"> <p>Ce symlink est <strong>toujours à jour</strong>. Pointez dessus dans <code>.zshenv</code> et vous êtes couvert, quel que soit le shell. Beautiful.</p> </div> <div class="paragraph"> <p>NVM, lui, ne crée <strong>rien</strong> de tel. Pas de symlink <code>current</code>. Pas de point d’ancrage stable. On doit pointer sur un chemin versionné en dur, qui ressemble à ça :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/.nvm/versions/node/v22.19.0/bin/node</code></pre> </div> </div> <div class="paragraph"> <p>Au prochain <code>nvm install 24</code>, ce chemin est mort. Votre <code>.zshenv</code> pointera vers une version qui n’est plus la version active. C’est une bombe à retardement.</p> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Pourquoi NVM fait-il ça ?</strong> NVM fonctionne en modifiant dynamiquement le PATH à chaque <code>nvm use</code>. C’est conçu pour des développeurs qui changent de version souvent, dans un shell interactif. Le symlink <code>current</code> n’était pas dans les spécifications initiales — c’est un oubli de design que nous allons corriger nous-mêmes.</p> </div> </td> </tr> </table> </div> <div class="imageblock"> <div class="content"> <img src="./images/nvm-vs-sdkman.svg" alt="nvm vs sdkman" width="1758" height="5676"> </div> </div> </div> <div class="sect2"> <h3 id="_la_solution_créer_le_symlink_current_pour_nvm">La solution : créer le symlink <code>current</code> pour NVM</h3> <div class="paragraph"> <p>Puisque NVM ne le fait pas, on le fait nous-mêmes. Le principe est le même que SDKMAN — un symlink <code>current</code> qui pointe toujours vers la version active. On le crée une fois, puis on l’automatise pour qu’il se mette à jour tout seul.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Créer le symlink initial ln -sfn "$HOME/.nvm/versions/node/v22.19.0" "$HOME/.nvm/current"</code></pre> </div> </div> <div class="paragraph"> <p>Maintenant, dans <code>.zshenv</code>, on utilise :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$HOME/.nvm/current/bin</code></pre> </div> </div> <div class="paragraph"> <p>Plutôt que :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># ❌ Chemin en dur — cassé au prochain changement de version $HOME/.nvm/versions/node/v22.19.0/bin</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_automatiser_la_mise_à_jour_du_symlink">Automatiser la mise à jour du symlink</h3> <div class="paragraph"> <p>Un symlink ne vaut rien s’il ne se met pas à jour. Le symlink <code>current</code> doit se mettre à jour quand on fait <code>nvm use</code> ou <code>nvm install</code>. La solution : un <strong>wrapper</strong> — une fonction qui enveloppe la vraie commande <code>nvm</code> et met à jour le symlink après chaque appel.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># À la fin de .zshrc, APRÈS le chargement de NVM nvm use --lts --silent ln -sfn "$(nvm_version_path "$(nvm current)")" "$NVM_DIR/current" _nvm() { command nvm "$@" local rc=$? ln -sfn "$(nvm_version_path "$(nvm current)")" "$NVM_DIR/current" return $rc } alias nvm='_nvm'</code></pre> </div> </div> <div class="paragraph"> <p>Comment ça marche, en détail :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/nvm-wrapper-flow.svg" alt="nvm wrapper flow" width="676" height="393"> </div> </div> <div class="paragraph"> <p>Le wrapper <code>_nvm</code> appelle la vraie commande <code>nvm</code>, puis met à jour le symlink. L’alias <code>nvm='_nvm'</code> fait en sorte qu’en tapant <code>nvm</code>, on passe par le wrapper. Et à l’initialisation du shell, on fait de même après <code>nvm use --lts</code>.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><code>nvm_version_path</code> est une fonction interne de NVM qui résout le chemin complet d’une version. Ça évite de reconstruire le chemin manuellement.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tableau_récapitulatif_des_chemins">Tableau récapitulatif des chemins</h2> <div class="sectionbody"> <div class="paragraph"> <p>Avant de passer aux pièges, un résumé visuel de la transformation. Sur la gauche, ce que vous aviez (tout dans <code>.zshrc</code>, invisible pour l’agent). Sur la droite, ce que vous avez maintenant (les chemins essentiels dans <code>.zshenv</code>, visibles partout).</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Outil</th> <th class="tableblock halign-left valign-top">Avant (.zshrc seulement)</th> <th class="tableblock halign-left valign-top">Après (.zshenv + symlink)</th> <th class="tableblock halign-left valign-top">Visible par OpenCode ?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps</code> (gh, vscode)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PATH non exporté dans .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/apps</code> dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN Java</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sdkman-init.sh</code> sourcé dans .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.sdkman/candidates/java/current/bin</code> dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN Gradle</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sdkman-init.sh</code> sourcé dans .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.sdkman/candidates/gradle/current/bin</code> dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM Node</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nvm use --lts</code> dans .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.nvm/current/bin</code> dans .zshenv (symlink)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">pnpm</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$PNPM_HOME</code> dans .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$PNPM_HOME</code> dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">JetBrains Toolbox</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Auto-ajouté par Toolbox dans .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>$HOME/.local/share/JetBrains/Toolbox/scripts</code> dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Python 3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>/usr/bin/python3</code> dans PATH .zshrc</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Explicitement dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">✅</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_pièges_et_mitigations">Pièges et mitigations</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tout n’est pas parfait avec cette approche. Voici les problèmes que j’ai rencontrés, et comment les contourner.</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Piège</th> <th class="tableblock halign-left valign-top">Description</th> <th class="tableblock halign-left valign-top">Mitigation</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PATH dupliqué</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Si .zshenv et .zshrc ajoutent le même chemin, il apparaît deux fois</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>.zshenv</code> est sourcé <strong>avant</strong> .zshrc. Les deux sont lus dans un shell interactif. Le PATH peut doublonner. C’est cosmétique, pas fonctionnel. Pour l’éviter : ne mettre dans .zshenv que les chemins <em>absents</em> du PATH par défaut.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">NVM : version en dur dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mettre <code>~/.nvm/versions/node/v22.19.0/bin</code> en dur devient faux au prochain <code>nvm install</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utiliser le symlink <code>$HOME/.nvm/current/bin</code> + le wrapper <code>_nvm</code> dans .zshrc</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">SDKMAN : source sdkman-init.sh dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lent, fragile, inutile dans un shell non-interactif</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utiliser les symlinks <code>candidates/<tool>/current/bin</code> directement</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Alias manquant après modification</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le wrapper <code>nvm='_nvm'</code> dans .zshrc ne prend effet qu’après rechargement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relancer le shell ou <code>source ~/.zshrc</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">OpenCode ne voit pas les changements</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’agent a déjà lancé ses sous-shells avec l’ancien .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Redémarrer OpenCode après modification de .zshenv</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv trop chargé</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Mettre des fonctions lourdes ou des initialisations interactives dans .zshenv</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.zshenv = variables d’environnement + PATH uniquement. Pas de <code>source</code>, pas de fonctions lourdes, pas de prompts.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_leçons_apprises">Leçons apprises</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong><code>.zshrc</code> est interactif, <code>.zshenv</code> est universel</strong> — Si une variable doit exister dans <em>tous</em> les shells (agents IA, cron, scripts, IDE), elle va dans <code>.zshenv</code>. Le salon est confortable, mais le hall d’entrée est le seul endroit où tout le monde passe.</p> </li> <li> <p><strong>Les gestionnaires de versions ne sont pas égaux</strong> — SDKMAN crée des symlinks <code>current</code> par design. NVM non. Il faut combler ce manque manuellement. C’est une leçon importante : avant de configurer votre PATH, vérifiez si votre gestionnaire offre un point d’ancrage stable.</p> </li> <li> <p><strong>Ne pas sourcer les init scripts dans .zshenv</strong> — <code>sdkman-init.sh</code> et <code>nvm.sh</code> sont conçus pour un shell interactif. Ils sont lents et fragiles dans un contexte non-interactif. Les symlinks <code>current</code> suffisent et sont instantanés.</p> </li> <li> <p><strong>Toujours tester en shell non-interactif</strong> — <code>zsh -c 'echo $PATH'</code> simule exactement ce que voit un agent. C’est le test de validation. Sans ce test, vous ne savez pas si votre configuration fonctionne pour les agents.</p> </li> <li> <p><strong>Le wrapper pattern est réutilisable</strong> — Le même pattern <code>_nvm</code> + <code>alias nvm='_nvm'</code> s’applique à tout outil qui modifie le PATH dynamiquement sans laisser de trace stable. C’est un outil de plus dans votre boîte à idées.</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/avant-apres.svg" alt="avant apres" width="238" height="306"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_vérification_finale">Vérification finale</h2> <div class="sectionbody"> <div class="paragraph"> <p>Après avoir créé <code>.zshenv</code> et le symlink NVM, validez que tout fonctionne — dans les deux contextes :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell interactif (votre terminal) gh --version && java -version && node --version</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Shell non-interactif (simulation OpenCode) zsh -c 'gh --version && java -version && node --version'</code></pre> </div> </div> <div class="paragraph"> <p>Les deux doivent réussir. Si oui, votre agent IA verra les mêmes outils que vous. Si non, revenez au diagnostic pas à pas — vous avez probablement oublié un chemin ou le symlink NVM n’est pas à jour.</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>Automatisez ce test.</strong> Ajoutez cette vérification dans un script de healthcheck que vous lancez après chaque mise à jour de vos outils. Un <code>zsh -c 'which java && which node && which gh'</code> en CI, c’est une assurance contre les surprises.</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p><em><em>_ Un shell non-interactif est comme un invité silencieux : il ne lit que ce qui est affiché sur la porte d’entrée. Si le PATH est dans le salon, il ne le verra jamais. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_liens">Liens</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_documentation_officielle">Documentation officielle</h3> <div class="ulist"> <ul> <li> <p><a href="https://zsh.sourceforge.io/Doc/Release/Files.html">Zsh documentation : Startup Files</a> — La référence officielle sur les fichiers d’initialisation de Zsh. C’est là que tout est expliqué, même si on l’oublie souvent.</p> </li> <li> <p><a href="https://opencode.ai/docs/config/">OpenCode : configuration</a> — Comment configurer OpenCode et son environnement d’exécution.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_outils_mentionnés">Outils mentionnés</h3> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nvm-sh/nvm">NVM sur GitHub</a> — Node Version Manager. Gestionnaire de versions Node.js.</p> </li> <li> <p><a href="https://sdkman.io">SDKMAN — site officiel</a> — SDKMAN! Le gestionnaire de versions pour la JVM (Java, Kotlin, Gradle…​)</p> </li> <li> <p><a href="https://sdkman.io/install">SDKMAN : installation</a> — Guide d’installation de SDKMAN.</p> </li> <li> <p><a href="https://cli.github.com"><code>gh</code> — GitHub CLI</a> — L’outil en ligne de commande GitHub, indispensable pour tout développeur.</p> </li> <li> <p><a href="https://gradle.org">Gradle — site officiel</a> — Le système de build que nous installons via SDKMAN.</p> </li> <li> <p><a href="https://pnpm.io">pnpm — site officiel</a> — Le gestionnaire de paquets Node.js rapide et économe en espace.</p> </li> <li> <p><a href="https://www.jetbrains.com/toolbox-app/">JetBrains Toolbox</a> — Le gestionnaire d’IDE JetBrains, qui ajoute ses scripts au PATH.</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_pour_aller_plus_loin">Pour aller plus loin</h3> <div class="ulist"> <ul> <li> <p><a href="https://blog.andy2003.org/posts/2022/zsh-dotfiles/">Zsh dotfiles : un guide complet</a> — Article approfondi sur la gestion des dotfiles Zsh.</p> </li> <li> <p><a href="https://wiki.archlinux.org/title/Zsh">Zsh sur ArchWiki</a> — L’une des meilleures documentations communautaires sur Zsh.</p> </li> <li> <p><a href="https://github.com/nvm-sh/nvm/issues">NVM issues GitHub</a> — Pour voir les discussions autour du symlink <code>current</code> et des problèmes de PATH.</p> </li> </ul> </div> </div> </div> </div> https://cheroliv.com/blog/2026/0105_integrer_graphify_workflow_gradle_post.html Sun, 19 Apr 2026 00:00:00 +0000 blog/2026/0105_integrer_graphify_workflow_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_problème_des_diagrammes_toujours_en_retard_sur_le_code">Le problème : des diagrammes toujours en retard sur le code</a></li> <li><a href="#_la_solution_un_pipeline_déterministe_knowledge_graph_plantuml">La solution : un pipeline déterministe Knowledge Graph → PlantUML</a></li> <li><a href="#_étape_1_installer_graphify_et_extraire_le_knowledge_graph">Étape 1 : Installer Graphify et extraire le Knowledge Graph</a> <ul class="sectlevel2"> <li><a href="#_installation">Installation</a></li> <li><a href="#_configurer_les_exclusions">Configurer les exclusions</a></li> <li><a href="#_extraire_le_knowledge_graph">Extraire le Knowledge Graph</a></li> </ul> </li> <li><a href="#_étape_2_le_plugin_gradle_transforme_le_knowledge_graph_en_plantuml">Étape 2 : Le plugin Gradle transforme le Knowledge Graph en PlantUML</a> <ul class="sectlevel2"> <li><a href="#_architecture_du_pipeline">Architecture du pipeline</a></li> <li><a href="#_les_composants_internes">Les composants internes</a></li> <li><a href="#_règles_de_rendu">Règles de rendu</a></li> </ul> </li> <li><a href="#_étape_3_utilisation_au_quotidien">Étape 3 : Utilisation au quotidien</a> <ul class="sectlevel2"> <li><a href="#_diagramme_complet">Diagramme complet</a></li> <li><a href="#_filtrer_par_communauté">Filtrer par communauté</a></li> <li><a href="#_filtrer_par_type_darête">Filtrer par type d’arête</a></li> <li><a href="#_filtrer_par_type_de_noeud_et_confiance">Filtrer par type de noeud et confiance</a></li> <li><a href="#_répertoire_de_sortie_personnalisé">Répertoire de sortie personnalisé</a></li> <li><a href="#_référence_complète_des_propriétés">Référence complète des propriétés</a></li> </ul> </li> <li><a href="#_le_pipeline_complet_dans_un_workflow_gradle">Le pipeline complet dans un workflow Gradle</a> <ul class="sectlevel2"> <li><a href="#_workflow_type">Workflow type</a></li> <li><a href="#_intégration_dans_le_cycle_de_développement">Intégration dans le cycle de développement</a></li> <li><a href="#_mise_à_jour_incrémentale">Mise à jour incrémentale</a></li> </ul> </li> <li><a href="#_le_dogfooding_le_plugin_se_documente_lui_même">Le dogfooding : le plugin se documente lui-même</a></li> <li><a href="#_pourquoi_cest_déterministe_et_pourquoi_ça_compte">Pourquoi c’est déterministe (et pourquoi ça compte)</a></li> <li><a href="#_diagrammes_du_pipeline_lui_même">Diagrammes du pipeline lui-même</a></li> <li><a href="#_intégration_dans_la_gouvernance_de_projet">Intégration dans la gouvernance de projet</a></li> <li><a href="#_mise_en_place_checklist_en_5_minutes">Mise en place : checklist en 5 minutes</a></li> <li><a href="#_pièges_et_mitigations">Pièges et mitigations</a></li> <li><a href="#_ce_quon_obtient_au_final">Ce qu’on obtient au final</a></li> <li><a href="#_liens">Liens</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 12 minutes</div> <p>Votre codebase grandit. Les dépendances entre modules se multiplient. La documentation architecture devient obsolète avant même d’être écrite. Et si votre build Gradle pouvait <em>automatiquement</em> générer des diagrammes à jour à partir de la structure réelle du code ? C’est exactement ce que fait le pipeline Graphify + PlantUML Gradle Plugin : <code>graphify . --no-viz</code> extrait le Knowledge Graph, <code>./gradlew generateKnowledgeGraphDiagram</code> le transforme en diagrammes PlantUML. Zéro LLM, zéro manuel, 100% déterministe.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_le_problème_des_diagrammes_toujours_en_retard_sur_le_code">Le problème : des diagrammes toujours en retard sur le code</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tout projet qui dépasse quelques milliers de lignes connaît ce syndrome :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>On dessine un diagramme d’architecture au début du projet</p> </li> <li> <p>Le code évolue, les dépendances changent</p> </li> <li> <p>Le diagramme devient un mensonge décoratif</p> </li> <li> <p>Personne ne le met à jour parce que c’est pénible</p> </li> <li> <p>Les nouveaux arrivants se basent dessus et font des erreurs</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/probleme-diagrammes-obsoletes.svg" alt="probleme diagrammes obsoletes" width="824" height="418"> </div> </div> <div class="paragraph"> <p>La question n’est pas <em>faut-il des diagrammes ?</em> — tout le monde sait que oui. La question est : <strong>qui les maintient à jour ?</strong></p> </div> <div class="paragraph"> <p>La réponse : personne. Sauf si c’est automatique.</p> </div> </div> </div> <div class="sect1"> <h2 id="_la_solution_un_pipeline_déterministe_knowledge_graph_plantuml">La solution : un pipeline déterministe Knowledge Graph → PlantUML</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le principe est simple : au lieu de dessiner les diagrammes à la main, on les <strong>génère depuis la structure réelle du code</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-complet.svg" alt="pipeline complet" width="1738" height="5516"> </div> </div> <div class="paragraph"> <p>Deux commandes. C’est tout.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Étape 1 : extraire le Knowledge Graph graphify . --no-viz # Étape 2 : générer les diagrammes PlantUML ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>Le résultat ? Des fichiers <code>.puml</code> et <code>.png</code> dans <code>diagrams/knowledge-graph/</code>, versionnés dans Git, toujours à jour avec le code.</p> </div> </div> </div> <div class="sect1"> <h2 id="_étape_1_installer_graphify_et_extraire_le_knowledge_graph">Étape 1 : Installer Graphify et extraire le Knowledge Graph</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_installation">Installation</h3> <div class="paragraph"> <p>Graphify est un outil Python qui analyse votre codebase et construit un graphe de connaissances structuré :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Méthode recommandée uv tool install graphifyy && graphify install --platform opencode # Alternative avec pip pip install graphifyy && graphify install --platform opencode</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_configurer_les_exclusions">Configurer les exclusions</h3> <div class="paragraph"> <p>Créer un fichier <code>.graphifyignore</code> à la racine du projet pour exclure les fichiers qui ne font pas partie de la logique métier :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-gitignore hljs" data-lang="gitignore"># Secrets — JAMAIS dans le graphe *-context.yml *.env # Fichiers générés build/ .gradle/ # Tests fonctionnels src/functionalTest/</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_extraire_le_knowledge_graph">Extraire le Knowledge Graph</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">graphify . --no-viz</code></pre> </div> </div> <div class="paragraph"> <p>Le flag <code>--no-viz</code> saute la génération HTML (inutile dans un pipeline Gradle). Le résultat est un fichier <code>graphify-out/graph.json</code> contenant :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Noeuds</strong> : classes, fonctions, fichiers — avec leur type et communauté</p> </li> <li> <p><strong>Arêtes</strong> : relations entre noeuds (EXTRACTED depuis le code, INFERRED par l’LLM)</p> </li> <li> <p><strong>Communautés</strong> : regroupements automatiques de noeuds liés</p> </li> </ul> </div> <div class="listingblock"> <div class="title">Exemple de structure <code>graph.json</code></div> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "nodes": [ {"id": "0", "label": "LlmService", "file_type": "code", "community": 0}, {"id": "1", "label": "ApiKeyPool", "file_type": "code", "community": 0}, {"id": "2", "label": "PlantumlService", "file_type": "code", "community": 1} ], "links": [ {"source": "1", "target": "0", "relation": "uses", "confidence": "EXTRACTED", "weight": 0.9}, {"source": "0", "target": "2", "relation": "calls", "confidence": "INFERRED", "weight": 0.7} ] }</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>Le code source (<code>.kt</code>, <code>.java</code>) est analysé localement par tree-sitter, <strong>sans appel LLM</strong>. Seuls les fichiers de documentation (<code>.adoc</code>, <code>.md</code>) nécessitent un appel LLM pour l’extraction sémantique. Donc <code>--update</code> sur du code Kotlin est quasi instantané.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_étape_2_le_plugin_gradle_transforme_le_knowledge_graph_en_plantuml">Étape 2 : Le plugin Gradle transforme le Knowledge Graph en PlantUML</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_architecture_du_pipeline">Architecture du pipeline</h3> <div class="paragraph"> <p>Le plugin <code>com.cheroliv.plantuml</code> intègre une tâche <code>generateKnowledgeGraphDiagram</code> qui transforme <code>graph.json</code> en diagrammes PlantUML de manière <strong>totalement déterministe</strong> :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/architecture-pipeline-kg.svg" alt="architecture pipeline kg" width="1109" height="450"> </div> </div> </div> <div class="sect2"> <h3 id="_les_composants_internes">Les composants internes</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Composant</th> <th class="tableblock halign-left valign-top">Rôle</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphParser</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse <code>graph.json</code> — supporte 3 formats : graphify natif (<code>nodes</code>+<code>links</code>), legacy (<code>communities</code>), flat. Résout les IDs numériques en labels.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>KnowledgeGraphRenderer</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforme déterministement un <code>KnowledgeGraph</code> en code PlantUML. Groupes par type, communautés en packages, légende automatique.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GenerateKnowledgeGraphDiagramTask</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tâche Gradle qui orchestre : parse → render → validate → PNG. Configurable via propriétés Gradle.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kgmodels.kt</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Modèles de données : <code>KnowledgeGraph</code>, <code>KnowledgeGraphNode</code>, <code>KnowledgeGraphEdge</code>, <code>KnowledgeGraphCommunity</code>, <code>EdgeType</code>.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PlantumlService</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Validation syntaxique + rendu PNG (réutilisé par toutes les tâches du plugin).</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_règles_de_rendu">Règles de rendu</h3> <div class="paragraph"> <p>Le renderer applique des conventions visuelles déterministes :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Type d’arête</th> <th class="tableblock halign-left valign-top">Notation PlantUML</th> <th class="tableblock halign-left valign-top">Signification</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">EXTRACTED</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-→</code> (trait plein, noir)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relation extraite du code source (certitude)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">INFERRED</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>..></code> (trait pointillé)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relation inférée par l’LLM (score de confiance)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">AMBIGUOUS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>--x</code> (trait rouge pointillé)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Relation ambiguë (à vérifier)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Les communautés sont rendues comme des packages PlantUML avec une palette de couleurs automatique.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_étape_3_utilisation_au_quotidien">Étape 3 : Utilisation au quotidien</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_diagramme_complet">Diagramme complet</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Générer le diagramme du Knowledge Graph complet ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="paragraph"> <p>Sortie : <code>diagrams/knowledge-graph/knowledge-graph-full.puml</code> + <code>.png</code></p> </div> </div> <div class="sect2"> <h3 id="_filtrer_par_communauté">Filtrer par communauté</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Une seule communauté ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 # Limiter le nombre de noeuds (lisibilité) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.community=community_0 \ -Pplantuml.kg.maxNodes=15</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtrer_par_type_darête">Filtrer par type d’arête</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les relations certaines (EXTRACTED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED # Relations certaines + inférées ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.edgeTypes=EXTRACTED,INFERRED</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_filtrer_par_type_de_noeud_et_confiance">Filtrer par type de noeud et confiance</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Uniquement les classes de code ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.nodeTypes=code # Seuil de confiance minimum (pour les INFERRED) ./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.minConfidence=0.7</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_répertoire_de_sortie_personnalisé">Répertoire de sortie personnalisé</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./gradlew generateKnowledgeGraphDiagram \ -Pplantuml.kg.outputDir=docs/architecture</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_référence_complète_des_propriétés">Référence complète des propriétés</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Propriété</th> <th class="tableblock halign-left valign-top">Défaut</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.community</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(toutes)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrer les communautés par nom (correspondance sous-chaîne)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.edgeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(tous)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Types d’arêtes séparés par virgules : <code>EXTRACTED</code>, <code>INFERRED</code>, <code>AMBIGUOUS</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.minConfidence</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0.0</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Seuil minimum de confiance pour les arêtes</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.maxNodes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(illimité)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Nombre maximum de noeuds à afficher</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.nodeTypes</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><em>(tous)</em></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Types de noeuds séparés par virgules (ex. <code>class</code>, <code>code</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plantuml.kg.outputDir</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagrams/knowledge-graph</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Répertoire de sortie pour les fichiers <code>.puml</code> et <code>.png</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_le_pipeline_complet_dans_un_workflow_gradle">Le pipeline complet dans un workflow Gradle</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_workflow_type">Workflow type</h3> <div class="imageblock"> <div class="content"> <img src="./images/workflow-complet.svg" alt="workflow complet" width="618" height="714"> </div> </div> </div> <div class="sect2"> <h3 id="_intégration_dans_le_cycle_de_développement">Intégration dans le cycle de développement</h3> <div class="paragraph"> <p>Le pipeline s’intègre naturellement dans les étapes clés du développement :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/cycle-developpement.svg" alt="cycle developpement" width="733" height="454"> </div> </div> </div> <div class="sect2"> <h3 id="_mise_à_jour_incrémentale">Mise à jour incrémentale</h3> <div class="paragraph"> <p>Quand le code change, on ne reconstruit pas tout le graphe depuis zéro :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Mise à jour incrémentale (fichiers modifiés uniquement) graphify . --update # Puis régénérer les diagrammes ./gradlew generateKnowledgeGraphDiagram</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><code>--update</code> re-extrait uniquement les fichiers modifiés (détectés par SHA256 dans <code>graphify-out/cache/</code>). Sur du code Kotlin, c’est quasi instantané car tree-sitter travaille localement sans appel LLM.</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_dogfooding_le_plugin_se_documente_lui_même">Le dogfooding : le plugin se documente lui-même</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le plugin PlantUML existe pour transformer des prompts en diagrammes. Il peut aussi transformer le Knowledge Graph de sa <em>propre</em> codebase en diagrammes de documentation. C’est du <em>dogfooding</em> : le plugin consomme son propre service.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/dogfooding-pipeline.svg" alt="dogfooding pipeline" width="1055" height="533"> </div> </div> <div class="paragraph"> <p>Tâches Gradle associées :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Tâche</th> <th class="tableblock halign-left valign-top">LLM ?</th> <th class="tableblock halign-left valign-top">Description</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateKnowledgeGraphDiagram</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Transforme <code>graph.json</code> en PlantUML (déterministe)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>generateDiagramDocs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Oui</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Génère des <code>.prompt</code> depuis le graphe, les traite via LLM (dogfooding)</p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Documentation déterministe (rapide, pas de LLM) ./gradlew generateKnowledgeGraphDiagram # Documentation LLM (plus riche, consomme des tokens) ./gradlew generateDiagramDocs</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_cest_déterministe_et_pourquoi_ça_compte">Pourquoi c’est déterministe (et pourquoi ça compte)</h2> <div class="sectionbody"> <div class="paragraph"> <p>Le point clé du pipeline <code>generateKnowledgeGraphDiagram</code> : <strong>il n’appelle aucun LLM</strong>. La transformation <code>graph.json</code> → PlantUML est une fonction pure.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/determinisme-vs-llm.svg" alt="determinisme vs llm" width="1004" height="405"> </div> </div> <div class="paragraph"> <p>Les avantages concrets :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Avantage</th> <th class="tableblock halign-left valign-top">Impact</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Reproductibilité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Même <code>graph.json</code> → même diagramme. Exactement. Tous les fois.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zéro coût</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pas d’appel LLM = pas de tokens = pas de facture API.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zéro latence</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Parse + render prend ~100ms, pas 1-5 secondes.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Compatible CI</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Pas de clé API nécessaire. Pas de flaky test dû à une réponse LLM variable.</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Versionnable</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le <code>.puml</code> généré est du texte. On peut le <code>diff</code>, le reviewer en PR, le versionner dans Git.</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_diagrammes_du_pipeline_lui_même">Diagrammes du pipeline lui-même</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pour boucler la boucle, voici le diagramme du pipeline tel qu’il serait généré par le plugin :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/pipeline-sequence.svg" alt="pipeline sequence" width="1695" height="554"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_intégration_dans_la_gouvernance_de_projet">Intégration dans la gouvernance de projet</h2> <div class="sectionbody"> <div class="paragraph"> <p>Dans notre projet, ce pipeline s’intègre dans une stratégie de gestion de contexte EAGER/LAZY pour l’agent IA. Le Knowledge Graph remplace la documentation architecture manuelle par un graphe structuré, queryable, et auto-mis à jour.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/strategie-hybride.svg" alt="strategie hybride" width="2019" height="240"> </div> </div> <div class="paragraph"> <p>Le mariage des deux systèmes est complémentaire :</p> </div> <div class="ulist"> <ul> <li> <p><strong>La stratégie gère le QUAND et le COMMENT</strong> — gouvernance, workflow, archivage</p> </li> <li> <p><strong>Graphify gère le QUOI et le OÙ</strong> — structure du code, relations, requêtes ciblées</p> </li> </ul> </div> <div class="paragraph"> <p><em><em>_ La stratégie de session gère le <strong>QUAND</strong> et le <strong>COMMENT</strong> (gouvernance, workflow, seuils), Graphify gère le <strong>QUOI</strong> et le <strong>OÙ</strong> (structure du code, relations, requêtes ciblées). Le pipeline PlantUML gère le <strong>AVEC QUOI</strong> (diagrammes déterministes, versionnés, toujours à jour). </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_mise_en_place_checklist_en_5_minutes">Mise en place : checklist en 5 minutes</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">#</th> <th class="tableblock halign-left valign-top">Étape</th> <th class="tableblock halign-left valign-top">Commande</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Installer Graphify</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>uv tool install graphifyy</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Configurer les exclusions</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Créer <code>.graphifyignore</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extraire le Knowledge Graph</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>graphify . --no-viz</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Générer les diagrammes</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>./gradlew generateKnowledgeGraphDiagram</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Committer les résultats</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>git add diagrams/knowledge-graph/</code></p></td> </tr> </tbody> </table> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Script complet en 5 commandes uv tool install graphifyy cat > .graphifyignore << 'EOF' *-context.yml *.env build/ .gradle/ EOF graphify . --no-viz ./gradlew generateKnowledgeGraphDiagram git add graphify-out/GRAPH_REPORT.adoc graphify-out/graph.json diagrams/knowledge-graph/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pièges_et_mitigations">Pièges et mitigations</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 33.3333%;"> <col style="width: 33.3334%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Piège</th> <th class="tableblock halign-left valign-top">Description</th> <th class="tableblock halign-left valign-top">Mitigation</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Graphe trop dense</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un gros projet génère des centaines de noeuds illisibles</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utiliser <code>-Pplantuml.kg.maxNodes=30</code> et filtrer par communauté</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Exclusions trop larges</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Trop de fichiers dans <code>.graphifyignore</code> réduit la valeur du graphe</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Commencer par exclure seulement credentials et build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Direction des flèches</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Les arêtes INFERRED peuvent avoir une direction ambiguë</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Filtrer par <code>-Pplantuml.kg.edgeTypes=EXTRACTED</code> pour les relations certaines uniquement</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Graphe obsolète</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Le code change mais le graphe n’est pas reconstruit</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Utiliser <code>graphify . --update</code> régulièrement ou le hook git <code>graphify hook install</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Coût mis à jour</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Les mises à jour incrémentales sont quasi gratuites (tree-sitter local)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Seules les docs (<code>.adoc</code>) consomment des tokens LLM</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_ce_quon_obtient_au_final">Ce qu’on obtient au final</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/recap-visuel.svg" alt="recap visuel" width="372" height="258"> </div> </div> <div class="paragraph"> <p>Les bénéfices concrets :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Bénéfice</th> <th class="tableblock halign-left valign-top">Détail</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Documentation toujours à jour</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Les diagrammes reflètent le code actuel, pas un snapshot manuel</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Zéro effort de maintenance</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Les diagrammes se régénèrent à chaque build</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Réduction de la dette technique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Plus besoin de maintenir les diagrammes à la main</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Contexte visuel pour les nouveaux</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un nouveau développeur comprend l’architecture en regardant les diagrammes</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fine-tuning potentiel</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Les paires (sous-graphe → diagramme) sont des exemples d’entraînement IA</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Validation automatique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PlantumlService.validateSyntax()</code> vérifie chaque diagramme généré</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Onboarding rapide</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">5 diagrammes = vue complète de l’architecture</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><em><em>_ Celui qui a un _pourquoi</em> peut supporter tous les <em>comment</em>. </em>__</p> </div> <div class="paragraph"> <p>Le <em>pourquoi</em> : des diagrammes toujours à jour. Le <em>comment</em> : deux commandes dans un pipeline Gradle.</p> </div> </div> </div> <div class="sect1"> <h2 id="_liens">Liens</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/nicholasgasior/graphify">Graphify sur GitHub</a></p> </li> <li> <p><a href="https://github.com/cheroliv/plantuml-gradle">PlantUML Gradle Plugin</a></p> </li> <li> <p><a href="/blog/2026/0104_fg_command_super_tips_post.html">Le super tips de la commande fg</a> — article précédent sur le workflow terminal</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0104_fg_command_super_tips_post.html Sat, 18 Apr 2026 00:00:00 +0000 blog/2026/0104_fg_command_super_tips_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_le_problème_un_terminal_occupé">Le problème : un terminal occupé</a></li> <li><a href="#_les_trois_commandes_indispensables">Les trois commandes indispensables</a> <ul class="sectlevel2"> <li><a href="#_ctrlz_suspendre_sigtstp">Ctrl+Z — Suspendre (SIGTSTP)</a></li> <li><a href="#_fg_reprendre_en_avant_plan">fg — Reprendre en avant-plan</a></li> <li><a href="#_bg_reprendre_en_arrière_plan">bg — Reprendre en arrière-plan</a></li> <li><a href="#_jobs_lister_les_jobs_du_shell">jobs — Lister les jobs du shell</a></li> </ul> </li> <li><a href="#_scénario_1_le_long_build">Scénario 1 : Le long build</a> <ul class="sectlevel2"> <li><a href="#_pas_à_pas">Pas à pas</a></li> </ul> </li> <li><a href="#_scénario_2_léditeur_oublié">Scénario 2 : L’éditeur oublié</a></li> <li><a href="#_scénario_3_le_processus_opencode_suspendu">Scénario 3 : Le processus opencode suspendu</a></li> <li><a href="#_scénario_4_gérer_plusieurs_jobs_simultanément">Scénario 4 : Gérer plusieurs jobs simultanément</a> <ul class="sectlevel2"> <li><a href="#_récapitulatif_des_commandes_de_jobs">Récapitulatif des commandes de jobs</a></li> </ul> </li> <li><a href="#_différences_entre_fg_bg_ctrlz_ctrlc_et">Différences entre fg, bg, Ctrl+Z, Ctrl+C et &</a></li> <li><a href="#_le_cycle_de_vie_complet_dun_job">Le cycle de vie complet d’un job</a></li> <li><a href="#_tips_avancés">Tips avancés</a> <ul class="sectlevel2"> <li><a href="#_fg_avec_le_job_le_plus_récent_et_lalternance">fg avec le job le plus récent et l’alternance</a></li> <li><a href="#_tuer_un_job_proprement">tuer un job proprement</a></li> <li><a href="#_désown_détacher_du_shell">désown : détacher du shell</a></li> <li><a href="#_combiner_avec_nohup_pour_les_longs_processus">Combiner avec nohup pour les longs processus</a></li> </ul> </li> <li><a href="#_pièges_et_erreurs_courantes">Pièges et erreurs courantes</a> <ul class="sectlevel2"> <li><a href="#_confondre_ctrlz_et_ctrlc">Confondre Ctrl+Z et Ctrl+C</a></li> <li><a href="#_les_jobs_sont_locaux_au_shell">Les jobs sont locaux au shell</a></li> <li><a href="#_les_jobs_ne_survivent_pas_à_la_fermeture_du_shell">Les jobs ne survivent pas à la fermeture du shell</a></li> <li><a href="#_les_processus_interactifs_et_fg">Les processus interactifs et fg</a></li> </ul> </li> <li><a href="#_diagramme_récapitulatif">Diagramme récapitulatif</a></li> <li><a href="#_pourquoi_fg_est_sous_estimé">Pourquoi fg est sous-estimé</a></li> <li><a href="#_mémoire_technique_les_signaux">Mémoire technique : les signaux</a></li> <li><a href="#_conclusion">Conclusion</a></li> <li><a href="#_références">Références</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 10 minutes</div> <p>Vous lancez <code>./gradlew build</code>, le terminal est bloqué pendant 3 minutes, et vous avez besoin de faire autre chose <em>en attendant</em> ? Pas besoin d’ouvrir un nouvel onglet. <code>Ctrl+Z</code> suspend le processus, <code>fg</code> le ramène exactement là où vous l’avez laissé. C’est le tips Unix le plus sous-estimé du quotidien d’un développeur.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_le_problème_un_terminal_occupé">Le problème : un terminal occupé</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tout développeur a connu cette situation :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building...</code></pre> </div> </div> <div class="paragraph"> <p>Le terminal est bloqué. Vous ne pouvez plus taper aucune commande. Et vous avez besoin de consulter un fichier, lancer un <code>git status</code>, ou vérifier un port occupé.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/terminal-bloque.svg" alt="terminal bloque" width="455" height="408"> </div> </div> <div class="paragraph"> <p>La plupart des développeurs ouvrent un nouveau terminal. Mais il existe une solution plus élégante, plus rapide, et native : la gestion des jobs.</p> </div> </div> </div> <div class="sect1"> <h2 id="_les_trois_commandes_indispensables">Les trois commandes indispensables</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrlz_suspendre_sigtstp">Ctrl+Z — Suspendre (SIGTSTP)</h3> <div class="paragraph"> <p><code>Ctrl+Z</code> envoie le signal <code>SIGTSTP</code> au processus en avant-plan. Le processus est <strong>suspendu</strong> — pas tué — et le terminal retrouve son prompt.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $</code></pre> </div> </div> <div class="paragraph"> <p>Le nombre entre crochets <code>[1]</code> est le <strong>numéro de job</strong>. Le <code>+</code> indique le job par défaut.</p> </div> </div> <div class="sect2"> <h3 id="_fg_reprendre_en_avant_plan">fg — Reprendre en avant-plan</h3> <div class="paragraph"> <p><code>fg</code> ramène le job suspendu au premier plan. Le processus reprend exactement là où il s’était arrêté.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg ./gradlew build > Building... (reprend où il en était)</code></pre> </div> </div> <div class="paragraph"> <p>Avec un numéro de job spécifique :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ fg %2</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_bg_reprendre_en_arrière_plan">bg — Reprendre en arrière-plan</h3> <div class="paragraph"> <p><code>bg</code> reprend le processus <em>sans</em> bloquer le terminal. Idéal pour les longs builds.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ bg [1]+ ./gradlew build & $</code></pre> </div> </div> <div class="paragraph"> <p>Le <code>&</code> à la fin signifie que le processus tourne en arrière-plan.</p> </div> </div> <div class="sect2"> <h3 id="_jobs_lister_les_jobs_du_shell">jobs — Lister les jobs du shell</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim README.md [2]+ En cours ./gradlew build</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/jobs-lifecycle.svg" alt="jobs lifecycle" width="606" height="395"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_scénario_1_le_long_build">Scénario 1 : Le long build</h2> <div class="sectionbody"> <div class="paragraph"> <p>C’est le cas d’usage le plus courant. Vous lancez un build Gradle, le terminal est bloqué, et vous avez besoin de faire autre chose.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/scenario-build.svg" alt="scenario build" width="641" height="599"> </div> </div> <div class="sect2"> <h3 id="_pas_à_pas">Pas à pas</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build > Building... ^Z [1]+ Stoppé ./gradlew build $ git status On branch main nothing to commit, working tree clean $ fg ./gradlew build > Building... BUILD SUCCESSFUL in 2m 34s</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_scénario_2_léditeur_oublié">Scénario 2 : L’éditeur oublié</h2> <div class="sectionbody"> <div class="paragraph"> <p>Vous êtes dans <code>vim</code>, vous avez besoin de consulter un autre fichier <em>sans</em> quitter <code>vim</code>.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, en mode commande : :shell $ cat /path/to/other/file.txt $ exit # Retour dans vim</code></pre> </div> </div> <div class="paragraph"> <p>Mais c’est lourd. Avec <code>Ctrl+Z</code>, c’est immédiat :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Dans vim, n'importe quel moment : Ctrl+Z [1]+ Stoppé vim README.md $ cat /path/to/other/file.txt # ... lire le fichier ... $ fg vim README.md # Retour exact là où on en était, curseur en place</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/vim-suspend.svg" alt="vim suspend" width="410" height="510"> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <code>vim</code> restaure parfaitement son état après un <code>fg</code> : position du curseur, contenu du buffer, historique d’annulation — tout est préservé. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_scénario_3_le_processus_opencode_suspendu">Scénario 3 : Le processus opencode suspendu</h2> <div class="sectionbody"> <div class="paragraph"> <p>C’est le scénario qui a motivé cet article. Vous utilisez <code>opencode</code> (outil CLI pour piloter un LLM sur votre code), et le processus est suspendu.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/opencode-fg.svg" alt="opencode fg" width="431" height="618"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ opencode # ... session en cours, LLM analyse le code ... ^Z [1]+ Stoppé opencode $ git diff HEAD~1 # vérifier les changements récents $ fg opencode # Le LLM reprend là où il s'était arrêté</code></pre> </div> </div> <div class="paragraph"> <p>L’avantage est double :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Pas de perte de contexte</strong> : la session LLM, l’historique de conversation, les fichiers ouverts — tout est préservé</p> </li> <li> <p><strong>Pas de redémarrage</strong> : pas besoin de relancer opencode, de recharger le contexte, de réexpliquer le problème au LLM</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_scénario_4_gérer_plusieurs_jobs_simultanément">Scénario 4 : Gérer plusieurs jobs simultanément</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>fg</code> et <code>bg</code> acceptent un numéro de job pour cibler un processus spécifique quand plusieurs sont suspendus.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim config.yml ^Z [1]+ Stoppé vim config.yml $ ./gradlew test ^Z [2]+ Stoppé ./gradlew test $ htop ^Z [3]+ Stoppé htop $ jobs [1] Stoppé vim config.yml [2]- Stoppé ./gradlew test [3]+ Stoppé htop $ fg %2 ./gradlew test # Le build reprend en avant-plan $ bg %3 [3] htop & # htop reprend en arrière-plan</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/multiple-jobs.svg" alt="multiple jobs" width="778" height="280"> </div> </div> <div class="sect2"> <h3 id="_récapitulatif_des_commandes_de_jobs">Récapitulatif des commandes de jobs</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Commande</th> <th class="tableblock halign-left valign-top">Effet</th> <th class="tableblock halign-left valign-top">Exemple</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Suspend le processus en avant-plan</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Envoi de <code>SIGTSTP</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reprend le job par défaut en avant-plan</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code> ou <code>fg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reprend le job n en avant-plan</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reprend le job par défaut en arrière-plan</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg</code> ou <code>bg %1</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Reprend le job n en arrière-plan</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bg %2</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Liste les jobs du shell courant</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jobs -l</code> (avec PID)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Termine le job n</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %2</code></p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_différences_entre_fg_bg_ctrlz_ctrlc_et">Différences entre fg, bg, Ctrl+Z, Ctrl+C et &</h2> <div class="sectionbody"> <div class="paragraph"> <p>Beaucoup de développeurs confondent ces mécanismes. Voici une clarification décisive.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/signals-comparison.svg" alt="signals comparison" width="1476" height="244"> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 33.3333%;"> <col style="width: 16.6666%;"> <col style="width: 33.3335%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Raccourci/Commande</th> <th class="tableblock halign-left valign-top">Signal</th> <th class="tableblock halign-left valign-top">Effet</th> <th class="tableblock halign-left valign-top">Revenir en arrière ?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Suspend le processus (figé, en mémoire)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Oui : <code>fg</code> ou <code>bg</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tue le processus (terminé)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non : processus détruit</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tue le processus + core dump</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non : processus détruit</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commande &</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">—</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Lance en arrière-plan directement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code> pour le ramener en avant-plan</p></td> </tr> </tbody> </table> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <code>Ctrl+Z</code> est <strong>non-destructif</strong>. Le processus est figé tel quel, en mémoire. Vous pouvez reprendre immédiatement avec <code>fg</code>. C’est un <em>pause</em>, pas un <em>stop</em>. </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_le_cycle_de_vie_complet_dun_job">Le cycle de vie complet d’un job</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/job-lifecycle-complete.svg" alt="job lifecycle complete" width="466" height="689"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_tips_avancés">Tips avancés</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_fg_avec_le_job_le_plus_récent_et_lalternance">fg avec le job le plus récent et l’alternance</h3> <div class="paragraph"> <p><code>fg</code> sans argument ramène le job marqué <code>+</code> (le plus récent). Mais vous pouvez aussi utiliser <code>%-</code> pour cibler le job précédent :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ vim file1.txt ^Z [1]+ Stoppé vim file1.txt $ vim file2.txt ^Z [2]+ Stoppé vim file2.txt $ fg # ramène job [2] (le plus récent) $ fg %- # ramène job [1] (le précédent)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_tuer_un_job_proprement">tuer un job proprement</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ jobs [1]- Stoppé vim config.yml [2]+ Stoppé ./gradlew test $ kill %2 # envoie SIGTERM au job 2 $ kill -9 %1 # envoie SIGKILL au job 1 (force)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_désown_détacher_du_shell">désown : détacher du shell</h3> <div class="paragraph"> <p><code>disown</code> retire un job de la table des jobs du shell. Le processus continue de tourner mais ne peut plus être ramené avec <code>fg</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ ./gradlew build & [1] 12345 $ disown %1 # Le processus continue mais n'est plus lié au shell # Ça survives à la fermeture du terminal</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_combiner_avec_nohup_pour_les_longs_processus">Combiner avec nohup pour les longs processus</h3> <div class="paragraph"> <p>Pour qu’un processus survive à la fermeture du terminal :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Le build continue même si vous fermez le terminal</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/advanced-tips.svg" alt="advanced tips" width="1371" height="205"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pièges_et_erreurs_courantes">Pièges et erreurs courantes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_confondre_ctrlz_et_ctrlc">Confondre Ctrl+Z et Ctrl+C</h3> <div class="paragraph"> <p>C’est l’erreur la plus fréquente. <code>Ctrl+C</code> tue le processus. <code>Ctrl+Z</code> le suspend. Si vous appuyez sur <code>Ctrl+C</code> par réflexe, tout l’état est perdu — fichiers ouverts, sessions LLM, builds en cours.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/ctrlz-vs-ctrlc.svg" alt="ctrlz vs ctrlc" width="1142" height="129"> </div> </div> </div> <div class="sect2"> <h3 id="_les_jobs_sont_locaux_au_shell">Les jobs sont locaux au shell</h3> <div class="paragraph"> <p><code>jobs</code>, <code>fg</code> et <code>bg</code> ne fonctionnent que dans le shell qui a lancé les processus. Si vous ouvrez un nouveau terminal, vous ne verrez pas les jobs de l’autre.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Terminal 1 $ vim file.txt ^Z [1]+ Stoppé vim file.txt # Terminal 2 (nouveau) $ jobs # (rien — les jobs sont locaux au shell)</code></pre> </div> </div> <div class="paragraph"> <p>Pour voir les processus system-wide, utilisez <code>ps</code> ou <code>htop</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">ps aux | grep vim</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_les_jobs_ne_survivent_pas_à_la_fermeture_du_shell">Les jobs ne survivent pas à la fermeture du shell</h3> <div class="paragraph"> <p>Si vous fermez le terminal, tous les jobs suspendus ou en arrière-plan sont détruits. Pour qu’un processus survive, utilisez <code>nohup</code> + <code>disown</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ nohup ./gradlew build & [1] 12345 $ disown %1 # Fermer le terminal → le build continue</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_les_processus_interactifs_et_fg">Les processus interactifs et fg</h3> <div class="paragraph"> <p>Certains programmes interactifs ne se portent pas bien après un <code>Ctrl+Z</code> + <code>fg</code>. C’est rare mais ça arrive :</p> </div> <div class="ulist"> <ul> <li> <p>Certains programmes qui utilisent des signaux (vim, htop, less gèrent bien <code>Ctrl+Z</code>)</p> </li> <li> <p>Les programmes réseau longs (ssh, opencode) récupèrent généralement correctement</p> </li> <li> <p>Les programmes qui modifient le terminal (ncurses) peuvent parfois laisser le terminal dans un état inattendu</p> </li> </ul> </div> <div class="paragraph"> <p>En cas de terminal corrompu après un <code>fg</code>, tapez :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">reset</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_diagramme_récapitulatif">Diagramme récapitulatif</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/fg-recap.svg" alt="fg recap" width="1271" height="233"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pourquoi_fg_est_sous_estimé">Pourquoi fg est sous-estimé</h2> <div class="sectionbody"> <div class="paragraph"> <p>La plupart des développeurs modernes découvrent <code>fg</code> tard, voire jamais. Quelques raisons :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Les IDE cachent le terminal</strong> : VS Code propose un terminal intégré, mais les onglets multiples rendent <code>fg</code> moins nécessaire en apparence</p> </li> <li> <p><strong>Les outils graphiques remplacent les CLI</strong> : les gestionnaires de fichiers, les moniteurs système, les clients Git graphiques</p> </li> <li> <p><strong>tmux et screen</strong> : ces multiplexeurs résolvent le même problème différemment, mais <code>fg</code> est plus simple et toujours disponible</p> </li> </ol> </div> <div class="paragraph"> <p>Pourtant, <code>fg</code> est :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Universel</strong> : présent dans tous les shells POSIX (bash, zsh, fish…​)</p> </li> <li> <p><strong>Sans dépendance</strong> : pas besoin d’installer tmux ou screen</p> </li> <li> <p><strong>Instantané</strong> : deux frappes (<code>Ctrl+Z</code> puis <code>fg</code>) pour suspendre et reprendre</p> </li> <li> <p><strong>Préservateur de contexte</strong> : l’état du processus est intact</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="./images/why-fg-underrated.svg" alt="why fg underrated" width="771" height="227"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_mémoire_technique_les_signaux">Mémoire technique : les signaux</h2> <div class="sectionbody"> <div class="paragraph"> <p>Pour les curieux, voici les signaux impliqués :</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 14.2857%;"> <col style="width: 28.5714%;"> <col style="width: 28.5714%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Signal</th> <th class="tableblock halign-left valign-top">Nom</th> <th class="tableblock halign-left valign-top">Envoyé par</th> <th class="tableblock halign-left valign-top">Effet</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGINT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+C</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Interruption — termine le processus</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGQUIT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+\</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Quitte avec core dump</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">18</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTSTP</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Ctrl+Z</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Stop interactif — suspend le processus</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">19</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGCONT</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>fg</code> / <code>bg</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Continue — reprend un processus suspendu</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGTERM</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Terminaison propre</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>SIGKILL</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>kill -9 %n</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Terminaison forcée (impossible à intercepter)</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Le flux complet :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/signal-flow.svg" alt="signal flow" width="434" height="525"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion">Conclusion</h2> <div class="sectionbody"> <div class="paragraph"> <p><code>fg</code> n’est pas un tips obscur — c’est un mécanisme fondamental du shell Unix, disponible depuis les années 70. Le fait que la plupart des développeurs l’ignorent est un symptôme de notre époque : les IDE et les multiplexeurs nous ont éloignés des bases.</p> </div> <div class="paragraph"> <p>Mais quand vous êtes sur un serveur SSH, dans un terminal minimal, ou simplement en train d’utiliser <code>opencode</code> et que le LLM est en plein travail — <code>Ctrl+Z</code>, <code>fg</code>, <code>bg</code>, <code>jobs</code> sont vos meilleurs amis.</p> </div> <div class="paragraph"> <p><em><em>_ Ctrl+Z suspend, fg reprend. C’est la pause-play du terminal. </em>_</em></p> </div> </div> </div> <div class="sect1"> <h2 id="_références">Références</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><code>man bash</code> — section JOB CONTROL</p> </li> <li> <p><code>man signal</code> — liste des signaux POSIX</p> </li> <li> <p><a href="https://www.gnu.org/software/bash/manual/bash.html#Job-Control">Bash Reference Manual — Job Control</a></p> </li> <li> <p><a href="https://man7.org/linux/man-pages/man7/signal.7.html">man 7 signal — signaux Linux</a></p> </li> <li> <p><a href="https://tldp.org/LDP/abs/html/x312743.htm">Advanced Bash-Scripting Guide — Job Control</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0103_vscode_local_install_custom_fonts_post.html Fri, 17 Apr 2026 00:00:00 +0000 blog/2026/0103_vscode_local_install_custom_fonts_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_vue_densemble_du_parcours">Vue d’ensemble du parcours</a></li> <li><a href="#_le_pourquoi_vs_code_dans_le_home">Le Pourquoi : VS Code dans le Home</a> <ul class="sectlevel2"> <li><a href="#_le_problème_avec_linstallation_système">Le problème avec l’installation système</a></li> <li><a href="#_la_solution_une_installation_locale">La solution : une installation locale</a></li> <li><a href="#_avantages_concrets">Avantages concrets</a></li> </ul> </li> <li><a href="#_customiser_la_police_du_menu_principal">Customiser la police du menu principal</a> <ul class="sectlevel2"> <li><a href="#_le_constat">Le constat</a></li> <li><a href="#_la_technique_patch_css_direct">La technique : patch CSS direct</a></li> <li><a href="#_supprimer_lavertissement_dintégrité">Supprimer l’avertissement d’intégrité</a></li> </ul> </li> <li><a href="#_customiser_la_police_du_volet_explorer_le_combat">Customiser la police du volet Explorer — le combat</a> <ul class="sectlevel2"> <li><a href="#_tentative_1_un_paramètre_qui_nexiste_pas">Tentative 1 : un paramètre qui n’existe pas</a></li> <li><a href="#_tentative_2_lextension_custom_css_and_js_loader">Tentative 2 : l’extension Custom CSS and JS Loader</a></li> <li><a href="#_le_piège_il_faut_activer_lextension_à_chaque_fois">Le piège : il faut activer l’extension à chaque fois</a></li> <li><a href="#_tentative_3_les_lignes_se_superposent">Tentative 3 : les lignes se superposent</a></li> <li><a href="#_la_solution_zoom_sur_le_conteneur_parent">La solution : <code>zoom</code> sur le conteneur parent</a></li> <li><a href="#_récapitulatif_des_selectors_et_de_ce_qui_fonctionne">Récapitulatif des selectors et de ce qui fonctionne</a></li> </ul> </li> <li><a href="#_le_script_de_mise_à_jour_automatique">Le script de mise à jour automatique</a> <ul class="sectlevel2"> <li><a href="#_le_problème">Le problème</a></li> <li><a href="#_le_script_vscode_update_sh">Le script <code>vscode-update.sh</code></a></li> </ul> </li> <li><a href="#_fichiers_impliqués_vue_densemble">Fichiers impliqués — vue d’ensemble</a></li> <li><a href="#_leçons_apprises">Leçons apprises</a> <ul class="sectlevel2"> <li><a href="#_installer_dans_le_home_libère_tout">Installer dans le home libère tout</a></li> <li><a href="#_zoom_font_size_pour_les_composants_list"><code>zoom</code> > <code>font-size</code> pour les composants list</a></li> <li><a href="#_lextension_custom_css_nécessite_une_activation_explicite">L’extension Custom CSS nécessite une activation explicite</a></li> <li><a href="#_un_script_de_mise_à_jour_est_indispensable">Un script de mise à jour est indispensable</a></li> </ul> </li> <li><a href="#_références_rapides">Références rapides</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 8 minutes</div> <p>Pourquoi installer VS Code dans <code>/opt</code> ou via <code>apt</code> quand on peut le poser dans son home et transformer son IDE en terrain de jeu sans jamais taper <code>sudo</code> ? Voici le récit d’une installation locale suivie d’un combat acharné pour agrandir les polices du menu et de l’explorateur de fichiers.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_vue_densemble_du_parcours">Vue d’ensemble du parcours</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-local-overview.svg" alt="vscode local overview" width="1057" height="380"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_pourquoi_vs_code_dans_le_home">Le Pourquoi : VS Code dans le Home</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_le_problème_avec_linstallation_système">Le problème avec l’installation système</h3> <div class="paragraph"> <p>VS Code installé via <code>apt</code>, <code>dnf</code> ou dans <code>/opt</code> verrouille les fichiers de l’application derrière les droits root. Toute modification du CSS natif, de <code>product.json</code> ou du dossier d’installation nécessite <code>sudo</code>.</p> </div> <div class="paragraph"> <p>Or, quand on utilise <strong>opencode</strong> (tool CLI pour piloter un LLM sur son code), l’agent a besoin de pouvoir :</p> </div> <div class="ulist"> <ul> <li> <p>Écrire dans les fichiers de configuration (<code>~/.config/Code/User/settings.json</code>) — ça, c’est déjà dans le home</p> </li> <li> <p>Modifier les assets de l’IDE (CSS du workbench, <code>product.json</code>) pour les customisations avancées — ça, c’est bloqué sans sudo</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_la_solution_une_installation_locale">La solution : une installation locale</h3> <div class="paragraph"> <p>On télécharge l’archive tarball officielle et on la décompresse directement dans <code>~/apps/</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/apps cd ~/apps wget "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" -O vscode.tar.gz tar -xzf vscode.tar.gz rm vscode.tar.gz</code></pre> </div> </div> <div class="paragraph"> <p>Le binaire se trouve alors en <code>~/apps/VSCode-linux-x64/bin/code</code>. Aucun <code>sudo</code> n’est nécessaire pour lire, modifier ou remplacer n’importe quel fichier sous <code>~/apps/VSCode-linux-x64/</code>.</p> </div> </div> <div class="sect2"> <h3 id="_avantages_concrets">Avantages concrets</h3> <div class="imageblock"> <div class="content"> <img src="./images/vscode-local-vs-system.svg" alt="vscode local vs system" width="1749" height="5676"> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Avantage</th> <th class="tableblock halign-left valign-top">Détail</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Pas de sudo</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Tous les fichiers de l’IDE appartiennent à l’utilisateur</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Modification directe du CSS</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">On peut patcher <code>workbench.desktop.main.css</code> sans élévation de privilèges</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Script de mise à jour maison</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Un simple script shell télécharge, remplace et repatch automatiquement</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Isolation</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">L’installation système n’est pas polluée ; rollback = supprimer le dossier</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_customiser_la_police_du_menu_principal">Customiser la police du menu principal</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_le_constat">Le constat</h3> <div class="paragraph"> <p>La police par défaut du menu principal (File, Edit, View…​) et des dropdowns est trop petite. VS Code n’offre aucun paramètre pour la modifier.</p> </div> </div> <div class="sect2"> <h3 id="_la_technique_patch_css_direct">La technique : patch CSS direct</h3> <div class="paragraph"> <p>On ajoute du CSS à la fin du fichier <code>workbench.desktop.main.css</code> :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/menubar-patch-sequence.svg" alt="menubar patch sequence" width="675" height="599"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">CSS_FILE="$HOME/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css" cat >> "$CSS_FILE" << 'EOF' .menubar-menu-title{font-size:23px!important} .menubar>.menubar-menu-button{font-size:23px!important} .monaco-menu-option{font-size:22px!important;line-height:34px!important} .monaco-menu .action-label:not(.codicon){font-size:22px!important} .menubar-menu-items-holder .monaco-menu .action-item .action-label{font-size:22px!important} EOF</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_supprimer_lavertissement_dintégrité">Supprimer l’avertissement d’intégrité</h3> <div class="paragraph"> <p>VS Code détecte les modifications de ses fichiers et affiche un bandeau "Your installation is corrupt". Pour l’éviter, on supprime les checksums de <code>product.json</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">import json product_json = "$HOME/apps/VSCode-linux-x64/resources/app/product.json" with open(product_json, 'r') as f: data = json.load(f) data.pop('checksums', None) with open(product_json, 'w') as f: json.dump(data, f, indent=2)</code></pre> </div> </div> <div class="paragraph"> <p>Après redémarrage, plus de warning et les menus sont enfin lisibles.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_customiser_la_police_du_volet_explorer_le_combat">Customiser la police du volet Explorer — le combat</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_tentative_1_un_paramètre_qui_nexiste_pas">Tentative 1 : un paramètre qui n’existe pas</h3> <div class="paragraph"> <p>On tente d’abord le paramètre natif <code>workbench.tree.fontSize</code> dans <code>settings.json</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "workbench.tree.fontSize": 20 }</code></pre> </div> </div> <div class="paragraph"> <p>Résultat : <strong>aucun effet</strong>. Ce paramètre n’existe pas dans VS Code. La preuve que les paramètres non reconnus sont silencieusement ignorés.</p> </div> </div> <div class="sect2"> <h3 id="_tentative_2_lextension_custom_css_and_js_loader">Tentative 2 : l’extension Custom CSS and JS Loader</h3> <div class="paragraph"> <p>On installe l’extension <code>be5invis.vscode-custom-css</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">~/apps/VSCode-linux-x64/bin/code --install-extension be5invis.vscode-custom-css</code></pre> </div> </div> <div class="paragraph"> <p>On crée un fichier CSS dans <code>~/.vscode-custom-css/custom.css</code> avec des sélecteurs ciblant les éléments de l’explorateur :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.monaco-tree-rows .monaco-tree-row, .sidebar .monaco-list-row, .explorer-viewlet .monaco-list-row, .monaco-list-row .monaco-icon-label { font-size: 22px !important; line-height: 36px !important; }</code></pre> </div> </div> <div class="paragraph"> <p>Et on référence ce fichier dans les settings :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{ "vscode_custom_css.imports": [ "file:///home/user/.vscode-custom-css/custom.css" ] }</code></pre> </div> </div> <div class="paragraph"> <p>Résultat : <strong>les changements ne s’appliquent pas</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_le_piège_il_faut_activer_lextension_à_chaque_fois">Le piège : il faut activer l’extension à chaque fois</h3> <div class="paragraph"> <p>La documentation de l’extension est discrète sur ce point crucial : après chaque modification du CSS custom, il faut <strong>impérativement</strong> exécuter la commande depuis la palette :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><code>Ctrl+Shift+P</code> → taper <strong>"Enable Custom CSS and JS"</strong></p> </li> <li> <p>VS Code demande un redémarrage → accepter</p> </li> </ol> </div> <div class="paragraph"> <p>Sans cette étape, le CSS n’est jamais injecté dans l’IDE.</p> </div> </div> <div class="sect2"> <h3 id="_tentative_3_les_lignes_se_superposent">Tentative 3 : les lignes se superposent</h3> <div class="paragraph"> <p>Même avec <code>font-size: 22px</code> et <code>line-height: 36px</code>, les lettres à jambage (g, p, f, b) débordent sur les lignes voisines. On tente d’ajouter <code>height</code> et <code>min-height</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.monaco-list-row { height: 36px !important; min-height: 36px !important; }</code></pre> </div> </div> <div class="paragraph"> <p>Résultat : <strong>aucun changement</strong>. VS Code calcule les hauteurs de lignes en JavaScript et override les valeurs CSS.</p> </div> </div> <div class="sect2"> <h3 id="_la_solution_zoom_sur_le_conteneur_parent">La solution : <code>zoom</code> sur le conteneur parent</h3> <div class="imageblock"> <div class="content"> <img src="./images/explorer-css-approaches.svg" alt="explorer css approaches" width="1752" height="5700"> </div> </div> <div class="paragraph"> <p>Plutôt que de lutter contre le layout JavaScript, on utilise la propriété <code>zoom</code> sur le conteneur des lignes :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.explorer-viewlet .monaco-list-rows, .sidebar .monaco-list-rows { zoom: 1.25; }</code></pre> </div> </div> <div class="paragraph"> <p><code>zoom</code> agrandit uniformément le rendu du conteneur — texte ET espacement — sans casser le layout calculé par le moteur JavaScript de VS Code. Le facteur 1.25 correspond à peu près à un passage de 13px à 16px.</p> </div> <div class="paragraph"> <p>Résultat : <strong>les noms de fichiers sont enfin lisibles, les lignes correctement espacées</strong>.</p> </div> </div> <div class="sect2"> <h3 id="_récapitulatif_des_selectors_et_de_ce_qui_fonctionne">Récapitulatif des selectors et de ce qui fonctionne</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 50%;"> <col style="width: 25%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Approche</th> <th class="tableblock halign-left valign-top">CSS</th> <th class="tableblock halign-left valign-top">Résultat</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>font-size</code> sur <code>.monaco-list-row</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>font-size: 22px !important</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Texte plus grand mais lignes superposées</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>line-height</code> + <code>height</code> sur <code>.monaco-list-row</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>line-height: 36px; height: 36px</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Aucun effet (override JS)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>zoom</code> sur <code>.monaco-list-rows</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>zoom: 1.25</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Réussi — texte + espacement proportionnels</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_le_script_de_mise_à_jour_automatique">Le script de mise à jour automatique</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-update-sequence.svg" alt="vscode update sequence" width="1079" height="654"> </div> </div> <div class="sect2"> <h3 id="_le_problème">Le problème</h3> <div class="paragraph"> <p>Quand VS Code se met à jour, il remplace le dossier d’installation et <strong>efface tous les patches CSS</strong>. Il faut ré-appliquer les modifications manuellement à chaque fois.</p> </div> </div> <div class="sect2"> <h3 id="_le_script_vscode_update_sh">Le script <code>vscode-update.sh</code></h3> <div class="paragraph"> <p>On crée <code>~/apps/vscode-update.sh</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">#!/bin/bash set -e VSCODE_DIR="$HOME/apps/VSCode-linux-x64" BACKUP_DIR="$HOME/apps/vscode-backup" TEMP_DIR="/tmp/vscode-update" MENUBAR_FONT_SIZE="23px" DROPDOWN_FONT_SIZE="22px" echo "=== VS Code Local Updater ===" CURRENT_VERSION=$("$VSCODE_DIR/bin/code" --version 2>/dev/null | head -1) echo "Current version: $CURRENT_VERSION" echo "Downloading latest VS Code..." mkdir -p "$TEMP_DIR" wget -q "https://code.visualstudio.com/sha/download?build=stable&os=linux-x64" \ -O "$TEMP_DIR/vscode.tar.gz" echo "Extracting..." mkdir -p "$TEMP_DIR/extracted" tar -xzf "$TEMP_DIR/vscode.tar.gz" -C "$TEMP_DIR/extracted" NEW_VERSION=$("$TEMP_DIR/extracted/VSCode-linux-x64/bin/code" \ --version 2>/dev/null | head -1) echo "New version: $NEW_VERSION" if [ "$CURRENT_VERSION" = "$NEW_VERSION" ]; then echo "Already up to date!" rm -rf "$TEMP_DIR" exit 0 fi echo "Backing up current installation..." mkdir -p "$BACKUP_DIR" cp -r "$VSCODE_DIR" "$BACKUP_DIR/VSCode-linux-x64-$(date +%Y%m%d-%H%M%S)" echo "Updating..." rm -rf "$VSCODE_DIR" mv "$TEMP_DIR/extracted/VSCode-linux-x64" "$VSCODE_DIR" rm -rf "$TEMP_DIR" CSS_FILE="$VSCODE_DIR/resources/app/out/vs/workbench/workbench.desktop.main.css" echo "Re-applying custom CSS patch \ (menubar=${MENUBAR_FONT_SIZE}, dropdown=${DROPDOWN_FONT_SIZE})..." cat >> "$CSS_FILE" << CSSEOF .menubar-menu-title{font-size:${MENUBAR_FONT_SIZE}!important}\ .menubar>.menubar-menu-button{font-size:${MENUBAR_FONT_SIZE}!important}\ .monaco-menu-option{font-size:${DROPDOWN_FONT_SIZE}!important;\ line-height:34px!important}\ .monaco-menu .action-label:not(.codicon)\ {font-size:${DROPDOWN_FONT_SIZE}!important}\ .menubar-menu-items-holder .monaco-menu .action-item .action-label\ {font-size:${DROPDOWN_FONT_SIZE}!important} CSSEOF PRODUCT_JSON="$VSCODE_DIR/resources/app/product.json" if [ -f "$PRODUCT_JSON" ]; then echo "Removing checksums to prevent integrity warning..." python3 -c " import json with open('$PRODUCT_JSON','r') as f: data=json.load(f) data.pop('checksums', None) with open('$PRODUCT_JSON','w') as f: json.dump(data,f,indent=2) print('Done.') " fi echo "=== Update complete: $CURRENT_VERSION -> $NEW_VERSION ==="</code></pre> </div> </div> <div class="paragraph"> <p>Le script :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Télécharge la dernière version stable</p> </li> <li> <p>Vérifie si la version diffère de l’actuelle</p> </li> <li> <p>Sauvegarde l’installation courante (timestampée) dans <code>~/apps/vscode-backup/</code></p> </li> <li> <p>Remplace le dossier d’installation</p> </li> <li> <p><strong>Re-applique</strong> le patch CSS du menu principal</p> </li> <li> <p><strong>Supprime les checksums</strong> de <code>product.json</code> pour éviter le warning d’intégrité</p> </li> </ol> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> Les customisations du volet Explorer via l’extension Custom CSS et le fichier <code>~/.vscode-custom-css/custom.css</code> survivent aux mises à jour car elles vivent hors du dossier d’installation. </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_fichiers_impliqués_vue_densemble">Fichiers impliqués — vue d’ensemble</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-files-deployment.svg" alt="vscode files deployment" width="907" height="331"> </div> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 28.5714%;"> <col style="width: 42.8571%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Chemin</th> <th class="tableblock halign-left valign-top">Rôle</th> <th class="tableblock halign-left valign-top">Survit aux mises à jour ?</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Installation de l’IDE</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non (remplacée)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/resources/app/out/vs/workbench/workbench.desktop.main.css</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSS du workbench (menu, dropdowns)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non (re-patché par le script)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/VSCode-linux-x64/resources/app/product.json</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Checksums d’intégrité</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Non (re-nettoyé par le script)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/apps/vscode-update.sh</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Script de mise à jour automatique</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Oui</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/.config/Code/User/settings.json</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Paramètres utilisateur (fontSize, custom CSS)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Oui</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>~/.vscode-custom-css/custom.css</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">CSS custom pour l’Explorer (zoom)</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Oui</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_leçons_apprises">Leçons apprises</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/vscode-lessons-learned.svg" alt="vscode lessons learned" width="1116" height="532"> </div> </div> <div class="sect2"> <h3 id="_installer_dans_le_home_libère_tout">Installer dans le home libère tout</h3> <div class="paragraph"> <p>Une installation locale dans <code>~/apps</code> donne un contrôle total sur VS Code :</p> </div> <div class="ulist"> <ul> <li> <p>Pas de <code>sudo</code> pour modifier le CSS ou la configuration</p> </li> <li> <p>L’agent opencode+LLM peut écrire dans les fichiers de config et les assets de l’IDE</p> </li> <li> <p>Rollback trivial : restaurer le backup horodaté</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_zoom_font_size_pour_les_composants_list"><code>zoom</code> > <code>font-size</code> pour les composants list</h3> <div class="paragraph"> <p>VS Code contrôle la hauteur des lignes via JavaScript. Modifier <code>font-size</code> sans pouvoir toucher à la hauteur allouée par le moteur de layout donne des textes qui débordent. La propriété <code>zoom</code> sur le conteneur parent agrandit tout proportionnellement et contourne ce problème.</p> </div> </div> <div class="sect2"> <h3 id="_lextension_custom_css_nécessite_une_activation_explicite">L’extension Custom CSS nécessite une activation explicite</h3> <div class="paragraph"> <p>Ce n’est pas un paramètre "set and forget". Chaque modification du fichier CSS custom nécessite de re-exécuter "Enable Custom CSS and JS" depuis la palette de commandes (<code>Ctrl+Shift+P</code>).</p> </div> </div> <div class="sect2"> <h3 id="_un_script_de_mise_à_jour_est_indispensable">Un script de mise à jour est indispensable</h3> <div class="paragraph"> <p>Sans script, chaque mise à jour de VS Code efface les patches CSS du workbench. Le script <code>vscode-update.sh</code> automatise le téléchargement, le remplacement, le re-patch et le nettoyage des checksums.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_références_rapides">Références rapides</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Téléchargement VS Code : <a href="https://code.visualstudio.com/Download" class="bare">https://code.visualstudio.com/Download</a></p> </li> <li> <p>Extension Custom CSS and JS Loader : <code>be5invis.vscode-custom-css</code></p> </li> <li> <p>Issue VS Code demandant un paramètre natif pour la police de l’Explorer : <a href="https://github.com/microsoft/vscode/issues/149">github.com/microsoft/vscode#149</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2026/0102_migration_gradle_script_to_plugin_post.html Thu, 16 Apr 2026 00:00:00 +0000 blog/2026/0102_migration_gradle_script_to_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_contexte_et_objectif">Contexte et objectif</a> <ul class="sectlevel2"> <li><a href="#_le_point_de_départ">Le point de départ</a></li> <li><a href="#_lobjectif">L’objectif</a></li> </ul> </li> <li><a href="#_le_premier_obstacle_ruby_gems">Le premier obstacle : <code>ruby { gems() }</code></a> <ul class="sectlevel2"> <li><a href="#_ce_que_cache_le_sucre_syntaxique_groovy">Ce que cache le sucre syntaxique Groovy</a></li> <li><a href="#_décomposition_du_mécanisme">Décomposition du mécanisme</a></li> </ul> </li> <li><a href="#_la_solution_en_trois_parties">La solution en trois parties</a> <ul class="sectlevel2"> <li><a href="#_partie_1_le_repo_ivy_pour_rubygems">Partie 1 : le repo Ivy pour rubygems</a></li> <li><a href="#_partie_2_la_dépendance_asciidoctorgems">Partie 2 : la dépendance asciidoctorGems</a></li> <li><a href="#_partie_3_settings_gradle_kts">Partie 3 : settings.gradle.kts</a></li> </ul> </li> <li><a href="#_introspection_de_lapi_par_bytecodes">Introspection de l’API par bytecodes</a> <ul class="sectlevel2"> <li><a href="#_pourquoi_javap">Pourquoi <code>javap</code> ?</a></li> <li><a href="#_hiérarchie_de_la_tâche">Hiérarchie de la tâche</a></li> <li><a href="#_découverte_de_forkoptions">Découverte de <code>forkOptions</code></a></li> <li><a href="#_lapi_de_javaforkoptions_grolifant">L’API de JavaForkOptions (grolifant)</a></li> <li><a href="#_revealjsextension">RevealJSExtension</a></li> </ul> </li> <li><a href="#_configuration_du_toolchain_java">Configuration du toolchain Java</a> <ul class="sectlevel2"> <li><a href="#_le_problème_de_javatoolchainservice">Le problème de JavaToolchainService</a></li> </ul> </li> <li><a href="#_détection_automatique_docker">Détection automatique Docker</a> <ul class="sectlevel2"> <li><a href="#_contexte">Contexte</a></li> <li><a href="#_stratégie">Stratégie</a></li> </ul> </li> <li><a href="#_résultat_final">Résultat final</a> <ul class="sectlevel2"> <li><a href="#_le_buildscript_consommateur">Le buildscript consommateur</a></li> <li><a href="#_settings_gradle_kts">settings.gradle.kts</a></li> </ul> </li> <li><a href="#_récapitulatif_des_pièges_et_solutions">Récapitulatif des pièges et solutions</a></li> <li><a href="#_méthode_dinvestigation_lire_une_api_inconnue_avec_javap">Méthode d’investigation : lire une API inconnue avec javap</a> <ul class="sectlevel2"> <li><a href="#_principe">Principe</a></li> <li><a href="#_étape_1_localiser_le_jar_dans_le_cache_gradle">Étape 1 : localiser le jar dans le cache Gradle</a></li> <li><a href="#_étape_2_lister_les_classes_du_jar">Étape 2 : lister les classes du jar</a></li> <li><a href="#_étape_3_inspecter_une_classe">Étape 3 : inspecter une classe</a></li> <li><a href="#_étape_4_remonter_la_hiérarchie">Étape 4 : remonter la hiérarchie</a></li> <li><a href="#_étape_5_suivre_les_types_inconnus">Étape 5 : suivre les types inconnus</a></li> <li><a href="#_étape_6_vérifier_les_extensions_de_projet">Étape 6 : vérifier les extensions de projet</a></li> <li><a href="#_récapitulatif_de_la_méthode">Récapitulatif de la méthode</a></li> </ul> </li> <li><a href="#_prochaine_étape">Prochaine étape</a></li> </ul> </div> <div class="sect1"> <h2 id="_contexte_et_objectif">Contexte et objectif</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_le_point_de_départ">Le point de départ</h3> <div class="paragraph"> <p>Le projet <code>slider-gradle</code> génère des présentations Reveal.js à partir de fichiers AsciiDoc via le plugin Gradle <code>org.asciidoctor.jvm.revealjs</code>. La configuration de la tâche principale <code>asciidoctorRevealJs</code> vivait directement dans le buildscript racine <code>build.gradle.kts</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { id("org.asciidoctor.jvm.revealjs") } apply<slides.SlidesPlugin>() project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { repositories { ruby { gems() } } revealjs { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } revealjsOptions { // ... configuration complète } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_lobjectif">L’objectif</h3> <div class="paragraph"> <p>Déplacer toute cette configuration dans <code>buildSrc/src/main/kotlin/slides/SlidesPlugin.kt</code> pour que le buildscript consommateur se réduise à :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">apply<slides.SlidesPlugin>()</code></pre> </div> </div> <div class="paragraph"> <p>Le plugin doit être totalement autonome : il applique lui-même ses dépendances de plugins, configure ses repos, et gère ses gems Ruby.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_le_premier_obstacle_ruby_gems">Le premier obstacle : <code>ruby { gems() }</code></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ce_que_cache_le_sucre_syntaxique_groovy">Ce que cache le sucre syntaxique Groovy</h3> <div class="paragraph"> <p>La ligne <code>repositories { ruby { gems() } }</code> est une extension DSL Groovy disponible uniquement dans le contexte d’exécution du buildscript. Elle n’existe pas en tant qu’API Kotlin statique accessible depuis buildSrc.</p> </div> <div class="paragraph"> <p>En tentant de l’appeler depuis <code>SlidesPlugin.kt</code>, la compilation échoue immédiatement.</p> </div> </div> <div class="sect2"> <h3 id="_décomposition_du_mécanisme">Décomposition du mécanisme</h3> <div class="paragraph"> <p>Après analyse du cache Gradle (<code>~/.gradle/caches/modules-2/files-2.1/rubygems/</code>), on découvre dans le fichier <code>ivy-3.1.0.xml</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><artifact type='gem' url='https://rubygems.org/gems/asciidoctor-revealjs-3.1.0.gem' /></code></pre> </div> </div> <div class="paragraph"> <p><code>ruby { gems() }</code> effectuait en réalité <strong>trois opérations distinctes</strong> :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>Enregistrer un repo Ivy pointant vers <code><a href="https://rubygems.org/gems/" class="bare">https://rubygems.org/gems/</a></code></p> </li> <li> <p>Exclure le groupe <code>rubygems</code> des repos Maven pour éviter les conflits</p> </li> <li> <p>Enregistrer la gem dans la configuration <code>asciidoctorGems</code> pour que JRuby la charge au runtime</p> </li> </ol> </div> <div class="paragraph"> <p>Ces trois responsabilités doivent être reproduites séparément en Kotlin.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_la_solution_en_trois_parties">La solution en trois parties</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_partie_1_le_repo_ivy_pour_rubygems">Partie 1 : le repo Ivy pour rubygems</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } <i class="conum" data-value="1"></i><b>(1)</b> metadataSources { artifact() } content { includeGroup("rubygems") } }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>L’extension <code>.gem</code> doit être hardcodée. <code>[ext]</code> résout par défaut en <code>.jar</code>, ce qui provoque une erreur <code>Resource missing</code>.</td> </tr> </table> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> Le repo Ivy est déclaré directement sur <code>project.repositories</code> et non dans un bloc <code>repositories { }</code> car le receiver de ce bloc n’est pas le <code>RepositoryHandler</code> standard de Gradle mais une API grolifant incompatible avec l’extension <code>ivy</code> Kotlin DSL. </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_partie_2_la_dépendance_asciidoctorgems">Partie 2 : la dépendance asciidoctorGems</h3> <div class="paragraph"> <p>Le plugin <code>org.asciidoctor.jvm.gems</code> doit être appliqué en premier — il crée la configuration <code>asciidoctorGems</code> et la tâche <code>asciidoctorGemsPrepare</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.plugins.apply("org.asciidoctor.jvm.gems") project.plugins.apply("org.asciidoctor.jvm.revealjs") <i class="conum" data-value="1"></i><b>(1)</b> project.dependencies { add("asciidoctorGems", "rubygems:asciidoctor-revealjs:3.1.0@gem") <i class="conum" data-value="2"></i><b>(2)</b> }</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>L’ordre d’application est important : <code>gems</code> avant <code>revealjs</code>. <2> Le qualificateur <code>@gem</code> force l’extension correcte sur la dépendance.</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_partie_3_settings_gradle_kts">Partie 3 : settings.gradle.kts</h3> <div class="paragraph"> <p><code>dependencyResolutionManagement</code> dans <code>settings.gradle.kts</code> doit autoriser les projets à déclarer leurs propres repos :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) }</code></pre> </div> </div> <div class="paragraph"> <p>Sans cette ligne, Gradle ignore les repos déclarés dans le plugin et la résolution des gems échoue.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_introspection_de_lapi_par_bytecodes">Introspection de l’API par bytecodes</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_pourquoi_javap">Pourquoi <code>javap</code> ?</h3> <div class="paragraph"> <p>Le plugin <code>asciidoctor-gradle-jvm-slides</code> est en version <code>4.0.0-alpha.1</code>. Sa documentation est inexistante ou incomplète. La seule source fiable est l’inspection directe des classes compilées.</p> </div> </div> <div class="sect2"> <h3 id="_hiérarchie_de_la_tâche">Hiérarchie de la tâche</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask</code></pre> </div> </div> <div class="paragraph"> <p>Résultat :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask implements org.asciidoctor.gradle.base.slides.SlidesToExportAware</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_découverte_de_forkoptions">Découverte de <code>forkOptions</code></h3> <div class="paragraph"> <p>En inspectant <code>AbstractAsciidoctorTask</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm"</code></pre> </div> </div> <div class="paragraph"> <p>On trouve :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">final org.ysb33r.grolifant.api.v4.JavaForkOptions javaForkOptions; public void forkOptions(org.gradle.api.Action<org.ysb33r.grolifant.api.v4.JavaForkOptions>); public static final org.asciidoctor.gradle.base.process.ProcessMode JAVA_EXEC;</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_lapi_de_javaforkoptions_grolifant">L’API de JavaForkOptions (grolifant)</h3> <div class="paragraph"> <p><code>javaLauncher</code> n’existe pas sur cette tâche. L’API réelle de <code>org.ysb33r.grolifant.api.v4.JavaForkOptions</code> expose :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public void executable(java.lang.Object); <i class="conum" data-value="1"></i><b>(1)</b> public void setExecutable(java.lang.Object);</code></pre> </div> </div> <div class="colist arabic"> <table> <tr> <td><i class="conum" data-value="1"></i><b>1</b></td> <td>La méthode <code>executable(Object)</code> remplace l’assignation <code>executable = …​</code> qui ne compile pas (<code>val</code> cannot be reassigned).</td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_revealjsextension">RevealJSExtension</h3> <div class="paragraph"> <p><code>revealjs { }</code> n’est pas une méthode de la tâche mais une <strong>extension de projet</strong> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension</code></pre> </div> </div> <div class="paragraph"> <p>Elle s’accède via :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_configuration_du_toolchain_java">Configuration du toolchain Java</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_le_problème_de_javatoolchainservice">Le problème de JavaToolchainService</h3> <div class="paragraph"> <p><code>JavaToolchainService</code> n’est pas une extension de projet. L’appel suivant échoue :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ERREUR : Extension of type 'JavaToolchainService' does not exist project.extensions.getByType<JavaToolchainService>()</code></pre> </div> </div> <div class="paragraph"> <p>La bonne API est <code>serviceOf</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.gradle.kotlin.dsl.support.serviceOf project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_détection_automatique_docker">Détection automatique Docker</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_contexte">Contexte</h3> <div class="paragraph"> <p>Le plugin Asciidoctor/JRuby requiert Java 17. Kotlin 2.0.x dans buildSrc ne supporte pas Java 25 (le parser de version crashe sur <code>"25.0.2"</code>). Le daemon Gradle doit donc tourner sur Java 17 ou Docker doit être utilisé.</p> </div> </div> <div class="sect2"> <h3 id="_stratégie">Stratégie</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>Docker disponible → exécution via container <code>eclipse-temurin:17</code> (comportement par défaut)</p> </li> <li> <p>Docker absent + Java 17 → exécution locale</p> </li> <li> <p>Docker absent + Java > 17 → erreur explicite</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val isDockerAvailable = try { Runtime.getRuntime().exec(arrayOf("docker", "info")).waitFor() == 0 } catch (e: Exception) { false } val javaVersion = JavaVersion.current().majorVersion.toInt() when { isDockerAvailable -> project.tasks.register<Exec>(TASK_ASCIIDOCTOR_REVEALJS) { group = GROUP_TASK_SLIDER description = "Slider settings and generation (via Docker)" dependsOn(TASK_CLEAN_SLIDES_BUILD) finalizedBy(TASK_DASHBOARD_SLIDES_BUILD) commandLine( "docker", "run", "--rm", "-v", "${project.rootDir.absolutePath}:/workspace", "-v", "${System.getProperty("user.home")}/.gradle:/root/.gradle", "-w", "/workspace", "eclipse-temurin:17", "./gradlew", TASK_ASCIIDOCTOR_REVEALJS ) workingDir = project.rootDir } javaVersion == 17 -> { project.repositories.mavenCentral() { content { excludeGroup("rubygems") } } project.repositories.ivy { url = project.uri("https://rubygems.org/gems/") patternLayout { artifact("[module]-[revision].gem") } metadataSources { artifact() } content { includeGroup("rubygems") } } project.extensions.getByType<RevealJSExtension>().apply { version = "3.1.0" templateGitHub { setOrganisation("hakimel") setRepository("reveal.js") setTag("3.9.1") } } project.tasks.getByName<AsciidoctorJRevealJSTask>(TASK_ASCIIDOCTOR_REVEALJS) { setInProcess("JAVA_EXEC") forkOptions { executable( project.serviceOf<JavaToolchainService>() .launcherFor { languageVersion.set(JavaLanguageVersion.of(17)) vendor.set(JvmVendorSpec.ADOPTIUM) } .get() .executablePath .asFile .absolutePath ) } // ... reste de la configuration } } else -> error( "Docker est requis pour exécuter $TASK_ASCIIDOCTOR_REVEALJS " + "avec Java $javaVersion. Installez Docker ou utilisez Java 17." ) }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_résultat_final">Résultat final</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_le_buildscript_consommateur">Le buildscript consommateur</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">apply<slides.SlidesPlugin>()</code></pre> </div> </div> <div class="paragraph"> <p>C’est tout. Le plugin porte l’intégralité de la responsabilité.</p> </div> </div> <div class="sect2"> <h3 id="_settings_gradle_kts">settings.gradle.kts</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">pluginManagement { repositories { mavenLocal() gradlePluginPortal() } } plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0" } @Suppress("UnstableApiUsage") dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_PROJECT) } rootProject.name = "slider-gradle"</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_récapitulatif_des_pièges_et_solutions">Récapitulatif des pièges et solutions</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 37.5%;"> <col style="width: 37.5%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Problème</th> <th class="tableblock halign-left valign-top">Cause</th> <th class="tableblock halign-left valign-top">Solution</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ruby { gems() }</code> non disponible en Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extension DSL Groovy uniquement</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Trois mécanismes séparés : repo Ivy + exclusion Maven + <code>asciidoctorGems</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Gradle cherche un <code>.jar</code> au lieu d’un <code>.gem</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>[ext]</code> résout en <code>jar</code> par défaut</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Hardcoder <code>.gem</code> dans le pattern Ivy + qualificateur <code>@gem</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ivy { }</code> ne compile pas dans <code>repositories { }</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Receiver grolifant incompatible avec le DSL Kotlin</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Appel direct <code>project.repositories.ivy { }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>javaLauncher</code> non résolu</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Propriété inexistante sur <code>AsciidoctorJRevealJSTask</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>setInProcess("JAVA_EXEC")</code> + <code>forkOptions { executable(…​) }</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>executable = …​</code> ne compile pas</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Propriété <code>val</code> dans <code>JavaForkOptions</code> grolifant</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Méthode <code>executable(Object)</code> à la place</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>JavaToolchainService</code> introuvable via <code>extensions</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">C’est un service Gradle, pas une extension</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project.serviceOf<JavaToolchainService>()</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>revealjs { }</code> non résolu dans la tâche</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Extension de projet, pas méthode de tâche</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>project.extensions.getByType<RevealJSExtension>()</code></p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Build crashe avec Java 25</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Kotlin 2.0.x ne parse pas les versions Java à deux chiffres</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Détection Docker automatique + fallback Java 17</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_méthode_dinvestigation_lire_une_api_inconnue_avec_javap">Méthode d’investigation : lire une API inconnue avec javap</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principe">Principe</h3> <div class="paragraph"> <p>Quand la documentation est absente ou incomplète, les bytecodes sont la source de vérité. <code>javap</code> est l’outil standard du JDK qui décompile les fichiers <code>.class</code> en signatures Java lisibles, sans nécessiter le code source.</p> </div> </div> <div class="sect2"> <h3 id="_étape_1_localiser_le_jar_dans_le_cache_gradle">Étape 1 : localiser le jar dans le cache Gradle</h3> <div class="paragraph"> <p>Gradle télécharge toutes ses dépendances dans <code>~/.gradle/caches/modules-2/files-2.1/</code>. La première étape est de trouver le jar qui contient la classe à inspecter :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "asciidoctor-gradle-jvm-slides*.jar" 2>/dev/null</code></pre> </div> </div> <div class="listingblock"> <div class="title">Résultat :</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">/home/user/.gradle/caches/modules-2/files-2.1/org.asciidoctor/ asciidoctor-gradle-jvm-slides/4.0.0-alpha.1/.../ asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_étape_2_lister_les_classes_du_jar">Étape 2 : lister les classes du jar</h3> <div class="paragraph"> <p>Avant d’inspecter une classe, on vérifie qu’elle existe bien dans le jar :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">jar tf asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar | grep -i "RevealJS\|revealjs"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_étape_3_inspecter_une_classe">Étape 3 : inspecter une classe</h3> <div class="listingblock"> <div class="title">Cela révèle toutes les classes disponibles : <code>AsciidoctorJRevealJSTask</code>, <code>RevealJSExtension</code>, <code>RevealJSOptions</code>, etc.</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.AsciidoctorJRevealJSTask</code></pre> </div> </div> <div class="paragraph"> <p>L’option <code>-p</code> affiche tous les membres y compris les privés. Le résultat montre immédiatement la ligne clé :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class AsciidoctorJRevealJSTask extends org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_étape_4_remonter_la_hiérarchie">Étape 4 : remonter la hiérarchie</h3> <div class="paragraph"> <p>La tâche étend <code>AbstractAsciidoctorTask</code>. On l’inspecte à son tour en localisant d’abord son jar :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "asciidoctor-gradle-jvm-[0-9]*.jar" 2>/dev/null javap -p -classpath asciidoctor-gradle-jvm-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.AbstractAsciidoctorTask | grep -i "fork\|exec\|jvm\|java"</code></pre> </div> </div> <div class="paragraph"> <p>C’est là qu’on découvre <code>forkOptions</code>, <code>JAVA_EXEC</code>, et <code>javaForkOptions</code> de type <code>org.ysb33r.grolifant.api.v4.JavaForkOptions</code>.</p> </div> </div> <div class="sect2"> <h3 id="_étape_5_suivre_les_types_inconnus">Étape 5 : suivre les types inconnus</h3> <div class="paragraph"> <p><code>JavaForkOptions</code> est une classe grolifant inconnue. On localise son jar :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">find ~/.gradle/caches -name "grolifant*.jar" 2>/dev/null</code></pre> </div> </div> <div class="paragraph"> <p>Puis on l’inspecte :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath grolifant40-legacy-api-2.0.0-alpha.6.jar \ org.ysb33r.grolifant.api.v4.JavaForkOptions</code></pre> </div> </div> <div class="paragraph"> <p>On y trouve <code>executable(java.lang.Object)</code> — la méthode correcte à appeler, par opposition à <code>executable = …​</code> qui ne compile pas car c&amp;#8217;est une propriété <code>val</code>.</p> </div> </div> <div class="sect2"> <h3 id="_étape_6_vérifier_les_extensions_de_projet">Étape 6 : vérifier les extensions de projet</h3> <div class="paragraph"> <p>Pour <code>revealjs { }</code>, la question était : est-ce une méthode de la tâche ou une extension de projet ? L’inspection de <code>AsciidoctorJRevealJSTask</code> ne montre aucune méthode <code>revealjs</code>. On inspecte alors <code>RevealJSExtension</code> :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">javap -p -classpath asciidoctor-gradle-jvm-slides-4.0.0-alpha.1.jar \ org.asciidoctor.gradle.jvm.slides.RevealJSExtension | head -5</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">public class RevealJSExtension implements groovy.lang.GroovyObject { public static final java.lang.String NAME;</code></pre> </div> </div> <div class="paragraph"> <p>La présence de <code>NAME</code> confirme que c’est une extension enregistrée sur le projet, accessible via <code>project.extensions.getByType<RevealJSExtension>()</code>.</p> </div> </div> <div class="sect2"> <h3 id="_récapitulatif_de_la_méthode">Récapitulatif de la méthode</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">Étape</th> <th class="tableblock halign-left valign-top">Action</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>find ~/.gradle/caches -name "*.jar"</code> — localiser le jar</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>jar tf jar.jar | grep NomClasse</code> — vérifier que la classe existe</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>javap -p -classpath jar.jar NomCompletClasse</code> — inspecter la classe</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Identifier <code>extends</code> et remonter la hiérarchie</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Suivre les types inconnus dans leurs propres jars</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Chercher <code>NAME</code> pour identifier une extension de projet</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>Cette méthode s’applique à n’importe quel plugin Gradle dont l’API n’est pas documentée ou dont la version alpha ne correspond plus à la documentation existante.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_prochaine_étape">Prochaine étape</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ce plugin buildSrc sera extrait dans un projet indépendant publié sur Gradle Plugin Portal ou Maven Local. Le buildscript consommateur deviendra alors :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">plugins { id("slides") version "1.0.0" }</code></pre> </div> </div> <div class="paragraph"> <p>Et <code>settings.gradle.kts</code> sera réduit à son strict minimum sans référence à <code>foojay-resolver-convention</code>, le provisioning JDK étant géré par le plugin lui-même ou documenté comme prérequis.</p> </div> </div> </div> https://cheroliv.com/blog/2026/0101_jbake_portfolio_post.html Thu, 15 Jan 2026 00:00:00 +0000 blog/2026/0101_jbake_portfolio_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_建筑愿景">建筑愿景</a> <ul class="sectlevel2"> <li><a href="#_指导原则">指导原则</a></li> <li><a href="#_战略选择asciidoc_用于投资组合">战略选择：AsciiDoc 用于投资组合</a></li> <li><a href="#_数据模型">数据模型</a></li> </ul> </li> <li><a href="#_详细用例">详细用例</a> <ul class="sectlevel2"> <li><a href="#_uc1_添加一个元素到投资组合">UC1 : 添加一个元素到投资组合</a> <ul class="sectlevel3"> <li><a href="#_额定通量">额定通量</a></li> <li><a href="#_要创建的文件模板">要创建的文件模板</a></li> <li><a href="#_验证点">验证点</a></li> </ul> </li> <li><a href="#_uc2_删除投资组合中的一项">UC2 : 删除投资组合中的一项</a> <ul class="sectlevel3"> <li><a href="#_标称通量">标称通量</a></li> <li><a href="#_替代策略归档">替代策略：归档</a></li> <li><a href="#_资源清理">资源清理</a></li> </ul> </li> <li><a href="#_uc3_设置为未发布草稿">UC3 : 设置为未发布（草稿）</a> <ul class="sectlevel3"> <li><a href="#_额定通量_2">�额定通量</a></li> <li><a href="#_可能的状态">可能的状态</a></li> <li><a href="#_典型用例">典型用例</a></li> </ul> </li> </ul> </li> <li><a href="#_模板化架构">模板化架构</a> <ul class="sectlevel2"> <li><a href="#_可重用模板的策略">可重用模板的策略</a></li> <li><a href="#_数据提取模式">数据提取模式</a></li> <li><a href="#_命名约定">命名约定</a></li> </ul> </li> <li><a href="#_发布工作流">发布工作流</a> <ul class="sectlevel2"> <li><a href="#_开发流水线">开发流水线</a></li> <li><a href="#_环境">环境</a></li> </ul> </li> <li><a href="#_可扩展性">可扩展性</a> <ul class="sectlevel2"> <li><a href="#_添加新属性">添加新属性</a></li> <li><a href="#_高级分类">高级分类</a></li> </ul> </li> <li><a href="#_最佳实践">最佳实践</a> <ul class="sectlevel2"> <li><a href="#_文件组织">文件组织</a></li> <li><a href="#_内容管理">内容管理</a></li> <li><a href="#_性能">性能</a></li> </ul> </li> <li><a href="#_结论">结论</a></li> </ul> </div> <div class="sect1"> <h2 id="_建筑愿景">建筑愿景</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_指导原则">指导原则</h3> <div class="paragraph"> <p>架构基于*关注点分离*的原则：</p> </div> <div class="ulist"> <ul> <li> <p><strong>内容</strong> : 结构丰富的 AsciiDoc 文件，带有丰富的元数据</p> </li> <li> <p><strong>Presentation</strong> : 可重用的 Thymeleaf 模板</p> </li> <li> <p><strong>数据</strong> : 由 JBake 自动从 AsciiDoc 属性提取的模型</p> </li> <li> <p><strong>样式</strong> : Bootstrap 5 用于视觉一致性</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_战略选择asciidoc_用于投资组合">战略选择：AsciiDoc 用于投资组合</h3> <div class="paragraph"> <p>为什么 AsciiDoc ?</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 33.3333%;"> <col style="width: 66.6667%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">标准</th> <th class="tableblock halign-left valign-top">�优势</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">一致性</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">与博客文章相同的格式</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">元数据</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">结构化和可扩展的属性 (<code>project-*</code>)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">可维护性</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">简单文本编辑，可由 Git 版本控制</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">灵活性</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">可以包含丰富内容 (表格, 代码, 图片)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">模板</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JBake 自动提取 Thymeleaf 的属性</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_数据模型">数据模型</h3> <div class="paragraph"> <p>每个投资组合项目都是一个 AsciiDoc 文档，包含：</p> </div> <div class="ulist"> <ul> <li> <p><strong>表头元数据</strong> : 结构化信息（客户、时长、技术等）</p> </li> <li> <p><strong>文档正文</strong> : 叙事描述, 挑战, 解决方案, 结果</p> </li> <li> <p><strong>自定义属性</strong> : 前缀`project-*`用于自动提取</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-d74c4aad2d92cfd4f5322e199ef63730.png" alt="Diagram" width="386" height="811"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_详细用例">详细用例</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_uc1_添加一个元素到投资组合">UC1 : 添加一个元素到投资组合</h3> <div class="sect3"> <h4 id="_额定通量">额定通量</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "编辑器 ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "编辑器 文本" as editor participant "文件\nAsciiDoc" as file participant "JBake 引擎" as jbake participant "站点 静态" as site dev -> editor : Créer nouveau fichier activate editor editor -> file : portfolio/nouveau-projet.adoc activate file dev -> editor : Rédiger en-tête avec métadonnées\n(titre, type=project, status=published,\nattributs project-*) dev -> editor : Rédiger contenu narratif\n(contexte, défis, solutions) dev -> editor : Ajouter images dans assets/img/portfolio/ editor -> file : Sauvegarder deactivate editor dev -> jbake : Lancer build (jbake -b) activate jbake jbake -> file : Lire et parser jbake -> jbake : Extraire métadonnées jbake -> jbake : Convertir AsciiDoc → HTML jbake -> jbake : Appliquer template project.html jbake -> jbake : Ajouter à la liste portfolio.html jbake -> site : Générer pages statiques deactivate jbake dev -> site : Vérifier résultat activate site site --> dev : Afficher projet deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_要创建的文件模板">要创建的文件模板</h4> <div class="paragraph"> <p>开发者创建`content/portfolio/nom-projet.adoc`具有标准化的结构：</p> </div> <div class="ulist"> <ul> <li> <p>包含所有必需属性的标题</p> </li> <li> <p>标准化部分（背景、挑战、解决方案、结果）</p> </li> <li> <p>图像的一致命名</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_验证点">验证点</h4> <div class="ulist"> <ul> <li> <p>必需的属性已存在 (<code>jbake-type</code>, <code>jbake-status</code>, <code>project-thumbnail</code>)</p> </li> <li> <p>引用的图像存在于`assets/img/portfolio/`</p> </li> <li> <p>JBake 构建成功，无错误</p> </li> <li> <p>项目出现在作品集页面上</p> </li> <li> <p>单个项目页面显示正常</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc2_删除投资组合中的一项">UC2 : 删除投资组合中的一项</h3> <div class="sect3"> <h4 id="_标称通量">标称通量</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "系统 ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "系统 文件" as fs participant "JBake 引擎" as jbake participant "网站\n静态" as site database "缓存 JBake" as cache dev -> fs : Supprimer portfolio/projet-ancien.adoc activate fs fs --> dev : Fichier supprimé deactivate fs dev -> fs : (Optionnel) Supprimer images associées\nassets/img/portfolio/projet-ancien-* activate fs fs --> dev : Images supprimées deactivate fs dev -> cache : Nettoyer cache JBake activate cache cache --> dev : Cache vidé deactivate cache dev -> jbake : Rebuild complet (jbake -b) activate jbake jbake -> jbake : Scanner content/portfolio/ jbake -> jbake : Projet absent → non généré jbake -> jbake : Régénérer portfolio.html\n(sans le projet supprimé) jbake -> site : Déployer nouveau build deactivate jbake dev -> site : Vérifier activate site site --> dev : Projet absent de la liste deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_替代策略归档">替代策略：归档</h4> <div class="paragraph"> <p>而不是永久删除，可以创建一个文件夹`content/portfolio/archive/`:</p> </div> <div class="ulist"> <ul> <li> <p>移动文件而不是删除它</p> </li> <li> <p>可以轻松恢复</p> </li> <li> <p>保持 Git 历史更清晰</p> </li> </ul> </div> </div> <div class="sect3"> <h4 id="_资源清理">资源清理</h4> <div class="ulist"> <ul> <li> <p>检查孤立的图像在`assets/img/portfolio/`</p> </li> <li> <p>删除未被其他项目引用的图片</p> </li> <li> <p>清理 JBake 缓存以避免幽灵引用</p> </li> </ul> </div> </div> </div> <div class="sect2"> <h3 id="_uc3_设置为未发布草稿">UC3 : 设置为未发布（草稿）</h3> <div class="sect3"> <h4 id="_额定通量_2">�额定通量</h4> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "文件 ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "文件 AsciiDoc" as file participant "JBake 引擎" as jbake participant "静态网站" as site dev -> file : Ouvrir portfolio/projet.adoc activate file dev -> file : Modifier attribut\n:jbake-status: published\n↓\n:jbake-status: draft file --> dev : Sauvegardé deactivate file dev -> jbake : Rebuild (jbake -b) activate jbake jbake -> file : Parser le fichier jbake -> jbake : Détecter status=draft jbake -> jbake : Exclure de published_projects jbake -> jbake : Ne pas créer page publique note right Le projet existe toujours mais n'est pas publié end note jbake -> site : Générer site (sans ce projet) deactivate jbake dev -> site : Vérifier portfolio activate site site --> dev : Projet absent de la liste publique deactivate site @enduml</pre> </div> </div> </div> <div class="sect3"> <h4 id="_可能的状态">可能的状态</h4> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-a4b71e9dbf30083d131223257db47469.png" alt="Diagram" width="556" height="448"> </div> </div> </div> <div class="sect3"> <h4 id="_典型用例">典型用例</h4> <div class="ulist"> <ul> <li> <p><strong>项目正在起草中</strong> : 创建草稿，准备好后发布</p> </li> <li> <p><strong>临时保密项目</strong>：切换到草稿，等待客户确认</p> </li> <li> <p><strong>重大更新</strong>：切换到草稿，编辑，重新发布</p> </li> <li> <p><strong>A/B testing</strong> : 在草稿中复制，测试，发布最佳版本</p> </li> </ul> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_模板化架构">模板化架构</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_可重用模板的策略">可重用模板的策略</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-879867fbcc3f82d2e437e9baade0b45d.png" alt="Diagram" width="881" height="350"> </div> </div> </div> <div class="sect2"> <h3 id="_数据提取模式">数据提取模式</h3> <div class="paragraph"> <p>JBake 会自动将 AsciiDoc 属性转换为在 Thymeleaf 中可访问的属性：</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-73c69c8076027bd802fd166ce969691f.png" alt="Diagram" width="879" height="344"> </div> </div> </div> <div class="sect2"> <h3 id="_命名约定">命名约定</h3> <div class="ulist"> <ul> <li> <p><strong>项目属性</strong> : 前缀`project-*` (ex: <code>project-client</code>, <code>project-tech-stack</code>)</p> </li> <li> <p><strong>文件</strong> : kebab-case (例如:`ecommerce-platform.adoc`)</p> </li> <li> <p><strong>图片</strong> : 前缀 项目名称 (例如:`ecommerce-platform-thumb.jpg`)</p> </li> <li> <p><strong>模板</strong> : 功能名称 (例如：<code>project-card.html</code>, <code>tech-badge.html</code>)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_发布工作流">发布工作流</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_开发流水线">开发流水线</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-20cdbe2dae05213f5637f61ba401a659.png" alt="Diagram" width="386" height="811"> </div> </div> </div> <div class="sect2"> <h3 id="_环境">环境</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 20%;"> <col style="width: 40%;"> <col style="width: 40%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">环境</th> <th class="tableblock halign-left valign-top">用法</th> <th class="tableblock halign-left valign-top">已接受状态</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">本地</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">开发和预览</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">草稿，已发布</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">布置</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�预生产验证</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">仅发布</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">生产</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">公开网站</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">仅发布</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_可扩展性">可扩展性</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_添加新属性">添加新属性</h3> <div class="paragraph"> <p>为丰富数据模型，只需添加带前缀的新属性`project-*`：</p> </div> <div class="ulist"> <ul> <li> <p>`project-awards`奖项与表彰</p> </li> <li> <p>`project-testimonial`客户引用</p> </li> <li> <p><code>project-team-size</code>: 团队规模</p> </li> <li> <p><code>project-budget-range</code>�预算范围</p> </li> </ul> </div> <div class="paragraph"> <p>这些属性会在模板中自动可用，无需修改JBake引擎。</p> </div> </div> <div class="sect2"> <h3 id="_高级分类">高级分类</h3> <div class="imageblock"> <div class="content"> <img src="./images/diag-plantuml-md5-b0f6553dc639769d6228d6e9482aa7fc.png" alt="Diagram" width="561" height="259"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_最佳实践">最佳实践</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_文件组织">文件组织</h3> <div class="ulist"> <ul> <li> <p><strong>一个文件 = 一个项目</strong> : 避免混合多个项目</p> </li> <li> <p><strong>专用文件夹中的图像</strong><code>assets/img/portfolio/nom-projet/</code></p> </li> <li> <p><strong>一致的命名</strong> : 便于查找和维护</p> </li> <li> <p><strong>Versioning Git</strong> : 完全追踪修改</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_内容管理">内容管理</h3> <div class="ulist"> <ul> <li> <p><strong>默认草稿状态</strong> : 仅在准备好时发布</p> </li> <li> <p><strong>发布前评审</strong> : 质量和保密性验证</p> </li> <li> <p><strong>完整元数据</strong>：填写所有相关字段</p> </li> <li> <p><strong>丰富的叙事内容</strong> : 不要仅限于元数据</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_性能">性能</h3> <div class="ulist"> <ul> <li> <p><strong>优化图片</strong> : 提交前压缩</p> </li> <li> <p><strong>如需分页</strong> : 如果项目数量超过20</p> </li> <li> <p><strong>Lazy loading</strong> : 图库图片按需加载</p> </li> <li> <p>浏览器缓存：适用于资源的适当标头</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>此架构允许：</p> </div> <div class="ulist"> <ul> <li> <p><strong>使用简便</strong> : 添加一个项目 = 创建一个文本文件</p> </li> <li> <p><strong>灵活性</strong> : 可通过新属性扩展</p> </li> <li> <p><strong>可维护性</strong> : 分离 内容/表现</p> </li> <li> <p><strong>可追溯性</strong> : 完整的 Git 版本控制</p> </li> <li> <p><strong>自动化</strong> : 可实现持续构建和部署</p> </li> </ul> </div> <div class="paragraph"> <p>选择 AsciiDoc 能够与网站其余部分保持一致，同时提供专业投资组合所需的丰富元数据。</p> </div> </div> </div> https://cheroliv.com/blog/2026/0100_jbake_supabase_springboot_hybride_post.html Wed, 14 Jan 2026 00:00:00 +0000 blog/2026/0100_jbake_supabase_springboot_hybride_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title">temps de lecture : 12 minutes</div> <p>Plutôt que de choisir entre la simplicité de Supabase et la puissance de Spring Boot, pourquoi ne pas combiner les deux ? Découvrez une architecture hybride qui exploite le meilleur de chaque technologie.</p> </div> <div class="dlist"> <dl> <dt class="hdlist1">toc</dt> <dd> <p>[]</p> </dd> </dl> </div> </div> </div> <div class="sect1"> <h2 id="_le_faux_dilemme_de_larchitecture_moderne">Le Faux Dilemme de l’Architecture Moderne</h2> <div class="sectionbody"> <div class="paragraph"> <p>Lorsqu’on construit une application moderne avec un frontend statique, on se retrouve souvent face à un choix binaire :</p> </div> <div class="ulist"> <ul> <li> <p><strong>Tout miser sur une solution Backend-as-a-Service</strong> (Supabase, Firebase) - simple mais limitée</p> </li> <li> <p><strong>Construire un backend complet</strong> (Spring Boot, Node.js) - puissant mais complexe</p> </li> </ul> </div> <div class="paragraph"> <p>Ce choix est un faux dilemme. L’architecture hybride propose une troisième voie : <strong>utiliser chaque technologie là où elle excelle</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_vision_architecturale">Vision Architecturale</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_larchitecture_traditionnelle_monolithique">L’Architecture Traditionnelle : Monolithique</h3> <div class="imageblock"> <div class="content"> <img src="traditional-architecture.svg" alt="traditional architecture" width="1738" height="5652"> </div> </div> <div class="paragraph"> <p>Dans cette approche, même les opérations les plus simples (lecture d’un article, création d’un commentaire) doivent transiter par votre backend. Vous payez le coût de la complexité dès le premier jour.</p> </div> </div> <div class="sect2"> <h3 id="_larchitecture_baas_tout_délégué">L’Architecture BaaS : Tout Délégué</h3> <div class="imageblock"> <div class="content"> <img src="baas-architecture.svg" alt="baas architecture" width="504" height="432"> </div> </div> <div class="paragraph"> <p>À l’opposé, tout déléguer à un BaaS est séduisant au début mais montre rapidement ses limites dès que la logique métier se complexifie.</p> </div> </div> <div class="sect2"> <h3 id="_larchitecture_hybride_séparation_des_responsabilités">L’Architecture Hybride : Séparation des Responsabilités</h3> <div class="imageblock"> <div class="content"> <img src="hybrid-overview.svg" alt="hybrid overview" width="1742" height="5760"> </div> </div> <div class="paragraph"> <p>L’architecture hybride sépare clairement les responsabilités selon la complexité et la nature des opérations.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_principes_de_conception">Principes de Conception</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_principe_1_commencer_simple_évoluer_intelligemment">Principe 1 : Commencer Simple, Évoluer Intelligemment</h3> <div class="imageblock"> <div class="content"> <img src="evolution-phases.svg" alt="evolution phases" width="465" height="392"> </div> </div> <div class="paragraph"> <p><strong>Ne construisez pas Spring Boot si vous n’en avez pas besoin.</strong> Démarrez avec Supabase, ajoutez Spring Boot quand la complexité le justifie.</p> </div> </div> <div class="sect2"> <h3 id="_principe_2_séparation_par_nature_dopération">Principe 2 : Séparation par Nature d’Opération</h3> <div class="imageblock"> <div class="content"> <img src="operation-types.svg" alt="operation types" width="1266" height="241"> </div> </div> </div> <div class="sect2"> <h3 id="_principe_3_une_seule_source_de_vérité">Principe 3 : Une Seule Source de Vérité</h3> <div class="imageblock"> <div class="content"> <img src="single-source-truth.svg" alt="single source truth" width="1758" height="5700"> </div> </div> <div class="paragraph"> <p>En partageant la même instance PostgreSQL, Supabase et Spring Boot travaillent sur les mêmes données sans synchronisation complexe.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_orchestration_des_flux">Orchestration des Flux</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_flux_1_authentification_centralisée">Flux 1 : Authentification Centralisée</h3> <div class="imageblock"> <div class="content"> <img src="auth-orchestration.svg" alt="auth orchestration" width="1101" height="950"> </div> </div> <div class="paragraph"> <p><strong>Point clé</strong> : Un seul processus d’authentification, un seul JWT, utilisable partout.</p> </div> </div> <div class="sect2"> <h3 id="_flux_2_orchestration_dun_processus_métier_complexe">Flux 2 : Orchestration d’un Processus Métier Complexe</h3> <div class="imageblock"> <div class="content"> <img src="business-orchestration.svg" alt="business orchestration" width="1093" height="990"> </div> </div> <div class="paragraph"> <p><strong>Ce que Spring Boot apporte</strong> : Orchestration fiable de processus complexes impliquant plusieurs systèmes avec garantie transactionnelle.</p> </div> </div> <div class="sect2"> <h3 id="_flux_3_jobs_planifiés_et_synchronisations">Flux 3 : Jobs Planifiés et Synchronisations</h3> <div class="imageblock"> <div class="content"> <img src="scheduled-jobs.svg" alt="scheduled jobs" width="945" height="912"> </div> </div> <div class="paragraph"> <p><strong>Ce que Spring Boot apporte</strong> : Jobs planifiés fiables avec gestion d’état, retry automatique, et exécution garantie.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_matrice_de_décision">Matrice de Décision</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_quand_utiliser_supabase">Quand Utiliser Supabase ?</h3> <div class="imageblock"> <div class="content"> <img src="supabase-decision.svg" alt="supabase decision" width="1030" height="445"> </div> </div> </div> <div class="sect2"> <h3 id="_quand_utiliser_spring_boot">Quand Utiliser Spring Boot ?</h3> <div class="imageblock"> <div class="content"> <img src="springboot-decision.svg" alt="springboot decision" width="1142" height="485"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_exemples_darchitecture_par_type_de_projet">Exemples d’Architecture par Type de Projet</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_blog_portfolio">Blog / Portfolio</h3> <div class="imageblock"> <div class="content"> <img src="blog-architecture.svg" alt="blog architecture" width="1328" height="242"> </div> </div> <div class="paragraph"> <p><strong>Verdict</strong> : 100% Supabase suffit largement.</p> </div> </div> <div class="sect2"> <h3 id="_application_saas">Application SaaS</h3> <div class="imageblock"> <div class="content"> <img src="saas-architecture.svg" alt="saas architecture" width="1751" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Verdict</strong> : Architecture hybride nécessaire. Supabase pour l’essentiel, Spring Boot pour la partie critique (paiements, facturation).</p> </div> </div> <div class="sect2"> <h3 id="_e_commerce">E-commerce</h3> <div class="imageblock"> <div class="content"> <img src="ecommerce-architecture.svg" alt="ecommerce architecture" width="1759" height="5748"> </div> </div> <div class="paragraph"> <p><strong>Verdict</strong> : Spring Boot indispensable. Supabase pour auth et catalogue uniquement.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_stratégie_de_migration_progressive">Stratégie de Migration Progressive</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="migration-strategy.svg" alt="migration strategy" width="2050" height="954"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_coûts_et_considérations_opérationnelles">Coûts et Considérations Opérationnelles</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_structure_des_coûts">Structure des Coûts</h3> <div class="imageblock"> <div class="content"> <img src="cost-structure.svg" alt="cost structure" width="1738" height="5688"> </div> </div> </div> <div class="sect2"> <h3 id="_responsabilités_opérationnelles">Responsabilités Opérationnelles</h3> <div class="imageblock"> <div class="content"> <img src="operational-responsibilities.svg" alt="operational responsibilities" width="1763" height="5676"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_léquilibre_parfait">Conclusion : L’Équilibre Parfait</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’architecture hybride Supabase + Spring Boot n’est pas un compromis, c’est une <strong>synergie</strong>.</p> </div> <div class="sect2"> <h3 id="_les_principes_à_retenir">Les Principes à Retenir</h3> <div class="imageblock"> <div class="content"> <img src="key-principles.svg" alt="key principles" width="581" height="316"> </div> </div> </div> <div class="sect2"> <h3 id="_quand_choisir_cette_architecture">Quand Choisir Cette Architecture ?</h3> <div class="paragraph"> <p><strong>✅ Cette architecture est idéale si :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Vous voulez démarrer rapidement (MVP en jours, pas en mois)</p> </li> <li> <p>Vous anticipez une croissance de la complexité métier</p> </li> <li> <p>Vous voulez minimiser les coûts initiaux</p> </li> <li> <p>Vous aimez PostgreSQL et voulez une source de vérité unique</p> </li> <li> <p>Vous appréciez Kotlin et les Coroutines pour le code métier</p> </li> <li> <p>Vous voulez éviter le vendor lock-in total</p> </li> </ul> </div> <div class="paragraph"> <p><strong>❌ Cette architecture n’est PAS adaptée si :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Votre projet est simple et le restera (blog personnel → 100% Supabase suffit)</p> </li> <li> <p>Vous avez déjà une stack backend établie que vous maîtrisez</p> </li> <li> <p>Vous préférez un monolithe traditionnel</p> </li> <li> <p>Vous avez besoin de .NET, Python, ou autre langage côté backend</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_vision_densemble_finale">Vision d’Ensemble Finale</h3> <div class="imageblock"> <div class="content"> <img src="final-vision.svg" alt="final vision" width="1747" height="5748"> </div> </div> </div> <div class="sect2"> <h3 id="_le_meilleur_des_deux_mondes">Le Meilleur des Deux Mondes</h3> <div class="paragraph"> <p>Cette architecture vous donne :</p> </div> <div class="paragraph"> <p><strong>🚀 La Vélocité de Supabase</strong></p> </div> <div class="ulist"> <ul> <li> <p>Démarrage en heures, pas en semaines</p> </li> <li> <p>Authentification OAuth2 en quelques clics</p> </li> <li> <p>APIs REST générées automatiquement</p> </li> <li> <p>Zéro configuration de serveur</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💪 La Puissance de Spring Boot</strong></p> </div> <div class="ulist"> <ul> <li> <p>Kotlin et Coroutines pour code asynchrone élégant</p> </li> <li> <p>Orchestration de processus métier complexes</p> </li> <li> <p>Jobs planifiés fiables</p> </li> <li> <p>Transactions ACID garanties</p> </li> <li> <p>Écosystème Spring complet</p> </li> </ul> </div> <div class="paragraph"> <p><strong>💰 L’Économie Progressive</strong></p> </div> <div class="ulist"> <ul> <li> <p>0€ pour démarrer et valider</p> </li> <li> <p>Coûts qui suivent la croissance</p> </li> <li> <p>Pas de sur-engineering prématuré</p> </li> </ul> </div> <div class="paragraph"> <p><strong>🎯 La Flexibilité Architecturale</strong></p> </div> <div class="ulist"> <ul> <li> <p>Migration progressive sans refonte</p> </li> <li> <p>Ajout de Spring Boot seulement si nécessaire</p> </li> <li> <p>Pas de vendor lock-in total</p> </li> <li> <p>Architecture évolutive</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_pour_aller_plus_loin">Pour Aller Plus Loin</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ressources_techniques">Ressources Techniques</h3> <div class="paragraph"> <p><strong>Documentation Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://supabase.com/docs/guides/auth">Guide d’Authentification</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/database/postgres/row-level-security">Row Level Security</a></p> </li> <li> <p><a href="https://supabase.com/docs/guides/api">Auto-generated APIs</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Documentation Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p><a href="https://spring.io/guides/tutorials/spring-boot-kotlin/">Spring Boot avec Kotlin</a></p> </li> <li> <p><a href="https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow">Coroutines et Spring</a></p> </li> <li> <p><a href="https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html">JWT Resource Server</a></p> </li> </ul> </div> <div class="paragraph"> <p><strong>Articles Complémentaires :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Sécurisation des APIs avec JWT</p> </li> <li> <p>Optimisation des performances PostgreSQL</p> </li> <li> <p>Patterns de migration progressive</p> </li> <li> <p>Gestion des erreurs en architecture distribuée</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_cas_dusage_réels">Cas d’Usage Réels</h3> <div class="paragraph"> <p>Cette architecture hybride est utilisée avec succès dans :</p> </div> <div class="ulist"> <ul> <li> <p><strong>SaaS B2B</strong> : Authentification Supabase, facturation Spring Boot</p> </li> <li> <p><strong>Marketplaces</strong> : Catalogue Supabase, transactions Spring Boot</p> </li> <li> <p><strong>Plateformes de contenu</strong> : Articles Supabase, analytics Spring Boot</p> </li> <li> <p><strong>Outils internes</strong> : CRUD Supabase, workflows Spring Boot</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_checklist_de_démarrage">Checklist de Démarrage</h3> <div class="paragraph"> <p><strong>Phase 1 - Fondations (Semaine 1)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Créer compte Supabase - [ ] Configurer projet PostgreSQL - [ ] Activer Auth (Google, GitHub) - [ ] Définir schéma initial - [ ] Configurer Row Level Security - [ ] Tester APIs depuis JBake</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 2 - MVP (Semaine 2-3)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Implémenter pages principales - [ ] Intégrer authentification OAuth2 - [ ] Créer formulaires CRUD - [ ] Configurer Storage pour fichiers - [ ] Déployer sur GitHub Pages - [ ] Tester en conditions réelles</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Phase 3 - Évolution (Selon besoins)</strong></p> </div> <div class="ulist checklist"> <ul class="checklist"> <li> <p><i class="fa fa-square-o"></i> Identifier besoins de logique complexe - [ ] Créer projet Spring Boot si nécessaire - [ ] Configurer validation JWT Supabase - [ ] Connecter à PostgreSQL Supabase - [ ] Migrer fonctionnalités complexes - [ ] Implémenter jobs planifiés - [ ] Déployer Spring Boot (Cloud Run, etc.)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_anti_patterns_à_éviter">Anti-Patterns à Éviter</h3> <div class="paragraph"> <p><strong>❌ Ne pas faire :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Dupliquer les données entre Supabase et Spring Boot</p> </li> <li> <p>Créer deux bases PostgreSQL séparées</p> </li> <li> <p>Coder l’authentification vous-même</p> </li> <li> <p>Utiliser Spring Boot pour du CRUD simple</p> </li> <li> <p>Sur-architecturer dès le départ</p> </li> <li> <p>Ignorer Row Level Security de Supabase</p> </li> </ul> </div> <div class="paragraph"> <p><strong>✅ Faire plutôt :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Partager une seule base PostgreSQL</p> </li> <li> <p>Laisser Supabase gérer l’authentification</p> </li> <li> <p>Utiliser Spring Boot seulement pour la complexité</p> </li> <li> <p>Commencer simple, évoluer progressivement</p> </li> <li> <p>Exploiter les forces de chaque technologie</p> </li> <li> <p>Sécuriser avec RLS au niveau base de données</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_perspectives_dévolution">Perspectives d’Évolution</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ajout_de_nouvelles_capacités">Ajout de Nouvelles Capacités</h3> <div class="imageblock"> <div class="content"> <img src="future-capabilities.svg" alt="future capabilities" width="1746" height="5688"> </div> </div> </div> <div class="sect2"> <h3 id="_scaling_horizontal">Scaling Horizontal</h3> <div class="paragraph"> <p>Lorsque votre application grandit, l’architecture hybride scale naturellement :</p> </div> <div class="paragraph"> <p><strong>Supabase :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Scale automatiquement jusqu’à des millions d’opérations</p> </li> <li> <p>Read replicas pour performances lecture</p> </li> <li> <p>Point-in-time recovery pour sécurité</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Spring Boot :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Multiple instances derrière load balancer</p> </li> <li> <p>Stateless design facilite le scaling horizontal</p> </li> <li> <p>Kubernetes pour orchestration si nécessaire</p> </li> </ul> </div> <div class="paragraph"> <p><strong>PostgreSQL :</strong></p> </div> <div class="ulist"> <ul> <li> <p>Partitioning pour tables volumineuses</p> </li> <li> <p>Connection pooling (PgBouncer)</p> </li> <li> <p>Sharding si vraiment nécessaire (rare)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_témoignages_architecturaux">Témoignages Architecturaux</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_startup_saas_50k_utilisateurs">Startup SaaS (50k utilisateurs)</h3> <div class="paragraph"> <p><em><em>_ Nous avons démarré 100% Supabase. À 5k utilisateurs, nous avons ajouté Spring Boot uniquement pour la facturation Stripe et les rapports mensuels. Un an plus tard, 80% de nos opérations passent toujours par Supabase. Spring Boot gère seulement la partie critique. Cette séparation nous a permis de scaler sans refonte. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_plateforme_e_learning_10k_utilisateurs">Plateforme E-learning (10k utilisateurs)</h3> <div class="paragraph"> <p><em><em>_ L’authentification OAuth2 de Supabase nous a fait gagner 3 semaines de développement. Les APIs auto-générées gèrent tout notre catalogue de cours. Spring Boot ne sert que pour les certificats PDF et les emails de progression. Architecture simple, maintenable, évolutive. </em>_</em></p> </div> </div> <div class="sect2"> <h3 id="_marketplace_b2b_3k_utilisateurs">Marketplace B2B (3k utilisateurs)</h3> <div class="paragraph"> <p><em><em>_ Spring Boot gère les transactions entre acheteurs et vendeurs (critique). Supabase gère tout le reste : profils, messagerie temps réel, documents. Le fait qu’ils partagent la même base PostgreSQL nous évite toute synchronisation complexe. Meilleur choix architectural que nous ayons fait. </em>_</em></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_synthèse_un_paradigme_architectural_moderne">Synthèse : Un Paradigme Architectural Moderne</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’architecture hybride Supabase + Spring Boot représente un nouveau paradigme : <strong>la spécialisation architecturale</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="paradigm-shift.svg" alt="paradigm shift" width="1773" height="5456"> </div> </div> <div class="paragraph"> <p><strong>Le principe fondamental :</strong> Ne construisez pas ce qui existe déjà sous forme de service. Concentrez-vous sur ce qui différencie votre application.</p> </div> <div class="sect2"> <h3 id="_la_règle_des_8020">La Règle des 80/20</h3> <div class="paragraph"> <p>Dans la plupart des applications :</p> </div> <div class="ulist"> <ul> <li> <p><strong>80% des opérations</strong> sont du CRUD standard → Supabase</p> </li> <li> <p><strong>20% des opérations</strong> nécessitent de la logique métier → Spring Boot</p> </li> </ul> </div> <div class="paragraph"> <p>Cette règle naturelle justifie l’architecture hybride.</p> </div> <div class="imageblock"> <div class="content"> <img src="8020-rule.svg" alt="8020 rule" width="1751" height="5652"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_conclusion_finale">Conclusion Finale</h2> <div class="sectionbody"> <div class="paragraph"> <p>L’architecture hybride n’est pas un compromis technique, c’est une <strong>décision stratégique</strong>.</p> </div> <div class="paragraph"> <p><strong>Elle vous permet de :</strong></p> </div> <div class="ulist"> <ul> <li> <p>✅ Démarrer rapidement avec un MVP fonctionnel</p> </li> <li> <p>✅ Valider votre marché sans investissement lourd</p> </li> <li> <p>✅ Évoluer progressivement quand la complexité l’exige</p> </li> <li> <p>✅ Maîtriser vos coûts à chaque étape</p> </li> <li> <p>✅ Exploiter le meilleur de chaque technologie</p> </li> <li> <p>✅ Éviter le sur-engineering prématuré</p> </li> <li> <p>✅ Conserver la flexibilité pour l’avenir</p> </li> </ul> </div> <div class="paragraph"> <p><strong>Elle représente :</strong></p> </div> <div class="ulist"> <ul> <li> <p>🎯 <strong>Pragmatisme</strong> : Chaque technologie où elle excelle</p> </li> <li> <p>🚀 <strong>Vélocité</strong> : Time-to-market minimal</p> </li> <li> <p>💰 <strong>Économie</strong> : Coûts alignés sur la valeur</p> </li> <li> <p>🔮 <strong>Évolutivité</strong> : Architecture qui grandit avec vous</p> </li> <li> <p>🛡️ <strong>Robustesse</strong> : Services éprouvés et fiables</p> </li> </ul> </div> <div class="sect2"> <h3 id="_votre_prochain_pas">Votre Prochain Pas</h3> <div class="paragraph"> <p>Si cette architecture vous parle, voici par où commencer :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Créez un compte Supabase</strong> (gratuit)</p> </li> <li> <p><strong>Définissez votre schéma de données minimal</strong></p> </li> <li> <p><strong>Configurez l’authentification OAuth2</strong></p> </li> <li> <p><strong>Créez votre première page JBake qui consomme l’API</strong></p> </li> <li> <p><strong>Déployez sur GitHub Pages</strong></p> </li> </ol> </div> <div class="paragraph"> <p>Vous aurez un MVP fonctionnel en <strong>quelques jours</strong>.</p> </div> <div class="paragraph"> <p>Spring Boot viendra naturellement quand vous en aurez besoin. Pas avant.</p> </div> <hr> <div class="paragraph"> <p><strong>L’architecture hybride, c’est l’art de construire exactement ce qu’il faut, quand il faut.</strong></p> </div> <div class="paragraph"> <p><em>Bon développement ! 🚀</em></p> </div> <hr> <div class="paragraph"> <p><em>Partagez cet article si vous pensez qu’il peut aider d’autres développeurs à faire les bons choix architecturaux.</em></p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0098_preloading_css_variable_post.html Sat, 15 Nov 2025 00:00:00 +0000 blog/2025/0098_preloading_css_variable_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_摘要">摘要</a></li> <li><a href="#_问题这个该死的主题闪烁">问题：这个该死的主题闪烁</a> <ul class="sectlevel2"> <li><a href="#_用户体验的噩梦">用户体验的噩梦</a></li> <li><a href="#_fouc一个老旧的网页问题">FOUC：一个老旧的网页问题</a></li> <li><a href="#_对质量感知的影响">对质量感知的影响</a></li> <li><a href="#_问题的技术分析">问题的技术分析</a></li> </ul> </li> <li><a href="#_为什么经典脚本不够">为什么经典脚本不够？</a> <ul class="sectlevel2"> <li><a href="#_直观但无效的方法">直观但无效的方法</a></li> <li><a href="#_理解domcontentloaded事件">理解DOMContentLoaded事件</a></li> <li><a href="#_渲染阻塞问题">渲染阻塞问题</a></li> <li><a href="#_问题可视化">问题可视化</a></li> <li><a href="#_无效的解决方案尝试">无效的解决方案尝试</a></li> <li><a href="#_真正的解决方案更早行动">真正的解决方案：更早行动</a></li> </ul> </li> <li><a href="#_解决方案预加载early_loading">解决方案：预加载（Early Loading）</a> <ul class="sectlevel2"> <li><a href="#_基本原则">基本原则</a></li> <li><a href="#_为什么_head_是理想的位置">为什么 <code><head></code> 是理想的位置？</a></li> <li><a href="#_三层解决方案架构">三层解决方案架构</a></li> </ul> </li> <li><a href="#_步骤_1保存用户的选择">步骤 1：保存用户的选择</a> <ul class="sectlevel2"> <li><a href="#_localstorage您的持久性内存">localStorage：您的持久性内存</a></li> <li><a href="#_主题备份的实现">主题备份的实现</a></li> <li><a href="#_错误案例管理">错误案例管理</a></li> <li><a href="#_高级持久化策略">高级持久化策略</a></li> </ul> </li> <li><a href="#_步骤_2预加载脚本位于_head">步骤 2：预加载脚本位于 `<head></a> <ul class="sectlevel2"> <li><a href="#_解决方案的核心">解决方案的核心</a></li> <li><a href="#_脚本解剖每一行都很重要">脚本解剖：每一行都很重要</a></li> <li><a href="#_系统偏好检测奖励">系统偏好检测（奖励）</a></li> <li><a href="#_性能为什么这个脚本很快">性能：为什么这个脚本很快</a></li> <li><a href="#_在head中的最佳放置">在`<head>`中的最佳放置</a></li> </ul> </li> <li><a href="#_步骤_3css属性选择器的强大功能">步骤 3：CSS属性选择器的强大功能</a> <ul class="sectlevel2"> <li><a href="#_bootstrap_5_主题系统">Bootstrap 5 主题系统</a></li> <li><a href="#_主题系统的css结构">主题系统的CSS结构</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_摘要">摘要</h2> <div class="sectionbody"> <div class="paragraph"> <p>在这篇深入的技术文章中，我们探讨如何实现主题选择器（light/dark），而不会出现页面加载时令人讨厌的闪烁效果。我们详细分析浏览器渲染周期、FOUC（未样式内容闪现）的根本原因，并提出一种基于同步预加载的稳健解决方案，位于该`<head>`. 此技术保证了流畅且专业的用户体验。</p> </div> </div> </div> <div class="sect1"> <h2 id="_问题这个该死的主题闪烁">问题：这个该死的主题闪烁</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_用户体验的噩梦">用户体验的噩梦</h3> <div class="paragraph"> <p>想象一下这个场景：您已经花了几个小时为您的网络应用设计一个令人惊艳的暗色主题。颜色完美平衡，对比度最佳，您的用户也喜欢这个选项。但有一个尴尬的问题：每次页面重新加载时，默认的亮色主题会在暗色主题生效之前闪现出一小段时间。</p> </div> <div class="paragraph"> <p>这个视觉闪光虽然短暂（有时少于100毫秒），但对人眼来说立刻可感知，并产生不愉快的体验。对于选择深色主题以获得视觉舒适或无障碍需求的用户而言，这种闪烁甚至可能令人感到疼痛，特别是在光线较暗的环境中。</p> </div> </div> <div class="sect2"> <h3 id="_fouc一个老旧的网页问题">FOUC：一个老旧的网页问题</h3> <div class="paragraph"> <p>此现象是所谓的“无样式内容闪烁”(Flash of Unstyled Content, FOUC)的一种变体，这是一种经典的 Web 开发问题，可追溯到 CSS 的早期时代。当浏览器在未应用 CSS 样式的情况下临时显示 HTML 内容时，就会发生 FOUC，从而出现未样式化内容的闪现。</p> </div> <div class="paragraph"> <p>在我们特定的情况下，我们并不是在说一个完全没有样式的内容，而是一个<strong>错误主题的闪光</strong>(FOWT) - 内容被设样，但使用了错误的主题。这尤其令人沮丧，因为这表明我们的应用程序 "oublie" 用户的偏好在每次页面加载时。</p> </div> </div> <div class="sect2"> <h3 id="_对质量感知的影响">对质量感知的影响</h3> <div class="paragraph"> <p>虽然这是一个技术问题，但它对您的应用程序质量的感知有重要影响：</p> </div> <div class="paragraph"> <p><strong>�缺乏润色</strong>: 闪烁让人感觉像是一个未完成或未优化好的应用程序。用户常常将这些小的视觉缺陷与整体缺乏专业性联系起来。</p> </div> <div class="paragraph"> <p><strong>连贯性断裂</strong>该应用程序似乎"oublier"用户的偏好，产生了界面与期望之间不同步的感觉。</p> </div> <div class="paragraph"> <p><strong>视觉疲劳</strong>对于对光敏感或患有偏头痛的用户来说，这种闪光灯可能不仅仅是一种美观上的不适。</p> </div> <div class="paragraph"> <p><strong>感知性能</strong>: 有趣的是，即使你的网站加载速度很快，这种闪烁也可能给人一种应用程序缓慢或不响应的印象。</p> </div> </div> <div class="sect2"> <h3 id="_问题的技术分析">问题的技术分析</h3> <div class="paragraph"> <p>要了解如何解决这个问题，首先要了解它为什么会发生。闪烁是由于网页生命周期中三个关键事件之间的时间偏差导致的：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>初始的HTML解析</strong>: 浏览器读取并分析您的网页结构</p> </li> <li> <p><strong>应用CSS样式</strong>: 浏览器应用 CSS 规则并计算视觉渲染</p> </li> <li> <p><strong>JavaScript 的执行</strong>您的更改主题的代码正在执行</p> </li> </ol> </div> <div class="paragraph"> <p>当事件 n°3（执行 JavaScript）在浏览器已经开始或完成事件 n°2（应用样式）之后到达时，问题就会出现。此时，浏览器已经决定显示哪个主题，而您的代码来得太晚，无法在首次渲染之前影响它。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_为什么经典脚本不够">为什么经典脚本不够？</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_直观但无效的方法">直观但无效的方法</h3> <div class="paragraph"> <p>对开发者来说，最自然的方式是把脚本放在我们……的末尾`<body>`它检查用户首选的主题并应用。这种做法遵循传统的网页最佳实践，建议在页面底部加载脚本以避免阻塞渲染。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">// À la fin de <body> - L'APPROCHE INSUFFISANTE document.addEventListener('DOMContentLoaded', () => { const theme = localStorage.getItem('preferred-theme'); if (theme === 'dark') { document.documentElement.setAttribute('data-bs-theme', 'dark'); } });</code></pre> </div> </div> <div class="paragraph"> <p>这种方法看起来一开始很合乎逻辑。我们等待 DOM 准备就绪，然后应用主题。很简单，不是吗？不幸的是，这种简洁掩盖了与浏览器渲染周期时机相关的根本缺陷。</p> </div> </div> <div class="sect2"> <h3 id="_理解domcontentloaded事件">理解DOMContentLoaded事件</h3> <div class="paragraph"> <p>事件`DOMContentLoaded`当初始的 HTML 文档被浏览器完全加载并解析时触发，<strong>不等待</strong>样式表、图片和子框架加载完成。这是一个重要的理解点。</p> </div> <div class="paragraph"> <p>以下是事件的典型序列：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>浏览器开始下载HTML</p> </li> <li> <p>它在接收HTML的过程中进行分析。</p> </li> <li> <p>他发现了这些标签`<link>`为 CSS 并开始下载它们</p> </li> <li> <p>他发现了标签`<script>`并根据其类型和属性执行它们</p> </li> <li> <p>它构建了DOM（文档对象模型）</p> </li> <li> <p><strong>事件 <code>DOMContentLoaded</code> 被触发</strong></p> </li> <li> <p>它继续应用样式并进行布局</p> </li> <li> <p>第一次 绘制 （显示） 发生</p> </li> <li> <p>事件`load`触发当所有资源都已加载</p> </li> </ol> </div> <div class="paragraph"> <p>问题在于：在第 6 步（DOMContentLoaded）和第 8 步（首次绘制）之间，浏览器已经决定了如何显示页面。如果你的主题切换脚本在第 6 步执行，那么为避免首次使用默认样式的显示已经太晚了。</p> </div> </div> <div class="sect2"> <h3 id="_渲染阻塞问题">渲染阻塞问题</h3> <div class="paragraph"> <p>实际上，时间安排更加复杂。现代浏览器使用复杂的优化技术来提升感知性能。他们试图让首次内容绘制（First Contentful Paint）尽可能快速，以便用户能在屏幕上看到一些内容。</p> </div> <div class="paragraph"> <p>CSS 默认是 "render-blocking" 的，这意味着浏览器会等待下载并解析样式表后才进行首次绘制。这是合乎逻辑的：我们不想展示未经样式化的内容。</p> </div> <div class="paragraph"> <p>但这里有个陷阱：当浏览器首次应用这些CSS样式时，它是基于当前DOM的状态来完成的。如果属性`data-bs-theme`尚未在标签上定义`<html>`, 浏览器将应用默认样式（通常是亮色主题。）</p> </div> <div class="paragraph"> <p>接下来，当您的脚本执行并更改此属性时，浏览器必须：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>重新计算所有受此更改影响的样式</p> </li> <li> <p>如有必要，重新布局</p> </li> <li> <p>重新油漆受影响的元素</p> </li> </ol> </div> <div class="paragraph"> <p>这个重新计算和重新绘制的过程是导致可见闪烁的原因。</p> </div> </div> <div class="sect2"> <h3 id="_问题可视化">问题可视化</h3> <div class="paragraph"> <p>为了更好地理解这个有问题的序列，让我们检查一个详细的序列图 :</p> </div> <div id="diag-flux-incorrect" class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-a0e5760627bb0e088e4b6b3b1fd3de7c.svg" alt="Diagramme de séquence du chargement incorrect" width="1418" height="666"> </div> </div> <div class="paragraph"> <p>这个图表清楚地说明了问题：首次绘制发生在我们的脚本有机会设置正确主题之前。随后的重绘导致了可见的闪烁。</p> </div> </div> <div class="sect2"> <h3 id="_无效的解决方案尝试">无效的解决方案尝试</h3> <div class="paragraph"> <p>已经尝试了多种方法来解决这个问题，但大多数都有各自的缺点：</p> </div> <div class="paragraph"> <p><strong>方法 1 : 在加载前隐藏内容</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">body { opacity: 0; transition: opacity 0.3s; } body.loaded { opacity: 1; }</code></pre> </div> </div> <div class="paragraph"> <p>这种方法会在JavaScript设置正确主题之前隐藏所有内容。问题是什么？这会人为地延迟内容的显示，使网站感觉更慢。此外，如果JavaScript被禁用，用户完全看不到任何内容！</p> </div> <div class="paragraph"> <p><strong>方法 2：使用加载器/旋转器</strong></p> </div> <div class="paragraph"> <p>类似于方法1，但带有加载指示器。这掩盖了问题，但未提升实际性能，并增加了不必要的感知延迟。</p> </div> <div class="paragraph"> <p><strong>方法 3 : 默认使用深色主题</strong></p> </div> <div class="paragraph"> <p>一些开发者在 CSS 中将深色主题设置为默认。这可以避免深色主题用户出现闪烁，但会为浅色主题用户产生相反的问题！</p> </div> <div class="paragraph"> <p>这些方法都不令人满意，因为它们治疗的是症状而不是问题的根本原因。</p> </div> </div> <div class="sect2"> <h3 id="_真正的解决方案更早行动">真正的解决方案：更早行动</h3> <div class="paragraph"> <p>解决此问题的关键是要意识到我们必须设置该属性。<code>data-bs-theme</code> <strong>之前</strong>在浏览器开始应用 CSS 样式之前。这意味着我们的脚本必须在页面生命周期中更早地执行，而这正是我们将在下一节中探讨的内容。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_解决方案预加载early_loading">解决方案：预加载（Early Loading）</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_基本原则">基本原则</h3> <div class="paragraph"> <p>解决我们闪烁问题的优雅方案基于一个简单却强大的原则:<strong>同步应用程序的状态与浏览器渲染进程</strong>与其等待页面加载后再设置主题，我们应该立即设置它。<strong>期间</strong>加载时，甚至在 CSS 样式被应用之前。</p> </div> <div class="paragraph"> <p>此方法在网页开发术语中被称为“Early Loading”或“Synchronous Preloading”。其想法是在页面生命周期中尽可能早地执行我们的主题检测逻辑，最好是在标签中`<head>`, 甚至在浏览器开始下载 CSS 文件之前。</p> </div> </div> <div class="sect2"> <h3 id="_为什么_head_是理想的位置">为什么 <code><head></code> 是理想的位置？</h3> <div class="paragraph"> <p>Le `<head>`HTML 文档由浏览器从上到下依次处理。每个元素按照其出现的顺序进行处理。此特性对我们的解决方案至关重要。</p> </div> <div class="paragraph"> <p>当浏览器遇到一个标签时`<script>`在`<head>`无属性`async` ou <code>defer</code>, il :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>中断 HTML 解析</strong></p> </li> <li> <p><strong>下载脚本</strong>（如果外部）或 床（如果内联）</p> </li> <li> <p><strong>立即执行脚本</strong></p> </li> <li> <p><strong>继续解析HTML</strong></p> </li> </ol> </div> <div class="paragraph"> <p>此行为通常被视为性能问题（因此通常建议将脚本放在页面底部），在此特定情况下成为我们的盟友。通过将我们的主题检测脚本放在开头的`<head>`, 我们保证它在浏览器遇到标签之前执行`<link>`我们的样式表。</p> </div> </div> <div class="sect2"> <h3 id="_三层解决方案架构">三层解决方案架构</h3> <div class="paragraph"> <p>我们的完整解决方案由三个相互依赖的层组成，每一层都发挥着特定的作用：</p> </div> <div class="paragraph"> <p><strong>�层 1 : 持久化 (localStorage)</strong> 此层负责在会话之间保存和恢复用户的选择。</p> </div> <div class="paragraph"> <p><strong>第二�层：早期同步 (内联脚本在 <code><head></code> 中)</strong> 此层在初始渲染前将应用程序的状态与 DOM 同步。</p> </div> <div class="paragraph"> <p><strong>�层3：响应式样式（带属性选择器的CSS）</strong> 此层根据第 2 层定义的状态来设置视觉样式。</p> </div> <div class="paragraph"> <p>现在让我们详细探索每一层。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_1保存用户的选择">步骤 1：保存用户的选择</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_localstorage您的持久性内存">localStorage：您的持久性内存</h3> <div class="paragraph"> <p>Le <code>localStorage`这是一个 Web Storage API，允许以持久化方式在浏览器中存储键值对。与 cookie 不同，存储的数据`localStorage</code>:</p> </div> <div class="ulist"> <ul> <li> <p>永远不会自动发送到服务器</p> </li> <li> <p>它们具有更大的存储容量（通常为5-10MB）</p> </li> <li> <p>没有到期日期（持续至显式删除）</p> </li> <li> <p>仅限于协议和域（同源策略）</p> </li> </ul> </div> <div class="paragraph"> <p>对于我们的用例，`localStorage`完美，因为：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>我们不需要与服务器共享此信息</p> </li> <li> <p>我们希望偏好能够永远持续</p> </li> <li> <p>所需的存储空间非常小（几个字节）</p> </li> </ol> </div> </div> <div class="sect2"> <h3 id="_主题备份的实现">主题备份的实现</h3> <div class="paragraph"> <p>以下是我们在用户更改主题时保存其选择的方法：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">// Fonction complète pour changer le thème function setTheme(newTheme) { // Validation de l'entrée if (!['light', 'dark', 'auto'].includes(newTheme)) { console.error('Thème invalide:', newTheme); return; } try { // Sauvegarde dans localStorage localStorage.setItem('preferred-theme', newTheme); // Application immédiate dans le DOM document.documentElement.setAttribute('data-bs-theme', newTheme); // Dispatch d'un événement personnalisé pour notifier d'autres composants window.dispatchEvent(new CustomEvent('theme-changed', { detail: { theme: newTheme } })); console.log('Thème changé:', newTheme); } catch (error) { console.error('Erreur lors de la sauvegarde du thème:', error); // Fallback : on applique quand même le thème visuellement document.documentElement.setAttribute('data-bs-theme', newTheme); } } // Exemple d'utilisation avec un bouton document.getElementById('theme-toggle').addEventListener('click', () => { const currentTheme = document.documentElement.getAttribute('data-bs-theme') || 'light'; const newTheme = currentTheme === 'light' ? 'dark' : 'light'; setTheme(newTheme); });</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_错误案例管理">错误案例管理</h3> <div class="paragraph"> <p>至关重要的是处理以下情况：<code>localStorage`不可用或无法访问。 几种情况可能会阻止访问`localStorage</code>:</p> </div> <div class="paragraph"> <p><strong>严格的私密导航</strong>Safari 在无痕浏览模式下抛出异常`QuotaExceededError`在写入尝试期间`localStorage`.</p> </div> <div class="paragraph"> <p><strong>隐私设置</strong>: 一些浏览器或隐私扩展可以阻止访问至`localStorage`。</p> </div> <div class="paragraph"> <p><strong>域限制</strong> : Le `localStorage`不可通过协议访问`file://`在某些浏览器中。</p> </div> <div class="paragraph"> <p><strong>存储空间已满</strong>虽然�罕见，但存储空间可能会被完全填满。</p> </div> <div class="paragraph"> <p>这就是为什么我们的代码使用一个块`try…​catch`为优雅地处理这些情况，即使持久性不可用，也继续提供主题切换功能。</p> </div> </div> <div class="sect2"> <h3 id="_高级持久化策略">高级持久化策略</h3> <div class="paragraph"> <p>对于更复杂的应用，您可以考虑采用额外的策略：</p> </div> <div class="paragraph"> <p><strong>服务器同步(可选)</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">async function setTheme(newTheme) { // Sauvegarde locale immédiate localStorage.setItem('preferred-theme', newTheme); document.documentElement.setAttribute('data-bs-theme', newTheme); // Synchronisation serveur en arrière-plan (si l'utilisateur est connecté) if (userIsAuthenticated()) { try { await fetch('/api/user/preferences', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ theme: newTheme }) }); } catch (error) { console.warn('Échec de la synchronisation serveur:', error); // L'échec n'est pas critique car la préférence est déjà sauvegardée localement } } }</code></pre> </div> </div> <div class="paragraph"> <p>此方法可在已登录用户的设备之间同步偏好设置，同时保持本地响应的即时性。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_2预加载脚本位于_head">步骤 2：预加载脚本位于 `<head></h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_解决方案的核心">解决方案的核心</h3> <div class="paragraph"> <p>这里正是魔法真正发挥作用的地方。我们将放置一个小脚本。<strong>内联</strong>直接在我们的`<head>`, 在我们所有的标签之前`<link>`样式表的。此脚本故意极简、自包含，并且设计为尽可能快速执行。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Mon Site Incroyable</title> <!-- ========================================== NOTRE SCRIPT MAGIQUE DE PRÉ-CHARGEMENT Ce script DOIT être le premier élément dans le <head> après les meta tags ========================================== --> <script> // IIFE pour ne pas polluer le scope global (function() { 'use strict'; try { // Lecture de la préférence sauvegardée const savedTheme = localStorage.getItem('preferred-theme'); // Si une préférence existe, on l'applique immédiatement if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); } // Optionnel : Détecter la préférence système si aucune sauvegarde else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); } // Sinon, le thème par défaut du CSS sera utilisé (généralement 'light') } catch (error) { // En cas d'erreur (localStorage bloqué, etc.), on log discrètement // et on laisse le thème par défaut s'appliquer console.warn('Impossible de charger la préférence de thème:', error); } })(); </script> <!-- FIN DU SCRIPT MAGIQUE --> <!-- Les feuilles de style sont chargées APRÈS le script --> <link rel="stylesheet" href="css/bootstrap.min.css"> <link rel="stylesheet" href="css/styles.css"> <!-- Autres ressources du head --> <link rel="icon" href="favicon.ico"> </head> <body> <!-- Contenu de la page --> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_脚本解剖每一行都很重要">脚本解剖：每一行都很重要</h3> <div class="paragraph"> <p>让我们逐行分析这个脚本，以理解每一个设计决策：</p> </div> <div class="paragraph"> <p><strong>IIFE（立即调用函数表达式）</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">(function() { // ... })();</code></pre> </div> </div> <div class="paragraph"> <p>此结构创建了一个立即执行的函数。为什么？为了将我们的变量隔离在局部作用域中，以免污染全局作用域。即使我们只使用了`const`(它具有块级作用域)，IIFE 是一种良好实践，能够使我们的意图更清晰并防止潜在的命名冲突。</p> </div> <div class="paragraph"> <p><strong>严格模式</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">'use strict';</code></pre> </div> </div> <div class="paragraph"> <p>此指令启用 JavaScript 严格模式，其： - 禁止使用未声明的变量 - 为危险操作生成错误 - 改善某些 JavaScript 引擎的性能</p> </div> <div class="paragraph"> <p>对于像这样的关键脚本，我们想要最大的安全性。</p> </div> <div class="paragraph"> <p><strong>try…​catch 块</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">try { // Code principal } catch (error) { console.warn('Impossible de charger la préférence de thème:', error); }</code></pre> </div> </div> <div class="paragraph"> <p>此块绝对至关重要。它保证如果出现问题（如 localStorage 被阻塞、语法错误等），我们的脚本将不会阻止整个页面的加载。使用`console.warn`而不是`console.error`表明这是一个非关键问题。</p> </div> <div class="paragraph"> <p><strong>读取 localStorage</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">const savedTheme = localStorage.getItem('preferred-theme');</code></pre> </div> </div> <div class="paragraph"> <p>此行在某些上下文（Safari 的严格私人浏览）下可能会引发异常。因此它位于一个 <code>try…​catch</code> 块中。</p> </div> <div class="paragraph"> <p><strong>条件应用</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">if (savedTheme) { document.documentElement.setAttribute('data-bs-theme', savedTheme); }</code></pre> </div> </div> <div class="paragraph"> <p>我们仅在找到已保存的主题时才应用该主题。否则，我们让 CSS 使用其默认主题。这种方法比在 JavaScript 中硬编码的默认值更稳健。</p> </div> </div> <div class="sect2"> <h3 id="_系统偏好检测奖励">系统偏好检测（奖励）</h3> <div class="paragraph"> <p>一种可选但优雅的改进是，在用户尚未在你的应用中做出明确选择时，检测其操作系统的主题偏好：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); }</code></pre> </div> </div> <div class="paragraph"> <p>此功能使用媒体查询`prefers-color-scheme`� 查询系统。在 macOS、Windows 10+、iOS 和现代 Android 上，此查询会返回用户的系统偏好设置。</p> </div> <div class="paragraph"> <p><strong>优势：</strong> - 个性化体验，从首次访问开始 - 与用户系统环境一致 - 首次访问不需要存储</p> </div> <div class="paragraph"> <p><strong>考虑：</strong> - 并非所有浏览器都支持此功能（但自2020年以来支持情况非常好） - 验证`window.matchMedia`确保兼容性 - 用户始终可以覆盖此选择</p> </div> </div> <div class="sect2"> <h3 id="_性能为什么这个脚本很快">性能：为什么这个脚本很快</h3> <div class="paragraph"> <p>我们的预加载脚本设计为极速：</p> </div> <div class="paragraph"> <p><strong>最小尺寸</strong>大约 300 字节未压缩，200 字节压缩。与任何图片或 JavaScript 库相比，这可以忽略不计。</p> </div> <div class="paragraph"> <p><strong>内联</strong>: 不需要额外的 HTTP 请求。脚本在 HTML 中，因此它立即可用。</p> </div> <div class="paragraph"> <p><strong>简单的同步操作</strong>从 localStorage 中读取键（超快操作）并修改 DOM 属性（浏览器原生操作）。</p> </div> <div class="paragraph"> <p><strong>无依赖</strong>没有框架，没有库，只有原生 JavaScript。没有启动时间，没有依赖解析。</p> </div> <div class="paragraph"> <p><strong>单次执行</strong>此脚本在加载时仅执行一次。没有事件监听器，没有循环，没有复杂的计算。</p> </div> <div class="paragraph"> <p>实际上，在现代硬件上，该脚本的执行时间不到1毫秒，这是一个无法感知的时间，对页面加载性能没有任何影响。</p> </div> </div> <div class="sect2"> <h3 id="_在head中的最佳放置">在`<head>`中的最佳放置</h3> <div class="paragraph"> <p>元素在…​中的顺序`<head>`是 重要的。 这是 顺序 推荐 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><head> <!-- 1. Métadonnées critiques --> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <!-- 2. Notre script de pré-chargement (IMMÉDIATEMENT après les meta) --> <script> (function() { /* notre code */ })(); </script> <!-- 3. Titre de la page --> <title>Mon Site</title> <!-- 4. Feuilles de style --> <link rel="stylesheet" href="styles.css"> <!-- 5. Autres ressources (fonts, favicons, etc.) --> <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="icon" href="favicon.ico"> <!-- 6. Autres scripts avec defer ou async --> <script src="app.js" defer></script> </head></code></pre> </div> </div> <div class="paragraph"> <p>这个命令保证：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>字符集在任何文本处理之前被定义</p> </li> <li> <p>我们的脚本在加载CSS之前执行</p> </li> <li> <p>CSS 会随后被加载，并直接应用正确的主题</p> </li> <li> <p>其他非关键资源最后加载</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_3css属性选择器的强大功能">步骤 3：CSS属性选择器的强大功能</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_bootstrap_5_主题系统">Bootstrap 5 主题系统</h3> <div class="paragraph"> <p>Bootstrap 5 引入了一种基于 CSS 自定义属性（CSS 变量）和属性选择器的优雅主题管理系统。此系统使用属性。<code>data-bs-theme`在元素上</code><html>`为了确定应用哪一组颜色变量。</p> </div> <div class="paragraph"> <p>这个系统的美在于其简单性：与其加载不同的样式表或在成千上万的元素上切换类，不如我们只需在单个元素上更改一个属性，然后CSS通过级联处理其余部分。</p> </div> </div> <div class="sect2"> <h3 id="_主题系统的css结构">主题系统的CSS结构</h3> <div class="paragraph"> <p>以下是实现强健主题系统的完整 CSS 结构：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/** * SYSTÈME DE THÈME COMPLET * Utilise les Custom Properties CSS pour une maintenance facile */ /* ============================================ THÈME PAR DÉFAUT (LIGHT) Défini sur :root pour être le fallback ============================================ */ :root { /* Couleurs de base */ --color-primary: #0d6efd; --color-secondary: #6c757d; --color-success: #198754; --color-danger: #dc3545; --color-warning: #ffc107; --color-info: #0dcaf0; /* Couleurs de fond */ --bg-primary: #ffffff; --bg-secondary: #f8f9fa; --bg-tertiary: #e9ecef; /* Couleurs de texte */ --text-primary: #212529; --text-secondary: #6c757d; --text-tertiary: #adb5bd; /* Couleurs de bordure */ --border-color: #dee2e6; --border-color-subtle: #e9ecef; /* Couleurs d'ombre */ --shadow-sm: rgba(0, 0, 0, 0.075); --shadow-md: rgba(0, 0, 0, 0.15); --shadow-lg: rgba(0, 0, 0, 0.25</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html Fri, 7 Nov 2025 00:00:00 +0000 blog/2025/0097_gradle_plugin_dev_func_test_logger_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_问题对_gradlerunner_的依赖">问题：对 GradleRunner 的依赖</a> <ul class="sectlevel2"> <li><a href="#_插件开发的上下文">�插件开发的上下文</a></li> <li><a href="#_日志的困境">日志的困境</a></li> <li><a href="#_错误的好主意">错误的好主意</a></li> </ul> </li> <li><a href="#_解决方案独立的_logger">解决方案：独立的 Logger</a> <ul class="sectlevel2"> <li><a href="#_推荐架构">推荐架构</a></li> <li><a href="#_执行流">执行流</a></li> </ul> </li> <li><a href="#_完整实现">完整实现</a> <ul class="sectlevel2"> <li><a href="#_gradle_依赖">Gradle 依赖</a></li> <li><a href="#_配置_logback">配置 Logback</a></li> <li><a href="#_完整的测试类">完整的测试类</a></li> </ul> </li> <li><a href="#_多层次日志记录方案">多层次日志记录方案</a></li> <li><a href="#_良好实践">良好实践</a> <ul class="sectlevel2"> <li><a href="#_推荐的日志结构">推荐的日志结构</a></li> <li><a href="#_提升可读性的视觉符号">提升可读性的视觉符号</a></li> <li><a href="#_从输出中提取信息">从输出中提取信息</a></li> </ul> </li> <li><a href="#_前后对比">前后对比</a> <ul class="sectlevel2"> <li><a href="#_前_有问题的方法">前 : 有问题的方法</a></li> <li><a href="#_之后_鲁棒_方法">之后 : 鲁棒 方法</a></li> </ul> </li> <li><a href="#_汇总图">汇总图</a></li> <li><a href="#_应避免的陷阱">应避免的陷阱</a> <ul class="sectlevel2"> <li><a href="#_陷阱_1忘记_forwardoutput">�❌ 陷阱 1：忘记 `.forwardOutput()</a></li> <li><a href="#_陷阱_2_logger_未初始化">�❌ 陷阱 2： Logger 未初始化</a></li> <li><a href="#_陷阱3_日志过度">❌ 陷阱3 : 日志过度</a></li> </ul> </li> <li><a href="#_结果和度量">结果和度量</a></li> <li><a href="#_结论">结论</a></li> <li><a href="#_资源">资源</a></li> <li><a href="#_更进一步">更进一步</a></li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <p>在开发 Gradle 插件时，功能测试对于验证插件在真实 Gradle 环境中的行为至关重要。然而，一个关键问题很快就会出现：<strong>如何在不与 <code>GradleRunner</code> 创建问题依赖的情况下构建一个高效的日志系统？</strong></p> </div> <div class="paragraph"> <p>在本文中，我们将探索：</p> </div> <div class="ulist"> <ul> <li> <p>Gradle功能测试中的日志问题</p> </li> <li> <p>使用 SLF4J 和 Logback 构建健壮解决方案的架构</p> </li> <li> <p>完整的实现，带有具体示例</p> </li> <li> <p>良好实践及应避免的陷阱</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_问题对_gradlerunner_的依赖">问题：对 GradleRunner 的依赖</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_插件开发的上下文">�插件开发的上下文</h3> <div class="paragraph"> <p>在开发 Gradle 插件时，我们通常使用`GradleRunner`使用 <em>Gradle TestKit</em> 执行测试构建 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `test my plugin`() { val result = GradleRunner.create() .withProjectDir(projectDir) .withArguments("myTask") .build() // Comment logger efficacement ici ? }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_日志的困境">日志的困境</h3> <div class="paragraph"> <p>主要问题是：<strong>日志不应依赖于我们不确定其初始化的对象</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-a33bb19f01c2b69aecf620887a29e815.png" alt="Diagram" width="433" height="262"> </div> </div> </div> <div class="sect2"> <h3 id="_错误的好主意">错误的好主意</h3> <div class="admonitionblock warning"> <table> <tr> <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>不要这样做：</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ MAUVAIS: Tentative d'obtenir un logger du runner val runner = GradleRunner.create() val logger = runner.logger // N'existe pas ! // ❌ MAUVAIS: Logger partagé initialisé tardivement lateinit var logger: Logger @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) }</code></pre> </div> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_解决方案独立的_logger">解决方案：独立的 Logger</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_推荐架构">推荐架构</h3> <div class="paragraph"> <p>解决方案是使用一个日志记录器<strong>完全独立</strong> du <code>GradleRunner</code>, 在测试类级别初始化。</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-3f99d1d6650ac1754381e2b11795a3b4.png" alt="Diagram" width="601" height="448"> </div> </div> </div> <div class="sect2"> <h3 id="_执行流">执行流</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-1f3376d0a2bfc35ec5ba58ffb416b791.png" alt="Diagram" width="646" height="686"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_完整实现">完整实现</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_gradle_依赖">Gradle 依赖</h3> <div class="paragraph"> <p>在您的中添加必要的依赖`build.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Pour les tests fonctionnels testImplementation(gradleTestKit()) testImplementation("org.junit.jupiter:junit-jupiter:5.10.2") // Pour le logging testImplementation("org.slf4j:slf4j-api:2.0.17") testRuntimeOnly("ch.qos.logback:logback-classic:1.4.14") // Pour les assertions testImplementation("org.assertj:assertj-core:3.27.6") } tasks.test { useJUnitPlatform() }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_配置_logback">配置 Logback</h3> <div class="paragraph"> <p>创建文件`src/test/resources/logback-test.xml`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- Appender console avec format lisible --> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> </encoder> </appender> <!-- Appender fichier pour conservation --> <appender name="FILE" class="ch.qos.logback.core.FileAppender"> <file>build/test-results/functional-tests.log</file> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern> </encoder> </appender> <!-- Logger pour vos tests --> <logger name="com.cheroliv.bakery" level="DEBUG"/> <!-- Réduire le bruit de Gradle --> <logger name="org.gradle" level="WARN"/> <!-- Configuration racine --> <root level="INFO"> <appender-ref ref="STDOUT"/> <appender-ref ref="FILE"/> </root> </configuration></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_完整的测试类">完整的测试类</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package com.cheroliv.bakery import org.gradle.testkit.runner.GradleRunner import org.gradle.testkit.runner.TaskOutcome import org.junit.jupiter.api.* import org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS import org.junit.jupiter.api.io.TempDir import org.slf4j.Logger import org.slf4j.LoggerFactory import java.io.File import kotlin.test.assertEquals import kotlin.test.assertTrue @TestInstance(PER_CLASS) class BakeryPluginFunctionalTest { @field:TempDir lateinit var projectDir: File private val buildFile by lazy { projectDir.resolve("build.gradle.kts") } private val settingsFile by lazy { projectDir.resolve("settings.gradle.kts") } companion object { // ✓ Logger indépendant, initialisé au chargement de la classe private val logger: Logger = LoggerFactory.getLogger( BakeryPluginFunctionalTest::class.java ) @JvmStatic @BeforeAll fun globalSetup() { logger.info("═".repeat(60)) logger.info("DÉMARRAGE DE LA SUITE DE TESTS FONCTIONNELS") logger.info("═".repeat(60)) } @JvmStatic @AfterAll fun globalTeardown() { logger.info("═".repeat(60)) logger.info("FIN DE LA SUITE DE TESTS") logger.info("═".repeat(60)) } } @BeforeEach fun setup() { logger.info("─".repeat(60)) logger.info("Préparation de l'environnement de test") logger.debug("Répertoire de test: ${projectDir.absolutePath}") settingsFile.writeText(""" rootProject.name = "test-bakery-project" """.trimIndent()) logger.debug("✓ settings.gradle.kts créé") } @AfterEach fun teardown(testInfo: TestInfo) { logger.info("✓ Test terminé: ${testInfo.displayName}") logger.info("─".repeat(60)) } @Test fun `plugin can be applied successfully`() { logger.info("TEST: Application du plugin Bakery") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Fichier build.gradle.kts créé") logger.debug("Lancement du build Gradle...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() // ← Important : capture la sortie .withPluginClasspath() .withArguments("tasks", "--group=bakery", "--stacktrace") .withProjectDir(projectDir) .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // Analyse de la sortie logger.debug("Analyse de la sortie Gradle...") val outputLines = result.output.lines() logger.debug("Nombre de lignes capturées: ${outputLines.size}") // Validation val expectedTasks = listOf("bake", "printConfigPath", "printJBakeClasspath") logger.info("Vérification des tâches attendues:") expectedTasks.forEach { task -> val found = result.output.contains(task) logger.debug(" ${if (found) "✓" else "✗"} $task") assertTrue(found, "Task '$task' should be available") } logger.info("✓ Plugin appliqué avec succès - ${expectedTasks.size} tâches trouvées") } @Test fun `bake task executes and prints version`() { logger.info("TEST: Exécution de la tâche 'bake'") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) logger.debug("Exécution de 'gradle bake'...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("bake", "--info") // --info pour plus de détails .withProjectDir(projectDir) .build() // Extraction d'informations depuis la sortie logger.debug("Recherche du message 'Baking site'...") val hasBakingMessage = result.output.contains("Baking site with Bakery Plugin!") logger.debug("Recherche de la version JBake...") val hasVersionMessage = result.output.contains("Using JBake version:") // Extraction de la version (si présente) val versionRegex = Regex("Using JBake version: (.+)") val versionMatch = versionRegex.find(result.output) if (versionMatch != null) { val version = versionMatch.groupValues[1] logger.info("Version JBake détectée: $version") } // Validation assertTrue(hasBakingMessage, "Message 'Baking site' attendu") assertTrue(hasVersionMessage, "Message de version attendu") assertEquals(TaskOutcome.SUCCESS, result.task(":bake")?.outcome) logger.info("✓ Tâche 'bake' exécutée avec succès") } @Test fun `analyze output with structured logging`() { logger.info("TEST: Analyse structurée de la sortie") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } task("diagnostics") { doLast { println("[DIAG] Project: ${'$'}{project.name}") println("[DIAG] Build dir: ${'$'}{project.buildDir}") println("[DIAG] Plugin applied: true") val config = configurations.findByName("jbakeRuntime") println("[DIAG] JBake config exists: ${'$'}{config != null}") if (config != null) { println("[DIAG] Dependencies count: ${'$'}{config.dependencies.size}") } } } """.trimIndent()) logger.debug("Exécution de la tâche diagnostics...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("diagnostics", "--quiet") .withProjectDir(projectDir) .build() // Analyse structurée logger.info("Extraction des informations de diagnostic:") val diagLines = result.output.lines() .filter { it.startsWith("[DIAG]") } logger.debug("Nombre de lignes de diagnostic: ${diagLines.size}") diagLines.forEach { line -> logger.info(" $line") // Analyse spécifique par type de ligne when { line.contains("Project:") -> { val projectName = line.substringAfter("Project:").trim() logger.debug(" → Nom du projet extrait: '$projectName'") } line.contains("Dependencies count:") -> { val count = line.substringAfter("count:").trim() logger.debug(" → Nombre de dépendances: $count") } } } assertTrue(diagLines.isNotEmpty(), "Des lignes de diagnostic devraient être présentes") logger.info("✓ Analyse structurée terminée - ${diagLines.size} lignes analysées") } @Test fun `test with error handling`() { logger.info("TEST: Gestion d'erreurs avec logging") buildFile.writeText(""" plugins { id("com.cheroliv.bakery") } """.trimIndent()) try { logger.debug("Tentative d'exécution...") val result = GradleRunner.create() .forwardOutput() .withPluginClasspath() .withArguments("printJBakeClasspath") .withProjectDir(projectDir) .build() val outcome = result.task(":printJBakeClasspath")?.outcome logger.info("Outcome: $outcome") if (outcome == TaskOutcome.SUCCESS) { logger.info("✓ Exécution réussie") } else { logger.warn("⚠ Outcome inattendu: $outcome") } assertEquals(TaskOutcome.SUCCESS, outcome) } catch (e: Exception) { logger.error("✗ Échec du test", e) logger.error("Type d'exception: ${e.javaClass.simpleName}") logger.error("Message: ${e.message}") // Log de la stack trace si nécessaire if (logger.isDebugEnabled) { logger.debug("Stack trace complète:", e) } throw e } } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_多层次日志记录方案">多层次日志记录方案</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-9bb27dbdb9ed98e33b26be9adeac5684.png" alt="Diagram" width="314" height="911"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_良好实践">良好实践</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_推荐的日志结构">推荐的日志结构</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `mon test`() { // 1. LOG: Début du test logger.info("TEST: Description du test") // 2. LOG: Préparation logger.debug("Préparation des fichiers...") buildFile.writeText("...") logger.debug("✓ Fichiers préparés") // 3. LOG: Exécution logger.debug("Lancement du build...") val startTime = System.currentTimeMillis() val result = GradleRunner.create() .forwardOutput() .withArguments("task") .build() val duration = System.currentTimeMillis() - startTime logger.info("Build terminé en ${duration}ms") // 4. LOG: Analyse logger.debug("Analyse des résultats...") // ... validations ... // 5. LOG: Conclusion logger.info("✓ Test réussi") }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_提升可读性的视觉符号">提升可读性的视觉符号</h3> <div class="paragraph"> <p>使用 Unicode 符号来提升日志的可读性：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">logger.info("✓ Succès") logger.info("✗ Échec") logger.info("⚠ Attention") logger.info("→ Étape suivante") logger.info("═".repeat(60)) // Séparateur principal logger.info("─".repeat(60)) // Séparateur secondaire</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_从输出中提取信息">从输出中提取信息</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Recherche simple val hasMessage = result.output.contains("Expected message") // Extraction avec regex val versionRegex = Regex("Version: (.+)") val version = versionRegex.find(result.output)?.groupValues?.get(1) // Filtrage de lignes val errorLines = result.output.lines() .filter { it.contains("ERROR") } errorLines.forEach { logger.error("Gradle error: $it") }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_前后对比">前后对比</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_前_有问题的方法">前 : 有问题的方法</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { lateinit var logger: Logger // ❌ Initialisé tardivement @BeforeEach fun setup() { logger = LoggerFactory.getLogger(...) // ❌ Dépendance } @Test fun test() { val runner = GradleRunner.create() logger.info("Testing...") // ⚠ Peut échouer } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_之后_鲁棒_方法">之后 : 鲁棒 方法</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class MyTest { companion object { private val logger = LoggerFactory.getLogger(...) // ✓ Indépendant } @Test fun test() { logger.info("TEST: Starting...") // ✓ Toujours disponible val result = GradleRunner.create() .forwardOutput() // ✓ Capture la sortie .build() logger.debug("Output: ${result.output}") // ✓ Analyse } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_汇总图">汇总图</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-0d066c7b61fef02c90918a4912efe62f.png" alt="Diagram" width="878" height="1345"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_应避免的陷阱">应避免的陷阱</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_陷阱_1忘记_forwardoutput">�❌ 陷阱 1：忘记 `.forwardOutput()</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: La sortie Gradle n'est pas capturée val result = GradleRunner.create() .withArguments("task") .build() // result.output sera vide !</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: La sortie est capturée val result = GradleRunner.create() .forwardOutput() // ✓ .withArguments("task") .build()</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_陷阱_2_logger_未初始化">�❌ 陷阱 2： Logger 未初始化</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS class Test { lateinit var logger: Logger // Peut ne pas être initialisé }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON class Test { companion object { private val logger = LoggerFactory.getLogger(...) // Toujours initialisé } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_陷阱3_日志过度">❌ 陷阱3 : 日志过度</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// MAUVAIS: Trop de logs DEBUG en production logger.debug("Variable a = $a") logger.debug("Variable b = $b") logger.debug("Variable c = $c") // ... 100 lignes de logs</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// BON: Logging ciblé logger.info("Traitement de ${items.size} éléments") logger.debug("Détails: ${items.take(5)}...") // Échantillon seulement</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结果和度量">结果和度量</h2> <div class="sectionbody"> <div class="paragraph"> <p>使用这种方法，您将获得：</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 28.5714%;"> <col style="width: 42.8571%;"> <col style="width: 28.5715%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">度量</th> <th class="tableblock halign-left valign-top">前</th> <th class="tableblock halign-left valign-top">之后</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">代码行</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~50 行</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">约80行 (+60%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">调试时间</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">约30分钟</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">~5 分钟 (-83%)</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">检测到错误</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">基本</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">详细</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">维护</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">困难</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">简单</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">独立</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">❌ 已耦合</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">独立</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>在Gradle插件的功能测试中建立一个健壮的日志系统的原则很简单：<strong>独立</strong>。</p> </div> <div class="paragraph"> <p>要点：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>独立日志记录器</strong>: 已在一个`companion object`</p> </li> <li> <p><strong>SLF4J + Logback</strong>: 经验证且可配置的堆栈</p> </li> <li> <p><strong>.forwardOutput()</strong>: 捕获 Gradle 输出</p> </li> <li> <p><strong>结构化日志</strong>: INFO 用于步骤, DEBUG 用于详情</p> </li> <li> <p><strong>输出分析</strong>信息提取自从`result.output`</p> </li> </ol> </div> <div class="paragraph"> <p>这种方法保证了测试<strong>可维护的</strong>, <strong>可调试的</strong> et <strong>健壮的</strong>,同时遵循坚实的设计原则。</p> </div> </div> </div> <div class="sect1"> <h2 id="_资源">资源</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/test_kit.html">Gradle TestKit 文档</a></p> </li> <li> <p><a href="https://www.slf4j.org/manual.html">SLF4J 手册</a></p> </li> <li> <p><a href="https://logback.qos.ch/manual/configuration.html">Logback 配置</a></p> </li> <li> <p><a href="https://github.com/gradle/gradle/tree/master/subprojects/test-kit">Gradle TestKit 源代码</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_更进一步">更进一步</h2> <div class="sectionbody"> <div class="paragraph"> <p>在即将发表的文章中，我们将探讨：</p> </div> <div class="ulist"> <ul> <li> <p>带有结构化日志的持续集成</p> </li> <li> <p>带有内嵌日志的 HTML 测试报告</p> </li> <li> <p>使用 JVM 附件进行高级调试</p> </li> <li> <p>日志性能与优化</p> </li> </ul> </div> <div class="paragraph"> <p>这篇文章是我在技术博客上的《Gradle 插件开发》系列的一部分。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0096_afficher-couleurs-asciidoc_post.html Sat, 1 Nov 2025 00:00:00 +0000 blog/2025/0096_afficher-couleurs-asciidoc_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_问题">问题</a> <ul class="sectlevel2"> <li><a href="#_使用上下文">使用上下文</a></li> <li><a href="#_可能的方法">可能的方法</a> <ul class="sectlevel3"> <li><a href="#_选项_1_unicode_字符">选项 1 : Unicode 字符</a></li> <li><a href="#_选项2外部图像">选项2：外部图像</a></li> <li><a href="#_选项_3_自定义_css_角色">选项 3 : 自定义 CSS 角色</a></li> <li><a href="#_选项_4_html注入已采纳的解决方案">选项 4 : HTML注入（已采纳的解决方案）</a></li> </ul> </li> </ul> </li> <li><a href="#_解决方案html_注入带有">解决方案：HTML 注入，带有 </a> <ul class="sectlevel2"> <li><a href="#_工作原理">工作原理</a></li> <li><a href="#_实现">实现</a> <ul class="sectlevel3"> <li><a href="#_css属性的解释">CSS属性的解释</a></li> </ul> </li> <li><a href="#_完整示例">完整示例</a></li> </ul> </li> <li><a href="#_优化与最佳实践">优化与最佳实践</a> <ul class="sectlevel2"> <li><a href="#_管理浅色">管理浅色</a></li> <li><a href="#_调整方块的大小">调整方块的大小</a></li> <li><a href="#_创建变体">创建变体</a> <ul class="sectlevel3"> <li><a href="#_彩色圆">彩色圆</a></li> <li><a href="#_带有彩色边框的正方形">带有彩色边框的正方形</a></li> </ul> </li> </ul> </li> <li><a href="#_解决方案架构">解决方案架构</a></li> <li><a href="#_优势和局限">�优势和局限</a> <ul class="sectlevel2"> <li><a href="#_优势">优势</a></li> <li><a href="#_限制">限制</a></li> <li><a href="#_改善无障碍">改善无障碍</a></li> </ul> </li> <li><a href="#_具体示例主题文档">具体示例：主题文档</a></li> <li><a href="#_结论">结论</a></li> <li><a href="#_资源">资源</a></li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <p>在编写技术文档时，特别是样式指南或用户界面规范，常常需要显示调色板。AsciiDoc 虽然在文档方面非常强大，但没有提供原生语法来展示颜色样本。本文探讨了这一问题，并提出了一种基于 HTML 注入的优雅解决方案。</p> </div> </div> </div> <div class="sect1"> <h2 id="_问题">问题</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_使用上下文">使用上下文</h3> <div class="paragraph"> <p>想象一下，你正在记录一个 Web 应用程序主题的 CSS 变量。你需要：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>列出十六进制颜色代码</p> </li> <li> <p>显示每种颜色的视觉预览</p> </li> <li> <p>保持源文档的可读性</p> </li> <li> <p>确保与JBake等静态站点生成器兼容</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="use-case-diagram.svg" alt="use case diagram" width="1739" height="5604"> </div> </div> </div> <div class="sect2"> <h3 id="_可能的方法">可能的方法</h3> <div class="paragraph"> <p>可以考虑多种方案在 AsciiDoc 文档中显示颜色：</p> </div> <div class="imageblock"> <div class="content"> <img src="component-diagram.svg" alt="component diagram" width="1826" height="5676"> </div> </div> <div class="sect3"> <h4 id="_选项_1_unicode_字符">选项 1 : Unicode 字符</h4> <div class="paragraph"> <p>使用Unicode字符作为`■`(■) 简单但有限：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* ■ --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p><strong>限制</strong> : 无法控制颜色，依赖系统字体。</p> </div> </div> <div class="sect3"> <h4 id="_选项2外部图像">选项2：外部图像</h4> <div class="paragraph"> <p>为每种颜色创建 PNG 或 SVG 图像：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* image:colors/violet.svg[width=16] --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>限制</strong> : 维护繁重，文件增多，没有自动同步。</p> </div> </div> <div class="sect3"> <h4 id="_选项_3_自定义_css_角色">选项 3 : 自定义 CSS 角色</h4> <div class="paragraph"> <p>定义 CSS 类并通过 AsciiDoc 角色应用它们：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* [.color-violet]##■## --accent-color: #7952b3</code></pre> </div> </div> <div class="paragraph"> <p><strong>Limitations</strong> : 需要外部样式表，预先定义所有可能的颜色。</p> </div> </div> <div class="sect3"> <h4 id="_选项_4_html注入已采纳的解决方案">选项 4 : HTML注入（已采纳的解决方案）</h4> <div class="paragraph"> <p>使用宏``用于注入带有内联样式的HTML：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em; background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: #7952b3 (violet Bootstrap)</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_解决方案html_注入带有">解决方案：HTML 注入，带有 </h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_工作原理">工作原理</h3> <div class="paragraph"> <p>宏``AsciiDoc的功能允许插入不会被AsciiDoc处理器解释的原始内容。这使我们能够直接注入带有内联CSS样式的HTML。</p> </div> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 2) ] @startuml participant "文档 ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml participant "文档 AsciiDoc" as doc participant "处理器 AsciiDoc" as processor participant "pass:[] 宏" as pass participant "HTML 最终" as html doc -> processor : Analyse document processor -> pass : Détecte pass:[] pass -> processor : Retourne HTML brut processor -> html : Insère sans transformation html -> html : Navigateur applique styles @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_实现">实现</h3> <div class="paragraph"> <p>这是要注入的HTML结构：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block; width:1em; height:1em; background:#7952b3; vertical-align:middle; margin-right:0.5em"> </span></code></pre> </div> </div> <div class="sect3"> <h4 id="_css属性的解释">CSS属性的解释</h4> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">属性</th> <th class="tableblock halign-left valign-top">功能</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>display:inline-block</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�允许设置 width/height 同时保持在行内流中</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>width:1em; height:1em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">方块的大小相对于字体的大小（响应式）</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>background:#7952b3</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">要显示的颜色（根据您的需求可变）</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>vertical-align:middle</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">将方块与相邻文本对齐</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>margin-right:0.5em</code></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">正方形与文本之间的间距</p></td> </tr> </tbody> </table> </div> </div> <div class="sect2"> <h3 id="_完整示例">完整示例</h3> <div class="paragraph"> <p>以下是一个记录主题调色板的示例：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">== Thème Clair * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)</code></pre> </div> </div> <div class="paragraph"> <p>谁生成以下渲染：</p> </div> <div class="paragraph"> <p>亮色主题</p> </div> <div class="ulist"> <ul> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span> --bg-primary:`#f8f9fa`(米白色)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span> --text-primary:`#212529`（极深的黑色）</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span> --accent-color:`#7952b3`(紫色 Bootstrap)</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span> --accent-hover:`#61428f`( 更深的紫色 )</p> </li> <li> <p><span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span> --card-bg:`#ffffff`(白色)</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_优化与最佳实践">优化与最佳实践</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_管理浅色">管理浅色</h3> <div class="paragraph"> <p>对于非常浅的颜色（白色，非常浅的灰色），添加一个边框以使其在白色背景上可见：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><span style="display:inline-block;width:1em;height:1em; background:#ffffff;border:1px solid #ccc; vertical-align:middle;margin-right:0.5em"></span></code></pre> </div> </div> <div class="paragraph"> <p>灰色边框 (<code>border:1px solid #ccc</code>) 允许在白色背景上勾勒出白色方框。</p> </div> </div> <div class="sect2"> <h3 id="_调整方块的大小">调整方块的大小</h3> <div class="paragraph"> <p>您可以根据需要调整方块的大小：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré * pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré</code></pre> </div> </div> <div class="paragraph"> <p>单元的使用`em`确保正方形适应字体大小。</p> </div> </div> <div class="sect2"> <h3 id="_创建变体">创建变体</h3> <div class="paragraph"> <p>对于特定需求，您可以创建不同的形式：</p> </div> <div class="sect3"> <h4 id="_彩色圆">彩色圆</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_带有彩色边框的正方形">带有彩色边框的正方形</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette</code></pre> </div> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_解决方案架构">解决方案架构</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="architecture-diagram.svg" alt="architecture diagram" width="1756" height="5432"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_优势和局限">�优势和局限</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_优势">优势</h3> <div class="ulist"> <ul> <li> <p><strong>自主性</strong>：不依赖于外部文件</p> </li> <li> <p>�✓ <strong>可移植性</strong> : 可与所有 AsciiDoc 处理器一起工作</p> </li> <li> <p>✓ <strong>同步</strong> : 颜色代码直接位于 HTML 中</p> </li> <li> <p>�✓ <strong>Flexibilité</strong> : 完全自定义样式</p> </li> <li> <p>✓ <strong>维护</strong> : 十六进制代码的简单修改</p> </li> <li> <p>✓ <strong>JBake 兼容性</strong> : 与静态站点生成器完美配合</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_限制">限制</h3> <div class="ulist"> <ul> <li> <p>�✗ <strong>冗长</strong> : AsciiDoc 源文件中的重复 HTML 代码</p> </li> <li> <p>✗ <strong>源文档可读性</strong> : 源文档较不精简</p> </li> <li> <p>✗ <strong>Accessibilité</strong> : 没有原生的替代文本（需要手动添加）</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_改善无障碍">改善无障碍</h3> <div class="paragraph"> <p>为了让方块对屏幕阅读器可访问：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* pass:[<span role="img" aria-label="Couleur violet Bootstrap" style="display:inline-block;width:1em;height:1em;background:#7952b3; vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)</code></pre> </div> </div> <div class="paragraph"> <p>属性`role="img"` et `aria-label`使辅助技术能够理解和描述视觉内容。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_具体示例主题文档">具体示例：主题文档</h2> <div class="sectionbody"> <div class="paragraph"> <p>这里有一个完整的示例，记录了多个主题：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Guide des couleurs de l'application == Thème Clair (`:root`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap) == Thème Sombre (`[data-bs-theme="dark"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap) == Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc) * pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>HTML注入通过宏``AsciiDoc 提供了一种优雅且实用的解决方案，用于在技术文档中显示颜色样本。尽管这种方法略显冗长，但它确保了最大程度的可移植性和简化的维护。</p> </div> <div class="paragraph"> <p>此技术不需要任何外部配置，也不需要额外的样式表，并且可以在 JBake 和所有标准的 AsciiDoc 处理器上立即使用。</p> </div> <div class="paragraph"> <p>一旦您创建了第一个彩色方块，只需复制粘贴 HTML 代码并修改十六进制代码，即可快速创建完整的调色板。</p> </div> <div class="paragraph"> <p>该技术可扩展至需要自定义视觉渲染的其他使用场景：图标、徽章、简单图表，或所有需要精确控制样式的视觉元素。</p> </div> </div> </div> <div class="sect1"> <h2 id="_资源">资源</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/" target="_blank" rel="noopener">文档 AsciiDoc : pass 宏</a></p> </li> <li> <p><a href="https://jbake.org/docs/2.6.7/" target="_blank" rel="noopener">JBake 文档</a></p> </li> <li> <p><a href="https://developer.mozilla.org/fr/docs/Web/CSS/color_value">MDN : CSS 颜色值</a></p> </li> </ul> </div> <div class="paragraph"> <p><em>文章发表于 2025-11-01</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html Mon, 20 Oct 2025 00:00:00 +0000 blog/2025/0095_i18n-site-statique-jbake-thymeleaf_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_介绍">介�绍</a> <ul class="sectlevel2"> <li><a href="#_用例图_use_case">用例图 (Use Case)</a></li> </ul> </li> <li><a href="#_国际化架构">国际化架构</a> <ul class="sectlevel2"> <li><a href="#_结构图文件组织">结构图（文件组织）</a></li> <li><a href="#_为什么采用这种方法">为什么采用这种方法？</a></li> <li><a href="#_组件图">组件图</a></li> </ul> </li> <li><a href="#_thymeleaf_模板国际化">Thymeleaf 模板国际化</a> <ul class="sectlevel2"> <li><a href="#_消息文件的结构">消息文件的结构</a></li> <li><a href="#_消息文件的内容">消息文件的内容</a></li> <li><a href="#_在模板中使用">在模板中使用</a></li> <li><a href="#_时序图_国际化解决方案">时序图 - 国际化解决方案</a></li> <li><a href="#_jbake_的语言环境配置">JBake 的语言环境配置</a></li> </ul> </li> <li><a href="#_文章国际化按文件夹组织">文章国际化：按文件夹组织</a> <ul class="sectlevel2"> <li><a href="#_流程图_flow_生成">流程图 (Flow) - 生成</a></li> <li><a href="#_文件夹结构">文件夹结构</a></li> <li><a href="#_这种方法的优势">这种方法的优势</a></li> <li><a href="#_文章的元数据">文章的元数据</a></li> <li><a href="#_url_配置">URL 配置</a></li> </ul> </li> <li><a href="#_多语言显示模板">多语言显示模板</a> <ul class="sectlevel2"> <li><a href="#_带有语言选择器的文章模板">带有语言选择器的文章模板</a></li> <li><a href="#_按语言过滤的索引">按语言过滤的索引</a></li> </ul> </li> <li><a href="#_语言之间的导航">语言之间的导航</a> <ul class="sectlevel2"> <li><a href="#_全局语言选择器">全局语言选择器</a></li> <li><a href="#_流程图_用户读取">流程图 - 用户读取</a></li> <li><a href="#_选择器的_css_样式">选择器的 CSS 样式</a></li> </ul> </li> <li><a href="#_按语言的_rss_订阅">按语言的 RSS 订阅</a></li> <li><a href="#_良好实践和技巧">良好实践和技巧</a> <ul class="sectlevel2"> <li><a href="#_1_文章标识符的一致性">1. 文章标识符的一致性</a></li> <li><a href="#_2_日期一致">2. 日期一致</a></li> <li><a href="#_3_多语言标签">3. 多语言标签</a></li> <li><a href="#_4_未翻译项目的管理">4. 未翻译项目的管理</a></li> <li><a href="#_5_多语言站点地图">5. 多语言站点地图</a></li> </ul> </li> <li><a href="#_结论">结论</a> <ul class="sectlevel2"> <li><a href="#_部署图">部署图</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介�绍</h2> <div class="sectionbody"> <div class="paragraph"> <p>静态网站的国际化（i18n）乍看起来可能很复杂，但JBake结合Thymeleaf提供了创建多语言站点的优雅解决方案。在本文中，我将展示我如何在我的博客上实现i18n，涵盖模板和多语言文章管理。</p> </div> <div class="sect2"> <h3 id="_用例图_use_case">用例图 (Use Case)</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-3dc0e253ecd651c64e5bd6780c5c0b5c.png" alt="Diagram" width="367" height="401"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_国际化架构">国际化架构</h2> <div class="sectionbody"> <div class="paragraph"> <p>我们的方法基于两个支柱：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>模板的国际化</strong>: 使用 Thymeleaf 消息文件用于界面元素</p> </li> <li> <p><strong>内容的 i18n</strong>按语言组织文章，放置在专用的文件夹结构中</p> </li> </ol> </div> <div class="sect2"> <h3 id="_结构图文件组织">结构图（文件组织）</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-2f100fc3ec2ec37f9556818cdc246602.png" alt="Diagram" width="188" height="513"> </div> </div> </div> <div class="sect2"> <h3 id="_为什么采用这种方法">为什么采用这种方法？</h3> <div class="paragraph"> <p>这种分离可以：</p> </div> <div class="ulist"> <ul> <li> <p>保持界面一致性，无论语言如何</p> </li> <li> <p>独立管理文章的内容和翻译</p> </li> <li> <p>简化添加新语言，无需进行大规模重构</p> </li> <li> <p>允许仅在特定语言中可用的文章</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_组件图">组件图</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-7317c50fde667b195d96b66ad65876d9.png" alt="Diagram" width="1771" height="477"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_thymeleaf_模板国际化">Thymeleaf 模板国际化</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_消息文件的结构">消息文件的结构</h3> <div class="paragraph"> <p>第一步是为每种支持的语言创建属性文件：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">src/jbake/templates/ ├── messages.properties # Fallback par défaut ├── messages_fr.properties # Français ├── messages_en.properties # Anglais └── messages_de.properties # Allemand</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_消息文件的内容">消息文件的内容</h3> <div class="paragraph"> <p>这是一个文件示例`messages_fr.properties`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Accueil nav.blog=Blog nav.about=À propos nav.contact=Contact # Articles article.readmore=Lire la suite article.published=Publié le article.tags=Étiquettes article.also.available=Également disponible en # Interface site.title=Mon Blog Technique site.description=Partage de connaissances et expériences footer.copyright=© 2025 Tous droits réservés search.placeholder=Rechercher un article...</code></pre> </div> </div> <div class="paragraph"> <p>以及其英语等价`messages_en.properties`：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Navigation nav.home=Home nav.blog=Blog nav.about=About nav.contact=Contact # Articles article.readmore=Read more article.published=Published on article.tags=Tags article.also.available=Also available in # Interface site.title=My Tech Blog site.description=Sharing knowledge and experiences footer.copyright=© 2025 All rights reserved search.placeholder=Search articles...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_在模板中使用">在模板中使用</h3> <div class="paragraph"> <p>在您的Thymeleaf模板中，使用语法`#{}`要访问消息 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> <meta name="description" th:content="#{site.description}" /> </head> <body> <nav> <a th:href="@{/}" th:text="#{nav.home}">Accueil</a> <a th:href="@{/blog/}" th:text="#{nav.blog}">Blog</a> <a th:href="@{/about.html}" th:text="#{nav.about}">À propos</a> </nav> <footer> <p th:text="#{footer.copyright}">Copyright</p> </footer> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_时序图_国际化解决方案">时序图 - 国际化解决方案</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 4) ] @startuml actor Auteur participant JBake participant "AsciiDoc ^^^^^ Syntax Error? (Assumed diagram type: sequence) @startuml actor Auteur participant JBake participant "AsciiDoc 解析器" as parser participant "Thymeleaf\n引擎" as thymeleaf participant "I18n 解析器" as i18n database "messages_*.properties" as messages Auteur -> JBake: jbake -b activate JBake JBake -> parser: Lire article.fr.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=fr, article-id=xyz) deactivate parser JBake -> parser: Lire article.en.adoc activate parser parser --> JBake: Contenu + métadonnées\n(lang=en, article-id=xyz) deactivate parser JBake -> thymeleaf: Générer page FR activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_fr.properties messages --> i18n: "首页" i18n --> thymeleaf: "首页" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=fr) JBake --> thymeleaf: article.en.html trouvé thymeleaf --> JBake: /fr/blog/article.html deactivate thymeleaf JBake -> thymeleaf: Générer page EN activate thymeleaf thymeleaf -> i18n: Résoudre #{nav.home} activate i18n i18n -> messages: Lire messages_en.properties messages --> i18n: "首页" i18n --> thymeleaf: "首页" deactivate i18n thymeleaf -> JBake: Rechercher traductions\n(article-id=xyz, lang!=en) JBake --> thymeleaf: article.fr.html trouvé thymeleaf --> JBake: /en/blog/article.html deactivate thymeleaf JBake --> Auteur: Site généré deactivate JBake @enduml</pre> </div> </div> </div> <div class="sect2"> <h3 id="_jbake_的语言环境配置">JBake 的语言环境配置</h3> <div class="paragraph"> <p>在您的文件中`jbake.properties`, 设置默认语言环境 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Locale par défaut thymeleaf.locale=fr # Encodage template.encoding=UTF-8</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_文章国际化按文件夹组织">文章国际化：按文件夹组织</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_流程图_flow_生成">流程图 (Flow) - 生成</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-2afbc0cd5fdf60b7aca5aa535a62f60e.png" alt="Diagram" width="285" height="1034"> </div> </div> </div> <div class="sect2"> <h3 id="_文件夹结构">文件夹结构</h3> <div class="paragraph"> <p>与其在文件名中使用后缀，我选择了按文件夹组织的方式，这样更清晰且易于维护：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">content/blog/ ├── 2024/ │ ├── fr/ │ │ ├── introduction-jbake.adoc │ │ ├── guide-thymeleaf.adoc │ │ └── astuces-asciidoc.adoc │ └── en/ │ ├── introduction-jbake.adoc │ ├── thymeleaf-guide.adoc │ └── asciidoc-tips.adoc └── 2025/ ├── fr/ │ └── internationalisation-jbake.adoc └── en/ └── jbake-internationalization.adoc</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_这种方法的优势">这种方法的优势</h3> <div class="paragraph"> <p>这种结构具有多个优势：</p> </div> <div class="ulist"> <ul> <li> <p><strong>清晰的分离</strong>: 每种语言都有自己的空间</p> </li> <li> <p><strong>灵活命名</strong>: 文件可以根据语言具有不同的名称</p> </li> <li> <p><strong>可扩展性</strong>: 容易添加一种新语言</p> </li> <li> <p><strong>自然组织</strong>: 遵循 JBake 的时间逻辑</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_文章的元数据">文章的元数据</h3> <div class="paragraph"> <p>每篇文章都必须包含元数据以允许翻译之间的链接。以下是一个示例：</p> </div> <div class="paragraph"> <p><strong>法文版</strong>(<code>2025/fr/internationalisation-jbake.adoc</code>) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalisation d'un site statique JBake :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: fr :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide pour mettre en place l'i18n avec JBake</code></pre> </div> </div> <div class="paragraph"> <p><strong>英文版本</strong>(<code>2025/en/jbake-internationalization.adoc</code>) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Internationalizing a JBake Static Site :jbake-type: post :jbake-status: published :jbake-date: 2025-10-20 :jbake-lang: en :jbake-article-id: jbake-i18n-thymeleaf :jbake-tags: jbake, thymeleaf, i18n :jbake-description: Guide to implement i18n with JBake</code></pre> </div> </div> <div class="paragraph"> <p>注意：该属性`:jbake-article-id:`至关重要：它能够将同一篇文章的不同译文关联起来。</p> </div> </div> <div class="sect2"> <h3 id="_url_配置">URL 配置</h3> <div class="paragraph"> <p>在`jbake.properties`, 配置 URL 模式以包含语言 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># Pattern d'URL avec langue post.permalink.pattern=:lang/blog/:year/:name.html # Langue par défaut site.default.lang=fr</code></pre> </div> </div> <div class="paragraph"> <p>这将生成如下形式的 URL：</p> </div> <div class="ulist"> <ul> <li> <p><code>/fr/blog/2025/internationalisation-jbake.html</code></p> </li> <li> <p><code>/en/blog/2025/jbake-internationalization.html</code></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_多语言显示模板">多语言显示模板</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_带有语言选择器的文章模板">带有语言选择器的文章模板</h3> <div class="paragraph"> <p>创建一个模板`post.html`显示可用翻译：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="${content.title}">Article</title> </head> <body> <article> <header> <h1 th:text="${content.title}">Titre</h1> <div class="article-meta"> <time th:text="${#dates.format(content.date, 'dd MMMM yyyy')}" th:attr="datetime=${#dates.format(content.date, 'yyyy-MM-dd')}"> Date </time> <!-- Sélecteur de traductions --> <div class="translations" th:if="${content['article-id']}"> <span th:text="#{article.also.available}">Aussi disponible en :</span> <ul class="language-list"> <li th:each="post : ${published_posts}" th:if="${post['article-id'] == content['article-id'] and post.lang != content.lang}"> <a th:href="${post.uri}" th:text="${post.lang.toUpperCase()}"> LANG </a> </li> </ul> </div> </div> </header> <div class="content" th:utext="${content.body}"> Contenu de l'article </div> <footer class="article-footer"> <div class="tags" th:if="${content.tags}"> <span th:text="#{article.tags}">Étiquettes :</span> <span th:each="tag : ${content.tags}"> <a th:href="@{/tags/{tag}.html(tag=${tag})}" th:text="${tag}">tag</a> </span> </div> </footer> </article> </body> </html></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_按语言过滤的索引">按语言过滤的索引</h3> <div class="paragraph"> <p>为每种语言创建索引模板：</p> </div> <div class="paragraph"> <p><strong>index.html</strong>(法文索引) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">Mon Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Titre</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Lire la suite </a> </article> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><strong>index_en.html</strong>(英文索引) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <title th:text="#{site.title}">My Blog</title> </head> <body> <main> <h1 th:text="#{nav.blog}">Blog</h1> <div class="articles-list"> <article th:each="post : ${published_posts}" th:if="${post.lang == 'en'}"> <h2> <a th:href="${post.uri}" th:text="${post.title}">Title</a> </h2> <time th:text="${#dates.format(post.date, 'dd MMMM yyyy')}"> Date </time> <p th:text="${post.description}">Description</p> <a th:href="${post.uri}" th:text="#{article.readmore}"> Read more </a> </article> </div> </main> </body> </html></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_语言之间的导航">语言之间的导航</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_全局语言选择器">全局语言选择器</h3> </div> <div class="sect2"> <h3 id="_流程图_用户读取">流程图 - 用户读取</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-35c457cfbd1b9be0156f6bbbfb2925d1.png" alt="Diagram" width="494" height="761"> </div> </div> <div class="paragraph"> <p>在你的主模板中添加语言选择器：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><nav class="language-switcher"> <a href="/index.html" th:classappend="${content.lang == 'fr'} ? 'active'" title="Français"> 🇫🇷 FR </a> <a href="/en/index.html" th:classappend="${content.lang == 'en'} ? 'active'" title="English"> 🇬🇧 EN </a> </nav></code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_选择器的_css_样式">选择器的 CSS 样式</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.language-switcher { display: flex; gap: 1rem; padding: 0.5rem; background: #f5f5f5; border-radius: 4px; } .language-switcher a { padding: 0.5rem 1rem; text-decoration: none; color: #333; border-radius: 4px; transition: background 0.2s; } .language-switcher a:hover { background: #e0e0e0; } .language-switcher a.active { background: #007bff; color: white; } .translations { margin: 1rem 0; padding: 1rem; background: #f8f9fa; border-left: 4px solid #007bff; } .language-list { display: inline-flex; gap: 0.5rem; list-style: none; padding: 0; margin: 0; } .language-list li::after { content: "•"; margin-left: 0.5rem; } .language-list li:last-child::after { content: ""; }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_按语言的_rss_订阅">按语言的 RSS 订阅</h2> <div class="sectionbody"> <div class="paragraph"> <p>要获得按语言分离的 RSS 源，请创建单独的模板：</p> </div> <div class="paragraph"> <p><strong>feed.xml</strong>(法语流) :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:th="http://www.thymeleaf.org"> <channel> <title th:text="#{site.title}">Mon Blog</title> <link th:text="${config.site_host}">http://example.com</link> <description th:text="#{site.description}">Description</description> <language>fr</language> <item th:each="post : ${published_posts}" th:if="${post.lang == 'fr'}"> <title th:text="${post.title}">Titre</title> <link th:text="${config.site_host + post.uri}">Lien</link> <pubDate th:text="${#dates.format(post.date, 'EEE, dd MMM yyyy HH:mm:ss Z')}"> Date </pubDate> <description th:text="${post.description}">Description</description> </item> </channel> </rss></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_良好实践和技巧">良好实践和技巧</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_1_文章标识符的一致性">1. 文章标识符的一致性</h3> <div class="paragraph"> <p>请确保`:jbake-article-id:`对于同一文章的所有翻译都是相同的。 请使用一致的格式：</p> </div> <div class="ulist"> <ul> <li> <p>请使用英文标识符以实现通用性</p> </li> <li> <p>使用短横线来分隔单词</p> </li> <li> <p>避免使用特殊字符</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_2_日期一致">2. 日期一致</h3> <div class="paragraph"> <p>一篇文章的所有翻译必须有相同的出版日期`:jbake-date:`). 这有助于排序和按时间顺序显示。</p> </div> </div> <div class="sect2"> <h3 id="_3_多语言标签">3. 多语言标签</h3> <div class="paragraph"> <p>对于标签，您有两种选择：</p> </div> <div class="paragraph"> <p><strong>选项1：通用英文标签</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> <div class="paragraph"> <p><strong>选项 2：使用映射翻译的标签</strong></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc"># Version française :jbake-tags: java, spring-boot, microservices # Version anglaise :jbake-tags: java, spring-boot, microservices</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_未翻译项目的管理">4. 未翻译项目的管理</h3> <div class="paragraph"> <p>不需要翻译所有文章。如果某篇文章只存在于一种语言中，它将不会出现在另一种语言的列表中。</p> </div> </div> <div class="sect2"> <h3 id="_5_多语言站点地图">5. 多语言站点地图</h3> <div class="paragraph"> <p>生成一个包含所有语言的站点地图：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml"><?xml version="1.0" encoding="UTF-8"?> <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org"> <url th:each="post : ${published_posts}"> <loc th:text="${config.site_host + post.uri}">URL</loc> <lastmod th:text="${#dates.format(post.date, 'yyyy-MM-dd')}">Date</lastmod> <!-- Liens alternatifs pour les traductions --> <xhtml:link th:each="translation : ${published_posts}" th:if="${translation['article-id'] == post['article-id'] and translation.lang != post.lang}" rel="alternate" th:attr="hreflang=${translation.lang},href=${config.site_host + translation.uri}" /> </url> </urlset></code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>使用 Thymeleaf 对 JBake 站点进行国际化是一种健壮且可维护的方法。通过将 i18n 与模板分离（通过消息文件）以及将内容的 i18n 通过目录组织来分离，您可以获得一个灵活、易于演进的系统。</p> </div> <div class="paragraph"> <p>要点如下：</p> </div> <div class="ulist"> <ul> <li> <p><strong>Thymeleaf 消息文件</strong>对于用户界面</p> </li> <li> <p><strong>按文件夹组织</strong>(年/语言) 用于文章</p> </li> <li> <p><strong>文章标识符</strong>用于链接翻译</p> </li> <li> <p><strong>专用模板</strong>对于每种语言</p> </li> <li> <p><strong>显式 URL</strong>包含语言代码</p> </li> </ul> </div> <div class="sect2"> <h3 id="_部署图">部署图</h3> <div class="listingblock"> <div class="content"> <pre>Failed to generate image: PlantUML preprocessing failed: [From <input> (line 15) ] @startuml node "开发机器" { artifact "来源" { folder "content/" folder "模板/" folder "资产/" } component "JBake 命令行界面" as jbake Sources --> jbake : jbake -b } node "构建服务器\n(CI/CD)" { component "GitHub Actions ^^^^^ Syntax Error? (Assumed diagram type: component) @startuml node "开发机器" { artifact "来源" { folder "content/" folder "模板/" folder "资产/" } component "JBake 命令行界面" as jbake Sources --> jbake : jbake -b } node "构建服务器\n(CI/CD)" { component "GitHub Actions 或 GitLab CI" as ci jbake --> ci : push } cloud "CDN / 托管" { node "静态Web服务器" { artifact "已生成的网站" { folder "/fr/blog/" folder "/en/blog/" folder "/assets/" } } } ci --> "已生成的网站" : déploiement actor "读者" as users users --> "静态Web服务器" : HTTPS @enduml</pre> </div> </div> <div class="paragraph"> <p>这种架构让您可以简单地使用两种语言开始，并且可以在不进行大规模重构的情况下添加更多语言。整个系统保持完全静态且高性能，忠实于JBake的理念。</p> </div> <div class="paragraph"> <p>祝您多语言开发顺利！🌍</p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0094_tor_browser_install_post.html Sun, 5 Oct 2025 00:00:00 +0000 blog/2025/0094_tor_browser_install_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_简介">简介</a></li> <li><a href="#_下载_tor_及其签名">下载 Tor 及其签名</a></li> <li><a href="#_签名的加密验证">签名的加密验证</a> <ul class="sectlevel2"> <li><a href="#_导入_tor_项目的公钥">导入 Tor 项目的公钥</a></li> <li><a href="#_2_检查签名">2. 检查签名</a></li> <li><a href="#_实践案例签名有效但密钥未认证">实践案例：签名有效但密钥未认证</a></li> </ul> </li> <li><a href="#_为什么要验证签名">为什么要验证签名？</a></li> <li><a href="#_提取和启动_tor_browser">提取和启动 Tor Browser</a></li> <li><a href="#_集成到ubuntu桌面">集成到Ubuntu桌面</a></li> <li><a href="#_使用tor探索教育资源">使用Tor探索教育资源</a></li> <li><a href="#_tor_浏览器更新">Tor 浏览器更新</a></li> <li><a href="#_结论">结论</a></li> <li><a href="#_参考文献">参考文献</a></li> </ul> </div> <div class="sect1"> <h2 id="_简介">简介</h2> <div class="sectionbody"> <div class="paragraph"> <p>在一个数字隐私日益受到威胁的世界里，<strong>Tor Browser</strong> 仍然是保护匿名和信息自由的重要工具。 然而，执行下载的软件而不先有 是至关重要的<strong>验证了其真实性</strong>。 本文介绍了一种完整的方法：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>下载 <strong>Tor Browser</strong> 及其签名`.asc`</p> </li> <li> <p>验证下载文件的有效性</p> </li> <li> <p>在 Ubuntu 上安装并启动 <strong>Tor Browser</strong></p> </li> <li> <p>将其添加到桌面菜单以供日常使用</p> </li> <li> <p>通过 Tor 探索教育资源和道德的 OSINT</p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_下载_tor_及其签名">下载 Tor 及其签名</h2> <div class="sectionbody"> <div class="paragraph"> <p>为Tor浏览器创建一个专用文件夹：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">mkdir -p ~/workspace/tipiak/tor cd ~/workspace/tipiak/tor</code></pre> </div> </div> <div class="paragraph"> <p>然后下载Tor浏览器的归档文件及其签名：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz wget https://www.torproject.org/dist/torbrowser/14.5.7/tor-browser-linux-x86_64-14.5.7.tar.xz.asc</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_签名的加密验证">签名的加密验证</h2> <div class="sectionbody"> <div class="paragraph"> <p>此步骤是<strong>必不可少的</strong>为了确保下载的文件确实来自 <strong>Tor Project</strong> 并且未被修改。</p> </div> <div class="sect2"> <h3 id="_导入_tor_项目的公钥">导入 Tor 项目的公钥</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --auto-key-locate nodefault,wkd --locate-keys torbrowser@torproject.org</code></pre> </div> </div> <div class="paragraph"> <p>�检查密钥是否已正确导入：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --list-keys torbrowser@torproject.org</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_检查签名">2. 检查签名</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz</code></pre> </div> </div> <div class="paragraph"> <p>如果一切正确，将显示以下消息：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg: Good signature from "Tor Browser Developers (signing key)"</code></pre> </div> </div> <div class="paragraph"> <p>如果出现未认证密钥警告，这仅仅意味着您尚未签署 Tor 项目的可信密钥，但该签名仍然有效。</p> </div> </div> <div class="sect2"> <h3 id="_实践案例签名有效但密钥未认证">实践案例：签名有效但密钥未认证</h3> <div class="paragraph"> <p>在验证过程中，经常会遇到这样的消息：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">gpg --verify tor-browser-linux-x86_64-14.5.7.tar.xz.asc tor-browser-linux-x86_64-14.5.7.tar.xz gpg: Signature faite le mar. 16 sept. 2025 14:26:26 CEST gpg: avec la clef RSA CAAE408AEBE2288E96FC5D5E157432CF78A65729 gpg: Bonne signature de « Tor Browser Developers (signing key) <torbrowser@torproject.org> » [inconnu] gpg: Attention : cette clef n'est pas certifiée avec une signature de confiance. gpg: Rien n'indique que la signature appartient à son propriétaire. Empreinte de clef principale : EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290 Empreinte de la sous-clef : CAAE 408A EBE2 288E 96FC 5D5E 1574 32CF 78A6 5729</code></pre> </div> </div> <div class="paragraph"> <p>此消息表明签名在技术上是“有效的”（文件未被修改），但您的 GPG 系统无法 <strong>验证对该密钥本身的信任</strong>。为了消除此疑虑，必须比较主密钥的指纹 (<code>EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290</code>) 与Tor Project官方网站上发布的内容相同。</p> </div> <div class="paragraph"> <p>根据官方网站，预期的指纹是：<code>EF6E286DDA85EA2A4BA7DE684E2C6E8793298290</code>。</p> </div> <div class="paragraph"> <p>由于显示的印记由`gpg`如果它*完全*对应于官方网站的那个，您可以确定密钥是合法的且文件是安全的。‘未认证密钥’的警告则是关于您本地 GPG 配置的信息，而非关于签名的有效性或文件的真实性。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_为什么要验证签名">为什么要验证签名？</h2> <div class="sectionbody"> <div class="paragraph"> <p>验证 GPG 签名是数字安全的基本行为。 它可以：</p> </div> <div class="ulist"> <ul> <li> <p>保证<strong>真实性</strong>已下载的软件</p> </li> <li> <p>防止受恶意行为者破坏的文件被安装</p> </li> <li> <p>参加<strong>数字主权</strong>个体的</p> </li> <li> <p>�促进负责任且符合伦理的数字文化</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="usecase-tor-verification.svg" alt="usecase tor verification" width="270" height="211"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_提取和启动_tor_browser">提取和启动 Tor Browser</h2> <div class="sectionbody"> <div class="paragraph"> <p>解压已下载的压缩包：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">tar -xvf tor-browser-linux-x86_64-14.5.7.tar.xz cd tor-browser</code></pre> </div> </div> <div class="paragraph"> <p>然后启动浏览器：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>首次启动时，将打开一个配置窗口以建立与Tor网络的连接。</p> </div> </div> </div> <div class="sect1"> <h2 id="_集成到ubuntu桌面">集成到Ubuntu桌面</h2> <div class="sectionbody"> <div class="paragraph"> <p>要将 <strong>Tor Browser</strong> 添加到应用程序菜单：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">./start-tor-browser.desktop --register-app</code></pre> </div> </div> <div class="paragraph"> <p>您 可以 然后 :</p> </div> <div class="ulist"> <ul> <li> <p>从应用程序菜单启动 <strong>Tor Browser</strong></p> </li> <li> <p>将其添加到 Dock 收藏夹</p> </li> <li> <p>如需，创建快捷键</p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="activity-tor-installation.svg" alt="activity tor installation" width="457" height="470"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用tor探索教育资源">使用Tor探索教育资源</h2> <div class="sectionbody"> <div class="paragraph"> <p>Tor 不仅仅是一个匿名工具。 它是一个通往教育和科研资源的门户，尤其在以下领域：</p> </div> <div class="ulist"> <ul> <li> <p><strong>开源情报（Open Source Intelligence）</strong></p> </li> <li> <p><a href="https://inteltechniques.com">https://inteltechniques.com</a></p> </li> <li> <p><a href="https://osintframework.com">https://osintframework.com</a></p> </li> <li> <p><strong>教育共享和开源</strong></p> </li> <li> <p><a href="https://archive.org">https://archive.org</a>(通过 Tor 访问以获得更高的隐私)</p> </li> <li> <p><a href="https://github.com/">https://github.com/</a>(可通过 Tor 访问)</p> </li> <li> <p><a href="https://librarygenesis.pro">https://librarygenesis.pro</a>(开放获取科学文献)</p> </li> <li> <p><strong>知识的传播与对数字社会中人类的理解</strong></p> </li> <li> <p>关于数字文化、言论自由和获取知识的资源</p> </li> <li> <p>自由的网络安全和技术伦理文档</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_tor_浏览器更新">Tor 浏览器更新</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了确保最佳安全性，保持 <strong>Tor Browser</strong> 更新至关重要。浏览器内置了一个可以通过命令行触发的自动更新机制。</p> </div> <div class="paragraph"> <p>从 Tor Browser 安装目录，只需重新启动启动脚本：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">cd ~/workspace/tipiak/tor/tor-browser ./start-tor-browser.desktop</code></pre> </div> </div> <div class="paragraph"> <p>启动时，<strong>Tor Browser</strong> 会自动检查是否有新版本。如果有，它会为您下载并安装。</p> </div> <div class="paragraph"> <p>这种简单的方法可确保您始终拥有最新的安全补丁和最新的改进，这对于安全浏览至关重要。</p> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>检查自己的下载是所有希望在安全数字环境中前进的人必不可少的习惯。 以验证的方式安装 Tor，这是<strong>保护其数字完整性</strong>, <strong>保持对自由软件的信任</strong>, et <strong>加强其信息自主性</strong>.</p> </div> <div class="paragraph"> <p>数字安全是良知的行为，而非偏执。</p> </div> <div class="imageblock"> <div class="content"> <img src="summary-diagram.svg" alt="summary diagram" width="1578" height="5348"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_参考文献">参考文献</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Tor 项目官方网站 :https://www.torproject.org/download/[<a href="https://www.torproject.org/download/" class="bare">https://www.torproject.org/download/</a>]</p> </li> <li> <p>签名验证文档：https://support.torproject.org/tbb/how-to-verify-signature/[<a href="https://support.torproject.org/tbb/how-to-verify-signature/" class="bare">https://support.torproject.org/tbb/how-to-verify-signature/</a>]</p> </li> <li> <p>Ubuntu 文档：https://ubuntu.com[<a href="https://ubuntu.com" class="bare">https://ubuntu.com</a>]</p> </li> <li> <p>教育档案：https://archive.org/details/opensource[<a href="https://archive.org/details/opensource" class="bare">https://archive.org/details/opensource</a>]</p> </li> </ul> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>本文属于 <strong>安全与数字意识</strong> 系列 旨在推广负责任且富有教育意义的做法 �围绕自由工具。</p> </div> </td> </tr> </table> </div> </div> </div> https://cheroliv.com/blog/2025/0093_gradle_plugin_toml_composite_build_post.html Sat, 27 Sep 2025 00:00:00 +0000 blog/2025/0093_gradle_plugin_toml_composite_build_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_1_版本目录_libs_versions_toml_一个提醒">1. 版本目录 (<code>libs.versions.toml</code>) : 一个提醒</a></li> <li><a href="#_2_问题复合构建与两个独立的世界">2. 问题：复合构建与两个独立的世界</a></li> <li><a href="#_3_解决方案共享依赖解析">3. 解决方案：共享依赖解析</a></li> <li><a href="#_4_结论管理良好的组合构建的力量">4. 结论：管理良好的组合构建的力量</a></li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">目标受众：面对多项目构建依赖管理挑战的 Gradle 开发者。</div> <p>在我们创建插件的追求中`site-baker`我们一直致力于保持代码库的整洁和集中化。现代 Gradle 生态系统中最佳实践之一是使用<strong>版本目录</strong>(<code>libs.versions.toml</code>) 用于管理依赖项。但是当你的项目变得更复杂时，会发生什么情况，例如一个<strong>构建复合</strong>在哪里需要将一个独立的构建（我们的插件）包含在另一个构建中？</p> </div> <div class="paragraph"> <p>正是在这里，我们的冒险迎来了意想不到的转折。我们希望我们的插件`site-baker`, 它本身是一个 Gradle 项目，使用与我们主项目相同的版本目录。本文是我们系列的第五篇，讲述了我们如何解决了这个挑战。</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_版本目录_libs_versions_toml_一个提醒">1. 版本目录 (<code>libs.versions.toml</code>) : 一个提醒</h2> <div class="sectionbody"> <div class="paragraph"> <p>文件`gradle/libs.versions.toml`是Gradle的一项功能，用于集中管理项目依赖的版本和坐标。它通常被结构为四个部分：</p> </div> <div class="ulist"> <ul> <li> <p><code>[versions]</code>: 为版本号定义别名（例如：<code>kotlin = "1.9.20"</code>).</p> </li> <li> <p><code>[libraries]`定义完整依赖项的别名，使用上面定义的版本 （例如：`kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }</code>).</p> </li> <li> <p><code>[bundles]</code>: 将多个库归组到一个别名下 (ex:`jackson = ["jackson-core", "jackson-databind"]`).</p> </li> <li> <p><code>[plugins]</code>: 为 Gradle 插件设置别名。</p> </li> </ul> </div> <div class="paragraph"> <p>一旦定义，Gradle 会自动生成类型化的访问器，这使得您的`build.gradle.kts`更易读：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">dependencies { // Au lieu de : implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.20") implementation(libs.kotlin.stdlib) }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="toml-flow.svg" alt="toml flow" width="244" height="252"> </div> <div class="title">Figure 1. 版本目录的数据流</div> </div> </div> </div> <div class="sect1"> <h2 id="_2_问题复合构建与两个独立的世界">2. 问题：复合构建与两个独立的世界</h2> <div class="sectionbody"> <div class="paragraph"> <p>我们的项目结构是一个<strong>构建复合体</strong>. 主要项目 (<code>thymeleaf.cheroliv.com</code>) 包含插件项目 (<code>site-baker</code>) 通过命令`includeBuild("site-baker")<code>在文件中`settings.gradle.kts</code>.</p> </div> <div class="imageblock"> <div class="content"> <img src="composite-build.svg" alt="composite build" width="1592" height="5708"> </div> <div class="title">Figure 2. 复合构建的结构</div> </div> <div class="paragraph"> <p>问题是，默认情况下，一个包含的构建是一个<strong>独立的世界</strong>. 它有自己的配置，自己的生命周期，并且它看不到该文件`libs.versions.toml`主构建。 我们的`plugin/build.gradle.kts`试图使用`libs.plugins.kotlin.jvm`, 但该对象`libs`它不是从正确的 TOML 文件生成的，导致构建错误。</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_解决方案共享依赖解析">3. 解决方案：共享依赖解析</h2> <div class="sectionbody"> <div class="paragraph"> <p>经过多次研究，解决方案被证明是Gradle专为这种情况设计的功能：<code>dependencyResolutionManagement</code>。</p> </div> <div class="paragraph"> <p>在文件中`settings.gradle.kts` du <strong>构建包容</strong>(<code>site-baker/settings.gradle.kts</code>), 我们可以告诉 Gradle 在哪里找到要使用的版本目录。</p> </div> <div class="paragraph"> <p>以下是我们添加的配置`site-baker/settings.gradle.kts`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// site-baker/settings.gradle.kts dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { gradlePluginPortal() mavenCentral() } versionCatalogs { create("libs") { from(files("../gradle/libs.versions.toml")) } } } rootProject.name = "site-baker" include("plugin")</code></pre> </div> </div> <div class="paragraph"> <p>让我们分析关键部分 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">versionCatalogs { create("libs") { // Crée un catalogue nommé 'libs' from(files("../gradle/libs.versions.toml")) // En utilisant ce fichier } }</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>create("libs")</code>: 我们声明一个版本目录，将可通过别名访问`libs`。</p> </li> <li> <p><code>from(files("../gradle/libs.versions.toml"))</code>: 这就是魔法。我们告诉 Gradle 此目录的来源是位于该目录下的 TOML 文件`gradle` du <strong>父项目</strong>(</p> </li> </ul> </div> <div class="paragraph"> <p></think> (<code>../</code>)</p> </div> <div class="paragraph"> <p>使用此配置，构建`site-baker`现在他知道他必须使用主项目的版本目录。对象`libs`已正确生成，并且依赖关系按预期解决。</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_结论管理良好的组合构建的力量">4. 结论：管理良好的组合构建的力量</h2> <div class="sectionbody"> <div class="paragraph"> <p>这段经历非常充实。版本目录是提高可维护性的绝佳工具，但在复合构建场景中的行为并不总是直观。</p> </div> <div class="paragraph"> <p>关键是要记住，被包含的构建仍然是一个独立的构建。要共享诸如版本目录之类的配置，必须使用 Gradle 提供的显式机制，例如代码块。<code>dependencyResolutionManagement`在`settings.gradle.kts</code>.</p> </div> <div class="paragraph"> <p>通过解决此问题，我们不仅使构建更加整洁，还增强了项目的一致性，确保插件和主项目共享唯一的事实来源来管理它们的依赖项。</p> </div> <div class="paragraph"> <p>在下一篇文章中，我们将在现有插件的基础上继续添加更复杂的任务来丰富它，因为现在我们的依赖管理已经很稳固且集中。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0092_gradle_configuration_cache_post.html Fri, 26 Sep 2025 00:00:00 +0000 blog/2025/0092_gradle_configuration_cache_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_引言">引言</a></li> <li><a href="#_症状幽灵构建">�症状：幽灵构建</a></li> <li><a href="#_调查配置缓存是什么">调查：配置缓存是什么？</a></li> <li><a href="#_问题的原因不合规的插件">问题的原因：不合规的插件</a></li> <li><a href="#_临时解决方案禁用缓存">临时解决方案：禁用缓存</a></li> <li><a href="#_真正的解决方案使插件兼容">真正的解决方案：使插件兼容</a></li> </ul> </div> <div class="sect1"> <h2 id="_引言">引言</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">目标受众：Gradle开发者曾经遇到过’神奇的’或意外的构建行为.</div> <p>在我们创建插件的历程中`site-baker`, 我们遵循了严格的TDD方法。每个功能都进行了测试、验证，并且我们充满信心地前进。然后有一天，意外到来。构建开始表现得反复无常。插件逻辑或配置文件的修改似乎被忽略，而我们之前可靠的功能测试莫名其妙地失败了。</p> </div> <div class="paragraph"> <p>这种问题可能会令人极度沮丧。它质疑了工具的可靠性和我们代码的有效性。经过一次激烈的调试会话后，罪魁祸首被确定为：<strong>Gradle 配置缓存</strong>.</p> </div> </div> </div> <div class="sect1"> <h2 id="_症状幽灵构建">�症状：幽灵构建</h2> <div class="sectionbody"> <div class="paragraph"> <p>问题以多种方式表现出来：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>我在一项任务中修改字符串`println`, 但旧的字符串在运行时仍然显示。</p> </li> <li> <p>我当时正在更改我的文件中的一个值`managed-jbake-context.yml`, 但插件的行为就像文件没有被修改一样。</p> </li> <li> <p>功能测试会即时创建测试项目，但它们失败了，因为插件似乎没有检测到新创建的配置文件。</p> </li> </ol> </div> <div class="paragraph"> <p>一切都好像 Gradle 在执行我们构建的一个“幻影版本”，忽略了我们最近的更改。</p> </div> </div> </div> <div class="sect1"> <h2 id="_调查配置缓存是什么">调查：配置缓存是什么？</h2> <div class="sectionbody"> <div class="paragraph"> <p>配置缓存是 Gradle 相对现代且功能极其强大的特性，在新版本中默认启用。其目标是让构建更快。</p> </div> <div class="olist arabic"> <div class="title">原则很简单：</div> <ol class="arabic"> <li> <p>在第一次执行时，Gradle 执行阶段<strong>配置</strong>( 读取 的)<code>build.gradle.kts</code>, 创建任务，解析依赖) 并构建任务图。</p> </li> <li> <p>在此阶段结束时，Gradle<strong>序列化此任务图</strong>并将其缓存。</p> </li> <li> <p>在随后的执行中，如果没有任何更改（构建脚本`gradle.properties`, etc.), Gradle<strong>完全跳过配置阶段</strong>并重新使用缓存的任务图。</p> </li> </ol> </div> <div class="paragraph"> <p>在大型项目中，时间节约效果惊人。然而，这种性能有代价：它对插件的编写方式提出了严格的要求。</p> </div> <div class="imageblock"> <div class="content"> <img src="config-cache-lifecycle.svg" alt="config cache lifecycle" width="661" height="709"> </div> <div class="title">Figure 1. 配置缓存的生命周期</div> </div> </div> </div> <div class="sect1"> <h2 id="_问题的原因不合规的插件">问题的原因：不合规的插件</h2> <div class="sectionbody"> <div class="paragraph"> <p>我们的插件`site-baker`不知不觉地违反了配置缓存的若干规则。 为了使任务图可序列化，任务不得包含对复杂对象（如对象）的引用`Project`或以任意方式读取文件，在执行阶段。</p> </div> <div class="paragraph"> <p>我们的主要错误是在任务执行逻辑内直接读取 YAML 文件的内容，使用我们扩展中存储的路径引用。这种方法与缓存不兼容，因为如果这种读取未被建模为一个，Gradle 无法知道文件内容是否已更改。<strong>任务条目</strong>(任务输入).</p> </div> </div> </div> <div class="sect1"> <h2 id="_临时解决方案禁用缓存">临时解决方案：禁用缓存</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了使我们摆脱困境并恢复可预测的构建行为，最快的解决方案是禁用配置缓存。只需在文件中添加以下行即可。<code>gradle.properties`使用该插件的项目（或者在我们的情况下，是测试项目）`site-baker</code>).</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-properties hljs" data-lang="properties"># site-baker/gradle.properties org.gradle.configuration-cache=false</code></pre> </div> </div> <div class="paragraph"> <p>瞬间，构建恢复了正常行为。每次执行都重新启动了配置阶段，我们的更改被考虑在内。</p> </div> <div class="paragraph"> <p>然而，这是一个变通的解决方案，而不是一个持久的解决方案。它牺牲了性能，也没有解决我们插件的根本问题。</p> </div> </div> </div> <div class="sect1"> <h2 id="_真正的解决方案使插件兼容">真正的解决方案：使插件兼容</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了让插件成为现代 Gradle 生态系统的良好公民，它必须与配置缓存兼容。这意味着我们需要重新思考数据如何流向我们的任务。</p> </div> <div class="paragraph"> <p>关键是使用<strong>提供方 API</strong>Gradle的。 而不是直接传递值（如一个)<code>String</code> ou un <code>File</code>) 对于我们的任务，我们必须花费`Property<T>`或一些`Provider<T>`。</p> </div> <div class="olist arabic"> <div class="title">以下是重构计划：</div> <ol class="arabic"> <li> <p><strong>声明任务条目：</strong>解析 YAML 文件的任务必须将该文件声明为输入。为此，我们使用该注解。<code>@InputFile</code>。</p> </li> </ol> </div> <div class="paragraph"> <p>[source,kotlin] ---- @get:InputFile abstract val configFile: RegularFileProperty ----</p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0091_jackson_yaml_tdd_post.html Thu, 25 Sep 2025 00:00:00 +0000 blog/2025/0091_jackson_yaml_tdd_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_1_上下文我们的插件_site_baker">1. 上下文：我们的插件 `site-baker</a></li> <li><a href="#_2_kotlin_中的配置建模">2. Kotlin 中的配置建模</a></li> <li><a href="#_3_在_build_gradle_kts_中集成_jackson">3. 在 <code>build.gradle.kts</code> 中集成 Jackson</a></li> <li><a href="#_4_tdd方法测试yaml解析">4. TDD方法：测试YAML解析</a> <ul class="sectlevel2"> <li><a href="#_4_1_单元测试_将_yaml_映射为_kotlin_对象">4.1. 单元测试 : 将 YAML 映射为 Kotlin 对象</a></li> <li><a href="#_4_2_功能测试验证配置文件的读取">4.2. 功能测试：验证配置文件的读取</a></li> </ul> </li> <li><a href="#_5_解析流可视化">5. 解析流可视化</a></li> <li><a href="#_结论">结论</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>阅读时间 :</em> 12 分钟。</div> <p>目标受众：希望管理复杂配置的中级 Gradle 开发者。</p> </div> </div> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <p>在开发Gradle插件时，管理复杂配置是一项常见任务。与其在DSL中堆砌数百个属性，不如将配置定义在外部文件中（如YAML）更为简洁且易于维护。本文将引导您使用强大的Jackson库将YAML文件解析为Kotlin对象，并采用严格的TDD方法以确保插件的健壮性。<code>site-baker</code>。</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_上下文我们的插件_site_baker">1. 上下文：我们的插件 `site-baker</h2> <div class="sectionbody"> <div class="paragraph"> <p>我们的插件`site-baker`旨在自动化静态站点的生成和部署。它需要读取一个 YAML 配置文件 (<code>managed-jbake-context.yml</code>) 以获取诸如源代码路径、部署目标和 Git 标识符等信息。</p> </div> <div class="paragraph"> <p>我们希望解析的YAML配置看起来像这样：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" cname: "cheroliv.com" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/pages-content.github.io.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com" # ... autres configurations (pushMaquette, supabase, etc.)</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_2_kotlin_中的配置建模">2. Kotlin 中的配置建模</h2> <div class="sectionbody"> <div class="paragraph"> <p>在解析之前，我们需要用 Kotlin 定义数据的结构。Jackson 将使用这些类自动映射 YAML 内容。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/main/kotlin/com/cheroliv/site/baker/data/SiteConfiguration.kt package com.cheroliv.site.baker.data import com.fasterxml.jackson.databind.ObjectMapper import com.fasterxml.jackson.dataformat.yaml.YAMLFactory import com.fasterxml.jackson.module.kotlin.readValue import com.fasterxml.jackson.module.kotlin.registerKotlinModule fun parseSiteConfiguration(yaml: String): SiteConfiguration { val mapper = ObjectMapper(YAMLFactory()).registerKotlinModule() return mapper.readValue(yaml) } data class GitPushConfiguration( val from: String = "", val to: String = "", val repo: RepositoryConfiguration = RepositoryConfiguration(), val branch: String = "", val message: String = "", ) data class RepositoryConfiguration( val name: String = "", val repository: String = "", val credentials: RepositoryCredentials = RepositoryCredentials(), ) { companion object { const val ORIGIN = "origin" const val CNAME = "CNAME" const val REMOTE = "remote" } } data class RepositoryCredentials(val username: String = "", val password: String = "") data class SiteConfiguration( val bake: BakeConfiguration = BakeConfiguration(), val pushPage: GitPushConfiguration = GitPushConfiguration(), val pushMaquette: GitPushConfiguration = GitPushConfiguration(), val pushSource: GitPushConfiguration? = null, val pushTemplate: GitPushConfiguration? = null, val supabase: SupabaseContactFormConfig? = null ) data class BakeConfiguration( val srcPath: String = "", val destDirPath: String = "", val cname: String? = null, ) // ... (autres data classes pour Supabase, si nécessaire)</code></pre> </div> </div> <div class="paragraph"> <p>函数`parseSiteConfiguration`这是我们的反序列化入口点。它使用`ObjectMapper`Jackson 的, 配置为`YAMLFactory`用于 YAML 格式和`registerKotlinModule()`用于支持 Kotlin 的特性（如属性的默认值）。</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_在_build_gradle_kts_中集成_jackson">3. 在 <code>build.gradle.kts</code> 中集成 Jackson</h2> <div class="sectionbody"> <div class="paragraph"> <p>要使用 Jackson，我们需要在 中添加必要的依赖项`build.gradle.kts`我们的模块的`plugin`[Empty string]</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/build.gradle.kts dependencies { // Jackson for YAML parsing implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3") implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.18.3") // ... autres dépendances }</code></pre> </div> </div> <div class="paragraph"> <p>我们使用`jackson-module-kotlin`用于 Kotlin 支持和`jackson-dataformat-yaml`用于管理 YAML 格式。</p> </div> </div> </div> <div class="sect1"> <h2 id="_4_tdd方法测试yaml解析">4. TDD方法：测试YAML解析</h2> <div class="sectionbody"> <div class="paragraph"> <p>现在，让我们应用TDD来验证我们的解析逻辑。</p> </div> <div class="sect2"> <h3 id="_4_1_单元测试_将_yaml_映射为_kotlin_对象">4.1. 单元测试 : 将 YAML 映射为 Kotlin 对象</h3> <div class="paragraph"> <p>我们从单元测试开始，在`SiteBakerPluginTest.kt`为验证该函数`parseSiteConfiguration`可以正确地将 YAML 字符串转换为对象`SiteConfiguration`。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/test/kotlin/com/cheroliv/site/baker/SiteBakerPluginTest.kt @Test fun `can map configuration text to SiteConfiguration object`() { val yamlString = "../../managed-jbake-context.yml" .run(::File) .readText() .trimIndent() val config: SiteConfiguration = parseSiteConfiguration(yamlString) assertEquals("cheroliv.com", config.bake.cname) assertEquals("main", config.pushPage.branch) assertEquals("https://github.com/pages-content/pages-content.github.io.git", config.pushPage.repo.repository) }</code></pre> </div> </div> <div class="paragraph"> <p>此测试读取文件的内容`managed-jbake-context.yml`(必须存在才能使测试有效)并对对象执行断言`SiteConfiguration`生成的。它验证 YAML 中的键值是否正确映射。</p> </div> </div> <div class="sect2"> <h3 id="_4_2_功能测试验证配置文件的读取">4.2. 功能测试：验证配置文件的读取</h3> <div class="paragraph"> <p>为了确保插件能够通过其 DSL 读取配置文件，并且在真实的 Gradle 环境中解析正常工作，我们添加了一个功能测试到`SiteBakerPluginFunctionalTest.kt`。</p> </div> <div class="paragraph"> <p>此测试至关重要，因为它在真实项目中模拟了插件的执行。它必须<strong>密封的</strong>, 也就是说，他必须自己创建该文件`managed-jbake-context.yml`� 带有受控内容，以确保测试的可重复性和隔离性。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// plugin/src/functionalTest/kotlin/com/cheroliv/site/baker/SiteBakerPluginFunctionalTest.kt @Test fun `config file contains good data`(){ val configContent = configFile.readText(UTF_8) // Vérifications comme dans vos commentaires assertTrue(configContent.contains("bake")) assertTrue(configContent.contains("pushPage")) assertTrue(configContent.contains("repository")) }</code></pre> </div> </div> <div class="paragraph"> <p>此功能测试验证复制到测试临时目录的配置文件包含预期的数据。尽管此测试不会直接将 YAML 解析为 Kotlin 对象，但它验证了文件及其内容的存在，这是插件解析之前必不可少的前置步骤。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_解析流可视化">5. 解析流可视化</h2> <div class="sectionbody"> <div class="paragraph"> <p>下图说明了在解析YAML配置时的数据流和交互：</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-1dff65ce30f499da3af2b2801d1a6018.png" alt="Diagram" width="1396" height="472"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>通过采用 TDD 方法，我们成功地在 Gradle 插件中集成了 Jackson 库，以将 YAML 配置文件解析为 Kotlin 对象。此方法使我们能够：</p> </div> <div class="ulist"> <ul> <li> <p><strong>清晰地建模</strong>我们的配置使用 Kotlin 数据类。</p> </li> <li> <p><strong>验证解析逻辑</strong>带有有针对性的单元测试。</p> </li> <li> <p><strong>确保集成</strong>在真实的 Gradle 环境中，通过密闭的功能测试。</p> </li> </ul> </div> <div class="paragraph"> <p>这个坚实的基础让我们有信心在插件上扩展功能，这些功能建立在此配置之上，同时保证代码的可维护性和健壮性。YAML 解析现在已成为我们插件的一个可靠且经过测试的功能。<code>site-baker</code>。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0090_TDD_gradle_plugin_post.html Wed, 24 Sep 2025 00:00:00 +0000 blog/2025/0090_TDD_gradle_plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_项目初始化">项目初始化</a></li> <li><a href="#_2_我们的首个_tdd_周期记录一项任务">2. 我们的首个 TDD 周期：记录一项任务</a> <ul class="sectlevel2"> <li><a href="#_2_1_首先测试失败的测试">2.1. 首先测试（失败的测试）</a></li> <li><a href="#_2_2_代码随后使测试通过">2.2. 代码随后（使测试通过）</a></li> </ul> </li> <li><a href="#_3_tdd_第二阶段添加_dsl_扩展">3. TDD 第二阶段：添加 DSL 扩展</a> <ul class="sectlevel2"> <li><a href="#_3_1_首先测试">3.1. 首先测试</a></li> <li><a href="#_3_2_接下来的代码">3.2. 接下来的代码</a></li> </ul> </li> <li><a href="#_4_功能测试验证集成">4. 功能测试：验证集成</a> <ul class="sectlevel2"> <li><a href="#_4_1_集成测试创建受控环境">4.1. 集成测试：创建受控环境</a></li> <li><a href="#_4_2_完成逻辑">4.2. 完成逻辑</a></li> </ul> </li> <li><a href="#_结论">结论</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>在本文中，我们将探讨如何使用测试驱动开发（TDD - Test-Driven Development）的方法为 Gradle 插件建立一个坚实的开发基础。 这种方法确保我们的代码是健壮、可维护的，并且能够从一开始就精确满足需求。</p> </div> </div> </div> <div class="sect1"> <h2 id="_项目初始化">项目初始化</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 通过命令大大简化了创建新插件的过程。<code>gradle init</code>. 选择使用 Kotlin 创建一个 "Gradle Plugin"，我们将得到一个即用型项目结构，其中包含两种关键的测试类型：</p> </div> <div class="ulist"> <ul> <li> <p><strong>单元测试 :</strong>位于`src/test`, 它们允许验证我们插件的隔离组件，例如任务的内部逻辑或扩展的配置。它们速度快，不需要完整的 Gradle 执行。</p> </li> <li> <p><strong>功能测试：</strong>位于`src/functionalTest`, 他们使用`GradleRunner`为了在临时测试项目中执行完整的Gradle构建。这使我们能够在受控环境中验证插件的实际行为。</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_2_我们的首个_tdd_周期记录一项任务">2. 我们的首个 TDD 周期：记录一项任务</h2> <div class="sectionbody"> <div class="paragraph"> <p>我们的第一个要求很简单：插件必须记录一个已命名的任务。<code>printSiteConfig</code>。</p> </div> <div class="sect2"> <h3 id="_2_1_首先测试失败的测试">2.1. 首先测试（失败的测试）</h3> <div class="paragraph"> <p>根据 TDD，我们首先编写一个测试来验证该任务的存在。在`SiteBakerPluginTest.kt`(我们的单元测试文件)，我们添加：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers task`() { // Créer un projet de test en mémoire val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Vérifier que la tâche a bien été enregistrée assertNotNull(project.tasks.findByName("printSiteConfig")) }</code></pre> </div> </div> <div class="paragraph"> <p>此测试失败，因为我们尚未在插件中编写任何代码。</p> </div> </div> <div class="sect2"> <h3 id="_2_2_代码随后使测试通过">2.2. 代码随后（使测试通过）</h3> <div class="paragraph"> <p>现在，我们写所需的最少代码在`SiteBakerPlugin.kt`让测试通过:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer une tâche simple project.tasks.register("printSiteConfig") { task -> // ... la logique de la tâche viendra plus tard } } }</code></pre> </div> </div> <div class="paragraph"> <p>我们重新运行测试，它们通过了。我们的第一个功能已被验证。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_3_tdd_第二阶段添加_dsl_扩展">3. TDD 第二阶段：添加 DSL 扩展</h2> <div class="sectionbody"> <div class="paragraph"> <p>接下来的要求是允许用户通过一个 DSL 块在其配置我们的插件`build.gradle.kts`. 我们想要一个块`site { …​ }`可以指定配置路径的地方。</p> </div> <div class="sect2"> <h3 id="_3_1_首先测试">3.1. 首先测试</h3> <div class="paragraph"> <p>我们添加一个测试来验证扩展`site`它已正确记录，且可为其赋予一个值。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin registers extension`() { val project = ProjectBuilder.builder().build() project.plugins.apply("com.cheroliv.site-baker") // Récupérer l'extension et lui affecter une valeur project.extensions .findByType(SiteExtension::class.java)!! .configPath .set("config.yml") // Vérifier que la valeur a bien été prise en compte assertEquals( "config.yml", project.extensions.findByType(SiteExtension::class.java)?.configPath?.get() ) }</code></pre> </div> </div> <div class="paragraph"> <p>此测试失败，因为既不该类`SiteExtension`也不存在扩展的注册</p> </div> </div> <div class="sect2"> <h3 id="_3_2_接下来的代码">3.2. 接下来的代码</h3> <div class="paragraph"> <p>我们正在创建该类`SiteBakerExtension.kt`和我们更新`SiteBakerPlugin.kt`：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// SiteBakerExtension.kt open class SiteExtension @Inject constructor(objects: ObjectFactory) { val configPath: Property<String> = objects.property(String::class.java) } // SiteBakerPlugin.kt class SiteBakerPlugin: Plugin<Project> { override fun apply(project: Project) { // Enregistrer l'extension val extension = project.extensions.create("site", SiteExtension::class.java) project.tasks.register("printSiteConfig") { task -> task.doLast { // On utilisera l'extension plus tard } } } }</code></pre> </div> </div> <div class="paragraph"> <p>�测试再次通过。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_功能测试验证集成">4. 功能测试：验证集成</h2> <div class="sectionbody"> <div class="paragraph"> <p>既然单元已经测试完毕，我们必须确保它们在真实构建中能够协同工作。这就是功能测试的作用在`SiteBakerPluginFunctionalTest.kt`。</p> </div> <div class="sect2"> <h3 id="_4_1_集成测试创建受控环境">4.1. 集成测试：创建受控环境</h3> <div class="paragraph"> <p>这个测试将模拟使用我们插件的真实项目。为了让它可靠，它必须<strong>密封的</strong>, 换句话说，它不应依赖于系统上已存在的文件。它必须自己创建执行所需的所有条件。</p> </div> <div class="paragraph"> <p>�测试将因此 :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>创建一个`build.gradle.kts`使用我们的插件及其DSL的测试</p> </li> <li> <p><strong>创建配置文件</strong>(<code>managed-jbake-context.yml</code>) 插件应该读取的内容。这是测试稳健性的一步关键步骤。</p> </li> <li> <p>执行任务`printSiteConfig`经过`GradleRunner`.</p> </li> <li> <p>� 检查构建输出是否正确。</p> </li> </ol> </div> <div class="paragraph"> <p>通过在每次执行时复制或创建此配置文件，我们确保测试是<strong>可重复</strong>并且不依赖于外部状态。这可以保护我们的测试免受与文件读取相关的回归问题的影响。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `can run task with DSL`() { // 1. Créer un build.gradle.kts de test buildFile.writeText(""" plugins { id("com.cheroliv.site-baker") } site { configPath = "managed-jbake-context.yml" } """.trimIndent()) // 2. Créer le fichier de configuration pour un test contrôlé val configFile = File(projectDir, "managed-jbake-context.yml") configFile.writeText("site: { title: 'Mon Site de Test' }") // Contenu YAML simple // 3. Exécuter la build val runner = GradleRunner.create() runner.withPluginClasspath() runner.withArguments("printSiteConfig") runner.withProjectDir(projectDir) // Spécifier le répertoire du projet de test val result = runner.build() // 4. Vérifier la sortie assertTrue(result.output.contains("Site config path: managed-jbake-context.yml")) }</code></pre> </div> </div> <div class="paragraph"> <p>此测试将在任务未完成时一直失败`printSiteConfig`它不会真的使用扩展的值。</p> </div> </div> <div class="sect2"> <h3 id="_4_2_完成逻辑">4.2. 完成逻辑</h3> <div class="paragraph"> <p>我们正在更新任务在`SiteBakerPlugin.kt`为了使它显示配置的值 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.tasks.register("printSiteConfig") { task -> task.doLast { println("Site config path: ${extension.configPath.get()}") } }</code></pre> </div> </div> <div class="paragraph"> <p>所有测试，单元测试和功能测试，现在都通过了。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>采用TDD方法，我们以增量且安全的方式构建了一个插件。每个小功能都会立即通过测试进行验证，从快速的单元测试到验证完整集成的功能测试。</p> </div> <div class="paragraph"> <p>通过确保我们的测试是功能性的<strong>密封的</strong>— 例如，通过以编程方式创建必要的配置文件 — — 我们构建了一个极其健壮的安全网。这种严谨性能够有效防止回归，并使我们有足够信心随后添加更复杂的功能，如解析 YAML 配置文件。</p> </div> <div class="paragraph"> <p>这个坚实的测试基础是维护和插件未来发展最宝贵的资产。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0089_creation_projet_plugin_gradle_post.html Tue, 23 Sep 2025 00:00:00 +0000 blog/2025/0089_creation_projet_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_引言">引言</a></li> <li><a href="#_步骤_1_启动项目助手">步骤 1 : 启动项目助手</a></li> <li><a href="#_步骤_2理解生成的结构">步骤 2：理解生成的结构</a> <ul class="sectlevel2"> <li><a href="#_关键文件和文件夹">关键文件和文件夹</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_引言">引言</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">目标受众：从初级到中级的 Gradle 开发者。</div> <p>启动一个新的 Gradle 插件项目可能会让人感到望而生畏。幸运的是，Gradle 提供了一个强大的交互式助手，任务`init`, 它生成一个完整、干净且可直接使用的项目结构。本指南将向您展示如何使用此工具创建健康的插件基础，解释其结构，并演示如何启动初始的构建任务。</p> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_1_启动项目助手">步骤 1 : 启动项目助手</h2> <div class="sectionbody"> <div class="paragraph"> <p>命令`gradle init`是起点。它启动一个命令行助手，会向您提出一系列问题以配置项目。</p> </div> <div class="paragraph"> <p>在空文件夹中打开终端并执行：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle init</code></pre> </div> </div> <div class="paragraph"> <p>助手会为您指引。以下是为使用 Kotlin 编写的 Gradle 插件所需做出的选择：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>选择要生成的项目类型：</strong>选择`Gradle plugin`.</p> </li> <li> <p><strong>选择实现语言：</strong>选择`Kotlin`.</p> </li> <li> <p><strong>选择构建脚本DSL:</strong>选择`Kotlin`.</p> </li> <li> <p><strong>项目名称:</strong>请输入您的项目名称 （例如：<code>site-baker</code>).</p> </li> <li> <p><strong>插件 ID:</strong>为您的插件提供一个唯一的标识符 （例如：<code>com.cheroliv.site-baker</code>)</p> </li> <li> <p><strong>�插件类：</strong>请指定实现类的名称 (例如：<code>com.cheroliv.SiteBakerPlugin</code>).</p> </li> </ol> </div> <div class="paragraph"> <p>完成后，Gradle 生成完整的文件树。</p> </div> <div class="imageblock"> <div class="content"> <img src="init-gradle.svg" alt="init gradle" width="193" height="406"> </div> <div class="title">Figure 1. 初始化过程的图表</div> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_2理解生成的结构">步骤 2：理解生成的结构</h2> <div class="sectionbody"> <div class="paragraph"> <p>助手创建了一个多模块项目结构，将根项目与插件本身的源代码分开。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">. ├── gradle/ │ └── wrapper/ │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat ├── plugin/ │ ├── build.gradle.kts │ └── src/ │ ├── main/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPlugin.kt │ ├── test/ │ │ └── kotlin/ │ │ └── com/cheroliv/SiteBakerPluginTest.kt │ └── functionalTest/ │ └── kotlin/ │ └── com/cheroliv/SiteBakerPluginFunctionalTest.kt └── settings.gradle.kts</code></pre> </div> </div> <div class="sect2"> <h3 id="_关键文件和文件夹">关键文件和文件夹</h3> <div class="ulist"> <ul> <li> <p><code>settings.gradle.kts</code>: 此根目录文件定义了构建中包含的模块。在这里，它包含了子项目。<code>plugin</code>。</p> </li> </ul> </div> <div class="paragraph"> <p>[source,kotlin] (empty) rootProject.name = "site-baker include("plugin") ----</p> </div> <div class="listingblock"> <div class="content"> <pre></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0088_environnement_plugin_gradle_post.html Mon, 22 Sep 2025 00:00:00 +0000 blog/2025/0088_environnement_plugin_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_简介">简介</a></li> <li><a href="#_1_jdkgradle_的引擎">1. JDK：Gradle 的引擎</a> <ul class="sectlevel2"> <li><a href="#_选择哪个版本">选择哪个版本？</a></li> <li><a href="#_通过_sdkman_安装推荐">通过 SDKMAN! 安装（推荐）</a> <ul class="sectlevel3"> <li><a href="#_安装_sdkman">安装 SDKMAN！</a></li> <li><a href="#_安装_jdk_版本">安装 JDK 版本</a></li> <li><a href="#_检查安装">检查安装</a></li> </ul> </li> </ul> </li> <li><a href="#_ideintellij_idea">IDE：IntelliJ IDEA</a></li> <li><a href="#_3_gradle构建工具">3. Gradle：构建工具</a> <ul class="sectlevel2"> <li><a href="#_通过_sdkman_安装">通过 SDKMAN! 安装</a> <ul class="sectlevel3"> <li><a href="#_安装_gradle">安装 Gradle</a></li> <li><a href="#_检查安装_2">检查安装</a></li> </ul> </li> </ul> </li> <li><a href="#_4_jbake_静态站点生成器">4. JBake : 静态站点生成器</a> <ul class="sectlevel2"> <li><a href="#_通过sdkman_安装">通过SDKMAN! 安装</a> <ul class="sectlevel3"> <li><a href="#_安装_jbake">安装 JBake</a></li> <li><a href="#_检查安装_3"><strong>检查安装</strong></a></li> </ul> </li> </ul> </li> <li><a href="#_5_gradle_包装器绝对的最佳实践">5. Gradle 包装器：绝对的最佳实践</a></li> <li><a href="#_6_docker_和_portainer实现可重复构建可选">6. Docker 和 Portainer：实现可重复构建（可选）</a> <ul class="sectlevel2"> <li><a href="#_docker_engine_安装">Docker Engine 安装</a> <ul class="sectlevel3"> <li><a href="#_通过官方脚本安装_docker"><strong>通过官方脚本安装 Docker :</strong></a></li> <li><a href="#_管理_docker_不使用_sudo推荐">管理 Docker 不使用 <code>sudo</code>（推荐）：</a></li> </ul> </li> <li><a href="#_使用_portainer_gui_管理_docker">使用 Portainer (GUI) 管理 Docker</a> <ul class="sectlevel3"> <li><a href="#_创建一个用于_portainer_数据的卷"><strong>创建一个用于 Portainer 数据的卷 :</strong></a></li> <li><a href="#_启动_portainer_容器">启动 Portainer 容器：</a></li> </ul> </li> </ul> </li> <li><a href="#_结论">结论</a></li> </ul> </div> <div class="sect1"> <h2 id="_简介">简介</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">目标受众 : 希望开始创建 Gradle 插件的开发者。</div> <p>要高效地开发 Gradle 插件，一个配置良好的开发环境是必不可少的。 良好的设置会为您节省时间，减少挫败感，并确保您的构建保持一致。</p> </div> <div class="olist arabic"> <div class="title">本指南专注于四个关键支柱：</div> <ol class="arabic"> <li> <p>Le <strong>Java 开发工具包</strong>（Java Development Kit），因为 Gradle 和 JBake 在 JVM 上运行。</p> </li> <li> <p>Un <strong>集成开发环境</strong>使用现代化的 IntelliJ IDEA，对 Kotlin 和 Gradle 提供了良好的支持。</p> </li> <li> <p><strong>Gradle</strong>他自己，为了初始化项目。</p> </li> <li> <p><strong>JBake</strong>, 我们静态网站的引擎。</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/gradle-env.svg" alt="gradle env" width="1618" height="5696"> </div> <div class="title">Figure 1. 开发环境的组件</div> </div> </div> </div> <div class="sect1"> <h2 id="_1_jdkgradle_的引擎">1. JDK：Gradle 的引擎</h2> <div class="sectionbody"> <div class="paragraph"> <p>Gradle 是一个运行在 Java虚拟机(JVM) 上的应用程序。 因此，安装 JDK 是绝对的前置条件。</p> </div> <div class="sect2"> <h3 id="_选择哪个版本">选择哪个版本？</h3> <div class="paragraph"> <p>建议使用 Java 的长期支持（LTS）版本。 目前，<strong>JDK 17</strong> ou <strong>JDK 21</strong>是很好的选择。</p> </div> </div> <div class="sect2"> <h3 id="_通过_sdkman_安装推荐">通过 SDKMAN! 安装（推荐）</h3> <div class="paragraph"> <p>SDKMAN！ 是管理众多 SDK 版本（包括 Java 和 Gradle）的绝佳工具。</p> </div> <div class="sect3"> <h4 id="_安装_sdkman">安装 SDKMAN！</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -s "https://get.sdkman.io" | bash source "$HOME/.sdkman/bin/sdkman-init.sh"</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_安装_jdk_版本">安装 JDK 版本</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Pour lister les versions de Java disponibles sdk list java # Pour installer Java 17 (par exemple, la distribution Temurin) sdk install java 17.0.8-tem</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_检查安装">检查安装</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">java -version</code></pre> </div> </div> <div class="paragraph"> <p>您应该能看到您刚刚安装的版本显示出来。</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_ideintellij_idea">IDE：IntelliJ IDEA</h2> <div class="sectionbody"> <div class="paragraph"> <p>用于使用 Kotlin DSL 开发 Gradle 插件，<strong>IntelliJ IDEA</strong>是首选工具。 其与Gradle和Kotlin的集成无与伦比。</p> </div> <div class="ulist"> <ul> <li> <p><strong>社区版：</strong>免费且足够充裕，可以开始。</p> </li> <li> <p><strong>终极版：</strong>付费版，它提供了用于Web开发和数据库的高级功能。</p> </li> </ul> </div> <div class="paragraph"> <p>从JetBrains网站下载适合您的版本：https://www.jetbrains.com/idea/download/</p> </div> <div class="paragraph"> <p>IDE 将自动检测您的文件`build.gradle.kts` et <code>settings.gradle.kts</code>, 提供强大的自动补全、代码导航和集成调试工具。</p> </div> </div> </div> <div class="sect1"> <h2 id="_3_gradle构建工具">3. Gradle：构建工具</h2> <div class="sectionbody"> <div class="paragraph"> <p>虽然每个项目都会通过 Gradle Wrapper 使用其自己的 Gradle 版本，但拥有全局 Gradle 安装对于诸如初始化新项目之类的任务仍然很有用 （<code>gradle init</code>)</p> </div> <div class="sect2"> <h3 id="_通过_sdkman_安装">通过 SDKMAN! 安装</h3> <div class="paragraph"> <p>同样如同 JDK，SDKMAN! 简化了 Gradle 的安装。</p> </div> <div class="sect3"> <h4 id="_安装_gradle">安装 Gradle</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install gradle</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_检查安装_2">检查安装</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">gradle -v</code></pre> </div> </div> <div class="paragraph"> <p>此命令将显示所使用的 Gradle、Kotlin、Groovy 和 JDK 版本。</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_4_jbake_静态站点生成器">4. JBake : 静态站点生成器</h2> <div class="sectionbody"> <div class="paragraph"> <p>JBake 是我们将用来将源文件（如这个）转换为静态网站的工具。 �拥有本地安装对于预览更改很方便。</p> </div> <div class="sect2"> <h3 id="_通过sdkman_安装">通过SDKMAN! 安装</h3> <div class="paragraph"> <p>与其他工具一样，SDKMAN! 是最简单的方法。</p> </div> <div class="sect3"> <h4 id="_安装_jbake">安装 JBake</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sdk install jbake</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_检查安装_3"><strong>检查安装</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">jbake -v</code></pre> </div> </div> <div class="paragraph"> <p>此命令将显示 JBake 的版本及其使用的 Java 环境信息。</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_5_gradle_包装器绝对的最佳实践">5. Gradle 包装器：绝对的最佳实践</h2> <div class="sectionbody"> <div class="paragraph"> <p>创建您的项目后（我们将在下一篇文章中介绍），您不应该再使用全局命令。<code>gradle</code>. 您将使用<strong>Gradle 包装器</strong> (<code>./gradlew</code>), 一个包含在您的项目中的脚本。</p> </div> <div class="paragraph"> <p>为什么？</p> </div> <div class="ulist"> <ul> <li> <p><strong>可重复性：</strong>Wrapper 确保项目中的每个人（包括您的 CI/CD 服务器）都使用完全相同的<strong>相同版本的 Gradle</strong>, 从而消除了由于不同环境导致的构建错误。</p> </li> <li> <p><strong>简洁：</strong>不需要手动安装 Gradle 即可为项目做出贡献。</p> </li> </ul> </div> <div class="paragraph"> <p>只需克隆仓库并启动`./gradlew`.</p> </div> <div class="paragraph"> <p>一个典型的命令将如下所示：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash"># Ne pas faire : gradle build # À faire : ./gradlew build</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_6_docker_和_portainer实现可重复构建可选">6. Docker 和 Portainer：实现可重复构建（可选）</h2> <div class="sectionbody"> <div class="paragraph"> <p>虽然在编写插件时并非严格必需，但 Docker 和 Portainer 是现代的 DevOps 工具，极大地便利了创建可重现的构建以及管理您的环境。</p> </div> <div class="sect2"> <h3 id="_docker_engine_安装">Docker Engine 安装</h3> <div class="paragraph"> <p>Docker 允许您将应用程序及其依赖项打包到一个容器中。</p> </div> <div class="sect3"> <h4 id="_通过官方脚本安装_docker"><strong>通过官方脚本安装 Docker :</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_管理_docker_不使用_sudo推荐">管理 Docker 不使用 <code>sudo</code>（推荐）：</h4> <div class="paragraph"> <p>将您的用户添加到组`docker`.</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo usod -aG docker $USER</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> </td> </tr> </table> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run hello-world</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_使用_portainer_gui_管理_docker">使用 Portainer (GUI) 管理 Docker</h3> <div class="paragraph"> <p>Portainer 是一个轻量级的 Web 界面，用于管理您的 Docker 容器。</p> </div> <div class="sect3"> <h4 id="_创建一个用于_portainer_数据的卷"><strong>创建一个用于 Portainer 数据的卷 :</strong></h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker volume create portainer_data</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_启动_portainer_容器">启动 Portainer 容器：</h4> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest</code></pre> </div> </div> <div class="paragraph"> <p>您现在可以访问Portainer界面在`https://localhost:9443`.</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>您的环境现在已准备好！ 您�拥有 JDK、最合适的 IDE、Gradle 和 JBake。 加入 Docker 后，您也已准备好创建容器化且可复现的构建。 这个坚实的基础将让你能够专注于本质：开发强大而实用的插件。</p> </div> <div class="paragraph"> <p>在下一篇文章中，我们将使用该命令`gradle init`用于生成我们第一个插件项目的结构。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0087_pypi_cicd_part_3_post.html Sat, 19 Jul 2025 00:00:00 +0000 blog/2025/0087_pypi_cicd_part_3_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_与_poetry_集成">与 Poetry 集成</a> <ul class="sectlevel2"> <li><a href="#_安装_poetry">安装 Poetry</a></li> <li><a href="#_项目初始化">项目初始化</a></li> <li><a href="#_添加和安装依赖">�添加和安装依赖</a></li> <li><a href="#_使用_poetry_进行发布">使用 Poetry 进行发布</a></li> </ul> </li> <li><a href="#_可复现的_docker_构建">可复现的 Docker 构建</a> <ul class="sectlevel2"> <li><a href="#_dockerfile_示例">Dockerfile 示例</a></li> <li><a href="#_在_github_actions_中的集成">在 GitHub Actions 中的集成</a></li> </ul> </li> <li><a href="#_条件发布">条件发布</a></li> <li><a href="#_使用_renovate_和_dependabot_自动化依赖">使用 Renovate 和 Dependabot 自动化依赖</a> <ul class="sectlevel2"> <li><a href="#_dependabot">Dependabot</a></li> <li><a href="#_翻新">翻新</a></li> </ul> </li> <li><a href="#_plantuml_图表">PlantUML 图表</a> <ul class="sectlevel2"> <li><a href="#_用例_高级_cicd">用例 – 高级 CI/CD</a></li> <li><a href="#_序列_有条件发布">序列 – 有条件发布</a></li> <li><a href="#_状态_cicd_管道">状态 – CI/CD 管道</a></li> <li><a href="#_部署_cicd_架构">部署 – CI/CD 架构</a></li> </ul> </li> <li><a href="#_结论">结论</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>在这系列的前两部分中，我们有： - 建立了一个可用于 Python 应用的 CI/CD 流水线，使用 GitHub Actions 和 PyPI。 - 已将此流水线工业化，使用多版本测试、通过 Test PyPI 进行渐进式发布，并配备质量和安全工具。</p> </div> <div class="paragraph"> <p>在这第三部分，我们将会去<strong>超越在 PyPI 上的简单发布</strong>为了构建一个完整、健壮且专业的 CI/CD 流水线，配有： - <strong>诗歌</strong>为了现代化的包装和依赖的优化管理。 - <strong>Docker</strong>为了创建可重复且跨平台的构建。 - <strong>条件发布</strong>用于处理诸如候选发布版之类的场景。 - <strong>自动化工具</strong>(Renovate, Dependabot) 轻松保持管道最新。</p> </div> </div> </div> <div class="sect1"> <h2 id="_与_poetry_集成">与 Poetry 集成</h2> <div class="sectionbody"> <div class="paragraph"> <p>Poetry 通过集中管理依赖和构建，取代了旧的打包工具（setup.py, requirements.txt）<code>pyproject.toml</code>.</p> </div> <div class="sect2"> <h3 id="_安装_poetry">安装 Poetry</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Installer Poetry curl -sSL https://install.python-poetry.org | python3 - # Vérifier la version poetry --version</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_项目初始化">项目初始化</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Initialiser un nouveau projet avec Poetry poetry init # Suivre l'assistant pour renseigner : nom, version, description, licence, dépendances.</code></pre> </div> </div> <div class="paragraph"> <p>这会生成一个文件`pyproject.toml` :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="toml">[tool.poetry] name = "playlist-downloader" version = "0.1.0" description = "CLI tool for managing YouTube playlists" authors = ["Christophe Hérolivier <cheroliv@example.com>"] [tool.poetry.dependencies] python = ">=3.8" typer = "^0.9.0" yt-dlp = "^2023.7.6" google-api-python-client = "^2.0.0" google-auth-oauthlib = "^1.0.0" [tool.poetry.group.dev.dependencies] pytest = "^7.0" mypy = "^1.0" bandit = "^1.7" safety = "^2.3" black = "^23.0" ruff = "^0.1"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_添加和安装依赖">�添加和安装依赖</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell">poetry add typer yt-dlp google-api-python-client google-auth-oauthlib poetry add --group dev pytest mypy black bandit safety ruff</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_使用_poetry_进行发布">使用 Poetry 进行发布</h3> <div class="paragraph"> <p>Poetry 原生管理发布：</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="shell"># Publication sur Test PyPI poetry publish --build --repository test-pypi # Publication sur PyPI poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>此命令会自动使用存在于…​中的信息`pyproject.toml`.</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_可复现的_docker_构建">可复现的 Docker 构建</h2> <div class="sectionbody"> <div class="paragraph"> <p>为确保在开发、CI/CD 和生产环境中实现一致的执行，Docker 与 Poetry 完全集成。</p> </div> <div class="sect2"> <h3 id="_dockerfile_示例">Dockerfile 示例</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="dockerfile">FROM python:3.11-slim WORKDIR /app COPY pyproject.toml poetry.lock ./ RUN pip install poetry RUN poetry install --no-root --only main COPY . . CMD ["poetry", "run", "python", "cli.py"]</code></pre> </div> </div> <div class="paragraph"> <p>这确保： - 一个固定的 Python 环境。 - 已锁定的依赖项通过`poetry.lock`. - 可在所有支持 Docker 的系统上运行的可执行镜像。</p> </div> </div> <div class="sect2"> <h3 id="_在_github_actions_中的集成">在 GitHub Actions 中的集成</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: Docker Build on: push: branches: [main] jobs: build-docker: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build Docker image run: docker build -t ghcr.io/${{ github.repository }}:latest . - name: Push Docker image run: docker push ghcr.io/${{ github.repository }}:latest</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_条件发布">条件发布</h2> <div class="sectionbody"> <div class="paragraph"> <p>在专业流水线中，必须能够仅在某些情况下发布： - 发布候选版本至 Test PyPI 将稳定版本发布到 PyPI。 - 仅触发的 Docker 构建用于`main`。</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">- name: Publish to Test PyPI if: contains(github.ref, '-rc') run: poetry publish --build --repository test-pypi - name: Publish to PyPI if: startsWith(github.ref, 'refs/tags/v') run: poetry publish --build</code></pre> </div> </div> <div class="paragraph"> <p>这种方法可以避免意外发布。</p> </div> </div> </div> <div class="sect1"> <h2 id="_使用_renovate_和_dependabot_自动化依赖">使用 Renovate 和 Dependabot 自动化依赖</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了防止您的依赖变得过时，请集成自动更新工具。</p> </div> <div class="sect2"> <h3 id="_dependabot">Dependabot</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">version: 2 updates: - package-ecosystem: "pip" directory: "/" schedule: interval: "weekly" - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly"</code></pre> </div> </div> <div class="paragraph"> <p>Dependabot 每周创建 PR 以更新 Python 和 GitHub Actions 依赖。</p> </div> </div> <div class="sect2"> <h3 id="_翻新">翻新</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="json">{ "extends": ["config:base"], "packageRules": [ { "matchManagers": ["pip"], "groupName": "python-dependencies", "schedule": ["before 6am on monday"] } ] }</code></pre> </div> </div> <div class="paragraph"> <p>Renovate 允许进行更细粒度的控制：依赖分组、调度以及高级规则。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_plantuml_图表">PlantUML 图表</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_用例_高级_cicd">用例 – 高级 CI/CD</h3> <div class="imageblock"> <div class="content"> <img src="images/usecase-cicd.svg" alt="usecase cicd" width="786" height="317"> </div> </div> </div> <div class="sect2"> <h3 id="_序列_有条件发布">序列 – 有条件发布</h3> <div class="imageblock"> <div class="content"> <img src="images/sequence-cicd.svg" alt="sequence cicd" width="275" height="571"> </div> </div> </div> <div class="sect2"> <h3 id="_状态_cicd_管道">状态 – CI/CD 管道</h3> <div class="imageblock"> <div class="content"> <img src="images/states-cicd.svg" alt="states cicd" width="284" height="608"> </div> </div> </div> <div class="sect2"> <h3 id="_部署_cicd_架构">部署 – CI/CD 架构</h3> <div class="imageblock"> <div class="content"> <img src="images/deployment-cicd.svg" alt="deployment cicd" width="1567" height="5592"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>在这第三部分中，我们了解了如何： - 使用 Poetry 现代化 Python 包装。 - 通过Docker确保构建可重现。 - 设置条件性发布. 自动化依赖项的更新。</p> </div> <div class="paragraph"> <p>您现在拥有了一个 CI/CD 管道<strong>完整、工业化和安全</strong>, 准备好随着您的项目发展。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0086_pypi_cicd_part_2_post.html Fri, 18 Jul 2025 00:00:00 +0000 blog/2025/0086_pypi_cicd_part_2_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_cicd_流水线架构">CI/CD 流水线架构</a></li> <li><a href="#_项目结构">项目结构</a></li> <li><a href="#_使用_pyproject_toml_配置包">使用 pyproject.toml 配置包</a></li> <li><a href="#_cicd_工作流程_测试与质量">CI/CD 工作流程 - 测试与质量</a></li> <li><a href="#_发布和部署工作流程">发布和部署工作流程</a></li> <li><a href="#_架构图">架构图</a> <ul class="sectlevel2"> <li><a href="#_序列图_发布流程">序列图 - 发布流程</a></li> <li><a href="#_状态图_包的生命周期">状态图 - 包的生命周期</a></li> <li><a href="#_部署图_cicd_基础设施">部署图 - CI/CD 基础设施</a></li> </ul> </li> <li><a href="#_管道的对象和模型">管道的对象和模型</a> <ul class="sectlevel2"> <li><a href="#_类图_cicd_模板">类图 - CI/CD 模板</a></li> </ul> </li> <li><a href="#_秘密配置">秘密配置</a> <ul class="sectlevel2"> <li><a href="#_github_actions_机密">GitHub Actions 机密</a></li> <li><a href="#_生成_pypi_令牌">生成 PyPI 令牌</a></li> </ul> </li> <li><a href="#_本地开发脚本">本地开发脚本</a> <ul class="sectlevel2"> <li><a href="#_makefile">Makefile</a></li> <li><a href="#_版本脚本">版本脚本</a></li> </ul> </li> <li><a href="#_最佳实践和建议">最佳实践和建议</a> <ul class="sectlevel2"> <li><a href="#_语义版本控制">语义版本控制</a></li> <li><a href="#_分支策略">分支策略</a></li> <li><a href="#_测试和覆盖">�测试和覆盖</a></li> <li><a href="#_安全">安全</a></li> </ul> </li> <li><a href="#_监控和可观测性">�监控和可观测性</a> <ul class="sectlevel2"> <li><a href="#_管道指标">管道指标</a></li> <li><a href="#_通知">通知</a></li> </ul> </li> <li><a href="#_结论">结论</a></li> <li><a href="#_补充资源">补充资源</a></li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">Objectif : 将简单的流水线转变为符合现代包装和软件工程标准的稳健工业流水线。</div> <p>在这个系列的第一部分，我们构建了一个简单但有效的 CI/CD 流水线，以自动化 Python 包在 PyPI 上的测试和发布。</p> </div> <div class="paragraph"> <p>现在是时候专业化这个管道了。 在这第二部分，我们将要：</p> </div> <div class="ulist"> <ul> <li> <p>�迁移到现代 pyproject.toml 标准，</p> </li> <li> <p>添加质量和安全工具（Black, Mypy, Bandit, Safety）</p> </li> <li> <p>设置多版本测试，</p> </li> <li> <p>通过 Test PyPI 进行渐进式部署,</p> </li> <li> <p>自动化版本控制并改进管道监控。</p> </li> </ul> </div> <div class="paragraph"> <p>准备好从功能性的流水线过渡到专业的CI/CD基础设施。</p> </div> <div class="paragraph"> <p>在 PyPI 上部署 Python 应用程序需要一个健壮的 CI/CD 流水线，该流水线能够自动化测试、构建和发布包。 本文详细介绍了使用 GitHub Actions 为 Python CLI 应用构建完整流水线的过程，遵循现代 Python 生态系统的最佳实践。</p> </div> </div> </div> <div class="sect1"> <h2 id="_cicd_流水线架构">CI/CD 流水线架构</h2> <div class="sectionbody"> <div class="paragraph"> <p>我们将要构建的管道遵循多步骤的方法:</p> </div> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-cff917c776e88c1e8b4e55e6a87954a7.png" alt="Diagram" width="846" height="604"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_项目结构">项目结构</h2> <div class="sectionbody"> <div class="paragraph"> <p>准备好进行分发的Python CLI应用程序必须遵循一个标准化的结构:</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="text">playlist-downloader/ ├── .github/ │ └── workflows/ │ ├── ci.yml │ ├── release.yml │ └── security.yml ├── src/ │ └── playlist_downloader/ │ ├── __init__.py │ ├── cli.py │ ├── core/ │ └── adapters/ ├── tests/ │ ├── unit/ │ ├── integration/ │ └── conftest.py ├── docs/ ├── pyproject.toml ├── requirements.txt ├── requirements-dev.txt ├── MANIFEST.in ├── README.md ├── LICENSE └── CHANGELOG.md</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用_pyproject_toml_配置包">使用 pyproject.toml 配置包</h2> <div class="sectionbody"> <div class="paragraph"> <p>文件`pyproject.toml`是配置 Python 包的现代标准 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="toml">[build-system] requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2"] build-backend = "setuptools.build_meta" [project] name = "playlist-downloader" authors = [ {name = "Christophe Hérolivier", email = "cheroliv@example.com"}, ] description = "CLI tool for YouTube playlist management" readme = "README.md" requires-python = ">=3.8" keywords = ["youtube", "playlist", "cli", "downloader"] license = {text = "MIT"} classifiers = [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: End Users/Desktop", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Topic :: Multimedia :: Sound/Audio", "Topic :: Utilities", ] dependencies = [ "typer>=0.9.0", "yt-dlp>=2023.7.6", "google-api-python-client>=2.0.0", "google-auth-oauthlib>=1.0.0", "pyyaml>=6.0", "rich>=13.0.0", ] dynamic = ["version"] [project.optional-dependencies] dev = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", "black>=23.0.0", "flake8>=6.0.0", "mypy>=1.0.0", "pre-commit>=3.0.0", "tox>=4.0.0", ] test = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", "pytest-mock>=3.10.0", ] [project.urls] Homepage = "https://github.com/cheroliv/playlist-downloader" Documentation = "https://github.com/cheroliv/playlist-downloader#readme" Repository = "https://github.com/cheroliv/playlist-downloader.git" "Bug Tracker" = "https://github.com/cheroliv/playlist-downloader/issues" [project.scripts] playlist-downloader = "playlist_downloader.cli:main" [tool.setuptools_scm] write_to = "src/playlist_downloader/_version.py" [tool.setuptools.packages.find] where = ["src"] [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] addopts = [ "--cov=src/playlist_downloader", "--cov-report=html", "--cov-report=term-missing", "--cov-fail-under=85", ] [tool.black] line-length = 88 target-version = ['py38'] include = '\.pyi?$' extend-exclude = ''' /( \.eggs | \.git | \.hg | \.mypy_cache | \.tox | \.venv | _build | buck-out | build | dist )/ ''' [tool.mypy] python_version = "3.8" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true disallow_incomplete_defs = true check_untyped_defs = true disallow_untyped_decorators = true no_implicit_optional = true warn_redundant_casts = true warn_unused_ignores = true warn_no_return = true warn_unreachable = true strict_equality = true [[tool.mypy.overrides]] module = [ "yt_dlp.*", "googleapiclient.*", "google_auth_oauthlib.*", ] ignore_missing_imports = true</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_cicd_工作流程_测试与质量">CI/CD 工作流程 - 测试与质量</h2> <div class="sectionbody"> <div class="paragraph"> <p>主工作流程 (<code>ci.yml</code>) 在多个 Python 版本上执行测试：</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: CI on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.8", "3.9", "3.10", "3.11"] steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - name: Cache dependencies uses: actions/cache@v3 with: path: | ~/.cache/pip ~/.cache/pre-commit key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }} restore-keys: | ${{ runner.os }}-pip- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -e ".[dev]" - name: Lint with flake8 run: | flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics flake8 src tests --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics - name: Check code formatting with Black run: black --check src tests - name: Type checking with mypy run: mypy src - name: Run tests with pytest run: | pytest tests/ -v --cov=src/playlist_downloader \ --cov-report=xml --cov-report=term-missing - name: Upload coverage to Codecov uses: codecov/codecov-action@v3 if: matrix.python-version == '3.11' with: file: ./coverage.xml flags: unittests name: codecov-umbrella security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install dependencies run: | python -m pip install --upgrade pip pip install bandit[toml] safety - name: Run security checks with bandit run: bandit -r src/ -f json -o bandit-report.json - name: Check dependencies with safety run: safety check --json --output safety-report.json - name: Upload security reports uses: actions/upload-artifact@v3 if: always() with: name: security-reports path: | bandit-report.json safety-report.json build: needs: [test, security] runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.11" - name: Install build dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package with twine run: twine check dist/* - name: Upload build artifacts uses: actions/upload-artifact@v3 with: name: dist path: dist/</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_发布和部署工作流程">发布和部署工作流程</h2> <div class="sectionbody"> <div class="paragraph"> <p>发布工作流程 (<code>release.yml</code>) 管理自动发布到 PyPI :</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: Release on: push: tags: - 'v*.*.*' workflow_dispatch: inputs: environment: description: 'Deployment environment' required: true default: 'test' type: choice options: - test - production env: PYTHON_VERSION: "3.11" jobs: release: runs-on: ubuntu-latest environment: name: ${{ github.event.inputs.environment || (startsWith(github.ref, 'refs/tags/') && 'production' || 'test') }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install build twine - name: Build package run: python -m build - name: Check package run: twine check dist/* - name: Publish to Test PyPI if: github.event.inputs.environment == 'test' || (startsWith(github.ref, 'refs/tags/') && contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }} run: | twine upload --repository testpypi dist/* - name: Publish to PyPI if: github.event.inputs.environment == 'production' || (startsWith(github.ref, 'refs/tags/') && !contains(github.ref, 'rc')) env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | twine upload dist/* - name: Create GitHub Release if: startsWith(github.ref, 'refs/tags/') uses: actions/create-release@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: tag_name: ${{ github.ref }} release_name: Release ${{ github.ref }} draft: false prerelease: ${{ contains(github.ref, 'rc') }} post-release: needs: release runs-on: ubuntu-latest if: startsWith(github.ref, 'refs/tags/') steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ env.PYTHON_VERSION }} - name: Test installation from PyPI run: | sleep 60 # Attendre la propagation sur PyPI pip install playlist-downloader playlist-downloader --version - name: Update documentation run: | # Script pour mettre à jour la documentation echo "Documentation updated for version ${GITHUB_REF#refs/tags/}"</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_架构图">架构图</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_序列图_发布流程">序列图 - 发布流程</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-a3ee9f850df53f9bb06b7b0cba2cc3d9.png" alt="Diagram" width="924" height="832"> </div> </div> </div> <div class="sect2"> <h3 id="_状态图_包的生命周期">状态图 - 包的生命周期</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-996d32847fba3622d1b1db7f44fc9614.png" alt="Diagram" width="525" height="740"> </div> </div> </div> <div class="sect2"> <h3 id="_部署图_cicd_基础设施">部署图 - CI/CD 基础设施</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-258d42aa7ec6ab086447895edd24e800.png" alt="Diagram" width="619" height="604"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_管道的对象和模型">管道的对象和模型</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_类图_cicd_模板">类图 - CI/CD 模板</h3> <div class="imageblock"> <div class="content"> <img src="images/diag-plantuml-md5-c83852c420ebb571d85a4eb4527253d9.png" alt="Diagram" width="814" height="635"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_秘密配置">秘密配置</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了使流水线正常运行，您需要在 GitHub 中配置以下密钥：</p> </div> <div class="sect2"> <h3 id="_github_actions_机密">GitHub Actions 机密</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="bash"># Dans Settings > Secrets and variables > Actions # Token PyPI pour la production PYPI_API_TOKEN=pypi-... # Token Test PyPI pour les pré-releases TEST_PYPI_API_TOKEN=pypi-... # Token GitHub pour créer les releases GITHUB_TOKEN=(automatiquement fourni) # Token Codecov (optionnel) CODECOV_TOKEN=...</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_生成_pypi_令牌">生成 PyPI 令牌</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="bash"># 1. Créer un compte sur PyPI et Test PyPI # 2. Aller dans Account Settings > API tokens # 3. Créer un token avec scope "Entire account" ou spécifique au projet # 4. Format du token : pypi-AgEIcHlwaS5vcmc...</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_本地开发脚本">本地开发脚本</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了方便开发，创建实用脚本：</p> </div> <div class="sect2"> <h3 id="_makefile">Makefile</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="makefile">.PHONY: install test lint format security build clean release-test release-prod install: pip install -e ".[dev]" test: pytest tests/ -v --cov=src/playlist_downloader lint: flake8 src tests mypy src format: black src tests security: bandit -r src/ safety check build: python -m build twine check dist/* clean: rm -rf build/ dist/ *.egg-info/ find . -type d -name __pycache__ -delete find . -name "*.pyc" -delete release-test: clean build twine upload --repository testpypi dist/* release-prod: clean build twine upload dist/* pre-commit: format lint test security @echo "✅ Prêt pour commit"</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_版本脚本">版本脚本</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="python">#!/usr/bin/env python3 """Script pour gérer les versions du projet.""" import sys import subprocess from pathlib import Path def get_current_version(): """Récupère la version actuelle depuis git.""" try: result = subprocess.run( ["git", "describe", "--tags", "--abbrev=0"], capture_output=True, text=True, check=True ) return result.stdout.strip() except subprocess.CalledProcessError: return "0.0.0" def create_version_tag(version, message=None): """Crée un tag de version.""" if not version.startswith('v'): version = f'v{version}' tag_message = message or f"Release {version}" subprocess.run(["git", "tag", "-a", version, "-m", tag_message], check=True) print(f"✅ Tag {version} créé") # Push le tag subprocess.run(["git", "push", "origin", version], check=True) print(f"✅ Tag {version} poussé vers origin") if __name__ == "__main__": if len(sys.argv) < 2: current = get_current_version() print(f"Version actuelle: {current}") print("Usage: python version.py <new_version> [message]") sys.exit(1) new_version = sys.argv[1] message = sys.argv[2] if len(sys.argv) > 2 else None create_version_tag(new_version, message)</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_最佳实践和建议">最佳实践和建议</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_语义版本控制">语义版本控制</h3> <div class="paragraph"> <p>使用语义版本控制（SemVer）：</p> </div> <div class="ulist"> <ul> <li> <p><code>MAJOR.MINOR.PATCH</code> (ex: 1.2.3)</p> </li> <li> <p>`MAJOR`不兼容的更改</p> </li> <li> <p><code>MINOR</code>: 新的兼容功能</p> </li> <li> <p><code>PATCH</code>: 兼容的错误修复</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_分支策略">分支策略</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="text">main ──●──●──●──●──●────●── (releases stables) / / / develop ──●──●──●──●──●──●──●──●── (développement) / / / feature/xxx ●──●──●──●──●──/ (fonctionnalités)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_测试和覆盖">�测试和覆盖</h3> <div class="ulist"> <ul> <li> <p>最低代码覆盖率：85%</p> </li> <li> <p>业务逻辑的单元测试</p> </li> <li> <p>�适配器的集成测试</p> </li> <li> <p>CLI 端到端测试</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_安全">安全</h3> <div class="ulist"> <ul> <li> <p>自动扫描依赖项（Safety）</p> </li> <li> <p>代码的静态分析 (Bandit)</p> </li> <li> <p>密码永不在代码中</p> </li> <li> <p>使用特定的 PyPI 令牌</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_监控和可观测性">�监控和可观测性</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_管道指标">管道指标</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml"># .github/workflows/metrics.yml name: Pipeline Metrics on: workflow_run: workflows: ["CI", "Release"] types: [completed] jobs: metrics: runs-on: ubuntu-latest steps: - name: Collect metrics run: | echo "Pipeline: ${{ github.event.workflow_run.name }}" echo "Status: ${{ github.event.workflow_run.conclusion }}" echo "Duration: ${{ github.event.workflow_run.updated_at - github.event.workflow_run.created_at }}" # Envoyer vers système de monitoring</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_通知">通知</h3> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml"># Ajout dans les workflows pour notifications - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: failure text: "❌ Pipeline failed for ${{ github.repository }}" env: SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>此完整的 Python CI/CD 流程提供：</p> </div> <div class="ulist"> <ul> <li> <p><strong>完全自动化</strong>: 从代码验证到发布</p> </li> <li> <p><strong>安全</strong>: 自动扫描和安全的密钥管理</p> </li> <li> <p><strong>质量</strong>: 多版本测试、代码检查和代码覆盖率</p> </li> <li> <p><strong>可靠性</strong>: 通过Test PyPI的渐进式部署</p> </li> <li> <p><strong>可追溯性</strong>工件、报告和 GitHub 发行版</p> </li> </ul> </div> <div class="paragraph"> <p>采用这些做法可以确保您的Python CLI应用程序具备稳健且专业的交付流程，使得项目在长期内更易于维护与演进。</p> </div> </div> </div> <div class="sect1"> <h2 id="_补充资源">补充资源</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://packaging.python.org/">Python 包装用户指南</a></p> </li> <li> <p><a href="https://docs.github.com/en/actions">GitHub Actions 文档</a></p> </li> <li> <p><a href="https://pypi.org/help/">PyPI 帮助文档</a></p> </li> <li> <p><a href="https://semver.org/">语义化版本规范</a></p> </li> <li> <p><a href="https://keepachangelog.com/">保持变更日志</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2025/0085_pypi_cicd_part_1_post.html Thu, 17 Jul 2025 00:00:00 +0000 blog/2025/0085_pypi_cicd_part_1_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_pipeline架构">Pipeline架构</a></li> <li><a href="#_持续集成ci管道配置">持续集成(CI)管道配置</a> <ul class="sectlevel2"> <li><a href="#_ci_工作流程结构">CI 工作流程结构</a></li> <li><a href="#_ci步骤分析">CI步骤分析</a> <ul class="sectlevel3"> <li><a href="#_1_触发器_on">1. 触发器 (<code>on</code>)</a></li> </ul> </li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">目标 : 引导读者为一个 Python 应用程序构建一个简约但功能完整的 CI/CD 流程，实现自动部署到 PyPI。</div> <p>开发流程的自动化已经成为现代项目中不可或缺的一部分。一个设计良好的CI/CD流水线不仅能够在开发周期早期检测到回归，还能够完全自动化部署过程。</p> </div> <div class="paragraph"> <p>在本文中，我们将探讨如何为 Python 应用程序使用 GitHub Actions 搭建一个完整的流水线，从持续集成 (CI) 到持续部署 (CD) 发布到 PyPI。</p> </div> </div> </div> <div class="sect1"> <h2 id="_pipeline架构">Pipeline架构</h2> <div class="sectionbody"> <div class="paragraph"> <p>我们的流水线由两个不同的工作流组成：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>CI 流水线</strong>在每次 push 和 pull request 时执行</p> </li> <li> <p><strong>持续交付流水线</strong>: 仅在 GitHub 发布期间触发</p> </li> </ol> </div> <div class="imageblock"> <div class="content"> <img src="images/ci-cd-overview.svg" alt="ci cd overview" width="1614" height="5132"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_持续集成ci管道配置">持续集成(CI)管道配置</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ci_工作流程结构">CI 工作流程结构</h3> <div class="paragraph"> <p>CI 工作流程旨在验证每次代码贡献。以下是其完整配置：</p> </div> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">name: CI/CD Pipeline on: push: branches: - main pull_request: branches: - main jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock - name: Run Linting (Ruff) run: ruff check . - name: Run Tests (Pytest) run: pytest</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_ci步骤分析">CI步骤分析</h3> <div class="sect3"> <h4 id="_1_触发器_on">1. 触发器 (<code>on</code>)</h4> <div class="listingblock"> <div class="content"> <pre class="pygments highlight"><code data-lang="yaml">---- ---- on: push: branches: - main pull_request: branches: - main ---- 流水线在以下情况下触发： - 每次推送到该分支`main` - � 每个 pull request 向`main` 这种方法保证主代码保持稳定，且在集成之前验证所有贡献。 ==== 2. 运行环境 ---- runs-on: ubuntu-latest Ubuntu Latest 在性能、成本和兼容性之间提供了一个很好的折中方案，适用于大多数 Python 项目。 ==== 3. 代码检出 ```yaml ---- ---- - name: Checkout code uses: actions/checkout@v4 ---- 行动`checkout@v4`检索存储库的源代码。v4 版本带来了性能和安全性的改进。 ==== 4. Python配置 ---- - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' 使用`'3.x'`允许自动使用 Python 3 的最新稳定版本，简化了维护。 ==== 5. 安装依赖 ```yaml ---- ---- - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install ruff pytest pytest-mock ---- 这一步： - 将 pip 更新到最新版本 - 安装项目依赖 - 添加开发工具（linting 和测试） ==== 6. 使用 Ruff 进行代码检查 ---- - name: Run Linting (Ruff) run: ruff check . **Ruff**它是一个使用Rust编写的超快速Python linter。它结合了多个工具（Flake8、Black、isort）的功能，成为一个高性能的单一工具。 ==== 7. 测试执行 ```yaml ---- ---- - name: Run Tests (Pytest) run: pytest ---- Pytest 执行整个测试套件，确保修改不会引入回归。 == 部署流水线配置 (CD) === CD 工作流的结构 CD 工作流仅在 GitHub 发布时触发，并自动化将包发布到 PyPI： [source,yaml] ---- name: Publish to PyPI on: release: types: - published jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - name: Install dependencies run: | python -m pip install --upgrade pip pip install setuptools wheel twine - name: Build and publish env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} run: | python setup.py sdist bdist_wheel twine upload dist/* ---- === CD步骤分析 ==== 1. 触发器释放 ---- on: release: types: - published CD 管道仅在发布 GitHub 版本时触发。此方法确保对部署进行精确控制。 ==== 2. 安装构建工具 ```yaml ---- ---- pip install setuptools wheel twine ---- - **setuptools**Python打包工具 - **轮子**现代的 Python 发布格式 - **绳子**用于安全上传至 PyPI 的工具 ==== 3. 身份验证配置 ---- env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} 身份验证采用存储为 GitHub 密钥的 PyPI API 令牌，比传统凭据更安全。 ==== 4. 构建和发布 ```yaml ---- ---- run: | python setup.py sdist bdist_wheel twine upload dist/* ---- - `sdist`: 创建源分发 - `bdist_wheel`: 创建一个 wheel (二进制分发) - `twine upload`: 在 PyPI 上发布分发包 == Python包配置 === setup.py 的结构 为了让管道正常运行，您的项目必须包含一个文件`setup.py` : [source,python] ---- from setuptools import setup, find_packages with open("README.adoc", "r", encoding="utf-8") as fh: long_description = fh.read() setup( name="playlist-downloader", version="1.0.0", author="Votre Nom", author_email="votre.email@example.com", description="CLI tool for managing YouTube playlists", long_description=long_description, long_description_content_type="text/plain", url="https://github.com/cheroliv/playlist-downloader", packages=find_packages(), classifiers=[ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", ], python_requires=">=3.8", install_requires=[ "typer>=0.9.0", "yt-dlp>=2023.1.6", "google-api-python-client>=2.70.0", "google-auth-oauthlib>=0.7.1", "pymonad>=2.4.0", "pyyaml>=6.0", ], entry_points={ "console_scripts": [ "playlist-downloader=cli:app", ], }, ) ---- === setup.py 的关键点 1. **元数据**名称, 版本, 作者, 描述 2. **依赖**: 所需软件包列表 3. **入口点**:暴露的 CLI 命令 4. **分类器**: 用于 PyPI 的元数据 == 使用 GitHub Secrets 进行安全防护 === PyPI 令牌配置 1. **在 PyPI 上创建 API 令牌** : - 登录到 PyPI - 进入 账户设置 > API 令牌 - 创建一个具有适当权限的新令牌 1. **在 GitHub 中添加密钥**： - 仓库设置 > 密钥和变量 > 操作 - 创建一个新的已命名密钥`PYPI_API_TOKEN` - 粘贴您的 PyPI 令牌 [plantuml, secrets-flow, svg] ---- @startuml !theme plain actor Developer as dev participant "GitHub 仓库" as repo participant "GitHub Actions" as actions participant PyPI dev -> repo : Configure PYPI_API_TOKEN secret repo -> actions : Trigger CD pipeline on release actions -> actions : Access secret securely actions -> PyPI : Authenticate with token PyPI -> PyPI : Validate and publish package note over actions, PyPI Token never exposed in logs Automatic rotation possible end note @enduml ---- == 完整的部署工作流 === 部署顺序 [plantuml, deployment-sequence, svg] ---- @startuml !theme plain actor Developer as dev participant "本地 Git" as git participant "GitHub" as github participant "GitHub Actions" as actions participant PyPI participant "最终用户" as users dev -> git : git tag v1.0.0 dev -> git : git push origin v1.0.0 git -> github : Push tag dev -> github : Create release from tag github -> actions : Trigger CD pipeline actions -> actions : Checkout code actions -> actions : Setup Python environment actions -> actions : Install build tools actions -> actions : Build distributions (sdist + wheel) actions -> PyPI : Upload to PyPI with token PyPI -> PyPI : Validate and publish users -> PyPI : pip install playlist-downloader note over dev, github Release creation can be automated or done manually through GitHub UI end note @enduml ---- === 管道状态 [plantuml, pipeline-states, svg] ---- @startuml !theme plain [*] --> Idle Idle --> CI_Running : Push/PR created CI_Running --> CI_Success : All checks pass CI_Running --> CI_Failed : Linting/Tests fail CI_Success --> Idle : Merge completed CI_Failed --> Idle : Fix and retry Idle --> CD_Running : Release published CD_Running --> CD_Success : Package published CD_Running --> CD_Failed : Build/Upload error CD_Success --> Idle : Package available on PyPI CD_Failed --> Idle : Fix and retry release note on link #red : Blocks merge note on link #green : Allows deployment @enduml ---- == 良好实践与优化 === 1. 版本管理 使用语义化的 Git 标签： ---- git tag -a v1.2.3 -m "Release version 1.2.3" git push origin v1.2.3 === 2. 矩阵测试 为了在多个 Python 版本上进行测试： ```yaml ---- ---- strategy: matrix: python-version: [3.8, 3.9, "3.10", "3.11"] ---- === 3. 依赖缓存 用缓存加速构建： ---- - name: Cache pip dependencies uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} === 4. 部署环境 使用 GitHub 环境进行受控部署 : ```yaml ---- ---- jobs: deploy: environment: production runs-on: ubuntu-latest ---- == 用例和架构 === 用例图 [plantuml, use-cases, svg] ---- @startuml !theme plain left to right direction actor "开发者" as dev actor "GitHub Actions" as ga actor "终端用户" as user package "CI/CD 系统" { usecase "运行代码检查" as lint usecase "�执行测试" as test usecase "构建包" as build usecase "发布到 PyPI" as publish usecase "创建版本" as release } dev --> lint : Pushes code dev --> test : Pushes code dev --> release : Creates release ga --> build : On release trigger ga --> publish : After successful build user --> publish : Downloads package lint .> test : triggers test .> build : on success build .> publish : on success @enduml ---- === 部署架构 [plantuml, deployment-architecture, svg] ---- @startuml !theme plain cloud "GitHub" { [Source Repository] [GitHub Actions] [Secrets Store] } cloud "PyPI" { [Package Registry] [Distribution Files] } node "CI/CD 流水线" { [Linting] [Testing] [Building] [Publishing] } [Source Repository] --> [GitHub Actions] : Triggers [GitHub Actions] --> [Linting] [Linting] --> [Testing] [Testing] --> [Building] [Building] --> [Publishing] [Publishing] --> [Package Registry] : Uploads [Secrets Store] --> [Publishing] : Provides token note as N1 Secure token-based authentication end note [Secrets Store] .. N1 @enduml ---- == �监控和调试 === 日志和监控 GitHub Actions 提供每个步骤的详细日志。为了调试： 1. **�检查日志**每个步骤的 2. **启用调试**与`ACTIONS_STEP_DEBUG` 3. **使用 artifacts**为了保存构建文件 ---- - name: Upload build artifacts uses: actions/upload-artifact@v3 if: failure() with: name: build-logs path: build/ === 通知 �添加 Slack 或电子邮件通知： ```yaml ---- ---- - name: Notify on failure if: failure() uses: 8398a7/action-slack@v3 with: status: ${{ job.status }} webhook_url: ${{ secrets.SLACK_WEBHOOK }} ---- == 结论 使用 GitHub Actions 建立一个强大的 CI/CD 流水线彻底改变了开发体验。通过自动化 linting、测试和部署，您： - **减少错误**正在生产 - **加速循环**的发展 - **提升信任**在您的发布版 - **�促进协作**作为一个团队 此管道可以通过调整 lint 工具、测试框架或部署目标来适应不同类型的 Python 项目。 对这些工作流程进行初始配置的投资能够很快通过节省时间和减少部署过程中的手动错误来收回成本。 == 补充资源 - https://docs.github.com/en/actions[GitHub Actions 文档] - https://packaging.python.org/[Python 打包指南] - https://docs.pytest.org/[Pytest 文档] - https://docs.astral.sh/ruff/[文档 Ruff] - https://twine.readthedocs.io/[文档 Twine] ✅ 功能管道已达成！ 您现在拥有一个简单的 CI/CD 流水线，可以让您自动化测试并直接从 GitHub Actions 将 Python 包发布到 PyPI。 然而，此流水线仍然保持故意的极简主义。它尚未涵盖在专业环境中必不可少的一些方面： 多版本 Python 测试, 自动安全分析， 通过 Test PyPI 进行渐进式部署, 流水线的监控和指标 自动化版本控制并集成现代最佳实践（pyproject.toml）。 在下一部分，我们将进入更高一步。您将学习如何将这个基本的管道转换为真正的工业级部署链——健壮且安全，并准备好用于生产环境的 Python 项目。 ----</code></pre> </div> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0084_disco_bot_discord_python_post.html Wed, 16 Jul 2025 00:00:00 +0000 blog/2025/0084_disco_bot_discord_python_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_背景和当前挑战">背景和当前挑战</a> <ul class="sectlevel2"> <li><a href="#_音乐_api_的演变">音乐 API 的演变</a></li> <li><a href="#_日志驱动开发">日志驱动开发</a></li> </ul> </li> <li><a href="#_概念架构">概念架构</a></li> <li><a href="#_技术栈和函数式范式">技术栈和函数式范式</a> <ul class="sectlevel2"> <li><a href="#_技术选择">技术选择</a></li> <li><a href="#_应用功能原理">应用功能原理</a></li> </ul> </li> <li><a href="#_敏捷方法论和backlog">敏捷方法论和Backlog</a> <ul class="sectlevel2"> <li><a href="#_主要史诗">主要史诗</a> <ul class="sectlevel3"> <li><a href="#_史诗_1基础设施机器人_discord">史诗 1：基础设施机器人 Discord</a></li> <li><a href="#_史诗_2spotify_集成">史诗 2：Spotify 集成</a></li> <li><a href="#_史诗_3youtube_集成">史诗 3：YouTube 集成</a></li> <li><a href="#_epic_4_音乐功能">Epic 4 : 音乐功能</a></li> </ul> </li> <li><a href="#_详细的用户故事">�详细的用户故事</a> <ul class="sectlevel3"> <li><a href="#_us1_1_机器人初始化">US1.1 : 机器人初始化</a></li> <li><a href="#_us2_1_智能_spotify_搜索">US2.1 : 智能 Spotify 搜索</a></li> <li><a href="#_us3_1_有弹性的_youtube_提取">US3.1 : 有弹性的 YouTube 提取</a></li> </ul> </li> </ul> </li> <li><a href="#_日志驱动开发方法">日志驱动开发方法</a> <ul class="sectlevel2"> <li><a href="#_日志策略">日志策略</a></li> <li><a href="#_日志结构">日志结构</a></li> <li><a href="#_日志设计示例">日志设计示例</a></li> </ul> </li> <li><a href="#_使用_pydantic_的验证架构">使用 Pydantic 的验证架构</a> <ul class="sectlevel2"> <li><a href="#_数据模型">数据模型</a></li> </ul> </li> <li><a href="#_功能性错误管理">功能性错误管理</a> <ul class="sectlevel2"> <li><a href="#_单子和错误处理">单子和错误处理</a></li> </ul> </li> <li><a href="#_规避限制的策略">规避限制的策略</a> <ul class="sectlevel2"> <li><a href="#_多源方法">多源方法</a></li> </ul> </li> <li><a href="#_迭代开发计划">迭代开发计划</a> <ul class="sectlevel2"> <li><a href="#_冲刺计划">冲刺计划</a></li> <li><a href="#_质量指标">质量指标</a></li> </ul> </li> <li><a href="#_部署与监控">部署与监控</a> <ul class="sectlevel2"> <li><a href="#_生产架构">生产架构</a></li> <li><a href="#_主动监控">主动监控</a></li> </ul> </li> <li><a href="#_结论与展望">结论与展望</a> <ul class="sectlevel2"> <li><a href="#_下一步">下一步</a></li> </ul> </li> </ul> </div> <div class="sect1"> <h2 id="_介绍"><a class="anchor" href="#_介绍"></a>介绍</h2> <div class="sectionbody"> <div class="paragraph"> <p>开发一个集成 Spotify 和 YouTube API 的 Discord 机器人代表了一项现代技术挑战，特别是在面对平台最近的限制和演变时。本文介绍了一种基于的方法论方法。<strong>日志驱动开发</strong>(LDD) 是一种在函数式编程范式中以 Python 实现的测试驱动开发的扩展。</p> </div> <div class="paragraph"> <p>我们的目标：创建一个健壮、可维护且可扩展的机器人，能够应对当前音乐 API 的限制，同时在 Discord 上提供流畅的用户体验。</p> </div> </div> </div> <div class="sect1"> <h2 id="_背景和当前挑战"><a class="anchor" href="#_背景和当前挑战"></a>背景和当前挑战</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_音乐_api_的演变"><a class="anchor" href="#_音乐_api_的演变"></a>音乐 API 的演变</h3> <div class="paragraph"> <p>音乐平台已经大幅收紧了他们的访问政策：</p> </div> <div class="ulist"> <ul> <li> <p><strong>Spotify</strong>对元数据访问的限制，配额限制</p> </li> <li> <p><strong>油管</strong>: 强化的反机器人政策，身份验证的复杂化</p> </li> <li> <p><strong>Discord</strong>: 新的安全和性能要求</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_日志驱动开发"><a class="anchor" href="#_日志驱动开发"></a>日志驱动开发</h3> <div class="paragraph"> <p>LDD 通过将日志置于开发核心来扩展 TDD :</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>日志的定义</strong>在实施前</p> </li> <li> <p><strong>通过观察验证</strong>预期的行为</p> </li> <li> <p><strong>完整追踪</strong>数据流</p> </li> <li> <p><strong>主动调试</strong>为预防错误</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_概念架构"><a class="anchor" href="#_概念架构"></a>概念架构</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-1a758d5babf1cc2d4a0bdb0a97211257.png" alt="Diagram" width="777" height="618"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_技术栈和函数式范式"><a class="anchor" href="#_技术栈和函数式范式"></a>技术栈和函数式范式</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_技术选择"><a class="anchor" href="#_技术选择"></a>技术选择</h3> <div class="paragraph"> <p>我们的技术栈围绕函数式编程展开 ：</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>PyMonade</strong></dt> <dd> <p>副作用管理与函数组合</p> </dd> <dt class="hdlist1"><strong>Pydantic</strong></dt> <dd> <p>类型安全的数据验证和序列化</p> </dd> <dt class="hdlist1"><strong>异步 I/O</strong></dt> <dd> <p>用于 API 的异步编程</p> </dd> <dt class="hdlist1"><strong>Structlog</strong></dt> <dd> <p>用于LDD的结构化日志</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_应用功能原理"><a class="anchor" href="#_应用功能原理"></a>应用功能原理</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-7bf34fbfe52bbfdec2e412de8f53bf10.png" alt="Diagram" width="670" height="554"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_敏捷方法论和backlog"><a class="anchor" href="#_敏捷方法论和backlog"></a>敏捷方法论和Backlog</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_主要史诗"><a class="anchor" href="#_主要史诗"></a>主要史诗</h3> <div class="paragraph"> <p>我们的开发围绕4个主要的史诗：</p> </div> <div class="sect3"> <h4 id="_史诗_1基础设施机器人_discord"><a class="anchor" href="#_史诗_1基础设施机器人_discord"></a>史诗 1：基础设施机器人 Discord</h4> <div class="paragraph"> <p><strong>业务价值</strong> :坚实且可扩展的基础</p> </div> <div class="paragraph"> <p><strong>验收标准</strong> : 稳定的 Discord 连接，配备重连管理 - 模块化命令系统 - 集成结构化日志 - 集中错误管理</p> </div> </div> <div class="sect3"> <h4 id="_史诗_2spotify_集成"><a class="anchor" href="#_史诗_2spotify_集成"></a>史诗 2：Spotify 集成</h4> <div class="paragraph"> <p><strong>业务价值</strong> : 访问音乐元数据</p> </div> <div class="paragraph"> <p><strong>验收标准</strong> : - 安全的OAuth2身份验证 - 使用智能缓存的曲目搜索 - API配额管理 - 网络错误的回退</p> </div> </div> <div class="sect3"> <h4 id="_史诗_3youtube_集成"><a class="anchor" href="#_史诗_3youtube_集成"></a>史诗 3：YouTube 集成</h4> <div class="paragraph"> <p><strong>业务价值</strong> : 访问音频内容</p> </div> <div class="paragraph"> <p><strong>验收标准</strong> - 合法规避限制 - 优化的音频提取 - 管理私有/已删除的视频 - 遵守 YouTube 的服务条款</p> </div> </div> <div class="sect3"> <h4 id="_epic_4_音乐功能"><a class="anchor" href="#_epic_4_音乐功能"></a>Epic 4 : 音乐功能</h4> <div class="paragraph"> <p><strong>业务价值</strong> : 完整的用户体验</p> </div> <div class="paragraph"> <p><strong>接受标准</strong> - 高质量音频播放 - 智能阅读队列 - Discord 语音命令 - 跨平台同步</p> </div> </div> </div> <div class="sect2"> <h3 id="_详细的用户故事"><a class="anchor" href="#_详细的用户故事"></a>�详细的用户故事</h3> <div class="sect3"> <h4 id="_us1_1_机器人初始化"><a class="anchor" href="#_us1_1_机器人初始化"></a>US1.1 : 机器人初始化</h4> <div class="paragraph"> <p><strong>作为</strong> 开发者 <strong>我想要</strong> 一个可靠连接的Discord机器人 <strong>Afin de</strong> 为了确保服务的可用性</p> </div> <div class="paragraph"> <p><strong>DoD (完成的定义)</strong> : - [ ] 机器人在启动时自动连接 - [ ] 结构化日志记录每一步 - [ ] 自动重连（断开连接时） - [ ] 集成测试通过</p> </div> </div> <div class="sect3"> <h4 id="_us2_1_智能_spotify_搜索"><a class="anchor" href="#_us2_1_智能_spotify_搜索"></a>US2.1 : 智能 Spotify 搜索</h4> <div class="paragraph"> <p><strong>作为</strong> 用户 Discord <strong>我想</strong> 通过 Spotify 搜索曲目 <strong>为了</strong> 发现和分享音乐</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] 订单`/search`功能的 - [ ] 相关结果，带有元数据 - [ ] 本地缓存以优化请求 - [ ] 优雅的API错误处理</p> </div> </div> <div class="sect3"> <h4 id="_us3_1_有弹性的_youtube_提取"><a class="anchor" href="#_us3_1_有弹性的_youtube_提取"></a>US3.1 : 有弹性的 YouTube 提取</h4> <div class="paragraph"> <p>作为系统 <strong>我想</strong> 可靠地提取 YouTube 音频 为了 保持服务的连续性</p> </div> <div class="paragraph"> <p><strong>DoD</strong> : - [ ] 不违反服务条款的提取 - [ ] 音质最佳 - [ ] 管理地理限制 - [ ] 详细的操作日志</p> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_日志驱动开发方法"><a class="anchor" href="#_日志驱动开发方法"></a>日志驱动开发方法</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_日志策略"><a class="anchor" href="#_日志策略"></a>日志策略</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-9705e19776eeb21de285dd1348680ff9.png" alt="Diagram" width="687" height="633"> </div> </div> </div> <div class="sect2"> <h3 id="_日志结构"><a class="anchor" href="#_日志结构"></a>日志结构</h3> <div class="paragraph"> <p>我们的LDD方法使用带有语义级别的结构化日志：</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>痕迹</strong></dt> <dd> <p>�详细数据流</p> </dd> <dt class="hdlist1"><strong>调试</strong></dt> <dd> <p>函数的内部状态</p> </dd> <dt class="hdlist1"><strong>信息</strong></dt> <dd> <p>成功的业务运营</p> </dd> <dt class="hdlist1"><strong>警告</strong></dt> <dd> <p>降级但得到管理的情况</p> </dd> <dt class="hdlist1"><strong>错误</strong></dt> <dd> <p>需要干预的错误</p> </dd> <dt class="hdlist1"><strong>关键</strong></dt> <dd> <p>系统故障</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_日志设计示例"><a class="anchor" href="#_日志设计示例"></a>日志设计示例</h3> <div class="paragraph"> <p>在实现 Spotify 搜索功能之前，我们先定义它的日志：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">INFO: spotify.search.start query="bohemian rhapsody" user_id=123456 DEBUG: spotify.search.validation query_length=16 safe_chars=true DEBUG: spotify.search.api_call endpoint="/search" params={...} INFO: spotify.search.success results_count=15 duration_ms=340</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用_pydantic_的验证架构"><a class="anchor" href="#_使用_pydantic_的验证架构"></a>使用 Pydantic 的验证架构</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_数据模型"><a class="anchor" href="#_数据模型"></a>数据模型</h3> <div class="paragraph"> <p>我们的功能方法优先考虑前置验证：</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-ebd4e1dfbd7b19d5a6054ecf213e9e2d.png" alt="Diagram" width="696" height="339"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_功能性错误管理"><a class="anchor" href="#_功能性错误管理"></a>功能性错误管理</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_单子和错误处理"><a class="anchor" href="#_单子和错误处理"></a>单子和错误处理</h3> <div class="paragraph"> <p>使用 PyMonade 可以实现优雅的错误处理：</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-136202d4ff85a3301d5f061e8e0d5d86.png" alt="Diagram" width="466" height="494"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_规避限制的策略"><a class="anchor" href="#_规避限制的策略"></a>规避限制的策略</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_多源方法"><a class="anchor" href="#_多源方法"></a>多源方法</h3> <div class="paragraph"> <p>面对 API 限制，我们采取了多元化策略：</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-7d9e8e51fad9678862e67af0f945456e.png" alt="Diagram" width="665" height="744"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_迭代开发计划"><a class="anchor" href="#_迭代开发计划"></a>迭代开发计划</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_冲刺计划"><a class="anchor" href="#_冲刺计划"></a>冲刺计划</h3> <div class="paragraph"> <p>我们的开发遵循为期两周的冲刺周期 :</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><strong>冲刺 1-2</strong></dt> <dd> <p>基础设施和 Discord Bot 核心</p> </dd> <dt class="hdlist1"><strong>冲刺 3-4</strong></dt> <dd> <p>Spotify 与 LDD 的集成</p> </dd> <dt class="hdlist1"><strong>�冲刺 5-6</strong></dt> <dd> <p>YouTube 集成与规避</p> </dd> <dt class="hdlist1"><strong>冲刺 7-8</strong></dt> <dd> <p>高级音乐功能</p> </dd> <dt class="hdlist1"><strong>�冲刺 9-10</strong></dt> <dd> <p>优化与生产</p> </dd> </dl> </div> </div> <div class="sect2"> <h3 id="_质量指标"><a class="anchor" href="#_质量指标"></a>质量指标</h3> <div class="paragraph"> <p>每个 sprint 的评估基于 :</p> </div> <div class="ulist"> <ul> <li> <p><strong>日志覆盖</strong>: >90% 的关键路径</p> </li> <li> <p><strong>API 可靠性</strong>: <1% 未处理的错误</p> </li> <li> <p><strong>性能</strong>: <500ms 平均响应时间</p> </li> <li> <p><strong>可维护性</strong>圈复杂度 <10</p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_部署与监控"><a class="anchor" href="#_部署与监控"></a>部署与监控</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_生产架构"><a class="anchor" href="#_生产架构"></a>生产架构</h3> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-64260b24081cf450e8871a253b326f1b.png" alt="Diagram" width="938" height="381"> </div> </div> </div> <div class="sect2"> <h3 id="_主动监控"><a class="anchor" href="#_主动监控"></a>主动监控</h3> <div class="paragraph"> <p>LDD 有助于智能监控：</p> </div> <div class="ulist"> <ul> <li> <p><strong>基于日志模式的警报</strong></p> </li> <li> <p><strong>行为异常检测</strong></p> </li> <li> <p><strong>实时业务指标</strong></p> </li> <li> <p><strong>日志关联的调试辅助</strong></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论与展望"><a class="anchor" href="#_结论与展望"></a>结论与展望</h2> <div class="sectionbody"> <div class="paragraph"> <p>这种方法论结合了函数式编程范式的优势与日志驱动开发（Log Driven Development）的稳健性。它使我们能够：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>预见问题</strong>得益于预先设计的日志</p> </li> <li> <p><strong>保持质量</strong>通过持续验证</p> </li> <li> <p><strong>快速适应</strong>对 API 的变更</p> </li> <li> <p><strong>确保可追溯性</strong>完整的操作</p> </li> </ol> </div> <div class="paragraph"> <p>迭代开发和模块化架构确保了在面对音乐平台不断变化的约束时的可扩展性。</p> </div> <div class="sect2"> <h3 id="_下一步"><a class="anchor" href="#_下一步"></a>下一步</h3> <div class="ulist"> <ul> <li> <p><strong>第一阶段</strong>使用 PyMonade 实现核心</p> </li> <li> <p><strong>阶段 2</strong>: 带有智能缓存的 Spotify 集成</p> </li> <li> <p><strong>阶段 3</strong>有弹性的 YouTube 解决方案</p> </li> <li> <p><strong>第四阶段</strong>: 高级特性和优化</p> </li> </ul> </div> <div class="paragraph"> <p>这个坚实的概念性基础将使我们能够在交付卓越用户体验的同时应对技术挑战。</p> </div> <hr> <div class="paragraph"> <p><strong>本文将随后提供一系列技术文章，详细介绍每个组件的实现，并附带代码示例和函数式模式。</strong></p> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0083_cold_computer_post.html Tue, 15 Jul 2025 00:00:00 +0000 blog/2025/0083_cold_computer_post.html <div id="toc" class="toc"> <div id="toctitle">Table of Contents</div> <ul class="sectlevel1"> <li><a href="#_本指南的目标">本指南的目标</a></li> <li><a href="#_先决条件">先决条件</a></li> <li><a href="#_安装并配置工具">安装并配置工具</a> <ul class="sectlevel2"> <li><a href="#_lm_sensors_用于检测传感器">lm-sensors` 用于检测传感器</a></li> <li><a href="#_tlp_智能能源管理器">tlp` : 智能能源管理器</a></li> <li><a href="#_cpufrequtils_限制cpu频率">cpufrequtils` : 限制CPU频率</a></li> <li><a href="#_auto_cpufreq_简化的动态管理">auto-cpufreq` : 简化的动态管理</a></li> <li><a href="#_thermald_自动热保护">thermald` : 自动热保护</a></li> </ul> </li> <li><a href="#_实时监控">实时监控</a> <ul class="sectlevel2"> <li><a href="#_sensors_在命令行中">sensors` 在命令行中</a></li> <li><a href="#_选项_gui_psensor">选项 GUI : `psensor</a></li> </ul> </li> <li><a href="#_额外技巧">额外技巧</a></li> <li><a href="#_清理系统以限制过载">清理系统以限制过载</a></li> <li><a href="#_更进一步">更进一步</a></li> <li><a href="#_结论">📚 结论</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>您是否感觉到您的笔记本电脑在Ubuntu下异常发热？ 这篇文章为您提出了一种方法<strong>软件</strong>完整的 为了<strong>冷却</strong>, <strong>�监控</strong> et <strong>控制温度</strong>您的机器的。</p> </div> </div> </div> <div class="sect1"> <h2 id="_本指南的目标">本指南的目标</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>降低计算机的整体温度</p> </li> <li> <p>优化能源管理</p> </li> <li> <p>�监控关键组件（CPU、GPU等）</p> </li> <li> <p>避免由于造成的减速<strong>热降频</strong></p> </li> </ul> </div> <div class="imageblock"> <div class="content"> <img src="gestion_thermique.svg" alt="gestion thermique" width="392" height="298"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_先决条件">先决条件</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>Ubuntu 机器（推荐使用 20.04 或更高版本）</p> </li> <li> <p>互联网连接</p> </li> <li> <p>命令行能力（初级到中级）</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_安装并配置工具">安装并配置工具</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_lm_sensors_用于检测传感器">lm-sensors` 用于检测传感器</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install lm-sensors sudo sensors-detect sensors</code></pre> </div> </div> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p>请回答`YES`对所有问题的`sensors-detect`检测模块。</p> </div> </td> </tr> </table> </div> </div> <div class="sect2"> <h3 id="_tlp_智能能源管理器">tlp` : 智能能源管理器</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install tlp tlp-rdw sudo systemctl enable tlp sudo systemctl start tlp</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="tlp_etat.svg" alt="tlp etat" width="156" height="390"> </div> </div> </div> <div class="sect2"> <h3 id="_cpufrequtils_限制cpu频率">cpufrequtils` : 限制CPU频率</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install cpufrequtils cpufreq-info sudo cpufreq-set -g powersave</code></pre> </div> </div> <div class="ulist"> <ul> <li> <p><code>powersave</code>: 限制频率峰值</p> </li> <li> <p><code>performance</code>: 更倾向于功率，以牺牲温度为代价</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_auto_cpufreq_简化的动态管理">auto-cpufreq` : 简化的动态管理</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">git clone https://github.com/AdnanHodzic/auto-cpufreq.git cd auto-cpufreq sudo ./auto-cpufreq-installer sudo auto-cpufreq --install</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="auto_cpufreq_cycle.svg" alt="auto cpufreq cycle" width="189" height="298"> </div> </div> </div> <div class="sect2"> <h3 id="_thermald_自动热保护">thermald` : 自动热保护</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install thermald sudo systemctl enable thermald sudo systemctl start thermald</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_实时监控">实时监控</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_sensors_在命令行中">sensors` 在命令行中</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">watch -n 2 sensors</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_选项_gui_psensor">选项 GUI : `psensor</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install psensor</code></pre> </div> </div> <div class="quoteblock"> <blockquote> <div class="paragraph"> <p>简单的 CPU、GPU、风扇图形界面。</p> </div> </blockquote> </div> </div> </div> </div> <div class="sect1"> <h2 id="_额外技巧">额外技巧</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>关闭标签页和资源密集型应用程序 (例如: 浏览器)</p> </li> <li> <p>避免在电池上进行高强度使用</p> </li> <li> <p>通过监控进程`htop` :</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt install htop htop</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_清理系统以限制过载">清理系统以限制过载</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">sudo apt autoremove sudo apt autoclean sudo journalctl --vacuum-time=3d</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_更进一步">更进一步</h2> <div class="sectionbody"> <div class="paragraph"> <p>您可以创建一个服务`systemd`自定义以在启动时自动应用某些设置。 您想在下一篇文章中看到一个例子吗？请告诉我！</p> </div> </div> </div> <div class="sect1"> <h2 id="_结论">📚 结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>结合这些简单的工具，您将获得：</p> </div> <div class="ulist"> <ul> <li> <p>受控的CPU温度</p> </li> <li> <p>更少的通风噪音</p> </li> <li> <p>更好的自主性</p> </li> </ul> </div> <div class="paragraph"> <p>请记得定期监控您的温度，以防止过热。</p> </div> <div class="paragraph"> <p>(No visible content to translate) 与其让CPU熔化，不如提前预防。 <em>__</em></p> </div> </div> </div> https://cheroliv.com/blog/2025/0082_ui_struggle_post.html Mon, 14 Jul 2025 00:00:00 +0000 blog/2025/0082_ui_struggle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_战场一个模型三个浏览器多种渲染">战场：一个模型，三个浏览器，多种渲染</a></li> <li><a href="#_问题1hero部分的飞行卡">问题1：'Hero’部分的飞行卡</a></li> <li><a href="#_问题_2食人导航栏">问题 2：食人导航栏</a></li> <li><a href="#_问题3排版混乱">问题3：排版混乱</a></li> <li><a href="#_问题4导航栏溢出">问题4：导航栏溢出</a></li> <li><a href="#_问题_5不可见的汉堡菜单">问题 5：不可见的汉堡菜单</a></li> <li><a href="#_结论艰苦调试的教训">结论：艰苦调试的教训</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="admonitionblock note"> <table> <tr> <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>阅读时间：*大约 7 分钟 *Niveau :</strong> 中等</p> </div> </td> </tr> </table> </div> <div class="paragraph"> <p>在这个详细案例研究中，我们将分析在使用 Bootstrap 5.2 创建 UI 设计稿时遇到的最常见且有时最令人沮丧的浏览器兼容性问题。从 Flexbox 的管理到字体渲染的细微差别，探索我们的调试过程，以将 Firefox 下出错的布局转变为在所有浏览器上都能实现像素完美的体验。</p> </div> <hr> </div> </div> <div class="sect1"> <h2 id="_战场一个模型三个浏览器多种渲染">战场：一个模型，三个浏览器，多种渲染</h2> <div class="sectionbody"> <div class="paragraph"> <p>每位前端开发者都有这种感觉。经过数小时的工作，稿子终于完美了。对齐清晰，排版优雅，动画流畅。我们松了一口气，满意地欣赏自己在 Chrome（或 Brave、或 Edge）上的作品，随后出于职责，打开项目在 Firefox 上查看。这时候，灾难就来了。元素溢出，对齐被破坏，字体大小混乱……美好的和谐瞬间消失。</p> </div> <div class="paragraph"> <p>这是我们在开发新的作品集界面时面临的确切场景。需求很简单：一个现代、响应式的主页，带有主题选择器（亮色、暗色和高对比度），使用 <strong>vanilla JavaScript</strong> 和 <strong>Bootstrap 5.2</strong> 的最新版本。</p> </div> <div class="paragraph"> <p>这篇文章不是灵丹妙药解决方案的清单。它是我们调试会话的日志，深入探讨了Blink引擎（Chromium、Brave）和Gecko引擎（Firefox）之间渲染差异的“为什么”，并表明稳健而现代的解决方案总比仓促的补丁更好。</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/usecase-debugging-firefox.svg" alt="usecase debugging firefox" width="1222" height="5484"> </div> <div class="title">Figure 1. 用例图: 调试过程</div> </div> <div class="paragraph"> <p>组件图：前端解决方案架构</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/components-solution-architecture.svg" alt="components solution architecture" width="1250" height="5160"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_问题1hero部分的飞行卡">问题1：'Hero’部分的飞行卡</h2> <div class="sectionbody"> <div class="paragraph"> <p>第一个错误也是最明显的错误。首页（“hero”）部分由两列组成：左侧是主标题；右侧是介绍卡片。</p> </div> <div class="ulist"> <ul> <li> <p><strong>症状 :</strong>在 Chrome 和 Brave 中，两列完全垂直居中。在 Firefox 中，右侧卡片莫名其妙地掉到了左侧文本下方。</p> </li> <li> <p><strong>调查：</strong>HTML 代码看起来却很简单且正确，使用了 Bootstrap 的标准类。</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container"> <!-- Cette ligne est la clé du problème --> <div class="row align-items-center min-vh-100"> <div class="col-lg-6"> <!-- Contenu de gauche --> </div> <div class="col-lg-6"> <!-- Carte de droite --> </div> </div> </div> </section></code></pre> </div> </div> <div class="paragraph"> <p>我们的自定义CSS为`.hero-section`定义`display: flex` et <code>align-items: center</code>, 以及该班级`min-vh-100`它确实为该行提供了最小的高度`div.row`). 那么，为什么 Firefox 拒绝居中这些列？</p> </div> <div class="ulist"> <ul> <li> <p><strong>根本原因：</strong>这是一个关于渲染引擎如何解释隐式高度的教科书案例。La`<section>`有一个`min-height`,但是没有`height`显式。为了应用`align-items-center`在…​内部`div.row`, Firefox 需要知道此容器的参考高度。就像它的父元素 (<code>div.container</code> et la `<section>`她自己)没有高度<strong>严格的</strong>, Firefox 迷失了。 Blink 引擎更宽松，能够“猜测”意图并将元素居中。 Gecko 更忠实于规范，则不会这样做。</p> </li> <li> <p><strong>解决方案：</strong>将高度显式化。我们已经强制了`.container` et le `.row`占用其父容器100%的高度，使用该实用类`h-100`的Bootstrap。</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><section id="home" class="hero-section"> <div class="container h-100"> <div class="row align-items-center min-vh-100 h-100"> <!-- ... --> </div> </div> </section></code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p>当一个`align-items`如果 Flexbox 在垂直轴上未按预期工作，请始终检查容器是否有高度`height` ou <code>min-height</code>) 定义后，如果问题仍然存在（尤其是在 Firefox 上），请确保中间的父容器正确地传递此高度。</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_问题_2食人导航栏">问题 2：食人导航栏</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">在对齐"Hero"部分后，出现了另一个问题：导航栏，带有其类`fixed-top`, 叠加在标题上。 Un`padding-top: 80px`已被应用于 "Hero" 部分作为解决方案。</div> <ul> <li> <p><strong>�症状：</strong> Le `padding`在 Chrome 上已经足够，但在 Firefox 上却不够，标题仍然被部分遮挡。</p> </li> <li> <p><strong>根本原因 :</strong>使用一个"魔数`80px`) 是一种非常糟糕的做法。像导航栏这样的元素的高度可能会因浏览器之间的细微差异（如字体渲染、间距或甚至用户设置）而相差几个像素。依赖固定值是脆弱设计的根源。</p> </li> <li> <p><strong>解决方案：</strong>一个动态且无懈可击的 JavaScript 解决方案。我们编写了一个小脚本用于：</p> </li> <li> <p>�测量导航栏在页面渲染后的*实际*高度。</p> </li> <li> <p>应用此测量高度作为`padding-top`到“Hero”部分。</p> </li> <li> <p>每次窗口尺寸变化时重新执行此函数，以适应变化（如切换到汉堡菜单）。</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">document.addEventListener('DOMContentLoaded', function() { function adjustHeroPadding() { const navbar = document.querySelector('.navbar.fixed-top'); const heroSection = document.querySelector('.hero-section'); if (navbar && heroSection) { const navbarHeight = navbar.offsetHeight; heroSection.style.paddingTop = navbarHeight + 'px'; } } // Ajuster au chargement et au redimensionnement adjustHeroPadding(); window.addEventListener('resize', adjustHeroPadding); });</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/sequence-dynamic-padding.svg" alt="sequence dynamic padding" width="895" height="703"> </div> <div class="title">Figure 2. 序列图：动态调整填充</div> </div> <div class="paragraph"> <p>与此同时，我们当然删除了该规则`padding-top: 80px;`我们的文件`styles.css`。</p> </div> </div> </div> <div class="sect1"> <h2 id="_问题3排版混乱">问题3：排版混乱</h2> <div class="sectionbody"> <div class="paragraph"> <p>接下来的问题是对品牌形象最不利的：主标题的大小。</p> </div> <div class="ulist"> <ul> <li> <p><strong>�症状：</strong>在Firefox上，标题“Développeur Formateur…​”的字体巨大，几乎令人震惊，而它在其他浏览器上却很和谐。</p> </li> <li> <p><strong>根本原因：</strong>标题使用了一个类`display-4`Bootstrap。这些类使用响应式字体大小，通常基于单位`rem`媒体查询。再次，Firefox的渲染算法结合了“Inter”字体，导致在我们的1920x1080分辨率下出现了远大于预期的尺寸计算。</p> </li> <li> <p><strong>解决方案：</strong>使用 CSS 函数重新获得控制`clamp()<code>. 此功能是流畅排版的革命。它允许使用三个值定义字体大小：一个最小值，一个“首选”值（会随视图宽度自适应”，`vw</code>），以及最大尺寸。</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">.hero-content h1 { color: var(--text-primary); line-height: 1.2; /* Min: 2rem Préférée: s'adapte à la vue Max: 2.5rem (40px) */ font-size: clamp(2rem, 1.2rem + 1.5vw, 2.5rem); }</code></pre> </div> </div> <div class="paragraph"> <p>与`clamp()<code>, 我们可以告诉浏览器 : "让字体随着屏幕增大，不要超过<strong>从不</strong>的限制`2.5rem</code>. 这使得所有浏览器的渲染瞬间统一，让我们对最终的美学拥有完全控制。</p> </div> </div> </div> <div class="sect1"> <h2 id="_问题4导航栏溢出">问题4：导航栏溢出</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">这个问题给我们带来了最大的麻烦，并且最终揭示了渲染微小差异的深层特性。</div> <ul> <li> <p><strong>�症状：</strong>在1920×1080的屏幕上，菜单中的最后几个链接（“Blog”、“Contact”）被推到了屏幕右侧外，但仅在Firefox中出现。</p> </li> <li> <p><strong>根本原因：</strong>在多次尝试失败后（更改Bootstrap的断点`lg` à <code>xl`然后`xxl</code>),我们已经明白了。原因不是Bootstrap的逻辑，而是一个简单的宽度计算。在Firefox上，所有链接宽度的总和，包括它们的`padding` et `margin`以亚像素精度，<strong>légèrement</strong> 超过 1920 像素。在 Chrome 上，同样的总和 <strong>légèrement</strong> 不足。我们缺少了几个像素。</p> </li> <li> <p><strong>解决方案：</strong>手术般的间距缩减。由于不可能使用过时的 CSS hack 专门针对 Firefox，唯一整洁的解决方案是找到一种在所有地方都通用的样式。因此，我们稍微减小了每个导航链接的水平外边距和内边距。</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* La version finale, légèrement plus compacte */ .navbar-nav .nav-link { font-size: 0.9rem; /* 90% de la taille de base */ color: var(--text-primary) !important; font-weight: 500; margin: 0 0.2rem; padding: 0.5rem 0.5rem !important; border-radius: 0.375rem; transition: all 0.3s ease; }</code></pre> </div> </div> <div class="paragraph"> <p>这种减少在单个元素上几乎肉眼不可见，却让我们在整体上获得了足够的空间，使所有链接能够放入 Firefox 的框架内，同时在其他浏览器上保持几乎相同的外观。</p> </div> </div> </div> <div class="sect1"> <h2 id="_问题_5不可见的汉堡菜单">问题 5：不可见的汉堡菜单</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">最后一个问题，而且并非小问题，涉及移动端的可访问性。</div> <ul> <li> <p><strong>�症状：</strong>在响应式模式（汉堡菜单），菜单图标在 "dark" 和 "high-contrast" 主题下不可见。</p> </li> <li> <p><strong>根本原因：</strong>Bootstrap 5的菜单图标是一个`background-image`(一个URL编码的SVG)。默认情况下，其描边颜色为深色，已针对浅色背景进行了优化。它不会自动适应主题的更改。</p> </li> <li> <p><strong>解决方案：</strong>使用 Bootstrap 的 CSS 变量来覆盖图标。我们已经定义了一个新的 SVG 图标，但这次使用了白色描边。<code>#ffffff`并且我们在主题时具体应用了它`dark</code> ou `high-contrast`活跃的</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-css hljs" data-lang="css">/* ====================== Fix pour l'icône du menu Burger (Blanc) ====================== */ [data-bs-theme="dark"] .navbar-toggler-icon, [data-bs-theme="high-contrast"] .navbar-toggler-icon { --bs-navbar-toggler-icon-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 30 30'%3e%3cpath stroke='%23ffffff' stroke-linecap='round' stroke-miterlimit='10' stroke-width='2' d='M4 7h22M4 15h22M4 23h22'/%3e%3c/svg%3e"); }</code></pre> </div> </div> <div class="admonitionblock important"> <table> <tr> <td class="icon"> <i class="fa icon-important" title="Important"></i> </td> <td class="content"> <div class="paragraph"> <p>像这样的Bootstrap组件的自定义通过覆盖CSS变量的方式变得越来越常见 (<code>--bs-component-property</code>), 这是最干净且最持久的方法。</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_结论艰苦调试的教训">结论：艰苦调试的教训</h2> <div class="sectionbody"> <div class="paragraph"> <p>虽然这条道路有时令人沮丧，但它充满了教训。每解决一个问题，都会强化网页开发的一条基本真理：<strong>没有什么能取代严格的跨浏览器测试。</strong>.</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/mindmap-debugging-summary.svg" alt="mindmap debugging summary" width="999" height="866"> </div> <div class="title">Figure 3. 思维导图 : 调试的综述与学到的教训</div> </div> <div class="paragraph"> <p>以下是我们记住的教训：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Firefox 是一个盟友：</strong>它对CSS标准的更高忠诚度迫使我们编写出更健壮且歧义更少的代码。</p> </li> <li> <p><strong>请远离"魔法数字" :</strong>固定值（如`padding-top: 80px`) 是定时炸弹。始终优先考虑动态解决方案(JavaScript)或相对布局(Flexbox, Grid)。</p> </li> <li> <p><strong>�掌握您的排版：</strong>使用`clamp()`用于完全控制响应式字体的大小。</p> </li> <li> <p><strong>想以 "组件" :</strong>要自定义 Bootstrap，请覆盖其 CSS 变量，而不是增加覆盖框架的规则。</p> </li> <li> <p><strong>不要面向特定的浏览器：</strong>解决方案几乎从不在于为特定浏览器进行 "hack" ，而在于找到一种在各处都能通用的样式。</p> </li> </ol> </div> <div class="paragraph"> <p>最终，原型现在坚固、可预测，并且准备好被集成到一个模板系统中。每个被修复的错误不是失败，而是迈向更高质量代码的一步。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0081_TDD_Gradle_Properties_Fix_post.html Sun, 13 Jul 2025 00:00:00 +0000 blog/2025/0081_TDD_Gradle_Properties_Fix_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_问题隔离_gradle_插件的单元测试">问题：隔离 Gradle 插件的单元测试</a> <ul class="sectlevel2"> <li><a href="#_问题的架构">问题的架构</a></li> <li><a href="#_假好主意的诱惑">假好主意的诱惑</a></li> </ul> </li> <li><a href="#_解决方案使用_extrapropertiesextension_模拟属性">解决方案：使用 <code>ExtraPropertiesExtension</code> 模拟属性</a> <ul class="sectlevel2"> <li><a href="#_步骤1理解extrapropertiesextension">步骤1：理解ExtraPropertiesExtension</a></li> <li><a href="#_步骤_2测试布置_准备">步骤 2：测试布置 - 准备</a></li> <li><a href="#_步骤_3_注入属性">步骤 3 : 注入属性</a></li> <li><a href="#_步骤_4_解决方案流程图">步骤 4 : 解决方案流程图</a></li> <li><a href="#_步骤_5_前后对比">步骤 5 : 前后对比</a></li> <li><a href="#_步骤_6管理多个测试用例">步骤 6：管理多个测试用例</a></li> <li><a href="#_解决方案的最终架构">解决方案的最终架构</a></li> </ul> </li> <li><a href="#_此方法的优势">此方法的优势</a></li> <li><a href="#_良好实践和建议">良好实践和建议</a> <ul class="sectlevel2"> <li><a href="#_创建一个实用方法">创建一个实用方法</a></li> <li><a href="#_属性验证">属性验证</a></li> </ul> </li> <li><a href="#_结论">结论</a></li> </ul> </div> <div class="sect1"> <h2 id="_问题隔离_gradle_插件的单元测试">问题：隔离 Gradle 插件的单元测试</h2> <div class="sectionbody"> <div class="paragraph"> <p>在编写Gradle插件的单元测试时，一个常见的挑战是管理对项目配置的依赖，例如在文件中定义的属性。<code>gradle.properties</code>. 在我们的情况下，插件`jbake.ghpages`应该读取一个属性`site_config_path`为了正常运行。 该任务的单元测试`initialize`它必须检查插件在此属性存在时的行为。</p> </div> <div class="paragraph"> <p>根本问题是，单元测试在设计上必须是 <strong>隔离</strong>。使用`ProjectBuilder`Gradle 创建一个…​ 的实例`Project`在内存中，完全与文件系统上的真实项目脱节。因此，此测试实例不会自动读取该文件。<code>gradle.properties`因此并不知道该属性`site_config_path</code>.</p> </div> <div class="sect2"> <h3 id="_问题的架构">问题的架构</h3> <div class="paragraph"> <p>以下图示说明了测试环境与文件系统之间的脱节 :</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/test-isolation-problem.svg" alt="test isolation problem" width="1226" height="5787"> </div> </div> </div> <div class="sect2"> <h3 id="_假好主意的诱惑">假好主意的诱惑</h3> <div class="paragraph"> <p>一种初步的方法可能是创建一个文件`gradle.properties`在测试资源中是虚假的。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">// src/test/resources/gradle.properties site_config_path=src/jbake/settings/site.yml</code></pre> </div> </div> <div class="paragraph"> <p>然而，这种方法注定会以失败告终，因为`ProjectBuilder`它不是为扫描文件系统以查找配置文件而设计的。测试将保持隔离并忽略此文件。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_解决方案使用_extrapropertiesextension_模拟属性">解决方案：使用 <code>ExtraPropertiesExtension</code> 模拟属性</h2> <div class="sectionbody"> <div class="paragraph"> <p>�优雅地解决此问题的方法不是 <strong>读取</strong> 文件，而是 <strong>模拟</strong> 该属性直接存在于对象中。`Project`测试。 Gradle提供了一种强大的机制来实现这一点：<strong>额外属性</strong>（Extra Properties).</p> </div> <div class="sect2"> <h3 id="_步骤1理解extrapropertiesextension">步骤1：理解ExtraPropertiesExtension</h3> <div class="paragraph"> <p>`ExtraPropertiesExtension`是一个键值容器，附加到 Gradle 模型的每个对象上。它允许动态地向项目、任务或任何其他 Gradle 扩展添加属性。</p> </div> <div class="imageblock"> <div class="content"> <img src="./images/extra-properties-architecture.svg" alt="extra properties architecture" width="533" height="436"> </div> </div> </div> <div class="sect2"> <h3 id="_步骤_2测试布置_准备">步骤 2：测试布置 - 准备</h3> <div class="paragraph"> <p>让我们先来创建单元测试的基本结构 :</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Structure de base</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File @Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Suite des étapes... } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_步骤_3_注入属性">步骤 3 : 注入属性</h3> <div class="paragraph"> <p>以下是将属性注入测试项目的详细过程：</p> </div> <div class="listingblock"> <div class="title">JbakeGhPagesPluginTest.kt - Injection complète</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `check initialize and config yaml file if not existing`() { // Étape 1 : Créer un projet de test isolé en mémoire val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Étape 2 : Récupérer le gestionnaire de propriétés supplémentaires val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) // Étape 3 : Définir la propriété requise pour ce test extra.set("site_config_path", "src/jbake/settings/site.yml") // Étape 4 : Vérifier que la propriété est bien injectée assertTrue(project.hasProperty("site_config_path")) // Étape 5 : Appliquer le plugin qui pourra maintenant accéder à la propriété project.plugins.apply("jbake.ghpages") // Étape 6 : Exécuter la tâche et vérifier son comportement val task: Task = project.tasks.findByName("initialize") .apply(::assertNotNull)!! // Étape 7 : Exécuter les actions de la tâche task.actions.forEach { it.execute(task) } // Étape 8 : Assertions finales assertEquals( "src/jbake/settings/site.yml", project.properties["site_config_path"], "La propriété devrait être accessible dans le projet" ) }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_步骤_4_解决方案流程图">步骤 4 : 解决方案流程图</h3> <div class="imageblock"> <div class="content"> <img src="./images/solution-flow.svg" alt="solution flow" width="242" height="807"> </div> </div> </div> <div class="sect2"> <h3 id="_步骤_5_前后对比">步骤 5 : 前后对比</h3> <div class="imageblock"> <div class="content"> <img src="./images/before-after-comparison.svg" alt="before after comparison" width="1259" height="5759"> </div> </div> </div> <div class="sect2"> <h3 id="_步骤_6管理多个测试用例">步骤 6：管理多个测试用例</h3> <div class="paragraph"> <p>为了测试不同的场景，让我们创建多个测试，使用各种配置：</p> </div> <div class="listingblock"> <div class="title">Tests multiples avec configurations différentes</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JbakeGhPagesPluginTest { @TempDir lateinit var testProjectDir: File private fun createProjectWithProperty(propertyValue: String?): Project { val project = ProjectBuilder.builder() .withProjectDir(testProjectDir) .build() // Injection conditionnelle de la propriété propertyValue?.let { value -> val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) extra.set("site_config_path", value) } return project } @Test fun `should work with valid property`() { val project = createProjectWithProperty("src/jbake/settings/site.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! task.actions.forEach { it.execute(task) } // Assertions pour le cas normal assertEquals("src/jbake/settings/site.yml", project.properties["site_config_path"]) } @Test fun `should handle missing property gracefully`() { val project = createProjectWithProperty(null) // Pas de propriété project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Le plugin devrait gérer l'absence de propriété assertDoesNotThrow { task.actions.forEach { it.execute(task) } } } @Test fun `should handle invalid property path`() { val project = createProjectWithProperty("invalid/path/to/config.yml") project.plugins.apply("jbake.ghpages") val task = project.tasks.findByName("initialize")!! // Test du comportement avec un chemin invalide assertThrows<FileNotFoundException> { task.actions.forEach { it.execute(task) } } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_解决方案的最终架构">解决方案的最终架构</h3> <div class="imageblock"> <div class="content"> <img src="./images/final-architecture.svg" alt="final architecture" width="1211" height="5851"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_此方法的优势">此方法的优势</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><strong>完全隔离</strong>: 该测试不依赖任何外部文件。它是自包含的，可以在任何环境中可靠地执行（本地、CI/CD 等）。</p> </li> <li> <p><strong>清晰与意图</strong>: 测试显式声明了其执行的前提条件。任何读取测试的人都会立即看到该插件需要该属性`site_config_path`以便运行。</p> </li> <li> <p><strong>可维护性</strong>: 如果属性名称更改，只需在测试中的一个地方更新它，而无需操作测试配置文件。</p> </li> <li> <p><strong>灵活性</strong>: 通过简单地更改每个测试中注入属性的值，就可以轻松地测试不同的场景（有效值、无效值、缺失值等）。</p> </li> <li> <p><strong>性能</strong>: 不读取文件，一切都在内存中进行，这使得测试更快。</p> </li> <li> <p><strong>可重复性</strong>: 这些测试是确定性的，因为它们不依赖于文件系统的状态。</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_良好实践和建议">良好实践和建议</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_创建一个实用方法">创建一个实用方法</h3> <div class="listingblock"> <div class="title">Méthode utilitaire pour la réutilisation</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GradleTestUtils { companion object { fun createProjectWithProperties( projectDir: File, properties: Map<String, String> ): Project { val project = ProjectBuilder.builder() .withProjectDir(projectDir) .build() val extra = project.extensions.getByType(ExtraPropertiesExtension::class.java) properties.forEach { (key, value) -> extra.set(key, value) } return project } } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_属性验证">属性验证</h3> <div class="listingblock"> <div class="title">Validation robuste</div> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `should validate property injection`() { val project = createProjectWithProperty("test-value") // Vérifications multiples assertTrue(project.hasProperty("site_config_path")) assertEquals("test-value", project.property("site_config_path")) assertNotNull(project.properties["site_config_path"]) // Vérification que la propriété est accessible par le plugin project.plugins.apply("jbake.ghpages") // ... reste du test }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>与其为让单元测试环境读取配置文件而苦苦挣扎，最佳做法是模拟所需的状态。使用`ExtraPropertiesExtension`以编程方式定义 Gradle 属性是实现有效且可靠的插件单元测试的最干净且最强大的方法。</p> </div> <div class="paragraph"> <p>这种技术将外部依赖问题转化为简单的依赖注入，这正是测试驱动开发（TDD）哲学的核心。它提供了对测试环境的完全控制，同时保持了进行高质量单元测试所需的隔离。</p> </div> <div class="paragraph"> <p>本文中的图表和示例展示了如何以渐进且系统的方式实施这种方法，从而能够为您的 Gradle 插件创建一个健壮且易于维护的测试套件。</p> </div> </div> </div> https://cheroliv.com/blog/2025/0079_gradle_tasks_tests_report_post.html Fri, 11 Jul 2025 00:00:00 +0000 blog/2025/0079_gradle_tasks_tests_report_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_使用_allprojects_和_subprojects_集中管理配置">使用 <code>allprojects</code> 和 <code>subprojects</code> 集中管理配置</a></li> <li><a href="#_sourceplantuml">[source,plantuml]</a></li> <li><a href="#_enduml">@enduml</a></li> <li><a href="#_sourcekotlin">[source,kotlin]</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>构建任务的自动化对任何软件项目都至关重要，而 Gradle 凭借其 Kotlin DSL 提供了卓越的灵活性。在我们的对话过程中，我们探讨了如何集中和复用构建逻辑，尤其是针对测试报告，通过利用<strong>所有项目</strong>, <strong>buildSrc</strong>和自定义 Kotlin 任务。</p> </div> </div> </div> <div class="sect1"> <h2 id="_使用_allprojects_和_subprojects_集中管理配置">使用 <code>allprojects</code> 和 <code>subprojects</code> 集中管理配置</h2> <div class="sectionbody"> <div class="paragraph"> <p>这些块`allprojects` et `subprojects`在你的`build.gradle.kts`根是应用跨多模块项目的通用配置的基础。</p> </div> <div class="paragraph"> <p>*<code>allprojects { …​ }</code>: 应用配置到<strong>根项目及其所有子项目</strong>. 适合定义一个`group`，一个`version`, 或一些`repositories`共同的。 *<code>subprojects { …​ }</code>: 应用配置<strong>仅限于子项目</strong>, 排除根项目。非常适合将特定于模块的插件应用于模块（如`java` ou <code>kotlin-jvm</code>) 或您库中的公共依赖</p> </div> <div class="paragraph"> <p>以下是一个示例：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// build.gradle.kts (projet racine) plugins { base // Appliqué au projet racine } allprojects { group = "com.example" version = "1.0.0" repositories { mavenCentral() } tasks.withType<org.gradle.api.tasks.testing.Test> { useJUnitPlatform() // Configuration commune des tests pour tous les projets } } subprojects { apply(plugin = "java") apply(plugin = "org.jetbrains.kotlin.jvm") dependencies { implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") } }</code></pre> </div> </div> <div class="paragraph"> <p>\== `buildSrc`构建逻辑的瑞士军刀</p> </div> <div class="paragraph"> <p>当您的任务逻辑变得复杂或需要重复使用时<strong>buildSrc</strong>是首选方案。这是一个特殊的 Gradle 模块，在主要构建脚本之前编译，使其类在整个构建的 classpath 上可用。</p> </div> <div class="paragraph"> <p>\=== 为什么使用`buildSrc`对于任务？</p> </div> <div class="ulist"> <ul> <li> <p><strong>可重用性</strong>一个定义在`buildSrc`可以应用于构建的任何项目。</p> </li> <li> <p><strong>组织</strong>: 集中构建代码，使其更清晰且易于维护。</p> </li> <li> <p><strong>类型安全和自动补全</strong>: Kotlin 代码在`buildSrc`已编译，提供 IDE 的错误检查和自动补全，提升开发体验。</p> </li> </ul> </div> <div class="paragraph"> <p>\=== 流程图`buildSrc`(PlantUML代码)</p> </div> <div class="paragraph"> <p>要生成此图表，请复制以下代码并将其粘贴到支持 PlantUML 的工具中。</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourceplantuml">[source,plantuml]</h2> <div class="sectionbody"> <div class="paragraph"> <p>@startuml skinparam 手写的 true skinparam 单色 true</p> </div> <div class="paragraph"> <p>矩形 "Gradle 构建过程" { 组件 "buildSrc" 作为 BS { file "MyCustomTask.kt" as T 文件 "MyConventionPlugin.kt" 作为 P } 组件 "Root Project" 作为 RP 组件 "Subproject A" 作为 SA 组件 "Subproject B" 作为 SB }</p> </div> <div class="paragraph"> <p>T --\> P : "定义于 P --\> RP : \"应用于\ P --\> SA : "应用于 P -→ SB : "被应用于</p> </div> <div class="paragraph"> <p>RP --|\> SA : "contains RP --|\> SB : "contains</p> </div> <div class="paragraph"> <p>RP -up-\> BS : "depends on (for build logic) SA -up-\> BS : "依赖（用于构建逻辑） SB -up-\> BS : "依赖于（用于构建逻辑）</p> </div> <div class="paragraph"> <p>T 右侧的注释 自定义任务类 (例如: OpenTestReportTask) end note</p> </div> <div class="paragraph"> <p>注释在P的右侧 约定插件 记录任务的 尾注</p> </div> </div> </div> <div class="sect1"> <h2 id="_enduml">@enduml</h2> <div class="sectionbody"> <div class="paragraph"> <p>抽象报告任务创建</p> </div> <div class="paragraph"> <p>为了管理测试报告，我们设计了一种模块化的方法，通过使用抽象任务类在`buildSrc`. 根据您的需求，此类可以继承`DefaultTask` ou de <code>Exec</code>。</p> </div> <div class="paragraph"> <p>\=== 抽象任务`OpenTestReportTask`(继承自`DefaultTask`)</p> </div> <div class="paragraph"> <p>这种方法适用于您需要自定义的 Kotlin 逻辑与文件系统或其他 Gradle API 交互，然后启动外部命令的情况。</p> </div> </div> </div> <div class="sect1"> <h2 id="_sourcekotlin">[source,kotlin]</h2> <div class="sectionbody"> <div class="paragraph"> <p>包 com.yourpackage</p> </div> <div class="paragraph"> <p>导入 org.gradle.api.DefaultTask import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction 导入 java.io.File</p> </div> <div class="paragraph"> <p>抽象类 OpenTestReportTask : DefaultTask() {</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-none hljs">---- ---- init { group = "verification" description = "Opens a test report in Firefox." dependsOn("check") // Assure que les rapports sont générés } @get:Input abstract var reportPath: String @TaskAction fun openReport() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportPath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } project.exec { commandLine("firefox", "--new-tab", reportFile.absolutePath) } logger.lifecycle("Opened test report: ${reportFile.absolutePath}") } ---- ## } \=== 具体实现 这些类继承自抽象任务，并定义了报告的特定路径。 ## [source,kotlin] 包 com.yourpackage 抽象类 ReportUnitTestsTask : OpenTestReportTask() init { 在 Firefox 中打开单元测试报告。 reportPath = "build/reports/tests/test/index.html } } package com.yourpackage abstract class ReportFunctionalTestsTask : OpenTestReportTask() { init { description = "在Firefox中打开功能测试报告。" reportPath = "build/reports/tests/functionalTest/index.html" } } \=== 任务记录 在`build.gradle.kts`您的根项目 : ## [source,kotlin] tasks.register\<com.yourpackage.ReportUnitTestsTask\>("reportTests") {} tasks.register\<com.yourpackage.ReportFunctionalTestsTask\>("reportFunctionalTests") {} 报告任务UML图 (PlantUML代码) 复制下面的代码，然后粘贴到支持 PlantUML 的工具。 ## [source,plantuml] @startuml skinparam handwritten true skinparam 单色 true �抽象类 DefaultTask { } abstract class Exec { \+ commandLine(args: String...) \+ exec() } abstract class OpenTestReportTask extends DefaultTask { \+ group: String = "verification + 描述: 字符串 \+ dependsOn("check") + 抽象 报告路径: 字符串 + openReport() : void } 抽象类 AbstractJbakeExecTask 继承自 Exec { \+ group: String = "验证 \+ 描述: 字符串 \+ dependsOn("check") \+ abstract reportRelativePath: String \+ exec() : 无返回值 } 类 ReportUnitTestsTask 继承自 OpenTestReportTask { \+ reportPath: String = "build/reports/tests/test/index.html } class ReportFunctionalTestsTask extends OpenTestReportTask { \+ reportPath: String = "build/reports/tests/functionalTest/index.html } 类 ReportJbakeTestsTask 继承 AbstractJbakeExecTask { \+ reportRelativePath: String = "build/reports/tests/test/index.html } 类 ReportJbakeFunctionalTestsTask 继承 AbstractJbakeExecTask { \+ reportRelativePath: 字符串 = "build/reports/tests/functionalTest/index.html } OpenTestReportTask \<-- ReportUnitTestsTask OpenTestReportTask \<-- ReportFunctionalTestsTask AbstractJbakeExecTask <-- ReportJbakeTestsTask AbstractJbakeExecTask \<-- ReportJbakeFunctionalTestsTask 默认任务 \<|-- 打开测试报告任务 Exec \<|-- AbstractJbakeExecTask 默认任务 <|-- 执行 ## @enduml \== 抽象任务`AbstractJbakeExecTask`(继承`Exec`) 如果您的任务主要是执行带有变量参数的外部命令，请直接继承**�执行**更直接。 ## [source,kotlin] 包 com.yourpackage import org.gradle.api.tasks.Exec import org.gradle.api.tasks.Input import java.io.File 抽象类 AbstractJbakeExecTask : Exec() { ---- init { group = "verification" description = "Opens a Jbake project report in Firefox." dependsOn("check") } @get:Input abstract var reportRelativePath: String override fun exec() { val separator = File.separator val reportFile = project.layout.projectDirectory.asFile.toPath() .resolve(reportRelativePath.replace("/", separator)) .toAbsolutePath() .toFile() if (!reportFile.exists()) { logger.warn("Report file does not exist: $reportFile. Ensure 'check' ran.") return } commandLine("firefox", "--new-tab", reportFile.absolutePath) logger.lifecycle("Attempting to open report: ${reportFile.absolutePath}") super.exec() // Appelle la méthode exec() de la super-classe Exec } ## } \=== 具体实现用于`Exec` ## [source,kotlin] package com.yourpackage 抽象类 ReportJbakeTestsTask : AbstractJbakeExecTask() 初始化 { 在 Firefox 中打开 Jbake 单元测试报告。 reportRelativePath = "build/reports/tests/test/index.html } } package com.yourpackage ## abstract class ReportJbakeFunctionalTestsTask : AbstractJbakeExecTask() { init { description = "在 Firefox 中打开功能测试报告。" reportRelativePath = "build/reports/tests/functionalTest/index.html" } } \== 任务可见性`buildSrc` 您定义的任务和类在**buildSrc**是： ***可见且可用**由您的主构建中的所有项目（根项目和子项目）。因此，您可以使用`com.yourpackage.ReportUnitTestsTask`在`allprojects { ... }`. ***不可执行的**直接作为 buildSrc 任务（例如,`gradle :buildSrc:reportTests`如果任务没有被具体地记录在`buildSrc/build.gradle.kts`)。`buildSrc`这是一个编译模块，而不是用于这些主构建任务的可执行应用模块。 \=== 为测试运行报告`buildSrc`他自己 Si `buildSrc`它有自己的测试并生成报告，您可以直接在其中记录报告任务`buildSrc/build.gradle.kts`: ## [source,kotlin] 插件 { `kotlin-jvm` } 仓库 { mavenCentral() } tasks.withType<Test>{ useJUnitPlatform() reports.html.outputLocation.set(layout.buildDirectory.dir("reports/tests")) } import com.yourpackage.ReportJbakeTestsTask // 导入您的任务类 tasks.register<ReportJbakeTestsTask>("reportBuildSrcTests") { // 路径已经在类中定义，它将指向 buildSrc 的报告。 } 然后您可以执行 :`./gradlew :buildSrc:test`随后`./gradlew :buildSrc:reportBuildSrcTests`. 通过采用这些实践，您将构建出不仅功能强大，而且模块化程度极高、易于维护且易于理解的 Gradle Kotlin DSL 构建系统。</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html Wed, 9 Jul 2025 00:00:00 +0000 blog/2025/0078_jbake_gradle_plugin_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_目标">目标</a></li> <li><a href="#_声明式配置">声明式配置</a></li> <li><a href="#_插件架构">�插件架构</a></li> <li><a href="#_dsl_扩展的定义">DSL 扩展的定义</a></li> <li><a href="#_自定义任务的定义">自定义任务的定义</a></li> <li><a href="#_接口_gitadapter">接口 GitAdapter</a></li> <li><a href="#_使用_jgit_的具体实现">使用 JGit 的具体实现</a></li> <li><a href="#_配置_dsl_kotlin">配置 DSL Kotlin</a></li> <li><a href="#_使用_mockito_进行单元测试">使用 Mockito 进行单元测试</a> <ul class="sectlevel2"> <li><a href="#_依赖">依赖</a></li> <li><a href="#_git行为测试">Git行为测试</a></li> </ul> </li> <li><a href="#_结论">结论</a></li> <li><a href="#_下一步">下一步</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>本文介绍了用 Kotlin DSL 编写的 Gradle 插件的完整设计和测试（TDD）流程。该插件通过 <strong>JBake</strong> 自动生成静态站点，并通过 <strong>JGit</strong> 实现 <strong>Git 部署</strong>，所有这些均基于一个 YAML 配置文件。</p> </div> </div> </div> <div class="sect1"> <h2 id="_目标">目标</h2> <div class="sectionbody"> <div class="paragraph"> <p>创建 Gradle 插件：</p> </div> <div class="ulist"> <ul> <li> <p>可在 Kotlin DSL 中配置；</p> </li> <li> <p>能够：</p> </li> <li> <p>使用 JBake 生成静态网站；</p> </li> <li> <p>通过 JGit 部署到远程 Git 仓库 ;</p> </li> <li> <p>可集成到 CI/CD 工作流中；</p> </li> <li> <p>采用 TDD 方法进行测试。</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_声明式配置">声明式配置</h2> <div class="sectionbody"> <div class="paragraph"> <p>这是一个YAML配置的示例，需要在我们的DSL中进行建模：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">bake: srcPath: "./site/jbake" destDirPath: "bake" pushPage: from: "bake" to: "cvs" repo: name: "trainings" repository: "https://github.com/pages-content/trainings.git" credentials: username: "USERNAME" password: "SECRET_TOKEN" branch: "main" message: "cheroliv.com"</code></pre> </div> </div> <div class="paragraph"> <p>此配置通过可在 Kotlin DSL 中声明的 Gradle 扩展表示。</p> </div> </div> </div> <div class="sect1"> <h2 id="_插件架构">�插件架构</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/jbake-asciidoctor-class-diagram.png" alt="jbake asciidoctor class diagram" width="568" height="261"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_dsl_扩展的定义">DSL 扩展的定义</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">open class WorkspaceEngineExtension { var outputDir: String = "build/site" var template: String = "freemarker" var repoUrl: String = "" var branch: String = "main" var message: String = "Generated by engine" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_自定义任务的定义">自定义任务的定义</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">abstract class GenerateSiteTask : DefaultTask() { lateinit var gitAdapter: GitAdapter @get:Input abstract val repoUrl: Property<String> @get:InputDirectory abstract val outputDir: DirectoryProperty @get:Input abstract val branch: Property<String> @get:Input abstract val message: Property<String> @TaskAction fun run() { val repo = gitAdapter.cloneRepository(repoUrl.get(), outputDir.get().asFile) gitAdapter.commitAndPush(repo, branch.get(), message.get()) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_接口_gitadapter">接口 GitAdapter</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">interface GitAdapter { fun cloneRepository(uri: String, directory: File): Repository fun commitAndPush(repo: Repository, branch: String, message: String) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用_jgit_的具体实现">使用 JGit 的具体实现</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class JGitAdapter : GitAdapter { override fun cloneRepository(uri: String, directory: File): Repository { return Git.cloneRepository() .setURI(uri) .setDirectory(directory) .call() .repository } override fun commitAndPush(repo: Repository, branch: String, message: String) { Git(repo).use { it.add().addFilepattern(".").call() it.commit().setMessage(message).call() it.push().call() } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_配置_dsl_kotlin">配置 DSL Kotlin</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">workspaceEngine { outputDir = "build/out" template = "freemarker" repoUrl = "https://github.com/cheroliv/trainings.git" branch = "main" message = "deploy from plugin" }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用_mockito_进行单元测试">使用 Mockito 进行单元测试</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_依赖">依赖</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">testImplementation("org.mockito:mockito-core:5.12.0") testImplementation("org.mockito.kotlin:mockito-kotlin:5.2.1") testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_git行为测试">Git行为测试</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class GenerateSiteTaskMockitoTest { @TempDir lateinit var tempDir: File @Test fun `task should call clone and commitAndPush`() { val project = ProjectBuilder.builder().build() val task = project.tasks.create("generateSite", GenerateSiteTask::class.java) val mockGitAdapter = mock<GitAdapter>() val mockRepo = mock<Repository>() whenever(mockGitAdapter.cloneRepository(any(), any())).thenReturn(mockRepo) task.gitAdapter = mockGitAdapter task.repoUrl.set("https://github.com/cheroliv/test.git") task.outputDir.set(project.layout.projectDirectory.dir(tempDir.name)) task.branch.set("main") task.message.set("test commit") task.run() verify(mockGitAdapter).cloneRepository(eq("https://github.com/cheroliv/test.git"), any()) verify(mockGitAdapter).commitAndPush(eq(mockRepo), eq("main"), eq("test commit")) } }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/jbake-asciidoctor-sequence-diagram.png" alt="jbake asciidoctor sequence diagram" width="693" height="326"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>通过责任分离`GitAdapter`可以在 Gradle 插件开发中充分应用 TDD :</p> </div> <div class="ulist"> <ul> <li> <p>Git 调用被抽象且可测试 ;</p> </li> <li> <p>DSL 配置干净且清晰；</p> </li> <li> <p>该插件对实际实现保持不可知。</p> </li> </ul> </div> <div class="paragraph"> <p>这种方法确保了高可测性和可扩展性（适用于 GitHub API、GitLab 等）。</p> </div> </div> </div> <div class="sect1"> <h2 id="_下一步">下一步</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>集成 JBake 生成作为一个`BakeAdapter`</p> </li> <li> <p>添加集成测试`GradleRunner`</p> </li> <li> <p>支持自动加载文件`site.yml`通过 SnakeYAML</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2025/0077_asciidoc_syntaxe_post.html Fri, 20 Jun 2025 00:00:00 +0000 blog/2025/0077_asciidoc_syntaxe_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_引言">引言</a></li> <li><a href="#_什么是_asciidoc">什么是 AsciiDoc？</a> <ul class="sectlevel2"> <li><a href="#_为什么选择_asciidoc">为什么选择 AsciiDoc？</a></li> </ul> </li> <li><a href="#_用例图_use_case">用例图 (Use Case)</a></li> <li><a href="#_思维导图图">思维导图图</a></li> <li><a href="#_流程图流量">流程图（流量）</a></li> <li><a href="#_asciidoc_文件的基本结构">AsciiDoc 文件的基本结构</a></li> <li><a href="#_基本语法">基本语法</a> <ul class="sectlevel2"> <li><a href="#_标题和章节">标题和章节</a></li> <li><a href="#_粗体斜体和等宽文本">粗体、斜体和等宽文本</a></li> <li><a href="#_项目符号列表和编号列表">项目符号列表和编号列表</a></li> <li><a href="#_链接和图片">链接和图片</a></li> <li><a href="#_代码块">代码块</a></li> <li><a href="#_表格">表格</a></li> <li><a href="#_注释和警告">注释和警告</a></li> </ul> </li> <li><a href="#_使用属性和变量">使用属性和变量</a></li> <li><a href="#_常见的用例">常见的用例</a></li> <li><a href="#_最佳实践">最佳实践</a></li> <li><a href="#_结论">结论</a></li> <li><a href="#_更进一步">更进一步</a></li> </ul> </div> <div class="sect1"> <h2 id="_引言">引言</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>目标受众 :</em> 开发者、技术编写人员以及任何希望编写技术文档或撰写内容丰富文章的人。</div> <p>AsciiDoc 是一种轻量级标记语言，专为编写结构化的技术文档、文章、书籍或演示文稿而设计。它以其可读性、丰富的语法以及能够生成多种格式（HTML、PDF、DocBook 等）的能力而脱颖而出。本文将探讨 AsciiDoc 的基本语法，并提供一些快速上手的技巧。</p> </div> </div> </div> <div class="sect1"> <h2 id="_什么是_asciidoc">什么是 AsciiDoc？</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc 是一种文档描述语言，类似于 Markdown 但功能更强大。它能够高效地组织文本、标题、列表、表格、代码块等，而且还有更多功能。其多功能性使其成为开源项目文档、书籍撰写和网页发布的热门选择。</p> </div> <div class="sect2"> <h3 id="_为什么选择_asciidoc">为什么选择 AsciiDoc？</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>语法易读且直观。</p> </li> <li> <p>对复杂结构（表格、笔记、警告等）的原生支持。</p> </li> <li> <p>多格式生成 (HTML, PDF, ePub, DocBook…)</p> </li> <li> <p>与JBake或Antora等静态站点生成器实现轻松集成。</p> </li> <li> <p>使用属性和扩展的高级自定义。</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_用例图_use_case">用例图 (Use Case)</h2> <div class="sectionbody"> <div class="paragraph"> <p>用例图可以呈现用户与系统之间的主要交互。以下是一个文档系统的简单示例：</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-381f40e6e0660c0c53433ff054330b76.png" alt="Diagram" width="423" height="258"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_思维导图图">思维导图图</h2> <div class="sectionbody"> <div class="paragraph"> <p>思维导图（脑图）非常适合用于探索与 AsciiDoc 相关的概念及其关系：</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-e1560e9cc014158b6fbeed1e5ad8e138.png" alt="Diagram" width="394" height="527"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_流程图流量">流程图（流量）</h2> <div class="sectionbody"> <div class="paragraph"> <p>流程图可用于描述生成一个 AsciiDoc 文档的过程：</p> </div> <div class="imageblock"> <div class="content"> <img src="diag-plantuml-md5-51318d77b9e18062d3a9b751587670ae.png" alt="Diagram" width="299" height="361"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_asciidoc_文件的基本结构">AsciiDoc 文件的基本结构</h2> <div class="sectionbody"> <div class="paragraph"> <p>一个 AsciiDoc 文件通常以标题开始，然后是可选属性，随后是结构化内容。以下是一个最小示例：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre Principal Auteur 2024-09-03 :toc: :icons: font Votre contenu commence ici...</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_基本语法">基本语法</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_标题和章节">标题和章节</h3> <div class="paragraph"> <p>AsciiDoc 支持多个标题级别：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">= Titre de niveau 1 == Titre de niveau 2 === Titre de niveau 3 ==== Titre de niveau 4</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_粗体斜体和等宽文本">粗体、斜体和等宽文本</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">*gras* _italique_ `monospace`</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_项目符号列表和编号列表">项目符号列表和编号列表</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">* Élément 1 * Élément 2 . Premier . Deuxième . Troisième</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_链接和图片">链接和图片</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">Lien standard : https://asciidoc.org[AsciiDoc] Image : image::images/logo.png[AsciiDoc Logo]</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_代码块">代码块</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">[source,python]</code></pre> </div> </div> <div class="paragraph"> <p>def hello(): print("Bonjour AsciiDoc !")</p> </div> </div> <div class="sect2"> <h3 id="_表格">表格</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">|=== | Colonne 1 | Colonne 2 | Valeur A | Valeur B | Valeur C | Valeur D |===</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_注释和警告">注释和警告</h3> <div class="paragraph"> <p>AsciiDoc 提供可视化信息块：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">NOTE: Ceci est une note importante. TIP: Conseil utile pour l’utilisateur. WARNING: Attention à ce point.</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用属性和变量">使用属性和变量</h2> <div class="sectionbody"> <div class="paragraph"> <p>自定义属性允许重用值或配置行为：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">:project-name: AsciiDoc Explorer Le projet s’appelle {project-name}.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_常见的用例">常见的用例</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>开源项目文档（README, 技术指南） 编写书籍和电子书 - 自动生成静态网站 (JBake, Antora) - 技术演示</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_最佳实践">最佳实践</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>使用一致的标题和自动目录 (:toc:). - 建议使用提示框来突出关键点。 - 组织您的文件以便于维护。 - 利用带注释的代码块来说明示例。</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>AsciiDoc 是一种功能强大且易于使用的工具，可用于编写任何技术文档或结构化文章。其丰富的语法结合多格，使其成为开发者和要求严格的编辑者的理想伙伴。请在您的下一个项目中尝试使用 AsciiDoc，体验其中的差别！</p> </div> </div> </div> <div class="sect1"> <h2 id="_更进一步">更进一步</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>官方文档：https://asciidoc.org - Asciidoctor : <a href="https://asciidoctor.org" class="bare">https://asciidoctor.org</a> - JBake 和 AsciiDoc : <a href="https://jbake.org/docs/2.6.4/#asciidoc_support" class="bare">https://jbake.org/docs/2.6.4/#asciidoc_support</a></p> </li> </ul> </div> <div class="paragraph"> <p>在评论中分享你的经验和技巧！</p> </div> </div> </div> https://cheroliv.com/blog/2025/0076_port_forwarding_post.html Wed, 28 May 2025 00:00:00 +0000 blog/2025/0076_port_forwarding_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_问题nat_和私有地址">问题：NAT 和私有地址</a></li> <li><a href="#_步骤1识别您的公共ip地址">步骤1：识别您的公共IP地址</a></li> <li><a href="#_步骤2了解您的ubuntu机器的本地ip地址">步骤2：了解您的Ubuntu机器的本地IP地址</a></li> <li><a href="#_步骤_3在您的盒子上配置端口转发">步骤 3：在您的盒子上配置端口转发</a> <ul class="sectlevel2"> <li><a href="#_访问管理界面">访问管理界面</a></li> <li><a href="#_重定向的配置">重定向的配置</a></li> </ul> </li> <li><a href="#_步骤_4在_ubuntu_上配置服务">步骤 4：在 Ubuntu 上配置服务</a></li> <li><a href="#_步骤_5_配置_ubuntu_防火墙">步骤 5 : 配置 Ubuntu 防火墙</a></li> <li><a href="#_步骤_6测试与验证">步骤 6：测试与验证</a> <ul class="sectlevel2"> <li><a href="#_来自局域网的测试">来自局域网的测试</a></li> <li><a href="#_外部测试">外部测试</a></li> </ul> </li> <li><a href="#_良好实践与安全">良好实践与安全</a> <ul class="sectlevel2"> <li><a href="#_基础安全">基础安全</a></li> <li><a href="#_连接监控">连接监控</a></li> <li><a href="#_使用反向代理">使用反向代理</a></li> </ul> </li> <li><a href="#_端口转发的替代方案">端口转发的替代方案</a> <ul class="sectlevel2"> <li><a href="#_云解决方案">云解决方案</a></li> <li><a href="#_vps和反向代理">VPS和反向代理</a></li> </ul> </li> <li><a href="#_故障排除">故障排除</a> <ul class="sectlevel2"> <li><a href="#_常见问题">常见问题</a></li> <li><a href="#_网络调试">网络调试</a></li> </ul> </li> <li><a href="#_结论">结论</a></li> </ul> </div> <div id="preamble"> <div class="sectionbody"> <div class="ulist"> <div class="title">目标受众：中级</div> <ul> <li> <p><strong>假设的前提</strong> : 对Ubuntu的基本了解, 终端, 基本网络概念</p> </li> <li> <p><strong>技术概念</strong> : NAT, 端口转发, 防火墙, 反向代理</p> </li> <li> <p><strong>系统命令</strong> : 使用终端, 网络配置</p> </li> <li> <p><strong>高级部分</strong> : 监控, 安全, 云替代方案</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_问题nat_和私有地址">问题：NAT 和私有地址</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">问题 : 您在 Ubuntu 机器上开发一个网页应用，并希望使其从家庭网络外部可访问？您来对地方了！在这篇文章中，我们将看到如何通过在您的互联网盒子上配置端口转发，将本地服务（例如在端口 8080 上）暴露到互联网。</div> <p>默认情况下，您的互联网盒子使用 NAT（网络地址转换）在家庭网络的所有设备之间共享一个公共 IP 地址。您的本地机器使用私有 IP 地址（192.168.x.x、10.x.x.x 等），这些地址在 Internet 上不可路由。</p> </div> <div class="paragraph"> <p>当您在 Ubuntu 机器上启动一个服务（例如在端口 8080 上运行一个 Web 服务器）时，该服务只能从本地网络访问。为了使其从 Internet 可访问，我们需要配置端口转发。</p> </div> </div> </div> <div class="sect1"> <h2 id="_步骤1识别您的公共ip地址">步骤1：识别您的公共IP地址</h2> <div class="sectionbody"> <div class="paragraph"> <p>首先，获取您的Internet连接的公共IP地址：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Plusieurs méthodes au choix curl ifconfig.me curl ipecho.net/plain wget -qO- http://ipecho.net/plain # Ou encore curl -s checkip.amazonaws.com</code></pre> </div> </div> <div class="paragraph"> <p>此IP地址是互联网用户用于访问您服务的地址。</p> </div> </div> </div> <div class="sect1"> <h2 id="_步骤2了解您的ubuntu机器的本地ip地址">步骤2：了解您的Ubuntu机器的本地IP地址</h2> <div class="sectionbody"> <div class="paragraph"> <p>你的Ubuntu机器在局域网上有一个私有IP地址。要查看它：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Afficher toutes les interfaces réseau ip addr show # Ou plus spécifiquement pour l'interface principale ip route get 1.1.1.1 | awk '{print $7; exit}' # Alternative avec hostname hostname -I | awk '{print $1}'</code></pre> </div> </div> <div class="paragraph"> <p>注意此地址（例如`192.168.1.100`), 我们将在配置过程中需要它们。</p> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_3在您的盒子上配置端口转发">步骤 3：在您的盒子上配置端口转发</h2> <div class="sectionbody"> <div class="paragraph"> <p>配置会根据您的盒子型号而有所不同，但原理保持不变：</p> </div> <div class="sect2"> <h3 id="_访问管理界面">访问管理界面</h3> <div class="paragraph"> <p>打开您的浏览器并前往您的盒子的Web界面：</p> </div> <div class="ulist"> <ul> <li> <p><strong>Freebox</strong>:`192.168.1.1` ou <code>mafreebox.freebox.fr</code></p> </li> <li> <p><strong>Livebox Orange</strong>:`192.168.1.1`</p> </li> <li> <p><strong>SFR Box</strong>：<code>192.168.1.1</code></p> </li> <li> <p><strong>Bbox Bouygues</strong> : <code>192.168.1.254</code></p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_重定向的配置">重定向的配置</h3> <div class="paragraph"> <p>查找专门用于端口转发的部分（名称可能因设备而异）：</p> </div> <div class="ulist"> <ul> <li> <p>端口转发</p> </li> <li> <p>网络地址转换/端口地址转换</p> </li> <li> <p>端口转发</p> </li> <li> <p>游戏服务器</p> </li> </ul> </div> <div class="paragraph"> <p>使用这些参数创建一个新规则：</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 25%;"> <col style="width: 75%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">场</th> <th class="tableblock halign-left valign-top">价值</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">名称/描述</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Ubuntu Web服务"（或其他明确名称）</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">外部端口（或公共端口）</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">内部 IP 地址</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">您的Ubuntu机器的IP（例如：192.168.1.100）</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">内部端口（或私有端口）</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">8080</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">�协议</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">TCP</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">状态</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">已激活</p></td> </tr> </tbody> </table> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_4在_ubuntu_上配置服务">步骤 4：在 Ubuntu 上配置服务</h2> <div class="sectionbody"> <div class="paragraph"> <p>请确保您的服务在所有接口上监听，而不仅仅是 localhost :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># ✅ Correct : écoute sur toutes les interfaces python3 -m http.server 8080 --bind 0.0.0.0 # ❌ Incorrect : écoute seulement en local python3 -m http.server 8080 --bind 127.0.0.1</code></pre> </div> </div> <div class="paragraph"> <p>为了验证您的服务正在正确地侦听：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Vérifier les ports en écoute sudo netstat -tlnp | grep :8080 # ou avec ss (plus moderne) sudo ss -tlnp | grep :8080</code></pre> </div> </div> <div class="paragraph"> <p>你应该会看到类似的东西`0.0.0.0:8080`并且不`127.0.0.1:8080`.</p> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_5_配置_ubuntu_防火墙">步骤 5 : 配置 Ubuntu 防火墙</h2> <div class="sectionbody"> <div class="paragraph"> <p>Ubuntu 默认使用 UFW（Uncomplicated Firewall）。检查其状态并在必要时允许该端口：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Vérifier le statut du pare-feu sudo ufw status # Si le pare-feu est actif, autoriser le port 8080 sudo ufw allow 8080/tcp # Ou plus spécifiquement pour un service web sudo ufw allow 'Apache' # si vous utilisez Apache sudo ufw allow 'Nginx Full' # si vous utilisez Nginx</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_步骤_6测试与验证">步骤 6：测试与验证</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_来自局域网的测试">来自局域网的测试</h3> <div class="paragraph"> <p>首先，从您的局域网中的另一台机器测试访问：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Remplacez par l'IP locale de votre machine Ubuntu curl http://192.168.1.100:8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_外部测试">外部测试</h3> <div class="paragraph"> <p>现在，使用您的公共IP从互联网进行测试：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Remplacez par votre IP publique curl http://VOTRE_IP_PUBLIQUE:8080</code></pre> </div> </div> <div class="paragraph"> <p>您也可以使用在线工具，如：</p> </div> <div class="ulist"> <ul> <li> <p><a href="https://www.yougetsignal.com/tools/open-ports/" class="bare">https://www.yougetsignal.com/tools/open-ports/</a></p> </li> <li> <p><a href="https://canyouseeme.org/" class="bare">https://canyouseeme.org/</a></p> </li> </ul> </div> </div> </div> </div> <div class="sect1"> <h2 id="_良好实践与安全">良好实践与安全</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_基础安全">基础安全</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Configurer fail2ban pour protéger contre les attaques par force brute sudo apt update && sudo apt install fail2ban # Limiter l'accès avec UFW (exemple : autoriser seulement certaines IP) sudo ufw allow from 203.0.113.0/24 to any port 8080</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_连接监控">连接监控</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Surveiller les connexions en temps réel sudo netstat -an | grep :8080 # Logs des connexions (selon votre application) sudo tail -f /var/log/nginx/access.log # pour Nginx sudo journalctl -f -u your-service # pour un service systemd</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_使用反向代理">使用反向代理</h3> <div class="paragraph"> <p>为了更好的安全性和灵活性，请考虑使用如 Nginx 的反向代理：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-nginx" data-lang="nginx">server { listen 80; server_name votre-domaine.com; location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_端口转发的替代方案">端口转发的替代方案</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_云解决方案">云解决方案</h3> <div class="ulist"> <ul> <li> <p><strong>ngrok</strong>: 临时安全隧道</p> </li> <li> <p><strong>Cloudflare Tunnel</strong>免费且安全的解决方案</p> </li> <li> <p><strong>serveo.net</strong>: 简单的SSH隧道</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Exemple avec ngrok ngrok http 8080 # Exemple avec serveo ssh -R 80:localhost:8080 serveo.net</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_vps和反向代理">VPS和反向代理</h3> <div class="paragraph"> <p>对于专业使用，请考虑使用一个通过 VPN 指向您本地基础设施的反向代理的 VPS。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_故障排除">故障排除</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_常见问题">常见问题</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 40%;"> <col style="width: 60%;"> </colgroup> <thead> <tr> <th class="tableblock halign-left valign-top">问题</th> <th class="tableblock halign-left valign-top">解决方案</th> </tr> </thead> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">服务从外部不可访问</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�检查端口转发配置，并确保服务在 0.0.0.0 上监听</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">连接被拒绝</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">服务未启动或仅在 127.0.0.1 上监听</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">连接超时</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">防火墙问题（盒子或Ubuntu）或端口转发配置错误</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">公共IP会定期更换</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">配置动态 DNS（DynDNS、No-IP 等）</p></td> </tr> </tbody> </table> </div> <div class="sect2"> <h3 id="_网络调试">网络调试</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"># Tester la connectivité locale telnet localhost 8080 # Tester depuis une autre machine du réseau telnet 192.168.1.100 8080 # Vérifier les routes réseau ip route show # Analyser le trafic réseau sudo tcpdump -i any port 8080</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>在互联网上暴露本地服务需要仔细配置端口转发、安全和监控。虽然这种方法非常适合开发或个人项目，但请考虑更稳健的替代方案（VPS、CDN、云服务），以用于生产环境。</p> </div> <div class="paragraph"> <p>重要的是要始终将安全放在心上：使用强密码，定期更新系统，并监控对您暴露服务的访问。</p> </div> <div class="paragraph"> <p>请不要犹豫，在评论中分享您的经验和问题！</p> </div> </div> </div> https://cheroliv.com/blog/2025/0099_debugging-mockito-gradle-plugin_post.html Sun, 17 Nov 2024 00:00:00 +0000 blog/2025/0099_debugging-mockito-gradle-plugin_post.html <div id="toc" class="toc"> <div id="toctitle">Table des matières</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_上下文gradle_bakery_插件">上下文：Gradle Bakery 插件</a></li> <li><a href="#_问题_1验证错误的模拟">问题 #1：验证错误的模拟</a> <ul class="sectlevel2"> <li><a href="#_诊断">�诊断</a></li> <li><a href="#_解决方案">解决方案</a></li> </ul> </li> <li><a href="#_问题_2级联的_unfinishedstubbingexception">问题 #2：级联的 UnfinishedStubbingException</a> <ul class="sectlevel2"> <li><a href="#_诊断_2">�诊断</a></li> <li><a href="#_解决方案_2">解决方案</a></li> </ul> </li> <li><a href="#_问题_3_配置文件不存在">问题 #3 : 配置文件不存在</a> <ul class="sectlevel2"> <li><a href="#_诊断_3">诊断</a></li> <li><a href="#_解决方案_3">解决方案</a></li> </ul> </li> <li><a href="#_问题_4afterevaluate_和_nullpointerexception">问题 #4：afterEvaluate 和 NullPointerException</a> <ul class="sectlevel2"> <li><a href="#_诊断_4">诊断</a></li> <li><a href="#_解决方案_4">解决方案</a></li> </ul> </li> <li><a href="#_完整的解决方案">完整的解决方案</a></li> <li><a href="#_学到的教训">学到的教训</a> <ul class="sectlevel2"> <li><a href="#_检查正确的_mock">检查正确的 mock</a></li> <li><a href="#_2_避免使用嵌套的_mock">2. 避免使用嵌套的 mock</a></li> <li><a href="#_3_模拟评估回调">3. 模拟评估回调</a></li> <li><a href="#_4_测试路径解析">4. 测试路径解析</a></li> </ul> </li> <li><a href="#_最终测试架构">最终测试架构</a></li> <li><a href="#_结论">结论</a></li> <li><a href="#_资源">资源</a></li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <p>在开发 Gradle 插件期间<strong>面包店</strong>对于我的 JBake 博客，我遇到了一个看似简单的问题：一个单元测试在出现错误时失败`Wanted but not invoked`. 这似乎是一个琐碎的 bug，结果却是一个完美的案例，用于理解使用 Mockito 和 Kotlin 进行模拟的细微差别。</p> </div> <div class="paragraph"> <p>在这篇文章中，我将带您踏上一次系统的调试之旅，每个解决方案都会揭示一个新问题，直至最终的解决。</p> </div> </div> </div> <div class="sect1"> <h2 id="_上下文gradle_bakery_插件">上下文：Gradle Bakery 插件</h2> <div class="sectionbody"> <div class="paragraph"> <p>Bakery 插件是围绕 JBake 的包装器，它简化了静态网站的发布。以下是其简化的结构：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">class BakeryPlugin : Plugin<Project> { override fun apply(project: Project) { val extension = project.extensions.create( "bakery", BakeryExtension::class.java ) project.afterEvaluate { if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") } else { // C'EST ICI QUE ÇA SE PASSE project.plugins.apply(JBakePlugin::class.java) val site = FileSystemManager.from(project, extension.configPath.get()) // Configuration de JBake... } } } }</code></pre> </div> </div> <div class="paragraph"> <p>失败的测试很简单 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val project = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(project.plugins).apply(JBakePlugin::class.java) }</code></pre> </div> </div> <div class="paragraph"> <p>错误：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">Wanted but not invoked: pluginContainer.apply(class org.jbake.gradle.JBakePlugin); Actually, there were zero interactions with this mock.</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_问题_1验证错误的模拟">问题 #1：验证错误的模拟</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_诊断">�诊断</h3> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-1.svg" alt="mockito problem 1" width="613" height="521"> </div> </div> <div class="paragraph"> <p>问题：Mockito 无法追踪交互在`project.plugins`因为这只是一个返回真实 mock 的 getter`mockPluginContainer`. 验证必须直接在 mock 实例上进行。</p> </div> </div> <div class="sect2"> <h3 id="_解决方案">解决方案</h3> <div class="paragraph"> <p>修改`createMockProject()`为了返回两个对象：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { val mockPluginContainer = mock<PluginContainer>() val mockProject = mock<Project> { on { plugins } doReturn mockPluginContainer } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>并调整测试：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) // ✅ Vérification directe sur le bon mock verify(mockPluginContainer).apply(JBakePlugin::class.java) }</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_问题_2级联的_unfinishedstubbingexception">问题 #2：级联的 UnfinishedStubbingException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_诊断_2">�诊断</h3> <div class="paragraph"> <p>在应用第一次修正后，出现了新的错误：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-text hljs" data-lang="text">UnfinishedStubbingException: Unfinished stubbing detected here Hints: 3. you are stubbing the behaviour of another mock inside before 'thenReturn' instruction is completed</code></pre> </div> </div> <div class="paragraph"> <p>有问题的代码使用了 Mockito-Kotlin 的 DSL 语法：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">val mockProject = mock<Project> { on { extensions } doReturn mockExtensionContainer on { plugins } doReturn mockPluginContainer on { logger } doReturn mock() // ❌ PROBLÈME ICI ! }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-2.svg" alt="mockito problem 2" width="690" height="316"> </div> </div> </div> <div class="sect2"> <h3 id="_解决方案_2">解决方案</h3> <div class="paragraph"> <p>创建<strong>所有</strong>所有 mocks 在任何存根块之外，然后用……配置它们`whenever()`</think></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ Créer TOUS les mocks d'abord val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() // 2️⃣ Configurer les mocks séparément avec whenever() whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.logger).thenReturn(mockLogger) return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>黄金规则</strong>永远不要调用`mock()`在 mock 配置块内。始终先创建 mock，然后再进行配置。</p> </div> </td> </tr> </table> </div> </div> </div> </div> <div class="sect1"> <h2 id="_问题_3_配置文件不存在">问题 #3 : 配置文件不存在</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_诊断_3">诊断</h3> <div class="paragraph"> <p>即使使用了正确的模拟，测试仍然会失败，因为插件找不到配置文件：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Dans BakeryPlugin.kt if (!project.layout.projectDirectory.asFile .resolve(extension.configPath.get()).exists()) { println("config file does not exists") return@afterEvaluate // ❌ Sort avant d'appliquer JBake ! }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/mockito-problem-3.svg" alt="mockito problem 3" width="401" height="373"> </div> </div> </div> <div class="sect2"> <h3 id="_解决方案_3">解决方案</h3> <div class="paragraph"> <p>配置 mock 以使路径解析正常工作 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile // Configuration cohérente des chemins whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // Maintenant : projectDir.resolve("site.yml") existe ! ✅ }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/path-resolution.svg" alt="path resolution" width="1784" height="5580"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_问题_4afterevaluate_和_nullpointerexception">问题 #4：afterEvaluate 和 NullPointerException</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_诊断_4">诊断</h3> <div class="paragraph"> <p>插件在代码块中使用 JBake。<code>afterEvaluate</code>, 并访问`buildDirectory.dir()`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">project.afterEvaluate { // ... project.tasks.withType(JBakeTask::class.java) .getByName("bake").apply { output = project.layout.buildDirectory .dir(site.bake.destDirPath) // ❌ NPE ici ! .get() .asFile } }</code></pre> </div> </div> <div class="paragraph"> <p>的模拟`buildDirectory.dir()<code>返回`null</code>。</p> </div> </div> <div class="sect2"> <h3 id="_解决方案_4">解决方案</h3> <div class="paragraph"> <p>�嘲笑`afterEvaluate`为了让它立即执行，并完全配置`buildDirectory`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // ... autres mocks ... val mockBuildDirectory = mock<DirectoryProperty>() val buildDir = File(projectDir, "build") // Mocker dir() pour retourner un Provider valide whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // Mocker afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) // ✅ Exécution synchrone null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="imageblock"> <div class="content"> <img src="./images/after-evaluate-flow.svg" alt="after evaluate flow" width="762" height="357"> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_完整的解决方案">完整的解决方案</h2> <div class="sectionbody"> <div class="paragraph"> <p>以下是函数`createMockProject()`最终，解决所有问题：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">private fun createMockProject(): Pair<Project, PluginContainer> { // 1️⃣ CRÉER tous les mocks (pas de nested mocks !) val mockPluginContainer = mock<PluginContainer>() val mockExtensionContainer = mock<ExtensionContainer>() val mockLogger = mock<org.gradle.api.logging.Logger>() val mockTaskContainer = mock<TaskContainer>() val mockConfigPathProperty = mock<Property<String>>() val mockBakeryExtension = mock<BakeryExtension>() val mockProjectDirectory = mock<Directory>() val mockBuildDirectory = mock<DirectoryProperty>() val mockProjectLayout = mock<ProjectLayout>() val mockProject = mock<Project>() // 2️⃣ CONFIGURER la résolution des chemins val configFile = File("../../site.yml").canonicalFile val projectDir = configFile.parentFile val buildDir = File(projectDir, "build") whenever(mockConfigPathProperty.get()).thenReturn("site.yml") whenever(mockConfigPathProperty.isPresent).thenReturn(true) whenever(mockBakeryExtension.configPath).thenReturn(mockConfigPathProperty) whenever(mockProjectDirectory.asFile).thenReturn(projectDir) // 3️⃣ CONFIGURER buildDirectory avec dir() whenever(mockBuildDirectory.dir(any<String>())).doAnswer { invocation -> val path = invocation.arguments[0] as String val mockDirProvider = mock<Provider<Directory>>() val mockDir = mock<Directory>() whenever(mockDir.asFile).thenReturn(File(buildDir, path)) whenever(mockDirProvider.get()).thenReturn(mockDir) mockDirProvider } // 4️⃣ ASSEMBLER le projet whenever(mockProjectLayout.projectDirectory).thenReturn(mockProjectDirectory) whenever(mockProjectLayout.buildDirectory).thenReturn(mockBuildDirectory) whenever(mockExtensionContainer.create("bakery", BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockExtensionContainer.getByType(BakeryExtension::class.java)) .thenReturn(mockBakeryExtension) whenever(mockProject.extensions).thenReturn(mockExtensionContainer) whenever(mockProject.plugins).thenReturn(mockPluginContainer) whenever(mockProject.tasks).thenReturn(mockTaskContainer) whenever(mockProject.layout).thenReturn(mockProjectLayout) whenever(mockProject.logger).thenReturn(mockLogger) whenever(mockProject.projectDir).thenReturn(projectDir) // 5️⃣ CONFIGURER afterEvaluate pour exécution immédiate whenever(mockProject.afterEvaluate(any<Action<Project>>())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null } return Pair(mockProject, mockPluginContainer) }</code></pre> </div> </div> <div class="paragraph"> <p>以及通过的最终测试：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">@Test fun `plugin applies jbake gradle plugin`() { val (project, mockPluginContainer) = createMockProject() val plugin = BakeryPlugin() plugin.apply(project) verify(mockPluginContainer).apply(JBakePlugin::class.java) // ✅ SUCCÈS ! }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_学到的教训">学到的教训</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/lessons-learned.svg" alt="lessons learned" width="748" height="472"> </div> </div> <div class="sect2"> <h3 id="_检查正确的_mock">检查正确的 mock</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX verify(project.plugins).apply(JBakePlugin::class.java) // ✅ CORRECT val (project, mockPluginContainer) = createMockProject() verify(mockPluginContainer).apply(JBakePlugin::class.java)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_2_避免使用嵌套的_mock">2. 避免使用嵌套的 mock</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ❌ FAUX - UnfinishedStubbingException val mockProject = mock<Project> { on { logger } doReturn mock() // Nested mock creation ! } // ✅ CORRECT - Créer séparément val mockLogger = mock<org.gradle.api.logging.Logger>() val mockProject = mock<Project>() whenever(mockProject.logger).thenReturn(mockLogger)</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_3_模拟评估回调">3. 模拟评估回调</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// ✅ afterEvaluate doit s'exécuter pour les tests whenever(mockProject.afterEvaluate(any())).doAnswer { invocation -> val action = invocation.arguments[0] as Action<Project> action.execute(mockProject) null }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_4_测试路径解析">4. 测试路径解析</h3> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">// Toujours vérifier que les chemins se résolvent correctement val extension = project.extensions.getByType(BakeryExtension::class.java) val configPath = extension.configPath.get() val projectDir = project.layout.projectDirectory.asFile val resolvedConfig = projectDir.resolve(configPath) println("Resolved config: ${resolvedConfig.absolutePath}") println("Exists: ${resolvedConfig.exists()}")</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_最终测试架构">最终测试架构</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="./images/test-architecture.svg" alt="test architecture" width="1744" height="5468"> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>看起来似乎只是一个简单的测试问题，结果却被证明是一个极佳的案例研究对象：</p> </div> <div class="ulist"> <ul> <li> <p>Mockito 与 Kotlin 的细微差别</p> </li> <li> <p>模拟正确对象的重要性</p> </li> <li> <p>测试中异步回调的管理</p> </li> <li> <p>在 Gradle 插件中解析路径</p> </li> </ul> </div> <div class="paragraph"> <p>有条不紊的调试，通过理解问题的每一层，得出了一个健壮且可维护的解决方案。</p> </div> <div class="admonitionblock tip"> <table> <tr> <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> <p><strong>您的测试建议</strong>如果在使用 Mockito 时遇到 "Wanted but not invoked"，请始终自问： 1. 我是否在检查正确的 mock？ 2. 所有我的 mock 都是在配置块之外创建的吗？ 3. 我的回调真的在执行吗？ 4. 我的路径能正确解析吗？</p> </div> </td> </tr> </table> </div> </div> </div> <div class="sect1"> <h2 id="_资源">资源</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p><a href="https://github.com/mockito/mockito-kotlin">Mockito-Kotlin 文档</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/custom_plugins.html">Gradle 插件开发指南</a></p> </li> <li> <p><a href="https://jbake.org/">JBake 静态站点生成器</a></p> </li> </ul> </div> <hr> <div class="paragraph"> <p>您在测试中遇到类似的问题吗？请在评论中分享您的经验！</p> </div> </div> </div> https://cheroliv.com/blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html Tue, 24 Sep 2024 00:00:00 +0000 blog/2024/0075_kotlin_arrow-traverse_right_and_left_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_either_单子是什么">Either 单子是什么？</a> <ul class="sectlevel2"> <li><a href="#_为什么使用_either">为什么使用 Either？</a></li> </ul> </li> <li><a href="#_上下文">上下文</a></li> <li><a href="#_不同的方法">不同的方法</a> <ul class="sectlevel2"> <li><a href="#_经典方法与_when">经典方法与 `when</a></li> <li><a href="#_使用_fold_以获得更简洁的方法">使用 <code>fold</code> 以获得更简洁的方法</a></li> <li><a href="#_使用_map_和_mapleft_进行转换">使用 <code>map</code> 和 <code>mapLeft</code> 进行转换</a></li> <li><a href="#_使用_getorelse_的错误处理">使用 <code>getOrElse</code> 的错误处理</a></li> <li><a href="#_使用_onleft_和_onright_的侧向动作">使用 <code>onLeft</code> 和 <code>onRight</code> 的侧向动作</a></li> <li><a href="#_使用_flatmap_进行操作链">使用 <code>flatMap</code> 进行操作链</a></li> <li><a href="#_双向转换使用_bimap">双向转换使用 `bimap</a></li> <li><a href="#_使用_swap_进行侧面反转">使用 <code>swap</code> 进行侧面反转</a></li> <li><a href="#_使用_tap_和_tapleft">使用 <code>tap</code> 和 <code>tapLeft</code> :</a></li> <li><a href="#_使用_recover">使用 <code>recover</code> :</a></li> </ul> </li> <li><a href="#_实际使用案例">实际使用案例</a></li> <li><a href="#_结论">结论</a></li> <li><a href="#_更进一步">更进一步</a></li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>目标受众 :</em> 中级至高级 Kotlin 开发者。</div> <p>在Kotlin的函数式编程世界中，Arrow库提供了强大的工具来处理错误和替代情况。在这些工具中，单子`Either`以其能够表示两种可能状态的能力而脱颖而出：成功（Right）或失败（Left）。但是如何在这两种状态之间高效导航？这就是我们将在本文中探讨的内容。</p> </div> </div> </div> <div class="sect1"> <h2 id="_either_单子是什么">Either 单子是什么？</h2> <div class="sectionbody"> <div class="paragraph"> <p>单子`Either`是一种表示两种互斥可能性的数据结构。在 Kotlin 中使用 Arrow 时，它通常用于处理操作的成功和失败情况，提供了一种优雅的替代传统异常的方案。</p> </div> <div class="sect2"> <h3 id="_为什么使用_either">为什么使用 Either？</h3> <div class="olist arabic"> <ol class="arabic"> <li> <p>显式错误处理：迫使开发者考虑失败情况。</p> </li> <li> <p>函数式组合：便于链式操作，这些操作可能会失败。</p> </li> <li> <p>Type-safety : 错误是有类型的，这有助于更精确地处理它们。</p> </li> <li> <p>没有例外：避免副作用和执行流的意外中断。</p> </li> </ol> </div> </div> </div> </div> <div class="sect1"> <h2 id="_上下文">上下文</h2> <div class="sectionbody"> <div class="paragraph"> <p>想象一下，你正在开发一个REST APIhttps://spring.io/projects/spring-boot/[Spring Boot,windows=稍后读取] et <a href="https://kotlinlang.org/">Kotlin</a>, 使用该库https://arrow-kt.io/[箭头,窗口=稍后阅读]. 您有一个功能`findOneUserByEmail`返回一个`Either<Throwable, User>`. 您如何能以优雅且功能性的方式处理此结果？</p> </div> <div class="paragraph"> <p>我们有一个 User 类：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@file:Suppress( "RemoveRedundantQualifierName", "MemberVisibilityCanBePrivate", "SqlNoDataSourceInspection" ) package webapp.users import arrow.core.Either import arrow.core.left import arrow.core.right import com.fasterxml.jackson.annotation.JsonIgnore import com.fasterxml.jackson.databind.ObjectMapper import jakarta.validation.constraints.NotNull import jakarta.validation.constraints.Pattern import jakarta.validation.constraints.Size import org.springframework.beans.factory.getBean import org.springframework.context.ApplicationContext import org.springframework.data.r2dbc.core.R2dbcEntityTemplate import org.springframework.r2dbc.core.DatabaseClient import org.springframework.r2dbc.core.awaitOne import org.springframework.r2dbc.core.awaitRowsUpdated import webapp.core.property.ANONYMOUS_USER import webapp.core.property.EMPTY_STRING import webapp.core.utils.AppUtils.cleanField import webapp.users.EntityModel.Companion.ID_MEMBER import webapp.users.User.UserDao.Attributes.EMAIL_ATTR import webapp.users.User.UserDao.Attributes.ID_ATTR import webapp.users.User.UserDao.Attributes.LANG_KEY_ATTR import webapp.users.User.UserDao.Attributes.LOGIN_ATTR import webapp.users.User.UserDao.Attributes.PASSWORD_ATTR import webapp.users.User.UserDao.Attributes.VERSION_ATTR import webapp.users.User.UserDao.Constraints.LOGIN_REGEX import webapp.users.User.UserDao.Fields.EMAIL_FIELD import webapp.users.User.UserDao.Fields.ID_FIELD import webapp.users.User.UserDao.Fields.LANG_KEY_FIELD import webapp.users.User.UserDao.Fields.LOGIN_FIELD import webapp.users.User.UserDao.Fields.PASSWORD_FIELD import webapp.users.User.UserDao.Fields.VERSION_FIELD import webapp.users.User.UserDao.Relations.INSERT import webapp.users.security.Role import webapp.users.security.Role.RoleDao import webapp.users.security.UserRole.UserRoleDao import java.util.* import jakarta.validation.constraints.Email as EmailConstraint data class User( override val id: UUID? = null, @field:NotNull @field:Pattern(regexp = LOGIN_REGEX) @field:Size(min = 1, max = 50) val login: String, @JsonIgnore @field:NotNull @field:Size(min = 60, max = 60) val password: String = EMPTY_STRING, @field:EmailConstraint @field:Size(min = 5, max = 254) val email: String = EMPTY_STRING, @JsonIgnore val roles: MutableSet<Role> = mutableSetOf(Role(ANONYMOUS_USER)), @field:Size(min = 2, max = 10) val langKey: String = EMPTY_STRING, @JsonIgnore val version: Long = -1, ) : EntityModel<UUID>() { companion object { @JvmStatic fun main(args: Array<String>) = println(UserDao.Relations.sqlScript) } object UserDao { object Constraints { // Regex for acceptable logins const val LOGIN_REGEX = "^(?>[a-zA-Z0-9!$&*+=?^_`{|}~.-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*)|(?>[_.@A-Za-z0-9-]+)$" const val PASSWORD_MIN: Int = 4 const val PASSWORD_MAX: Int = 16 const val IMAGE_URL_DEFAULT = "https://placehold.it/50x50" const val PHONE_REGEX = "^(\\+|00)?[1-9]\\d{0,49}\$" } object Members { const val PASSWORD_MEMBER = "password" const val ROLES_MEMBER = "roles" } object Fields { const val ID_FIELD = "`id`" const val LOGIN_FIELD = "`login`" const val PASSWORD_FIELD = "`password`" const val EMAIL_FIELD = "`email`" const val LANG_KEY_FIELD = "`lang_key`" const val VERSION_FIELD = "`version`" } object Attributes { val ID_ATTR = ID_FIELD.cleanField() val LOGIN_ATTR = LOGIN_FIELD.cleanField() val PASSWORD_ATTR = PASSWORD_FIELD.cleanField() val EMAIL_ATTR = EMAIL_FIELD.cleanField() const val LANG_KEY_ATTR = "langKey" val VERSION_ATTR = VERSION_FIELD.cleanField() } object Relations { const val TABLE_NAME = "`user`" const val SQL_SCRIPT = """ CREATE TABLE IF NOT EXISTS $TABLE_NAME ( $ID_FIELD UUID default random_uuid() PRIMARY KEY, $LOGIN_FIELD VARCHAR, $PASSWORD_FIELD VARCHAR, $EMAIL_FIELD VARCHAR, $LANG_KEY_FIELD VARCHAR, $VERSION_FIELD bigint ); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_login` ON $TABLE_NAME ($LOGIN_FIELD); CREATE UNIQUE INDEX IF NOT EXISTS `uniq_idx_user_email` ON $TABLE_NAME ($EMAIL_FIELD); """ @Suppress("SqlDialectInspection") const val INSERT = """ insert into $TABLE_NAME ( $LOGIN_FIELD, $EMAIL_FIELD, $PASSWORD_FIELD, $LANG_KEY_FIELD, $VERSION_FIELD ) values ( :login, :email, :password, :langKey, :version)""" @JvmStatic val sqlScript: String get() = setOf( UserDao.Relations.SQL_SCRIPT, RoleDao.Relations.SQL_SCRIPT, UserRoleDao.Relations.SQL_SCRIPT ).joinToString("") .trimMargin() } object Dao { val Pair<User, ApplicationContext>.toJson: String get() = second.getBean<ObjectMapper>().writeValueAsString(first) suspend fun Pair<User, ApplicationContext>.save(): Either<Throwable, Long> = try { second.getBean<R2dbcEntityTemplate>() .databaseClient .sql(INSERT) .bind(LOGIN_ATTR, first.login) .bind(EMAIL_ATTR, first.email) .bind(PASSWORD_ATTR, first.password) .bind(LANG_KEY_ATTR, first.langKey) .bind(VERSION_ATTR, first.version) .fetch() .awaitRowsUpdated() .right() } catch (e: Throwable) { e.left() } suspend fun ApplicationContext.findOneUserByEmail( email: String ): Either<Throwable, User> = try { getBean<DatabaseClient>() .sql("SELECT * FROM `user` WHERE LOWER(email) = LOWER(:email)") .bind("email", email) .fetch() .awaitOne() .let { row -> User( id = row[ID_ATTR] as UUID?, login = row[LOGIN_ATTR] as String, password = row[PASSWORD_ATTR] as String, email = row[EMAIL_ATTR] as String, langKey = row[LANG_KEY_ATTR] as String, version = row[VERSION_ATTR] as Long ) }.right() } catch (e: Throwable) { e.left() } } } /** Account REST API URIs */ object UserRestApis { const val API_AUTHORITY = "/api/authorities" const val API_USERS = "/api/users" const val API_SIGNUP = "/signup" const val API_SIGNUP_PATH = "$API_USERS$API_SIGNUP" const val API_ACTIVATE = "/activate" const val API_ACTIVATE_PATH = "$API_USERS$API_ACTIVATE?key=" const val API_ACTIVATE_PARAM = "{activationKey}" const val API_ACTIVATE_KEY = "key" const val API_RESET_INIT = "/reset-password/init" const val API_RESET_FINISH = "/reset-password/finish" const val API_CHANGE = "/change-password" const val API_CHANGE_PATH = "$API_USERS$API_CHANGE" } } // Abstract entity model with Generic ID, which can be of any type abstract class EntityModel<T>( open val id: T? = null ) { companion object { const val ID_MEMBER = "id" } } // Generic extension function that allows the ID to be applied to any EntityModel type inline fun <reified T : EntityModel<ID>, ID> T.withId(id: ID): T { // Use reflection to create a copy with the passed ID return this::class.constructors.first { it.parameters.any { param -> param.name == ID_MEMBER } } .call(id, *this::class.constructors.first().parameters.drop(1).map { param -> this::class.members.first { member -> member.name == param.name }.call(this) }.toTypedArray()) }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_不同的方法">不同的方法</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_经典方法与_when">经典方法与 `when</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val user: User by lazy { userFactory(USER) } val result: Either<Throwable, User> = context.findOneUserByEmail(user.email) when (result) { is Either.Left -> { val error = result.value println("Erreur : ${error.message}") } is Either.Right -> { val user = result.value println("Utilisateur trouvé : ${user.login}") } }</code></pre> </div> </div> <div class="paragraph"> <p>虽然简单易读，但它没有充分利用Arrow的函数式能力。</p> </div> </div> <div class="sect2"> <h3 id="_使用_fold_以获得更简洁的方法">使用 <code>fold</code> 以获得更简洁的方法</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.fold( { error -> println("Erreur : ${error.message}") }, { user -> println("Utilisateur trouvé : ${user.login}") } )</code></pre> </div> </div> <div class="paragraph"> <p>`fold`可以为 Left 和 Right 两种情况定义操作，简洁且优雅。</p> </div> </div> <div class="sect2"> <h3 id="_使用_map_和_mapleft_进行转换">使用 <code>map</code> 和 <code>mapLeft</code> 进行转换</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val processedResult = result .map { user -> "Utilisateur trouvé : ${user.login}" } .mapLeft { error -> "Erreur : ${error.message}" } println(processedResult.merge())</code></pre> </div> </div> <div class="paragraph"> <p>这种方法可以在保持 Either 结构不变的情况下转换其中的值，适用于更复杂的处理链。</p> </div> </div> <div class="sect2"> <h3 id="_使用_getorelse_的错误处理">使用 <code>getOrElse</code> 的错误处理</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val user = result.getOrElse { error -> println("Erreur : ${error.message}") User(login = "default", email = "default@example.com") // utilisateur par défaut } println("Login : ${user.login}")</code></pre> </div> </div> <div class="paragraph"> <p>`getOrElse`它提供了一种优雅的错误处理方式，通过允许提供默认值。</p> </div> </div> <div class="sect2"> <h3 id="_使用_onleft_和_onright_的侧向动作">使用 <code>onLeft</code> 和 <code>onRight</code> 的侧向动作</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.onLeft { error -> println("Erreur : ${error.message}") } .onRight { user -> println("Utilisateur trouvé : ${user.login}") }</code></pre> </div> </div> <div class="paragraph"> <p>这些方法可以在每一边执行操作而不修改 Either，非常适合用于日志记录或轻微的副作用。</p> </div> </div> <div class="sect2"> <h3 id="_使用_flatmap_进行操作链">使用 <code>flatMap</code> 进行操作链</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun findUser(email: String): Either<Throwable, User> = // ... implémentation fun getUserPermissions(user: User): Either<Throwable, List<String>> = // ... implémentation val userPermissions = findUser("user@example.com") .flatMap { user -> getUserPermissions(user) }</code></pre> </div> </div> <div class="paragraph"> <p><code>flatMap`有助于将那些自身返回的操作链接起来`Either</code>，从而避免了`Either`嵌套的</p> </div> </div> <div class="sect2"> <h3 id="_双向转换使用_bimap">双向转换使用 `bimap</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val processedResult = result.bimap( { error -> "Erreur: ${error.message}" }, { user -> "Utilisateur: ${user.login}" } )</code></pre> </div> </div> <div class="paragraph"> <p>`bimap`可以在一次操作中同时转换左侧和右侧。</p> </div> </div> <div class="sect2"> <h3 id="_使用_swap_进行侧面反转">使用 <code>swap</code> 进行侧面反转</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result: Either<Throwable, User> = // ... obtention du résultat val swapped = result.swap()</code></pre> </div> </div> <div class="paragraph"> <p><code>swap`在您想要反转某物的两侧时很有用`Either</code>, 例如，用于将一个函数的接口适配到另一个函数。</p> </div> </div> <div class="sect2"> <h3 id="_使用_tap_和_tapleft">使用 <code>tap</code> 和 <code>tapLeft</code> :</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">result.tap { user -> println("Utilisateur trouvé : ${user.login}") } .tapLeft { error -> println("Erreur : ${error.message}") }</code></pre> </div> </div> <div class="paragraph"> <p>类似于`onLeft` et <code>onRight</code>, 但是这些方法返回原始的 Either，这对于链式操作很有用。</p> </div> </div> <div class="sect2"> <h3 id="_使用_recover">使用 <code>recover</code> :</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val recoveredUser = result.recover { error -> println("Erreur récupérée : ${error.message}") User(login = "recovered", email = "recovered@example.com") } println("Login : ${recoveredUser.login}")</code></pre> </div> </div> <div class="paragraph"> <p>此方法通过提供一个替换值将 Either.Left 转换为 Either.Right。</p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_实际使用案例">实际使用案例</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>使用`fold`适用于需要逐案处理的简单操作。 - 更倾向于`map` et <code>mapLeft`用于数据转换而不更改结构的`Either</code>. - 选择`flatMap`在可能失败的操作链中。 - 使用`recover`为提供默认值以防出错。 - 选择`onLeft` et <code>onRight</code> (ou <code>tap</code> et <code>tapLeft</code>) 用于诸如日志记录之类的副作用。 - 使用`bimap`将两边转换为单一操作。 - 应用`swap`当您需要将一个函数的接口适配到另一个函数时。</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>每种方法根据使用情境各有其优势。诸如这些方法`fold`, <code>map</code>(Empty)<code>mapLeft</code>, et `recover`在您希望链式执行多个操作或以函数式方式转换数据时特别有用。</p> </div> <div class="paragraph"> <p>单子`Either`Arrow 提供了出色的灵活性，用于在 Kotlin 应用程序中处理成功和错误情况。通过掌握这些不同的方法，您将能够编写更健壮、更易读且更具功能性的代码。</p> </div> <div class="paragraph"> <p>在您的下一个项目中，不要犹豫去探索这些技术，以充分利用 Kotlin 和 Arrow 的函数式编程！</p> </div> </div> </div> <div class="sect1"> <h2 id="_更进一步">更进一步</h2> <div class="sectionbody"> <div class="paragraph"> <p>Arrow 的官方文档：https://arrow-kt.io/docs/apidocs/arrow-core/arrow.core/-either/[箭头 任一] - Kotlin 协程与 Arrow :https://arrow-kt.io/docs/fx/[Arrow Fx 协程]</p> </div> <div class="paragraph"> <p>别忘记分享你的经验和你最喜欢的工作技巧`Either`在下面的评论中！</p> </div> </div> </div> https://cheroliv.com/blog/2024/0074_seach_file_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2024/0074_seach_file_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_介绍">介绍</a></li> <li><a href="#_使用命令_find">使用命令 `find</a> <ul class="sectlevel2"> <li><a href="#_find_的附加选项">find` 的附加选项</a></li> </ul> </li> <li><a href="#_使用命令_locate">使用命令 `locate</a></li> <li><a href="#_使用命令_grep_在文件中搜索文本">使用命令 <code>grep</code> 在文件中搜索文本</a></li> <li><a href="#_结论">结论</a></li> </ul> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">问题： 在 Linux 操作系统的终端中搜索文件。</div> <p>在本文中，我们将探讨如何在 Ubuntu 中使用 Zsh 终端搜索文件。Zsh（Z shell）是一种功能强大且广泛使用的命令解释器，因其灵活性和高级功能而受到欢迎。</p> </div> <div class="paragraph"> <p>Ubuntu，一种流行的 Linux 发行版，提供了多种命令行工具来搜索文件。我们将看到如何使用诸如`find`, <code>locate</code> et `grep`在终端中快速有效地定位文件。</p> </div> </div> </div> <div class="sect1"> <h2 id="_使用命令_find">使用命令 `find</h2> <div class="sectionbody"> <div class="paragraph"> <p>命令`find`可以在特定目录及其子目录中搜索文件。其基本语法如下：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find [chemin] -name [nom_du_fichier]</code></pre> </div> </div> <div class="paragraph"> <p>这是一个实际示例，我们正在搜索一个名为的文件。<code>example.txt`在目录中</code>/home`:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find /home -name "example.txt"</code></pre> </div> </div> <div class="paragraph"> <p>此命令将遍历所有子目录`/home`并显示文件的完整路径（如果已找到）。</p> </div> <div class="paragraph"> <p><strong>命令的在线手册`find` : <a href="https://man.archlinux.org/man/find.1.fr/">man find</a></strong></p> </div> <div class="sect2"> <h3 id="_find_的附加选项">find` 的附加选项</h3> <div class="paragraph"> <p>命令`find`非常强大，具有许多选项。以下是一些有用的例子：</p> </div> <div class="ulist"> <ul> <li> <p><strong>按文件类型搜索</strong>: 要仅搜索文件，请使用`-type f`, 并且要搜索目录，请使用`-type d`. - <strong>按尺寸搜索</strong>: 你也可以根据文件大小使用该选项来过滤文件`-size`. Par exemple, pour rechercher des fichiers de plus de 100 Mo, utilisez :</p> </li> </ul> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">find /home -size +100M</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用命令_locate">使用命令 `locate</h2> <div class="sectionbody"> <div class="paragraph"> <p>命令`locate`比……更快`find`因为它使用了一个预先索引的数据库，其中包含系统上存在的文件。您必须首先使用以下命令更新此数据库：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo updatedb</code></pre> </div> </div> <div class="paragraph"> <p>然后，您可以像这样搜索文件：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">locate example.txt</code></pre> </div> </div> <div class="paragraph"> <p>我使用https://fr.wikipedia.org/wiki/Z_Shell[zsh]与https://github.com/ohmyzsh/ohmyzsh/wiki[oh-my-zsh], 结果发现该命令`locate`无法从…​访问`zsh`但自从…​确实有可能`bash`, 为应对这一点，论点`-c`命令的`bash`允许启动一条命令`bash`从另一种类型的终端。</p> </div> <div class="paragraph"> <p>我正在查找以该模式结尾的文件`001.pdf`在用户目录中</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">bash -c "locate ~/*001.pdf"</code></pre> </div> </div> <div class="paragraph"> <p><strong>命令的在线手册`locate`:https://man.archlinux.org/man/locate.1.fr/[man locate,windows=read-later]</strong></p> </div> </div> </div> <div class="sect1"> <h2 id="_使用命令_grep_在文件中搜索文本">使用命令 <code>grep</code> 在文件中搜索文本</h2> <div class="sectionbody"> <div class="paragraph"> <p>如果您想在文件中搜索特定文本，您可以使用`grep`. 例如，为了在所有文件中搜索单词“Ubuntu”的出现`.txt`当前目录，使用 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">grep "Ubuntu" *.txt</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>在 Ubuntu 中通过 Zsh 终端搜索文件可以使用多种强大的工具。`find`灵活且提供了众多选项，而`locate`它允许使用预构建的数据库进行快速搜索。 最后,`grep`可以在文件中查找文本的出现。</p> </div> <div class="paragraph"> <p>这些命令为您提供了一套完整的工具，使您的文件搜索更高效并适应您的需求而每个这些命令都有一个可通过该命令查看的手册`man`</p> </div> </div> </div> https://cheroliv.com/blog/2021/0030_memo_linux_post.html Mon, 23 Sep 2024 00:00:00 +0000 blog/2021/0030_memo_linux_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_键盘">键盘：</a> <ul class="sectlevel2"> <li><a href="#_ctrl键"><em>Ctrl键</em></a></li> </ul> </li> <li><a href="#_许可授权">许可(授权)</a></li> <li><a href="#_文件搜索">文件搜索</a></li> </ul> </div> <div class="sect1"> <h2 id="_键盘">键盘：</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_ctrl键"><em>Ctrl键</em></h3> <table class="tableblock frame-all grid-all stretch"> </table> <div class="paragraph"> <p><a href="https://korben.info/les-raccourcis-clavier-pour-bash-terminal-linux-et-macos.html">链接</a><br> <a href="https://blogmotion.fr/systeme/astuces-bash-linux-16175">其他链接</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_许可授权">许可(授权)</h2> <div class="sectionbody"> <div class="paragraph"> <p>CHMOD 用于更改文件的权限。</p> </div> <div class="paragraph"> <p>权限 命令</p> </div> <div class="paragraph"> <p>U G W rwx rwx rwx chmod 777 filename rwx rwx r-x chmod 775 文件名 rwx r-x r-x chmod 755 filename rw- rw- r-- chmod 664 filename rw- r-- r-- chmod 644 文件名</p> </div> <div class="paragraph"> <p>U = 用户 G = Group W = 世界</p> </div> <div class="paragraph"> <p>r = 可读 w = 可写 x = 可执行的 - = 无权限</p> </div> <div class="paragraph"> <p>另一种查看权限的方式：</p> </div> <div class="paragraph"> <p>400 由所有者读取 040 组可读 004 由任何人阅读（其他） 200 write by owner 020 按组写入 002 任何人都可以写 100 由所有者执行 010 按组执行 任何人都可以执行</p> </div> <div class="paragraph"> <p>要获得组合，只需把它们相加。<br> 例如，为了让所有者能够读取、写入、执行，<br> 已读取，已执行，按组执行以及任何人都可以执行，<br> 您将把 400+200+100+040+010+001 相加得到 751.<br></p> </div> </div> </div> <div class="sect1"> <h2 id="_文件搜索"><a href="/blog/2024/0074_seach_file_linux_post.html">文件搜索</a></h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html Thu, 1 Feb 2024 00:00:00 +0000 blog/2024/0072_Exposer_un_port_linux_subsystem_post.adoc.html <div class="paragraph"> <div class="title"><em>阅读时间：10秒</em></div> <p>问题： 如何在 Windows 主机上暴露 Ubuntu 子系统的 8820 端口？ Ubuntu 是由命令启动的`wsl --install`。</p> </div> <div class="paragraph"> <p>参考 : <a href="https://www.it-connect.fr/wsl-2-port-forwarding-comment-acceder-a-sa-machine-virtuelle-a-distance/">wsl-2端口转发</a></p> </div> https://cheroliv.com/blog/2024/0070_installer_pandoc_post.html Tue, 30 Jan 2024 00:00:00 +0000 blog/2024/0070_installer_pandoc_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>阅读时间：3分钟</em> Pandoc 是一个通用的文档转换器</div> <p>Pandoc 是一种开源的文本处理软件，可用于在不同格式之间转换文档。 有几种安装 Pandoc 的方式。</p> </div> </div> </div> <div class="sect1"> <h2 id="_从下载页面安装"><strong>从下载页面安装</strong></h2> <div class="sectionbody"> <div class="paragraph"> <p>要从下载页面安装 Pandoc，请按照以下步骤操作：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>�访问 Pandoc 下载页面：https://pandoc.org/installing.html/[<a href="https://pandoc.org/installing.html" class="bare">https://pandoc.org/installing.html</a>]</p> </li> <li> <p>下载您操作系统的软件包安装程序。</p> </li> <li> <p>运行安装程序以安装 Pandoc。</p> </li> </ol> </div> <div class="paragraph"> <p><strong>从 zip 文件安装</strong></p> </div> <div class="paragraph"> <p>要从 zip 文件安装 Pandoc，请按照以下步骤：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>下载包含 Pandoc 二进制文件和文档的 zip 文件。</p> </li> <li> <p>解压缩 zip 文件。</p> </li> <li> <p>将二进制文件移动到您选择的目录。</p> </li> </ol> </div> <div class="paragraph"> <p><strong>使用 Chocolatey 安装</strong></p> </div> <div class="paragraph"> <p>要使用 Chocolatey 安装 Pandoc，请按照以下步骤：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>打开命令提示符。</p> </li> <li> <p>�执行以下命令：</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-powershell" data-lang="powershell">choco install pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>使用 winget 进行安装</strong></p> </div> <div class="paragraph"> <p>要使用 winget 安装 Pandoc，请按以下步骤操作：</p> </div> <div class="olist arabic"> <ol class="arabic"> <li> <p>打开命令提示符。</p> </li> <li> <p>执行以下命令：</p> </li> </ol> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-powershell" data-lang="powershell">winget install --source winget --exact --id JohnMacFarlane.Pandoc</code></pre> </div> </div> <div class="paragraph"> <p><strong>建议</strong></p> </div> <div class="paragraph"> <p>默认情况下，Pandoc 使用 LaTeX 创建 PDF。 建议通过 MiKTeX 安装 LaTeX。 带有该选项`--pdf-engine`, 您也可以为此任务指定其他程序。</p> </div> <div class="paragraph"> <p><strong>警告</strong></p> </div> <div class="paragraph"> <p>使用多种安装方法可能导致 Pandoc 的两个独立安装。 建议在切换到替代安装方法之前正确卸载 Pandoc。</p> </div> <div class="paragraph"> <p><strong>在linux上通过WSL的安装</strong></p> </div> <div class="paragraph"> <p>请确认您的包管理器中 pandoc 的版本不是过时的。 Pandoc 位于 Debian、Ubuntu、Slackware、Arch、Fedora、NixOS、openSUSE、gentoo 和 Void 的软件仓库中。</p> </div> <div class="paragraph"> <p>要获取最新版本，我们在下载页面提供适用于 amd64 架构的二进制包。</p> </div> <div class="paragraph"> <p>可执行文件是静态链接的，没有动态依赖，也没有对外部数据文件的依赖。 注意：由于静态链接，此包的 pandoc 二进制文件无法使用需要外部 C 编写的 Lua 模块的 Lua 过滤器。</p> </div> <div class="paragraph"> <p>提供一个 tarball 和一个 deb 安装程序。 要安装 deb :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo dpkg -i $DEB</code></pre> </div> </div> <div class="paragraph"> <p>写作时的例子：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">wget https://github.com/jgm/pandoc/releases/download/3.1.11.1/pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">sudo dpkg -i pandoc-3.1.11.1-1-amd64.deb</code></pre> </div> </div> <div class="paragraph"> <p>où `$DEB`是下载的deb文件的路径。 这将安装可执行文件`pandoc`和手册页。</p> </div> <div class="paragraph"> <p>如果您使用的是基于 RPM 的发行版，您可能能够使用 alien 从我们的下载页面安装 deb 包。</p> </div> <div class="paragraph"> <p>在任何发行版中，您可以从 tarball 中`$DEST`(例如，<code>/usr/local/</code> ou <code>$HOME/.local</code>) 通过做 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">tar xvzf $TGZ --strip-components 1 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>où `$TGZ`是下载的压缩 tarball 的路径。 对于 Pandoc 2.0 之前的版本，这些版本不提供 tarball，请尝试以下方法：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">ar p $DEB data.tar.gz | tar xvz --strip-components 2 -C $DEST</code></pre> </div> </div> <div class="paragraph"> <p>您也可以从源代码安装，使用下面的说明下`Compilation à partir de la source`。 请注意，大多数发行版的软件包仓库中都包含 Haskell 平台。 例如，在 Debian/Ubuntu 上，您可以使用它来安装</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">apt-get install haskell-platform</code></pre> </div> </div> <div class="paragraph"> <p>默认情况下，Pandoc 使用 LaTeX 创建 PDF。 我们建议通过您的包管理器安装TeX Live。 (在 Debian/Ubuntu,<code>apt-get install texlive</code>). 带有选项`--pdf-engine`不过，您也可以为此任务指定其他程序。</p> </div> </div> </div> https://cheroliv.com/blog/2023/0069_triple_python_js_ts_post.html Mon, 25 Dec 2023 00:00:00 +0000 blog/2023/0069_triple_python_js_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <div class="title"><em>阅读时间：2 分钟</em> 创建 kotlin.Triple 类的完整实现，使用 JavaScript、TypeScript 和 Python，采用函数式编程。</div> <p><strong>注意：</strong>这些类型`Maybe`, <code>Either</code>, `Result`它们不是 JavaScript 或 TypeScript 基础语言的一部分，因此我们必须自己实现它们。</p> </div> </div> </div> <div class="sect1"> <h2 id="_javascript">JavaScript</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//javascript // Maybe type const Maybe = (value) => ({ map: (fn) => (value !== null && value !== undefined ? Maybe(fn(value)) : Maybe(null)), flatMap: (fn) => (value !== null && value !== undefined ? fn(value) : Maybe(null)), getOrElse: (defaultValue) => (value !== null && value !== undefined ? value : defaultValue), }); // Either type const Either = { Left: (value) => ({ map: (fn) => Either.Left(value), flatMap: (fn) => Either.Left(value), getOrElse: (defaultValue) => defaultValue, isLeft: true, isRight: false, }), Right: (value) => ({ map: (fn) => Either.Right(fn(value)), flatMap: (fn) => fn(value), getOrElse: (defaultValue) => value, isLeft: false, isRight: true, }), }; // Triple class class Triple { constructor(a, b, c) { this.a = a; this.b = b; this.c = c; } map(fn) { return new Triple(fn(this.a), fn(this.b), fn(this.c)); } static of(a, b, c) { return new Triple(a, b, c); } // Example method using Maybe and Either divideBy(other) { return Maybe(this.b) .flatMap((numerator) => Maybe(other) .flatMap((denominator) => denominator !== 0 ? Either.Right(numerator / denominator) : Either.Left('Division by zero') ) ) .getOrElse(Either.Left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_typescript">TypeScript</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">//Typescript // Maybe type // noinspection JSAnnotator type Maybe<T> = { map<U>(fn: (value: T) => U): Maybe<U>; flatMap<U>(fn: (value: T) => Maybe<U>): Maybe<U>; getOrElse(defaultValue: T): T; }; const just = <T>(value: T): Maybe<T> => ({ map: <U>(fn: (value: T) => U) => just(fn(value)), flatMap: <U>(fn: (value: T) => Maybe<U>) => fn(value), getOrElse: (_: T) => value, }); const nothing = <T>(): Maybe<T> => ({ map: <U>(_: (value: T) => U) => nothing<U>(), flatMap: <U>(_: (value: T) => Maybe<U>) => nothing<U>(), getOrElse: (defaultValue: T) => defaultValue, }); // Either type type Either<L, R> = { map<U>(fn: (value: R) => U): Either<L, U>; flatMap<U>(fn: (value: R) => Either<L, U>): Either<L, U>; getOrElse(defaultValue: R): R; isLeft: boolean; isRight: boolean; }; const left = <L, R>(value: L): Either<L, R> => ({ map: <U>(_: (value: R) => U) => left<L, U>(value), flatMap: <U>(_: (value: R) => Either<L, U>) => left<L, U>(value), getOrElse: (defaultValue: R) => defaultValue, isLeft: true, isRight: false, }); const right = <L, R>(value: R): Either<L, R> => ({ map: <U>(fn: (value: R) => U) => right<L, U>(fn(value)), flatMap: <U>(fn: (value: R) => Either<L, U>) => fn(value), getOrElse: (_: R) => value, isLeft: false, isRight: true, }); // Triple class class Triple<T> { constructor(public a: T, public b: T, public c: T) {} map<U>(fn: (value: T) => U): Triple<U> { return new Triple<U>(fn(this.a), fn(this.b), fn(this.c)); } static of<T>(a: T, b: T, c: T): Triple<T> { return new Triple<T>(a, b, c); } // Example method using Maybe and Either divideBy(other: T): Either<string, number> { return just(this.b) .flatMap((numerator) => just(other) .flatMap((denominator) => denominator !== 0 ? right(numerator / denominator) : left('Division by zero') ) ) .getOrElse(left('Invalid input')); } } // Example usage const triple = Triple.of(1, 2, 3); const result = triple.map((x) => x * 2); console.log(result); // Triple { a: 2, b: 4, c: 6 } const divisionResult = triple.divideBy(2); console.log(divisionResult); // Either.Right { value: 1 } const invalidDivisionResult = triple.divideBy(0); console.log(invalidDivisionResult); // Either.Left { value: 'Division by zero' }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_python_pydantic_pymonad">Python, pydantic, pymonad</h2> <div class="sectionbody"> <div class="paragraph"> <p>创建一个使用 Python 的实现`pydantic`用于类型验证和`pymonad`对于单子：</p> </div> <div class="listingblock"> <div class="title">安装依赖 :</div> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">pip install pydantic pymonad</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-python" data-lang="python">from pymonad.either import Either, Left, Right from pydantic import BaseModel, ValidationError, validator # Définition de la classe Triple avec Pydantic class Triple(BaseModel): a: int b: int c: int @validator('b') def validate_b(cls, b, values): if b == 0: raise ValueError('Division by zero is not allowed') return b # Méthode utilisant Either pour la gestion des erreurs def divide_by(self, other): def division(numerator, denominator): return Right(numerator / denominator) def handle_error(error): return Left(str(error)) return Either(lambda: division(self.b, other)).or_else(handle_error) # Exemple d'utilisation try: triple = Triple(a=1, b=2, c=3) result = triple.divide_by(2) if result.is_right: print(f'Division result: {result.value}') else: print(f'Error: {result.value}') except ValidationError as e: print(f'Validation Error: {e}') except Exception as e: print(f'An unexpected error occurred: {e}')</code></pre> </div> </div> <div class="paragraph"> <p>在此示例：</p> </div> <div class="ulist"> <ul> <li> <p><code>pydantic`定义类`Triple</code>� 带有类型化的字段。 - 方法`divide_by`使用单子`Either` de `pymonad`用于处理由除以零导致的潜在错误。 - 自定义验证以确保值的`b`不等于零。如果等于零，则会引发异常，并`pymonad`捕获此异常以返回一个结果`Left`指示错误。</p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2023/0068_introduction_google_apps_script_post.html Fri, 22 Dec 2023 00:00:00 +0000 blog/2023/0068_introduction_google_apps_script_post.html <div class="sect1"> <h2 id="_目录">目录</h2> <div class="sectionbody"> <div class="paragraph"> <p><em>阅读时间：30分钟</em></p> </div> <div class="ulist"> <ul> <li> <p><a href="#引言">[引言]</a></p> </li> <li> <p><a href="#Google Apps Script 基本结构">[Google Apps Script 基本结构]</a></p> </li> <li> <p><a href="#Google Apps Script 中的类型和变量">[Google Apps Script 中的类型和变量]</a></p> </li> <li> <p><a href="#常量、变量和在 Google Apps Script 中的字母">[常量、变量和在 Google Apps Script 中的字母]</a></p> </li> <li> <p><a href="#Google Apps Script 中的操作和运算符">[Google Apps Script 中的操作和运算符]</a></p> </li> <li> <p><a href="#Var、Let 和 Const 在 Google Apps Script 中">[Var、Let 和 Const 在 Google Apps Script 中]</a></p> </li> <li> <p><a href="#Google Apps Script 中的控制结构">[Google Apps Script 中的控制结构]</a></p> </li> <li> <p><a href="#_google_apps_script_中的循环">Google Apps Script 中的循环</a></p> </li> <li> <p><a href="#_google_apps_script_中的对象">Google Apps Script 中的对象</a></p> </li> <li> <p>Google Apps Script 中的函数</p> </li> <li> <p>Google Apps Script 中的设置和作用域</p> </li> <li> <p><a href="#Google Apps Script 中的 Rest 和 Spread 运算符">[Google Apps Script 中的 Rest 和 Spread 运算符]</a></p> </li> <li> <p><a href="#在 Google Apps Script 中通过分解进行的分配">[在 Google Apps Script 中通过分解进行的分配]</a></p> </li> <li> <p><a href="#集合和声明式编程在 Google Apps Script 中">[集合和声明式编程在 Google Apps Script 中]</a></p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_介绍">介绍</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script (GAS) 是一种与 Google 的多种服务（如 Google Sheets、Google Docs 和 Google Forms）关联的脚本开发平台。它可以自动化任务、添加自定义功能以及集成 Google 服务。</p> </div> <div class="paragraph"> <p>在这份备忘录中，我们将通过具体示例探索 Google Apps Script 的主要概念。我们将讨论诸如变量、循环、函数等概念，并还有许多其他内容，针对 GAS 的特定情境进行调整。</p> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script_的基本结构">Google Apps Script 的基本结构</h2> <div class="sectionbody"> <div class="paragraph"> <p>首先，让我们检查一下Google Apps脚本的基本结构。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Structure de base en Google Apps Script */ function exempleStructureGAS() { // Votre code ici Logger.log("Hello, Google Apps Script!"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_类型和变量在_google_apps_script_中">类型和变量在 Google Apps Script 中</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script 使用 JavaScript 作为编程语言。数据类型和变量的工作方式与标准 JavaScript 类似。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Types et Variables en Google Apps Script */ function exempleTypesVariablesGAS() { // Votre code ici var nombre = 42; var texte = "Bonjour, Google Apps Script!"; Logger.log(nombre); Logger.log(texte); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_操作和运算符在_google_apps_script_中">操作和运算符在 Google Apps Script 中</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script 中的操作和运算符与 JavaScript 中的相同。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérations et Opérateurs en Google Apps Script */ function exempleOperationsGAS() { // Votre code ici var x = 10; var y = 5; var resultat = x + y; Logger.log(resultat); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_变量let_和_const_在_google_apps_script_中">变量、let 和 const 在 Google Apps Script 中</h2> <div class="sectionbody"> <div class="paragraph"> <p>在 GAS 中，概念的`var`, <code>let</code>, et `const`用于声明变量。然而，理解它们之间的差异及其影响是至关重要的。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Var, Let et Const en Google Apps Script */ function exempleVarLetConstGAS() { // Votre code ici // Utilisation de var var x = 10; if (true) { var x = 20; // La variable x est modifiée globalement } Logger.log(x); // Utilisation de let let y = 30; if (true) { let y = 40; // La variable y est limitée au bloc if } Logger.log(y); // Utilisation de const const z = 50; // z = 60; // Impossible de réassigner une constante Logger.log(z); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script中的控制结构">Google Apps Script中的控制结构</h2> <div class="sectionbody"> <div class="paragraph"> <p>控制结构例如`if`, <code>else</code>, <code>while</code> et `for`用于在 Google Apps Script 中管理执行流程。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Structures de Contrôle en Google Apps Script */ function exempleStructuresControleGAS() { // Votre code ici var condition = true; if (condition) { Logger.log("La condition est vraie."); } else { Logger.log("La condition est fausse."); } var compteur = 0; while (compteur < 5) { Logger.log(compteur); compteur++; } for (var i = 0; i < 3; i++) { Logger.log(i); } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_参数和作用域在_google_apps_script_中">参数和作用域在 Google Apps Script 中</h2> <div class="sectionbody"> <div class="paragraph"> <p>参数和作用域在 GAS 脚本开发中起着至关重要的作用。了解它们的工作原理，以避免出现意外行为。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Paramètres et Scopes en Google Apps Script */ function exempleParametresScopesGAS(parametre) { // Votre code ici var variableGlobale = "Je suis global"; function afficherParametre() { Logger.log(parametre); } afficherParametre(); Logger.log(variableGlobale); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_常量变量和字母在_google_apps_script_中">常量、变量和字母在 Google Apps Script 中</h2> <div class="sectionbody"> <div class="paragraph"> <p>理解…​之间的差别`const`, <code>var</code>, et `let`对于在Google Apps Script中有效使用变量至关重要。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script_中的循环">Google Apps Script 中的循环</h2> <div class="sectionbody"> <div class="paragraph"> <p>循环，例如`for` et <code>while</code>, 是遍历元素和执行重复操作所必需的。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Boucles en Google Apps Script */ function exempleBouclesGAS() { // Votre code ici for (var i = 0; i < 3; i++) { Logger.log(i); } var condition = true; var compteur = 0; while (condition) { Logger.log("Tour de boucle"); compteur++; if (compteur === 3) { condition = false; } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script_中的对象">Google Apps Script 中的对象</h2> <div class="sectionbody"> <div class="paragraph"> <p>对象用于结构化数据。在 GAS 中，许多内置对象有助于与 Google 服务进行交互。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Objets en Google Apps Script */ function exempleObjetsGAS() { // Votre code ici var feuille = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); var cellule = feuille.getRange("A1"); cellule.setValue("Nouvelle valeur"); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_常量变量和字母在_google_apps_script_中_2">常量、变量和字母在 Google Apps Script 中</h2> <div class="sectionbody"> <div class="paragraph"> <p>理解…​之间的差异`const`, <code>var</code>, et `let`这对于在 Google Apps Script 中高效使用变量是必不可少的。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Constantes, Variables, et Lettres en Google Apps Script */ function exempleConstantesVariablesLettresGAS() { // Votre code ici const constante = "Je ne change pas"; Logger.log(constante); var variable = "Je peux changer"; Logger.log(variable); let lettre = "Je peux aussi changer, mais seulement dans mon bloc"; Logger.log(lettre); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script_中的函数">Google Apps Script 中的函数</h2> <div class="sectionbody"> <div class="paragraph"> <p>函数是编程中的基本要素。在 GAS 中，它们可以以多种方式声明和调用。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Fonctions en Google Apps Script */ function exempleFonctionsGAS() { // Votre code ici function additionner(a, b) { return a + b; } var resultat = additionner(2, 3); Logger.log(resultat); // Fonction anonyme var multiplier = function (x, y) { return x * y; }; Logger.log(multiplier(4, 5)); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script_中的剩余参数和展开运算符">Google Apps Script 中的剩余参数和展开运算符</h2> <div class="sectionbody"> <div class="paragraph"> <p>剩余运算符 (<code>…​</code>) 和传播 (<code>…​</code>) 对于以简洁方式操作数组和对象很有用。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérateurs de Repos et de Propagation en Google Apps Script */ function exempleOperateursReposPropagationGAS() { // Votre code ici // Opérateur de repos (...) pour les tableaux var nombres = [1, 2, 3, 4, 5]; var [...copieNombres] = nombres; Logger.log(copieNombres); // Opérateur de propagation (...) pour les objets var objOriginal = { x: 1, y: 2 }; var objClone = { ...objOriginal, z: 3 }; Logger.log(objClone); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_在_google_apps_script_中的解构赋值">在 Google Apps Script 中的解构赋值</h2> <div class="sectionbody"> <div class="paragraph"> <p>解构赋值是一种强大的功能，允许以简洁的方式从对象和数组中提取值。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Affectation par Décomposition en Google Apps Script */ function exempleAffectationDecompositionGAS() { // Votre code ici var coordonnees = [3, 4]; var [x, y] = coordonnees; Logger.log(x); Logger.log(y); var utilisateur = { nom: "John", age: 30 }; var { nom, age } = utilisateur; Logger.log(nom); Logger.log(age); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_google_apps_script_中的集合和声明式编程">Google Apps Script 中的集合和声明式编程</h2> <div class="sectionbody"> <div class="paragraph"> <p>Google Apps Script 支持诸如数组之类的数据结构，以及函数式编程和声明式迭代 (><命令式), 诸如`map`, <code>reduce</code> et <code>forEach</code>。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Collections et Programmation Déclarative en Google Apps Script */ function exempleCollectionsFonctionnelleGAS() { // Votre code ici // Exemple de tableau (collection) var nombres = [1, 2, 3, 4, 5]; // Utilisation de forEach nombres.forEach(function (nombre) { Logger.log(nombre); }); // Utilisation de map var carresNombres = nombres.map(function (nombre) { return nombre * nombre; }); Logger.log(carresNombres); // Utilisation de reduce var somme = nombres.reduce(function (acc, nombre) { return acc + nombre; }, 0); Logger.log(somme); }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_结论">结论</h2> <div class="sectionbody"> <div class="paragraph"> <p>本备忘录通过具体代码示例说明了Google Apps Script的基本概念。利用这些知识，您可以自动化日常任务、自定义文档，并充分发挥Google Apps Script的功能。</p> </div> </div> </div> https://cheroliv.com/blog/2023/0067_formation_express_sur_google_forms_script_post.html Wed, 20 Dec 2023 00:00:00 +0000 blog/2023/0067_formation_express_sur_google_forms_script_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>时长：30分钟</p> </div> </div> </div> <div class="sect1"> <h2 id="_目标">目标</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>理解 Google Apps Script 在 Forms 中的基础 - 学习如何访问脚本编辑器并在触发器中执行指令</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_延迟">延迟</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><strong>Google Form Script 介绍</strong>(5分钟)</p> <div class="ulist"> <ul> <li> <p>快速预览 Google 表单脚本 - 主要功能介绍</p> </li> </ul> </div> </li> <li> <p><strong>创建一个 Google 表单及其关联脚本</strong>(5分钟)</p> <div class="ulist"> <ul> <li> <p>创建一个简单的表单，使用 Google Forms - 关联脚本编辑器介绍</p> </li> </ul> </div> </li> <li> <p><strong>�执行一条指令</strong>(10 分钟)</p> <div class="ulist"> <ul> <li> <p>配置 "on start" 触发器 - "on submit" 触发器的配置 - 编写脚本以执行指令 - 快速测试以验证日志中的正常运行</p> </li> </ul> </div> </li> <li> <p><strong>结果分析与最佳实践</strong>(10分钟)</p> <div class="ulist"> <ul> <li> <p>验证指令执行结果 - 讨论脚本示例以及自动化如何可以节省时间</p> </li> </ul> </div> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="_先决条件">先决条件</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>拥有一个Google账户并能够访问Google表单和Google表格</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_材料">材料</h2> <div class="sectionbody"> <div class="ulist"> <ul> <li> <p>带有网页浏览器和互联网连接的计算机</p> </li> </ul> </div> </div> </div> <div class="sect1"> <h2 id="_备注">备注</h2> <div class="sectionbody"> <div class="paragraph"> <p>此速成培训提供了使用 Google Form Script 进行自动化的快速介绍。 为了更深入的理解，建议进行更长时间的培训。</p> </div> </div> </div> <div class="sect1"> <h2 id="_1_google_表单脚本简介">1 - Google 表单脚本简介</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_slide_1_google_表单脚本快速概览">Slide 1: Google 表单脚本快速概览</h3> <div class="ulist"> <ul> <li> <p>Google Form Script 是一个集成到 Google Forms 中的脚本平台。 - 它允许添加自定义功能并自动执行任务。</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_slide_2_主要功能介绍">Slide 2: 主要功能介绍</h3> <div class="paragraph"> <p>脚本编辑器：用于编写 Google Apps Script 脚本的内置脚本编辑器。 - 触发器：诸如 'on submit' 之类的事件会激活脚本的执行。</p> </div> </div> <div class="sect2"> <h3 id="_幻灯片_3使用_google_表单脚本的优势">幻�灯片 3：使用 Google 表单脚本的优势</h3> <div class="paragraph"> <p>自定义：创建具有独特功能的自定义表单。 - 自动化：根据表单响应自动执行操作。 - 集成：将脚本与其他 Google 服务集成，以获得更丰富的体验。</p> </div> </div> <div class="sect2"> <h3 id="_演讲者备注">演讲者备注:</h3> <div class="paragraph"> <p>这些功能提供了可观的潜力，用于自定义和自动化表单。 此培训的后续部分将更深入地探讨特定脚本和自动化的创建。</p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr" class="bare">https://developers.google.com/apps-script/add-ons/editors/forms?hl=fr</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms?hl=fr" class="bare">https://developers.google.com/apps-script/reference/forms?hl=fr</a></p> </div> <div class="paragraph"> <p><a href="https://developers.google.com/apps-script/reference/forms/form-app?hl=fr" class="bare">https://developers.google.com/apps-script/reference/forms/form-app?hl=fr</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_创建一个google表单及其关联脚本5_分钟">创建一个Google表单及其关联脚本（5 分钟）</h2> <div class="sectionbody"> </div> </div> https://cheroliv.com/blog/2023/0066_memo_python_post.html Sun, 19 Nov 2023 00:00:00 +0000 blog/2023/0066_memo_python_post.html <div class="sect1"> <h2 id="_在_windows_上安装_python">在 Windows 上安装 Python</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://ninite.com/pythonx3/">Windows 上的 Python</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/starting/install3/win.html" class="bare">https://python-docs.readthedocs.io/en/latest/starting/install3/win.html</a></p> </div> <div class="paragraph"> <p><a href="https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref" class="bare">https://python-docs.readthedocs.io/en/latest/dev/virtualenvs.html#virtualenvironments-ref</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_运行_python">运行 python</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">问题：Python venv</div> <p>参考 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">cd mon_projet python -m venv mon_venv source mon_venv/bin/activate # Sur windows mon_venv\Scripts\activate deactivate</code></pre> </div> </div> <div class="sect2"> <h3 id="_安装需求">安装需求</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">pip install -r requirements.txt</code></pre> </div> </div> </div> </div> </div> <div class="sect1"> <h2 id="_入门">入门</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://python.doctor/page-apprendre-programmation-orientee-objet-poo-classes-python-cours-debutants">Python面向对象编程</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_python_中的_gof_设计模式">Python 中的 GoF 设计模式</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://github.com/whikwon/python-patterns/">实现 1</a></p> </div> <div class="paragraph"> <p><a href="https://github.com/Sean-Bradley/Design-Patterns-In-Python">实现 2</a></p> </div> <div class="paragraph"> <p><a href="https://sbcode.net/python/">完整的书</a></p> </div> <div class="paragraph"> <p>GoF 的设计模式是一组在《Design Patterns: Elements of Reusable Object-Oriented Software》一书中描述的23种设计模式。</p> </div> <table class="tableblock frame-all grid-all stretch"> <caption class="title">Table 1. 以下是 GoF 设计模式的列表。</caption> <colgroup> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0833%;"> <col style="width: 2.0849%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">名称</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�描述</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>工厂方法</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">创建对象而无需指定要实例化的确切类。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>�抽象工厂</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">创建相关或依赖对象的系列，而无需指定其具体类。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>建造者</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">将复杂对象的构造与其表示分离，以便相同的构造过程可以创建不同的表示。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>原型</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">通过复制现有的原型来创建新对象。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>单例</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">将类的实例化限制为仅一个对象。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>�适配器</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">将一个类的接口转换为客户端所期望的另一个接口。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>桥</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">将抽象与其实现解耦，使两者能够独立变化。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>组合</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">将对象组合成树形结构以表示部分-整体层次结构。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>装饰器</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">动态地向对象添加额外职责。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>立面</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">为子系统中的一组接口提供统一的接口。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>享元</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">降低创建和使用轻量级对象的成本。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>代理</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">为另一个对象提供替代或占位符，以控制对该对象的访问。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>责任链</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�允许多个对象处理请求。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>命令</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">将请求封装在一个对象中，从而可以使用不同的请求、队列或日志来配置客户端，并支持可撤销的操作。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>解释器</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">给出一种语言的语法表示，并使用该表示来解释该语言中的句子。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>迭代器</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">提供一种按顺序遍历聚合对象元素的方法，而不暴露其底层表示。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>调解人</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">允许通过使对象仅通过一个中介对象进行通信来减少对象之间的复杂依赖关系。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>纪念</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">提供将对象恢复到其先前状态的能力 （且不破坏封装）。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>观察者</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">定义对象之间的一对多依赖关系，使得当一个对象的状态改变时，所有依赖它的对象都会被通知并自动更新。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>状态</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�允许对象在其内部状态发生变化时改变其行为。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>策略</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">定义一族算法，封装每个算法，使其可以互换。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>模板方法</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">在方法中定义算法的骨架，并将某些步骤推迟到子类。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>�访客</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�允许定义在对象结构上执行的新操作，而无需更改其操作对象的类。</p></td> </tr> </tbody> </table> </div> </div> <div class="sect1"> <h2 id="_函数式编程">�函数式编程</h2> <div class="sectionbody"> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 16.6666%;"> <col style="width: 27.7777%;"> <col style="width: 55.5557%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">图书馆</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�描述</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/jasondelaat/pymonad" class="bare">https://github.com/jasondelaat/pymonad</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyMonad 是一种在 Python 中基于 Haskell 和 F# 等编程语言的单子数据结构的实现，并提供了函数式编程中最常用的单子类型的实现。https://www.miguelfarrajota.com/2021/06/monads-in-python-with-pymonad/[文章]</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">PyFunctional</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/EntilZha/PyFunctional/" class="bare">https://github.com/EntilZha/PyFunctional/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">PyFunctional 是一个用于函数式编程的 Python 库，它提供了用于处理纯函数和可迭代对象的工具。</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://toolz.readthedocs.io/en/latest/" class="bare">https://toolz.readthedocs.io/en/latest/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Toolz 是一个用于函数式编程的 Python 库，提供了用于处理纯函数和可迭代对象的工具。</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://github.com/kachayev/fn.py" class="bare">https://github.com/kachayev/fn.py</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Fn.py 是一个用于函数式编程的 Python 库，提供了用于处理纯函数和可迭代对象的工具。</p></td> </tr> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">椰子</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="https://coconut-lang.org/" class="bare">https://coconut-lang.org/</a></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Coconut 为 Python 添加了多种功能，用于函数式编程，包括模式匹配。https://stackoverflow.com/questions/11909681/are-there-pattern-matching-functions-in-python-like-this[对话 sof]</p></td> </tr> </tbody> </table> <div class="sect2"> <h3 id="_副作用">副作用</h3> </div> <div class="sect2"> <h3 id="_循环">�循环</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-python" data-lang="python"># impérative way result = [] for i in inputs: x = f(g(i)) result.append(x) # idiomatic way result = map(comp(f,g), inputs)</code></pre> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2023/0065_training_web_dev_post.html Thu, 24 Aug 2023 00:00:00 +0000 blog/2023/0065_training_web_dev_post.html https://cheroliv.com/blog/2023/0064_training_trading_card_games_post.html Mon, 21 Aug 2023 00:00:00 +0000 blog/2023/0064_training_trading_card_games_post.html https://cheroliv.com/blog/2023/0063_memo_ts_post.html Sat, 19 Aug 2023 00:00:00 +0000 blog/2023/0063_memo_ts_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>github 仓库:https://github.com/cheroliv/ts-codebase[ts-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_ts"><span class="underline">Intro typescript</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#ts_types">TypeScript中的类型</a></p> </li> <li> <p><a href="#功能">[功能]</a></p> </li> <li> <p><a href="#data_struct">数据结构</a></p> </li> <li> <p><a href="#enums_tuples">枚举和元组</a></p> </li> <li> <p><a href="#void_never">[void_never]</a></p> </li> <li> <p><a href="#class_interface">类和接口</a></p> </li> <li> <p><a href="#tsconfig">tsconfig.json 文件</a></p> </li> <li> <p><a href="#modules">模块</a></p> </li> <li> <p><a href="#承诺">[承诺]</a></p> </li> <li> <p>异步-等待</p> </li> <li> <p>通用</p> </li> </ol> </div> <div class="paragraph"> <p>index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> <title>Document</title> </head> <body> Intro typescript <script src="01_types.js"></script> <script src="02_data_structure.js"></script> <script src="03_enums_tuples.js"></script> </body> </html></code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="ts_types">TypeScript中的类型</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Les types en typescript */ //quand le type n'est pas defini des le debut, // alors il est réassignable // c'est le type Any qui est attribué par défaut let my_var; my_var = "username"; console.assert(my_var === "username"); my_var = 11; console.assert(my_var === 11); my_var = true; console.assert(my_var === true); let age = 1; console.assert(age === 1); age = 2; // age="trois" c'est impossible // car l'inference de type a attribué le type number console.assert(age === 2); // Déclaration explicite de type let pi: Number = 3.14; console.assert(typeof pi === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="fonctions">函数</h2> <div class="sectionbody"> <div class="paragraph"> <p>函数是可重用的代码块。</p> </div> <div class="paragraph"> <p>示例评级：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const add = (a: number, b: number): number => a + b;</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="data_struct">数据结构</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_data_structure.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/*** * Structure de données: * Avec le type any on peut changer * le type de la variable à tout instruction * Lorsque l'on fixe le type * alors il n'est plus possible de le changer * lors d'une assignation */ // Arrays let buddies: any[] = [ "cheroliv", "imrandeh", "issoudeh", "soumi92" ] console.assert(buddies[0] === "cheroliv"); console.assert(buddies[1] === "imrandeh"); console.assert(buddies[2] === "issoudeh"); console.assert(buddies[3] === "soumi92"); // Déclaré en type any, l'inference de type // a bien réaligné en type string console.assert(typeof buddies[0] === "string"); console.assert(typeof buddies[1] === "string"); console.assert(typeof buddies[2] === "string"); console.assert(typeof buddies[3] === "string"); let writers: (String | String | String | Number)[][] = [ ["Chrétien", "de Troyes", "fr", 12], ["François", "Rabelais", "fr", 16], ["René", "Descartes", "fr", 17], ["Jean-Jacques", "Rousseau", "fr", 18], ["Georg", "Hegel", "de", 19], ["Karl", "Marx", "de", 19], ["Friedrich", "Engels", "de", 19], ["Victor", "Hugo", "fr", 19], ["Paul", "Verlaine", "fr", 19], ["Arthur", "Rimbaud", "fr", 19], ["Gérard", "de Nerval", "fr", 19], ["Georg", "Lukacs", "hu", 20], ["Franz", "Kafka", "hu", 20], ["Antonio", "Gramsci", "it", 20], ["Domenico","Losurdo","it",20], ]; // console.table(writers); // Objects let author: { first_name: String, last_name: String, lang: String, century: Number } = { // slice(-1) renvoie le dernier élèment first_name: writers.slice(-1)[0][0] as String, last_name: writers.slice(-1)[0][1] as String, lang: writers.slice(-1)[0][2] as String, century: writers.slice(-1)[0][3] as Number, } // assertion sur la valeur en accés par encapsulation(dot) console.assert(author.first_name === "Antonio") console.assert(author.last_name === "Gramsci") console.assert(author.lang === "it") console.assert(author.century === 20); // assertion sur le type en accès par index console.assert(typeof author["first_name"] === "string") console.assert(typeof author["last_name"] === "string") console.assert(typeof author["lang"] === "string") console.assert(typeof author["century"] === "number");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="enums_tuples">枚举和元组</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_enums_tuples.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Enums et Tuples * * Enum: il existe les enums numérique * et les enums chaine de caracteres. * * Tuple: similaire aux arrays mais ne peut * contenir qu'une valeur de type spécifié. * */ //Enum numérique // l'index par de debut défaut est 0 // ici on le place a 1 enum Week { Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday = 5, Saturday = 6, Sunday = 7, }; console.assert(Week.Monday == 1); console.assert(Week.Tuesday == 2); console.assert(Week.Wednesday == 3); console.assert(Week.Thursday == 4); console.assert(Week.Friday == 5); console.assert(Week.Saturday == 6); console.assert(Week.Sunday == 7); console.assert(Week[1] === "Monday"); console.assert(Week[2] === "Tuesday"); console.assert(Week[3] === "Wednesday"); console.assert(Week[4] === "Thursday"); console.assert(Week[5] === "Friday"); console.assert(Week[6] === "Saturday"); console.assert(Week[7] === "Sunday"); let motd_arr_fr: String[] = [ "Associé à la Lune", "Du dieu Tiw, associé à Mars", "Du dieu germanique Odin", "Du dieu germanique du tonnerre Thor", "De la déesse germanique Frigga associée à Vénus", "Associé à Saturne", "Associé au Soleil", ]; let motd_arr_en: String[] = [ "associated with the Moon", "from the god Tiw, associated with Mars", "from Germanic god Odin", "from Germanic god of thunder Thor", "from Germanic goddess Frigga associated with Venus", "associated with Saturn", "associated with the Sun", ]; // Un tuple (triple) let monday_triple_fr: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_fr[0], ]; console.assert(monday_triple_fr[0] === 1); console.assert(monday_triple_fr[1] === "Monday"); console.assert(monday_triple_fr[2] === "Associé à la Lune"); let monday_triple_en: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_arr_en[0], ]; console.assert(monday_triple_en[0] === 1); console.assert(monday_triple_en[1] === "Monday"); console.assert(monday_triple_en[2] === "associated with the Moon"); // On se fait un type pour ajouter le nom de la langue type Meaning_of_the_day = { lang: String, meaning: (Week | String)[][], }; //fonction d'affichage du type Meaning_of_the_day const display_motd = (motd: Meaning_of_the_day) => { motd.meaning.forEach(day => console.table(`${Week[day[0] as Week]}: ${day[1]}.(${motd.lang})`) ) }; //fonction d'assertion sur le type Meaning_of_the_day // afin de verifier la concordance du contenu avec // motd_arr_#lang# const test_motd = ( motd: Meaning_of_the_day, motd_arr: String[] ) => { console.assert(motd.lang.length === 2) for (const [i, value] of motd.meaning.entries()) { console.assert(value[1] === motd_arr[i]); } }; let motd_fr: Meaning_of_the_day = { lang: "fr", meaning: [ [Week.Monday, motd_arr_fr[0]], [Week.Tuesday, motd_arr_fr[1]], [Week.Wednesday, motd_arr_fr[2]], [Week.Thursday, motd_arr_fr[3]], [Week.Friday, motd_arr_fr[4]], [Week.Saturday, motd_arr_fr[5]], [Week.Sunday, motd_arr_fr[6]], ], } console.log("---------"); console.log("display_motd(motd_fr):"); display_motd(motd_fr); test_motd(motd_fr, motd_arr_fr) let motd_en: Meaning_of_the_day = { lang: "en", meaning: [ [Week.Monday, motd_arr_en[0]], [Week.Tuesday, motd_arr_en[1]], [Week.Wednesday, motd_arr_en[2]], [Week.Thursday, motd_arr_en[3]], [Week.Friday, motd_arr_en[4]], [Week.Saturday, motd_arr_en[5]], [Week.Sunday, motd_arr_en[6]], ], } console.log("---------"); console.log("display_motd(motd_en):"); display_motd(motd_en); console.log("---------"); test_motd(motd_en, motd_arr_en); // Un tuple (triple) utilisant le type // Meaning_of_the_day pour peupler le meaning let motd_triple: [ Number, String, String ] = [ Week.Monday, Week[Week.Monday], motd_fr.meaning[0][1] as String ]; console.assert(motd_triple[0] === 1); console.assert(motd_triple[1] === "Monday"); console.assert(motd_triple[2] === "Associé à la Lune");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="_空虚与永不">空虚与永不<a id="void_never"></a></h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">// Le type void est l'opposé du type any // c'est l'absence de type. function verify_writers_length(): void { console.assert(writers.length > 0); } verify_writers_length(); const verify_writers_length_arrow = (): void => console.assert(writers.length > 0); verify_writers_length_arrow(); //Type of et never let value = 30; console.assert(typeof value === "number"); //never: qqchs qui n'arrive jamais function foo(x: String | Number): Boolean { if (typeof x === "string") { return true; } else if (typeof x === "number") { return false; } return fail("Error!") } function fail(message: String): never { throw new Error(message as string); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="class_interface">类和接口</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_void_never_types.ts</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">/** * Les classes: * members, * visibility, * nommage, * accesseurs * scope identifier: static,private,protected * * convention de nommage : * Les membres private sont préfixés avec un _ * */ class Member { username: String = ""; email: String = ""; private _password: String = ""; readonly signup_date: Date = new Date(Date.now()); constructor(username: String, email: String) { this.username = username; this.email = email; } get password(): String { return this._password; } set password(new_password: String) { this._password = new_password; } /** * Une fonction static qui initilise un member, * à partir d'un author */ static fromAuthor(author: { first_name: String, last_name: String, lang: String, century: Number }): Member { return new Member( `${author.first_name}.${author.last_name}`, `${author.first_name}.${author.last_name}@acme.com`, ); } }; let domenico = Member.fromAuthor(author); domenico.password = "test"; console.assert(domenico.email === "Domenico.Losurdo@acme.com"); console.assert(domenico.password === "test"); // Héritage enum Forms { Undefined = 0, Polygones = 1, Circle = 2, Straight = 3, Segment = 4, }; class Form { type: Forms = Forms.Undefined; }; class Rectangle extends Form { h: Number = 0; w: Number = 0; }; class Square extends Rectangle { side: Number = 0; }; /** * Interface donne un contrat à un type. * Les interfaces permettent de définir la structure d'un objet. */ interface IPerson { username: String; email: String; readonly signup_date: Date; } const user1: IPerson = { username: Member.fromAuthor(author)["username"], email: Member.fromAuthor(author)["email"], signup_date: Member.fromAuthor(author)["signup_date"], }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="tsconfig">tsconfig.json 文件</h2> <div class="sectionbody"> <div class="paragraph"> <p>tsconfig.json</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-json" data-lang="json">{ /* Visit https://aka.ms/tsconfig to read more about this file */ "compileOnSave": true, "compilerOptions": { "target": "es2016", "module": "CommonJS", "noEmitOnError": true, "strict": true, "noImplicitAny": true, "esModuleInterop": true } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="modules">模块</h2> <div class="sectionbody"> <div class="paragraph"> <p>模块允许将代码组织成多个文件。</p> </div> <div class="paragraph"> <p>示例评分 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">// Dans un fichier math.ts export const add = (a: number, b: number): number => a + b; // Dans un autre fichier import { add } from './math'; let result = add(2, 3);</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="promesses">承诺</h2> <div class="sectionbody"> <div class="paragraph"> <p>承诺用于执行异步操作。</p> </div> <div class="paragraph"> <p>示例评级：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const promise = new Promise<string>((resolve) => { // Code asynchrone ici resolve("Succès"); }); promise.then((result) => { console.log(result); });</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="async-await">async/await</h2> <div class="sectionbody"> <div class="paragraph"> <p>async/await 简化了对 Promise 的处理。</p> </div> <div class="paragraph"> <p>示例评分 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const fetchData = async (): Promise<void> => { const result = await someAsyncFunction(); console.log(result); };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_ts"><span class="underline">Intro typescript</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="generiques">�泛型</h2> <div class="sectionbody"> <div class="paragraph"> <p>泛型允许创建具有动态类型的可重用组件。</p> </div> <div class="paragraph"> <p>示例评分：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-typescript" data-lang="typescript">const identity = <T>(arg: T): T => arg; const output = identity<string>("hello"); console.log(output);</code></pre> </div> </div> </div> </div> https://cheroliv.com/blog/2023/0062_memo_css_post.html Mon, 14 Aug 2023 00:00:00 +0000 blog/2023/0062_memo_css_post.html <div class="sect1"> <h2 id="toc">目录</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#good_links">良好链接</a></p> </li> <li> <p><a href="#repo">存储库和代码示例</a></p> </li> <li> <p><a href="#目录开始">[目录开始]</a></p> </li> </ol> </div> <div class="sect2"> <h3 id="good_links">良好链接</h3> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> <div class="sect2"> <h3 id="repo">存储库和代码示例</h3> <div class="paragraph"> <p>GitHub 仓库：https://github.com/cheroliv/css-codebase[css-codebase, window = "_blank]</p> </div> </div> <div class="sect2"> <h3 id="toc_début"><span class="underline">开始 CSS</span></h3> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#开始_intro">[开始_intro]</a></p> </li> <li> <p>开始</p> </li> <li> <p><a href="#开始_背景">[开始_背景]</a></p> </li> <li> <p>开始_盒子</p> </li> <li> <p><a href="#开始_flexbox">[开始_flexbox]</a></p> </li> <li> <p><a href="#开始_网格">[开始_网格]</a></p> </li> <li> <p><a href="#开始_绝对_位置">[开始_绝对_位置]</a></p> </li> <li> <p><a href="#开始响应式">[开始响应式]</a></p> </li> <li> <p>开始结论</p> </li> </ol> </div> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="开始介绍">介绍 & 设置</h2> <div class="sectionbody"> <div class="paragraph"> <p>基于此视频的介绍：</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/iSWjmVcfQGg?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> <div class="paragraph"> <p>GitHub 仓库:https://github.com/cheroliv/css-codebase/début_css/[开始 css, window = "_blank]</p> </div> <div class="paragraph"> <p>备忘录来源：<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message" ></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p>将 style.css 文件链接到 HTML 页面：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"></head> <link rel="stylesheet" href="style.css" /> </head></code></pre> </div> </div> <div class="paragraph"> <p><a href="#目录开始">[目录开始]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_texts">这些文本</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/* import remote de font sur l'ensemble de la feuille*/ @import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); /* import local de font */ @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* body est le parent de toutes les balises, qu'il contient, donc je le déclare avant, pour la logique de précédence de parent */ body { /* si DMSerif n'est pas trouvé alors il se rabat sur Verdana*/ font-family: "DMSerif", Verdana; } /* va styliser toutes les balises h1, celles de body sont surchargés, par la déclaration présente */ h1 { text-transform: uppercase; /* espacement entre les lettres en pixel*/ letter-spacing: 3px; /* alignement du texte*/ text-align: center; /* Les tailles de polices doivent être en REM (rem = root em). Le REM se base pas sur l'élément parent pour obtenir sa taille mais sur l'élément racine. Ainsi 1rem prendra sa valeur de la font-size de votre document (body ou html).*/ font-size: 2.5rem; /* ombrage du texte */ text-shadow: 3px /* offset-x */ 3px /* offset-y */ 8px /* blur-radius */ #00000042/* color */; /* couleur du texte */ color: #ab0ef4; /*attibuer les polices(font): liste, ordonnée par priorité, de polices à utiliser pour mettre en forme le texte de l'élément ciblé.*/ font-family: "Oswald", sans-serif; /* surligner le text*/ text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#目录开始">[目录开始]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_background">背景</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; /* 100VH = 100% de la taille de l'écran (viewport height) min afin de ne pas bloquer la possibilité d'avoir un plus grand */ min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_开始">[toc_开始]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_boxes">盒子（boxes）</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } /* *: létoile donne du style a tous les éléments. Ensuite remettre un à un les parametres par defaut afin d'eviter les stylisation inattendu.*/ * { /* surcharge de base tous les elements à padding 0*/ margin: 0; /* surcharge de base tous les elements à padding 0*/ padding: 0; } body { font-family: "DMSerif", Verdana; /* image comme background*/ background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; /* quelque soit la taille de l'écran, la boite fait toujours 90% de la taille de la page, les 10% restant sont une marge à droite, pour avoir 5% de chaque coté on ajoute une margin, tel que [0, auto]*/ width: 90%; /* haut bas prend 0, et gauche droite prend auto(center cad meme de chaque cotés)*/ margin: 0 auto; /* on ajoute des bords a notre boite*/ border: 2px solid rgb(0, 140, 255); /* on arrondis les coins de la boite*/ border-radius: 20px 20px 0 0; /* ombrage sur la boite*/ box-shadow: 0px 0px 20px 4px #81cfc6; /* marge interrieure de la boite sur tous les cotés*/ padding: 15px; } h2 { /* afin de recuprer le comportement par defaut qui a ete surchargé par l'operateur étoile*/ margin: 0; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_début"><span class="underline">开始 CSS</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_flexbox">Flexbox</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } /* le point permet d'acceder à la classe d'un composant*/ .flexbox { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } /* FLEXBOX */ /* Sert à répartir équitablement des éléments sur la page */ .flexbox ul { padding: 0; /* aligne les éléments enfants de ul(les li)*/ display: flex; /* reparti convenablement(équitablement les li sur la page) */ justify-content: space-around; } /* ce style concerne les li de la classe, flexbox des balises qui y font referencent*/ .flexbox li { /* suprime les boules des éléments de la list li*/ list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; /* Centrer un unique élément verticalement et horizontalement */ display: flex; justify-content: center; align-items: center; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_开始">[toc_开始]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="开始_grid">网格</h2> <div class="sectionbody"> <div class="paragraph"> <p>为了以比使用flexbox更复杂的方式分布元素，例如使用网格系统。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } /* GRID */ .grid-container { display: grid; /* séparatuion de la grille en deux(à ses deux enfants), avec à gauche 30% pour l'image et à droite 70% pour le formulaire*/ grid-template-columns: 30% 70%; } /* sizing de l'image css-logo contenu dans la classe grid qui est dans le parent grid-container*/ .grid img { /* l'image remplt 80% de part de grille*/ width: 80%; margin: 20px auto; display: block; } form { display: grid; /* deux colonnes de chacune 1 fraction*/ grid-template-columns: 1fr 1fr; /* trois rangés de chacune 1 fraction*/ grid-template-rows: 1fr 1fr 1fr; /* structuration sous forme de template de notre repartition des composants enfants de la forme*/ grid-template-areas: "i1 i2"/* i1: input1, i2:input2*/ "ta ta"/*ta: text area */ "vi bt"/*vi:, bt: bouton */; } /* on donne du style sur deux éléments en meme temps en les listant avant les parentheses*/ input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } /* donner du style uniquement la textearea*/ textarea { /* renseigner le nommage pour le grid template area*/ grid-area: ta; height: 40px; /* empeche le cassage du style de la page en empechant le resizing de la textarea du formulaire*/ resize: none; } /* pour pointer un id d'élément html on utilise la notation préfixe # */ #btn-submit { /* renseigner le nommage*/ grid-area: bt; /* change le le symbole de curseur souris quand il survole sur le bouton*/ cursor: pointer; background: cyan; transition: 0.2s; } /* au survole(hover) de la souris le bouton change de comportement*/ #btn-submit:hover { background: darkblue; /* couleur de text du bouton devient blanc*/ color: white; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#目录开始">[目录开始]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_abs_pos">绝对定位</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } /* ABSOLUTE */ /* Sans élément en Relative, de base, l'élément en absolute l'est par rapport au Body */ /* Il faut mettre une position relative au parent pour contraindre l'élément en absolute dans ses frontières */ .absolute { /* position relative par rapport à son parent, donc contenu dans les frontieres de son parents*/ position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: /*traslate de 50% de la taille du cercle, pour etre centré par rapport au centre du cercle, plutot que sur son bord gauche par défaut.*/ translateX(-50%); top: 100px; }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_开始">[toc_开始]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="début_responsive">响应式</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">@import url("https://fonts.googleapis.com/css2?family=Oswald:wght@500&display=swap"); @font-face { font-family: "DMSerif"; src: url(./assets/fonts/DMSerifDisplay-Regular.ttf); } body { font-family: "DMSerif", Verdana; background: url(./assets/img/bg.jpg) center/cover; min-height: 100vh; } h1 { text-transform: uppercase; letter-spacing: 3px; text-align: center; /* pour etre plus responsive on peut passer la taille en vw(view port width) pour qu'elle s'adapte à la taille de l'ecran*/ font-size: 2.5rem; text-shadow: 3px 3px 8px #00000042; color: #ab0ef4; font-family: "Oswald", sans-serif; text-decoration: underline; } main { background: rgba(245, 245, 245, 0.9); min-height: 500px; width: 90%; margin: 0 auto; border: 2px solid rgb(0, 140, 255); border-radius: 20px 20px 0 0; box-shadow: 0px 0px 20px 4px #81cfc6; padding: 15px; } h2 { margin: 0; } .flexbox, .grid, .absolute { border: 2px solid skyblue; border-radius: 10px; padding: 10px; margin-top: 20px; min-height: 150px; } .flexbox ul { padding: 0; display: flex; justify-content: space-around; } .flexbox li { list-style: none; height: 160px; width: 160px; margin: 10px; background: turquoise; display: flex; justify-content: center; align-items: center; } .grid-container { display: grid; grid-template-columns: 30% 70%; } .grid img { width: 80%; margin: 20px auto; /* permet en media query de la centrer en petit écran*/ display: block; } form { display: grid; grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr; grid-template-areas: "i1 i2" "ta ta" "vi bt"; } input, textarea { margin: 5px; border: 1px solid darkblue; padding: 10px; font-size: 1.1rem; font-family: "DMSerif"; border-radius: 5px; } textarea { grid-area: ta; height: 40px; resize: none; } #btn-submit { grid-area: bt; cursor: pointer; background: cyan; transition: 0.2s; } #btn-submit:hover { background: darkblue; color: white; } .absolute { position: relative; } #circle1 { height: 80px; width: 80px; background: skyblue; position: absolute; border-radius: 150px; top: -20px; right: -20px; } #circle2 { height: 40px; width: 40px; border-radius: 150px; background: teal; position: absolute; left: 50%; transform: translateX(-50%); top: 100px; } /* RESPONSIVE: a partir des tailles d'ecran permet de surcharger les reglages definis plus haut */ @media screen and (max-width: 900px) { .grid-container { display: block; } .grid-container img { width: 40%; } } @media screen and (max-width: 610px) { .flexbox ul { flex-direction: column; align-items: center; } form { grid-template-columns: 1fr; grid-template-rows: 1fr; grid-template-areas: "i1" "i2" "ta" "bt"; } input, textarea { font-size: 0.8rem; } }</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Cours CSS</title> <link rel="stylesheet" href="style.css" /> </head> <body> <header> <h1>Les bases de CSS</h1> </header> <main> <div class="flexbox"> <h2>Flexbox</h2> <ul> <li>boite 1</li> <li>boite 2</li> <li>boite 3</li> </ul> </div> <div class="grid"> <h2>Grid</h2> <div class="grid-container"> <img src="./assets/img/css-logo.png" alt="logo css" /> <form action=""> <input type="text" id="firstname" placeholder="Prénom" /> <input type="text" id="surname" placeholder="Nom" /> <textarea cols="30" rows="10" placeholder="Ici votre message"></textarea> <input type="submit" value="Valider" id="btn-submit" /> </form> </div> </div> <div class="absolute"> <h2>Absolute</h2> <span id="circle1"></span> <span id="circle2"></span> </div> </main> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_开始">[toc_开始]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="开头_结论">调试 & 结论</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-css" data-lang="css">/* all elements: supprime les comportements par défaut*/ * { /* les marges à zéro*/ margin: 0; /* les parge internes(padding) à zéro*/ padding: 0; /* tous les bords avec un cadre rouge de 2px. qui est ou et qui fait quoi...*/ border: 2px solid red; }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_开始">[toc_开始]</a></p> </div> </div> </div> https://cheroliv.com/blog/2023/0061_memo_html_post.html Sun, 13 Aug 2023 00:00:00 +0000 blog/2023/0061_memo_html_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_好的链接">好的链接</a></li> <li><a href="#_仓库和代码示例">�仓库和代码示例</a></li> </ul> </div> <div class="sect1"> <h2 id="_好的链接">好的链接</h2> <div class="sectionbody"> <div class="ulist"> <div class="title">html</div> <ul> <li> <p><a href="https://htmlcheatsheet.com">htmlcheatsheet.com</a>: HTML 速查表</p> </li> </ul> </div> <div class="ulist"> <div class="title">字体</div> <ul> <li> <p><a href="https://fontawesome.com">fontawesome.com，窗口 = "_blank</a>图标库</p> </li> <li> <p><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target=""_blank">toptal.com/designers/htmlarrows/symbols</a>: 原生图标在HTML中</p> </li> </ul> </div> <div class="ulist"> <div class="title">特殊字符和转义</div> <ul> <li> <p><a href="https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/" class="bare">https://www.sonarsource.com/blog/encoding-differentials-why-charset-matters/</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/3614344/13104550" class="bare">https://stackoverflow.com/a/3614344/13104550</a></p> </li> <li> <p><a href="https://html.spec.whatwg.org/multipage/named-characters.html" class="bare">https://html.spec.whatwg.org/multipage/named-characters.html</a></p> </li> </ul> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> <div class="sect1"> <h2 id="_仓库和代码示例">�仓库和代码示例</h2> <div class="sectionbody"> <div class="paragraph"> <p>GitHub 仓库:https://github.com/cheroliv/html-codebase[html-codebase, 窗口 = "_blank]</p> </div> <div class="paragraph"> <p>备忘录来源:<br> index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlightjs highlight"><code class="language-html hljs" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <!-- Le titre de la page --> <title>Cours HTML</title> <!-- Icone de l'onglet --> <link rel="shortcut icon" href="html-logo.png" /> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.2/css/all.css" /> </head> <body> <header> <h1>Texte - Titre H1</h1> <p> <em>em pour mettre en italique</em>, <strong>strong pour mettre en gras</strong> <span>L'élement en span ne revient pas à la ligne</span>. </p> <p> Lorem ipsum dolor sit amet consectetur adipisicing elit. Exercitationem cumque ratione veniam officiis nulla a debitis at facilis sed dignissimos. </p> </header> <section> <div> <h2>Photo - Titre H2</h2> <img src="./img-1.jpg" alt="image-arbre" height="200" /> </div> <div> <h3>Liste - Titre H3</h3> <ul> <li>UL = unordered list</li> <li>UL = unordered list</li> <li>UL = unordered list</li> </ul> <ol> <li>OL = ordered list</li> <li>OL = ordered list</li> <li>OL = ordered list</li> </ol> </div> <div> <h4>Tableaux - Titre H4</h4> <table border="4" cellpadding="10" cellspacing="4" style="text-align: center"> <thead> <tr> <th>Col 1</th> <th>Col 2</th> <th>Col 3</th> </tr> </thead> <tbody> <tr> <td rowspan="2">Row 1 Cell 1</td> <td>Row 1 Cell 2</td> <td>Row 1 Cell 3</td> </tr> <tr> <td>Row 2 Cell 2</td> <td>Row 2 Cell 3</td> </tr> <tr> <td colspan="3">Row 3 Cell 1</td> </tr> </tbody> </table> </div> <div> <h5><span>♖</span> Liens - Titre H5</h5> <a href="https://htmlcheatsheet.com/" target="_blank">HTML Cheatsheet</a> <br /> <a href="https://www.toptal.com/designers/htmlarrows/symbols/" target="_blank">Icones natifs en HTML</a> </div> <div> <h6><i class="fas fa-video"></i> Vidéo - Titre H6</h6> <video src="video.mp4" height="150" autoplay loop muted></video> </div> </section> <br /> <!-- Formulaires en HTML --> <section> <h2>Formulaire</h2> <form action="/action.php" method="post"> <label for="name">Nom</label> <input id="name" type="text" placeholder="Entrez votre nom" /><br /> <label for="number">Entrez votre age</label> <input type="number" id="number-age" value="15" oninput="document.getElementById('range-age').value=this.value"> <input type="range" id="range-age" min="0" max="100" oninput="document.getElementById('number-age').value=this.value"><br /> <!-- Input select --> <label for="gender">Genre</label> <select id="gender"> <option selected="selected" value="Homme">Homme</option> <option value="Femme">Femme</option> </select><br /> <!-- Input radio --> <div> <input type="radio" name="type" id="human" checked /> <label for="human">Humain</label> <input type="radio" name="type" id="dog" /> <label for="dog">Chien</label> <input type="radio" name="type" id="cat" /> <label for="cat">Chat</label> </div> <textarea cols="20" rows="5" placeholder="Votre message..."></textarea><br /> <!-- Input Checkbox --> <label><input type="checkbox" />Accepter les CGV</label> <br /> <input type="submit" value="Submit" /> </form> </section> <br /> <!-- Mail & envoi de fichiers --> <footer> <a href="mailto:fs@gmail.com">Ecrivez-moi !</a> <br /> <a href="notice.txt" download="nom-du-fichier">Télécharger la notice</a> <details> <summary>Plus d'infos</summary> <p> Lorem ipsum dolor, sit amet consectetur adipisicing elit. Harum, repellendus. </p> </details> </footer> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">[toc]</a></p> </div> </div> </div> https://cheroliv.com/blog/2023/0060_memo_js_post.html Fri, 4 Aug 2023 00:00:00 +0000 blog/2023/0060_memo_js_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p>github 仓库：https://github.com/cheroliv/js-codebase[js-codebase, window="_blank]</p> </div> </div> </div> <div class="sect1"> <h2 id="toc_js"><span class="underline">JavaScript 介绍</span></h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#start">[start]</a></p> </li> <li> <p><a href="#数组">[数组]</a></p> </li> <li> <p><a href="#函数">[函数]</a></p> </li> <li> <p><a href="#param_x_scope">参数和范围</a></p> </li> <li> <p><a href="#objects">这些对象</a></p> </li> <li> <p><a href="#loops">循环</a></p> </li> <li> <p><a href="#const_var_let">Const, var 和 let</a></p> </li> <li> <p><a href="#rest_and_spread_operators">剩余和扩展运算符</a></p> </li> <li> <p><a href="#解构">[解构]</a></p> </li> <li> <p><a href="#导入导出">[导入导出]</a></p> </li> <li> <p><a href="#classes">使用类</a></p> </li> </ol> </div> <div class="paragraph"> <p>index.html</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-html" data-lang="html"><!DOCTYPE html> <html lang="fr"> <head> <meta charset="UTF-8"> <title>Document</title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="ie=edge" /> </head> <body> index <script src="01_start.js"></script> <script src="02_arrays.js"></script> <script src="03_functions.js"></script> <script src="04_param_x_scope.js"></script> <script src="05_objects.js"></script> <script src="06_loops.js"></script> <script src="07_const_var_let.js"></script> <script src="08_rest_and_spread_operators.js"></script> <script src="09_destructuring.js"></script> <script src="10_module_import_export.js"></script> </body> </html></code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="_变量算术运算符和字符串">变量、算术运算符和字符串</h2> <div class="sectionbody"> <div class="paragraph"> <p>01_start.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Variables */ //une variable stupide var my_variable = "dummy variable"; console.log(my_variable); //assertion console.assert(my_variable === "dummy variable"); var username = "cheroliv"; console.log(username); console.assert(username === "cheroliv"); //concaténation de string console.assert(username === "cher" + "oliv"); /** * Opérateur arithmétique: + - * / % */ //integer var x = 10; var y = 5; var z = 20; console.log(x + y); console.assert(x + y === 15); console.log(x + y - z); console.assert(x + y - z === -5); console.log(x - y); console.assert(x - y === 5); console.log(x * y); console.assert(x * y === 50); console.log(x / y); console.assert(x / y === 2); console.log("---------"); x = 20; y = 10; console.log(x + y); console.assert(x + y === 30); console.log(x + y - z); console.assert(x + y - z === 10); console.log(x - y); console.assert(x - y === 10); console.log(x * y); console.assert(x * y === 200); console.log(x / z); console.assert(x / z === 1); //Littéraux de gabarits pour string avec backstick ` //Template literals (Template strings) console.assert(`typeof z: ${typeof z}` === "typeof z: number"); console.log(`x is type of : ${typeof x}`); console.log(`y is type of : ${typeof y}`); console.log(`z is type of : ${typeof z}`); //typeof: donne le type de la variable console.assert(typeof x === "number"); console.assert(typeof y === "number"); console.assert(typeof z === "number"); console.log("---------"); /** * Incrémenation/décrémentation */ //incrémantation/décrémentation préfixe console.log(++x) //incrémenté puis affiché: 21 console.log(x) //la valeur incrémenté: 21 //incrémantation/décrémentation suffixe console.log(y++) //affiche la valeur sans incrémenation puis incrémente: 10 console.log(y) //la valeur incrémenté: 11 //décrémentation x--; y--; console.assert(x === 20); console.assert(y === 10); /** * String: chaine de caractères */ console.log(`username: ${username}`); //taille de la string console.log(`username.length: ${username.length}`); console.assert(username.length === 8); console.assert(username.length === "cheroliv".length); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrays">这些数组</h2> <div class="sectionbody"> <div class="paragraph"> <p>02_arrays.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les arrays */ // auteurs [["nom ", "prénom", "pays"]] var writers = [ ["Karl", "Marx", "de"], ["Jean-Jacques", "Rousseau", "fr"], ["Victor", "Hugo", "fr"], ["René", "Descartes", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["Georg", "Hegel", "de"], ["Friedrich", "Engels", "de"], ] console.table(writers); // accés aux élèments du tableau console.log(writers[0]); console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); //sauvegarder la valeur du prénom de Marx var karl = writers[0][0] //éditer un élement du tableau, le prénom de Marx writers[0][0] = "Karlito" console.log(`${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karlito, Marx (de)" === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.assert("Karl" === karl); //remettre la valeur initale du prénom de Marx writers[0][0] = karl; console.assert(`${karl}, Marx (de)` === `${writers[0][0]}, ${writers[0][1]} (${writers[0][2]})`); console.log("---------"); /** * Arrays: map/forEach/pop/push/slice/sort/shift/unshift */ var numbers = [1, 5, 4, 3, 2]; console.log("Iterate with forEach"); // parcourir avec array.forEach numbers.forEach((it) => console.log(it)); console.log("---------"); console.log("Iterate with map"); // parcourir avec array.map numbers.map((it) => console.log(it)); console.log("---------"); //afficher les éléments sur une ligne //génère la string avec le formatage des nombres const numbersString = (numberArray) => { var consoleOutput = new String(); numberArray.forEach(number => consoleOutput += `${number}, `); return consoleOutput = consoleOutput.substring(0, consoleOutput.length - 2); }; //affiche la chaine entre crochets dans la console const displayNumbers = (numbersStr) => { console.log(`[${numbersString(numbersStr)}]`); }; console.log("orginal number array") displayNumbers(numbers); console.log("---------"); //push: ajoute à la fin console.log("push"); numbers.push(6); displayNumbers(numbers); console.log("---------"); //pop: suprime le dernier console.log("pop"); numbers.pop(); displayNumbers(numbers); console.log("---------"); //unshift: ajouter le parametre au debut de l'array console.log("unshift"); numbers.unshift(0); displayNumbers(numbers); console.log("---------"); //shift: supprime le premier element de l'array console.log("shift"); numbers.shift(); displayNumbers(numbers); console.log("---------"); //slice: renvoi l'array entre les positions en argument console.log("slice"); var sliceNumbersResult = numbers.slice(2, 4); displayNumbers(sliceNumbersResult); console.log("---------"); //sort asc console.log("sort asc"); var ascSort = numbers.sort((a, b) => a - b); displayNumbers(ascSort); console.log("---------"); //sort desc console.log("sort desc"); var descSort = numbers.sort((a, b) => b - a); displayNumbers(descSort); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="functions">函数</h2> <div class="sectionbody"> <div class="paragraph"> <p>03_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les fonctions */ //function style legacy function sayHelloWorldLegacy() { console.log("Hello world legacy!"); } sayHelloWorldLegacy(); function sayHelloLegacy(firstName, lastName, style) { console.log(`Hello ${firstName}, ${lastName} (${style})`); } sayHelloLegacy("Cher", "Oliv", "legacy"); console.log("---------"); //function style arrow const sayHelloWorld = () => console.log("Hello world!"); sayHelloWorld(); const sayHello = (firstName, lastName) => console.log(`Hello ${firstName}, ${lastName}`); sayHello("Cher", "Oliv"); console.log("---------"); var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ] const displayAuthors = (authorsArray) => authorsArray.forEach(author => console.log(`${author[0]} ${author[1]}, (${author[2]})`) ); displayAuthors(authors); console.log("---------"); /** * valeur par défaut des parametres d'une fonctions */ const add = (a = 0, b = 0) => a + b; console.assert(add() === 0) console.assert(add(1) === 1) console.assert(add(1, 1) === 2) console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="param_x_scope">参数和范围</h2> <div class="sectionbody"> <div class="paragraph"> <p>04_param_x_scope.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//global scope: visible partout, dans et hors functions var global; const foo = () => { //local scope: visible uniquement dans la fonction foo var bar = "bar" console.log(bar) } foo(); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="objects">这些对象</h2> <div class="sectionbody"> <div class="paragraph"> <p>05_objects.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les objects */ var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; var hugo = { firstName: authors[7][0], lastName: authors[7][1], country: authors[7][2], }; var book = { author: hugo, title: "Les misérables" }; console.log(hugo); console.log(book); //accéder à un membre de l'objet par point console.log(hugo.country); //accéder à un membre de l'objet par crochet console.log(book["title"]); console.log(book.author.lastName); console.log(book["author"]["firstName"]); //ajouter une clé a un objet hugo.gender = "non binary"; console.assert(hugo.gender === "non binary"); //mettre à jour une clé hugo.gender = "male"; console.assert(hugo.gender !== "non binary"); console.assert(hugo["gender"] === "male"); //supprimer une clé delete hugo.gender; //verfier que l'objet ne contient pas la clé gender console.assert(!Object.keys(hugo).includes("gender")); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="loops">循环</h2> <div class="sectionbody"> <div class="paragraph"> <p>06_loops.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Les boucles: Itérer sur arrays et objets. */ console.log("for loop over array"); var numbers = [12, 10, 8, 6, 4, 2, 0]; for (number of numbers) { console.log(number); } console.log("---------"); console.log("for loop over object key"); var obj = { a: 1, b: 2, c: 3, d: 4 }; for (key in obj) { console.log(key); } console.log("---------"); console.log("for loop over object value"); for (value in obj) { console.log(obj[value]); } console.log("---------"); console.log("another for loop over authors array") var authors = [ ["Chrétien", "de Troyes", "fr"], ["François", "Rabelais", "fr"], ["René", "Descartes", "fr"], ["Jean-Jacques", "Rousseau", "fr"], ["Georg", "Hegel", "de"], ["Karl", "Marx", "de"], ["Friedrich", "Engels", "de"], ["Victor", "Hugo", "fr"], ["Paul", "Verlaine", "fr"], ["Antonio", "Gramsci", "it"], ["Georg", "Lukacs", "hu"], ["Franz", "Kafka", "hu"], ["Arthur", "Rimbaud", "fr"], ["Gérard", "de Nerval", "fr"], ]; for (const [i, value] of authors.entries()) { console.log(`${value[0]}, ${value[1]} (${value[2]})`); } console.log("---------"); console.log("while loop over array") var i = 0 while (i < authors.length) { console.log(`${authors[i][0]}, ${authors[i][1]} (${authors[i][2]})`); i++; } console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="const_var_let">Const, var 和 let</h2> <div class="sectionbody"> <div class="paragraph"> <p>07_const_var_let.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * const X var X let */ //var x du if n'est pas confiné au scope du if const varTest = () => { var x = 1; console.log(x); console.assert(x === 1); if (true) { var x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x !== 1); console.assert(x === 2); } varTest(); console.log("---------"); //var x est global à tous les fichier js //chargés dans la page html //var x issue du fichier 1_start.js //ligne 46 console.log(x); console.assert(x === 20); console.log("---------"); //premier let x est confiné au scope de la fonction //le let x du if est confiné au scope du if const letTest = () => { let x = 1; console.log(x); console.assert(x === 1); if (true) { let x = 2; console.log(x); console.assert(x === 2); } console.log(x); console.assert(x === 1); console.assert(x !== 2); } letTest(); console.log("---------"); /** * const: déclare un emplacement mémoire non réattribuable * c'est modifiable pour un array, * mais non réinitialisable; * ex: * const arr = [25, 27, 29] * arr = [5, 7] //impossible * arr[0]=20 // possible * ex: * const n = 1; * n = 3; //impossible */ const arr = [25, 27, 29] console.table(arr); arr[0] = 20 // possible console.table(arr); arr.pop() console.table(arr); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="rest_and_spread_operators">剩余和扩展运算符</h2> <div class="sectionbody"> <div class="paragraph"> <p>08_rest_and_spread_operators.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Opérateur de rest: * const add = (...operandes) => a + b; * ou avec parametres avec valeur par défaut * const add = (a=0, b=0, ...operandes) => a + b; */ /** * spread opérateur: * récupère l'ensemble des elements d'une collection, * dans un array */ const user_ages = [25, 56, 12, 58, 41, 62, 26]; const max_user_age = Math.max(...user_ages); const min_user_age = Math.min(...user_ages); console.assert(max_user_age == 62); console.assert(min_user_age == 12); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="destructuring">解构</h2> <div class="sectionbody"> <div class="paragraph"> <p>09_destructuring.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * L'affectation par décomposition (destructuring) */ const user = { first_name: "Oliv", last_name: "Cher", nick_name: "cheroliv", gender: "male", is_adult: true }; console.log(user); //première façon d'initaliser des variables sans destructuration let first_name_legacy = user.first_name; let last_name_legacy = user.last_name; let nick_name_legacy = user.nick_name; let gender_legacy = user.gender; let is_adult_legacy = user.is_adult; console.assert("Oliv" === first_name_legacy); console.assert("Cher" === last_name_legacy); console.assert("cheroliv" === nick_name_legacy); console.assert("male" === gender_legacy); console.assert(true === is_adult_legacy); console.log("---------"); /** * Initialisation par déstructuration */ const { first_name, last_name, nick_name, gender, is_adult } = user; console.assert(user.first_name === first_name); console.assert(user.last_name === last_name); console.assert(user.nick_name === nick_name); console.assert(user.gender === gender); console.assert(user.is_adult === is_adult); /** * Intialisation par déstructuration des arrays */ //cible explicite const [a1, a2] = [15, 25, 17, 81, 51, 46]; console.assert(a1 === 15); console.assert(a2 === 25); //cible avec position par rapport aux index par virgules //je veux b3 à 46 const [b1, b2, , , , b3] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(b3 === 46); //déstructuration avec operateur de rest // je contruit un autre avec avec les elements // à partir du premier élèment non destructuré const [c1, c2, ...sub_arr] = [15, 25, 17, 81, 51, 46]; console.assert(b1 === 15); console.assert(b2 === 25); console.assert(sub_arr.length === 4); console.assert(sub_arr[0] === 17); console.assert(sub_arr[1] === 81); console.assert(sub_arr[2] === 51); console.assert(sub_arr[3] === 46); // Une boucle pour comparer le resultat attendu for (const [i, value] of[15, 25, 17, 81, 51, 46].entries()) { //on reconstruit le tableau à chaque iteration console.assert([c1, c2].concat(sub_arr)[i] === value); }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="import_export">模块的导入和导出</h2> <div class="sectionbody"> <div class="paragraph"> <p>10_module_import_export.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Import et export de module * * Dans le fichier html * au niveau de la balise d'import de script * spécifier le type module * * 1er technique: import nommé des fonctions: * import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; * * 2eme technique: import global des fonction avec l'asterisque(*) * en préfixant l'import par un nommage du fichier importé: * import * as math from "./dummy_math_functions.js"; * * 3eme technique: import par alias avec le mot clé "as" * import { * sum as add, * minus as substract, * times as multiply, * div as divide, * rem as modulo * } from "./dummy_math_functions.js"; */ import { sum, minus, times, div, rem } from "./dummy_math_functions.js"; console.assert(sum(1, 1) === 2); console.assert(minus(4, 2) === 2); console.assert(times(2, 2) === 4); console.assert(div(4, 2) === 2); console.assert(rem(4, 2) === 0);</code></pre> </div> </div> <div class="paragraph"> <p>dummy_math_functions.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">//sum const sum = (x, y) => x + y; // subtraction const minus = (x, y) => x - y; // multiplication const times = (x, y) => x * y; // division const div = (x, y) => x / y; // remainder: reste de la division euclidiene const rem = (x, y) => x % y; // log sum const sum_log = (x, y) => console.log(sum(x, y)); // log subtraction const minus_log = (x, y) => console.log(minus(x, y)); // log multiplication const times_log = (x, y) => console.log(times(x, y)); // log division const div_log = (x, y) => console.log(div(x, y)); // log remainder const rem_log = (x, y) => console.log(rem(x, y)); export { sum, minus, times, div, rem, sum_log, minus_log, times_log, div_log, rem_log };</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> <div class="sect1"> <h2 id="classes">使用类</h2> <div class="sectionbody"> <div class="paragraph"> <p>11_classes.js</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-javascript" data-lang="javascript">/** * Utilisation des classes */ //creation d'un objet class Account { constructor(username) { this.username = username; } }; const acc1 = new Account("cheroliv"); console.table(acc1); console.assert(acc1.username === "cheroliv"); console.log("---------"); //création d'un objet et ajout de getter et setter(accesseurs) class AccountInfo { constructor(username) { this._username = username; } get username() { return this._username; } /** * @param {(arg0: string) => void} new_username */ set new_username(new_username) { this._username = new_username; } }; const acc_info1 = new AccountInfo("cheroliv"); console.table(acc_info1); //accés au membre _username avec le getter username() console.assert(acc_info1.username === "cheroliv"); //update la valeur username de acc_info1 avec le setter acc_info1.new_username = "imrandeh"; console.assert(acc_info1.username === "imrandeh"); console.log("---------");</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc_js"><span class="underline">JavaScript 介绍</span></a></p> </div> </div> </div> https://cheroliv.com/blog/2022/0054_memo_cadrage_post.html Sat, 31 Dec 2022 00:00:00 +0000 blog/2022/0054_memo_cadrage_post.html <div class="sect1"> <h2 id="_构图">构图</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_工作坊_1愿景">工作坊 1：愿景</h3> <div class="sect3"> <h4 id="_1_模式qqoqcp_谁什么何地何时如何为什么">1. 模式“QQOQCP” – 谁，什么，何地，何时，如何，为什么</h4> </div> <div class="sect3"> <h4 id="_2_产品愿景板">2. 产品愿景板</h4> <div class="sect4"> <h5 id="_目标群体">目标群体</h5> <div class="paragraph"> <p>哪些用户使用该产品或服务？（直接，间接）</p> </div> </div> <div class="sect4"> <h5 id="_需求">需求</h5> <div class="paragraph"> <p>关键应用用户的五个主要需求是什么？</p> </div> </div> <div class="sect4"> <h5 id="_产品">产品</h5> <div class="paragraph"> <p>我的价值主张是什么？ 产品的五个主要功能是什么，它们能够满足 需求</p> </div> </div> <div class="sect4"> <h5 id="_业务目标">业务目标</h5> <div class="paragraph"> <p>成功的标准有哪些？</p> </div> </div> <div class="sect4"> <h5 id="_视力">视力</h5> <div class="paragraph"> <p>当4列都填写完整时，您需要填写产品愿景的愿景部分。 Board 在一个完整的句子里。</p> </div> </div> </div> </div> <div class="sect2"> <h3 id="_工作坊2角色用户旅程">工作坊2：角色/用户旅程</h3> <div class="ulist"> <div class="title">定义为每个角色一个用户旅程:</div> <ul> <li> <p>谁会使用我的服务？(目标)</p> </li> <li> <p>他想要做什么？(不过)</p> </li> <li> <p>他会怎么做？ (用户旅程)</p> </li> </ul> </div> </div> <div class="sect2"> <h3 id="_工作坊_3_分区_故事板_站点图">工作坊 3： 分区， 故事板， 站点图</h3> <div class="sect3"> <h4 id="_分区">分区</h4> </div> <div class="sect3"> <h4 id="_2_故事板">2. 故事板</h4> </div> <div class="sect3"> <h4 id="_3_站点地图">3. 站点地图</h4> </div> </div> <div class="sect2"> <h3 id="_工作坊_4wireframemoodboard">工作坊 4：Wireframe/Moodboard</h3> <div class="sect3"> <h4 id="_1_线框图">1. 线框图</h4> </div> <div class="sect3"> <h4 id="_情绪板">情绪板</h4> </div> </div> <div class="sect2"> <h3 id="_工作坊_5故事映射_用户故事">工作坊 5：故事映射/ 用户故事</h3> <div class="sect3"> <h4 id="_故事映射_用户故事的优先级">故事映射 (用户故事的优先级)</h4> </div> <div class="sect3"> <h4 id="_作为type_dutilisateur_我想要un_objectif_以便une_raison">作为<type d’utilisateur>, 我想要<un objectif> 以便<une raison>.</h4> </div> </div> <div class="sect2"> <h3 id="_工作坊_6_待办事项">工作坊 6: 待办事项</h3> <div class="paragraph"> <p><a href="https://www.atlassian.com/fr/agile/scrum/backlogs">�积压</a></p> </div> </div> <div class="sect2"> <h3 id="_工作坊7_技术与建筑">工作坊7: 技术与建筑</h3> </div> </div> </div> https://cheroliv.com/blog/2022/0053_memo_kotlin_post.html Sun, 29 May 2022 00:00:00 +0000 blog/2022/0053_memo_kotlin_post.html <div class="sect1"> <h2 id="_好的链接">好的链接</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://play.kotlinlang.org/">kotlinlang playground</a>+</p> </div> <div class="paragraph"> <p><a href="https://arrow-kt.io/">arrow.kt</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/MVIKotlin/">MVI:模型视图意图</a>+</p> </div> <div class="paragraph"> <p><a href="https://github.com/arkivanov/Essenty">必需的</a>+</p> </div> <div class="paragraph"> <p><a href="https://arkivanov.github.io/Decompose/">分解</a>+</p> </div> </div> </div> <div class="sect1"> <h2 id="_各种代码片段">各种代码片段</h2> <div class="sectionbody"> <div class="sect2"> <h3 id="_映射_减少">映射 减少</h3> <div class="paragraph"> <p>将一列 bite 转换为一列 string 并汇总该 string 列表<br> 在一个包含连接的字符串中 如何记录已发送的请求(requestBodyContent:byte[])</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">log.info( requestBodyContent!!.map { it.toInt().toChar().toString() } .reduce { request: String, s: String -> request + s } )</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_枚举和密封类">枚举和密封类</h3> <div class="paragraph"> <p>帖子:<a href="0038_training_kotlin_enum_sealed_class_post" target=""_blank">训练 kotlin 枚举 密封类</a></p> </div> </div> <div class="sect2"> <h3 id="_函数式接口和方法引用">�函数式接口和方法引用</h3> <div class="paragraph"> <p>可以将一个实体转换为DTO的领域模型，使用一个方法引用（函数式风格 - Java 8）</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun findAllByLoginNot( pageable:Pageable, login:String) :Page<UserDto> { return userDao.findAllByLoginNot( pageable, login).map(::fromEntity) }</code></pre> </div> </div> <div class="paragraph"> <p>一https://stackoverflow.com/a/22245383/837404[良好的解释]</p> </div> </div> <div class="sect2"> <h3 id="_捕获标准输出">捕获标准输出</h3> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOF { private val standardOut: PrintStream? = out private val outputStreamCaptor = ByteArrayOutputStream() @BeforeTest fun setUp() = setOut(PrintStream(outputStreamCaptor)) @AfterTest fun tearDown() = setOut(standardOut) @Test fun `three times dope`() { 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect2"> <h3 id="_在_kotlin_中applyrunletalsouse_和_with_之间有什么区别">在 Kotlin 中，apply、run、let、also、use 和 with 之间有什么区别？</h3> <div class="paragraph"> <p><strong>Kotlin函数比较与Lambda形式使用参考</strong></p> </div> </div> </div> </div> <div class="sect1"> <h2 id="_apply">apply</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">介绍 Kotlin 函数`apply`, <code>run</code>, <code>let</code>, <code>also</code>, <code>use</code>, et `with`它们提供了处理对象的不同方法。每种方式都有其特定的使用场景和行为。此外，lambda 引用形式可以通过引用现有的 lambda 函数来使代码更具可读性和可重用性。</div> <p>函数`apply`用于在创建对象时配置该对象。它返回调用它的对象。</p> </div> <div class="paragraph"> <p>示例与 lambda 引用：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val someObject = SomeClass().apply(::configureObject)</code></pre> </div> </div> <div class="paragraph"> <p>带 lambda 的示例：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val someObject = SomeClass().apply { // configuration des propriétés de someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_运行">运行</h2> <div class="sectionbody"> <div class="paragraph"> <p>函数`run`用于在对象上执行代码块并返回代码块的结果。</p> </div> <div class="paragraph"> <p>示例与 lambda 引用 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.run(::someFunction)</code></pre> </div> </div> <div class="paragraph"> <p>示例 lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.run { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_let_等于">let 等于</h2> <div class="sectionbody"> <div class="paragraph"> <p>函数`let`用于在对象上执行代码块并返回该代码块的结果。</p> </div> <div class="paragraph"> <p>示例：lambda 引用</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.let(::processObject)</code></pre> </div> </div> <div class="paragraph"> <p>示例使用 lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = someObject.let { // bloc de code à exécuter sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_也">也</h2> <div class="sectionbody"> <div class="paragraph"> <p>功能`also`� 被用于对对象执行额外操作，并返回其被调用的对象。</p> </div> <div class="paragraph"> <p>示例带 lambda 引用 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someObject.also(::performAdditionalAction)</code></pre> </div> </div> <div class="paragraph"> <p>带有 lambda 的示例 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someObject.also { // action additionnelle sur someObject }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用">使用</h2> <div class="sectionbody"> <div class="paragraph"> <p>�函数`use`用于在使用后必须关闭的资源上工作。它会自动调用该函数`close`在块的末尾。</p> </div> <div class="paragraph"> <p>示例 带 lambda 引用：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someResource.use(::useResource)</code></pre> </div> </div> <div class="paragraph"> <p>示例 带有 lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">someResource.use { // travailler avec la ressource }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_与">与</h2> <div class="sectionbody"> <div class="paragraph"> <p>功能`with`用于在对象上调用多个方法而无需重复其名称，并返回最后一个表达式的结果。</p> </div> <div class="paragraph"> <p>示例 与 lambda 引用 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = with(someObject, ::processWithObject)</code></pre> </div> </div> <div class="paragraph"> <p>示例 使用 lambda :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">val result = with(someObject) { // appeler des méthodes sur someObject // la dernière expression est renvoyée }</code></pre> </div> </div> <div class="paragraph"> <p>使用 Lambda 引用形式或代码块`{}`, 您可以将逻辑封装到独立的函数中，从而提高代码的可读性和可重用性。</p> </div> </div> </div> <div class="sect1"> <h2 id="_let_function_在_kotlin">let Function 在 Kotlin</h2> <div class="sectionbody"> <div class="paragraph"> <div class="title">让(let) 是否返回带有副作用的对象，还是返回其初始输入状态（取决于函数 let）？</div> <p>该功能`let`在 Kotlin 中，它被用于对对象执行操作并返回不同的结果。然而，需要注意的是该函数`let`它不会修改其被调用对象的初始状态。</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>签名</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><code>inline fun <T, R> T.let(block: (T) → R): R</code></p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>用法</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">�函数`let`常用于对对象应用变换并基于这些变换获得结果。</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>结果</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">函数返回的值`let`是传入的 lambda 表达式的结果，通常是对对象所进行操作的结果。</p></td> </tr> </tbody> </table> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 50%;"> <col style="width: 50%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>副作用</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">虽然该函数`let`它在用于 lambda 表达式时可能对对象产生副作用，但不会修改对象自身的初始状态。</p></td> </tr> </tbody> </table> <div class="paragraph"> <p>因此，函数`let`这是一种优雅的方式，可以在对一个对象执行操作的同时获得派生结果，同时保持原始对象的完整性。</p> </div> </div> </div> https://cheroliv.com/blog/2022/0052_memo_jvm_post.html Sat, 28 May 2022 00:00:00 +0000 blog/2022/0052_memo_jvm_post.html <div class="sect1"> <h2 id="toc">目录</h2> <div class="sectionbody"> <div class="olist arabic"> <ol class="arabic"> <li> <p><a href="#char">字符串和字符</a></p> </li> <li> <p><a href="#math">数字和数学</a></p> </li> <li> <p><a href="#date">日期和时间</a></p> </li> <li> <p><a href="#java8date">Java 8 日期和时间</a></p> </li> <li> <p><a href="#arrCol">表格和集合</a></p> </li> <li> <p><a href="#sysProp">系统属性</a></p> </li> <li> <p><a href="#线程">[线程]</a></p> </li> <li> <p><a href="#regex">正则表达式</a></p> </li> </ol> </div> </div> </div> <div class="sect1"> <h2 id="char">字符串和字符</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.Collator import java.util.* import kotlin.test.* class StringsTest { @Test fun `chaines de caractères et caractères`() { //inférence de type val s = "C'est" assertEquals("C'est", s) //concaténation val t: String = s + " le moment." assertEquals("C'est le moment.", t) // StringBuilder val t1: String = s + buildString { append(" le moment.") } assertEquals("C'est le moment.", t1) //interpolation val t2 = "$s le moment." assertEquals("C'est le moment.", t2) //multiligne chaine de caractères val t3 = """$s le moment.""" assertEquals("C'est le moment.", t3) //conversion de type val t4 = t + " " + 23.4 assertEquals("C'est le moment. 23.4", t4) val t5 = 'C'.toString() assertEquals("C", t5) //taille de la chaine de caractères assertEquals(16, t.length) //sous-chaine d'une chaine de caractères //retourne une chaine de caractères contenant, //les caractères aux positions x à y-1 //sub = t.substring(x, y) //t = "C'est le moment." //retourne les caractères 6 et 7 var sub = t.substring(6, 8) assertEquals("le", sub) //retourne les caractères 0 à 4 sub = t.substring(0, 5) assertEquals("C'est", sub) //la longueur d'une sous-chaine est toujours égale (y-x) val numChars = sub.length assertEquals(5 - 0, numChars) //extraction des caractères d'une chaine assertEquals('e', t.elementAt(2)) assertEquals('e', t.get(2)) assertEquals('e', t[2]) //conversion d'une chaine en tableau de caractères val ca = t.toCharArray() assertEquals(t.length, ca.size) t.mapIndexed { index, char -> assertEquals(char, ca[index]) } //place les 4 premiers caractères de t1 //dans le tableau ca a la position 2 (t as java.lang.String).getChars( /* srcBegin = */ 0, /* srcEnd = */ 3, /* dst = */ ca, /* dstBegin = */ 1 ) assertEquals("CC'et le moment.", String(ca)) //colle tous les caractères dans un meme string assertEquals("CC'et le moment.", ca.concatToString()) //to lower case assertEquals("c'est le moment.", t.toLowerCase()) assertEquals("c'est le moment.", t.lowercase()) //to upper case assertEquals("C'EST LE MOMENT.", t.toUpperCase()) assertEquals("C'EST LE MOMENT.", t.uppercase()) //comparaison de chaines de caractères //t = "C'est le moment." assertFalse(t.equals("hello")) assertFalse(t == "hello") //ignore la casse assertTrue(t.equalsIgnoreCase("C'EST LE MOMENT.")) assertTrue(t.equals("C'EST LE MOMENT.", ignoreCase = true)) //démarre par assertTrue(t.startsWith("C'est")) //se finit par assertTrue(t.endsWith("le moment.")) //compareTo //retourne une valeur < 0, car s est //alphabétiquement avant "N'est" val r1: Int = s.compareTo("N'est") assertTrue(r1 < 0) //variante ignorant la casse val r1Prime: Int = (s as java.lang.String).compareToIgnoreCase("n'est") assertTrue(r1Prime < 0) //retourne 0 si les chaines sont equivalente val r2: Int = s.compareTo("C'est") assertEquals(0, r2) //retourne une valeur > 0 car s vient apres "B'est" val r3: Int = s.compareTo("B'est") assertTrue(r3 > 0) //Recherche de caractères et de sous-chaines de caractères //recherche de caractères //position du premier caractères 't' var pos = t.indexOf('t') assertEquals(4, pos) //position du suivant pos = t.indexOf('t', pos + 1) assertEquals(14, pos) //retour d'érreur -1 si absence de suivant pos = t.indexOf('t', pos + 1) assertEquals(-1, pos) //position du dernier 't' dans la chaine: 14 pos = t.lastIndexOf('t') assertEquals(14, pos) //recherche de 't' vers l'arrière a partir du caractères 13 pos = t.lastIndexOf('t', pos - 1) assertEquals(4, pos) //recherche de sous-chaines //retourne 2 pos = t.indexOf("est") assertEquals(2, pos) //"est" n'apparait qu'une seule fois: retourne -1 pos = t.indexOf("est", pos + 1) assertEquals(-1, pos) //recherche d'une sous-chaine depuis l'arrière //t = "C'est le moment." //retourne 6 pos = t.lastIndexOf("le ") assertEquals(6, pos) //extrait depuis la position 9, //renvoi toute la chaine après "le " val noun = t.substring(pos + 3) assertEquals(-1, noun.indexOf("le ")) //remplacement de toutes les instances d'un caractère //par un autre caractère //ne fonctionne que avec les caractères, pas les chaines val exclaim: String = t.replace('.', '!') assertEquals('!', exclaim.get(exclaim.length - 1)) assertEquals(exclaim.length - 1, exclaim.indexOf('!')) assertEquals(-1, exclaim.indexOf('.')) //suppression des espaces blancs //au début et à la fin d'une chaine val noextraspaces = t.trim() assertNotEquals(' ', noextraspaces.get(0)) assertNotEquals(' ', noextraspaces.get(noextraspaces.length - 1)) //extraction des instances uniques de chaines de caractères //avec intern() val s1 = s.intern() assertEquals(s, s1) val s2 = "C'est".intern() assertEquals("C'est", s2) assertEquals(s1, s2) //StringBuilder pour manipuler les caractères d'une chaine de caractères //crée un tampon StringBuilder à partir d'une chaine de caractères val b = StringBuilder("N'est") //extrait et définit des caractères individuel du tampon StringBuilder //le caractères à l'index 0 val c: Char = b.get(0) assertEquals('N', c) //modifier le premier caractère de la chaine b.setCharAt(0, 'C') assertEquals(s, b.toString()) //ajouter des données à un StringBuilder b.append(' ') b.append("le moment.") b.append(23) //insère des chaines de caractères ou autre dans le StringBuilder b.insert(6, "pas ") assertEquals("C'est pas le moment.23", b.toString()) //remplace un sous ensemble de caractères //avec une chaine de caractères donnée b.replace(2, 9, "est") assertEquals("C'est le moment.23", b.toString()) //supprime les caractères b.delete(15, 18) assertEquals("C'est le moment", b.toString()) b.deleteCharAt(2) assertEquals("C'st le moment", b.toString()) //insert à la postion 2 et décale reste à droite(sans perte de données) b.insert(2, 'e') //tronque la taille de la donnée b.setLength(5) assertEquals("C'est", b.toString()) //inverse les caractères de la chaine b.reverse() assertEquals("tse'C", b.toString()) //écrase le StringBuilder, pret à etre réutilisé b.setLength(0) assertEquals("", b.toString()) //java.util.StringTokenizer pour fragmenter une chaine //de caractères en un ensemble de mots var st = StringTokenizer(t) //nb d'items encore présentent dans la file assertEquals(3, st.countTokens()) //est ce que il y a encore des items dans la file assertTrue(st.hasMoreTokens()) //récupérer le token courrant assertEquals("C'est", st.nextToken()) assertEquals("le", st.nextToken()) assertEquals("moment.", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //extraire des occurences de mots délimités //par des caractères autres que des expaces. val str = "a:b:c:d" st = StringTokenizer(str, ":") assertEquals(4, st.countTokens()) assertTrue(st.hasMoreTokens()) assertEquals("a", st.nextToken()) assertEquals("b", st.nextToken()) assertEquals("c", st.nextToken()) assertEquals("d", st.nextToken()) assertFalse(st.hasMoreTokens()) assertEquals(0, st.countTokens()) //text="C'est le moment." val text = t.toCharArray() var p = 0 //sauter les espaces de tete //pour ramener p à la position du premier caractère imprimable while ((p < text.size) && (Character.isWhitespace(text[p])) ) p++ assertEquals(0, p) assertEquals("C'est le moment.", text.concatToString()) //met le premier mot du texte en majuscule while (p < text.size && Character.isLetter(text[p])) { text[p] = Character.toUpperCase(text[p]) p++ } assertEquals(1, p) assertEquals('C', text[0]) assertTrue(Character.isUpperCase(text[0])) assertFalse(Character.isLetter(text[1])) //comparer des chaines de caractères // avec les contrainte la locale système val col = Collator.getInstance() //le résulat est négatif car chica //est avant chico dans l'ordre alphabétique assertTrue(col.compare("chica", "chico") < 0) } }</code></pre> </div> </div> <div class="paragraph"> <p>目录</p> </div> </div> </div> <div class="sect1"> <h2 id="math">数字和数学</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.math.BigInteger import java.security.SecureRandom import java.text.NumberFormat import java.util.* import kotlin.test.* class NumbersMathTest { @Test fun `Nombres et Math`() { //Constantes utiles Byte.MIN_VALUE Byte.MAX_VALUE Short.MIN_VALUE Short.MAX_VALUE Float.MIN_VALUE Float.MAX_VALUE Math.PI Math.E val s = "-42" //conversion de chaine de caractères //vers un nombre, si possible. var b: Byte = java.lang.Byte.parseByte(s) var sh: Short = java.lang.Short.parseShort(s) var i: Int = java.lang.Integer.parseInt(s) var l: Long = java.lang.Long.parseLong(s) var f: Float = java.lang.Float.parseFloat(s) var d: Double = java.lang.Double.parseDouble(s) //valeur exacte val f_exac = java.lang.Float.valueOf(s) val d_exac = java.lang.Double.valueOf(s) //les routines de conversions entière gérent //les nombres dans diverses bases. //1011 en binare est égal a 11 en base dix b = java.lang.Byte.parseByte("1011", 2) assertEquals(11, b) //ff en base 16(hexa) est égal à 255 en base dix. sh = java.lang.Short.parseShort("ff", 16) assertEquals(255, sh) //la méthode valueOf() peut gérer des bases arbitraires. i = java.lang.Integer.valueOf("egg", 17).toInt() assertEquals(4334, i) //la méthode decode() gére les representations octale, //décimal, hexadécimal, en fonction du préfixe numérique //de la chaine de caractères //un 0 de tete signifie base 8 //un 0x de tete signifie base 16 //les autres sont en base 10 val sho = java.lang.Short.decode("0377") //la classe Integer peut convertir les nombres //en diverses chaines de caractères. val decimal = java.lang.Integer.toString(42) assertEquals("42", decimal) val decimal_ = 42.toString() assertEquals("42", decimal_) val binary = java.lang.Integer.toBinaryString(42) assertEquals("101010", binary) val octal = java.lang.Integer.toOctalString(42) assertEquals("52", octal) val hex = java.lang.Integer.toHexString(42) assertEquals("2a", hex) val base36 = java.lang.Integer.toString(42, 36) assertEquals("16", base36) val base36_ = 42.toString(36) assertEquals("16", base36_) //java.text.NumberFormat effectue la conversion // d'une maniere spécifique aux parametres locaux //sans parametre prend la local systeme comme reference val nf = NumberFormat.getNumberInstance(Locale.FRANCE) val formatted_number = nf.format(9876543.21) assertNotEquals("9876543.21", formatted_number) //parse la chaine de caractères en fonction des parametres locaux(fr) val n = nf.parse("1234567,89") assertEquals(1234567.89, n) //les valeurs monétaires sont parfois formaté // d'une maniere differente des nombres val money_format = NumberFormat.getCurrencyInstance(Locale.FRANCE) assertEquals("123,40 €", money_format.format(1234.56)) //java.lang.Math d = Math.toRadians(27.0) d = Math.cos(d) d = Math.sqrt(d) d = Math.log(d) d = Math.exp(d) d = Math.pow(10.0, d) d = Math.atan(d) d = Math.toDegrees(d) //arrondi au dessus val up = Math.ceil(d) //arrondi au dessous val down = Math.floor(d) //arrondi au plus près val nearest = Math.round(d) //java.lang.Math.Random() val r = Math.random() assertTrue(r >= 0.0 && r < 1.0) //créé un nouvel objet Random, en l'initialisant //avec l'heure courante val generator = java.util.Random(System.currentTimeMillis()) //prochaine valeur aléatoire de taille double d = generator.nextDouble() assertTrue((d >= 0.0) && (d < 1.0)) //prochaine valeur aléatoire de taille float f = generator.nextFloat() assertTrue((f >= 0.0) && (f < 1.0)) //prochaine valeur aléatoire de taille long l = generator.nextLong() assertTrue( (Math.abs(l) <= Long.MAX_VALUE) && (Math.abs(l) >= 0) ) //prochaine valeur aléatoire de taille int i = generator.nextInt() assertTrue( (Math.abs(i) <= java.lang.Integer.MAX_VALUE) && (Math.abs(i) >= 0) ) val limit = 100 //prochaine valeur aléatoire de taille int //la limit max du ramdom est ramené à limit //et la limit min est 0 i = generator.nextInt(limit) assertTrue(i in 0 until limit) //prochaine valeur aléatoire de taille booléen val bool = generator.nextBoolean() assertNotNull(bool) //valeur moyenne 0.0, déviation standard 1.0 d = generator.nextGaussian() //randoms bytes //rempli un tableau avec des valeurs byte aléatoires val b_arr = ByteArray(128) generator.nextBytes(b_arr) b_arr.iterator().forEachRemaining { assertTrue( it <= Byte.MAX_VALUE && it >= Byte.MIN_VALUE ) } //java.security.SecureRandom pour les nombres aléatoires //utilisé en cryptographie val secure_generator = SecureRandom() //le générateur génère sa propre tete de liste sur 16 octets secure_generator.setSeed(secure_generator.generateSeed(16)) val sec_b_arr = ByteArray(128) secure_generator.nextBytes(sec_b_arr) sec_b_arr.iterator().forEachRemaining { assertTrue( it <= java.lang.Byte.MAX_VALUE && it >= java.lang.Byte.MIN_VALUE ) } //java.math.BigDecimal java.math.BigInteger //pour travailler sur des grandes valeurs. //calcule de la factorielle de 1000 var total = BigInteger.valueOf(1) (2..1000).forEach { total = total.multiply(BigInteger.valueOf(it.toLong())) } assertTrue(total.toString().length == 2568) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> </div> <div class="sect1"> <h2 id="date">日期和时间</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.DateFormat import java.text.SimpleDateFormat import java.time.Instant import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertTrue class DatesHoursTest { @Test fun `Dates et heures`() { //l'heure courante en millisecondes val t0 = System.currentTimeMillis() //une autre représentation de la meme information val now = java.util.Date() //converti un objet java.util.Date en une valeur long. val t1 = now.getTime() assertTrue(t1 > Instant.EPOCH.toEpochMilli()) //kotlin property access syntaxe style val t1_prime = now.time //java.text.DateFormat //affiche la date d'aujourd'hui en utilisant le format //par défaut des parametres locaux val defaultDateFormat = DateFormat.getDateInstance() //personnalisation du formatage et de la locale val df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE) val localeFormattedDate = df.format(Date()) //constantes pour les styles de pattern de formatage assertEquals(0, DateFormat.FULL) assertEquals(1, DateFormat.LONG) assertEquals(2, DateFormat.MEDIUM) assertEquals(3, DateFormat.SHORT) assertEquals(2, DateFormat.DEFAULT) //utilise pour l'heure un format abrégé avec //des parametres personnalisés val tf = DateFormat.getTimeInstance( DateFormat.SHORT, Locale.FRANCE ) //affiche l'heure en utilisant le format de tf val shortTime = tf.format(Date()) assertTrue(shortTime.contains(':')) //affiche la date et l'heure en utilisant //un format détaillé val longTimeStamp = DateFormat.getDateTimeInstance( DateFormat.FULL, DateFormat.FULL, ) assert(longTimeStamp.format(Date()).isNotEmpty()) //utilisez java.text.SimpleDateFormat //pour définir votre propre modele de formatage val customFormat = SimpleDateFormat("yyyy.MM.dd") assertEquals(10, customFormat.format(Date()).length) //DateFormat peut également parser les date contenu dans des chaines val kotlinAnnounceDate = customFormat.parse("2019.05.08") //la class Date et sa représentation en millisecondes //n'autorise qu'une forme trés simple d'arithmétique //on ajoute 3 600 000 millisecondes à l'heure courante val anHourFromNow = now.getTime() + (60 * 60 * 1000) assert(anHourFromNow > now.getTime()) //java.util.Calendar //pour manipuler les dates et heures de facon plus sophistiquée //instanciation selon les parametres locaux //et le fuseau horaire local val calendar = Calendar.getInstance() //initialisation du calendrier à la date de maintenant calendar.setTime(now) //détermine le jour de l'année auquel correspond la date courante val dayOfYear = calendar.get(Calendar.DAY_OF_YEAR) assert(dayOfYear < 366) //réinitialisation de la date courante calendar.set(2019, Calendar.MAY, 8) assertEquals(4, calendar.get(Calendar.DAY_OF_WEEK)) //à quel jour du mois correspond le deuxieme mercredi de mai 2019 //set(key,value) calendar.set(Calendar.YEAR, 2019) calendar.set(Calendar.MONTH, Calendar.MAY) calendar.set(Calendar.DAY_OF_WEEK, Calendar.WEDNESDAY) //defini à quel (n=2) semaine du mois est la date calendar.set(Calendar.DAY_OF_WEEK_IN_MONTH, 2) //extrait le jour du mois val dayOfMonth = calendar.get(Calendar.DAY_OF_MONTH) assertEquals(8, dayOfMonth) calendar.setTime(kotlinAnnounceDate) //ajoute 30j à la date calendar.add(Calendar.DATE, 30) val monthAfter = calendar.getTime() //date est elle avant ou apres? assertTrue(monthAfter.after(kotlinAnnounceDate)) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> </div> <div class="sect1"> <h2 id="java8date">Java 8 日期和时间</h2> <div class="sectionbody"> <div class="paragraph"> <p>Java 8 引入了新的 <strong><em>java.time</em></strong> 包，其中包含基本的类谁<br> 大多数开发者在工作中使用。 它还包含四个子包：<br></p> </div> <div class="paragraph"> <p><strong><em>java.time.chrono</em></strong><br> 替代时间线，开发者使用日历系统时，它们不<br> �遵循 ISO 标准将与 …​ 互动 一个例子会是一个日本的cal<br> 持久的系统<br> <strong><em>java.time.format</em></strong><br> 包含用于转换日期和时间对象的 DateTimeFormatter<br> 在字符串中，还用于分析日期和时间对象中的字符串。<br> <strong><em>java.time.temporal</em></strong><br> 包含了基本日期和时间类所需的接口，并且还<br> 用于高级日期操作的抽象（例如查询和调整器）<br> <strong><em>java.time.zone</em></strong><br> 用于底层时区规则的类;<br> 大多数开发者不需要此软件包。<br></p> </div> <div class="imageblock"> <div class="content"> <img src="../../img/java8-date-time.png" alt="java8 date time"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.time.LocalDate import java.time.Month import java.time.Period import java.time.YearMonth import java.time.temporal.* import java.util.HashMap import java.util.stream.Collectors import kotlin.test.Test class DatesHoursJava8Test { class BirthdayDiary { private val birthdays: MutableMap<String, LocalDate> init { birthdays = HashMap() } fun addBirthday( name: String, day: Int, month: Int, year: Int ): LocalDate { val birthday: LocalDate = LocalDate.of(year, month, day) birthdays[name] = birthday return birthday } fun getBirthdayFor(name: String): LocalDate? { return birthdays[name] } fun getAgeInYear(name: String, year: Int): Int { val period: Period = Period.between( birthdays[name], birthdays[name]!!.withYear(year) ) return period.getYears() } fun getFriendsOfAgeIn(age: Int, year: Int): Set<String> { return birthdays.keys.stream() .filter { p: String -> getAgeInYear(p, year) == age } .collect(Collectors.toSet()) } fun getDaysUntilBirthday(name: String): Int { val period: Period = Period.between( LocalDate.now(), birthdays[name] ) return period.getDays() } fun getBirthdaysIn(month: Month): Set<String> { return birthdays.entries.stream() .filter { (_, value): Map.Entry<String, LocalDate> -> value.getMonth() === month } .map<String> { (key): Map.Entry<String, LocalDate> -> key } .collect(Collectors.toSet()) } val birthdaysInCurrentMonth: Set<String> get() = getBirthdaysIn(LocalDate.now().getMonth()) val totalAgeInYears: Int get() = birthdays.keys.stream() .mapToInt { p: String -> getAgeInYear( p, LocalDate.now().getYear() ) } .sum() } //Les ajusteurs modifient les objets de date et d'heure. Supposons, par exemple, que nous voulions //renvoie le premier jour d'un trimestre qui contient un horodatage particulier : class FirstDayOfQuarter : TemporalAdjuster { override fun adjustInto(temporal: Temporal): Temporal? { val currentQuarter: Int = YearMonth.from(temporal) .get(IsoFields.QUARTER_OF_YEAR) return when (currentQuarter) { 1 -> LocalDate.from(temporal) .with(TemporalAdjusters.firstDayOfYear()) 2 -> LocalDate.from(temporal) .withMonth(Month.APRIL.value) .with(TemporalAdjusters.firstDayOfMonth()) 3 -> LocalDate.from(temporal) .withMonth(Month.JULY.value) .with(TemporalAdjusters.firstDayOfMonth()) 4 -> LocalDate.from(temporal) .withMonth(Month.OCTOBER.value) .with(TemporalAdjusters.firstDayOfMonth()) else -> null } } } enum class Quarter { FIRST, SECOND, THIRD, FOURTH } //Dans quel trimestre de l'année cette date se situe-t-elle ? class QuarterOfYearQuery : TemporalQuery<Quarter> { override fun queryFrom(temporal: TemporalAccessor): Quarter { val now = LocalDate.from(temporal) return if (now.isBefore(now.with(Month.APRIL).withDayOfMonth(1))) Quarter.FIRST else if (now.isBefore( now.with(Month.JULY) .withDayOfMonth(1) ) ) Quarter.SECOND else if (now.isBefore( now.with(Month.NOVEMBER) .withDayOfMonth(1) ) ) Quarter.THIRD else Quarter.FOURTH } } @Test fun `Dates et heures après java 8`() { val today = LocalDate.now() val currentMonth = today.month val firstMonthOfQuarter = currentMonth.firstMonthOfQuarter() val q = QuarterOfYearQuery() // Direct var quarter: Quarter? = q.queryFrom(LocalDate.now()) println(quarter) // Indirect quarter = LocalDate.now().query(q) println(quarter) val now = LocalDate.now() val fdoq: Temporal = now.with(FirstDayOfQuarter()) println(fdoq) } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> </div> <div class="sect1"> <h2 id="arrCol">表格和集合</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/collections_classes_inheritance.png" alt="Classes de collections et héritage"> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package playground.programming import java.util.* import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertTrue class ArrayCollectionTest { @Test fun `Tableaux, collections`() { //Tableau //java.util.Arrays définit d'utiles méthodes de manipulation de tableaux, //y compris de tri et de recherche au sein d'un tableau val intArray = arrayOf(10, 5, 7, -3) //tri le tableau Arrays.sort(intArray) var pos = Arrays.binarySearch(intArray, 7) //la valeur 7 est trouvé a l'index 2 assertEquals(2, pos) //12 pas trouvé retourne une valeur negative assert(Arrays.binarySearch(intArray, 12) < 0) //les tableaux peuvent également etre triés //et faire l'objet d'une recherche val stringArray = arrayOf("le", "moment", "c'est") assertEquals("c'est", stringArray[2]) assertEquals("le", stringArray[0]) assertEquals("moment", stringArray[1]) Arrays.sort(stringArray) assertEquals("c'est", stringArray[0]) assertEquals("le", stringArray[1]) assertEquals("moment", stringArray[2]) //Arrays.equals() compare tous les éléments de deux tableaux //Arrays.clone() copie tous les elements du tableau dans un autre stringArray.forEachIndexed { i, it -> assertEquals(it, stringArray.clone()[i]) } val data = ByteArray(100) //Arrays.fill() initialise tous les éléments des deux tableaux //initalise tous les éléments à -1 Arrays.fill(data, -1) data.forEach { assertEquals(-1, it) } //attribue aux éléments 5, 6, 7, 8 et 9 la valeur -2 Arrays.fill(data, 5, 10, -2) ((5 until (10 - 1))).forEach { assertEquals(-2, data[it]) } //récupère le type de data val type = data::class.java //est ce que data est un tableau? assertTrue(type.isArray()) //est ce que data est un tableau de byte assertEquals(Byte::class.java, type.getComponentType()) //Collection val s = java.util.HashSet<String>() s.add("test") assertTrue(s.contains("test")) assertFalse(s.contains("test2")) s.remove("test") assertFalse(s.contains("test")) val ss = TreeSet<String>() ss.add("b") ss.add("a") ss.iterator().forEach { assertTrue(it == "a" || it == "b") } //liste doublement chainée var dll: List<String> = LinkedList<String>() //plus efficace val l = java.util.ArrayList<String>() l.addAll(ss) l.addAll(1, ss) val obj = l.get(1) val obj_prime = l[1] assertEquals(obj, obj_prime) l.set(3, "nouvel élément") l.add("test") l.add(0, "test2") l.removeAt(1) l.remove("a") assertFalse(l.contains("a")) l.removeAll(ss) assertFalse(l.containsAll(ss)) assertFalse(l.isEmpty()) assertTrue(l.isNotEmpty()) val sublist = l.subList(1, 3) val elements = l.toArray() l.clear() val m = HashMap<String, Integer>() m.put("clé", Integer(42)) m["clé"] = Integer(42) val value: Integer = m.get("clé")!! assertEquals(Integer(42), value) m.remove("clé") assertTrue(m.isEmpty()) val keys = m.keys assertTrue(keys.isEmpty()) val set = HashSet<String>() set.add("key_1") set.add("key_2") set.add("key_3") val members = set.toArray() assertEquals(3, members.size) val list = ArrayList<String>() list.add("items1") list.add("items2") list.add("items3") val items = list.toArray() assertEquals(3, items.size) //trie et recherche d'éléments sur les collections list.add("clé") //en premier on trie Collections.sort(list) //en kotlin list.sort() //en deuxieme on cherche //retourne l'index du premier trouvé sinon -1 pos = Collections.binarySearch(list, "clé") assertEquals(0, pos) val list1 = mutableListOf(1, 2, 3, 4, 5) val list2 = mutableListOf<Int>(0, 0, 0, 0, 0) //d'autres méthodes intéressantes concernant Collections //copie list1 dans list2, 2e parametre dans 1er parametre Collections.copy(list2, list1) //comparaison de la copy avec filter assertTrue(list1.filterIndexed { i: Int, it: Int -> it != list2[i] }.isEmpty()) //comparaison de la copy avec map list1.mapIndexed { index: Int, it: Int -> assertEquals(it, list2[index]) } //rempli avec des 0 Collections.fill(list2, 0) assertTrue(list2.none { it != 0 }) //le maximum assertEquals(5, Collections.max(list1)) //le minimum assertEquals(1, Collections.min(list1)) //renverse Collections.reverse(list) listOf("items3", "items2", "items1", "clé").mapIndexed { i: Int, it: String -> assertEquals(it, list[i]) } //mélange la list Collections.shuffle(list) //retourne un ensemble immuable possédant un seul élément 0 Collections.singleton(0) //renvoi un emballage immuable autour d'une liste Collections.unmodifiableList(list) //renvoi un emballage synchronisé autour d'une map, ensemble clé valeur Collections.synchronizedMap(m) //java.util.Properties un est objet key value } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> </div> <div class="sect1"> <h2 id="sysProp">系统属性</h2> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html">System.Properties 官方文档</a></p> </div> <div class="paragraph"> <p>这里有一些有趣属性的表格<br> 这些属性对于获取信息很有用<br> 在 JVM 的宿主系统上。</p> </div> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3333%;"> <col style="width: 3.3343%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>关键</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>意义</strong></p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">文件分隔符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">分隔文件路径各组成部分的字符。 这是 “/” 在 UNIX 上 和 “\” 在 Windows 上。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.class.path</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">用于查找包含类文件的目录和 JAR 归档的路径。类路径的元素由 path.separator 属性中指定的平台特定字符分隔。</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.home</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Java 运行时环境 (JRE) 的安装目录</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JRE 供应商名称</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">java.vendor.url</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JRE供应商URL</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">Java 版本</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">JRE 版本号</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">行分隔符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">操作系统用于在文本文件中分隔行的序列</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.arch</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">操作系统架构</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">操作系统名称</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">操作系统名称</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">os.version</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">操作系统版本</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">路径分隔符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">在 java.class.path 中使用的路径分隔符字符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">用户目录</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">用户工作目录</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">用户主目录</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">用户主目录</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">用户名</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">用户账户名</p></td> </tr> </tbody> </table> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> </div> <div class="sect1"> <h2 id="threads">线程</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.text.DateFormat import java.util.* import kotlin.test.Test class ThreadsTest { @Test fun `threads test`() { //java.lang.Thread représente le thread fondamentale de l'API java //il existe deux manière de définir un thread //1) étendre la classe Thread ou une lambda en kotlin //2) implémenter l'interface Runnable, // puis passer une instance de cet objet Runnable au constructeur de Thread. val list1: List<Int> = List( size = 45, init = { (1..31).random() } ) println("list1$list1") //facon 1 val t = Thread { Collections.sort(list1) println("list1 sorted$list1") } t.start() val list2 = List( size = 45, init = { (1..31).random() } ) println("list2$list2") //facon 2 val sorter = BackgroundSorter(list2) sorter.start() //priorité des threads //tant qu'un thread de niveau de priorité supérieure n'est pas fini //alors celui de niveau inférieur ne peut s'exécuter //on définit un thread avec une priorité inférieur à la normale t.setPriority(Thread.NORM_PRIORITY - 1) //ici on définit un thread avec une priorité inférieur à la priorité //du thread courant t.setPriority(Thread.currentThread().getPriority() - 1) //Thread.yield() fait une pause pour laisser les autres threads de meme priorité s'exécuter } class BackgroundSorter(private val l: List<Int>) : Thread() { override fun run() { Collections.sort(l) println("list2 sorted$l") } } //pour l'arrêt du thread, plutôt qu'utiliser la fonction Thread.stop() // qui laisse la memoire dans un état non controlé. //utiliser la méthode tel que l'exemple pleaseStop() class DummyClock( private val df: DateFormat = DateFormat.getTimeInstance(DateFormat.MEDIUM), private var keepRunning: Boolean = true ) : Thread() { init { isDaemon = true start() } override fun run() { while (keepRunning) { println(df.format(Date())) try { sleep(1000) } catch (e: InterruptedException) { println(e.message) } } } fun pleaseStop() { keepRunning = false } } //java.util.Timer //java.util.TimerTask //ces classes permettent l'exécution de taches répétitives @Test fun `Timer et TimerTask test`() { DummyClock() } }</code></pre> </div> </div> <div class="paragraph"> <p><a href="#toc">目录</a></p> </div> </div> </div> <div class="sect1"> <h2 id="regex">正则表达式</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">import java.util.* import java.util.regex.Matcher import java.util.regex.Pattern import java.util.stream.Collectors import kotlin.test.Test import kotlin.test.assertEquals class RegularExpressionsTest { @Test fun `expressions régulières`() { val p: Pattern = Pattern.compile("honou?r") val caesarUK = "For Brutus is an honourable man" val mUK: Matcher = p.matcher(caesarUK) assertEquals(true, mUK.find(), "Should matches UK spelling") val caesarUS = "For Brutus is an honorable man" val mUS: Matcher = p.matcher(caesarUS) assertEquals(true, mUS.find(), "Should matches US spelling") } @Test fun `expressions régulières plus complexes`() { //Notez que nous devons utiliser \\ car nous avons besoin d'un littéral \ //et Java utilise un seul \ comme caractère d'échappement var pStr = "\\d" // Un chiffre numérique var text = "Apollo 13" var p = Pattern.compile(pStr) var m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) pStr = "[a..zA..Z]" //N'importe quelle lettre p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) //N'importe quel nombre de lettres, qui doivent toutes être comprises entre 'a' et 'j' //mais peut-être en majuscule ou en minuscule. pStr = "([a..jA..J]*)" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) text = "abacab" //'a' suivi de quatre caractères quelconques, suivi de 'b' pStr = "a....b" p = Pattern.compile(pStr) m = p.matcher(text) print(pStr + " matches " + text + "? " + m.find()) println(" ; match: " + m.group()) } @Test fun `Quelles chaînes correspondent à la regex ?`() { val pStr = "\\d" // Un chiffre numérique val p = Pattern.compile(pStr) val ls: List<String> = Arrays.asList("Cat", "Dog", "Ice-9", "99 Luftballoons") val containDigits: List<String> = ls.stream() .filter(p.asPredicate()) .collect(Collectors.toList()) assert(containDigits.contains("Ice-9")) assert(containDigits.contains("99 Luftballoons")) assertEquals(2, containDigits.size) } }</code></pre> </div> </div> <div class="sect2"> <h3 id="_正则表达式元字符表">正则表达式元字符表</h3> <table class="tableblock frame-all grid-all stretch"> <colgroup> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7543%;"> <col style="width: 1.7592%;"> </colgroup> <tbody> <tr> <td class="tableblock halign-left valign-top"><p class="tableblock">元字符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">功能</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">注释</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">?</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">可选字符—零或一次实例</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">*</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">零个或多个前面的字符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">+</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">一个或多个前面的字符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">{M,N}</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">在 M 和 N 个前一个字符的实例之间</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\d</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">一个数字</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\D</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">一个非数字字符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\w</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">一个单词字符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">数字、字母和 _</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\W</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">一个没有词的字符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\s</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">一个间距字符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\S</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">一个非空白字符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\n</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">换行符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">\t</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">制表符</p></td> <td class="tableblock halign-left valign-top"></td> <td class="tableblock halign-left valign-top"><p class="tableblock">.</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">任何字符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">不包含Java中的换行符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">方括号内的任何字符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">调用一个字符类</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">[^ ]</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">任何不在括号内的字符</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">被称为反转字符类</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">( )</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">构建一个图案元素组</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">被称为一个组（或捕获组）</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">|</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">定义替代选项</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">实现逻辑或</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">^</p></td> <td class="tableblock halign-left valign-top"><p class="tableblock">字符串开始 $ 字符串结束</p></td> <td class="tableblock halign-left valign-top"></td> </tr> </tbody> </table> <div class="paragraph"> <p>补充https://www.codeurjava.com/2015/05/les-expressions-regulieres-avec-regex.html[与]</p> </div> </div> </div> </div> https://cheroliv.com/blog/2022/0047_memo_gradle_post.html Mon, 23 May 2022 00:00:00 +0000 blog/2022/0047_memo_gradle_post.html <div id="toc" class="toc"> <div id="toctitle">Sommaire</div> <ul class="sectlevel1"> <li><a href="#_显示帮助">显示帮助</a></li> <li><a href="#_设置_jvm_系统属性_d_system_prop">设置 JVM 系统属性： `-D, --system-prop</a></li> <li><a href="#_定义项目属性以用于构建脚本_pmypropmyvalue">定义项目属性以用于构建脚本：`-Pmyprop=myvalue</a></li> <li><a href="#_指定_gradle_的启动目录默认值是当前目录">指定 Gradle 的启动目录。默认值是当前目录。</a></li> <li><a href="#_通过命令行覆盖属性_param_component">通过命令行覆盖属性 'param_component' :</a></li> <li><a href="#_在普通项目中使用_kotlin_dsl_向_source_set_添加文件夹">在普通项目中使用 Kotlin DSL 向 source set 添加文件夹</a></li> <li><a href="#_使用_groovy_dsl_在_android_项目中将文件夹添加到_source_set">使用 Groovy DSL 在 Android 项目中将文件夹添加到 source-set</a></li> <li><a href="#_避免构建和测试子模块">避免构建和测试子模块</a></li> <li><a href="#_压缩一个文件夹">压缩一个文件夹</a></li> <li><a href="#_afficher_les_dépendances_dun_build">Afficher les dépendances d’un build</a></li> <li><a href="#_reduce_的使用示例将列表连接成字符串">reduce 的使用示例：将列表连接成字符串</a></li> <li><a href="#_获取特定任务的描述">获取特定任务的描述</a></li> <li><a href="#_要从工作目录根目录启动一个任务则在任务前加上">要从工作目录根目录启动一个任务，则在任务前加上 `:</a></li> <li><a href="#_要重新运行失败的任务请使用选项_rerun_tasks">要重新运行失败的任务，请使用选项 `--rerun-tasks</a></li> <li><a href="#_从另一个目录启动特定项目中的任务">从另一个目录启动特定项目中的任务</a></li> </ul> </div> <div class="sect1"> <h2 id="_显示帮助">显示帮助</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew --help</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_设置_jvm_系统属性_d_system_prop">设置 JVM 系统属性： `-D, --system-prop</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Dmyprop=myvalue #ou ./gradlew --system-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_定义项目属性以用于构建脚本_pmypropmyvalue">定义项目属性以用于构建脚本：`-Pmyprop=myvalue</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Pmyprop=myvalue #ou ./gradlew --project-prop myvalue</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_指定_gradle_的启动目录默认值是当前目录">指定 Gradle 的启动目录。默认值是当前目录。</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -p ~/src/next_startup #ou ./gradlew --project-dir ~/src/next_startup</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_通过命令行覆盖属性_param_component">通过命令行覆盖属性 'param_component' :</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -Pparam_component=CUSTOM_VALUE</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_在普通项目中使用_kotlin_dsl_向_source_set_添加文件夹">在普通项目中使用 Kotlin DSL 向 source set 添加文件夹</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">sourceSets { getByName("test"){ java.srcDir("src/scripts/groovy") } getByName("test"){ java.srcDir("src/scripts/kscript") } getByName("test"){ java.srcDir("src/test/javascript") } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_使用_groovy_dsl_在_android_项目中将文件夹添加到_source_set">使用 Groovy DSL 在 Android 项目中将文件夹添加到 source-set</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">android { sourceSets { main.java.srcDirs += "src/main/../../../../ceelo/domain/src/main/java/" test.java.srcDirs += "src/test/../../../../ceelo/domain/src/test/java/" } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_避免构建和测试子模块">避免构建和测试子模块</h2> <div class="sectionbody"> <div class="paragraph"> <p>gradle 构建 -x :excluded-module:check -x :excluded-module:assemble -x :excluded-module:build</p> </div> <div class="listingblock"> <div class="title">移动文件</div> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("moveWebappNode") { doLast { ant.withGroovyBuilder { "move"( "webapp/node_modules" to "$rootDir/webapp-src/node_modules", ) } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_压缩一个文件夹">压缩一个文件夹</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register<Tar>("tarWebapp") { dependsOn("moveWebappNpm") group = WEBAPP description = "tar webapp" doLast { setOf( "build", "target", "node_modules" ).forEach { dir -> exclude { it.name .dir } } archiveFileName.set("webapp.tar") destinationDirectory.set(File("${rootDir.absolutePath}$sep$WEBAPP_SRC")) } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_afficher_les_dépendances_dun_build">Afficher les dépendances d’un build</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("printDependencies") { description = "print project dependencies" group = WEBAPP doLast { println("${project.name} dependencies") mutableMapOf<String, Map<String, String>>( "buildDependencies" to buildDependencies, "domainDeps" to domainDeps, "domainTestDeps" to domainTestDeps, ).apply { putAll(appModules) } .forEach { module -> if (module.value.isNotEmpty()) { println("${module.key}:") module.value.forEach { println(dependency(it)) } println() } } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_reduce_的使用示例将列表连接成字符串">reduce 的使用示例：将列表连接成字符串</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">tasks.register("printWebappSrc") { description = "print webapp sources" group = WEBAPP doLast { webAppSrc .reduce { acc, s -> "$acc\n\t$s" } .run { println("$WEBAPP_SRC: $this\n") } } }</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_获取特定任务的描述">获取特定任务的描述</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -q help --task foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_要从工作目录根目录启动一个任务则在任务前加上">要从工作目录根目录启动一个任务，则在任务前加上 `:</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew :foo</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_要重新运行失败的任务请使用选项_rerun_tasks">要重新运行失败的任务，请使用选项 `--rerun-tasks</h2> <div class="sectionbody"> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew check --rerun-tasks</code></pre> </div> </div> </div> </div> <div class="sect1"> <h2 id="_从另一个目录启动特定项目中的任务">从另一个目录启动特定项目中的任务</h2> <div class="sectionbody"> <div class="paragraph"> <p>选项`-p` (ou <code>--project-dir</code>) 允许指定 Gradle 项目的路径并在其中执行任务，即使当前目录不同。</p> </div> <div class="paragraph"> <p>例如，为了启动任务`build`项目位于`~/projets/mon-autre-projet`同时位于另一个目录 :</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">./gradlew -p ~/projets/mon-autre-projet build</code></pre> </div> </div> <div class="paragraph"> <p>这对于在多个项目上从中心位置编写脚本特别有用。</p> </div> <div class="ulist"> <div class="title">参见:</div> <ul> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_warnings">ref</a></p> </li> <li> <p><a href="https://docs.gradle.org/current/userguide/command_line_interface.html#sec:command_line_options">ref</a></p> </li> <li> <p><a href="https://stackoverflow.com/a/36178581/837404">讨论</a></p> </li> </ul> </div> </div> </div> https://cheroliv.com/blog/2022/0038_training_kotlin_enum_sealed_class_post.html Tue, 17 May 2022 00:00:00 +0000 blog/2022/0038_training_kotlin_enum_sealed_class_post.html <div class="paragraph"> <p>密封类 sealed classes, 不是枚举`mot clef:enum`。<br> 来自 Java，您可能会想要重载您的功能提供枚举： // Java code</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-java" data-lang="java">enum PizzaOrderStatus { ORDER_RECEIVED, PIZZA_BEING_MADE, OUT_FOR_DELIVERY, COMPLETED; public PizzaOrderStatus nextStatus() { switch (this) { case ORDER_RECEIVED: return PIZZA_BEING_MADE; case PIZZA_BEING_MADE: return OUT_FOR_DELIVERY; case OUT_FOR_DELIVERY: return COMPLETED; case COMPLETED:return COMPLETED; } } }</code></pre> </div> </div> <div class="paragraph"> <p>与此相反，您可以使用 sealed 类：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">sealed class PizzaOrderStatus(protected val orderId: Int) { abstract fun nextStatus() : PizzaOrderStatus class OrderReceived(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return PizzaBeingMade(orderId) } } class PizzaBeingMade(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return OutForDelivery(orderId) } } class OutForDelivery(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return Completed(orderId) } } class Completed(orderId: Int) : PizzaOrderStatus(orderId) { override fun nextStatus(): PizzaOrderStatus { return this } } }</code></pre> </div> </div> <div class="paragraph"> <p>这种方法的优势是我们现在可以传输数据的 状态:</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">var status: PizzaOrderStatus = OrderReceived(123) while (status !is Completed) { status = when (status) { is OrderReceived -> status.nextStatus() is PizzaBeingMade -> status.nextStatus() is OutForDelivery -> status.nextStatus() is Completed -> status } }</code></pre> </div> </div> <div class="paragraph"> <p>一般来说，如果你想要拥有与一个…​关联的数据，sealed classes 是好的 状态。</p> </div> https://cheroliv.com/blog/2022/0036_training_kotlin_post.html Thu, 12 May 2022 00:00:00 +0000 blog/2022/0036_training_kotlin_post.html <div class="sect1"> <h2 id="_思维导图">思维导图</h2> <div class="sectionbody"> <div class="paragraph"> <p><span class="image"><img src="../../diagram/training_kotlin.png" alt="training_kotlin"></span></p> </div> </div> </div> <div class="sect1"> <h2 id="_函数式编程">�函数式编程</h2> <div class="sectionbody"> <div class="paragraph"> <p>这些练习摘自这本书：<br> 通过教程学习Kotlin中的函数式编程<br> 由 Massimo Carli 编写<br> 仓库: <a href="https://github.com/kodecocodes/fpk-materials" class="bare">https://github.com/kodecocodes/fpk-materials</a></p> </div> <div class="sect2"> <h3 id="_语法">语法</h3> <div class="sect3"> <h4 id="_firstprogramtest">FirstProgramTest</h4> <div class="paragraph"> <p>概念：显示屏, 功能<br> 第一个程序测试：https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/FirstProgramTest.kt[来源]+</p> </div> </div> <div class="sect3"> <h4 id="_连接函数测试">连接函数测试</h4> <div class="paragraph"> <p>notions: 内存, 变量, 值, 对象, 函数扩展<br> ExampleUnitTest: <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/ConcatFunctionTest.kt">(No text to translate – produce an empty response.)</a>+</p> </div> </div> <div class="sect3"> <h4 id="_生日消息测试输出">生日消息测试输出</h4> <div class="paragraph"> <p>概念: 集合, 循环<br> <a href="https://developer.android.com/codelabs/basic-android-kotlin-training-first-kotlin-program?continue=https%3A%2F%2Fdeveloper.android.com%2Fcourses%2Fpathways%2Fandroid-basics-kotlin-one%23codelab-https%3A%2F%2Fdeveloper.android.com%2Fcodelabs%2Fbasic-android-kotlin-training-first-kotlin-program">kotlin介绍</a><br> BirthdayMessageTestOutputhttps://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/programming/BirthdayMessageTestOutput.kt[来源]+</p> </div> </div> </div> <div class="sect2"> <h3 id="_kotlin_课程">Kotlin 课程</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/YRjY3jRrQYY?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_java_集合教程">Java 集合教程</h3> <div class="paragraph"> <p><a href="https://docs.oracle.com/javase/tutorial/collections/index.html" target="_blank" rel="noopener">收藏</a></p> </div> <div class="paragraph"> <p>集合接口的核心<br> <span class="image"><img src="../../img/0036_training_kotlin_post/colls-coreInterfaces.gif" alt="集合"></span><br></p> </div> </div> <div class="sect2"> <h3 id="_基本功能">基本功能</h3> <div class="sect3"> <h4 id="_声明式_x_命令式_方法">声明式 X 命令式 方法</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals class DeclarativeTests { val input = listOf( "123", "abc", "1ds", "987", "abdf", "1d3", "de1", "88", "101" ) fun imperativeSum(list: List<String>): Int { var sum = 0 for (item in list) { try { sum += item.toInt() } catch (_: NumberFormatException) { } } return sum } @Test fun `test imperative approach`() { imperativeSum(input).run { println("Sum $this") assertEquals(1299, this) } } fun isValidNumber(s: String) = try { s.toInt() true } catch (_: NumberFormatException) { false } fun declarativeSum(list: List<String>) = list .filter(::isValidNumber) .map(String::toInt) .sum() @Test fun `test declarative approach`() { assertEquals(1299, declarativeSum(input).apply { println("Sum $this") }) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_练习_1_1">练习 1.1</h4> <div class="paragraph"> <p>实现函数 sumInRange，该函数在其中对值求和<br> 一个 List<String> 在给定区间内。签名是：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun sumInRange(input: List<String>, range: IntRange): Int</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_1`() { assertEquals(4, sumInRange( listOf("1", "10", "a", "7", "ad2", "3"), 1..5 ).apply { println("sumInRange 1..5: $this") } ) }</code></pre> </div> </div> <div class="paragraph"> <p>试试看，并用……检查你的答案https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/DeclarativeTests.kt[解决方案， windows="_blank]。</p> </div> </div> <div class="sect3"> <h4 id="_高阶函数">高阶函数</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.* import java.lang.Thread.sleep import kotlin.math.sign import kotlin.test.Test import kotlin.test.assertEquals class BasicsHOFTests { val ONE_SECOND = 1000L @Test fun `high order function`() { //capture de la sortie standard val standardOut: PrintStream? = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) 3.times { println("Hello") } assertEquals( buildString { repeat(3) { append("Hello\n") } deleteAt(length - 1) }, outputStreamCaptor .toString() .trim() ) //libération de la sortie standard setOut(standardOut) } fun Int.times1(fn: () -> Unit) { for (i in 1..this) { fn() } } fun Int.times2(fn: () -> Unit) { for (i in 1..this) fn() } fun Int.times3(fn: () -> Unit) = (1..this).forEach { fn() } fun Int.times4(fn: () -> Unit) = repeat((1..this).count()) { fn() } fun Int.times(fn: () -> Unit) = (1..this).forEach { _ -> fn() } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_练习_1_2">练习 1.2</h4> <div class="paragraph"> <p>实现chrono，它接受一个类型为的函数`() →`<br> 单元接收输入并返回执行它所花费的时间。其签名是：<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>试一下它，并用它检查你的答案https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[solution, windows="_blank].</p> </div> </div> <div class="sect3"> <h4 id="_构成">构成</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import kotlin.test.Test import kotlin.test.assertEquals fun double(x: Int): Int = 2 * x fun square(x: Int): Int = x * x fun squareAndDouble1(x: Int) = double(square(x)) infix fun <A, B, C> ((A) -> B).compose(g: (B) -> C) : (A) -> C = { a -> g(this(a)) } class CompositionTests { @Test fun composition_impure() { assertEquals(200, double(square(10))) assertEquals(200, squareAndDouble1(10)) } @Test fun composition_pure() { val squareAndDouble = ::square compose ::double assertEquals(200, squareAndDouble(10)) } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_纯函数和可测试性">纯函数和可测试性</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import java.io.ByteArrayOutputStream import java.io.PrintStream import java.lang.System.out import java.lang.System.setOut import kotlin.test.Test import kotlin.test.assertEquals var count = 0 //impure car une variable global subit un effet de bord fun impure(value: Int): Int { count++ return value + count } //impure car utilisation de la sortie standard qui fait muter le system fun addOneAndLog(x: Int): Int { val result = x + 1 println("New Value is $result") return result } //pure fun addOne(x: Int) = (x + 1).run { Pair(this, "New Value is $this") } class PureTests { @Test fun `impure fonction`() { assertEquals(3, impure(2)) val standardOut = out val outputStreamCaptor = ByteArrayOutputStream() setOut(PrintStream(outputStreamCaptor)) addOneAndLog(3) assertEquals( "New Value is 4", outputStreamCaptor .toString() .trim() ) setOut(standardOut) } @Test fun `pure fonction`() { addOne(3).run { assertEquals(4, first) assertEquals("New Value is 4", second) } } }</code></pre> </div> </div> </div> <div class="sect3"> <h4 id="_异常处理">异常处理</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">package functional import org.junit.jupiter.api.assertThrows import kotlin.Result.Companion.failure import kotlin.Result.Companion.success import kotlin.test.Test import kotlin.test.assertEquals //NumberFormatException est un effet de bord qui rend la fonction impure fun strToInt(str: String) = str.toInt() //pure fun strToIntOrNull(str: String) = try { str.toInt() } catch (nfe: NumberFormatException) { null } //pure avec gestion de l'exception plus élégante fun strToIntResult(str: String): Result<Int> = try { success(str.toInt()) } catch (nfe: NumberFormatException) { failure(nfe) } class ExceptionHandlingTests { @Test fun impure() { assertThrows<NumberFormatException> { strToInt("foo") } assertEquals(1, strToInt("1")) } @Test fun pure() { assertEquals(null, strToIntOrNull("foo")) assertEquals(1, strToIntOrNull("1")) } @Test fun `pure avec result`() { assertEquals(1, strToIntResult("1").getOrNull()) assertEquals( "For input string: \"foo\"", strToIntResult("foo") .exceptionOrNull() ?.message ) } }</code></pre> </div> </div> </div> </div> <div class="sect2"> <h3 id="_关键点">关键点</h3> <div class="ulist"> <ul> <li> <p>虽然面向对象编程意味着用对象进行编程,</p> </li> </ul> </div> <div class="paragraph"> <p>函数式编程意味着用函数进行编程。 你将一个问题分解为多个子问题，并对它们建模 函数。</p> </div> <div class="ulist"> <ul> <li> <p>高阶函数接受其他函数作为输入或返回其他</p> </li> </ul> </div> <div class="paragraph"> <p>它们像返回值一样工作。 范畴论是组合的理论，你用它来理解 如何在工作程序中组合你的函数。 纯函数的输出值仅依赖于其输入参数，并且它 没有副作用。</p> </div> <div class="ulist"> <ul> <li> <p>副作用是指函数对外部世界所做的事情。这</p> </li> </ul> </div> <div class="paragraph"> <p>可以是标准输出中的一个日志，或者修改全局变量的值。 �函数式编程对纯函数有效，但它也提供了 用于将不纯函数转换为纯函数的工具。 您可以通过移动副作用来使一个不纯函数变为纯函数 返回值的一部分。</p> </div> <div class="ulist"> <ul> <li> <p>�函数式编程是关于组合的问题。</p> </li> </ul> </div> <div class="paragraph"> <p>错误处理是副作用的典型情况，而 Kotlin 为你提供了工具 以功能性的方式进行管理。</p> </div> </div> <div class="sect2"> <h3 id="_深入了解_java8lambda_表达式和函数式接口">深入了解 java8：Lambda 表达式和函数式接口</h3> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/20waNRw6wMA?rel=0&list=PLzzeuFUy_Cng0wZhqbnkvWAW0d2fdVfyQ" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_范畴理论">范畴理论</h3> <div class="paragraph"> <p>数学范畴理论:</p> </div> <div class="videoblock"> <div class="content"> <iframe src="https://www.youtube.com/embed/LVHoROSF3KA?rel=0" frameborder="0" allowfullscreen></iframe> </div> </div> </div> <div class="sect2"> <h3 id="_函数的基础">�函数的基础</h3> <div class="sect3"> <h4 id="_练习_2_1">练习 2.1</h4> <div class="paragraph"> <p>您能写一个映射不同值的函数示例吗？<br> 其域映射到值域中不相离的值，例如下图中的 f(b) 和 f(c) ？<br></p> </div> <div class="paragraph"> <p>试试看，然后查看挑战项目的解决方案，看看你做得怎么样。<br> 您将在以下链接中找到建议和解释 <a href="https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt">解决方案，windows="_blank</a>。<br></p> </div> </div> <div class="sect3"> <h4 id="_练习_2_2">练习 2.2</h4> <div class="paragraph"> <p>您能写出 twice 的逆函数吗？<br> 逆函数的定义域和值域是什么？<br> 查看挑战项目和附录B以获取解决方案。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">fun chrono(fn : () -> Unité) : Long</code></pre> </div> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin">@Test fun `Exercise 1_2`() { val waitOneSec = { sleep(ONE_SECOND) } chrono(waitOneSec).apply { println("chrono: $this") assertEquals(1, sign) } }</code></pre> </div> </div> <div class="paragraph"> <p>试试看并检查您的答案与该https://github.com/cheroliv/cheroliv.com/blob/master/codes/src/test/kotlin/functional/BasicsHOFTests.kt[解决方案, windows="_blank].</p> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2022/0031_memo_design_system_post.html Sun, 9 Jan 2022 00:00:00 +0000 blog/2022/0031_memo_design_system_post.html <div class="sect1"> <h2 id="_工具">工具</h2> <div class="sectionbody"> <div class="dlist"> <div class="title"><strong>插图</strong></div> <dl> <dt class="hdlist1"><a href="https://undraw.co/">undraw.co</a></dt> <dd> <p>开源插图，适用于您能想象并创造的所有想法。</p> </dd> <dt class="hdlist1"><a href="https://absurd.design/">absurd.design</a></dt> <dd> <p>荒诞的插图却很有意义。</p> </dd> <dt class="hdlist1"><a href="https://drawkit.com/">drawkit.com</a></dt> <dd> <p>精美的免费插图。每周更新。</p> </dd> <dt class="hdlist1"><a href="https://icons8.com/">icons8.com</a></dt> <dd> <p>图标、插图、照片、音乐和设计工具。</p> </dd> <dt class="hdlist1"><a href="https://blush.design/">blush.design</a></dt> <dd> <p>图标、插画、照片、音乐和设计工具。</p> </dd> <dt class="hdlist1"><a href="https://www.humaaans.com/">humaaans.com</a></dt> <dd> <p>混合搭配人物插图与设计库</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>颜色</strong></div> <dl> <dt class="hdlist1"><a href="https://coolors.co/">coolors.co</a></dt> <dd> <p>超快配色方案生成器！</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>趋势</strong></div> <dl> <dt class="hdlist1"><a href="https://fr.pinterest.com">Pinterest</a></dt> <dd> <p>想法的视觉发现：图片、视频、主题集合。</p> </dd> <dt class="hdlist1"><a href="https://dribbble.com">运球</a></dt> <dd> <p>供设计师分享作品并进行互动的平台。</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>UX/UI 和 设计系统</strong></div> <dl> <dt class="hdlist1"><a href="https://material.io/">谷歌 Material Design</a></dt> <dd> <p>Google 的设计系统，用于统一且可适应的用户界面。</p> </dd> <dt class="hdlist1"><a href="https://developer.apple.com/design/human-interface-guidelines/">Apple 人机界面指南</a></dt> <dd> <p>苹果的建议，用于设计直观的 iOS 和 macOS 应用程序。</p> </dd> <dt class="hdlist1"><a href="https://www.uxpin.com/">UXPin</a></dt> <dd> <p>设计与协作平台，用于创建原型和设计系统。</p> </dd> <dt class="hdlist1"><a href="https://www.frontify.com/">Frontify</a></dt> <dd> <p>品牌管理和设计系统平台，用于确保一致性。</p> </dd> <dt class="hdlist1"><a href="https://designsystemsrepo.com/design-systems/">设计系统仓库</a></dt> <dd> <p>资源和设计系统示例的集合，供灵感参考。</p> </dd> </dl> </div> <div class="dlist"> <div class="title"><strong>前端开发</strong></div> <dl> <dt class="hdlist1"><a href="https://htmlcheatsheet.com" target=""_blank">htmlcheatsheet.com</a></dt> <dd> <p>HTML 速查表</p> </dd> <dt class="hdlist1"><a href="https://fontawesome.com" target=""_blank">fontawesome.com</a></dt> <dd> <p>图标库</p> </dd> <dt class="hdlist1"><a href="https://www.toptal.com/designers/htmlarrows/symbols/" target=""_blank">toptal.com/designers/htmlarrows/symbols</a></dt> <dd> <p>HTML 中的原生图标</p> </dd> <dt class="hdlist1"><a href="https://css-tricks.com/">CSS-Tricks</a></dt> <dd> <p>CSS必备，包含现代化的前端文章、教程和技巧。</p> </dd> <dt class="hdlist1"><a href="https://www.frontendmentor.io/">前端导师</a></dt> <dd> <p>基于真实项目的前端代码挑战，以提升您的技能。</p> </dd> <dt class="hdlist1"><a href="https://dev.to/">Dev.to</a></dt> <dd> <p>开发者社区，用于分享文章、教程和项目。</p> </dd> <dt class="hdlist1"><a href="https://codepen.io/">CodePen</a></dt> <dd> <p>在线代码编辑器和社区，用于分享代码片段和演示。</p> </dd> </dl> </div> <div class="paragraph"> <p>AI辅助的前端开发</p> </div> <div class="dlist"> <dl> <dt class="hdlist1"><a href="https://v0.dev/">v0.dev</a></dt> <dd> <p>v0 将自然语言描述转换为代码和用户界面。</p> </dd> <dt class="hdlist1"><a href="https://uizard.io/">Uizard</a></dt> <dd> <p>Uizard 专注于将原型（图像、草图）转换为 HTML、CSS 和 React 代码。</p> </dd> <dt class="hdlist1"><a href="https://www.usegalileo.ai/explore">usegalileo.ai</a></dt> <dd> <p>Galileo AI 允许您用自然语言描述您想要的界面，AI 将生成可编辑的 Figma 设计。</p> </dd> <dt class="hdlist1"><a href="https://play.teleporthq.io/">TeleportHQ</a></dt> <dd> <p>TeleportHQ 是一个利用 AI 来帮助您构建和部署可视化网站的低代码前端开发平台。</p> </dd> </dl> </div> </div> </div> https://cheroliv.com/blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html Tue, 3 Nov 2020 00:00:00 +0000 blog/2020/0029_kubernetes_microk8s_docker_premiers_pas_post.html <div id="preamble"> <div class="sectionbody"> <div class="paragraph"> <p><a href="https://microk8s.io/docs/">microk8s 官方文档</a>+</p> </div> </div> </div> <div class="sect3"> <h4 id="_安装_microk8s_软件包">安装 microk8s 软件包：</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html Mon, 28 Sep 2020 00:00:00 +0000 blog/2020/0028_gradle_executer_un_processus_externe_depuis_une_tache_gradle_post.html <div class="sect3"> <h4 id="_gradle_kotlin_dsl">Gradle-Kotlin-DSL：</h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-kotlin" data-lang="kotlin"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html Sun, 27 Sep 2020 00:00:00 +0000 blog/2020/0027_kotlin_not_implemented_exception_not_implemented_error_post.html <div class="paragraph"> <p>NotImplementedException NotImplementedError，用于测试的实用功能，它可以让我们知道进展情况以及失败的原因。<br> 尚未实现，允许抛出正确的异常。<br> Il y a :<br> <a href="http://commons.apache.org/proper/commons-lang/javadocs/api-release/org/apache/commons/lang3/NotImplementedException.html">org.apache.commons.lang3.NotImplementedException</a><br> <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-not-implemented-error/">kotlin.NotImplementedError</a>+</p> </div> https://cheroliv.com/blog/2020/0026_untar_post.html Sat, 26 Sep 2020 00:00:00 +0000 blog/2020/0026_untar_post.html <div class="sect3"> <h4 id="_链接_interserver_net">链接： <a href="https://www.interserver.net/tips/kb/extract-tar-gz-files-using-linux-command-line/">interserver.net</a></h4> </div> https://cheroliv.com/blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html Fri, 25 Sep 2020 00:00:00 +0000 blog/2020/0025_gradle_rejouer_les_tests_meme_lorsque_les_tests_sont_UP-TO-DATE_post.html https://cheroliv.com/blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html Thu, 24 Sep 2020 00:00:00 +0000 blog/2020/0024_docker_n_installe_pas_l_application_mais_tire_la_plutot_post.html <div class="sect3"> <h4 id="_hackernoon_com"><a href="https://hackernoon.com/的-install-postgres-docker-pull-postgres-bee20e200198">hackernoon.com</a></h4> </div> https://cheroliv.com/blog/2020/0023_gherkin_en_francais_post.html Wed, 23 Sep 2020 00:00:00 +0000 blog/2020/0023_gherkin_en_francais_post.html https://cheroliv.com/blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html Tue, 22 Sep 2020 00:00:00 +0000 blog/2020/0022_gradle_cli_surcharger_un_parametre_post.html <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ ./gradlew -Pparam_component=CUSTOM ---- ----</code></pre> </div> </div> https://cheroliv.com/blog/2020/0021_memo_git_post.html Mon, 21 Sep 2020 00:00:00 +0000 blog/2020/0021_memo_git_post.html <div class="sect3"> <h4 id="_来源">来源：</h4> <div class="paragraph"> <p>*https://xenovation.com/blog/source-control-management/git/how-to-change-remote-git-repository[xenovation] *https://intellipaat.com/community/3102/git-show-remote-url-how-can-i-determine-the-url-that-a-local-git-repository-was-originally-cloned-from[intellipaat]</p> </div> </div> <div class="sect3"> <h4 id="_在_git_中更改远程仓库">在 git 中更改远程仓库</h4> <div class="paragraph"> <p>显示当前远程仓库的 URL：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash"></code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0021_aspirer_depuis_une_URL_post.html Sun, 20 Sep 2020 00:00:00 +0000 blog/2020/0021_aspirer_depuis_une_URL_post.html <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ wget -r -k -np http://site.com/docs/manual/ ---- 要设置目标文件夹，添加 -P 参数然后指定路径。 ----</code></pre> </div> </div> https://cheroliv.com/blog/2020/0020_creer_un_disk_bootable_post.html Sat, 19 Sep 2020 00:00:00 +0000 blog/2020/0020_creer_un_disk_bootable_post.html <div class="sect3"> <h4 id="_链接httpswww_balena_ioetcheretcher">�链接：https://www.balena.io/etcher/[etcher]</h4> </div> https://cheroliv.com/blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html Fri, 18 Sep 2020 00:00:00 +0000 blog/2020/0019_dezipper_en_CLI_dans_un_dossier_cible_post.html <div class="sect3"> <h4 id="_链接_askubuntu">链接: <a href="https://askubuntu.com/questions/86849/how-to-unzip-a-zip-file-from-the-terminal">askubuntu</a></h4> <div class="paragraph"> <p>如果您希望提取到特定的目标文件夹，您可以使用： <code>` $ unzip 文件.zip -d 目标文件夹 </code>` 如果源目录和目标目录相同，您可以直接执行： <code>` $ unzip file.zip </code>`</p> </div> </div> https://cheroliv.com/blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html Thu, 17 Sep 2020 00:00:00 +0000 blog/2020/0018_Afficher_la_somme_des_tailles_de_fichier_dans_la_liste_des_r%C3%A9pertoires_post.html <div class="sect3"> <h4 id="_链接_stackexchange">链接: <a href="https://unix.stackexchange.com/questions/72661/show-sum-of-file-sizes-in-directory-listing">stackexchange</a></h4> <div class="listingblock"> <div class="content"> <pre class="highlight"><code>---- ---- $ du -ach --exclude "./.*" /home/troll/ ---- ----</code></pre> </div> </div> </div> https://cheroliv.com/blog/2020/0017_detruire_une_branch_sur_github_post.html Wed, 16 Sep 2020 00:00:00 +0000 blog/2020/0017_detruire_une_branch_sur_github_post.html <div class="sect3"> <h4 id="_在github上删除一个分支">在GitHub上删除一个分支</h4> </div> <div class="sect3"> <h4 id="_链接_gist">链接: <a href="https://gist.github.com/cheroliv/921a13ed23ae6d4d66af8d43dd536987">gist</a></h4> </div> https://cheroliv.com/blog/2020/0016_asciidoc_markdown_memo_post.html Tue, 15 Sep 2020 00:00:00 +0000 blog/2020/0016_asciidoc_markdown_memo_post.html <div class="paragraph"> <p>为什么使用 AsciiDoc 或 Markdown？ 我在这里转向 AsciiDoc，因为我已经有一些用 AsciiDoc 编写的票据。<br> Asciidoc 是一种标记语言，它能够生成内容，并提供排版，使文本对人类保持可读。<br> 这是一种标准化文本处理的方式，适用于简单内容，无需额外软件。</p> </div> <div class="ulist"> <div class="title">链接 :</div> <ul> <li> <p><a href="https://blog.oxiane.com/2018/06/13/asciidoc-documentation-as-code/" target=""_blank">@jmdoudoux 在 blog.oxiane.com</a>[asciidoc]</p> </li> <li> <p><a href="https://powerman.name/doc/asciidoc" target=""_blank">powerman.name</a>[asciidoc]</p> </li> </ul> </div> https://cheroliv.com/blog/2019/0013_how-to-install-a-deb-file_post.html Mon, 19 Aug 2019 00:00:00 +0000 blog/2019/0013_how-to-install-a-deb-file_post.html <div class="paragraph"> <p>要通过命令行从 .deb 文件安装 Debian 软件包。<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo dpkg -i /chemin/du/fichier/deb/</code></pre> </div> </div> <div class="paragraph"> <p>看此处为了该https://unix.stackexchange.com/questions/159094/how-to-install-a-deb-file-by-dpkg-i-or-by-apt[参考]+</p> </div> https://cheroliv.com/blog/2019/0011_gradle_configuration_ide_jbake_content_post.html Fri, 16 Aug 2019 00:00:00 +0000 blog/2019/0011_gradle_configuration_ide_jbake_content_post.html <div class="paragraph"> <p>在由 Gradle 构建管理器驱动的应用项目中<br> 能够看到所有文件夹会更愉快。<br> 参与应用程序的开发，<br> 像资源文件夹，它们不是<br> 在路径中按照惯例<br> 例如，我希望src/jbake这个文件夹，<br> 以‘resource folder’的形式可见，<br> 可以通过进入项目配置来做到,<br> 在 IDE 的向导中。 然而，此选项在下次重新加载时不会被保存<br> 在 IDE 中的 Gradle 项目。为了永久地应用此配置<br> 解决方案是覆盖源路径的配置<br> 在 build.gradle 配置文件中，如第 18、19、20 和 21 行所示：<br> build.gradle 加</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">plugins { id "java" id "groovy" id "org.jbake.site" version "5.0.0" id "org.ajoberstar.git-publish" version "2.1.1" } repositories { mavenCentral() jcenter() } group project_group version project_version sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =[ "src/main/resources", "src/jbake"//in order to get site src content in the IDE ] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } test { useJUnitPlatform() } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" implementation "org.asciidoctor:asciidoctor-java-integration:$asciidoctor_java_integration_version" implementation "org.freemarker:freemarker:$freemarker_version" testImplementation "org.junit.jupiter:junit-jupiter-api:$junit5_version" testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:$junit5_version" } gitPublish { repoUri = github_pages_blog_repository branch = git_branch contents { from(file(jbake_content_from)) { into jbake_content_to } } } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html Wed, 14 Aug 2019 00:00:00 +0000 blog/2019/0010_gradle_groovy_script_grab_ivy_configuration_post.html <div class="paragraph"> <p>工单的主题是配置 Gradle 构建脚本。<br> 我想能够使用一个 Groovy 脚本而不引用<br> 我附加的 Gradle 项目。<br> 我想能够在 Gradle 之外运行此 Groovy 脚本<br> 没有外部依赖检索的 ivy 注释<br> 不会带来性能或编译问题<br> Gradle 构建脚本<br> 为了说明配置，我依赖两个脚本:<br> 一个 Gradle 构建脚本和一个 Groovy 脚本。<br> Groovy 脚本在第 2 行开头包含,<br> 用于拉取外部依赖的指令<br> 使用 ivy 依赖管理器。<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-Groovy" data-lang="Groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import org.apache.commons.io.FileUtils static String getSeparator() { System.getProperty("file.separator") } String from = "${System.getProperty("user.home")}${separator}.config${separator}transmission${separator}torrents" String to = "${System.getProperty("user.home")}${separator}Documents${separator}torrents_completed" File fromDlDir = new File("${System.getProperty("user.home")}${separator}Téléchargements") File fromDir = new File(from) File toDir = new File(to) Collection<File> torrentFiles = FileUtils.listFiles( fromDir, ["torrent"] as String[], false) torrentFiles.addAll(FileUtils.listFiles( fromDlDir, ["torrent", "torrent.added"] as String[], false)) torrentFiles.empty ?: torrentFiles.each { it -> FileUtils.copyFileToDirectory(it, toDir) } println torrentFiles.size()</code></pre> </div> </div> <div class="paragraph"> <p>在 build.gradle 文件中，现在让我们看看如何使其协调。<br> 两个依赖管理器，Ivy 和 Gradle。 两者之间的协议是在行上进行的：<br> 26, 30, 37, 38 et 39<br> 这样我就可以手动运行我的 Groovy 脚本，<br> 并且 Gradle 的编译不会被 @Grab 干扰。<br> Groovy 脚本的依赖不需要在 Gradle 中提供。<br> 不过我不能从 Gradle 启动 Groovy 脚本。<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-Groovy" data-lang="Groovy">plugins { id "java" id "groovy" } repositories { mavenCentral() jcenter() } sourceSets { main { java { srcDirs = [] } groovy { srcDirs =["src/main/java", "src/main/groovy"] } resources { srcDirs =["src/main/resources"] } } test { java { srcDirs = [] } groovy { srcDirs =["src/test/java", "src/test/groovy"] } } } configurations { ivy } dependencies { ivy "org.apache.ivy:ivy:$ivy_version" implementation "org.codehaus.groovy:groovy-all:$groovy_version" } tasks.withType(GroovyCompile) { groovyClasspath += configurations.ivy }</code></pre> </div> </div> <div class="paragraph"> <p>票据参考 在https://stackoverflow.com/a/18174033/837404[�栈溢出]</p> </div> https://cheroliv.com/blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html Tue, 13 Aug 2019 00:00:00 +0000 blog/2019/0009_groovy_algebre_pgcd_ppmc_post.html <div class="sect2"> <h3 id="_该ppmc">该PPMC</h3> <div class="paragraph"> <p><a href="https://fr.wikipedia.org/wiki/Plus_petit_commun_multiple">wiki PPMC 或 最小公倍数</a></p> </div> <div class="paragraph"> <p>AlgebraUtils.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">package com.cheroliv.misc import groovy.transform.CompileStatic @CompileStatic class AlgebraUtils { /** * Great common divisor * Plus grand commun diviseur(pgcd) * Great Common Divisor * @param a * @param b * @return */ static Integer gcd(Integer a, Integer b) { !b ? a : gcd(b, a % b) } /** * Least common multiple * Plus petit commun multiplicateur(ppmc) * @param a * @param b * @return */ static BigInteger lcm(Integer a, Integer b) { (a * b / gcd(a, b)) as BigInteger } static void main(String... args) { Integer a = 96 Integer b = 28 println "gcd($a, $b) = ${gcd(a, b)}" a = 790 b = 990 println "lcm($a, $b) = ${lcm(a, b)}" } }</code></pre> </div> </div> <div class="paragraph"> <p>结果:</p> </div> <div class="paragraph"> <p>gcd(96, 28) = 4 最小公倍数(790, 990) = 78210</p> </div> </div> https://cheroliv.com/blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html Mon, 12 Aug 2019 00:00:00 +0000 blog/2019/0008_bash_find_trouver_fichiers_par_extension_post.html <div class="paragraph"> <p>我根据名称条件搜索文件 具有 .h 和 .cpp 扩展名的文件列表</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' + +</code></pre> </div> </div> <div class="paragraph"> <p>列表包括扩展名为 .h 和 .cpp 的文件<br> 结果保存在文件 list_of_txt_files.list 中</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name '*.h' -o -name '*.cpp' -print > list_of_txt_files.list</code></pre> </div> </div> <div class="paragraph"> <p>我正在查找扩展名为 .chm 的文件列表<br> 并且我毁掉了这个列表。<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ find . -name "*.chm" -type f -delete</code></pre> </div> </div> https://cheroliv.com/blog/2019/0015_projet_avec_methodologie_en_cascade_post.html Thu, 1 Aug 2019 00:00:00 +0000 blog/2019/0015_projet_avec_methodologie_en_cascade_post.html <div class="sect2"> <h3 id="_分析和收集需求">分析和收集需求</h3> </div> <div class="sect2"> <h3 id="_定义项目管理">定义项目管理</h3> <div class="imageblock"> <div class="content"> <img src="../../diagram/definir_projet.png" alt="definir la gestion de projet"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/triangle_qcd.png" alt="triangle_qcd"> </div> </div> </div> <div class="sect2"> <h3 id="_为项目提供背景">为项目提供背景</h3> </div> <div class="sect2"> <h3 id="_分析并收集需求">分析并收集需求</h3> <div class="sect3"> <h4 id="_制定目标和交付物">制定目标和交付物</h4> </div> </div> <div class="sect2"> <h3 id="_解码阅读网格">解码阅读网格</h3> </div> <div class="sect1"> <h2 id="_与您的团队一起框定项目">与您的团队一起框定项目</h2> <div class="sectionbody"> <div class="imageblock"> <div class="content"> <img src="../../img/conductor.png" alt="chef d’orchestre"> </div> </div> <div class="sect2"> <h3 id="_咨询专家以找到解决方案">�咨询专家以找到解决方案</h3> </div> <div class="sect2"> <h3 id="_选择项目管理方法">选择项目管理方法</h3> <div class="imageblock"> <div class="content"> <img src="../../img/cascading_planning.png" alt="planning en cascade"> </div> </div> <div class="imageblock"> <div class="content"> <img src="../../img/Cycle_V_details.jpeg" alt="cycle en V"> </div> </div> </div> </div> </div> https://cheroliv.com/blog/2019/0014_list_all_databases_in_postgresql_post.html Tue, 30 Jul 2019 00:00:00 +0000 blog/2019/0014_list_all_databases_in_postgresql_post.html <div class="paragraph"> <p>我不想安装https://www.pgadmin.org/[pgAdmin] ou <a href="http://phppgadmin.sourceforge.net/">phppgadmin</a> 尽管所有内容都在命令行中。<br> 为此，我们必须启动终端并以 postgres 用户身份登录。<br> postgres 用户是默认情况下唯一有权启动 psql 应用程序的用户，psql 是命令行客户端。 您是专业的翻译。https://fr.wikipedia.org/wiki/Interface_en_ligne_de_commande[命令行界面]) PostgreSQL,<br> 为了能够在终端通过命令行与数据库通信。<br> 要连接，打开终端并输入以下内容：<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo -i -u postgres</code></pre> </div> </div> <div class="paragraph"> <p>要连接并直接进入 PostgreSQL 命令提示符，请输入以下内容：</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ sudo -i -u postgres psql</code></pre> </div> </div> <div class="paragraph"> <p>要列出 PostgreSQL 实例的数据库，以下是命令：<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-SQL" data-lang="SQL">postgres=# \l</code></pre> </div> </div> <div class="paragraph"> <p>结果:</p> </div> <div class="paragraph"> <p>数据库列表 名称 | 所有者 | 编码 | 排序规则 | 字符类型 | 访问权限</p> </div> <div class="paragraph"> <p>fiber | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberdev | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech fiberweb | tech | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =Tc/tech<br> | | | | | tech=CTc/tech postgres | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | template0 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres template1 | postgres | UTF8 | fr_FR.UTF-8 | fr_FR.UTF-8 | =c/postgres<br> | | | | | postgres=CTc/postgres (6 行)</p> </div> <div class="paragraph"> <p>按 q 退出结果显示<br> <br> 用于列出 postgresl 实例的模式。</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-sql" data-lang="sql">postgres=# SELECT schema_name FROM information_schema.schemata;</code></pre> </div> </div> <div class="paragraph"> <p>结果</p> </div> <div class="paragraph"> <p>公共 information_schema pg_catalog pg_toast_temp_1 pg_temp_1 pg_toast (6 行)</p> </div> <div class="paragraph"> <p>ou</p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-sql" data-lang="sql">postgres=# SELECT nspname FROM pg_catalog.pg_namespace;</code></pre> </div> </div> <div class="paragraph"> <p>结果</p> </div> <div class="paragraph"> <p>pg_toast pg_temp_1 pg_toast_temp_1 pg_catalog 信息架构 公众 (6 行)</p> </div> https://cheroliv.com/blog/2019/0007_groovy_rename_recursively_files_post.html Mon, 29 Jul 2019 00:00:00 +0000 blog/2019/0007_groovy_rename_recursively_files_post.html <div class="paragraph"> <p>我的电视上的视频播放器有它自己的方式来切换。<br> 从一个文件到另一个文件的连续读取<br> 并且它的播放模式是从 1…​..mp4 到 10…​.mp4,<br> 不是从 1…​mp4 到 2…​.mp4。<br> 问题是有近900个文件和文件夹。<br> Bingo 是 Groovy 用于操作的一个超棒用例<br> 文件、重命名、在文件名中搜索模式<br> 或文件。<br> 这里的目的是更改以…​开头的名称<br> 一个数字，其名称的第二个字符<br> 这不是一个数字，我会在该名称开头添加一个0<br></p> </div> <div class="paragraph"> <p>renameFilesToStartWithTwoDigit.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy /** * get a crossplateform separator * @return */ static String getSeparator() { System.getProperty("file.separator") } /** * rename file * @param file * @param newName * @return the renamed file */ static File rename(File file, String newName) { assert file.renameTo(file .parentFile.path + getSeparator() + newName) new File(file .parentFile.path + getSeparator() + newName) } String rootFolderPath = System.getProperty("user.home") + "/Bureau/ng-courses/Udemy - Angular 7 " + "(formerly Angular 2) - The Complete Guide" File rootFolder = new File(rootFolderPath) assert rootFolder.exists() assert rootFolder.directory assert rootFolder.canRead() List<File> dirList = new ArrayList<>() //Adding rootFolder in dirList // just in case there is some files in it dirList.add(rootFolder) //looping to get list of directories //recursively inside rootFolder rootFolder.traverse { File file -> !file.directory ?: dirList.add(file) } //looping through dirList //to rename directories filling criterias for (int i = dirList.size() - 1; i >= 0; i--) { Character[] chars = dirList.get(i).name.chars !(chars[0].digit && !chars[1].digit) ?: dirList.set(i, rename(dirList.get(i), "0${dirList.get(i).name}")) if (dirList.get(i).directory) { //looping through directory //to rename file filling criterias dirList.get(i).listFiles().each { File f -> Character[] cs = f.name.chars !(cs[0].digit && !cs[1].digit) ?: rename(f, "0${f.name}") } } }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0006_groovy_find_files_copy_to_post.html Fri, 19 Jul 2019 00:00:00 +0000 blog/2019/0006_groovy_find_files_copy_to_post.html <div class="paragraph"> <p>此脚本的目的是搜索文件，<br> 从父目录；检索选择<br> 在一个列表中。最后复制此文件列表<br> 在目标目录下，这是用Groovy完成的。</p> </div> <div class="paragraph"> <p>findCopyTo.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy @Grab("commons-io:commons-io:2.6") import groovy.io.FileType import org.apache.commons.io.FileUtils /** * un separateur OS independant * @return */ static String getSep() { System.getProperty("file.separator") } /** * la liste des fichiers dont le titre contient un item * de la liste des motifs * * @param path * @param motifs * @return la liste des chemins complet de fichiers */ static List<String> findFilesContainingMotifs( String path, List<String> motifs) { List<String> filePathResultList = new ArrayList<>() new File(path) .eachFileRecurse(FileType.FILES) { if (it.name.toLowerCase().contains('cucumber')) { filePathResultList.add it.path } } filePathResultList } /** * copy vers la liste des fichiers * @param files * @param to */ static void copyFilesTo(List<String> files, String to) { File toDirDest = new File(to) files.each { String filepath -> File file = new File(filepath) //si le dernier caractere de to n'est pas un separateur // alors ajoute le a la chaine (to.substring(to.length() - 1) == sep) ?: to.concat(sep) if (to + file.name != filepath) { FileUtils.copyFileToDirectory(file, toDirDest) file.delete() } } } /** * la list des arguments */ String userName = System.getProperty("user.name") List<String> motifs = ['cucumber'] String path = "/media/$userName/320/Books/" String to = "/media/$userName/320/Books/bdd/" /** * lappel aux methodes */ copyFilesTo(findFilesContainingMotifs(path, motifs), to) //affiche moi les fichiers déplacés findFilesContainingMotifs(path, motifs).each { println it }</code></pre> </div> </div> https://cheroliv.com/blog/2019/0005_groovy_manipulation_files_post.html Thu, 18 Jul 2019 00:00:00 +0000 blog/2019/0005_groovy_manipulation_files_post.html <div class="paragraph"> <p>这里我将关注在构建项目中加载属性https://docs.gradle.org/current/userguide/userguide.html[Gradle]<br> 即使此项不在代码中可用。<br> 该属性将在 ~/.gradle/gradle.properties 目录下的 gradle.properties 文件中定义。<br> ~ 是符号变量 HOME_PATH 的快捷方式，表示会话用户根目录： lehttps://fr.wikipedia.org/wiki/R%C3%A9pertoire_personnel[主目录].<br> 同样地在一个构建项目https://maven.apache.org/guides/index.html[行家], 与 `~/.m2/settings.xml 此脚本的目的是删除匹配所列模式的文件<br> 在变量strCriteria中。 为此我将使用这些https://fr.wikipedia.org/wiki/Fermeture_(informatique)[闭包]: 每个, 查找所有, 收集<br> 以及 StringTokenizer 类，它将把我的条件字符串分割成若干块<br> 为了检索一个字符串列表。 如果我的待清理文件夹中的某个文件的名称包含了某个模式<br> 那么它将成为破坏的候选者，通过被添加到结果列表中。<br> 并且在最后一行有一个小例子https://en.wikipedia.org/wiki/Elvis_operator[Elvis 运算符]<br> filemanip.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy //Mes criteres de selection des fichiers à detruire String strCriteria = "Dummies Dummie ajax Objective-C Windows blackberry " + "wordpress joomla ios c# f# rails ruby flex asp flash Dreamweaver adobe " + "CoffeeScript c++ .chm .epub .rar .zip .tar drupal drupals .net php javascript " + ".js iphone ipad js _js facebook gwt vaadin linq python py zope window " + "3D scala gaming active_directory tomcat jboss glassfish microsoft 2d " + "lego blogger blog cocoa dojo dom dotnetnuke eclipse .gz unity sharepoint " + ".tgz iwork filemaker .doc .txt" //repertoire personnel String userDir = System.getProperty("user.home") //un separateur de chemin crossplatform String sep = System.getProperty("file.separator") //la variable symbolique String sym_books_vrac_path = "books_vrac_path" //le chemin de mon fichier gradle.properties hors projet String propertiesFilePath = userDir .concat("${sep}.gradle${sep}gradle.properties") File propertiesFile = new File(propertiesFilePath) //je m'aassure que le fichier existe et que ce n'est pas un dossier assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() //on boucle avec un inpustream sur le fichier //gradle.properties pour peupler ma variable gradleProperties propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } //le chemin du dossier books_vrac est la valeur de notre clé books_vrac_path String pathVracDir = gradleProperties.get(sym_books_vrac_path) //j'ai récuperé tous ces livres en tapant cette commande dans le terminal //wget -m -np -c -R "index.html*" "http://the-eye.eu/public/Books/IT%20Various/" //on ouvre le dossier dont le chemin est dans la variable pathVracDir // on s'assure qu'il existe et que c'est un dossier File vracDir = new File(pathVracDir) assert vracDir.exists() && vracDir.directory //separer les élèments de ma liste de critère StringTokenizer tokenizer = new StringTokenizer(strCriteria) //la liste de critere List<String> criteriaList = new ArrayList<>() //j'itère sur les tokens et je construit ma liste de token, // mot clef critère de recherche tokenizer.each { String it -> criteriaList.add(it.toLowerCase()) } //je collect tous les noms de fichier dans le dossier List<String> fileNameList = vracDir .listFiles() .collect { File it -> it.directory ?: it.name } // je collect les noms de fichier qui contiendraient un des criteres List<String> resultList = fileNameList.findAll { String name -> criteriaList.findAll { String crit -> name.toLowerCase().contains(crit) } } // je parcours ma liste de résultat pour les effacer resultList.each { String fileName -> assert new File(vracDir.path + sep + fileName).delete() } println fileNameList.size() println resultList.size() resultList.empty ?: println(vracDir.path + sep + resultList.first())</code></pre> </div> </div> https://cheroliv.com/blog/2019/0004_groovy_replace_string_load_properties_post.html Wed, 17 Jul 2019 00:00:00 +0000 blog/2019/0004_groovy_replace_string_load_properties_post.html <div class="paragraph"> <p>这是一段可运行的 Groovy 代码，<br> 要替换字符串中所有字符序列的出现<br> 并将一个 .properties 文件加载到 properties 对象中。<br> 在字符串中执行命令。<br> replaceTextinFile.groovy<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy println System.getProperty("user.home") static String getSeparator_() { System.getProperty("file.separator") } String separator = separator_ String path = System.getProperty("user.home") .concat("${separator}.gradle" + separator + "gradle.properties") File propertiesFile = new File(path) assert propertiesFile.exists() && !propertiesFile.directory Properties gradleProperties = new Properties() propertiesFile.withInputStream { InputStream it -> gradleProperties.load(it) } String user_name = gradleProperties.getProperty("user_name") String text String resultText text = new File("${System.getProperty("user.home")}" + separator + "src" + separator + "cheroliv.github.io" + separator + "src" + separator + "main" + separator + "resources" + separator + "eco_space.txt").text String to = separator + "media" + separator + "${user_name}" + separator + "320" + separator + "videoCours" + separator String from = "${System.getProperty("user.home")}" + separator + "p2p" + separator resultText = text.replace(to, from) println resultText //execute command line in a string println "rsync -avr ${resultText} ${to}".execute().text</code></pre> </div> </div> https://cheroliv.com/blog/2019/0003_groovy_char_ascci_post.html Wed, 10 Jul 2019 00:00:00 +0000 blog/2019/0003_groovy_char_ascci_post.html <div class="paragraph"> <p>这是一个在 Groovy 中能正常工作的代码片段，它会生成一个文本文件，<br> 带有 ASCII 表的前 256 个可读字符<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-groovy" data-lang="groovy">#!/usr/bin/env groovy import java.nio.charset.StandardCharsets List<Character> chars = new ArrayList<>() int j = 0 Character jumpLine = '\n' 256.times { Integer idx -> if (Character.isAlphabetic(idx) || Character.isDigit(idx)) { if (j % 10 == 0 && j != 0) { chars.add(jumpLine) chars.add(idx as char) } else chars.add(idx as char) j++ } } String seperator = System.getProperty("file.separator") String path = "${System.getProperty("user.home")}${seperator}ascii.txt" File speCharFile = new File(path) if (speCharFile.exists() && !speCharFile.directory) { speCharFile.text = "" } else { speCharFile.createNewFile() } String text = new String() chars.each { Character it -> text = it == jumpLine ? "$text$it" : "$text $it " } speCharFile.setText(text, StandardCharsets.UTF_8.toString())</code></pre> </div> </div> <div class="paragraph"> <p>我把文件命名为 spe_char.groovy,<br> 从文件所在的文件夹<br> 打开终端并复制粘贴以执行脚本<br></p> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-bash" data-lang="bash">$ groovy spe_char.groovy</code></pre> </div> </div> <div class="paragraph"> <p>结果:</p> </div> <div class="paragraph"> <p>0 1 2 3 4 5 6 7 8 9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z ª µ º À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ð Ñ Ò Ó Ô Õ Ö Ø Ù Ú Û Ü Ý Þ ß à á â ã ä å æ ç è é ê ë ì í î ï ð ñ ò ó ô õ ö ø ù ú û ü ý þ ÿ</p> </div>