LocalMiniDrama

https://github.com/xuanyustudio/localminidrama
Admin
LocalMiniDrama is an AI-powered local short drama and comic drama generation tool that is completely...
Tokens:21,043
Snippets:228
Trust Score:6.1
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Backend Development

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

Instructions to set up and run the backend Node.js server, including installing dependencies, configuring settings, and migrating the database.

```bash
cd backend-node
npm install
cp configs/config.example.yaml configs/config.yaml
# 编辑 config.yaml，填入你的 AI API 配置
npm run migrate   # 首次运行，初始化数据库
npm start         # 默认端口 5679
```

--------------------------------

### Clone and Run LocalMiniDrama in Development Mode

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/en.md

This snippet outlines the steps to clone the repository, set up the backend and frontend development environments, and start the application. Ensure Node.js is installed and follow the configuration steps for the backend.

```bash
git clone https://github.com/your-username/LocalMiniDrama.git
cd LocalMiniDrama

# 1. Backend (port 5679)
cd backend-node
npm install
cp configs/config.example.yaml configs/config.yaml
# Edit config.yaml — set your AI API endpoint and key
npm run migrate   # first run: initialise DB
npm start

# 2. Frontend (new terminal, port 3013)
cd frontweb
npm install
npm run dev
```

--------------------------------

### Start Batch Mix Cut

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Starts a batch video mixing process. Allows uploading up to 120 video files for mixing.

```HTTP
POST {baseUrl}/api/v1/mixcut/start
Content-Type: multipart/form-data

videos: <最多120个视频文件>
```

--------------------------------

### Start Frontend Development

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

Instructions to set up and run the frontend Vue.js development server.

```bash
cd frontweb
npm install
npm run dev       # 默认端口 3013
```

--------------------------------

### Package as Executable

Source: https://github.com/xuanyustudio/localminidrama/blob/main/desktop/README.md

Package the application into an executable installer and portable version for Windows.

```bash
cd desktop
npm install
npm run dist
```

--------------------------------

### Start Desktop (Electron) Development

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

Instructions to set up and run the Electron-based desktop application. Requires Python and Visual Studio C++ build tools.

```bash
cd desktop
npm install
npm start
```

--------------------------------

### Start Rewrite

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Initiates a process to improve or rewrite existing content.

```APIDOC
## POST /api/v1/rewrite/start

### Description
Initiates a process to improve or rewrite existing content.

### Method
POST

### Endpoint
/api/v1/rewrite/start
```

--------------------------------

### Start Originalization

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Initiates a process to make content more original.

```APIDOC
## POST /api/v1/original/start

### Description
Initiates a process to make content more original.

### Method
POST

### Endpoint
/api/v1/original/start
```

--------------------------------

### Fork and Clone Repository

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

Steps to fork the LocalMiniDrama repository and clone it locally to start development.

```bash
# 1. Fork 本仓库，然后克隆你的 Fork
git clone https://github.com/你的用户名/LocalMiniDrama.git
cd LocalMiniDrama
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for different types of changes.

```bash
feat: 新增批量生成分镜功能
fix: 修复导出 ZIP 时视频文件丢失的问题
docs: 更新 AI 配置指南中的火山引擎配置说明
```

--------------------------------

### Get All AI Configurations

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves a list of all configured AI models.

```APIDOC
## GET /api/v1/ai-configs

### Description
Retrieves a list of all configured AI models.

### Method
GET

### Endpoint
/api/v1/ai-configs
```

--------------------------------

### Start One-Click Originalization

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Starts the one-click originalization process for content. This endpoint is used to make existing content more original.

```HTTP
POST {baseUrl}/api/v1/original/start
```

--------------------------------

### Get All AI Configurations

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves a list of all configured AI settings. Use this endpoint to view existing AI configurations.

```HTTP
GET {baseUrl}/api/v1/ai-configs
```

--------------------------------

### Get Storyboard Status

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Checks the status of each storyboard video for a given episode.

```bash
GET /api/v1/episodes/{episode_id}/storyboards
```

--------------------------------

### Get Character List

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves the list of characters associated with a drama project.

```bash
GET /api/v1/dramas/{drama_id}/characters
```

--------------------------------

### Get Episode Storyboards

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves the storyboards for a specific episode.

```APIDOC
## GET /api/v1/episodes/{episode_id}/storyboards

### Description
Retrieves the generated storyboards for a specific episode.

### Method
GET

### Endpoint
/api/v1/episodes/{episode_id}/storyboards

### Parameters
#### Path Parameters
- **episode_id** (string) - Required - The ID of the episode.
```

--------------------------------

### Start One-Click Translation

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Initiates a one-click translation process for videos, including adding subtitles and background music. Requires uploading video, BGM, and subtitle files, and specifying the target language.

```HTTP
POST {baseUrl}/api/v1/globalize/start
Content-Type: multipart/form-data

