配置¶

flower 没有配置文件格式,也没有配置子命令能真的跑到 —— 所有配置都是环境变量加 .env 文件,再加一批只能从 Python 侧给的策略对象。这一页把散在五个地方的东西收成一份: 每个变量、凭证按什么顺序找、.env 认什么语法、setting_sources=[] 到底隔绝了什么、 跑一次在磁盘上留下什么、会话存储三层各自丢掉什么、断网时怎么等。术语一律按术语表。

环境变量完整表¶

分五组:flower 直接读的凭证与端点、模型选择、路径查找、行为开关,以及 flower 写给 agent 子进程的。 最后一组不用你设 —— 设了也会被覆盖。

凭证与端点¶

两个都没设(或者都是空字符串),check_credentials() 就返回那段四行的错误,Runtime.__init__ 也会抛 RuntimeError(env.py:184-194;runtime.py:156-158)。

模型选择¶

flower 只读其中三个用来做自己的判断,其余是加载进来透传给 SDK 的。

flower setup 填了模型名的话,ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、 ANTHROPIC_DEFAULT_SONNET_MODEL 三个一起写(cli.py:1383-1385)。

路径与查找¶

行为开关¶

这两个都是逃生口:不设是常态,设了是为了让 flower 少做一件事。设成任意非空值即生效, 值本身不解析(update.py:121;cli.py:1413)。

从 git 源码跑的 flower 不受自动更新影响,FLOWER_NO_UPDATE 对它是空操作 —— 更新命令那一步 认出仓库里有 .git 就直接返回 None(update.py:83-87)。

flower 写给 agent 子进程的¶

这三个是 CompactPolicy.env() 生成后塞进 ClaudeAgentOptions.env 的(agent.py:48-58、:241-245), 控制 harness 内置的压缩。你在 shell 里设它们没有意义 —— 真正生效的是 flower 传给子进程的那一份。

容器包装器读的¶

这两个不是 flower 本体读的,是 docker/flowerbox 这个 shell 包装器读的。完整用法见部署。

.env 里的键不限于上面这些。 解析器把所有 k=v 行都加载进 os.environ,不做白名单 (env.py:30、:102-107)。上面那 9 个凭证键组成的 KNOWN 只在两处起作用:借用 ~/.claude 配置时的白名单(env.py:72),和 -v 启动时打印 describe() 的字段范围(env.py:205)。

凭证查找优先级¶

load_dotenv() 不传路径时,按下面的顺序把所有存在的文件依次读进来 (env.py:45-53、:78-112):

1. 进程环境变量 —— 永远最高。任何 .env 都盖不过已经 export 的值。(env.py:91)
2. $FLOWER_ENV 指向的文件 —— 设了才有这一条。(env.py:48-49)
3. $PWD/.env —— 当前工作目录。cd 到哪个项目就近读哪个。(env.py:50)
4. ${XDG_CONFIG_HOME:-~/.config}/flower/.env —— 每人一份的全局位置,flower setup 写的就是它。(env.py:51、:39-42)
5. 源码仓库根的 .env —— flower/core/env.py 往上三层。只有从源码跑才存在;pip / pipx / uv 装出来的 flower 在 site-packages 里,没有这一条。(env.py:52)
6. ~/.claude/settings.json,然后 ~/.claude/settings.local.json 的 env 块 —— 最后的回退,只取 9 个凭证键。(env.py:56-75、:109-111)

哪个文件赢:第 3 条(项目 .env)赢第 4 条(全局 .env),第 4 条赢第 5 条(仓库根 .env), 三者都赢第 6 条(Claude Code 的配置),而全部都赢不过第 1 条(进程环境)。

实现方式是"已经有值的键不覆盖"(env.py:90-93):排在前面的先把键占住,后面的只补空缺。 所以优先级是按键算的,不是按文件算的 —— 项目 .env 里只写了 ANTHROPIC_BASE_URL, token 照样可以来自全局那份。同名键第一次出现的值定终身。

第 6 条只在自动查找时启用。显式给了路径(load_dotenv("/path/to/.env"))就只读那一个文件, 不走任何回退(env.py:86-87、:109)。

第 6 条:借 Claude Code 的 token¶

