momentry_core_0_1/docs/DEVELOPMENT_LOG.md

Momentry Core 開發日誌

文檔維護開始：2026-03-18 ⚠️ 補充說明：事後補記（2026-03-18 以前），僅供參考。未來紀錄將即時記錄，參考價值較高。

---

開發工具

Coding LLM 模型

階段	工具	模型	ID	說明
初期	Claude CLI	-	-	初始專案架構建立
中期	OpenCode	big-pickle	opencode/big-pickle	主要開發協作者

切換記錄：

• 初期使用 Claude CLI 建立專案基本架構
• 中期切換至 OpenCode (big-pickle) 進行主要功能開發

---

2026-03-17

ML 模型選用

Processor	模型	版本/大小	說明
ASR	WhisperX (faster-whisper)	base, int8	語音識別 + 對話分段
CUT	PySceneDetect	0.6.7.1	ContentDetector 場景檢測
YOLO	YOLOv8n	yolov8n.pt (6.2MB)	物體檢測（nano 版本最快）
OCR	EasyOCR	1.7.2	文字識別
Face	OpenCV Haar Cascade	built-in	人臉檢測（無需額外下載）
Pose	YOLOv8n-Pose	yolov8n-pose.pt (6.5MB)	姿態估計（nano 版本）

模型下載：

• YOLOv8n: yolov8n.pt (6.2MB)
• YOLOv8n-Pose: yolov8n-pose.pt (6.5MB)

Python 依賴：

torch==2.8.0
whisperx==3.8.2
ultralytics==8.4.23
scenedetect==0.6.7.1
easyocr==1.7.2
opencv-python==4.13.0.92

---

ASR 實作完成

• 完成 Python ML processor scripts（使用本地模型）

  • asrx_processor.py - whisperx for speaker diarization
  • cut_processor.py - PySceneDetect for scene detection
  • yolo_processor.py - YOLOv8 for object detection
  • ocr_processor.py - EasyOCR for text recognition
  • face_processor.py - OpenCV Haar Cascade for face detection
  • pose_processor.py - YOLOv8 Pose for pose estimation

• 更新 requirements.txt with all dependencies

• 安裝完成：torch 2.8.0, whisperx 3.8.2, ultralytics 8.4.23, scenedetect 0.6.7.1, easyocr 1.7.2, opencv-python 4.13.0.92

• 下載模型：YOLOv8n.pt (6.2MB), YOLOv8n-Pose.pt (6.5MB)

Async Streaming 實作

• 更新 Rust processor modules 使用 async streaming 進行 real-time progress
  • src/core/processor/asr.rs
  • src/core/processor/cut.rs
  • src/core/processor/yolo.rs
  • src/core/processor/ocr.rs
  • src/core/processor/face.rs
  • src/core/processor/pose.rs

測試結果

• 測試影片：BigBuckBunny_320x180.mp4
• ASR: 4 segments
• CUT: 134 scenes
• YOLO: 14315 frames（每幀處理耗時）
• OCR: 40 frames with text
• Face: 44 frames with faces
• Pose: Timeout

---

Warning 清理

修復 clippy warnings：

• 移除未使用的 imports (HashMap in mongodb_db.rs, postgres_db.rs)
• 新增 #[allow(dead_code)] 標註未使用變數
• 新增 Default implementation for MongoDb, QdrantDb
• 將 probe module 重新命名為 ffprobe
• 新增 player feature in Cargo.toml
• 修復 format_in_format_args 警告

---

TUI Progress Window 實作

建立新的 UI module：

• 建立 src/ui/mod.rs
• 建立 src/ui/progress/mod.rs

實作功能：

• ProcessorProgress 結構（追蹤每個 processor 狀態）
• ProgressState 結構（管理所有 processors）
• ProgressUi 結構（ratatui TUI 渲染）
• 整合到 src/main.rs 的 process 命令

TUI 顯示：

┌ Processing: BigBuckBunny_320x180.mp4 ────────────────────────────────────────┐
│ ASR     [████████████] 100% (4 segs)                                       │
│ CUT     [████████████] 100% (134 scenes)                                  │
│ ASRX    [████████████] 100% (0 segs)                                       │
│ YOLO    [██░░░░░░░░░░░]  30% (4200/14315) ETA 2:30                      │
│ OCR     [---------]   0%                                                   │
│ Face    [---------]   0%                                                  │
│ Pose    [---------]   0%                                                   │
└──────────────────────────────────────────────────────────────────────────────┘

---

輸出位置討論

討論 stdout vs stderr vs TUI 的輸出配置：

• 最終結果 → stdout
• Python progress → 需改用 Redis Pub/Sub
• TUI Progress → stderr (ratatui)

---

2026-03-18

Redis Message Bus 設計

討論使用 Redis 作為消息總線，分離 Python 輸出與 Rust TUI 顯示。

設計重點：

