插件与开发扩展/任务动作与自定义流程扩展

本文说明 Whimbox 后端中与任务、动作、能力调用及自定义流程扩展相关的公开结构，并以仓库当前可见的项目说明为边界，帮助开发者判断应从哪些模块入手扩展自动化能力。

Purpose and Scope

本页聚焦以下能力边界：

whimbox/task/：任务模块，承载可供 Agent 调用的各种功能脚本。
whimbox/action/：动作模块，承载拾取、钓鱼、战斗等具体游戏动作。
whimbox/ability/：能力切换模块，用于组织或切换不同自动化能力。
whimbox/agent_workspace/：大模型上下文管理，与自然语言触发任务及技能扩展有关。
whimbox/interaction/、whimbox/ui/、whimbox/view_and_move/、whimbox/map/：任务和动作执行时依赖的交互、界面识别、移动视角和地图能力。
whimbox/agent.py、whimbox/rpc_server.py：分别代表大模型 Agent 调用入口及与前端通信的 RPC 边界。
scripts/：自动跑图和宏脚本的脚本仓库。

当前提供的源材料只有项目说明文档，未包含上述 Python 模块的实现、类定义、函数签名、注册逻辑、异常处理或测试。因此，本文不会臆测插件接口、任务基类、动作参数、返回值、生命周期或异常类型；对于这些内容，将明确标记为“实现细节未在当前源材料中找到”。

UI、前端 App、部署打包和具体模型实现不在本页展开。项目说明指出，本仓库是 Whimbox 后端，当前主要负责 RPC 服务、大模型调用和工具调用；前端 App 位于另一个项目。

Overview

Whimbox 的扩展模型可以从项目目录和功能清单中确认出一个分层方向：上层由 Agent 或 RPC 请求触发能力，中层由任务脚本编排流程，下层由动作、交互、识别、移动和地图模块完成实际操作。

项目说明将 task/ 定义为“任务模块（各种功能脚本，供 agent 调用）”，将 action/ 定义为“动作模块（拾取、钓鱼、战斗等等）”。这一区分意味着扩展一个完整流程时，应优先把“目标和步骤编排”放入任务侧，把“可复用的单次游戏操作”放入动作侧，而不是把所有逻辑都堆到 Agent 或 RPC 层。

已列出的功能也体现了这种组合关系：

每日任务包括美鸭梨挖掘、多个幻境、周本、朝夕心愿、星海拾光、星光结晶、大月卡和奇迹之冠巅峰赛。
自动小功能包括自动对话、自动采集、自动钓鱼和自动清洁跳过。
自动跑图包括路线录制、路线编辑、自动跑图，以及跑图中的采集、捕虫、清洁和钓鱼。
宏功能包括操作录制与播放，但不支持视角转动。
自动弹琴支持将 MIDI 乐谱转换为奇想盒脚本。
AI 对话可以通过自然语言触发上述能力，并在一定程度上支持 SKILL。

因此，自定义流程扩展通常可理解为：定义一个可被上层调用的任务流程，组合现有动作和识别能力，必要时使用路线、宏或 MIDI 转换结果作为外部脚本资源，再通过 Agent 或 RPC 暴露给前端。

Architecture

根据项目说明中给出的目录职责，扩展相关组件之间的关系如下：

外部调用方通过 rpc_server.py 与后端通信，或由 agent.py 根据自然语言调用工具。
task/ 提供面向目标的流程脚本，是最接近“任务插件”的位置。
action/ 提供可复用的具体动作。
interaction/ 提供截图及鼠标键盘等交互核心能力。
api/ 提供 OCR、YOLO 等第三方模型能力；ui/ 负责游戏 UI 的识别和操作。
map/、view_and_move/ 支持地图识别、大地图操作、视角及移动。
assets/、scripts/ 提供流程执行所需的资源和脚本。
config/、configs/ 提供全局配置和 Agent 工作区相关配置。

当前源材料没有给出模块之间的实际 import、调用链或依赖注入代码，因此上述关系是由 README 中的目录职责和功能说明直接归纳出的扩展边界；具体调用方向仍需以 Python 实现为准。

扩展边界与职责划分

