cluster4npu/.autoflow/00-onboarding/health-check.md

專案健檢報告

基本資訊

• 專案名稱：Cluster4NPU UI — Visual Pipeline Designer
• 版本：v0.0.3
• 程式碼來源：本地路徑 C:\Users\sungs\Documents\abin\temp\cluster4npu
• Git 分支：developer（主分支為 main）
• 最後 commit：feat: Reorganize test scripts and improve YOLOv5 postprocessing
• 健檢日期：2026-04-05

---

技術堆疊

層級	技術	版本
語言	Python	>=3.9, <3.12
GUI 框架	PyQt5	>=5.15.11
視覺節點編輯器	NodeGraphQt	>=0.6.40
影像處理	OpenCV	(runtime dependency)
數值運算	NumPy	(runtime dependency)
硬體 SDK	Kneron KP SDK	(runtime, NPU dongle 驅動)
套件管理	uv	—
打包	PyInstaller (main.spec)	—

支援硬體： Kneron NPU dongles — KL520、KL720、KL1080

---

專案結構概覽

cluster4npu/
├── main.py                        # 應用程式入口點
├── config/                        # 設定與主題 (settings.py, theme.py)
├── core/
│   ├── pipeline.py                # Pipeline 分析、stage 偵測、驗證
│   ├── functions/
│   │   ├── InferencePipeline.py   # 多 stage pipeline 執行引擎（多執行緒）
│   │   ├── Multidongle.py         # NPU dongle 管理與自動偵測
│   │   ├── camera_source.py       # 相機輸入來源
│   │   ├── video_source.py        # 影片輸入來源
│   │   ├── result_handler.py      # 推論結果處理
│   │   ├── workflow_orchestrator.py
│   │   ├── mflow_converter.py     # .mflow 格式轉換
│   │   └── yolo_v5_postprocess_reference.py
│   └── nodes/                     # 節點定義（5 種類型）
│       ├── base_node.py
│       ├── input_node.py
│       ├── model_node.py
│       ├── preprocess_node.py
│       ├── postprocess_node.py
│       ├── output_node.py
│       ├── simple_input_node.py
│       └── exact_nodes.py
├── ui/
│   ├── windows/                   # 主視窗（login.py, dashboard.py, pipeline_editor.py）
│   ├── components/                # 可重用元件（node_palette, properties_widget, common_widgets）
│   └── dialogs/                   # 對話框（deployment, performance, stage_config 等）
├── utils/                         # 工具函式（file_utils, folder_dialog, ui_utils）
├── example_utils/                 # 範例後處理工具（ByteTrack 等）
├── tests/                         # 測試腳本（42 個，多為腳本式，非正式 test suite）
├── resources/                     # 資源檔案
└── output/                        # 推論輸出結果

---

文件完整度

文件類型	狀態	位置	備註
README	✅ 有	README.md	詳細，含安裝、架構說明
產品需求 / PRD	⚠️ 部分	PROJECT_SUMMARY.md	有願景與待開發功能，但非正式 PRD 格式
開發路線圖	✅ 有	DEVELOPMENT_ROADMAP.md	四個 Phase，有具體目標
架構設計文件	❌ 無	—	README 內有簡介，但無正式 Design Doc
API 文件	❌ 無	—	無正式 API 文件
設計稿	❌ 無	只有 Flowchart.jpg	無 Wireframe 或 UI 規格
技術設計文件 (TDD)	❌ 無	—	無
測試計畫	❌ 無	—	有測試腳本但無正式測試計畫
部署文件	⚠️ 部分	README 內	有基本步驟，無完整部署文件
Release Notes	✅ 有	release_note.md	目前到 v0.0.2

---

程式碼健康度

• 測試覆蓋率：⚠️ 部分測試 — tests/ 下有 42 個腳本，但多為情境測試腳本（非 pytest 單元測試），缺乏系統性覆蓋
• 程式碼品質：中等 — 有明確的模組分離；部分根目錄腳本（debug_*.py, force_cleanup.py 等）為開發過程遺留，結構略混亂
• 安全性：低風險（本地桌面應用，無網路 API）
• 技術債：
  • 根目錄有多個 debug/cleanup 腳本未整理
  • tests/ 下腳本命名與分類混亂（部分非 test_ 開頭）
  • 缺乏正式的 pytest 測試架構

---

現有功能清單

功能	描述	狀態
視覺化 Pipeline 編輯器	拖拽節點建立 Pipeline（NodeGraphQt）	✅ 完成
5 種節點類型	Input / Preprocess / Model / Postprocess / Output	✅ 完成
Pipeline 驗證	即時 stage 偵測與錯誤標示	✅ 完成
.mflow 檔案格式	Pipeline 儲存與載入（JSON）	✅ 完成
多 NPU Dongle 支援	KL520 / KL720 / KL1080 自動偵測	✅ 完成
多 stage 推論引擎	多執行緒 Pipeline 執行	✅ 完成
效能監控	FPS、延遲即時顯示	✅ 完成（有 known bugs）
相機 / 影片 / 圖片輸入	多種輸入來源	✅ 完成
專案管理	登入畫面、最近專案、新增/載入 Pipeline	✅ 完成
YOLOv5 後處理	偵測結果格式化	✅ 完成（最近改善）
ByteTrack 追蹤	物件追蹤後處理	✅ 完成（example_utils）

---

缺失項目摘要（待開發）

根據 PROJECT_SUMMARY.md 與 DEVELOPMENT_ROADMAP.md：

1. 效能視覺化：並行 vs 循序執行比較、Speedup 指標顯示（Phase 1）
2. Benchmarking 系統：自動化效能測試、圖表比較（Phase 1）
3. 裝置管理介面：視覺化裝置分配、負載平衡（Phase 2）
4. 即時監控 Dashboard：FPS/延遲圖表、資源使用率（Phase 2）
5. 優化引擎：自動化建議、效能預測（Phase 3）

已知 Bug：

• 節點屬性顯示問題
• 輸出視覺化（含後處理）

---

CI/CD 與基礎設施

項目	狀態
Docker	❌ 無
CI/CD	❌ 無
部署設定	❌ 無（本地桌面應用，有 PyInstaller spec）
環境變數管理	❌ 無
版本控制	✅ Git（GitHub 遠端）