ok-script-app/文件

ok-script-app

English | 中文

ok-script-app 是一個基於 ok-script 的 Python 自動化專案模板。它提供了可直接執行的 GUI、任務示例、配置控制元件示例、OCR 示例、模板匹配示例、測試用例和打包配置，適合快速建立面向 Windows 原生遊戲、Android 模擬器或瀏覽器遊戲的自動化專案。

這個倉庫不是某個具體遊戲的自動化成品，而是 ok-script 應用的起步工程和功能演示。

功能演示

API 列表與指令碼錄製

image_scripting

多種截圖與互動方式

image_screenshot

標註管理與模板匹配

image_template image_markup

主要內容

  • 可直接啟動的 ok-script GUI 應用入口。
  • MyOneTimeTask 示例任務，演示常用任務 API 和配置控制元件。
  • 配置控制元件示例：下拉框、布林值、整數、浮點數、字串、多行文本、列表、多選、檔案選擇、資料夾選擇、全域性配置和按鈕組。
  • OCR、相對區域識別和模板匹配示例。
  • ConfigOption 全域性配置示例。
  • TaskTestCase 自動化測試示例。
  • i18n 翻譯檔案和 .mo 編譯產物。
  • pyappify.yml 和 GitHub Actions 打包釋出配置。

快速開始

1. 從模板建立倉庫

點選 GitHub 上的 Use this template，建立你自己的 repository，然後 clone：

git clone https://github.com/<你的 GitHub 用户名>/<你的仓库名>.git
cd <你的仓库名>

clone 完成後，可以選擇以下任一方式初始化專案：

  • 使用 AI 程式設計工具（推薦）：在 Codex 中輸入 使用 $initialize-ok-script-app 初始化这个仓库。使用其他 AI 程式設計工具時，請讓它先閱讀 .agents/skills/initialize-ok-script-app/SKILL.md。初始化助手會先詢問遊戲名、執行平臺、Windows 程序名、Android 包名或瀏覽器 URL、倉庫地址、圖示和第一個任務等資訊，再修改專案。
  • 手動初始化：繼續完成下面的步驟。

2. 安裝 Python 3.12 並建立虛擬環境

安裝 Python 3.12.10（Python 3.12 最後一個提供 Windows 安裝包的完整維護版本），然後在倉庫目錄中執行：

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt --upgrade

通常不需要管理員許可權；如果目標遊戲以管理員許可權執行，自動化程式也需要使用相同許可權啟動，否則截圖或輸入可能無法生效。

3. 根據遊戲修改 src/config.py

至少檢查並修改以下配置：

  • gui_title：應用視窗名稱。
  • windows：Windows 原生遊戲的 exe、視窗類名、互動方式和截圖方式。
  • adb.packages：模擬器或 Android 裝置上的遊戲包名。
  • browser：瀏覽器遊戲的 URL、顯示名稱和瀏覽器解析度。
  • supported_resolution：支援的畫面比例和最低解析度。
  • links：專案主頁、反饋渠道和社群連結。

windows、adb、browser 三種執行目標必須至少配置一種，也可以同時配置多種。瀏覽器配置示例已放在 src/config.py 中；啟用瀏覽器目標時，還需要安裝 playwright，並將它加入 requirements.in 和鎖定後的 requirements.txt，否則本地執行或 GitHub 打包會缺少依賴。不確定視窗或裝置資訊時，可以先執行 Debug 模式進行確認。

4. 替換應用圖示

使用自己的圖示替換 icons/icon.png 和 icons/icon.ico。保持檔名不變即可避免額外修改配置；如果更改檔名，還需要同步修改 src/config.py 和 pyappify.yml。

5. 配置更新倉庫

修改 pyappify.yml 中各 profile 的 name 和 git_url：

  • 正式釋出時，建議讓 git_url 指向單獨的輕量更新倉庫。
  • 前期測試時，可以直接指向第 1 步建立的原始碼倉庫。
  • 如果使用獨立更新倉庫，還需要同步修改 .github/workflows/build.yml 中的同步目標並配置對應的 GitHub Actions Secrets；刪除不使用的 CNB、MirrorChyan 等模板專用步驟。

