warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
4d75b2e2519c3837ed9f25f0c9384e2440e42ed4
momentry_core/docs_v1.0/ARCHITECTURE/TERMINOLOGY_MAPPING.md
Warren 4d75b2e251 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
2026-04-30 15:10:41 +08:00

9.2 KiB
Raw Blame History

document_type, service, title, date, version, status, owner, created_by, tags, ai_query_hints
document_type service title date version status owner created_by tags ai_query_hints
architecture_design MOMENTRY_CORE 術語對照表 (Terminology Mapping) 2026-04-22 V1.0 active Warren OpenCode
術語對照表
查詢 術語對照表 (Terminology Mapping) 的內容
術語對照表 (Terminology Mapping) 的主要目的是什麼？
如何操作或實施 術語對照表 (Terminology Mapping)？

術語對照表 (Terminology Mapping)

項目 內容
建立者 OpenCode
建立時間 2026-04-22
文件版本 V1.0
相關文件 DESIGN_IMPLEMENTATION_GAP.md
ARCHITECTURE_OVERVIEW.md
CHUNKING_ARCHITECTURE.md

版本歷史

版本 日期 目的 操作人 工具/模型
V1.0 2026-04-22 創建術語對照表 OpenCode OpenCode / deepseek-v3.2

1. 核心原則

當設計與實現出現矛盾時，以實際的 Rust 代碼實現為最高權威。

本文檔提供設計文檔中的術語與實際 Rust 代碼實現之間的對照關係，用於：

  1. 統一所有架構文檔的術語使用
  2. 指導新文檔的撰寫
  3. 作為代碼審查的參考標準

2. 分片類型 (Chunk Type) 對照

2.1 設計與實現對照表

設計概念 設計值 實現值 實現狀態 說明
時間基準分片 time TimeBased ✅ 已實現 基於固定時間間隔的分片
句子級分片 sentence Sentence ✅ 已實現 基於 ASR 轉錄的句子邊界
場景級分片 scene Cut ⚠️ 部分實現 基於 CUT 算法的場景邊界檢測
視覺物件級分片 visual (未實現) ❌ 未實現 基於 YOLO 的物件檢測分片
摘要級分片 summary Story ⚠️ 概念調整 基於分片聚合的敘事重建
軌跡追蹤分片 (未定義) Trace ✅ 已實現 人物/物件軌跡追蹤分片

2.2 實際 Rust 代碼定義

// src/core/chunk/mod.rs 中的 ChunkType 枚舉
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ChunkType {
    TimeBased,    // 時間基準分片
    Sentence,     // 句子級分片
    Cut,          // 場景級分片 (基於 CUT 算法)
    Trace,        // 軌跡追蹤分片
    Story,        // 敘事分片 (原設計的摘要分片)
}

2.3 文檔撰寫指南

  1. 新文檔撰寫：一律使用實現值 (TimeBased, Sentence, Cut, Trace, Story)
  2. 舊文檔更新：將設計值替換為實現值，並添加註釋說明
  3. 狀態標記：對於未實現或部分實現的功能，使用狀態標記 (✅, ⚠️, ❌)

3. 分片規則 (Chunk Rule) 對照

3.1 設計與實現對照表

規則編號 設計名稱 實現名稱 實現狀態 對應 ChunkType
Rule 1 句子級分片 Rule 1 (句子分片) ✅ 已實現 Sentence
Rule 2 視覺物件級分片 (未實現) ❌ 未實現 (未實現)
Rule 3 場景級分片 Rule 3 (場景分片) ⚠️ 部分實現 Cut
Rule 4 摘要級分片 Rule 4 (敘事分片) ⚠️ 概念調整 Story

3.2 實際實現狀態

  1. Rule 1: 完整實現於 src/core/chunk/rule1_ingest.rs
  2. Rule 2: 未實現，僅有設計概念
  3. Rule 3: 部分實現，使用 CUT 算法檢測場景邊界
  4. Rule 4: 概念調整，實現為基於分片聚合的敘事重建

4. 數據模型對照

4.1 設計中的數據模型

{
  "chunk_type": "sentence|visual|scene|summary",  // 設計值
  "content": {
    "text": "轉錄文本",
    "visual_objects": ["person", "car", "dog"],
    "scene_context": "辦公室會議",
    "summary": "會議討論項目進度"
  }
}

4.2 實際實現的數據模型

// src/core/chunk/mod.rs 中的 Chunk 結構
pub struct Chunk {
    pub id: i64,
    pub uuid: String,
    pub video_record_id: i64,
    pub chunk_type: ChunkType,  // 實現值: TimeBased|Sentence|Cut|Trace|Story
    pub start_time: f64,
    pub end_time: f64,
    pub content: serde_json::Value,  // 動態 JSON 內容
    pub embedding: Option<Vec<f32>>,
    pub created_at: DateTime<Utc>,
}

4.3 關鍵差異

  1. 類型系統：設計使用字符串枚舉，實現使用 Rust 枚舉
  2. 內容結構：設計有固定字段，實現使用動態 JSON
  3. 時間表示：設計使用時間戳+時長，實現使用開始/結束時間

5. 處理管道對照

5.1 設計管道

ASR → OCR → YOLO → CUT → LLM → 分片生成

5.2 實際管道

ASR → OCR → YOLO → CUT → 分片生成
                    ↓
                LLM（尚未集成）

5.3 關鍵差異點

  1. LLM 集成：設計中有完整 LLM 階段，實際尚未集成
  2. 處理順序：實際實現根據技術依賴關係調整了順序
  3. 並行處理：實際實現有更多並行處理優化

6. 文檔更新指南

6.1 更新原則

  1. 優先級：以實際 Rust 代碼實現為準
  2. 一致性：所有文檔使用相同的術語
  3. 狀態標記：明確標記功能實現狀態
  4. 版本控制：記錄術語變更歷史

6.2 具體更新操作

6.2.1 分片類型更新

舊術語 新術語 更新說明
chunk_type: "sentence" chunk_type: "Sentence" 保持 PascalCase
chunk_type: "visual" chunk_type: (未實現) 標記為未實現
chunk_type: "scene" chunk_type: "Cut" 使用實際實現值
chunk_type: "summary" chunk_type: "Story" 使用實際實現值

6.2.2 規則名稱更新

舊術語 新術語 更新說明
Rule 2 (visual) Rule 2 (未實現) 標記為未實現
Rule 3 (scene) Rule 3 (場景分片) 使用中文描述
Rule 4 (summary) Rule 4 (敘事分片) 使用中文描述

6.3 狀態標記系統

標記 含義 使用場景
✅ 已完整實現 功能完全按照設計實現
⚠️ 部分實現 功能部分實現，有差異
❌ 未實現 功能尚未實現
🔄 概念調整 設計概念在實現中調整

7. 使用示例

7.1 正確示例

## 分片類型

Momentry Core 支持以下分片類型：

1. **TimeBased** (時間基準分片) ✅ 已實現
2. **Sentence** (句子級分片) ✅ 已實現  
3. **Cut** (場景級分片) ⚠️ 部分實現
4. **Trace** (軌跡追蹤分片) ✅ 已實現
5. **Story** (敘事分片) ⚠️ 概念調整

**注意**：設計中的 `visual` 分片尚未實現，設計中的 `summary` 分片已調整為 `Story` 分片。

7.2 錯誤示例

## 分片類型

Momentry Core 支持以下分片類型：

1. sentence (句子級分片)
2. visual (視覺物件級分片)
3. scene (場景級分片) 
4. summary (摘要級分片)

8. 維護與更新

8.1 更新流程

  1. 代碼變更：當 Rust 代碼中的類型定義變更時
  2. 文檔更新：根據本文檔更新所有相關文檔
  3. 一致性檢查：運行 scripts/check_architecture_docs.py 驗證
  4. 版本更新：更新本文檔的版本歷史

8.2 審查要點

  1. 術語一致性：所有文檔是否使用相同的術語
  2. 狀態準確性：功能實現狀態是否準確標記
  3. 文檔完整性：所有重要概念是否都有對照說明

8.3 自動化檢查

# 運行架構文檔一致性檢查
python3 scripts/check_architecture_docs.py --check-terminology

9. 結論

本文檔作為 Momentry Core 架構文檔的術語標準，確保：

  1. 設計與實現一致性：文檔準確反映實際代碼狀態
  2. 文檔統一性：所有文檔使用相同的術語體系
  3. 可維護性：提供明確的更新和維護指南

核心原則重申：在出現矛盾時，實際的 Rust 代碼實現是最高權威，設計文檔應反映實際實現狀態並指導未來改進方向。

附錄 A：快速參考

A.1 分片類型快速參考

使用場景 推薦術語 狀態
時間基準分片 TimeBased ✅
句子級分片 Sentence ✅
場景級分片 Cut ⚠️
軌跡追蹤分片 Trace ✅
敘事分片 Story ⚠️
視覺物件分片 (標記為未實現) ❌

A.2 規則名稱快速參考

規則 推薦名稱 狀態
Rule 1 句子分片規則 ✅
Rule 2 (標記為未實現) ❌
Rule 3 場景分片規則 ⚠️
Rule 4 敘事分片規則 ⚠️

A.3 狀態標記快速參考

  • ✅：使用 chunk_type: "Sentence" (已實現)
  • ⚠️：使用 chunk_type: "Cut" ⚠️ 部分實現 (部分實現)
  • ❌：標記為 "未實現" 或 "設計概念" (未實現)
  • 🔄：說明概念調整原因 (概念調整)

文件版本: V1.0
最後更新: 2026-04-22
維護者: OpenCode

Reference in New Issue View Git Blame Copy Permalink