빠른 시작¶

명령 세 줄이면 돌아간다: 설치하고, 프로젝트 디렉터리로 들어가고, 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 도 필요 없다. 세 번째 줄은 인자를 하나도 받지 않고, 셸에서 따옴표를 칠 필요도 없다.

다른 설치 방법(pipx / pip / 소스에서)을 쓰고 싶거나 이 스크립트가 당신 머신에서 동작하지 않으면 설치를 보라 —— 다만 그 페이지를 다 읽고 돌아올 필요는 없다.

엔터를 누른 다음¶

이 머신에서 처음 돌리면 먼저 자격 증명을 묻는다: API key 또는 게이트웨이 주소. 한 번 설정하면 ~/.config/flower/.env 에 저장되어 이후 어디서나 유효하다. 이 머신에 Claude Code 가 이미 설치되어 있고 설정까지 되어 있다면, 그 token 을 그대로 빌려 쓰고 아예 묻지도 않는다.

자격 증명이 준비되면 커서가 > 에 멈춘다:

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

이 줄은 표준 입력을 읽는다. 셸 파싱을 거치지 않는다 —— 중국어 따옴표, 공백, 느낌표를 그대로 쳐도 된다.

시작하기 전에 - 验一下凭证… 한 줄을 찍는데, 이건 진짜 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 세트를 쓰며, 당신 화면과 똑같다.

추가로 세 군데는 한 번 더 볼 만하다:

• 마지막 두 줄의 + 完成 은 중복이 아니다. 첫 줄은 일한 라운드이고, 둘째 줄은 판정 라운드다 —— 판정은 자기 session 에서 돌지만 == 가로줄을 새로 긋지 않는다. 干活 스텝 내부의 한 라운드이기 때문이다. 런 매니페스트에서 이름은 干活·判定#1 이다.
• + 完成 줄의 $ 는 그 라운드의 비용이고, 用时 는 시작부터 지금까지의 총 시간이다. 기준이 서로 다르다.
• - 上下文 … · 累计 … · … 같은 상태 줄은 메인 스레드만 따라간다. subagent 의 context 는 여기 포함되지 않는다. 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 에도 기록되므로 스텝 경계를 넘어 살아남는다 —— 다음 스텝은 새 session 이고 동결된 산출물만 읽으므로, 디스크에 남기지 않으면 말한 적 없는 것과 같다.

? 로 시작 = 잠깐 하나 묻기. 읽기 전용 session 을 따로 띄워 답해 준다. 손에 든 것은 최근 60개 이벤트와 워크벤치 안의 것뿐이다. 이 사이드 경로는 오라클이 돌리고, 기본 상한은 12 라운드 / $0.5 다:

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

답하고 나면 버린다 —— 그 문답은 이번 run 의 context 에 들어가지 않고, 비용도 메인 런 매니페스트에 들어가지 않는다. runs/aside/ 아래 자기 몫에 따로 기록된다. 그래서 물어봐도 run 에 영향이 없고, 그 돈이 장부에 올라갈까 아까워할 필요도 없다.

Ctrl+C 도 덧붙이면: 실행 중에 처음 누르는 것은 이 라운드를 끊고 한마디 하는 것이지 종료가 아니다.

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

한 번 더 눌러야 진짜로 종료된다. (맨 처음 要做什么? 프롬프트에서 Ctrl-C 를 누르면 바로 종료되고 已取消 를 찍는다.)

다시 돌리면 지난번을 이어받는다¶

같은 디렉터리에서 flower 를 다시 치면 첫 문장이 달라진다:

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

<- 줄은 웨이크 배너이고, 이 디렉터리의 현재 상태를 알려 준다. 요구를 처음부터 다시 캐묻지 않고, 목표도 다시 세우지 않는다. 프로세스가 kill 되었거나 머신이 재부팅되었어도 마찬가지다. 이때 한 말은 需求.md 에 추가되며, 판정 목록 재도출을 트리거한다 —— 다시 도출하지 않으면 저지는 여전히 옛 목록을 읽고, 새로 추가한 내용은 판정에 아예 들어가지 않는다. 세부와 대가(context 는 계속 늘어난다)는 연속성을 보라.

이어받고 싶지 않으면 /new 를 친다: 이전 구간의 요구, 목표, 혈통이 notes/archive/<타임스탬프>/ 로 옮겨지고(삭제되지 않는다) 처음부터 다시 시작한다.

스크립트에 넣고, 무인 실행¶

요청을 인자로 바로 줄 수도 있고, 옵션은 요청 앞이든 뒤든 상관없다:

flower "帮我做一个 X"                      # 요청을 인자로
flower --rounds 5 "帮我做一个 X"           # 옵션이 앞
flower "帮我做一个 X" --rounds 5           # 옵션이 뒤, 동일
echo "帮我做一个 X" | flower --timeout 0   # 파이프로 표준 입력에 먹임, 완전 자동

옵션만 주고 요청을 주지 않아도 된다 —— flower --clarify-only 는 무엇을 할지 먼저 물은 뒤 진행한다.

왜 "엔터 다음에 입력하는" 경로를 남겨 두었나. 명령줄의 그 따옴표 쌍은 순전히 부담이다. 실제로 밟은 적이 있다: 닫는 따옴표를 중국어 ” 로 쳤더니 zsh 가 진짜 닫는 따옴표를 계속 기다렸고(dquote> 연속 입력 프롬프트에 빠졌다), 프로그램이 멈춘 것처럼 보였지만 사실 한 번도 시작되지 않았다. 맨몸으로 flower 를 돌리면 표준 입력을 읽고 셸 파싱을 거치지 않으므로, 중국어 따옴표, 공백, 느낌표, 줄바꿈 모두 그대로 칠 수 있다. 파이프 경로도 같은 입구로 들어간다 —— 표준 입력이 터미널이 아니면 프롬프트 헤더를 찍지 않고 바로 한 줄을 읽는다.

안 돌아갈 때¶

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 이다 (이벤트마다 렌더러를 새로 만들어 상태가 쌓이지 않는다).

이 한 발이 통하면 자격 증명, 게이트웨이, 모델 이름, 내장 바이너리가 전부 맞다는 뜻이고, 문제는 다른 데 있다. 통하지 않으면 설치 범주이니 설치로 돌아가라.

다음에 읽을 것¶