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

package/services/geminiService.ts

@@ -0,0 +1,236 @@
+import { GoogleGenAI, Type } from "@google/genai";
+import { 
+  DOUFANG_SYSTEM_PROMPT,
+  getDoufangSystemPromptWithReference,
+  getReferenceImageAnalysisPrompt,
+  getSimpleUserInputPrompt,
+  getImageGenerationPromptWithReference
+} from "../constants";
+import { processImageDataUrl } from "../utils/imageUtils";
+import { handleApiError } from "../utils/errorHandler";
+import { retryWithBackoff } from "../utils/retry";
+import type { GeminiContentPart } from "../types";
+
+const getClient = (apiKey?: string) => {
+  // Use user-provided key if available, otherwise fallback to env var
+  const userKey = apiKey?.trim();
+  const envKey = process.env.API_KEY?.trim();
+  const key = userKey || envKey;
+  
+  if (!key) {
+    throw new Error("API Key is missing. Please click the Settings icon to configure your Gemini API Key.");
+  }
+  
+  // Basic validation: API keys should be non-empty strings
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error("Invalid API Key format. Please check your API Key configuration.");
+  }
+  
+  return new GoogleGenAI({ apiKey: key });
+};
+
+export const generateDoufangPrompt = async (
+  userKeyword: string, 
+  apiKey?: string, 
+  referenceImageDataUrl?: string | null,
+  signal?: AbortSignal
+): Promise<{ blessingPhrase: string; imagePrompt: string }> => {
+  return retryWithBackoff(async () => {
+    const ai = getClient(apiKey);
+    
+    try {
+      // Check if request was cancelled
+      if (signal?.aborted) {
+        throw new Error('Request cancelled');
+      }
+
+      // Prepare content parts
+      const parts: GeminiContentPart[] = [];
+    
+    // Add reference image if provided - image should come first
+    if (referenceImageDataUrl) {
+      const imageData = processImageDataUrl(referenceImageDataUrl);
+      if (imageData) {
+        parts.push({
+          inlineData: {
+            mimeType: imageData.mimeType,
+            data: imageData.base64Data
+          }
+        });
+      } else {
+        // Fallback: try to use as-is (may fail, but attempt anyway)
+        console.warn('Reference image format may be incorrect, attempting to use as-is');
+        parts.push({
+          inlineData: {
+            mimeType: 'image/jpeg', // Default to JPEG
+            data: referenceImageDataUrl.replace(/^data:image\/[^;]+;base64,/, '')
+          }
+        });
+      }
+      
+      // Add text instruction with reference image context
+      parts.push({ 
+        text: getReferenceImageAnalysisPrompt(userKeyword)
+      });
+    } else {
+      // No reference image, use simple text
+      parts.push({ text: getSimpleUserInputPrompt(userKeyword) });
+    }
+    
+    // Get system instruction based on whether reference image is provided
+    const systemInstruction = referenceImageDataUrl 
+      ? getDoufangSystemPromptWithReference()
+      : DOUFANG_SYSTEM_PROMPT;
+    
+    const response = await ai.models.generateContent({
+      model: 'gemini-3-flash-preview',
+      contents: {
+        parts: parts
+      },
+      config: {
+        systemInstruction: systemInstruction,
+        responseMimeType: "application/json",
+        responseSchema: {
+          type: Type.OBJECT,
+          properties: {
+            blessingPhrase: { type: Type.STRING },
+            imagePrompt: { type: Type.STRING }
+          },
+          required: ["blessingPhrase", "imagePrompt"]
+        }
+      }
+    });
+
+    const text = response.text;
+    if (!text) {
+      throw new Error("No response from Gemini");
+    }
+
+      // Check if request was cancelled before parsing
+      if (signal?.aborted) {
+        throw new Error('Request cancelled');
+      }
+
+      return JSON.parse(text);
+    } catch (e: unknown) {
+      if (signal?.aborted) {
+        throw new Error('Request cancelled');
+      }
+      throw handleApiError(e, 'generateDoufangPrompt');
+    }
+  });
+};
+
+export const generateDoufangImage = async (
+  prompt: string, 
+  apiKey?: string, 
+  model: string = 'gemini-2.5-flash-image', 
+  imageSize: '1K' | '2K' | '4K' = '1K', 
+  referenceImageDataUrl?: string | null,
+  signal?: AbortSignal
+): Promise<string> => {
+  return retryWithBackoff(async () => {
+    const ai = getClient(apiKey);
+
+    // Check if request was cancelled
+    if (signal?.aborted) {
+      throw new Error('Request cancelled');
+    }
+
+    let config: Record<string, unknown> = {};
+  
+    // Different models have different support for imageConfig
+    // Flash model does NOT support imageConfig parameter - it will cause 400 errors
+    // Only Pro model supports imageConfig with custom sizes
+    if (model === 'gemini-3-pro-image-preview') {
+      // Pro model supports all sizes (1K, 2K, 4K)
+      config = {
+        imageConfig: {
+          aspectRatio: "1:1",
+          imageSize: imageSize
+        }
+      };
+    }
+    // For Flash model: Do NOT set imageConfig at all
+    // Flash model only supports default 1K (1024x1024) resolution
+    // Setting imageConfig will cause 400 INVALID_ARGUMENT error
+
+    try {
+      // Prepare content parts
+      const parts: GeminiContentPart[] = [];
+    
+    // Add reference image if provided - image should come first
+    // Note: The prompt already contains style guidance from the reference image
+    // (generated in generateDoufangPrompt), so we just need to provide the image
+    // as additional visual reference for the image generation model
+    if (referenceImageDataUrl) {
+      const imageData = processImageDataUrl(referenceImageDataUrl);
+      if (imageData) {
+        parts.push({
+          inlineData: {
+            mimeType: imageData.mimeType,
+            data: imageData.base64Data
+          }
+        });
+      } else {
+        // Fallback: try to use as-is (may fail, but attempt anyway)
+        console.warn('Reference image format may be incorrect, attempting to use as-is');
+        parts.push({
+          inlineData: {
+            mimeType: 'image/jpeg', // Default to JPEG
+            data: referenceImageDataUrl.replace(/^data:image\/[^;]+;base64,/, '')
+          }
+        });
+      }
+      
+      // Add prompt with reference image context
+      // The prompt already includes style guidance, so we just reinforce it
+      parts.push({ 
+        text: getImageGenerationPromptWithReference(prompt)
+      });
+    } else {
+      // No reference image, use original prompt
+      parts.push({ text: prompt });
+    }
+
+    const response = await ai.models.generateContent({
+      model: model,
+      contents: {
+        parts: parts
+      },
+      config: Object.keys(config).length > 0 ? config : undefined
+    });
+
+      // Check if request was cancelled before processing response
+      if (signal?.aborted) {
+        throw new Error('Request cancelled');
+      }
+
+      // Extract image
+      for (const part of response.candidates?.[0]?.content?.parts || []) {
+        if (part.inlineData) {
+          return `data:${part.inlineData.mimeType};base64,${part.inlineData.data}`;
+        }
+      }
+
+      throw new Error("No image generated in the response.");
+    } catch (e: unknown) {
+      if (signal?.aborted) {
+        throw new Error('Request cancelled');
+      }
+      
+      const error = handleApiError(e, 'generateDoufangImage');
+      
+      // Add specific context for image size errors
+      if (error.code === 'INVALID_REQUEST') {
+        if (model === 'gemini-2.5-flash-image') {
+          error.userMessage = 'Flash 模型不支援自訂圖片大小設定，僅支援預設 1K (1024×1024) 解析度。如需更高解析度，請使用 Pro 模型。';
+        } else if (imageSize === '4K') {
+          error.userMessage = '4K 解析度可能不被此模型或您的 API 方案支援，請嘗試 2K 或 1K。';
+        }
+      }
+      
+      throw error;
+    }
+  });
+};

package/skills/README.md

@@ -23,6 +23,37 @@ doufang-skills show generate-doufang-prompt
 doufang-skills path generate-doufang-image
 ```
 
+### 使用 CLI 命令執行 Skills
+
+安裝後，您可以直接使用 CLI 命令執行 skills：
+
+```bash
+# 生成 prompt
+doufang-prompt "財富"
+doufang-prompt "健康" images/reference.png
+
+# 生成圖片
+doufang-image "A diamond-shaped Doufang..." gemini-3-pro-image-preview 2K
+doufang-image "..." gemini-3-pro-image-preview 2K images/ref.png output/my-doufang.png
+
+# 優化 prompt
+doufang-optimize "A diamond-shaped Doufang with wide white margins..."
+```
+
+### 直接執行 Skill 腳本
+
+您也可以直接執行 skill 腳本：
+
+```bash
+# 從專案根目錄
+node skills/generate-doufang-prompt/index.js "財富"
+node skills/generate-doufang-image/index.js "..." gemini-3-pro-image-preview 2K
+node skills/optimize-doufang-prompt/index.js "..."
+
+# 從 npm 包（如果已安裝）
+node node_modules/@justin_666/square-couplets-master-skills/skills/generate-doufang-prompt/index.js "財富"
+```
+
 ### 方式 2：從 GitHub 克隆
 
 ```bash
@@ -68,12 +99,20 @@ npm install @justin_666/square-couplets-master-skills
    ```
 
 4. **使用 Slash Command**：
-   在 Cursor / Windsurf / Antigravity 的聊天中輸入：
+   
+   **在 Cursor 中**：
+   - 輸入 `/` 會自動顯示 `/doufang` 選項（已自動註冊）
+   - 選擇 `/doufang` 後輸入您的請求
+   - 或直接輸入：`/doufang Generate a prompt for wealth theme`
+   
+   **在 Windsurf / Antigravity 中**：
    ```
    /doufang Generate a prompt for wealth theme
    /doufang Create a 2K image using Gemini 3 Pro
    /doufang Optimize this prompt to reduce white space
    ```
+   
+   **注意**：Cursor 會自動識別 `/doufang` 命令並使用 CLI 工具執行，無需手動編寫代碼。
 
 ### 手動設置
 

package/skills/generate-doufang-image/index.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+/**
+ * Executable script for generate-doufang-image skill
+ * Can be called directly by agents or users
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
+import { config } from 'dotenv';
+
+// Resolve project root and service path
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const skillDir = resolve(__dirname);
+const projectRoot = resolve(skillDir, '../..');
+
+// Try to find services directory
+function findServicesPath() {
+  const possiblePaths = [
+    join(projectRoot, 'services'),
+    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+    join(process.cwd(), 'services'),
+    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      if (statSync(path).isDirectory()) {
+        return path;
+      }
+    } catch (e) {
+      // Path doesn't exist, try next
+    }
+  }
+  return null;
+}
+
+// Load environment variables
+const envLocalPath = join(projectRoot, '.env.local');
+const envPath = join(projectRoot, '.env');
+
+if (existsSync(envLocalPath)) {
+  config({ path: envLocalPath });
+} else if (existsSync(envPath)) {
+  config({ path: envPath });
+} else {
+  config();
+}
+
+async function main() {
+  try {
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+    const prompt = args[0];
+    const model = args[1] || 'gemini-2.5-flash-image';
+    const imageSize = args[2] || '1K';
+    const referenceImagePath = args[3]; // Optional reference image path
+    const outputPath = args[4]; // Optional output path
+    
+    if (!prompt) {
+      console.error('❌ Error: Prompt is required');
+      console.log('\nUsage:');
+      console.log('  node skills/generate-doufang-image/index.js <prompt> [model] [size] [reference-image] [output-path]');
+      console.log('\nParameters:');
+      console.log('  prompt           - Image generation prompt (required)');
+      console.log('  model            - Model to use: gemini-2.5-flash-image (default) or gemini-3-pro-image-preview');
+      console.log('  size             - Image size: 1K (default), 2K, or 4K (Pro model only)');
+      console.log('  reference-image  - Optional reference image path');
+      console.log('  output-path      - Optional output file path (default: output/doufang-{timestamp}.png)');
+      console.log('\nExample:');
+      console.log('  node skills/generate-doufang-image/index.js "A diamond-shaped Doufang..."');
+      console.log('  node skills/generate-doufang-image/index.js "..." gemini-3-pro-image-preview 2K');
+      console.log('  node skills/generate-doufang-image/index.js "..." gemini-3-pro-image-preview 2K images/ref.png output/my-doufang.png');
+      process.exit(1);
+    }
+
+    // Validate image size
+    if (!['1K', '2K', '4K'].includes(imageSize)) {
+      console.error('❌ Error: Invalid image size. Must be 1K, 2K, or 4K');
+      process.exit(1);
+    }
+
+    // Validate model and size combination
+    if (model === 'gemini-2.5-flash-image' && imageSize !== '1K') {
+      console.error('❌ Error: Flash model only supports 1K resolution');
+      console.log('💡 Use Pro model (gemini-3-pro-image-preview) for 2K/4K');
+      process.exit(1);
+    }
+
+    // Get API key
+    const apiKey = process.env.GEMINI_API_KEY || process.env.API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+    
+    if (!apiKey) {
+      console.error('❌ Error: API Key is missing');
+      console.log('💡 Set GEMINI_API_KEY in .env file or environment variable');
+      process.exit(1);
+    }
+
+    // Try to import service function
+    const servicesPath = findServicesPath();
+    if (!servicesPath) {
+      console.error('❌ Error: Cannot find services directory');
+      console.log('💡 Make sure you are running from the project root or have installed the package');
+      process.exit(1);
+    }
+
+    // Dynamic import of service (support both .ts and .js)
+    let serviceModule;
+    try {
+      // Try .js first (for npm package)
+      serviceModule = await import(`file://${join(servicesPath, 'geminiService.js')}`);
+    } catch (e) {
+      try {
+        // Try .ts (for development)
+        serviceModule = await import(`file://${join(servicesPath, 'geminiService.ts')}`);
+      } catch (e2) {
+        console.error('❌ Error: Cannot import service module');
+        console.error('   Tried:', join(servicesPath, 'geminiService.js'));
+        console.error('   Tried:', join(servicesPath, 'geminiService.ts'));
+        process.exit(1);
+      }
+    }
+    const { generateDoufangImage } = serviceModule;
+
+    // Load reference image if provided
+    let referenceImageDataUrl = null;
+    if (referenceImagePath) {
+      const fullPath = resolve(process.cwd(), referenceImagePath);
+      if (!existsSync(fullPath)) {
+        console.error(`❌ Error: Reference image not found: ${fullPath}`);
+        process.exit(1);
+      }
+      
+      const imageBuffer = readFileSync(fullPath);
+      const base64 = imageBuffer.toString('base64');
+      const ext = referenceImagePath.split('.').pop()?.toLowerCase();
+      const mimeType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : 'image/png';
+      referenceImageDataUrl = `data:${mimeType};base64,${base64}`;
+    }
+
+    // Generate image
+    console.log(`🖼️  Generating image...`);
+    console.log(`    Model: ${model}`);
+    console.log(`    Size: ${imageSize}`);
+    if (referenceImagePath) {
+      console.log(`    Reference: ${referenceImagePath}`);
+    }
+    console.log('    This may take a while, please wait...\n');
+    
+    const imageDataUrl = await generateDoufangImage(
+      prompt,
+      apiKey,
+      model,
+      imageSize,
+      referenceImageDataUrl
+    );
+    
+    // Extract base64 data
+    const base64Data = imageDataUrl.replace(/^data:image\/\w+;base64,/, '');
+    const buffer = Buffer.from(base64Data, 'base64');
+    
+    // Determine output path
+    let finalOutputPath = outputPath;
+    if (!finalOutputPath) {
+      const outputDir = join(process.cwd(), 'output');
+      if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+      }
+      const timestamp = Date.now();
+      finalOutputPath = join(outputDir, `doufang-${timestamp}.png`);
+    } else {
+      finalOutputPath = resolve(process.cwd(), finalOutputPath);
+      // Ensure output directory exists
+      const outputDir = dirname(finalOutputPath);
+      if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+      }
+    }
+    
+    // Save image
+    writeFileSync(finalOutputPath, buffer);
+    
+    console.log('✅ Image generated successfully!');
+    console.log(`📁 Saved to: ${finalOutputPath}`);
+    console.log(`📊 File size: ${(buffer.length / 1024 / 1024).toFixed(2)} MB`);
+    
+    // Also output data URL for programmatic use
+    console.log('\n📋 Image data URL (for programmatic use):');
+    console.log(imageDataUrl.substring(0, 100) + '...');
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/skills/generate-doufang-prompt/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * Executable script for generate-doufang-prompt skill
+ * Can be called directly by agents or users
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { config } from 'dotenv';
+
+// Resolve project root and service path
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const skillDir = resolve(__dirname);
+const projectRoot = resolve(skillDir, '../..');
+
+// Try to find services directory
+function findServicesPath() {
+  const possiblePaths = [
+    join(projectRoot, 'services'),
+    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+    join(process.cwd(), 'services'),
+    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      if (statSync(path).isDirectory()) {
+        return path;
+      }
+    } catch (e) {
+      // Path doesn't exist, try next
+    }
+  }
+  return null;
+}
+
+// Load environment variables
+const envLocalPath = join(projectRoot, '.env.local');
+const envPath = join(projectRoot, '.env');
+
+if (existsSync(envLocalPath)) {
+  config({ path: envLocalPath });
+} else if (existsSync(envPath)) {
+  config({ path: envPath });
+} else {
+  // Try current working directory
+  config();
+}
+
+async function main() {
+  try {
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+    const keyword = args[0];
+    const referenceImagePath = args[1]; // Optional reference image path
+    
+    if (!keyword) {
+      console.error('❌ Error: Keyword is required');
+      console.log('\nUsage:');
+      console.log('  node skills/generate-doufang-prompt/index.js <keyword> [reference-image-path]');
+      console.log('\nExample:');
+      console.log('  node skills/generate-doufang-prompt/index.js "財富"');
+      console.log('  node skills/generate-doufang-prompt/index.js "健康" images/reference.png');
+      process.exit(1);
+    }
+
+    // Get API key
+    const apiKey = process.env.GEMINI_API_KEY || process.env.API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+    
+    if (!apiKey) {
+      console.error('❌ Error: API Key is missing');
+      console.log('💡 Set GEMINI_API_KEY in .env file or environment variable');
+      process.exit(1);
+    }
+
+    // Try to import service function
+    const servicesPath = findServicesPath();
+    if (!servicesPath) {
+      console.error('❌ Error: Cannot find services directory');
+      console.log('💡 Make sure you are running from the project root or have installed the package');
+      process.exit(1);
+    }
+
+    // Dynamic import of service (support both .ts and .js)
+    let serviceModule;
+    try {
+      // Try .js first (for npm package)
+      serviceModule = await import(`file://${join(servicesPath, 'geminiService.js')}`);
+    } catch (e) {
+      try {
+        // Try .ts (for development)
+        serviceModule = await import(`file://${join(servicesPath, 'geminiService.ts')}`);
+      } catch (e2) {
+        console.error('❌ Error: Cannot import service module');
+        console.error('   Tried:', join(servicesPath, 'geminiService.js'));
+        console.error('   Tried:', join(servicesPath, 'geminiService.ts'));
+        process.exit(1);
+      }
+    }
+    const { generateDoufangPrompt } = serviceModule;
+
+    // Load reference image if provided
+    let referenceImageDataUrl = null;
+    if (referenceImagePath) {
+      const fullPath = resolve(process.cwd(), referenceImagePath);
+      if (!existsSync(fullPath)) {
+        console.error(`❌ Error: Reference image not found: ${fullPath}`);
+        process.exit(1);
+      }
+      
+      const imageBuffer = readFileSync(fullPath);
+      const base64 = imageBuffer.toString('base64');
+      const ext = referenceImagePath.split('.').pop()?.toLowerCase();
+      const mimeType = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : 'image/png';
+      referenceImageDataUrl = `data:${mimeType};base64,${base64}`;
+    }
+
+    // Generate prompt
+    console.log(`📝 Generating prompt for keyword: "${keyword}"`);
+    if (referenceImagePath) {
+      console.log(`🖼️  Using reference image: ${referenceImagePath}`);
+    }
+    
+    const result = await generateDoufangPrompt(keyword, apiKey, referenceImageDataUrl);
+    
+    // Output as JSON
+    console.log(JSON.stringify(result, null, 2));
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();