generate-clues

Generate clue design images

Use the Gemini 3 Pro Image API to create clue design images, ensuring visual consistency of important items and environments throughout the video.

Prompt Best Practices

Before writing clue descriptions and generating prompts, please first read the docs/nano-banana.md section starting at line 365 of Prompting guide and strategies to learn the best practices for Gemini image generation.

Core Principles：

"Describe the scene, don't just list keywords. A narrative, descriptive paragraph will almost always produce a better, more coherent image than a list of disconnected words."

Clue Description Writing Guide

Prop type (prop)

When writing prop description , please follow thenarrative style：

✅ Recommended:

"A jade-green heirloom jade pendant, about the size of a thumb, with a warm, translucent jade texture. The surface is carved with an exquisite lotus pattern, the petals unfolding layer by layer, with a small lotus seed pod in the center. A red silk cord is attached to the jade pendant, tied in a traditional Chinese knot."

❌ Avoid:

"Jade pendant, green, lotus pattern, red cord"

Location type (location)

When writing environment description , also use the narrative style:

✅ Recommended:

"The century-old locust tree at the village entrance, its trunk so thick it takes three people to encircle it, its bark cracked and weathered. There is an obvious lightning-burn scar on the main trunk, winding down from the top. The canopy is dense, casting dappled tree shadows in summer."

❌ Avoid:

"Old locust tree, big, has lightning strike marks"

Key Points:

• Describe form, texture, and details in coherent paragraphs
• Include material, color, size, and features
• Highlight unique features that can be recognized in different scenes

Overview

Clues are important elements that need to remain consistent across multiple scenes, including:

• Prop type (prop): key items such as tokens, weapons, letters, jewelry, etc.
• Location type (location): iconic buildings, specific trees, important places, etc.

Workflow

1. Load project metadata

   • If no project name is specified, ask the user
   • From projects/{项目名}/project.json load project data
   • List importance='major' and those without clue_sheet clues

2. Generate clue designs

   • For each clue to be generated:
     • Select the corresponding prompt template based on the type (prop/location)
     • Run .claude/skills/generate-clues/scripts/generate_clue.py
     • Save to projects/{项目名}/clues/

3. Review checkpoint

   • Show each generated clue image
   • Ask the user whether to approve or regenerate
   • Allow adjusting the description

4. Update project metadata

   • Update the clue_sheet path in project.json
   • Sync project status

Command Format

# 生成所有待处理的线索
python .claude/skills/generate-clues/scripts/generate_clue.py <项目名> --all

# 生成指定线索
python .claude/skills/generate-clues/scripts/generate_clue.py <项目名> --clue "玉佩"

# 列出待生成的线索
python .claude/skills/generate-clues/scripts/generate_clue.py <项目名> --list

Prompt Templates

Prop type (prop)

一张专业的道具设计参考图，{项目 style}。

道具「[名称]」的多视角展示。[详细描述 - 叙事式段落]

三个视图水平排列在纯净浅灰背景上：左侧正面全视图、中间45度侧视图展示立体感、右侧关键细节特写。柔和均匀的摄影棚照明，高清质感，色彩准确。

Location type (location)

一张专业的场景设计参考图，{项目 style}。

标志性场景「[名称]」的视觉参考。[详细描述 - 叙事式段落]

主画面占据四分之三区域展示环境整体外观与氛围，右下角小图为细节特写。柔和自然光线。

API Usage

Use lib/gemini_client.py：

from lib.gemini_client import GeminiClient

client = GeminiClient()
image = client.generate_image(
    prompt=clue_prompt,
    aspect_ratio="16:9",
    output_path=f"projects/{项目名}/clues/{线索名}.png"
)

Quality Checklist

Prop type

Checklist before approving prop designs:

• The three views are clear and consistent
• Details match the description (color, material, size)
• Special markings or textures are clearly visible
• The overall style is consistent with the project

Environment Category

Checklist before approving environment designs:

• The overall composition matches the description
• Iconic features are prominent
• Lighting and atmosphere are appropriate
• Detail images are clearly distinguishable

Clue Management

Add New Clue

Add a clue in the Claude conversation:

请为项目添加一个新线索：
- 名称：玉佩
- 类型：prop
- 描述：一块翠绿色的祖传玉佩，约拇指大小，雕刻着莲花纹样，系着红色丝绳
- 重要程度：major

Or edit directly project.json：

{
  "clues": {
    "玉佩": {
      "type": "prop",
      "description": "一块翠绿色的祖传玉佩，约拇指大小，雕刻着莲花纹样，系着红色丝绳",
      "importance": "major",
      "clue_sheet": ""
    }
  }
}

Use clues in scenes

Add clues_in_scene fields to a scene in the script:

{
  "scene_id": "E1S3",
  "characters_in_scene": ["姜月茴"],
  "clues_in_scene": ["玉佩", "老槐树"],
  "visual": {
    "description": "姜月茴站在老槐树下，手中紧握着玉佩..."
  }
}

When generating storyboards, the clue's clue_sheet will automatically be passed to the API as reference images.