---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "Momentry Core 處理器資源管理架構 (v1.0)"
date: "2026-04-21"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "core"
  - "處理器資源管理架構"
ai_query_hints:
  - "查詢 Momentry Core 處理器資源管理架構 (v1.0) 的內容"
  - "Momentry Core 處理器資源管理架構 (v1.0) 的主要目的是什麼？"
  - "如何操作或實施 Momentry Core 處理器資源管理架構 (v1.0)？"
---

# Momentry Core 處理器資源管理架構 (v1.0)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-21 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-21 | 創建處理器資源管理架構文件 | OpenCode | OpenCode / Qwen3.6-Plus |

---

## 0. 設計目標

將所有影片處理腳本與程式（Processors）視為**標準化可執行資源**，實現：

1. **插件化架構**: 支援 Python, Shell, CLI App 及未來 Docker/HTTP 擴展。
2. **版本追溯**: 精確記錄處理器版本號與構建時間 (Build Time)。
3. **產出標準化**: 定義 JSON 輸出規範，確保上下游系統相容。
4. **動態調度**: 排程器根據處理器類型與狀態分配任務。

---

## 1. 核心架構

### 1.1 處理器分類 (Execution Types)

| 類型 | 說明 | 範例 | 執行指令範例 |
|------|------|------|--------------|
| `python` | 依賴 Python 環境的腳本 | ASR (WhisperX), Face (InsightFace), OCR | `python3 script.py --uuid ...` |
| `shell` | Bash 腳本，用於系統工具串接 | Smart Thumbnail (ffmpeg) | `bash script.sh --uuid ...` |
| `cli_app` | 編譯後的二進位程式 | 高效能向量計算器 | `./bin/processor --uuid ...` |
| `docker` | 容器化執行 (未來擴展) | 隔離環境的 AI 推論 | `docker run --rm image ...` |
| `http` | 遠端 API 呼叫 (未來擴展) | 外部雲端服務 | `POST /api/process` |

### 1.2 處理器與服務的關係

```
處理器 (Processors)
   │
   ├── 依賴 ──> [服務資源] (Services: Ollama, Qdrant, GPU)
   │
   ├── 讀取 ──> [資產] (Assets: Video Files)
   │
   └── 產出 ──> [文件] (JSON Results in Storage)
```

---

## 2. 資料庫設計

### 2.1 `processors` 表結構

```sql
CREATE TABLE processors (
    id UUID PRIMARY KEY,                     -- 處理器唯一標識符
    name VARCHAR(100) NOT NULL,              -- 顯示名稱
    category VARCHAR(50) NOT NULL,           -- 分類: preprocessing, audio, visual, text
    execution_type VARCHAR(50) NOT NULL,     -- 執行型態: python, shell, cli_app, docker, http
    entry_point VARCHAR(255) NOT NULL,       -- 腳本路徑或二進位檔名
    version VARCHAR(20) DEFAULT '1.0.0',     -- 語義化版本號
    build_time TIMESTAMPTZ DEFAULT NOW(),    -- 構建/部署時間
    
    description TEXT,                        -- 功能說明
    technical_details TEXT,                  -- 技術手段描述
    output_spec JSONB,                       -- 產出規範 (JSON Schema)
    runtime_config JSONB,                    -- 執行環境配置 (如 venv, timeout, gpu)
    
    is_active BOOLEAN DEFAULT TRUE,          -- 是否啟用
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_processors_category ON processors(category);
CREATE INDEX idx_processors_type ON processors(execution_type);
```

---

## 3. 欄位詳細說明

### 3.1 執行環境配置 (runtime_config)

根據 `execution_type` 不同，此欄位內容也會不同。

**Python**:
```json
{
    "venv_path": "/Users/accusys/momentry_core_0.1/venv",
    "timeout_secs": 7200,
    "requirements": ["torch", "insightface", "easyocr"]
}
```

**Shell**:
```json
{
    "timeout_secs": 300,
    "dependencies": ["ffmpeg", "ffprobe"]
}
```

**Docker**:
```json
{
    "image": "registry.gitlab.com/momentry/ocr:v1.2",
    "gpu": true,
    "shm_size": "4g"
}
```

### 3.2 產出規範 (output_spec)

定義處理器執行成功後應生成的 JSON 結構。

**ASR (WhisperX)**:
```json
{
    "format": "json",
    "structure": {
        "segments": [
            {
                "start": "float",
                "end": "float",
                "text": "string",
                "speaker": "string (optional)"
            }
        ]
    },
    "naming_convention": "{uuid}_asr_{timestamp}.json"
}
```

**Smart Thumbnail**:
```json
{
    "format": "image/jpeg",
    "resolution": "320x(width/height ratio)",
    "storage_path": "thumbnails/{uuid}.jpg",
    "metadata_key": "thumbnail_generated_at"
}
```

---

## 4. 完整註冊範例

### 4.1 Smart Thumbnail (Shell)