依次读 ~/.claude/settings.json 和 ~/.claude/settings.local.json,取 data["env"] 这个 dict, 从里面挑出这 9 个键(env.py:31-36、:65-74):

ANTHROPIC_API_KEY   ANTHROPIC_AUTH_TOKEN   ANTHROPIC_BASE_URL
ANTHROPIC_MODEL     ANTHROPIC_DEFAULT_OPUS_MODEL    ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL    CLAUDE_CODE_SUBAGENT_MODEL    CLAUDE_CODE_EFFORT_LEVEL

文件不存在、读不动、或者不是合法 JSON(OSError / ValueError),就返回空字典继续往下走 —— 回退失效不该带走这次运行(env.py:62-63、:66-69)。

代码里的立场是:借的只是"去哪找 token",settings.json 里其它任何东西(权限规则、hook、 模型设置)一概不接管,所以这不违背 setting_sources=[] 的可移植承诺(env.py:17-19、:59-61)。 install.sh:77 把它当成一个特性宣传:本机配好 Claude Code 的人,连配置界面都不会看到。

flower 不读 ~/.claude/settings.json —— 那是可移植性的代价。

.env 解析规则¶

解析规则短到可以背下来(env.py:95-107,13 行):逐行 strip,跳过空行、# 开头的行、 不含 = 的行;剩下的按第一个 = 切成 key 和 value,两边各自 strip,value 再走一次 .strip("'\"") —— 首尾的单双引号一律剥掉,不要求成对。

认这些写法:

不认这些。写了不报错,只会静默得到一个意外的值:

空值会把键占住。ANTHROPIC_AUTH_TOKEN= 在高优先级的文件里出现,take() 会执行 os.environ["ANTHROPIC_AUTH_TOKEN"] = "",于是后面的文件因为"键已存在"补不进来 (env.py:90-93);而 check_credentials() 判的是真值,空字符串照样算没配(env.py:186)。 结果是既没有凭证、也拿不到回退。 不想要某个键就整行删掉,别留一个空的。

可移植性的代价¶

build_options() 里那一行是全部机关(agent.py:207):

"setting_sources": [] if portable else ["project"],

portable=True 是 Runtime 的默认值,命令行没有开关能关掉它 —— 要关只能走 Python API 写 Runtime(portable=False),那会变成 ["project"],即读项目的 .claude/。

被隔绝的东西¶

领域能力不走这条路 —— 它随仓库分发,通过 plugins=[{"type": "local", "path": PLUGIN_DIR}] 加载 (agent.py:26、:210-212),见部署。领域指令则是叠加在 Claude Code 原生系统 提示词之后,不是替换(agent.py:198-202),所以专业化不以损失通用能力为代价。

换台机器要带什么¶

• 凭证:一个文件。~/.config/flower/.env 拷过去就行,或者在新机器上重新配一次。 不带的话什么都跑不起来 —— 不会有任何东西被自动继承。
• 接续状态:整个目录。runs/(会话库、清单、血缘)和 .flower/(工作台)。
• 但路径要一致。lineage.json 里存了工作区的绝对路径,对不上就当没有,静默退回新会话, 不报错(lineage.py:65-66)。原因是 SDK 的 project_key 从工作区路径推导 (/、_、. 全换成 -,runtime.py:40-41),目录换了位置,旧的 session_id 就查不到了。

磁盘布局¶

跑一次 flower 会写两棵树:<run_dir>/ 放账目和会话,<workspace>/.flower/ 放工作台。 两者默认都在当前目录下,但它们的基准不同。

<run_dir>/ —— 默认 ./runs/¶

runs/
  sessions.db        SQLite,全量 transcript(含每个 subagent 自己那条)
  manifest.json      运行清单:每一步的 session_id / 花费 / 重试 / 失败原因,跨进程累积
  lineage.json       血缘:步骤名 → session_id,同一个目录再跑一次靠它接上
  aside/             旁路问答的独立 Runtime,自己的 sessions.db + manifest.json
  workbench/         仅当走 run / once 路径且给了 -W

manifest.json 每一行是 asdict(StepResult) 加两个补丁(runtime.py:44-71、:579-582):

写盘策略是追加不覆盖:每次落盘先重读一遍文件,把 run 等于自己的行换成最新的, 别人的行原样留着(runtime.py:564-586)。所以同一个目录并行跑多个 flower,账不会互相冲掉。

runs/ 里的东西是纯数据,随时可以用 sqlite3 或 tools/analyze_run.py 离线翻。

<workspace>/.flower/ —— 工作台¶

.flower/
  INDEX.md      自动生成的索引,注入主 agent 的 system prompt
  scripts/      要跑第二次的脚本。首行 `# desc: 一句话` 会出现在索引里
  artifacts/    超过 2000 字符的长产出:报告、数据、日志
  notes/        跨步骤的决策记录
  spill/        落盘的大工具结果,文件名 = 内容 sha256 前 16 位 + `.txt`

三个子目录加索引由 Workbench 建(workbench.py:73-92)。INDEX.md 走会话级的 system_prompt.append,subagent 继承不到 —— 所以"长产出写 artifacts/"这条规矩必须由 协调者在任务书里转述,那是唯一通道。

go 路径在 notes/ 下固定生成这些:

--isolate 时工作台移到仓库外:<workspace 的父目录>/.flower-<workspace 名>/ (starter.py:47-55)。worktree 是每个 agent 的私有副本,工作台是跨 agent 的共享层, 共享的东西不能放进私有围栏里。此时给模型的路径是绝对路径(workbench.py:69-71、:142-145)。

spill/ 有两个写入者,落点算法不同:

默认布局下这是同一个目录。但工作台被挪走时(-W 让它落到 runs/workbench/,或者 --isolate 让它落到仓库外)两者就分开了 —— TrimPolicy 那一份始终在工作区里,因为 agent 的 Read 必须够得到它。

spill_guard 换上去的不是一行,是一行指针加开头 400 字符(guard.py:132-140)。 读落盘文件本身的调用会被放行,不然"需要全文用 Read 读它"是句空话 —— 读回来又超阈值,又被落盘, 无限循环(guard.py:155-170)。

sessions.db 的表结构¶

三张表,建表语句在 stores/sqlite.py:27-51:

CREATE TABLE entries (
    store_key TEXT NOT NULL,
    seq       INTEGER NOT NULL,
    uid       TEXT,
    payload   TEXT NOT NULL,
    PRIMARY KEY (store_key, seq)
);
CREATE UNIQUE INDEX entries_uid
    ON entries(store_key, uid) WHERE uid IS NOT NULL;
CREATE TABLE meta (
    store_key TEXT PRIMARY KEY,
    mtime     INTEGER NOT NULL,
    next_seq  INTEGER NOT NULL
);
CREATE TABLE summaries (
    project_key TEXT NOT NULL,
    session_id  TEXT NOT NULL,
    mtime       INTEGER NOT NULL,
    data        TEXT NOT NULL,
    PRIMARY KEY (project_key, session_id)
);

store_key 的构造(sqlite.py:54-58):<project_key>/<session_id>,subagent 再接一段 subpath。project_key 由 SDK 从工作区路径推导 —— /、_、. 全换成 -。

拿真实样本看一眼(human-test/HT002/runs/sessions.db):

sqlite3 runs/sessions.db "select store_key, next_seq from meta;"

-Users-hechenyu-explore-test-ide/601c8c91-6c4b-4525-8a5f-295b99bf9515|37
-Users-hechenyu-explore-test-ide/47395075-bec7-466e-80cd-f4d60b360235|80
-Users-hechenyu-explore-test-ide/47395075-…/subagents/agent-a99a6ce30a5471f44|104

那一份是 956 条 entries、10 条 meta、4 条 summaries —— 10 条会话里 4 条是主 transcript, 6 条是 subagent 的,而 summaries 恰好等于主 transcript 的数目。

会话存储三层¶

append(写)永远是全量落盘,一个字不改。三层只影响 load(读回去喂给模型的那一份)。 load 的实际顺序是:

SqliteSessionStore.load     从 entries 表按 seq 读出全部
  → TrimmingSessionStore.expire()   时效性 Bash 结果 → 换成"已过期"
  → TrimmingSessionStore.trim()     旧的大 tool_result → 落盘 + 换成指针
    → PruningSessionStore.prune()   合成错误消息 / 旧的被拒调用 → 整条摘掉并重接链

第 2 层是裁剪,第 3 层是剪除 —— 裁剪按体积和价值丢,剪除按"是不是错误"丢,别混。完整签名见 Python API。

SqliteSessionStore —— 地基¶

SqliteSessionStore(path: str | Path)

零外部依赖的 SQLite 实现。要换 Postgres / S3 / Redis,实现同一个协议即可,SDK 自带一致性测试 套件 claude_agent_sdk.testing.session_store_conformance 可以直接验证(sqlite.py:1-8)。

除协议方法外,还有三个同步查询,给 flower 自己用:

TrimmingSessionStore + TrimPolicy / EphemeralPolicy¶

TrimmingSessionStore(path, workspace, policy: TrimPolicy | None = None,
                     ephemeral: EphemeralPolicy | None = None)

两条正交的规则。TrimPolicy 管体积:

被裁的正文写成 <sha256 前 16 位>.txt,原位置换成 [工具结果已归档:N 字符。完整内容在 <路径>,需要时用 Read 读取](trim.py:54-57、:308-317)。

EphemeralPolicy 管时效:git status、ls、ps 这类结果很短,按体积永远轮不到裁, 但它们的正确性随时间衰减 —— 20 轮前那份 git status 不是"没用",是会误导。

只作用于 Bash 工具的结果,而且命令要匹配 EPHEMERAL_CMD。Read 不在此列:文件内容不会因为 时间流逝失真到误导的程度,而且它可能正是模型推理的依据(trim.py:153-160)。过期的内容 不落盘 —— 归档一份过期的 git status 没有意义,重跑一次就有了。

判断函数是 is_ephemeral(cmd),它同时是还给协调者的权限清单:delegate_guard(allow_glance=True) 用的是同一个函数(trim.py:63-68、:128-150)。两个集合必须永远相等 —— 放行了但不裁剪,过期的 git status 就永久占着上下文;裁剪了但不放行,协调者为一条 ls 派个 subagent,4.3k 启动成本换几十字符。往白名单里加一条命令,等于同时说了这两句话。

什么时候用哪个:

• 只想让断线残渣不进上下文 → 什么都不用做,Runtime 默认就是 PruningSessionStore。 trim=False 只是不裁大结果,摘除照做。
• 长跑、工具输出很大 → trim=True。go 路径的 CLI 默认已经开着,用 --no-trim 反向关。
• 协调者开了 glance=True → ephemeral 必须保持开着,理由见上一段。

PruningSessionStore + PrunePolicy¶

PruningSessionStore(path, workspace, policy: TrimPolicy | None = None,
                    prune: PrunePolicy | None = None,
                    ephemeral: EphemeralPolicy | None = None)

keep_denials 是唯一透传到这一层的 Runtime 构造参数(Runtime(keep_denials=N))。 默认 1 而不是 0 的理由:最新那次拒绝是有效信号,能防止模型在同一轮里反复重试同一条被拦的命令。 别调大 —— 被拒的调用从来没执行过,结果里没有任何信息,实测一次占 273 字符 (93 字拒绝语加 180 字死命令原文),而且它会误导:实测协调者读到几条"不直接使用 Bash"之后, 连放行的 git status 都不再尝试,直接说"Bash 被限制了,派个 agent 去看"(prune.py:135-148)。

heal_orphans 治的是打断之后 resume 每次都 400:打断在消息边界断开,当时在飞的 tool_use 后面可能根本没有 tool_result,而 API 要求两者成对。这条坏历史留在 transcript 里不会自己消失, 于是之后每一次 resume 都被它打回。补法是在含孤儿的那条 assistant 之后插一条 user 条目, 把这条里所有孤儿的结果一次补齐,再把原本指向那条 assistant 的 parentUuid 改指到补的这条 (prune.py:95-147)。补而不删:删孤儿要重接父子链,同一条 assistant 里可能还有正常的块、 文本和 thinking,容易连累(prune.py:195-204)。

三条结构性红线,违反了 API 直接报错:

