---
document_type: "standard_doc"
service: "MOMENTRY_CORE"
title: "AI Agent 設計規範"
date: "2026-04-27"
version: "V1.1"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "AI Agent"
  - "設計規範"
  - "三層架構"
  - "processing_status"
ai_query_hints:
  - "查詢 AI Agent 設計規範的內容"
  - "AI Agent 的三層架構定義"
  - "Agent 類型列表"
  - "Agent 進度追蹤方式"
  - "processing_status JSONB agents 字段"
  - "如何設計 AI Agent"
---

# AI Agent 設計規範 (Agent Design Specification)

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 定義 Momentry Core 中 AI Agent 的標準設計與職責 | OpenCode | OpenCode |
| V1.1 | 2026-04-27 | 添加 Agent 類型列表和進度追蹤（processing_status JSONB） | OpenCode | GLM-5 |

---

## 1. 核心概念

在 Momentry Core 系統中，處理邏輯分為三個層次，本規範專注於第三層：

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

---

## 2. Agent 職責 (Responsibilities)

AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
**注意**: 在系統架構中，Agent 被視為一種 **資源 (Resource)**，與 Processor 和 Service 統一由 **資源註冊中心 (Resource Registry)** 管理。

1. **語義理解 (Semantic Understanding)**: 將非結構化數據（如 OCR 文字、雜訊 ASR 文本）轉化為結構化標籤 (5W1H)。
2. **跨模態匹配 (Cross-Modal Matching)**: 綜合視覺、聽覺和文本證據，判斷「畫面中的臉」是否為「資料庫中的人」。
3. **內容生成 (Content Generation)**: 為影片片段生成自然的摘要或標題。
4. **查詢解析 (Query Parsing)**: 將用戶的自然語言請求轉譯為系統可執行的 API 調用序列。

---

## 3. 標準設計結構 (Design Structure)

所有 AI Agent 的設計文件必須遵循以下結構：

### 3.1 檔案命名
* **格式**: `[AGENT_TYPE]_[PURPOSE].md`
* **範例**: `CONTEXT_5W1H_INFERENCE.md`

### 3.2 文件內容

#### 3.2.1 Agent 目標 (Goal)
簡短描述此 Agent 解決的業務問題。
> **範例**: 從雜亂的 YOLO 標籤和 OCR 文本中推論場景的「地點」和「天氣」資訊。

#### 3.2.2 輸入數據 (Input)
定義 Agent 接收的數據格式。通常來自 Processor 輸出或 Rule 產物。
* **來源**: `PROCESSORS/` 或 `CHUNKING/`
* **格式**: JSON, Text, List of Frames.

#### 3.2.3 核心邏輯 (Core Logic: Prompt / Workflow)
這是 Agent 的靈魂。
* **單一 Prompt Agent**: 提供完整的 System Prompt。
    ```markdown
    ## System Prompt
    You are a scene analysis assistant...
    ```
* **多步 Workflow Agent**: 提供步驟圖或偽代碼。
    ```mermaid
    graph TD
      A[Start] --> B[Extract Entities]
      B --> C[Verify with Knowledge Base]
      C --> D[Output Result]
    ```

#### 3.2.4 輸出格式 (Output)
定義 Agent 產出的結構化數據 (通常為 JSON)。
```json
{
  "who": ["Actor Name"],
  "what": ["Action"],
  "confidence": 0.95
}
```

#### 3.2.5 模型配置 (Model Config)
建議使用的模型類型及其原因。
* **推理模型 (Reasoning)**: `o1`, `R1` (用於複雜邏輯判斷)
* **生成模型 (Generation)**: `GPT-4o`, `Sonnet` (用於摘要)
* **本地模型 (Local)**: `Llama-3`, `Qwen` (用於隱私數據)

---

## 4. 開發工作流 (Development Workflow)

1. **定義需求**: 確定是否需要 AI 介入 (若規則可解，優先使用 Rule)。
2. **撰寫 Prompt**: 在文檔中迭代 Prompt，直到達到穩定輸出。
3. **工具串接**: 若需要外部數據 (如 TMDB)，定義 Tool 定義。
4. **實作封裝**: 將 Prompt/Workflow 封裝為 Rust/Python 模組，透過 API 調用。

---

## 5. 相關文件

* `UNIFIED_RESOURCE_REGISTRY.md` - 系統統一資源管理架構 (Agents 作為資源註冊)。
* `AI_DRIVEN_PROCESSOR_CONTRACT.md` - Processor 層級的整合合約。
* `CHUNKING_ARCHITECTURE.md` - Rule 層級的架構。
* `FILE_IDENTITY_API_DESIGN.md` - 全局架構。

---

## 6. Agent 類型列表

| Agent | 目的 | 觸發條件 | 文檔 |
|-------|------|----------|------|
| **Translation Agent** | 多語言翻譯 | 用戶手動觸發 | `AI_AGENTS/TRANSLATION/TEXT_TRANSLATION.md` |
| **5W1H Agent** | 場景分析（Who/What/When/Where/Why/How） | Rule 3 完成 | `AI_AGENTS/SUMMARIZATION/CHUNK_RULE_4_SUMMARY.md` |
| **Identity Agent** | 身份解析（Face/Speaker → Person） | Face/Speaker 完成 | `AI_AGENTS/IDENTITY/FACE_SPEAKER_PERSON_WORKFLOW.md` |

---

## 7. Agent 進度追蹤

從 V1.2 起，所有 Agent 任務透過 `processing_status` JSONB 的 `agents` 字段追蹤。

### JSONB 範例

```json
{
  "agents": {
    "5w1h": {
      "status": "running",
      "scenes_processed": 5,
      "scenes_total": 1332,
      "progress_pct": 0.4
    }
  }
}
```

### 查詢 Agent 進度

```sql
SELECT processing_status->'agents'->'5w1h'->>'status' FROM videos WHERE uuid = 'xxx';
```

詳細規範請參考: `REFERENCE/PROCESSING_STATUS_JSONB_SPEC.md`

---

## 版本資訊

* 版本: V1.1
* 建立日期: 2026-04-25
* 文件更新: 2026-04-27
