快速上手¶

三条命令就能跑起来:装、进项目目录、敲 flower。这一页把这三条摆在最前面, 然后讲按下回车之后屏幕上会发生什么、它问你话的时候怎么答、跑不起来时先查什么。

装上,进目录,敲 flower¶

curl -fsSL https://chenyuheee.github.io/flower/install.sh | sh
cd /path/to/your/project
flower

第一条脚本自动找 uv / pipx / pip 把 flower 命令装上,只要 Python ≥ 3.10, 不用装 Node,也不用装 Claude Code CLI。第三条不带任何参数,也不用在 shell 里打引号。

想用别的装法(pipx / pip / 从源码)、或者这条脚本在你机器上不工作,见安装 —— 但不必先读完那一页再回来。

敲下回车之后¶

第一次在这台机器上跑,它先问凭证:API key 或者网关地址。配一次存进 ~/.config/flower/.env,以后处处生效。本机已经装了 Claude Code 并且配好的话, 它直接借那份 token,连问都不问。

凭证有了,光标停在 > 上:

要做什么? 一句话就够,回车开始(Ctrl-C 退出)
> 帮我做一个 X

这一行读的是标准输入,不经过 shell 解析 —— 中文引号、空格、感叹号都能直接打。

开跑前它会打一行 - 验一下凭证…,那是一次真的 API 探针。凭证被拒会打 ! 凭证被拒:… 并当场问你要不要重配;连不上则打 (探针没打通:… —— 当作网络问题,照常开跑), 不会让你去重配一个本来好好的 token。

探针过了就开始干活,它按三步走。屏幕上每一行 == 横杠就是一个 步骤边界,右边的 1/3 是进度:

== 确认需求 ======================================================== 1/3

  ? X 要跑在什么环境上?
     1) 只在我这台 macOS 上
     2) Linux 服务器
     3) 两个都要
你的回答 (回车=跳过,让它自己判断) > 1
  + 只在我这台 macOS 上

  ? 「做完了」以什么为准?
你的回答 (回车=跳过,让它自己判断) > 能跑起来,并且 pytest 全绿
  + 能跑起来,并且 pytest 全绿

  + 完成 9 轮 · $0.53 · 用时 6:02

== 设定目标 ======================================================== 2/3

  ~ 把这份需求拆成能当场验证的条目
  + 完成 12 轮 · $0.41 · 用时 9:06

== 干活 ============================================================ 3/3

  ~ 先看一眼现在有什么,再决定第一刀切哪
  * Read README.md
  > 派人 coder 实现 X 的第一版,带最小测试
  先让 coder 把骨架搭起来,我再看要不要拆第二个人。
  - 上下文 36.8K · 累计 $0.94 · 12:44
  + 完成 12 轮 · $12.34 · 用时 52:53
  + 完成 37 轮 · $1.40 · 用时 58:19

总花费 $14.68 · 清单 /path/to/your/project/runs/manifest.json

图标一律是 ASCII:~ 思考、* 工具调用、> 派人、+ 成功、x 失败、? 提问、<- 接上次。 不是 emoji —— emoji 和框线字符会触发终端字形回退,实测崩过两次终端。这份文档里所有终端样例 用的都是这套 ASCII,和你屏幕上一模一样。

另外三个地方值得多看一眼:

• 最后那两行 + 完成 不是重复。第一行是干活那一轮,第二行是判定那一轮 —— 判定跑在自己的会话里,但不另起 == 横杠,因为它是 干活 这一步内部的一轮。 它在运行清单里的名字是 干活·判定#1。
• + 完成 行里的 $ 是这一轮的钱,用时 是从开跑到现在的总时长,两个不同口径。
• - 上下文 … · 累计 … · … 那种状态行只跟主线程走, subagent 的上下文不在里面。subagent 的工具调用默认会显示,缩进到一条 | 竖线后面; 它们说的话要加 -v 才看得到 —— 那是现场,不是决策。

屏幕上这三步分别是谁在跑¶

前两步是前置确认和目标看守 这两个机制的落地;第三步是它们合起来在管的那段。默认最多跑 3 轮判定(--rounds), --no-goal 可以整个关掉 —— 关掉之后"它说做完了"就真的算做完了。

判定只有三种结论:达成、没到、这个环境验不了。后两种是不同的结论 —— "这里没法验"绝对不判通过,而是停下来问你。

一次完整跑不便宜。实测参照:HT002 把一个已有项目装到 macOS 上跑起来, 4 步、约 1 小时、$38.24;HT001 从零写一个终端 IDE, 10.4 小时、$171.62。想先看看它会问什么再决定要不要往下跑,用 --clarify-only。

提问怎么答¶

? 开头那一段是它在问你,三种答法:

• 打序号(1 / 2 / 3)—— 选那一条,屏幕回一行 + <选中的那条>。
• 直接打字 —— 自由回答,不必是选项里的。
• 直接回车 —— 跳过,让它自己判断,屏幕回一行 . 已跳过。

默认等你 1800 秒(--timeout)。等不到人就打 ! 无人应答 —— 它会自己判断,把假设记进「未知与假设」,然后继续往下跑,不会卡死。 提问次数默认不限(--asks 默认 -1);给个正数就是硬额度,用完打 ! 提问额度用完。

