企业官网建设流程全解析

ok-wuthering-waves 的 ok-script 任务模板详解：从 BaseTask 一次性任务到 TriggerTask 后台任务

【免费下载链接】ok-wuthering-waves鸣潮 后台自动战斗 自动刷声骸 一键日常 Automation for Wuthering Waves项目地址: https://gitcode.com/GitHub_Trending/ok/ok-wuthering-waves

本文基于 ok-wuthering-waves 仓库内置的开发参考文档 templates.md，系统讲解 ok-script 框架的几类任务模板：最小一次性任务（BaseTask）、后台触发任务（TriggerTask）、基于特征匹配的任务、带下拉/多选控件的配置声明、任务注册方式以及ok_tasks自定义脚本加载规则。读完本文后，你可以按照仓库现有的任务风格，为 ok-wuthering-waves（或任意基于 ok-script 的应用）编写、注册并通过校验清单验收新的自动化任务类。

一、模板文档在仓库中的定位

ok-script 是一套面向游戏/应用 GUI 自动化的 Python 库，ok-wuthering-waves 用它实现了自动战斗、刷声骸、一键日常等能力。仓库在 .agents/skills/ok-script-tasks/ 下维护了一份“如何创建和修改 ok-script 任务类”的开发技能说明，其配套参考文档正是本文的主体 templates.md。它与同目录的 task-api.md 分工明确：后者描述任务生命周期、执行器语义与配置模型，前者提供可直接套用的代码模板。

技能文档 SKILL.md 给出的工作流程可以概括为七步：

1. 检查目标项目已有的任务、应用配置和项目专属基类——如果项目已有基任务类（本项目是BaseWWTask），优先继承它而不是直接继承BaseTask；
2. 决定任务类型：BaseTask用于用户启动后跑完即止的流程，TriggerTask用于启用状态下循环巡检的后台检查；
3. 在__init__中补全任务元数据：name、description、default_config、config_description、config_type、supported_languages、图标、分组与调度标记；
4. 用run()实现小而可观测的步骤，优先使用self.log_info、self.info_set、self.wait_until、self.next_frame、self.sleep、self.click_relative、self.find_one、self.wait_click_feature、self.ocr、self.wait_ocr等框架方法，而不是自造轮询或直接调用设备；
5. 按项目风格注册任务：内置配置列表、ok_tasks自定义任务目录，或导入的脚本包；
6. 若项目使用 gettext 目录，用 i18n 工具同步任务文案；
7. 尽可能用项目的测试或无头路径验证；至少做到能导入模块并实例化类。

下面按 templates.md 的章节顺序，逐一展开每个模板，并结合本仓库的真实任务代码做印证。

二、最小一次性任务（BaseTask）模板

适用场景：用户主动启动、应当运行到完成的工作流。模板文档给出的最小示例是一个“领取奖励”任务，核心结构是：继承BaseTask，在__init__中设置元数据与默认配置，在run()中做“等待 OCR → 点击 → 成功即返回”的有限重试：

from ok import BaseTask, Logger logger = Logger.get_logger(__name__) class ClaimRewardTask(BaseTask): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.name = "Claim Reward" self.description = "Open the reward screen and claim available rewards." self.default_config = { "Retry Count": 3, "Confirm Text": ["Claim", "领取"], } self.config_description = { "Retry Count": "Maximum attempts before stopping. 最大尝试次数。", "Confirm Text": "Button OCR text to click. 要点击的按钮 OCR 文本。", } def run(self): for attempt in range(self.config.get("Retry Count", 3)): self.info_set("Attempt", attempt + 1) button = self.wait_ocr(match=self.config.get("Confirm Text"), time_out=3) if button: self.click_box(button, after_sleep=1) self.log_info("Task completed", notify=True) return self.next_frame() self.log_warning("No reward button found")

这个模板体现了模板文档（以及 task-api.md）强调的几条原则：

