快速上手（QUICKSTART）

本專案僅支援 Python 3.12，請以管理員許可權啟動終端。依賴管理使用 uv。

💡 提示：如果只需使用程式掛機或輔助，建議直接前往 GitHub Releases 下載打包好的安裝包執行，無需配置 Python 開發環境。

1. 安裝依賴

uv sync

2. 從原始碼執行

# Release 版
uv run python main.py

# Debug 版（开启调试模式，输出更多识别信息）
uv run python main_debug.py

3. 新增一個一次性任務

1. 在 src/tasks/onetime/ 下新建檔案，繼承 BaseGameTask（最簡範例見 src/tasks/test/test_screenshot_task.py，完整業務任務見 src/tasks/onetime/claim_daily_task.py 等）。
2. 在 __init__ 中設定 name、description、icon 與 default_config。
3. 實現 run(self)，使用 self.wait_ocr / self.wait_click_feature / self.click_relative 等 API。 若是「看到某東西 → 點它 → 驗證結果」這類流程，用 self.wait_action_result（識別源介面卡見 src/core/detector/）；只等一個結果用 self.wait_expectation。詳見 development.md 的 「Action 生命週期」一節。
4. 在 src/config.py 的 onetime_tasks 中註冊：["src.tasks.onetime.my_task", "MyTask"]。

4. 新增一個觸發式任務

1. 在 src/tasks/trigger/ 下新建檔案，繼承 BaseGameTask, TriggerTask（見 src/tasks/trigger/skip_dialog_task.py）。
2. 設定 trigger_interval 與 default_config。
3. 在 src/config.py 的 trigger_tasks 中註冊。

5. 模板匹配

標記模板資源後（ok-script 的標註工具），在 debug 模式執行一次會生成 src/data/feature_list.py 列舉。之後可用 self.wait_feature(FeatureList.xxx)。

6. 測試

./run_tests.ps1
# 或
uv run python -m unittest discover -s tests