feat: add asynchronous Shujk image generation skill

2026-07-17 00:16:00 +08:00
commit 5ae8622f2d
3 changed files with 163 additions and 0 deletions
@@ -0,0 +1,70 @@
+---
+name: shujkimagegen-async-api
+description: Generate images through the server4 asynchronous Sub2API endpoint, poll the task, and download the resulting image.
+---
+
+# Shujk Async ImageGen API
+
+Use this helper when image generation should run asynchronously on server4.
+
+## Boundary
+
+- Do not print, copy, commit, or summarize API keys.
+- Read only `OPENAI_API_KEY` from `~/.codex/auth.json`; do not read plaintext `.env` files or unrelated secrets.
+- Keep the durable source in the Gitea repo `shujakuin/skill-shujkimagegen-api`; treat `ai-infra/skills/sources/shujkimagegen-api/` and HOME runtime copies as managed mirrors.
+- Do not place this skill under the infra repo's `.agents/skills/` or manage it through cc-switch WebDAV.
+- Treat this as a thin wrapper around the system `imagegen` CLI; do not copy or patch the system script.
+- Current HOME runtime placements are `pc` and `a100` under `~/.agents/skills/shujkimagegen-api/`. Update only explicitly modeled placements.
+
+## Endpoint
+
+- Async endpoint: `https://sub2apius.shujk.top/v1/images/generations/async`
+
+The `/v1` suffix is required because `/models` is an application page while `/v1/models` is the authenticated OpenAI-compatible API.
+
+## Workflow
+
+Run the wrapper:
+
+   ```bash
+   python3 ~/.agents/skills/shujkimagegen-async-api/scripts/shujk_imagegen.py \
+     --prompt "..." --out output/imagegen/example.png
+   ```
+
+The command submits a task, honors `Retry-After`, polls until completion, and downloads the object-storage URL.
+
+5. Save project-bound assets inside the active workspace and report the output path and final prompt.
+
+For source validation before placement, use the equivalent wrapper under the standalone checkout or infra mirror.
+
+## Installation Validation
+
+After placing the skill in `~/.agents/skills/shujkimagegen-api/`, validate the installed copy before reporting success:
+
+1. Confirm `SKILL.md`, `agents/openai.yaml`, and `scripts/shujk_imagegen.py` exist.
+2. Check whether the selected Python environment can import `openai`. Do not add it to an unrelated project's dependencies just for validation. If it is absent and `uv` is available, use an ephemeral environment:
+
+   ```bash
+   uv run --with openai python ~/.agents/skills/shujkimagegen-api/scripts/shujk_imagegen.py \
+     --print-config-redacted
+   ```
+
+3. Run a no-cost command-path test:
+
+   ```bash
+   uv run --with openai python ~/.agents/skills/shujkimagegen-api/scripts/shujk_imagegen.py \
+     generate --prompt "installation validation" --out /tmp/shujkimagegen-dry-run.png \
+     --dry-run --no-augment
+   ```
+
+4. When the user authorizes a real API test, generate one low-cost image with `gpt-image-2`, `quality=low`, and a simple prompt. Confirm the command exits successfully and inspect the resulting file as a real, non-empty image.
+5. Remove test artifacts that are not intended deliverables.
+
+If validation requires a compatibility fix, edit the standalone Gitea checkout first, rerun validation, commit and push it, then resync the infra mirror and selected runtime placement. Never leave the only fix in `~/.agents/skills/`.
+
+## Failure Handling
+
+- If `OPENAI_API_KEY` is absent, report that auth is unavailable without revealing file contents.
+- If the system imagegen CLI is missing, report its expected path.
+- If the endpoint rejects a model or option, retry only with an explicitly compatible model or option.
+- Do not silently fall back to `sub2apius.shujk.top` or another Cloudflare-proxied endpoint.