Déploiement et extension¶

Porter flower ailleurs demande de régler trois choses : le conteneur (enfermer le Bash non restreint, et au passage vérifier la formule « sans CLI »), le plugin (les capacités métier suivent le dépôt, sans regarder ce qui est installé sur la machine hôte), le site de documentation (un push sur main publie automatiquement, install.sh est servi depuis le domaine Pages). Les trois sections sont indépendantes, lisez celle dont vous avez besoin.

1. Le conteneur¶

Pourquoi un conteneur¶

Premièrement, pour enfermer. L'exécutant qui travaille dispose d'un Bash non restreint — la liste blanche Bash de flower (delegate_guard) ne couvre que le thread principal, et celui qu'on envoie au front doit pouvoir lancer les tests : c'est intentionnel. Dans le conteneur, seul votre répertoire de projet est monté ; le code source du framework est dans l'image sous /opt/flower, et le reste de l'hôte est invisible.

Deuxièmement, c'est en soi la vérification de la contrainte de portabilité. L'image ne contient ni le CLI Claude Code, ni Node, seulement Python et claude-agent-sdk — les requêtes partent via le binaire natif embarqué dans la wheel. Si ça tourne ici, « sans CLI » n'est plus une affirmation sur le papier.

Vérifié en conditions réelles (2026-09-06, macOS 15 / arm64 / colima + docker 28.4.0) :

Ce qu'il y a dans l'image¶

Image de base python:3.13-slim, par-dessus laquelle apt n'installe que trois paquets. Chacun a sa raison :

Le code source du framework entre dans l'image par COPY, pas par bind mount — c'est pourquoi l'agent dans le conteneur ne peut pas toucher au code source du framework sur l'hôte :

Le point d'entrée est ENTRYPOINT ["flower"], CMD est vide — lancer le conteneur sans argument ouvre la saisie interactive (il vous demande ce que vous voulez faire) au lieu d'afficher --help. On évite ainsi d'avoir à mettre une demande en français entre guillemets dans le shell.

Pourquoi on ne peut pas monter le .venv de l'hôte¶

Le SDK publie une wheel par plateforme, et le binaire embarqué est spécifique à la plateforme :

Hôte       claude_agent_sdk-0.2.152-py3-none-macosx_11_0_arm64.whl
           → _bundled/claude est un Mach-O 64-bit arm64, 191M
Conteneur  claude_agent_sdk-0.2.152-py3-none-manylinux_2_17_aarch64.whl

Monté tel quel, ça ne tourne pas : l'image doit donc faire son propre pip install. Inversement, c'est aussi une preuve de portabilité : même pyproject.toml, on change de plateforme, on change de binaire natif, et pas une ligne du code du framework ne bouge.

Les deux scripts¶

Les réglages de docker/build passent tous par des variables d'environnement :

Les trois dernières n'ont d'effet que si FLOWER_MIRRORS=1 — la branche FLOWER_MIRRORS=0 ne définit tout simplement aucun build-arg.

docker/flowerbox en reconnaît deux :

FLOWER_HOME est déduit de l'emplacement du script lui-même, aucun chemin n'est codé en dur : le dépôt fonctionne quel que soit l'endroit où on l'a cloné.

Construire l'image et lancer le conteneur¶

docker/build                          # une seule fois suffit
cd ~/un-projet-quelconque             # doit être sous $HOME, voir la frontière de montage ci-dessous
/path/to/flower/docker/flowerbox      # sans argument → il vous demande quoi faire, pas de guillemets à poser

Si le réseau vers pypi.org / Docker Hub fonctionne normalement, la construction se fait ainsi :

FLOWER_MIRRORS=0 docker/build

Les arguments de flowerbox sont exactement ceux de flower — il colle "$@" tel quel derrière l'ENTRYPOINT. --clarify-only, --asks N, --timeout 秒, --isolate, -v passent tous ; tableau complet dans ligne de commande :

cd ~/proj
/path/to/flower/docker/flowerbox --clarify-only -v
/path/to/flower/docker/flowerbox "fais-moi un X"

