ok-end-field/文件

ok-ef 開發指南

返回：文件索引 / README

本文以當前原始碼、src/config.py、測試目錄和 workflow 為準，說明專案結構和貢獻流程。具體專案自有介面見 API 參考。

1. 執行架構

ok-ef 是基於 ok-script 的 Windows 遊戲自動化應用。倉庫負責業務任務、專案級識別/互動封裝、資源和自定義 GUI；截圖、基礎 OCR/Feature API、任務排程和主 GUI 由 ok-script 提供。

flowchart TD
    A[main.py / main_debug.py] --> B[src.config.config]
    A --> C[install_startup_patches]
    C --> D[ok.OK config]
    B --> D
    D --> E[onetime_tasks]
    D --> F[trigger_tasks]
    D --> G[custom_tabs]
    E --> H[业务 Mixin / BaseEfTask]
    F --> H
    H --> I[src/core/base_mixin]
    I --> J[ok.BaseTask]
    H --> K[Feature / OCR / YOLO / Win32 interaction]

當前關鍵技術配置：

領域 當前實現
Python CI 和 China 打包使用 3.12
平臺 Windows；遊戲程序 Endfield.exe、視窗類 UnityWndClass
捕獲 優先 WGC，後備 BitBlt_RenderFull
OCR onnxocr，啟用 OpenVINO 和 NPU 引數
Feature COCO 標註區域 + OpenCV 模板匹配
YOLO ONNX/OpenVINO，多模型註冊和按目標路由
UI ok-script GUI + qfluentwidgets 自定義頁
打包 PyAppify；China/Global profile

2. 基類與組合

2.1 BaseEfTask

基礎設施 Mixin 已從任務目錄移動到 src/core/base_mixin/：

BaseEfTask(
    WindowArrowDrawingMixin,
    AccountOverrideMixin,
    GameFlowMixin,
    RuntimeMixin,
    ok.BaseTask,
    ProcessManager,
)

職責：

類 檔案 職責
WindowArrowDrawingMixin src/core/base_mixin/window_arrow_drawing_mixin.py 導航箭頭視窗繪製
AccountOverrideMixin src/core/base_mixin/account_override_mixin.py 按穩定賬號 ID 覆蓋任務配置
GameFlowMixin src/core/base_mixin/game_flow_mixin.py 主介面、地圖、登入截圖、彈窗和場景流程
RuntimeMixin src/core/base_mixin/runtime_mixin.py Feature、點選、按鍵、移動、UI 穩定、YOLO
ProcessManager src/core/base_mixin/process_manager.py 遊戲程序終止能力

不要再引用舊的 src/tasks/mixin/runtime_mixin.py、game_flow_mixin.py、process_manager.py 或 window_arrow_drawing_mixin.py 路徑。

2.2 業務 Mixin

src/tasks/mixin/ 保留跨領域通用能力，src/tasks/navigation/mixin/ 保留導航領域能力：

BaseEfTask
├── Common
├── MapMixin
├── BattleMixin
├── MouseScanMixin
├── NavigationMixin
│   ├── LiaisonMixin
│   └── ZipLineMixin
└── LoginMixin
    └── AccountMixin

EndCommandMixin、WsPositionMixin、RuntimeStateMixin 是無 BaseEfTask 基類的 協作 Mixin，通過最終任務組合獲得任務能力。WsPositionMixin 是定位底層的南向介面卡， 業務任務讀取即時位置時應使用 RuntimeStateMixin，不要直接消費 WS。

2.3 實際任務 MRO

主要組合以類宣告順序為準：

DailyTask(
    Common, MapMixin, ZipLineMixin, BattleMixin, LiaisonMixin,
    EndCommandMixin, AccountMixin, MouseScanMixin
)

BattleTask(Common, MapMixin, ZipLineMixin, BattleMixin)
DeliveryTask(AccountMixin, ZipLineMixin, MapMixin)
AutoCombatTask(BattleMixin, TriggerTask)
ItemNavigatorTask(WsPositionMixin, BaseEfTask, TriggerTask)

