快速開始
English · 文件中心 · 進階指南 · API 參考
本指南幫助你使用 ok-script 模板專案 ok-script-app 建立並執行自己的自動化專案。完成後，你將能連線 Windows 遊戲或安卓裝置、執行診斷，並開始編寫任務。
開始之前
- Windows 10 或 Windows 11
- Python 3.11 或更高版本（推薦 Python 3.12）
- Git
- Windows 客戶端遊戲，或已啟用 ADB 的安卓模擬器/裝置
1. Fork 專案
訪問 ok-script-app，點選頁面右上角的 Use this template，從模板建立自己的 GitHub 倉庫。
2. Clone 專案
將您復刻的專案克隆到本地。建議為您自己的專案起一個新名字。
git clone https://github.com/YOUR_USERNAME/your-project-name.git
cd your-project-name
請將 YOUR_USERNAME 和 your-project-name 替換為您的 GitHub 使用者名稱和您專案的名稱。
3. 安裝 Python
框架支援 Python 3.11 及以上版本，推薦使用 Python 3.12。可以從 Python 官網 下載。安裝後確認版本：
Python 下載渠道
中國大陸使用者推薦優先使用國內映象站：
- 清華大學開源映象站：訪問清華大學 Python 映象倉庫，選擇所需版本並下載安裝包。
- 華為雲映象站：訪問華為雲 Python 映象，選擇對應版本下載。
- 官方渠道：網路順暢時，可前往 Python 官方網站 Downloads 頁面下載。
在版本目錄中，Windows 64 位系統通常應選擇名稱包含 amd64.exe 的安裝程式。安裝時建議勾選 Add Python to PATH。
python --version
4. 建立虛擬環境
建議為專案建立獨立的虛擬環境，避免依賴衝突。
python -m venv .venv
.\.venv\Scripts\Activate.ps1
如果 PowerShell 阻止啟用指令碼，可以直接使用 .\.venv\Scripts\python.exe 執行後續命令。
5. 安裝依賴
使用 pip 安裝專案所需的所有依賴包。
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
6. 修改 config.py
此檔案是專案的核心配置檔案。您必須根據您要適配的遊戲型別，正確配置 windows 或 adb 部分，至少需要配置其中一項。
開啟 src/config.py 檔案，找到並修改以下配置：
windows：適配 Windows 客戶端遊戲時填寫。exe：遊戲執行檔名列表，例如['StarRail.exe']。start_exe：是否由指令碼啟動並檢查遊戲程序，預設為True。設為False後，啟動任務時不會自動啟動或檢查遊戲。start_method：啟動遊戲的方式，預設為start，也可使用os.startfile。interaction：互動方式，例如Genshin、PostMessage或Pynput。
adb：適配安卓模擬器或真機時填寫。packages：遊戲包名列表，例如['com.abc.efg1']。
您可以同時保留 windows 和 adb 的配置，指令碼會根據實際執行的遊戲視窗或裝置進行匹配。
7. 執行指令碼
專案提供了兩種執行模式：
除錯模式
python main_debug.py此模式會產生額外的日誌，並在遊戲介面上繪製方框來標註正在尋找的目標和區域，方便開發和除錯。
正式模式
python main.py此模式為正式執行版本，不會在遊戲介面上繪製額外內容。
重要提示： Windows 遊戲的輸入方式可能需要管理員許可權。如果互動沒有響應，請以管理員身份啟動終端或 IDE。模擬器和 ADB 裝置通常不需要管理員許可權。
8. 測試截圖功能
在程式介面中，點選 "截圖測試" 按鈕。程式會擷取當前螢幕並儲存。請檢查專案 screenshots 目錄下是否生成了新的截圖檔案，以確認功能正常。
9. 執行診斷任務
點選介面上的 "執行診斷任務" 按鈕。這將執行一個預設的診斷任務，幫助您檢查環境和配置是否正確。
10. 自定義你的任務
專案的核心在於任務的擴充套件。您可以根據您的具體需求，修改示例任務檔案或建立新的任務檔案：
src/tasks/MyOneTimeTask.py：用於實現只需要執行一次的單次任務（例如，點選簽到）。src/tasks/MyTriggerTask.py：用於實現基於特定觸發器（如時間、影像識別）迴圈執行的任務（例如，自動戰鬥）。
通過模仿這兩個檔案的結構，您可以建立更多符合您業務邏輯的 Task。
在 GitHub 查看來源 ↗