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

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 定義 Momentry Core 中 AI Agent 的標準設計與職責 | OpenCode | OpenCode |

---

## 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` - 全局架構。

---

## 版本資訊

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