ok-kes 軟體需求文件 (SRD)

1. 專案概述

ok-kes 是一個基於 ok-py 框架的《卡厄思夢境》遊戲自動化輔助工具。通過 OCR 識別遊戲畫面並模擬點選/按鍵操作，實現遊戲內各項功能的自動化。

1.1 專案定位

• 目標使用者：卡厄思夢境玩家
• 執行環境：Windows 11，Python 3.12，miniconda3/oknikke 環境
• 框架依賴：ok-script（基於 PySide6 的 GUI 自動化框架）

1.2 技術棧

元件	技術選型
GUI 框架	ok-script (PySide6 + qfluentwidgets)
OCR	onnxocr-ppocrv5
繁簡轉換	OpenCC
影像處理	OpenCV + OpenVINO
雲端儲存	Supabase (PostgreSQL + REST API)
版本控制	Git + GitHub

---

2. 功能模組

2.1 自動卡厄思模式 (ChaosMode)

檔案: ok_tasks/ChaosMode.py, ok_tasks/utils_chaos.py

2.1.1 功能概述

自動運行遊戲內卡厄思模式副本，處理戰鬥、路線選擇、卡牌操作等完整流程。

2.1.2 核心邏輯

每秒觸發一次 run() 方法：

1. OCR 識別當前畫面文本，繁體轉簡體
2. 依次嘗試約 50 個頁面處理函式（PAGE_HANDLERS 列表）
3. 命中某一頁面則執行對應操作並結束本輪迴圈

2.1.3 頁面處理函式型別

類別	函式示例	功能
通用操作	handle_confirm, handle_next_step	確認、下一步等通用按鈕點選
戰鬥相關	handle_battle_auto_check	檢測自動戰鬥開關，檢查手牌數
路線選擇	handle_route_selection	按優先順序識別節點型別並選擇路線
卡牌操作	handle_select_card, handle_remove, handle_flash	移除/閃光/複製卡牌
商店	handle_shop	德朗商店購買卡牌
休息	handle_rest	免費休息恢復
事件	handle_event_task	事件任務選擇
面具	handle_mask_card, handle_chaos_mask_engraving	面具卡牌選擇與刻印
精神/治療	handle_mental_breakdown, handle_trauma_center	精神崩潰治療
探險結算	handle_expedition_result	記錄勝負，更新勝率統計
獎勵	handle_chaos_reward_claim, handle_chaos_reward_settlement	領取獎勵

2.1.4 配置項

配置項	型別	預設值	說明
任務優先順序	列表	["複製","信用點增加","移除"]	事件任務選擇優先順序
拉黑任務	列表	["咒術卡牌","壓力"]	事件任務過濾，描述包含關鍵詞則不選
閃光優先順序	JSON	{"劍雨":["生成2張極光劍"]}	卡牌閃光效果優先順序
移除卡牌列表	列表	["劍幕","劍光",...]	移除操作的目標卡牌
閃光卡牌列表	列表	["展開極光","劍雨",...]	閃光操作的目標卡牌
複製卡牌列表	列表	["展開極光","劍雨",...]	複製操作的目標卡牌
路線優先順序	列表	["休息","事件","小怪","boss"]	路線節點選擇順序
優先使用金幣治療	布林	True	創傷中心治療方式
治療崩潰	布林	True	精神崩潰時去創傷中心
優先移除基礎牌	布林	True	移除時優先選基礎牌
進入商店	布林	False	路線中是否進商店
保留存檔	布林	False	是否保留儲存資料
領取獎勵(只使用驗證卡)	布林	False	獎勵領取策略
指定面具卡牌	字串	"丟棄最多2張卡牌"	優先選擇的面具效果
面具卡牌刻印	字串	"自身攻擊卡牌傷害總量提升30%"	優先選的刻印效果
只打第一層	布林	False	通過一次最終boss後退出的圖層

---

2.2 自動出擊模式 (SortieMode)

檔案: ok_tasks/SortieMode.py, ok_tasks/utils_sortie.py

2.2.1 功能概述

自動運行遊戲內出擊模式副本，包括手牌識別與出牌、主戰員選擇等。

2.2.2 核心邏輯

與 ChaosMode 相同，使用 PAGE_HANDLERS 列表驅動頁面處理。

2.2.3 特色功能