它跑起来之后,你还能说话¶

屏幕最下面永远有一行可以打字的提示符。这不是摆设 —— 每条输出之前它被擦掉、之后被重画, 所以它不会被日志冲到上面去。两种文案,随"有没有待答提问"切换:

你的回答 (回车=跳过,让它自己判断) >
(直接说 = 加需求,下个检查点送达;? 开头 = 顺便问一句,不打扰它干活) >

没有待答提问时,你能做两件事。

直接打一句话 = 加需求。 它不会被打断,下次查收件箱才看到。回执长这样:

+ 收到 (它下次查收件箱时会看到;已追加进确认书)

"已追加进确认书"很重要:这句话同时落进了 需求.md,所以它活得过步骤边界 —— 下一步是新会话,只读冻结件,不落盘的话说了等于没说。

? 开头 = 顺便问一句。 它会另起一条只读会话回答你,手上只有最近 60 条事件和 工作台里的东西。这条旁路由 旁路顾问跑,默认封顶 12 轮 / $0.5:

? 现在到哪了
# 旁路
  在干活第二轮,coder 刚补完 parser 的测试,正在跑第三次验证。
  ($0.0123,没有打扰正在跑的运行)

答完即弃 —— 那段问答不进这次运行的上下文,花费也不进主运行清单, 它记在 runs/aside/ 下面自己的一份里。所以问了不影响运行,也不用心疼那笔钱进了账。

顺带一提 Ctrl+C:在运行途中按第一次是打断这一轮并说句话,不是退出。

! 已打断这一轮。正在跑的 subagent 会丢掉半成品。
  要说什么?(直接回车 = 什么都不说,接着跑;再按一次 Ctrl+C = 退出)
>

再按一次才真的退出。(在最开始那个 要做什么? 提示符上按 Ctrl-C 则直接退出,打印 已取消。)

再跑一次就是接着上次¶

同一个目录再敲一次 flower,第一句话就换了:

接着上次? 直接回车 = 接着做;也可以说点新的;/new = 重开一件事(Ctrl-C 退出)
> 顺便支持代码块高亮
<- 在 ~/proj 接上上次  需求已确认 · 目标 7 条 · 干活上下文 71.4K · 第 3 次唤醒

<- 那一行是唤醒横幅,报的是这个目录现在的状态。 它不会再盘问一遍需求,也不会重设一遍目标;进程被 kill、机器重启都一样。 这时说的那句话会追加进 需求.md,并触发重新推导判定清单 —— 不重推的话判定者读的还是老清单,你新加的事根本不进判定。 细节和代价(上下文会一直涨)见接续。

不想接上次就打 /new:上一段的需求、目标、血缘 会被移进 notes/archive/<时间戳>/(不删),然后从头开始。

写进脚本,无人值守¶

诉求也可以直接当参数给,开关写在诉求前面或后面都行:

flower "帮我做一个 X"                      # 诉求当参数
flower --rounds 5 "帮我做一个 X"           # 开关在前
flower "帮我做一个 X" --rounds 5           # 开关在后,等价
echo "帮我做一个 X" | flower --timeout 0   # 管道喂标准输入,全自动

只给开关不给诉求也行 —— flower --clarify-only 会先问你要做什么再往下走。

为什么还留着"回车之后再输入"那条路。 命令行里那对引号是纯负担。实测踩过: 右引号打成了中文的 ”,zsh 一直在等真正的右引号(掉进 dquote> 续行提示符), 看起来像程序卡住了,其实一次都没启动。裸跑 flower 时读的是标准输入,不经过 shell 解析, 中文引号、空格、感叹号、换行全都能直接打。管道那一条走的是同一个入口 —— 标准输入不是终端时它不打提示头,直接读一行。

跑不起来的话¶

敲了 flower 没反应、报凭证错、或者输出一眼看着就不对,先用最便宜的一发把凭证和二进制 单独验一遍。单 agent、只读工具,打一发看两头通不通:

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

once 默认只给三个工具 —— Read、Glob、Grep,它写不了任何东西,所以这一发很便宜。 实测参照:Opus 5 配 100 万窗口经第三方网关,单轮地板价是 $0.1741,便宜的模型更低。 安装那一页的"验证装好了没有"跑的就是这一条命令。

跑通的话是这个形状 —— 数字和正文会不一样,图标不会:

ANTHROPIC_AUTH_TOKEN = sk-1***(共 19 位)
ANTHROPIC_BASE_URL = https://your-gateway.example.com
ANTHROPIC_MODEL = claude-opus-5[1m]
- 验一下凭证…
  ~ 先看目录结构,再挑一两个文件读
  * Glob **/*.py
  * Read README.md
  这是一个用 Rust 写的命令行 HTTP 压测工具。
  - 累计 $0.00 · 0:00
  + 完成 4 轮 · $0.0932 · 用时 0:00

两件事要认出来:

• 头几行是 -v 打的生效配置。连错网关一眼就看得出来 —— 这是这个开关存在的主要理由。
• + 完成 那一行的 $ 是真的,累计 和 用时 在 once 这条路上恒为 0 (每个事件新建一次渲染器,状态攒不起来)。

这一发跑通,说明凭证、网关、模型名、自带二进制全都对,问题在别处。跑不通属于安装范畴, 回安装。

接下来读什么¶