Side Story Navigation

SideStory 活动导航 Skill

新增或更新一个 SideStory 活动的关卡导航，涉及多个文件的联动修改。

必需信息清单

开始前必须向用户收集以下信息；用户提供了部分后，列出仍缺少的项目。

若选章方式为模板图，还需额外提醒用户提供模板图片，并准备修改 MinimumRequired 版本号。

0. 术语

1. 涉及的文件

2. tasks 导航文件结构（resource/tasks/Stages/XX.json）

参考往期活动（如 AT.json、ME.json、AveMujica.json）。

2.1 关卡范围

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

2.2 任务定义模板

{
    // —— 关卡入口（按编号从小到大）——
    "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"] },
    "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"]
    },
    "XX-Open": {
        "baseTask": "SS-Open",
        "postDelay": 5000,              // 进活动后等待时间，按需调整
        "template": ["StageSideStory.png", "StageActivity.png"],
        "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"]
    }
}

2.3 XXChapterToXX 选章任务的两种方式

方式 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/ 目录，并且 必须修改 StageActivityV2.json 中的 MinimumRequired（详见 §3.3）。

2.4 OCR 文本规则

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

2.5 排列顺序规则

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

先放所有入口任务，再放所有 @SideStoryStage，最后放 Open/Chapter 相关。排列时：常规关卡按编号从小到大，搓玉关（低编号如 XX-4/XX-5，Drop 为搓玉描述）放在常规关之后。

2.6 roi 坐标

由用户提供截图坐标。格式为 [x, y, width, height]。

• XXChapterToXX 的 roi 通常由用户指定形如 "x1040+150 y420+50"，即 [1040, 420, 150, 50]。

3. StageActivityV2.json

3.1 位置

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

3.2 替换规则

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

"TO": {
    "MinimumRequired": "v6.11.0",       // 见 §3.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": "搓玉用" }
    ]
}

3.3 MinimumRequired 版本号规则

模板图方式的具体操作：

1. 查看当前最新版本号（如 git describe --tags 得到 v6.15.1）。
2. 将 MinimumRequired 改为下一个 patch 版本（如 v6.15.2）。
3. 通知用户复查该版本号是否正确，因为新模板图片需要随新版本客户端分发。

3.4 排列顺序规则

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

高难关卡（高掉落价值）排在前面，搓玉等低关卡排在后面。

3.5 Drop 字段

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

4. MaaRelease 仓库同步（可选）

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

4.1 前置检查

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

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

4.2 需要同步的文件

4.3 tasks.json 追加规则

• MaaRelease 的 tasks.json 是精简覆盖层，只放活动导航任务本身，不放依赖项（SS-Open、SideStoryStage、SwipeToStage、ChapterSwipeToTheRight 等基础任务由客户端本地资源提供）。
• 新内容放文件开头（{ 之后、第一个已有 key 之前），不是末尾。
• 内容与主仓库 resource/tasks/Stages/XX.json 完全一致。

5. 排列顺序速查

6. 完整操作清单

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（导航任务追加到开头，关卡从小到大）