配置语义
支持原生脚本配置接管的专项,使用 基础层(base) 和 覆盖层(overlay) 描述任务配置。任务运行时,覆盖层按字段覆盖基础层,得到本次任务的生效配置:
task_config = base ⊕ overlay
overlay 的优先级高于 base;没有覆盖层时,任务直接使用基础层。覆盖层只存在于任务运行过程,不改变基础配置的来源。本文是开发者和文档维护者使用的配置语义规范。
三种基础来源和“覆写常规配置”是否可用,以对应专项的界面和适配实现为准,不能将兼容字段当作有效开关,见下方专项适用边界。配置框架的事务工作区也不是本页的业务覆盖层,见配置管理。
核心实体
托管(Managed script)
托管是 MAS 侧创建的控制实体。它保存一个外部自动化脚本的路径、启动参数及托管级配置,并可以包含多个账号。
账号(Account)
账号是托管下的执行配置条目,可保存游戏账号信息、凭据和任务设置;是否支持切换游戏账号由对应专项决定。同一托管可以有多个账号。
代码和 API 中现有的 Script / User、script_id / user_id 等标识符保持不变;说明文字使用“托管”与“账号”。
“托管”和“账号”描述的是 MAS 的实体边界,不等同于外部脚本自身的对象模型。接入某个脚本时,应优先沿用该脚本的原生概念,不能因为 MAS 的实体名称而改写上游术语。
基础层(base)
基础层是任务运行时的主配置,持久化在磁盘上,跨任务保留。它有三种互斥的来源:
| 来源 | 所属层级 | 含义 | 基础配置的 owner |
|---|---|---|---|
| 托管级(共享配置) | 托管 | 同一托管下的多个账号共用一份基础配置 | 托管 |
| 账号级(独立配置) | 账号 | 每个账号拥有独立的基础配置 | 账号 |
| 原生 | 无 MAS 层级 | 基础配置直接来自外部脚本,MAS 不维护一份平行配置 | 外部脚本 |
托管级和账号级是基础层的存储层级;原生是与它们并列的第三种来源,并不是另一个 MAS 层级。
三种来源的边界
三种来源只决定基础配置的 owner,不决定任务运行时一定使用哪些字段:
- 托管级表示基础配置可以被多个账号共享,不表示所有账号的最终运行配置永远相同。
- 账号级表示基础配置按账号隔离,不表示账号不能使用覆盖层。
- 原生表示 MAS 把外部脚本现有配置作为基础,不复制、不平行维护该配置。
因此,“共享配置”不等于“修改一次后所有账号的运行结果都相同”。账号若启用了覆盖层,本次任务仍会以自己的覆盖字段为准。
覆盖层(overlay)
覆盖层是账号在用户侧通过覆写常规配置启用的任务期配置。它承载 MAS 页面提供的常规任务字段,并在任务启动时临时覆盖基础层的对应字段。
覆盖层必须遵守以下规则:
- 优先于基础层:同名字段以覆盖层的值生效。
- 不改变基础来源:启用或关闭“覆写常规配置”不会把托管级、账号级或原生互相转换。
- 按账号生效:覆盖层属于账号的任务设置,不会自动扩散到同一托管下的其他账号。
- 任务结束恢复:任务开始前保存基础配置,任务结束后恢复原值;成功、失败、取消、超时、异常和进程崩溃都必须纳入恢复路径。
- 字段范围有限:覆盖层只覆盖 MAS 明确提供的常规任务字段,不替代外部脚本的完整配置。
覆盖层与基础层可以自由组合:
| 基础来源 | 未启用“覆写常规配置” | 已启用“覆写常规配置” |
|---|---|---|
| 托管级(共享配置) | 使用共享基础配置 | 共享基础配置 + 当前账号的覆盖层 |
| 账号级(独立配置) | 使用独立基础配置 | 独立基础配置 + 当前账号的覆盖层 |
| 原生 | 使用外部脚本的原生配置 | 原生配置 + MAS 常规字段覆盖 |
这里的“覆写”是任务运行期间的临时覆盖,不应被实现为永久写回基础配置。只有外部脚本自身的配置界面明确保存的内容,才属于原生基础配置。
配置选择与运行流程
一个账号的配置解析可以按以下顺序理解:
- 根据账号选择的来源,定位基础层:托管级、账号级或原生。
- 如果账号启用了“覆写常规配置”,读取该账号的覆盖字段。
- 将覆盖字段按字段合并到基础层,覆盖层值优先。
- 启动任务并使用合并后的配置。
- 任务结束后恢复被临时覆盖的基础文件,并清理本次任务的覆盖状态。
实现新的专项适配时,必须明确每个字段属于基础层还是覆盖层,并明确该字段的磁盘 owner。不能把只在运行期间使用的字段写入持久化基础配置,也不能让账号覆盖层意外污染同一托管下的其他账号。
专项适用边界
下面是当前实现的例外,不能仅凭字段存在就套用通用三态或覆写流程:
| 专项 | 实际行为 |
|---|---|
| MFW 及其风味 | 账号页任务快照是任务来源,运行不消费 Info.Base 或 Info.IfQuickConfig。 |
| General | 原生来源使用外部脚本配置;非原生来源使用当前账号的 ConfigFile。旧 shared 值与 independent 行为相同,不读取共享 Default,也不消费覆写开关。 |
| BetterGI | 界面提供独立配置与原生配置;旧 shared 值按当前账号的独立配置处理,不表示账号间共享。 |
| HSR | 基础配置按共享计划、账号计划或上游原生配置解析,不建立账号 ConfigFile 副本;运行不消费 Info.IfQuickConfig。 |
| BAAH | 使用账号绑定的 Info.ConfigName 文件,运行不消费 Info.Base 或 Info.IfQuickConfig。模拟器等托管项、关卡计划和活动优先另有生效规则,不能据来源值承诺不写配置。 |
| Whimbox | shared 与 independent 当前都使用本账号页面设置,不表示账号间共享配置;native 仅在启用覆写时临时写入面板覆盖集,结束后恢复。 |
zzz-od 的特殊模型
zzz-od 是单托管、多账号的结构。MAS 账号绑定上游配置中的实例槽;一个托管关联的原生配置树中,同时存在按槽保存的配置和跨槽共享的内容。
因此:
- 界面提供独立与原生来源;旧
shared值按账号字段与绑定槽处理,不表示账号间共享基础配置。 - MAS 配置备份按绑定槽分桶,不能直接套用普通专项的账号目录布局。
- 运行不消费
Info.IfQuickConfig;原生来源不下发 MAS 任务覆盖。共享物理目录不等于共享基础配置。
术语约定
开发者用语统一使用:
base:基础层;面向用户描述为基础配置。overlay:覆盖层;面向用户显示为“覆写常规配置”。- Managed script:托管;Account:账号。
- 基础层来源:托管级(共享配置)、账号级(独立配置)、原生。
普通语境中的“脚本”和“用户”可以继续使用,例如“外部脚本配置”或“用户填写的凭据”;但它们不能作为上述 MAS 实体或基础配置来源的名称。
相关讨论
- AUTO-MAS#879:配置语义与术语统一