手牌識別與出牌 (handle_battle_page):

• OCR 識別手牌區域卡牌名
• 按鍵識別（卡牌上的數字鍵位）
• 出牌卡手檢測（連續 3 輪同一張牌未出掉則兜底出牌）
• EP 能量檢測（滿能量時釋放 Ego 技能）
• 幀卡住檢測與恢復

主戰員選擇 (handle_member_selection, handle_battle_member_config):

• 按優先順序選擇主戰員
• 支援拉黑列表（跳過指定角色）
• 重新整理候選槽位
• 出戰主戰員選擇（戰鬥前配置）

卡牌操作:

• handle_battle_hand_select: 戰鬥中手牌選擇
• handle_get_card: 獲得卡牌頁面按優先順序選擇
• handle_draw_card_event: 抽牌事件選擇
• handle_discard_hand_card: 丟棄手牌
• handle_curiosity_activate: 尼婭的好奇心卡牌選擇
• handle_extra_card_use: 額外使用卡牌

其他:

• handle_boss_selection: 隨機選擇首領
• handle_rest_sortie: 休息區閃光/休息選擇
• handle_sortie_reward_settlement: 獎勵結算
• handle_rational_supply, handle_ether_supply: 資源補充

2.2.4 配置項

配置項	型別	預設值	說明
路線優先順序	列表	["休息","事件","小怪","boss"]	節點選擇順序
主戰員優先順序	列表	["米卡","尼婭",...]	會合主戰員選擇
出戰主戰員優先順序	列表	["海德瑪麗","九",...]	戰鬥前主戰員配置
獲得卡牌優先順序	列表	["展開極光","劍雨",...]	獲得卡牌時的選擇
出牌優先順序	列表	["劍雨","水之源",...]	戰鬥中出牌順序
丟棄卡牌優先順序	列表	["展開極光",...]	丟棄操作的目標
任務優先順序	列表	["選取隨機3條命運",...]	事件任務選擇
拉黑任務	列表	["咒術卡牌","壓力"]	事件任務過濾
拉黑主戰員	列表	["黛安娜","阿黛爾海特"]	跳過的角色
移除/複製/閃光卡牌列表	列表	...	各類卡牌操作的目標
跳過非優先順序卡牌	布林	True	獲得卡牌時跳過非優先順序
優先移除基礎牌	布林	True	移除時優先基礎牌
領取獎勵	布林	False	獎勵領取開關
進入商店	布林	False	路線中進商店
只打第一層	布林	True	通過最終boss後退出
生命值大於多少優先閃光	字串	"60"	HP 百分比閾值

---

2.3 配置同步與熱門配置

檔案: ok_tasks/config_sync.py, ok_tasks/config_io.py

2.3.1 上傳機制

• 觸發方式: 模式執行時每 300 秒（5 分鐘）自動檢查上傳
• 最低場數: 2 場（MIN_ROUNDS = 2，可配置）
• 上傳內容: 配置 base64 + 勝率 + 版本號 + 遊戲語言 + 匿名使用者 hash
• 不上傳: 個人身份資訊、遊戲賬號、截圖、IP 地址

2.3.2 匿名使用者標識

_get_user_hash(): 組合 MAC 地址 + 主機名 + 使用者名稱，取 SHA256 前 16 位。

2.3.3 雲端儲存 (Supabase)

欄位	型別	說明
id	BIGINT	自增主鍵
mode	TEXT	"chaos" 或 "sortie"
config_b64	TEXT	配置的 base64 編碼
config_ver	TEXT	版本號
game_lang	TEXT	遊戲語言
win_rate	REAL	勝率 (0.0~1.0)
total_rounds	INTEGER	總戰鬥場數
user_hash	TEXT	匿名使用者標識
created_at	TIMESTAMPTZ	建立時間
updated_at	TIMESTAMPTZ	更新時間

唯一約束: (user_hash, mode, config_b64) — 同一使用者同一配置只保留一條記錄

2.3.4 熱門配置展示

• 排序方式：按平均勝率降序 / 按使用人數降序
• 展示上限：20 條
• 展示資訊：排名、勝率、使用人數、遊戲語言、版本

2.3.5 配置匯入匯出

• _export_config_to_text(): 匯出為 base64 編碼
• _import_config_from_text(): 從 base64 匯入（合併到當前配置）
• 按鈕功能：所有配置操作在 UI 的 config 按鈕中完成

