AUTO-MAS-Project/AUTO-MAS / .agents/skills/mas-script-specialized-adapter
mas-script-specialized-adapter
VerifiedReview, add, or refactor AUTO-MAS specialized script adapters by upstream architecture, including MAA, SRC, MaaEnd/MXU, General, ok-script adapters such as Okww and OkNte, multi-engine adapters such as HSR, and the one-dragon line such as BetterGI, as well as per-adapter issue-bundle exports. Use when lowering user setup friction, judging whether a change stays inside the black-box boundary (barrier first, then capability ownership), or changing ScriptType registration, task lifecycle, config ownership, ScriptConfig sessions, Electron integration, frontend edit surfaces, and verification.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.4 KB |
| references/adapter-code-norms.md | markdown | 12.4 KB |
| references/blackbox-boundary.md | markdown | 8.9 KB |
| references/config-archive.md | markdown | 17.7 KB |
| references/config-restore.md | markdown | 42.1 KB |
| references/examples-baah.md | markdown | 12.3 KB |
| references/examples-bettergi.md | markdown | 7.4 KB |
| references/examples-hsr.md | markdown | 16.6 KB |
| references/examples-m9a.md | markdown | 1.0 KB |
| references/examples-maaend.md | markdown | 4.4 KB |
| references/examples-oknte.md | markdown | 4.3 KB |
| references/examples-okww.md | markdown | 10.6 KB |
| references/examples-src.md | markdown | 4.9 KB |
| references/examples-whimbox.md | markdown | 13.8 KB |
| references/examples-zzzod.md | markdown | 33.9 KB |
| references/guide.md | markdown | 2.2 KB |
| references/issue-report.md | markdown | 2.6 KB |
| references/logbox-api.md | markdown | 22.7 KB |
| references/ocr-tools.md | markdown | 3.6 KB |
| references/script-frontend-architectures.md | markdown | 7.2 KB |
references/examples-baah.md
View on GitHub# 案例:BAAH(碧蓝档案爱丽丝助手)
BAAH 是**独立发行版 + 自带 JSON 配置体系**的线:入口 `BAAH.exe <配置名>.json`,配置由它自己的 jsoneditor 界面维护,MAS 不复制配置目录、不做字段化,只以「配置文件名」引用 BAAH 原有配置,并在运行期对少量关键字段做托管。模拟器不归 BAAH 管,由 MAS 调度。
具体字段、路径、函数名现场读 `app/task/BAAH/` 与 BAAH 发行版确认。本文件只记推不出来的部分。
## 产品决策(读代码看不出为什么)
- **用户身份 = BAAH 配置文件名,不是 MAS 目录副本**。BAAH 的配置是单个 JSON(`BAAH_CONFIGS/<名称>.json`),含大量 MAS 不该理解的任务字段,而该脚本自带的 jsoneditor 就是它的配置 UI。所以用户级配置只存配置名,运行前把该 JSON 交给 BAAH 自己读,**不把配置字段搬进 MAS 表单**——与 MAA/Okww 系「每用户一份配置树」的差异来自 owner 判定,不是省事。
- **路径单一来源**:只保留主程序路径一个字段,程序目录、配置目录、日志目录全部由它派生。不要给它们各开一个可填字段——用户填得越多,三者互相矛盾的概率越高,而它们本来就是同一个安装目录下的固定相对位置。
- **配置名要过校验再拼路径**:配置名直接参与路径拼接,必须先拒绝路径分隔符、`..` 与非法字符并按需补 `.json` 后缀,否则用户可以借配置名写任意路径。
- **托管字段取最小集**:只强制「跑完必须能自己结束」「日志必须落盘」「模拟器与游戏不许 BAAH 碰」这三类。任务是 BAAH 自己的模型,MAS 不接管、不改写、不校验其语义;超出这个集合就是越权。
- **模拟器归 MAS**:BAAH 只读 ADB 地址连过去,启动/等待/关闭由 MAS 做。不要在 BAAH 侧填模拟器路径。
## 上游契约(实测,光读代码看不出结论的部分)
- **启动**:`BAAH.exe <配置名>.json`,参数必须以 `.json` 结尾;配置名不带后缀时由 MAS 补齐。
- **日志**:写到 `DATA/LOGS/log_YYYY-MM-DD-HH-MM-SS.txt`(文件名即启动时刻)。同目录还会出现 `custom_log_*.txt`,**不是**本次运行日志——按前缀匹配时不要卷进来。
- **日志行格式**:`{版本} - {分:秒} - {级别} : {消息}`,例 `2.4.13 - 24:19 - INFO : 执行任务EnterGame`。
- **成败判据**:成功文本 `所有任务结束`(英文 `All tasks are finished`)只在成功路径出现;失败文本 `运行出错:` / `Error occurred:` 来自顶层异常处理。
- **退出码无约定**:不要拿进程退出码判结果,也不要因此认为它"总会成功"。
- **没有心跳**:只能靠日志推进与进程存活判活。
- **命中成功标记 ≠ 进程已结束**:BAAH 跑完还要执行自动退出与用户配置的 `POST_COMMAND`,立即强杀会截断后置命令,所以要留一段宽限时间再强制结束。
- **模拟器侧没有"已在运行则跳过"的判断**:对已启动的模拟器再发一次启动,会打印「模拟器启动进程已结束,可能是启动失败,或者是模拟器已经在运行」这种误导性 WARN。因此不允许两侧都尝试启动模拟器。
## 托管配置
运行前写入、运行后恢复;快照 + 原子写 + 自校验 + 失败回滚(任一文件写失败要回滚已落盘的那份,不留半托管状态)。
| 托管项 | 值 | 为什么 |
| --- | --- | --- |
| `CLOSE_BAAH_FINISH` / `CLOSE_BAAH_ERROR` | `True` | BAAH 默认停在 `input()` 等回车,进程永不结束,会被误判成脚本卡死并反复重启 |
| `CLOSE_EMULATOR_FINISH` / `_ERROR`、`CLOSE_GAME_FINISH` / `_ERROR` | `False` | 模拟器与游戏的启停由 MAS 编排,不能让 BAAH 关掉仍需复用的实例 |
| `TARGET_EMULATOR_PATH` | `""` | 禁止 BAAH 自行启动模拟器:它按实例编号走,配置稍有出入就拉起另一个实例,且冷启动耗时吃掉它自己的等待窗口 |
| `KILL_PORT_IF_EXIST` | `False` | 它的"清理残留端口"会 `taskkill` 监听目标端口的进程——那正是 MAS 刚拉起的模拟器,而此时启动器路径已置空、拉不回来 |
| `ADB_DIRECT_USE_SERIAL_NUMBER` | `False` | ADB 目标改由 MAS 按绑定的模拟器槽位推算,不依赖 BAAH 侧手填 |
| `RETRY_WHEN_ERROR` | `0` | 重试与通知收归 MAS 统一负责,避免两边各重试一遍 |
| `NOTI_WHEN_SUCCESS` / `_ERROR` | `False` | 通知由 MAS 发送 |
| 软件配置 `SAVE_LOG_TO_FILE` | `True` | BAAH 默认不写日志文件,而任务节点采集依赖它 |
- **运行期值覆盖静态托管值**:ADB 地址由模拟器调度解析(形如 `127.0.0.1:16448`),拆成 `TARGET_IP_PATH` / `TARGET_PORT` 注入,用户因此不必在 BAAH 里手填端口。
- **写盘必须无 BOM**:带 BOM 的 JSON 会让 BAAH 静默按默认值运行,不报错。
- **读配置不能把失败当空**:读取失败或内容损坏时若退化成空对象,比对与恢复就会拿空配置覆盖用户文件,运行结束时把用户配置清空。
- **恢复要能在"什么都没写"时安全返回**:任务在托管前被中止时收尾拿到的是 `None` 快照,恢复函数必须直接返回而不是访问属性。
## 配置恢复接入要求(引用型专项形态)
接入通用配置恢复(见 [config-restore.md](config-restore.md))时,本线「用户身份 = 配置文件名」的差异必须遵守:
- **native 池目标按当前用户 ConfigName 动态解析**:池 key 恒为 `native`(按 BAAH 配置目录物理指纹分桶),归档对象 = 当前用户绑定的 `<配置名>.json` + `software_config.json`;配置名可改可不存在——目标文件缺失(未创建/被误删)时跳过归档不报错,恢复前 `resolve_config_name` 必须重新校验(防空/防路径穿越)。
- **恢复写到当前 ConfigName 指向的文件**(覆盖语义):备份文件名是归档时的配置名,与当前名不同说明用户改过绑定——恢复内容写到当前绑定,不回填 ConfigName(改绑定是用户的主动决策,恢复配置不等于恢复绑定)。
- **归档与托管写入的时序**:运行前归档必须在 `apply_managed_config` 之前(托管键改写会污染归档内容);托管结束的键级还原 ≠ 归档——托管键之外的内容(用户在 jsoneditor 改坏的其余字段)只有持久归档能找回,这正是本专项接入的核心价值。
- **mas 池是元字段侧车**:BAAH 无字段化配置面板,侧车当前只有 ConfigName(可回填)+ Mode/IfQuickConfig(决定 MAS 是否写入 BAAH,仅预览不回填);未来 MAS 侧扩展配置内容时侧车直接扩展。
- **无遮罩会话**:不提供「查看详细配置」;归档时机 = 运行前(托管写入前)+ 编辑页进入(native)/ 退出(mas)。
- **预览反读关键字段(以实测为准)**:扁平 JSON 结构可读——目标设备(`TARGET_IP_PATH:TARGET_PORT` / `ADB_SEIAL_NUMBER` 串号直连)、行为开关类托管键、任务编排 = **`TASK_ORDER` + `TASK_ACTIVATE` 对位**合成「已启用任务」(2.4.13 实测结构,缺任一键降级不反读);软件配置单列。**教训:反读键名必须现场核实**(example.json 160 键里并没有臆想的 `JSON_PATH`),上游私有字段想当然就会预览空行。
## 模拟器调度
- 字段挂在 `Emulator` 段(`Id` / `Index` / `CloseOnFinish`),并注册进 `related_config`,前端才能取到模拟器下拉。
- 每次尝试前调模拟器的 `open(Index)` 并等设备在线,结束按开关 `close(Index)`。**管理器的 open 是幂等的**——已在线立即返回,所以"让实例常驻"没有收益,不要用常驻绕冷启动。
- 调度解析出的设备地址可能是**串号**(`emulator-5554` 这类)而不只是 `host:port`:串号要按串号直连,不要静默回落到 BAAH 侧手填的端口,否则会连到别的设备上去。
- 收尾路径全程幂等:失败重试、手动中止、异常退出都要走到关闭逻辑。
## 任务节点采集(log_box)
- 规则**顺序敏感**:`log_box` 对同一行只取首个命中规则,所以最具体的「整体运行失败」必须排在最前——失败原因文本里可能带任务名(真实日志:`运行出错: 任务InCafe执行后条件不成立或超时…`),排在任务规则之后会被任务正则当成普通节点行吞掉。
- **任务是嵌套的**:开始与结束标记构成后进先出配对,用栈跟踪「已开始、未结束」的任务;运行终止时仍在栈里的任务(运行出错、进程被强杀、日志静默超时)统一标为失败,否则它们会按开始标记的默认成功进入报告。只有栈为空时,才把上游给出的错误原因本身作为失败节点输出。
- **同一节点会重复出现**(BAAH 自己会重跑任务):保留最高优先级状态(失败 > 跳过 > 成功),节点顺序与时间戳取最后一次出现——报告应呈现最终一次的流程顺序。
- **开关消费在"是否创建采集会话"处**:关闭时不创建 log_box(省采集开销),而不是采完再过滤;采集会话建在日志文件定位之后,只取会话内新增;重试时丢弃上一轮节点,报告只呈现最后一轮。
- 「是否展示节点详情」与「任务日志记录 / 结果判定」是两件事,不要复用一个开关:后者是基础能力。
## 陷阱
- ★**日志时间戳区间不能写死**。`LogMonitor` 的第一个参数是**对整行做的字符切片**(`line[start:end]`),不是按分隔符分词后的字段下标;而 BAAH 行首是版本号,位数会随版本变化(`2.4.13` 6 位、`2.4.100` 7 位)。正确做法是**读日志首行、按第一个 ` - ` 的位置推算**区间,长度由时间戳格式自身推算。写死区间一旦对不上,`LogMonitor` 会把每一行判为解析失败并被 `suppress` 静默丢弃 → **整轮日志一行都不入库**:界面停在「正在等待 BAAH 日志文件生成」,成功文本永远匹配不到,任务只能等到超时。(BAAH 适配踩过;排障时先看后端日志有没有「成功定位到日志文件」——有就说明文件找到了,问题在采集不在查找。)
- **日志监控器要在定位到日志文件之后才构造**:提前构造会让基准时刻落在跨整点之前,首行时间戳被算成上个小时而整段丢弃。
- **上游自带的等待窗口短于冷启动**:实测 MuMu 冷启动约 49.7s,而 BAAH 自己的 `check_adb_connect` 重试上限约 45s,于是它先自判失败。把等待移到 MAS 侧后问题消失——这是"模拟器归 MAS"的实际动机,不只是架构偏好。
- **MuMu 的 `-v N` 是实例序号,不是 ADB 端口**。传错序号会让它连到别的实例(实测目标实例 2 连到了实例 1 的 16416),而日志只表现为"打开游戏失败"。端口规律:`16384 + (index + 1) * 32`。
- **自造状态文案会打断状态机**:运行态文本必须用既有枚举值,自加后缀会让调度台与前端的等值判断全部失效。
- **状态字段要真的接上**:跨天重置代理日期与次数、成功后递减剩余天数并累加次数、通知按用户级配置分支——这些字段存在于模型和界面上,不代表运行时会消费。
## 审查清单
- [ ] 路径字段只有一个来源(主程序路径),目录由它派生,未新增可填的目录字段
- [ ] 用户级配置只引用配置名,未把上游配置字段搬进 MAS 表单;配置名经校验后才参与路径拼接
- [ ] 托管项仅限三类,且逐条能说出"不托管会怎样";写入无 BOM、失败回滚、`None` 快照下的恢复安全
- [ ] 运行期注入的 ADB 地址支持串号与 `host:port` 两种形态,未静默回落
- [ ] 日志文件按前缀 + 启动时刻定位,未把 `custom_log_*` 当运行日志;切片区间按首行推算而非写死
- [ ] 日志监控器在文件定位之后构造
- [ ] 模拟器由 MAS 启动/等待/关闭,脚本侧路径已置空,端口清理已关闭,关闭受用户开关控制
- [ ] 成功标记后留宽限时间,未截断上游后置命令
- [ ] 节点采集规则顺序正确、LIFO 配对、状态取最高优先级;开关关掉时不创建采集会话
- [ ] 状态与统计字段确实被运行时消费,未停留在模型层
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |