botrun-horse 2.29.2 → 2.30.0

package/botrun-c/.claude/skills//345/234/226/347/211/207/347/224/237/346/210/220/346/212/200/350/203/275/scripts/__tests__/utils.test.mjs

@@ -0,0 +1,139 @@
+// ============================================================================
+// utils.test.mjs - 工具函式單元測試
+// ============================================================================
+
+import { describe, it, expect } from 'vitest';
+import {
+  parseArgs,
+  buildFullPrompt,
+  validateParams,
+  generateSessionId,
+  generateFilename,
+} from '../utils.mjs';
+
+describe('utils.mjs', () => {
+  describe('parseArgs', () => {
+    it('should parse basic prompt', () => {
+      const result = parseArgs(['A cute cat']);
+      expect(result.prompt).toBe('A cute cat');
+      expect(result.aspectRatio).toBe('1:1');
+    });
+
+    it('should parse aspect ratio', () => {
+      const result = parseArgs(['prompt', '--aspect', '16:9']);
+      expect(result.aspectRatio).toBe('16:9');
+    });
+
+    it('should parse style', () => {
+      const result = parseArgs(['prompt', '--style', 'oil painting']);
+      expect(result.style).toBe('oil painting');
+    });
+
+    it('should parse session ID', () => {
+      const result = parseArgs(['prompt', '--session', 'abc-123']);
+      expect(result.session).toBe('abc-123');
+    });
+
+    it('should parse all options', () => {
+      const result = parseArgs([
+        'A mountain',
+        '--aspect', '16:9',
+        '--style', 'photorealistic',
+        '--negative', 'blur',
+        '--temperature', '1.5',
+        '--count', '2',
+        '--session', 'sess-123',
+      ]);
+
+      expect(result.prompt).toBe('A mountain');
+      expect(result.aspectRatio).toBe('16:9');
+      expect(result.style).toBe('photorealistic');
+      expect(result.negativePrompt).toBe('blur');
+      expect(result.temperature).toBe(1.5);
+      expect(result.count).toBe(2);
+      expect(result.session).toBe('sess-123');
+    });
+  });
+
+  describe('buildFullPrompt', () => {
+    it('should return base prompt when no options', () => {
+      const result = buildFullPrompt('A cat');
+      expect(result).toBe('A cat');
+    });
+
+    it('should prepend style', () => {
+      const result = buildFullPrompt('A cat', { style: 'anime' });
+      expect(result).toBe('anime style: A cat');
+    });
+
+    it('should append negative prompt', () => {
+      const result = buildFullPrompt('A cat', { negativePrompt: 'blur' });
+      expect(result).toBe('A cat. Avoid: blur');
+    });
+
+    it('should combine style and negative prompt', () => {
+      const result = buildFullPrompt('A cat', {
+        style: 'anime',
+        negativePrompt: 'blur',
+      });
+      expect(result).toBe('anime style: A cat. Avoid: blur');
+    });
+  });
+
+  describe('validateParams', () => {
+    it('should throw on empty prompt', () => {
+      expect(() => validateParams({ prompt: null })).toThrow('請提供圖片描述');
+    });
+
+    it('should throw on invalid temperature', () => {
+      expect(() => validateParams({ prompt: 'test', temperature: 3 })).toThrow();
+      expect(() => validateParams({ prompt: 'test', temperature: -1 })).toThrow();
+    });
+
+    it('should throw on invalid count', () => {
+      expect(() => validateParams({ prompt: 'test', count: 0 })).toThrow();
+      expect(() => validateParams({ prompt: 'test', count: 5 })).toThrow();
+    });
+
+    it('should pass valid params', () => {
+      expect(() => validateParams({
+        prompt: 'test',
+        temperature: 1,
+        count: 2,
+      })).not.toThrow();
+    });
+  });
+
+  describe('generateSessionId', () => {
+    it('should generate UUID format', () => {
+      const id = generateSessionId();
+      expect(id).toMatch(/^[a-f0-9-]{36}$/);
+    });
+
+    it('should generate unique IDs', () => {
+      const id1 = generateSessionId();
+      const id2 = generateSessionId();
+      expect(id1).not.toBe(id2);
+    });
+  });
+
+  describe('generateFilename', () => {
+    it('should include index', () => {
+      const filename = generateFilename(0);
+      expect(filename).toContain('-0.png');
+    });
+
+    it('should include timestamp', () => {
+      const before = Date.now();
+      const filename = generateFilename(0);
+      const after = Date.now();
+
+      const match = filename.match(/generated-(\d+)-/);
+      expect(match).not.toBeNull();
+
+      const timestamp = parseInt(match[1], 10);
+      expect(timestamp).toBeGreaterThanOrEqual(before);
+      expect(timestamp).toBeLessThanOrEqual(after);
+    });
+  });
+});