file: <视频文件>
bgm: <BGM音频>
subtitle_file: <字幕文件>
target_lang: "en"
```

--------------------------------

### Preset AI Configurations

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Applies a one-click preset for specific AI vendors. Use this for quick setup of common configurations like DashScope (Tongyi Qianwen) or Volcengine (Doubao/Volcano Engine).

```HTTP
POST {baseUrl}/api/v1/ai-configs/preset/dashscope   # 通义千问
```

```HTTP
POST {baseUrl}/api/v1/ai-configs/preset/volcengine   # 豆包/火山引擎
```

--------------------------------

### Get Character List

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves the list of characters associated with a drama project.

```APIDOC
## GET /api/v1/dramas/{drama_id}/characters

### Description
Retrieves the list of characters for a given drama project.

### Method
GET

### Endpoint
/api/v1/dramas/{drama_id}/characters

### Parameters
#### Path Parameters
- **drama_id** (string) - Required - The ID of the drama project.
```

--------------------------------

### Synthesize Final Video

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Initiates the synthesis of the final video. Requires polling until the process is completed. The final video can be downloaded via a GET request.

```bash
POST /api/v1/video-merges
→ 轮询直到 completed
→ GET /api/v1/episodes/{episode_id}/download 获取下载
```

--------------------------------

### Prompt Overrides Management

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Manages prompt overrides for specific keys. Allows getting, setting, or deleting custom prompt values.

```HTTP
GET  {baseUrl}/api/v1/settings/prompts
```

```HTTP
PUT  {baseUrl}/api/v1/settings/prompts/{key}   { "value": "..." }
```

```HTTP
DELETE {baseUrl}/api/v1/settings/prompts/{key}
```

--------------------------------

### Start Manuscript Improvement

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Initiates the manuscript improvement process. This endpoint is used for refining written content.

```HTTP
POST {baseUrl}/api/v1/rewrite/start
```

--------------------------------

### Get LocalMiniDrama Backend URL

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves the base URL for the LocalMiniDrama backend. Defaults to http://localhost:5679 if not configured.

```javascript
const baseUrl = config.base_url || "http://localhost:5679";
```

--------------------------------

### Build Frontend

Source: https://github.com/xuanyustudio/localminidrama/blob/main/AGENTS.md

Build the frontend application for production. Navigate to the frontend directory before running the build command.

```bash
cd frontweb && npm run build
```

--------------------------------

### Merge Final Video

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Merges all generated video segments into a final video. Poll the task until completion. Use GET /api/v1/episodes/{episode_id}/download to get the final video.

```APIDOC
## POST /api/v1/video-merges

### Description
Merges all generated video segments into a single final video for the episode.

### Method
POST

### Endpoint
/api/v1/video-merges

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the video merge task. Poll this task's status until 'completed'.

### Download
Use `GET /api/v1/episodes/{episode_id}/download` to retrieve the final merged video once the merge task is completed.
```

--------------------------------

### Create Project

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Initiates a new drama project. Remember to record the returned drama_id for subsequent operations.

```bash
POST /api/v1/dramas
→ 记下返回的 drama_id
```

--------------------------------

### Build Frontend

Source: https://github.com/xuanyustudio/localminidrama/blob/main/desktop/README.md

Build the frontend for the application. This is a prerequisite for running the Electron app.

```bash
cd ../frontweb && npm install && npm run build
```

--------------------------------

### Import framePromptService and loadConfig

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quad-grid.md

Add these lines at the top of `imageService.js` to import necessary modules. Ensure `loadConfig` is moved to the top if it was previously required locally within a function.

```javascript
const framePromptService = require('./framePromptService');
const loadConfig = require('../config').loadConfig;
```

--------------------------------

### Configure Aliyun DashScope for Text, Image, and Video Generation

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/configuration.md

Use this configuration to connect to Aliyun DashScope for text, image, or video generation. Ensure you have obtained the correct API Key and selected the appropriate model for your task.

```text
服务商：DashScope
Base URL：https://dashscope.aliyuncs.com/compatible-mode/v1
API Key：sk-xxxxxxxxxxxxxxxx
模型：qwen-plus（文本）/ wanx2.1-t2i-turbo（图片）/ wan2.1-t2v-turbo（视频）
```

--------------------------------

### macOS One-Click Packaging

Source: https://github.com/xuanyustudio/localminidrama/blob/main/desktop/README.md

Execute the script to package the application for macOS, including full and clean DMG versions, with accelerated domestic mirror usage.

```bash
bash dist-mac.sh
```

--------------------------------

### Storage Configuration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/backend-node/README.md

Sets the root directory for local storage of images and videos.

```yaml
storage:
  local_path: ./data/storage      # 图片/视频本地存储根目录