DailyTask 的日常子功能不再全部作為 Python 基類混入。它在 __init__ 中組合 DailyBuyFeature、DailyBattleFeature、DailyTradeFeature、DailyShopFeature、DailyRoutineFeature、DailyLiaisonFeature、DailyDemoFeature 物件，並由 DailyTaskRunner 執行 build_task_plan()。

所有協作式 __init__ 都應呼叫 super()。配置字典使用 update 增量合併，避免破壞 MRO 前序類註冊的資料。

3. 註冊清單

src/config.py 是 GUI 註冊的唯一權威來源。

一次性任務

順序 類 模組
1 DailyTask src.tasks.onetime.DailyTask
2 TakeDeliveryTask src.tasks.onetime.TakeDeliveryTask
3 WarehouseTransferTask src.tasks.onetime.WarehouseTransferTask
4 DeliveryTask src.tasks.onetime.DeliveryTask
5 BattleTask src.tasks.onetime.BattleTask
6 DemoDrawTask src.tasks.onetime.DemoDrawTask
7 YingTuoTask src.tasks.onetime.YingTuoTask
8 TestStartGame src.tasks.onetime.TestStartGame
9 MinimapRealtimePosition src.tasks.localization.MinimapRealtimePosition
10 MinimapRegionCheck src.tasks.localization.MinimapRegionCheck
11 MinimapScaleCapture src.tasks.localization.MinimapScaleCapture
12 MinimapTurnToHeading src.tasks.localization.MinimapTurnToHeading
13 MinimapNavigateToPoint src.tasks.navigation.MinimapNavigateToPoint
14 RealtimeYoloScanTask src.tasks.test.RealtimeDetectTask
15 RealtimeDetectTask src.tasks.test.RealtimeDetectTask
16 PeriodicScreenshotTask src.tasks.test.PeriodicScreenshotTask
17 DiagnosisTask src.tasks.test.DiagnosisTask
18 MouseRotationCalibration src.tasks.test.MouseRotationCalibration
19 TestArrowAngle src.tasks.test.TestArrowAngle
20 TestCircularPulseDetect src.tasks.test.TestCircularPulseDetect
21 TeamCompositionDetectTask src.tasks.test.TeamCompositionDetectTask

一次性任務按「業務任務（src.tasks.onetime.*）→ 除錯/測試任務（src.tasks.test.*）」分組排列。

TakeDeliveryTask 的類宣告還包含 TriggerTask，但它當前只註冊在一次性任務列表中。

觸發式任務

順序 類 模組
1 AutoCombatTask src.tasks.trigger.AutoCombatTask
2 AutoInteractionTask src.tasks.trigger.AutoInteractionTask
3 AutoPickTask src.tasks.trigger.AutoPickTask
4 ItemNavigatorTask src.tasks.trigger.ItemNavigatorTask
5 TemplateMonitorTask src.tasks.trigger.TemplateMonitorTask

當前沒有 AutoLoginTask.py 或觸發式自動登入註冊。登入切換能力由 LoginMixin/AccountMixin 供多賬號任務呼叫。

自定義頁

  • GlobalConfigTab：全域性戰鬥、鍵位和基礎配置。
  • AccountConfigTab：賬號資料及按任務覆蓋配置。

4. 當前目錄

以下只列開發時需要理解和維護的檔案，不包含執行快取、日誌、截圖、IDE 後設資料和生成的檔案、目錄。

