Skip to content

AUTO-MAS-Project/AUTO-MAS / .agents/skills/mas-script-specialized-adapter

mas-script-specialized-adapter

Verified

Review, 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.

references/blackbox-boundary.md

View on GitHub
# 黑箱边界:专项适配红线

适用范围:所有专项适配(`app/task/*`)的需求评估、方案设计与代码审查。本文件规定判据与提示要求,不构成开工许可。

## 推进顺序:先降门槛,再补缺位

1. **先降低配置门槛**:消除安装导入、路径选择、首次配置与高频任务编排中的手工步骤,减少用户需要调整的选项。
2. **再补本体缺位**:仅当第 1 步无剩余空间、且缺口确属 MAS 领域时,才实现补位。

立项判定(新功能必须先回答):

- 它消除了用户当前必须手工完成的哪一步?答不出具体步骤,不立项。
- 若以「补齐上游缺位」立论:缺位是否属 MAS 领域?上游是否确实没有任何等效入口?两者同时成立才立项。

反模式:

- 配置门槛没有下降,却在上游已有能力之上自建功能;
- 把上游原始配置面板原样搬进 MAS,并当作门槛降低;
- 补出的功能没有对应用户场景与手工步骤,只是「字段齐全」。

## 判定:能力归属

先判定能力属于谁,再决定 MAS 能否实现。

1. 这件事是不是「脚本该干的活」?涉及**游戏内操作**(登录、切号、进本、战斗)、**脚本任务的执行与成败判定**、或**脚本配置语义**,即为上游领域。
2. 操作对象是**游戏本体**,还是上游程序或模拟器?直接操作游戏本体一律属上游领域;操作上游程序、模拟器或操作系统属复用或 MAS 领域。

| 归属 | 范围 | MAS 可做 | MAS 不可做 |
| --- | --- | --- | --- |
| 上游领域 | 游戏内操作、脚本任务的执行与成败、脚本配置语义 | 复用其入口;用其既有机制驱动 | 自行实现这些能力——上游缺失时按「上游缺失能力的处理顺序」办 |
| MAS 领域 | 用户与账号管理、多脚本/多实例调度、计划表、通知、统计与历史、模拟器生命周期、跨脚本编排 | 自行实现,判定权归自己 | 读取或反推上游内部状态 |
| 上游私有格式 | 配置文件内部字段、计划/队列/运行记录、资源文件、源码内部 | 透传读写:值经手、语义不过手 | 在其上建映射表、平行模型或自造判定信号 |

补位分两类:**MAS 领域内**的固有实现(无需上游许可);**上游领域缺失能力**经上游 PR 受阻后的**临时补位**(见下节,必须标注移除计划)。除这两类,MAS 替上游实现其领域能力即为越界。

## 上游缺失能力的处理顺序

当适配层需要上游不存在的能力时,按以下顺序处理:

1. **先向上游提 PR**:由上游实现该能力,适配层只调用。黑箱属性最强,抗上游改动最好。
2. **上游实现不可行时,适配层可临时补位**:满足下列任一情形即可先行实现,并在代码与文档中标注为**临时补位**:
   - 上游作者评估为不需要,而适配层判断该能力确有必要;
   - 上游审核或发布周期过长,阻塞用户场景。
3. **上游实现后移除补位**:上游提供同能力入口后,按「时效与存量越界」处理,改为复用并移除适配层实现。

临时补位仍受能力归属与附加约束限制:不得读取或反推上游内部状态、不得在私有格式之上建模型、不得自造上游执行任务的判定信号。

## 三种合规介入方式

1. **复用**:CLI、原生 GUI 与配置会话、上游文档化接口。
2. **驱动**:用上游既有机制表达 MAS 意图——写配置或队列字段、传启动参数、启进程;执行与成败判定仍归上游。
3. **MAS 领域实现**:MAS 领域能力自行实现,不读取也不反推上游内部状态。

不属于以上三者,即为越界。

## 附加约束

| 轴 | 合规 | 违规 |
| --- | --- | --- |
| 执行权与判定权 | 上游执行的任务,成败取自上游结果面(日志、报告、退出码) | 上游执行的任务,适配层自打标记并自行判定成败 |
| 语义所有权 | 透传:只写入或读取上游字段 | 复制:在上游私有格式之上维护适配层模型、字段映射表或状态机 |
| 失效可发现性 | 上游变更后响亮失败(注入无效、报错、任务不生效) | 上游变更后静默误判(字段被忽略、仍判成功) |

## 允许依赖:上游对外契约

- CLI 参数、`--help` 声明、退出码
- 上游文档化的 JS/API、脚本与插件接口
- 原生 GUI 与配置会话(适配层只负责打开与切回)
- 进程名、发行版目录结构、可执行文件相对路径
- 日志文案与滚动行为、运行报告等用户可见输出

## 禁止复制:不在上游私有布局之上建语义层

- 上游配置文件内部字段之上的字段映射表或平行模型
- 上游计划、队列、任务顺序、运行记录等私有格式的副本
- 上游资源文件、数据库内部结构的再解析结果
- 上游源码类名、方法名、私有异常文案、内部状态机
- 取代上游结果面的自造判定信号(对上游执行的任务自行打标记再自行解析)

## 读上游文件的健壮性约定

适配层为枚举、守卫或备份而读取的上游文件(注册表、状态文件、运行记录等),解析层必须响亮失败,禁止静默降级:

- 未知后缀的文件必须显式指定解析格式:`read_file` 按后缀不认得时返回原始字符串,后续字段访问必然出错(#877 根因);
- 上游以非原子方式写盘的文件(进程被杀/断电可能残留 NUL 填充)读取走容错解析(`format=".sanitized.yaml"`),剔除控制字符后按正常内容处理,不视为损坏;
- 「解析失败 / 根节点非映射」属内容损坏:基座入口 `app.utils.io.read_dict_file` 抛带文件路径的 `ConfigCorruptedError`;必备结构完整性(键是否存在、列表非空等)由调用方在返回的映射上自行校验,判为损坏时抛同一异常——再交上层决定拦截或经用户确认后继续;禁止 `read_file(x) or {}` 静默当作空配置——那会把「读不到」伪装成「没有」,污染备份完整性与占用判定;
- 「空值是否算损坏」取决于上游语义,同一空形态在不同上游可能结论相反(如某上游保证实例列表必非空,空即损坏;另一上游允许空列表,空即正常)——须以上游源码或文档为据,不得臆断。

备份池内 MAS 自产文件(如 `_mas_overlay.json`)不在此列:其缺失/损坏由基座按兼容语义处理。

## 时效与存量越界

上游领域能力在上游缺失期由 MAS 实现,不因当时上游没有而转为合规,属历史容忍。上游提供同能力入口后,按存量越界处理,优先级高于「收口隔离」:

1. 改为复用上游入口;
2. 移除适配层实现及其配置项、前端入口与判定逻辑;
3. 不保留两套语义并存。

## 例外:解析上游内部字段的条件

同时满足以下四条方可实施:

1. 有核查证据表明上游无 CLI、无文档化接口、无日志或退出码可用的等效路径;
2. 开发者明确接受该耦合;
3. 解析集中在单一模块,并标注上游变更时的失效表现;
4. 不因解析结果扩展平行模型;可从上游入口获取的数据不再解析。

参考案例:[examples-zzzod.md](./examples-zzzod.md)。

## 分析参考

专项适配任务在需求澄清、方案设计或审查时,可参考上文判据梳理能力归属、上游入口、证据和可选方案。相关内容用于帮助 Agent 分析并向用户提供参考意见,不要求在开工阶段输出固定结论;如提出风险意见,应以可核实事实为依据,无法确认时标注待核实,不得编造。

可选方案包括复用上游入口、由上游补齐能力,或在符合条件时临时补位并明确移除计划。字段齐全、与上游界面一致、实现成本低、上游暂时没有、先实现再调整等理由本身不改变能力归属判定。

存量越界的建议处理优先级:改为复用 > 移除 > 收口隔离;由开发者结合具体上下文决定。

## 自检清单

- [ ] 本次改动消除了用户当前哪一步手工操作?(答不出即不立项)
- [ ] 本次改动实现的是否是脚本该干的活(游戏内操作、任务执行与判定、脚本配置语义)?
- [ ] 是否在上游私有格式之上新建了模型、字段映射表或状态机?
- [ ] 上游执行的任务,成败是否取自上游结果面?
- [ ] 上游当前是否已提供同能力入口(使现有实现成为存量越界)?
- [ ] 若上游能力缺失:是否已评估向上游提 PR?若直接补位,是否属允许情形并标注了临时补位与移除计划?
- [ ] 读取上游文件的代码是否显式指定解析格式、损坏时响亮失败(无 `or {}` 静默降级)?
- [ ] 新增字段是否被运行时消费?
- [ ] 相关方案判断是否有事实依据,风险或替代建议是否准确表达为参考意见?
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall