Instalação¶

Instalar o flower exige apenas Python ≥ 3.10. A única dependência de runtime é claude-agent-sdk — o binário nativo que faz as requisições já vem dentro da wheel dele, então não é preciso instalar Node nem o Claude Code CLI. Esta página percorre tudo do zero: instalação em uma linha, instalação a partir do código-fonte, a primeira configuração de credenciais e um comando que prova que "instalou mesmo". Depois que isso funcionar, vá para o Começo rápido.

Antes de instalar: confira o Python¶

python3 -c 'import sys; print(sys.version_info >= (3, 10), sys.version.split()[0])'

Uma saída como True 3.13.7 já basta. Se sair False ou se python3 nem existir, instale um antes (brew install python / apt install python3), senão o script de instalação sai na hora.

Nome do pacote flower, versão 0.1.0, única dependência de runtime claude-agent-sdk>=0.2.152 (pyproject.toml:2-6). mkdocs-material só é usado no CI para construir o site de documentação; para rodar o flower não é preciso.

Instalação em uma linha¶

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

Terminada a instalação, o terminal deve mostrar algo assim (sem as cores):

== 用 uv 安装 flower…

== 装好了 /Users/you/.local/bin/flower

下一步:
  cd 到任意项目目录,然后:  flower
  第一次会问你要 API key / 网关地址,配一次存到 ~/.config/flower/.env,处处生效。
  本机已经装了 Claude Code 并配好的话,flower 会直接借它的 token,连问都不问。

  文档:https://chenyuheee.github.io/flower/

O que importa é a linha == 装好了 <caminho absoluto> — ela é o resultado de o próprio script ter rodado um command -v flower (install.sh:60-61). Se o caminho foi impresso, flower já está no PATH.

O que o instalador realmente faz¶

O install.sh faz só três coisas: escolhe um instalador de ferramentas Python, instala a partir do GitHub e diz qual é o próximo passo. Ele não toca em uma única letra das suas credenciais (install.sh:7-8). A fonte de instalação é fixa: git+https://github.com/ChenyuHeee/flower.git (install.sh:11).

O instalador tenta em ordem e para na primeira que funcionar (install.sh:33-57):

Nos quatro casos instala-se o mesmo console script: flower = "flower.cli:main" (pyproject.toml:12). Depois de instalado também dá para chamar com python -m flower.cli, com o mesmo efeito (cli.py:1451-1452).

Como o comando flower entra no PATH¶

Quando command -v flower não encontra nada, o script sugere adicionar $HOME/.local/bin ao ~/.zshrc ou ~/.bashrc (install.sh:62-70):

export PATH="$HOME/.local/bin:$PATH"

Tanto uv tool install quanto pipx install colocam o binário ali, então para eles a dica está correta. Mas o caso 4 (pip install --user) nem sempre — o diretório dessa mensagem está fixo no código, enquanto o diretório de scripts de usuário do pip depende da plataforma. No macOS ele é ~/Library/Python/3.13/bin. Confira você mesmo:

python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))"

A saída pode ser, por exemplo, /Users/you/Library/Python/3.13/bin — adicione esse diretório ao PATH, não ~/.local/bin, e depois reabra o terminal ou dê um source.

Instalar a partir do código-fonte¶

Se você quer ler o código, alterar o framework ou rodar as verificações offline de tests/, instale a partir do código-fonte:

git clone https://github.com/ChenyuHeee/flower.git
cd flower
python3 -m venv .venv
.venv/bin/pip install -e .

Feito isso, .venv/bin/flower --help deve imprimir as linhas de usage.

O shebang daquele executável dentro do venv é um caminho absoluto, então não é preciso ativar o venv; basta um symlink para usá-lo em qualquer diretório:

mkdir -p ~/.local/bin
ln -sf "$PWD/.venv/bin/flower" ~/.local/bin/flower

Com ~/.local/bin no PATH, cd para qualquer diretório de projeto e digite flower: vai rodar o interpretador desse venv e esse código-fonte.

A instalação a partir do código-fonte ainda traz um lugar a mais para as credenciais: o .env na raiz do repositório (é o 5º na ordem de busca, veja Configuração · Prioridade de busca de credenciais). Durante o desenvolvimento:

