Orca Trace

Orca Trace（簡稱 OT）是跨平台網路封包觀測工具：

• Flutter (Dart) 負責 UI 與互動
• Rust 負責封包擷取、流量統計、mDNS 探索
• 兩者透過 flutter_rust_bridge 溝通

你可以先看這裡（推薦閱讀順序）

如果你對 Dart / Rust 還不熟，建議照這個順序讀：

1. README.md（本文件）：先知道怎麼跑、專案有哪些模組
2. DOCS_DART_RUST_PRIMER.md：快速補齊本專案會用到的 Dart/Rust 基礎
3. DOCS_ARCHITECTURE.md：完整資料流、模組責任、Dart-Rust 交互細節
4. DOCS_MDNS.md：專看 mDNS 行為與探索機制
5. DOCS_TEXT_ANALYSIS_SPEC.md：文本分類、段落上色、規則 pipeline 草案

目前功能

• 全域設備儀表板（介面 IP + 活躍 IP + mDNS 資訊整合）
• 即時封包擷取（單介面 / 多介面）
• per-IP 即時流量統計（RX/TX）
• Flow Session 聚合與封包詳情檢視
• 二進位 payload 安全預覽（預設 256 bytes）與 Hex 預覽（預設收合）
• Flow Detail 支援一鍵 複製 完整 payload
• Flow Detail 支援單一會話錄製（開始/停止）
• 錄製清單與詳情頁（封包檢視、刪除、到期清理）
• 錄製匯出：pcap 與 outbound-only raw payload
• 網路重放（Replay）：將錄製中的 outbound payload 發送到指定 target IP/Port
• 每個封包 payload capture 上限為 64KB，超過會標示為截斷（payloadTruncated）
• Insight Workspace（parent class 分類 + 結構區塊同色高亮，MVP）
• 全域監控暫停（統一控制 live monitoring / analytics / recording channel）
• 搜尋語法：port:、ip:、host:、proto:、text:、data:（text/data 僅比對可解碼文字 payload）
• Orca Trace 視覺系統（macOS App Icon + UI SVG icon + 一致化主題色盤）

產品路線（草案）

• 品牌主名：Orca Trace（縮寫：OT）
• 能力主軸：Capture / Replay / Insight
• Insight 的文本分析與規則套用草案請見：DOCS_TEXT_ANALYSIS_SPEC.md

技術棧

層	技術	說明
UI	Flutter (Dart)	頁面、狀態、列表渲染、互動
Native	Rust	libpcap 擷取、流量統計、mDNS、錄製/重放
橋接	flutter_rust_bridge 2.11.1	Dart/Rust 型別與 API 綁定
視覺資產	SVG + Pillow 產圖腳本	Orca Trace 主題 icon、macOS AppIcon 多尺寸輸出

系統需求

• Flutter SDK ^3.10.8
• Rust stable
• macOS / Linux: libpcap
• Windows: Npcap
• macOS 封包擷取需 /dev/bpf* 權限（App 啟動時會嘗試請求）

快速開始

# 1) 安裝 Dart/Flutter 依賴
flutter pub get

# 2)（若有修改 Rust API）重新產生綁定
flutter_rust_bridge_codegen generate

# 3) 執行（以 macOS 為例）
flutter run -d macos

開發時最常用指令

# Dart 格式化與靜態分析
dart format lib
dart analyze lib

# Rust 格式化與編譯檢查
cd rust
cargo fmt
cargo check

Orca Trace 視覺系統與 icon

目前專案已整合：

• A 版 Orca Trace 主題 macOS App Icon（AppIcon.appiconset 全尺寸）
• Orca Trace UI SVG icon（design/icons/orca/ui/*.svg）
• 全域 UI 主題（lib/theme/orca_theme.dart）

重新產生 macOS App Icon（含小尺寸優化）：

python3 design/icons/orca/scripts/generate_macos_appicon.py

說明文件：

• design/icons/orca/README.md

修改 Rust API 的標準流程

當你修改 rust/src/api/*.rs 的公開 struct / 函式：

1. 修改 Rust 程式碼
2. 執行 flutter_rust_bridge_codegen generate
3. 確認 lib/src/rust/ 產生的 Dart 端 API 與型別
4. 在 Dart 端接上新 API

注意：

• lib/src/rust/frb_generated*.dart 與 rust/src/frb_generated.rs 是產生檔，不要手改。

全域監控暫停策略

• 監控暫停狀態由 Rust 端管理（rust/src/api/monitoring.rs），Flutter 僅做 UI 與互動。
• 暫停狀態會持久化並在 app 重啟後恢復。
• MonitoringPolicyGate 為 Flutter 端統一入口，所有 channel 都應先過 gate 再執行。
• 目前 channel：
  • liveMonitoring：首頁活躍節點、連線會話、第二頁即時流量卡
  • analyticsUpload
  • recording

目錄結構（重點）

Orca/
├── lib/
│   ├── main.dart                         # App 入口，初始化 Rust
│   ├── theme/orca_theme.dart             # Orca Trace 色彩/字級/間距主題
│   ├── navigation/app_route_observer.dart
│   ├── pages/
│   │   ├── unified_devices_page.dart     # 主頁：設備與活躍流量
│   │   ├── packet_list_page.dart         # Flow 列表與搜尋
│   │   ├── flow_detail_page.dart         # Flow 封包內容詳情 + 錄製入口
│   │   ├── recordings_list_page.dart     # 錄製清單
│   │   └── recording_detail_page.dart    # 錄製詳情（匯出/重放）
│   ├── services/identity_service.dart    # mDNS 身份解析服務
│   ├── services/monitoring_pause_service.dart
│   ├── services/monitoring_policy_gate.dart
│   ├── services/recording_service.dart   # 錄製狀態管理與封包寫入
│   ├── widgets/orca_svg_icon.dart        # Orca Trace SVG icon 封裝元件
│   ├── widgets/live_device_dashboard.dart
│   ├── widgets/monitoring_pause_action_button.dart
│   ├── widgets/monitoring_pause_banner.dart
│   ├── models/flow_session.dart
│   └── src/rust/                         # FRB 自動產生綁定
├── design/icons/orca/                    # Orca Trace icon 設計資產與產圖腳本
├── rust/src/api/
│   ├── simple.rs                         # 共用資料結構 + 介面清單
│   ├── capture.rs                        # 封包擷取
│   ├── stats.rs                          # 流量統計
│   ├── monitoring.rs                     # 監控暫停策略與持久化
│   ├── recording.rs                      # 錄製、匯出、重放
│   └── mdns.rs                           # mDNS 探索
├── DOCS_DART_RUST_PRIMER.md              # Dart/Rust 新手導讀
├── DOCS_ARCHITECTURE.md                  # 架構與資料流詳解
├── DOCS_TEXT_ANALYSIS_SPEC.md            # 文本分析與規則 pipeline 草案
└── DOCS_MDNS.md                          # mDNS 補充說明

文件

• DOCS_DART_RUST_PRIMER.md：Dart / Rust 初學者導讀（專案導向）
• DOCS_ARCHITECTURE.md：完整架構、資料流、執行緒模型、擴充教學
• DOCS_MDNS.md：mDNS 原理、現象與對應程式碼
• DOCS_TEXT_ANALYSIS_SPEC.md：文本分類、段落色彩標註、規則套用與 snapshot 草案
• design/icons/orca/README.md：Orca Trace icon 設計規格、產圖與輸出流程

支援平台

Android | iOS | macOS | Linux | Windows