貢獻指南
設定開發環境並了解如何貢獻 Remaku。
Remaku 以 AGPL-3.0 授權開源，歡迎貢獻。
前置需求
專案結構
remaku/
main.py # 進入點
paths.py # 檔案路徑工具
theme.py # 主題管理
version.py # 版本資訊（從 pyproject.toml 讀取）
controllers/
home_controller.py # 主編輯器控制器
main_controller.py # 應用層控制器
macro_explorer_controller.py # 巨集瀏覽器邏輯
settings_controller.py # 設定頁面控制器
core/
capture.py # 畫面擷取（BetterCam / DXGI）
dialogs.py # 原生對話框輔助工具
display.py # 顯示器與螢幕資訊工具
event_bus.py # 全域事件系統
i18n.py # 多國語言
keymap.py # 虛擬鍵碼對應
keys.py # 鍵盤輸入模擬（pydirectinput）
vision.py # OpenCV 模板匹配
window.py # Windows 視窗管理
models/
config_model.py # 設定資料模型
macro_model.py # 巨集資料模型
pack_model.py # 巨集包目錄模型
step_dict.py # 步驟序列化／反序列化
step_node.py # 步驟樹節點模型
step_tree.py # 步驟樹管理器
resources/
icon.py # SVG 圖示引擎（Lucide）
resources.qrc # Qt 資源檔
icons/ # SVG 圖示檔案
images/ # 圖片資源
locales/ # Qt 翻譯檔（.ts / .qm）
services/
clipboard_service.py # 剪貼簿操作
engine.py # JSON 巨集解析與執行
hotkey_service.py # 全域熱鍵註冊
macro_import_service.py # 巨集匯入／匯出（ZIP）
macro_recorder.py # 鍵盤與滑鼠錄製
macro_runner.py # 巨集執行器
migration.py # 舊版資料遷移
pack_service.py # 巨集包目錄管理
template_service.py # 模板檔案管理
updater.py # 自動更新
views/
home_view.py # 主編輯器檢視
main_window.py # 主應用程式視窗
macro_explorer_view.py # 巨集瀏覽器 介面
region_selector.py # 螢幕區域選取
settings_view.py # 設定頁面介面
components/ # 可重複使用的 UI 元件快速開始
make setup # 建立虛擬環境並安裝依賴
make dev # 熱重載執行（需要 nodemon）執行 make 可查看所有可用目標。
開發指令
| 指令 | 說明 |
|---|---|
make setup | 建立虛擬環境並安裝依賴 |
make sync | 同步依賴 |
make dev | 熱重載執行 |
make test | 執行測試（含覆蓋率報表） |
make lint | 執行 ruff 程式碼檢查 |
make format | 執行 ruff 格式化 |
make format-check | 檢查格式但不變更 |
make typecheck | 執行 pyright 型別檢查 |
make check-all | 執行 lint、格式檢查、型別檢查與測試 |
make translate | 更新並編譯翻譯檔案 |
make build | 建置安裝程式 |
make clean | 清除所有建置產物與快取 |
程式碼風格
- 請勿在函式或變數名稱前加上
_前綴。 - 在區塊語句（
if、for、while）前後加入空行，elif/else前不加。
多國語言
使用者可見的字串請用 self.tr() 或 QCoreApplication.translate() 包裝。執行 make translate 更新並編譯 .ts / .qm 檔案。
測試
執行所有測試：
make test執行單一測試檔：
uv run pytest tests/path/to/test_file.py提交前檢查
送出 Pull Request 前，請執行 make check-all 確保全部通過。