momentry_studio/docs/ARCHITECTURE.md

Momentry Studio Tauri GUI 架构文档

生成时间: 2026-10-10 版本: v1.0.0

---

1. 四大模块总览

┌─────────────────────────────────────────────────────────────────────┐
│                         Momentry Studio GUI                          │
│                      (Vue 3 + TypeScript + Vite)                     │
└────────────────────────────┬────────────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐
│ Search Module │  │ File Prep/    │  │ Admin Module  │  │ File Mgmt    │
│               │  │ Processing    │  │               │  │ Module       │
│ SearchView    │  │ LibraryView   │  │ AdminView     │  │ ClientView   │
└───────┬───────┘  └───────┬───────┘  └───────┬───────┘  └──────┬───────┘
        │                  │                  │                  │
        └──────────────────┼──────────────────┼──────────────────┘
                           │                  │
                ┌──────────┴──────────┐       │
                │                     │       │
                ▼                     ▼       ▼
        ┌───────────────┐    ┌──────────────┐ ┌──────────────┐
        │ Core API      │    │ MarkBase API │ │ Local SQLite │
        │ (localhost:   │    │ (localhost:  │ │ (demo.sqlite)│
        │  3002)        │    │  11438)      │ │              │
        └───────┬───────┘    └───────┬──────┘ └──────────────┘
                │                    │
                │   /api/v1/*        │   /api/v2/*
                │   (Momentry Core)  │   (MarkBase Core)
                │                    │
                └────────────────────┼────────────────────┐
                                     │                    │
                          ┌──────────┴──────────┐        │
                          │  Studio Proxy       │        │
                          │  (localhost:8888)   │        │
                          │  - v1/v2 gateway    │        │
                          │  - API key inject   │        │
                          │  - Face thumbnail   │        │
                          │  - Search history   │        │
                          │  - Bookmarks        │        │
                          └─────────────────────┘        │
                                                         │
                          ┌──────────────────────────────┘
                          │
              ┌───────────┴────────────┐
              │  Tauri IPC Commands    │
              │  (19 Rust commands)    │
              │  - search_llm_smart    │
              │  - get_files           │
              │  - get_people          │
              │  - register_file       │
              │  - process_file        │
              │  - update_identity     │
              │  - get_thumbnail       │
              │  - etc.                │
              └────────────────────────┘

---

2. 模块详解

2.1 Search 模块

职责: 提供多模式搜索功能（Keyword, Semantic, Visual, Agent, People）

前端组件:

• SearchView.vue - 主搜索界面
• VideoPlayer.vue - 搜索结果播放
• useSearchHistory.ts - 搜索历史管理
• useBookmarks.ts - 书签管理

API 端点:

// v1 端点 (Momentry Core API)
/api/v1/search/keyword          // 关键字搜索
/api/v1/search/semantic         // 语义搜索
/api/v1/search/llm-smart        // LLM 智能搜索
/api/v1/search/people           // 人物搜索
/api/v1/agents/search           // Agent 搜索
/api/v1/search/vlm/scenes       // Scene VLM 搜索
/api/v1/search/vlm/traces       // Trace VLM 搜索

// v1 端点 (本地处理)
/api/v1/search-history          // 搜索历史
/api/v1/bookmarks               // 书签

数据流:

用户输入 → SearchView → apiCall() → Core API
    ↓
返回结果 → mergeResults() → 结果卡片
    ↓
History/Bookmarks → SQLite (demo.sqlite)

数据库:

• search_history (SQLite) - 搜索历史
• bookmarks (SQLite) - 书签

关键特性:

1. 多模式搜索: Keyword, Semantic, Visual, Agent, People 五种模式
2. OCR 合并: 相似文本自动合并，减少重复
3. 搜索历史: SQLite 持久化，支持 Pin/Rename/Delete
4. 书签系统: 快速访问常用搜索

---

2.2 文件准备/处理模块

职责: 管理原始档案的处理流程，从注册到完成

前端组件:

• LibraryView.vue - 文件列表和处理控制
• PeopleView.vue - 人物管理
• PersonDetailView.vue - 人物详情

API 端点:

// v1 端点
/api/v1/files/register              // 注册文件
/api/v1/file/{uuid}/process          // 处理文件
/api/v1/unregister                   // 注销文件
/api/v1/file/{uuid}/sync-status      // 同步状态
/api/v1/progress/{uuid}              // 处理进度
/api/v1/stats/pipeline/{uuid}        // Pipeline 统计
/api/v1/stats/file/{uuid}            // 文件统计
/api/v1/file/{uuid}/processor-counts // 处理器统计
/api/v1/re-scan                      // 重新扫描

处理 Pipeline:

Rule 1 Ingestion → Face Tracing → Face Dedup → 
TKG Nodes → TKG Edges → Rule 2 Ingestion → 
VLM Summary → Scene VLM

状态机:

registered → scanning → keyword_ready → 
semantic_ready → face_mgmt_ready → agent_ready

数据库:

• videos (PostgreSQL) - 文件注册表
• monitor_jobs (PostgreSQL) - 处理任务
• processor_status (PostgreSQL) - 处理器状态

关键特性:

1. 状态追踪: 6 个状态，实时更新
2. 进度监控: Pipeline 进度 + 系统资源
3. 批量操作: 批量注册、扫描、注销
4. 处理器控制: 单独重跑 ASR/OCR/Face 等

---

2.3 Admin 监控及参数模块

职责: 系统监控、配置管理、服务控制

前端组件:

• AdminView.vue - 管理界面

API 端点:

// v1 端点
/api/v1/health                       // 健康检查
/api/v1/system-stats/validate        // 系统验证
/api/v1/admin/config                 // 系统配置

// v2 端点
/api/v2/admin/system-stats           // 系统统计
/api/v2/admin/users                  // 用户列表
/api/v2/admin/shares                 // 共享列表
/api/v2/service/start                // 启动服务
/api/v2/service/stop                 // 停止服务

配置文件:

// admin_config.json
{
  "vlm_prompts": {...},
  "llm_config": {...},
  "processor_config": {...},
  "filter_config": {...},
  "search": {...}
}

关键特性:

1. 系统监控: CPU、内存、GPU、ANE 实时监控
2. 服务管理: Core API、MarkBase、MBE、Proxy 启停
3. 配置编辑: VLM Prompts、LLM、Processor、Filter 配置
4. 语言包管理: 多语言支持

---

2.4 File Management 模块

职责: 原始档案的上传、下载、移动、删除

前端组件:

• ClientView.vue - 文件浏览器

API 端点:

// v2 端点
/api/v2/myfiles/{user}/folders              // 文件夹列表
/api/v2/myfiles/{user}/files                // 文件列表
/api/v2/upload-unlimited/{user}             // 上传文件
/api/v2/myfiles/{user}/preview/{filename}   // 文件预览
/api/v2/myfiles/{user}/move                 // 移动文件
/api/v2/myfiles/{user}/tags                 // 标签管理

数据库:

• files (MarkBase PostgreSQL) - 文件元数据
• folders (MarkBase PostgreSQL) - 文件夹结构

关键特性:

1. 文件浏览器: 文件夹导航、搜索、排序
2. 上传管理: 多文件上传、进度显示
3. 文件操作: 重命名、移动、删除
4. 预览功能: 多格式预览
5. 拖拽支持: 文件拖拽移动

---

3. 数据流图

3.1 搜索数据流

User Query → SearchView → apiCall()
    ↓
Core API (PostgreSQL + Qdrant + MongoDB)
    ↓
Results → VideoPlayer
    ↓
History/Bookmarks → SQLite

3.2 文件处理数据流

File Selection → register_file()
    ↓
videos (PostgreSQL) → Pipeline
    ↓
Processor Output (*.json) → Ingestion
    ↓
Status Update → LibraryView

3.3 Admin 配置数据流

Admin Edit → admin_config.json
    ↓
Service Control (MarkBase API)
Config Reload (Core API)

---

4. 模块间交互

4.1 依赖关系

Search Module
    ├──> File Management (缩略图、视频流)
    ├──> Admin Module (VLM 配置)
    └──> Core API (搜索数据)

File Prep/Processing
    ├──> File Management (原始文件)
    ├──> Admin Module (处理器配置)
    └──> Core API (Pipeline)

Admin Module
    ├──> Core API (配置)
    ├──> MarkBase API (服务控制)
    └──> File Management (上传路径)

File Management
    ├──> Admin Module (用户权限)
    └──> MarkBase API (文件存储)

4.2 数据共享

• 全局 Store: store.ts

  • filesCache - 文件列表
  • thumbnailsCache - 缩略图
  • profilesCache - 人物头像
  • pipelineStatsCache - 处理进度

• SQLite 共享:

  • search_history - Search 模块
  • bookmarks - Search 模块
  • app_users - Admin + File Management

---

5. 技术栈

层次	技术	用途
前端框架	Vue 3 + TypeScript + Vite	响应式 UI
桌面框架	Tauri 2	原生桌面应用
路由	Vue Router	SPA 路由
状态管理	Pinia-like (store.ts)	全局状态
API 层	Dual-mode (IPC + HTTP)	桌面/浏览器双模式
代理层	Axum (Rust)	API Gateway
数据库	PostgreSQL + Qdrant + MongoDB	Core 数据存储
缓存	Redis	任务队列
本地存储	SQLite (rusqlite)	历史和书签

---

6. 已知问题

6.1 双 API 架构复杂度

• 问题: /api/v1/* → Core API, /api/v2/* → MarkBase API，易混淆
• 影响: 文档维护成本高，开发者需要记住命名空间
• 优先级: 中

6.2 状态同步不一致

• 问题: fileStatusCache 前端和 Core API 状态不同步
• 影响: 用户看到的处理状态滞后
• 优先级: 高

6.3 缩略图缓存无淘汰策略

• 问题: 缩略图缓存无 LRU 淘汰，内存占用持续增长
• 影响: 长时间使用后内存占用过高
• 优先级: 中

6.4 Pipeline 进度轮询效率低

• 问题: 每个文件独立轮询，并发处理时 API 压力大
• 影响: 系统负载高
• 优先级: 高

6.5 搜索历史功能受限

• 问题: 限制 30 条，无全文搜索
• 影响: 用户无法按时间/模式过滤历史
• 优先级: 低

6.6 VideoPlayer 性能问题

• 问题: 大视频加载慢，Seek 卡顿
• 影响: 用户体验差
• 优先级: 中

6.7 Admin 配置无验证

• 问题: admin_config.json 编辑无前端验证
• 影响: 可能保存错误配置导致服务崩溃
• 优先级: 高

6.8 文件上传无断点续传

• 问题: 大文件上传失败需重头开始
• 影响: 网络不稳定时体验极差
• 优先级: 中

---

7. 改进建议

7.1 短期（1-2 周）

1. ✅ 实现 WebSocket 状态推送，替代轮询
2. ✅ 增加 LRU Cache 用于缩略图
3. ✅ 增加批量状态查询 API
4. ✅ 实现 Admin 配置前端验证

7.2 中期（1-2 月）

1. 统一 API Gateway，简化双 API
2. 实现 Resumable Upload
3. 增强搜索历史功能
4. VideoPlayer 性能优化

7.3 长期（3-6 月）

1. 迁移到 IndexedDB 持久化
2. 实现离线模式
3. 增加插件系统
4. 实现多租户架构

---

8. API 调用链示例

8.1 搜索场景

用户输入 "find red car"
    ↓
apiCall('search_llm_smart', {query: 'find red car'})
    ↓
[Tauri] invoke('search_llm_smart')
[Browser] httpCall → Proxy :8888 → Core API :3002
    ↓
Core API 查询 PostgreSQL + Qdrant
    ↓
返回 20 条结果
    ↓
前端加载缩略图 → 显示卡片

8.2 文件处理场景

用户选择文件 → register_file()
    ↓
Core API 创建 videos 记录 + monitor_job
    ↓
process_file() → 触发 Pipeline
    ↓
pollPipelineProgress() → 显示进度条
    ↓
Pipeline 完成 → 状态更新为 'agent_ready'

---

9. 总结

Momentry Studio 是一个复杂的 Tauri GUI 应用，集成了四大核心模块：

1. Search - 多模式搜索 + 历史管理
2. File Prep/Processing - Pipeline 处理 + 状态追踪
3. Admin - 系统监控 + 配置管理
4. File Management - 文件上传/下载/移动

通过双 API 架构（Core API + MarkBase API）实现了功能解耦，但也增加了维护成本。当前主要问题集中在状态同步、性能优化和用户体验改进。

---

最后更新: 2026-10-10 维护者: Momentry Studio Team