Ce qui est réellement exécuté, c'est cette ligne (-t n'est ajouté qu'en présence d'un TTY, voir plus bas) :

docker run -i $TTY --rm \
    --env-file "$FLOWER_HOME/.env" \
    -v "$PWD:/work" \
    -w /work \
    "$IMAGE" "$@"

Frontière de montage et persistance¶

Hôte $PWD  ──monté──>  /work       ← l'agent travaille ici, les productions restent sur l'hôte
Dans l'image           /opt/flower ← code source du framework, **non monté**, impossible d'atteindre celui de l'hôte

Lancer depuis un sous-répertoire du dépôt comme flower/human-test/HT001 est donc sans danger : seul HT001 est monté, le code source du framework est hors du périmètre de montage.

Comment les identifiants entrent dans le conteneur¶

Via docker run --env-file, jamais dans les couches de l'image. flowerbox lit $FLOWER_HOME/.env, c'est-à-dire par défaut le .env à la racine du dépôt :

cp .env.example .env       # remplissez le token ; .env est déjà gitignoré

Attention : flower setup écrit dans ~/.config/flower/.env, et flowerbox ne regarde pas ce chemin. Si vous avez déjà configuré via setup et ne voulez pas dupliquer, pointez FLOWER_HOME dessus :

FLOWER_HOME=~/.config/flower /path/to/flower/docker/flowerbox

Noms des clés, ordre de priorité, comment renseigner la passerelle : voir configuration.

git submodule¶

.gitmodules ne contient qu'une entrée :

Un git clone ordinaire ne le récupère pas : human-test/HT001 est alors un répertoire vide (le - en tête de git submodule status correspond à cet état). Faut-il s'en occuper :

Réseau en Chine : pourquoi tous ces remplacements de miroirs¶

Quand on installe tout ça derrière le pare-feu, ce qui est lent n'est pas la bande passante mais les liaisons internationales. Le docker/build par défaut a déjà remplacé tout ce qui devait l'être, et FLOWER_MIRRORS=0 coupe tout d'un coup. Ci-dessous les mesures et le détail des quatre remplacements — inutile de lire si votre réseau n'a pas ce problème.

A=https://github.com/abiosoft/colima-core/releases/download/v0.9.0-2/ubuntu-24.04-minimal-cloudimg-arm64-docker.qcow2
mkdir -p ~/.colima/images
curl -sSL -C - -o ~/.colima/images/colima-arm64-docker.qcow2 "https://ghfast.top/$A"
# Vérification : le digest vient de l'API GitHub. Ne sautez pas cette étape — c'est ce qui va tourner comme VM
curl -sSL https://api.github.com/repos/abiosoft/colima-core/releases/tags/v0.9.0-2 \
  | python3 -c "import json,sys;[print(a['digest'],a['name']) for a in json.load(sys.stdin)['assets'] if a['name'].endswith('arm64-docker.qcow2')]"
shasum -a 256 ~/.colima/images/colima-arm64-docker.qcow2

colima start --disk-image ~/.colima/images/colima-arm64-docker.qcow2 \
             --cpu 4 --memory 6 --disk 20

export LIMA_HOME=~/.colima/_lima
limactl shell colima -- sudo sh -c '
  cat > /etc/apt/sources.list.d/ubuntu.sources <<EOF
Types: deb
URIs: https://mirrors.ustc.edu.cn/ubuntu-ports/
Suites: noble noble-updates noble-backports noble-security
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
EOF
  sed -i "s|https://download.docker.com|https://mirrors.ustc.edu.cn/docker-ce|g" \
      /etc/apt/sources.list.d/docker.list
  pkill -f "apt-get update"          # boot.sh ira jusqu au bout et écrira le marqueur de fin
'
# colima start sort alors normalement ; ensuite on rattrape rsync (maintenant à 1.95 MB/s)
limactl shell colima -- sudo sh -c 'apt-get update -q && apt-get install -y -q rsync'

2. plugin¶

Ce qu'est un plugin, et comment le SDK le charge¶

