企业官网建设流程全解析

MaaAssistantArknights SideStory 活动导航详解：tasks 任务、StageActivityV2 配置与 MaaRelease 同步的联动实践

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights

本篇围绕明日方舟小助手 MaaAssistantArknights 中 SideStory（别传）活动关卡导航的新增与更新流程展开：读者将完整掌握resource/tasks/Stages/XX.json导航任务文件的结构设计与字段含义、StageActivityV2.json活动配置条目的替换规则与MinimumRequired版本号策略，以及 MaaRelease 远程资源仓库的镜像同步方法，并理解 OCR 选章与模板图选章两种识别方案在底层任务系统中的实现依据。

一、SideStory 导航为什么需要"多文件联动"

SideStory 活动关卡（如TO-9、ME-7）与普通常驻关卡不同：它们只存在于当期活动入口内，需要小助手先识别活动横幅、进入活动界面、切换到目标章节、再在关卡列表中定位具体关卡。这条链路由三处内容共同支撑：

1. 导航任务定义（resource/tasks/Stages/XX.json）：描述"如何打开活动、如何选章、如何找关"的图式任务（Task Graph）；
2. 活动元数据（StageActivityV2.json）：描述"活动叫什么、何时开放、有哪些关卡、每关掉落什么"，供 GUI 与调度层读取；
3. 远程资源镜像（MaaRelease 仓库的api/目录）：客户端运行时实际拉取资源与配置的来源。

三者的内容必须保持一致，任何一处遗漏都会导致活动导航失效或 GUI 中不显示当期活动。本文的写作骨架即来自仓库内的技能文档 SKILL.md，下面在其基础上结合仓库中的真实配置文件与任务源码逐项展开。

二、新增活动前必须收集的信息清单

按 SKILL.md 的要求，动手改文件之前必须先把以下 11 项信息收集完整；若用户只提供了一部分，需要列出仍缺少的项：

若选章方式为模板图，还需额外提醒用户提供模板图片，并准备修改MinimumRequired版本号（原因见本文第五节）。

三、术语与涉及文件

3.1 术语约定

3.2 需要改动的四类文件

当前仓库resource/tasks/Stages/目录下已积累了大量历史活动的导航文件，可作为直接参照：

• TO.json——OCR 选章 +ocrReplace纠错的完整样例；
• AT.json——含搓玉关（AT-4）与preDelay的样例；
• ME.json——三常规关 + 三低编号关的样例；
• 以及 TD.json、AveMujica.json、base.json 等。

四、tasks 导航文件结构与字段深讲（resource/tasks/Stages/XX.json）

4.1 关卡范围约定

• 通常是活动的后三关（如 7/8/9、6/7/8、8/9/10），但具体关卡编号由用户提供；
• 可能有额外的低关卡用于搓玉（如第 4 关、第 5 关），搓玉关与后三关一并加入导航。

以真实存在的 TO.json 为例，它导入了常规关TO-7/8/9与低编号关TO-5，文件内所有键按本文第 4.6 节的顺序规则排列。

4.2 任务定义模板（逐项字段解释）

SKILL.md 给出的标准模板如下，每个字段的作用在注释中进一步说明：