ok-end-field/
├── main.py / main_debug.py       # 正式/调试入口，均安装启动补丁
├── pyproject.toml                # 项目 Python 依赖声明
├── requirements.txt              # 由 uv 针对平台生成，供发布流水线 pip 使用
├── pyappify.yml                  # China/Global 打包 profile
├── deploy.txt                    # tag 构建时同步到更新仓库的清单
├── src/
│   ├── config.py                 # ok-script 应用配置、任务和 tab 注册
│   ├── globals.py                # 应用级共享对象
│   ├── icons.py                  # 图标定义
│   ├── core/
│   │   ├── BaseEfTask.py
│   │   ├── BattleConfig.py
│   │   ├── NavConfig.py
│   │   ├── config_migration.py
│   │   ├── global_config_store.py
│   │   ├── sequence_parser.py
│   │   └── base_mixin/
│   │       ├── account_override_mixin.py
│   │       ├── game_flow_mixin.py
│   │       ├── process_manager.py
│   │       ├── runtime_mixin.py
│   │       └── window_arrow_drawing_mixin.py
│   ├── localization/             # 小地图定位、融合、朝向与位置接口
│   ├── nav/                      # 二维网格、A* 规划与路线跟随
│   ├── runtime_state/            # 进程内 latest-value 状态网关与主题契约
│   ├── tasks/
│   │   ├── onetime/              # 一次性任务和 AutoCombatLogic
│   │   ├── localization/         # 定位、标定和朝向任务
│   │   ├── navigation/           # 导航任务与导航领域 Mixin
│   │   ├── trigger/              # 通用后台触发任务
│   │   ├── test/                 # 通用诊断与算法测试任务
│   │   ├── mixin/                # 业务能力 Mixin
│   │   ├── account/              # 账号解析、稳定 ID 和覆盖存储
│   │   └── daily/                # Feature 组合、runner、汇总和 misc 子功能
│   ├── data/
│   │   ├── FeatureList.py        # 模板名称字符串枚举
│   │   ├── characters*.py
│   │   ├── delivery_area*.py
│   │   ├── item_map_query.py
│   │   ├── world_map*.py
│   │   ├── zh_en.py
│   │   └── lang/__init__.py      # 统一 JSON 语言访问器
│   ├── interaction/              # Win32 输入、键位、鼠标、屏幕区域
│   ├── image/                    # HSV、登录截图、旋转模板
│   ├── yolo/                     # 模型定义、注册、加载和 OpenVINO 检测
│   ├── patches/                  # 启动 monkey patches
│   └── gui/                      # 全局/账号配置页、WebView 对话框
├── assets/
│   ├── coco_annotations.json
│   ├── images/                   # Feature 图片
│   ├── items/                    # 物品和地图数据
│   ├── lang/*.json              # 每模块一个统一多 locale JSON
│   ├── models/yolo/              # ONNX 模型
│   └── ocr_fix/ocr_text_fix.json
├── i18n/<locale>/LC_MESSAGES/   # gettext ok.po/ok.mo
├── configs/                      # 任务、全局、账号作用域配置
├── tests/                        # unittest 测试
├── scripts/                      # 维护/CI 脚本，按功能分目录
│   ├── i18n/                     # 语言与翻译维护（sync_* 官方译名同步、gen_lang_stubs、lang_fill_missing 等）
│   ├── data-capture/             # 官方 API / Wiki 数据抓取（capture_*、dump_*）
│   ├── release/                  # tag 辅助、requirements 生成、tag 冒烟
│   ├── docs/                     # mkdocs 构建辅助（mkdocs_mermaid）
│   ├── stats/                    # 下载统计 SVG 生成
│   ├── testing/                  # run_tests.ps1 测试运行
│   └── maintenance/              # 日志截图恢复、邮件工具
├── tools/                        # 脚本产出的本地数据（wiki_catalog 等，gitignored）
├── ok_tasks/                     # 用户自定义任务
├── ok_templates/                 # 模板标注子模块
└── .github/workflows/            # 构建、统计、地图数据和维护 workflow

5. 開發環境

git clone --recurse-submodules https://github.com/AliceJump/ok-end-field.git
Set-Location ok-end-field
uv sync
uv run python main_debug.py

約束：

  • 使用 Python 3.12 與當前 CI/打包環境保持一致。
  • 依賴通過 uv 管理：uv sync 依照 uv.lock 建立 .venv；uv run python ... 在該環境中執行 Python。requirements.txt 是面向釋出流水線的派生產物，不要手動編輯。
  • Windows 互動需要程序許可權不低於遊戲，開發時通常以管理員許可權啟動 IDE/終端。
  • 從倉庫根目錄執行，資源和配置路徑大量以當前工作目錄解析。
  • 遊戲視窗配置要求 16:9，最低 1600x900（900P）。
  • WGC 常規截圖不適合登入介面；登入 Mixin 使用 Win32 螢幕捕獲，通常需要視窗可見並可啟用。

6. 開發流程

6.1 新增任務

一次性任務通常直接繼承 BaseEfTask 或業務 Mixin：

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({"选项 A": True})
        self.config_description.update({"选项 A": "控制该步骤。"})

    def run(self):
        self.ensure_main()

註冊格式：

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

觸發式任務還需在最終 MRO 中包含 ok.TriggerTask，並註冊到 trigger_tasks。完整最小示例見 QUICKSTART。

6.2 新增業務 Mixin

  • 跨領域通用能力放 src/tasks/mixin/。
  • 導航、定位和滑索能力放 src/tasks/navigation/mixin/。
  • 基礎執行時能力才放 src/core/base_mixin/。
  • Mixin 不定義最終任務的 name、description 或 run()。
  • 若繼承 BaseEfTask，使用協作式 super()。
  • 如果 Mixin 只是依賴最終任務提供能力，可像 EndCommandMixin 一樣不繼承 BaseEfTask，但必須明確它的依賴。
  • 增加基類前用 Python 的 Class.__mro__ 檢查 C3 線性化，避免重複基類順序衝突。

6.3 任務配置

框架任務配置使用：

self.default_config.update({...})
self.config_description.update({...})
self.config_type[key] = {...}
self.default_config_group.update({...})

BaseEfTask.register_config_groups(groups) 可建立一個帶 sub_configs 的分組下拉框。配置舊鍵遷移通過類屬性 config_key_migrations 宣告，BaseEfTask.load_config() 會沿 MRO 合併後呼叫 migrate_config_file_keys。

全域性配置定義在 src/core/global_config_store.py：

  • Game Hotkey Config
  • Battle Config
  • Ensure Main Once Action Sleep
  • Zip Line Config
  • Nav Config
  • Position Config

戰鬥任務通過 BattleMixin.get_battle_config() 讀取。任務可通過「使用獨立配置」開關選擇全域性或獨立戰鬥配置；「使用獨立配置」關閉時，get_battle_config() 直接返回全域性配置，賬號任務覆蓋不會生效。僅當「使用獨立配置」開啟時，繫結賬號上下文後，賬號任務覆蓋才為最高優先順序。不要在多個任務中複製全域性戰鬥預設值。

網格導航的定位真值、解析度檔位比例尺與軸對映，以及網格規劃、行走和脫困引數均由 Nav Config 統一提供；導航任務側只保留目標 X/Z 等單次目標引數。定位鏈路見小地圖定位，規劃與執行見網格導航。

Position Config 儲存應用級 WorldPoseService 的執行引數（WS、里程計、融合、視覺校正和抓包後端）。該服務不是 TriggerTask，首次有消費者讀取 world_pose 時才建立和取樣；沒有消費者時不會後臺取幀。

6.4 Feature 資源

src/config.py 的 template_tab 會生成 src/data/FeatureList 標籤列舉，Feature 影像和標註以 assets/images/、assets/coco_annotations.json 及 ok_templates/ 資料為準。

from src.data.FeatureList import FeatureList as fL

box = self.find_one(fL.transfer_go)
boxes = self.find_feature([fL.monthly_card, fL.monthly_card2])

解析度名稱約定為無後綴、_2k、_4k。RuntimeMixin.get_feature_by_resolution() 只會選擇 FeatureList 中實際存在的名稱，缺失時拋 AttributeError。

6.5 OCR 與語言

OCR 業務文本儲存在單檔案 assets/lang/<module>.json，不是 locale 子目錄：

self.wait_ocr(match=self.lang.login_mixin.k_20275ef2, time_out=5)

當前活動 OCR locale 是 zh_CN、zh_TW。全域性混淆補丁只擴充套件 match，不改寫 OCR 輸出。新增資源和糾錯前閱讀 i18n 與 OCR 配置流程。

6.6 鍵位

可改鍵操作不得直接傳送預設字面值：

self.press_key("f")  # common
self.press_industry_key("y")  # industry
self.press_combat_key("e")  # combat

KeyConfigManager 只有 resolve_key(key, key_type)。方向移動、固定角色數字鍵、固定滑索鍵和 alt 等系統修飾鍵可按明確的不改鍵語義使用底層介面。若遊戲設定允許改鍵，對應 UI 圖示也不應做成固定按鍵字樣模板。

6.7 登入和多賬號

LoginMixin.login_flow(username) 通過登入介面的“最近賬號”列表選擇賬號，不輸入密碼。匹配手機號前三位和後四位；重複可見號碼結合“最近”標識與切換前賬號身份消歧，無法唯一確定時拒絕猜測。舊賬號行中首個逗號後的內容會被忽略且不儲存。

多賬號任務應使用 iter_multi_account_context() 或現有 AccountMixin 流程，並在讀取賬號覆蓋配置前設定 current_account_id。賬號覆蓋優先穩定 ID，使用者名稱僅作為後備。

7. 測試清單

當前 tests/ 有 42 個測試模組：

檔案 主要覆蓋
TestAccountBattleConfig.py 賬號配置可見性、快照合併、任務賬號配置黑名單、戰鬥配置優先順序
TestAccountOverrideMixin.py 賬號覆蓋 Mixin：僅任務執行時啟用覆蓋、其餘回退預設
TestAutoCombat.py 排軸技能序列解析（_parse_skill_sequence）
TestAutoPick.py 自動拾取規則（可生產植物預設跳過與開關）
TestCheckLang.py 原始碼語言 key 與統一 JSON 的 zh_CN/zh_TW 引用
TestConditionalRotation.py 排軸條件旋轉 AST 歸一化與 AutoCombatLogic.run() 即時條件路徑（含 if/else 分支）
TestConditionalRotationGui.py 條件旋轉 GUI 動作/條件格式化
TestDailyBattleToEnd.py 日常刷本到結束：YOLO 命中停用中鍵點選、獎勵等待
TestDailyBoatState.py 日常聯運狀態共享範圍
TestDailyConfigMigration.py 日常地區布林鍵合併遷移
TestDailyRegionalRunner.py 日常地區執行器（僅購買/回撥/重試）
TestDailyRewardWaits.py 日常獎勵領取等待邏輯
TestDailyTaskFinallyFile.py 日常彙總檔案生成和清理
TestDeliveryAreaConfig.py 送貨地區、搜尋區域、目標和券種配置
TestDeliveryRewardsClaim.py 送貨獎勵領取狀態處理
TestEfInteraction.py 視窗啟用與後臺訊息互動
TestEssenceImageFeatures.py 裝備詞條 Feature 資產存在性
TestFindZipLineBoardButton.py 滑索上車站點按鈕多階段查詢
TestGameWindow.py 遊戲視窗查詢（類名與執行檔匹配）
TestGifIcon.py GIF/主題圖示合成與快取失效
TestGrayBarDetector.py 灰條檢測演算法（合成幀）
TestGuiI18n.py GUI 翻譯呼叫和執行時採集汙染
TestItemMapQuery.py 物品地圖查詢和篩選
TestLogZipDedup.py 日誌打包圖片去重
TestMapDeviceFingerprint.py 地圖裝置指紋與註冊 payload 構造
TestMouseRotationCalibration.py 滑鼠視角旋轉系數標定角度差純函式與任務註冊
TestOkWin32GdiPointPatch.py Win32 GDI 座標補丁冪等安裝
TestOutpostExchange.py 據點兌換優先順序與排除邏輯
TestPoLocaleConsistency.py gettext catalog 完整性和一致性
TestPreConfigPatch.py 啟動前配置環境變數補丁
TestPressEsc.py press_esc 走任務鍵盤控制器
TestQfluentNavigationPatch.py qfluentwidgets 導航補丁迴歸
TestRealtimeGrayBarDetectTask.py 即時灰條檢測任務常量與除錯繪製
TestRuntimeMixinFeatureClick.py 普通/Alt Feature 點選路徑
TestScreenshotSidecar.py 截圖側邊資料序列化
TestSequenceParser.py 中英文逗號序列和整數序列解析
TestStateDrivenWaits.py 狀態驅動的等待（ensure_main/ensure_map/safe_back 等）
TestYingTuoTask.py 影拓豐碑關卡灰條識別
TestYoloDetect.py 檢測注入、ROI/overlay 和引數驗證
TestYoloModelRegistry.py 模型配置合併及目標路由
TestZipLineConfig.py 滑索全域性配置分組與舊配置遷移

推薦從倉庫根目錄執行：

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

或使用倉庫指令碼：

.\scripts\testing\run_tests.ps1

scripts/testing/run_tests.ps1 通過 uv run python 在專案 .venv 中執行，無需手動啟用虛擬環境。

測試並非全是無資源的純演算法測試。部分依賴 assets 圖片、OCR 樣本、OpenCV、ok-script 的 TaskTestCase 或 Windows 相關匯入。它們通常不要求正在運行遊戲，但視窗互動流程仍必須實機驗證。

8. CI、釋出與工具

.github/workflows/build.yml 只在推送 v* tag 時觸發：

checkout(LFS)
-> Python 3.12
-> pip install -r requirements.txt（requirements.txt 由 uv 从 pyproject.toml 生成）
-> inline ok-script requirements
-> 逐个运行 tests/*.py
-> 按 deploy.txt 同步更新仓库
-> PyAppify 打包
-> GitHub Release
-> 触发 MirrorChyan workflow

其它當前 workflow：

  • download_stats.yml：每日/手動生成並提交 .github/stats/downloads.svg（位於 deploy.txt 發版監測路徑之外）。
  • mirrorchyan_uploading.yml、mirrorchyan_release_note.yml：MirrorChyan 釋出流程。
  • update-endfield-map-data.yml：地圖資料更新。
  • stale.yml：issue/PR 維護。

scripts/release/auto_release.py、scripts/release/auto_release.ps1、scripts/release/auto_release.sh 是 tag 輔助指令碼。釋出行為以指令碼和 workflow 當前實現為準，不要假定測試在“打 tag 前”自動執行；CI 是 tag 已推送後啟動。

語言工具：scripts/i18n/ 保留 sync_*.py（官方譯名同步進 lang JSON 與 ok.po）、gen_lang_stubs.py（型別提示存根生成）、lang_fill_missing.py（缺失語言補全）和 restore_empty_po_entries.py（從 git 歷史恢復被清空的翻譯）；針對舊 assets/lang/<module>/<locale>.json 目錄 schema 的批次翻譯與遷移工具已隨 schema 切換刪除。詳見 i18n 文件。

9. 維護檢查

程式碼變更後按影響面檢查：

  1. 任務註冊變化：同步 src/config.py 對應使用者/開發文件。
  2. Mixin 或基礎設施移動：同步匯入示例和 MRO 圖，搜尋舊路徑。
  3. API 引數或返回語義變化：更新 API.md 並執行直接測試。
  4. 配置變化：同步預設值、描述、型別、全域性/任務/賬號優先順序測試。
  5. OCR 文本變化：更新統一語言 JSON，執行 TestCheckLang。
  6. GUI gettext 變化：執行 TestGuiI18n 和 TestPoLocaleConsistency。
  7. Feature/YOLO 變化：驗證資源、模型路由、ROI 座標及 Debug overlay。
  8. 互動流程變化：除單元測試外，用 main_debug.py 在支援解析度實測。

權威來源：

  • 註冊和應用引數：src/config.py
  • 核心組合：src/core/BaseEfTask.py
  • 執行時介面：src/core/base_mixin/*.py
  • 業務行為：src/tasks/**/*.py
  • 全域性戰鬥配置：src/core/BattleConfig.py
  • OCR locale/schema：src/data/lang/__init__.py
  • 測試範圍：tests/*.py
  • 釋出：.github/workflows/*.yml
在 GitHub 查看來源 ↗ · 頁面產生時間: 2026年10月23日