⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.2.2

agnes-ai-skill

jomeswang@jomeswang⭐ 47 stars· last commit 5mo ago· 0 open issues

Agnes API key used for live authenticated text, image, and video requests. The skill can still load without it and guide setup.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 47 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Agnes AI Free Text, Image & Video Generation Skill

MIT License Agent Skill Models Agnes AI Chinese README

Agnes AI Skill is a free multimodal Agent Skill for Codex, Claude Code, OpenClaw, Claude Desktop, Hermes, WorkBuddy, Cherry Studio, Opencode, and similar AI agent tools. It helps agents use Agnes 2.0 APIs for text generation, image generation, image editing, text-to-video, image-to-video, and API integration through a single root SKILL.md.

Use this Agnes skill when you want an Agnes AI skill, image generation skill, video generation skill, text to image workflow, image to video workflow, free AI API workflow, or free AI model workflow that fits Codex skills, Claude Code skills, and OpenClaw skills.

中文:Agnes AI 免费文本 / 生图 / 图片编辑 / 生视频 Agent Skill,支持 Codex、 Claude Code、OpenClaw、Claude Desktop、Hermes、WorkBuddy、Cherry Studio、 Opencode 等工具。

Quick Start

Install the skill with a repository-aware skills installer:

npx skills add jomeswang/agnes-ai-skill -g

Or copy this sentence to your agent:

Please read and install Agnes AI Skill: https://github.com/jomeswang/agnes-ai-skill

After installation, create an Agnes API key at platform.agnes-ai.com/settings/apiKeys and configure it as AGNES_API_KEY. Then tell the agent generate an image, generate a video, edit this image, or integrate Agnes API, and it can choose the proper Agnes model and execution path automatically.

This skill helps agents:

  • set up Agnes AI and persist an AGNES_API_KEY
  • use agnes-2.0-flash for chat, coding, streaming, and tool calling
  • use agnes-image-2.0-flash and agnes-image-2.1-flash for AI image generation, image editing, and image-to-image workflows
  • use agnes-video-v2.0 for text-to-video, image-to-video, and async video generation
  • prefer the companion agnes-ai-cli for live requests

Compatible tools: Codex, Claude Code, Claude Desktop, OpenClaw, Hermes, WorkBuddy, Cherry Studio, Opencode, Kimi Work, and other Agent Skills / SKILL.md-compatible environments.

Agnes AI frontier models hero

Important Announcement

Agnes 2.0 full-modal model APIs are officially open for free global calls.

  • No fixed end date, full-modal access, and free API calls within RPM 20
  • Register on the official platform, create a key, and call directly
  • Text, image, and video are all supported
  • Models keep upgrading while free access is maintained

Official platform: https://platform.agnes-ai.com

The live official model docs also include pricing sections. For cost, quota, or commercial use, check the current official docs first.

This repository packages a single root SKILL.md so coding agents can quickly:

  • get and persist an Agnes API key
  • use agnes-2.0-flash for chat, coding, streaming, and tool calling
  • use agnes-image-2.0-flash and agnes-image-2.1-flash for image generation and editing
  • use agnes-video-v2.0 for asynchronous video generation and polling

It is designed for the exact pitch that makes Agnes easy to try:

  • one provider for text, image, and video
  • public free-access positioning that lowers experimentation friction
  • agent, creative, and prototyping workflows where repeated calls matter

The skill stays intentionally lightweight. It teaches agents how to make Agnes API calls successfully without copying the full docs into the repository.

Install

With a repository-aware skills installer:

npx skills add jomeswang/agnes-ai-skill -g

Because this repository uses a single root SKILL.md, installers that support repository-root skills can discover it directly.

Verified Install Path

This repository has been validated with:

npx skills add jomeswang/agnes-ai-skill --list
npx skills add jomeswang/agnes-ai-skill --agent codex --yes

The repository is discoverable as a single root-level skill named agnes-ai-skill.

Companion CLI

The published companion execution layer is:

Install it when you want stable commands instead of hand-written requests:

npm install -g agnes-ai-cli
agnes --help

Model Guide

Use the repository skill with these defaults:

  • agnes-2.0-flash
    • chat, coding, streaming, tool calling, and agent workflows
    • default when text chat runs without --model
  • agnes-image-2.1-flash
    • default for new text-to-image and image-to-image work
    • strongest fit for denser layouts, richer detail, and better semantic alignment
    • default when image text2img, image img2img, or image compose runs without --model
  • agnes-image-2.0-flash
    • better when you explicitly need its documented tags: ["img2img"] flow, multi-image composition, or seed-based reproducibility
  • agnes-video-v2.0
    • text-to-video, image-to-video, multi-image guided video, keyframes, and asynchronous polling
    • current default when any video generate command runs without --model

The official docs also give each model fairly different best practices:

  • Image 2.1 leans into high-information-density visuals and composition preservation
  • Image 2.0 is more explicit about edit/composition workflows, response fields, and OpenAI Images-style compatibility
  • Video 2.0 is task-based and documents multiple generation modes, task states, result polling, and frame-count constraints

Showcase

The strongest outside prompt libraries all do the same three things well: lead with a preview, keep the prompt compact enough to scan, and organize examples by outcome instead of by raw API parameter lists. This gallery follows that pattern with 9 compact cases regenerated with Agnes on June 1, 2026. The image prompts were tightened toward the shorter, more editorial style seen in awesome-gpt-image-2, the video prompts were rebuilt around ad-film, animation, and cinematic beats inspired by awesome-seedance, and the HTML cases were regenerated as brighter, more public-facing product experiences.

Image Cases

agnes-image-2.1-flash

PreviewCaseModelPrompt recipe
Y2K golden hour portraitY2K golden hour portraitagnes-image-2.1-flashCandid blonde portrait, baby-pink velour tracksuit, butterfly clips, glossy lips, palm trees, warm golden hour, real skin texture, soft film grain.
Pencil editorial fashionPencil editorial fashionagnes-image-2.1-flashMinimal monochrome pencil-sketch fashion portrait, round sunglasses, rolled white shirt, denim overalls, combat boots, burnt-orange circle, indie magazine composition.
Brand envelope perfume adBrand-envelope perfume adagnes-image-2.1-flashDusty-rose brand world, travertine pedestal, translucent perfume bottle, matte cream paper curves, warm studio light, quiet-luxury beauty campaign.

Video Cases

agnes-video-v2.0

PreviewCaseModelPrompt recipe
Perfume ad film first framePerfume ad filmagnes-video-v2.0Ten-second luxury commercial with macr

// HOW IT'S BUILT

// FILES

