@comate/zulu 1.4.0-beta.3 → 1.4.0-beta.5

package/comate-engine/assets/skills/create-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-image
-description: "Generate/edit images with Nano Banana Pro (Gemini 3 Pro Image). Use for image create/modify requests incl. edits. Supports text-to-image + image-to-image; 1K/2K/4K resolution."
+description: "Generate/edit images with Nano Banana Pro (Gemini 3 Pro Image). Use for image create/modify requests incl. edits. Supports text-to-image + image-to-image; 1K/2K/4K resolution and multiple aspect ratios."
 metadata:
     enableWhen:
         - isInternalComateIDE
@@ -8,274 +8,270 @@ metadata:
 
 # Nano Banana Pro Image Generation & Editing
 
-Generate new images or edit existing ones using Google's Nano Banana Pro API (Gemini 3 Pro Image) via curl.
+Generate new images or edit existing ones using Google's Nano Banana Pro API (Gemini 3 Pro Image), via a unified cross-platform wrapper script.
 
-## Requirements
+---
+
+## Prerequisites
+
+- **macOS / Linux:** `curl`, `base64`, and **one** of `python3` / `jq` for JSON handling (python3 is preferred and universally available). Resolution auto-detect needs `sips` (macOS built-in) or `identify` (Linux, `imagemagick`).
+- **Windows:** `curl.exe` (Win10 1803+) and a PowerShell host. **Default to `powershell.exe`** (Windows PowerShell 5.1, ships with every Windows 10/11) — no detection needed. Only fall back to `pwsh.exe` (PowerShell 7+) if `powershell.exe` fails or is unavailable.
+- **Credentials:** the script resolves the encrypted login name automatically:
+  1. `COMATE_USERNAME_ENCRYPTED` env var, if set; otherwise
+  2. `~/.comate/login` JWT (written by the Comate IDE on login) — payload's `content.identity` is extracted.
+
+  Agents do **not** need to export the env var themselves as long as the user is signed in to Comate.
+
+---
 
-### macOS / Linux
+## PowerShell host on Windows
 
-- `curl` and `jq` must be installed
-- `base64` built-in
-- `sips` for auto-resolution detection (macOS built-in)
-- `identify` for auto-resolution detection (Linux, via `imagemagick`)
+**Default: `powershell.exe`** (Windows PowerShell 5.1). It ships with every Windows 10/11, so no probing is required — just call it directly.
 
-### Windows
+Only switch to `pwsh.exe` (PowerShell 7+) if `powershell.exe` is missing or the invocation fails for a host-specific reason.
 
-- `curl.exe` built-in (Windows 10 1803+)
-- PowerShell 5.1+ built-in (Windows 10+), used for all JSON parsing
+### Recommended invocation template
 
-### Common
+Always pass `-NoProfile -ExecutionPolicy Bypass -File <script>` so user profile overrides and execution-policy blocks cannot break the run:
 
-- API endpoint: `https://comate.baidu-int.com/api/aidevops/autocomate/rest/autowork/v1/generate-image`
-- Username is passed via Header `login-name`, NOT in the request body
-- Username: ${COMATE_USERNAME_ENCRYPTED}
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File <SKILL_DIR>\scripts\generate-image.ps1 `
+  -Prompt "..." -Output "hero-v1.png" ...
+```
+
+If that call fails because `powershell.exe` is unavailable, retry with `pwsh` using the same arguments.
 
 ---
 
-## Usage
 
-**Important:** Always save output images to the user's current working directory.
 
-### 1. Generate new image (text-to-image)
+Two scripts ship alongside this skill and encapsulate all HTTP / JSON / base64 / temp-file details. **Always call these instead of writing curl by hand.**
+
+- macOS / Linux: `scripts/generate-image.sh`
+- Windows:       `scripts/generate-image.ps1`
+
+Both produce output in `<projectRoot>/images/` (created on demand) and print the absolute path of the generated file to stdout.
 
