ok-ef 開發者快速開始

1. 從原始碼執行

專案	當前要求
作業系統	Windows 10/11；互動、截圖和登入流程依賴 Win32
Python	3.12；CI 和 China 打包配置均固定為 3.12
許可權	建議管理員許可權執行終端/IDE，以與遊戲許可權一致
遊戲視窗	16:9，最低 `1920x1080`（1080P）；見 `src/config.py`

git clone --recurse-submodules https://github.com/AliceJump/ok-end-field.git
Set-Location ok-end-field

經上述命令克隆後，確保安裝了 uv 這一依賴管理程式，隨後：

uv sync
uv run python main_debug.py

若 clone 時漏了子模組：

git submodule update --init --recursive

main.py 和 main_debug.py 都會先呼叫 install_startup_patches()，再構造 ok.OK(config)；Debug 入口只額外設定 config["debug"] = True。

2. 新增一次性任務

最小任務放在 src/tasks/onetime/MyTask.py：

from src.core.BaseEfTask import BaseEfTask


class MyTask(BaseEfTask):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = "我的任务"
        self.description = "执行一个可重复验证的步骤"
        self.default_config.update({"等待秒数": 1})
        self.config_description.update({
            "等待秒数": "操作完成后的等待时间。",
        })

    def run(self):
        self.ensure_main()
        self.log_info("任务开始")
        self.sleep(self.config.get("等待秒数", 1))

在 src/config.py 的 config["onetime_tasks"] 中註冊模組路徑和類名：

["src.tasks.onetime.MyTask", "MyTask"],

不要直接賦值 self.default_config = {...}；多重繼承任務需要保留 MRO 中其它 Mixin 已註冊的配置。

3. 新增觸發式任務

from ok import TriggerTask

from src.core.BaseEfTask import BaseEfTask


class MyTriggerTask(BaseEfTask, TriggerTask):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = "我的触发任务"
        self.description = "后台检查条件并执行动作"

    def run(self):
        if self.find_one("some_feature"):
            self.log_info("检测到目标")

註冊到 config["trigger_tasks"]：

["src.tasks.trigger.MyTriggerTask", "MyTriggerTask"],

現有組合可作為 MRO 參考：AutoCombatTask(BattleMixin, TriggerTask)、ItemNavigatorTask(WsPositionMixin, BaseEfTask, TriggerTask)。業務 Mixin 已繼承 BaseEfTask 時不需要再次顯式列出 BaseEfTask。

4. 複用現有能力

核心能力現在位於 src/core/base_mixin/，業務能力位於 src/tasks/mixin/：

from src.tasks.mixin.battle_mixin import BattleMixin
from src.tasks.mixin.map_mixin import MapMixin


class MyBattleTask(MapMixin, BattleMixin):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = "地图战斗任务"

    def run(self):
        self.ensure_main()
        self.ensure_map()

常用規則：

Feature 使用 FeatureList 或其中存在的字串名稱；find_feature 返回列表，find_one 返回首項。
OCR 文本使用 self.lang.<module>.<key>，資源寫入統一的 assets/lang/<module>.json。
可改鍵操作用 press_key、press_industry_key 或 press_combat_key；引數傳預設按鍵值。
self.click(box) 可點選識別框；當前專案封裝不使用 click(box=...) 示例。
login_flow(username) 選擇登入介面的最近賬號，不輸入密碼。

5. 驗證

執行全部測試：

uv run python -m unittest discover -s tests -p "Test*.py"

倉庫的 run_tests.ps1 會逐個執行 tests/*.py，也可使用：

.\run_tests.ps1

新增語言引用後至少執行：

uv run python -m unittest tests.TestCheckLang
uv run python -m unittest tests.TestPoLocaleConsistency

涉及視窗、OCR 或遊戲狀態的行為仍需用 main_debug.py 實機驗證；測試集中既有純離線測試，也有依賴樣本圖片和 ok-script 測試工具的測試，不能概括為全部不需要專案資源。