forked from masonhuang/cluster4npu
abin
5aa374625f
- Add .autoflow/ with health check, PRD, Design Doc, TDD, progress tracking - Add tests/conftest.py with PyQt5/KP SDK stubs for unit testing - Add pytest config to pyproject.toml (pythonpath, import-mode, test naming) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
142 lines
6.0 KiB
Markdown
142 lines
6.0 KiB
Markdown
# 專案健檢報告
|
||
|
||
## 基本資訊
|
||
|
||
- **專案名稱**：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 遠端） |
|