1. 頻道命名：momentry:progress:{uuid}
2. 本地 Redis：localhost:6379
3. 失敗策略：完全失效（因 stdout 問題未解決）

UUID 使用時機分析

分析 Redis Key 上使用 UUID 的時機：

全局 Keys（無 UUID）：

• health, stats, jobs 管理

Per-Video Keys（UUID 必要）：

• job:{uuid}, progress:{uuid}, metrics:{uuid}

Per-Processor Keys（UUID + Processor 必要）：

• job:{uuid}:processor:{name}

備份系統整合

參考 docs/SERVICE_ADDITION_GUIDE.md 設計規範，規劃 OutputDir 模組：

1. 環境變數：

   • MOMENTRY_OUTPUT_DIR - JSON 輸出目錄
   • MOMENTRY_BACKUP_DIR - 備份目錄（預設：/Users/accusys/momentry/backup/momentry）
   • MOMENTRY_BACKUP_ENABLED - 啟用備份

2. 命名格式：

   • 備份格式：momentry_data_{YYYYMMDD}_{HHMMSS}_{uuid}.{ext}
   • 校驗和：{filename}.sha256

3. CLI 命令：

   • cargo run -- backup list - 列出備份
   • cargo run -- backup cleanup - 清理舊備份
   • cargo run -- backup verify - 驗證備份

---

監控系統整合

討論將 momentry_core 納入監控系統：

1. Layer 2: Service 監控

   • 新增 momentry_core CLI 檢查

2. Layer 7: Backup 監控

   • 新增 momentry 備份配置

3. Redis 監控

   • 健康檢查
   • Job 狀態監控
   • 即時進度監控

---

實作完成項目

程式碼變更