package/botrun-c/.claude/skills//345/234/226/347/211/207/347/224/237/346/210/220/346/212/200/350/203/275/scripts/constants.mjs

@@ -0,0 +1,40 @@
+// ============================================================================
+// constants.mjs - 圖片生成技能常數定義
+// 遵循 SOLID 原則：單一職責 - 只負責常數定義
+// ============================================================================
+
+// Vertex AI 配置
+export const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT || 'botrun-c';
+export const VERTEX_AI_LOCATION = 'global';
+export const GEMINI_MODEL = process.env.GEMINI_IMAGE_MODEL || 'gemini-3-pro-image-preview';
+
+// GCS 配置
+export const GCS_BUCKET = process.env.GCS_BUCKET || '';
+export const GCS_AVAILABLE = !!GCS_BUCKET;
+export const SIGNED_URL_EXPIRY_DAYS = 7;
+
+// Session 配置
+export const SESSION_TTL_MS = 30 * 60 * 1000; // 30 分鐘
+export const SESSION_DIR = process.env.SESSION_DIR || '/tmp/image-sessions';
+
+// 使用者配置
+export const USER_ID = process.env.USER_ID || 'anonymous';
+
+// 圖片生成預設值
+export const DEFAULT_ASPECT_RATIO = '1:1';
+export const DEFAULT_TEMPERATURE = 1.0;
+export const DEFAULT_IMAGE_COUNT = 1;
+export const DEFAULT_IMAGE_SIZE = '1K';
+export const DEFAULT_SAFETY_LEVEL = 'BLOCK_MEDIUM_AND_ABOVE';
+export const DEFAULT_PERSON_GENERATION = 'allow_adult';
+
+// 支援的長寬比
+export const SUPPORTED_ASPECT_RATIOS = ['1:1', '16:9', '9:16', '4:3', '3:4', '21:9', '9:21'];
+
+// 安全類別
+export const SAFETY_CATEGORIES = [
+  'HARM_CATEGORY_HATE_SPEECH',
+  'HARM_CATEGORY_HARASSMENT',
+  'HARM_CATEGORY_SEXUALLY_EXPLICIT',
+  'HARM_CATEGORY_DANGEROUS_CONTENT',
+];

package/botrun-c/.claude/skills//345/234/226/347/211/207/347/224/237/346/210/220/346/212/200/350/203/275/scripts/gcs-uploader.mjs

