@justin_666/square-couplets-master-skills 1.0.8 → 1.0.11

package/{constants.ts → dist/constants.js}

@@ -1,12 +1,11 @@
 // 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;
-
+    MAX_SIZE_KB: 500,
+    MAX_DIMENSION: 1920,
+    MAX_FILE_SIZE_MB: 10,
+    COMPRESSION_QUALITY: 0.85,
+    MIN_COMPRESSION_QUALITY: 0.1
+};
 // Base system prompt for generating Doufang prompts
 export const DOUFANG_SYSTEM_PROMPT = `
 You are a professional Chinese New Year couplet and calligraphy art designer.
@@ -69,9 +68,8 @@ Return a JSON object with the following structure:
   "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.
+export const getDoufangSystemPromptWithReference = () => {
+    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.
@@ -185,11 +183,9 @@ Return only a JSON object:
 }
 `;
 };
-
-
 // User input prompt template for reference image analysis
-export const getReferenceImageAnalysisPrompt = (userKeyword: string): string => {
-  return `User input keyword: 「${userKeyword}」
+export const getReferenceImageAnalysisPrompt = (userKeyword) => {
+    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.
 
@@ -224,17 +220,15 @@ The generated prompt MUST explicitly describe:
 
 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}」`;
+export const getSimpleUserInputPrompt = (userKeyword) => {
+    return `User input keyword: 「${userKeyword}」`;
 };
-
 // Image generation prompt enhancement when reference image is provided
-export const getImageGenerationPromptWithReference = (basePrompt: string): string => {
-  return `${basePrompt}
+export const getImageGenerationPromptWithReference = (basePrompt) => {
+    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/dist/services/geminiService.js

@@ -0,0 +1,196 @@
+import { GoogleGenAI, Type } from "@google/genai";
+import { DOUFANG_SYSTEM_PROMPT, getDoufangSystemPromptWithReference, getReferenceImageAnalysisPrompt, getSimpleUserInputPrompt, getImageGenerationPromptWithReference } from "../constants.js";
+import { processImageDataUrl } from "../utils/imageUtils.node.js";
+import { handleApiError } from "../utils/errorHandler.js";
+import { retryWithBackoff } from "../utils/retry.js";
+const getClient = (apiKey) => {
+    // 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, apiKey, referenceImageDataUrl, signal) => {
+    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 = [];
+            // 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) {
+            if (signal?.aborted) {
+                throw new Error('Request cancelled');
+            }
+            throw handleApiError(e, 'generateDoufangPrompt');
+        }
+    });
+};
+export const generateDoufangImage = async (prompt, apiKey, model = 'gemini-2.5-flash-image', imageSize = '1K', referenceImageDataUrl, signal) => {
+    return retryWithBackoff(async () => {
+        const ai = getClient(apiKey);
+        // Check if request was cancelled
+        if (signal?.aborted) {
+            throw new Error('Request cancelled');
+        }
+        let config = {};
+        // 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 = [];
+            // 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) {
+            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/dist/types.js

@@ -0,0 +1,8 @@
+export var GenerationStatus;
+(function (GenerationStatus) {
+    GenerationStatus["IDLE"] = "IDLE";
+    GenerationStatus["PROCESSING_PROMPT"] = "PROCESSING_PROMPT";
+    GenerationStatus["PROCESSING_IMAGE"] = "PROCESSING_IMAGE";
+    GenerationStatus["COMPLETED"] = "COMPLETED";
+    GenerationStatus["ERROR"] = "ERROR";
+})(GenerationStatus || (GenerationStatus = {}));

package/dist/utils/errorHandler.js

@@ -0,0 +1,62 @@
+/**
+ * Custom error class for application errors
+ */
+export class AppError extends Error {
+    constructor(message, code, userMessage, recoverable = false, originalError) {
+        super(message);
+        this.code = code;
+        this.userMessage = userMessage;
+        this.recoverable = recoverable;
+        this.originalError = originalError;
+        this.name = 'AppError';
+        Object.setPrototypeOf(this, AppError.prototype);
+    }
+}
+/**
+ * Handle API errors and convert them to AppError
+ */
+export const handleApiError = (error, context) => {
+    // Log error for debugging
+    console.error(`API Error${context ? ` in ${context}` : ''}:`, error);
+    // Extract error properties safely
+    const errorObj = error && typeof error === 'object' ? error : null;
+    const status = errorObj?.status;
+    const message = errorObj?.message || (error instanceof Error ? error.message : String(error));
+    // Handle 400 errors - Invalid Request
+    if (status === 400 || message?.includes('400') || message?.includes('INVALID_ARGUMENT')) {
+        if (message?.includes('image') || message?.includes('format') || message?.includes('mime')) {
+            return new AppError(message || 'Invalid image format', 'INVALID_IMAGE_FORMAT', '圖片格式不支援，請嘗試其他圖片（建議使用 JPG 或 PNG）', true, error);
+        }
+        return new AppError(message || 'Invalid request', 'INVALID_REQUEST', '請求格式不正確，請檢查設置', true, error);
+    }
+    // Handle 403 errors - Permission Denied
+    if (status === 403 || message?.includes('403') || message?.includes('Permission Denied')) {
+        if (message?.includes('Paid API Key') || message?.includes('billing')) {
+            return new AppError(message || 'Billing required', 'BILLING_REQUIRED', '此功能需要付費 API Key，請在設置中切換到免費模型或啟用付費帳戶', true, error);
+        }
+        return new AppError(message || 'Permission denied', 'PERMISSION_DENIED', 'API Key 無效或沒有權限，請檢查設置', true, error);
+    }
+    // Handle 429 errors - Rate Limit
+    if (status === 429 || message?.includes('429') || message?.includes('rate limit')) {
+        return new AppError(message || 'Rate limit exceeded', 'RATE_LIMIT', '請求過於頻繁，請稍後再試', true, error);
+    }
+    // Handle 500 errors - Server Error
+    if (status === 500 || status === 503 || message?.includes('overloaded')) {
+        return new AppError(message || 'Server error', 'SERVER_ERROR', '服務器暫時無法處理請求，請稍後再試', true, error);
+    }
+    // Handle network errors
+    if (message?.includes('network') || message?.includes('fetch')) {
+        return new AppError(message || 'Network error', 'NETWORK_ERROR', '網路連線錯誤，請檢查網路連線', true, error);
+    }
+    // Default error
+    return new AppError(message || 'An unexpected error occurred', 'UNKNOWN_ERROR', '發生未知錯誤，請稍後再試', false, error);
+};
+/**
+ * Get user-friendly error message
+ */
+export const getUserFriendlyErrorMessage = (error) => {
+    if (error instanceof AppError) {
+        return error.userMessage;
+    }
+    return error.message || '發生未知錯誤';
+};

package/dist/utils/imageUtils.node.js

@@ -0,0 +1,35 @@
+/**
+ * Node.js version of image utilities (no browser APIs)
+ * For CLI usage only
+ */
+/**
+ * Process image data URL to extract mime type and base64 data
+ */
+export function processImageDataUrl(dataUrl) {
+    try {
+        const matches = dataUrl.match(/^data:([^;]+);base64,(.+)$/);
+        if (!matches) {
+            console.warn('Invalid data URL format');
+            return null;
+        }
+        return {
+            mimeType: matches[1],
+            base64Data: matches[2]
+        };
+    }
+    catch (error) {
+        console.error('Error processing image data URL:', error);
+        return null;
+    }
+}
+/**
+ * Validate image file size (Node.js version - simplified)
+ * @param buffer - Image buffer
+ * @param maxSizeMB - Maximum file size in MB
+ */
+export function validateImageSize(buffer, maxSizeMB = 10) {
+    const sizeMB = buffer.length / (1024 * 1024);
+    if (sizeMB > maxSizeMB) {
+        throw new Error(`Image file too large: ${sizeMB.toFixed(2)}MB (max: ${maxSizeMB}MB)`);
+    }
+}

package/dist/utils/retry.js

@@ -0,0 +1,33 @@
+/**
+ * Retry a function with exponential backoff
+ * @param fn - The function to retry
+ * @param maxRetries - Maximum number of retries (default: 3)
+ * @param initialDelay - Initial delay in milliseconds (default: 1000)
+ * @returns Promise resolving to the function result
+ */
+export const retryWithBackoff = async (fn, maxRetries = 3, initialDelay = 1000) => {
+    let lastError;
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry on certain errors (4xx client errors except 429)
+            if (error && typeof error === 'object' && 'status' in error) {
+                const status = error.status;
+                if (status && status >= 400 && status < 500 && status !== 429) {
+                    throw error;
+                }
+            }
+            // If this is the last retry, throw the error
+            if (i === maxRetries - 1) {
+                throw error;
+            }
+            // Calculate delay with exponential backoff
+            const delay = initialDelay * Math.pow(2, i);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError || new Error('Max retries exceeded');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justin_666/square-couplets-master-skills",
-  "version": "1.0.8",
+  "version": "1.0.11",
   "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",
@@ -14,8 +14,9 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "build:cli": "tsc --project tsconfig.cli.json && node fix-imports.js",
     "preview": "vite preview",
-    "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));\""
+    "prepublishOnly": "npm run build:cli && 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",
@@ -45,10 +46,7 @@
   "files": [
     "bin/",
     "skills/",
-    "services/",
-    "utils/",
-    "constants.ts",
-    "types.ts",
+    "dist/",
     "README.md",
     "LICENSE",
     "package.json"
@@ -60,10 +58,10 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "dotenv": "^17.2.3"
+    "dotenv": "^17.2.3",
+    "@google/genai": "^1.37.0"
   },
   "devDependencies": {
-    "@google/genai": "^1.37.0",
     "@types/node": "^22.14.0",
     "@vitejs/plugin-react": "^5.0.0",
     "react": "^19.2.3",

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

@@ -167,22 +167,41 @@ async function main() {
       process.exit(1);
     }
 
-    // Dynamic import of service (support both .ts and .js)
+    // Dynamic import of service (prioritize compiled .js from dist/)
     let serviceModule;
-    try {
-      // Try .js first (for npm package)
-      serviceModule = await import(`file://${join(servicesPath, 'geminiService.js')}`);
-    } catch (e) {
+    const possibleServicePaths = [
+      // 1. Compiled JS in dist/ (npm package)
+      join(dirname(servicesPath), 'dist', 'services', 'geminiService.js'),
+      // 2. Compiled JS in services/ (if built locally)
+      join(servicesPath, 'geminiService.js'),
+      // 3. Source TS (development only)
+      join(servicesPath, 'geminiService.ts'),
+    ];
+    
+    let importError = null;
+    for (const servicePath of possibleServicePaths) {
       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);
+        if (existsSync(servicePath)) {
+          serviceModule = await import(`file://${servicePath}`);
+          break;
+        }
+      } catch (e) {
+        importError = e;
+        continue;
       }
     }