-**macOS / Linux (bash/zsh):**
+### Arguments
+
+| Flag (bash)         | Param (PowerShell) | Required | Default | Values                                                          |
+|---------------------|--------------------|----------|---------|-----------------------------------------------------------------|
+| `--prompt`, `-p`    | `-Prompt`          | yes      | —       | any string                                                      |
+| `--output`, `-o`    | `-Output`          | yes      | —       | filename only (e.g. `hero-v1.png`), stored under `images/`      |
+| `--input`, `-i`     | `-InputPath`       | no       | —       | path to reference image (png/jpg/webp) for image-to-image       |
+| `--resolution`, `-r`| `-Resolution`      | no       | `1K`*   | `1K` / `2K` / `4K`                                              |
+| `--aspect-ratio`,`-a`| `-AspectRatio`    | no       | `1:1`   | `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` / `21:9` |
+
+*When `--input` is given and `--resolution` is omitted, the script auto-picks `4K` / `2K` / `1K` from the input image's longest edge (≥3000 / ≥1500 / else).
+
+### Parameter selection heuristics (when user is ambiguous)
+
+- "壁纸 / 横版封面 / banner" → `16:9`
+- "手机壁纸 / 竖屏海报" → `9:16`
+- "头像 / icon / 方形卡片" → `1:1`
+- "书籍插画 / 故事场景（横）" → `4:3` or `3:2`
+- "电影宽屏 / cinematic" → `21:9`
+- Draft / 快速试错 → `1K`; 中等交付 → `2K`; 定稿 → `4K`
+
+If intent is unclear, ask the user before calling.
+
+---
+
+## Usage
+
+### Text-to-image
+
+**macOS / Linux:**
 
 ```bash
-curl -s -X POST https://comate.baidu-int.com/api/aidevops/autocomate/rest/autowork/v1/generate-image \
-  -H "Content-Type: application/json" \
-  -H "login-name: ${COMATE_USERNAME_ENCRYPTED}" \
-  -d '{
-    "contents": [{"role": "USER", "parts": [{"text": "YOUR_PROMPT_HERE"}]}],
-    "resolution": "1K"
-  }' \
-  | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' \
-  | base64 --decode > output-name.png
+bash <SKILL_DIR>/scripts/generate-image.sh \
+  --prompt "a minimalist mountain at sunrise, flat illustration" \
+  --output hero-v1.png \
+  --aspect-ratio 16:9 \
+  --resolution 2K
 ```
 
 **Windows (PowerShell):**
 
+> Default to `powershell`; only fall back to `pwsh` if `powershell` fails or is unavailable.
+
 ```powershell
-# Write JSON to temp file to avoid PowerShell double-quote escaping bug with curl.exe -d
-$tmpFile = "$env:TEMP\request.json"
-@'
-{"contents":[{"role": "USER", "parts":[{"text":"YOUR_PROMPT_HERE"}]}],"resolution":"1K"}
-'@ | Set-Content -Path $tmpFile -Encoding UTF8 -NoNewline
-
-$response = curl.exe -s -X POST https://comate.baidu-int.com/api/aidevops/autocomate/rest/autowork/v1/generate-image `
-  -H "Content-Type: application/json" `
-  -H "login-name: $env:${COMATE_USERNAME_ENCRYPTED}" `
-  -d "@$tmpFile" | ConvertFrom-Json
-
-$imgBase64 = $response.candidates[0].content.parts |
-  Where-Object { $_.inlineData } |
-  Select-Object -First 1 -ExpandProperty inlineData |
-  Select-Object -ExpandProperty data
-[System.IO.File]::WriteAllBytes(
-  (Join-Path (Get-Location) "output-name.png"),
-  [System.Convert]::FromBase64String($imgBase64)
-)
+powershell -NoProfile -ExecutionPolicy Bypass -File <SKILL_DIR>\scripts\generate-image.ps1 `
+  -Prompt "a minimalist mountain at sunrise, flat illustration" `
+  -Output hero-v1.png `
+  -AspectRatio 16:9 `
+  -Resolution 2K
 ```
 
-### 2. Edit existing image (image-to-image)
+### Image-to-image (edit an existing file)
 
-**base64 image data is large — must write to a temp file, never inline in the command.**
-
-**macOS / Linux (bash/zsh):**
+**macOS / Linux:**
 
 ```bash
-# Step 1: encode input image
-IMG_B64=$(base64 -i path/to/input.png | tr -d '\n')
-
-# Step 2: write JSON to temp file
-cat > /tmp/request.json << EOF
-{
-  "contents": [
-    {
-      "role": "USER",
-      "parts": [
-        {"inline_data": {"mime_type": "image/png", "data": "${IMG_B64}"}},
-        {"text": "YOUR_EDIT_INSTRUCTIONS_HERE"}
-      ]
-    }
-  ],
-  "resolution": "2K"
-}
-EOF
-
-# Step 3: send request
-curl -s -X POST https://comate.baidu-int.com/api/aidevops/autocomate/rest/autowork/v1/generate-image \
-  -H "Content-Type: application/json" \
-  -H "login-name: ${COMATE_USERNAME_ENCRYPTED}" \
-  -d @/tmp/request.json \
-  | jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' \
-  | base64 --decode > output-name.png
+bash <SKILL_DIR>/scripts/generate-image.sh \
+  --prompt "repaint in Ghibli style, warmer palette" \
+  --input images/hero-v1.png \
+  --output hero-v2.png \
+  --aspect-ratio 16:9
 ```
 
 **Windows (PowerShell):**
 
 ```powershell
