导入与载荷视图
要点
- 选目录就是导入:项目文件被投影成不可变的载荷,托管在自己的视图上运行;来源目录一个字节不动,导入后可以删除或挪走,MAS 也不会删它。
- 载荷按「谱系 + 版本 + 内容哈希」登记、全局一份;视图是完整的硬链接目录树,路径永不改变。
- 组 = 谱系 + 更新渠道,同组永远挂同一个载荷,没有「钉在某个版本」的概念。换版本就是切视图,升级、降级、迁移统一走同一个
switch_view。 - 投影规则:能确认是外壳才剔,确认不了一律保留;项目自带的
maafw/、python/原样带走。 - 开发者模式与源码形态:私有渠道、运行前按来源重导、不参与项目更新、读不了来源时沿用上次同步的版本。
导入
| 设计 | 为什么 |
|---|---|
有效项目根只从一处取:embedded_project.resolve_maafw_project_root 永远返回视图。新代码不许再自行读 Info.Path | 多处各读各的会让副本与来源混用 |
| 唯一例外:运行前架构自检在副本自带原生库架构不符时,只读地看一眼来源,决定提示「重新导入」还是「换发行包」(#1024) | 给选错架构的用户一条能走通的出路 |
| 视图目录名 = 托管 uuid 去连字符后前 12 位,不进配置、不可手改 | Python 字节码前缀树里项目根会出现两遍,长路径会超过 Windows 的 MAX_PATH |
ensure_embedded_copy:视图不在,或 Info.Path 与导入报告的来源不是同一目录 → 导入一次;来源不在而视图健康 → 什么都不做 | 「来源可删」的承诺 |
视图与来源都没了:从同项目的其他托管或登记过的来源反查,按本托管渠道的最新版重建(_rebuild_from_group) | 同上 |
| 复制之前先校验来源(#1258) | 先复制、后写字段会导致 500 且副本与来源错位 |
| 导入后目录字段锁定、只显示副本路径 | 导入后来源只是记录;换项目请新建托管 |
| 导入进度按投影字节数经 WebSocket 推送 | 大项目导入不能干等 |
导入后按项目决定托管类型(flavor.decide_project_config_class),双向自动、uid 不变 | 类型由项目决定 |
投影
| 规则 | 为什么 |
|---|---|
白名单 = interface 声明的内容(import、resource、控制器附加资源、语言文件、agent / pretask 目录、依赖清单、图标、欢迎信息)+ 剩余不超过 64 MB 的未声明顶层条目(projection.UNDECLARED_KEEP_LIMIT) | MaaEnd 的 data/、locales/,M9A 的 data/activity 都没在 interface 里声明,却是 agent 运行时要读的 |
规则第 2 版:按名字剔除的只剩顶层的界面程序、Qt 运行时与顶层运行期目录(cache/ logs/ temp/ update/ backup/ 等);自带 Python、.NET 托管库、标准布局的原生库目录按内容确认后才剔;任意深度只剔无歧义的缓存与 .pyc/.log/.tmp(#1104、#1117) | 旧规则逐级按目录名剔,误删过某项目 agent 代码里的 battle/runtime/ 与另一项目资源里的 UI/ 图片 |
debug/ 不按名字剔,也不进载荷;导入时从来源的 debug/ 挑出不超过 1 MB 的非日志状态文件,作为视图私有文件(_runtime_state_seed) | 有的项目把会读回的持久状态(账号盐值、时区偏移)放在 debug/ |
项目自带的原生库目录与解释器目录原样带走,分类规则在里面不起作用、只剔 __pycache__ | 有的 agent 要求特定 Python 版本,有的原生 agent 固定从 <项目>/maafw 加载;CPython 自带名叫 build 的子目录,剔了 pip 就坏 |
| 冻结 Python 外壳散在根目录的二进制依赖包不带 | agent 的 PYTHONPATH 是项目根,半截的包会变成命名空间包盖住真正的模块 |
| 不剔任何架构的文件;没有本机能用的那份时,在运行环境日志开头提示(#1102) | 剔了就找不回;提示按当前视图现场计算,换版本不残留 |
检测到混装原生库(maafw/ 与 runtimes/<rid>/native 并存)只提示、不删(#1144) | 清理放到全量更新时按新包判 |
载荷与视图
| 设计 | 为什么 |
|---|---|
载荷 data/mfw/.payloads/<谱系>/<版本>-<hash8>/ + 同名清单,不可变;视图 data/mfw/<12hex>/(#973) | 一次下载、一次落地、一次预检;运行中的托管不受打扰;差量基线不会被 agent 热更新弄脏;复用不会带走运行期状态 |
| 视图是完整的硬链接目录树,不做目录级 junction 拆分 | Windows 没有 overlayfs;data/、config/、python/ 都是出厂文件与运行期写入混放;agent 按工作目录或可执行文件位置解析路径,只有完整的树才看不出区别 |
| 载荷 id 只由版本号与文件内容哈希决定 | 同一棵树必须算出同一个 id |
| 视图路径永不改变 | 环境缓存、隔离 venv、interface 缓存、备份、运行池对账都按路径作键,不用改键 |
视图标记 .auto_mas_view.json 是物化事实的唯一来源,不进指纹,随目录原子换入 | 切换发生在工作线程、配置只在事件循环上改,两者不能互相等;标记先落进新目录才不会出现「新内容 + 旧标记」 |
配置项零新增:谱系、载荷、版本都不进 ScriptConfig.json;唯一新增的配置项是 Embedded.FollowSource | 界面不需要展示这些内部簿记 |
按内容共用
| 设计 | 为什么 |
|---|---|
共用谓词只有一个 projection.is_shared_path:≥ 64 KB、不在 config/ debug/ logs/ temp/ cache/ .pycache/ 下、后缀不是 .lock .sha256 .pth .log .tmp、不在 *.dist-info 里、不在谱系记下的私有路径里 | 运行期会被原地改写的文件都在 64 KB 以下或这些目录里 |
满足的存进 data/maafw_blobs/<ab>/<sha256>,载荷与视图里是 NTFS 硬链接;链接失败退回复制 | 同样的字节只存一份 |
铁律:永远不往已有文件里写(blob_store.place_fresh 独占新建);小文件不入库;链接失败退回复制 | 硬链接没有写时复制,写穿会改坏所有视图 |
| 不用只读属性保护 | 只读属性跨链接共享,会让删除、替换、pip 卸载全部失败 |
每次运行收尾做写穿巡检(view_audit.py):链接数 > 1 且修改时间晚于物化时刻才读哈希;确认写穿就隔离该文件、记为私有路径、把载荷标成损坏(下次更新只要全量包) | 修改时间只作触发、哈希作确认,扫描几乎不花时间 |
谱系与组
| 设计 | 为什么 |
|---|---|
谱系键 = mirrorchyan_rid > github > name(取原文值) | 更新发现本来就以 Mirror 酱资源 id 为入口 |
组 = 谱系 + Update.Channel;每个渠道的最新版只前进、同版本不换 id | 同组永远同一个载荷;两个来源导入同一版本不会来回切 |
| 同版本换 id 只有两个例外:组的最新版自带的 MaaFramework 在本机加载不了而新登记的能加载(#1024);新登记的按更高版本的投影规则建(#1117) | 修复已经装坏的载荷 |
自动更新模式只决定谁去联网发现:运行前更新会推进整组,旧 AfterRun 配置也按运行前执行;「不更新」的托管自己不查,但组推进时照样跟着切 | 没有钉住 |
| 改渠道 = 换组,下次运行前切到新渠道的最新版,允许降级;新渠道还没有版本就留在原版本 | 同一项目要停在两个版本,唯一办法是两个渠道 |
| 本地导入:比组新 → 整组推进;相同或更旧 → 不登记,托管立即用组的当前版本 | 组里容不下领先或落后的成员 |
| 远端渠道回滚不跟随 | 最新版只前进 |
换版本就是切视图
| 设计 | 为什么 |
|---|---|
embedded_project.switch_view:在暂存目录按新载荷重建链接树 → 带上视图私有文件 → 本地改过的受管文件以新版本为准、旧内容留档到 data/maafw_project_state/<视图哈希>/local-modified/ → 标记先写进暂存目录 → 两次目录重命名换入 | 声明式、幂等、方向无关,约 2 秒 |
切换日志在 data/mfw/.switch/,启动时 recover_switches 按盘上状态收尾,没有「重跑切换」 | 崩溃在半途时重跑会把整棵新树误判成本地修改 |
旧视图私有、新载荷也有的路径以载荷为准;例外 contracts.RUNTIME_STATE_FILES(如 M9A 的账号记录)原样带过去 | 否则换版本会把账号记录换回导入那天 |
例外中的例外 contracts.VERSION_BOUND_STATE_FILES(M9A 的热更新缓存)换到另一个载荷时只取新载荷那份 | 缓存与随版本发布的数据表成对,带旧的会让热更新一直跳过 |
自带解释器里的 maafw binding 不当受管文件:以新载荷为准、不留档、不当私有文件带走(_is_maafw_binding_path) | 它是准备环境时钉回的,不是用户改的 |
| 新载荷是旧载荷的超集且共同文件内容相同(投影补齐建出的)时只补缺:视图已有的文件原样保留 | 项目不会因为补齐而重跑热更新 |
| 切换之后无条件接一次运行环境确认;确认成功才在标记里记下「已为这个载荷确认过」 | 否则隔离 venv 的分钟级重建会落进运行中,用户只看到任务卡住 |
复用:同一项目再建一个托管
| 设计 | 为什么 |
|---|---|
| 入口只在新建托管对话框:第一行「选择本地目录」,下面列出已导入的项目,只列与所选类型相同的项目 | 复用是新建阶段的决定;导入后的目录字段只是展示 |
embedded_project.clone_embedded_copy 从源托管挂的载荷物化新视图,不读源视图、不要求源空闲、不带源的运行期状态 | 载荷不可变 |
Info.Path 与导入记录随源一起继承;类型随项目 | 运行前检查靠两者比对决定是否重导 |
| 「复制托管」复用同一个函数 | 一种操作一份实现 |
开发者模式:跟随来源目录
Embedded.FollowSource,默认关(#1294)。给在本地发行包或源码仓里改东西修 bug 的开发者用。
| 行为 | 为什么 |
|---|---|
组换成私有渠道 dev:<视图名>(effective_channel),每次导入都前进;载荷版本带 PEP 440 本地段 +dev | 同项目的其他托管与官方更新碰不到它 |
| 运行前检查按投影白名单算来源签名(路径 + 大小 + 修改时间,≤ 1 MB 的再加内容哈希),变了就重导;内容没变不重建视图 | 避免每次全量复制 |
| 读不了来源(文件被锁、interface 暂时不在、解析失败)时沿用上次同步的版本照常运行,日志写一行醒目警告;只有视图本身不在才按导入失败处理 | 开发者的来源目录经常处在半成品状态 |
| 「立即同步」不看签名、强制重导;运行中、更新中、来源不在都直接拒绝 | 补上修改时间没变而漏掉的改动 |
| 不参与项目更新:自动更新跳过,手动检查与更新被拒 | 以来源目录为准 |
| 离开开发者载荷时不留「本地改过」档 | 那些差异就是从来源同步来的 |
| 关掉开关回到原渠道组的最新版;复制、复用不继承开关,源挂开发者载荷时新托管取原渠道的正式版本 | 开发者载荷不扩散 |
| 开发者载荷不传播到普通渠道 | 同上 |
源码形态
源码仓式的项目:assets/interface.json,agent 写成 "child_exec": "python", "child_args": ["-u", "./../agent/main.py"],根上有 agent/、requirements.txt,没有 python/ 与 maafw/(#1294)。
| 设计 | 为什么 |
|---|---|
视图按发行包的平铺布局建:assets/ 提升到根,agent/、requirements.txt 等原样放根 | 与项目自己打包得到的布局一致 |
interface 不改写:越出项目根的 agent 入口由 interface/agent_entry.py 的 flattened_entry_path 兜底,投影与解释器规划共用 | 一处兜底全对;改写就要在每份载荷里维护一份与来源不同的文件 |
| 只放行有运行时映射的越界(agent 的第一个 Python 入口);其他越界写法导入时就拒绝并说明 | 不让用户导入成功却在运行时报路径越界 |
child_exec: uv 不支持(describe_uv_agent) | uv 按项目自己的锁文件另建环境,maafw 未必与运行用的 MaaFramework 同版本 |
| 源码形态一律处在开发者模式,界面上开关锁在开着 | 没有正式发行渠道 |
| 被 CFA(MFW-PyQt6)源码热更新过的发行包目录走同一个入口兜底,不在导入时改写 interface | 那正是 CFA 自己的解析规则;第一次走 MAS 更新后自然变成发行包写法(#1157) |
迁移与回收
| 设计 | 为什么 |
|---|---|
| 启动期的一次性迁移在后台任务里跑,不挡主定时器 | 挡住主定时器会让按分钟匹配的定时任务被静默跳过 |
| 采纳旧副本时载荷内容以视图自身为准 | 「来源旧、视图新」会登记出残缺载荷 |
| 全部采纳完再统一定同版本的最新版,再把每组统一过去;迁移统一不单独预检 | 结果与托管顺序无关;目标载荷来自本机跑过的健康副本 |
| 回收只在启动期做:删掉无人引用的载荷;一个视图都不剩的项目整个收走;本进程启动之后建的不收;删前在谱系锁内复判 | 有引用就留、无引用就删,不做「保留最近 N 版」 |
| 随后删掉链接数为 1 的共用文件;更新包下载缓存 7 天没用的删掉 | 同上 |
数据备份排除 data/mfw、data/maafw_blobs、data/maafw_update_cache | 都能重建,硬链接按路径读会重复打包 |
限制
- 开发者模式下大于 1 MB 的文件只比大小与修改时间;源码形态会把源码仓里不超过 64 MB 的杂项(测试、文档)一起带进视图。
- 没有界面入口可以「用本地新版本更新现有托管」,只能新建托管导入(比组新会推进整组)。