---

2.4 通用功能

2.4.1 多語言支援

• 使用 OpenCC（繁轉簡）統一 OCR 文本處理
• i18n 通過 .po / .mo 檔案實現 UI 翻譯
• 全域性配置「遊戲語言」支援：簡體中文、繁體中文、日文、英文

2.4.2 卡牌識別增強（劍雨合併）

在 select_card 中，如果 OCR 將"劍雨"識別為分離的"劍"和"雨"兩個單字框，自動合併為一個 Box(name="剑雨")，刪除舊的單字框，使後續匹配能正確識別。

2.4.3 幀卡住檢測

is_frame_stuck(): 基於畫素變化檢測畫面是否卡住（連續 30 秒變化比例 < 0.5%），用于战斗恢复和日志输出。

---

3. 架构设计

3.1 整体架构

main.py (入口)
  └── ok.OK(config) ──→ GUI 启动
        ├── ChaosMode (TriggerTask)
        │     └── run() → 遍历 utils_chaos.PAGE_HANDLERS
        ├── SortieMode (TriggerTask)
        │     └── run() → 遍历 utils_sortie.PAGE_HANDLERS
        └── 全局配置 (Settings)
              ├── 游戏语言
              └── 配置上传开关

3.2 任务调度

• 继承 ok.TriggerTask，每秒触发一次 run()
• 每帧 OCR → 繁转简 → 依次尝试页面处理函数 → 命中即返回
• 帧末尾检查是否需要上传配置

3.3 互斥机制

• 开启 ChaosMode 时自动禁用 SortieMode
• 开启 SortieMode 时自动禁用 ChaosMode

3.4 数据流

用户操作配置 → 保存到 configs/ 目录 JSON 文件
      ↓
每 5 分钟 → 读取配置 → base64 编码 → 上传到 Supabase
      ↓
热门配置按钮 → 从 Supabase 获取 → 聚合计算 → 展示列表 → 用户选择 → 导入配置

---

4. 配置项总览

4.1 全局配置 (src/config.py)

配置分类	配置项	类型	默认值
游戏语言	游戏语言	下拉框	简体中文
配置上传	是否上传配置	开关	True

4.2 卡厄思模式配置（18 项）

任务优先级、拉黑任务、闪光优先级、移除卡牌列表、闪光卡牌列表、复制卡牌列表、路线优先级、优先使用金币治疗、治疗崩溃、优先移除基础牌、进入商店、保留存档、领取奖励(只使用验证卡)、指定面具卡牌、面具卡牌刻印、只打第一层、导出配置、导入配置、热门配置

4.3 出击模式配置（20 项）

路线优先级、主战员优先级、出战主战员优先级、获得卡牌优先级、移除卡牌列表、复制卡牌列表、闪光卡牌列表、领取奖励、出牌优先级、丢弃卡牌优先级、进入商店、卡牌奖励优先级、任务优先级、拉黑任务、拉黑主战员、跳过非优先级卡牌、优先移除基础牌、生命值大于多少优先闪光、只打第一层、导出配置、导入配置、热门配置

---

5. 环境要求

5.1 运行环境

• 操作系统：Windows 11
• Python：3.12 (miniconda3/oknikke)
• 游戏窗口：16:9 分辨率，最低 1280x720，推荐 1920x1080
• 网络：可选（上传配置及获取热门配置需要）

5.2 依赖

ok-script>=1.0.163
onnxocr-ppocrv5>=0.0.18
OpenCC>=1.2.0
opencv-python>=4.12.0
openvino>=2026.0.0
requests (用於配置同步)

5.3 声明的 OCR 库配置

'ocr': {
    'lib': 'onnxocr',
    'auto_simplify': True,
    'params': {
        'use_openvino': True,
    }
}

5.4 Windows 交互配置

'interaction': ['Pynput', 'PostMessage', 'Genshin', 'PyDirect', 'ForegroundPostMessage']
'capture_method': ['WGC', 'BitBlt_RenderFull', 'BitBlt']

---

6. 版本歷史

版本	日期	變更內容
v1.3.5	2026-07-22	新增熱門配置同步功能；提高劍雨卡牌識別率；新增拉黑任務功能；程式碼去重最佳化
v1.3.4	-	-
...	-	-