```

--------------------------------

### Build Quad-Grid Prompt in imageService.js

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quadgrid.md

This function constructs a detailed prompt for generating a 2x2 storyboard grid image. It requires database access, logging, configuration, storyboard ID, and the AI model. It generates prompts for the first, key, and last frames, then combines them into a single prompt for the quad-grid.

```javascript
async function buildQuadGridPrompt(db, log, cfg, storyboardId, model) {
  const framePromptService = require('./framePromptService');
  const sb = framePromptService.loadStoryboard(db, storyboardId);
  if (!sb) return null;
  const scene = framePromptService.loadScene(db, sb.scene_id);
  const characterNames = framePromptService.loadStoryboardCharacterNames(db, storyboardId);

  const [first, key1, key2, last] = await Promise.all([
    framePromptService.generateSingleFrameExported(db, log, cfg, sb, scene, characterNames, model, 'first'),
    framePromptService.generateSingleFrameExported(db, log, cfg, sb, scene, characterNames, model, 'key'),
    framePromptService.generateSingleFrameExported(db, log, cfg, sb, scene, characterNames, model, 'key'),
    framePromptService.generateSingleFrameExported(db, log, cfg, sb, scene, characterNames, model, 'last'),
  ]);

  const style = cfg?.style?.default_style || '';
  const styleNote = style ? `, consistent style: ${style}` : '';
  return `Generate a 2x2 four-panel storyboard grid image (comic strip layout, clear panel borders). Each panel shows a different moment in sequence${styleNote}:
Panel 1 (top-left, first frame): ${first.prompt}
Panel 2 (top-right, key moment): ${key1.prompt}
Panel 3 (bottom-left, key moment): ${key2.prompt}
Panel 4 (bottom-right, last frame): ${last.prompt}
All panels have consistent character appearance and scene. Clear visible borders between panels. Sequential action progression.`;
}
```

--------------------------------

### Get Episode Merge Status

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Checks the merge status of the final video for an episode.

```APIDOC
## GET /api/v1/episodes/{episode_id}/merge-status

### Description
Checks the status of the final video merge process for a specific episode.

### Method
GET

### Endpoint
/api/v1/episodes/{episode_id}/merge-status

### Parameters
#### Path Parameters
- **episode_id** (string) - Required - The ID of the episode.
```

--------------------------------

### Get Merge Status

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Checks the synthesis status of the final video for a given episode.

```bash
GET /api/v1/episodes/{episode_id}/merge-status
```

--------------------------------

### Create Project

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Initiates a new drama project. Remember to record the returned drama_id for subsequent operations.

```APIDOC
## POST /api/v1/dramas

### Description
Creates a new drama project.

### Method
POST

### Endpoint
/api/v1/dramas

### Response
#### Success Response (200)
- **drama_id** (string) - The unique identifier for the newly created drama project.
```

--------------------------------

### Run Backend Log File

Source: https://github.com/xuanyustudio/localminidrama/blob/main/desktop/README.md

Locate and open the backend log file to diagnose issues. This is the recommended method for viewing logs.

```powershell
%APPDATA%\LocalMiniDrama\backend\logs\app.log
```

--------------------------------

### Package with Chinese Mirrors

Source: https://github.com/xuanyustudio/localminidrama/blob/main/desktop/README.md

Package the application using Chinese mirrors for Electron and electron-builder binaries to avoid timeouts.

```bash
npm run dist:cn
```

--------------------------------

### Create AI Configuration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Creates a new AI configuration with specified parameters.

```APIDOC
## POST /api/v1/ai-configs

### Description
Creates a new AI configuration with specified parameters.

### Method
POST

### Endpoint
/api/v1/ai-configs

### Request Body
- **name** (string) - Required - The name of the AI configuration.
- **vendor** (string) - Required - The vendor of the AI model (e.g., 'dashscope').
- **api_key** (string) - Required - The API key for authentication.
- **model** (string) - Required - The specific AI model to use (e.g., 'qwen-plus').
- **api_base** (string) - Optional - The base URL for the API endpoint.

### Request Example
```json
{
  "name": "通义千问",
  "vendor": "dashscope",
  "api_key": "sk-...",
  "model": "qwen-plus",
  "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
}
```
```

--------------------------------

### Build Quad Grid Prompt Function

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quad-grid.md

This asynchronous helper function constructs a prompt for generating a 2x2 storyboard grid image. It loads storyboard and scene data, incorporates drama style and metadata, and generates individual prompts for four frames (first, key, key, last) using `framePromptService.generateSingleFrameForQuadGrid`.

```javascript
/**
 * 四宫格模式：为分镜生成 4 帧提示词，拼成 2×2 grid 格式的单张图生成提示词
 */
