デプロイと拡張¶

flower を別の場所に持っていくとき、扱うことは三つある。コンテナ(制限のない Bash を囲い込む、 ついでに「CLI から独立している」という主張を検証する)、 plugin(ドメイン能力がリポジトリに付いて回る。ホストマシンに何が入っているかは見ない)、 ドキュメントサイト(main に push すれば自動で公開、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 はスクリプト自身の位置から導出しており、パスをハードコードしていない。だからリポジトリをどこに clone しても使える。

イメージをビルドしてコンテナを起動する¶

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 の先頭に - が付くのがこの状態)。扱うべきかどうか:

中国国内のネットワーク:なぜあれだけミラー差し替えがあるのか¶

この一式を Great Firewall の内側で入れるとき、遅いのは帯域ではなく国際回線だ。デフォルトの 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        # 前のタグ
git log --oneline <前のタグ>..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/ が効かないのは設定漏れではなく、この制約の定義そのものだ:ホストマシンから 1 バイトでも読む限り、 「マシンを変えても挙動が同じ」は成り立たない。したがってドメイン能力の通り道は一つしかない —— リポジトリに付いて回る plugin/ だ。

スイッチは二つ(どちらも build_options() にあり、デフォルト値がポータブルな側):

ついでに:instructions は追記(system_prompt の append)を通り、 plugin とは別の通り道だ —— 前者は毎ターンコンテキストに載り、後者は必要に応じて読み込まれる。 短くて必須の規律は instructions に、長くてたまに役立つ知識は skill に書く。

三、ドキュメントサイト¶

いま読んでいるこのサイトは mkdocs-material で作られており、ソースはリポジトリの docs/ 配下にある。 main に push すれば自動で公開される。

ローカルでドキュメントを直すとき:

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

CI のトリガー条件は main への push かつ変更が以下のパスにヒットすること。加えて 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 に保存される。