```sql
INSERT INTO processors (
    id, name, category, execution_type, entry_point,
    description, technical_details, output_spec, runtime_config
) VALUES (
    '550e8400-e29b-41d4-a716-446655440001',
    'Smart Thumbnail Extractor',
    'preprocessing',
    'shell',
    'scripts/smart_thumbnail.sh',
    'Detects black screens to find the first valid frame of the main content.',
    'Uses FFmpeg `blackdetect` filter to scan first 60s; applies 0.5s offset to avoid transitions.',
    '{
        "format": "image/jpeg",
        "naming_convention": "{uuid}.jpg"
    }'::jsonb,
    '{
        "timeout_secs": 300,
        "dependencies": ["ffmpeg"]
    }'::jsonb
);
```

### 4.2 ASR WhisperX (Python)

```sql
INSERT INTO processors (
    id, name, category, execution_type, entry_point,
    version, build_time, description, technical_details, output_spec, runtime_config
) VALUES (
    '550e8400-e29b-41d4-a716-446655440002',
    'WhisperX Speech Recognition',
    'audio',
    'python',
    'scripts/asr_processor.py',
    '2.1.0',
    '2026-04-20 10:00:00+08', -- 真實構建時間
    'High-accuracy speech-to-text with word-level timestamps and speaker diarization.',
    'WhisperX (faster-whisper) + pyannote-audio for speaker diarization.',
    '{
        "format": "json",
        "structure": {
            "segments": [{"start": "f64", "end": "f64", "text": "str", "speaker": "str"}]
        },
        "naming_convention": "{uuid}_asr_{timestamp}.json"
    }'::jsonb,
    '{
        "venv_path": "/Users/accusys/momentry_core_0.1/venv",
        "timeout_secs": 7200,
        "gpu": true
    }'::jsonb
);
```

### 4.3 OCR (Python)

```sql
INSERT INTO processors (
    id, name, category, execution_type, entry_point,
    description, technical_details, output_spec, runtime_config
) VALUES (
    '550e8400-e29b-41d4-a716-446655440003',
    'EasyOCR Text Recognition',
    'visual',
    'python',
    'scripts/ocr_processor.py',
    'Extracts text blocks with coordinates from video frames.',
    'Uses EasyOCR (local model) with English language support.',
    '{
        "format": "json",
        "structure": {
            "frames": [
                {
                    "frame": "int",
                    "timestamp": "float",
                    "texts": [{"text": "str", "bbox": "object", "confidence": "float"}]
                }
            ]
        },
        "naming_convention": "{uuid}_ocr_{timestamp}.json"
    }'::jsonb,
    '{
        "venv_path": "/Users/accusys/momentry_core_0.1/venv",
        "timeout_secs": 3600,
        "sample_interval_frames": 30
    }'::jsonb
);
```

---

## 5. 標準化執行介面 (Execution Interface)

為了讓排程器 (Scheduler) 能統一呼叫所有類型的處理器，所有處理器必須遵循以下參數規範：

| 參數 | 說明 | 範例值 |
|:---|:---|:---|
| `--uuid` | 影片/任務唯一標識符 | `--uuid 384b0ff4...` |
| `--input` | 輸入媒體檔案路徑 | `--input /data/raw/video.mp4` |
| `--output` | 產出 JSON/檔案目錄 | `--output /data/output/384b...` |
| `--config` | (選用) 額外 JSON 配置路徑 | `--config settings.json` |

**Rust 執行分發邏輯 (Dispatcher)**:

```rust
match processor.execution_type.as_str() {
    "python" => {
        Command::new(venv_python)
            .arg(&entry_point)
            .args(common_args)
            .spawn()?
    }
    "shell" => {
        Command::new("bash")
            .arg(&entry_point)
            .args(common_args)
            .spawn()?
    }
    "cli_app" => {
        Command::new(&entry_point)
            .args(common_args)
            .spawn()?
    }
    _ => bail!("Unsupported execution type")
}
```

---

## 6. 處理器與服務整合 (Integration)

處理器在執行時，需要查詢「服務註冊中心」來獲取依賴資源的配置。

**流程範例**:
1. 排程器啟動 `asr_processor.py`。
2. Python 腳本查詢本地配置檔 (由排程器生成，內容來自 `services` 表)。
3. 腳本獲取 Ollama 的 `endpoint` 與 `model_name`。
4. 腳本執行 Embedding 任務。

這樣實現了**處理器與基礎設施配置的解耦**。

---

## 7. 總結

本設計確立了 Momentry 處理器管理的標準：

| 管理維度 | 實作方式 |
|----------|----------|
| **唯一標識** | UUID (`id` 欄位) |
| **多態執行** | `execution_type` (Python/Shell/CLI/Docker...) |
| **版本控制** | `version` + `build_time` |
| **品質保證** | `output_spec` (JSON Schema 驗證) |
| **環境隔離** | `runtime_config` (Venv, Docker Image) |
| **依賴管理** | 啟動時注入 `services` 配置 |

此架構支持未來無限擴展，新的 AI 模型或工具只需編寫腳本並註冊即可納入系統管轄。
