安装¶

装 flower 只需要 Python ≥ 3.10。运行时依赖只有一个 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,唯一运行时依赖 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 装、告诉你下一步。它一个字都不碰你的凭证(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 都往这里放,这句提示对它们是准的。但第 4 条路 (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 —— 把那个目录而不是 ~/.local/bin 加进 PATH, 然后重开终端或者 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 里的解释器 和这份源码。

源码安装还多一个凭证落点:仓库根的 .env(查找顺序里排第 5,见 配置 · 凭证查找优先级)。开发时:

cp .env.example .env        # 填 ANTHROPIC_AUTH_TOKEN

.env 已经被 .gitignore 忽略,不会进版本库。pip / pipx / uv 装出来的 flower 没有这个位置 可用 —— 它在 site-packages 里,没有"仓库根" —— 所以那种装法要用下面的全局凭证文件。

自动更新¶

flower 还在快速迭代,所以 pip / pipx / uv 装出来的那份默认会自己更新:装了三天前版本的人 报回来的 bug 可能早就修了,双方都在浪费时间。这件事没有开关式的"要不要开"的问法 —— 默认开,要关就设环境变量。

它做的事(update.py:116-129):

1. 每次 flower 启动时,在后台线程里查一次 GitHub 上 main 的最新 commit (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 管,不归它管。 非交互(stdin 不是终端,比如管道 / CI)也整个跳过(update.py:121)。

要关掉:

export FLOWER_NO_UPDATE=1

任意非空值都算(update.py:33、:121)。CI、离线环境、要复现某个旧版本行为的时候用它。

第一次跑:配凭证¶

go、run、once 三条跑活入口开头都调 ensure_credentials()(cli.py:1192、:1160、:1225), 两道关:

1. 有没有 —— 按优先级找一遍,找不到就当场问你。
2. 能不能用 —— 真打一次 API。max_tokens=16 的最小请求(env.py:120-123),几乎不花钱。 过期的 token、写错的网关地址,光看环境变量查不出来,不探就要跑到几分钟后才炸。

没有凭证时,第一次跑 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

第 1 问必填,留空就打红字 没给 token,取消。 然后退出。第 2、3 问直接回车即可。 用官方端点就把第 2 问留空;第三方网关填它的根地址,别带 /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 的话,可能一个问题都不问¶

凭证查找有一条最后的回退:读 ~/.claude/settings.json,再读 ~/.claude/settings.local.json, 从它们的 env 块里取 9 个凭证键(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" 当成一句诉求跑一遍完整流程。 目前没有任何命令行写法能到达那个子命令,尽管好几处错误文案还在让你去跑它。要改凭证:

$EDITOR ~/.config/flower/.env

或者把那个文件里的 token 删掉再跑一次 flower —— 缺凭证那道关会重新问(前提是别的位置也没有, 比如 ~/.claude/settings.json)。凭证被拒(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 框架

第二级 —— 凭证、端点、原生二进制都通(几分钱):最便宜的真跑是 once —— 单 agent、默认只给 Read / Glob / Grep 三个只读工具,不开目标看守, 不开工作台:

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

-v 会在开跑之前先打印当前生效的配置,token 只留前 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]

这几行确认没连错网关。接着是凭证探针和真正的运行:

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

没有步骤头。 once 走 _run_once → rt.run(),不经 _drive / Workflow.run, 而 Event("step", …) 只在 workflow/base.py:220 发出 —— 所以 == 步骤名 ===== 1/1 这种分隔行在 once 下不会出现,只有 go / run 才有。

+ 完成 那一行出现就算通过,它同时证明了三件事:凭证能用、端点连得上、 claude-agent-sdk wheel 里的原生二进制在这台机器上跑得起来。看到 - 验一下凭证… 下面跟着 ! 凭证被拒 或 ! 网关地址或模型名不对,去下面的排错表。

装不上的时候¶

下一步¶

• 快速上手 —— 进一个项目目录,跑通第一件真活。
• 配置 —— 全部环境变量、凭证优先级、.env 语法、磁盘上留下什么。
• 命令行 —— 全部子命令和开关。
• 部署 —— 容器里跑、用 plugin 分发领域能力。
• 术语表 —— 文档里每个词的准确含义。