Despliegue y extensión¶

Llevar flower a otro sitio implica tres cosas: el contenedor (encerrar el Bash sin restricciones y, de paso, comprobar aquello de "sin depender del CLI"), los plugin (las capacidades de dominio viajan con el repositorio, sin mirar qué hay instalado en el anfitrión) y el sitio de documentación (push a main y se publica solo; install.sh cuelga del dominio de Pages). Las tres secciones son independientes; lee la que necesites.

1. Contenedor¶

Por qué un contenedor¶

Primero, para encerrarlo. El worker que hace el trabajo tiene Bash sin restricciones —— la lista blanca de Bash de flower (delegate_guard) solo cubre el main thread; quien sale delegado tiene que poder ejecutar pruebas, así que es intencionado. En el contenedor solo se monta el directorio de tu proyecto; el código fuente del framework vive en /opt/flower dentro de la imagen, y del anfitrión no se ve nada más.

Segundo, es en sí mismo la comprobación de la restricción de portable. En la imagen no hay Claude Code CLI, no hay Node, solo Python y claude-agent-sdk —— las peticiones salen por el binario nativo que trae la propia wheel. Si aquí arranca, "sin depender del CLI" deja de ser una afirmación sobre el papel.

Verificado en la práctica (2026-09-06, macOS 15 / arm64 / colima + docker 28.4.0):

Qué lleva instalado la imagen¶

Imagen base python:3.13-slim, y encima apt instala solo tres paquetes. Cada uno tiene su motivo:

El código fuente del framework entra en la imagen por COPY, no por bind mount —— por eso el agent del contenedor no puede tocar el código fuente del framework en el anfitrión:

El entrypoint es ENTRYPOINT ["flower"] y CMD está vacío —— al ejecutar el contenedor sin argumentos entra en modo interactivo (te pregunta qué quieres hacer) en lugar de imprimir --help. Así no hace falta entrecomillar en el shell una petición escrita en chino.

Por qué no se puede montar el .venv del anfitrión¶

El SDK publica wheels por plataforma, y el binario que traen es específico de cada plataforma:

宿主   claude_agent_sdk-0.2.152-py3-none-macosx_11_0_arm64.whl
       → _bundled/claude 是 Mach-O 64-bit arm64,191M
容器   claude_agent_sdk-0.2.152-py3-none-manylinux_2_17_aarch64.whl

Montado no funciona, así que la imagen tiene que hacer su propio pip install. Visto al revés, esto también es prueba de portabilidad: con el mismo pyproject.toml, cambiar de plataforma cambia el binario nativo y no hay que tocar ni una línea del código del framework.

Los dos scripts¶

Los interruptores de docker/build, todos por variables de entorno:

Las tres últimas solo tienen efecto con FLOWER_MIRRORS=1 —— la rama de FLOWER_MIRRORS=0 sencillamente no define ningún build-arg.

docker/flowerbox reconoce dos:

FLOWER_HOME se deduce de la ubicación del propio script, sin rutas fijas, así que funciona clones el repositorio donde lo clones.

Construir la imagen y levantar el contenedor¶

docker/build                       # 一次就够
cd ~/任意项目目录                   # 必须在 $HOME 下面,见下面的挂载边界
/path/to/flower/docker/flowerbox   # 不带参数 → 它问你要做什么,不用打引号

Si la red a pypi.org / Docker Hub va bien, la construcción se lanza así:

FLOWER_MIRRORS=0 docker/build

Los argumentos de flowerbox son exactamente los de flower —— pasa "$@" tal cual detrás del ENTRYPOINT. --clarify-only, --asks N, --timeout segundos, --isolate, -v valen todos; la tabla completa está en línea de comandos:

cd ~/proj
/path/to/flower/docker/flowerbox --clarify-only -v
/path/to/flower/docker/flowerbox "帮我做一个 X"

Lo que se ejecuta realmente es esta línea (-t solo se añade si hay TTY, ver más abajo):

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

Límites del montaje y persistencia¶

宿主 $PWD  ──挂载──>  /work       ← agent 在这里干活,产出留在宿主
镜像内                /opt/flower ← 框架源码,**没挂载**,改不到宿主

