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/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 {}` 静默降级)?
- [ ] 新增字段是否被运行时消费?
- [ ] 相关方案判断是否有事实依据,风险或替代建议是否准确表达为参考意见?
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 |