Skip to content

refactor(mfw): MFW 迁插件的宿主侧改造(进行中) - #2109

Open
qiyinxi wants to merge 148 commits into
AUTO-MAS-Project:devfrom
qiyinxi:feat/mfw-plugin-migration-20261121
Open

qiyinxi wants to merge 148 commits into
AUTO-MAS-Project:devfrom
qiyinxi:feat/mfw-plugin-migration-20261121

Conversation

@qiyinxi

@qiyinxi qiyinxi commented Nov 22, 2026 •

Copy link
Copy Markdown
Member

摘要

  • MFW、M9A、MSS 不再内置在宿主里,改由插件提供:app/task/MaaFW、app/task/M9A、app/task/MSS 整体删除,相对 dev 净减约 7.2 万行。回退单元是提交 5baecd419。
  • 插件包在另外四个仓库:AUTO-MAS-MaaFW(解析库、原生库识别库、专项共用库三个库,Agent 环境、运行、项目更新三个服务插件)、AUTO-MAS-MaaFW-Adapter、AUTO-MAS-M9A-Adapter、AUTO-MAS-MSS-Adapter。九个包的 0.2.0 已在 PyPI,0.2 起要求宿主带本 PR 的托管生命周期钩子。
  • 升级:存量的 MaaFW、M9A、MSS 托管按类型映射到对应插件,首启自动安装并启用(专项不低于 0.2.0);scripts.yaml、plans.yaml 先备份到 config/legacy-maafw-plugin/。装不上(离线、PyPI 不通)时托管和计划表原样留在盘上,界面只读显示并写明原因,不删数据。
  • 插件 SDK 与宿主补的能力:
    • 安装时连带加载依赖插件、停用和卸载前的预检与连带范围;停用、卸载确认把连带专项名下的托管和计划表列出来。
    • 托管类型暂时没人认领时旁挂保留;插件回来后恢复,原文与新条目在同一次写入里交接,失败或取消都保留原文;类型已登记但单条读不了时只隔离这一条,其余照常加载。
    • 托管生命周期钩子(新建账号、保存、复制、删除)、按配置判定游戏类型与桌面分身、良性跳过。
    • 同族插件一起升级:装一个插件时别的已装插件照旧钉住;确定无解时只放开目标依赖到的同族插件,无关插件不动。存量配置要的专项低于下限时,启动时在导入任何插件之前就升到位;升不上去的这一轮不启用、不接手配置。
  • 内置的 MaaEnd 改成用到时才导入 MFW 的解析库;配置里有 MaaEnd 托管时,宿主启动前把解析库装进插件环境。
  • 顺带的小修复:任务状态查询回传结束时间;等待、获取游戏实例同时写进后端日志;插件环境里有读不了的发行元数据时不再挡住后端启动;单个镜像的 uv 超时换下一个镜像。
  • 文档:docs/maafw-plugin-migration.md(升级、离线、两种起点的回退),docs/mfw-plugins-local-integration.md(本地源码联调)。

测试与验证

  • 自动化测试:CI 上 Windows、Ubuntu 两边 pytest 全过。前端 yarn test 53 个文件 225 条全过,typecheck、lint 没有新增问题。
  • 测试提交:
    • 新增 8 条后端回归(约 540 行)和 1 条前端用例。每条在把被守的代码改坏后都会变红。
      • tests/core/test_config_unresolved_members.py(4 条):插件不在时保存别的托管,旁挂托管的原文、位置和队列引用都在;恢复进行中夹进一次保存,盘上始终是原文或新条目之一;恢复排队时被取消后重启,UID、顺序、引用都在;插件回来但读不进旧原文时这一条留在旁挂区。已提交测试原先只在启动当下比过一次文件,没有覆盖恢复过程。
      • tests/core/test_config_initialization.py(1 条):已升级数据里一条托管读不进来时照常启动、只隔离这一条;同样的数据处在旧格式升级阶段时拒绝推进版本。修复前这种情况整机起不来。
      • tests/core/test_task_tree_dispatch.py(1 条):队列里有托管所属插件不可用时跳过它,其余照常跑。
      • tests/core/test_plugin_startup_upgrade.py(2 条):补装一个专项时同族一起升、无关插件不动;放开后仍无解时什么都不改。修复前这里直接无解。
      • frontend/src/views/plugins/pluginCenterModel.test.ts(1 条):三个专项按托管拦截,停用服务插件时列出连带专项名下的托管和计划表。
    • 「恢复期间写盘失败后重启」没有单独留用例:整文件写失败时盘上本来就不变,这条用例改坏任何一处都不会红,等于假覆盖;重启后数据完好由「排队时取消后重启」守住。
    • 删掉 4 个只测已删内置代码的测试文件(test_maafw_core、test_maafw_reimport、test_maafw_result_progress、test_m9a_nickname)和 test_desktop_session_process_scope 里按 MFW 控制器判定的一例,原件留在插件仓库那边接手。
    • 启动前升到下限、未达标不接手、MaaEnd 解析库、镜像超时这几处另有 16 条离线测试(真实 uv 加本地造的发行包),留在本地没有提交;长期缺口是「运行中插件重新启用后自动恢复」的接线。
  • 环境与提交:Windows 11,Python 3.12.13;提交见本 PR。
  • 未覆盖范围:
    • 已装旧版本插件的升级(启动前升到位、未达标不接手、同族一起升)只做过离线测试,没有在真后端上用真实包复验。同族一起升在更早的一个提交上用真实 PyPI 跑通过一次(0.1.0 → 0.2.0,九个包到位、托管可用、scripts.yaml 字节不变),当时还需要重启一次才生效。
    • 桌面分身(Win32 托管跑在分身里)、M9A 登录流程、MSS 活动期判定、项目更新的应用一步、外壳配置导入,在插件形态下还没实跑;通用 MFW、MSS 还没在模拟器上跑过;手动停止和超时停止没实跑。
    • 前端的只读卡片、删除确认、停用确认里的连带清单、插件中心失败原因只过了单元测试和类型检查,没在界面里看过。
    • 回退说明里「从旧 JSON 升上来」那种起点的步骤按代码写出,没有实机演练。
    • 运行中新建第一个 MaaEnd 托管不会当场补装解析库,要等下次启动。
    • 宿主的「手动更新」任务入口不支持 MFW 一族。这个入口一直只认 BetterGI、MaaEnd、Okww,MFW 内置时也不在其中,不是本 PR 带来的。
    • 已知问题清单在 AUTO-MAS-MaaFW 仓库的 docs/known-issues-0.2.0.md,转正式前清掉。
  • 作者本机真实流程:
    • 用本地源码接入六个插件,三种托管走完新建、导入、预览、新建账号、复制、删除、准备环境;各用空白窗口程序真跑一轮,拉起、连 Win32 控制器、起 agent、任务结束、关游戏都正常。
    • 模拟器真机:M9A 专项经 ADB 在魔改 AVD 测试实例上跑启动游戏、收取荒原、领取奖励、关闭游戏,301 秒全部完成;模拟器由 MAS 无头开机、跑完正常关机,游戏目标占用跑前为空、跑中被占、跑后释放,历史记录带四个日志附件,后端日志没有 ERROR。同一天上午内置实现跑同样四个任务是 356 秒。
    • 从 PyPI 安装:全新运行目录经插件中心装 0.2.0,九个包与 PyPI 上 wheel 的 RECORD 逐个一致;只装三个专项,三个服务插件连带装上;三种托管的新建、导入、预览、新建账号、准备环境、复制、删除全部走通。PyPI 版没有派发过运行。
    • 存量升级演练:拿正式版配置的只读副本升级,备份与原件逐字节相同,托管、账号、队列引用和定时项全部原样;与删内置实现之前的提交对同一副本升级的结果相比,只多出插件配置类自带的 info、custom_webhooks、notify 键。
    • 离线首启:三种托管和 MSS 计划表旁挂保留,scripts.yaml、plans.yaml 连启两次逐字节不变。
    • MaaEnd 解析库:真实 PyPI 镜像、全新运行目录。没有托管时首启对 uv 的调用次数与改动前相同;新建一条 MaaEnd 托管后重启,auto-mas-maafw-interface 0.2.0 被装进插件环境,只装这一个包,插件列表不变;之后再启动、删掉托管后再启动都不再求解。按宿主加载插件环境的方式能读出 MaaEnd 的 interface;没有在宿主进程里派发 MaaEnd 运行来直接证明。
    • 运行在途时去停用 M9A 专项插件:被拒并说明原因,运行没被打断。

