feat: backup architecture docs, source code, and scripts

docs_v1.0/AI_AGENTS/CORE/AGENT_SPEC.md

@@ -0,0 +1,116 @@
+# 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