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-bettergi.md
View on GitHub# 案例:BetterGI(better-genshin-impact 线,原神一条龙)
BetterGI 基于 BetterGI 程序(`BetterGI.exe`)跑原神一条龙,与 ZzzOd 同属
一条龙家族但物理形态不同:**无持久槽位**——用户独立配置模式下运行时把
字段物化到临时槽位 `User/OneDragon/MAS独立配置.json` + 前缀配置组,运行
结束删除/还原;MAS 前端是唯一编辑入口。本文件只记读代码推不出来的部分,
文件与字段现场读 `app/task/BetterGI/` 与 `views/BetterGIUserEdit/` 确认。
## 配置分层(决定备份对象)
| 层 | 位置 | 性质 |
| --- | --- | --- |
| 用户字段 | `UserData`(Info/OneDragon/Switch/Data/Notify) | 前端编辑,事实源之一 |
| per-user 副本 | `data/{script_id}/{user_id}/` 的 `OneDragon/`(一条龙副本)、`ScriptGroup/`(配置组)、`GlobalDomain/`(秘境刷取) | **前端端点直接读写**(`/scripts` 的 read/write_user_script_group、read/write_global_domain_settings 等)——就是页面编辑对象 |
| BGI 全局主配置 | `{RootPath}/User/config.json` | **MAS 每次运行临时补写队伍/策略叶子、结束还原**(`apply_global_battle_*` + `snapshot/restore_global_battle_config`)——唯一被触碰的持久原生文件 |
| BGI 一条龙实配 | `{RootPath}/User/OneDragon/*.json`(含「默认配置」) | 直控+关闭时直接跑;用户独立配置模式 MAS **零接触** |
| 临时槽位 | `{RootPath}/User/OneDragon/MAS独立配置.json` + 前缀配置组 | 运行时物化、结束删除(`_restore_one_dragon_config`) |
## 配置恢复接入要求(mas=per-user 副本 + 字段侧车;native=全局 config.json)
BetterGI 已接入通用配置恢复(mas/native 双池 + 字段侧车 + viewOnly 查看
会话),后续改动必须符合 [config-restore.md](config-restore.md) 通用要求,
另守以下 BetterGI 特有项:
- **mas 池 = per-user 副本目录 + 页面字段侧车**:副本是前端端点直接读写的
编辑对象(对齐 OkNte「ConfigFile 即页面编辑对象」),字段侧车承载 UserData
里会物化/注入的字段(OneDragon 段全部 + Task.OneDragonConfigName +
Switch.Resource + Info.Mode 仅预览);Id/Password/前后置脚本/通知/Data
由 MAS 自己消费(登录与执行域)**不进侧车**。恢复 = 副本目录回滚 +
字段回填 UserData。
- **per-user 副本与来源无关、恒按用户分桶,无 owner 解耦**(对齐 General):
直控用户前端同样编辑副本落盘,mas 池对三态都存在——不要按 MAA/MaaEnd
「直控无 mas 池」套 BetterGI。
- **native 池 = 全局 config.json + BGI 一条龙实配**(``{RootPath}/User/config.json``
+ ``{RootPath}/User/OneDragon/*.json``,按物理根指纹分桶)。一条龙实配在
用户独立配置模式下 MAS 零接触,但它是**用户在 BGI GUI 里的直接编辑对象**
(直控/手工编辑场景,改坏无 MAS 侧找回点——用户实测「改了一条龙配置重进
编辑页无备份」后纳入);归档排除 MAS 运行时临时槽位「MAS独立配置.json」
(运行物化、结束删除,不是用户实配)。
- **native 预览只收 mas 侧有对应概念的字段**(§3.3「两池同字段同口径」):
- **已启用任务**(一条龙实配反读,置顶):实配 JSON 的 ``TaskOrder``(uid 序)
+ ``TaskEnabledList``(uid→bool) + ``TaskDefinitions``(uid→任务名) 三键
对位合成;实配文件取 config.json 顶层 ``selectedOneDragonFlowConfigName``
指向那份(BGI「配置」下拉所选),缺失回退首个实配;任一键缺失降级不反读;
- 战斗配置叶子(config.json):``autoFightConfig.strategyName`` 战斗策略
(= 侧车 AutoBossStrategyName)、``autoDomainConfig.partyName`` 秘境队伍
(= 侧车 PartyName)、``autoBossConfig``/``autoLeyLineOutcropConfig``/
``autoStygianOnslaughtConfig`` 各队伍与策略(= Plan 战斗步骤物化目标)。
**MAS 侧无对应概念的段不进预览**——一键开关(自动拾取/剧情/钓鱼/快速
传送/吃料理)、游戏路径、捕获模式、遮罩外观、热键等;通知凭据/米游社
cookie 等敏感字段一律不读不展示。
- **mas 预览任务行同口径**:侧车 ``Groups``(内置组开关)显示为「已启用任务」
罗列行(与 native 同标签);``CustomGroups``/``Queue`` 解析 JSON 字符串
显示罗列;不显示 Python 列表 repr。
- **运行前归档时机**:native 在 `manager.main_task`(物化前,任务级一次);
mas 在 `AutoProxy.main_task` 的 `_write_one_dragon_config` 前(物化会覆盖
副本)。**注意 BetterGI 无 manager 任务级 Temp 快照机制**(与 SRC/MAA 不同),
无恢复守卫需求。
- **viewOnly 查看会话**:BetterGI 配置会话本就「无参打开 BGI + 无基线注入
+ 无回写」(任务配置以 MAS 前端为准),viewOnly 与配置会话共享同一打开
路径,`ScriptConfigTask` 只需收 `view_only` 参数(manager 透传),无需
额外分支;前端查看会话超时静默关闭、关闭时不冲刷右栏配置(避免写盘)。
- **前端遮罩用 `GuiSessionMask`**:配置/查看两个实例(查看用专项
`bettergiViewing*` 词条);恢复按钮挂**「任务配置」标题行右侧**(该页有
此区块;只在页面没有任务配置类区块时才退挂基本信息)。
- **清理存量死调用**:`ScriptConfigTask.on_crash` 曾调用未定义方法
`_snapshot_one_dragon_config`(被 suppress 吞掉、永远静默失败),接入时
已删除——不要重新引入同类「调了等于没调」的残留。
## 节点详情注入(推送报告)
- **不建 log_box 采集会话**:BGI 日志已由 LogMonitor 按相/按轮捕获进
`log_record`(执行层一条、原生一条龙每轮重试各一条),`one_dragon_report`
是权威解析器(Serilog 头行配对、致命信号判失败、任务名对齐、重试取轮)。
`AutoProxy.final_task` 解析出合并分步表后,经 `tools/push_log.py` 的
`steps_to_push_log` 转成 push_log 三元组——在这里再喂一套 log_box 逐行
规则只会复刻解析器的上下文判定,且单会话跨重试轮的分段比 log_record 更差,
会与判态侧形成两份并行语义(MaaEnd「聚合按任务名、判态按任务 id」同款分叉)。
若上游日志规则足够「行内自足」(如 ok 系、MaaEnd 的 stdout 标记行)才走
log_box 采集会话。
- **开关与聚合**:开关 = 用户级 `Notify.PushLogMode`(关闭/逐条/汇总,前端在
用户编辑页基本信息区直接内联下拉,与 MaaEnd/ZzzOd 同型;共享组件
`UserNotifyConfig.vue` 保留 `showPushLogMode` 门控的呈现块,默认关闭、
按需传 prop 启用),关闭即不注入
(push_log 保持为空);注入点在 `AutoProxy.final_task`(on_crash 后
final_task 仍会跑,崩溃前解析出的步骤同样进报告)。`manager.final_task`
用 `build_user_result_text` + `mirror_report_to_dispatch` 聚合,与 ZzzOd 同型。
- **节点文本不带原因与异常计数**:只保留「✅ 成功/❌ 失败: 任务名」,
与 `app/tools/push_log.py` 的状态行契约及汇总式渲染对齐;步内可恢复报错
(含树脂耗尽这类预期停止)的数量与完整原因都在统计通知的分步表里,
节点时间戳取步骤开始时刻(naive 时刻须按今天组合,
直接 `timestamp()` 在 Windows 抛 OSError)。
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 |