---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "Processor 升級分析報告"
date: "2026-04-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "processor"
  - "agent"
  - "upgrade"
  - "identity-agent"
  - "三層架構"
ai_query_hints:
  - "查詢 Processor 升級分析報告的內容"
  - "Processor 是否需要升級到 Agent"
  - "Identity Agent 設計方案"
  - "三層架構 Processor 分析"
  - "Face Clustering 升級建議"
  - "ASRX 升級建議"
related_documents:
  - "AI_AGENTS/CORE/AGENT_SPEC.md"
  - "AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_WORKFLOW.md"
  - "PROCESSORS/_CORE/PROCESSOR_RESUME_STRATEGY.md"
---

# Processor 升級分析報告

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-27 | 分析 Processor 是否需要迭代或升級到 Agent | OpenCode | GLM-5 |

---

## 概述

本文檔分析 Momentry Core 系統中所有 Processor 的架構定位，判斷是否需要迭代或升級為 Agent。

---

## 當前狀態

| 項目 | 狀態 |
|------|------|
| Processor 總數 | 17 個 |
| 總代碼行數 | 4947 行 |
| 已添加 Resume 支持 | YOLO, OCR, Face |
| 待添加 Resume 支持 | Pose, CUT, ASRX |

---

## 1. Processor 三層架構分類

根據 `AGENT_SPEC.md` 定義的三層架構：

| 層次 | 名稱 | 特性 | 範例 |
|------|------|------|------|
| **L1** | **Processor (處理器)** | **確定性 (Deterministic)**<br>輸入 A 必得輸出 B | FFmpeg, Whisper, YOLO |
| **L2** | **Rule (規則)** | **邏輯性 (Logic)**<br>基於明確條件、正則表達式、時間軸聚合 | 語句切分，時間重疊計算 |
| **L3** | **Agent (智能體)** | **推論性 (Probabilistic)**<br>依賴 LLM 進行語義理解、決策或生成 | 5W1H 推論，身份解析 |

---

## 2. Processor 分類分析表

| Processor | 文件行數 | 當前層級 | 特性分析 | 是否需要升級 |
|-----------|----------|----------|----------|--------------|
| **asr_processor.py** | 126 | L1 (Processor) | 確定性：Whisper 模型，輸入音頻→輸出文本 | ❌ 不需要升級 |
| **asrx_processor.py** | 124 | L1 (Processor) | 確定性：WhisperX，輸入音頻→輸出 speaker segments | ⚠️ 需與 Identity Agent 結合 |
| **yolo_processor.py** | 483 | L1 (Processor) | 確定性：YOLOv8，輸入帧→輸出檢測結果（已支持 Resume） | ❌ 不需要升級 |
| **ocr_processor.py** | 245 | L1 (Processor) | 確定性：EasyOCR，輸入帧→輸出文字（已支持 Resume） | ❌ 不需要升級 |
| **face_processor.py** | 297 | L1 (Processor) | 確定性：InsightFace，輸入帧→輸出人脸（已支持 Resume） | ❌ 不需要升級 |
| **pose_processor.py** | 178 | L1 (Processor) | 確定性：YOLOv8 Pose，輸入帧→輸出姿态 | ❌ 不需要升級 |
| **cut_processor.py** | 106 | L1 (Processor) | 確定性：PySceneDetect，輸入视频→輸出场景 | ❌ 不需要升級 |
| **face_clustering_processor.py** | 282 | **L2 (Rule)** | 邏輯性：聚类算法，將 Face ID→Person ID | ⚠️ 建議升級到 Identity Agent |
| **face_recognition_processor.py** | 648 | **L2 (Rule)** | 邏輯性：人脸匹配，將 Face→Database Person | ⚠️ 建議升級到 Identity Agent |
| **fast_face_clustering_processor.py** | 334 | L2 (Rule) | 邏輯性：快速聚类版本 | ⚠️ 建議升級到 Identity Agent |
| **story_processor.py** | 325 | **L3 (Agent)** | 推論性：需要 LLM 分析故事结构 | ✅ 已經是 Agent |
| **caption_processor.py** | 291 | L1 (Processor) | 確定性：字幕提取 | ❌ 不需要升級 |
| **lip_processor.py** | 351 | L1 (Processor) | 確定性：唇语识别 | ❌ 不需要升級 |
| **visual_chunk_processor.py** | 431 | L2 (Rule) | 邏輯性：视觉分塊邏輯 | ❌ 不需要升級 |
| **music_segmentation_processor.py** | 138 | L1 (Processor) | 確定性：音乐分割 | ❌ 不需要升級 |
| **audio_taxonomy_processor.py** | 137 | L1 (Processor) | 確定性：音频分类 | ❌ 不需要升級 |
| **unified_synonym_processor.py** | 451 | L2 (Rule) | 邏輯性：同义词扩展 | ❌ 不需要升級 |

---

## 3. 需要迭代的 Processor

### 3.1 Face Clustering Processor

| 項目 | 說明 |
|------|------|
| **當前問題** | 純聚类算法，無法處理跨場景身份識別 |
| **局限** | 1. 無法處理 Speaker 與 Face 的關聯<br>2. 無法處理時間重叠推理<br>3. 無法處理模糊、遮擋情況 |
| **迭代建議** | 升級到 **Identity Agent**（Face+Speaker→Person） |
| **優先級** | High |

---

### 3.2 Face Recognition Processor

| 队目 | 說明 |
|------|------|
| **當前問題** | 簡單匹配，無法處理模糊、遮擋、跨年齡識別 |
| **局限** | 1. 純 embedding 匹配，置信度低<br>2. 無法處理多證據推理<br>3. 無法處理跨場景身份關聯 |
| **迭代建議** | 升級到 **Identity Agent**（多證據推理） |
| **優先級** | High |

---

### 3.3 ASRX Processor

| 队目 | 說明 |
|------|------|
| **當前問題** | Speaker ID 與 Face ID 未關聯 |
| **局限** | 輸出 speaker segments，但無法與 Person ID 绑定 |
| **迭代建議** | 需與 **Identity Agent** 結合 |
| **優先級** | Medium |

---

## 4. 建議升級到 Agent 的 Processor

### 4.1 Identity Agent（核心建議）

| 特性 | 說明 |
|------|------|
| **目的** | 綜合多證據（Face + Speaker + 時間重叠）推論 Person Identity |
| **層級** | L3 (Agent) - 需要推理和决策 |
| **觸發條件** | Face Clustering + ASRX 完成 |
| **輸入** | pre_chunks(face), pre_chunks(asrx), face_clusters, person表 |
| **輸出** | identity 表（person_id → identity_id 映射） |
| **核心邏輯** | 1. 時間重叠匹配（Speaker segment vs Face frames）<br>2. Embedding 相似度計算<br>3. 多證據置信度融合<br>4. LLM 推論（處理模糊情況） |

---

### 4.2 Identity Agent 設計方案

#### 4.2.1 Agent 目標

從多個 processor 的輸出中，推論出「誰是誰」（Who is Who）：

- **Face Processor**: 輸出每一帧的人脸位置和 embedding
- **ASRX Processor**:輸出每個 speaker 的時間段落
- **Face Clustering**: 輸出 Person ID（聚合後的人脸群）
- **Identity Agent**: 推論 Person ID → Identity Name（全局身份）

---

#### 4.2.2 輸入數據

```json
{
  "file_uuid": "384b0ff44aaaa1f14cb2cd63b3fea966",
  "person_id": "Person_17",
  "face_frames": [100, 200, 300, ...],
  "face_embeddings": [emb1, emb2, emb3, ...],
  "speaker_segments": [
    {"start": 10.5, "end": 15.2, "speaker": "SPEAKER_01"},
    {"start": 20.3, "end": 25.1, "speaker": "SPEAKER_02"}
  ],
  "face_clusters": {
    "Person_17": {"frames": [100, 200, ...], "avg_embedding": emb_avg},
    "Person_25": {"frames": [400, 500, ...], "avg_embedding": emb_avg}
  }
}
```

---

#### 4.2.3 核心邏輯

**Step 1: 時間重叠匹配**

```python
def match_speaker_to_person(speaker_segments, person_frames, fps):
    overlaps = []
    for segment in speaker_segments:
        start_frame = int(segment["start"] * fps)
        end_frame = int(segment["end"] * fps)
        overlap_frames = [f for f in person_frames if start_frame <= f <= end_frame]
        overlap_ratio = len(overlap_frames) / len(person_frames)
        if overlap_ratio > 0.5:
            overlaps.append({
                "speaker": segment["speaker"],
                "person_id": person_id,
                "overlap_ratio": overlap_ratio
            })
    return overlaps
```

**Step 2: Embedding 相似度計算**

```python
def calculate_similarity(face_emb, speaker_voice_emb):
    cosine_sim = cosine_similarity(face_emb, speaker_voice_emb)
    return cosine_sim
```

**Step 3: 多證據置信度融合**

```python
def fuse_evidence(face_conf, speaker_conf, time_overlap):
    weighted_conf = 0.4 * face_conf + 0.3 * speaker_conf + 0.3 * time_overlap
    return weighted_conf
```

**Step 4: LLM 推論（處理模糊情況）**

```python
def llm_identity_inference(evidence):
    prompt = f"""
    Given the following evidence:
    - Face similarity: {evidence['face_sim']}
    - Speaker overlap: {evidence['speaker_overlap']}
    - Time overlap: {evidence['time_overlap']}
    
    Should Person_17 and SPEAKER_01 be the same identity?
    Provide confidence score and reasoning.
    """
    response = llm.generate(prompt)
    return response
```

---

#### 4.2.4 輸出格式

```json
{
  "identity_id": "audrey_hepburn_001",
  "identity_name": "Audrey Hepburn",
  "person_ids": ["Person_17", "Person_25"],
  "speaker_ids": ["SPEAKER_01"],
  "confidence": 0.92,
  "evidence": {
    "face_similarity": 0.85,
    "speaker_overlap": 0.78,
    "time_overlap": 0.90,
    "llm_reasoning": "High overlap in face and speaker segments..."
  }
}
```

---

## 5. 實施計畫

### 5.1 Phase 1: Resume 功能補全（已完成部分）

| 任務 | 状态 | 預估工時 |
|------|------|----------|
| Pose Processor 添加 Resume | ⏳ 待處理 | 1h |
| CUT Processor 添加 Resume | ⏳ 待處理 | 1h |

---

### 5.2 Phase 2: Identity Agent 設計與實作

| 任務 | 預估工時 |
|------|----------|
| Identity Agent 設計文檔更新 | 2h |
| Identity Agent API 實作（Rust） | 6h |
| Identity Agent 核心邏輯實作（Python） | 4h |
| Identity Agent LLM 推論模塊 | 3h |
| Identity Agent 測試與驗證 | 2h |

**總計**: 17 小時

---

### 5.3 Phase 3: Processor 整合

| 任務 | 預估工時 |
|------|----------|
| Face Clustering → Identity Agent 輸出調整 | 2h |
| ASRX → Identity Agent 數據流調整 | 2h |
| Face Recognition → Identity Agent 整合 | 3h |

**總計**: 7 小時

---

## 6. 相關文件

| 文件 | 說明 |
|------|------|
| `AGENT_SPEC.md` | Agent 三層架構定義 |
| `FACE_SPEAKER_PERSON_WORKFLOW.md` | Identity Workflow 流程 |
| `PROCESSOR_RESUME_STRATEGY.md` | Resume 功能設計 |
| `JOB_WORKER_IMPLEMENTATION_PLAN.md` | Worker 數據流向修正計畫 |

---

## 7. 檔案位置

| 類型 | 路徑 |
|------|------|
| Processor 目錄 | `/scripts/*_processor.py` |
| Agent 設計文檔 | `/docs_v1.0/AI_AGENTS/` |
| Resume Framework | `/scripts/resume_framework.py` |

---

## 版本資訊

- 版本: V1.0
- 建立日期: 2026-04-27