没有 MFW 语义,内置 MaaEnd 专项与 main.py 也在用;搬到 app/utils/common 并接入 app.utils 的懒导出,行为不变。
RangeHTTPReader、RangeSpeedGuard 及其异常和小工具搬到 app/utils/common/zip_range.py,与已有的 ZIP 区间重建放在一起;MaaEnd 整包重建改用宿主那份,MFW 项目更新模块改为从宿主导入,行为不变。
- 新增 views/m9a/M9AScriptEdit.vue、M9AUserEdit.vue 与 views/mss/MSSScriptEdit.vue、MSSUserEdit.vue,
  直接用 pageKit 的分节与编排层拼;M9A、MSS 的字段组件挪到对应目录,props 改为显式传入
- 风味描述对象改登记整页(scriptPage.page / userPage.page),去掉插入点组件;文案、受管任务与
  MSS 计划表预取仍由风味提供,第二步再挪进页面
- 脚本页、账号页的页面级样式抽成共用 css;外壳队列导入后的回填挪进用户页编排层,新增
  queuedTaskCount 返回值
- 新增 views/{maafw,m9a,mss}/entry.ts,静态资料从 scriptMetadata 搬入,并带上 MaaFW 家族标记
  (配置类名、默认名、引导标题、是否用项目图标)
- scriptAdapters 拆成普通专项与 MaaFW 家族两组:家族条目不进 SCRIPT_PLUGIN_EDITORS / BINDINGS,
  新增 SCRIPT_ADAPTER_METADATA、MAAFW_FAMILY_ADAPTERS、SCRIPT_BUILTIN_PLANS;plan 可写 createType
- MSSPlanTable.vue 挪到 views/mss,计划表注册表的 MSS 项改为 SCRIPT_BUILTIN_PLANS,仍排在最后
- 新增 core/interface/plan_rules:不可选、失败即结束本轮、失败不计、不回落默认值四张表收成
  MaaFWPlanRules;flavor.plan_rules 从特调读出,建计划与 /maafw/preview 传同一份
- 新增 core/runner/task_selection:inspect_task_snapshot / expand_task_snapshot 交回今日队列、
  被排除的实例及原因、失效任务名与选项值提示;merge_arranged_queue 合回停跑日实例;
  apply_plan_rules / attach_snapshot_findings / describe_plan_failure 取代 runner_task 里
  事后打标记的几个模块级函数
- 预览改用核心 apply_preview_plan_rules,调用处按脚本的特调读规则表传入
- 顺序不变:先剔不可选与停跑日实例,再交给 decorate_selection;行为不变
- 新增 core/runner/plan_transforms:filter_period_once_tasks / record_period_completions
  吃计划、周期名单、已完成记录与当前时刻,返回新计划 / 新记录;周期键按 UTC+4 算
  (period_keys);skip_tasks_completed_this_run 的允许剔除名单改为参数,交回新计划与
  同名多份而全部重跑的任务名
- runner_task 只读配置与特调、调用这些函数,记录变了才自己写回并提交配置
- 跳过原因文案(今日 / 本周 / 本月已正常完成、本轮已安排一次、前面的尝试已完成)收到核心
  一处;行为不变
- 新增 plugins/maafwFamily.ts:家族判断、配置类映射、默认名、标签与图标都从
  MAAFW_FAMILY_ADAPTERS 上的 maafw 标记取;MaaFWFamilyType 由适配条目推出
- router/maafwFlavorRoutes.ts 改名 maafwRoutes.ts,按适配条目生成四条路由,
  路由名、路径、标题不变
- 页面宿主挪到 views/EditView/MaaFW/,改按适配条目的 editors 选页面,
  异步组件按类型与页面缓存,引用稳定
