docs: update docs_v1.0/ documentation
- Fix markdown lint issues (MD030, MD047, MD051, MD028, MD005) - Update AI agents, architecture, implementation docs - Add new identity, face recognition, and API documentation - Remove deprecated face/person API guides
This commit is contained in:
Warren
@@ -1,10 +1,33 @@
|
||||
---
|
||||
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.0 |
|
||||
| 文件版本 | V1.1 |
|
||||
|
||||
---
|
||||
|
||||
@@ -13,6 +36,7 @@
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-04-25 | 定義 Momentry Core 中 AI Agent 的標準設計與職責 | OpenCode | OpenCode |
|
||||
| V1.1 | 2026-04-27 | 添加 Agent 類型列表和進度追蹤（processing_status JSONB） | OpenCode | GLM-5 |
|
||||
|
||||
---
|
||||
|
||||
@@ -33,10 +57,10 @@
|
||||
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 調用序列。
|
||||
1. **語義理解 (Semantic Understanding)**: 將非結構化數據（如 OCR 文字、雜訊 ASR 文本）轉化為結構化標籤 (5W1H)。
|
||||
2. **跨模態匹配 (Cross-Modal Matching)**: 綜合視覺、聽覺和文本證據，判斷「畫面中的臉」是否為「資料庫中的人」。
|
||||
3. **內容生成 (Content Generation)**: 為影片片段生成自然的摘要或標題。
|
||||
4. **查詢解析 (Query Parsing)**: 將用戶的自然語言請求轉譯為系統可執行的 API 調用序列。
|
||||
|
||||
---
|
||||
|
||||
@@ -45,8 +69,8 @@ AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
|
||||
所有 AI Agent 的設計文件必須遵循以下結構：
|
||||
|
||||
### 3.1 檔案命名
|
||||
* **格式**: `[AGENT_TYPE]_[PURPOSE].md`
|
||||
* **範例**: `CONTEXT_5W1H_INFERENCE.md`
|
||||
* **格式**: `[AGENT_TYPE]_[PURPOSE].md`
|
||||
* **範例**: `CONTEXT_5W1H_INFERENCE.md`
|
||||
|
||||
### 3.2 文件內容
|
||||
|
||||
@@ -56,17 +80,17 @@ AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
|
||||
|
||||
#### 3.2.2 輸入數據 (Input)
|
||||
定義 Agent 接收的數據格式。通常來自 Processor 輸出或 Rule 產物。
|
||||
* **來源**: `PROCESSORS/` 或 `CHUNKING/`
|
||||
* **格式**: JSON, Text, List of Frames.
|
||||
* **來源**: `PROCESSORS/` 或 `CHUNKING/`
|
||||
* **格式**: JSON, Text, List of Frames.
|
||||
|
||||
#### 3.2.3 核心邏輯 (Core Logic: Prompt / Workflow)
|
||||
這是 Agent 的靈魂。
|
||||
* **單一 Prompt Agent**: 提供完整的 System Prompt。
|
||||
* **單一 Prompt Agent**: 提供完整的 System Prompt。
|
||||
```markdown
|
||||
## System Prompt
|
||||
You are a scene analysis assistant...
|
||||
```
|
||||
* **多步 Workflow Agent**: 提供步驟圖或偽代碼。
|
||||
* **多步 Workflow Agent**: 提供步驟圖或偽代碼。
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start] --> B[Extract Entities]
|
||||
@@ -86,31 +110,71 @@ AI Agent 負責處理那些傳統程式難以精確定義規則的任務。
|
||||
|
||||
#### 3.2.5 模型配置 (Model Config)
|
||||
建議使用的模型類型及其原因。
|
||||
* **推理模型 (Reasoning)**: `o1`, `R1` (用於複雜邏輯判斷)
|
||||
* **生成模型 (Generation)**: `GPT-4o`, `Sonnet` (用於摘要)
|
||||
* **本地模型 (Local)**: `Llama-3`, `Qwen` (用於隱私數據)
|
||||
* **推理模型 (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 調用。
|
||||
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` - 全局架構。
|
||||
* `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.0
|
||||
- 建立日期: 2026-04-25
|
||||
* 版本: V1.1
|
||||
* 建立日期: 2026-04-25
|
||||
* 文件更新: 2026-04-27
|
||||
|
||||
Reference in New Issue
Block a user