C'est le paquet de capacités métier qui suit le dépôt. Le code du framework ne contient aucune connaissance métier ; toute la connaissance métier vit dans le répertoire plugin/ à la racine du dépôt, clonée avec le code, relue avec le code, taguée avec le code.

Côté SDK, le câblage tient en deux lignes dans build_options(), dans flower/core/agent.py :

PLUGIN_DIR = Path(__file__).resolve().parent.parent.parent / "plugin"
...
if use_plugin and PLUGIN_DIR.is_dir():
    opts["plugins"] = [{"type": "local", "path": str(PLUGIN_DIR)}]

Combiné à setting_sources=[] (traité séparément plus bas), c'est ce qui permet à flower d'être à la fois portable et « au fait de votre métier » : il ne demande pas ce qui est installé sur la machine hôte, il ne connaît que ce seul répertoire apporté par le dépôt.

Disposition des répertoires¶

La différence entre probabiliste et déterministe est le critère de choix, pas une nuance de vocabulaire :

• un skill est de la connaissance posée là. Le modèle voit sa description et ne va la lire que s'il la juge pertinente pour la tâche en cours. Le jugement de pertinence est fait par le modèle, donc la même demande lancée deux fois peut l'utiliser une fois et pas l'autre.
• un hook est du code. Il s'exécute dès que l'événement correspond, indépendamment de ce que le modèle veut ou sait. Le déversement et l'isolation de flower sont des hooks, précisément parce qu'ils ne peuvent pas « s'appliquer parfois ».

Le critère est donc unique : est-ce que cette chose doit arriver à chaque fois ? Si oui — écrivez un hook. Si c'est seulement « bon à savoir » — écrivez un skill. Écrire en skill une chose obligatoire, c'est parier la discipline sur un jugement unique du modèle.

Aujourd'hui, le plugin/ du dépôt ne contient que deux choses : .claude-plugin/plugin.json et skills/example/SKILL.md. agents/, hooks/, .mcp.json n'existent pas encore — créez-les vous-même si vous en avez besoin, avec exactement les noms de répertoires du tableau ci-dessus.

Écrire un skill : exemple complet¶

Prenons « générer les notes de version », de zéro jusqu'à la confirmation que ça marche.

Première étape : créer le répertoire. Le nom du répertoire est le nom du skill, identique au name du frontmatter.

mkdir -p plugin/skills/release-notes

Deuxième étape : écrire plugin/skills/release-notes/SKILL.md. Le nom du fichier doit être SKILL.md, en majuscules. Le format est un frontmatter YAML + un corps Markdown ; le frontmatter a deux champs :

Un fichier minimal directement utilisable :

---
name: release-notes
description: À utiliser pour rédiger des notes de version. Quand l'utilisateur dit « écris les release notes », « qu'est-ce qui a changé dans cette version », « on publie ».
---

# Notes de version

## Où prendre la matière

```bash
git describe --tags --abbrev=0        # tag précédent
git log --oneline <上一个 tag>..HEAD   # les commits de cette version
```

## Format de sortie

Trois sections, chacune une liste à puces, une ligne par entrée, décrivant des changements
perceptibles par l'utilisateur, jamais les refactorings internes :

- **Nouveautés** — ce que cette version permet de faire et qu'on ne pouvait pas faire avant
- **Corrections** — ce qui a été corrigé, symptôme décrit en une phrase
- **Ruptures de compatibilité** — ce qu'il faut modifier à la main pour monter de version. S'il n'y en a pas, on omet toute la section

## Limites

- N'inventez pas le numéro de version, lisez-le dans le champ `version` de `pyproject.toml`.
- Si vous ne savez pas si un commit est perceptible par l'utilisateur, listez-le et posez la question, ne décidez pas à sa place.

Le corps n'a pas de format imposé — c'est juste un texte lu dans le contexte. Suivez la manière de plugin/skills/example/SKILL.md : dire clairement quand l'utiliser, les étapes, la forme du résultat, où sont les limites est plus utile qu'empiler des connaissances de fond.