async function buildQuadGridPrompt(db, log, storyboardId, model) {
  let cfg = loadConfig();
  // 复用 framePromptService 内的辅助函数
  const sb = framePromptService.loadStoryboard(db, storyboardId);
  if (!sb) throw new Error('分镜不存在');

  // 读取 drama style
  try {
    const epRow = db.prepare(
      'SELECT drama_id FROM episodes WHERE id = (SELECT episode_id FROM storyboards WHERE id = ? AND deleted_at IS NULL) AND deleted_at IS NULL'
    ).get(Number(storyboardId));
    if (epRow && epRow.drama_id) {
      const dramaRow = db.prepare('SELECT style, metadata FROM dramas WHERE id = ? AND deleted_at IS NULL').get(epRow.drama_id);
      if (dramaRow) {
        const styleOverrides = {};
        if (dramaRow.style && String(dramaRow.style).trim()) {
          styleOverrides.default_style = String(dramaRow.style).trim();
        }
        if (dramaRow.metadata) {
          try {
            const meta = typeof dramaRow.metadata === 'string' ? JSON.parse(dramaRow.metadata) : dramaRow.metadata;
            if (meta && meta.aspect_ratio) {
              styleOverrides.default_image_ratio = meta.aspect_ratio;
            }
          } catch (_) {}
        }
        if (Object.keys(styleOverrides).length > 0) {
          cfg = { ...cfg, style: { ...(cfg?.style || {}), ...styleOverrides } };
        }
      }
    }
  } catch (_) {}

  const scene = framePromptService.loadScene(db, sb.scene_id);
  const characterNames = framePromptService.loadStoryboardCharacterNames(db, storyboardId);

  log.info('[四宫格] 开始生成4帧提示词', { storyboard_id: storyboardId });

  const [first, key1, key2, last] = await Promise.all([
    framePromptService.generateSingleFrameForQuadGrid(db, log, cfg, sb, scene, characterNames, model, 'first'),
    framePromptService.generateSingleFrameForQuadGrid(db, log, cfg, sb, scene, characterNames, model, 'key'),
    framePromptService.generateSingleFrameForQuadGrid(db, log, cfg, sb, scene, characterNames, model, 'key'),
    framePromptService.generateSingleFrameForQuadGrid(db, log, cfg, sb, scene, characterNames, model, 'last'),
  ]);

  log.info('[四宫格] 4帧提示词生成完成', { storyboard_id: storyboardId });

  const style = cfg?.style?.default_style || '';
  const styleHint = style ? `, art style: ${style}` : '';

  const quadPrompt = 
    `Generate a 2x2 storyboard grid image (four panels showing action sequence progression${styleHint}). ` + 
    `Each panel is clearly separated by a thin border. ` + 
    `Panel 1 (top-left, initial state): ${first.prompt}. ` + 
    `Panel 2 (top-right, action begins): ${key1.prompt}. ` + 
    `Panel 3 (bottom-left, action climax): ${key2.prompt}. ` + 
    `Panel 4 (bottom-right, final state): ${last.prompt}. ` + 
    `Consistent character appearance and scene across all panels. Cinematic quality.`;

  return quadPrompt;
}
```

--------------------------------

### Run from Command Line for Real-time Logs

Source: https://github.com/xuanyustudio/localminidrama/blob/main/desktop/README.md

Execute the application from the command line to view real-time logs directly in the terminal.

```powershell
& "D:\path\to\release\LocalMiniDrama 1.2.8.exe"
```

--------------------------------

### Add QuadGridMode Reactive Variable in Vue

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quad-grid.md

This Vue.js JavaScript snippet shows how to declare a new reactive boolean variable `quadGridMode` within a `<script setup>` block. This variable will control the quad-grid feature's UI state.

```javascript
const quadGridMode = ref(false)
```

--------------------------------

### Run Backend Tests

Source: https://github.com/xuanyustudio/localminidrama/blob/main/AGENTS.md

Execute backend tests using Node.js built-in test runner. Navigate to the backend directory first.

```bash
cd backend-node && node --test test/*.test.js
```

--------------------------------

### Open Frontend Developer Tools

Source: https://github.com/xuanyustudio/localminidrama/blob/main/desktop/README.md

Enable and open the frontend developer tools for debugging API requests. This requires setting an environment variable before launching the application.

```powershell
$env:LOCALMINIDRAMA_DEVTOOLS=1
& "D:\path\to\release\LocalMiniDrama 1.2.8.exe"
```

--------------------------------

### Database Configuration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/backend-node/README.md

Specifies the file path for the SQLite database.

```yaml
database:
  path: ./data/drama_generator.db # SQLite 文件路径
```

--------------------------------

### Default Style Configuration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/backend-node/README.md

Sets the default drawing style and aspect ratios for images and videos.

```yaml
style:
  default_style: realistic         # 默认绘图风格
  default_image_ratio: "16:9"      # 默认图片比例
  default_video_ratio: "16:9"      # 默认视频比例
```

--------------------------------

### Add Quad-Grid Processing in processImageGeneration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quadgrid.md

This code adds a conditional branch to the `processImageGeneration` function to handle 'quad_grid' frame types. It calls `buildQuadGridPrompt` to generate the prompt and updates the database if successful. Includes error handling for prompt generation failures.

```javascript
// ── 四宫格模式：先生成4帧提示词，再拼装组合提示词 ──────────────────
  if (row.frame_type === 'quad_grid' && row.storyboard_id) {
    try {
      const quadPrompt = await buildQuadGridPrompt(db, log, cfg, row.storyboard_id, row.model);
      if (quadPrompt) {
        db.prepare('UPDATE image_generations SET prompt = ?, updated_at = ? WHERE id = ?')
          .run(quadPrompt, new Date().toISOString(), imageGenId);
        row.prompt = quadPrompt;
      }
    } catch (quadErr) {
      log.warn('[图生] 四宫格提示词生成失败，使用原始提示词', { error: quadErr.message });
    }
  }
```

--------------------------------

### List Existing Projects

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Fetches a list of existing drama projects to determine if a new one needs to be created. Uses pagination with default page size of 20.

```http
GET {baseUrl}/api/v1/dramas?page=1&page_size=20
```

--------------------------------

### Build Quad-Grid Prompt for AI Image Generation

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quad-grid.md

This backend JavaScript snippet shows how to conditionally build a combined prompt for quad-grid image generation. It attempts to create a specialized prompt for storyboards marked as 'quad_grid' and falls back to the original prompt if an error occurs during the quad-grid prompt building process.

```javascript
    // ── Step 3.5: 四宫格模式 — 用 AI 生成的4帧内容替换 prompt ────────
    let finalPrompt = row.prompt;
    if (row.frame_type === 'quad_grid' && row.storyboard_id) {
      log.info('[图生] Step3.5 四宫格模式，生成组合提示词', { id: imageGenId });
      try {
        finalPrompt = await buildQuadGridPrompt(db, log, row.storyboard_id, row.model);
        log.info('[图生] Step3.5 四宫格提示词生成完成', { id: imageGenId,
          prompt_preview: finalPrompt.slice(0, 120),
        });
      } catch (qErr) {
        log.warn('[图生] Step3.5 四宫格提示词生成失败，回退到原始 prompt', { error: qErr.message });
        // 回退到原始 prompt，不中断流程
      }
    }
```

--------------------------------

### Create New Drama Project

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Creates a new short drama project with specified title, style, type, and metadata like aspect ratio and video duration.

```http
POST {baseUrl}/api/v1/dramas
Content-Type: application/json

{
  "title": "少年修仙传",
  "style": "古风仙侠",
  "type": "short_drama",
  "metadata": {
    "aspect_ratio": "16:9",
    "video_duration": 5
  }
}
```

--------------------------------

### Generate Character Image (Quick Question)

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Generates an image for a specific character. This is part of a quick question workflow.

```bash
POST /api/v1/characters/{id}/generate-image
```

--------------------------------

### Commit Frontend Changes for Quad-Grid UI Toggle

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quad-grid.md

This bash snippet shows the Git commands to stage and commit the frontend code changes for adding the quad-grid mode global toggle UI.

```bash
git add frontweb/src/views/FilmCreate.vue
git commit -m "feat: add quad-grid mode global toggle in storyboard section UI"
```

--------------------------------

### Create AI Configuration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Creates a new AI configuration. Requires a JSON payload with details such as name, vendor, API key, model, and API base URL.

```HTTP
POST {baseUrl}/api/v1/ai-configs
Content-Type: application/json

{
  "name": "通义千问",
  "vendor": "dashscope",
  "api_key": "sk-...",
  "model": "qwen-plus",
  "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
}
```

--------------------------------

### Commit Backend Changes for Quad-Grid Generation

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quad-grid.md

This bash snippet shows the Git commands to stage and commit the backend code changes related to implementing quad-grid storyboard image generation.

```bash
git add backend-node/src/services/imageService.js
git add backend-node/src/services/framePromptService.js
git commit -m "feat: add quad-grid storyboard image generation via combined frame prompts"
```

--------------------------------

### Implement Text AI for Prompt Optimization

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-14-storyboard-image-quality.md

A new text AI optimization step is introduced before image generation (Step 3 in imageService.js). This step enhances the original storyboard prompts by adding detailed descriptions, unifying style vocabulary, and incorporating reference asset name mappings, making them more effective for image generation models.

```javascript
在 `imageService.js` Step 3 之前增加一个文本 AI 优化步骤：
- 输入：原始分镜提示词 + 风格 + 宽高比 + 参考资产名称列表
- 输出：针对图片生成模型优化的提示词（增强细节描述、统一风格词汇、加入参考资产名称映射）
- 模型：使用轻量文本模型（如 deepseek-v3），成本低
- 缓存：优化后的 prompt 回写 `image_generations.prompt`，同一分镜重新生成时可复用
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/xuanyustudio/localminidrama/blob/main/AGENTS.md

Execute frontend tests using Node.js built-in test runner. Navigate to the frontend directory first. Supports ESM.

```bash
cd frontweb && node --test test/*.test.js
```

--------------------------------

### Generate Scene Image

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Generates an image for a specific scene.

```bash
POST /api/v1/scenes/{scene_id}/generate-image
```

--------------------------------

### Server Configuration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/backend-node/README.md

Defines the HTTP server port for the application.

```yaml
server:
  port: 5679                      # HTTP 服务端口
```

--------------------------------

### Git Commit for Quad-Grid Support

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quadgrid.md

This command stages the modified files and creates a Git commit with a descriptive message, indicating the addition of support for quad-grid storyboard image generation.

```bash
git add backend-node/src/services/imageService.js backend-node/src/services/framePromptService.js
git commit -m "feat: add quad-grid storyboard image generation support"
```

--------------------------------

### Create New Drama Project

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Creates a new drama project with specified details like title, style, and type. Metadata for aspect ratio and video duration can also be configured.

```APIDOC
## POST /api/v1/dramas

### Description
Creates a new drama project.

### Method
POST

### Endpoint
/api/v1/dramas

### Request Body
- **title** (string) - Required - The title of the drama project.
- **style** (string) - Optional - The style or genre of the drama.
- **type** (string) - Optional - The type of the drama (e.g., "short_drama").
- **metadata** (object) - Optional - Contains metadata for the drama.
  - **aspect_ratio** (string) - Optional - The default aspect ratio (e.g., "16:9", "9:16", "1:1").
  - **video_duration** (number) - Optional - The default duration for video clips in seconds.
```

--------------------------------

### Get/Set Language

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves or sets the prompt language for the system.

```APIDOC
## GET/PUT /api/v1/settings/language

### Description
Retrieves or sets the prompt language for the system.

### Method
GET, PUT

### Endpoint
/api/v1/settings/language

### Request Body (for PUT)
- **language** (string) - Required - The desired language code (e.g., 'zh', 'en').
```

--------------------------------

### Multi-Agent Collaboration for Outline Generation

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-14-storyboard-image-quality.md

A three-agent collaboration system using Vercel AI SDK's Tool Use is proposed for outline generation. The 'Storyteller' agent generates the storyline, the 'Outliner' agent creates episode outlines based on the storyline, and the 'Director' agent reviews and refines the outlines for consistency.

```javascript
基于 Vercel AI SDK 的 Tool Use，实现三 Agent 协作：
- **故事师**：分析输入主题，生成故事线（存 `storylines` 表）
- **大纲师**：根据故事线生成各集大纲（存 `outlines` 表）
- **导演**：审核大纲与故事线一致性，提出修改建议并执行

工具调用链：`主Agent → 故事师 → saveStoryline → 大纲师 → saveOutline → 导演 → updateOutline`
```

--------------------------------

### Create Feature Branch

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

How to create a new branch for feature development or bug fixes from the main branch.

```bash
# 2. 创建功能分支（从 main 分支切出）
git checkout -b feature/your-feature-name
# 或 bugfix/your-bug-description
```

--------------------------------

### Preset AI Configurations

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Applies preset configurations for supported AI vendors.

```APIDOC
## POST /api/v1/ai-configs/preset/{vendor}

### Description
Applies preset configurations for supported AI vendors.

### Method
POST

### Endpoint
/api/v1/ai-configs/preset/{vendor}

### Parameters
#### Path Parameters
- **vendor** (string) - Required - The vendor name (e.g., 'dashscope', 'volcengine').

### Example Usage
- **Dashscope (Tongyi Qianwen):** `POST /api/v1/ai-configs/preset/dashscope`
- **Volcengine (Doubao/Volcengine):** `POST /api/v1/ai-configs/preset/volcengine`
```

--------------------------------

### Batch Grid Generation for Consistent Storyboards

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-14-storyboard-image-quality.md

To improve visual consistency within the same storyboard, multiple frames will be combined into a grid prompt for single API generation. The resulting grid image will then be automatically split into individual frames using `splitQuadGridToImages`, reducing API calls and ensuring stylistic coherence.

```javascript
在分镜图生成时，将同一分镜的多帧组合为宫格提示词，一次生成宫格图
- 生成完成后调用 `splitQuadGridToImages` 自动拆分为独立帧
- API 调用次数从 N 次降为 1 次
```

--------------------------------

### Commit Changes

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

Stage all changes and commit them with a descriptive message following the Conventional Commits format.

```bash
# 3. 完成开发并提交
git add .
git commit -m "feat: 简短描述改动"
```

--------------------------------

### Batch Generate Videos

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Generates videos in batch for a given episode. Requires polling the task status until completion.

```bash
POST /api/v1/videos/episode/{episode_id}/batch
→ 轮询视频任务直到完成
```

--------------------------------

### List Existing Projects

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves a list of existing drama projects. This can be used to check if a project already exists before creating a new one.

```APIDOC
## GET /api/v1/dramas

### Description
Lists existing drama projects.

### Method
GET

### Endpoint
/api/v1/dramas

### Parameters
#### Query Parameters
- **page** (number) - Optional - The page number for pagination.
- **page_size** (number) - Optional - The number of items per page.
```

--------------------------------

### Language Configuration

Source: https://github.com/xuanyustudio/localminidrama/blob/main/backend-node/README.md

Configures the language for prompts (e.g., Chinese or English).

```yaml
language: zh                      # 提示词语言（zh / en）
```

--------------------------------

### Reference Image Compression using Sharp

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-14-storyboard-image-quality.md

To prevent API request size limits, reference images will be compressed before being sent. The target size for single images is ≤ 3MB (using JPEG quality reduction), and the total size is ≤ 10MB, with larger images being prioritized for compression. The `sharp` library will be used for this process.

```javascript
在 `callGeminiImageApi` 中对参考图 buffer 做压缩：
- 单张目标：≤ 3MB（JPEG quality 递减压缩）
- 总大小：≤ 10MB（按大小降序优先压缩大图）
- 使用 `sharp` 处理（项目已依赖）
```

--------------------------------

### Prompt Overrides

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Manages prompt overrides, allowing custom values for specific keys.

```APIDOC
## GET/PUT/DELETE /api/v1/settings/prompts/{key}

### Description
Manages prompt overrides, allowing custom values for specific keys.

### Method
GET, PUT, DELETE

### Endpoint
/api/v1/settings/prompts/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The key of the prompt to manage.

### Request Body (for PUT)
- **value** (string) - Required - The new value for the prompt.
```

--------------------------------

### Get/Set Generation Parameters

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves or sets the default generation parameters for content creation. Use these endpoints to manage default settings for AI-generated content.

```HTTP
GET  {baseUrl}/api/v1/settings/generation
```

```HTTP
PUT  {baseUrl}/api/v1/settings/generation
```

--------------------------------

### Generate Storyboards

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Generates storyboards for an episode. Characters are automatically populated, and backgrounds are inferred.

```APIDOC
## POST /api/v1/episodes/{episode_id}/storyboards

### Description
Generates storyboards for a given episode. The AI automatically infers characters and backgrounds.

### Method
POST

### Endpoint
/api/v1/episodes/{episode_id}/storyboards

### Parameters
#### Path Parameters
- **episode_id** (string) - Required - The ID of the episode for which to generate storyboards.

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the task created for storyboard generation. Poll this task's status to know when generation is complete. The generated storyboards will include populated `characters` and inferred `background` fields.
```

--------------------------------

### Batch Generate Videos

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Generates videos for an episode in batch. Poll the task until completion.

```APIDOC
## POST /api/v1/videos/episode/{episode_id}/batch

### Description
Generates videos for all scenes/storyboards within an episode in a batch process.

### Method
POST

### Endpoint
/api/v1/videos/episode/{episode_id}/batch

### Parameters
#### Path Parameters
- **episode_id** (string) - Required - The ID of the episode for which to generate videos.
```

--------------------------------

### Bulk Update API Keys

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Updates the API key for multiple AI configurations in bulk.

```APIDOC
## PUT /api/v1/ai-configs/bulk-update-key

### Description
Updates the API key for multiple AI configurations in bulk.

### Method
PUT

### Endpoint
/api/v1/ai-configs/bulk-update-key

### Request Body
- **api_key** (string) - Required - The new API key to apply.

### Request Example
```json
{
  "api_key": "sk-..."
}
```
```

--------------------------------

### Export generateSingleFrameForQuadGrid

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quad-grid.md

Modify the `module.exports` in `framePromptService.js` to export the `generateSingleFrame` function, aliasing it as `generateSingleFrameForQuadGrid` for use by `imageService`.

```javascript
module.exports = {
  generateFramePrompt,
  loadStoryboard,
  loadStoryboardCharacterNames,
  loadScene,
  getFramePrompts: (db, storyboardId) => storyboardService.getFramePrompts(db, storyboardId),
  // 供 imageService 的四宫格模式调用
  generateSingleFrameForQuadGrid: generateSingleFrame,
};
```

--------------------------------

### Pass Quadgrid Parameter in Batch Generation

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quadgrid.md

Ensure that the `quadGridMode` state is also passed to `imagesAPI.create` calls within the `startBatchImageGeneration` function. This maintains consistency for batch operations.

```js
frame_type: quadGridMode.value ? 'quad_grid' : undefined,
```

--------------------------------

### Generate Storyboards

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Generates storyboards for an episode. This process automatically infers scenes and populates the characters field in the storyboard, assuming character extraction has been completed.

```bash
POST /api/v1/episodes/{episode_id}/storyboards
→ 轮询 task，分镜中 characters 字段会自动填充，background 自动推断
```

--------------------------------

### Automated Storyboard Scene Segmentation and Shot Generation

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-14-storyboard-image-quality.md

An automated process for storyboard generation is planned, involving two agents. The `segmentAgent` automatically splits scenes from scripts into segments with emotional and action descriptions. The `shotAgent` then generates storyboard prompts, including shot type, angle, camera movement, characters, and dialogue, based on these segments.

```javascript
- **segmentAgent**：从剧本中自动拆分场景片段（含情绪、动作描述）
- **shotAgent**：根据片段生成分镜提示词（含景别、角度、运镜、角色、对话）
- 前端通过 WebSocket 接收流式进度更新
```

--------------------------------

### Get/Set Generation Parameters

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves or sets the default generation parameters.

```APIDOC
## GET/PUT /api/v1/settings/generation

### Description
Retrieves or sets the default generation parameters.

### Method
GET, PUT

### Endpoint
/api/v1/settings/generation
```

--------------------------------

### Download Episode

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Provides a download link for the final merged video of an episode.

```APIDOC
## GET /api/v1/episodes/{episode_id}/download

### Description
Retrieves the download URL for the final merged video of an episode.

### Method
GET

### Endpoint
/api/v1/episodes/{episode_id}/download

### Parameters
#### Path Parameters
- **episode_id** (string) - Required - The ID of the episode.
```

--------------------------------

### Add Quadgrid Switch UI to Storyboard Config

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quadgrid.md

Integrate a UI switch for the quadgrid mode within the storyboard configuration row. This allows users to toggle the quadgrid feature on or off.

```html
<span class="sb-config-divider">｜</span>
          <label class="sb-config-item">
            <span class="sb-config-label">四宫格序列图</span>
            <el-switch v-model="quadGridMode" />
            <span class="sb-config-hint">生成含4帧的序列参考图</span>
          </label>
```

--------------------------------

### Git Commit for Quadgrid Feature

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-09-storyboard-angle-and-quadgrid.md

Commit the changes made to the frontend web application, specifically to the `FilmCreate.vue` file, with a descriptive message indicating the addition of the quad-grid mode switch.

```bash
git add frontweb/src/views/FilmCreate.vue
git commit -m "feat: add quad-grid mode switch to storyboard UI"
```

--------------------------------

### Generate Script (Streaming)

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Generates the script content in a streaming format. Requires premise, style, genre, and episode count as body parameters.

```bash
POST /api/v1/generation/story/stream

> body 字段：`premise`（梗概）、`style`（风格）、`genre`（类型）、`episode_count`（集数）
```

--------------------------------

### Push Branch

Source: https://github.com/xuanyustudio/localminidrama/blob/main/CONTRIBUTING.md

Push the local feature branch to your forked repository on GitHub.

```bash
# 4. 推送分支
git push origin feature/your-feature-name
```

--------------------------------

### Prioritize Single Panel Reference for Character Appearance

Source: https://github.com/xuanyustudio/localminidrama/blob/main/docs/plans/2026-03-14-storyboard-image-quality.md

When generating character images, the system now prioritizes using split single panels from a quad grid as reference images. Specifically, the front-facing full-body image (quad_panel_1) is preferred to accurately capture character appearance. If no split panels are available, it falls back to using the entire quad grid image.

```javascript
imageService.js（Step 2 参考图解析）：优先查询拆分后的单张面板作为参考：
  - 场景：`quad_panel_0`（左上格 = 建立远景，最能代表环境）
  - 角色：`quad_panel_1`（右上格 = 正面全身图，最能代表角色外貌）
  - 无拆分面板时 fallback 到四视图合图
```

--------------------------------

### Batch Mix Cut

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Performs a batch mix cut operation on multiple videos.

```APIDOC
## POST /api/v1/mixcut/start

### Description
Performs a batch mix cut operation on multiple videos.

### Method
POST

### Endpoint
/api/v1/mixcut/start

### Request Body
- **videos** (array of files) - Required - Up to 120 video files to process.
```

--------------------------------

### Get/Set Language

Source: https://github.com/xuanyustudio/localminidrama/blob/main/openclaw-skill/SKILL.md

Retrieves or sets the global language for prompts. The language can be set to 'zh' (Chinese) or 'en' (English).

```HTTP
GET  {baseUrl}/api/v1/settings/language
```

```HTTP
PUT  {baseUrl}/api/v1/settings/language   { "language": "zh" | "en" }
```
Tokens:
Raw