374 lines
6.6 KiB
Markdown
374 lines
6.6 KiB
Markdown
# MoMentry Playground - AGENTS.md
|
||
|
||
## 概述
|
||
|
||
MoMentry Playground 是一個整合式桌面應用程式，提供：
|
||
- 多格式媒體播放（視頻、音頻、圖片）
|
||
- Markdown/PDF/HTML 檢視
|
||
- Frame-精確的視頻控制
|
||
- 與 momentry_core 處理模組的進度監控
|
||
- Database 查詢功能
|
||
|
||
## 技術棧
|
||
|
||
| 元件 | 技術 |
|
||
|------|------|
|
||
| 語言 | Rust 2021 |
|
||
| 桌面框架 | tao + wry |
|
||
| 視頻播放 | SDL2 + FFmpeg-sidecar |
|
||
| 前端 | HTML/CSS/JS (WebView) |
|
||
| 後端接口 | HTTP API (momentry_core port 3002) |
|
||
| 數據庫 | PostgreSQL, MongoDB, Qdrant (via API) |
|
||
|
||
---
|
||
|
||
## 構建/測試/代碼質量命令
|
||
|
||
### 構建
|
||
```bash
|
||
# Debug 構建
|
||
cargo build
|
||
|
||
# Release 構建
|
||
cargo build --release
|
||
|
||
# 運行
|
||
cargo run
|
||
|
||
# 指定功能運行
|
||
cargo run --features "youtube,cloud"
|
||
```
|
||
|
||
### 測試
|
||
```bash
|
||
# 運行所有測試
|
||
cargo test
|
||
|
||
# 運行單個測試
|
||
cargo test test_name
|
||
|
||
# 運行並顯示輸出
|
||
cargo test -- --nocapture
|
||
|
||
# 運行 doc tests
|
||
cargo test --doc
|
||
```
|
||
|
||
### 代碼質量
|
||
```bash
|
||
# 格式化代碼
|
||
cargo fmt
|
||
|
||
# 檢查格式化
|
||
cargo fmt -- --check
|
||
|
||
# Lint + 自動修復
|
||
cargo clippy --fix --allow-dirty --allow-staged
|
||
|
||
# Lint 檢查
|
||
cargo clippy
|
||
|
||
# 類型檢查
|
||
cargo check
|
||
|
||
# 完整檢查（相當於所有以上）
|
||
cargo build --all-targets
|
||
```
|
||
|
||
### WASM 目標（如使用 Yew）
|
||
```bash
|
||
# 添加 WASM 目標
|
||
rustup target add wasm32-unknown-unknown
|
||
|
||
# 使用 Trunk 開發
|
||
trunk serve
|
||
|
||
# Production 構建
|
||
trunk build --release
|
||
```
|
||
|
||
---
|
||
|
||
## 代碼風格指南
|
||
|
||
### 格式規範
|
||
- **最大行長**: 100 字符
|
||
- **縮進**: 4 空格（使用 `rustfmt` 自動處理）
|
||
- **換行**: Unix 風格 (`\n`)
|
||
|
||
### 命名慣例
|
||
```rust
|
||
// 類型/結構體/枚舉: PascalCase
|
||
struct VideoPlayer;
|
||
enum PlaybackState;
|
||
trait MediaViewer;
|
||
|
||
// 函數/方法/變量: snake_case
|
||
fn play_video();
|
||
let current_frame = 0;
|
||
let is_playing = true;
|
||
|
||
// 常量: SCREAMING_SNAKE_CASE
|
||
const MAX_FRAME_BUFFER: usize = 10;
|
||
const SEEK_DELAY_MS: u64 = 500;
|
||
|
||
// 模塊: snake_case
|
||
mod video_player;
|
||
pub mod ffmpeg;
|
||
|
||
// 公開 API: 完整單詞
|
||
fn get_playback_position() -> Duration;
|
||
fn set_volume() -> Result<(), PlayerError>;
|
||
```
|
||
|
||
### 錯誤處理
|
||
```rust
|
||
// 使用 anyhow 進行應用級錯誤處理
|
||
use anyhow::{Context, Result, anyhow};
|
||
|
||
fn load_video(path: &str) -> Result<VideoFile> {
|
||
let file = File::open(path)
|
||
.with_context(|| format!("Failed to open video: {}", path))?;
|
||
// ...
|
||
}
|
||
|
||
// 定義專用錯誤枚舉
|
||
#[derive(Debug, thiserror::Error)]
|
||
pub enum PlayerError {
|
||
#[error("Codec not supported: {0}")]
|
||
UnsupportedCodec(String),
|
||
|
||
#[error("Seek failed: {0}")]
|
||
SeekFailed(String),
|
||
|
||
#[error("FFmpeg error: {stderr}")]
|
||
FFmpegError { stderr: String },
|
||
}
|
||
```
|
||
|
||
### 模塊結構
|
||
```rust
|
||
// src/lib.rs - 庫入口
|
||
pub mod player;
|
||
pub mod ui;
|
||
pub mod viewer;
|
||
pub mod api;
|
||
|
||
// 每個模塊的組織
|
||
mod player {
|
||
pub mod video; // 公開子模塊
|
||
mod controls; // 私有實現
|
||
|
||
pub use video::{VideoPlayer, VideoEvent};
|
||
}
|
||
```
|
||
|
||
### 並發安全
|
||
```rust
|
||
// 使用 Arc<Mutex<T>> 共享狀態
|
||
let player = Arc::new(Mutex::new(VideoPlayer::new()));
|
||
|
||
// 在多線程間共享 Frame buffer
|
||
type FrameBuffer = Arc<Mutex<VecDeque<Frame>>>;
|
||
|
||
// Spawn 線程時克隆 Arc
|
||
let player_clone = Arc::clone(&player);
|
||
std::thread::spawn(move || {
|
||
// ...
|
||
});
|
||
```
|
||
|
||
### 文檔注釋
|
||
```rust
|
||
/// 視頻播放器核心結構
|
||
///
|
||
/// # Example
|
||
/// ```
|
||
/// let player = VideoPlayer::new();
|
||
/// player.open("video.mp4")?;
|
||
/// player.play()?;
|
||
/// ```
|
||
pub struct VideoPlayer {
|
||
// ...
|
||
}
|
||
|
||
/// 播放事件
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub enum PlayEvent {
|
||
/// 播放開始
|
||
Play,
|
||
/// 播放暫停
|
||
Pause,
|
||
/// 進度更新 (當前幀, 總幀數)
|
||
Progress(u64, u64),
|
||
/// 播放結束
|
||
End,
|
||
}
|
||
```
|
||
|
||
### 依賴管理
|
||
```toml
|
||
# 明確版本範圍
|
||
[dependencies]
|
||
anyhow = "1.0"
|
||
serde = { version = "1.0", features = ["derive"] }
|
||
|
||
# 避免使用 * 導入
|
||
# 錯誤: use std::collections::*;
|
||
# 正確: use std::collections::{HashMap, HashSet};
|
||
```
|
||
|
||
### API 設計
|
||
```rust
|
||
// 使用 Result 明確錯誤
|
||
fn command(&self, cmd: &str) -> Result<String>;
|
||
|
||
// 公開方法要有文檔
|
||
/// 發送播放命令
|
||
///
|
||
/// # Arguments
|
||
/// * `cmd` - 命令字串 ("play", "pause", "seek <time>")
|
||
///
|
||
/// # Errors
|
||
/// 返回無效命令或播放錯誤
|
||
pub fn command(&self, cmd: &str) -> Result<String> {
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## WebView 前端規範
|
||
|
||
### HTML 結構
|
||
```html
|
||
<div id="app">
|
||
<div id="toolbar"><!-- 控制工具欄 --></div>
|
||
<div id="input-area"><!-- 命令輸入 --></div>
|
||
<div id="media-viewport"><!-- 媒體顯示 --></div>
|
||
<div id="controls"><!-- 播放控制 --></div>
|
||
<div id="status-bar"><!-- 狀態信息 --></div>
|
||
<div id="output-log"><!-- 日誌輸出 --></div>
|
||
</div>
|
||
```
|
||
|
||
### JS 命令接口
|
||
```javascript
|
||
// 發送命令到 Rust 後端
|
||
function sendCommand(cmd) {
|
||
window.momentry_command(cmd);
|
||
}
|
||
|
||
// 接收後端事件
|
||
window.momentry_on_event = function(event) {
|
||
console.log('Event:', event);
|
||
};
|
||
```
|
||
|
||
### CSS 樣式
|
||
```css
|
||
:root {
|
||
--bg-primary: #1e1e1e;
|
||
--bg-secondary: #2d2d2d;
|
||
--text-primary: #ffffff;
|
||
--accent: #007acc;
|
||
--error: #f44747;
|
||
}
|
||
|
||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||
body { font-family: system-ui, sans-serif; }
|
||
```
|
||
|
||
---
|
||
|
||
## 外部依賴
|
||
|
||
### FFmpeg (必需)
|
||
```bash
|
||
# macOS
|
||
brew install ffmpeg
|
||
|
||
# Linux
|
||
sudo apt install ffmpeg
|
||
|
||
# 驗證
|
||
ffmpeg -version
|
||
ffprobe -version
|
||
```
|
||
|
||
### yt-dlp (YouTube 支援)
|
||
```bash
|
||
brew install yt-dlp # macOS
|
||
pip install yt-dlp # pip
|
||
```
|
||
|
||
---
|
||
|
||
## 環境變量
|
||
|
||
```bash
|
||
# API 服務地址
|
||
export MOMENTRY_API_URL=http://localhost:3002
|
||
|
||
# 數據庫連接
|
||
export DATABASE_URL=postgresql://user:pass@localhost:5432/momentry
|
||
export QDRANT_URL=http://localhost:6333
|
||
|
||
# 輸出目錄
|
||
export MOMENTRY_OUTPUT_DIR=./output
|
||
|
||
# 日誌級別
|
||
export RUST_LOG=debug
|
||
```
|
||
|
||
---
|
||
|
||
## 開發工作流
|
||
|
||
### 1. 創建功能分支
|
||
```bash
|
||
git checkout -b feature/video-controls
|
||
```
|
||
|
||
### 2. 開發與測試
|
||
```bash
|
||
cargo test feature_name
|
||
cargo clippy --fix
|
||
cargo fmt
|
||
cargo build --release
|
||
```
|
||
|
||
### 3. 提交（使用Conventional Commits）
|
||
```bash
|
||
git commit -m "feat(player): add frame-precise seeking"
|
||
git commit -m "fix(controls): correct volume sync"
|
||
git commit -m "docs: update AGENTS.md"
|
||
```
|
||
|
||
### 4. 推送與 PR
|
||
```bash
|
||
git push -u origin feature/video-controls
|
||
# 在 Gitea 創建 PR → main
|
||
```
|
||
|
||
---
|
||
|
||
## 常見問題
|
||
|
||
### Q: FFmpeg 路徑找不到
|
||
```rust
|
||
// 在代碼中指定路徑
|
||
let ffmpeg_path = std::path::Path::new("/opt/homebrew/bin/ffmpeg");
|
||
VideoDecoder::new(ffmpeg_path)
|
||
```
|
||
|
||
### Q: WebView 不顯示
|
||
確保 `index.html` 在正確的資源路徑，或使用 `include_bytes!` 嵌入。
|
||
|
||
### Q: 編譯緩慢
|
||
```bash
|
||
# 使用 sccache
|
||
cargo install sccache
|
||
export RUSTC_WRAPPER=sccache
|
||
```
|