{ // —— 关卡入口（按编号从小到大）—— "XX-4": { "algorithm": "JustReturn", // 该节点本身不做识别，仅用于组织子任务与后续节点 "sub": ["XX-4@XX-OpenOpt"], // 前置子任务：先执行"打开活动"流程 "next": ["XX-4@SideStoryStage", "XX-4@SwipeToStage"] // 之后依次尝试"识别关卡号"与"滑动找关" }, "XX-7": { ... }, "XX-8": { ... }, "XX-9": { ... }, // —— 关卡识别（按编号从小到大）—— "XX-4@SideStoryStage": { "text": ["XX-4"] }, // 继承 baseTask "SideStoryStage" 的 OCR 识别 "XX-7@SideStoryStage": { "text": ["XX-7"] }, "XX-8@SideStoryStage": { "text": ["XX-8"] }, "XX-9@SideStoryStage": { "text": ["XX-9"] }, // —— 活动入口 —— "XX-OpenOpt": { "algorithm": "JustReturn", "next": ["XX-OpenOcr", "XX-Open"] // 先试 OCR 识别横幅，失败再退化为模板匹配 }, "XX-Open": { "baseTask": "SS-Open", // 继承基础任务的动作与 roi "postDelay": 5000, // 进活动后等待时间，按需调整 "template": ["StageSideStory.png", "StageActivity.png"], // SideStory/活动入口图标 "next": ["XXChapterToXX"] }, "XX-OpenOcr": { "baseTask": "SS-OpenOcr", "text": [...], // 见下方 OCR 文本规则 "postDelay": 5000, "next": ["XXChapterToXX"] }, // —— 选章（进入活动后选择关卡列表）—— "XXChapterToXX": { // 方式 A：OCR 识别（章节名可被 OCR 时优先使用） "algorithm": "OcrDetect", "action": "ClickSelf", // 识别成功后点击识别到的文字自身位置 "text": ["章节名"], "roi": [x, y, w, h], "postDelay": 2000, "next": ["#self", "SideStoryStage", "ChapterSwipeToTheRight"] // #self 表示未识别到时重试自身；失败兜底是滑动到最右再扫一遍章节 } }

4.3 基础任务的继承来源：SS-Open、SS-OpenOcr、SideStoryStage

模板中出现的baseTask字段是 MaaAssistantArknights 任务系统的"继承"机制：子任务只写差异，基础字段（roi、action、algorithm）由基础任务提供。这些基础任务都定义在主任务文件 resource/tasks/Stages/base.json 与 resource/tasks/tasks.json 中：

• SS-OpenOcr（base.json）：ClickSelf + OcrDetect，默认roi: [0, 500, 500, 150]，即左侧活动横幅区域；
• SS-Open（base.json）：模板匹配点击，roi: [505, 57, 462, 628]覆盖右侧活动/剧情入口列，注释明确要求"使用时需再次指定 template"——这正解释了为什么每个XX-Open节点都要再写一次StageSideStory.png/StageActivity.png；
• SideStoryStage（tasks.json）：OcrDetect + ClickSelf，isAscii: true（关卡编号为 ASCII，使用更快的识别路径），并内置了一组ocrReplace纠错规则（去除空格、o→O、c→C、s→S、-1O$→-10$等），把 OCR 的易错输出归一化为XX-N形式；
• SwipeToStage（tasks.json）：基于ChapterSlowlySwipeToTheLeft的"活动导航左滑找关"滑动器；
• ChapterSwipeToTheRight（tasks.json）：maxTimes: 10的向右扫到底兜底，用于选章未命中时遍历章节列表。

值得注意的是，各活动文件可以覆写继承来的ocrReplace。例如 TO.json 中每个@SideStoryStage都追加了["T0-", "TO-"]——因为 OCR 极易把字母 O 识别为数字 0，这个局部纠错规则正是模板第 4.4 节规则的落地写法。

4.4 真实案例：TO.json与模板逐段对照

TO.json 是模板的一个逐字实现，可以对照验证各字段的实际取值：

// 入口节点：先 sub 打开活动，再识别/滑动找关（TO-4 在真实文件中对应 TO-5 搓玉关） "TO-5": { "algorithm": "JustReturn", "sub": ["TO-5@TO-OpenOpt"], "next": ["TO-5@SideStoryStage", "TO-5@SwipeToStage"] }, // OCR 入口：text 中同时放"长活动名全文"与"4 字短词兜底"（原文在前，短词在后） "TO-OpenOcr": { "baseTask": "SS-OpenOcr", "text": [ "直到大地变成一颗酸橙", // 活动第一期横幅 "踏上归家长途", // 后续章节开放后横幅会变化 "眺望待行之路", "直到大地", "大地变成", "一颗酸橙", "踏上归家", "归家长途", "眺望待行", "待行之路" ], "postDelay": 5000, "next": ["TOChapterToTO"] }, // 选章：OCR 方式，识别章节名后点击自身 "TOChapterToTO": { "algorithm": "OcrDetect", "action": "ClickSelf", "text": ["驶向大地尽头"], "roi": [1040, 420, 150, 50], "postDelay": 2000, "next": ["#self", "SideStoryStage", "ChapterSwipeToTheRight"] }

对照 AT.json 可以看到选章任务还常带preDelay（AT 的选章用了preDelay: 3000），用于等待章节列表动画完成；ME.json 则示范了postDelay: 3000的取值差异——这些毫秒数正是信息清单第 11 项"进活动后等待时间"要用户提供的参数。

4.5XXChapterToXX选章任务的两种方式

方式 B 示例：

"XXChapterToXX": { "action": "ClickSelf", "template": "XXChapterToXX.png", "roi": [x, y, w, h], "postDelay": 2000, "next": ["#self", "SideStoryStage", "ChapterSwipeToTheRight"] }

使用模板图时的联动操作：需要新增XXChapterToXX.png模板图片到resource/template/StageNavigation/SideStory/XX/目录（当前仓库中该目录下已有TD、WB等历史活动子目录，以及公共的StageSideStory.png、StageActivity.png），并且必须修改 StageActivityV2.json 中的MinimumRequired（原因见第五节 5.3）。

4.6 OCR 文本规则与排列顺序规则

OCR 文本规则：

• 长活动名切成多段 4 字短词，同时保留原文，混排在text数组中；
• 原文放前面，短词兜底放后面；
• 示例："text": ["直到大地变成一颗酸橙", "踏上归家长途", "眺望待行之路", "直到大地", "一颗酸橙", "踏上归家", "归家长途", "眺望待行", "待行之路"]；
• 原因：全字匹配任一错字就失败；短词提高容错，但不可太短（≥4 字）避免误匹配。

排列顺序规则：

tasks 导航文件中关卡按编号从小到大排列；搓玉关放最后。

先放所有入口任务（XX-N），再放所有XX-N@SideStoryStage，最后放XX-OpenOpt/XX-Open/XX-OpenOcr/XXChapterToXX。同一组内：常规关卡按编号从小到大，搓玉关（低编号如XX-4/XX-5，Drop 为搓玉描述）放在常规关之后。TO.json 中TO-7/8/9在前、TO-5（搓玉）在后的写法即为范例。

4.7 roi 坐标

由用户提供截图坐标，格式为[x, y, width, height]。XXChapterToXX的 roi 通常由用户以 "x1040+150 y420+50" 的形式给出，即[1040, 420, 150, 50]——TO.json 中的"roi": [1040, 420, 150, 50]与 SKILL.md 示例完全一致，说明该示例即来源于 TO 活动的真实配置。

五、StageActivityV2.json：活动元数据配置

5.1 两个存放位置

• 本地测试缓存：build/bin/Debug/cache/gui/StageActivityV2.json（客户端运行时从远程 API 拉取到本地缓存；该路径为构建/运行产物，通常不随仓库提交，修改此文件仅用于本地测试）；
• 远程源文件：../MaaRelease/MaaAssistantArknights/api/gui/StageActivityV2.json（位于主仓库上级目录的 MaaRelease 中，是 StageActivityV2 的真正来源。修改必须 commit 推送后才对用户生效；提交/推送 MaaRelease 与主仓库一样，须先获得用户明确指令）；
• 两者内容必须一致。

GUI 侧的读取逻辑可参见 StageManager.cs 与 StageActivityInfo.cs：从源码结构看，活动名称、开放/过期时间与关卡列表正是由这份 JSON 驱动界面上"活动关卡"的显示与可用性判断的。

5.2 条目结构与替换规则

将旧活动条目整体替换为新活动。键名为活动前缀（如"TO"），结构如下：

"TO": { "MinimumRequired": "v6.11.0", // 见 §5.3 版本号规则 "Activity": { "Tip": "SideStory「活动全名」", "StageName": "活动全名", "UtcStartTime": "2026/08/01 12:00:00", "UtcExpireTime": "2026/08/22 03:59:59", "TimeZone": 8 }, "Stages": [ { "Display": "TO-9", "Value": "TO-9", "Drop": "31033" }, { "Display": "TO-8", "Value": "TO-8", "Drop": "31013" }, { "Display": "TO-7", "Value": "TO-7", "Drop": "30023" }, { "Display": "TO-4", "Value": "TO-4", "Drop": "搓玉用" } ] }

字段说明：

• Tip/StageName：对应信息清单第 2 项"活动全名"，Tip带SideStory「…」前缀；
• UtcStartTime/UtcExpireTime/TimeZone：对应第 7 项"关卡开放时间"，格式为yyyy/MM/dd HH:mm:ss，TimeZone一般为 8（服务器时区）；
• Stages中Display与Value相同，均为XX-N形式的关卡名，Drop取值规则见 5.5。

5.3 MinimumRequired 版本号规则

模板图方式的具体操作：

1. 查看当前最新版本号（如git describe --tags得到v6.15.1）；
2. 将MinimumRequired改为下一个 patch 版本（如v6.15.2）；
3. 通知用户复查该版本号是否正确，因为新模板图片需要随新版本客户端分发——旧版本客户端的资源包里根本没有这张模板图，若版本号不抬升，用户将直接遇到模板缺失导致的导航失败。

5.4 Stages 数组排列顺序

StageActivityV2 的 Stages 数组按编号从大到小排列。

高难关卡（高掉落价值）排在前面，搓玉等低关卡排在后面。这与 tasks 导航文件"从小到大、搓玉关最后"的规则方向相反，是两处文件最容易搞混的地方，见 5.6 速查表。

5.5 Drop 字段取值规则

resource/item_index.json是以材料 ID 为 key 的字典（含name、description、usage等字段）。当前仓库中确实存在上述示例 ID：30023、31013、31033（分别位于 item_index.json、L577、L623 附近），可据此反查材料名，验证"按材料名查表取 key"的操作闭环。

知识：个别关卡可能有独立的MinimumRequired（如某关卡需要更新版本才能解锁），可单独加到该关卡的条目中：{ "Display": "XX-4", "Value": "XX-4", "Drop": "搓玉用", "MinimumRequired": "v6.16.0" }。但用户通常不会指定，不需要主动询问。

六、MaaRelease 仓库同步（可选步骤）

MaaRelease 仓库的同步是可选操作。用户本地可能没有拉取该仓库，或者仓库不在上级目录。操作前先检查../MaaRelease/是否存在，不存在则跳过此步骤。

6.1 前置检查

# 检查上级目录是否有 MaaRelease Test-Path ..\MaaRelease

若存在则git pull更新到最新。

6.2 需要同步的文件

6.3api/resource/tasks.json的追加规则

• MaaRelease 的tasks.json是精简覆盖层，只放活动导航任务本身，不放依赖项（SS-Open、SideStoryStage、SwipeToStage、ChapterSwipeToTheRight等基础任务由客户端本地资源提供）——这与第四节分析的baseTask继承机制相互印证：基础任务本就来自本地 base.json 与 tasks.json，无需重复分发；
• 新内容放文件开头（{之后、第一个已有 key 之前），不是末尾；
• 内容与主仓库resource/tasks/Stages/XX.json完全一致。

七、排列顺序速查与完整操作清单

7.1 排列顺序速查

7.2 完整操作清单

1. ✅ 创建/修改resource/tasks/Stages/XX.json（导航任务，常规关卡从小到大，搓玉关放最后）；
2. ✅ 修改build/bin/Debug/cache/gui/StageActivityV2.json（本地测试缓存，替换活动，关卡从大到小，Drop 查表或用用户描述）
   • 若XXChapterToXX用模板图：修改MinimumRequired为下一个版本，通知用户复查；
3. 🔶 检查../MaaRelease/是否存在；存在则：
   • cd ../MaaRelease; git pull
   • 修改api/gui/StageActivityV2.json（远程源文件，同步骤 2）
   • 修改api/resource/tasks.json（导航任务追加到开头，关卡从小到大）

八、要点回顾

SideStory 导航的本质是一条"OCR/模板识别 → 点击进入 → 选章 → 滑动找关"的任务图，而活动元数据与远程资源镜像保证这条任务图在正确的时间、正确的客户端版本上对用户可见。实操时的三条铁律：

1. 三处内容一致：主仓库 tasks 文件、本地 StageActivityV2 缓存、MaaRelease 远程源必须同步修改；
2. 两种排序方向：tasks 文件从小到大（搓玉关最后），StageActivityV2 的 Stages 从大到小；
3. 模板图必抬版本号：凡新增模板图片，MinimumRequired必须指向包含该图片的新版本，并请用户复核。

按 SKILL.md 的信息清单收集齐 11 项参数后，以 TO.json 这类历史文件为范本复制改写，即可完成一次完整、可测试的活动导航更新。

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights