feat(skill): multi-provider image generation with auto-fallback

- Add Gemini, Seedream (Volcengine Ark), Qwen (DashScope), MiniMax providers to image-generation skill with universal sequential fallback: OpenAI → Gemini → Seedream → Qwen → MiniMax → LinkAI - Each provider filters unsupported size tiers to valid values (e.g. Seedream 1K→2K, Qwen 3K→2K, Gemini 3K→2K) - Pinned model only tries its native provider; auto-routing uses each provider's default model - Support skill-namespaced config (config.skill.image-generation.model → SKILL_IMAGE_GENERATION_MODEL env var) - Add image lightbox (click-to-enlarge) in web console - Add docs for built-in skills (skill-creator, knowledge-wiki, image-generation) under docs/skills/
2026-07-20 05:27:59 +08:00 · 2026-04-23 12:39:39 +08:00
parent 81e8bb62ae
commit 68ce2e5232
16 changed files with 2189 additions and 84 deletions
--- a/docs/ja/skills/image-generation.mdx
+++ b/docs/ja/skills/image-generation.mdx
@@ -0,0 +1,158 @@
+---
+title: image-generation - 画像生成
+description: テキストから画像生成 / 画像編集 / 複数画像の融合、複数プロバイダーの自動ルーティングとフォールバック対応
+---
+
+汎用の画像生成・編集スキルです。OpenAI、Gemini、Seedream（Volcengine Ark）、Qwen（DashScope）、MiniMax、LinkAI の 6 社に対応。モデルを手動で選ぶ必要はなく、固定の優先順位に従って、設定済みのプロバイダーを自動的に選択します。
+
+## モデル選択
+
+`image-generation` は「固定優先度 + 自動フォールバック」のストラテジーを採用しています。API Key を設定するだけで使えます：
+
+1. **優先順位**: `OpenAI → Gemini → Seedream → Qwen → MiniMax → LinkAI`
+2. **未設定のプロバイダーはスキップ**: API Key が設定されているプロバイダーのみが参加
+3. **失敗時は自動で次へ**: 401、モデル未開通、ネットワークエラーなどの場合、次のプロバイダーを試行
+4. **モデル指定時は前置**: 特定のモデル名を渡すと、そのプロバイダーが最前列に昇格
+
+### 対応モデル
+
+| プロバイダー | モデル / エイリアス | 特徴 |
+| --- | --- | --- |
+| OpenAI | `gpt-image-2`、`gpt-image-1` | 汎用テキスト→画像、高品質、`quality` パラメータ対応 |
+| Gemini Nano Banana | `nano-banana-2`、`nano-banana-pro`、`nano-banana` | `gemini-3.1-flash`、`gemini-3-pro`、`gemini-2.5-flash` の画像バージョン |
+| Seedream（Volcengine Ark） | `seedream-5.0-lite`、`seedream-4.5` | ネイティブ 2K–4K、最大 14 枚の参照画像を融合 |
+| Qwen（DashScope） | `qwen-image-2.0`、`qwen-image-2.0-pro` | 中国語テキスト描画やテキスト・画像レイアウトに強い |
+| MiniMax | `image-01` | シンプルで高速な画像生成 |
+| LinkAI | 任意のモデル | 汎用プロキシ、フォールバック用 |
+
+<Note>
+デフォルトでは Agent はモデルを選ばず、自動ルーティングを使用します。特定のモデルを使いたい場合は、会話で直接指定してください（例：「seedream で猫を描いて」「gpt-image-2 でポスターを作って」）。下記の「カスタム設定」でデフォルトモデルを固定することもできます。
+</Note>
+
+## カスタム設定
+
+### API Key の設定
+
+**少なくとも 1 つ**のプロバイダーの Key が必要です。複数設定すると自動フォールバックが有効になります。設定方法は 3 通り：
+
+#### 方法 1：既存のモデル Key を自動再利用
+
+Web コンソールや `config.json` で対話モデルの Key（`openai_api_key`、`gemini_api_key` など）を設定済みの場合、起動時にこれらの Key は対応する環境変数に**自動同期**されます。つまり、対話モデルが使えていれば、画像生成も同じ Key で追加設定なしに利用できます。
+
+#### 方法 2：config.json で設定
+
+`config.json` に Key フィールドを直接記述：
+
+```json
+{
+  "openai_api_key": "sk-xxx",
+  "openai_api_base": "https://api.openai.com/v1",
+  "gemini_api_key": "AIza-xxx",
+  "ark_api_key": "xxx",
+  "dashscope_api_key": "sk-xxx",
+  "minimax_api_key": "xxx",
+  "linkai_api_key": "xxx"
+}
+```
+
+変更後は再起動が必要です。各 Key には対応する `*_api_base` フィールドがあり、カスタムエンドポイントを指定できます。
+
+#### 方法 3：会話で直接設定
+
+チャットで API Key を送信すると、Agent が `env_config` ツールで `~/cow/.env` に保存します。**再起動不要**でただちに反映されます。例：
+
+```
+OPENAI_API_KEY を sk-xxx に設定して
+```
+
+または：
+
+```
+ARK_API_KEY を xxx に設定して
+```
+
+### API Key 一覧
+
+| 環境変数 | config.json フィールド | プロバイダー | デフォルト Base URL |
+| --- | --- | --- | --- |
+| `OPENAI_API_KEY` | `openai_api_key` | OpenAI | `https://api.openai.com/v1` |
+| `GEMINI_API_KEY` | `gemini_api_key` | Gemini | `https://generativelanguage.googleapis.com` |
+| `ARK_API_KEY` | `ark_api_key` | Volcengine Ark（Seedream） | `https://ark.cn-beijing.volces.com/api/v3` |
+| `DASHSCOPE_API_KEY` | `dashscope_api_key` | Alibaba DashScope（Qwen） | `https://dashscope.aliyuncs.com` |
+| `MINIMAX_API_KEY` | `minimax_api_key` | MiniMax | `https://api.minimaxi.com` |
+| `LINKAI_API_KEY` | `linkai_api_key` | LinkAI | `https://api.link-ai.tech` |
+
+### デフォルトモデルの固定
+
+すべての画像生成を特定のプロバイダーのモデルで固定したい場合、`config.json` に以下を追加：
+
+```json
+"skill": {
+  "image-generation": {
+    "model": "seedream-5.0-lite"
+  }
+}
+```
+
+起動時にこの設定は環境変数 `SKILL_IMAGE_GENERATION_MODEL` に自動変換され、スクリプトはこのモデルのプロバイダーを常に使用します。
+
+## 有効化と無効化
+
+`image-generation` は内蔵スキルで、**API Key に基づいてステータスが自動調整**されます：
+
+- **Key 設定済み**：スキルはアクティブ — Agent は画像生成リクエストを受けると呼び出す
+- **Key 未設定**：スキルはコンテキストに表示される（「設定が必要」とマーク）— Agent は呼び出し失敗の代わりに Key の設定を案内する
+
+手動で制御する場合：
+
+```text
+/skill disable image-generation    # 無効化（Key があっても呼び出されない）
+/skill enable image-generation     # 再有効化
+```
+
+ターミナルでは `cow skill disable image-generation` / `cow skill enable image-generation`。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | デフォルト | 説明 |
+| --- | --- | --- | --- | --- |
+| `prompt` | string | はい | — | 画像の説明 |
+| `image_url` | string / list | いいえ | null | 編集用の入力画像。ローカルパスまたは URL。複数指定で複数画像融合 |
+| `quality` | string | いいえ | auto | `low` / `medium` / `high` — 一部のプロバイダーのみ対応 |
+| `size` | string | いいえ | auto | `512` / `1K` / `2K` / `3K` / `4K`、またはピクセル値（例: `1024x1024`） |
+| `aspect_ratio` | string | いいえ | null | `1:1` / `3:2` / `2:3` / `16:9` / `9:16` / `21:9`；Gemini は `1:4` / `4:1` / `1:8` / `8:1` にも対応 |
+
+<Warning>
+**品質が高いほど・解像度が大きいほど、コストが高く、時間がかかります。**
+
+- 日常の会話やプレビューにはデフォルト（`auto`）、または `quality=low` + `size=1K` を使用 — 約 20 秒で生成
+- ポスターやユーザーが高解像度を明示的に要求した場合は `quality=high` + `size=2K/4K` — モデルによって 1〜5 分かかる場合があります
+</Warning>
+
+## 出力
+
+成功時：
+
+```json
+{
+  "model": "doubao-seedream-5-0-260128",
+  "images": [
+    {"url": "/path/to/output.png"}
+  ]
+}
+```
+
+失敗時：`{ "error": "..." }`。エラー後は**直接リトライしないでください** — ほぼ確実に設定の問題です（Key の誤り、API ベース URL の不一致、モデル未開通など）。まず設定を修正してから再試行してください。
+
+## よくある使い方
+
+- **テキスト→画像**：説明からイラスト、ポスター、アイコン、アバター、絵コンテなどを生成
+- **画像→画像**：既存の画像のスタイル変更、要素の入れ替え、装飾やテキストの追加
+- **複数画像の融合**：複数の参照画像を 1 枚に合成（着せ替え、キャラクター集合写真など）
+
+<Note>
+- bash タイムアウトは 600 秒に設定してください。各プロバイダーの HTTP タイムアウトは 300 秒ですが、スクリプトが複数のプロバイダーを順番に試行する場合があります
+- 入力画像は自動的に 4 MB 以下・最長辺 4096 px 以下に圧縮されます
+- Gemini / Seedream / Qwen / MiniMax は `quality` パラメータに対応していません（渡しても無視されます）
+- Seedream のデフォルトは 2K。`seedream-5.0-lite` は 3K まで、`seedream-4.5` は 4K まで対応
+</Note>
--- a/docs/ja/skills/knowledge-wiki.mdx
+++ b/docs/ja/skills/knowledge-wiki.mdx
@@ -0,0 +1,112 @@
+---
+title: knowledge-wiki - ナレッジベース
+description: ローカルの構造化ナレッジベースを管理し、自動でアーカイブ・分類・相互参照を行う
+---
+
+会話で生まれた資料、アイデア、メモをローカルの構造化ナレッジベースに整理し、インデックスとページ間の相互参照を自動で維持します。
+
+`knowledge-wiki` はワークスペース内の `knowledge/` ディレクトリを管理します。Agent の「外部メモリ」のようなものです。`always: true` が設定されているため**常にコンテキストにロード**され、外部依存は不要です。
+
+## いつ起動するか
+
+- 記事、ドキュメント、URL を共有して、後で参照できるように残したいとき
+- 会話の中で長期保存に値する結論が出たとき
+- 以前蓄積したナレッジを調べたいとき
+
+## ディレクトリ構成
+
+```
+knowledge/
+├── index.md           # グローバルインデックス（必ずメンテナンスする）
+├── log.md             # 操作ログ（追記のみ）
+└── <category>/        # カテゴリサブディレクトリ（内容ごとにグループ化）
+    └── <slug>.md      # ナレッジページ（小文字ハイフン区切りのファイル名）
+```
+
+## 3 つの基本操作
+
+### 1. 収録（Ingest）
+
+資料を共有すると、Agent は：
+
+1. 原文を読んで理解し、重要な情報を抽出
+2. どのカテゴリに属するか判断 — まず `index.md` をチェックし、適切なカテゴリがなければ新規作成
+3. `knowledge/<category>/<slug>.md` にナレッジページを生成
+4. インデックス `index.md` とログ `log.md` を更新
+
+### 2. 統合（Synthesize）
+
+会話の中で新しい結論やインサイトが生まれたとき：
+
+1. 適切なカテゴリの下に新しいナレッジページを作成
+2. 関連する既存ページに相互リンクを追加
+3. インデックスとログを更新
+
+### 3. 検索（Query）
+
+以前蓄積したナレッジについて質問されたとき：
+
+1. `index.md` から関連しそうなページを探す
+2. `read` ツールで具体的なページを開く
+3. 必要に応じて `memory_search` で補完検索
+4. 回答にナレッジページへのリンクを含め、ユーザーが原文を確認できるようにする
+
+## ページの書き方
+
+```markdown
+# ページタイトル
+
+> Source: <ソース URL または簡単な説明>
+
+本文。ページ間は相対パスでリンク：
+[関連ページ](../category/related-page.md)
+
+## 要点
+
+- ...
+
+## 関連ページ
+
+- [ページ A](../category/page-a.md) — 関連する理由
+```
+
+<Note>
+- `> Source:` はこのナレッジの出典を記録します。明確な出典がある場合は必ず記載してください
+- 相互参照は重要です：ページを作成・更新したら、関連ページにも逆リンクを追加してください
+- **既に存在するページにのみリンクしてください**。ある概念が独立ページに値する場合は、先にページを作成してからリンクを追加してください
+</Note>
+
+## インデックス形式
+
+`knowledge/index.md` はフラットリスト形式で、カテゴリごとにグループ化し、各ナレッジページを 1 行で表します：
+
+```markdown
+# Knowledge Index
+
+## カテゴリ A
+- [ページタイトル](category-a/page-slug.md) — 一行の要約
+
+## カテゴリ B
+- [ページタイトル](category-b/page-slug.md) — 一行の要約
+```
+
+テーブルや絵文字は使いません。カテゴリ名や構成は柔軟に調整できます。
+
+## ログ形式
+
+`knowledge/log.md` は追記のみ、最新のエントリが一番下：
+
+```markdown
+## [YYYY-MM-DD] ingest | ページタイトル
+## [YYYY-MM-DD] synthesize | ページタイトル
+```
+
+## 執筆ガイドライン
+
+- **ファイル名**は小文字＋ハイフン（例: `machine-learning.md`）
+- **1 ページ 1 トピック** — 関連コンテンツはリンクで繋ぐ
+- **重複ページを作らず、既存ページを更新する**
+- **変更のたびにインデックスを更新する**（`knowledge/index.md`）
+- **要点を抽出し、全文をコピーしない**
+- **会話中にナレッジページを参照する際はフルパスを使用**（例: `[タイトル](knowledge/<category>/<slug>.md)`）。ページ間の相互リンクのみ相対パスを使用
+- **ナレッジページに基づいて回答する際はリンクを含める** — ユーザーが詳細を確認できるように
--- a/docs/ja/skills/skill-creator.mdx
+++ b/docs/ja/skills/skill-creator.mdx
@@ -0,0 +1,180 @@
+---
+title: skill-creator - スキル作成
+description: スキルの作成・インストール・更新、SKILL.md の書き方とディレクトリ構成の標準化
+---
+
+`skill-creator` は「メタスキル」です。Agent が他のスキルを作成・インストール・更新する際に呼び出され、すべてのスキルの `SKILL.md` の書き方とディレクトリ構成を統一します。
+
+## いつ起動するか
+
+- ユーザーが URL やリモートリポジトリからスキルをインストールしたいとき
+- ユーザーが新しいスキルをゼロから作成したいとき
+- 既存のスキルをアップグレード・リファクタリングする必要があるとき
+
+## スキルとは
+
+スキルは「再利用可能な説明書」にオプションのスクリプトやリソースを加えたものです。特定のドメインの専門知識を Agent に注入し、該当タスクをスペシャリストのように処理できるようにします。
+
+スキルには通常、以下が含まれます：
+
+1. **専門ワークフロー** — ある種のタスクの完全な手順
+2. **ツールの使い方** — 特定の API やファイル形式の処理方法
+3. **ドメイン知識** — チームの規約、ビジネスルール、データ構造など
+4. **付属リソース** — スクリプト、参考ドキュメント、テンプレートなど
+
+<Note>
+**基本原則：省けるものは省く。** Agent が自力で推測できない内容だけを書きましょう。1 行追加するたびに「このトークンコストに見合うか？」と自問してください。
+</Note>
+
+## ディレクトリ構成
+
+```
+skill-name/
+├── SKILL.md            # 必須：スキル定義
+│   ├── YAML frontmatter（name / description は必須）
+│   └── Markdown 本文（説明 + 例）
+└── オプションリソース
+    ├── scripts/        # 実行可能スクリプト（Python / Bash など）
+    ├── references/     # 分量が多い参考ドキュメント（Agent が必要時に読む）
+    └── assets/         # テンプレート、アイコンなど（出力に直接使われるもの）
+```
+
+## SKILL.md 仕様
+
+SKILL.md ヘッダーの `frontmatter` フィールド：
+
+| フィールド | 説明 |
+| --- | --- |
+| `name` | スキル名。小文字＋ハイフン、ディレクトリ名と一致させる |
+| `description` | **最も重要なフィールド**。「このスキルが何をするか」「いつ使うべきか」を明記する。Agent はこれを見て呼び出すかどうかを判断する。トリガーに関する記述はすべてここに書き、本文には書かない |
+| `metadata.cowagent.requires.bins` | システムに必要な CLI ツール |
+| `metadata.cowagent.requires.env` | 必要な環境変数（すべて揃っている必要がある） |
+| `metadata.cowagent.requires.anyEnv` | 複数の API Key のうち 1 つあればよい |
+| `metadata.cowagent.requires.anyBins` | 複数のツールのうち 1 つあればよい |
+| `metadata.cowagent.always` | `true` にすると常にロードされ、依存チェックをスキップ |
+| `metadata.cowagent.emoji` | 表示用の絵文字（任意） |
+| `metadata.cowagent.os` | OS 制限、例: `["darwin", "linux"]` |
+
+<Note>
+`category` フィールドは手動で設定する必要はありません。システムが自動的に `skill` に設定します。
+</Note>
+
+API Key 依存の宣言方法は 2 通り：
+
+```yaml
+metadata:
+  cowagent:
+    requires:
+      env: ["MYAPI_KEY"]            # 必須
+```
+
+```yaml
+metadata:
+  cowagent:
+    requires:
+      anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]   # いずれか 1 つ
+```
+
+**スキルは依存関係に基づいて自動的に有効/無効になります**：環境変数が揃えば自動有効、不足すれば自動無効。手動で `/skill enable` する必要はありません。
+
+## リソースディレクトリの使い方
+
+| ディレクトリ | 入れるもの | 入れないもの |
+| --- | --- | --- |
+| `scripts/` | 繰り返し実行するコード、確定的な結果が必要なスクリプト | デモ用のコード片 |
+| `references/` | **500 行超**で SKILL.md に収まらない大きなドキュメント（完全な DB スキーマなど） | 一般的な API ドキュメント、チュートリアル |
+| `assets/` | 最終出力に含まれるファイル（テンプレート、アイコン、ボイラープレートなど） | 説明用ドキュメント |
+
+<Warning>
+**原則としてすべての内容を `SKILL.md` に書きます** — リソースディレクトリに分割するのは本当に収まらない場合だけです。
+
+`README.md`、`CHANGELOG.md`、`INSTALLATION_GUIDE.md` などをスキルに追加しないでください。すべて `SKILL.md` に入れましょう。リソースディレクトリには実際に実行するスクリプトや実際に使う素材だけを配置してください。
+</Warning>
+
+## 外部スキルのインストール
+
+インストール後、スキルは `<workspace>/skills/<name>/` に配置されます。
+
+| ソース | インストール方法 |
+| --- | --- |
+| URL（単一ファイル） | curl / web_fetch |
+| URL（zip アーカイブ） | ダウンロードして展開 |
+| ローカル SKILL.md | 直接読み込み |
+| ローカル zip アーカイブ | 展開 |
+
+インストール手順：
+
+1. `SKILL.md` を見つける（アーカイブのルートまたはサブディレクトリにある場合がある）
+2. frontmatter から `name` を読み取る
+3. **スキルディレクトリ全体**（`SKILL.md`、`scripts/`、`assets/` など）を `<workspace>/skills/<name>/` にコピー
+4. アーカイブに `INSTALL.md` などのセットアップスクリプトがあれば実行するが、最終的に `<workspace>/skills/<name>/` に収まっている必要がある
+
+## スキルをゼロから作成
+
+推奨手順：
+
+1. **要件を明確にする** — ユーザーに具体的なユースケースをいくつか挙げてもらう（一度に多く聞きすぎない）
+2. **構成を計画する** — スクリプトは必要か？参考ドキュメントは？テンプレートは？
+3. **スキャフォールド** — 初期化スクリプトを使用：
+
+   ```bash
+   scripts/init_skill.py <skill-name> --path <workspace>/skills [--resources scripts,references,assets] [--examples]
+   ```
+
+4. **内容を埋める** — SKILL.md を書き、スクリプトとリソースを追加。スクリプトは必ず実行テストする
+5. **バリデーション**（任意）：
+
+   ```bash
+   scripts/quick_validate.py <workspace>/skills/<skill-name>
+   ```
+
+6. **イテレーション** — 実際の使用フィードバックに基づいて継続的に改善
+
+## 命名規則
+
+- 小文字、数字、ハイフンのみ使用。ユーザーの入力は正規化する（例: `Plan Mode` → `plan-mode`）
+- 64 文字以内
+- 短く、動詞で始め、一目で何をするか分かるように
+- 必要に応じてツール名をプレフィックスにする（例: `gh-address-comments`、`linear-address-issue`）
+- ディレクトリ名と `name` フィールドは完全に一致させる
+
+## 3 段階ローディング
+
+スキルは一度にすべてコンテキストに読み込まれるわけではなく、3 段階で必要に応じてロードされます：
+
+1. **メタ情報**（`name` + `description`） — 常にコンテキスト内（約 100 語）。Agent がスキルを使うかどうかの判断に使用
+2. **SKILL.md 本文** — スキルが有効化されたときだけロード。500 行以内を推奨
+3. **リソースファイル** — Agent が必要なときに読み込む
+
+複数のバリエーション（例: マルチクラウドデプロイ）を持つスキルは次のように整理：
+
+```
+cloud-deploy/
+├── SKILL.md             # メインワークフローとプロバイダー選択ロジック
+└── references/
+    ├── aws.md
+    ├── gcp.md
+    └── azure.md
+```
+
+ユーザーが AWS を選んだら、Agent は `aws.md` だけを読みます。3 社分のドキュメントをすべてロードする必要はありません。
+
+## よくあるデザインパターン
+
+**ステップ式**：番号付きの手順と対応スクリプト。
+
+```markdown
+1. フォーム構造を分析（analyze_form.py を実行）
+2. フィールドマッピングを生成（fields.json を編集）
+3. フォームを自動入力（fill_form.py を実行）
+```
+
+**分岐式**：ユーザーの意図に応じて異なるフローへ。
+
+```markdown
+1. 操作タイプを判定：
+   **新規作成？** → 「作成フロー」へ
+   **既存の編集？** → 「編集フロー」へ
+```
+
+**テンプレート式**：出力形式に厳密な要件がある場合、SKILL.md にテンプレートを含め、Agent にそれに従って出力させる。