快速開始

1. 從模板建立倉庫

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

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

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

使用 AI 程式設計工具（推薦）：在 Codex 中輸入 使用 $initialize-ok-script-app 初始化这个仓库。使用其他工具時，讓它先閱讀 .agents/skills/initialize-ok-script-app/SKILL.md。初始化助手會先詢問遊戲名、執行目標、倉庫地址、圖示和首個任務，再修改專案。
手動初始化：繼續完成本文和後續頁面中的步驟。

2. 安裝 Python 3.12 和專案依賴

安裝 Python 3.12.10，然後在倉庫目錄中執行：

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
$PypiIndex = "https://pypi.org/simple/"
python -m pip install --index-url $PypiIndex --upgrade pip

根據應用的執行目標選擇一個依賴 profile。Qt 桌面介面：

python -m pip install --index-url $PypiIndex --no-deps --upgrade -r requirements.txt
python main_debug.py

Web 介面：

python -m pip install --index-url $PypiIndex --no-deps --upgrade -r requirements-web.txt
python web_main_debug.py

鎖定檔案用於可重複安裝，是日常開發的推薦方式。如果需要直接從 pyproject.toml 解析最新的相容依賴，可以分別使用：

python -m pip install --index-url $PypiIndex ".[qt]"
python -m pip install --index-url $PypiIndex ".[web]"

只需執行與目標對應的一條命令。官方 PyPI 的 pip 索引入口是 https://pypi.org/simple/，而不是網站首頁 https://pypi.org/；使用後者會導致 No matching distribution found，即使該包實際存在。

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

3. 初始化應用

接下來完成以下工作：

按應用配置修改應用名稱、執行目標、圖示和更新倉庫。
按任務開發建立並註冊第一個任務。
啟動 Debug 模式：

python main_debug.py

執行測試：

python -m unittest tests.TestMain

驗證完成後，按打包與釋出配置工作流並推送 tag。