6. 新建並註冊第一個任務

在 src/tasks 中新建任務類，然後將它新增到 src/config.py 的 onetime_tasks 或 trigger_tasks：

'onetime_tasks': [
    ["src.tasks.MyFirstTask", "MyFirstTask"],
    ["ok", "DiagnosisTask"],
],

一次性任務繼承 BaseTask，後臺觸發任務繼承 TriggerTask。可以參考 src/tasks/MyOneTimeTask.py，或讓 AI 使用 $ok-script-tasks 和 $ok-script-codegen 建立任務。

啟動 Debug 模式驗證配置和任務：

python main_debug.py

執行測試：

python -m unittest tests.TestMain

7. 推送 tag，觸發 exe 打包

推送 tag 前，必須先根據自己的專案修改 .github/workflows/build.yml，包括更新倉庫同步目標、安裝包名稱、Release 下載連結、Git 資訊和所需 Secrets。

  • 接入 Mirror醬：保留並修改 .github/workflows/mirrorchyan_uploading.yml 和 .github/workflows/mirrorchyan_release_note.yml 中的 owner、repo、mirrorchyan_rid、安裝包檔名等專案引數；同時保留 build.yml 中觸發這兩個工作流的步驟，並在倉庫中配置 MirrorChyanUploadToken。
  • 不接入 Mirror醬：刪除上述兩個 MirrorChyan workflow 檔案，並刪除 build.yml 中的 Trigger MirrorChyanUploading 步驟。

完成工作流配置後，提交併推送程式碼，再建立符合 v* 規則的版本 tag：

git add .
git commit -m "Initialize project"
git push origin HEAD
git tag v0.1.0
git push origin v0.1.0

GitHub Actions 會執行測試、打包 exe，並在倉庫的 Releases 頁面建立對應版本。首次釋出前，請再次檢查 .github/workflows 中是否仍有模板倉庫地址、模板專案名或尚未配置的 Secrets。

專案結構

src/tasks              任务类示例
src/config.py          ok-script 应用配置
src/ui                 自定义 UI Tab 示例
tests                  自动化测试用例
assets                 模板匹配资源和 COCO 标注
docs/images            README 使用的演示图片
i18n                   翻译文件
icons                  应用图标
.agents/skills         AI 初始化、任务开发、翻译和发布 Skills
main.py                普通入口
main_debug.py          Debug 入口
requirements.in        直接依赖列表
requirements.txt       锁定后的完整依赖
run_tests.ps1          PowerShell 测试入口
pyappify.yml           打包配置
deploy.txt             发布时同步到更新仓库的文件列表
.github/workflows      自动化构建与发布流程

開發任務

一次性任務示例位於 src/tasks/MyOneTimeTask.py，後臺觸發任務示例位於 src/tasks/MyTriggerTask.py。你可以從這裡開始：

  • 修改 default_config 增加任務配置預設值。
  • 修改 config_type 選擇配置控制元件型別。
  • 在 run() 中編寫自動化邏輯。
  • 使用 self.ocr() 做文字識別。
  • 使用 self.find_one() 或 self.find_feature() 做模板匹配。
  • 使用 self.info_set() 在 UI 中展示任務狀態。
  • 使用 self.log_info(..., notify=True) 傳送通知。

啟用自定義任務後，也可以在 GUI 中建立和編輯任務指令碼。

釋出相關檔案

  • .github/workflows/build.yml：監聽 v* tag，執行測試、同步更新檔案、打包並建立 GitHub Release。
  • pyappify.yml：定義應用名稱、入口、圖示、Python 版本和更新倉庫。
  • deploy.txt：定義需要同步到獨立更新倉庫的檔案。
  • .github/workflows/mirrorchyan_*.yml：可選的 Mirror醬上傳與更新日誌工作流；不接入時按快速開始第 7 步刪除。

ok-script 文件

社群

  • 使用者群：1097603920
  • 開發者群：938132715
  • Discord

致謝

在 GitHub 查看來源 ↗ · 頁面產生時間: 2026年8月9日