40 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md17 KBedd3830b7df2upstream ↗
    ---
    name: agnes-ai-skill
    version: 1.2.2
    description: "Use when the user wants Agnes AI text, image, or video generation and should execute it through the agnes-ai-cli command line instead of hand-writing raw HTTP requests."
    tags:
      - agnes
      - agnes-ai
      - agnes-skill
      - multimodal-ai
      - free-ai-api
      - free-ai-model
      - text-generation
      - image-generation
      - ai-image-generation
      - text-to-image
      - image-editing
      - image-to-image
      - video-generation
      - ai-video-generation
      - text-to-video
      - image-to-video
      - api-integration
      - agent-skill
      - codex
      - claude-code
      - openclaw
    metadata:
      openclaw:
        emoji: "sparkles"
        homepage: "https://github.com/jomeswang/agnes-ai-skill"
        requires:
          bins:
            - npm
            - npx
            - node
        primaryEnv: AGNES_API_KEY
        envVars:
          - name: AGNES_API_KEY
            required: false
            description: Agnes API key used for live authenticated text, image, and video requests. The skill can still load without it and guide setup.
    ---
    
    # Agnes AI Skill
    
    Use this skill when the user wants Agnes AI text, image, or video generation.
    This skill is now **CLI-first**: prefer `agnes-ai-cli` for all live execution,
    guide the user through `--help` when needed, and do not default to hand-written
    `curl` commands for Agnes work.
    
    Agnes is attractive because one platform covers:
    
    - text with `agnes-2.0-flash`
    - image generation and editing with `agnes-image-2.1-flash` and
      `agnes-image-2.0-flash`
    - video generation with `agnes-video-v2.0`
    
    Some public June 2026 materials positioned Agnes as broadly free to try. The
    live docs also include pricing sections, so treat that free-access message as a
    strong but time-sensitive positioning claim and verify current billing when the
    user cares about cost.
    
    ## When To Use
    
    Use this skill when:
    
    - the user mentions Agnes AI, `agnes-ai.com`, or the Agnes platform
    - the user wants one provider for text, image, and video generation
    - the user wants Agnes text, image, or video APIs executed from a terminal
    - the user wants image-to-image, multi-image composition, image-to-video, or
      keyframe video generation
    - the user wants a low-friction multimodal API for prototyping, agent loops,
      creative iteration, ecommerce content, or storyboard work
    
    Do not use this skill when:
    
    - the user is asking for a different provider only
    - the task does not need Agnes-specific models, auth, or request behavior
    - you would have to guess current Agnes behavior without running the CLI or
      checking the live docs
    
    ## Source Of Truth
    
    Prefer these Agnes pages:
    
    - Quickstart: `https://agnes-ai.com/doc/quickstart`
    - API key page: `https://platform.agnes-ai.com/settings/apiKeys`
    - Text docs: `https://agnes-ai.com/doc/agnes-20-flash`
    - Image 2.0 docs: `https://agnes-ai.com/doc/agnes-image-20-flash`
    - Image 2.1 docs: `https://agnes-ai.com/doc/agnes-image-21-flash`
    - Video docs: `https://agnes-ai.com/doc/agnes-video-v20`
    - Published CLI: `https://www.npmjs.com/package/agnes-ai-cli`
    - CLI repo: `https://github.com/jomeswang/agnes-ai-cli`
    
    Use public articles only as supporting context for likely use cases and product
    positioning, not as the operational source of truth.
    
    ## Base URL And Auth
    
    - Base URL: `https://apihub.agnes-ai.com/v1`
    - Main environment variable: `AGNES_API_KEY`
    - Preferred execution package: `agnes-ai-cli`
    
    Check `AGNES_API_KEY` before making live Agnes requests.
    
    ## Missing Key Behavior
    
    If `AGNES_API_KEY` is missing and the task requires live Agnes access:
    
    1. Tell the user Agnes access is not configured yet.
    2. Point them to:
       - `https://agnes-ai.com/doc/quickstart`
       - `https://platform.agnes-ai.com/settings/apiKeys`
    3. Explain the path briefly:
       `Settings -> API Keys -> Create new secret key`
    4. Ask them to provide the key if they want you to save it for future use.
    
    Do not continue with live Agnes calls until a valid key exists.
    
    ## Chinese Quick Start Response
    
    When a Chinese-speaking user asks how to get started, install, or use Agnes
    from an agent tool, give them this concise copy-paste path:
    
    ```text
    Please read and install Agnes AI Skill: https://github.com/jomeswang/agnes-ai-skill
    ```
    
    Then explain:
    
    - install the skill into the agent's skill directory or use a repository-aware
      installer such as `npx skills add jomeswang/agnes-ai-skill -g`
    - create an Agnes API key at `https://platform.agnes-ai.com/settings/apiKeys`
      and configure it as `AGNES_API_KEY`
    - say `generate an image`, `generate a video`, or `integrate Agnes API`
    - the agent should choose the proper Agnes model and use `agnes-ai-cli` when it
      is available
    
    Keep this onboarding short before moving into model-specific details.
    
    ## Persisting The Key Permanently
    
    If the user explicitly gives you an Agnes key and wants it remembered, persist
    it for future terminal sessions instead of keeping it only in the current
    process.
    
    ### Rules
    
    - Save it as `AGNES_API_KEY`
    - Detect the shell and write to the matching rc file:
      - zsh -> `~/.zshrc`
      - bash -> `~/.bashrc`
      - fallback -> `~/.profile`
    - Update an existing `export AGNES_API_KEY=...` line if present
    - Otherwise append a new export line
    - Also export it in the current session immediately
    - Do not echo the full key back after saving
    - Tell the user which rc file you changed
    
    ### Reliable Shell Snippet
    
    Use a non-interactive shell flow like this when saving a provided key:
    
    ```bash
    AGNES_API_KEY_VALUE='USER_PROVIDED_KEY'
    shell_name="$(basename "${SHELL:-}")"
    case "$shell_name" in
      zsh) rc_file="$HOME/.zshrc" ;;
      bash) rc_file="$HOME/.bashrc" ;;
      *) rc_file="$HOME/.profile" ;;
    esac
    
    touch "$rc_file"
    tmp_file="$(mktemp)"
    grep -v '^export AGNES_API_KEY=' "$rc_file" > "$tmp_file" || true
    printf '\nexport AGNES_API_KEY=%q\n' "$AGNES_API_KEY_VALUE" >> "$tmp_file"
    mv "$tmp_file" "$rc_file"
    export AGNES_API_KEY="$AGNES_API_KEY_VALUE"
    unset AGNES_API_KEY_VALUE
    ```
    
    After saving, continue using `AGNES_API_KEY` for the current task.
    
    ## Execution Contract
    
    This skill should execute Agnes through the CLI, not by manually composing raw
    HTTP requests.
    
    ### Preferred Order
    
    1. First use the no-install command path:
       - `npx -y agnes-ai-cli@^0.1.0 --help`
    2. Use `npx -y agnes-ai-cli@^0.1.0 ...` as the default live execution path
       in fresh or unknown environments.
    3. If a local `agnes` binary already exists, run:
       - `agnes --version`
       - `agnes --help`
    4. Use the local binary only when its version falls inside:
       - `>=0.1.0 <0.2.0`
    5. Do not fall back to raw `curl` for normal Agnes execution paths.
    
    ### Why CLI-First
    
    The CLI already handles:
    
    - auth checks
    - local file to temporary public URL bridging
    - image request normalization
    - video task creation
    - video polling
    - JSON output for agent consumption
    
    That means the agent should select the right CLI command, not rebuild the
    underlying HTTP payload each time.
    
    ## Mandatory `--help` Guidance
    
    When the user is new to the CLI, or when you are about to use a less common
    command, guide through `--help` first.
    
    At minimum, know these help entry points:
    
    ```bash
    npx -y agnes-ai-cli@^0.1.0 --help
    npx -y agnes-ai-cli@^0.1.0 auth --help
    npx -y agnes-ai-cli@^0.1.0 media --help
    npx -y agnes-ai-cli@^0.1.0 text chat --help
    npx -y agnes-ai-cli@^0.1.0 image text2img --help
    npx -y agnes-ai-cli@^0.1.0 image img2img --help
    npx -y agnes-ai-cli@^0.1.0 image compose --help
    npx -y agnes-ai-cli@^0.1.0 video text2video --help
    npx -y agnes-ai-cli@^0.1.0 video img2video --help
    npx -y agnes-ai-cli@^0.1.0 video multivideo --help
    npx -y agnes-ai-cli@^0.1.0 video keyframes --help
    npx -y agnes-ai-cli@^0.1.0 video poll --help
    ```
    
    If `agnes` is already installed globally and version-compatible, you can drop
    the `npx -y agnes-ai-cli@^0.1.0` prefix and run the same subcommands directly.
    
    ## Model Selection
    
    Choose the smallest suitable Agnes model path:
    
    - `agnes-2.0-flash`
      - chat, coding, tool calling, structured agent work, fast production tasks
      - default when `text chat` runs without `--model`
    - `agnes-image-2.1-flash`
      - default for new text-to-image and straightforward image-to-image work
      - especially useful for denser layouts and stronger semantic alignment
      - default when `image text2img`, `image img2img`, or `image compose` runs
        without `--model`
    - `agnes-image-2.0-flash`
      - use when the user explicitly wants Image 2.0
      - useful for edit-heavy or multi-image composition flows
    - `agnes-video-v2.0`
      - use for text-to-video, image-to-video, multi-image guided video, and
        keyframes
      - current default when any `video` generate command runs without `--model`
    
    ## CLI Command Map
    
    ### Auth
    
    ```bash
    npx -y agnes-ai-cli@^0.1.0 auth check
    npx -y agnes-ai-cli@^0.1.0 auth save-key --key 'YOUR_KEY'
    ```
    
    Use `auth check` before live requests when auth may be missing.
    
    ### Media URL Bridge
    
    ```bash
    npx -y agnes-ai-cli@^0.1.0 media url ./local-image.png
    npx -y agnes-ai-cli@^0.1.0 media url https://example.com/already-remote.png
    ```
    
    Use this when the user gives a local image path and Agnes needs a public image
    URL. The CLI handles the temporary upload bridge automatically.
    
    ### Text
    
    ```bash
    npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong."
    ```
    
    Use this for one-shot text verification, coding help, or small agent checks.
    If `--model` is omitted here, the CLI defaults to `agnes-2.0-flash`.
    
    ### Image
    
    ```bash
    npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "A premium studio product photo of a perfume bottle"
    
    npx -y agnes-ai-cli@^0.1.0 image img2img \
      --image ./input.png \
      --prompt "Turn this into a refined editorial campaign visual"
    
    npx -y agnes-ai-cli@^0.1.0 image compose \
      --image ./subject.png \
      --image ./reference.png \
      --prompt "Blend these references into one polished commercial still"
    ```
    
    Use:
    
    - `text2img` for prompt-only image generation
    - `img2img` for one input image
    - `compose` for multiple input images
    - if `--model` is omitted, the CLI defaults to `agnes-image-2.1-flash`
    
    ### Video
    
    ```bash
    npx -y agnes-ai-cli@^0.1.0 video text2video \
      --prompt "A cinematic beach scene at dusk"
    
    npx -y agnes-ai-cli@^0.1.0 video img2video \
      --image ./frame.png \
      --prompt "Add subtle wind and a slow camera push"
    
    npx -y agnes-ai-cli@^0.1.0 video multivideo \
      --image ./frame-a.png \
      --image ./frame-b.png \
      --prompt "Blend these frames into one smooth motion concept"
    
    npx -y agnes-ai-cli@^0.1.0 video keyframes \
      --image ./frame-a.png \
      --image ./frame-b.png \
      --prompt "Transition between these frames with a polished morph"
    
    npx -y agnes-ai-cli@^0.1.0 video poll video_123 --interval 5 --timeout 600
    ```
    
    Use:
    
    - `text2video` for prompt-only video
    - `img2video` for one image input
    - `multivideo` for multiple guiding images
    - `keyframes` for explicit keyframe interpolation
    - `poll` for asynchronous completion
    - if `--model` is omitted, current CLI behavior uses `agnes-video-v2.0`
    
    ## Practical CLI Workflow
    
    ### Text Verification
    
    1. `npx -y agnes-ai-cli@^0.1.0 text chat --help`
    2. `npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong." --json`
    
    ### Text-To-Image
    
    1. `npx -y agnes-ai-cli@^0.1.0 image text2img --help`
    2. run `npx -y agnes-ai-cli@^0.1.0 image text2img ... --json`
    3. read the returned image URL
    
    ### Image-To-Image
    
    1. `npx -y agnes-ai-cli@^0.1.0 image img2img --help`
    2. if the user gave a local path, let the CLI bridge it automatically
    3. run `npx -y agnes-ai-cli@^0.1.0 image img2img ... --json`
    
    ### Multi-Image Composition
    
    1. `npx -y agnes-ai-cli@^0.1.0 image compose --help`
    2. pass `--image` multiple times
    3. run with `npx -y agnes-ai-cli@^0.1.0 image compose ... --json`
    
    ### Text-To-Video
    
    1. `npx -y agnes-ai-cli@^0.1.0 video text2video --help`
    2. run `npx -y agnes-ai-cli@^0.1.0 video text2video ... --json`
    3. capture `videoId`
    4. run `npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json`
    
    ### Image-To-Video
    
    1. `npx -y agnes-ai-cli@^0.1.0 video img2video --help`
    2. if the user gave a local path, let the CLI bridge it automatically
    3. run `npx -y agnes-ai-cli@^0.1.0 video img2video ... --json`
    4. capture `videoId`
    5. run `npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json`
    
    ### Keyframes
    
    1. `npx -y agnes-ai-cli@^0.1.0 video keyframes --help`
    2. pass `--image` at least twice
    3. run `npx -y agnes-ai-cli@^0.1.0 video keyframes ... --json`
    4. capture `videoId`
    5. run `npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json`
    
    ## Image Guidance
    
    Use the CLI as the execution layer, but keep these Agnes-specific rules in mind:
    
    - Image 2.1 is the default for most new image work
    - Image 2.0 is useful for edit-heavy or multi-image composition work
    - For edits, explicitly separate:
      - what should change
      - what must stay fixed
    - For dense images, be explicit about:
      - primary subject
      - background environment
      - important secondary details
      - style and lighting
      - composition constraints
    
    ## Video Guidance
    
    Use the CLI as the execution layer, but keep these Agnes-specific rules in mind:
    
    - the API is asynchronous
    - `num_frames` must be `<= 441`
    - `num_frames` must satisfy `8n + 1`
    - `frame_rate` supports `1-60`
    - common safe example settings are:
      - `width: 1152`
      - `height: 768`
      - `num_frames: 121`
      - `frame_rate: 24`
    - for keyframes, use the dedicated CLI subcommand instead of inventing your
      own payload shape
    
    For text-to-video prompts, describe:
    
    - subject
    - action
    - environment
    - camera movement
    - lighting
    - style
    
    For image-to-video prompts, describe:
    
    - what should move
    - what should stay stable
    - how subtle or dramatic the motion should be
    
    For keyframes and multi-image work, describe:
    
    - how the inputs relate
    - what continuity should remain stable
    - what transition feeling is desired
    
    ## JSON Output
    
    Prefer `--json` whenever the command result will be consumed by the agent.
    
    Examples:
    
    ```bash
    npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "..." --json
    npx -y agnes-ai-cli@^0.1.0 video text2video --prompt "..." --json
    npx -y agnes-ai-cli@^0.1.0 video poll video_123 --json
    ```
    
    This makes it easier to:
    
    - read `taskId` and `videoId`
    - extract image URLs
    - extract final video URLs
    - detect failures cleanly
    
    ## Operational Guidance
    
    - Supported companion CLI range for this skill release:
      - `>=0.1.0 <0.2.0`
    - Prefer live CLI tests over guessing when the user asks whether a model path
      or parameter actually works.
    - For image results, expect a URL in the response.
    - For video results, expect task creation first, then polling.
    - Prefer `videoId` for polling. Passing an older `taskId` remains compatible
      through the CLI's legacy endpoint routing.
    - Use the CLI's local-file bridge instead of manually uploading files yourself
      unless the user explicitly wants a separate upload step.
    - If the user asks for SDK code, translate the confirmed CLI behavior into the
      target language only after the CLI path has been validated.
    - If the user asks about pricing, limits, or free access, verify the live docs.
    
    ## Compact Reference
    
    - Base URL: `https://apihub.agnes-ai.com/v1`
    - Text endpoint behind CLI: `/chat/completions`
    - Image endpoint behind CLI: `/images/generations`
    - Video create endpoint behind CLI: `/videos`
    - Video recommended poll endpoint behind CLI: `/agnesapi?video_id={video_id}`
    - Video legacy poll endpoint behind CLI: `/videos/{task_id}`
    
    - Text model: `agnes-2.0-flash`
    - Image model: `agnes-image-2.1-flash`
    - Image compatibility model: `agnes-image-2.0-flash`
    - Video model: `agnes-video-v2.0`
    
    ## Do Not
    
    - Do not proceed with live Agnes calls when the key is missing
    - Do not default to raw `curl` for Agnes execution in this skill
    - Do not rebuild request payloads by hand when the CLI already covers the flow
    - Do not skip `video poll` and assume video generation is synchronous
    - Do not trust stale marketing claims over the current API docs
    
    ## Safety
    
    - Never echo a full Agnes API key back to the user after it has been supplied
    - Never continue with live Agnes requests when auth is missing or clearly
      invalid
    - Never treat article copy or marketing claims as more authoritative than the
      official Agnes docs
    - Never promise pricing, limits, or "forever free" terms without noting they
      can change over time
    - Never write the key to a project file unless the user explicitly asks for
      that behavior
    
    ## Installation
    
    With repository-aware skill installers:
    
    ```bash
    npx skills add jomeswang/agnes-ai-skill -g
    ```
    
    After installation, invoke this skill whenever Agnes setup or Agnes model usage
    comes up.
    
    ## Version History
    
    - `1.2.2` - Added a linked Chinese README and Chinese quick-start onboarding
      guidance for agent responses.
    - `1.2.1` - Made `npx -y agnes-ai-cli@^0.1.0` the default copy-paste execution
      path in fresh environments and kept global `agnes` as an optional fast path.
    - `1.2.0` - Switched the skill to CLI-first Agnes execution, removed raw curl
      execution guidance, and made `--help` discovery part of the expected flow.
    - `1.1.2` - Added dual-track CLI guidance so agents prefer the separate Agnes
      execution layer when available and keep raw `curl` as the fallback.
    - `1.1.0` - Expanded official doc coverage for Image 2.0, Image 2.1, and Video
      2.0 parameters, scenarios, prompt structures, response fields, and task
      states.
    - `1.0.0` - Initial public release with Agnes platform setup, persistent auth,
      text, image, and video workflow guidance.
    
  • README.md16 KBbf60ed361b19upstream ↗
    # Agnes AI Free Text, Image & Video Generation Skill
    
    [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
    [![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-blue)](./SKILL.md)
    [![Models](https://img.shields.io/badge/models-text%20%7C%20image%20%7C%20video-black)](https://agnes-ai.com/doc)
    [![Agnes AI](https://img.shields.io/badge/platform-Agnes%20AI-ff6b3d)](https://platform.agnes-ai.com/)
    [![Chinese README](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-blue)](./README.zh-CN.md)
    
    Agnes AI Skill is a free multimodal Agent Skill for Codex, Claude Code,
    OpenClaw, Claude Desktop, Hermes, WorkBuddy, Cherry Studio, Opencode, and
    similar AI agent tools. It helps agents use Agnes 2.0 APIs for text generation,
    image generation, image editing, text-to-video, image-to-video, and API
    integration through a single root `SKILL.md`.
    
    Use this Agnes skill when you want an Agnes AI skill, image generation skill,
    video generation skill, text to image workflow, image to video workflow, free AI API
    workflow, or free AI model workflow that fits Codex skills, Claude Code skills,
    and OpenClaw skills.
    
    中文:Agnes AI 免费文本 / 生图 / 图片编辑 / 生视频 Agent Skill,支持 Codex、
    Claude Code、OpenClaw、Claude Desktop、Hermes、WorkBuddy、Cherry Studio、
    Opencode 等工具。
    
    ## Quick Start
    
    Install the skill with a repository-aware skills installer:
    
    ```bash
    npx skills add jomeswang/agnes-ai-skill -g
    ```
    
    Or copy this sentence to your agent:
    
    ```text
    Please read and install Agnes AI Skill: https://github.com/jomeswang/agnes-ai-skill
    ```
    
    After installation, create an Agnes API key at
    [platform.agnes-ai.com/settings/apiKeys](https://platform.agnes-ai.com/settings/apiKeys)
    and configure it as `AGNES_API_KEY`. Then tell the agent `generate an image`,
    `generate a video`, `edit this image`, or `integrate Agnes API`, and it can
    choose the proper Agnes model and execution path automatically.
    
    This skill helps agents:
    
    - set up Agnes AI and persist an `AGNES_API_KEY`
    - use `agnes-2.0-flash` for chat, coding, streaming, and tool calling
    - use `agnes-image-2.0-flash` and `agnes-image-2.1-flash` for AI image
      generation, image editing, and image-to-image workflows
    - use `agnes-video-v2.0` for text-to-video, image-to-video, and async video
      generation
    - prefer the companion `agnes-ai-cli` for live requests
    
    Compatible tools: Codex, Claude Code, Claude Desktop, OpenClaw, Hermes,
    WorkBuddy, Cherry Studio, Opencode, Kimi Work, and other Agent Skills /
    SKILL.md-compatible environments.
    
    ![Agnes AI frontier models hero](./assets/images/agnes-frontier-models-banner.jpg)
    
    ## Important Announcement
    
    **Agnes 2.0 full-modal model APIs are officially open for free global calls.**
    
    - No fixed end date, full-modal access, and free API calls within RPM 20
    - Register on the official platform, create a key, and call directly
    - Text, image, and video are all supported
    - Models keep upgrading while free access is maintained
    
    **Official platform:** https://platform.agnes-ai.com
    
    > The live official model docs also include pricing sections. For cost, quota,
    > or commercial use, check the current official docs first.
    
    This repository packages a single root `SKILL.md` so coding agents can quickly:
    
    - get and persist an Agnes API key
    - use `agnes-2.0-flash` for chat, coding, streaming, and tool calling
    - use `agnes-image-2.0-flash` and `agnes-image-2.1-flash` for image generation
      and editing
    - use `agnes-video-v2.0` for asynchronous video generation and polling
    
    It is designed for the exact pitch that makes Agnes easy to try:
    
    - one provider for text, image, and video
    - public free-access positioning that lowers experimentation friction
    - agent, creative, and prototyping workflows where repeated calls matter
    
    The skill stays intentionally lightweight. It teaches agents how to make Agnes
    API calls successfully without copying the full docs into the repository.
    
    ## Install
    
    With a repository-aware skills installer:
    
    ```bash
    npx skills add jomeswang/agnes-ai-skill -g
    ```
    
    Because this repository uses a single root `SKILL.md`, installers that support
    repository-root skills can discover it directly.
    
    ### Verified Install Path
    
    This repository has been validated with:
    
    ```bash
    npx skills add jomeswang/agnes-ai-skill --list
    npx skills add jomeswang/agnes-ai-skill --agent codex --yes
    ```
    
    The repository is discoverable as a single root-level skill named
    `agnes-ai-skill`.
    
    ## Companion CLI
    
    The published companion execution layer is:
    
    - npm: [`agnes-ai-cli`](https://www.npmjs.com/package/agnes-ai-cli)
    - GitHub: [`jomeswang/agnes-ai-cli`](https://github.com/jomeswang/agnes-ai-cli)
    
    Install it when you want stable commands instead of hand-written requests:
    
    ```bash
    npm install -g agnes-ai-cli
    agnes --help
    ```
    
    ## Model Guide
    
    Use the repository skill with these defaults:
    
    - `agnes-2.0-flash`
      - chat, coding, streaming, tool calling, and agent workflows
      - default when `text chat` runs without `--model`
    - `agnes-image-2.1-flash`
      - default for new text-to-image and image-to-image work
      - strongest fit for denser layouts, richer detail, and better semantic
        alignment
      - default when `image text2img`, `image img2img`, or `image compose` runs
        without `--model`
    - `agnes-image-2.0-flash`
      - better when you explicitly need its documented `tags: ["img2img"]` flow,
        multi-image composition, or `seed`-based reproducibility
    - `agnes-video-v2.0`
      - text-to-video, image-to-video, multi-image guided video, keyframes, and
        asynchronous polling
      - current default when any `video` generate command runs without `--model`
    
    The official docs also give each model fairly different best practices:
    
    - Image 2.1 leans into high-information-density visuals and composition
      preservation
    - Image 2.0 is more explicit about edit/composition workflows, response fields,
      and OpenAI Images-style compatibility
    - Video 2.0 is task-based and documents multiple generation modes, task states,
      result polling, and frame-count constraints
    
    ## Showcase
    
    The strongest outside prompt libraries all do the same three things well:
    lead with a preview, keep the prompt compact enough to scan, and organize
    examples by outcome instead of by raw API parameter lists. This gallery follows
    that pattern with 9 compact cases regenerated with Agnes on June 1, 2026. The
    image prompts were tightened toward the shorter, more editorial style seen in
    `awesome-gpt-image-2`, the video prompts were rebuilt around ad-film,
    animation, and cinematic beats inspired by `awesome-seedance`, and the HTML
    cases were regenerated as brighter, more public-facing product experiences.
    
    ### Image Cases
    
    `agnes-image-2.1-flash`
    
    | Preview | Case | Model | Prompt recipe |
    | --- | --- | --- | --- |
    | [![Y2K golden hour portrait](./assets/images/y2k-golden-hour.png)](./assets/images/y2k-golden-hour.png) | Y2K golden hour portrait | `agnes-image-2.1-flash` | Candid blonde portrait, baby-pink velour tracksuit, butterfly clips, glossy lips, palm trees, warm golden hour, real skin texture, soft film grain. |
    | [![Pencil editorial fashion](./assets/images/pencil-editorial-fashion.png)](./assets/images/pencil-editorial-fashion.png) | Pencil editorial fashion | `agnes-image-2.1-flash` | Minimal monochrome pencil-sketch fashion portrait, round sunglasses, rolled white shirt, denim overalls, combat boots, burnt-orange circle, indie magazine composition. |
    | [![Brand envelope perfume ad](./assets/images/brand-envelope-perfume.png)](./assets/images/brand-envelope-perfume.png) | Brand-envelope perfume ad | `agnes-image-2.1-flash` | Dusty-rose brand world, travertine pedestal, translucent perfume bottle, matte cream paper curves, warm studio light, quiet-luxury beauty campaign. |
    
    ### Video Cases
    
    `agnes-video-v2.0`
    
    | Preview | Case | Model | Prompt recipe |
    | --- | --- | --- | --- |
    | [![Perfume ad film first frame](./assets/video-previews/ad-film-10s.jpg)](./assets/videos/ad-film-10s.mp4) | Perfume ad film | `agnes-video-v2.0` | Ten-second luxury commercial with macro bottle details, orbiting reflections, atomizer tension beat, champagne-gold glow, and a final hero reveal built for premium beauty launch pages. |
    | [![Mechanical otter animation short first frame](./assets/video-previews/animation-film-10s.jpg)](./assets/videos/animation-film-10s.mp4) | Mechanical otter animation short | `agnes-video-v2.0` | Ten-second animated short: fearless otter pilot bursts through a clockwork engine room, expressive face, hand-painted adventure energy, cinematic action timing, family-film clarity. |
    | [![Desert cinematic film scene first frame](./assets/video-previews/cinema-film-10s.jpg)](./assets/videos/cinema-film-10s.mp4) | Desert cinematic film scene | `agnes-video-v2.0` | Ten-second widescreen film moment: lone traveler crosses a dust-heavy desert test site, sculptural machine in the background, restrained grading, prestige sci-fi drama mood. |
    
    ### App Cases
    
    `agnes-2.0-flash`
    
    Single-file HTML demos generated from Agnes text prompts and saved in
    [`examples/apps`](./examples/apps).
    
    | Preview | Case | Model | Prompt recipe |
    | --- | --- | --- | --- |
    | [![Agnes AI official-style homepage](./assets/apps/cinematic-ai-landing.jpg)](./examples/apps/cinematic-ai-landing.html) | Agnes AI official-style homepage | `agnes-2.0-flash` | Fresh one-file official product homepage for Agnes AI, bright premium palette, strong platform nav, enterprise hero copy, high-clarity call-to-action hierarchy. |
    | [![Lantern Sprint mini-game](./assets/apps/beijing-map-ui.jpg)](./examples/apps/beijing-map-ui.html) | Lantern Sprint mini-game | `agnes-2.0-flash` | Fresh browser mini-game with bright festival palette, instant start state, arcade score loop, keyboard and touch controls, polished one-file mobile-friendly presentation. |
    | [![Golden Hour Stories promo page](./assets/apps/watch-experience.jpg)](./examples/apps/watch-experience.html) | Golden Hour Stories promo page | `agnes-2.0-flash` | Fresh campaign landing page for Agnes image and video outputs, soft daylight tones, editorial serif hero, luxury launch framing, clear promotional storytelling. |
    
    ## Why Agnes
    
    Agnes is most interesting when one workflow needs all three layers together:
    
    - text for planning, coding, prompting, and agent loops
    - image for marketing, e-commerce, and creative visual generation
    - video for storyboards, product demos, motion tests, and short-form content
    
    The supplied public writeups consistently frame Agnes as useful for:
    
    - rapid AI product prototyping
    - high-frequency agent workflows where repeated model calls matter
    - frontend or HTML generation
    - marketing and e-commerce creatives
    - ad, storyboard, and cinematic short-video iteration
    
    This skill turns that platform surface into one reusable installation target for
    Codex and other SKILL.md-compatible agents, with guidance that helps the agent
    choose the right Agnes model and authenticate cleanly.
    
    ## What It Does
    
    - Platform and auth flow from the Agnes quickstart docs
    - API key creation via the Agnes platform settings page
    - Persistent `AGNES_API_KEY` setup for future sessions
    - OpenAI-style request patterns for text and image endpoints
    - Asynchronous task workflow for video generation
    - Practical use cases reinforced by the supplied public writeups
    
    ## Why The Free Angle Matters
    
    - Agnes is unusually compelling when one platform covers text, image, and video
      together.
    - The strongest growth hook in its public messaging is not just quality, but
      the promise of lower-cost or broadly free experimentation.
    - That matters most for agents, prototypes, content pipelines, and repeated
      A/B-style creative iteration.
    - In practice, treat this as a major adoption advantage, while still verifying
      the current live billing terms before promising zero cost.
    
    ## Model Quick Reference
    
    | Model | Best for | Endpoint | Required fields | Special fields / caveats |
    | --- | --- | --- | --- | --- |
    | `agnes-2.0-flash` | chat, coding, streaming, tool calling, agent loops | `/v1/chat/completions` | `model`, `messages` | OpenAI-style `tools`, `tool_choice`, `stream` |
    | `agnes-image-2.1-flash` | new text-to-image, image-to-image, denser layouts, composition-preserving edits | `/v1/images/generations` | `model`, `prompt` | `size`, `extra_body.image`, `extra_body.response_format`; strongest fit for high-information-density scenes |
    | `agnes-image-2.0-flash` | edit-heavy workflows, multi-image composition, compatibility-style image flows | `/v1/images/generations` | `model`, `prompt` | often pair with `tags: ["img2img"]`; supports `seed`, `extra_body.image`, `extra_body.response_format` |
    | `agnes-video-v2.0` | text-to-video, image-to-video, multi-image guided video, keyframes | create: `/v1/videos`; poll: `/agnesapi?video_id={video_id}` | `model`, `prompt` | asynchronous task workflow; create returns `taskId` and `videoId`; use `videoId` for polling, while older `taskId` polling remains legacy-compatible |
    
    ## Pricing / Operational Caveats
    
    - The official Image 2.0, Image 2.1, and Video 2.0 docs currently include
      pricing sections.
    - Some public writeups still frame Agnes as broadly free or indefinitely free.
    - The Video 2.0 docs are also operationally time-sensitive: the same page can
      mix concrete price figures with "pricing to be announced" style notes.
    - Treat all pricing, free-tier, and billing claims as live-doc verified only.
    
    ## Safety Model
    
    - The skill checks for `AGNES_API_KEY` before live requests
    - If the key is missing, it points the user to the official Agnes quickstart
      and API key page instead of guessing
    - If the user provides a key and wants it remembered, the skill persists
      `AGNES_API_KEY` in the correct shell rc file for future sessions
    - Live payloads and response handling stay grounded in Agnes docs and real API
      behavior, not only in marketing copy
    
    ## Manual Install
    
    Copy this repository into any standard skills location supported by your agent,
    for example:
    
    - Codex: `~/.codex/skills/agnes-ai-skill`
    - Claude Code: `~/.claude/skills/agnes-ai-skill`
    - Cursor: `~/.cursor/skills/agnes-ai-skill`
    
    ## What Agents Learn
    
    - How to detect missing Agnes auth before making live calls
    - How to guide the user to create an API key
    - How to persist `AGNES_API_KEY` in shell startup files for future sessions
    - How to choose between Agnes text, image, and video models
    - How to make the smallest reliable live request first
    - How to poll Agnes video tasks until they complete
    
    ## Discovery Notes
    
    - GitHub repository: [jomeswang/agnes-ai-skill](https://github.com/jomeswang/agnes-ai-skill)
    - Public repository topics:
      `agent-skills`, `ai-agent-skills`, `codex-skills`, `multimodal-ai`, `agnes-ai`
    - These topics improve discoverability across GitHub-linked skill directories
      and crawler-based ecosystems.
    - The repository is ready for third-party skill hub submission, including
      ClawHub-style marketplaces that read `SKILL.md` metadata.
    
    ## Primary Sources
    
    - Agnes quickstart: [https://agnes-ai.com/doc/quickstart](https://agnes-ai.com/doc/quickstart)
    - API key settings:
      [https://platform.agnes-ai.com/settings/apiKeys](https://platform.agnes-ai.com/settings/apiKeys)
    - Text model:
      [https://agnes-ai.com/doc/agnes-20-flash](https://agnes-ai.com/doc/agnes-20-flash)
    - Image 2.0:
      [https://agnes-ai.com/doc/agnes-image-20-flash](https://agnes-ai.com/doc/agnes-image-20-flash)
    - Image 2.1:
      [https://agnes-ai.com/doc/agnes-image-21-flash](https://agnes-ai.com/doc/agnes-image-21-flash)
    - Video:
      [https://agnes-ai.com/doc/agnes-video-v20](https://agnes-ai.com/doc/agnes-video-v20)
    
    ## Notes
    
    - The public materials supplied with this repository describe Agnes as offering
      free access to its core multimodal APIs as of June 1, 2026. Treat pricing and
      promotion details as time-sensitive and verify them in the platform if cost
      matters.
    - ClawHub publishing requires a separate ClawHub login or publish token plus a
      GitHub OAuth grant.
    - This repository is released under the MIT License.
    
  • scripts/agnes-media-url.sh904 Bc5c10464edf4upstream ↗
    #!/usr/bin/env bash
    set -euo pipefail
    
    usage() {
      cat <<'EOF'
    Usage:
      agnes-media-url.sh <file-or-url> [ttl]
    
    Examples:
      agnes-media-url.sh ./frame.png
      agnes-media-url.sh ./frame.png 12h
      agnes-media-url.sh https://example.com/frame.png
    
    If the input is already an http(s) URL, the script prints it unchanged.
    If the input is a local file path, the script uploads it to Litterbox and
    prints the resulting temporary public URL.
    EOF
    }
    
    if [[ "${1:-}" == "-h" || "${1:-}" == "--help" || $# -lt 1 ]]; then
      usage
      exit 0
    fi
    
    input="$1"
    ttl="${2:-1h}"
    
    if [[ "$input" =~ ^https?:// ]]; then
      printf '%s\n' "$input"
      exit 0
    fi
    
    if [[ ! -r "$input" ]]; then
      printf 'Input must be a readable file path or an http(s) URL: %s\n' "$input" >&2
      exit 1
    fi
    
    curl -sS https://litterbox.catbox.moe/resources/internals/api.php \
      -F "reqtype=fileupload" \
      -F "time=${ttl}" \
      -F "fileToUpload=@${input}"
    
  • scripts/extract_first_frames.swift2.2 KB09114cdb6b0cupstream ↗
    import AppKit
    import AVFoundation
    import CoreMedia
    import Foundation
    
    enum FrameExtractError: Error, CustomStringConvertible {
      case invalidArguments
      case missingFrame(String)
      case encodeFailure(String)
    
      var description: String {
        switch self {
        case .invalidArguments:
          return "Usage: xcrun swift scripts/extract_first_frames.swift <input.mp4> <output.jpg> [<input.mp4> <output.jpg> ...]"
        case .missingFrame(let path):
          return "Could not extract a frame from \(path)"
        case .encodeFailure(let path):
          return "Could not encode a JPEG preview for \(path)"
        }
      }
    }
    
    func writeFirstFrame(from inputPath: String, to outputPath: String) throws {
      let inputURL = URL(fileURLWithPath: inputPath)
      let asset = AVURLAsset(url: inputURL)
      let generator = AVAssetImageGenerator(asset: asset)
      generator.appliesPreferredTrackTransform = true
      generator.maximumSize = CGSize(width: 1600, height: 1600)
    
      let semaphore = DispatchSemaphore(value: 0)
      var generatedImage: CGImage?
      var generationError: Error?
    
      generator.generateCGImageAsynchronously(for: .zero) { image, _, error in
        generatedImage = image
        generationError = error
        semaphore.signal()
      }
    
      semaphore.wait()
    
      if let generationError {
        throw generationError
      }
    
      guard let cgImage = generatedImage else {
        throw FrameExtractError.missingFrame(inputPath)
      }
    
      let bitmap = NSBitmapImageRep(cgImage: cgImage)
    
      guard let data = bitmap.representation(using: .jpeg, properties: [.compressionFactor: 0.9]) else {
        throw FrameExtractError.encodeFailure(inputPath)
      }
    
      let outputURL = URL(fileURLWithPath: outputPath)
      try FileManager.default.createDirectory(
        at: outputURL.deletingLastPathComponent(),
        withIntermediateDirectories: true
      )
      try data.write(to: outputURL)
    }
    
    let arguments = Array(CommandLine.arguments.dropFirst())
    
    guard !arguments.isEmpty, arguments.count.isMultiple(of: 2) else {
      throw FrameExtractError.invalidArguments
    }
    
    for pairIndex in stride(from: 0, to: arguments.count, by: 2) {
      let inputPath = arguments[pairIndex]
      let outputPath = arguments[pairIndex + 1]
      try writeFirstFrame(from: inputPath, to: outputPath)
      FileHandle.standardOutput.write(Data("\(outputPath)\n".utf8))
    }
    
  • assets/apps/beijing-map-ui.jpg79 KBf9d064abd273upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/apps/cinematic-ai-landing.jpg125 KBbd322f6f5d5aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/apps/watch-experience.jpg146 KB7bd1cb1231f0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/images/agnes-frontier-models-banner.jpg257 KB79af0e82fc43upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/images/brand-envelope-perfume.png3.5 MBc3c20e0039b6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/images/cyberpunk-bridge.jpg461 KBf6c0d03e3e5bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/images/latte-infographic.jpg324 KB69c94f0a41e7upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/images/pencil-editorial-fashion.png2.3 MB193069a60916upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/images/perfume-product.jpg351 KB172859cfabd8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/images/y2k-golden-hour.png2.6 MBaa4056b9de1eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/ad-film-10s.jpg102 KB4062bd0e3ec8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/animation-film-10s.jpg140 KB9a3a2e8151ddupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/bridge-pushin-clean.png673 KBa01df4f7ee9cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/cinema-film-10s.jpg93 KB2368cccba861upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/forest-waterfall.jpg31 KB33000ebfd27cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/luxury-perfume-10s.jpg110 KB30015a650644upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/perfume-motion.png565 KB16bdd205516bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/video-previews/rural-cooking.png234 KB57cc4e64c36aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/ad-film-10s.mp42.2 MB63ffa5b752f8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/animation-film-10s.mp42.9 MB028f9c9c72e1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/bridge-pushin.mp4313 KBaae65216e585upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/cinema-film-10s.mp41.7 MB4c98f0246a58upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/forest-waterfall.mp4643 KB2ca478887ed7upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/luxury-perfume-10s.mp42.6 MB2ddf1bf3c56aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/perfume-motion.mp41.5 MBb418bff1b3e9upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • assets/videos/rural-cooking.mp4276 KBab63dad67693upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • .gitattributes189 Bb05f4d0a2a5cupstream ↗
    scripts/extract_first_frames.swift linguist-documentation
    scripts/*.sh linguist-documentation
    examples/apps/*.html linguist-documentation
    docs/superpowers/specs/*.md linguist-documentation
    
  • .gitignore36 B05c9b4603809upstream ↗
    .DS_Store
    .agents/
    skills-lock.json
    
  • agents/openai.yaml307 Bf0de657de813upstream ↗
    interface:
      display_name: "Agnes AI Skill"
      short_description: "Set up Agnes auth once, then use Agnes text, image, and video APIs from one installable skill"
      default_prompt: "Use $agnes-ai-skill to set up Agnes access, persist my API key if needed, and call the right Agnes text, image, or video API."
    
  • docs/superpowers/specs/2026-06-02-agnes-cli-design-zh.md20 KB6976112ec035upstream ↗
    # Agnes CLI 与 npm 包双轨方案设计稿
    
    日期:2026-06-02  
    仓库:`jomeswang/agnes-ai-skill`  
    状态:待评审
    
    ## 目标
    
    为 Agnes 增加一个真正可执行的工具层,让 agent 在常见场景下不再优先手写原始
    `curl`,同时继续保留当前 skill 仓库的轻量安装体验。
    
    这套设计要同时满足:
    
    - `agnes-ai-skill` 继续保持轻量,适合 `npx skills add ... -g`
    - Agnes 的执行层单独沉淀为 npm 包和 CLI
    - 图生图、图生视频等需要远程 URL 的场景,可以自动把本地文件转成临时公网 URL
    - 后续 Node 自动流可以直接复用 JS API,而不只是调用命令行
    
    ## 核心结论
    
    推荐采用**双轨方案**,而不是 Monorepo 根目录 skill + CLI 源码混放。
    
    ### 轨道 1:`agnes-ai-skill`
    
    定位:
    
    - 安装型 skill 仓库
    - 面向 Codex / Claude Code / 其他 `SKILL.md` 兼容 agent
    - 尽量轻,不把完整 CLI 源码打包进 skill 安装目录
    
    职责:
    
    - `SKILL.md`
    - `README.md`
    - 最少量必要脚本或 fallback helper
    - Agnes 能力说明、模型选择、auth 指导、命令调用策略
    
    ### 轨道 2:`agnes-ai-cli`
    
    定位:
    
    - 执行型 npm 包
    - 面向 agent、命令行用户、Node 自动流
    
    职责:
    
    - 提供 `agnes` CLI
    - 提供 JS API
    - 负责真实的 Agnes 请求执行
    - 负责本地文件转临时公网 URL
    - 负责视频轮询、参数归一化、稳定输出
    
    ## 为什么不推荐根目录 Monorepo 直接混放
    
    当前 skill 安装器的典型行为是:**复制选中的 skill 目录**。
    
    如果继续保持:
    
    - 仓库根目录就是 skill
    - CLI 源码也放在根目录下的 `packages/`
    
    那么用户安装 skill 时,很可能会把 CLI 源码也一起复制进去。
    
    这会带来几个问题:
    
    - 安装体积变大
    - skill 安装目录变重
    - 图片、视频、示例、CLI 源码容易一起被带下去
    - skill 仓库不再像“安装型 skill”,而更像“全量项目镜像”
    
    所以更合理的边界是:
    
    - `agnes-ai-skill` 只负责教 agent 怎么做
    - `agnes-ai-cli` 负责真正去做
    
    ## 双轨结构
    
    ### 仓库 A:`agnes-ai-skill`
    
    建议保留当前仓库名,继续作为 skill 分发入口。
    
    建议结构:
    
    ```text
    agnes-ai-skill/
      LICENSE
      README.md
      SKILL.md
      agents/
        openai.yaml
      scripts/
        agnes-media-url.sh
        extract_first_frames.swift
    ```
    
    说明:
    
    - `scripts/agnes-media-url.sh` 可以先保留,作为 fallback 或调试工具
    - 不再把完整 npm CLI 源码塞进这个仓库
    
    ### 仓库 / 包 B:`agnes-ai-cli`
    
    建议单独作为 npm 包维护。
    
    建议结构:
    
    ```text
    agnes-ai-cli/
      LICENSE
      README.md
      package.json
      bin/
        agnes.js
      src/
        cli.ts
        index.ts
        config.ts
        errors.ts
        output.ts
        auth/
          check.ts
          saveKey.ts
        media/
          toPublicUrl.ts
          litterbox.ts
        image/
          generateImage.ts
          normalizeImageRequest.ts
        video/
          generateVideo.ts
          pollVideo.ts
          normalizeVideoRequest.ts
      test/
        cli/
        unit/
    ```
    
    ## 两个轨道怎么衔接
    
    `agnes-ai-skill` 不再鼓励 agent 直接拼原始 `curl`,而是优先按这个顺序执行:
    
    1. 先尝试调用本机已安装的 `agnes` CLI
    2. 如果没装 CLI,则尝试 `npx -y agnes-ai-cli@<兼容版本范围> ...`
    3. 只有在 CLI 不可用或需要最小验证时,才退回原始 `curl`
    
    这样有几个好处:
    
    - skill 继续轻量
    - 执行逻辑集中在 CLI
    - agent 的调用方式更稳定
    - 用户不用每次关心 Agnes 的底层 payload 细节
    
    ## Skill / CLI 兼容契约
    
    双轨方案要成立,必须显式定义 skill 和 CLI 的兼容关系,不能默认跟随
    “latest”。
    
    规则建议:
    
    - skill 文档声明一个最小兼容 CLI 主版本或次版本范围
    - 本机已安装的 `agnes` 只有在 `agnes --version` 满足兼容范围时才可直接使用
    - `SKILL.md` 优先调用:
      1. 先校验版本后再使用本机 `agnes`
      2. `npx -y agnes-ai-cli@<兼容范围> ...`
      3. 最后再退回原始 `curl`
    - 如果 CLI 引入了 breaking change,skill 必须在同一个发布窗口同步更新
    - skill 不能假设“最新 npm 包永远兼容”
    
    ## CLI 设计
    
    ### 设计原则
    
    - 不要把 `generate` 做成过重的层级,例如 `agnes video generate`
    - 命令要尽量贴近任务场景,让 agent 好选、人也好记
    - 内部实现统一,外部命令清晰
    
    ### 技术选型
    
    推荐使用成熟开源库,不建议手写参数解析器。
    
    建议组合:
    
    - `commander`
      - 作为 CLI 主框架
      - 负责子命令、参数解析、`--help`、`--version`
    - `zod`
      - 作为参数校验和内部 options 归一化层
      - 让 CLI 参数校验和 JS API 参数校验复用同一套规则
    - Node 原生 `fetch` / `FormData`
      - 作为 Agnes API 与 Litterbox 上传的 HTTP 层
      - 尽量避免为简单请求额外引入过多网络依赖
    - 可选 `picocolors`
      - 用于命令行输出的轻量着色
      - 不是必须依赖
    
    不建议作为第一选择:
    
    - `yargs`
      - 功能很强,但对这个项目来说偏重
    - `cac`
      - 可以用,但在多层命令和帮助信息组织上不如 `commander` 稳妥
    
    当前推荐结论:
    
    - CLI 框架:`commander`
    - 参数校验:`zod`
    - HTTP / 上传:Node 原生 `fetch` + `FormData`
    - 输出美化:可选 `picocolors`
    
    ### 推荐命令树
    
    ```text
    agnes auth check
    agnes auth save-key [--key <value>]
    
    agnes media url <file-or-url> [--ttl 1h|12h|24h|72h]
    
    agnes text chat --prompt <text> [--model agnes-2.0-flash] [--json]
    
    agnes image text2img --prompt <text> [options]
    agnes image img2img --image <path-or-url> --prompt <text> [options]
    agnes image compose --image <path-or-url> --image <path-or-url> --prompt <text> [options]
    
    agnes video text2video --prompt <text> [options]
    agnes video img2video --image <path-or-url> --prompt <text> [options]
    agnes video multivideo --image <path-or-url> --image <path-or-url> --prompt <text> [options]
    agnes video keyframes --image <path-or-url> --image <path-or-url> --prompt <text> [options]
    agnes video poll <task-id> [--interval 3] [--timeout 600]
    ```
    
    ### 为什么这样设计
    
    - `text chat` 保留一个最小文本入口,让 agent 可以通过 CLI 跑通 Agnes
      文本、图片、视频三类流程
    - `text2img`、`img2img`、`text2video`、`img2video` 足够直观
    - `keyframes` 单独暴露更清晰,因为它本来就是 Agnes 的特殊模式
    - `poll` 是视频异步任务的一等操作,不应该被埋掉
    - 比 `video generate` 更利落,也更容易让 agent 命中
    
    ### `--help` 设计要求
    
    CLI 必须内建完整帮助系统,而不是只在 README 里说明。
    
    至少要支持:
    
    ```bash
    agnes --help
    agnes auth --help
    agnes media --help
    agnes text --help
    agnes text chat --help
    agnes image --help
    agnes image img2img --help
    agnes video --help
    agnes video keyframes --help
    ```
    
    每一层帮助都应包含:
    
    - 这个命令的用途
    - 必填参数
    - 可选参数
    - 至少 1 个最小示例
    - 与 Agnes request shape 对应的场景说明
    
    例如 `agnes video keyframes --help` 应明确说明:
    
    - 这是 Agnes `keyframes` 模式
    - 需要 2 张或以上图片
    - `--image` 可重复传入
    - 常用参数:
      - `--width`
      - `--height`
      - `--num-frames`
      - `--frame-rate`
      - `--seed`
      - `--json`
    
    帮助信息应同时面向:
    
    - 人类开发者
    - 直接读取命令输出的 agent
    
    ### 是否保留别名
    
    可以保留,但不作为主入口:
    
    - `agnes image generate` -> `agnes image text2img`
    - `agnes video generate` -> `agnes video text2video`
    
    skill 文档和 agent 提示里应该优先使用明确命令,不优先使用别名。
    
    ## JS API 设计
    
    CLI 面向人和 agent,JS API 面向 Node 自动流。
    
    ### 公共入口建议
    
    ```ts
    const agnes = createAgnesClient(config)
    
    agnes.auth.check()
    
    agnes.media.toPublicUrl(input, options?)
    
    agnes.text.complete(options)
    
    agnes.image.generate(options)
    
    agnes.video.generate(options)
    agnes.video.poll(taskId, options?)
    ```
    
    推荐使用 `Client + 命名空间` 结构,而不是在顶层直接裸暴露
    `generateImage()` / `generateVideo()`。
    
    这样可以同时保留:
    
    - 清晰的能力分组
    - 统一的配置入口
    - 更小的顶层 API 面
    - 对未来 provider、logger、默认参数、重试策略的扩展空间
    
    shell 启动文件写入应保持为 CLI-only 行为,不建议作为公开 JS API 暴露。
    
    文本能力建议保留一个轻量公开入口:
    
    - `agnes.text.complete()`
    
    这样可以让 Node 自动流直接跑最小 Agnes 文本请求,而不会逼调用方退回
    原始 `fetch`。
    
    ### 为什么 JS API 要统一成 `image.generate()` / `video.generate()`
    
    如果把图片和视频拆成很多公开方法,例如:
    
    - `textToImage()`
    - `imageToImage()`
    - `composeImage()`
    - `textToVideo()`
    - `imageToVideo()`
    - `multiImageVideo()`
    - `keyframesVideo()`
    
    短期看起来直观,但长期会有两个问题:
    
    1. API 面会越来越碎
    2. 新模式或 provider 差异出现时,方法名会持续膨胀
    
    而 Agnes 的能力本质上本来就是“同一能力域下的多种 mode”。
    
    图片:
    
    - 文生图
    - 图生图
    - 多图合成
    
    视频:
    
    - 文生视频
    - 单图生视频
    - 多图生视频
    - keyframes 生视频
    
    所以:
    
    - 对外 CLI:按场景命令拆开,方便人和 agent 使用
    - 对内 JS API:统一为 `generate()`,通过 `mode` 区分
    
    这是更兼容、更容易演进的设计。
    
    ### 推荐的 Client 形态
    
    ```ts
    const agnes = createAgnesClient({
      apiKey: process.env.AGNES_API_KEY,
    })
    
    await agnes.image.generate({
      mode: "text2img",
      prompt: "A luminous floating city above a misty canyon at sunrise",
    })
    
    await agnes.image.generate({
      mode: "img2img",
      image: "/path/to/input.png",
      prompt: "Preserve the silhouette and convert the scene into a bright editorial campaign",
    })
    
    await agnes.video.generate({
      mode: "img2video",
      image: "/path/to/frame.png",
      prompt: "Keep the hero subject stable while adding subtle wind and a soft push-in",
    })
    
    await agnes.video.generate({
      mode: "keyframes",
      images: ["frame-a.png", "frame-b.png"],
      prompt: "Create a smooth premium transition between the two frames",
    })
    
    await agnes.video.poll("video_123")
    ```
    
    ## 参数归一化规则
    
    ### `image.generate(options)`
    
    建议使用判别联合类型,而不是一个无限膨胀的大对象。
    
    ```ts
    type ImageGenerateOptions =
      | {
          mode: "text2img"
          model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
          prompt: string
          size?: string
          responseFormat?: "url"
          seed?: number
        }
      | {
          mode: "img2img"
          model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
          image: string
          prompt: string
          size?: string
          responseFormat?: "url"
          seed?: number
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
      | {
          mode: "compose"
          model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
          images: string[]
          prompt: string
          size?: string
          responseFormat?: "url"
          seed?: number
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
    ```
    
    归一化规则:
    
    - `mode: "text2img"` -> 文生图
    - `mode: "img2img"` -> 单图图生图
    - `mode: "compose"` -> 多图合成
    - 模型是 2.1 且有图像输入 -> `extra_body.image`
    - 模型是 2.0 且有图像输入 -> `tags: ["img2img"]` + `extra_body.image`
    
    ### `video.generate(options)`
    
    视频侧也建议使用判别联合类型。
    
    ```ts
    type VideoGenerateOptions =
      | {
          mode: "text2video"
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
        }
      | {
          mode: "img2video"
          image: string
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
      | {
          mode: "multivideo"
          images: string[]
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
      | {
          mode: "keyframes"
          images: string[]
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
    ```
    
    归一化规则:
    
    - `mode: "text2video"` -> 文生视频
    - `mode: "img2video"` -> Agnes 顶层 `image`
    - `mode: "multivideo"` -> `extra_body.image`
    - `mode: "keyframes"` -> `extra_body.image + extra_body.mode = "keyframes"`
    
    ### 视频参数校验与默认值
    
    这部分应直接内建在 CLI 和 JS API 中,而不是留到实现时临场决定。
    
    建议默认值:
    
    - `width: 1152`
    - `height: 768`
    - `numFrames: 121`
    - `frameRate: 24`
    
    必须校验:
    
    - `numFrames <= 441`
    - `numFrames` 必须满足 `8n + 1`
    - `frameRate` 必须在 `1-60`
    - `mode: "img2video"` 必须恰好 1 张图
    - `mode: "multivideo"` 至少 2 张图
    - `mode: "keyframes"` 至少 2 张图
    
    只要参数非法,就应在发送 Agnes 请求前直接失败。
    
    ### 为什么 CLI 和 JS API 要故意不完全一样
    
    这里刻意做分层设计:
    
    - CLI:显式命令
    - JS API:统一 `generate()`
    
    原因是:
    
    - CLI 更适合被人和 agent 通过命令名字发现能力
    - JS API 更适合通过 `mode` 保持兼容性和扩展性
    - 两层各自优化自己的使用体验,而不是强行完全一致
    
    ## 本地文件转公网 URL
    
    这是这次设计里最关键的一段。
    
    Agnes 官方文档当前写的是:
    
    - 图生图:传图片 URL
    - 图生视频:传图片 URL
    - 多图 / keyframes:也是图片 URL 数组
    
    所以 CLI 应自动做这件事:
    
    - 如果 `--image` 已经是 `http://` 或 `https://`,直接使用
    - 如果 `--image` 是本地路径,先上传到临时文件托管服务
    - 拿到公网 URL 后,再调用 Agnes
    
    ### 第一版上传 provider
    
    第一版建议使用 **Litterbox**:
    
    - 免费
    - 接口简单
    - 已经验证过可用
    - 足够做临时桥接层
    
    ### Provider 抽象
    
    后面不要把 CLI 写死在 Litterbox 上,建议一开始就留出抽象:
    
    ```ts
    interface MediaUrlProvider {
      upload(localPath: string, options?: { ttl?: string }): Promise<string>
    }
    ```
    
    第一版实现:
    
    - `LitterboxMediaUrlProvider`
    
    未来可扩展:
    
    - Cloudinary
    - Google Cloud Storage
    - 用户自定义 provider
    
    ### URL bridge 的行为约束
    
    这部分需要明确,不然后续实现容易不一致:
    
    - 多次传入 `--image` 时,必须严格保留输入顺序
    - 同一个命令调用里,重复本地路径可以只上传一次,再在归一化请求里复用
    - 如果其中任意一个上传失败,整个 Agnes 请求不应继续发送
    - 默认 TTL 设为 `1h`
    - 对长视频或可能排队较久的视频任务,CLI 应允许显式传更长 TTL,
      并在帮助信息中说明 `12h` / `24h` 更稳妥
    
    ## 输出协议
    
    CLI 应同时支持:
    
    - 默认输出:给人看
    - `--json`:给 agent / 自动流看
    
    ### 默认输出建议
    
    - `agnes media url`:只打印 URL
    - 图片命令:只打印生成结果 URL
    - 视频创建命令:打印 `task_id`、`video_id` + 状态
    - `agnes video poll`:打印最终视频 URL + 状态摘要
    
    ### `--json` 建议
    
    统一输出机器可读结构,例如:
    
    ```json
    {
      "ok": true,
      "url": "https://litter.catbox.moe/abc123.jpg",
      "source": "litterbox"
    }
    ```
    
    ```json
    {
      "ok": true,
      "taskId": "task_123",
      "videoId": "video_123",
      "status": "queued"
    }
    ```
    
    ### 视频任务标准化返回
    
    CLI 和 JS API 必须对 Agnes 视频异步结果做统一标准化,不应直接把原始
    `id` / `task_id` / `video_id` / 状态字段裸暴露给上层。
    
    建议的标准化创建结果:
    
    ```json
    {
      "ok": true,
      "taskId": "task_123",
      "videoId": "video_123",
      "status": "queued",
      "rawStatus": "queued",
      "model": "agnes-video-v2.0"
    }
    ```
    
    建议的标准化轮询结果:
    
    ```json
    {
      "ok": true,
      "taskId": "task_123",
      "videoId": "video_123",
      "status": "completed",
      "videoUrl": "https://...",
      "seconds": 10.0,
      "size": "1152x768"
    }
    ```
    
    建议保证的状态枚举:
    
    - `queued`
    - `in_progress`
    - `completed`
    - `failed`
    - `timed_out`
    
    规则建议:
    
    - 原始 `id` 或 `task_id` 一律映射成 `taskId`
    - 保留 `video_id` 为 `videoId`;推荐轮询接口返回 `id: "video_..."`
      时,也保留为 `videoId`
    - 如有需要,保留 `rawStatus`
    - `video.generate()` 返回标准化任务对象,不自动轮询
    - `video.poll()` 返回标准化终态对象
    - `video poll --json` 需要对以下情况有明确结构:
      - `failed`
      - `404`
      - `503`
      - timeout
    
    建议失败结构:
    
    ```json
    {
      "ok": false,
      "taskId": "task_123",
      "status": "failed",
      "code": "TASK_FAILED",
      "message": "Agnes video task failed"
    }
    ```
    
    ## 认证设计
    
    CLI 需要沿用当前 skill 已经建立好的 Agnes key 规则。JS API 只负责检查
    和运行时配置,不负责改写 shell 启动文件。
    
    ### `agnes auth check`
    
    职责:
    
    - 检查 `AGNES_API_KEY` 是否存在
    - 输出当前是否可直接调用 Agnes
    
    ### `agnes auth save-key`
    
    职责:
    
    - 将 `AGNES_API_KEY` 写入:
      - zsh -> `~/.zshrc`
      - bash -> `~/.bashrc`
      - fallback -> `~/.profile`
    - 更新已有 export 或追加新 export
    - 不回显完整 key
    
    ### JS auth surface
    
    公开 JS API 建议只保留:
    
    - `agnes.auth.check()`
    
    可选内部能力:
    
    - `resolveAuthConfig()`
    
    不建议把 shell rc 文件写入暴露成普通 JS API。
    
    ## 错误处理
    
    CLI 不能只把底层原始异常裸抛给 agent,建议统一成稳定错误类别:
    
    - auth missing
    - local file missing
    - upload failed
    - Agnes request failed
    - Agnes task timeout
    - invalid arguments
    
    `--json` 下错误也应该保持结构化:
    
    ```json
    {
      "ok": false,
      "code": "UPLOAD_FAILED",
      "message": "Failed to upload local file to Litterbox"
    }
    ```
    
    视频相关错误码至少应覆盖:
    
    - `TASK_FAILED`
    - `TASK_NOT_FOUND`
    - `SERVICE_BUSY`
    - `POLL_TIMEOUT`
    - `INVALID_VIDEO_SETTINGS`
    
    ## 测试建议
    
    ### 单元测试
    
    - 参数归一化
    - 本地路径与远程 URL 透传逻辑
    - shell rc 文件选择逻辑
    - JSON 输出格式
    - `task_id` / `video_id` / `id` 标准化
    - 视频状态映射
    - `numFrames <= 441` 校验
    - `numFrames = 8n + 1` 校验
    - `frameRate` 在 `1-60` 的校验
    - 默认 TTL 与显式 TTL 覆盖逻辑
    
    ### CLI 测试
    
    - `agnes media url https://example.com/x.png`
    - `agnes text chat --help`
    - `agnes image text2img --help`
    - `agnes video keyframes --help`
    - `agnes auth check`
    - `agnes video poll video_123 --json`
    
    ### 集成测试
    
    默认 mock:
    
    - Litterbox 上传
    - Agnes API
    
    live test 显式开启:
    
    - 要求 `AGNES_API_KEY`
    - 要求显式 opt-in
    
    ## 与 skill 的集成方式
    
    `agnes-ai-skill` 后续应更新为:
    
    - 优先使用 CLI
    - 只有在 CLI 不可用时才退回 `curl`
    
    推荐执行优先级:
    
    1. 本机 `agnes --version` 满足兼容范围时,使用 `agnes ...`
    2. `npx -y agnes-ai-cli@<兼容范围> ...`
    3. 原始 `curl`
    
    这能让:
    
    - skill 仓库保持轻
    - CLI 真正承担执行责任
    - agent 的调用更稳定
    
    ## 发布方式
    
    ### `agnes-ai-skill`
    
    继续作为 GitHub skill 仓库分发:
    
    - `npx skills add jomeswang/agnes-ai-skill -g`
    
    ### `agnes-ai-cli`
    
    单独发布到 npm:
    
    - 包名优先:`agnes-ai-cli`
    - 如果名字已占用,再退到:`@jomeswang/agnes-ai-cli`
    
    CLI 执行文件名:
    
    - `agnes`
    
    ## 实施顺序
    
    ### Phase 1
    
    - 初始化 `agnes-ai-cli`
    - 实现:
      - `auth check`
      - `auth save-key`
      - `media url`
      - `text chat`
    
    ### Phase 2
    
    - 实现图片命令:
      - `text2img`
      - `img2img`
      - `compose`
    
    ### Phase 3
    
    - 实现视频命令:
      - `text2video`
      - `img2video`
      - `multivideo`
      - `keyframes`
      - `poll`
    
    ### Phase 4
    
    - 更新 `agnes-ai-skill`
    - 将 CLI 作为首选执行路径
    - 保留 shell helper 作为 fallback
    
    ## 成功标准
    
    这套双轨方案算成功,当且仅当:
    
    1. skill 安装不再把完整 CLI 源码一起打包下去
    2. agent 能通过 CLI 稳定完成 Agnes 文本、图片、视频流程
    3. 本地图片路径在 Agnes 图生图 / 图生视频场景下能自动桥接为公网 URL
    4. npm 包可以独立发布和升级
    5. 视频任务标准化返回和参数校验足够稳定,agent 不需要猜 Agnes
       的原始响应差异
    
    ## 当前推荐
    
    如果现在要拍板,推荐是:
    
    - `agnes-ai-skill` 继续保持当前轻量 root skill 形态
    - `agnes-ai-cli` 单独做 npm 包
    - CLI 用场景式 commands
    - JS API 用 `createAgnesClient()` + 统一的 `image.generate()` /
      `video.generate()`
    - 本地文件第一版通过 Litterbox 做 URL bridge
    - shell helper 保留为 fallback,不作为长期主执行层
    
    ## 需要确认的两个点
    
    1. npm 包名优先用:
       - `agnes-ai-cli`
       - 还是 `@jomeswang/agnes-ai-cli`
    
    2. shell helper 的长期定位:
       - 仅 fallback
       - 还是继续作为公开脚本一起维护
    
  • docs/superpowers/specs/2026-06-02-agnes-cli-design.md19 KB44d7a995f939upstream ↗
    # Agnes CLI And npm Package Design
    
    Date: 2026-06-02
    Repository: `jomeswang/agnes-ai-skill`
    Status: Draft for review
    
    ## Objective
    
    Add a real execution layer for Agnes workflows so agents do not need to handcraft
    raw `curl` calls for common tasks. The new layer should:
    
    - preserve the current root-level `SKILL.md` install experience
    - provide a publishable npm package and CLI
    - normalize Agnes text, image, and video request shapes
    - bridge local file paths into temporary public URLs when Agnes expects remote
      image URLs
    - keep the repository lightweight enough to remain an install-friendly skill repo
    
    ## Current Context
    
    The repository already contains:
    
    - a root `SKILL.md` focused on Agnes platform setup and API usage
    - a public GitHub distribution path for `npx skills add jomeswang/agnes-ai-skill -g`
    - a lightweight shell helper:
      `scripts/agnes-media-url.sh`
    
    The current pain points are:
    
    - agents still need to assemble raw Agnes `curl` payloads
    - local-path handling for image-to-image and image-to-video is easy to forget
    - video polling and response normalization are repetitive
    - the execution layer is not yet reusable outside the skill itself
    
    ## Recommendation
    
    Choose a **dual-track architecture** instead of a root-level monorepo that
    mixes installable skill content and CLI source in the same copied directory.
    
    ### Track 1: `agnes-ai-skill`
    
    Role:
    
    - install-friendly root skill repository
    - optimized for `npx skills add ... -g`
    - intentionally lightweight
    
    Responsibilities:
    
    - `SKILL.md`
    - `README.md`
    - minimal fallback helpers or tiny utility scripts
    - Agnes capability guidance, model selection, auth flow, and command strategy
    
    ### Track 2: `agnes-ai-cli`
    
    Role:
    
    - executable npm package
    - reusable JS API for Node automation
    - canonical execution layer for Agnes requests
    
    Responsibilities:
    
    - provide the `agnes` CLI
    - provide the JS client API
    - normalize Agnes request shapes
    - bridge local file paths into temporary public URLs
    - own polling, output shaping, and validation
    
    ## Why Not A Root-Level Monorepo
    
    Typical skill installers copy the selected skill directory.
    
    If the root of `agnes-ai-skill` stays the installable skill and the CLI source
    also lives under that root, installing the skill is likely to copy:
    
    - CLI source
    - package metadata
    - extra assets or examples tied to the package
    
    That would make the skill distribution heavier and blur the repository's role.
    
    The better boundary is:
    
    - `agnes-ai-skill` teaches agents what to do
    - `agnes-ai-cli` performs the work
    
    ## Proposed Repository / Package Topology
    
    ### Repository A: `agnes-ai-skill`
    
    Keep the current repository name and continue using it as the public skill
    distribution entry point.
    
    ```text
    agnes-ai-skill/
      LICENSE
      README.md
      SKILL.md
      agents/
        openai.yaml
      scripts/
        agnes-media-url.sh
        extract_first_frames.swift
    ```
    
    Notes:
    
    - `scripts/agnes-media-url.sh` may remain as a fallback or debugging helper
    - do not place full npm CLI source in this repository root
    
    ### Repository / Package B: `agnes-ai-cli`
    
    Maintain the CLI as a separate npm package.
    
    ```text
    agnes-ai-cli/
      LICENSE
      README.md
      package.json
      bin/
        agnes.js
      src/
        cli.ts
        index.ts
        config.ts
        errors.ts
        output.ts
        auth/
          check.ts
          saveKey.ts
        media/
          toPublicUrl.ts
          litterbox.ts
        image/
          generateImage.ts
          normalizeImageRequest.ts
        video/
          generateVideo.ts
          pollVideo.ts
          normalizeVideoRequest.ts
      test/
        cli/
        unit/
    ```
    
    ## Package Scope
    
    The npm package should be both:
    
    - a CLI executable named `agnes`
    - a JS API for Node-based automation
    
    The package name should be one of:
    
    1. `agnes-ai-cli` (recommended)
    2. `@jomeswang/agnes-ai-cli`
    
    Recommendation:
    
    - Publish as `agnes-ai-cli` if available.
    - Fall back to `@jomeswang/agnes-ai-cli` only if the unscoped name is taken.
    
    ## Skill / CLI Compatibility Contract
    
    The dual-track setup needs an explicit compatibility rule so the skill can call
    the CLI without silent drift.
    
    Rules:
    
    - the skill documents the minimum supported CLI major or minor version
    - a locally installed `agnes` binary may be used only if `agnes --version`
      satisfies the declared compatible range
    - the preferred execution path is:
      1. `agnes ...` only after version verification
      2. `npx -y agnes-ai-cli@<supported-range> ...`
      3. raw `curl` only as a fallback
    - the skill should not assume "latest" without a declared compatible range
    - when the CLI introduces breaking request-shape behavior, the skill must be
      updated in the same release window
    
    ## CLI Design
    
    ### Principles
    
    - avoid raw `generate` as a repeated noun in the command tree
    - use explicit task-shaped commands that agents can select reliably
    - keep the user-facing commands short
    - let aliases map into a smaller internal API surface
    
    ### Command Tree
    
    ```text
    agnes auth check
    agnes auth save-key [--key <value>]
    
    agnes media url <file-or-url> [--ttl 1h|12h|24h|72h]
    
    agnes text chat --prompt <text> [--model agnes-2.0-flash] [--json]
    
    agnes image text2img --prompt <text> [options]
    agnes image img2img --image <path-or-url> --prompt <text> [options]
    agnes image compose --image <path-or-url> --image <path-or-url> --prompt <text> [options]
    
    agnes video text2video --prompt <text> [options]
    agnes video img2video --image <path-or-url> --prompt <text> [options]
    agnes video multivideo --image <path-or-url> --image <path-or-url> --prompt <text> [options]
    agnes video keyframes --image <path-or-url> --image <path-or-url> --prompt <text> [options]
    agnes video poll <task-id> [--interval 3] [--timeout 600]
    ```
    
    ### Why This Tree
    
    - `text chat` preserves a minimal Agnes text entry point so agents can complete
      Agnes text, image, and video flows through the CLI
    - `text2img`, `img2img`, `text2video`, and `img2video` are concrete and easy
      for agents to choose
    - `keyframes` stays explicit because it has a distinct Agnes request mode
    - `multivideo` avoids hiding the difference between one-image and multi-image
      requests
    - `poll` stays a first-class video operation because Agnes video is asynchronous
    
    ### Command Aliases
    
    The CLI may additionally support these aliases:
    
    - `agnes image generate` -> `agnes image text2img`
    - `agnes video generate` -> `agnes video text2video`
    
    However, the skill should prefer the explicit task commands, not the aliases.
    
    ## JS API Design
    
    ### Public Entry Point
    
    ```ts
    const agnes = createAgnesClient(config)
    
    agnes.auth.check()
    
    agnes.media.toPublicUrl(input, options?)
    
    agnes.text.complete(options)
    
    agnes.image.generate(options)
    
    agnes.video.generate(options)
    agnes.video.poll(taskId, options?)
    ```
    
    Use a `Client + namespaced services` shape instead of exposing top-level
    `generateImage()` / `generateVideo()` functions directly.
    
    This preserves:
    
    - clearer capability grouping
    - a single config entry point
    - a smaller top-level API surface
    - room for future providers, logging, retries, and defaults
    
    Shell startup-file mutation should stay CLI-only. The JS API should not expose a
    public method that edits `~/.zshrc`, `~/.bashrc`, or `~/.profile`.
    
    Text should keep a lightweight public entry point:
    
    - `agnes.text.complete()`
    
    This lets Node workflows run the smallest Agnes text request without dropping
    down to raw `fetch`.
    
    ### Why JS Should Use Unified `image.generate()` / `video.generate()`
    
    If the public JS API exposes many task-specific methods such as:
    
    - `textToImage()`
    - `imageToImage()`
    - `composeImage()`
    - `textToVideo()`
    - `imageToVideo()`
    - `multiImageVideo()`
    - `keyframesVideo()`
    
    it starts out readable, but it fragments quickly as new modes and provider
    differences appear.
    
    Agnes capabilities are a better fit for a unified `generate()` surface with
    mode-based branching.
    
    Images:
    
    - text-to-image
    - image-to-image
    - multi-image composition
    
    Video:
    
    - text-to-video
    - image-to-video
    - multi-image video
    - keyframe video
    
    So the design should intentionally split the layers:
    
    - CLI: explicit task-shaped commands
    - JS API: unified `generate()` methods keyed by `mode`
    
    That gives the best compatibility story without bloating the public JS API.
    
    ### Recommended Client Shape
    
    ```ts
    const agnes = createAgnesClient({
      apiKey: process.env.AGNES_API_KEY,
    })
    
    await agnes.image.generate({
      mode: "text2img",
      prompt: "A luminous floating city above a misty canyon at sunrise",
    })
    
    await agnes.image.generate({
      mode: "img2img",
      image: "/path/to/input.png",
      prompt: "Preserve the silhouette and convert the scene into a bright editorial campaign",
    })
    
    await agnes.video.generate({
      mode: "img2video",
      image: "/path/to/frame.png",
      prompt: "Keep the hero subject stable while adding subtle wind and a soft push-in",
    })
    
    await agnes.video.generate({
      mode: "keyframes",
      images: ["frame-a.png", "frame-b.png"],
      prompt: "Create a smooth premium transition between the two frames",
    })
    
    await agnes.video.poll("video_123")
    ```
    
    ### Type Shapes
    
    ```ts
    type ImageGenerateOptions =
      | {
          mode: "text2img"
          model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
          prompt: string
          size?: string
          responseFormat?: "url"
          seed?: number
        }
      | {
          mode: "img2img"
          model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
          image: string
          prompt: string
          size?: string
          responseFormat?: "url"
          seed?: number
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
      | {
          mode: "compose"
          model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
          images: string[]
          prompt: string
          size?: string
          responseFormat?: "url"
          seed?: number
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
    
    type VideoGenerateOptions =
      | {
          mode: "text2video"
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
        }
      | {
          mode: "img2video"
          image: string
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
      | {
          mode: "multivideo"
          images: string[]
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
      | {
          mode: "keyframes"
          images: string[]
          prompt: string
          width?: number
          height?: number
          numFrames?: number
          frameRate?: number
          seed?: number
          negativePrompt?: string
          ttl?: "1h" | "12h" | "24h" | "72h"
        }
    ```
    
    ### Internal Mapping Rules
    
    For images:
    
    - `mode: "text2img"` -> text-to-image
    - `mode: "img2img"` -> single-image image-to-image
    - `mode: "compose"` -> multi-image composition
    - Image 2.1 with image input -> `extra_body.image`
    - Image 2.0 with image input -> `tags: ["img2img"]` plus
      `extra_body.image`
    
    For video:
    
    - `mode: "text2video"` -> text-to-video
    - `mode: "img2video"` -> top-level `image`
    - `mode: "multivideo"` -> `extra_body.image`
    - `mode: "keyframes"` -> `extra_body.image` plus
      `extra_body.mode = "keyframes"`
    
    ### Video Validation And Defaults
    
    The design should bake Agnes-specific validation into the CLI and JS layer
    instead of leaving it to ad hoc request assembly.
    
    Recommended defaults:
    
    - `width: 1152`
    - `height: 768`
    - `numFrames: 121`
    - `frameRate: 24`
    
    Required validation:
    
    - `numFrames <= 441`
    - `numFrames` must satisfy `8n + 1`
    - `frameRate` must be in `1-60`
    - `mode: "img2video"` requires exactly one image
    - `mode: "multivideo"` requires at least two images
    - `mode: "keyframes"` requires at least two images
    
    Invalid settings should fail before any Agnes request is sent.
    
    ### Why CLI And JS Should Intentionally Differ
    
    This is a deliberate split:
    
    - CLI: explicit task-shaped commands
    - JS API: unified `generate()` surface
    
    The CLI optimizes for discoverability and help text.
    The JS API optimizes for compatibility and long-term extension.
    
    ## Local File Handling
    
    Agnes docs describe image inputs as remote image URLs. The CLI should therefore
    normalize local file paths automatically.
    
    ### Rule
    
    Whenever a command accepts `--image`:
    
    - if the value is already `http://` or `https://`, use it unchanged
    - if the value is a local file path, upload it to Litterbox first
    - then use the resulting temporary public URL in the Agnes request
    
    ### First Provider
    
    Use Litterbox first because:
    
    - it is free
    - it already works with simple `curl`
    - it is enough for temporary bridge behavior
    
    This provider should live behind an abstraction so future providers can be
    added without changing the public CLI.
    
    ### Provider Abstraction
    
    ```ts
    interface MediaUrlProvider {
      upload(localPath: string, options?: { ttl?: string }): Promise<string>
    }
    ```
    
    First implementation:
    
    - `LitterboxMediaUrlProvider`
    
    Future candidates:
    
    - Cloudinary
    - Google Cloud Storage
    - custom provider interface
    
    ### URL Bridge Behavior
    
    The bridge behavior should be deterministic:
    
    - repeated `--image` inputs preserve input order exactly
    - duplicate local paths may be uploaded once per command invocation and reused
      in-place in the normalized request
    - if any upload fails, the whole command fails before sending the Agnes request
    - default TTL is `1h`
    - commands that start long-running Agnes video jobs should allow explicit TTL
      override and document that longer jobs may require `12h` or `24h`
    
    ## Output Contract
    
    The CLI should support:
    
    - human-readable default output
    - `--json` for machine/agent consumption
    
    ### Default Output
    
    - `media url`: print only the resulting URL
    - image commands: print the resulting image URL
    - video create commands: print `task_id`, `video_id`, and status summary
    - `video poll`: print the resulting video URL and completion fields
    
    ### JSON Output
    
    Examples:
    
    ```json
    {
      "ok": true,
      "taskId": "task_123",
      "videoId": "video_123",
      "status": "queued"
    }
    ```
    
    ```json
    {
      "ok": true,
      "url": "https://litter.catbox.moe/abc123.jpg",
      "source": "litterbox"
    }
    ```
    
    ### Video Task Normalization
    
    The CLI and JS API must normalize Agnes async video responses into a stable
    shape, regardless of whether the raw API returns `id`, `task_id`, or `video_id`.
    
    Recommended normalized task object:
    
    ```json
    {
      "ok": true,
      "taskId": "task_123",
      "videoId": "video_123",
      "status": "queued",
      "rawStatus": "queued",
      "model": "agnes-video-v2.0"
    }
    ```
    
    Recommended normalized poll result:
    
    ```json
    {
      "ok": true,
      "taskId": "task_123",
      "videoId": "video_123",
      "status": "completed",
      "videoUrl": "https://...",
      "seconds": 10.0,
      "size": "1152x768"
    }
    ```
    
    Guaranteed status enum:
    
    - `queued`
    - `in_progress`
    - `completed`
    - `failed`
    - `timed_out`
    
    Rules:
    
    - map raw `id` or `task_id` into `taskId`
    - preserve `video_id` as `videoId`; when the recommended poll endpoint returns
      `id: "video_..."`, preserve it as `videoId` too
    - preserve the raw provider status as `rawStatus` when useful
    - `video.generate()` returns a normalized task object and does not auto-poll
    - `video.poll()` returns a normalized terminal result object
    - `video poll --json` must define structured output for:
      - `failed`
      - `404`
      - `503`
      - timeout
    
    Recommended failure shape:
    
    ```json
    {
      "ok": false,
      "taskId": "task_123",
      "status": "failed",
      "code": "TASK_FAILED",
      "message": "Agnes video task failed"
    }
    ```
    
    ## Auth Behavior
    
    The CLI should use the same Agnes key behavior already documented in the skill.
    The JS API should limit itself to inspection and runtime config, not shell file
    mutation.
    
    ### `agnes auth check`
    
    Returns whether `AGNES_API_KEY` is available and which source was used.
    
    ### `agnes auth save-key`
    
    Rules:
    
    - write `AGNES_API_KEY`
    - detect shell rc file:
      - zsh -> `~/.zshrc`
      - bash -> `~/.bashrc`
      - fallback -> `~/.profile`
    - update existing export if present
    - export into the current process for child calls when possible
    - never echo the full key back
    
    ### JS Auth Surface
    
    Recommended public JS auth surface:
    
    - `agnes.auth.check()`
    
    Optional internal or advanced surface:
    
    - `resolveAuthConfig()`
    
    Do not expose shell-rc mutation as a routine public JS API.
    
    ## Error Handling
    
    The CLI should convert raw failures into stable categories:
    
    - auth missing
    - local file missing
    - upload failed
    - Agnes request failed
    - Agnes task timeout
    - invalid command arguments
    
    For `--json`, errors should still print machine-readable output:
    
    ```json
    {
      "ok": false,
      "code": "UPLOAD_FAILED",
      "message": "Failed to upload local file to Litterbox"
    }
    ```
    
    Video-specific error codes should include at least:
    
    - `TASK_FAILED`
    - `TASK_NOT_FOUND`
    - `SERVICE_BUSY`
    - `POLL_TIMEOUT`
    - `INVALID_VIDEO_SETTINGS`
    
    ## Skill Integration
    
    The root `SKILL.md` should eventually prefer CLI commands over raw `curl`
    whenever the CLI is available.
    
    Preferred hierarchy:
    
    1. use local `agnes` only if `agnes --version` satisfies the supported range
    2. otherwise use `npx -y agnes-ai-cli@<supported-range> ...`
    3. otherwise fall back to the shell helper or raw `curl`
    
    The skill should keep the minimal `curl` examples for portability, but treat the
    CLI as the preferred execution path.
    
    ## Release And Distribution
    
    ### npm
    
    - package published from the dedicated `agnes-ai-cli` package repository
    - executable name: `agnes`
    - versioning should start at `0.1.0`
    
    ### Skill Repository
    
    `agnes-ai-skill` remains the canonical source for:
    
    - the skill install experience
    - skill-facing README and showcase
    - skill documentation and compatibility guidance
    
    ### CLI Repository
    
    `agnes-ai-cli` remains the canonical source for:
    
    - CLI source
    - JS API source
    - package README
    - release and npm publish workflow
    
    ## Testing Strategy
    
    ### Unit Tests
    
    - request normalization for image and video modes
    - local-path vs URL passthrough behavior
    - rc file selection logic
    - JSON output formatting
    - `task_id` / `video_id` / `id` normalization
    - video status mapping
    - validation of `numFrames <= 441`
    - validation of `numFrames = 8n + 1`
    - validation of `frameRate` in `1-60`
    - default TTL behavior and explicit TTL override
    
    ### CLI Tests
    
    - `agnes media url https://example.com/x.png`
    - `agnes text chat --help`
    - `agnes image text2img --help`
    - `agnes video keyframes --help`
    - `agnes auth check`
    - `agnes video poll video_123 --json`
    
    ### Integration Tests
    
    Mock by default:
    
    - Litterbox upload
    - Agnes API requests
    
    Optional live tests behind environment flags:
    
    - `AGNES_API_KEY`
    - explicit opt-in for live upload and live Agnes requests
    
    ## Rollout Plan
    
    ### Phase 1
    
    - scaffold the standalone `agnes-ai-cli` package repository
    - implement `auth check`, `auth save-key`, `media url`, and `text chat`
    
    ### Phase 2
    
    - implement image commands
    - implement video create + poll commands
    
    ### Phase 3
    
    - update `SKILL.md` to prefer CLI
    - keep shell fallback
    - document install and publish flow
    
    ## Success Criteria
    
    This design is successful when:
    
    1. an agent can complete Agnes text, image, and video workflows without
       hand-authoring raw `curl` payloads in normal cases
    2. local file inputs for Agnes image/video flows are bridged automatically
    3. the public skill repository remains installable as a root-level skill
    4. the CLI can be published independently to npm
    5. video task normalization and validation are stable enough that agents do not
       need to guess raw Agnes response differences
    
    ## Open Questions
    
    These should be decided before implementation:
    
    1. package name:
       - `agnes-ai-cli`
       - or `@jomeswang/agnes-ai-cli`
    2. whether to keep the shell helper permanently as a fallback
    3. whether live integration tests should run in CI or only manually
    
  • examples/apps/beijing-map-ui.html15 KB7d1f8384c761upstream ↗
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
        <title>Lantern Sprint</title>
        <style>
            :root {
                --bg-color: #fdfbf7; /* Cream */
                --primary-red: #d32f2f; /* Lacquer Red */
                --primary-gold: #ffc107; /* Gold */
                --accent-gold: #ffeb3b; /* Bright Gold */
                --text-color: #3e2723;
                --cloud-color: #546e7a;
            }
    
            body {
                margin: 0;
                padding: 0;
                background-color: var(--bg-color);
                font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
                overflow: hidden;
                touch-action: none;
                user-select: none;
                display: flex;
                flex-direction: column;
                align-items: center;
                justify-content: center;
                height: 100vh;
                color: var(--text-color);
            }
    
            #game-container {
                position: relative;
                width: 100%;
                max-width: 600px;
                height: 100%;
                max-height: 800px;
                box-shadow: 0 4px 20px rgba(0,0,0,0.1);
                background: linear-gradient(to bottom, #fffdf5, #f0efe9);
                border: 2px solid var(--text-color);
                overflow: hidden;
            }
    
            canvas {
                display: block;
                width: 100%;
                height: 100%;
            }
    
            .ui-layer {
                position: absolute;
                top: 0;
                left: 0;
                width: 100%;
                height: 100%;
                pointer-events: none;
                display: flex;
                flex-direction: column;
                justify-content: space-between;
            }
    
            .hud {
                display: flex;
                justify-content: space-between;
                padding: 20px;
                font-size: 24px;
                font-weight: bold;
                color: var(--primary-red);
                text-shadow: 1px 1px 0px var(--primary-gold);
            }
    
            .screen {
                position: absolute;
                top: 0;
                left: 0;
                width: 100%;
                height: 100%;
                background: rgba(253, 251, 247, 0.9);
                display: flex;
                flex-direction: column;
                align-items: center;
                justify-content: center;
                text-align: center;
                pointer-events: auto;
                transition: opacity 0.3s;
            }
    
            .hidden {
                opacity: 0;
                pointer-events: none;
            }
    
            h1 {
                font-size: 48px;
                color: var(--primary-red);
                margin: 0 0 10px 0;
                text-transform: uppercase;
                letter-spacing: 2px;
                border-bottom: 4px solid var(--primary-gold);
                padding-bottom: 10px;
            }
    
            p {
                font-size: 18px;
                margin-bottom: 30px;
                color: #5d4037;
            }
    
            button {
                background-color: var(--primary-red);
                color: white;
                border: none;
                padding: 15px 40px;
                font-size: 20px;
                font-weight: bold;
                border-radius: 2px;
                cursor: pointer;
                box-shadow: 0 4px 0 #b71c1c;
                transition: transform 0.1s, box-shadow 0.1s;
                text-transform: uppercase;
                letter-spacing: 1px;
            }
    
            button:active {
                transform: translateY(4px);
                box-shadow: 0 0 0 #b71c1c;
            }
    
            button:hover {
                background-color: #e53935;
            }
    
            .stat-value {
                color: var(--primary-gold);
                text-shadow: 1px 1px 0 #3e2723;
            }
    
            /* Decoration lines */
            .corner {
                position: absolute;
                width: 20px;
                height: 20px;
                border: 4px solid var(--primary-red);
                pointer-events: none;
            }
            .tl { top: 10px; left: 10px; border-right: none; border-bottom: none; }
            .tr { top: 10px; right: 10px; border-left: none; border-bottom: none; }
            .bl { bottom: 10px; left: 10px; border-right: none; border-top: none; }
            .br { bottom: 10px; right: 10px; border-left: none; border-top: none; }
    
        </style>
    </head>
    <body>
    
        <div id="game-container">
            <div class="corner tl"></div>
            <div class="corner tr"></div>
            <div class="corner bl"></div>
            <div class="corner br"></div>
    
            <canvas id="gameCanvas"></canvas>
    
            <div class="ui-layer">
                <div class="hud">
                    <div id="scoreDisplay">Score: 0</div>
                    <div id="timeDisplay">Time: 30</div>
                </div>
            </div>
    
            <div id="startScreen" class="screen">
                <h1>Lantern Sprint</h1>
                <p>Catch the glowing lanterns.<br>Avoid the rain clouds.<br>Use Arrow Keys or Touch sides.</p>
                <button id="startBtn">Start Run</button>
            </div>
    
            <div id="gameOverScreen" class="screen hidden">
                <h1>Time Up!</h1>
                <p>Final Score: <span id="finalScore" class="stat-value">0</span></p>
                <button id="restartBtn">Try Again</button>
            </div>
        </div>
    
        <script>
            const canvas = document.getElementById('gameCanvas');
            const ctx = canvas.getContext('2d');
            const scoreDisplay = document.getElementById('scoreDisplay');
            const timeDisplay = document.getElementById('timeDisplay');
            const startScreen = document.getElementById('startScreen');
            const gameOverScreen = document.getElementById('gameOverScreen');
            const finalScoreEl = document.getElementById('finalScore');
    
            let gameRunning = false;
            let score = 0;
            let timeLeft = 30;
            let lastTime = 0;
            let spawnTimer = 0;
            let difficulty = 1;
    
            // Game Objects
            const player = {
                x: 0, y: 0, width: 50, height: 70, speed: 0, targetX: 0, color: '#d32f2f'
            };
            let items = []; // Lanterns and Clouds
            let particles = [];
    
            // Input State
            const keys = { ArrowLeft: false, ArrowRight: false };
    
            // Setup Canvas Size
            function resize() {
                canvas.width = canvas.parentElement.clientWidth;
                canvas.height = canvas.parentElement.clientHeight;
                player.y = canvas.height - 100;
                if (!gameRunning) {
                    player.x = canvas.width / 2;
                }
            }
            window.addEventListener('resize', resize);
            resize();
    
            // Input Handling
            window.addEventListener('keydown', (e) => { if(keys.hasOwnProperty(e.code)) keys[e.code] = true; });
            window.addEventListener('keyup', (e) => { if(keys.hasOwnProperty(e.code)) keys[e.code] = false; });
    
            // Touch Support
            canvas.addEventListener('touchstart', handleTouch);
            canvas.addEventListener('touchmove', handleTouch);
            canvas.addEventListener('touchend', () => {
                player.targetX = player.x;
            });
    
            function handleTouch(e) {
                e.preventDefault();
                const rect = canvas.getBoundingClientRect();
                const touchX = e.touches[0].clientX - rect.left;
                player.targetX = touchX;
            }
    
            // Start / Restart
            document.getElementById('startBtn').addEventListener('click', startGame);
            document.getElementById('restartBtn').addEventListener('click', startGame);
    
            function startGame() {
                gameRunning = true;
                score = 0;
                timeLeft = 30;
                items = [];
                particles = [];
                difficulty = 1;
                player.x = canvas.width / 2;
                player.targetX = player.x;
                scoreDisplay.textContent = `Score: 0`;
                timeDisplay.textContent = `Time: 30`;
                startScreen.classList.add('hidden');
                gameOverScreen.classList.add('hidden');
                lastTime = performance.now();
                requestAnimationFrame(gameLoop);
    
                // Start Timer
                const timerInterval = setInterval(() => {
                    if (!gameRunning) {
                        clearInterval(timerInterval);
                        return;
                    }
                    timeLeft--;
                    timeDisplay.textContent = `Time: ${timeLeft}`;
                    difficulty = 1 + (30 - timeLeft) * 0.05;
                    if (timeLeft <= 0) endGame();
                }, 1000);
            }
    
            function endGame() {
                gameRunning = false;
                finalScoreEl.textContent = score;
                gameOverScreen.classList.remove('hidden');
            }
    
            function spawnItem() {
                const isCloud = Math.random() > 0.7; // 30% chance for cloud
                const size = isCloud ? 60 : 40;
                const x = Math.random() * (canvas.width - size);
                items.push({
                    x: x,
                    y: -50,
                    width: size,
                    height: size,
                    speed: (Math.random() * 3 + 2) * difficulty,
                    type: isCloud ? 'cloud' : 'lantern',
                    angle: 0
                });
            }
    
            function createParticles(x, y, color) {
                for (let i = 0; i < 8; i++) {
                    particles.push({
                        x: x,
                        y: y,
                        vx: (Math.random() - 0.5) * 10,
                        vy: (Math.random() - 0.5) * 10,
                        life: 1.0,
                        color: color
                    });
                }
            }
    
            function drawPlayer() {
                // Smooth movement towards target
                player.x += (player.targetX - player.x) * 0.2;
    
                // Clamp
                if (player.x < player.width/2) player.x = player.width/2;
                if (player.x > canvas.width - player.width/2) player.x = canvas.width - player.width/2;
    
                ctx.save();
                ctx.translate(player.x, player.y);
    
                // Handle keyboard override
                if (keys.ArrowLeft) player.targetX -= 8;
                if (keys.ArrowRight) player.targetX += 8;
    
                // Stick
                ctx.fillStyle = '#8d6e63';
                ctx.fillRect(-2, -10, 4, 20);
    
                // Body (Lantern shape)
                ctx.fillStyle = player.color;
                ctx.beginPath();
                ctx.ellipse(0, 0, 20, 30, 0, 0, Math.PI * 2);
                ctx.fill();
    
                // Shine
                ctx.fillStyle = '#ffeb3b';
                ctx.beginPath();
                ctx.ellipse(0, 0, 12, 20, 0, 0, Math.PI * 2);
                ctx.fill();
    
                // Glow
                ctx.shadowColor = '#ffeb3b';
                ctx.shadowBlur = 20;
                ctx.fillStyle = 'rgba(255, 235, 59, 0.5)';
                ctx.beginPath();
                ctx.ellipse(0, 0, 15, 25, 0, 0, Math.PI * 2);
                ctx.fill();
                ctx.restore();
            }
    
            function drawItems() {
                items.forEach((item, index) => {
                    ctx.save();
                    ctx.translate(item.x + item.width/2, item.y + item.height/2);
    
                    if (item.type === 'lantern') {
                        // Draw Lantern
                        item.angle += 0.05;
                        ctx.rotate(Math.sin(item.angle) * 0.2);
    
                        // Rope
                        ctx.strokeStyle = '#5d4037';
                        ctx.beginPath();
                        ctx.moveTo(0, -item.height/2 - 10);
                        ctx.lineTo(0, -item.height/2);
                        ctx.stroke();
    
                        // Red Shell
                        ctx.fillStyle = '#d32f2f';
                        ctx.beginPath();
                        ctx.rect(-15, -20, 30, 40);
                        ctx.fill();
    
                        // Gold Caps
                        ctx.fillStyle = '#ffb300';
                        ctx.fillRect(-15, -20, 30, 5);
                        ctx.fillRect(-15, 15, 30, 5);
    
                        // Inner Glow
                        ctx.shadowColor = '#ffeb3b';
                        ctx.shadowBlur = 15;
                        ctx.fillStyle = '#ffeb3b';
                        ctx.fillRect(-10, -15, 20, 30);
    
                    } else {
                        // Draw Cloud
                        ctx.fillStyle = '#78909c';
                        ctx.beginPath();
                        ctx.arc(0, 0, 25, 0, Math.PI*2);
                        ctx.arc(-20, 5, 20, 0, Math.PI*2);
                        ctx.arc(20, 5, 20, 0, Math.PI*2);
                        ctx.fill();
    
                        // Darker underbelly
                        ctx.fillStyle = '#455a64';
                        ctx.beginPath();
                        ctx.arc(0, 5, 25, 0, Math.PI, true);
                        ctx.fill();
                    }
                    ctx.restore();
                });
            }
    
            function drawParticles() {
                for (let i = particles.length - 1; i >= 0; i--) {
                    const p = particles[i];
                    ctx.fillStyle = p.color;
                    ctx.globalAlpha = p.life;
                    ctx.beginPath();
                    ctx.arc(p.x, p.y, 4 * p.life, 0, Math.PI*2);
                    ctx.fill();
                    p.x += p.vx;
                    p.y += p.vy;
                    p.life -= 0.05;
                    if (p.life <= 0) particles.splice(i, 1);
                }
                ctx.globalAlpha = 1.0;
            }
    
            function update(dt) {
                // Spawning
                spawnTimer += dt;
                if (spawnTimer > (1000 / difficulty)) {
                    spawnItem();
                    spawnTimer = 0;
                }
    
                // Item Physics
                for (let i = items.length - 1; i >= 0; i--) {
                    const item = items[i];
                    item.y += item.speed;
    
                    // Collision
                    const dx = (player.x) - (item.x + item.width/2);
                    const dy = (player.y) - (item.y + item.height/2);
                    const dist = Math.sqrt(dx*dx + dy*dy);
    
                    if (dist < 45) { // Hit
                        if (item.type === 'lantern') {
                            score += 10;
                            scoreDisplay.textContent = `Score: ${score}`;
                            createParticles(player.x, player.y, '#ffeb3b');
                        } else {
                            score -= 20;
                            scoreDisplay.textContent = `Score: ${score}`;
                            createParticles(player.x, player.y, '#546e7a');
                            // Visual shake or flash could go here
                        }
                        items.splice(i, 1);
                        continue;
                    }
    
                    // Remove off screen
                    if (item.y > canvas.height + 50) {
                        items.splice(i, 1);
                    }
                }
            }
    
            function gameLoop(timestamp) {
                if (!gameRunning) return;
    
                const dt = timestamp - lastTime;
                lastTime = timestamp;
    
                ctx.clearRect(0, 0, canvas.width, canvas.height);
    
                update(dt);
                drawItems();
                drawPlayer();
                drawParticles();
    
                requestAnimationFrame(gameLoop);
            }
        </script>
    </body>
    </html>
  • examples/apps/cinematic-ai-landing.html18 KB33a27e6eb65bupstream ↗
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Agnes AI | Intelligent Architecture</title>
        <style>
            :root {
                --pearl: #F9F9F7;
                --sand: #F4F2ED;
                --ink: #121212;
                --gray: #555555;
                --light-gray: #E5E5E5;
                --amber: #D96C2A;
                --amber-hover: #C0581D;
                --font-main: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
                --font-serif: Georgia, "Times New Roman", serif;
            }
            * { margin: 0; padding: 0; box-sizing: border-box; }
            body {
                font-family: var(--font-main);
                background-color: var(--pearl);
                color: var(--ink);
                line-height: 1.6;
                overflow-x: hidden;
                -webkit-font-smoothing: antialiased;
            }
            a { text-decoration: none; color: inherit; transition: opacity 0.2s; }
            a:hover { opacity: 0.6; }
    
            /* Layout Utilities */
            .container {
                max-width: 1200px;
                margin: 0 auto;
                padding: 0 2rem;
            }
            .grid {
                display: grid;
                gap: 2rem;
            }
            .grid-2 { grid-template-columns: 1fr 1fr; }
            .grid-3 { grid-template-columns: repeat(3, 1fr); }
    
            /* Typography */
            h1, h2, h3 { font-weight: 600; letter-spacing: -0.03em; line-height: 1.1; }
            h1 { font-size: 3.5rem; margin-bottom: 1.5rem; }
            h2 { font-size: 2rem; margin-bottom: 1rem; }
            h3 { font-size: 1.25rem; margin-bottom: 0.5rem; }
            p { margin-bottom: 1.5rem; color: var(--gray); font-size: 1.05rem; }
            .serif { font-family: var(--font-serif); font-style: italic; color: var(--amber); }
    
            /* Buttons */
            .btn {
                display: inline-block;
                padding: 0.8rem 1.8rem;
                font-size: 0.9rem;
                font-weight: 500;
                letter-spacing: 0.02em;
                border: 1px solid var(--ink);
                transition: all 0.3s ease;
                cursor: pointer;
            }
            .btn-primary {
                background-color: var(--ink);
                color: var(--pearl);
            }
            .btn-primary:hover {
                background-color: var(--amber);
                border-color: var(--amber);
                opacity: 1;
            }
            .btn-secondary {
                background-color: transparent;
                color: var(--ink);
            }
            .btn-secondary:hover {
                background-color: var(--ink);
                color: var(--pearl);
                opacity: 1;
            }
    
            /* Header */
            header {
                padding: 1.5rem 0;
                position: sticky;
                top: 0;
                background: rgba(249, 249, 247, 0.9);
                backdrop-filter: blur(10px);
                z-index: 100;
                border-bottom: 1px solid var(--light-gray);
            }
            nav {
                display: flex;
                justify-content: space-between;
                align-items: center;
            }
            .logo { font-weight: 700; font-size: 1.2rem; letter-spacing: -0.05em; }
            .nav-links { display: flex; gap: 2rem; align-items: center; }
            .nav-links a { font-size: 0.9rem; font-weight: 500; }
    
            /* Hero */
            .hero {
                padding: 8rem 0 6rem;
                display: flex;
                flex-direction: column;
                justify-content: center;
                min-height: 80vh;
            }
            .hero-grid {
                display: grid;
                grid-template-columns: 1.2fr 0.8fr;
                gap: 4rem;
                align-items: center;
            }
            .hero-visual {
                background: var(--sand);
                height: 400px;
                width: 100%;
                display: flex;
                align-items: center;
                justify-content: center;
                border-left: 4px solid var(--amber);
                position: relative;
            }
            .hero-visual::after {
                content: "System Ready";
                position: absolute;
                bottom: 1.5rem;
                right: 1.5rem;
                font-family: monospace;
                font-size: 0.8rem;
                color: var(--gray);
            }
    
            /* Sections */
            section { padding: 6rem 0; }
            .section-header {
                border-top: 1px solid var(--light-gray);
                padding-top: 2rem;
                margin-bottom: 4rem;
                display: flex;
                justify-content: space-between;
                align-items: flex-end;
            }
            .section-tag {
                text-transform: uppercase;
                font-size: 0.75rem;
                letter-spacing: 0.1em;
                color: var(--amber);
                margin-bottom: 1rem;
                display: block;
            }
    
            /* Cards */
            .card {
                background: white;
                padding: 2rem;
                border: 1px solid var(--light-gray);
                transition: transform 0.3s, box-shadow 0.3s;
            }
            .card:hover {
                transform: translateY(-4px);
                box-shadow: 0 10px 30px rgba(0,0,0,0.05);
                border-color: var(--amber);
            }
            .stat-number {
                font-size: 2.5rem;
                font-weight: 700;
                color: var(--ink);
                margin-bottom: 0.2rem;
            }
    
            /* Developer / API */
            .dev-section {
                background: var(--ink);
                color: var(--pearl);
                padding: 6rem 0;
            }
            .dev-section p { color: #A0A0A0; }
            .code-block {
                background: #1A1A1A;
                padding: 1.5rem;
                border-radius: 4px;
                font-family: monospace;
                font-size: 0.85rem;
                color: #D96C2A;
                margin: 2rem 0;
                border-left: 1px solid #333;
            }
    
            /* Trust */
            .trust-bar {
                display: flex;
                gap: 4rem;
                align-items: center;
                padding: 2rem 0;
                border-top: 1px solid var(--light-gray);
                border-bottom: 1px solid var(--light-gray);
                margin-top: 4rem;
                opacity: 0.6;
            }
            .trust-item { font-weight: 600; font-size: 1.2rem; color: var(--gray); }
    
            /* Footer */
            footer {
                background: white;
                padding: 4rem 0;
                margin-top: 4rem;
            }
            .footer-grid {
                display: flex;
                justify-content: space-between;
            }
            .footer-col h4 { font-size: 0.9rem; margin-bottom: 1.2rem; }
            .footer-col ul { list-style: none; }
            .footer-col li { margin-bottom: 0.8rem; }
            .footer-col a { font-size: 0.9rem; color: var(--gray); }
            .footer-col a:hover { color: var(--ink); opacity: 1; }
    
            /* Mobile */
            @media (max-width: 768px) {
                h1 { font-size: 2.5rem; }
                .grid-2, .grid-3, .hero-grid, .footer-grid { grid-template-columns: 1fr; display: flex; flex-direction: column; }
                .nav-links { display: none; }
                .hero-visual { height: 250px; margin-top: 2rem; }
                .section-header { flex-direction: column; align-items: flex-start; }
            }
        </style>
    </head>
    <body>
    
        <!-- Navigation -->
        <header>
            <div class="container">
                <nav>
                    <a href="#" class="logo">AGNES AI</a>
                    <div class="nav-links">
                        <a href="#platform">Platform</a>
                        <a href="#research">Research</a>
                        <a href="#enterprise">Enterprise</a>
                        <a href="#pricing">Pricing</a>
                        <a href="#" class="btn btn-primary" style="padding: 0.5rem 1.2rem; font-size: 0.8rem;">Launch Console</a>
                    </div>
                </nav>
            </div>
        </header>
    
        <!-- Hero Section -->
        <section class="container hero">
            <div class="hero-grid">
                <div>
                    <span class="section-tag">Next Generation Infrastructure</span>
                    <h1>Architectural <br><span class="serif">intelligence.</span></h1>
                    <p>Agnes AI delivers semantic precision for the world's most demanding developers. We bridge the gap between raw computation and refined logic.</p>
                    <div style="margin-top: 2rem;">
                        <a href="#api" class="btn btn-primary">Get API Keys</a>
                        <a href="#docs" class="btn btn-secondary" style="margin-left: 1rem;">Read Documentation</a>
                    </div>
                </div>
                <div class="hero-visual">
                    <div style="text-align: left; width: 80%;">
                        <div style="height: 4px; width: 40px; background: var(--amber); margin-bottom: 20px;"></div>
                        <div style="height: 8px; width: 100%; background: #EAE9E4; margin-bottom: 10px;"></div>
                        <div style="height: 8px; width: 85%; background: #EAE9E4; margin-bottom: 10px;"></div>
                        <div style="height: 8px; width: 92%; background: #EAE9E4; margin-bottom: 20px;"></div>
                        <div style="font-family: monospace; font-size: 0.8rem; color: var(--amber); margin-top: 30px;">
                            &gt; optimizing neural weights...<br>
                            &gt; latency: 12ms<br>
                            &gt; context window: 128k
                        </div>
                    </div>
                </div>
            </div>
        </section>
    
        <!-- Model Overview -->
        <section class="container">
            <div class="section-header">
                <div>
                    <span class="section-tag">Model Zoo</span>
                    <h2>Tailored for scale.</h2>
                </div>
                <a href="#" style="border-bottom: 1px solid var(--ink); font-size: 0.9rem;">View full specifications</a>
            </div>
                <div class="grid grid-3">
                    <div class="card">
                        <h3>agnes-2.0-flash</h3>
                        <p style="font-size: 0.9rem; margin-bottom: 1rem;">Fast default for chat, coding, tool calling, and agent workflows where teams want a single dependable text model.</p>
                        <a href="#" style="font-size: 0.85rem; font-weight: 600; color: var(--ink);">Launch text workflows &rarr;</a>
                    </div>
                    <div class="card" style="border-color: var(--ink);">
                        <div style="font-size: 0.7rem; background: var(--ink); color: white; display: inline-block; padding: 2px 6px; margin-bottom: 1rem;">RECOMMENDED</div>
                        <h3>agnes-image-2.1-flash</h3>
                        <p style="font-size: 0.9rem; margin-bottom: 1rem;">Preferred visual model for dense compositions, polished marketing imagery, and image-to-image work that preserves layout.</p>
                        <a href="#" style="font-size: 0.85rem; font-weight: 600; color: var(--amber);">Generate visual campaigns &rarr;</a>
                    </div>
                    <div class="card">
                        <h3>agnes-video-v2.0</h3>
                        <p style="font-size: 0.9rem; margin-bottom: 1rem;">Asynchronous video generation for ad spots, animated concepts, and cinematic motion studies driven by text or image prompts.</p>
                        <a href="#" style="font-size: 0.85rem; font-weight: 600; color: var(--ink);">Create motion stories &rarr;</a>
                    </div>
                </div>
            </section>
    
        <!-- Feature Story: Developer Experience -->
        <section id="api" class="dev-section">
            <div class="container">
                <div class="grid grid-2" style="align-items: center;">
                    <div>
                        <span class="section-tag">Integration</span>
                        <h2 style="color: white;">Designed for the <span style="color: var(--amber);">developer</span> workflow.</h2>
                        <p>Agnes AI isn't just a model; it's a structural component of your stack. Our API is standardized, typed, and incredibly fast.</p>
                        <ul style="margin-bottom: 2rem; list-style: none; color: #A0A0A0;">
                            <li style="margin-bottom: 0.5rem;">&bull; 99.99% SLA Uptime</li>
                            <li style="margin-bottom: 0.5rem;">&bull; JSON-mode strict parsing</li>
                            <li style="margin-bottom: 0.5rem;">&bull; Streaming tokens for real-time UI</li>
                        </ul>
                        <a href="#" class="btn btn-secondary" style="border-color: #555; color: white;">View API Reference</a>
                    </div>
                    <div>
                        <div class="code-block">
    const agnes = require('agnes-sdk');<br><br>
    const response = await agnes.chat.complete({<br>
    &nbsp;&nbsp;model: 'agnes-14b-v4',<br>
    &nbsp;&nbsp;messages: [<br>
    &nbsp;&nbsp;&nbsp;&nbsp;{ role: 'user', content: 'Analyze this dataset.' }<br>
    &nbsp;&nbsp;],<br>
    &nbsp;&nbsp;temperature: 0.2,<br>
    &nbsp;&nbsp;response_format: { type: 'json_object' }<br>
    });<br><br>
    console.log(response.choices[0].message);
                        </div>
                    </div>
                </div>
            </div>
        </section>
    
        <!-- Trust & Features -->
        <section class="container">
            <div class="section-header">
                <div>
                    <span class="section-tag">Enterprise Grade</span>
                    <h2>Reliability by design.</h2>
                </div>
            </div>
            <div class="grid grid-3">
                <div style="padding: 1rem 0;">
                    <div class="stat-number">128k</div>
                    <h3>Context Window</h3>
                    <p style="font-size: 0.9rem;">Process entire codebases or legal documents in a single pass.</p>
                </div>
                <div style="padding: 1rem 0; border-left: 1px solid var(--light-gray);">
                    <div class="stat-number">4x</div>
                    <h3>Inference Speed</h3>
                    <p style="font-size: 0.9rem;">Proprietary pruning algorithms ensure faster time-to-first-token.</p>
                </div>
                <div style="padding: 1rem 0; border-left: 1px solid var(--light-gray);">
                    <div class="stat-number">SOC2</div>
                    <h3>Compliant</h3>
                    <p style="font-size: 0.9rem;">Type B certification for data privacy and secure handling.</p>
                </div>
            </div>
    
            <div class="trust-bar">
                <span class="trust-item">NVIDIA PARTNER</span>
                <span class="trust-item">STACK OVERFLOW SPONSOR</span>
                <span class="trust-item">GITHUB EXCEL</span>
                <span class="trust-item">Vercel</span>
            </div>
        </section>
    
        <!-- Final CTA -->
        <section style="background: var(--sand); text-align: center;">
            <div class="container">
                <h2 style="font-size: 2.5rem; margin-bottom: 1rem;">Ready to build?</h2>
                <p style="max-width: 600px; margin: 0 auto 2rem auto;">Join thousands of engineers who have migrated to Agnes AI for better accuracy and lower latency.</p>
                <a href="#" class="btn btn-primary" style="padding: 1rem 3rem;">Start Building Now</a>
            </div>
        </section>
    
        <!-- Footer -->
        <footer class="container">
            <div class="footer-grid">
                <div class="footer-col" style="max-width: 300px;">
                    <div class="logo" style="margin-bottom: 1rem;">AGNES AI</div>
                    <p style="font-size: 0.85rem;">San Francisco, CA.<br>Optimizing the future of intelligence.</p>
                </div>
                <div class="footer-col">
                    <h4>PRODUCT</h4>
                    <ul>
                        <li><a href="#">Model Zoo</a></li>
                        <li><a href="#">Pricing</a></li>
                        <li><a href="#">Security</a></li>
                        <li><a href="#">Enterprise</a></li>
                    </ul>
                </div>
                <div class="footer-col">
                    <h4>DEVELOPERS</h4>
                    <ul>
                        <li><a href="#">Documentation</a></li>
                        <li><a href="#">API Reference</a></li>
                        <li><a href="#">GitHub Repo</a></li>
                        <li><a href="#">Status</a></li>
                    </ul>
                </div>
                <div class="footer-col">
                    <h4>COMPANY</h4>
                    <ul>
                        <li><a href="#">About</a></li>
                        <li><a href="#">Blog</a></li>
                        <li><a href="#">Careers</a></li>
                        <li><a href="#">Contact</a></li>
                    </ul>
                </div>
            </div>
            <div style="margin-top: 4rem; padding-top: 2rem; border-top: 1px solid var(--light-gray); display: flex; justify-content: space-between; font-size: 0.8rem; color: var(--gray);">
                <span>&copy; 2024 Agnes AI Inc. All rights reserved.</span>
                <div>
                    <a href="#" style="margin-left: 1rem;">Privacy Policy</a>
                    <a href="#" style="margin-left: 1rem;">Terms of Service</a>
                </div>
            </div>
        </footer>
    
        <script>
            // Simple script to handle smooth scroll for anchor links
            document.querySelectorAll('a[href^="#"]').forEach(anchor => {
                anchor.addEventListener('click', function (e) {
                    e.preventDefault();
                    document.querySelector(this.getAttribute('href')).scrollIntoView({
                        behavior: 'smooth'
                    });
                });
            });
    
            // Minimal scroll observer for fade-in effect (Performance conscious)
            const observer = new IntersectionObserver((entries) => {
                entries.forEach(entry => {
                    if (entry.isIntersecting) {
                        entry.target.style.opacity = 1;
                        entry.target.style.transform = 'translateY(0)';
                    }
                });
            });
    
            // Add subtle load animation to cards
            document.querySelectorAll('.card').forEach((card, index) => {
                card.style.opacity = 0;
                card.style.transform = 'translateY(20px)';
                card.style.transition = `all 0.6s ease ${index * 0.1}s`;
                observer.observe(card);
            });
        </script>
    </body>
    </html>
    
  • examples/apps/watch-experience.html12 KB804e8d1cca9aupstream ↗
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Golden Hour Stories | Agnes Image + Video</title>
        <style>
            :root {
                --cream: #F9F7F2;
                --blush: #F2E6E5;
                --gold: #C5A065;
                --gold-dark: #A68248;
                --text: #2C2824;
                --font-serif: 'Times New Roman', Times, serif;
                --font-sans: 'Helvetica Neue', Helvetica, Arial, sans-serif;
            }
            body {
                margin: 0;
                padding: 0;
                background-color: var(--cream);
                color: var(--text);
                font-family: var(--font-sans);
                line-height: 1.6;
                overflow-x: hidden;
            }
            .container {
                max-width: 1200px;
                margin: 0 auto;
                padding: 0 40px;
            }
            h1, h2, h3, h4 {
                font-family: var(--font-serif);
                font-weight: 400;
                margin: 0 0 20px 0;
                letter-spacing: -0.02em;
            }
            .btn {
                display: inline-block;
                background-color: var(--gold);
                color: #fff;
                padding: 18px 40px;
                text-decoration: none;
                text-transform: uppercase;
                font-size: 0.85rem;
                letter-spacing: 0.15em;
                transition: background 0.3s ease;
                border: none;
                cursor: pointer;
            }
            .btn:hover {
                background-color: var(--gold-dark);
            }
            header {
                padding: 40px 0;
                display: flex;
                justify-content: space-between;
                align-items: center;
            }
            .logo {
                font-family: var(--font-serif);
                font-size: 1.5rem;
                font-weight: 700;
                letter-spacing: 0.05em;
            }
            .nav-link {
                color: var(--text);
                text-decoration: none;
                font-size: 0.8rem;
                text-transform: uppercase;
                letter-spacing: 0.1em;
            }
            .hero {
                padding: 120px 0;
                text-align: center;
                background: linear-gradient(to bottom, var(--cream), var(--blush));
            }
            .hero h1 {
                font-size: 5rem;
                line-height: 0.95;
                color: var(--text);
                margin-bottom: 30px;
            }
            .hero p {
                font-size: 1.25rem;
                max-width: 600px;
                margin: 0 auto 50px;
                color: #665c56;
                font-family: var(--font-serif);
                font-style: italic;
            }
            .campaign-narrative {
                padding: 100px 0;
                border-top: 1px solid #E5DFD6;
            }
            .narrative-grid {
                display: grid;
                grid-template-columns: 1fr 1fr;
                gap: 60px;
                align-items: center;
            }
            .narrative-text h2 {
                font-size: 3rem;
                line-height: 1.1;
            }
            .narrative-text p {
                font-size: 1rem;
                margin-bottom: 30px;
                color: #555;
            }
            .narrative-visual {
                height: 500px;
                background-color: var(--gold);
                position: relative;
                overflow: hidden;
            }
            .narrative-visual::after {
                content: '';
                position: absolute;
                top: 0;
                left: 0;
                right: 0;
                bottom: 0;
                background: linear-gradient(45deg, rgba(197, 160, 101, 0.4), rgba(44, 40, 36, 0.2));
            }
            .panels {
                padding: 120px 0;
                background-color: var(--blush);
            }
            .section-header {
                text-align: center;
                margin-bottom: 80px;
            }
            .section-header h3 {
                font-size: 2.5rem;
            }
            .section-header p {
                font-size: 0.9rem;
                text-transform: uppercase;
                letter-spacing: 0.2em;
                color: var(--gold-dark);
            }
            .panel-grid {
                display: grid;
                grid-template-columns: repeat(3, 1fr);
                gap: 30px;
            }
            .panel {
                background-color: var(--cream);
                padding: 40px;
                transition: transform 0.4s ease;
            }
            .panel:hover {
                transform: translateY(-10px);
            }
            .panel-icon {
                width: 60px;
                height: 60px;
                background-color: var(--gold);
                margin-bottom: 30px;
                border-radius: 50%;
                display: flex;
                align-items: center;
                justify-content: center;
                color: white;
                font-size: 1.5rem;
                font-family: var(--font-serif);
            }
            .panel h4 {
                font-size: 1.5rem;
                margin-bottom: 15px;
            }
            .panel p {
                font-size: 0.95rem;
                color: #666;
            }
            .social-proof {
                padding: 80px 0;
                background-color: var(--cream);
                text-align: center;
            }
            .proof-strip {
                display: flex;
                justify-content: center;
                gap: 60px;
                margin-top: 40px;
                flex-wrap: wrap;
            }
            .proof-item {
                text-align: center;
            }
            .proof-number {
                font-family: var(--font-serif);
                font-size: 3rem;
                color: var(--gold);
                display: block;
                line-height: 1;
            }
            .proof-label {
                font-size: 0.75rem;
                text-transform: uppercase;
                letter-spacing: 0.1em;
                margin-top: 10px;
                display: block;
                color: #888;
            }
            .cta-section {
                padding: 150px 0;
                background-color: var(--text);
                color: var(--cream);
                text-align: center;
            }
            .cta-section h2 {
                font-size: 4rem;
                color: var(--gold);
                margin-bottom: 30px;
            }
            .cta-section p {
                font-size: 1.2rem;
                margin-bottom: 50px;
                color: #ccc;
                max-width: 700px;
                margin-left: auto;
                margin-right: auto;
            }
            .cta-section .btn {
                background-color: var(--gold);
            }
            footer {
                padding: 40px 0;
                text-align: center;
                font-size: 0.8rem;
                color: #888;
                background-color: var(--cream);
            }
            @media (max-width: 768px) {
                .hero h1 { font-size: 3rem; }
                .narrative-grid { grid-template-columns: 1fr; }
                .panel-grid { grid-template-columns: 1fr; }
                .proof-strip { gap: 30px; }
                .container { padding: 0 20px; }
            }
        </style>
    </head>
    <body>
    
        <div class="container">
            <header>
                <div class="logo">AGNES + VIDEO</div>
                <nav>
                    <a href="#" class="nav-link">Campaign</a>
                </nav>
            </header>
        </div>
    
        <section class="hero">
            <div class="container">
                <h1>GOLDEN HOUR<br>STORIES</h1>
                <p>A curated visual journey capturing the ephemeral beauty of fleeting moments. Experience luxury through light.</p>
                <a href="#cta" class="btn">View Collection</a>
            </div>
        </section>
    
        <section class="campaign-narrative">
            <div class="container">
                <div class="narrative-grid">
                    <div class="narrative-text">
                        <h2>THE ALCHEMY OF LIGHT</h2>
                        <p>Golden Hour Stories is not merely a collection; it is an immersive editorial experience. We explore the intersection of high fashion and natural brilliance, where every frame tells a story of warmth, elegance, and timeless appeal.</p>
                        <p>Our creative drop features exclusive imagery and cinematic video clips designed to elevate your digital presence. Crafted for the discerning eye, this campaign redefines the standard of premium content.</p>
                        <a href="#" class="nav-link" style="border-bottom: 1px solid var(--text); padding-bottom: 5px;">Read the Manifesto</a>
                    </div>
                    <div class="narrative-visual"></div>
                </div>
            </div>
        </section>
    
        <section class="panels">
            <div class="container">
                <div class="section-header">
                    <p>The Collection</p>
                    <h3>THREE PERSPECTIVES</h3>
                </div>
                <div class="panel-grid">
                    <div class="panel">
                        <div class="panel-icon">I</div>
                        <h4>Visual Essays</h4>
                        <p>High-resolution editorial photography capturing the essence of sunset hues and shadow play. Perfect for digital campaigns and print inspiration.</p>
                    </div>
                    <div class="panel">
                        <div class="panel-icon">II</div>
                        <h4>Cinematic Loops</h4>
                        <p>Seamless video loops designed to bring life to static spaces. Experience motion in its most refined form, with a focus on texture and movement.</p>
                    </div>
                    <div class="panel">
                        <div class="panel-icon">III</div>
                        <h4>Brand Assets</h4>
                        <p>Curated templates and overlays to integrate the Golden Hour aesthetic into your existing brand identity. Elevate your visual language instantly.</p>
                    </div>
                </div>
            </div>
        </section>
    
        <section class="social-proof">
            <div class="container">
                <div class="section-header">
                    <p>Impact</p>
                </div>
                <div class="proof-strip">
                    <div class="proof-item">
                        <span class="proof-number" data-target="250">0</span>
                        <span class="proof-label">Assets Included</span>
                    </div>
                    <div class="proof-item">
                        <span class="proof-number" data-target="48">0</span>
                        <span class="proof-label">Countries Reached</span>
                    </div>
                    <div class="proof-item">
                        <span class="proof-number" data-target="12">0</span>
                        <span class="proof-label">Industry Awards</span>
                    </div>
                    <div class="proof-item">
                        <span class="proof-number" data-target="100">0</span>
                        <span class="proof-label">Percent Premium</span>
                    </div>
                </div>
            </div>
        </section>
    
        <section id="cta" class="cta-section">
            <div class="container">
                <h2>ACQUIRE THE DROP</h2>
                <p>Join the list of creative directors and agencies transforming their visual narratives. Limited availability for the inaugural release.</p>
                <a href="#" class="btn">Get Access Now</a>
            </div>
        </section>
    
        <footer>
            <div class="container">
                <p>&copy; 2023 Agnes Image + Video. All rights reserved. Designed for Excellence.</p>
            </div>
        </footer>
    
        <script>
            document.addEventListener('DOMContentLoaded', function() {
                const counters = document.querySelectorAll('.proof-number');
                const speed = 200;
    
                const animateCounters = () => {
                    counters.forEach(counter => {
                        const target = +counter.getAttribute('data-target');
                        const count = +counter.innerText;
                        const inc = target / speed;
    
                        if (count < target) {
                            counter.innerText = Math.ceil(count + inc);
                            setTimeout(animateCounters, 20);
                        } else {
                            counter.innerText = target;
                        }
                    });
                };
    
                const observer = new IntersectionObserver((entries) => {
                    entries.forEach(entry => {
                        if (entry.isIntersecting) {
                            animateCounters();
                            observer.unobserve(entry.target);
                        }
                    });
                }, { threshold: 0.5 });
    
                const proofSection = document.querySelector('.social-proof');
                if (proofSection) {
                    observer.observe(proofSection);
                }
            });
        </script>
    </body>
    </html>
  • LICENSE1.0 KBbc8042b36d18upstream ↗
    MIT License
    
    Copyright (c) 2026 Jomes Wang
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
  • README.zh-CN.md6.5 KB9e95e26a55a4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/jomeswang-agnes-ai-skill.md

// REPO STATS

47 stars
0 open issues
Last commit: 5mo ago