任务模块：面向目标的流程编排

whimbox/task/ 被明确描述为“各种功能脚本，供 agent 调用”。适合放入任务模块的内容包括：

任务目标，例如完成某个每日任务或完成一次自动跑图。
多步骤顺序，例如识别目标、移动到目标区域、执行采集、判断是否完成。
任务级别的条件分支和完成判断。
对多个动作的组合，例如把移动、对话、采集和返回流程组合成一个可调用能力。
面向 Agent 的任务入口或工具包装。

不过，任务入口的实际命名、参数形式、同步或异步模型、取消机制和结果对象均未在当前源材料中出现。新增任务时不能仅根据本页推断这些接口。

动作模块：面向单次操作的复用能力

whimbox/action/ 被说明为动作模块，示例包括拾取、钓鱼和战斗。动作应尽量表达一个清晰、可复用的游戏操作，而不是绑定某个完整业务流程。

从现有功能清单可以确认的动作类别包括：

采集、拾取和捕虫。
钓鱼。
清洁，及跳过清洁的自动功能。
对话。
战斗相关操作。
与移动、视角或地图定位配合的操作。

动作的具体输入输出、识别前置条件、失败重试和停止条件未在当前源材料中定义。实现扩展时应先检查现有 action/ 文件，确认是否已有可复用动作，避免在任务脚本中重复模拟鼠标键盘或重复实现识别逻辑。

能力模块：组织可用功能

whimbox/ability/ 被定义为“能力切换模块”。从名称和项目结构可以确认它承担能力组织或切换职责，但 README 没有提供其公开 API、状态模型或切换规则。

在未读取实现前，以下内容均不能作为已确认行为：

能力是否以类、函数、注册表或配置项表示。
能力切换是否会改变 Agent 工具集合。
能力切换是否影响动作执行线程或当前任务。
能力是否支持插件动态加载。

因此，能力模块应作为扩展时需要重点核对的接入点，而不是依据目录名称直接创建假定接口。

自定义流程的组成方式

根据已公开的功能，可以把自定义流程拆成四类资源：

组成部分	对应目录或功能	已确认职责
流程入口	`task/`、`agent.py`	任务脚本供 Agent 调用；Agent 负责大模型能力
原子动作	`action/`	拾取、钓鱼、战斗等具体动作
感知与执行基础设施	`api/`、`interaction/`、`ui/`、`map/`、`view_and_move/`	OCR/YOLO、截图和输入模拟、UI 识别、地图及移动视角
外部流程资源	`scripts/`、`assets/`、`configs/`	跑图和宏脚本、地图与特征截图等资源、配置文件

一个新流程至少需要明确以下问题：

它是完整业务任务，还是可以被多个任务复用的原子动作。
它依赖哪种识别能力，是 UI 识别、OCR、YOLO、地图还是截图特征。
它是否需要移动、视角控制、路线或脚本资源。
它是否需要被 Agent 以自然语言触发，或只通过 RPC/内部调用触发。
它的完成条件、失败条件和用户可见结果是什么。
它是否会与已有自动任务、宏播放或跑图流程互相抢占输入控制。

上述问题中的接口细节和并发策略在当前源材料中没有答案，开发前必须回到对应源文件核实。

任务与动作的端到端调用方向

项目说明给出的系统入口是后端 RPC 服务、大模型调用和工具调用。结合目录职责，可以确定一个扩展流程至少跨越以下逻辑边界：

前端 App 或其他调用方发起 RPC 请求，或者用户通过自然语言请求 Agent 执行功能。
rpc_server.py 或 agent.py 将请求导向某个能力或任务入口。
任务模块根据目标组织多个动作。
动作通过交互模块模拟鼠标键盘并获取截图，再结合 UI、OCR、YOLO、地图或视角移动模块完成判断和操作。
任务依赖 assets/、scripts/ 或配置时，从对应资源中读取路线、特征或脚本数据。
任务完成后，将结果返回给上层调用方。

其中第 2、3、4、6 步的真实函数调用关系、消息格式、线程模型和结果协议未在 README 中提供。不能据此编写具体 API 示例。

路线、宏与脚本扩展

自动跑图路线