-# Step 1: encode input image
-$imgBytes  = [System.IO.File]::ReadAllBytes((Resolve-Path "path\to\input.png"))
-$imgBase64 = [System.Convert]::ToBase64String($imgBytes)
-
-# Step 2: write JSON to temp file
-$tmpFile = "$env:TEMP\request.json"
-@"
-{
-  "contents": [
-    {
-      "role": "USER",
-      "parts": [
-        {"inline_data": {"mime_type": "image/png", "data": "$imgBase64"}},
-        {"text": "YOUR_EDIT_INSTRUCTIONS_HERE"}
-      ]
-    }
-  ],
-  "resolution": "2K"
-}
-"@ | Set-Content -Path $tmpFile -Encoding UTF8
-
-# Step 3: send request
-$response = curl.exe -s -X POST https://comate.baidu-int.com/api/aidevops/autocomate/rest/autowork/v1/generate-image `
-  -H "Content-Type: application/json" `
-  -H "login-name: $env:${COMATE_USERNAME_ENCRYPTED}" `
-  -d "@$tmpFile" | ConvertFrom-Json
-
-$outBase64 = $response.candidates[0].content.parts |
-  Where-Object { $_.inlineData } |
-  Select-Object -First 1 -ExpandProperty inlineData |
-Select-Object -ExpandProperty data
-
-[System.IO.File]::WriteAllBytes(
-  (Join-Path (Get-Location) "output-name.png"),
-  [System.Convert]::FromBase64String($outBase64)
-)
+powershell -NoProfile -ExecutionPolicy Bypass -File <SKILL_DIR>\scripts\generate-image.ps1 `
+  -Prompt "repaint in Ghibli style, warmer palette" `
+  -InputPath images\hero-v1.png `
+  -Output hero-v2.png `
+  -AspectRatio 16:9
 ```
 
----
+`<SKILL_DIR>` resolves to this skill's directory at runtime. If the shell does not have that variable, substitute the absolute path to the skill folder.
+
+### Batch generation
 
-## Default Workflow (draft > iterate > final)
+Call the script multiple times (concurrent or sequential). Each run writes one image; use distinct `--output` names with a version suffix (`-v1`, `-v2`, `scene1`, `scene2`, …). Do NOT overwrite previous iterations.
 
-- Draft (1K): quick feedback loop
-- Iterate: adjust prompt in small diffs; keep filename new per run
-- Final (4K): only when prompt is locked
+---
 
-## Resolution Options
+## Output Directory & Naming
 
-- **1K** (default) - ~1024px, use for drafts and quick feedback
-- **2K** - ~2048px, use for mid-quality or medium-size input images
-- **4K** - ~4096px, use only when prompt is locked and quality is required
+- Always `<projectRoot>/images/` — unified location, **never** `.comate/images/` or other subfolders.
+- File names: kebab-case + version suffix (`hero-v1.png`, `scene1.png`). Iterate with `-v2`, `-v3` instead of overwriting.
 
 ---
 
-## Auto-Resolution Detection (image-to-image only)
+## Workflow (draft → iterate → final)
 
-When editing an existing image and the user has not specified a resolution,
-auto-detect based on the input image's longest edge.
+1. **Draft** — `--resolution 1K`, quick feedback loop.
+2. **Iterate** — tweak prompt in small diffs; bump filename (`-v2`, `-v3`).
+3. **Final** — re-run with `--resolution 4K` once the prompt is locked.
 
-**macOS (bash/zsh):**
+---
 
-```bash
-MAX_DIM=$(sips -g pixelWidth -g pixelHeight "input.png" \
-  | awk '/pixel/{print $2}' | sort -rn | head -1)
+## Output Display Format (MUST FOLLOW)
 
-if   [ "${MAX_DIM}" -ge 3000 ]; then RESOLUTION="4K"
-elif [ "${MAX_DIM}" -ge 1500 ]; then RESOLUTION="2K"
-else                                  RESOLUTION="1K"
-fi
-```
+After generation, display results using an **HTML `<table>` block** (NOT `![](path)` markdown). This renders as a polished gallery in the chat UI and in embedded `.md` files.
 
-**Linux (bash):**
+Each cell contains only:
 
-```bash
-# requires: apt install imagemagick  /  yum install imagemagick
-MAX_DIM=$(identify -format "%[fx:max(w,h)]" input.png)
+- `<img src="...">` with a `width` picked from the layout table below
 
-if   [ "${MAX_DIM}" -ge 3000 ]; then RESOLUTION="4K"
-elif [ "${MAX_DIM}" -ge 1500 ]; then RESOLUTION="2K"
-else                                  RESOLUTION="1K"
-fi
-```
+Do NOT add `<b>` titles or `<small>` captions unless the user explicitly asks for them. Keep cells image-only by default.
 
-**Windows (PowerShell):**
+### Path rule
 
-```powershell
-Add-Type -AssemblyName System.Drawing
-$img        = [System.Drawing.Image]::FromFile((Resolve-Path "input.png"))
-$maxDim     = [Math]::Max($img.Width, $img.Height)
-$img.Dispose()
-
-$resolution = if     ($maxDim -ge 3000) { "4K" }
-              elseif ($maxDim -ge 1500) { "2K" }
-              else                      { "1K" }
-```
+- Inside a `.md` file that lives next to the images → **relative path** (e.g. `scene1.png`).
+- Inline in chat reply:
+  - **macOS / Linux** → absolute path (e.g. `/Users/.../project/images/hero.png`).
+  - **Windows** → **relative path** (e.g. `images/hero.png`), because absolute Windows paths (e.g. `C:\Users\...`) do not render reliably inside `<img src>` in the chat UI / markdown preview.
+- **Always use forward slashes (`/`) in `<img src>` values, never backslashes (`\`)** — this applies to Windows too. For example, use `images/hero.png`, not `images\hero.png`.
+- Never mix absolute and relative formats in one table.
 
----
+### Layout rules
 
-## Prompt Handling
+| Image count | Layout                             | `width` per image |
+|-------------|------------------------------------|-------------------|
+| 1           | Single centered cell               | `640`             |
+| 2           | 1 row × 2 columns                  | `480`             |
+| 3           | 1 row × 3 columns                  | `360`             |
+| 4           | **2 rows × 2 columns** (preferred) | `480`             |
+| 5–6         | 2 rows × 3 columns                 | `360`             |
+| 7+          | 3 columns per row, wrap as needed  | `320`             |
 
-**For generation:** Pass the user's image description as-is to the `text` field.
-**For editing:** Pass editing instructions to the `text` field alongside the `inline_data` image part.
+### Single image
 
----
+```html
+<table>
+  <tr>
+    <td align="center">
+      <img src="/abs/path/to/images/hero.png" width="640" />
+    </td>
+  </tr>
+</table>
+```
 
-## Output
+On Windows, use a relative path with forward slashes instead:
 
-- Saves PNG to `.comate/images` directory, if directory is not exist, you need to create it.
-- Script outputs the full path to the generated image
-- **Do not read the image back** - display the image using markdown syntax: `![image](/absolute/path/to/image.png)`
-- **Display the image path only once** using an absolute path (e.g. `/home/user/project/.comate/images/output-name.png`)
-- Absolute paths are REQUIRED (e.g. paths starting with `/` on Unix or `C:\` on Windows);
-- do NOT use relative paths (e.g. `./output.png` or `images/output.png` formats are forbidden);
-- do NOT repeat the path multiple times in the conversation
+```html
+<table>
+  <tr>
+    <td align="center">
+      <img src="images/hero.png" width="640" />
+    </td>
+  </tr>
+</table>
+```
 
----
+### Multiple images (2×2 example)
+
+```html
+<table>
+  <tr>
+    <td align="center"><img src="/abs/path/to/images/scene1.png" width="480" /></td>
+    <td align="center"><img src="/abs/path/to/images/scene2.png" width="480" /></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="/abs/path/to/images/scene3.png" width="480" /></td>
+    <td align="center"><img src="/abs/path/to/images/scene4.png" width="480" /></td>
+  </tr>
+</table>
+```
 
-## Notes
+On Windows, use relative paths with forward slashes:
+
+```html
+<table>
+  <tr>
+    <td align="center"><img src="images/scene1.png" width="480" /></td>
+    <td align="center"><img src="images/scene2.png" width="480" /></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="images/scene3.png" width="480" /></td>
+    <td align="center"><img src="images/scene4.png" width="480" /></td>
+  </tr>
+</table>
+```
+
+### Display rules
 
-| Rule              | macOS/Linux                         | Windows                                                                                                                      |
-|-------------------|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
-| curl command      | `curl`                              | `curl.exe` (avoid PowerShell `curl` alias conflict)                                                                          |
-| `-d` body         | inline `'{"key":"val"}'` is fine    | **never** inline — PowerShell escapes `"` to `\u0022`, corrupts JSON; **always** write to temp file and use `-d "@$tmpFile"` |
-| base64 encode     | `base64 -i file \| tr -d '\n'`      | `[Convert]::ToBase64String([IO.File]::ReadAllBytes(...))`                                                                    |
-| base64 decode     | `base64 --decode`                   | `[IO.File]::WriteAllBytes(path, [Convert]::FromBase64String(...))` (PS 5.1 compatible)                                       |
-| image size detect | `sips` (macOS) / `identify` (Linux) | `System.Drawing.Image` (built-in)                                                                                            |
-| line continuation | `\`                                 | `` ` `` (backtick)                                                                                                           |
-| env variable      | `${COMATE_USERNAME_ENCRYPTED}`                | `$env:COMATE_USERNAME_ENCRYPTED`                                                                                                       |
+- Show the `<table>` block **once**; do not repeat paths elsewhere in the reply.
+- **Do not read the image back** with a file tool — just reference the printed path.
+- Do not use markdown `![]()` for the deliverable (only allowed inside the table's `<img>`).
 
 ---
 
-## Windows Pitfall: PowerShell escapes `"` when passing to external programs
+## Error Handling (Agent contract)
 
-When PowerShell passes a variable containing `"` to an external program like `curl.exe`,
-it silently converts `"` into `\u0022`, which corrupts JSON and causes the server to return:
+On any failure the script writes one or more **tagged, single-line messages** to stderr:
 
 ```
-JsonParseException: Unexpected character ('u'): was expecting double-quote to start field name
+[generate-image:<stage>] <message>
 ```
 
-**Wrong (never do this on Windows):**
+Always capture stderr alongside stdout (`bash ... 2>&1` or `$output = & ... 2>&1`) so you can forward the tag + message to the user. The final path on stdout only appears on success.
 
-```powershell
-$body = '{"contents":[...]}'
-curl.exe ... -d $body        # PowerShell corrupts the " characters
-```
+### Stages you may see
 
-**Correct — always write JSON to a temp file and pass with `-d @file`:**
+| Stage     | Meaning                                           | Typical remedy                                                     |
+|-----------|---------------------------------------------------|--------------------------------------------------------------------|
+| `args`    | bad / missing CLI flag                            | Fix the call — do NOT retry blindly                                |
+| `deps`    | `curl` / `base64` missing, or neither `python3` nor `jq` available | Ask user to install the missing tool (python3 preferred) |
+| `env`     | neither `COMATE_USERNAME_ENCRYPTED` nor `~/.comate/login` usable | Ask user to sign in to Comate, or export the env var |
+| `input`   | input image missing / unreadable / empty          | Verify the path, fix the `--input` argument                        |
+| `output`  | cannot create/use `images/` dir                   | Usually a file named `images` exists; rename or remove             |
+| `payload` | JSON build / write failed                         | Likely disk / `jq` issue; retry once                               |
+| `http`    | HTTP non-2xx or network failure; body snippet attached | Retry with smaller input/resolution or lower prompt size       |
+| `api`     | API returned `.error` or `no inlineData` — stderr includes the model's text explanation when present | Inspect the model message; often a policy rejection or bad prompt |
+| `write`   | decode/write-to-disk failed                       | Disk full / permissions                                            |
+| `tmp`     | `mktemp` failed                                   | `/tmp` full or read-only                                           |
 
-```powershell
-# Single-quote here-string: content is taken literally, no escaping
-$tmpFile = "$env:TEMP\request.json"
-@'
-{"contents":[{"role": "USER", "parts":[{"text":"YOUR_PROMPT_HERE"}]}],"resolution":"1K"}
-'@ | Set-Content -Path $tmpFile -Encoding UTF8 -NoNewline
+### Exit codes
 
-curl.exe ... -d "@$tmpFile"  # curl reads the file directly, no PowerShell escaping
-```
+`0` success · `2` args · `3` deps · `4` env · `5` input · `10` HTTP/network · `11` API error · `12` no image data · `13` local I/O
 
-**Here-string type selection:**
+### Idempotency guarantees
 
-| Situation                                  | Here-string type       | Reason                          |
-|--------------------------------------------|------------------------|---------------------------------|
-| text-to-image (no variables in JSON)       | `@'...'@` single-quote | content taken literally, safest |
-| image-to-image (need `$imgBase64` in JSON) | `@"..."@` double-quote | allows variable expansion       |
+- Existing `images/` directory is reused, not recreated.
+- Same `--output` filename will **overwrite** the previous file — if you want to keep both, use a new versioned filename (`-v2`, `-v3`).
+- Temp files in `$TMPDIR` / `%TEMP%` are always cleaned up, even on failure.
+- Safe to run concurrently with different `--output` names.