@@ -0,0 +1,195 @@
+// ============================================================================
+// gcs-uploader.mjs - GCS 圖片上傳器
+// 遵循 SOLID 原則：
+// - 單一職責：只負責 GCS 上傳操作
+// - 開放封閉：可擴展其他儲存後端
+// ============================================================================
+
+import { Storage } from '@google-cloud/storage';
+import {
+  GCS_BUCKET,
+  GCS_AVAILABLE,
+  SIGNED_URL_EXPIRY_DAYS,
+  USER_ID,
+} from './constants.mjs';
+import { log, generateFilename } from './utils.mjs';
+
+// ============================================================================
+// 初始化
+// ============================================================================
+
+let storage = null;
+
+/**
+ * 初始化 GCS 客戶端
+ * @returns {Storage|null}
+ */
+export function initializeStorage() {
+  if (storage) {
+    return storage;
+  }
+
+  if (!GCS_AVAILABLE) {
+    log('GCS_BUCKET 未設定，將使用 base64 輸出');
+    return null;
+  }
+
+  try {
+    storage = new Storage();
+    log('GCS 初始化成功:', GCS_BUCKET);
+    return storage;
+  } catch (error) {
+    log('GCS 初始化失敗:', error.message);
+    return null;
+  }
+}
+
+/**
+ * 檢查 GCS 是否可用
+ * @returns {boolean}
+ */
+export function isStorageAvailable() {
+  return GCS_AVAILABLE && storage !== null;
+}
+
+// ============================================================================
+// 上傳操作
+// ============================================================================
+
+/**
+ * 上傳結果
+ * @typedef {Object} UploadResult
+ * @property {boolean} success - 是否成功
+ * @property {string} imageUrl - 圖片 URL（Signed URL 或 base64）
+ * @property {string} [gcsUri] - GCS URI
+ * @property {string} filename - 檔案名稱
+ * @property {string} mimeType - MIME 類型
+ * @property {string} [expiresAt] - Signed URL 過期時間
+ * @property {string} [error] - 錯誤訊息
+ */
+
+/**
+ * 上傳圖片到 GCS
+ * @param {Object} params - 上傳參數
+ * @param {string} params.data - Base64 編碼的圖片資料
+ * @param {number} [params.index] - 圖片索引
+ * @param {Object} [params.metadata] - 額外的 metadata
+ * @returns {Promise<UploadResult>}
+ */
+export async function uploadImage(params) {
+  const { data, index = 0, metadata = {} } = params;
+
+  const filename = generateFilename(index);
+
+  // 如果 GCS 不可用，返回 base64
+  if (!isStorageAvailable()) {
+    return {
+      success: true,
+      imageUrl: `data:image/png;base64,${data}`,
+      filename,
+      mimeType: 'image/png',
+    };
+  }
+
+  try {
+    const gcsPath = `${USER_ID}/generated-images/${filename}`;
+    const bucket = storage.bucket(GCS_BUCKET);
+    const file = bucket.file(gcsPath);
+
+    // 上傳圖片（確保是 binary 而非 text）
+    await file.save(Buffer.from(data, 'base64'), {
+      contentType: 'image/png',
+      metadata: {
+        ...metadata,
+        generatedAt: new Date().toISOString(),
+      },
+    });
+
+    // 設定 customTime（用於 Lifecycle Policy）
+    try {
+      await file.setMetadata({ customTime: new Date().toISOString() });
+    } catch (e) {
+      // 非關鍵錯誤，忽略
+    }
+
+    // 生成 Signed URL
+    const signedUrlResult = await generateSignedUrl(file, gcsPath);
+
+    return {
+      success: true,
+      imageUrl: signedUrlResult.url,
+      gcsUri: `gs://${GCS_BUCKET}/${gcsPath}`,
+      filename,
+      mimeType: 'image/png',
+      expiresAt: signedUrlResult.expiresAt,
+    };
+  } catch (error) {
+    log('GCS 上傳失敗，回傳 base64:', error.message);
+
+    return {
+      success: true,
+      imageUrl: `data:image/png;base64,${data}`,
+      filename,
+      mimeType: 'image/png',
+      error: `GCS 上傳失敗: ${error.message}`,
+    };
+  }
+}
+
+/**
+ * 生成 Signed URL
+ * @param {File} file - GCS 檔案物件
+ * @param {string} gcsPath - GCS 路徑
+ * @returns {Promise<{url: string, expiresAt: string}>}
+ */
+async function generateSignedUrl(file, gcsPath) {
+  const expiresAt = new Date();
+  expiresAt.setDate(expiresAt.getDate() + SIGNED_URL_EXPIRY_DAYS);
+
+  try {
+    const [signedUrl] = await file.getSignedUrl({
+      version: 'v4',
+      action: 'read',
+      expires: expiresAt,
+    });
+
+    log(`圖片已上傳: ${gcsPath}`);
+
+    return {
+      url: signedUrl,
+      expiresAt: expiresAt.toISOString(),
+    };
+  } catch (signError) {
+    // Signed URL 失敗（可能是本地環境無權限）
+    log('Signed URL 生成失敗，使用公開 URL:', signError.message);
+
+    return {
+      url: `https://storage.googleapis.com/${GCS_BUCKET}/${gcsPath}`,
+      expiresAt: undefined,
+    };
+  }
+}
+
+/**
+ * 批次上傳多張圖片
+ * @param {Array<{data: string, mimeType: string}>} images - 圖片陣列
+ * @param {Object} [metadata] - 共用的 metadata
+ * @returns {Promise<UploadResult[]>}
+ */
+export async function uploadImages(images, metadata = {}) {
+  const results = [];
+
+  for (let i = 0; i < images.length; i++) {
+    const result = await uploadImage({
+      data: images[i].data,
+      index: i,
+      metadata,
+    });
+    results.push(result);
+  }
+
+  return results;
+}
+
+// 初始化
+initializeStorage();

package/botrun-c/.claude/skills//345/234/226/347/211/207/347/224/237/346/210/220/346/212/200/350/203/275/scripts/gemini-image-client.mjs

