ai-engineering-init 1.1.0

package/.codex/skills/banana-image/README.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Banana Image Logo" width="280">
+</p>
+
+<h1 align="center">Banana Image</h1>
+
+<p align="center">
+  <strong>AI-Powered Image Generation Tool for Claude Code</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#models">Models</a> •
+  <a href="#examples">Examples</a>
+</p>
+
+---
+
+## Features
+
+- **Dual Model Support** - Flash (fast) and Pro (high-quality 4K)
+- **Flexible Aspect Ratios** - 1:1, 16:9, 9:16, 4:3, 2:3, 21:9, and more
+- **Image Editing** - Modify existing images with text prompts
+- **Batch Generation** - Generate up to 4 variants at once
+- **Proxy Support** - Works behind corporate firewalls
+- **Claude Code Integration** - Seamless skill integration
+
+## Installation
+
+### 1. Set API Key
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+```
+
+### 2. Install Dependencies
+
+```bash
+cd ~/.claude/skills/banana-image/scripts
+npm install
+```
+
+## Usage
+
+### Quick Start
+
+```bash
+# Fast generation (Flash model)
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "A cute shiba inu in the park" -m flash
+
+# 4K high-quality (Pro model)
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "Professional product photo: iPhone case" -m pro -r 4K -a 4:5
+```
+
+### CLI Options
+
+| Option               | Description                     | Default          |
+| -------------------- | ------------------------------- | ---------------- |
+| `-p, --prompt`       | Image description (required)    | -                |
+| `-m, --model`        | Model: `flash` or `pro`         | `pro`            |
+| `-a, --aspect-ratio` | Ratio: 1:1, 16:9, 9:16, etc.    | `1:1`            |
+| `-r, --resolution`   | Resolution: 1K, 2K, 4K          | Pro=4K, Flash=1K |
+| `-o, --output`       | Output directory                | `./images`       |
+| `-n, --negative`     | Negative prompt                 | -                |
+| `-i, --input`        | Input image (edit mode)         | -                |
+| `-c, --count`        | Number of images (1-4)          | `1`              |
+| `-g, --grounding`    | Enable Google Search (Pro only) | `false`          |
+
+## Models
+
+| Model     | Speed  | Max Resolution | Best For                                |
+| --------- | ------ | -------------- | --------------------------------------- |
+| **Flash** | 2-5s   | 1024px         | Drafts, iterations, prototypes          |
+| **Pro**   | 10-40s | 4K             | Final delivery, marketing, professional |
+
+## Examples
+
+### Image Generation
+
+```bash
+# 16:9 landscape poster
+npx tsx banana_image_exec.ts -p "Sunset over mountains" -m pro -r 4K -a 16:9
+
+# Portrait for social media
+npx tsx banana_image_exec.ts -p "Product showcase" -m pro -a 9:16
+```
+
+### Image Editing
+
+```bash
+# Edit existing image
+npx tsx banana_image_exec.ts -p "Change background to beach sunset" -i ./photo.png
+```
+
+### Batch Generation
+
+```bash
+# Generate 4 variants
+npx tsx banana_image_exec.ts -p "Logo design concept" -m pro -c 4
+```
+
+## Output
+
+```json
+{
+  "success": true,
+  "images": [
+    {
+      "path": "./images/banana_pro_2025-01-01T12-00-00_abc123.png",
+      "model": "gemini-3-pro-image-preview",
+      "prompt": "Your prompt"
+    }
+  ],
+  "metadata": {
+    "model": "gemini-3-pro-image-preview",
+    "aspectRatio": "16:9",
+    "resolution": "4K",
+    "duration": 15234
+  }
+}
+```
+
+## Aspect Ratio Guide
+
+| Use Case            | Ratio | Keywords                   |
+| ------------------- | ----- | -------------------------- |
+| Social media square | 1:1   | Instagram, profile         |
+| Landscape banner    | 16:9  | YouTube, desktop wallpaper |
+| Portrait story      | 9:16  | Stories, mobile wallpaper  |
+| Product photo       | 4:5   | E-commerce, catalog        |
+| Movie poster        | 2:3   | Poster, print              |
+| Ultra-wide          | 21:9  | Banner, header             |
+
+## Requirements
+
+- Node.js 18+
+- Gemini API Key
+- Network access (proxy supported)
+
+## License
+
+MIT

package/.codex/skills/banana-image/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: banana-image
+description: |
+  【触发条件】当用户要求生成图片、创建海报、制作缩略图、编辑图片时使用。
+  关键词：生成图片、/image、产品图、海报、缩略图、4K、高清。
+  【核心产出】高质量 AI 生成图片（最高 4K 分辨率）。
+  【不触发】纯文本任务、代码生成、不涉及图片的设计讨论。
+  【先问什么】若缺少：图片描述、分辨率偏好、宽高比，先提问补齐。
+---
+
+# Banana Image - AI 图片生成
+
+基于 Gemini API 的独立图片生成技能，支持 4K 输出、双模型选择、图片编辑。
+
+## 环境要求
+
+```bash
+# 设置 API Key（必需）
+export GEMINI_API_KEY="your-api-key"
+
+# 安装依赖（首次使用）
+cd .claude/skills/banana-image/scripts && npm install
+```
+
+## 快速命令
+
+```bash
+# 快速生成（Flash 模型）
+npx tsx .claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "可爱的柴犬在公园玩耍" -m flash
+
+# 4K 高质量生成（Pro 模型）
+npx tsx .claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "专业产品照片：iPhone 手机壳" -m pro -r 4K -a 4:5
+```
+
+## 模型选择
+
+| 模型      | 速度 | 分辨率  | 适用场景                     |
+| --------- | ---- | ------- | ---------------------------- |
+| **Flash** | 2-3s | ≤1024px | 快速草图、迭代、原型         |
+| **Pro**   | 5-8s | ≤4K     | 最终交付、营销素材、专业作品 |
+
+**自动选择规则**：
+
+- 包含 "快速"、"草图"、"draft" → Flash
+- 包含 "4K"、"专业"、"高质量" → Pro（默认）
+
+## 参数说明
+
+```bash
+npx tsx banana_image_exec.ts --help
+
+Options:
+  --prompt, -p <text>      图片描述（必需）
+  --model, -m <type>       模型选择: flash | pro (默认: pro)
+  --aspect-ratio, -a <r>   宽高比: 1:1, 16:9, 9:16, 4:3, 3:2, 21:9 等
+  --resolution, -r <res>   分辨率: 1K, 2K, 4K (默认: Pro=4K, Flash=1K)
+  --negative, -n <text>    排除内容描述
+  --output, -o <dir>       输出目录 (默认: ./images)
+  --grounding, -g          启用 Google Search 锚定 (仅 Pro)
+  --input, -i <path>       输入图片路径（编辑模式）
+  --system, -s <text>      系统指令
+  --count, -c <num>        生成数量 (1-4)
+```
+
+## 工作流
+
+### 1. 简单生成
+
+```bash
+npx tsx .claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "A cute shiba inu playing in the park" \
+  -m pro
+```
+
+### 2. 带参数生成
+
+```bash
+# 16:9 横版海报，启用 Google 搜索锚定
+npx tsx .claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "2024年科技大会宣传海报" \
+  -m pro -r 4K -a 16:9 -g
+```
+
+### 3. 图片编辑
+
+```bash
+# 修改现有图片
+npx tsx .claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "将背景改为黄昏海滩" \
+  -i /path/to/original.png
+```
+
+### 4. 批量生成
+
+```bash
+# 生成多张变体
+npx tsx .claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "产品照片：无线耳机" \
+  -m pro -c 4
+```
+
+## 输出格式
+
+脚本输出 JSON 格式结果：
+
+```json
+{
+  "success": true,
+  "images": [
+    {
+      "path": "./images/banana_pro_2024-01-01T12-00-00_abc123.png",
+      "model": "gemini-3-pro-image-preview",
+      "prompt": "可爱的柴犬"
+    }
+  ],
+  "metadata": {
+    "model": "gemini-3-pro-image-preview",
+    "aspectRatio": "1:1",
+    "resolution": "4K",
+    "duration": 5234
+  }
+}
+```
+
+## 宽高比映射
+
+| 用途         | 宽高比 | 关键词                        |
+| ------------ | ------ | ----------------------------- |
+| 社交媒体方图 | 1:1    | "方形"、"Instagram"           |
+| 横版海报     | 16:9   | "横版"、"YouTube"、"桌面壁纸" |
+| 竖版海报     | 9:16   | "竖版"、"手机壁纸"、"Story"   |
+| 产品图       | 4:5    | "产品"、"电商"                |
+| 电影海报     | 2:3    | "海报"、"电影"                |
+| 超宽屏       | 21:9   | "超宽"、"Banner"              |
+
+## 模板系统
+
+读取预定义模板生成图片：
+
+```bash
+# 列出可用模板
+python .claude/skills/banana-image/scripts/apply_template.py list
+
+# 应用产品图模板
+python .claude/skills/banana-image/scripts/apply_template.py apply product \
+  -v '{"product": "wireless earbuds"}'
+```
+
+模板输出可直接传递给 `banana_image_exec.ts`。
+
+## 错误处理
+
+| 错误                    | 原因           | 解决方案                      |
+| ----------------------- | -------------- | ----------------------------- |
+| GEMINI_API_KEY not set  | 未设置 API Key | `export GEMINI_API_KEY="..."` |
+| Content filtered        | 内容安全过滤   | 调整描述，避免敏感词          |
+| Invalid aspect ratio    | 不支持的宽高比 | 使用支持的宽高比              |
+| Image generation failed | API 调用失败   | 检查网络和 API 配额           |
+
+## 参考文档
+
+- [高级用法](references/advanced-usage.md) - 批量生成、图片编辑、参数优化

package/.codex/skills/banana-image/references/advanced-usage.md

@@ -0,0 +1,189 @@
+# 高级用法参考
+
+## 批量生成工作流
+
+### 1. 准备 prompt 列表
+
+**纯文本格式** (`prompts.txt`):
+
+```
+可爱的柴犬在公园里玩耍
+专业产品照片：iPhone 手机壳
+科幻风格的城市夜景
+```
+
+**CSV 格式** (`prompts.csv`):
+
+```csv
+prompt,aspect_ratio,model
+可爱的柴犬,1:1,flash
+专业产品照片,4:5,pro
+科幻城市,16:9,pro
+```
+
+### 2. 转换为 JSON
+
+```bash
+python ~/.claude/skills/banana-image/scripts/batch_prep.py prompts.txt
+```
+
+输出：
+
+```json
+{
+  "source": "prompts.txt",
+  "count": 3,
+  "prompts": [
+    { "id": 1, "prompt": "可爱的柴犬在公园里玩耍" },
+    { "id": 2, "prompt": "专业产品照片：iPhone 手机壳" },
+    { "id": 3, "prompt": "科幻风格的城市夜景" }
+  ]
+}
+```
+
+### 3. Claude 批量生成
+
+Claude 读取 JSON 后逐个调用 `banana_image_exec.ts`：
+
+```bash
+# 对每个 prompt 执行
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "可爱的柴犬在公园里玩耍" \
+  -m pro
+```
+
+## 模板系统
+
+### 列出可用模板
+
+```bash
+python ~/.claude/skills/banana-image/scripts/apply_template.py list
+```
+
+### 应用模板
+
+```bash
+python ~/.claude/skills/banana-image/scripts/apply_template.py apply product \
+  -v '{"product": "sleek wireless earbuds"}'
+```
+
+输出：
+
+```json
+{
+  "prompt": "Create a professional, high-end product photography shot of sleek wireless earbuds...",
+  "model_tier": "pro",
+  "resolution": "4k",
+  "aspect_ratio": "4:5",
+  "enable_grounding": true
+}
+```
+
+然后使用输出参数调用 `banana_image_exec.ts`：
+
+```bash
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "Create a professional, high-end product photography shot of sleek wireless earbuds..." \
+  -m pro -r 4K -a 4:5 -g
+```
+
+## 图片编辑模式
+
+### 编辑现有图片
+
+```bash
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "Make the background a sunset beach scene" \
+  -i /path/to/original.png
+```
+
+### 风格迁移
+
+```bash
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "Transform this photo into a Studio Ghibli anime style" \
+  -i /path/to/photo.jpg \
+  -m pro
+```
+
+## 参数优化技巧
+
+### 提高质量
+
+1. 使用 Pro 模型：`-m pro`
+2. 使用 4K 分辨率：`-r 4K`
+3. 启用 Google 搜索锚定：`-g`
+4. 详细的提示词描述
+
+### 加快速度
+
+1. 使用 Flash 模型：`-m flash`
+2. 降低分辨率：`-r 1K`
+3. 简化提示词
+
+### Negative Prompt 示例
+
+```bash
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "Professional portrait photo of a business person" \
+  -n "blurry, low quality, distorted, watermark, text, cartoon" \
+  -m pro
+```
+
+## 输出目录管理
+
+默认输出目录：`~/.claude/banana-image-output/`
+
+自定义输出目录：
+
+```bash
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "产品图" \
+  -o /path/to/custom/output
+```
+
+## 常见问题
+
+### Q: 生成失败，提示安全过滤？
+
+尝试：
+
+1. 使用更中性的描述
+2. 避免敏感词汇
+3. 使用 `--negative` 排除不当内容
+
+### Q: 图片质量不够？
+
+1. 使用 Pro 模型：`-m pro`
+2. 提高分辨率：`-r 4K`
+3. 优化提示词，添加更多细节描述
+
+### Q: 如何生成多张变体？
+
+```bash
+npx tsx ~/.claude/skills/banana-image/scripts/banana_image_exec.ts \
+  -p "产品照片" \
+  -c 4
+```
+
+### Q: 如何查看已生成的图片？
+
+```bash
+ls -la ~/.claude/banana-image-output/
+```
+
+## 环境变量
+
+| 变量             | 说明            | 必需 |
+| ---------------- | --------------- | ---- |
+| `GEMINI_API_KEY` | Gemini API 密钥 | 是   |
+
+设置方式：
+
+```bash
+# 临时设置
+export GEMINI_API_KEY="your-api-key"
+
+# 永久设置（添加到 ~/.zshrc 或 ~/.bashrc）
+echo 'export GEMINI_API_KEY="your-api-key"' >> ~/.zshrc
+```

package/.codex/skills/banana-image/scripts/apply_template.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+模板应用脚本
+读取模板 JSON 并填充占位符，输出完整的生成参数
+"""
+
+import sys
+import json
+import argparse
+import re
+from pathlib import Path
+
+
+TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
+
+
+def list_templates() -> list[dict]:
+    """列出所有可用模板"""
+    templates = []
+    for f in TEMPLATES_DIR.glob("*.json"):
+        try:
+            with open(f, "r", encoding="utf-8") as file:
+                data = json.load(file)
+                templates.append(
+                    {
+                        "file": f.name,
+                        "name": data.get("name", f.stem),
+                        "description": data.get("description", ""),
+                    }
+                )
+        except Exception:
+            continue
+    return templates
+
+
+def load_template(name: str) -> dict:
+    """加载指定模板"""
+    # 尝试直接文件名
+    template_path = TEMPLATES_DIR / f"{name}.json"
+    if not template_path.exists():
+        # 尝试匹配名称
+        for f in TEMPLATES_DIR.glob("*.json"):
+            with open(f, "r", encoding="utf-8") as file:
+                data = json.load(file)
+                if data.get("name") == name:
+                    return data
+        raise FileNotFoundError(f"模板不存在: {name}")
+
+    with open(template_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def apply_template(template: dict, values: dict) -> dict:
+    """应用模板，填充占位符"""
+    prompt = template["prompt_template"]
+
+    # 替换占位符
+    for key, value in values.items():
+        prompt = prompt.replace(f"{{{{{key}}}}}", value)
+
+    # 检查未填充的占位符
+    missing = re.findall(r"\{\{(\w+)\}\}", prompt)
+    if missing:
+        placeholders = template.get("placeholders", {})
+        required = [m for m in missing if not placeholders.get(m, {}).get("optional")]
+        if required:
+            raise ValueError(f"缺少必需的占位符: {', '.join(required)}")
+        # 移除可选占位符
+        for m in missing:
+            prompt = prompt.replace(f"{{{{{m}}}}}", "")
+
+    # 构建结果
+    result = {"prompt": prompt.strip(), **template.get("defaults", {})}
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="应用模板生成图片参数")
+    subparsers = parser.add_subparsers(dest="command", help="子命令")
+
+    # list 子命令
+    subparsers.add_parser("list", help="列出所有模板")
+
+    # apply 子命令
+    apply_parser = subparsers.add_parser("apply", help="应用模板")
+    apply_parser.add_argument("template", help="模板名称")
+    apply_parser.add_argument(
+        "--values",
+        "-v",
+        type=str,
+        help='JSON 格式的占位符值，如: {"product": "coffee maker"}',
+    )
+    apply_parser.add_argument("--output", "-o", help="输出文件路径")
+
+    args = parser.parse_args()
+
+    if args.command == "list":
+        templates = list_templates()
+        print(json.dumps(templates, ensure_ascii=False, indent=2))
+
+    elif args.command == "apply":
+        try:
+            template = load_template(args.template)
+            values = json.loads(args.values) if args.values else {}
+            result = apply_template(template, values)
+
+            output = json.dumps(result, ensure_ascii=False, indent=2)
+
+            if args.output:
+                with open(args.output, "w", encoding="utf-8") as f:
+                    f.write(output)
+                print(f"已保存到: {args.output}")
+            else:
+                print(output)
+        except Exception as e:
+            print(json.dumps({"error": str(e)}))
+            sys.exit(1)
+
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()