1. tool_result 块本身必须在,只能换 content。少一个就是 "Missing Tool Result Block" (trim.py:20-22;prune.py:79-92)。
2. isCompactSummary / isMeta 条目不能动 —— 那是被压掉的那段历史唯一的存在形式 (trim.py:179-181)。
3. 摘掉一条就必须把它的孩子接到它的父亲上。transcript 是 parentUuid 单链,harness 从叶子 往回走,链断在哪里前面的历史就全丢(prune.py:95-122)。所以 relink() 要拿到包含待摘 条目的完整列表,过滤由它自己做。

SQLite 里的原文一个字都不改 —— 三层只影响"喂回模型的那一份"(trim.py:18;prune.py:8)。

断网韧性¶

长程 workflow 一跑就是几小时,网络必然会断一次。默认行为很糟:断线那一刻 harness 往 transcript 里塞一条合成 assistant 消息(model="<synthetic>"、isApiErrorMessage=true),正文是 API Error: Can't reach the API server …;它成了会话的叶子,之后 resume 就被当成"模型上一句说的话" 喂回去,模型以为自己在讨论网络故障;它还会混进 StepResult.text,顺着 workflow 传给下一步的 prompt(resilience.py:1-22)。

韧性这一层做三件事,缺一不可:探针、续跑而不是重来、错误不进上下文。

Resilience 参数¶

退避公式(resilience.py:119-121):

min(base_delay * 2 ** (attempt - 1), max_delay) * (0.75 + random() * 0.5)

即 ±25% 抖动,避免网络恢复的瞬间一堆进程一起冲上去。按默认值:第 1 次退避 4 秒(实际 3~5), 第 2 次 8 秒(6~10),第 5 次起封顶 120 秒(90~150)。

探针策略¶

• 探的是 ANTHROPIC_BASE_URL 的 host:port,不是 api.anthropic.com(resilience.py:67-72)。 用自建网关时,后者通说明不了前者通。
• 只做 DNS 加 TCP 握手:getaddrinfo 然后 connect_tcp 然后立刻关掉。不发 HTTP、 不带凭证、不花钱(resilience.py:75-85)。探针必须免费,否则"断网时每 15 秒探一次" 本身就成了故障。
• 任何失败都算不可达 —— 不区分是 DNS 挂了还是 TCP 拒绝。
• wait_online() 挂在那里等:通了返回 True,等满 max_offline_wait 返回 False。 第一次不可达时通知一行 <host>:<port> 不可达,等待恢复(最多 60 分钟),恢复时再通知一行 <host>:<port> 恢复,继续,中间不刷屏(resilience.py:126-140)。

开跑前那次凭证探针是另一回事:它真打一次 POST <BASE_URL>/v1/messages,max_tokens=16, 默认超时 20 秒(env.py:126-181)。max_tokens 别设成 1 —— 实测强制思维链的模型连思考都 放不下,服务端挣扎到 30 秒才返回;设 16 只要 3.6 秒(env.py:120-123)。

错误分类¶

classify(text) 返回三种之一。先判致命:401 之类的文本里常常也带着 "connection" 这种词, 顺序反了会死等(resilience.py:53-64)。

区分可重试与不可重试是这一层的核心:网络抖动该等,凭证错该立刻停 —— 断网时死等是对的,key 写错了死等就是烧时间。

什么被挡在上下文外面¶

1. 合成错误消息。PruningSessionStore 在 load 时把它整条摘掉并重接 parentUuid (prune.py:27-32、:191-195)。SQLite 里原样保留,只是不喂回去。
2. 事件流里它是 kind="error" 而不是 "text",所以不进 StepResult.text, 也就不会顺着 workflow 传给下一步的 prompt(resilience.py:17-18)。
3. resume_prompt 有意不含任何错误细节。模型需要知道"被打断了、接着做",不需要知道是 ENOTFOUND 还是 503。那属于日志,不属于上下文(resilience.py:112-113)。 日志去 manifest.json 的 errors 字段看。

续跑而不是重来:失败发生时 session_id 已经拿到了,用 resume 从中断处接上,之前的花费不白费。

相关¶

• 命令行 —— 每个开关怎么映射到这一页的配置。
• Python API —— Runtime、三个 store、Resilience 的完整签名。
• 部署 —— 容器里跑、用 plugin 分发领域能力。
• 术语表 —— 这一页用到的每个词的准确含义。