- 编排层不再取风味:脚本页收 type,账号页收 type、managed、queueHintKey、
  prepare,由 M9A、MSS 专属页传入;通用页去掉全部插入点和专项分支
- sectionContracts.ts 拆成脚本页、账号页两份 sectionProps.ts,新建流程的
  props 并入 scriptCreateFlow.ts;新建卡片一律按 createOrder 排序
- 删除风味注册表、defineFlavor、插入点组件、分节替换与三份风味描述对象
把 runner/environment.py 里只看项目目录、认项目自带 MaaFramework 原生库的那一组
函数分到新的核心包 tools/core/native(将来的库 maafw_native):

- project_runtime:原生库目录与候选搜索、取最高版本、读版本、能否在本机加载、
  缺依赖、完整与损坏、架构不符的描述、项目自带 maafw 版本探测;
- pe:PE 架构与导入表解析;
- requirement:项目对 maafw 的版本需求解析;
- versions:normalize_version、parse_maafw_requirement、exact_version_of 与
  MaaFWBindingError(从 runtime_pool/binding.py 移来,binding 反过来导入)、
  requirement 规范化;
- architecture、requirements_file(从 runtime_pool 移来)、offline_dependencies
  (从 tools/core 根移来)、layout(data/mfw、.payloads、.pycache 等目录布局常量,
  从 runtime_pool/host_environment.py 移来)。

给 agent 钉 maafw、拼运行期 pip 约束的函数不属于识别,移到
agent_env/pip_constraint.py;agent_env 不再反向导入 runner。

native 只用标准库、packaging 与本库模块,不导入 runner / agent_env /
runtime_pool / project_update。所有导入点改到新位置,旧位置不留转发。
被搬的私有函数在库里改成公开名(read_runtime_maafw_version 等),
逻辑、文案与返回值不变。
运行池(base venv + binding)的准备、借出与归还原来写在运行的目录里,
现在搬到 agent_env:

- agent_env/runtime_lease.py:borrow_runtime_environment 借出运行环境,
  返回普通数据 MaaFWRuntimeLease(解释器、base venv、binding 版本与
  目录、给 worker 的环境变量、租约标识);return_runtime_environment 按
  标识归还;describe_runner_runtime_selection、BASE_RUNTIME_PACKAGES
  一并迁来。
- agent_env/project_env.py:prepare_project_environment(借一次环境、
  备 agent、记项目输入指纹)与 project_environment_fingerprint,从
  MaaFWRunnerService 移出;宿主两处调用点直接调它。
- runner/environment.py 只剩向 agent 环境借还的 prepare_runner_environment
  / release_runner_environment,以及拼 worker PYTHONPATH 的
  build_runner_environment。
- agent pip 约束目录 AUTO_MAS_MAAFW_AGENT_CONSTRAINT_DIR 改由借运行环境的
  返回值带进 worker 环境,runner_task 不再自己拼。

下发给 worker 的环境变量、日志与进度文案不变;新旧实现对拍 289 项一致。
- DETAIL_LOG_PREFIX 定义移到 log_redact;agent_env、project_update 与宿主
  调用点从那里取,不再借 worker_protocol(worker_protocol 照旧对外提供)。
- pool_reconcile 只收普通数据:运行池对账、更新后豁免旧版本,以及新的
  reconcile_agent_venvs(隔离 venv 的回收,原在 maintenance 里)。读脚本
  配置与项目副本算存活集合、起后台对账的部分移到项目更新一侧的
  live_projects;maintenance 改调这两处。
- env_cache 自留一份项目路径规范化,不再导入 project_path。

日志文案与 logger 名不变;对拍覆盖的隔离 venv 回收、缓存键结果一致。
更新预检原来在 precheck 里直接建运行环境、做 agent 导入检查、把临时
agent 目录建在运行池根下再删。新的 env_trial 接缝承担这部分:
trial_environment 放置并在结束时回收预检根下本次专用的子目录,
TrialEnvironment.prepare_and_check 真建一次环境(不写环境缓存)再查
导入。precheck 只剩原生库加载检查、失败分类与备忘。

失败原因与备忘仍在删目录之前写完,顺序与原来一致;预检对拍(成功、
失败、取消、缺模块)结果一致。AGENTS.md 同步积木之间的依赖方向、运行
环境借还与接缝归属的说明。
建计划(run_plan、pipeline_override、hotkey、runner/models、task_selection、
plan_transforms、interface/plan_rules)归解析一侧,导入闭包里不再有 agent 环境、
运行池和 runner 的执行侧。

- agent 命令计划的数据模型移到 interface/agent_command,agent_env 与 runner 都从这里取;
  path_without_host_venv 移到 interface/host_path。
- 建出的计划 agents 为空,interface 声明的 agent 放在 declaredAgents(不随 job 下发);
  child_exec 越出项目目录仍在建计划时报,话不变。
- 借运行环境时 borrow_runtime_environment 按声明算出 agent_plans,
  runner/environment.worker_run_plan 填进下发给 worker 的计划,同一账号这一轮的重试沿用第一次的。
- runner/__init__ 改成惰性导出;build_plan 去掉只给 agent 规划用的 managed_env_root。
runner_task 里把模拟器或窗口信息换算成设备配置的那一组方法搬到
tools/embedded/device_config.py,改成参数是模拟器 uid、配置原值与
interface 控制器模型的函数,任务类只取配置、管缓存、在中间调登录与
游戏更新钩子:

- ADB:游戏包名、adb 路径、问 Toolkit 的判据(ask_toolkit 由调用方算
  好传入)、MuMu / 雷电 / ModAVD 控制档案、截图与输入方式位掩码、adb
  就绪超时。实例上的 _cached_adb_* 换成调用方持有的
  MaaFWAdbDeviceState,关模拟器时清地址与档案,adb 路径照旧不清。
- MuMu、雷电的额外配置收成与 SDK maafw_adb_extra 同形的
  mumu_maafw_adb_extra / ldplayer_maafw_adb_extra,方便以后交给各自的
  模拟器适配插件。
