跳到主要內容
MangoBoxAI 精準教學平台
MANGOTHONNY v0.4.3.1

安裝與使用說明

一般教學電腦建議使用 Installer;需要免安裝、隨身或測試環境時使用 Portable ZIP。v0.4.3.1 的重點是 Assignment Mode、Learning Log 與繁體中文 Error Advisor:學生從「開始作業」進入作業專案,在同一環境完成撰寫、執行、除錯、帶走、續作與正式繳交。

下載 v0.4.3.1

正式 Portable/Installer 已完成建置、校驗與 Windows install/launch/shortcut/upgrade/uninstall/reinstall smoke,並上架 GitHub Release。

下載 Installer下載 Portable中/英文 Release Notes

Portable SHA-256
b34e43209b7aa8dfbd7d9ae343e15617de5b0882e56f60eec08d3c34db6629a6

Installer SHA-256
fa1740dde1f314e18993391a757e48e145ba74785e53dd86464be687955924fc

1. Windows Installer

下載並執行 MangoThonny-Setup-v0.4.3.1.exe。安裝介面提供繁體中文。若電腦已安裝舊版,可直接執行新版 Installer 進行升級。

解除安裝時若要保留既有設定、作業與學習資料,請選擇保留 MangoThonny 使用者資料;v0.4.3.1 已驗證保留資料後重新安裝可正常讀回。

2. Portable

下載 MangoThonny-Portable-v0.4.3.1.zip 後,完整解壓縮到可寫入的資料夾,再執行 MangoThonny.exe。若原生 launcher 無法使用,可改執行 MangoThonny.bat。

3. 一般練習與作業模式

沒有指定課堂作業時,可以像一般 Thonny 一樣開檔、寫程式與 Run。老師指定作業時,請使用主工具列的 「開始」 進入 Assignment Mode,不要先在其他資料夾寫完後才複製貼上。

開始作業後系統會:

  • 在所選位置建立與作業代碼相同的作業專案資料夾。
  • 自動建立並開啟 main.py。
展開完整功能說明
  • 將作業代碼自動轉為大寫。
  • 鎖定學號與作業代碼,避免途中誤改。
  • 將左側檔案瀏覽器固定在目前 Project Root。
  • 在主工具列顯示作業狀態、歷程、存檔、專案狀態、Run/Event 數量與容量。

4. 正確的作業操作順序

  1. 收到題目後先按 開始,輸入學號與作業代碼。
  2. 直接在自動建立的 main.py 中撰寫程式。
  3. 反覆使用 Run 執行、觀察輸出或錯誤、修改後再 Run。
  4. 需要圖片、CSV、音訊或影片時,使用作業介面的匯入資源功能;若直接從 Windows 檔案總管複製進 Project,系統也會在繳交前重新檢查。
  5. 尚未完成但要換電腦時使用 帶走;到另一台電腦使用 匯入作業。
  6. 完成後使用 完成並匯出作業 產生正式繳交 ZIP。

這個流程的目的,是讓程式碼與 Learning Log 維持在同一個 Assignment Project 中,避免「最後才複製貼上」造成歷程缺失。

5. 匯入資源與容量限制

  • 程式/資料檔:單檔 2 MB。
  • 圖片:單檔 2 MB。
展開完整功能說明
  • 音訊:單檔 5 MB。
  • 影片:單檔 10 MB。
  • 可匯出的作業內容總計 15 MB。

超過限制時系統會提示使用者處理;正式繳交前仍會再驗證一次。Mango App Exporter 的系統輸出不納入作業繳交與容量計算。

6. 繁體中文 Error Advisor

Run 發生錯誤時,Shell 會保留 Python 原始 traceback;右側 Assistant 會顯示 MangoBox 繁體中文提示。Advisor 會依錯誤類型與可取得的程式碼內容,引導學生:

  1. 找問題:指出錯誤發生的位置與可能原因。
  2. 怎麼修改:說明修改方向,而不是直接代替學生完成整題。
  3. 怎麼確認:修改後再 Run,觀察錯誤是否消失或轉為另一個問題。

目前支援常見 Syntax、Indentation、Name、Type、Index、Value、Import、File、Attribute、OSError/I/O 等錯誤,並可在部分情況判斷變數型態、可能拼錯的變數名稱或索引範圍。

7. 「有幫助/還是不懂」回饋

部分 Error Advisor 提示底部會提供「有幫助」與「還是不懂」回饋。這項資料會和該次 Advisor episode 一起寫入 Learning Log,讓教師後續了解學生是否看過提示、是否互動,以及下一次 Run 發生什麼結果。

後續結果分為:下一次 Run 已修正、轉為其他錯誤、同錯誤持續、尚待下一次 Run。這些資料是教學診斷的描述性 evidence,不直接宣稱 Advisor 造成某種學習成效。

8. 帶走作業與跨電腦續作

  • 帶走:將目前作業、Assignment metadata 與 compact learning history 封裝。
  • 匯入作業:在另一台電腦建立新的本機 workspace,但保留原本 assignment_id。
展開完整功能說明
  • 重新匯入後,畫面會只保留目前作業專案內的程式頁,避免外部程式頁干擾 Assignment Mode。
  • 完成並匯出作業:產生正式繳交 ZIP;成功產生後作業才標記為 completed。

9. Learning Log 與高頻感測資料

Learning Log 可記錄 Run、code snapshot、輸出、runtime error、Student API/hardware evidence 與作業 identity。Assignment 模式可跨 Run、跨日期、跨 MangoThonny 啟閉維持同一份作業。

Light、Sound、Joystick、PIR、IR、Ultrasonic、Obstacle 等連續讀取不會把每筆 polling 都塞進作業歷程;系統會以 bounded queue 與 constant-memory aggregation 產生 hardware_summary。真正的按下/放開、門檻跨越等語意事件仍會個別保存。

10. Interpreter 切換與 Host Student API

  • Host / CPython:使用 MangoThonny 內建 Python 執行桌面程式與 Host Student API。
  • Raspberry Pi Pico / MicroPython:連接 Pico 系列裝置後,可切換到 MicroPython interpreter 執行板端程式。

Host Python 建議使用 canonical import:

from mangobox import Mango

m = Mango()

舊教材的 import mangox2 仍保留相容性。

11. 安裝版資料位置

%LOCALAPPDATA%\MangoBox\MangoThonny\user_data
%LOCALAPPDATA%\MangoBox\MangoThonny\workspace
%LOCALAPPDATA%\MangoBox\MangoThonny\cache

安裝版將可寫資料與應用程式本體分離;解除安裝時可依提示選擇是否保留使用者設定與學習資料。

v0.4.3.1 驗證摘要

已完成 Learning Log/Assignment/projection regression、Host 與 High-Level MicroPython lifecycle、作業 transfer/import/resource-policy、source-aware 繁體中文 Error Advisor、Advisor engagement/feedback/follow-up analytics、Portable Build + Package Verification,以及正式 Installer install/launch/shortcut/upgrade/uninstall/reinstall smoke。