@@ -0,0 +1,307 @@
+// ============================================================================
+// gemini-image-client.mjs - Gemini 3 Pro Image 客戶端
+// 遵循 SOLID 原則：
+// - 單一職責：只負責與 Gemini API 互動
+// - 依賴反轉：依賴抽象的 session manager
+// ============================================================================
+
+import { GoogleGenAI, Modality } from '@google/genai';
+import {
+  GOOGLE_CLOUD_PROJECT,
+  VERTEX_AI_LOCATION,
+  GEMINI_MODEL,
+  DEFAULT_TEMPERATURE,
+  DEFAULT_IMAGE_SIZE,
+  DEFAULT_SAFETY_LEVEL,
+  DEFAULT_PERSON_GENERATION,
+  SAFETY_CATEGORIES,
+} from './constants.mjs';
+import { log, buildFullPrompt } from './utils.mjs';
+import {
+  loadSession,
+  createSession,
+  updateSessionHistory,
+  getSessionHistory,
+} from './image-session-manager.mjs';
+
+// ============================================================================
+// 客戶端初始化
+// ============================================================================
+
+let genaiClient = null;
+
+/**
+ * 初始化 Gemini 客戶端
+ * @returns {GoogleGenAI|null}
+ */
+export function initializeClient() {
+  if (genaiClient) {
+    return genaiClient;
+  }
+
+  try {
+    genaiClient = new GoogleGenAI({
+      vertexai: true,
+      project: GOOGLE_CLOUD_PROJECT,
+      location: VERTEX_AI_LOCATION,
+    });
+    log('Vertex AI 初始化成功');
+    return genaiClient;
+  } catch (error) {
+    log('Vertex AI 初始化失敗:', error.message);
+    return null;
+  }
+}
+
+/**
+ * 取得客戶端實例
+ * @returns {GoogleGenAI}
+ * @throws {Error} 如果客戶端未初始化
+ */
+export function getClient() {
+  if (!genaiClient) {
+    initializeClient();
+  }
+
+  if (!genaiClient) {
+    throw new Error('Vertex AI 未初始化，請檢查 Google Cloud 認證');
+  }
+
+  return genaiClient;
+}
+
+// ============================================================================
+// 圖片生成
+// ============================================================================
+
+/**
+ * 生成圖片結果
+ * @typedef {Object} GenerateImageResult
+ * @property {Array<{data: string, mimeType: string}>} images - 生成的圖片陣列
+ * @property {string} textResponse - 模型的文字回應
+ * @property {string} sessionId - Session ID（用於後續迭代）
+ * @property {Object} modelResponse - 完整的模型回應（含 Thought Signature）
+ */
+
+/**
+ * 建立安全設定
+ * @param {string} safetyLevel - 安全等級
+ * @returns {Array} 安全設定陣列
+ */
+function buildSafetySettings(safetyLevel = DEFAULT_SAFETY_LEVEL) {
+  return SAFETY_CATEGORIES.map((category) => ({
+    category,
+    threshold: safetyLevel,
+  }));
+}
+
+/**
+ * 建立生成設定
+ * @param {Object} params - 參數
+ * @returns {Object} 生成設定
+ */
+function buildGenerateConfig(params) {
+  const {
+    aspectRatio = '1:1',
+    temperature = DEFAULT_TEMPERATURE,
+    personGeneration = DEFAULT_PERSON_GENERATION,
+    safetyLevel = DEFAULT_SAFETY_LEVEL,
+  } = params;
+
+  const config = {
+    responseModalities: [Modality.TEXT, Modality.IMAGE],
+    temperature,
+    imageConfig: {
+      aspectRatio,
+      imageSize: DEFAULT_IMAGE_SIZE,
+    },
+    safetySettings: buildSafetySettings(safetyLevel),
+  };
+
+  if (personGeneration !== 'allow_adult') {
+    config.personGeneration = personGeneration;
+  }
+
+  return config;
+}
+
+/**
+ * 生成圖片（支援多輪對話）
+ * @param {Object} params - 生成參數
+ * @param {string} params.prompt - 圖片描述
+ * @param {string} [params.sessionId] - 既有的 session ID（用於迭代）
+ * @param {string} [params.aspectRatio] - 長寬比
+ * @param {string} [params.style] - 藝術風格
+ * @param {string} [params.negativePrompt] - 負面提示
+ * @param {number} [params.temperature] - 創意程度
+ * @param {number} [params.numberOfImages] - 生成數量
+ * @returns {Promise<GenerateImageResult>} 生成結果
+ */
+export async function generateImage(params) {
+  const {
+    prompt,
+    sessionId,
+    aspectRatio = '1:1',
+    numberOfImages = 1,
+    style,
+    negativePrompt,
+    temperature = DEFAULT_TEMPERATURE,
+  } = params;
+
+  const client = getClient();
+
+  // 建構完整 prompt
+  const fullPrompt = buildFullPrompt(prompt, { style, negativePrompt });
+
+  log(`生成中: "${prompt.substring(0, 50)}..."`);
+  log(`參數: aspect=${aspectRatio}, style=${style || '無'}, temp=${temperature}`);
+
+  // 檢查是否為多輪對話
+  const existingSession = sessionId ? await loadSession(sessionId) : null;
+  const isMultiTurn = !!existingSession;
+
+  if (isMultiTurn) {
+    log(`多輪對話模式: session=${sessionId}, 歷史=${existingSession.history.length}筆`);
+  }
+
+  // 建立生成設定
+  const config = buildGenerateConfig({
+    aspectRatio,
+    temperature,
+  });
+
+  // 執行生成
+  let response;
+  let currentSessionId = sessionId;
+
+  if (isMultiTurn) {
+    // 多輪對話：使用 Chat API
+    response = await generateWithChat(client, existingSession.history, fullPrompt, config);
+  } else {
+    // 首次生成：使用串流 API
+    response = await generateWithStream(client, fullPrompt, config, numberOfImages);
+    // 建立新 session
+    const newSession = await createSession();
+    currentSessionId = newSession.id;
+  }
+
+  // 更新 session 歷史
+  if (response.images.length > 0) {
+    await updateSessionHistory(currentSessionId, fullPrompt, response.modelResponse);
+  }
+
+  return {
+    images: response.images,
+    textResponse: response.textResponse,
+    sessionId: currentSessionId,
+    modelResponse: response.modelResponse,
+  };
+}
+
+/**
+ * 使用 Chat API 生成（多輪對話）
+ * SDK 自動管理 Thought Signatures
+ *
+ * @google/genai SDK 正確格式：
+ * - sendMessage({ message: "..." }) 而非 sendMessage(string)
+ * - 參考文件: https://googleapis.github.io/js-genai/release_docs/classes/chats.Chat.html
+ */
+async function generateWithChat(client, history, prompt, config) {
+  const chat = client.chats.create({
+    model: GEMINI_MODEL,
+    history: history,
+    config: config,
+  });
+
+  // 修正：使用物件格式 { message: prompt } 而非直接傳入字串
+  const response = await chat.sendMessage({ message: prompt });
+
+  const images = [];
+  let textResponse = '';
+
+  // 處理回應
+  if (response.candidates && response.candidates[0]) {
+    const candidate = response.candidates[0];
+
+    for (const part of candidate.content.parts || []) {
+      if (part.text) {
+        textResponse += part.text;
+      }
+      if (part.inlineData) {
+        images.push({
+          data: part.inlineData.data,
+          mimeType: part.inlineData.mimeType || 'image/png',
+        });
+      }
+    }
+
+    return {
+      images,
+      textResponse,
+      modelResponse: candidate.content,
+    };
+  }
+
+  return {
+    images: [],
+    textResponse: '',
+    modelResponse: { parts: [] },
+  };
+}
+
+/**
+ * 使用串流 API 生成（首次生成）
+ */
+async function generateWithStream(client, prompt, config, numberOfImages) {
+  const response = await client.models.generateContentStream({
+    model: GEMINI_MODEL,
+    contents: prompt,
+    config,
+  });
+
+  const images = [];
+  let textResponse = '';
+  const parts = [];
+
+  // 處理串流回應
+  for await (const chunk of response) {
+    if (chunk.text) {
+      textResponse += chunk.text;
+      parts.push({ text: chunk.text });
+    }
+
+    if (chunk.data) {
+      images.push({
+        data: chunk.data,
+        mimeType: 'image/png',
+      });
+      parts.push({
+        inlineData: {
+          data: chunk.data,
+          mimeType: 'image/png',
+        },
+      });
+
+      if (images.length >= numberOfImages) break;
+    }
+  }
+
+  return {
+    images,
+    textResponse,
+    modelResponse: { role: 'model', parts },
+  };
+}
+
+/**
+ * 驗證客戶端是否可用
+ * @returns {boolean}
+ */
+export function isClientAvailable() {
+  try {
+    getClient();
+    return true;
+  } catch {
+    return false;
+  }
+}