• 元数据先行：super().__init__(*args, **kwargs)必须最先调用，之后再设置name、description等字段。模板文档的校验清单明确要求“super().__init__在修改任务元数据之前执行”；
• 配置键与说明一一对应：default_config中每个用户可编辑的设置都要有默认值，config_description提供中英文帮助文本。Config只持久化默认值中存在的键，并强制默认值的类型（bool 渲染为开关、int 渲染为数字框、list 渲染为可编辑列表等，参见 task-api.md 的“Config Model”一节）；
• 双语 OCR 文本："Confirm Text": ["Claim", "领取"]同时覆盖英文与中文界面，校验清单也要求“当目标 UI 可能使用两种语言时，OCR 文本要覆盖中英文”；
• 有限重试 + 状态上报：self.info_set("Attempt", attempt + 1)把进度写到 GUI 状态区，log_info(..., notify=True)完成时发系统通知，失败时log_warning兜底；
• 一次性任务的执行语义：执行器检查到一次性任务被启用就运行它，run()返回后执行器自动禁用该任务——因此模板允许“正常完成即可”，不需要手动复位开关。

本项目中的一次性任务大多继承项目基类BaseWWTask，而不是直接继承BaseTask。BaseWWTask 在super().__init__()之后统一读取了月卡、角色、游戏热键三个全局配置（get_global_config），并提供logged_in属性、地图缩放、语言特性查找等公共能力。典型的例子是 MergeEchoTask（合并丢弃声骸）：run()先用全局热键配置self.key_config.get("Bag Key", "b")打开背包，用wait_until等待脱离战斗状态，sleep(3)后进入合并页面，再用 OCR 正则re.compile(r"100\s*/\s*100")判断是否还有整百批次可合并——这正是模板中“小步、可观测、状态等待”的风格。

三、触发任务（TriggerTask）模板

适用场景：启用状态下周期性检查某个条件是否出现的后台任务。模板文档的示例是一个自动关闭弹窗的任务：

from ok import TriggerTask class AutoClosePopupTask(TriggerTask): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.name = "Auto Close Popup" self.description = "Close known popups when they appear." self.trigger_interval = 1.0 self.default_config.update({ "_enabled": True, "Close Text": ["Close", "关闭"], }) self.config_description.update({ "Close Text": "OCR text for popup close buttons. 弹窗关闭按钮文本。", }) def run(self): close_button = self.ocr(match=self.config.get("Close Text")) if not close_button: return False self.click_box(close_button, after_sleep=0.5) self.log_info("Closed popup") return True

触发任务与一次性任务的三个关键差异：

1. trigger_interval决定巡检频率。按 task-api.md 的执行器语义：trigger_interval = 0表示每次扫描都有资格运行；trigger_interval = 5表示至多每 5 秒运行一次。模板文档特别提示要为触发任务设置合理的trigger_interval以避免过度轮询；
2. _enabled是显式的持久化开关。TriggerTask在default_config中内置_enabled，在on_create()时从配置读取启用状态，并通过enable()/disable()持久化变更。模板中用self.default_config.update({...})的方式是向已有默认值表追加键，这与BaseTask模板里直接整体赋值self.default_config = {...}不同，因为TriggerTask.__init__已经建好了含_enabled的表；
3. 返回值控制执行器的扫描循环。run()返回真值时，执行器会从队首重新开始扫描触发任务——所以只在“真正处理了有意义的动作”时才返回True，让更高优先级的触发任务有机会先执行；返回假值则让执行器继续扫描其余触发任务。

模板文档还提醒：如果继承项目基类，TriggerTask与项目基类谁前谁后“按本地示例来”，保持既有的方法解析顺序。本仓库的 AutoPickTask 正是这种混合继承的真实例子：

class AutoPickTask(TriggerTask, BaseWWTask):

TriggerTask放在BaseWWTask之前，使得触发任务的生命周期钩子优先于项目基类；而BaseWWTask提供的f_search_box属性、find_f_with_text等场景辅助方法继续可用。它的run()严格遵循了模板语义：先用scene.in_team(self.in_team_and_world)做前置条件检查，然后在 1 秒窗口内循环find_one寻找拾取标记，命中后按白名单/黑名单配置决定执行还是跳过，成功拾取时return True，无目标或命中黑名单时return False。

