Documento original do Skill
Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.
MaaFW interface.json（PI V2）开发
interface.json 是项目对外的标准化声明：通用 GUI、打包分发、工具链都靠它认识项目。字段语义一律路由 MaaLLMWiki 的 3.3-ProjectInterfaceV2 协议与官方 schema（interface.schema.json），不凭记忆填（已安装 maallmwiki skill 时由其承载完整路由流程）。
本文只承载路由拿不到的三样：选型决策（什么时候用什么）、静默失败面（不报错但就是不生效的字段交互）、流程与验证手法。字段字典（枚举、默认值、字段清单）不在本文复制；文中版本标注均为"该机制自哪版起"的历史事实，不是当前版本快照。
版本双轨防混淆：interface_version 固定数字 2（JSON 结构主版本，兼容性新增不碰它）；PI 协议另有语义化版本 v2.x.y（独立于 MaaFW release 演进）——判断"目标 Client 支不支持某字段"看的是后者，协议当前到哪以原文变更表为准，不写死。
硬护栏
- 对外契约：字段改动 = 用户可见行为改动；软件更新走
github字段的 release 约定（通用 UI 只更新资源 release），不自造更新通道。 - resource / Bundle 分层（定义出自官方术语表 1.2-术语解释；3.3-ProjectInterfaceV2 协议行文的"资源包"指 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 顺序走；在既有项目上增改，先看下方「存量修改」。
- 骨架：
interface_version: 2+name/version；adb 的截图/输入方式不配，框架自动探测选优。controller 两个决策（枚举与默认值路由 schema）：
- 目标形态（安卓设备 / 桌面窗口 / mac 应用 / 手柄…）定 type。
- 截图缩放基准（识别与坐标所在的分辨率空间：短边锁定 / 长边 / Expand / 原始分辨率）——是框架截图的缩放，不是游戏自身 UI 缩放；全不配默认 720 短边（
maafw-pipeline的基准分辨率取自这里）。
- 资源差异怎么组织四选一：
- 让用户选 → 多 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 算进去会误报警告；不匹配只警告不阻断，调试/预发布版可跳过，未设置不校验。
- 任务：每个用户可见功能一个 task：
entry写 pipeline 节点名——interface 与 pipeline 的跨文件引用，不是文件名。- 功能多了用
group（v2.4.0+）分组。 - task 级
resource/controller过滤按 name 引用（不是 type）。
- 选项与预设：可调参数定义到顶层
option再逐级引用；task 级pipeline_override（写死在该 task、不经用户选择）与 option 的覆盖优先级见 options.md；preset（v2.3.0+）是任务勾选 + 选项值快照。控件选型、声明层级、覆盖顺序与静默坑见 references/options.md。 - 子进程——让 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 侧上下文，变量可能缺省，子进程需容错。
- 长尾字段：
setting（设置分区）、telemetry（遥测）等知道存在即可，用时路由原文。 - 拆分与校验：
- 任务量大时
import[]拆分（静默坑见 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 预设值静默落空。引用面：task / controller / resource / global_option 四级、
setting[].option、pretask[].option、嵌套 case 的option[]。 - 新增 import 文件：先查主文件与既有拆分文件有无同名 option 键——同名以后导入文件为准，主文件被顶掉。
审查清单
interface_version是 2；每个task.entry在合并后的 pipeline 里可解析。- option 引用键存在且逐字符一致——task 级悬空引用在参考实现里直接加载失败（不是静默），已存配置里的失效引用被警告后丢弃。
- option 适用当前 controller / resource——不适用时整个 option（含嵌套子项）静默失效（v2.3.1；"选项没生效"头号原因（经验值），机制见 options.md 适用性过滤）。
- 多级引用同一 option 按覆盖顺序推演最终值（task > controller > resource > global，后覆盖先）；checkbox 多 case 按定义顺序合并。
path[]每个条目都是 Bundle 根目录（不是pipeline/子目录）；import 无同名 option 键（同名以后导入为准）。languages文件存在且$键全覆盖；password 无 default、不入 preset、全文无明文密钥。- 用到的字段版本前提与目标 Client 的 PI 支持版本兼容，逐项路由核对——协议收录 ≠ schema / 参考实现 / 目标 Client 已支持，发布前实测。
深入阅读（按需）
- references/options.md — 控件选型判据、声明层级与覆盖顺序、过滤（v2.3.1）、preset 与 import 的静默坑
字段级细节、PI_* 变量表与版本变更一律路由 3.3-ProjectInterfaceV2 协议与官方 schema。
