部署与扩展¶

把 flower 搬到别处要处理三件事:容器(围住不受限的 Bash,顺便检验"脱离 CLI"这句话)、 plugin(领域能力随仓库走,不看宿主机装了什么)、文档站(推到 main 就自动发,install.sh 挂在 Pages 域名上)。三节互相独立,按需要读。

一、容器¶

为什么要容器¶

一是围起来。 干活的执行者有不受限的 Bash —— flower 的 Bash 白名单(delegate_guard)只管主线程,派出去的人要能跑测试,所以是有意的。 容器里只挂你的项目目录,框架源码在镜像内的 /opt/flower,宿主别的地方看不见。

二是它本身就是可移植那条约束的检验。 镜像里没有 Claude Code CLI、 没有 Node,只有 Python 和 claude-agent-sdk —— 请求靠 wheel 自带的原生二进制发出去。 能在这里跑起来,"脱离 CLI"就不是纸上的说法。

实测通过(2026-09-06,macOS 15 / arm64 / colima + docker 28.4.0):

镜像里装了什么¶

基础镜像 python:3.13-slim,上面 apt 只装三个包。每一样都有理由:

框架源码进镜像的方式是 COPY,不是 bind mount —— 容器里的 agent 因此碰不到宿主的框架源码:

入口是 ENTRYPOINT ["flower"],CMD 是空的 —— 不带参数跑容器时进交互输入 (它问你要做什么),而不是打印 --help。这样就不必在 shell 里给一句中文诉求打引号。

为什么不能把宿主的 .venv 挂进去¶

SDK 按平台发 wheel,自带的二进制是平台专属的:

宿主   claude_agent_sdk-0.2.152-py3-none-macosx_11_0_arm64.whl
       → _bundled/claude 是 Mach-O 64-bit arm64,191M
容器   claude_agent_sdk-0.2.152-py3-none-manylinux_2_17_aarch64.whl

挂进去跑不了,所以镜像必须自己 pip install。反过来说这也是可移植性的证据:同一个 pyproject.toml,换平台就换一份原生二进制,框架代码一行不用改。

两个脚本¶

docker/build 的开关,全部走环境变量:

后三个只在 FLOWER_MIRRORS=1 时起作用 —— FLOWER_MIRRORS=0 那条分支根本不设 build-arg。

docker/flowerbox 认两个:

FLOWER_HOME 从脚本自己的位置推出来,不写死路径,所以仓库克隆到哪都能用。

构建镜像并起容器¶

docker/build                       # 一次就够
cd ~/任意项目目录                   # 必须在 $HOME 下面,见下面的挂载边界
/path/to/flower/docker/flowerbox   # 不带参数 → 它问你要做什么,不用打引号

网络到 pypi.org / Docker Hub 正常的话,构建这样跑:

FLOWER_MIRRORS=0 docker/build

flowerbox 的参数和 flower 完全一样 —— 它把 "$@" 原样接在 ENTRYPOINT 后面。 --clarify-only、--asks N、--timeout 秒、--isolate、-v 都照给,全表见命令行:

cd ~/proj
/path/to/flower/docker/flowerbox --clarify-only -v
/path/to/flower/docker/flowerbox "帮我做一个 X"

真正执行的是这一行(-t 只在有 TTY 时加,见下):

docker run -i $TTY --rm \
    --env-file "$FLOWER_HOME/.env" \
    -v "$PWD:/work" \
    -w /work \
    "$IMAGE" "$@"

挂载边界与持久化¶

宿主 $PWD  ──挂载──>  /work       ← agent 在这里干活,产出留在宿主
镜像内                /opt/flower ← 框架源码,**没挂载**,改不到宿主

所以在 flower/human-test/HT001 这种仓库内的子目录里跑也是安全的:挂进去的只有 HT001, 框架源码不在挂载范围内。

凭证怎么进容器¶

走 docker run --env-file,不进镜像层。flowerbox 读的是 $FLOWER_HOME/.env, 默认就是仓库根的 .env:

cp .env.example .env       # 填 token;.env 已被 gitignore

注意 flower setup 写的是 ~/.config/flower/.env,那个路径 flowerbox 不看。 已经用 setup 配好、不想再拷一份的话,把 FLOWER_HOME 指过去:

FLOWER_HOME=~/.config/flower /path/to/flower/docker/flowerbox

键名、优先级、网关怎么填,见配置。

git submodule¶

.gitmodules 里只有一条:

普通 git clone 不会拉它,human-test/HT001 就是个空目录(git submodule status 前面 带 - 就是这个状态)。要不要管它:

国内网络:为什么有那一堆镜像替换¶

这套东西在墙内装的时候,慢的不是带宽而是国际线路。默认的 docker/build 已经把该换的都换了, FLOWER_MIRRORS=0 一键全关。下面是实测数据和四处替换的原委 —— 网络没这个问题就不用读。

A=https://github.com/abiosoft/colima-core/releases/download/v0.9.0-2/ubuntu-24.04-minimal-cloudimg-arm64-docker.qcow2
mkdir -p ~/.colima/images
curl -sSL -C - -o ~/.colima/images/colima-arm64-docker.qcow2 "https://ghfast.top/$A"
# 校验:digest 从 GitHub API 拿。别跳过 —— 这是要当 VM 跑的东西
curl -sSL https://api.github.com/repos/abiosoft/colima-core/releases/tags/v0.9.0-2 \
  | python3 -c "import json,sys;[print(a['digest'],a['name']) for a in json.load(sys.stdin)['assets'] if a['name'].endswith('arm64-docker.qcow2')]"
shasum -a 256 ~/.colima/images/colima-arm64-docker.qcow2

colima start --disk-image ~/.colima/images/colima-arm64-docker.qcow2 \
             --cpu 4 --memory 6 --disk 20

export LIMA_HOME=~/.colima/_lima
limactl shell colima -- sudo sh -c '
  cat > /etc/apt/sources.list.d/ubuntu.sources <<EOF
Types: deb
URIs: https://mirrors.ustc.edu.cn/ubuntu-ports/
Suites: noble noble-updates noble-backports noble-security
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
EOF
  sed -i "s|https://download.docker.com|https://mirrors.ustc.edu.cn/docker-ce|g" \
      /etc/apt/sources.list.d/docker.list
  pkill -f "apt-get update"          # boot.sh 会继续走完并写完成标记
'
# colima start 随即正常退出;之后补上 rsync(现在 1.95 MB/s)
limactl shell colima -- sudo sh -c 'apt-get update -q && apt-get install -y -q rsync'

二、plugin¶

plugin 是什么,SDK 怎么加载它¶

跟着仓库走的领域能力包。框架代码不含任何领域知识,领域知识全部放在仓库根的 plugin/ 目录里,和代码一起被 clone、一起被 review、一起被打 tag。

SDK 侧的接线在 flower/core/agent.py 的 build_options() 里,两行:

PLUGIN_DIR = Path(__file__).resolve().parent.parent.parent / "plugin"
...
if use_plugin and PLUGIN_DIR.is_dir():
    opts["plugins"] = [{"type": "local", "path": str(PLUGIN_DIR)}]

配合 setting_sources=[](下面单独讲),这就是 flower 能同时做到"可移植" 和"懂你的领域"的原因:它不问宿主机装了什么,只认仓库里带来的这一个目录。

目录布局¶

概率性和确定性的区别是选型的关键,不是措辞的区别:

• skill 是摆在那儿的知识。模型看到它的 description,觉得跟当前任务相关才会去读。 相关性判断由模型做,所以同一句话跑两次,可能一次用了、一次没用。
• hook 是代码。匹配到事件就跑,和模型想不想、知不知道无关。flower 自己的 落盘、隔离都是 hook,正是因为它们不能"有时生效"。

所以判据只有一条:这件事必须每次都发生吗? 必须 —— 写 hook。只是"知道了有好处" —— 写 skill。把必须的事写成 skill,等于把纪律押在模型的一次判断上。

现在仓库里 plugin/ 只有两样东西:.claude-plugin/plugin.json 和 skills/example/SKILL.md。 agents/、hooks/、.mcp.json 都还不存在 —— 要用就自己建,目录名照上表写死。

写一个 skill:完整例子¶

以"生成发版说明"为例,从零到确认生效。

第一步:建目录。 目录名就是 skill 名,和 frontmatter 里的 name 保持一致。

mkdir -p plugin/skills/release-notes

第二步:写 plugin/skills/release-notes/SKILL.md。 文件名必须是 SKILL.md,大写。 格式是 YAML frontmatter + Markdown 正文,frontmatter 两个字段:

一份能直接用的最小文件:

---
name: release-notes
description: 整理发版说明时使用。当用户说"写 release notes""这版改了什么""发版"时用它。
---

# 发版说明

## 怎么取素材

```bash
git describe --tags --abbrev=0        # 上一个 tag
git log --oneline <上一个 tag>..HEAD   # 这一版的提交
```

## 输出格式

按三段分,每段是无序列表,每条一行,写用户能感知的变化,不写内部重构:

- **新增** —— 这版能干什么以前干不了的事
- **修复** —— 修了什么,一句话说清症状
- **不兼容** —— 升级要动手改什么。没有就整段不写

## 边界

- 版本号不要自己编,从 `pyproject.toml` 的 `version` 读。
- 拿不准某条提交对用户有没有感知,列出来问,不要替用户决定。

正文写什么没有强制格式 —— 它就是被读进上下文的一段文本。参照 plugin/skills/example/SKILL.md 的写法:说清什么时候用、步骤、输出成什么样、边界在哪,比堆背景知识有用。

第三步:确认它被加载了。 只查一件确定的事 —— 目录到底在不在:

cd /path/to/flower
python3 -c "from flower.core.agent import PLUGIN_DIR; print(PLUGIN_DIR, PLUGIN_DIR.is_dir())"

打出 /path/to/flower/plugin True 才说明 build_options() 那个 if 会进去。 打出 False 就是没加载,而且运行时不会报错,见下面的警告。

别拿"跑一句看 example skill 有没有被调起来"当验证。 skill 是概率性的:模型没调用它, 既可能是没装上,也可能只是没觉得当前任务需要 —— 这个信号区分不了这两件事。而且 build_options() 从不设置 SDK 的会话级 skills= 选项,plugin 里的 skill 到底会不会出现在 协调者的可选列表里,没有实测过。上面那条 PLUGIN_DIR 的 True/False 是确定的,用它。

要给某个执行者点名开哪几个 skill,用 worker(..., skills=[...]) (flower/core/roles.py); 名字用 SKILL.md 里的 name,SDK 也接受 插件名:skill 名 这种限定写法。

setting_sources=[] 为什么逼着领域能力走 plugin¶

同一个函数里还有这一行:

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

SDK 的默认是 None = 三个来源全读:~/.claude/settings.json(用户)、 .claude/settings.json(项目)、.claude/settings.local.json(本地)。flower 默认传 [], 把它们全部关掉。

.claude/ 不生效不是配置漏了,是这条约束的定义:只要还从宿主机读一个字节,"换台机器行为一致" 就不成立。领域能力于是只有一条通道 —— 随仓库走的 plugin/。

两个开关(都在 build_options() 上,默认值就是可移植那套):

顺带:instructions 走的是叠加(system_prompt 的 append), 和 plugin 是两条不同的通道 —— 前者每轮都在上下文里,后者按需加载。短而必须的纪律写 instructions, 长而偶尔用得上的知识写 skill。

三、文档站¶

你正在读的这个站是 mkdocs-material 建的,源文件就在仓库的 docs/ 下,推到 main 就自动发。

本地改文档:

pip install -r docs-requirements.txt
mkdocs serve                  # 本地预览
mkdocs build --strict         # 提交前跑一遍,和 CI 同一条命令

CI 的触发条件是 push 到 main 且改动命中这几个路径,另外可以在 Actions 页面手动 workflow_dispatch:

docs/**  mkdocs.yml  hooks/**  docs-requirements.txt  install.sh  .github/workflows/docs.yml

install.sh 为什么从 Pages 发¶

构建那步末尾有一行:

- run: cp install.sh site/install.sh

安装脚本被塞进站点产物,于是它挂在文档站的域名上,一句话安装长这样:

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

理由很实际:raw.githubusercontent.com 在国内不通,而 *.github.io 通(实测)。 脚本本身放在仓库根,只是发布时多拷一份 —— 不需要维护两份内容,也不需要额外的 CDN。

install.sh 自己做的事:挑一个 Python 工具安装器(uv > pipx > 装 uv > pip --user), 从 GitHub 装 flower,然后提示下一步。它不碰凭证 —— 第一次跑 flower 会问,存到 ~/.config/flower/.env。