MaaAssistantArknights 专用 VS Code 扩展Maa Support完全指南tasks.json 语义编辑、截图裁剪与调试实战【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights导读本文面向《明日方舟》自动化框架 MaaAssistantArknights 及其底层 MaaFramework 的开发者与资源维护者系统讲解专用 VS Code 扩展「Maa Support」Maa Pipeline Support的安装、配置与全部核心功能。读完本文你将掌握如何借助该扩展高效编辑tasks.json任务流程文件——包括模板任务预览、next跳转、任务引用查询、自动补全、多路径资源覆盖与表达式展开计算以及如何用内置截图裁剪工具配合 OCR/模板识别快速调试任务。文中所有功能说明均以当前仓库的 interface.json、resource/tasks/tasks.json、.vscode/settings.json 等真实文件为佐证确保可直接落地使用。一、扩展是什么面向 MAA 生态的专用开发工具Maa Support扩展商店 IDnekosu.maa-support是专门针对 MaaAssistantArknights / MaaFramework 开发的 VS Code 扩展其核心价值在于把「纯文本 JSON 编辑」升级为「语义化资源编辑」。它提供的主要能力包括tasks.json深度支持模板Template预览、next跳转、任务引用解析、自动补全与合法性校验图片截取与裁剪内置截图工具直接连控制器截图、框选裁剪 ROI、一键保存回资源目录资源诊断对任务定义与图片引用进行定时扫描提前发现命名冲突、悬空引用等错误。扩展的绝大部分功能都基于**interface.json配置**驱动这一点与 MaaFramework 的接口约定完全一致本仓库根目录即存在一份 interface.json因此理解该文件的字段结构是使用扩展的前提。二、安装与初始化2.1 安装方式推荐直接在 VS Code 的扩展列表中搜索Maa并安装扩展全名 Maa Support / Maa Pipeline Support。安装完成后左侧活动栏会出现专用控制面板图标。2.2 首次使用的资源下载首次使用时扩展会自动下载默认版本的依赖资源模型、解析器等。若下载源不可用或速度不理想可通过命令面板执行Maa: 選擇下載源选择下载源在npm / cnpm两个来源之间切换后重试下载。::: tip 调用命令面板的快捷键为Ctrl Shift PmacOS 为Command Shift P本文后续所有Maa: xxx命令均在该面板中执行。 :::三、控制面板一切功能的入口控制面板位于左侧活动列扩展绝大部分功能均集中于此。3.1 选择当前生效的 interface.json控制面板最上方是interface.json选择器用于切换当前生效的接口配置。以本仓库根目录的 interface.json 为例其结构如下{ name: MaaAssistantArknights, controller: [ { name: Adb, type: Adb }, { name: Win32, type: Win32 } ], resource: [ { name: 官服 | Official, path: [{PROJECT_DIR}/resource] }, { name: 日服 | YoStarJP, path: [{PROJECT_DIR}/resource, {PROJECT_DIR}/resource/global/YoStarJP/resource] }, { name: 韩服 | YoStarKR, path: [{PROJECT_DIR}/resource, {PROJECT_DIR}/resource/global/YoStarKR/resource] }, { name: 美服 | YoStarEN, path: [{PROJECT_DIR}/resource, {PROJECT_DIR}/resource/global/YoStarEN/resource] }, { name: 台服 | txwy, path: [{PROJECT_DIR}/resource, {PROJECT_DIR}/resource/global/txwy/resource] } ] }从中可以看到两个关键信息controller数组声明了可用的控制器如Adb、Win32与 MaaPiCli 功能中的控制器扫描范围对应resource数组中的每个条目是一个资源方案path为数组而非单个路径——这正是扩展「多路径资源支持」的配置载体详见下文例如日服方案由resource与resource/global/YoStarJP/resource两级叠加而成。3.2 Maa 兼容模式Maa 相容模式当扩展检测到当前打开的文件夹下存在src/MaaCore目录时会自动启用Maa 兼容模式。该模式会解锁一系列 MAA 专属能力解析模板任务衍生任务、型任务支持联动父类查询任务定义与引用悬停任务定义时查看同名的模板图片输入触发任务自动补全图片路径的递归搜索计算任务/任务列表表达式的实际展开结果。也就是说直接在 VS Code 中打开本仓库根目录存在 src/MaaCore即可自动获得上述全部增强能力。四、语义化资源分析任务定义与引用的编辑体验4.1 选择资源与诊断范围通过切换控制面板中的**「資源」下拉菜单**选择预期资源扩展会根据对应路径进行索引与诊断。若某个 JSON 文件没有出现提示请检查当前启动的资源是否包含该文件——这是排查「为什么没有补全/跳转」的第一顺位原因。需要先厘清两个核心术语任务的定义任务对象中的键Key即任务名称任务的引用其他任务中可以填入任务名称的值Value典型场景是next字段。4.2 查询任务定义与引用扩展支持三类导航操作跳转至定义Go to Definition从引用位置直接跳到任务的声明处跳转至引用Go to References查看某任务被哪些任务引用查看任务定义Peek Definition不离开当前文件即可预览任务内容。开启 Maa 兼容模式后模板任务会被正确解析可以联动父类查询任务定义与引用——例如某个BA型任务引用了A的字段时跳转会定位到父任务A的声明。悬停任务定义时还能查看同名模板图片的预览。使用Ctrl T快捷键可以快速搜索并跳转至任意任务定义适合在大型tasks.json中导航。4.3 查询与打开图片扩展支持直接打开任务引用的图片文件开启 Maa 兼容模式后支持图片路径的递归搜索——这对应了 MAA 的模板加载约定模板图片可放在template目录及其子目录下加载时递归查找参见 docs/zh-tw/protocol/task-schema.md 中template字段的说明。4.4 任务自动补全扩展会根据所有已知任务提供自动补全。开启 Maa 兼容模式后在 JSON 值位置输入符号即可触发补全菜单快速生成任务名父任务形式的模板任务避免手写出错。4.5 补全图片路径类似地扩展会根据所有已知图片路径进行自动补全开启 Maa 兼容模式后支持递归搜索确保template字段引用的图片真实存在。五、任务与图片路径的自动验证扩展会定时扫描并分析所有任务自动检查以下四类问题检查项说明示例重复命名的任务定义同一任务名被多次定义两个文件都定义了Return未知的任务引用next/sub等字段引用了不存在的任务next: [NoSuchTask]未知的图片引用template指向不存在的图片文件template: missing.png单任务中的重复任务引用同一任务在列表中被重复列出next: [A, B, A]其中「重复引用」的检查与 MAA 的运行期语义一致——任务流程协议明确规定对于相同任务第一次识别后第二次不再识别即next: [ A, B, A, A ]等价于next: [ A, B ]见 docs/zh-tw/protocol/task-schema.md。扩展在编辑期就帮你把这类冗余暴露出来。六、多路径资源支持逻辑覆盖规则interface.json中resource[*].path可以是多个路径扩展会按照数组内指定的顺序进行逻辑覆盖后加载排在后面的路径内容可以引用到先加载排在前面路径的内容同名任务/图片在后加载路径中覆盖先加载路径的定义。这与 MAA 的多文件任务机制一脉相承如果后加载的任务文件中定义了与先加载文件同名的任务且没有baseTask字段则直接继承先加载同名任务的字段若定义了baseTask字段则直接覆盖参见 docs/zh-tw/protocol/task-schema.md 中「多檔案任務」一节。以 interface.json 中的台服方案为例{ name: 台服 | txwy, path: [{PROJECT_DIR}/resource, {PROJECT_DIR}/resource/global/txwy/resource] }即先加载通用 resource再加载台服专属覆盖目录resource/global/txwy/resource该目录下的tasks/可覆盖通用任务定义。七、计算任务 / 任务列表表达式仅限 MAA在 Maa 兼容模式下通过控制面板可以计算任务实际展开的内容及其每一项的来源——即模板任务继承父类字段后、最终生效的完整任务定义计算任务列表表达式展开后的结果——对sub、next、onErrorNext、exceededNext、reduceOtherTimes等任务列表类型字段中出现的表达式进行求值。MAA 的任务列表表达式包含以下运算符完整说明见 docs/zh-tw/protocol/task-schema.md 的「運算式計算」一节符号含义实例型任务FightReturnTo#一元虚任务#self#二元虚任务StartUpThemes#next*重复多个任务(ClickCornerAfterPRTSClickCorner)*10任务列表合并同名任务只保留最靠前者AB^任务列表差顺序不变(AABC)^(ABD)结果为C运算符优先级为#一元#二元*^。手工推算这类展开很容易出错而扩展可以直接给出展开结果与每一项的来源是调试复杂模板任务链路的利器。在本仓库 resource/tasks/tasks.json 中可以找到大量真实表达式示例例如Block: { Doc: base_task, algorithm: JustReturn, action: DoNothing, next: [#self] }, SlowlySwipeToTheLeft: { algorithm: JustReturn, action: Swipe, postDelay: 200, specificRect: [300, 310, 100, 100], specificRect_Doc: 滑动起点, rectMove: [880, 310, 100, 100], rectMove_Doc: 滑动终点, specialParams: [200, 1, 37, 1], next: [#next], maxTimes: 50 }其中next: [#self]表示执行完毕后跳回自身配合maxTimes构成循环next: [#next]表示继承父任务若为型任务的next字段——这些正是虚任务#型任务的典型应用编辑期通过扩展可以直观看到它们展开后的最终形态。八、MaaPiCli 功能仅限 MaaFramework 项目对于 MaaFramework 项目而非 MAA 本体控制面板还集成了 MaaPiCli 的常用操作无需切换到终端即可扫描并选择控制器对应interface.json中controller数组内声明的控制器选择资源切换resource数组中的资源方案新增并管理任务向当前界面任务队列增删任务执行任务直接驱动当前选中的控制器运行任务实现「改完即测」。注意该功能依赖 MaaFramework 的 CLI 产物仅适用于 MaaFramework 项目场景在本仓库MAA 本体中主要使用的是上文所述的语义分析、表达式计算等功能。九、截图裁剪与快速识别调试 ROI 的完整闭环在命令面板中执行Maa: 開啟截圖工具即可打开「截图 / 裁剪」面板。这是任务调试中使用频率最高的功能操作流程如下连接控制器选择并连接控制器后点击「截图」按钮可直接获取屏幕截图手动上传也可使用「上传」按钮手动上传已有图片例如从测试机导出的截图框选裁剪按住Ctrl键拖动框选需要裁剪的区域缩放使用鼠标滚轮对图片进行缩放便于精确定位小控件保存裁剪完成后点击「下载」按钮裁剪结果会自动保存到当前启动资源中最顶层的图片目录即interface.json所选资源方案的第一个path下的template目录命名后即可直接被template字段引用复制 ROI使用「复制」按钮可将裁剪区域的 ROI 以数组形式[x, y, width, height]复制到剪贴板直接粘贴进roi字段使用快速识别点击「工具」按钮打开识别工具面板可对当前图片直接进行识别测试模板匹配 / OCR无需跑完整流程即可验证任务参数。::: warning 若 OCR 识别结果为空请检查OCR 模型是否配置正确。针对 MAA扩展会自动维护所使用的模型你只需在控制面板中选择正确的资源即可若自建 MaaFramework 项目则需按 MaaFramework 文档自行配置文字识别模型文件。 :::十、日志查看功能调试期间产出的日志可通过两条命令直达命令查看内容对应日志文件Maa: 開啟 maa 日誌MaaFramework 运行日志maa.logMaa: 開啟插件日誌扩展自身的运行日志mse.log当扩展行为异常如补全不生效、资源未加载时优先查看mse.log定位扩展侧问题当任务识别不符合预期如模板得分偏低时结合maa.log中的实际匹配得分来调整templThreshold等参数得分查看方法参见 docs/zh-tw/protocol/task-schema.md 中templThreshold字段说明。十一、底部状态栏版本与面板入口VS Code 底部状态栏会常驻两个与扩展相关的条目MaaSupport 扩展版本点击可聚焦到左侧控制面板MaaFramework MaaFw版本点击可切换扩展使用的 MaaFramework 版本。需要留意的是可选择的版本受限于当前扩展所支持的版本范围若所需版本不在列表中需要更换扩展本身的版本升级或降级扩展以获取对应支持。十二、与仓库既有配置的协同Schema 校验与 JSONC扩展的语义分析能力与仓库自带的 JSON Schema 校验是互补关系二者共同构成完整的编辑体验仓库在 .vscode/settings.json 中已配置好json.schemas将resource/tasks/**/*.json与resource/global/**/resource/tasks/**/*.json关联到 docs/maa_tasks_schema.json同时通过files.associations将resource/tasks/**/*.json识别为JSONC允许带注释的_Doc字段如 resource/tasks/tasks.json 中的specificRect_Doc、specialParams_Doc得到正确的语法高亮。因此在 VS Code 中直接打开本仓库文件夹即可同时获得Schema 的字段级校验与提示来自maa_tasks_schema.json其中定义了JustReturnTask、MatchTemplateTask、OcrDetectTask、FeatureMatchTask四类任务结构 扩展的语义级跳转、补全、诊断与表达式计算。前者保证字段「写对了」后者保证任务「连得上、引得到、图找得到」。十三、实操建议从安装到调试的推荐工作流综合以上全部能力推荐的任务开发工作流如下打开仓库VS Code 打开 MaaAssistantArknights 仓库根目录确认状态栏出现MaaSupport条目、活动栏出现控制面板图标即扩展已生效并因存在 src/MaaCore 目录自动启用 Maa 兼容模式选择资源在控制面板顶部选择当前生效的 interface.json 与目标资源方案如「官服 | Official」编写任务在 resource/tasks/tasks.json 中编辑任务利用触发补全、Ctrl T跳转定义、表达式计算验证next链路的展开结果准备图片执行Maa: 開啟截圖工具连接控制器截取目标界面框选裁剪 ROI一键保存至资源顶层template目录并将 ROI 数组粘贴到roi字段识别验证在截图工具面板中对裁剪结果直接进行模板/OCR 识别测试确认参数有效查看日志任务执行后通过Maa: 開啟 maa 日誌检查maa.log若扩展本身异常则查看插件日志mse.log。结语Maa Support 扩展把 MaaAssistantArknights / MaaFramework 的tasks.json开发从「盲写 JSON」提升为「语义化编辑」模板任务与/#表达式的展开计算、定义/引用双向导航、图片路径递归补全与校验配合截图裁剪工具形成的「截图 → 裁剪 ROI → 识别测试 → 保存模板」闭环能够显著降低任务流程的开发与排错成本。对于本仓库的开发者而言只需以 VS Code 打开仓库根目录即可让扩展与仓库自带的 docs/maa_tasks_schema.json Schema、interface.json 多路径资源方案协同工作将主要精力集中在任务逻辑本身。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考