@justin_666/square-couplets-master-skills 1.0.3 → 1.0.4

package/README.md

@@ -167,6 +167,13 @@ doufang init --ai claude
 
 初始化後，在 Cursor / Windsurf / Antigravity 中使用 slash command：
 
+**在 Cursor 中（自動註冊）：**
+- 執行 `doufang init --ai cursor` 後，`/doufang` 命令會自動註冊
+- 輸入 `/` 會看到 `/doufang` 選項
+- 選擇後輸入請求，例如："Generate a prompt for wealth theme"
+- Cursor 會自動使用 CLI 工具執行，無需手動編寫代碼
+
+**在 Windsurf / Antigravity 中：**
 ```
 /doufang Generate a prompt for wealth theme
 /doufang Create a 2K image using Gemini 3 Pro
@@ -175,8 +182,9 @@ doufang init --ai claude
 
 ### CLI 工具命令
 
-安裝後，您還可以使用 `doufang-skills` 命令：
+安裝後，您可以使用多個 CLI 命令：
 
+**管理 Skills：**
 ```bash
 # 列出所有可用的 skills
 doufang-skills list
@@ -191,6 +199,25 @@ doufang-skills path generate-doufang-image
 doufang-skills help
 ```
 
+**執行 Skills（Agent 可直接調用）：**
+```bash
+# 生成 prompt
+doufang-prompt "財富"
+doufang-prompt "健康" images/reference.png
+
+# 生成圖片
+doufang-image "A diamond-shaped Doufang..." gemini-3-pro-image-preview 2K
+doufang-image "..." gemini-2.5-flash-image 1K images/ref.png output/my-doufang.png
+
+# 優化 prompt
+doufang-optimize "A diamond-shaped Doufang with wide white margins..."
+```
+
+**Agent 使用方式：**
+Agent 可以直接執行這些 CLI 命令來生成圖片，無需手動編寫代碼。例如：
+- Agent 執行：`doufang-prompt "財富"` → 獲得 prompt
+- Agent 執行：`doufang-image "<prompt>" gemini-3-pro-image-preview 2K` → 生成圖片
+
 ### 本地安裝
 
 ```bash

package/bin/doufang-image.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * CLI command for generate-doufang-image skill
+ * Usage: doufang-image <prompt> [model] [size] [reference-image] [output-path]
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { spawn } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '..');
+
+// Path to the skill script
+const skillScript = join(packageRoot, 'skills', 'generate-doufang-image', 'index.js');
+
+// Forward all arguments to the skill script
+const args = process.argv.slice(2);
+
+const child = spawn('node', [skillScript, ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd()
+});
+
+child.on('error', (error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/bin/doufang-init.js

@@ -106,10 +106,89 @@ Skills are located in the \`skills/\` directory.
   writeFileSync(cursorRulesPath, cursorRules);
   console.log(`   ✅ Created ${cursorRulesPath}`);
   
+  // Create .cursor/rules directory for slash command
+  const cursorRulesDir = join(projectPath, '.cursor', 'rules');
+  if (!existsSync(cursorRulesDir)) {
+    mkdirSync(cursorRulesDir, { recursive: true });
+  }
+  
+  // Create doufang.mdc rule file for slash command
+  const doufangRulePath = join(cursorRulesDir, 'doufang.mdc');
+  const doufangRule = `---
+description: Generate Chinese New Year Doufang artwork using Doufang Skills. Use /doufang command to generate prompts, images, or optimize prompts.
+globs: 
+---
+
+# Doufang Skills - Slash Command Handler
+
+You are a Doufang assistant. When the user uses the \`/doufang\` command or asks about Doufang functionality, follow these guidelines:
+
+## Available CLI Commands
+
+1. **Generate Prompt**: \`doufang-prompt <keyword> [reference-image]\`
+   - Generates a professional Doufang artwork prompt based on a keyword
+   - Example: \`doufang-prompt "財富"\`
+   - Example with reference: \`doufang-prompt "健康" images/reference.png\`
+
+2. **Generate Image**: \`doufang-image <prompt> [model] [size] [reference-image] [output-path]\`
+   - Generates actual Doufang artwork images using Gemini API
+   - Models: \`gemini-2.5-flash-image\` (fast, 1K only) or \`gemini-3-pro-image-preview\` (high quality, 1K/2K/4K)
+   - Sizes: \`1K\` (default), \`2K\`, \`4K\` (Pro model only)
+   - Example: \`doufang-image "A diamond-shaped Doufang..." gemini-3-pro-image-preview 2K\`
+
+3. **Optimize Prompt**: \`doufang-optimize <prompt>\`
+   - Optimizes prompts to reduce white margins and improve composition
+   - Example: \`doufang-optimize "A prompt with wide margins..."\`
+
+## Execution Guidelines
+
+- **Direct CLI Execution**: When user requests Doufang functionality, directly execute the appropriate CLI command using terminal, do NOT create .js files
+- **Read API Key**: Automatically read GEMINI_API_KEY from .env or .env.local file
+- **Ask for Details**: If user doesn't provide required parameters (like keyword or prompt), ask for clarification
+- **Error Handling**: If API key is missing, guide user to set GEMINI_API_KEY in .env file
+- **Output Format**: For prompt generation, output JSON format. For image generation, save to output/ directory and provide file path
+
+## Common Workflows
+
+### Generate Image from Keyword
+1. Generate prompt: \`doufang-prompt "財富"\`
+2. Extract imagePrompt from JSON output
+3. Generate image: \`doufang-image "<imagePrompt>" gemini-3-pro-image-preview 2K\`
+
+### Generate Image with Reference
+1. Generate prompt with reference: \`doufang-prompt "健康" images/reference.png\`
+2. Extract imagePrompt from JSON output
+3. Generate image: \`doufang-image "<imagePrompt>" gemini-3-pro-image-preview 2K images/reference.png\`
+
+### Optimize and Generate
+1. Generate prompt: \`doufang-prompt "財富"\`
+2. Optimize prompt: \`doufang-optimize "<imagePrompt>"\`
+3. Generate image with optimized prompt: \`doufang-image "<optimizedPrompt>" gemini-3-pro-image-preview 2K\`
+
+## Skills Location
+
+Skills are located in the \`skills/\` directory. Each skill has a \`SKILL.md\` file with detailed instructions.
+
+## API Key Setup
+
+The \`generate-doufang-image\` command requires GEMINI_API_KEY. Check for it in:
+- .env.local (priority)
+- .env
+- Environment variable GEMINI_API_KEY
+
+Get API key from: https://aistudio.google.com/
+`;
+  
+  writeFileSync(doufangRulePath, doufangRule);
+  console.log(`   ✅ Created ${doufangRulePath}`);
+  console.log(`   ✅ Slash command /doufang registered in Cursor`);
+  
   console.log('\n✨ Cursor setup complete!');
   console.log('\n📝 Usage:');
-  console.log('   Type "/doufang" in Cursor chat followed by your request');
-  console.log('   Example: /doufang Generate a prompt for wealth theme');
+  console.log('   1. Type "/" in Cursor chat to see available commands');
+  console.log('   2. Select "/doufang" from the dropdown');
+  console.log('   3. Enter your request, e.g.: "Generate a prompt for wealth theme"');
+  console.log('   4. Or directly type: /doufang Generate a prompt for wealth theme');
   
   return true;
 }

package/bin/doufang-optimize.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * CLI command for optimize-doufang-prompt skill
+ * Usage: doufang-optimize <prompt>
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { spawn } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '..');
+
+// Path to the skill script
+const skillScript = join(packageRoot, 'skills', 'optimize-doufang-prompt', 'index.js');
+
+// Forward all arguments to the skill script
+const args = process.argv.slice(2);
+
+const child = spawn('node', [skillScript, ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd()
+});
+
+child.on('error', (error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/bin/doufang-prompt.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * CLI command for generate-doufang-prompt skill
+ * Usage: doufang-prompt <keyword> [reference-image]
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { spawn } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = resolve(__dirname, '..');
+
+// Path to the skill script
+const skillScript = join(packageRoot, 'skills', 'generate-doufang-prompt', 'index.js');
+
+// Forward all arguments to the skill script
+const args = process.argv.slice(2);
+
+const child = spawn('node', [skillScript, ...args], {
+  stdio: 'inherit',
+  cwd: process.cwd()
+});
+
+child.on('error', (error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/constants.ts

@@ -0,0 +1,240 @@
+// Image Processing Constants
+export const IMAGE_CONSTANTS = {
+  MAX_SIZE_KB: 500,
+  MAX_DIMENSION: 1920,
+  MAX_FILE_SIZE_MB: 10,
+  COMPRESSION_QUALITY: 0.85,
+  MIN_COMPRESSION_QUALITY: 0.1
+} as const;
+
+// Base system prompt for generating Doufang prompts
+export const DOUFANG_SYSTEM_PROMPT = `
+You are a professional Chinese New Year couplet and calligraphy art designer.
+
+Your task is to generate a high-end, printable Chinese New Year "Doufang" (diamond-shaped) couplet artwork prompt based on ONE keyword provided by the user.
+
+Step 1: Understand the meaning and blessing intention of the keyword.
+- If the keyword is about wealth -> design a wealth-themed couplet.
+- If about health -> design a health & longevity themed couplet.
+- If about career -> design a success & promotion themed couplet.
+- If about peace -> design a safety & harmony themed couplet.
+- If about love -> design a relationship & harmony themed couplet.
+- If about study -> design wisdom & academic success themed couplet.
+- If about general luck -> design auspicious & good fortune themed couplet.
+
+Step 2: Decide the final 4-character Chinese blessing phrase automatically.
+- The phrase must be elegant, common in Chinese New Year usage, and culturally appropriate.
+- If the user input itself is suitable (e.g. "馬上發財", "平安喜樂"), you may use it directly.
+- Otherwise, transform or upgrade it into a proper 4-character blessing phrase.
+
+Step 3: Generate the artwork prompt with the following visual style:
+
+Artwork description:
+A diamond-shaped Chinese New Year "Doufang" couplet on antique gold-flecked red Xuan paper.
+
+Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the final 4-character blessing phrase: [INSERT PHRASE HERE].
+
+Around the calligraphy: symbolic elements that visually represent the user's keyword, painted in traditional Chinese ink painting style (for example: horse, dragon, pine tree, crane, gold ingots, clouds, mountains, sun, plum blossoms, etc).
+
+Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon.
+
+Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details.
+
+Color theme: deep Chinese red, gold, black ink, warm highlights.
+
+Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork.
+
+Composition: 
+The diamond-shaped Doufang fills the majority of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping).
+The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off.
+The Doufang should occupy 85-95% of the image area, maximizing visual impact.
+Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall.
+
+Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio.
+
+Framing requirements:
+- The entire diamond-shaped Doufang must be fully visible inside the image.
+- No part of the artwork is cut off, cropped, out of frame, or touching the image borders.
+- Minimal margins - the Doufang should fill most of the frame (85-95% of image area).
+
+Text requirements:
+- The Chinese characters must be clear, correct, readable.
+- No typo, no deformed text.
+- No modern elements, no western style, no watermark.
+
+OUTPUT FORMAT:
+Return a JSON object with the following structure:
+{
+  "blessingPhrase": "The 4 character phrase you chose",
+  "imagePrompt": "The full detailed English image generation prompt based on the instructions above."
+}
+`;
+
+export const getDoufangSystemPromptWithReference = (): string => {
+  return `You are a professional Chinese New Year Doufang (diamond-shaped couplet) designer and calligrapher.
+
+### CORE MISSION:
+Your task is to analyze a REFERENCE IMAGE and a KEYWORD to create a unique, high-end Chinese New Year Doufang. The reference image is your PRIMARY visual guide for style, subject category, and material language — but it must NEVER be copied.
+
+---
+
+### STEP 1: KEYWORD & BLESSING LOGIC
+Transform the user's keyword into a 4-character Chinese blessing phrase:
+- Wealth -> e.g., 招財進寶, 富貴吉祥
+- Health -> e.g., 龍馬精神, 延年益壽
+- Career/Success -> e.g., 大展宏圖, 步步高升
+- Peace/Harmony -> e.g., 平安喜樂, 歲歲平安
+- Love -> e.g., 永結同心, 花好月圓
+- Custom -> If the user provides a 4-character phrase, use it directly.
+
+---
+
+### STEP 2: REFERENCE IMAGE DNA EXTRACTION (CRITICAL)
+Analyze the reference image and extract the following "Visual DNA":
+1. **Primary Subject Category**: Identify the type of subject (e.g., cat, dragon, robot, girl), not the exact instance.
+2. **Artistic Style**: Is it 3D render, minimalist, oil painting, ink painting, cyberpunk, paper-cut, etc.
+3. **Material & Texture Language**: e.g., glossy plastic, brushed metal, rough impasto, rice paper fibers, silk, ceramic.
+4. **Color Language**: Identify the dominant colors beyond standard red/gold.
+5. **Shape Language & Design Grammar**: e.g., rounded cute proportions, sharp mechanical shapes, flowing ink strokes, geometric blocks.
+
+---
+
+### STEP 2.5: REFERENCE TRANSFORMATION RULE (EXTREMELY IMPORTANT)
+The reference image is **NOT** to be copied, replicated, traced, or minimally modified.
+
+- You MUST:
+  - Keep the same **artistic style, subject category, and material feeling**
+  - But **redesign the pose, composition, structure, and details**
+- You MUST:
+  - Change at least **3 major visual aspects** (for example: pose, camera angle, composition, costume/ornamentation, structure, surface details, silhouette, or proportion)
+- The final artwork must:
+  - Be **clearly inspired by** the reference image
+  - But **obviously a new original creation**, not a variant, not a replica
+- Think of it as:
+  > "Same species, same art director, but a completely new photoshoot."
+
+- You MUST absolutely avoid:
+  - Same pose
+  - Same composition
+  - Same framing
+  - Same silhouette
+  - Any form of visual overlay similarity
+
+- The generated image must not be visually alignable or overlayable with the reference image.
+
+---
+
+### STEP 3: ARTWORK SPECIFICATIONS (DOUFANG FORMAT)
+- **Shape**: A perfect diamond-shaped (rotated square) "Doufang".
+- **Background**: Traditional deep vermilion or "Wanshou" red Xuan paper, but infused with textures or visual language from the reference image.
+- **Calligraphy Layout**: The 4-character blessing MUST be arranged in a **balanced 2x2 square grid** at the center.
+- **Integration**: The subject inspired by the reference image should interact with the calligraphy (e.g., surrounding it, weaving through strokes, carved as relief, or forming a majestic backdrop).
+
+---
+
+### STEP 4: PROMPT CONSTRUCTION GUIDELINES
+Your generated "imagePrompt" must follow this logic:
+- **Style Fusion**: Do NOT just say "ink painting." Instead, say "Traditional Doufang reimagined in [Style from Reference Image]."
+- **Subject Redesign**: Describe the subject as "a reimagined, redesigned, and re-composed version inspired by the reference, not a copy".
+- **Subject Adaptation**: Always adapt the subject into an auspicious Chinese New Year version.
+- **Materiality**: Combine "red gold-flecked Xuan paper" with the material language from the reference (e.g., ceramic, metal, plastic, silk, oil paint).
+- **Lighting**: Use high-end studio lighting or museum-grade lighting to emphasize the diamond shape, material depth, and calligraphy relief.
+
+---
+
+### FINAL OUTPUT CONSTRAINTS:
+1. **Framing**:
+   - The entire diamond Doufang must be fully contained within the 1:1 frame.
+   - Minimal, elegant margins - just enough to prevent edge cropping (approximately 2-5% of frame width).
+   - The Doufang should fill most of the frame (85-95% of the image area).
+   - No cropping, no touching edges, no cut-off.
+2. **Text Quality**:
+   - Calligraphy must be clear, professional, and correctly written.
+   - No distorted strokes, no typos.
+3. **No Modern Junk**:
+   - No UI elements, no watermarks, no photography credits, no signatures.
+
+---
+
+Composition: 
+The diamond-shaped Doufang fills the majority of the 1:1 frame, centered with minimal elegant margins (just enough to prevent edge cropping, approximately 2-5% of frame width).
+The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off.
+The Doufang should occupy 85-95% of the image area, maximizing visual impact.
+Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall.
+
+Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio.
+
+Framing requirements:
+- The entire diamond-shaped Doufang must be fully visible inside the image.
+- No part of the artwork is cut off, cropped, out of frame, or touching the image borders.
+- Minimal margins - the Doufang should fill most of the frame (85-95% of image area).
+
+Text requirements:
+- The Chinese characters must be clear, correct, readable.
+- No typo, no deformed text.
+- No modern elements, no western style, no watermark.
+
+---
+
+### OUTPUT FORMAT (JSON ONLY):
+Return only a JSON object:
+{
+  "blessingPhrase": "The chosen 4-character phrase",
+  "analysis": "Briefly describe what you extracted from the reference image and how you transformed it",
+  "imagePrompt": "A highly detailed, around 200-word English prompt that blends the reference image DNA with the Doufang requirements. Focus on textures, lighting, redesigned subject, 2x2 text layout, and centering."
+}
+`;
+};
+
+
+// User input prompt template for reference image analysis
+export const getReferenceImageAnalysisPrompt = (userKeyword: string): string => {
+  return `User input keyword: 「${userKeyword}」
+
+CRITICAL INSTRUCTION: A reference image has been provided above. You MUST analyze this reference image in detail and generate a prompt that DIRECTLY USES the reference image's visual content, patterns, and style.
+
+STEP-BY-STEP ANALYSIS REQUIRED:
+1. FIRST, describe what you see in the reference image:
+   - What is the main subject or central figure? (e.g., samurai, warrior, character, object, etc.)
+   - What specific visual patterns, motifs, or decorative elements are present?
+   - What is the composition structure? How are elements arranged?
+   - What are the distinctive visual characteristics? (shapes, forms, graphic elements)
+   - What background elements or environmental details are visible?
+
+2. THEN, identify the artistic style:
+   - What is the artistic technique? (ink wash, brush painting, illustration style, etc.)
+   - What is the color palette? (specific colors, tones, contrast levels)
+   - What is the brushwork quality? (bold strokes, fine lines, texture, etc.)
+   - What is the visual mood? (dramatic, serene, energetic, etc.)
+   - What material/texture characteristics are visible?
+
+3. FINALLY, generate a prompt that:
+   - DIRECTLY incorporates the main subject or key visual elements from the reference image
+   - PRESERVES the exact visual patterns, motifs, and decorative elements visible in the reference
+   - MAINTAINS the same artistic style, brushwork, and technique
+   - USES the same color palette and visual mood
+   - ADAPTS these elements to the diamond-shaped Doufang format while keeping the reference image's visual identity
+   - BLENDS the user's keyword (${userKeyword}) with the reference image's visual content
+
+The generated prompt MUST explicitly describe:
+- The specific visual elements from the reference image to be included
+- How to recreate the reference image's patterns and motifs in the Doufang
+- The exact artistic style and technique to match the reference
+- The color palette and visual characteristics to preserve
+
+DO NOT create generic descriptions. Be SPECIFIC about what you see in the reference image and how to recreate it.`;
+};
+
+// Simple user input prompt without reference image
+export const getSimpleUserInputPrompt = (userKeyword: string): string => {
+  return `User input keyword: 「${userKeyword}」`;
+};
+
+// Image generation prompt enhancement when reference image is provided
+export const getImageGenerationPromptWithReference = (basePrompt: string): string => {
+  return `${basePrompt}
+
+IMPORTANT COMPOSITION NOTE: The diamond-shaped Doufang should fill 85-95% of the frame with minimal margins (2-5% of frame width). Avoid excessive white space or wide margins. Maximize the visual impact by making the Doufang artwork occupy most of the image area.
+
+Note: The reference image provided above should be used as a visual style guide. Follow the style, color palette, and artistic approach described in the prompt, which was generated based on analysis of this reference image.`;
+};

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@justin_666/square-couplets-master-skills",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Claude Agent Skills for generating Chinese New Year Doufang (diamond-shaped couplet) artwork using Google Gemini AI",
   "type": "module",
   "main": "bin/doufang-skills.js",
   "bin": {
     "doufang-skills": "bin/doufang-skills.js",
-    "doufang": "bin/doufang-init.js"
+    "doufang": "bin/doufang-init.js",
+    "doufang-prompt": "bin/doufang-prompt.js",
+    "doufang-image": "bin/doufang-image.js",
+    "doufang-optimize": "bin/doufang-optimize.js"
   },
   "scripts": {
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
-    "prepublishOnly": "node -e \"const fs = require('fs'); fs.chmodSync('bin/doufang-skills.js', 0o755); fs.chmodSync('bin/doufang-init.js', 0o755);\""
+    "prepublishOnly": "node -e \"const fs = require('fs'); ['doufang-skills.js', 'doufang-init.js', 'doufang-prompt.js', 'doufang-image.js', 'doufang-optimize.js'].forEach(f => fs.chmodSync('bin/' + f, 0o755));\""
   },
   "keywords": [
     "claude",
@@ -42,6 +45,10 @@
   "files": [
     "bin/",
     "skills/",
+    "services/",
+    "utils/",
+    "constants.ts",
+    "types.ts",
     "README.md",
     "LICENSE",
     "package.json"