# 統一資源註冊架構 (Unified Resource Registry Architecture)

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 定義 Service、Processor、Agent 為統一資源 (Resource) 的註冊與管理架構 | OpenCode | OpenCode |

---

## 1. 核心設計理念

在 Momentry Core 系統中，所有用於處理、分析和管理數據的組件，統一抽象為 **「資源 (Resource)」**。
這種設計允許系統以統一的方式發現、調度、監控和管理不同類型的組件。

### 1.1 資源三大分類 (Resource Types)

| 資源類型 | 英文代號 | 定義 | 特性 | 範例 |
|----------|----------|------|------|------|
| **服務** | **Service** | 系統運行依賴的基礎設施或長駐進程。 | 長生命週期 (Long-lived), 狀態保持。 | PostgreSQL, Redis, TMDB API |
| **處理器** | **Processor** | 執行確定性數據轉換的模組。 | 短生命週期 (Task-based), 輸入 A -> 輸出 B, 無狀態。 | FFmpeg (Probe), YOLO, Whisper |
| **智能體** | **Agent** | 依賴 LLM 進行語義推論或決策的模組。 | 短生命週期 (Task-based), 機率性輸出, 依賴 Prompt/Context。 | 5W1H Inference, Summarization, Identity Resolution |

---

## 2. 通用資源模型 (Universal Resource Model)

所有資源在註冊表中共享以下核心結構：

```json
{
  "resource_id": "unique_identifier",
  "resource_type": "processor | agent | service",
  "category": "visual | speech | metadata | logic",
  
  "capabilities": ["capability_1", "capability_2"],
  "status": "idle | busy | offline | error",
  
  "config": {
    "model": "yolov8n",
    "timeout": 60,
    "gpu_required": false
  },
  
  "health_check": {
    "endpoint": "/health",
    "interval_seconds": 30,
    "last_success": "2026-04-25T10:00:00Z"
  },
  
  "metadata": {
    "version": "1.0.0",
    "description": "..."
  }
}
```

---

## 3. 資源生命週期 (Resource Lifecycle)

1. **註冊 (Registration)**:
    * 組件啟動時向 **Resource Registry** 報到，聲明其 ID、類型和能力。
    * *範例*: Agent 啟動，註冊 `resource_type: "agent"`, `capabilities: ["summarize_text"]`。
2. **發現 (Discovery)**:
    * 調度器 (Scheduler) 根據任務需求查詢 Registry 尋找合適的資源。
    * *範例*: 任務需要「語音轉文字」，查詢 `capabilities: ["audio_to_text"]`。
3. **分配與執行 (Allocation & Execution)**:
    * 狀態變為 `busy`，接收任務並執行。
4. **健康檢查 (Health Monitoring)**:
    * Registry 定期 Ping 資源。若無回應，標記為 `offline`。
5. **登出 (Deregistration)**:
    * 組件關閉或崩潰時從 Registry 移除。

---

## 4. 資源註冊表設計 (Registry Schema)

### 4.1 資料庫表結構 (SQL)

```sql
CREATE TABLE resources (
    resource_id       VARCHAR(64) PRIMARY KEY,
    resource_type     VARCHAR(20) NOT NULL,  -- 'processor', 'agent', 'service'
    category          VARCHAR(50),           -- 'visual', 'speech', 'logic'
    
    name              VARCHAR(100) NOT NULL,
    description       TEXT,
    
    capabilities      JSONB,                 -- Array of strings
    config            JSONB,                 -- Resource specific config
    metadata          JSONB,                 -- Version, author, etc.
    
    status            VARCHAR(20) DEFAULT 'offline',
    last_heartbeat    TIMESTAMPTZ,
    
    created_at        TIMESTAMPTZ DEFAULT NOW(),
    updated_at        TIMESTAMPTZ DEFAULT NOW()
);

-- 索引優化查詢
CREATE INDEX idx_res_type ON resources(resource_type);
CREATE INDEX idx_res_status ON resources(status);
CREATE INDEX idx_res_caps ON resources USING GIN(capabilities);
```

### 4.2 API 端點設計

| Method | Endpoint | 說明 |
|--------|----------|------|
| `POST` | `/api/v1/resources/register` | 資源啟動時註冊 |
| `POST` | `/api/v1/resources/:id/heartbeat` | 發送心跳 |
| `GET` | `/api/v1/resources` | 查詢所有資源 (支援過濾) |
| `GET` | `/api/v1/resources?capability=summarize` | 查詢具備特定能力的資源 |
| `POST` | `/api/v1/resources/:id/deregister` | 資源關閉時登出 |

---

## 5. 實作建議

### 5.1 Processor 實作 (確定性)
* 通常由 Python 腳本或 Rust 二進制執行。
* 啟動時呼叫 `POST /resources/register`，宣告如 `["video_to_frames", "detect_objects"]`。

### 5.2 Agent 實作 (機率性)
* 通常封裝為具備 LLM Context 的服務。
* 啟動時呼叫 `POST /resources/register`，宣告如 `["summarize_text", "extract_5w1h"]`。
* **重點**: 在 `metadata` 中記錄使用的 LLM 模型名稱 (e.g., `gpt-4o`, `llama3`)。

### 5.3 Service 實作 (基礎設施)
* 通常由 Docker Compose 或 Systemd 管理。
* 可透過 Sidecar 或定期腳本進行註冊與心跳更新。

---

## 6. 與其他架構的關係

* **Job/Task Scheduler**: 任務調度器依賴 Resource Registry 來尋找誰能執行任務。
* **Configuration Management**: 資源的詳細參數 (如 API Key, Threshold) 應存在 Config 中心，Registry 僅儲存引用或摘要。
* **Monitoring**: Prometheus/Grafana 應抓取 Registry 狀態來展示系統資源健康度儀表板。

## 7. 關聯文檔

本目錄整合了原有的 Processor 與 Service 架構，並納入新的 Agent 架構：
* `PROCESSOR_REGISTRY_ARCHITECTURE.md` - 舊版處理器註冊設計 (已整合)。
* `SERVICE_REGISTRY_ARCHITECTURE.md` - 舊版服務註冊設計 (已整合)。
* `PROCESSOR_LIFECYCLE.md` - 處理器生命週期 (資源生命週期的子集)。

---

## 版本資訊

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