banana-claude

图1：Banana Claude 插件封面

想象一个场景：你是一名独立开发者，正在为刚上线的 SaaS 产品写推广文案，需要一张能让人眼前一亮的 Hero Image。打开 Figma 太重，Midjourney 需要复杂的 prompt 工程，Stable Diffusion 本地部署更是折腾。这时候，你只需要在终端里敲一行命令：

/banana generate "a hero image for a coffee shop website"

Claude Code 立刻化身创意总监，识别出这是一个**网站类（UI/Web）**场景，自动套用专业的构图和配色公式，调用 Google Gemini 的图片生成能力，产出一张可以直接使用的素材。整个过程不需要切换应用，不需要查阅文档，不需要手写提示词——你只需要描述想法，剩下的交给 AI。

这就是 Banana Claude 正在做的事。

背景：从 API 包装器到创意导演

Banana Claude 的作者是罗马尼亚独立开发者 AgriciDaniel。他最早在 2025 年初尝试将 Google Gemini 的图片生成 API 接入 Claude Code 时，发现了一个核心矛盾：Gemini 本身能力不差，但模型对 prompt 的格式和结构极度敏感——同样的需求，换一种写法，输出质量可能天差地别。

大多数现有的 Gemini 图片工具，只是简单地把用户输入透传给 API，等同于一个带 UI 的 curl 命令。AgriciDaniel 决定换一种思路：不把 Claude 当作 API 调用的执行者，而是让它扮演**创意总监（Creative Director）**的角色——理解用户意图，选择专业领域模板，构建结构化的 prompt，最后才是调用 API。

这个思路在 2025 年中旬正式落地，演变成今天的 Banana Claude。目前版本 1.4.1，GitHub 获得 704 颗 star，在 Claude Code 技能市场中排名靠前。

核心理念：五步 prompt 公式

Banana Claude 的灵魂是一套 Google 官方验证过的 五步 Prompt 公式（5-Component Prompt Formula），所有生成的 prompt 都遵循这个结构：

组件	作用	示例
Subject（主体）	明确画面主角的物理特征	A weathered Japanese ceramicist in his 70s, deep sun-etched wrinkles...
Action（动作）	描述行为或视觉状态	leaning forward with intense concentration, gently smoothing the rim...
Location（场景）	环境、时间、氛围	inside a traditional wood-fired anagama kiln workshop, late afternoon light...
Composition（构图）	镜头、视角、景别	intimate close-up, soft natural backlight, depth of field on the hands
Style（风格）	视觉风格和情绪	cinematic still life photography, Kodak Portra 400 film stock

这套公式的核心原则是：用自然段落叙事，而不是关键词罗列。Claude 在生成 prompt 时，会将这五个组件组合成流畅的英文段落，Gemini 对这类结构化叙事的理解效果远优于关键词堆砌。

图2：Claude 内部的推理 Brief，展示五步 prompt 的构建过程

九大领域模式：专业场景的精准路由

五步公式是通用框架，但在实际场景中，不同用途的图片有完全不同的专业标准。Banana Claude 提供了 9 个领域模式（Domain Modes），Claude 会根据用户需求自动选择最合适的领域，并应用该领域的特定专业知识：

• Cinema（电影）：适合故事感强、有情绪张力的场景，会套用镜头语言（焦距、光圈、胶片型号）
• Product（产品）：电商主图、packshot，要求干净的背景、专业的打光
• Portrait（人像）：面部细节、表情、Pose 的精确控制
• Editorial（编辑）：杂志风格、生活方式图片，强调造型和构图
• UI/Web（界面）：App 图标、Banner、插画，要求扁平化和品牌色
• Logo（标志）：几何构造、最小色彩盘、可缩放性
• Landscape（风景）：环境、壁纸、背景板，强调氛围和景深
• Abstract（抽象）：纹理、图案、数字艺术
• Infographic（信息图）：数据可视化风格

这种领域路由的能力，是 Banana Claude 区别于普通 API 包装器的关键——Claude 不仅仅在调用 Gemini，而是在用专业知识指导 Gemini。

技术架构：三层设计

Banana Claude 的技术实现分为三层，每一层都有清晰的设计边界：

第一层：技能定义（SKILL.md）

skills/banana/SKILL.md 是整个项目的核心，定义了 Claude 的行为规范。这不是一个简单的命令列表，而是一套完整的代理工作流（Agent Workflow）：

1. 每次生成图片前，Claude 必须先读取 references/gemini-models.md 和 references/prompt-engineering.md
2. 分析用户意图，必要时询问澄清问题
3. 选择领域模式，检查是否有品牌预设
4. 用五步公式构建 prompt
5. 选择模型和参数
6. 调用 MCP 工具（或降级到直接 API）
7. 检查返回状态，处理安全过滤、成本限制等异常
8. 确认图片文件实际存在后才报告成功

这种"必须先读文档再行动"的约束，是 Banana Claude 保持输出质量一致性的机制保证。

第二层：参考文档（references/）

文件	作用
gemini-models.md	模型选型表，包含 Nano Banana、Nano Banana 2、Nano Banana Pro 的能力对比、分辨率上限、速率限制
prompt-engineering.md	五步公式详解、各领域模式的 modifier 库、进阶技巧
mcp-tools.md	MCP 工具的参数定义和响应格式
post-processing.md	生成后处理：FFmpeg 视频处理、ImageMagick 抠图、透明度处理
cost-tracking.md	成本追踪：各模型的计费方式、免费额度
presets.md	品牌预设：保存配色、风格参数，方便重复使用

这些文档采用按需加载策略（on-demand），Claude 不会在每次启动时全部读取，而是在具体任务需要时才加载对应文档，既保证了质量又避免了 token 浪费。

第三层：Python 脚本（scripts/）

scripts/generate.py 和 scripts/edit.py 是 MCP 的降级方案——当 MCP 服务器不可用时，直接用 Python 标准库 urllib.request 调用 Gemini REST API。设计上坚持零 pip 依赖（stdlib only），确保在任何有 Python 3.6+ 的系统上都能运行。

上手体验：零门槛开箱即用

Banana Claude 支持两种安装方式。**插件模式（Plugin）**是官方推荐的方式，一条命令完成安装：

/plugin marketplace add AgriciDaniel/banana-claude
/plugin install banana-claude@banana-claude-marketplace

独立模式通过 install.sh 脚本将技能复制到 ~/.claude/skills/banana/：

git clone --depth 1 https://github.com/AgriciDaniel/banana-claude.git
cd banana-claude && bash install.sh --with-mcp YOUR_API_KEY

安装后，需要一个 Google AI Studio 的免费 API Key（https://aistudio.google.com/apikey），设置 MCP 配置即可。整个过程 10 分钟内可以完成。

使用时的交互方式非常自然：

/banana generate "a red apple on a white table"       # 简单生成
/banana edit ~/photo.png "make the background blurry"  # 图片编辑
/banana chat                                        # 多轮创意会话
/banana inspire                                     # 浏览 2500+ prompt 数据库
/banana batch "product shot for headphones" 5       # 批量生成 N 个变体

Claude 会主动询问模糊需求（比如"我要一张 Hero Image"），引导用户明确用途、风格、约束条件，确保输出的图片真的能用。

局限与挑战：坦诚地说

没有工具是完美的，Banana Claude 也不例外，有几个明显的局限性需要正视：

1. Gemini 模型本身的质量天花板

Banana Claude 的输出质量上限由 Gemini 决定。截至 2026 年 3 月，gemini-3.1-flash-image-preview（Nano Banana 2）是主力模型，最高支持 4K 分辨率和极端宽高比（1:4、4:1 等），但与 DALL-E 3、Midjourney v7 相比，在某些特定风格（如摄影级写实）上仍有差距。作者明确标注，Gemini 无法使用负向提示词（negative prompts），只能用语义重构的方式规避不想要的元素。

2. API 速率限制的困扰

免费层的 Gemini API 速率限制较为严格（每项目约 5-15 RPM，每天 20-500 次请求），批量生成时容易触发限制。gemini-3-pro-image-preview（Nano Banana Pro）已于 2026 年 3 月 9 日被 Google 关闭，导致 Banana Claude 1.4.0 版本紧急更新模型路由。这种上游依赖意味着，当 Google 调整 API 策略时，Banana Claude 必须快速响应。

3. 不适合纯服务器部署

Banana Claude 是一个 Claude Code 的交互式 CLI 工具，设计初衷是服务于开发者的本地工作流。没有 Web UI、没有 Docker 支持、不适合在无头服务器上运行。如果你的团队没有使用 Claude Code，这个工具的价值就大打折扣。

增长轨迹与行业意义

Banana Claude 的 GitHub 数据值得关注：704 颗 star、144 个 fork，这个比例（5:1）在工具类项目中属于偏高，说明项目的实际使用率和口碑都不错，而非靠标题党刷 star。topics 标签包括 claude-code-skill、content-creation、ai-art，清晰地定位在"AI 辅助创意工作流"这个细分赛道。

从更大的视角看，Banana Claude 体现了一个趋势：AI 工具正在从"独立的 API 调用"演化为"带有专业判断能力的智能助手"。五步 prompt 公式的本质，是把专业摄影、设计、影视领域的知识编码进 AI 的决策流程。当 Claude 识别出"产品摄影"场景并自动套用打光规则时，这已经不是在调用 API，而是在提供专业的创意服务。

技术规格速览

项目	值
语言	Python
核心依赖	Claude Code（插件）、Google Gemini API（免费 Key）
MCP 支持	是（@ycse/nanobanana-mcp）
最低 Python 版本	3.6+
最低 Node.js 版本	18+（MCP 模式）
容器化	❌ 不支持
Web UI	❌ CLI 工具
安装方式	插件市场 / install.sh 脚本
部署难度	简单（需有 Claude Code 环境）

---

本分析基于 GitHub 仓库 v1.4.1（2026-03-19），项目数据采集于 2026-06-18。 分析工具：PIFS 开源情报平台