image-sprout
Generate and iterate on images with consistent style and subject identity. Image Sprout turns reusable project context — reference images, derived guides, and persistent instructions — into repeatable outputs.
1. OpenRouter Key Setup
Image Sprout stores its OpenRouter key on disk. Set it once per machine:
CODEBLOCK0
How the calling environment stores or injects that key is outside this skill's scope.
2. The Project Model
Three context layers drive every generation:
- - Visual Style — consistent look and feel across outputs
- Subject Guide — consistent subject identity across outputs
- Instructions — persistent generation constraints (watermarks, framing, branding)
Two reference pools:
- - Shared refs — drive both guides (default, simplest)
- Split refs — separate style and subject pools (advanced; use
--role style or --role subject when adding)
Understanding this model prevents the most common agent mistake: generating without saved context and wondering why outputs are inconsistent.
3. Core CLI Workflow
CODEBLOCK1
Top-level aliases for convenience:
CODEBLOCK2
4. JSON Output — the Agent Pattern
Always use --json for structured output:
CODEBLOCK3
Use --value PATH to pluck a single field:
CODEBLOCK4
This is how agents hand image paths to downstream tools. Run images land in image-sprout's internal app data directory — use run latest --json --value images[0].path to get the path and leave what to do with it to the calling workflow.
5. Parallel-Safe Usage
INLINECODE5 sets a shared "current project" state on disk. When multiple agents or processes run concurrently, this state can collide. Always pass --project <name> explicitly — never rely on the current project shortcut in agent workflows.
6. Web UI — Agent Awareness
The web app runs over the same on-disk store as the CLI. Agents won't use it directly, but should know it exists so they can offer it to users when interactive review is appropriate.
CODEBLOCK5
Useful for:
- - reviewing and comparing generated images visually
- setting up a project interactively before handing off to CLI/agent use
- iterating on outputs via the canvas interface
Security: do not expose the web UI to the public internet. The server has no authentication. Safe options are localhost only, or a private network like Tailscale. The risk is public internet exposure — LAN and tailnet access are fine.
7. Model Management
CODEBLOCK6
Default generation model is Nano Banana 2 (google/gemini-3.1-flash-image-preview). Custom models must accept image input and produce image output via OpenRouter.
Guide derivation uses a separate configurable analysis model (default: google/gemini-3.1-flash-image-preview):
CODEBLOCK7
image-sprout
生成并迭代具有一致风格和主体特征的图像。Image Sprout 将可复用的项目上下文——参考图像、衍生指南和持久化指令——转化为可重复的输出。
1. OpenRouter 密钥设置
Image Sprout 将 OpenRouter 密钥存储在磁盘上。每台机器只需设置一次：
bash
image-sprout config set apiKey <你的-openrouter-密钥>
image-sprout config show # 确认密钥已设置（不会显示原始密钥）
调用环境如何存储或注入该密钥不在本技能范围内。
2. 项目模型
三个上下文层驱动每次生成：
- - 视觉风格 — 输出间一致的外观和感觉
- 主体指南 — 输出间一致的主体特征
- 指令 — 持久化生成约束（水印、构图、品牌标识）
两个参考池：
- - 共享参考 — 驱动两个指南（默认，最简单）
- 分离参考 — 分离风格和主体池（高级；添加时使用 --role style 或 --role subject）
理解此模型可防止最常见的代理错误：在没有保存上下文的情况下生成，然后疑惑为什么输出不一致。
3. 核心 CLI 工作流
bash
创建项目
image-sprout project create <名称>
添加参考（建议 3 个以上；更多参考 = 更好的衍生效果）
image-sprout ref add --project <名称> ./ref1.png ./ref2.png ./ref3.png
可选：持久化指令
image-sprout project update <名称> --instructions 右下角水印：微妙。
从参考衍生指南
image-sprout project derive <名称> --target both # 或：style, subject
生成前检查就绪状态
image-sprout project status <名称> --json
生成（--count 控制每次运行的图像数量：1, 2, 4, 6；默认为 4）
image-sprout project generate <名称> --prompt 霓虹雨中的英雄
image-sprout project generate <名称> --prompt 霓虹雨中的英雄 --count 1
检查结果
image-sprout run latest --project <名称> --json
删除会话及其所有运行/图像
image-sprout session delete --project <名称> <会话-id>
便捷的顶级别名：
bash
image-sprout generate --project <名称> --prompt 霓虹雨中的英雄 # 等同于 project generate
image-sprout analyze --project <名称> --target both # 等同于 project derive
4. JSON 输出——代理模式
始终使用 --json 获取结构化输出：
bash
image-sprout project show <名称> --json
image-sprout project status <名称> --json
image-sprout run latest --project <名称> --json
image-sprout run list --project <名称> --json --limit 5
使用 --value PATH 提取单个字段：
bash
image-sprout run latest --project <名称> --json --value images[0].path
这是代理将图像路径传递给下游工具的方式。运行图像存储在 image-sprout 的内部应用数据目录中——使用 run latest --json --value images[0].path 获取路径，如何处理该路径由调用工作流决定。
5. 并行安全使用
image-sprout project use <名称> 在磁盘上设置共享的当前项目状态。当多个代理或进程同时运行时，此状态可能发生冲突。始终显式传递 --project <名称>——在代理工作流中切勿依赖当前项目快捷方式。
6. Web UI——代理感知
Web 应用与 CLI 共享相同的磁盘存储。代理不会直接使用它，但应知道其存在，以便在适合交互式审查时提供给用户。
bash
image-sprout web # 启动本地应用
image-sprout web --open # 同时在默认浏览器中打开
image-sprout web --port 8080 # 自定义端口（默认：4310）
适用于：
- - 直观地审查和比较生成的图像
- 在交给 CLI/代理使用前交互式设置项目
- 通过画布界面迭代输出
安全：请勿将 Web UI 暴露到公共互联网。 服务器没有身份验证。安全选项包括仅限 localhost，或使用 Tailscale 等私有网络。风险在于公共互联网暴露——局域网和 tailnet 访问是安全的。
7. 模型管理
bash
image-sprout model list
image-sprout model set-default google/gemini-3.1-flash-image-preview
image-sprout model add openai/gpt-5-image
image-sprout model restore-defaults
默认生成模型是 Nano Banana 2 (google/gemini-3.1-flash-image-preview)。自定义模型必须通过 OpenRouter 接受图像输入并生成图像输出。
指南衍生使用单独的可配置分析模型（默认：google/gemini-3.1-flash-image-preview）：
bash
设置持久化分析模型
image-sprout config set analysisModel google/gemini-2.5-flash
每次衍生时覆盖
image-sprout project derive <名称> --target both --analysis-model google/gemini-2.5-flash