Por eso también es seguro ejecutarlo dentro de un subdirectorio del repositorio como flower/human-test/HT001: lo único montado es HT001, y el código fuente del framework queda fuera del ámbito del montaje.

Cómo entran las credenciales en el contenedor¶

Por docker run --env-file, no entran en las capas de la imagen. flowerbox lee $FLOWER_HOME/.env, que por defecto es el .env de la raíz del repositorio:

cp .env.example .env       # 填 token;.env 已被 gitignore

Ojo: flower setup escribe en ~/.config/flower/.env, y esa ruta flowerbox no la mira. Si ya lo configuraste con setup y no quieres duplicar el fichero, apunta FLOWER_HOME allí:

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

Nombres de clave, prioridad y cómo rellenar la pasarela: ver configuración.

git submodule¶

En .gitmodules solo hay una entrada:

Un git clone normal no lo trae, y human-test/HT001 es un directorio vacío (el - delante en git submodule status es justo ese estado). Si te importa o no:

Red en China: por qué toda esa tanda de espejos¶

Instalar todo esto detrás del muro no es lento por ancho de banda, sino por las rutas internacionales. El docker/build por defecto ya sustituye todo lo que hay que sustituir, y FLOWER_MIRRORS=0 lo desactiva todo de golpe. Abajo están las medidas reales y el porqué de las cuatro sustituciones —— si tu red no tiene este problema, no hace falta que lo leas.

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"
# 校验:digest 从 GitHub API 拿。别跳过 —— 这是要当 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 会继续走完并写完成标记
'
# colima start 随即正常退出;之后补上 rsync(现在 1.95 MB/s)
limactl shell colima -- sudo sh -c 'apt-get update -q && apt-get install -y -q rsync'

2. plugin¶

Qué es un plugin y cómo lo carga el SDK¶

Un paquete de capacidades de dominio que viaja con el repositorio. El código del framework no contiene ningún conocimiento de dominio; todo el conocimiento de dominio va en el directorio plugin/ de la raíz del repositorio, y se clona, se revisa y se etiqueta junto con el código.

El cableado del lado del SDK está en build_options(), en flower/core/agent.py, dos líneas:

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)}]

Junto con setting_sources=[] (explicado aparte más abajo), esta es la razón por la que flower puede a la vez ser "portable" y "entender tu dominio": no pregunta qué hay instalado en el anfitrión, solo reconoce ese único directorio que trae el repositorio.

Estructura de directorios¶

La diferencia entre probabilístico y determinista es la clave de la elección, no un matiz de redacción:

• Una skill es conocimiento puesto ahí. El modelo ve su description y solo va a leerla si le parece relevante para la tarea actual. El juicio de relevancia lo hace el modelo, así que la misma frase ejecutada dos veces puede usarla una vez y la otra no.
• Un hook es código. Si casa con el evento, se ejecuta, al margen de si el modelo quiere o si se entera. El spill y el isolation del propio flower son hooks, precisamente porque no pueden "activarse a veces".

Así que el criterio es uno solo: ¿esto tiene que ocurrir siempre? Si sí —— escribe un hook. Si solo es "viene bien saberlo" —— escribe una skill. Escribir como skill algo obligatorio equivale a apostar la disciplina a un único juicio del modelo.

Ahora mismo en el repositorio plugin/ solo tiene dos cosas: .claude-plugin/plugin.json y skills/example/SKILL.md. agents/, hooks/ y .mcp.json todavía no existen —— si los quieres, créalos tú, con los nombres de directorio exactos de la tabla de arriba.

Escribir una skill: ejemplo completo¶

Tomemos "generar notas de versión" como ejemplo, de cero hasta confirmar que está activa.

Paso uno: crear el directorio. El nombre del directorio es el nombre de la skill, y coincide con el name del frontmatter.

mkdir -p plugin/skills/release-notes

Paso dos: escribir plugin/skills/release-notes/SKILL.md. El nombre del fichero tiene que ser SKILL.md, en mayúsculas. El formato es frontmatter YAML + cuerpo Markdown, con dos campos en el frontmatter:

Un fichero mínimo listo para usar:

---
name: release-notes
description: 整理发版说明时使用。当用户说"写 release notes""这版改了什么""发版"时用它。
---

# 发版说明

## 怎么取素材