日期	檔案	變更
2026-03-17	src/core/processor/*.rs	Async streaming 更新
2026-03-17	src/ui/mod.rs	新增 UI module
2026-03-17	src/ui/progress/mod.rs	新增 Progress TUI
2026-03-17	src/main.rs	整合 Progress UI
2026-03-18	src/core/storage/output_dir.rs	新增 OutputDir 模組
2026-03-18	src/core/storage/mod.rs	新增 output_dir export
2026-03-18	src/core/db/redis_client.rs	新增 Redis 客戶端（Hash + Pub/Sub）
2026-03-18	src/core/db/mod.rs	新增 redis_client export

新增檔案

日期	檔案	說明
2026-03-18	docs/MOMENTRY_CORE_REDIS_KEYS.md	Redis Key 設計規範
2026-03-18	docs/MOMENTRY_CORE_MONITORING.md	監控規範（暫定）
2026-03-18	scripts/redis_publisher.py	Redis 訊息發布模組

更新檔案

日期	檔案	說明
2026-03-17	Cargo.toml	新增 player feature
2026-03-17	src/lib.rs	新增 ui module exports
2026-03-18	docs/PENDING_ISSUES.md	新增問題 #2, #3
2026-03-18	src/core/storage/output_dir.rs	預設改為 ./output
2026-03-18	scripts/yolo_processor.py	新增 --uuid 參數 + Redis
2026-03-18	scripts/cut_processor.py	新增 Redis
2026-03-18	scripts/ocr_processor.py	新增 Redis
2026-03-18	scripts/face_processor.py	新增 --uuid 參數 + Redis
2026-03-18	scripts/pose_processor.py	新增 --uuid 參數 + Redis
2026-03-18	scripts/asr_processor.py	新增 --uuid 參數 + Redis
2026-03-18	scripts/asrx_processor.py	新增 --uuid 參數 + Redis
2026-03-18	requirements.txt	新增 redis>=5.0.0
2026-03-18	src/core/processor/yolo.rs	新增 uuid 參數
2026-03-18	src/core/processor/cut.rs	新增 uuid 參數
2026-03-18	src/core/processor/ocr.rs	新增 uuid 參數
2026-03-18	src/core/processor/face.rs	新增 uuid 參數
2026-03-18	src/core/processor/pose.rs	新增 uuid 參數
2026-03-18	src/core/processor/asr.rs	新增 uuid 參數
2026-03-18	src/core/processor/asrx.rs	新增 uuid 參數
2026-03-18	src/main.rs	更新所有 processor 調用傳入 uuid
2026-03-18	Cargo.toml	新增 futures-util 依賴
2026-03-18	src/core/db/redis_client.rs	新增 subscribe_and_callback 方法，密碼認證
2026-03-18	src/ui/progress/mod.rs	新增 update_from_redis 方法
2026-03-18	scripts/redis_publisher.py	新增密碼認證支援
2026-03-18	測試	Redis Pub/Sub 成功運作

---

待解決問題

問題 #1: sqlx async INSERT 不會實際寫入數據庫

• 狀態：待解決
• 影響：store_vector 函數，PVector 存儲

問題 #2: TUI 與 stdout 輸出混合

• 狀態：已解決
• 解決方案：使用 Redis Message Bus
• 進度：
  • ✅ Redis 客戶端 (src/core/db/redis_client.rs)
  • ✅ Python redis_publisher.py
  • ✅ 所有 Python processors 更新完成
  • ✅ 所有 Rust processor 函數更新完成
  • ✅ main.rs 調用更新完成
  • ✅ Rust TUI Redis 訂閱已完成

問題 #3: Redis Message Bus 尚未實作

• 狀態：已解決
• 詳細設計：參考 docs/MOMENTRY_CORE_REDIS_KEYS.md
• 進度：Python 端 + Rust 端均已完成

---

環境變數

# 輸出目錄
MOMENTRY_OUTPUT_DIR=./output        # 預設

# 備份
MOMENTRY_BACKUP_ENABLED=false       # 預設
MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry

# Redis（未來實作）
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=accusys

---

數據庫

• PostgreSQL: postgres://accusys@localhost:5432/momentry
• Redis: localhost:6379（待實作）
• Qdrant: localhost:6333

---

指令範例

# 註冊視頻
cargo run -- register /path/to/video.mp4

# 處理視頻
cargo run -- process <uuid>

# 列出備份
cargo run -- backup list

# 清理備份
cargo run -- backup cleanup

# 驗證備份
cargo run -- backup verify

# 查看狀態
cargo run -- status

# API Server
cargo run -- server --host 0.0.0.0 --port 3000

---

2026-03-18 (進行中)

Redis Message Bus 實作

問題：TUI 與 Python stdout 輸出混合，導致 TUI 顯示混亂

解決方案：使用 Redis Pub/Sub 作為訊息匯流排

實作內容：

元件	檔案	狀態
Redis 客戶端	src/core/db/redis_client.rs	✅
Progress 訂閱	src/main.rs	✅
UI 更新	src/ui/progress/mod.rs	✅
Python Publisher	scripts/redis_publisher.py	✅
Python Processors	7 個 scripts/*_processor.py	✅
Rust 函數	src/core/processor/*.rs	✅

流程：

Python Processor ──(Redis Pub)──> Redis ──(Subscribe)──> Rust TUI

測試結果：

• Redis 連線 ✅
• 密碼認證 ✅
• 即時進度發布 ✅
• TUI 即時更新 ✅

新增依賴：

• futures-util = "0.3" (Cargo.toml)
• redis >= 5.0.0 (requirements.txt)

---

2026-03-18 (HTTP API)

HTTP API 實作

問題：TUI 運作正常但使用者偏好 HTTP API 來查詢進度

解決方案：建立 HTTP 端點 + Redis Hash 儲存

實作內容：

元件	檔案	變更
HTTP 端點	src/api/server.rs	新增 /api/v1/progress/:uuid
Redis Hash 查詢	src/core/db/redis_client.rs	新增 get_processor_status 方法
Progress 儲存	src/main.rs	新增 Redis HSET 儲存進度

API 端點：

GET /api/v1/progress/:uuid

Response:
{
  "uuid": "5dea6618a606e7c7",
  "processors": [
    {"name": "asr", "status": "complete", "current": 0, "total": 0, "message": "7 segments"},
    {"name": "cut", "status": "complete", "current": 134, "total": 134, "message": "134 scenes"},
    {"name": "yolo", "status": "complete", "current": 14300, "total": 14315, "message": "..."},
    ...
  ]
}

流程：

Python Processor ──(Redis Pub)──> Redis ──(Subscribe)──> Rust TUI
                              └──(HSET)──> Redis Hash
                                               │
HTTP Client ──(GET /progress/:uuid)──> Rust API ─(HGETALL)──> Redis Hash

測試結果：

• ✅ 編譯成功
• ✅ API 伺服器啟動 (port 3002)
• ✅ 即時進度查詢
• ✅ 完整流程測試 (BigBuckBunny_320x180.mp4)

除錯記錄：

1. 語法錯誤：main.rs 有重複程式碼區塊 (lines 297-322)，已移除
2. DB 連線池：從 5 增加到 10 個連線
3. PostgreSQL 狀態：處理 shutdown 狀態，殺掉 stale 連線

新增變更：

• src/api/server.rs - 新增進度端點
• src/core/db/redis_client.rs - 新增 get_processor_status 方法
• src/core/db/postgres_db.rs - 連線池 5→10
• src/main.rs - Redis Hash 儲存 + 語法修復

使用方式：

# 啟動 API 伺服器
cargo run --bin momentry -- server --host 127.0.0.1 --port 3002

# 註冊影片
cargo run --bin momentry -- register ~/test_video/BigBuckBunny_320x180.mp4

# 處理影片
cargo run --bin momentry -- process <uuid>

# 查詢進度
curl http://127.0.0.1:3002/api/v1/progress/<uuid>