MaaLYSK开发规范

一、Pipeline JSON 文件管理规范

目录结构

所有 Pipeline JSON 文件统一存放在 /pipeline/ 目录下，按功能类型划分子文件夹：

/pipeline/
  ├── base.json                 # 高复用基础节点（主页面点击、当前页面确认等）
  ├── mainmap.json              # 高复用导航节点（返回操作）
  ├── popop.json                # 高复用弹窗节点（牵绊度提升、点击空白继续等）
  ├── daily/                    # 日常
  ├── weekly/                   # 周常
  ├── fight/                    # 作战
  ├── event/                    # 限时活动
  ├── playtime/                 # 快乐出游（喵喵牌/娃娃机）
  └── feature/                  # 特色功能

文件命名规范

采用蛇形命名法（snake_case），全部使用小写字母，单词间以下划线连接。

存放位置	命名要求	示例
/pipeline/	高复用节点文件与游戏启动文件，功能命名	base.json、mainmap.json、popop.json
./daily/	日常任务，一般以 daily_ 为前缀	daily_energy.json、daily_shopping.json
./weekly/	周常任务，一般以 weekly_ 为前缀	weekly_end.json、weekly_shopping.json
./fight/	作战，使用战斗板块英文名称	bounty_hunt.json
./event/	限时活动，建议以 event_ 为前缀	event_daily_get.json、event_shopping.json
./playtime/	快乐出游小游戏，使用中文拼音或英文翻译	catcard_collect、weekly_game_catchtoy.json
./feature/	特色功能，使用中文拼音或英文翻译	message.json、telephone.json

IMPORTANT

特殊说明：

• 限时活动中，每日领取、读剧情等节点可以直接复用，因此每次只需重新截图即可。小游戏等可以存个备份，最后加上活动的日期或活动名。
• 特色功能部分目前只有手机读朋友圈/短信/电话等功能，后续如果板块增多需考虑加上phone的前缀。

文件存放规范

• daily、weekly文件夹：放置仅为完成日常/周常而设定的任务

• 其他文件夹：放置对应板块的任务，如快乐出游、战斗、限时活动等。

  可以利用对单个json加前缀的方式区别其属于日常/周常任务，如weekly_game_catchtoy.json、event_daily_get.json等。

二、节点命名规则

同样采用蛇形命名法（snake_case），但节点命名为中文，下划线为隔开前缀/后缀的标志。

多复用节点命名规则

多复用节点指可在多个 Pipeline 中重复使用的子流程，统一存放在 /pipeline/ 目录下。

目前多复用节点大致分为三类：入口导航节点、右上角返回节点、弹窗节点、选人节点。

其中，选人节点由于通用、无需新增，具体参照代码编写指南-选人模块进行使用即可。

文件	功能说明	命名规则	示例
base.json	主页面、各版块菜单的点击节点 对应页面的确认节点 各种通用 [JumpBack] 节点	点击xx xx页面确认	点击商城 商城页面确认 进入手机信息
mainmap.json	返回上一页按钮 返回上级页面 返回主页面	导航回xx页面（xx）	导航回主页面 导航回上级页面
popop.json	各类弹窗节点 （牵绊度提升、获取奖励）	退出xxpopop 确定返回xxpopop 取消返回xxpopop	退出牵绊度popop 退出获取奖励popop 确定返回快乐出游popop

• 利用base里的节点可以很好地复用入口节点。

• 利用popop里的节点可以很好地复用弹窗节点。

• base、popop节点写好后，把它们添加到mainmap对应的“返回上一级页面”等节点中，便于更好的复用。

• 请在写上述几类节点前，先查查这几个文件中有没有已经写好的节点，没有的话写好后也放到对应文件夹里。

• 确定返回xxpopop、取消返回xxpopop具体参照腾讯文档 - MaaLYSK收集表和代码编写指南

其他节点命名规则

具体参照MaaLYSK现有代码实例。

前缀规则

为了增强区分度，节点最好加上前缀以便区分，而不是简单地使用“一次点击”、“点点点”等名称。

• 对于有日常、周常、活动之分的，加上日常_、周常_的前缀。

  例：日常_点击礼包，周常_点击礼包

• 对于各个板块里的识别点击节点，加上各版块的前缀。

  例：喵喵牌_点击快乐出游、芯核向左滑、写真_选择祁煜

战斗规则

• 自动追击命名规则：芯核自动追击1次、豆佬自动追击10次
• 可以选择关卡的命名：选择追踪豆佬关卡，然后在interface中选择相关内容

其他规则

• 每一个开始类节点（interface中的entry入口），命名为进入xx。

  例：“进入星间探测”、"进入自动读短信"

• 节点命名尽量与识别内容（OCR文字、图片名称）进行匹配

  NOTE

  内容匹配：

  如OCR识别内容为确定，节点命名成”前缀_xx_确定“，不要写成确认。

  图片里识别内容为一键领取等类似内容，节点命名与图片内容、图片名称尽量一致。

三、图片存放规范

目录结构

所有图片资源统一存放在 /image/ 目录下，按功能模块划分子文件夹：

/image/
  ├──                   # 通用图片（领取、确认、关闭、男主图片识别等）
  ├── login/            # 登录相关图片
  ├── mainmap/          # 主界面导航返回相关图片
  ├── popop/            # 弹窗退出相关图片
  ├── fight/            # 战斗相关图片
  ├── event/            # 限时活动相关图片
  ├── phone/            # 手机相关图片
  ├── playtime/         # 快乐出游相关图片
      ├── catcard/      # 喵喵牌
      ├── catchtoy/     # 娃娃机
  ├── feature/          # 特色功能相关图片
  ├── task/             # 任务完成相关图片（主要为日常、周常）
      ├── daily/        # 日常
      ├── weekly/       # 周常
  └── shopping/         # 购物相关图片（通用）
      ├── daily/        # 日常购物（对应 daily_shopping.json）
      ├── weekly/       # 周常购物（对应 weekly_shopping.json）
      └── event/        # 活动购物（对应 event_shopping.json）

图片引用

在 JSON 文件中引用图片时，使用相对路径：

"商城每日礼包": {
  "recognition": {
    "type": "TemplateMatch",
    "param": {
      "template": ["shopping/daily/商城每日免费礼包.png"],
      "roi": [60, 279, 583, 926],
      "order_by": "Score",
      "threshold": [0.85]
    }
  },
  "action": {
    "type": "Click",
    "param": {}
  },
  "timeout": 5000,
  "next": ["每日礼包领取", "每日礼包售罄"]
},

四、MaaLYSK格式化要求

MaaLYSK 使用一系列的格式化工具来保证仓库中的代码和资源文件美观统一，以便于维护和阅读

请确保在提交之前已经格式化，也可以在本地手动格式化

格式化插件列表

目前启用的格式化工具如下：

文件类型	格式化工具
JSON	prettier
Markdown	MarkdownLint

安装依赖

npm install          # 安装 Node.js 依赖（prettier 等）

手动格式化

在项目根目录下执行以下命令：

npm run format          # prettier 格式化 JSON 文件

请确保在提交之前已经格式化，或是启用 Pre-commit Hooks 进行自动格式化

五、代码编写规范

采用pipelineV2、interfaceV2规范。

新增功能

interface规范

preset（预设）模块

新增一个功能时，注意将这个功能放进对应的preset模块中。

现有目录及预设模块分类说明如下（interface.json 位于 resource/ 根目录，其余预设均在 resource/tasks/preset/ 子目录下）：

预设模块	对应文件	存放说明	示例
全部任务列表	interface.json	【必放】 所有新增任务均需列入此表	/
日常任务	Daily.json	每日重置的基础任务与奖励领取	🍰领日常体力、📅日常收尾
周常任务	Weekly.json	每周刷新的固定任务	📷周常拍大头贴、🐱🗓️周常收尾
限时活动	Event.json	有明确起止时间的限时活动	🛍️限时活动商城领取、🏅喵喵牌限时抽卡
特色功能	Feature.json	系统全局、挂机等特色解手功能	📲自动读短信、🎮周常娃娃机

tasks（任务配置）模块

新增一个功能时，根据内容放入对应的tasks/xxx.json文件下。

如需新增一个文件，在interface.json的import字段中，需写入新增的文件。

文档编写

1、在docs/zh_cn/manual/1.2-功能介绍.md中，新增关于这个功能的介绍，包括每个选项的介绍与注意事项。

功能介绍举例

2、在assets/resource/Announcement/Changelog.md中，也可稍微编辑一下功能、选项的介绍，以便发公告大家了解新功能。

修复功能

常驻功能修复

代码更改

1、同步更新 interface 中对应的 description等内容。

2、改动了 base.json / popop.json / mainmap.json 中的共用节点，需确认其他 pipeline 不受影响。

2、改动了图片文件，需确认命名和路径符合图片存放规范。

文档修正

1、修复影响用户操作方式时，需同步更新 docs/zh_cn/manual/1.2-功能介绍.md。

2、重要 bug 修复时，需在 assets/resource/Announcement/Changelog.md 中写明。

3、纯内部修复（截图更新、ROI 微调、threshold 调整等，不影响用户使用）可不写文档。

活动适配

1、修改活动 pipeline 时，需同步更新 interface 中的版本、入口、选项说明。

2、尽可能复用已有代码，task 标题固定不变。

六、各种ROI、target

放置一点通用节点的roi、target参数，方便统一使用

1、侧边点击的target（在获得奖励、领取等页面点击的侧面）：[19,936,12,13]，[64, 894, 3, 3]（娃娃机结算卡）

2、fight/自动追击1次.png（芯核为单独位置，此为零点追踪的通用位置）

• ROI：[208, 939, 45, 45]
• target：[179, 952, 30, 20]

3、fight/自动追击10次.png

• ROI：[338, 941, 50 42]
• target：[318, 954, 30, 20]

4、选择追踪关卡：

• 9：ROI： [408, 306, 60, 68], target: [427, 330, 28, 30]

• 8：ROI： [522, 445, 47, 50], target: [542, 461, 22, 22]

• 7：ROI： [443, 589, 47, 68], target: [467, 611, 17, 15]

• 6：ROI： [312, 712, 35, 55], target: [336, 732, 15, 15]

• 5：ROI： [153, 612, 42, 47], target: [172, 629, 19, 18]

• 4：ROI： [290, 494, 40, 51], target: [308, 510, 16, 17]

• 3：ROI： [121, 358, 46, 50], target: [144, 378, 18, 14]

• 2：ROI： [269, 261, 46, 52], target: [292, 282, 15, 14]

• 1：ROI： [171, 167, 44, 53], target: [192, 188, 16, 14]

5、主页面识别（可以用共用节点已在主页面）

ROI：[20, 56, 49, 35]

6、横屏战斗点击空白处关闭

• ROI：[510,534,253,134]

7、退出战斗按钮

ROI：[63,1,84,66]

8、检测到道具框（体力耗尽/喵喵牌耗尽等）

ROI：[412, 407, 137, 48]

9、返回键识别

ROI：[0,0,88,132]

10、剧情

点击自动按钮：ROI：[473, 1203, 33, 18]

点击2倍速：target: [571, 1198, 17, 23]

点点点用来加快剧情：[631, 917, 25, 29]（仍待调试）