作成日: 2026-03-31
ステータス: Draft
前提文書:
docs/capabilities/maid/仕様書_v2.md（経緯参照）本仕様は、butler2 の Butler 配下にある内部実務ユニット群を Maid として再定義する。
v2 では、Maid を「Butler 配下の単一 provider 抽象」として整理していた。
v3 ではこれを拡張し、Maid を Butler が intent ごとに選択・監督する内部実行ユニットの抽象 として定義する。
Maid の実体は単一ではなく、用途ごとに異なる。
想定する実体:
v2 では、安価なモデルを OpenRouter で呼び、その不足している「手足」を Butler が自前実装する構想を取っていた。
しかし検討を進める中で、以下が分かった。
このため、「Butler が OpenRouter に手足を自作する」よりも、
Butler が複数の Maid 実体をルーティングして監督する 方が、構造として単純で現実的である。
Goose 試験では、完全自走ではなく「補助ありの部分成功」が確認された。
この問題は「Goose が使えない」ことを意味しない。
むしろ、以下の人間介入を Butler に移し替える設計問題として扱える。
したがって v3 では、Maid を完全自律にすることよりも、
Butler が Maid を監督しながら委譲を成立させる ことを優先する。
Maid は「実装AI」ではなく、Butler が委任できる内部実務ユニットである。
Maid は次の属性を持つ。
Butler は Maid の実体そのものではなく、Maid 群の管理者である。
Butler の責務:
Brain から見える窓口は Butler のみである。
Brain は「どの Goose / どの model を選ぶか」を意識しない。
Brain は以下だけを渡す。
Maid の選択・監督・検証は Butler 内部で完結させる。
ただし実装上は、Butler 本体そのものを最初から MCP サーバに埋め込まない。
現行方針では、Butler core を Python API として保ち、その上に
CLI / MCP などの facade を載せる。
Brain が MCP から見る入口は facade だが、routing / supervision / verification の実体は core 側に置く。
Brain
└─[MCP]──→ Butler
├─ MCP facade
├─ CLI facade
├─ Python API
├─ routing
├─ prompt builder
├─ launcher
├─ supervisor
├─ verifier
├─ session_complete / approval
└─ Maid Registry
├─ maid: goose_openrouter_impl
├─ maid: goose_ollama_impl
├─ maid: goose_docs
└─ maid: script_formatter
ACP または CLI 経由で起動される Goose 実体。
複数モデル・複数 role を持てる。
例:
goose_openrouter_qwen3coder30bgoose_openrouter_grok41fastgoose_ollama_qwen3_8bAI を伴わない決定論的スクリプト。
用途が固定で、AI を介す意味が薄い処理に使う。
初期方針として、Script Maid は次に限定する。
初期段階では、Script Maid は「定型生成」「format」「軽い変換」のような処理を主対象とし、
repo 全体探索や曖昧な仕様解釈を必要とする処理は担当しない。
例:
将来的な別エージェント実体。
CLI / ACP / MCP など接続方式は問わない。
Butler は intent ごとに適切な Maid を選択する。
初期段階では intent 単位で十分だが、将来的には条件付きルーティングを許容する。
ただし、ここでいう「intent ごとに選択する」は「常に委譲する」を意味しない。
初期段階では、task 規模や説明コストを見て非委譲を選ぶ余地を残す。
初期例:
| intent | maid | 備考 |
|---|---|---|
implement |
goose_openrouter_grok41fast_implement |
複雑実装の既定。小タスクは非委譲可 |
implement_docs |
goose_openrouter_grok41fast |
docs 系の候補例 |
review |
goose_openrouter_qwen3coder30b |
初期は共用可 |
format |
script_formatter |
AI 不要 |
初期段階では、Goose 系 Maid への委譲は次のような task を候補とする。
逆に次は非委譲としてよい。
ルーティングはコード分岐ではなく、テーブルまたはテーブル相当の設定で持つ。
最低限必要な概念:
maid_registryintent_maid_routesmaid_registry| カラム | 意味 |
|---|---|
maid_id |
内部識別子 |
kind |
goose / script / future |
label |
人間向け名前 |
provider |
openrouter / ollama / local_script など |
model |
利用モデル |
role |
worker の役割 |
command_template |
起動テンプレート |
enabled |
利用可否 |
verification_profile |
検証方法 |
初期実装では、maid_registry は SQLite ではなく YAML 設定ファイルで保持する。
理由は次の通り。
想定保存先:
config/maid_registry.ymlconfig/intent_maid_routes.ymlintent_maid_routes| カラム | 意味 |
|---|---|
intent |
Butler intent |
maid_id |
使用する Maid |
conditions_json |
route を適用する条件 |
retry_policy_json |
再試行方針 |
初期実装では、名前に _json を残していても、YAML 内では JSON 文字列ではなく通常の YAML ネストで保持する。
この命名は将来の内部表現変更を見越した論理名であり、保存形式を強制するものではない。
初期実装では priority は持たず、intent_maid_routes.yml の記述順に評価する。
したがって route の分岐は優先度数値ではなく、conditions_json を明示して曖昧さを減らす方針を取る。
Butler は自 repo 専用の固定ルートではなく、対象プロジェクトを切り替えて使える形を持つ。
現行実装では少なくとも次を facade 層から指定できる。
project_rootconfig_direnv_pathissue_template_dirsession_logs_dirこれにより、他プロジェクトの Brain / Codex からも同じ Butler core を利用できる。
verification_profile の最小定義verification_profile は、Butler verifier がその Maid 実行後に何を確認するかを定義する。
初期段階では自由形式にせず、次の定型要素だけを持つ。
| キー | 意味 |
|---|---|
http_checks |
URL と期待 status/body を確認する |
file_checks |
ファイル存在、有無、最小内容を確認する |
test_commands |
実行を許可された検証コマンド列 |
exact_output |
期待文字列との完全一致確認 |
初期例:
verification_profile:
http_checks:
- url: "http://127.0.0.1:8000/"
expect_status: 200
exact_output:
- url: "http://127.0.0.1:8000/"
expect: "hello world"
test_commands:
- "uv run pytest -q"
この profile は「成功判定」を定義するものであり、自由なシェル実行要求をそのまま受け入れるものではない。
実際の許可コマンドは Butler 側 allowlist に従う。
将来的には intent だけでなく、以下でも分岐できるようにしてよい。
1. Brain -> Butler: implement
2. Butler: 委譲すべき task かどうかを判断する
3. Butler: route table を引く
4. Butler: Goose Maid を選ぶ
5. Butler: hardened prompt を作る
6. Butler: Goose を launcher で起動
7. Butler: verifier で結果確認
8. 失敗時は Butler が再依頼
9. 成功時は session_complete / approval へ進む
10. Butler -> Brain: 結果返却
人間がやっていた補助は、原則として Butler の supervisor に移す。
対象例:
tree 不在時の代替指示pip install 禁止の再通知ただし、これらは goose_test リポジトリ Issue #1 に記録された代表例に過ぎず、失敗パターン全体を網羅したものではない。
supervision 設計は初期から過小評価せず、失敗分類の追加を前提に段階的に育てる。
Goose を完全自律 worker として放置しない。
Butler が監督者として外側に立ち、必要な補助を自動化する。
Brain → Butler → Goose → Butler(supervisor/verifier) → Brain
Goose Maid を使う場合、Butler 側には少なくとも以下が必要。
prompt_builderlaunchersupervisorverifierこれらは OpenRouter 手足の全面内製より小さくなる可能性があるが、
現時点では失敗パターンの多様性が未検証であり、実装コストを楽観しすぎない。
初期既定値として、supervisor は同一 task に対して 最大 3 回実行 する。
ここでいう 3 回実行は、初回実行 1 回 + 再依頼 2 回 を意味する。
3 回で回復しない場合、Butler は failed を返し、evidence に以下を残す。
この failed は「直ちに Brain が直接実装する」を意味しない。
Brain は evidence を見て、次のどれに進むかを判断する。
初期段階では、この失敗後判断は Butler の自動化対象ではなく Brain 側の判断として残す。
将来的には route ごとに retry_policy_json で上書きを許容してよいが、初期実装の既定は「最大 3 回実行」である。
v3 では、Ollama を Butler が直接叩く専用経路を減らし、
Ollama を使う Goose Maid へ寄せることを検討対象とする。
これは「モデル切り替え」をコード分岐ではなく maid 選択に寄せるためである。
以下はすべて「別 Goose」として管理できる。
これにより Butler は「どの model を呼ぶか」ではなく、
どの Maid を選ぶか に集中できる。
Maid 実体の採用は、完全自走かどうかだけで決めない。
以下で評価する。
この評価の結果、Maid は次のいずれかに分類される。
not_adoptedlimited_adoptiondefault_candidate現時点の Goose は、完全自走ではないため default_candidate ではなく、
limited_adoption 候補 として扱うのが妥当である。
v2:
v3:
maid_registry / intent_maid_routes を YAML で実装するsession_complete / approval と統合するdocs/黒執事アーキテクチャ_v2.mddocs/マスタードキュメント.mddocs/capabilities/maid/仕様書.md（経緯参照）docs/capabilities/maid/仕様書_v2.md（経緯参照）goose_test リポジトリ Issue #1 に記録された実験メモ（経緯参照）