cp .env.example .env        # preencha ANTHROPIC_AUTH_TOKEN

O .env já está no .gitignore e não entra no controle de versão. O flower instalado por pip / pipx / uv não tem esse lugar disponível — ele fica em site-packages, não existe "raiz do repositório" — então nesse tipo de instalação use o arquivo global de credenciais descrito abaixo.

Atualização automática¶

O flower ainda está iterando rápido, então a instalação feita por pip / pipx / uv se atualiza sozinha por padrão: quem instalou uma versão de três dias atrás pode reportar um bug que já foi corrigido há muito tempo, e os dois lados perdem tempo. Isso não vem em forma de pergunta "quer ativar?" — vem ativado por padrão, e para desligar você define uma variável de ambiente.

O que ele faz (update.py:116-129):

1. A cada inicialização do flower, consulta em uma thread em segundo plano o commit mais recente de main no GitHub (update.py:70-80). O fluxo principal não espera nem um segundo — essa é a primeira invariante.
2. Se for diferente do commit instalado localmente, roda um comando de atualização conforme o método de instalação original: com uv, usa uv tool install --force; com pipx, pipx install --force; sem nenhum dos dois, pip install --user --upgrade (update.py:83-93).
3. Mesmo depois de instalada, a nova versão não substitui o processo em execução — só o próximo flower usa a versão nova (update.py:113). Ser trocado no meio da execução é um dos tipos de falha mais difíceis de investigar.
4. Throttle: no máximo uma consulta a cada 24 horas, com o timestamp gravado em ~/.config/flower/.update (update.py:32, :36-37, :124).
5. Toda falha é silenciosa. Sem rede, GitHub fora do ar, instalação que não completa — nada disso interrompe seu trabalho (update.py:79, :108-110).

Quem roda a partir do código-fonte (git) não é afetado. A etapa do comando de atualização primeiro verifica se existe .git no repositório; se existir, retorna None na hora e não faz nada (update.py:83-87) — sua árvore de trabalho é assunto do git, não dele. Em modo não interativo (stdin não é um terminal, por exemplo em pipe / CI) tudo isso é pulado (update.py:121).

Para desligar:

export FLOWER_NO_UPDATE=1

Qualquer valor não vazio conta (update.py:33, :121). Use em CI, ambientes offline ou quando precisar reproduzir o comportamento de uma versão antiga.

Primeira execução: configurar as credenciais¶

As três entradas de execução — go, run e once — chamam ensure_credentials() logo no início (cli.py:1192, :1160, :1225), com dois portões:

1. Existe ou não — busca na ordem de prioridade; se não achar, pergunta a você na hora.
2. Funciona ou não — faz uma chamada de verdade à API. Uma requisição mínima com max_tokens=16 (env.py:120-123), praticamente sem custo. Token expirado, endereço de gateway digitado errado — isso não se descobre olhando variáveis de ambiente; sem a sondagem, o erro só estouraria minutos depois.

Sem credenciais, a primeira execução do flower para nesta tela (cli.py:1358-1388):

== 配置 flower ========================================
第一次用?给一次凭证就行。
凭证会存到 /Users/you/.config/flower/.env(只你可读)。装一次,处处生效。

1. 你的 API key 或网关 token (Anthropic 官方的 sk-ant-… 或第三方网关签发的)
   >

2. 网关地址 (直接回车 = Anthropic 官方;第三方网关填它的 BASE_URL)
   >

3. 模型名 (直接回车 = 默认;网关有自己的模型名就填,如 claude-opus-5[1m])
   >

+ 存好了:/Users/you/.config/flower/.env

A pergunta 1 é obrigatória; deixar em branco imprime em vermelho 没给 token,取消。 e sai. Nas perguntas 2 e 3 basta dar Enter. Se usa o endpoint oficial, deixe a pergunta 2 vazia; para um gateway de terceiros, informe o endereço raiz dele, sem /v1 — a sondagem do flower chama <BASE_URL>/v1/messages (env.py:162).

As chaves gravadas depois das respostas (cli.py:1378-1386):

O arquivo fica em ${XDG_CONFIG_HOME:-~/.config}/flower/.env (env.py:39-42), é sobrescrito por inteiro e, ao final, recebe chmod 0o600 (cli.py:1336-1347). É esse o arquivo do "configure uma vez, vale em todo lugar" — trocar de diretório de projeto não exige reconfigurar; o significado de cada variável está em Configuração.

Se a máquina já tem o Claude Code instalado, talvez ele não pergunte nada¶

A busca de credenciais tem um fallback final: lê ~/.claude/settings.json e depois ~/.claude/settings.local.json, pegando 9 chaves de credencial do bloco env deles (env.py:56-75, :109-111). Quem já tem o Claude Code configurado na máquina pode simplesmente rodar flower e começar a trabalhar; a tela de configuração nem aparece — é exatamente isso que o install.sh:77 anuncia.

Quando você quiser reconfigurar¶

O subcomando flower setup está registrado (cli.py:1326-1328), mas _CMDS esqueceu dele (cli.py:937), então flower setup é reescrito para flower go setup — tratando "setup" como um pedido e rodando o workflow inteiro. No momento não existe nenhuma forma de linha de comando que chegue àquele subcomando, embora vários textos de erro ainda mandem você rodá-lo. Para trocar as credenciais:

$EDITOR ~/.config/flower/.env

Ou apague o token daquele arquivo e rode flower de novo — o portão da credencial ausente vai perguntar outra vez (desde que também não exista em outro lugar, como ~/.claude/settings.json). Quando a credencial é rejeitada (HTTP 401 / 403), a mesma tela aparece na hora para você reconfigurar, com no máximo uma chance (cli.py:1416-1428).

Verificar se instalou¶

Dois níveis, do mais barato ao mais caro.

Nível 1 — o comando existe (sem custo):

flower --help

Ver estas linhas significa que o console script está instalado e no PATH:

usage: flower [-h] [-w WORKSPACE] [-r RUN_DIR] [-v] [-W] [-T]
              {go,run,once,setup} ...

可移植长程 agent 框架

Nível 2 — credenciais, endpoint e binário nativo, tudo funcionando (alguns centavos): a execução real mais barata é once — um único agent, por padrão apenas as três ferramentas somente leitura Read / Glob / Grep, sem goal guard, sem workbench:

flower -v -w /path/to/any/repo once "读一眼这个仓库,一句话说它是干什么的"

-v imprime a configuração em vigor antes de começar a rodar, mantendo só os 4 primeiros caracteres do token (cli.py:1445-1447; env.py:197-211):

ANTHROPIC_AUTH_TOKEN = sk-1***(共 108 位)
ANTHROPIC_BASE_URL = https://cloud.infini-ai.com/maas
ANTHROPIC_MODEL = claude-opus-5[1m]

Essas linhas confirmam que você não se conectou ao gateway errado. Em seguida vêm a sondagem de credenciais e a execução de verdade:

- 验一下凭证…
  * Read /path/to/any/repo/README.md
  这个仓库是……
  + 完成 1 轮 · $0.1741 · 用时 0:00

Não há cabeçalho de step. O once passa por _run_once → rt.run(), sem _drive / Workflow.run, e o Event("step", …) só é emitido em workflow/base.py:220 — portanto linhas separadoras como == 步骤名 ===== 1/1 não aparecem no once; só existem em go / run.

Se a linha + 完成 aparecer, passou, e ela prova três coisas ao mesmo tempo: as credenciais funcionam, o endpoint está acessível e o binário nativo dentro da wheel do claude-agent-sdk roda nesta máquina. Se depois de - 验一下凭证… vier ! 凭证被拒 ou ! 网关地址或模型名不对, vá para a tabela de diagnóstico abaixo.

Quando não instala¶

Próximo passo¶

• Começo rápido — entre em um diretório de projeto e faça o primeiro trabalho real.
• Configuração — todas as variáveis de ambiente, prioridade de credenciais, sintaxe do .env, o que fica em disco.
• Linha de comando — todos os subcomandos e flags.
• Deploy — rodar em contêiner, distribuir capacidades de domínio via plugin.
• Glossário — o significado exato de cada termo da documentação.