- Win32:窗口句柄与截图、鼠标、键盘方式的选择;窗口规则匹配仍在
  tools/core/controller_win32。
- 首任务下发闸门:最早下发时刻与 disk_quiet / screen 判据收成
  task_start_gate,开模拟器处只记拉起时刻,起 worker 处调它。

ModAVD 的 MaaFramework 版本门槛留在起 worker 之前原来的位置。设备
配置、日志、下发给 worker 的字段都不变。
用户 2026-11-21 定:托管类型在新建时就定了,之后导入什么项目都不变。

- 删掉导入、重新导入、克隆之后按项目换类型(_apply_project_flavor)与
  「已按项目识别为 …」系统通知,连同只为它服务的 decide_project_config_class、
  user_config_type_transform、retype_notice_lines 钩子(含 M9A 的实现)与谱系里
  没人读的 configClass 簿记
- 启动期 M9A 迁移去掉「通用托管跑着 M9A 项目就换成 M9A」那一步;旧版 M9A
  配置迁移、迁移损失补救、受管任务整理不动
- M9A / MSS 托管导入、重新导入、克隆别的项目时,在动副本之前按该特调的
  matches_project 判,不认就直接拒绝并给出原因;通用托管什么项目都收
- flavor_for_project 只留给没有脚本时的预览选规则表
- 三份 AGENTS.md 改成现在的规则;重导测试按新行为改(导入后仍是通用类型,
  去掉换类型窗口的取消用例)
托管类型不随导入变了,导入后不再重新拉类型,页面宿主选定页面后不再换:

- 删掉导入成功后的 refreshScriptType 与宿主里跟着类型就地换页面的逻辑,
  宿主交给页面的 scriptType 改为只读初值
- 引导步骤收回引导自身,不再为换页面后接着走而放在宿主里
- 类型后缀写错的旧链接照旧纠正到对应页面;M9A / MSS 托管选了别的项目时,
  后端的拒绝原因照常显示在目录字段下(沿用导入失败的显示)
把任务类里「把一份计划在一台设备上跑完」的那一段原样搬进
tools/embedded/plan_run.py:整轮硬杀兜底、借还运行环境、生成 job、
事件通道与 stdout 退回、起 worker(普通子进程与桌面分身)、喂 job、
读 stdout / stderr、处理 worker 事件、三份日志的增量复制与打码、
原生报错行摘取、附件收集、强杀前的进程树清理、ModAVD 的
MaaFramework 版本门槛。

入参 MaaFWPlanRunRequest 全是普通数据,不收脚本配置、账号配置或
任务类实例;两组打码值由调用方算好传入。过程中的输出只经一个同步
事件出口(账号日志、进度点、结构化运行记录事件、宿主阶段起止),
结果、附件清单、原生报错行经返回值拿,运行抛异常时同样的东西留在
运行对象上。按任务的截止时刻 task_deadlines 在下发 job 前一刻换算
成秒,过期抛 MaaFWTaskDeadlineExpired。停止经 MaaFWPlanRun.stop()。

运行记录的宿主阶段起止改为公开的 mark_stage,供事件出口转交。
这一提交只新增实现,任务类下一提交改为调用。
MaaFWPluginAutoProxyTask._run_maafw 现在只做:取配置 → 组装
MaaFWPlanRunRequest → 调 MaaFWPlanRun → 把事件转成账号日志、进度点
(仍以任务类为 owner 调 run_flow.point)、运行记录 → 处理返回值。
原来的 _run_maafw_worker、_wait_worker_exit、_note_native_error、
_check_avd_runtime_version 与那一串模块级辅助函数随实现搬走;
runner_process / _stdout_native_errors 换成 _plan_run,停止任务时
_terminate_runner_process 经 MaaFWPlanRun.stop() 结束 worker。

两组打码值由任务类按原算法先算好传入:本次运行的是
collect_run_password_values 的写法,项目日志的再并上整个托管全部
账号的密码。只和 M9A 有关的「登录交给首任务完成」不再进 plan_run:
调用前把首任务标成 abortRoundMessage、登录截止时刻放进
task_deadlines(仍在下发 job 前一刻换算),截止已过时换成原来的
「登录时限已耗尽」;首任务完成后才记已登录,按返回的结果做。

用说同样协议的假 worker 对拍了旧方法与新实现(正常完成、任务失败、
单任务超时、原地打转、中途崩溃、不退出硬杀、结果后不退出、事件通道
退回 stdout、停止、取消、登录首任务、登录时限耗尽、冷启动闸门、
ModAVD 门槛):账号日志、进度点、结果、历史附件内容、job、打码都一致;
差别只有整轮超时异常改了类名,以及「计划缺少公开启动任务」这一
防御性检查提前到借运行环境之前。AGENTS.md 同步 plan_run 的边界。
运行前设置(interface pretask)的执行、重跑判定、输出泵、进程树快照与结束、
失败原因文案从任务类搬到 tools/embedded/pretask_run.py。入参是普通数据
(计划里的 pretask、工作目录、时限原值、PI_* 与 ModAVD adb 端口两层进程环境、
打码写法、桌面分身目标),输出走 plan_run 同一种事件出口,失败抛
MaaFWPretaskError。解码、去色、进程树快照结束与单行上限从 plan_run 拿,只留一份。

MaaFWPretaskRunner 一个账号一份、跨尝试共用,停止与清理状态照旧跨尝试保留;
has_live_process 回答还有没有没确认退出的进程,exit_confirmation 记下此刻要等的
清理与进程。任务类释放项目预约前照旧要等它确认退出。

MaaFWPlanRunLog 加 warning 字段(默认假),任务类按它写账号日志级别;plan_run
自己的日志都不带它,行为不变。
- 按 interface 认出密码字段、从任务快照普通数据里收集要打码的值,挪到解析一侧
  tools/core/interface/password_values(只依赖 interface,密文经调用方给的 opener 认读);
  加解密与从配置里取快照原值留在宿主 option_secrets(DPAPI_SECRET_OPENER、
  user_task_snapshot、script_task_snapshots);写法与按值打码挪到运行一侧 run_redaction。
  任务类取快照原值交给收集函数,得到两组值再传给 plan_run / pretask_run,算法与收集范围不变。