+    
+    if (!serviceModule) {
+      console.error('❌ Error: Cannot import service module');
+      console.error('   Tried paths:');
+      possibleServicePaths.forEach(p => console.error(`   - ${p}`));
+      if (importError) {
+        console.error('\n   Last error:', importError.message);
+      }
+      console.error('\n💡 This usually means the package was not properly built.');
+      console.error('   Please report this issue at: https://github.com/poirotw66/Square_Couplets_Master/issues');
+      process.exit(1);
+    }
     const { generateDoufangImage } = serviceModule;
 
     // Load reference image if provided

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

@@ -42,7 +42,7 @@ const __dirname = dirname(__filename);
 const skillDir = resolve(__dirname);
 const projectRoot = resolve(skillDir, '../..');
 
-// Try to find services directory
+// Try to find dist directory (compiled JS) or services directory (source TS)
 function findServicesPath() {
   // Get npm global prefix to find globally installed packages
   let globalPrefix = null;
@@ -62,29 +62,42 @@ function findServicesPath() {
     // Package not found via require.resolve, will try other paths
   }
   
+  // Build list of possible paths
+  // IMPORTANT: We're looking for dist/services (compiled) not services/ (source)
   const possiblePaths = [
-    // Global npm package (highest priority - most reliable for installed packages)
+    // Global npm package - dist directory (compiled JS)
     ...(globalPrefix ? [
-      join(globalPrefix, 'lib', 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
-      join(globalPrefix, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+      join(globalPrefix, 'lib', 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
+      join(globalPrefix, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
     ] : []),
-    // From resolved package root (if it has services)
-    ...(packageRoot ? [join(packageRoot, 'services')] : []),
-    // Local project root
-    join(projectRoot, 'services'),
-    // Local node_modules
-    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
-    // Current working directory
+    // From resolved package root - dist directory
+    ...(packageRoot ? [
+      join(packageRoot, 'dist', 'services'),
+      join(packageRoot, 'services'), // fallback to source
+    ] : []),
+    // Local project root - dist directory
+    join(projectRoot, 'dist', 'services'),
+    join(projectRoot, 'services'), // fallback to source
+    // Local node_modules - dist directory
+    join(projectRoot, 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
+    // Current working directory - dist directory
+    join(process.cwd(), 'dist', 'services'),
     join(process.cwd(), 'services'),
     // Current working directory node_modules
-    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'services'),
+    join(process.cwd(), 'node_modules', '@justin_666', 'square-couplets-master-skills', 'dist', 'services'),
   ];
 
-  // Debug: log all paths being checked (only in development)
+  // Debug: log all paths being checked (enable with DEBUG_DOUFANG=1)
   if (process.env.DEBUG_DOUFANG) {
     console.log('🔍 Checking paths for services directory:');
+    console.log(`   packageRoot: ${packageRoot || 'not found'}`);
+    console.log(`   globalPrefix: ${globalPrefix || 'not found'}`);
+    console.log(`   projectRoot: ${projectRoot}`);
+    console.log(`   cwd: ${process.cwd()}`);
+    console.log('\n   Trying paths:');
     for (const path of possiblePaths) {
-      console.log(`   - ${path} ${existsSync(path) ? '✅' : '❌'}`);
+      const exists = existsSync(path);
+      console.log(`   ${exists ? '✅' : '❌'} ${path}`);
     }
   }
   
@@ -92,7 +105,7 @@ function findServicesPath() {
     try {
       if (statSync(path).isDirectory()) {
         if (process.env.DEBUG_DOUFANG) {
-          console.log(`✅ Found services at: ${path}`);
+          console.log(`\n✅ Found services at: ${path}`);
         }
         return path;
       }
@@ -103,7 +116,7 @@ function findServicesPath() {
   
   // If not found, provide helpful error message
   if (process.env.DEBUG_DOUFANG) {
-    console.log('❌ Services directory not found in any of the checked paths');
+    console.log('\n❌ Services directory not found in any of the checked paths');
   }
   return null;
 }
@@ -146,34 +159,41 @@ async function main() {
       process.exit(1);
     }
 
-    // Dynamic import of service (support both .ts and .js)
+    // Dynamic import of service (prioritize compiled .js from dist/)
     let serviceModule;
-    try {
-      // Try .js first (for compiled npm package)
-      serviceModule = await import(`file://${join(servicesPath, 'geminiService.js')}`);
-    } catch (e) {
+    const possibleServicePaths = [
+      // 1. Compiled JS in dist/ (npm package)
+      join(dirname(servicesPath), 'dist', 'services', 'geminiService.js'),
+      // 2. Compiled JS in services/ (if built locally)
+      join(servicesPath, 'geminiService.js'),
+      // 3. Source TS (development only)
+      join(servicesPath, 'geminiService.ts'),
+    ];
+    
+    let importError = null;
+    for (const servicePath of possibleServicePaths) {
       try {
-        // Try .ts (for development or source packages)
-        // Node.js cannot directly import .ts files
-        console.error('❌ Error: Cannot import TypeScript service module');
-        console.error('   The package contains TypeScript source files (.ts) which cannot be directly executed');
-        console.error('');
-        console.error('💡 Solution: Use the CLI command instead (recommended):');
-        console.error(`   doufang-prompt "${keyword}"${referenceImagePath ? ` ${referenceImagePath}` : ''}`);
-        console.error('');
-        console.error('   Or if you need to use the script directly:');
-        console.error('   1. Install tsx: npm install -g tsx');
-        console.error(`   2. Run: tsx skills/generate-doufang-prompt/index.js "${keyword}"${referenceImagePath ? ` ${referenceImagePath}` : ''}`);
-        process.exit(1);
-      } catch (e2) {
-        console.error('❌ Error: Cannot import service module');
-        console.error('   Tried:', join(servicesPath, 'geminiService.js'));
-        console.error('   Tried:', join(servicesPath, 'geminiService.ts'));
-        console.error('   💡 Solution: Use the CLI command instead:');
-        console.error(`      doufang-prompt "${keyword}"${referenceImagePath ? ` ${referenceImagePath}` : ''}`);
-        process.exit(1);
+        if (existsSync(servicePath)) {
+          serviceModule = await import(`file://${servicePath}`);
+          break;
+        }
+      } catch (e) {
+        importError = e;
+        continue;
       }
     }
+    
+    if (!serviceModule) {
+      console.error('❌ Error: Cannot import service module');
+      console.error('   Tried paths:');
+      possibleServicePaths.forEach(p => console.error(`   - ${p}`));
+      if (importError) {
+        console.error('\n   Last error:', importError.message);
+      }
+      console.error('\n💡 This usually means the package was not properly built.');
+      console.error('   Please report this issue at: https://github.com/poirotw66/Square_Couplets_Master/issues');
+      process.exit(1);
+    }
     const { generateDoufangPrompt } = serviceModule;
 
     // Load reference image if provided

package/services/geminiService.ts

@@ -1,236 +0,0 @@
-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/types.ts

@@ -1,70 +0,0 @@
-export interface GenerationResult {
-  keyword: string;
-  generatedPrompt: string;
-  imageUrl?: string;
-  blessingPhrase?: string;
-}
-
-export interface LoadingState {
-  isGeneratingPrompt: boolean;
-  isGeneratingImage: boolean;
-}
-
-export enum GenerationStatus {
-  IDLE = 'IDLE',
-  PROCESSING_PROMPT = 'PROCESSING_PROMPT',
-  PROCESSING_IMAGE = 'PROCESSING_IMAGE',
-  COMPLETED = 'COMPLETED',
-  ERROR = 'ERROR'
-}
-
-// API Types
-export interface GeminiResponse {
-  text?: string;
-  candidates?: Array<{
-    content?: {
-      parts?: Array<{
-        text?: string;
-        inlineData?: {
-          mimeType: string;
-          data: string;
-        };
-      }>;
-    };
-  }>;
-}
-
-export interface ApiError {
-  status?: number;
-  message?: string;
-  code?: string;
-}
-
-// Settings Types
-export interface AppSettings {
-  apiKey: string;
-  imageModel: 'gemini-2.5-flash-image' | 'gemini-3-pro-image-preview';
-  imageSize: '1K' | '2K' | '4K';
-}
-
-// Result Types
-export interface GenerationResultData {
-  prompt: string;
-  blessingPhrase: string;
-  imageUrl: string;
-}
-
-// Gemini API Types
-export interface GeminiContentPart {
-  text?: string;
-  inlineData?: {
-    mimeType: string;
-    data: string;
-  };
-}
-
-// Error Types
-export type ApiErrorInput = 
-  | { status?: number; message?: string; code?: string }
-  | Error
-  | unknown;

package/utils/errorHandler.ts

@@ -1,123 +0,0 @@
-import type { ApiErrorInput } from "../types";
-
-/**
- * Custom error class for application errors
- */
-export class AppError extends Error {
-  constructor(
-    message: string,
-    public code: string,
-    public userMessage: string,
-    public recoverable: boolean = false,
-    public originalError?: unknown
-  ) {
-    super(message);
-    this.name = 'AppError';
-    Object.setPrototypeOf(this, AppError.prototype);
-  }
-}
-
-/**
- * Handle API errors and convert them to AppError
- */
-export const handleApiError = (error: ApiErrorInput, context?: string): AppError => {
-  // Log error for debugging
-  console.error(`API Error${context ? ` in ${context}` : ''}:`, error);
-
-  // Extract error properties safely
-  const errorObj = error && typeof error === 'object' ? error as { status?: number; message?: string; code?: string } : null;
-  const status = errorObj?.status;
-  const message = errorObj?.message || (error instanceof Error ? error.message : String(error));
-
-  // Handle 400 errors - Invalid Request
-  if (status === 400 || message?.includes('400') || message?.includes('INVALID_ARGUMENT')) {
-    if (message?.includes('image') || message?.includes('format') || message?.includes('mime')) {
-      return new AppError(
-        message || 'Invalid image format',
-        'INVALID_IMAGE_FORMAT',
-        '圖片格式不支援，請嘗試其他圖片（建議使用 JPG 或 PNG）',
-        true,
-        error
-      );
-    }
-    return new AppError(
-      message || 'Invalid request',
-      'INVALID_REQUEST',
-      '請求格式不正確，請檢查設置',
-      true,
-      error
-    );
-  }
-
-  // Handle 403 errors - Permission Denied
-  if (status === 403 || message?.includes('403') || message?.includes('Permission Denied')) {
-    if (message?.includes('Paid API Key') || message?.includes('billing')) {
-      return new AppError(
-        message || 'Billing required',
-        'BILLING_REQUIRED',
-        '此功能需要付費 API Key，請在設置中切換到免費模型或啟用付費帳戶',
-        true,
-        error
-      );
-    }
-    return new AppError(
-      message || 'Permission denied',
-      'PERMISSION_DENIED',
-      'API Key 無效或沒有權限，請檢查設置',
-      true,
-      error
-    );
-  }
-
-  // Handle 429 errors - Rate Limit
-  if (status === 429 || message?.includes('429') || message?.includes('rate limit')) {
-    return new AppError(
-      message || 'Rate limit exceeded',
-      'RATE_LIMIT',
-      '請求過於頻繁，請稍後再試',
-      true,
-      error
-    );
-  }
-
-  // Handle 500 errors - Server Error
-  if (status === 500 || status === 503 || message?.includes('overloaded')) {
-    return new AppError(
-      message || 'Server error',
-      'SERVER_ERROR',
-      '服務器暫時無法處理請求，請稍後再試',
-      true,
-      error
-    );
-  }
-
-  // Handle network errors
-  if (message?.includes('network') || message?.includes('fetch')) {
-    return new AppError(
-      message || 'Network error',
-      'NETWORK_ERROR',
-      '網路連線錯誤，請檢查網路連線',
-      true,
-      error
-    );
-  }
-
-  // Default error
-  return new AppError(
-    message || 'An unexpected error occurred',
-    'UNKNOWN_ERROR',
-    '發生未知錯誤，請稍後再試',
-    false,
-    error
-  );
-};
-
-/**
- * Get user-friendly error message
- */
-export const getUserFriendlyErrorMessage = (error: Error | AppError): string => {
-  if (error instanceof AppError) {
-    return error.userMessage;
-  }
-  return error.message || '發生未知錯誤';
-};

package/utils/imageUtils.ts

@@ -1,135 +0,0 @@
-import { IMAGE_CONSTANTS } from "../constants";
-
-/**
- * Process image data URL and extract mime type and base64 data
- * @param dataUrl - The data URL string
- * @returns Object with mimeType and base64Data, or null if invalid
- */
-export const processImageDataUrl = (dataUrl: string): { mimeType: string; base64Data: string } | null => {
-  const base64Match = dataUrl.match(/^data:([^;]+);base64,(.+)$/);
-  if (base64Match) {
-    return {
-      mimeType: base64Match[1],
-      base64Data: base64Match[2]
-    };
-  }
-  return null;
-};
-
-/**
- * Compress image file to reduce size while maintaining quality
- * @param file - The image file to compress
- * @param maxSizeKB - Maximum file size in KB (default: 500KB)
- * @param maxDimension - Maximum width or height in pixels (default: 1920)
- * @returns Promise resolving to compressed image data URL
- */
-export const compressImage = async (
-  file: File, 
-  maxSizeKB: number = IMAGE_CONSTANTS.MAX_SIZE_KB,
-  maxDimension: number = IMAGE_CONSTANTS.MAX_DIMENSION
-): Promise<string> => {
-  return new Promise((resolve, reject) => {
-    // Validate file type
-    if (!file.type.startsWith('image/')) {
-      reject(new Error('File is not an image'));
-      return;
-    }
-
-    const reader = new FileReader();
-    reader.onload = (e) => {
-      const img = new Image();
-      img.onload = () => {
-        const canvas = document.createElement('canvas');
-        let width = img.width;
-        let height = img.height;
-        
-        // Calculate new dimensions to fit within maxDimension
-        if (width > height && width > maxDimension) {
-          height = (height * maxDimension) / width;
-          width = maxDimension;
-        } else if (height > maxDimension) {
-          width = (width * maxDimension) / height;
-          height = maxDimension;
-        }
-        
-        canvas.width = width;
-        canvas.height = height;
-        const ctx = canvas.getContext('2d');
-        
-        if (!ctx) {
-          reject(new Error('Could not get canvas context'));
-          return;
-        }
-        
-        // Draw image with new dimensions
-        ctx.drawImage(img, 0, 0, width, height);
-        
-        // Convert to blob with quality compression
-        canvas.toBlob(
-          (blob) => {
-            if (!blob) {
-              reject(new Error('Failed to compress image'));
-              return;
-            }
-            
-            // Check if compressed size is acceptable
-            const sizeKB = blob.size / 1024;
-            if (sizeKB <= maxSizeKB) {
-              // Size is acceptable, convert to data URL
-              const reader = new FileReader();
-              reader.onload = () => resolve(reader.result as string);
-              reader.onerror = () => reject(new Error('Failed to read compressed image'));
-              reader.readAsDataURL(blob);
-            } else {
-              // Still too large, try lower quality
-              const quality = Math.max(
-                IMAGE_CONSTANTS.MIN_COMPRESSION_QUALITY, 
-                IMAGE_CONSTANTS.COMPRESSION_QUALITY * (maxSizeKB / sizeKB)
-              );
-              canvas.toBlob(
-                (compressedBlob) => {
-                  if (!compressedBlob) {
-                    reject(new Error('Failed to compress image'));
-                    return;
-                  }
-                  const finalReader = new FileReader();
-                  finalReader.onload = () => resolve(finalReader.result as string);
-                  finalReader.onerror = () => reject(new Error('Failed to read compressed image'));
-                  finalReader.readAsDataURL(compressedBlob);
-                },
-                'image/jpeg',
-                quality
-              );
-            }
-          },
-          'image/jpeg',
-          IMAGE_CONSTANTS.COMPRESSION_QUALITY // Initial quality
-        );
-      };
-      img.onerror = () => reject(new Error('Failed to load image'));
-      img.src = e.target?.result as string;
-    };
-    reader.onerror = () => reject(new Error('Failed to read file'));
-    reader.readAsDataURL(file);
-  });
-};
-
-/**
- * Validate image file
- * @param file - The file to validate
- * @param maxSizeMB - Maximum file size in MB (default: 10MB)
- * @returns Error message if invalid, null if valid
- */
-export const validateImageFile = (file: File, maxSizeMB: number = IMAGE_CONSTANTS.MAX_FILE_SIZE_MB): string | null => {
-  // Validate file type
-  if (!file.type.startsWith('image/')) {
-    return 'Please upload an image file (JPG, PNG, etc.)';
-  }
-
-  // Validate file size
-  if (file.size > maxSizeMB * 1024 * 1024) {
-    return `Image file is too large. Maximum size is ${maxSizeMB}MB.`;
-  }
-
-  return null;
-};

package/utils/retry.ts

@@ -1,41 +0,0 @@
-/**
- * Retry a function with exponential backoff
- * @param fn - The function to retry
- * @param maxRetries - Maximum number of retries (default: 3)
- * @param initialDelay - Initial delay in milliseconds (default: 1000)
- * @returns Promise resolving to the function result
- */
-export const retryWithBackoff = async <T>(
-  fn: () => Promise<T>,
-  maxRetries: number = 3,
-  initialDelay: number = 1000
-): Promise<T> => {
-  let lastError: Error | unknown;
-  
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-      
-      // Don't retry on certain errors (4xx client errors except 429)
-      if (error && typeof error === 'object' && 'status' in error) {
-        const status = (error as { status?: number }).status;
-        if (status && status >= 400 && status < 500 && status !== 429) {
-          throw error;
-        }
-      }
-      
-      // If this is the last retry, throw the error
-      if (i === maxRetries - 1) {
-        throw error;
-      }
-      
-      // Calculate delay with exponential backoff
-      const delay = initialDelay * Math.pow(2, i);
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-  
-  throw lastError || new Error('Max retries exceeded');
-};