项目说明确认支持路线录制、路线编辑和自动跑图，并指出当前自动跑图暂时只支持大世界和星海。路线相关资源位于 scripts/，该目录被描述为“自动跑图和宏的脚本仓库”。

开发路线扩展时应区分：

路线数据本身：属于脚本或资源内容。
路线编辑：属于对路线资源的修改能力。
路线执行：属于任务流程，可能依赖地图、移动和视角模块。
路线中的采集、捕虫、清洁和钓鱼：属于动作组合。

README 没有公开路线文件格式、坐标系、版本兼容策略或路线执行 API，因此这些部分的实现细节未在当前源材料中找到。

宏录制与播放

项目说明确认支持录制操作和播放操作，但明确不支持视角转动的操作。该限制应作为扩展宏流程时的边界条件：不能假设宏能够重现包含视角变化的完整操作序列。

宏脚本同样位于 scripts/ 范围内，但当前材料没有说明宏格式、事件模型、播放速度、终止方式或错误恢复策略。新增宏能力前，应检查已有录制和播放实现，而不能自行假定脚本协议。

MIDI 转奇想盒脚本

自动弹琴功能支持将 MIDI 乐谱转换为奇想盒脚本。该能力表明脚本生成器可以作为一种扩展入口：外部格式先转换为项目脚本，再由后端执行。

目前没有公开转换器模块、脚本语法或执行入口，因此无法提供准确的转换 API 或脚本示例。相关实现细节未在当前源材料中找到。

Agent、SKILL 与自定义流程暴露

README 明确指出，AI 对话支持通过自然语言让奇想盒执行已有功能，并“一定程度上支持 SKILL”。这说明自定义流程不仅可能通过 Python 内部调用，也可能需要通过 Agent 的工具或技能描述暴露。

agent_workspace/ 用于“大模型上下文管理”，配置结构中也存在 configs/agent_workspace/，用于存放 Agent 的记忆。扩展 Agent 流程时，应重点确认以下实现事实：

Skill 的发现方式，是静态注册、文件扫描还是配置加载。
Skill 的描述、参数和返回结果格式。
Agent 是否允许调用任意任务，还是只允许白名单能力。
任务执行失败时，Agent 是否可以获得结构化错误并继续纠错。
上下文和记忆是否会影响任务选择。

当前源材料只确认“在一定程度上支持 SKILL”，没有给出 Skill 协议或注册实现。因此，不能在本文中声明具体 YAML、JSON、Python 装饰器或函数签名。

配置与资源

项目结构列出了两类配置位置：

whimbox/config/：全局配置模块。
configs/config.json：项目配置文件。
configs/agent_workspace/：存放 Agent 记忆。

同时，whimbox/assets/ 用于地图、特征截图、配置文件和文件模板等资源。扩展任务时应把稳定的资源数据与执行逻辑分离：地图、截图特征、模板和路线不应无必要地硬编码在任务流程中。

当前材料没有列出任何配置键、类型、默认值、环境变量覆盖规则或热加载行为。配置参考表无法可靠建立；具体配置选项必须以 config/、configs/ 和相关调用代码为准。

失败模式、边界与安全注意事项

已确认的功能边界

项目仅支持 Python 3.12。
游戏运行目前要求标准 16:9 分辨率。
自动跑图暂时只支持大世界和星海。
宏录制与播放不支持视角转动操作。
图像识别会额外消耗性能，目前仅支持中高配 PC。

这些限制会直接影响自定义流程：流程不能假定任意分辨率下的识别坐标都有效，也不能假定宏可以代替需要动态视角控制的任务。

输入控制风险

项目说明指出，Whimbox 不修改游戏文件、不读写游戏内存，只进行截图和模拟鼠标键盘；同时也明确使用后果由用户自行承担。新增动作或任务时，应保持这一运行模型，不应引入未经项目说明支持的进程注入、内存读写或游戏文件修改机制。

未知的错误处理

当前源材料没有公开任务取消、超时、重试、异常映射、日志字段、状态恢复或输入锁机制。因此以下行为均属于实现待核实项：

动作识别不到目标时是否重试。
RPC 断开时任务是否继续运行。
多个任务同时启动时是否排队或拒绝。
游戏窗口失焦时是否暂停。
任务失败时是否回滚已经执行的动作。

开发者应在实际实现和测试中补齐这些行为的文档，而不是根据目录结构作出默认承诺。

扩展开发建议

在实际代码可读之前，推荐采用以下工作顺序：

从 task/ 找到与目标功能最接近的现有任务，确认任务入口和调用约定。
从 action/ 找到可复用的原子动作，优先组合而不是复制输入模拟逻辑。
检查任务使用的 ui/、api/、map/ 和 view_and_move/ 能力，确认识别结果及坐标约定。
检查 ability/ 是否要求显式注册、切换或清理状态。
检查 agent.py、agent_workspace/ 和配置目录，确定自然语言或 SKILL 暴露方式。
若流程依赖路线、宏、地图或截图特征，放入既有的 scripts/ 或 assets/ 资源体系。
在标准 16:9、高负载和任务中断等条件下验证流程。
为成功、目标缺失、识别失败、窗口状态异常和用户主动停止分别补充测试或日志。

以上是基于当前项目结构提出的工程化接入顺序；具体注册代码和测试框架尚未在源材料中找到。

Usage Examples

基础任务示例

当前源材料没有提供 task/ 下的 Python 实现、任务入口或可执行调用代码，因此无可用代码示例。

动作组合示例

当前源材料没有提供 action/ 下的实际类、函数或调用关系，因此无可用代码示例。请以仓库中的真实实现为准，避免根据本页自行推断参数和返回值。

Skill 或 Agent 扩展示例

当前源材料只说明“在一定程度上支持 SKILL”，未给出 Skill 文件格式、注册方法或工具签名，因此无可用代码示例。

API Reference

任务 API

实现细节未在当前源材料中找到。README 没有列出任务类、函数、参数、返回值或异常类型。

动作 API

实现细节未在当前源材料中找到。README 只描述了动作模块的职责和部分功能类别，不能据此生成准确签名。

RPC 与 Agent 接口

README 确认存在 rpc_server.py 和 agent.py，但未提供 RPC 方法、消息结构、认证方式、错误协议或 Agent 工具调用接口。具体 API 参考需要读取这些文件的实现。

测试与运维

当前提供的源材料没有列出测试目录、测试用例或 CI 配置，因此无法确认任务和动作是否已有自动化测试覆盖。

从项目说明可以确认的运维关注点包括：

使用 Python 3.12。
运行游戏和图像识别会产生较高性能消耗。
当前仅支持标准 16:9 游戏分辨率。
日志目录为 logs/。
后端通过 RPC 与前端 App 协作，仓库本身不再提供 UI。

性能指标、日志级别、日志格式、任务监控、并发限制和部署参数未在当前源材料中找到。扩展任务上线前，应补充至少一次完整流程日志和异常退出验证。

当前资料缺口

为了把本页进一步扩展为可直接使用的插件开发参考，还需要读取并核实：

whimbox/task/ 的任务实现和入口。
whimbox/action/ 的动作实现及公共抽象。
whimbox/ability/ 的能力注册或切换逻辑。
whimbox/agent.py 的工具调用与 Skill 接入。
whimbox/rpc_server.py 的 RPC 协议。
whimbox/interaction/、whimbox/ui/、whimbox/api/、whimbox/map/、whimbox/view_and_move/ 的真实依赖关系。
scripts/ 的路线和宏文件格式。
configs/config.json 及 Agent 工作区配置的真实键值。
测试文件、异常处理、取消机制和并发控制实现。

在这些资料补齐前，本页适合作为目录级扩展地图和边界说明，不应替代具体 API 文档。

对 Agent 和大模型调用的具体实现，请参阅 whimbox/agent.py 与 whimbox/agent_workspace/。
对前端通信协议，请参阅 whimbox/rpc_server.py 及对应的 Whimbox App 项目。
对路线和宏资源，请参阅 scripts/。
对全局配置，请参阅 whimbox/config/ 与 configs/config.json。
对识别、截图和输入模拟，请参阅 whimbox/api/、whimbox/interaction/ 与 whimbox/ui/。