diff --git a/docs/RUST_DEVELOPMENT.md b/docs/RUST_DEVELOPMENT.md
index a5d3c5b..ea091f9 100644
--- a/docs/RUST_DEVELOPMENT.md
+++ b/docs/RUST_DEVELOPMENT.md
@@ -210,8 +210,6 @@ async fn good_practice() {
## 5. 外部程序整合
-### 5.1 Python 腳本呼叫
-
當需要使用 Python 生態系工具 (如 faster-whisper, YOLO) 時:
```rust
@@ -275,7 +273,289 @@ for line in stderr.lines() {
}
```
-## 6. 測試策略
+---
+
+## 6. Python 與 Node.js 混用規範
+
+本專案同時使用 Python 和 Node.js (n8n),需建立明確的版本隔離與管理規範。
+
+### 6.1 架構概述
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Momentry Core │
+│ │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
+│ │ Rust │ │ Python │ │ Node.js │ │
+│ │ (Core) │───▶ │ (Scripts) │ │ (n8n) │ │
+│ │ │ │ │ │ │ │
+│ │ - CLI │ │ - ASR │ │ - Workflow │ │
+│ │ - DB │ │ - Thumb │ │ - API │ │
+│ │ - Storage │ │ - OCR │ │ - Webhooks │ │
+│ └─────────────┘ └─────────────┘ └─────────────┘ │
+│ │ │ │ │
+│ ▼ ▼ ▼ │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ 資料庫 / 檔案系統 / Qdrant │ │
+│ └─────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 6.2 Python 版本管理
+
+#### 6.2.1 版本鎖定
+
+| 版本 | 用途 | 路徑 |
+|------|------|------|
+| 3.11.14 | 影片處理腳本 | `/opt/homebrew/bin/python3.11` |
+
+#### 6.2.2 虛擬環境
+
+使用專案隔離的 venv:
+
+```bash
+# 建立虛擬環境
+cd /Users/accusys/momentry_core_0.1
+python3.11 -m venv venv
+
+# 啟用
+source venv/bin/activate
+
+# 安裝依賴
+pip install faster-whisper opencv-python python-dotenv
+```
+
+#### 6.2.3 Rust 呼叫 Python
+
+```rust
+let venv_python = Path::new(env!("CARGO_MANIFEST_DIR"))
+ .join("venv")
+ .join("bin")
+ .join("python");
+
+let output = Command::new(venv_python)
+ .arg(script_path)
+ .arg(video_path)
+ .output()
+ .context("Failed to run Python script")?;
+```
+
+### 6.3 Node.js 版本管理
+
+#### 6.3.1 版本鎖定
+
+參考 `docs/NODEJS.md`:
+
+| 版本 | 用途 | 路徑 |
+|------|------|------|
+| 22.22.1 | n8n | `/opt/homebrew/opt/node@22/bin/node` |
+
+#### 6.3.2 n8n 服務配置
+
+使用 launchd plist 隔離:
+
+```xml
+
+ProgramArguments
+
+ /opt/homebrew/opt/node@22/bin/node
+ /opt/homebrew/lib/node_modules/n8n/bin/n8n
+ start
+
+
+EnvironmentVariables
+
+ PATH
+ /opt/homebrew/opt/node@22/bin:/opt/homebrew/bin:...
+
+```
+
+### 6.4 Python + Node.js 共存原則
+
+#### 6.4.1 隔離原則
+
+| 原則 | 說明 |
+|------|------|
+| **獨立路徑** | Python 用 venv 路徑,Node.js 用 node@22 路徑 |
+| **獨立環境** | n8n 服務使用 launchd plist,不與 Rust 共享環境 |
+| **明確版本** | 所有腳本明確指定直譯器路徑 |
+| **PORT 分配** | n8n: 5678/5690, API: 另行分配 |
+
+#### 6.4.2 環境變數隔離
+
+```bash
+# Rust 專案 .env
+DATABASE_URL=postgres://...
+
+# n8n plist
+N8N_ENCRYPTION_KEY=xxx
+N8N_BASIC_AUTH_ACTIVE=true
+
+# 勿混用,避免 Rust 讀到 n8n 環境變數
+```
+
+### 6.5 工作流程整合
+
+#### 6.5.1 Rust → Python
+
+```
+Rust CLI ──▶ Python Script ──▶ JSON Output ──▶ Rust Parse
+ │ │
+ └── venv/bin/python └── faster-whisper
+```
+
+#### 6.5.2 Rust → n8n Webhook
+
+```rust
+// 觸發 n8n workflow
+use reqwest;
+
+pub async fn trigger_n8n_webhook(webhook_url: &str, payload: &str) -> Result<()> {
+ let client = reqwest::Client::new();
+ client.post(webhook_url)
+ .json(payload)
+ .send()
+ .await
+ .context("Failed to trigger n8n webhook")?;
+ Ok(())
+}
+```
+
+#### 6.5.3 n8n → Rust API
+
+```
+n8n Workflow ──▶ HTTP Request Node ──▶ Rust API Server
+ │
+ ┌───────┴───────┐
+ │ axum server │
+ │ /api/webhook │
+ └───────────────┘
+```
+
+### 6.6 監控配置
+
+#### 6.6.1 獨立監控腳本
+
+```bash
+# monitor/service/node_monitor.sh
+# 監控 n8n Node.js 版本
+
+# monitor/service/python_monitor.sh
+# 監控 Python 腳本執行狀態
+```
+
+#### 6.6.2 健康檢查
+
+```yaml
+# monitor_config.yaml
+services:
+ - name: "n8n"
+ type: "http"
+ port: 5678
+ check_url: "http://localhost:5678/"
+
+ - name: "Python Scripts"
+ type: "process"
+ check: "pgrep -f asr_processor.py"
+```
+
+### 6.7 排程管理
+
+#### 6.7.1 備份排程 (Python 腳本)
+
+```bash
+# crontab
+0 3 * * * /Users/accusys/momentry/scripts/backup_all.sh
+```
+
+#### 6.7.2 n8n 工作流排程
+
+- 由 n8n 內建排程節點管理
+- 不與 crontab 衝突
+
+### 6.8 故障排除
+
+#### 6.8.1 常見問題
+
+| 問題 | 原因 | 解決方案 |
+|------|------|----------|
+| n8n 版本警告 | 使用 Node 25.x | 確認 plist 使用 node@22 |
+| Python 腳本找不到模組 | 未啟用 venv | 使用 venv/bin/python |
+| 執行權限錯誤 | shebang 錯誤 | 確認 #!/opt/homebrew/bin/python3.11 |
+| Port 被佔用 | 多個服務使用相同 port | 分配獨立 port |
+
+#### 6.8.2 診斷命令
+
+```bash
+# 檢查 Python 版本
+which python
+/opt/homebrew/bin/python3.11 --version
+
+# 檢查 Node.js 版本
+/opt/homebrew/opt/node@22/bin/node --version
+
+# 檢查 n8n 程序
+ps aux | grep n8n
+
+# 檢查 Python 程序
+ps aux | grep python
+
+# 檢查 Port 佔用
+lsof -i :5678 # n8n
+```
+
+### 6.9 新增服務決策
+
+```
+新服務需要哪種執行環境?
+ │
+ ├─ Python 腳本 ──▶ 使用專案 venv
+ │ (路徑: venv/bin/python)
+ │
+ ├─ Node.js 工具 ──▶ 評估版本需求
+ │ │
+ │ ├─ 支援 Node 22 ──▶ 使用 node@22
+ │ │
+ │ └─ 需要其他版本 ──▶ 安裝新版本 (如 node@20)
+ │
+ └─ 現有服務依賴 ──▶ 根據現有服務配置
+```
+
+### 6.10 文件維護
+
+當新增 Python 或 Node.js 服務時:
+
+1. 更新本文檔的版本表格
+2. 建立對應的監控腳本
+3. 如需 launchd plist,建立並加入 `momentry_runtime/plist/`
+4. 更新 `docs/NODEJS.md` 或 `docs/PYTHON.md`
+
+### 5.2 進度回報
+
+透過 stderr 回報進度,供 Rust 端解析:
+
+```python
+# Python 腳本
+import sys
+
+print(f"ASR_START", file=sys.stderr)
+print(f"ASR_LANGUAGE:{detected_lang}", file=sys.stderr)
+print(f"ASR_PROGRESS:{count}", file=sys.stderr)
+print(f"ASR_COMPLETE:{total}", file=sys.stderr)
+```
+
+```rust
+// Rust 端解析
+let stderr = String::from_utf8_lossy(&output.stderr);
+for line in stderr.lines() {
+ if line.starts_with("ASR_PROGRESS:") {
+ let count = line.trim_start_matches("ASR_PROGRESS:");
+ println!("[ASR] Processed {} segments...", count);
+ }
+}
+```
+
+## 7. 測試策略
### 6.1 單元測試
@@ -338,7 +618,7 @@ mod mocks {
}
```
-## 7. 日誌與監控
+## 8. 日誌與監控
### 7.1 日誌規範
@@ -377,7 +657,7 @@ fn init_logging() {
}
```
-## 8. 性能優化
+## 9. 性能優化
### 8.1 避免拷貝
@@ -413,7 +693,7 @@ let pool = SqlxPool::connect(&DATABASE_URL).await?;
let db = PostgresDb::new(pool);
```
-## 9. 安全考量
+## 10. 安全考量
### 9.1 敏感資訊
@@ -442,7 +722,7 @@ Command::new("ffprobe")
.output();
```
-## 10. 文件編寫
+## 11. 文件編寫
### 10.1 結構體/函式文件
@@ -487,7 +767,7 @@ pub struct VideoRecord {
pub async fn get_video(&self, uuid: &str) -> Result