```bash
git describe --tags --abbrev=0        # 上一个 tag
git log --oneline <上一个 tag>..HEAD   # 这一版的提交
```

## 输出格式

按三段分,每段是无序列表,每条一行,写用户能感知的变化,不写内部重构:

- **新增** —— 这版能干什么以前干不了的事
- **修复** —— 修了什么,一句话说清症状
- **不兼容** —— 升级要动手改什么。没有就整段不写

## 边界

- 版本号不要自己编,从 `pyproject.toml` 的 `version` 读。
- 拿不准某条提交对用户有没有感知,列出来问,不要替用户决定。

El cuerpo no tiene formato obligatorio —— es simplemente un texto que se lee dentro del contexto. Toma como referencia plugin/skills/example/SKILL.md: dejar claro cuándo usarla, los pasos, cómo debe salir la salida y dónde están los límites es más útil que amontonar conocimiento de fondo.

Paso tres: confirmar que se ha cargado. Comprueba una sola cosa segura —— si el directorio existe o no:

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

Solo si imprime /path/to/flower/plugin True se entrará en aquel if de build_options(). Si imprime False, no está cargado, y en tiempo de ejecución no dará ningún error; ver el aviso más abajo.

No tomes como verificación "ejecuto una frase y miro si se invoca la skill example". Las skills son probabilísticas: que el modelo no la invoque puede significar que no está instalada o simplemente que no le pareció necesaria para la tarea —— esa señal no distingue entre las dos cosas. Además, build_options() nunca define la opción skills= a nivel de session del SDK, y si las skills del plugin aparecen o no en la lista de opciones del coordinator no se ha comprobado en la práctica. El True/False de PLUGIN_DIR de arriba sí es determinista: usa ese.

Para activar por nombre unas skills concretas en un worker, usa worker(..., skills=[...]) (flower/core/roles.py); el nombre es el name del SKILL.md, y el SDK también acepta la forma cualificada nombre-de-plugin:nombre-de-skill.

Por qué setting_sources=[] obliga a que las capacidades de dominio pasen por plugin¶

En la misma función está también esta línea:

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

El valor por defecto del SDK es None = leer los tres orígenes: ~/.claude/settings.json (usuario), .claude/settings.json (proyecto) y .claude/settings.local.json (local). flower pasa [] por defecto, y los desactiva todos.

Que .claude/ no tenga efecto no es una configuración que falte, es la definición de esta restricción: mientras se lea un solo byte del anfitrión, "el comportamiento es igual al cambiar de máquina" deja de sostenerse. Las capacidades de dominio tienen entonces un único canal: el plugin/ que viaja con el repositorio.

Dos interruptores (ambos en build_options(), y los valores por defecto son los de la portabilidad):

De paso: instructions va por append (el append del system_prompt), y es un canal distinto del plugin —— lo primero está en el contexto en cada turno, lo segundo se carga bajo demanda. La disciplina corta y obligatoria va en instructions; el conocimiento largo y de uso ocasional, en una skill.

3. Sitio de documentación¶

El sitio que estás leyendo está hecho con mkdocs-material; los ficheros fuente están en docs/ dentro del repositorio, y con un push a main se publica solo.

Editar la documentación en local:

pip install -r docs-requirements.txt
mkdocs serve                  # 本地预览
mkdocs build --strict         # 提交前跑一遍,和 CI 同一条命令

CI se dispara con un push a main y siempre que los cambios toquen estas rutas; además se puede lanzar a mano desde la página de Actions con workflow_dispatch:

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

Por qué install.sh se publica desde Pages¶

Al final del paso de construcción hay una línea:

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

El script de instalación se mete en el artefacto del sitio, así que cuelga del dominio del sitio de documentación, y la instalación en una línea queda así:

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

La razón es muy práctica: raw.githubusercontent.com no es accesible desde China, y *.github.io sí (medido). El script vive en la raíz del repositorio; solo se copia una vez más al publicar —— no hay que mantener dos contenidos ni hace falta una CDN adicional.

Lo que hace install.sh por sí mismo: elegir un instalador de herramientas Python (uv > pipx > instalar uv > pip --user), instalar flower desde GitHub y luego indicar el siguiente paso. No toca las credenciales —— la primera vez que ejecutes flower te preguntará y las guardará en ~/.config/flower/.env.