Troisième étape : confirmer qu'il est bien chargé. On ne vérifie qu'une chose certaine — le répertoire existe-t-il, oui ou non :

cd /path/to/flower
python3 -c "from flower.core.agent import PLUGIN_DIR; print(PLUGIN_DIR, PLUGIN_DIR.is_dir())"

Ce n'est que si ça affiche /path/to/flower/plugin True que le if de build_options() sera pris. Si ça affiche False, ce n'est pas chargé, et aucune erreur ne sera levée à l'exécution : voir l'avertissement ci-dessous.

Ne prenez pas « je lance une demande et je regarde si le skill example a été invoqué » pour une vérification. Un skill est probabiliste : si le modèle ne l'a pas appelé, ça peut être qu'il n'est pas installé, ou simplement qu'il n'a pas jugé la tâche concernée — ce signal ne distingue pas les deux cas. De plus, build_options() ne définit jamais l'option skills= du SDK au niveau de la session ; savoir si les skills du plugin apparaissent réellement dans la liste des options du coordinateur n'a jamais été vérifié en pratique. Le True/False de PLUGIN_DIR ci-dessus est certain : utilisez celui-là.

Pour désigner nommément les skills ouverts à un exécutant donné, utilisez worker(..., skills=[...]) (flower/core/roles.py) ; le nom est le name du SKILL.md, et le SDK accepte aussi la forme qualifiée nom_du_plugin:nom_du_skill.

Pourquoi setting_sources=[] force les capacités métier à passer par le plugin¶

La même fonction contient aussi cette ligne :

"setting_sources": [] if portable else ["project"],

Le défaut du SDK est None = les trois sources sont lues : ~/.claude/settings.json (utilisateur), .claude/settings.json (projet), .claude/settings.local.json (local). flower passe [] par défaut, ce qui les coupe toutes.

Que .claude/ n'ait aucun effet n'est pas un oubli de configuration, c'est la définition de la contrainte : dès qu'on lit un seul octet depuis la machine hôte, « comportement identique en changeant de machine » ne tient plus. Les capacités métier n'ont donc qu'un seul canal — le plugin/ qui suit le dépôt.

Deux interrupteurs (tous deux sur build_options(), avec les valeurs par défaut de la portabilité) :

Au passage : instructions passe par l'append (le append du system_prompt), ce sont deux canaux distincts du plugin — le premier est dans le contexte à chaque tour, le second se charge à la demande. Une discipline courte et obligatoire va dans instructions ; une connaissance longue et occasionnellement utile va dans un skill.

3. Le site de documentation¶

Le site que vous lisez est construit avec mkdocs-material ; les sources sont dans docs/ du dépôt, et un push sur main publie automatiquement.

Modifier la documentation en local :

pip install -r docs-requirements.txt
mkdocs serve                  # prévisualisation locale
mkdocs build --strict         # à lancer avant de commiter, c'est la commande de la CI

La CI se déclenche sur un push vers main et si les modifications touchent ces chemins ; sinon on peut lancer manuellement un workflow_dispatch depuis la page Actions :

docs/**  mkdocs.yml  hooks/**  docs-requirements.txt  install.sh  .github/workflows/docs.yml

Pourquoi install.sh est publié depuis Pages¶

L'étape de construction se termine par cette ligne :

- run: cp install.sh site/install.sh

Le script d'installation est glissé dans l'artefact du site, il est donc servi depuis le domaine de la documentation, et l'installation en une ligne ressemble à ceci :

curl -fsSL https://chenyuheee.github.io/flower/install.sh | sh

La raison est très concrète : raw.githubusercontent.com est inaccessible en Chine, alors que *.github.io passe (mesuré). Le script lui-même reste à la racine du dépôt, on en fait simplement une copie à la publication — pas deux contenus à maintenir, pas de CDN supplémentaire.

Ce que install.sh fait de son côté : choisir un installeur d'outils Python (uv > pipx > installer uv > pip --user), installer flower depuis GitHub, puis indiquer l'étape suivante. Il ne touche pas aux identifiants — le premier lancement de flower les demande et les enregistre dans ~/.config/flower/.env.