配置语义

AUTO-MAS 的配置由**基础层（base）和覆盖层（overlay）**组成。任务运行时，覆盖层按字段覆盖基础层，得到本次任务的生效配置：

task_config = base ⊕ overlay

overlay 的优先级高于 base；没有覆盖层时，任务直接使用基础层。覆盖层只存在于任务运行过程，不改变基础配置的来源。本文是开发者和文档维护者使用的配置语义规范。

核心实体

托管（Managed）

托管是 MAS 侧创建的脚本控制实体。它保存一个外部自动化脚本的路径、启动参数及托管级配置，并可以包含多个账号。

账号（Account）

账号是托管下的游戏账号条目。账号保存账号级配置、账号凭据和任务相关设置；同一托管可以有多个账号。

“托管”和“账号”描述的是 MAS 的实体边界，不等同于外部脚本自身的对象模型。接入某个脚本时，应优先沿用该脚本的原生概念，不能因为 MAS 的实体名称而改写上游术语。

基础层（base）

基础层是任务运行时的主配置，持久化在磁盘上，跨任务保留。它有三种互斥的来源：

来源	所属层级	含义	基础配置的 owner
托管级（共享配置）	托管	同一托管下的多个账号共用一份基础配置	托管
账号级（独立配置）	账号	每个账号拥有独立的基础配置	账号
原生	无 MAS 层级	基础配置直接来自外部脚本，MAS 不维护一份平行配置	外部脚本

托管级和账号级是基础层的存储层级；原生是与它们并列的第三种来源，并不是另一个 MAS 层级。

三种来源的边界

三种来源只决定基础配置的 owner，不决定任务运行时一定使用哪些字段：

• 托管级表示基础配置可以被多个账号共享，不表示所有账号的最终运行配置永远相同。
• 账号级表示基础配置按账号隔离，不表示账号不能使用覆盖层。
• 原生表示 MAS 把外部脚本现有配置作为基础，不复制、不平行维护该配置。

因此，“共享配置”不等于“修改一次后所有账号的运行结果都相同”。账号若启用了覆盖层，本次任务仍会以自己的覆盖字段为准。

覆盖层（overlay）

覆盖层是账号在用户侧通过覆写常规配置启用的任务期配置。它承载 MAS 页面提供的常规任务字段，并在任务启动时临时覆盖基础层的对应字段。

覆盖层必须遵守以下规则：

• 优先于基础层：同名字段以覆盖层的值生效。
• 不改变基础来源：启用或关闭“覆写常规配置”不会把托管级、账号级或原生互相转换。
• 按账号生效：覆盖层属于账号的任务设置，不会自动扩散到同一托管下的其他账号。
• 任务结束恢复：任务开始前保存基础配置，任务结束后恢复原值；成功、失败、取消、超时、异常和进程崩溃都必须纳入恢复路径。
• 字段范围有限：覆盖层只覆盖 MAS 明确提供的常规任务字段，不替代外部脚本的完整配置。

覆盖层与基础层可以自由组合：

基础来源	未启用“覆写常规配置”	已启用“覆写常规配置”
托管级（共享配置）	使用共享基础配置	共享基础配置 + 当前账号的覆盖层
账号级（独立配置）	使用独立基础配置	独立基础配置 + 当前账号的覆盖层
原生	使用外部脚本的原生配置	原生配置 + MAS 常规字段覆盖

这里的“覆写”是任务运行期间的临时覆盖，不应被实现为永久写回基础配置。只有外部脚本自身的配置界面明确保存的内容，才属于原生基础配置。

配置选择与运行流程

一个账号的配置解析可以按以下顺序理解：

1. 根据账号选择的来源，定位基础层：托管级、账号级或原生。
2. 如果账号启用了“覆写常规配置”，读取该账号的覆盖字段。
3. 将覆盖字段按字段合并到基础层，覆盖层值优先。
4. 启动任务并使用合并后的配置。
5. 任务结束后恢复被临时覆盖的基础文件，并清理本次任务的覆盖状态。

实现新的专项适配时，必须明确每个字段属于基础层还是覆盖层，并明确该字段的磁盘 owner。不能把只在运行期间使用的字段写入持久化基础配置，也不能让账号覆盖层意外污染同一托管下的其他账号。

zzz-od 的特殊模型

zzz-od 是单托管、多账号的结构。它的 MAS 账号条目与上游“实例”不是同一层概念；上游实例实际上对应账号，并由原生配置中的实例管理承载。

因此：

• zzz-od 的账号视图可能都落在同一份托管级基础配置中。
• “托管级 / 账号级 / 原生”的物理落点不能直接套用普通专项的文件布局。
• 开发 zzz-od 适配时，应以其上游配置模型为准，同时保留 MAS 的托管、账号和覆盖层边界。

术语约定

开发者用语统一使用：

• base：基础层；面向用户描述为基础配置。
• overlay：覆盖层；面向用户显示为“覆写常规配置”。
• Managed：托管；Account：账号。
• 基础层来源：托管级（共享配置）、账号级（独立配置）、原生。

普通语境中的“脚本”和“用户”可以继续使用，例如“外部脚本配置”或“用户填写的凭据”；但它们不能作为上述 MAS 实体或基础配置来源的名称。

相关讨论

• AUTO-MAS#879：配置语义与术语统一