Установка¶

Для flower нужен только Python ≥ 3.10. Единственная runtime-зависимость — claude-agent-sdk; нативный бинарник, который отправляет запросы, лежит прямо в его wheel, поэтому ни Node, ни Claude Code CLI ставить не надо. Эта страница проходит путь с нуля: установка одной строкой, установка из исходников, первая настройка ключей и команда, которая доказывает, что «всё действительно встало». Когда заработает — переходите к Быстрому старту.

Перед установкой: проверьте Python¶

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

Вывод вроде True 3.13.7 — этого достаточно. Если печатается False или python3 вообще нет, сначала поставьте его (brew install python / apt install python3), иначе установочный скрипт просто выйдет.

Имя пакета flower, версия 0.1.0, единственная runtime-зависимость claude-agent-sdk>=0.2.152 (pyproject.toml:2-6). mkdocs-material нужен только в CI для сборки сайта документации, для запуска flower он не требуется.

Установка одной строкой¶

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

После установки в терминале должно быть примерно это (без цветов):

== 用 uv 安装 flower…

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

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

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

Ключевая строка — == 装好了 <абсолютный путь>: это результат того, что скрипт сам выполнил command -v flower (install.sh:60-61). Если путь напечатан, значит flower уже в PATH.

Что установщик делает на самом деле¶

install.sh делает всего три вещи: выбирает установщик Python-инструментов, ставит с GitHub и говорит, что дальше. Он не трогает ваши credentials ни единым символом (install.sh:7-8). Источник установки жёстко зафиксирован: git+https://github.com/ChenyuHeee/flower.git (install.sh:11).

Установщик пробует варианты по порядку и останавливается на первом сработавшем (install.sh:33-57):

Во всех четырёх случаях ставится один и тот же console script: flower = "flower.cli:main" (pyproject.toml:12). После установки его можно вызывать и через python -m flower.cli — эффект тот же (cli.py:1451-1452).

Как команда flower попадает в PATH¶

Если command -v flower ничего не находит, скрипт предлагает добавить $HOME/.local/bin в ~/.zshrc или ~/.bashrc (install.sh:62-70):

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

И uv tool install, и pipx install кладут файлы именно сюда, так что для них подсказка верна. Но для четвёртого пути (pip install --user) — не обязательно: каталог в этой подсказке зашит жёстко, а пользовательский каталог скриптов pip зависит от платформы. На macOS это ~/Library/Python/3.13/bin. Проверьте сами:

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

Вывод, например, /Users/you/Library/Python/3.13/bin — добавляйте в PATH именно этот каталог, а не ~/.local/bin, затем перезапустите терминал или сделайте source.

Установка из исходников¶

Если нужно читать код, менять фреймворк или запускать офлайн-проверки из tests/ — ставьте из исходников:

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

После этого .venv/bin/flower --help должен напечатать несколько строк usage.

У исполняемого файла в venv shebang — абсолютный путь, поэтому activate не нужен: достаточно символьной ссылки, и команда работает из любого каталога:

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

Если ~/.local/bin в PATH, то cd в любой каталог проекта и набранное flower пойдут через интерпретатор из этого venv и через эти исходники.

У установки из исходников есть ещё одно место для credentials: .env в корне репозитория (пятое место в порядке поиска, см. Конфигурация · Приоритет поиска credentials). При разработке:

cp .env.example .env        # впишите ANTHROPIC_AUTH_TOKEN

.env уже в .gitignore, в репозиторий он не попадёт. У flower, установленного через pip / pipx / uv, этого места нет — он лежит в site-packages, «корня репозитория» там не существует, — поэтому при такой установке используйте глобальный файл с credentials, описанный ниже.

Автообновление¶

flower пока быстро меняется, поэтому установка через pip / pipx / uv по умолчанию обновляет себя сама: баг, о котором сообщил человек с трёхдневной версией, может быть давно исправлен — и обе стороны теряют время. Тут нет вопроса «включать ли»: по умолчанию включено, выключается переменной окружения.

Что именно происходит (update.py:116-129):

1. При каждом старте flower в фоновом потоке один раз проверяется последний commit ветки main на GitHub (update.py:70-80). Основной поток не ждёт ни секунды — это первый инвариант.
2. Если commit отличается от установленного локально, запускается команда обновления тем же способом, каким было поставлено: есть uv — uv tool install --force, есть pipx — pipx install --force, нет ничего — pip install --user --upgrade (update.py:83-93).
3. Даже после успешной установки текущий процесс не подменяется — новая версия применится при следующем запуске flower (update.py:113). Подмена на середине выполнения — один из самых труднодиагностируемых видов отказа.
4. Троттлинг: не чаще одной проверки в 24 часа, метка времени пишется в ~/.config/flower/.update (update.py:32, :36-37, :124).
5. Любая ошибка — молча. Нет сети, GitHub лежит, установка не прошла — работу это не прерывает (update.py:79, :108-110).

Запуск из исходников (git) это не затрагивает. Шаг с командой обновления сначала проверяет, есть ли в репозитории .git; если есть — сразу возвращается None и ничего не делается (update.py:83-87): вашей рабочей копией управляет git, а не flower. В неинтерактивном режиме (stdin не терминал — например, pipe / CI) проверка пропускается целиком (update.py:121).

Чтобы выключить:

export FLOWER_NO_UPDATE=1

Подходит любое непустое значение (update.py:33, :121). Пригодится в CI, в офлайн-окружении и когда надо воспроизвести поведение какой-то старой версии.

Первый запуск: настройка credentials¶

Все три входа запуска работы — go, run, once — в начале вызывают ensure_credentials() (cli.py:1192, :1160, :1225), и это два барьера:

1. Есть ли они — поиск по приоритету; если не найдено, вас спросят прямо на месте.
2. Работают ли они — реальный запрос к API. Минимальный запрос с max_tokens=16 (env.py:120-123), стоит почти ничего. Протухший токен или неверный адрес шлюза по переменным окружения не видны, и без пробы всё взорвётся только через несколько минут.

Если credentials нет, первый запуск flower остановится на этом экране (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

Первый вопрос обязателен: если оставить пустым, красным напечатается 没给 token,取消。 и программа выйдет. На второй и третий вопросы можно просто нажать Enter. Для официального эндпоинта оставьте второй вопрос пустым; для стороннего шлюза укажите его корневой адрес, без /v1 — проба flower стучится в <BASE_URL>/v1/messages (env.py:162).

Ключи, которые записываются по вашим ответам (cli.py:1378-1386):

Файл лежит в ${XDG_CONFIG_HOME:-~/.config}/flower/.env (env.py:39-42), пишется целиком перезаписью, после записи — chmod 0o600 (cli.py:1336-1347). Это и есть тот самый файл «настроил один раз — работает везде»: при смене каталога проекта перенастраивать не нужно, значение каждой переменной см. в Конфигурации.

Если на машине уже стоит Claude Code, вопросов может не быть вовсе¶

В поиске credentials есть последний запасной вариант: прочитать ~/.claude/settings.json, затем ~/.claude/settings.local.json и взять из их блоков env 9 ключей credentials (env.py:56-75, :109-111). У тех, у кого Claude Code уже настроен, flower запускается и сразу работает — экран настройки вообще не появляется. Именно это и рекламирует install.sh:77.

Когда нужно перенастроить¶

Подкоманда flower setup зарегистрирована (cli.py:1326-1328), но в _CMDS её забыли (cli.py:937), поэтому flower setup переписывается в flower go setup — «setup» воспринимается как формулировка задачи и прогоняется целый workflow. Сейчас нет ни одного способа из командной строки добраться до этой подкоманды, хотя несколько текстов ошибок по-прежнему предлагают её запустить. Чтобы изменить credentials:

$EDITOR ~/.config/flower/.env

Либо удалите токен из этого файла и запустите flower ещё раз — барьер отсутствия credentials спросит заново (при условии, что в других местах их тоже нет, например в ~/.claude/settings.json). Если credentials отклонены (HTTP 401 / 403), тот же экран появится прямо на месте и предложит перенастроить — но только один раз (cli.py:1416-1428).

Проверка, что всё встало¶

Два уровня, от дешёвого к дорогому.

Первый уровень — есть ли команда (бесплатно):

flower --help

Если видите эти строки, значит console script установлен и находится в PATH:

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

可移植长程 agent 框架

Второй уровень — credentials, эндпоинт и нативный бинарник работают (несколько центов): самый дешёвый настоящий запуск — это once: один агент, по умолчанию только три read-only инструмента Read / Glob / Grep, без goal guard, без workbench:

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

-v перед стартом печатает действующую конфигурацию, от токена остаются только первые 4 символа (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]

Эти строки подтверждают, что вы подключились к нужному шлюзу. Дальше идут проба credentials и сам запуск:

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

Заголовков step здесь нет. once идёт по пути _run_once → rt.run(), минуя _drive / Workflow.run, а Event("step", …) отправляется только в workflow/base.py:220 — поэтому разделительные строки вида == 步骤名 ===== 1/1 в режиме once не появляются, они бывают только у go / run.

Появилась строка + 完成 — проверка пройдена, и она доказывает сразу три вещи: credentials работают, эндпоинт доступен, нативный бинарник из wheel claude-agent-sdk на этой машине запускается. Если под - 验一下凭证… идёт ! 凭证被拒 или ! 网关地址或模型名不对 — смотрите таблицу диагностики ниже.

Когда установка не удаётся¶

Дальше¶

• Быстрый старт — зайти в каталог проекта и довести до конца первую настоящую задачу.
• Конфигурация — все переменные окружения, приоритет credentials, синтаксис .env, что остаётся на диске.
• Командная строка — все подкоманды и флаги.
• Развёртывание — запуск в контейнере, раздача доменных возможностей через plugin.
• Глоссарий — точное значение каждого термина в документации.