---
name: side-story-navigation
description: 新增/更新 SideStory（别传）活动关卡导航。涵盖 tasks/Stages 导航任务、StageActivityV2.json 活动配置、MaaRelease 仓库同步三个文件的联动修改。用户要求添加新活动导航、更新活动关卡、活动开放或复刻时调整导航，以及提到同步 MaaRelease 时均应使用本 skill。
---

# SideStory 活动导航 Skill

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

## 用户输入格式

典型输入是一行式：活动 wiki 链接 + 关卡号与掉落物名称粘着的配对（搓玉关如有一并给出）：

```
https://prts.wiki/w/昨日海 6全新装置 7转质盐组 8液化高能气体
```

- wiki 链接用 WebFetch 抓取，提取：活动全名、关卡开放起止时间、分期章节名（二期/三期章节名及其开放时间）。**关卡前缀（关卡代号形如 `YW-N`）在 wiki 活动主页通常没有**，可靠路径是从关卡子页面确认（如直接访问 `https://prts.wiki/w/<XX>-1` 验证页面存在），拿不准就向用户要。
- `<关卡号><材料名>` 配对：材料名在 `resource/item_index.json` 按 `name` 字段反查 key，得 Drop 的 item ID。
- 选章三件套（方式、识别内容、roi 坐标）与进活动等待时间不在输入里，需另行向用户收集。

## 必需信息清单

先从用户输入与 wiki 链接提取；仍缺的向用户收集，列出缺少的项目。

| # | 信息项 | 来源 | 说明 | 示例 |
|---|--------|------|------|------|
| 1 | 活动前缀代号 XX | wiki/用户 | 两字母关卡前缀；wiki 活动主页通常无关卡代号，从关卡子页面确认（访问 `prts.wiki/w/<XX>-1` 验证）或直接问用户 | `TO` |
| 2 | 活动全名 | wiki | 填入 StageActivityV2 的 Tip/StageName | `昨日海` |
| 3 | OpenOcr 识别文字 | wiki | 活动名、二期章节名、三期章节名（如有），见 §2.4 | `昨日海, 我们的伊比利亚` |
| 4 | 关卡编号列表 | 用户输入 | 通常后三关 + 可选搓玉关 | `6, 7, 8` 或 `4, 6, 7, 8` |
| 5 | 各关卡掉落物名称（非搓玉关） | 用户输入 | 用于查 `item_index.json` 取 ID | `全新装置、转质盐组、液化高能气体` |
| 6 | 搓玉关掉落描述（如有搓玉关） | 用户 | 直接填入 Drop 字段，不查表 | `搓玉效率0.98` |
| 7 | 关卡开放时间 | wiki | 起止时间，**用关卡关闭时间，勿用商店截止时间**（见 §3.2） | `10.9 12:00 — 10.23 03:59` |
| 8 | 选章方式 | 用户 | OCR 文字 / 模板图 | OCR「伊比利亚」或模板图 |
| 9 | 选章识别内容 | 用户 | OCR 文字或模板图文件名；基本是第一期章节名（或其局部），但具体措辞与能否被 OCR 识别无法预判，须由用户从活动内截图确认 | `伊比利亚` |
| 10 | 选章 roi 坐标 | 用户 | 用户可能用 `[x, y, w, h]` 或 `x+w y+h` 两种格式之一 | `[870, 560, 120, 50]` 或 `x870+120 y560+50` |
| 11 | 进活动后等待时间 | 用户 | postDelay 毫秒数，默认 5000 | `5000`（等 5 秒） |

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

## 0. 术语

| 简称 | 含义 |
|------|------|
| **XX** | 活动前缀代号，如 `TD`、`TO`、`AT`，取自关卡名 `XX-7` 的前半 |
| **tasks 导航文件** | `resource/tasks/Stages/XX.json` |
| **StageActivityV2** | `build/bin/Debug/cache/gui/StageActivityV2.json`（主仓库的缓存副本） |
| **MaaRelease** | 上级目录 `../MaaRelease/MaaAssistantArknights/api/` 下的镜像文件 |

## 1. 涉及的文件

| # | 文件路径 | 必需性 | 作用 |
|---|----------|--------|------|
| 1 | `resource/tasks/Stages/XX.json` | ✅ 必须 | 关卡导航任务定义（OCR 识别活动入口、选章、找关） |
| 2 | `build/bin/Debug/cache/gui/StageActivityV2.json` | ✅ 本地测试 | 本地构建缓存，客户端运行时从远程 API（`gui/StageActivityV2.json`）拉取，改此文件用于本地测试 |
| 3 | `../MaaRelease/MaaAssistantArknights/api/gui/StageActivityV2.json` | ✅ 必须 | MaaRelease 远程源文件，StageActivityV2 的真正来源 |
| 4 | `../MaaRelease/MaaAssistantArknights/api/resource/tasks.json` | 🔶 可选 | MaaRelease 精简 tasks 覆盖层（只放活动导航，依赖项由客户端本地资源提供） |

## 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 任务定义模板

```jsonc
{
    // —— 关卡入口（按编号从小到大）——
    "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` 选章任务的两种方式

| 方式 | 适用场景 | algorithm |
|------|----------|------------|
| **A. OCR** | 章节名是可识别的文字 | `OcrDetect` |
| **B. 模板图** | 章节名不可 OCR（特殊字体/图标） | `MatchTemplate` |

方式 B 示例：
```jsonc
"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 文本规则

- `text` 依次列出：**活动名、二期章节名、三期章节名（如有）**，纯整词，不切短词。
  - 示例：`"text": ["昨日海", "我们的伊比利亚"]`
  - 活动入口横幅随分期开放变化：第一期显示活动名，后续章节开放后变为对应章节名，须提前从 wiki/公告把各期章节名写全。
  - **不切短词**：活动名与章节名都是常用字，OCR 不存在问题，切出的短词反而有误匹配风险。

### 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"`），结构如下：

```jsonc
"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": "搓玉用" }
    ]
}
```

> ⚠️ **时间取关卡开放周期，不取商店周期**：`UtcStartTime` = 活动关卡开放时刻（如 `12:00:00`），`UtcExpireTime` = **关卡关闭时刻**（通常开放日起第 14 天的 `03:59:59`）。活动商店兑换通常比关卡多开约一周（如关卡 10/23 03:59 关、商店 10/30 03:59 关），wiki/公告里两个时间并列时勿拿商店截止时间当 ExpireTime——该字段控制关卡导航在 GUI 的有效期。

### 3.3 MinimumRequired 版本号规则

| `XXChapterToXX` 方式 | 版本号处理 |
|----------------------|------------|
| **A. OCR**（已有任务可复用） | 沿用旧活动的值，通常无需改动 |
| **B. 模板图**（需新增模板） | 必须改为**当前最新 tag 的下一个版本** |

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

### 3.4 排列顺序规则

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

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

### 3.5 Drop 字段

| 关卡类型 | Drop 取值 | 获取方式 |
|----------|------------|----------|
| 后三关（常规掉落） | item_index ID（如 `"31033"`） | 在 `resource/item_index.json` 中按材料名查表取 key |
| 搓玉关等特殊关 | 用户提供的文字描述（如 `"搓玉效率0.98"`） | **直接使用用户提供的描述，不查表** |

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

## 4. MaaRelease 仓库同步（可选）

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

### 4.1 前置检查

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

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

### 4.2 需要同步的文件

| 文件 | 操作 |
|------|------|
| `api/gui/StageActivityV2.json` | 与主仓库缓存保持一致 |
| `api/resource/tasks.json` | 将新活动导航任务放文件**开头**（`BlackFlowTemporary` 之前），**并删除被替换旧活动的整块任务** |

### 4.3 tasks.json 追加规则

- MaaRelease 的 `tasks.json` 是精简覆盖层，**只放活动导航任务本身**，不放依赖项（`SS-Open`、`SideStoryStage`、`SwipeToStage`、`ChapterSwipeToTheRight` 等基础任务由客户端本地资源提供）。
- 新内容放**文件开头**（`{` 之后、第一个已有 key 之前），不是末尾。
- **同时删除被替换旧活动的全部任务块**（旧前缀 `<旧XX>-` 开头的所有键）：覆盖层只保留现役活动导航，与 StageActivityV2 旧条目整体替换的语义对齐。
- 内容与主仓库 `resource/tasks/Stages/XX.json` 完全一致。

## 5. 排列顺序速查

| 文件 | 顺序 |
|------|------|
| `resource/tasks/Stages/XX.json` | 常规关卡编号**从小到大**，**搓玉关放最后** |
| MaaRelease `api/resource/tasks.json` | 同上 |
| `StageActivityV2.json` 的 `Stages` 数组 | 关卡编号**从大到小**（搓玉关天然在末尾） |

## 6. 完整操作清单

0. ✅ 解析用户输入：WebFetch wiki 链接提取活动名/前缀/关卡时间（关卡关闭时刻）/各期章节名；材料名查 `item_index.json` 反查 Drop ID；仍缺的选章信息向用户收集
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`（导航任务放开头、删除旧活动整块，关卡从小到大）