其他触发任务的trigger_interval取值也能印证“避免过度轮询”的要求，例如 AutoLoginTask 设为 5 秒、SkipDialogTask 设为 0.5 秒、MouseResetTask 设为 10 秒、AutoCombatTask 设为 0.1 秒（需要高频响应战斗帧）。BaseWWTask.py 中的一行注释还说明了这种约束的实际影响：登录点击后的稳定等待时间刻意设为 4 秒，保持低于AutoLoginTask的trigger_interval（5 秒），以免触发任务相互重叠。

四、基于特征匹配的任务模板

适用场景：任务逻辑围绕“等待某个 UI 特征出现并点击它”展开，特征名称来自目标应用模板匹配数据。模板示例：

from ok import BaseTask class ClickFeatureTask(BaseTask): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.name = "Click Feature" self.description = "Wait for a feature and click it." self.default_config = { "Feature Name": "start_button", "Threshold": 0.8, } def run(self): feature = self.config.get("Feature Name") threshold = self.config.get("Threshold", 0.8) self.wait_click_feature( feature, threshold=threshold, time_out=10, raise_if_not_found=True, after_sleep=1, ) self.log_info("Clicked feature")

模板要点：特征名和匹配阈值都放进default_config，让用户可在 GUI 里调整；用wait_click_feature一次性完成“等待 + 点击”，而不是手动轮询find_one再click_box；raise_if_not_found=True让超时直接以异常暴露问题，便于在测试阶段发现特征缺失。

在 ok-wuthering-waves 中，特征匹配由 config.py 的template_matching段统一驱动：特征标注数据在 assets/coco_annotations.json，全局默认阈值'default_threshold': 0.8，并通过 process_feature 作为feature_processor对特征名做预处理。hcenter_features/vcenter_features列表则声明了哪些特征需要以水平/垂直居中对齐计算坐标（如monthly_card、message_dialog）。仓库中真实任务大量使用这一模式，例如 MergeEchoTask.merge_full_batch 中的self.wait_click_feature(Labels.echo_select_all, horizontal_variance=0.3, after_sleep=1)，以及 AutoPickTask.run 中的self.find_one('pick_up_f_hcenter_vcenter', box=self.f_search_box, threshold=0.8)——注意特征名里的hcenter_vcenter后缀正对应config.py中居中对齐声明的产物，模板阈值 0.8 也与全局default_threshold保持一致。

五、带下拉框与多选的配置声明

模板文档给出了config_type的完整用法，用于把默认值类型无法表达的控件（下拉框、多选列表）显式声明出来：

self.default_config.update({ "Mode": "Safe", "Enabled Labels": ["A"], }) self.config_type.update({ "Mode": {"type": "drop_down", "options": ["Safe", "Fast"]}, "Enabled Labels": {"type": "multi_selection", "options": ["A", "B", "C"]}, }) self.config_description.update({ "Mode": "Execution mode. 执行模式。", "Enabled Labels": "Labels allowed for matching. 允许匹配的标签。", })

规则上（见 task-api.md）：GUI 控件默认从默认值类型推断（bool→开关、int→数字框、float→双精度数字框、str→单行/多行文本框、list→可编辑列表）；当需要下拉框、多选、全局配置联动、文本域或按钮时，用config_type显式指定。task-api.md 列出的受支持显式类型包括drop_down、multi_selection、global、text_edit、button。校验清单要求：config_type中的每个键都必须同时存在于default_config。

ok-wuthering-waves 的多个任务严格遵循这一模式，例如 FarmEchoTask：

self.config_type['Teleport to Boss'] = {'type': "drop_down", ...} self.config_type['Boss Level'] = {'type': "drop_down", 'options': ['50', '60', '70', '80', '90'], } self.config_type['Echo Pickup Method'] = {'type': "drop_down", 'options': self.find_echo_method} self.config_type['Boss'] = {'type': "drop_down", 'options': self.boss_list}

以及 EnhanceEchoTask 和 NightmareNestTask 的multi_selection用法、ChangeEchoTask 的中文键名drop_down用法。FiveToOneTask 展示了从列表动态生成多选选项的写法：先置self.config_type = {}，再遍历self.main_stats逐键写入{'type': "multi_selection", 'options': self.main_stats}。

六、任务注册：内置配置列表与自定义 ok_tasks 脚本

模板文档给出了两种注册方式的模板。内置注册是把“模块路径 + 类名”写入应用配置的onetime_tasks/trigger_tasks列表：

config = { "onetime_tasks": [ ["my_app.tasks.claim_reward", "ClaimRewardTask"], ], "trigger_tasks": [ ["my_app.tasks.auto_close_popup", "AutoClosePopupTask"], ], }

ok-wuthering-waves 的实际注册就在 config.py：11 个一次性任务（DailyTask、FarmEchoTask、NightmareNestTask、TacetTask、ForgeryTask、SimulationTask、MultiAccountDailyTask、MergeEchoTask、EnhanceEchoTask、ChangeEchoTask、GardenTask）挂在onetime_tasks下；6 个触发任务（AutoCombatTask、AutoPickTask、AutoLoginTask、SkipDialogTask注册为类名AutoDialogTask、FastTravelTask、MouseResetTask）挂在trigger_tasks下；场景则通过'scene': ["src.scene.WWScene", "WWScene"]声明。这印证了校验清单中“注册路径和类名必须与真实模块一致”的要求——每个条目都是["模块点分路径", "顶层类名"]的二元组。

自定义ok_tasks脚本面向启用了custom_tasks的应用：在顶层目录ok_tasks/下创建一个.py文件，文件内定义一个顶层任务类：

from ok import BaseTask class MyCustomTask(BaseTask): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.name = "My Custom Task" self.default_config = {"Message": "Hello"} def run(self): self.log_info(self.config.get("Message"))

加载器会扫描文件顶层类，实例化第一个BaseTask或TriggerTask子类——每个文件只暴露一个顶层任务类，其余类（常量、工具函数除外）不会被加载。本仓库 config.py 中'custom_tasks': True已启用该能力，仓库根目录保留了ok_tasks/目录供用户放置自定义脚本。无头（headless）调试时，task-api.md 还给出了run_task的用法：可以按索引、名称、类或实例运行任务，例如run_task(config, task=DailyTask, debug=True)，适合在没有完整 GUI 环境时验证新写的任务。

七、验收清单：提交前逐项核对

templates.md 末尾的 Validation Checklist 是模板文档的收尾部分，也是新任务类合入前的最低门槛：

• 导入成功：用目标项目的解释器能无错误导入任务模块；
• 实例化成功：类能被 ok-script 以executor和app关键字参数实例化（任务总是以这两个参数构造，再由after_init(executor=..., scene=...)初始化，见 task-api.md 的“Lifecycle”一节）；
• super().__init__在任何任务元数据修改之前执行；
• 每个用户可编辑的设置都出现在default_config中（不在默认值表中的键不会被持久化，也不会出现在 GUI）；
• 每个config_type键都同时存在于default_config；
• 触发任务包含_enabled且有合理的trigger_interval；
• OCR 文本在目标 UI 可能双语显示时同时覆盖英文和中文（本项目惯例如['吸收', 'Absorb']，见 AutoPickTask）；
• 注册路径与类名同真实模块一致（对照 config.py 中的注册表）。

另外两条来自 SKILL.md 的基本规则值得一并遵守：不要用绕过Config的方式读写设置——默认值写入self.default_config，读取一律走self.config.get(...)（在after_init()加载配置之后）；一次性任务允许正常完成，由执行器在run()返回后负责禁用任务。

八、小结：从模板到仓库实践的映射

把 templates.md 的模板与本仓库任务代码对照，可以得到一张清晰的“模板→落地”映射：

按照这套模板与清单开发，新任务既能在 GUI 中呈现完整的元数据与配置控件，也能在执行器的“一次性任务优先、触发任务循环扫描”语义下稳定运行——这正是 ok-wuthering-waves 保持任务可组合、可配置、可扩展的核心机制。

【免费下载链接】ok-wuthering-waves鸣潮 后台自动战斗 自动刷声骸 一键日常 Automation for Wuthering Waves项目地址: https://gitcode.com/GitHub_Trending/ok/ok-wuthering-waves