活动推图适配协议
约 4773 字大约 16 分钟
提示
本文档是「活动推图」（AutoPromotion + AutoTrail）的换期适配协议。 功能采用流程与识别分层：流程层（调度状态机、阶段闸门）固定不变； 识别层的全部参数可经 pipeline JSON 的 custom_recognition_param 覆盖—— 换期适配只改 JSON，不动 Python。本协议面向 AI 执行设计： 把文档交给具备模拟器控制能力（如 MaaMCP）的 AI，说"按协议适配新活动"即可。
功能架构速览
| 文件 | 内容 | 层 |
|---|---|---|
resource/base/pipeline/activity/auto_promotion.json | 推图模式入口调度 + 推图循环 + 辅助 OCR 节点 | 流程 + 适配面 |
resource/base/pipeline/activity/auto_trail.json | 小径调度循环 | 流程 + 适配面 |
agent/custom/reco/auto_promotion.py | APModeGate（主线地图闸门）、APPhaseGate（任务状态重置）、APMapAnalyze（找关/星标/滑到头） | 识别算法（默认值事实源） |
agent/custom/reco/auto_trail.py | ATTrailAnalyze（小径五态） | 识别算法（默认值事实源） |
deps/tools/custom.recognition.schema.json | 全部可覆盖参数的声明（key/type/default） | 适配面清单 |
参数覆盖机制（v2 分层核心）
识别类的全部阈值/偏移/颜色/点击位常量都可在节点的 custom_recognition_param 中以常量名小写为 key 覆盖：
"AP_EnterStage": {
"recognition": {
"type": "Custom",
"param": {
"custom_recognition": "APMapAnalyze",
"custom_recognition_param": {
"query": "stage",
"lit_pixels": 25 // 仅本期需要的差异项
}
}
}
}规则：
- 默认值唯一事实源 = Python 类常量，pipeline JSON 平时只写
query， 换期只写差异项（避免 JSON 与代码默认值漂移） - 可覆盖参数全集见 schema 中
APMapAnalyze/ATTrailAnalyze的custom_recognition_paramproperties（含 type/default/description）， 修改类常量时需人工同步 schema（default/properties 双向一致） - 非法值回落默认并记 error；未知 key 记 warning 后忽略；参数 JSON 整体损坏时 使用全部默认值继续（不会中断任务）
- 国际服等多服差异走资源覆盖层（
global_en/等放同名节点覆盖文件）， 与参数覆盖正交
识别器契约
每个识别器（类 × query）的契约固定；某期 UI 大改导致参数调不动时， 替换对应实现方法即可，契约不变则流程层无感。
APModeGate / APPhaseGate（入口闸门，无可调参数）
推图模式 是单选项：
故事/主线：进入AP_EnsureStoryOrMain。主线地图（左上无模式按钮）或已在故事模式时直接推图；若单按钮布局显示「故事」，表示当前在探索页，点击该按钮切回故事；双按钮布局则点击「故事模式」按钮后直接进入故事推图流程。推图完成后自动接小径，小径不存在则正常结束。探索模式：进入AP_EnsureExplore。已在探索/探险模式时直接推图；若单按钮布局显示「探索/探险」，表示当前在故事页，点击该按钮切到探索；双按钮布局则点击「探索/探险模式」按钮后直接进入探索推图流程。主线地图由APModeGate(query=main)识别为无探索模式并正常结束。
小径不再作为独立 UI 开关，而是 故事/主线 推图完成后的自动收尾阶段。
APModeGate：
| query | 语义 | 命中返回 | 副作用 |
|---|---|---|---|
| main | 主线地图：左上无故事/探索模式按钮，且 is_stage_map() 成立 | box=[0,0,0,0], detail.mode=plain | 重置滑动计数 |
| story | 单按钮布局下左上显示「探索/探险」按钮，按钮文字是切换目标，故当前为故事页 | box=模式按钮位置, detail.mode=story | 重置滑动计数 |
| explore | 单按钮布局下左上显示「故事」按钮，按钮文字是切换目标，故当前为探索页 | box=模式按钮位置, detail.mode=explore | 重置滑动计数 |
APPhaseGate 目前保留用于任务入口状态重置，以及兼容旧阶段节点：
| query | 语义 | 命中返回 | 副作用 |
|---|---|---|---|
| entry | 任务入口，总命中 | box=[0,0,0,0] | 重置全部阶段与识别状态 |
| story / trail | 本次任务未进入过该阶段则命中 | 同上，detail.phase | 标记已进入 + 重置滑动计数 |
| explore | 同上，且地图左上有「探索/探险」或「故事」切换标签才命中 | 同上，detail.phase | 同上 |
新入口调度优先使用 AP_EnsureStoryOrMain / AP_EnsureExplore，不要再新增 故事模式 / 小径 / 探索模式 三个并列 switch。
APMapAnalyze（推图地图分析）
依赖辅助 OCR 节点：APStageNumberOCR（底部编号条）、APExploreAnchorOCR （左上模式标签锚点）——两者 ROI 直接在 pipeline JSON 调。
| query | 语义 | 命中返回 | 不命中含义 |
|---|---|---|---|
| map | 仅判定是否回到关卡地图页 | box=[0,0,0,0] | 不在地图页 |
| stage | 找编号最小的未完成关 | box=关卡点击区, detail.stage | 无未完成关（或亮星为 0 待下帧确认） |
| swipe | 无未完成关且未确认到头 | box=[0,0,0,0]（供 Swipe 动作） | 有未完成关 / 已到头 / 不在地图页 |
| done | 已确认滑到头且无未完成关 | box=[0,0,0,0] | 尚未确认到头 |
AP_StartAction 点击后先进入 AP_AfterStartAction 过渡循环：关卡详情页点完后，继续等待编队页第二个「开始行动」；识别到战斗标志后才进入肉鸽式 AP_WaitCombat 战斗等待循环。两个循环都只处理胜利/失败/跳过/奖励/确认，以及 APMapAnalyze(query=map) 识别到回到地图后的出口。 不要在这些循环里加入 AP_EnterStage / AP_SwipeMap / AP_AllDone，否则大招遮挡右上快进图标或左上回合数时会把战斗画面误当成地图继续滑动。
未解锁关卡不改变 APMapAnalyze 的职责：地图页仍只负责准确找到编号最小的未完成关。 进入关卡详情页后由调度层处理解锁分支：
AP_UnlockStage在详情页命中「解锁」按钮并点击；AP_UnlockConfirm命中确认弹窗后点击「确认」；- 若解锁失败，右上角会立刻出现「显影罐不足」，
AP_UnlockInsufficientCanister命中后停止任务并给出 log/toast； - 若解锁成功，详情页会变为可「开始行动」状态，继续走既有
AP_StartAction。
关键参数（全集见 schema，38 项）：
| json key | 默认 | 含义 / 调参依据 |
|---|---|---|
sat_min / val_min | 100 / 160 | 亮星像素的饱和度/亮度下限。val_min ≥150 才能排除关卡名底下的深色圆盘装饰 |
lit_pixels | 15 | 判完成的亮像素阈值。当期活动亮星 ≈120+，1987 的细四角星仅 ≈27-62，灰星恒 ≈0，故取 15 跨活动通用 |
zone_pad_left/top、zone_extra_w/h | 5/30/115/20 | 星标搜索区相对编号框的扩展（星标在编号右侧同行） |
stage_box_* | 见 schema | 编号 token 的位置/尺寸过滤；is_stage_map() 的主线兜底也必须通过这些过滤，不能只看“底部 OCR 有数字” |
stage_num_min/max | 1 / 30 | 有效活动关卡编号范围。实机曾把星标/装饰 OCR 成 0、70、75、76，必须过滤掉 |
multi_*、difficulty_*、marker_* | 见 schema | 三难度关卡的红色标记检测与分段判定。单星判定优先：亮像素 ≥ lit_pixels 直接判完成，三难度分组仅在亮像素不足时介入（防背景高饱和美术误触发多难度检测） |
right_half_x / right_empty_confirm | 640 / 2 | 滑到头判定：右半屏无关卡编号的连续确认帧数 |
滑到头判定：当前画面没有未完成关卡时，若屏幕右半仍有编号则继续向后滑； 若右半连续 right_empty_confirm 帧无编号，认为最后一关已过屏幕中线并结束。 不能用画面哈希——1987 等活动的星空背景有持续动画，静止画面的哈希也不稳定。
ATTrailAnalyze（小径五态）
| query | 语义 | 命中返回 |
|---|---|---|
| orange | 任务点橙色交互框（文案不定，统一点击） | box=orange_click_box |
| reading | 米白阅读面板（点面板外关闭） | box=read_close_box |
| dialogue | 对话场景（非地图 + 大面积暗，连续两帧确认） | box=dialog_click_box（右下空白，避开气泡） |
| task | 地图页小径列表最上面的任务项 | box=任务项 OCR 框 |
| done | 列表空（或剩余项反复点击无响应） | box=[0,0,0,0] |
参数全集见 schema（26 项）：橙框颜色掩码 orange_*、面板判定 cream_*/read_*、 对话判定 dark_v_max/dialog_*、列表过滤 item_* 等。 「小径」是本期活动的附加玩法——每期附加玩法不同（下期未必是小径）， 不强求跨期通用，失效时停在超时兜底即可，新玩法待上线后另行适配。
换期体检流程
- 直接跑：新活动地图页启动任务。大多数情况零修改可用（识别全部基于 OCR 文本 + 像素统计，已在「灰与砂的巨木」「1987宇宙组曲」两期验证）
- 失效时采样诊断：MaaMCP 截图 → OCR 拿编号 box → 跑取样脚本统计亮/灰星 像素 → 对照失效模式表定位参数
- 修复 = 写 JSON：把差异参数写进对应节点的
custom_recognition_param（或调整辅助 OCR 节点 ROI），不改 Python - 回验：对两期历史截图样本回跑判定（确认不退化）+ 实机全流程
取样脚本
# 输出指定编号框邻域的亮像素数：灰星应 ≈0，亮星应明显高于 lit_pixels
import numpy as np
from PIL import Image
SAT_MIN, VAL_MIN = 100, 160
PAD_LEFT, PAD_TOP, EXTRA_W, EXTRA_H = 5, 30, 115, 20
img = np.asarray(Image.open(r"截图路径.png").convert("RGB")).astype(np.int32)
box = [400, 547, 44, 35] # 编号 token 的 [x, y, w, h]，替换为实际 OCR 结果
h_img, w_img = img.shape[:2]
x0, y0 = max(box[0] - PAD_LEFT, 0), max(box[1] - PAD_TOP, 0)
x1 = min(box[0] + box[2] + EXTRA_W, w_img)
y1 = min(box[1] + box[3] + EXTRA_H, h_img)
c = img[y0:y1, x0:x1]
v = c.max(axis=2)
s = (v - c.min(axis=2)) * 255 // np.maximum(v, 1)
print("亮像素数:", int(((v >= VAL_MIN) & (s >= SAT_MIN)).sum()))失效模式对照表
| 现象 | 原因 | 修法（写 JSON） |
|---|---|---|
| 无任何关卡识别，直接滑动/超时 | 底部条位置变，OCR 不到编号 | 调 APStageNumberOCR ROI 与 stage_box_* |
| 已完成关被判未完成（反复进已通关卡） | 星标偏移/饱和度变 | 先调 zone_* 对准星标位置，再按取样调 lit_pixels/sat_min/val_min |
| 未完成关被判完成（跳关） | 邻域混入高饱和装饰 | 提高 val_min 或 lit_pixels，必要时收窄 zone_* |
| 滑动确认中断超时 | 模式标签位置超出锚点 ROI | 调 APExploreAnchorOCR ROI（当前 [20,60,220,260] 已覆盖单按钮与双按钮两种布局） |
| 滑个不停不判到头 | 编号签名异常（如 OCR 不稳） | 查 APStageNumberOCR；勿改回画面哈希（动态背景下不可用） |
| 三难度判定错乱 | 难度标记颜色/布局变 | 调 marker_* 颜色掩码与 multi_*。注意单星优先：亮像素足够即判完成，不会进入三难度分支 |
| 已完成关被报「三难度未完成」 | 背景红色美术被当难度标记 | 通常无需处理（单星优先已兜住）；仍误判则提高 multi_marker_pixels |
活动入口导航（已自动化）
入口分两条路径，由任务选项「选择活动」决定：
当期活动（case「当期活动」）：主页 → 点「入场」上方的版本名标题区 （固定位置 [966,226,184,42]，文字每期变化故按位置点击不依赖文案）→ 当期活动 入口界面 → 点右侧「步入剧情」→ 当期活动关卡地图。专用节点 AP_NavCurrentEntry / AP_NavStoryEnter 默认禁用，由该 case 启用。 注意 AP_NavLoop.next 中「步入剧情」必须排在 AP_NavArrived 之前—— 曾因顺序颠倒，进入活动入口页后下一轮直接假到达退出，从未点过步入剧情。
历史活动/主线（其余 20 个 case）：走映像页卡片查找，见下文。
到达判定 AP_NavArrived（is_stage_map）是两条路径共同的导航出口，且要求 先离开过地图页再回到地图页——否则从某张地图页启动导航会在错误的地图上 直接开推。另有两条反向排除防御：「步入剧情」可见（活动入口页）或 「活动正篇/主线正篇」可见（卡片详情页）均判非地图页——详情页标题含数字 （如「7号往事」）会被关卡编号 OCR 误读，曾导致卡在详情页假到达。
历史活动（映像页）
任务选项「选择活动」默认「当前页面」（手动进入地图页再运行）；选择具体活动名 则全自动导航（auto_entry.json，已实测 1987宇宙组曲/唐人街影话端到端通过）：
任意页面 → ReturnMain 回主页 →「入场」→ 世纪末尺度页 →「映像」→ 卡片横排 先回卷到最左（右滑至标题集合连续不变）→ 逐屏向右查找（慢速短距左滑， 快滑会触发惯性滚动跳屏）→ 点目标卡片（标题子串匹配，含屏幕边缘截断标题的 残缺反向匹配；点击不重置状态，未生效自动重试）→ 详情页「活动正篇/主线正篇」 （OCR 命中后点击上偏 40px 落在主按钮上——正篇文字是小字，直接点小字无响应； 按钮位置随活动浮动：唐人街在中下、1987 在右下，ROI [300,400,980,320] 通吃）→ 关卡地图页 → 接入三阶段推图。
卡片解锁分支：点击卡片后若活动未解锁会弹出含「解锁」按钮的弹窗 （此时背景卡片仍可见，解锁链必须排在 AP_NavCardClick 之前，否则反复误点 背景卡片卡死）：AP_NavUnlockButton 点「解锁」→ 公共 Confirm 点「确认」 （已提至卡片点击之前）→ 若右上角 ROI [1067,105,112,32] 弹出「显影罐不足」， AP_NavInsufficientCanister 命中后 toast 提示并停止任务（非 JumpBack）； 未弹出则解锁成功继续导航。
导航识别器 APCardFinder（query=nav/card/rewind/swipe/notfound）依赖辅助节点 APImagePageOCR（映像页「显影罐」横幅锚点，防止在地图页/世纪末页误触发滑动） 与 APCardTitleOCR（标题行）。新活动入卡片清单 = 在任务选项「选择活动」加一个 case（注入 card_name），多服卡片名差异经资源覆盖层处理。
卡片清单（自最左起，标题即任务选项「选择活动」的 case；全部 19 张已逐卡验证）： 雷米特杯失窃案 / 绿湖噩梦 / 行至摩卢旁卡 / 洞穴的囚徒※ / 复兴！乌卢鲁运动会 / 朔日手记 / 今夜星光灿烂※ / 再见，来亚什基 / 孤独之歌 / 飞驰！明日之城※ / 7号往事 / 忧郁的热带 / 圣火纪行：东区黎明※ / 地球上最后的夜晚 / 唐人街影话 / 疯癫与文明 / 1987宇宙组曲 / 复乐园 / 行于漫漫长路上※（※=主线卡，详情页为「主线正篇」、地图无模式按钮）
跨活动实测记录
| 活动 | 结果 | 适配动作 |
|---|---|---|
| 灰与砂的巨木（当期，2026-06） | 全流程通过（01→19 + 小径 12 项 + BOSS） | 基线 |
| 1987宇宙组曲（映像/历史） | 全流程通过（故事→小径空过→切探索→探索推完） | ① 锚点/切换 ROI 放宽至 [20,60,220,260] 覆盖双按钮布局；② lit_pixels 40→15（细四角星亮像素仅 27-62）；③ 滑到头判定从画面哈希改为编号签名（星空动画致哈希永不稳定） |
| 唐人街影话（映像/历史） | 识别验证通过（双按钮布局锚点/找关/详情页开始行动/三难度红标均正确） | ① stage_box_center_x_max 1160→1240：地图到尽头时末关停在屏幕右缘（21 关 cx=1226），过滤掉会被永久跳过；② stage 增加锚点校验：关卡详情页底部有缩略关卡条，曾被当成地图页反复点击；③ AP_StartAction ROI 放宽至 [1000,560,280,160] 并去掉 only_rec（详情页按钮位置随活动浮动；only_rec 在宽 ROI 下会把背景文字混入整行识别）；④ 小径列表排除词改为「模式」：双按钮布局的模式按钮落在列表区，曾被当成任务项点击 |
| 雷米特杯失窃案 / 绿湖噩梦 / 行至摩卢旁卡 / 复兴！乌卢鲁运动会 / 朔日手记 / 再见，来亚什基 / 孤独之歌 / 7号往事 / 忧郁的热带 / 地球上最后的夜晚 / 疯癫与文明 / 复乐园（映像/历史活动） | 导航+地图页识别验证全部通过（is_map ✓，均为双按钮布局） | 共性修复见上表与导航章节（PV 链/双帧确认/三档偏移） |
| 洞穴的囚徒 / 今夜星光灿烂 / 飞驰！明日之城 / 圣火纪行：东区黎明 / 行于漫漫长路上（映像/历史，主线卡） | 详情页为「主线正篇」，主线地图无模式按钮——锚点经 is_stage_map 备选判定（底部编号条 + 无开始行动按钮）全部通过 | 主线地图判定已通用化；早期误点相邻卡片由双帧位置确认修复 |
笔记
历史活动 19 张卡的导航均为实机端到端实测（真实进入各活动地图页）； 地图页识别用实机/离线截图逐节点跑 run_recognition 确认命中/不命中符合 预期。账号内历史关卡均已通关，战斗推进路径无从在历史活动上验证。 验证脚本模式：post_task 一个挂自定义 action 的入口节点，在 action 内对 截图调 context.run_recognition(节点名, image)。
适配状态与已知限制
| 范围 | 状态 |
|---|---|
| 当期活动（灰与砂的巨木）：入口导航 + 故事/主线（含小径）或探索模式 + 关卡/卡片解锁 + 吃糖 | ✅ 旧三阶段流程实机通过；单选模式入口/切换已实机截停通过 |
| 「当前页面」模式（手动进图后启动） | ✅ 实测通过 |
| 历史活动/主线 19 张卡：导航进图 + 地图识别 | ✅ 逐卡实测通过 |
| 历史活动未完成关卡的实战推进 | ⏳ 未验证——需未通关账号，待后续；识别层判定已通过，风险集中在进关/战斗/结算链 |
| 下期活动的附加玩法 | ⏳ 待定——每期玩法不同（本期为小径，下期未必），新活动上线后按本协议补适配 |
| 推图吃糖 | 固定不限有效期（infinite，吃所有糖），无单独的有效期选项 |
验收清单
- 识别单测：harness 对地图页跑 query=stage，未完成关识别正确且已完成关不误报
- 首关端到端：进关 → 战斗/剧情 → 结算 → 回地图
- 任意进度重启：中途停止再启动无缝继续
- 正常收尾：故事/主线模式为
AP_AllDone→ 小径 →AP_AllPhasesDone；探索模式为AP_AllDone→AP_AllPhasesDone，而非超时报错 - 兜底验证：未知界面优雅停止，
debug/on_error/有框架自动保存的现场截图 python -m pytest tests/全绿，schema 与类常量默认值人工核对一致
工具资产索引
- 实机踩点：MaaMCP（ADB 连接模拟器；Win32 窗口方式截图会黑屏）
- 进程内回归：stub
maa.agent.agent_server.AgentServer后Resource.post_bundle+Tasker.post_task，无需 GUI - 出错现场：框架 SaveOnError 自动存图到
debug/on_error/，无需自写截图 - 设计约定：调度节点
next按优先级排列 +[JumpBack]兜底；自定义识别用query多态；公共节点（CheckStopping/Confirm/ObtainedAwards/ClickBlank/EatCandyPage）直接引用；三阶段由APPhaseGate串联，任务选项经enabled开关