SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场maafw-interface

maafw-interface

编程与开发

查看项目

更新于 10-16 05:57

技能介绍

用途

maafw-interface 用于编写、修改与审查 MaaFramework 的 interface.json（Project Interface V2）。interface.json 是项目对外的标准化声明，通用 GUI、打包分发与工具链都依靠它认识项目。该 skill 关注三件事：选型决策（什么时候用什么）、静默失败面（不报错但就是不生效的字段交互）、以及流程与验证手法。字段字典（枚举、默认值、字段清单）不在本文复制，字段语义一律路由 MaaLLMWiki 的 3.3-ProjectInterfaceV2 协议与官方 schema（interface.schema.json），不凭记忆填写。

主要能力与结构

版本双轨

interface_version 固定数字 2，是 JSON 结构主版本，兼容性新增不碰它。PI 协议另有语义化版本 v2.x.y，独立于 MaaFW release 演进。判断「目标 Client 支不支持某字段」看的是后者，协议当前版本以原文变更表为准，不写死。

硬护栏

  • 对外契约：字段改动 = 用户可见行为改动；软件更新走 github 字段的 release 约定（通用 UI 只更新资源 release），不自造更新通道。
  • resource / Bundle 分层：Bundle 是按 pipeline / model / image 标准结构存储的文件夹，path[] 的每个条目指向一个 Bundle 根目录（不是 pipeline/ 子目录），按序加载、后者覆盖前者；resource 条目是声明单位（name / label / option），用户在 Client 里选择的就是它；controller / resource 声明不能经 import 合并，资源根永远由主 interface 声明。
  • 不编造字段：枚举、默认值、版本支持拿不准就路由 schema 与协议原文，宁可少写用默认。
  • i18n 完整性：$ 开头的键必须在 languages 指向的翻译文件里有对应键；不配 languages 默认仅中文。
  • 密钥卫生：interface.json 随资源分发，明文密钥不得写入；password 输入字段禁 default（schema 硬拒）、不入 preset（协议建议，schema 不校验，靠纪律）。

工作流

从零编写按 1→7 顺序走；在既有项目上增改，先看「存量修改」。

  1. 骨架：interface_version: 2 加 name / version；adb 的截图/输入方式不配，框架自动探测选优。controller 有两个决策（枚举与默认值路由 schema）：目标形态（安卓设备 / 桌面窗口 / mac 应用 / 手柄等）定 type，并用唯一 name 标识；截图缩放基准（识别与坐标所在的分辨率空间：短边锁定 / 长边 / Expand / 原始分辨率）是框架截图的缩放，不是游戏自身 UI 缩放，全不配默认 720 短边（maafw-pipeline 的基准分辨率取自这里）。

  2. 资源差异怎么组织四选一：让用户选则用多 resource 条目（声明层）；同一 resource 内叠加则用 path[] 里 base Bundle 加差异 Bundle，差异 Bundle 只放覆盖文件；差异绑定控制器用 controller.attach_resource_path（v2.2.0+），在该 resource 的 Bundle 全部加载后附加；整包只服务某控制器用 resource 条目的 controller 列表（按 name），Client 只展示适用的 resource 供选。发布配 hash 校验（v2.6.0+）注意：值是仅加载 path 里的 Bundle 后算出的，打包脚本把 attach 的 Bundle 算进去会误报警告；不匹配只警告不阻断，调试/预发布版可跳过，未设置不校验。

  3. 任务：每个用户可见功能一个 task；entry 写 pipeline 节点名，这是 interface 与 pipeline 的跨文件引用，不是文件名；功能多了用 group（v2.4.0+）分组；task 级 resource / controller 过滤按 name 引用（不是 type）。

  4. 选项与预设：可调参数定义到顶层 option 再逐级引用；preset（v2.3.0+）是任务勾选加选项值快照。控件选型、task 级 pipeline_override（写死在该 task、不经用户选择）与 option 四级声明的覆盖优先级、适用性过滤、静默坑及接线示例见 references/options.md。

  5. 子进程：让 Client 替你启动程序，两个字段按时机选。任务执行期间常驻、承接 Custom 识别/动作逻辑用 agent（Client 启动如 python ./agent/main.py 的子进程并与之通信；要不要上 Custom 见 maafw-custom）。连接设备之前跑一次性准备（如拉起模拟器、环境自检）用 pretask（v2.7.0+，跑完才连 Controller，非零退出即中止启动），可声明 controller / resource 过滤（v2.8.1+），协议只约定 Client 可隐藏/置灰不适用项，不保证跳过执行，「只在某控制器跑」要在程序内自判。两者 CWD 均为 interface.json 所在目录。pretask.option 只把选项取值序列化成末参传给程序，不参与 pipeline_override 合并。agent 子进程经 PI_* 环境变量（v2.5.0+）读 Client 侧上下文，变量可能缺省，子进程需容错。

  6. 长尾字段：setting（设置分区）、telemetry（遥测）等知道存在即可，用时路由原文。

  7. 拆分与校验：任务量大时 import[] 拆分（静默坑见 references/options.md）。静态校验跑脚本：带 dev-tools 的项目（create-maa-project 生成）跑 pnpm check，按官方 schema 校验 interface.json、tasks/ 下的 import 片段与各 Bundle 的 pipeline 文件，字段拼错、类型与枚举值非法在这里被抓（放 tasks/ 以外的 import 片段不在校验范围）；无此基建的项目退回编辑器挂 schema 关联。option 分支逐一验证 override 落点（override 按节点名定向，节点改名等于静默失联）。运行时验证（Client 能加载、任务能跑通、override 真的生效）超出本 skill，交接 maafw-debug。

存量修改

改名类操作先全库搜引用再动手，漏改的后果不一：option 键名漏改在参考实现里 interface 加载失败（能抓住），其余多为静默失联。改 pipeline 节点名：task.entry、task 级与 option 的 pipeline_override 都按节点名定向，全部同步（pipeline 侧的其余引用清单见 maafw-pipeline 修改轨）。改 option 键名 / case 名：键名漏改导致参考实现加载失败；case 名漏改导致 preset 预设值或 default_case 静默落空。引用面包括 task / controller / resource / global_option 四级、setting[].option、pretask[].option、嵌套 case 的 option[]、preset[].task[].option。改 controller / resource 的 name：同步 resource[].controller、task / pretask / option 的 controller[] 与 resource[] 过滤列表，option 适用列表失配会导致该选项整体静默失效。新增 import 文件：先查主文件与既有拆分文件有无同名 option 键，同名以后导入文件为准，主文件被顶掉。

审查清单

  • interface_version 是 2；每个 task.entry 在合并后的 pipeline 里可解析。
  • option 引用键存在且逐字符一致，task 级悬空引用在参考实现里直接加载失败（不是静默），已存配置里的失效引用被警告后丢弃。
  • option 适用当前 controller / resource；不适用时整个 option（含嵌套子项）静默失效（v2.3.1），这是「选项没生效」的头号原因（经验值），机制见 references/options.md 适用性过滤。
  • 多级引用同一 option 按覆盖顺序推演最终值（task > controller > resource > global，后覆盖先）；checkbox 多 case 按定义顺序合并。
  • path[] 每个条目都是 Bundle 根目录（不是 pipeline/ 子目录）；import 拆分无同名 option 键（同名以后导入为准）。
  • languages 文件存在且 $ 键全覆盖；password 无 default、不入 preset、全文无明文密钥。
  • 用到的字段版本前提与目标 Client 的 PI 支持版本兼容，逐项路由核对。协议收录不等于 schema / 参考实现 / 目标 Client 已支持，发布前实测。

适用场景

适合需要为 MaaFramework 项目编写或维护 interface.json 的开发者，尤其是涉及多资源差异、多控制器适配、大量可调选项与预设、以及需要在任务执行期或连接前启动子进程的场景。也适合在既有项目上做字段改名、引用同步与审查。

限制

本文只承载路由拿不到的三样：选型决策、静默失败面、流程与验证手法；字段字典（枚举、默认值、字段清单）不在本文复制。运行时验证超出本 skill，需交接 maafw-debug。文中版本标注均为「该机制自哪版起」的历史事实，不是当前版本快照；协议当前到哪以原文变更表为准，不写死。深入阅读可参考 references/options.md，字段级细节、PI_* 变量表与版本变更一律路由《ProjectInterface V2》与官方 schema。