- 主循环里「信号 / 要更新游戏 / 成功 / 失败,重不重试、先不先修资源、重不重启客户端、
  补不补『运行环境不可用』、尝试级类别」的判断收成 run_verdict.judge_attempt,吃运行结果
  或异常、返回普通数据;环境级失败标记、宿主自己抛的两个异常类也挪过去。循环结构、次数、
  日志与通知不变。
- AGENTS.md 写清跑计划、运行前设置、结果判定、密码三件事的位置与入参出参,以及任务类还剩什么。
托管类型已在新建时定死、导入不再换类型:api_service 包说明、M9A 受管任务与迁移注释、
scheduled-script-updates.md 里「导入后的特调类型转换」两句随之改写;precheck 的
_resolve_requirement 注释改指原生库识别库;AGENTS.md 里直连速度保护写明类在
app.utils.common.zip_range(range_delta 转出)。只改文字。
脚本级的「打开项目 / 收尾项目 / 预下载」从 MaaFWEmbeddedManager 搬到
tools/embedded/project_session.py(项目更新一侧),以后三个专项都调同一套:

- 打开项目:reserve 拿视图预约(拿不到返回良性跳过的结局:正在切换版本、
  正在更新、被占用),prepare 补视图(导入、组同步、投影补齐、读环境确认
  标记),结局是 opened / failed / stopped,打开成功带租约;hold 等管理器在
  预约里的那一段,停止时的宽限与「交给任务完成回调释放」照旧;release 交回。
- 运行前更新(含更新预检、预下载候选的身份核对)、运行环境确认、收尾
  (组同步、写穿巡检、原生日志备份清理)、预下载的发现 / 下载 / 撤销资格。
- 入参是普通数据 MaaFWProjectRequest,管理器每次现取配置组装;新实现不写
  配置,导入报告等要写回的项目记录与要弹的通知都作为返回值交回,由管理器
  照原来的时机写回、发出。过程输出经一个窄的事件出口(日志行、进度点、
  预下载字节进度)。

管理器里原来的方法只剩取配置、组装入参、调用、把事件转成日志、处理结局
与写回。用户看到的日志、写回的字段与次数、预约的释放与原来一致。
pretask_run 的 has_live_process 没有任何调用方,项目预约的释放只等
exit_confirmation,连同模块说明与 AGENTS 里的两处提法一起去掉。

AGENTS 补一句:接缝里归 runner 的 plan_run、pretask_run、run_verdict、
run_redaction 不导入项目更新一侧的接缝与专项;run_verdict 为认登录失败
导入 flavor.MaaFWLoginRequired 是临时例外,删风味时去掉。
项目更新一侧新增属主登记表(tools/embedded/owners.py):只记「属主名 → 取入口的办法」,每次用前现取,
入口的调用只传普通数据(列出名下托管、读单个托管、校验来源路径、写回项目记录、导入期间加解锁)。
属主的回答只在托管完整加载之后才算数(宿主注入的信号 + 各属主自己的 ready)。

内置属主入口 BuiltinConfigOwner 按确切类型认托管,类型每次现取。通用 MFW、M9A、MSS 各有自己的
registration.py:运行、配置回调、恢复池与属主分别登记,不再靠 M9AConfig / MSSConfig 继承
MaaFWConfig 挂到通用 MFW 的登记上。宿主的漏登校验、配置回调查找、恢复池查找都改成按确切类型,
子类不会落到父类的登记上。

删托管时的视图清理改由三种类型的配置回调各自声明(带属主名),视图上记着别的属主时不删;
builtin_registration 不再给所有类型挂视图清理。视图标记新增 owner 一项(读写函数,换版本时带过去)。
桌面分身判定、M9A 迁移后的归档、特调类型枚举也不再按继承判断。
启动期维护与运行期的运行池对账不再按配置类收集「MFW 家族的托管」,改问已登记的属主:
托管配置完整加载、且每个属主都答上来时才据此判断「不在了」,否则整轮跳过。

- 视图只在「标记里记着属主、属主已登记且名下没有这个托管」时才删;没有属主标记、属主没登记、
  记录对不上目录名的视图留着。迁移之后、清副本之前给属主确认仍在的视图补上属主标记。
- 应保留的视图 = 属主确认仍在的 + 判定不了的,交给 agent 环境(隔离 venv)与运行池对账。
  agent 环境对账挪到清副本之后(先清副本、再交给 agent 环境)。
- 有视图记着这轮没答上来的属主时不回收载荷;有不归任何属主的未采纳老副本时保留旧更新状态的基线。
- 宿主把「托管配置完整加载」注入属主登记表作为信号;维护服务不再接收托管快照。

行为上只多了一类「以前删、现在不删」:没有属主标记的孤儿视图不再被清理。
端点认托管的规则从「是 MaaFWConfig 或它的子类」改成「属主已登记的托管」:common.maafw_managed
经属主登记表找到托管,交回只读形状(Info / Update / Embedded 原值,is_locked 每次读都经属主现问),
认不出、uid 不合法、没有这个托管时的异常与文案与原先一字不差。

- 写回一律经属主:导入(持票写回与加解锁)、立即同步、克隆、补建视图后的导入记录;克隆跨属主时
  读源托管、写目标托管分别经两边的属主,写回前再经源的属主读一次源记录。
- 来源路径校验交给属主按自己的校验器判。
- 同组候选、同来源重建的候选、可复用来源列表都从属主快照取,按宿主托管列表的顺序。
- 管理器打开项目后的项目记录写回改经属主;自检「是不是 MFW 托管」按确切类型比。
- 外壳配置导入(通用 MFW 自己的端点)经属主确认后按确切类型取配置对象。

接口的路径、入参、返回与报错文案不变。
MaaFW 的 AGENTS 新增「托管属主登记」一节:登记与现取、入口只传普通数据、回答只在托管完整加载
之后算数、视图上的属主标记、删一个视图之前要过的判断与应保留的集合、以后新增专项要登记什么;
维护入口、agent 环境回收与载荷回收的说法同步改。M9A、MSS 的 AGENTS 改写成按确切类型各自登记,
不再说「isinstance(…, MaaFWConfig) 天然覆盖」。
- owners.snapshot(require_ready=True) 在登记表为空时返回 None,据此判断「不在了」
  的清理整轮跳过;以前返回空快照,运行池的应保留集合会少掉只有来源目录的托管,
  载荷回收会拿着空的存活来源去跑。
- live_projects.reconcile_in_background 在调用方线程上算存活集合,调用方(删除托管
  的回调、端点)都不兜异常:属主回答是坏数据、列 data/mfw 报 OSError 时只记一句
  warning、这一轮跳过,不再让删除托管跳过后面的数据目录清理、让接口报错。
scripts/dev/link_mfw_plugins.ps1 从联调分支搬来:在 plugins\ 下给三块服务插件和三个专项建目录联接,并写一份 uv.toml 让宿主解析插件依赖时能从本地 wheel 目录找到库(只有 UV_CONFIG_FILE 里的 find-links 会和宿主命令行自带的合并)。按本分支改了三处:库多了专项共用库 auto-mas-maafw-adapter-kit,wheel 检查和 -RefreshLibraries 清缓存都带上它;不再写死本机的 uv 路径和端口,取 AUTO_MAS_UV_EXE 或 PATH 上的 uv;说明里「没装插件时托管按内置类型保留」改成旁挂保留。
新增 docs/mfw-plugins-local-integration.md,按 2026-11-22 在本分支实际跑通的步骤写:本地打三块库的 wheel、用 link_mfw_plugins.ps1 接入、起干净后端、比文件确认装的是本地库而不是 PyPI 上同版本号的那份、启用、三种托管的主路径接口与结果、用自编空白窗口程序各真跑一轮(MAS 启动游戏用托管的 Game.Arguments,游戏目标的启动参数不读)、拿存量配置副本演练升级并与删内置实现之前的提交对比。maafw-plugin-migration.md 的「开发辅助」加一句指向它。
@github-actions github-actions Bot added 专项: MaaFW 类型: 变更 按更新日志碎片自动设置 labels Nov 22, 2026

Copy link
Copy Markdown
Contributor

总体结论:修改后合并(当前先不合)

11a4ccf 已经把内置 MFW、M9A、MSS 撤下,启动时按旧配置找插件。托管和计划页也补了「所属插件不可用」的卡片,停用弹窗现在能接住后端的计划表影响。上轮这两处界面缺口可以划掉;但真切换前,dot酱还想守住下面几条旧用户路径。

  1. [P1] 只用 MaaEnd 的用户,升级后可能连「MaaEnd 启动」都用不了。 启动入口 不管有没有开分辨率调整,都会走解析外部库;而自动补插件的索引 没有 MaaEnd,主程序也没声明这个解析包。马上的后果不是少一个设置,而是缺库时游戏还没启动就报错。请让内置 MaaEnd 自己声明并拿到解析依赖,或暂时保留宿主解析入口;别让只用 MaaEnd 的人手动装一整个 MFW 托管插件。三个适配器和解析包的公开 PyPI 项目页目前也未查到;本地链接联调不等于普通升级能安装。

  2. [P1] 旧配置恢复仍须等新记录安全接手,再移掉原件。 自动恢复 还是先从保留区移除原文,再等提交。在别的保存夹进来或恢复途中取消时,旧记录仍可能漏写;冷启动 也还是只隔离未注册类型,已注册但一条配置读坏会拖住整个集合。现在三个已切换的专项都会经过这条路径,更值得先修:把原文和新记录的交接放进同一个可回滚写入边界;已升级用户只隔离坏的那条,健康记录照常起来,旧格式的严格升级门槛保留。现有隔离落盘测试可直接加上取消/写盘失败后重启,确认 UID、顺序和计划引用仍在。

  3. [P2] 停用确认能数计划了,但仍认不出新切过来的三个插件。 插件中心绑定表 仍把它们当内置排除,弹窗因此跳过对应的托管和计划表,可后端会一并移除实际配置。请把三个插件补进生命周期统计绑定,不必重排编辑路由;让停用、卸载以及连带停用用同一份真实影响清单。

另外,回退说明 需要区分两种起点:原本就是 v2.2 的可以还原 YAML;从旧 JSON 升上来的,仅拷回 JSON 不会让已标成 v2.2 的旧宿主重新读它。请为后者指向升级前的整套备份,并明确配置文件和数据库版本要一起还原。

先给旧配置留好退路的 dot酱

Copy link
Copy Markdown
Contributor

总体结论:修改后合并(补正发布证据)

11a4ccf 上条查 PyPI 页面没拿到结果,不能据此说没发版。后来核到了 项目更新包 和三个适配器(MFW、M9A、MSS)的 0.1.0 上传成功记录。我要拦的不是「有没有包」,而是升级会不会拿到带修复的那版包。

宿主撤掉内置维护后,外置插件启动时会清项目副本。已发的 0.1.0 先删判作无引用的副本,才检查有没有属主没报到;这会让宿主上轮修过的清理顺序在切换后退回去。外置新源码 已把检查移到前面,但对应记录是构建和校验,不是发布。请先发带修复的包,再把切换依赖的最低版本一并抬上去;验收用正常用户会装到的包,别只用本地连源码。

把发过的包和修好的包对齐的 dot酱

托管页与计划表页各自的不可用卡片删除逻辑收进 UnavailableScriptCards、UnavailablePlanCards,页面只剩一个 v-model 标签;计划表不可用条目的投影移到 planList.ts 的 projectUnavailablePlans。另把托管页空状态连同样式拆成 ScriptsEmptyState,计划表页的 buildNestedObject 挪进 usePlanFieldSave.ts,两个页面回到组件尺寸门禁的基线行数以内,界面行为不变。

Copy link
Copy Markdown
Contributor

总体结论:修改后合并(当前先不合)

2bafa7b 这两笔把不可用托管和计划表的卡片拆回各自页面,删除成功才移除卡片;拿到或等候游戏实例的状态也写进了后端日志。我沿着卡片到删除接口对了一遍,未看到这次拆分改变原来的增删语义。

[P3] 查到已结束任务后,请用同一个 ID 去取结束时间。 状态接口接收的是字符串;任务查询 先把 UUID 转成标准格式,所以大写等合法写法也能找到任务。但新加的 finishedAt 再用请求原文查一次,大写的同一个 ID 会显示任务已结束却拿不到时间。建议复用第一次取到的终态缓存项,或统一用标准化的 UUID 键。

上轮的 MaaEnd 依赖、旧配置恢复和停用影响 这两笔没碰;外置更新包的清理顺序 也仍要以实际发出的版本验收。新卡片可以继续联调,但还不能把宿主切换当作就绪。

帮任务把结束时间记准的 dot酱

Copy link
Copy Markdown
Contributor

总体结论:仍是修改后合并,外置清理修复已发布

补一下上轮的发版判断:现在已核到项目更新包 0.2.0 和实际发布记录。这个发行版里,有属主没报到就先返回,不再先删判为孤儿的项目副本。修好的包已经能从公开渠道拿到,这条不再卡发布。

还要防宿主继续用旧包:自动接手逻辑 没给 MaaFW、M9A、MSS 三个适配器设最低版本,已装且记录正常的 0.1.0 可以跳过重装。建议把这三项接手的最低版本提到 0.2.0,分别核验从未装过和已经装了 0.1.0 的两种升级,确认实际加载的是修好的版本。上轮宿主自身的阻断不变。

确认升级确实拿到新包的 dot酱

装或升一个插件包时先照旧把别的已装插件钉在当前版本求解,能解就不变;确定无解(或部分镜像无解、其余镜像没结论)时,才放开目标包依赖闭包里出现的已装插件(目标单独求解一次读结果)以及直接依赖了目标或已放开包的已装插件,反复到不再增加,写成 >=当前版本再解一次,范围以外的插件照旧 ==当前版本。被连带升级的插件只要已加载,安装就保留候选、等重启,不热发布;它们的版本由安装后的发现流程和目标一起刷新,升级清单写进安装记录的 co_upgraded、安装进度的提示和日志。主程序升级补装同族插件时,若等待重启的安装已把它升到满足下限的版本,直接按需重启返回,不再当成另一轮安装拒掉。另外部分镜像判定无解、其余镜像没给出结论时不再提示检查网络,改说部分镜像判定无法同时满足并列出涉及的包。
存量配置补装 maafw_adapter、m9a_adapter、mss_adapter 时带上 0.2.0 的版本下限:0.2 起专项要求宿主带托管生命周期钩子,0.1.x 在本宿主上不是受支持的组合。不带下限时首个镜像还没同步新版本就会装成 0.1.0 全家;带了下限后镜像缺版本按无解处理并换下一个镜像,已装 0.1.0 的会发起升级,由同族一起升级把服务插件和兄弟专项一并升上去。

Copy link
Copy Markdown
Contributor

总体结论:修改后合并(当前先不合)

6eef2ef 给三个适配器都补了 0.2.0 的最低版本。同族库不能单独升时,也有了一起解依赖的路径。上轮「没有版本下限」这条可以划掉;dot酱还想拦一下从 0.1.0 升级的第一轮启动。

[P1] 新包还在等重启时,别让本轮的旧包接手配置。 启动会先加载、启用现有插件;如果升级要更换正在用的依赖,新环境只会放到待重启目录。这时安装会返回需要重启,但配置升级接着用当前登记:旧 0.1.0 已启用就被当成升级成功,未启用的旧版还可能在这一步被启用。同族包已经一起准备好、仍在等重启时也是一样。旧类因此仍可能接手并写回配置;如果旧版项目更新服务已启用,首启也不能保证用上 0.2.0 的清理保护。

建议把迁移需要的版本放到首次导入前求解;若确实要等重启,就明确停在「待生效」,不要让没达标的类接手或写盘,下一轮确认实际加载版本后再继续。验收重点是已装 0.1.0 且依赖在用,不只是干净环境能装上。

等新包真接班再放行的 dot酱

插件中心的绑定表一直把 MFW、M9A、MSS 当内置排除,用量统计对不上它们的托管和 MSS 计划表:直接停用时只按后端影响范围确认,服务插件连带停用时也列不出这三个专项名下的托管,可后端会一并删掉。现在三者进入绑定表,口径与 MAA 一致,编辑页路由照旧走 MFW 自己的四条。连带范围的统计挪进模型,停用按 disableCascade、卸载按 uninstallCascade 取同一份清单,卸载确认也列出会一并删除的托管和计划表。
状态接口按字符串收 taskId,查任务时先转成标准 UUID,所以大写等合法写法也能查到已结束的任务;但 finishedAt 又用请求原文去取终态缓存,同一个任务会显示已结束却没有结束时间。改成与查任务相同的标准 UUID 键。
宿主按 data/data.db 里记的数据版本决定读 YAML 还是从 JSON 转换,升级成功后都是 v2.2。原本就是 v2.2 的用户拷回 legacy-maafw-plugin 下的 YAML 即可;从旧 JSON 升上来的,只拷回 JSON 不会被旧宿主重新读取,改为指向升级前的整套备份 legacy-json/pre-upgrade,写明配置文件和数据库版本一起还原、并删掉这次升级生成的迁移记录和 YAML。
存量配置里有带版本下限的专项托管(MFW 一族要 0.2.0)而已装版本低于下限时,启动前的共享环境准备在任何插件模块导入前带上下限求解:先只把这些包写成 >=下限、别的插件照旧钉住;无解时照安装时的同族放开办法,把目标依赖闭包里和直接依赖它们的已装插件改成 >=当前版本再解一次,其余插件不动。所需专项沿用 required_adapter_plugins,下限沿用 _MINIMUM_ADAPTER_VERSIONS。以前环境指纹没变就直接跳过,现在已装版本低于下限不会被指纹短路;求解、下载出错或无解只记警告,按现有版本继续启动,不挡后端起来。这样已装 0.1.0 全家的环境首启就直接跑 0.2.0,不再先留一份等重启的候选。
启动前没能升到下限(离线、镜像没同步、无解)时,插件管理器这一轮不启用存量配置要求下限而已加载版本仍低于下限的专项,连同只为它们提供服务的上游插件(启用意图里的下游全在名单内才留下,别的插件还在用的服务照常启用),启用意图保留,下次启动达标后照常接手。这样旧版本的类不会接手托管、写回配置,旧版服务插件也不会在启动时跑维护。补装入口对这类专项不再把等待重启的安装当成升级成功、也不再去启用它:安装要等重启时报「新版本已准备好,重启后生效」,安装失败时报「插件版本过低,升级没有完成」带上原因,托管走所属插件不可用的旁挂路径;游戏插件没有旁挂区,仍按原样启用。确认安装时跳过这一轮有意不启用的插件,免得把无关安装判成失败回滚。旁挂托管的 detail 用该专项没启用的原因补上;启动提示在只差重启时写「部分专项插件重启后生效」,确实不可用时才写「部分托管所属插件不可用」。
插件回来后还原旁挂托管,原先先把原文移出保留区,再去排队提交新条目;排队期间夹进来的保存会写出一份两边都没有的配置,还原中途被取消时原文也不再放回。现在每条还原连同回到原位的顺序调整放进一笔根事务,原文一直留在保留区,直到这笔事务提交时才在同一刻移出;失败、取消都整笔回滚,原文留在原位,下次插件可用时再试。
已升级的配置里,类型已登记但某一条读不进来(校验不过、插件配置类抛错)时,原先整个托管或计划集合激活失败,下次启动整机起不来。现在只把这一条放进保留区并记下原因,其余照常加载,原文照旧原样落盘,队列和计划对它的引用都留着;启动提示、托管下拉和不可用卡片按「配置读不了」显示。旧格式升级阶段照旧不放行:有读不了的配置就拒绝推进数据版本,报错里写明是哪一条。逐层提交包出来的多层聚合错误,摘要只留最里面的原因。
内置 MaaEnd 拼游戏启动设置要用 MFW 的 interface 解析库,它只在装了 MFW 插件时才随依赖进插件环境,只用 MaaEnd 的人升级后由 MaaEnd 启动游戏会直接报错。现在配置的托管索引里有 MaaEndConfig 时,启动前的共享环境准备把 auto-mas-maafw-interface>=0.2.0 作为求解目标一起装进插件环境;它不是插件,不进注册表、不参与启用停用,只写下限,装了 MFW 一族时由那一族的范围定版本。哪种内置托管要哪个库写成和专项插件表并排的一张小表。已装且满足时钉在现版本,不为它触发求解;后来删光了 MaaEnd 托管也不为此求解,库留着。装不上(离线、镜像不通、无解)只记警告,退回不带它的原有流程照常启动;MaaEnd 用到时的报错改为说明解析库还没装上、联网后重启会自动安装。运行期新建第一个 MaaEnd 托管时不补装,等下次启动。

Copy link
Copy Markdown
Contributor

总体结论:修改后合并(当前先不合)

3f70a2a 这批有几条可以划掉。dot酱最想先记下旧配置终于不用提前交出原件了。

本轮没动两条仍会拦切换的路径:升级等重启时旧插件仍可能接手,以及只用内置 MaaEnd 时缺解析依赖。修好后再用实际发行包过一遍旧安装升级,不必用新的源码联调替代它。

看见原配置被稳稳接住的 dot酱

联合求解逐个镜像跑 uv pip compile / install,超时由进程工具重新抛出 TimeoutError,镜像循环没有接住,整次安装直接失败、错误原因为空,也不会去试下一个镜像(实测一个镜像卡满 600 秒后失败,立刻重试 36 秒成功)。现在单个镜像超时按「这个镜像没给出结论」处理,记一条警告后换下一个;安装一步超时时清掉装到一半的候选文件再换镜像;全部镜像都没给出结论时,提示里写明哪些镜像响应超时。单次 600 秒的上限不变:安装一步要下载较大的原生库,压短容易在慢网络上误判,而卡住的镜像现在只耽误它自己那一段。
托管所属插件不可用时原样保留、插件回来后还原这条链路,此前的回归测试只留在本地,这次按仓库测试规范挑出会丢配置或让整机起不来的几处随 PR 提交。新增 tests/core/test_config_unresolved_members.py,在隔离的配置文件上走真实集合激活、事务与落盘:插件不在时改别的托管再保存,旁挂托管的原文、位置和队列引用都留着;还原途中夹进来的保存、排队等待时被取消、新插件读不进旧原文,三种情况下盘上始终是完整的原文或还原后的条目,取消后重启 uid、顺序和引用都在。test_config_initialization 加一例真实启动链:已升级数据里一条托管值读不进来时照常启动、只隔离这一条、原文与队列引用不动;同样的数据处在旧格式升级阶段时拒绝推进数据版本并点名那一条。test_task_tree_dispatch 加一例:队列里有一项托管所属插件不可用时跳过它,同队列其余托管照常跑。改坏验证:撤回原子交接、撤回单条隔离、落盘不并回旁挂成员、引用回落默认值、还原失败的那条直接丢掉、升级阶段放过读不了的单条、队列不跳过旁挂托管,对应用例各自变红。
test_plugin_startup_upgrade 沿用本文件的离线 wheel 与真实 uv 求解,加两例同族升级:已装 0.1 全家(专项写了服务插件的次版本上限)、服务插件已加载时补装专项 0.2,服务插件与兄弟专项一起升到 0.2、在候选环境里等重启生效,无关插件不跟着升;同一轮接着补装已被一起升过的兄弟专项按需重启返回,不撞「等待重启」,下限更高时仍要先重启。另一例有个同族专项没出新版本、放开后仍无解时,报依赖冲突而不是网络问题,已装环境、安装记录和插件登记都不动。改坏验证:无解时不放开同族、放开全部已装插件、兄弟专项补装不认已一起升级的版本、放开后仍无解就只装目标,对应用例各自变红。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

专项: MaaFW 类型: 变更 按更新日志碎片自动设置

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants