abin/KNEO-Academy
1
0
Fork 0
forked from masonhuang/KNEO-Academy
Code Pull Requests Activity
KNEO-Academy/.autoflow/00-onboarding/health-check.md
abin 1e42293896 Add autoflow
2026-04-07 14:37:04 +08:00

6.4 KiB
Raw Permalink Blame History

專案健檢報告 — KNEO Academy

基本資訊

  • 專案名稱：KNEO Academy（Innovedus AI Playground）
  • 版本：v2.0
  • 程式碼來源：本地路徑 C:\Users\sungs\Documents\abin\KNEO-Academy
  • 主要語言：Python 3.12
  • 最後更新時間：2026-04-04
  • Git branch：main

技術堆疊

層級 技術 版本
GUI 框架 PyQt5 5.15.11
電腦視覺 OpenCV 4.10.0.84
AI 推論 SDK KneronPLUS 3.1.2
AI 推論（通用） PyTorch, TensorFlow, ONNX Runtime 最新
音訊 librosa, sounddevice —
打包 PyInstaller 6.12.0
加密 PyArmor —

專案結構概覽

KNEO-Academy/
├── main.py                         # Entry point，AppController（QStackedWidget 管理頁面）
├── src/
│   ├── config.py                   # 全域常數、路徑、顏色、DeviceType enum
│   ├── controllers/
│   │   ├── device_controller.py    # Kneron dongle 掃描、連接、韌體上傳
│   │   ├── inference_controller.py # 推論工具選擇、model 載入、queue 管理
│   │   └── media_controller.py     # 相機、影片捕捉
│   ├── models/
│   │   ├── inference_worker.py     # 標準推論 worker thread（動態載入 script.py）
│   │   ├── custom_inference_worker.py # 自定義模型推論 worker（YOLOv5 後處理）
│   │   └── video_thread.py         # 相機影像擷取 thread
│   ├── views/
│   │   ├── mainWindows.py          # 主應用視窗（推論結果顯示、工具選擇）
│   │   ├── selection_screen.py     # 首頁選擇畫面
│   │   ├── login_screen.py         # 工具程式登入頁
│   │   └── utilities_screen.py     # 裝置管理工具頁
│   ├── services/
│   │   ├── device_service.py       # 掃描 Kneron 裝置（含 timeout 機制）
│   │   ├── file_service.py         # 檔案上傳服務
│   │   └── script_service.py       # 推論腳本執行服務
│   └── utils/
│       ├── config_utils.py         # 設定工具
│       └── image_utils.py          # QImage ↔ NumPy 轉換
├── uxui/                           # 靜態 UI 資源（PNG、SVG、GIF）
├── dist/
│   └── test.iss                    # Inno Setup 安裝包設定
├── flowchart.md                    # 裝置連接流程設計圖（Mermaid）
└── env.txt                         # pip 套件清單

資料目錄（執行期，存在 %LOCALAPPDATA%/Kneron_Academy/）：

uploads/          # 使用者上傳的圖片/影片
utils/
  config.json     # 全域 plugin 設定
  {mode}/{model}/
    script.py     # 推論腳本
    config.json   # 模型設定
    *.nef         # 模型檔
firmware/
  {device}/
    fw_scpu.bin
    fw_ncpu.bin

應用頁面流程

SelectionScreen（首頁）
  ├── → LoginScreen → UtilitiesScreen（裝置管理工具，需登入）
  └── → MainWindow（Demo AI App，直接進入）

主要功能清單

功能 描述 狀態
頁面路由 QStackedWidget 管理多頁面切換 ✅ 完成
裝置掃描 掃描連接的 Kneron dongle（KL520 / KL720） ✅ 完成
裝置連接 連接裝置並上傳 firmware ✅ 完成
裝置中斷 安全中斷連接 ✅ 完成
Video 推論 相機即時推論（QThread + queue） ✅ 完成
Image 推論 上傳圖片單次推論 ✅ 完成
動態 Script 載入 從 utils/ 目錄動態 import script.py ✅ 完成
自定義模型推論 上傳 .nef + firmware，使用 YOLOv5 後處理 ✅ 完成
Plugin 系統 透過 config.json 定義 mode/model 結構 ✅ 完成
APP 打包 PyInstaller 打包 + Inno Setup 安裝包 ✅ 有設定
登入驗證 Server 驗證（詳細流程見 flowchart.md） 🔄 設計中（有 flowchart）
Dongle 授權管理 KN 號碼查詢、授權卡驗證 🔄 設計中（有 flowchart）

文件完整度

文件類型 狀態 位置 備註
README ✅ 有 README.md 完整，含安裝、架構、功能說明
流程圖 ⚠️ 部分 flowchart.md 僅有裝置連接/授權流程，缺主 App 完整流程
PRD / 需求文件 ❌ 無 — 無正式產品需求文件
架構設計文件 ❌ 無 — 無正式架構文件
API 文件 ❌ 無 — 無（script.py 介面未有規格文件）
設計稿 ⚠️ 部分 uxui/ 有 UI 資源圖，無 Wireframe 或設計規格
TDD（技術設計文件） ❌ 無 — 無
測試文件 ❌ 無 — README 提到 tests/ 目錄，但實際不存在
部署文件 ⚠️ 部分 dist/test.iss 有 Inno Setup 設定，無完整部署指南

程式碼健康度

項目 狀態 備註
測試覆蓋率 ❌ 無測試 tests/ 目錄不存在
程式碼組織 ✅ 良好 MVC 架構清晰，職責分明
Docstring 完整度 ✅ 良好 主要類別和方法均有完整 docstring
錯誤處理 ⚠️ 部分 多處使用 try/except，但部分只 print 不處理
Thread 安全 ⚠️ 待確認 Queue 管理有，但 UI 更新路徑需確認
技術債 ⚠️ 少量 debug print 語句散落在 controller 中

基礎設施

項目 狀態 備註
Docker ❌ 無 桌面應用，暫不需要
CI/CD ❌ 無 無自動化建置/測試流程
打包 ✅ 有 PyInstaller + Inno Setup
加密 ⚠️ 計畫中 PyArmor 已列在計畫中
監控 ❌ 無 無

目前正在修改的檔案（git status）

以下檔案有未提交的修改：

  • src/controllers/device_controller.py
  • src/controllers/inference_controller.py
  • src/models/custom_inference_worker.py
  • src/models/video_thread.py
  • src/services/device_service.py
  • src/views/utilities_screen.py

缺失項目摘要

高優先：

  • PRD / 需求文件（產品功能邊界不清晰）
  • 測試（完全沒有自動化測試）

中優先：

  • 架構文件 / TDD（plugin script.py 介面規格未文件化）
  • 完整流程圖（主 App 推論流程尚未有流程圖）

低優先：

  • 部署完整指南
  • 設計規格文件（Wireframe + Design Tokens）