为什么敢把整套功能塞进一个仓库:Erosion-CN 目录结构解剖
为什么敢把整套功能塞进一个仓库:Erosion-CN 目录结构解剖
在中文技术社区检索「Erosion-CN」,返回结果大概率是 Minecraft 的群系侵蚀参数、OpenCV 的形态学腐蚀操作,或者水土保持模型里的 RWEQ 侵蚀因子——名字撞车的噪声远多于对这个项目本身的讨论。但只要打开仓库,你会看到一个反差极强的现实:一个只有单一 Xcode target、外部依赖屈指可数、project.pbxproj 仅 434 行的 iOS 工程,里面塞进了 MobileGestalt 缓存改写、文件系统沙盒穿透、应用容器备份还原、状态栏与运营商定制、壁纸与拨号盘替换、缓存清理等整整一套系统级工具链,Swift / Objective-C / C 源码约 1.05 万行。
这不是随手堆出来的杂物间。它敢「全塞一个仓」,是因为在目录层做了三件事:把能力收敛成底座、把写入协议收敛成唯一通道、把工程文件交给 Xcode 的文件系统同步组托管。这篇文章就沿着这三条线,解剖它的分层、依赖与天花板。
一、第一印象:六个顶层目录与一条隐藏的依赖方向
先看规模分布。仓库根目录下真正参与编译的源码,集中在 Erosion/ 之下的六个一级目录里:
| 目录 | 文件数 | 职责定位 | 代表文件 |
|---|---|---|---|
Tweaks/ |
18 | 业务功能页,一个功能一个 View | GestaltView.swift(807 行)、AppDataBackupView.swift(594 行) |
FileManager/ |
13 | 文件浏览、查看、Plist 编辑 | FileBrowserView.swift(445 行)、PlistManager.swift(279 行) |
Helpers/ |
11 | 无状态工具与全局设施 | WriteHelpers.swift、DeviceInfoHelpers.swift、Alertinator.swift |
UI/ |
11 | 可复用的视觉原子件 | PlainToggle.swift、SectionPlatter.swift、HeaderLabel.swift |
Exploits/ |
7 | 系统能力底座(C / ObjC / Swift 桥) | worse_query.m、bad_query.c、pathleak.m |
App/ |
4 | 壳层:设置、日志、样式、信息页 | SettingsView.swift、LogView.swift |
依赖方向基本是单向的:App/ 与三个 Tab 是装配层,Tweaks/ 与 FileManager/ 是消费层,Helpers/ 与 UI/ 是被消费的横切层,Exploits/ 与 Tweaks/MobileGestalt/MGCacheLayout.swift 是依赖系统的最底层。这条方向在入口处看得最清楚——ErosionApp.swift 用三段式 TabView 把「主页 / 功能修改 / 文件浏览」挂起来,并把 ErosionManager 通过 environmentObject 注入整棵视图树:
TabView {
ContentView().tabItem { Label("主页", systemImage: "house") }.id(0)
TweaksView().tabItem { Label("功能修改", systemImage: "wrench.and.screwdriver") }.id(1)
FMRootView().tabItem { Label("文件浏览", systemImage: "folder") }.id(2)
}
.environmentObject(mgr)
值得注意的一个细节是:ErosionManager 被刻意做薄了。ErosionManager.swift 只有 41 行,全部内容就是三个 @Published 状态(logOutput、shouldRespring、refreshFiles)加一个全局文件列表,没有任何业务方法。业务逻辑不在「管理器」里,而在各自的 View 里。这是这个仓库最重要的结构选择:没有一个 God Object 去承载所有功能,所以功能堆到 18 个文件也不会把某一个类撑爆。
代价当然存在。跨模块共享的上下文用的是文件级全局变量,散落在各文件顶层:
let device = UIDevice.current // ErosionApp.swift
let fm = FileManager.default // ErosionApp.swift
let wq = WorseQuery() // Exploits/WorseQuerySwift.swift
var group = "group.com.jbdotparty.Erosion.WQ" // Exploits/WorseQuerySwift.swift
var pipe = Pipe() // ErosionApp.swift
这是一种「进程即容器」的写法:任何 View 直接引用 wq、fm 即可,不需要构造、不需要注入。它让新增功能的边际成本极低——这正是「敢塞」的第一层原因;但也意味着这些页面无法在独立进程中隔离测试。后文会展开。
二、为什么能塞:工程文件几乎不参与协作
大多数 iOS 单体仓库膨胀的第一道阻力不是代码,而是 project.pbxproj。每加一个文件就要新增 PBXFileReference 与 PBXBuildFile,多人协作时冲突高发。Erosion-CN 直接绕过了这道阻力。
打开 project.pbxproj,objectVersion = 77,整个工程只有一个 PBXNativeTarget,而它的源码不是靠文件列表组织的,而是靠 PBXFileSystemSynchronizedRootGroup:
15145801302FE21A00DDFE07 /* Erosion */ = {
isa = PBXFileSystemSynchronizedRootGroup;
exceptions = ( 15556FFF303C04DB006C2969 /* Exceptions for "Erosion" folder ... */ );
path = Erosion;
sourceTree = "<group>";
};
也就是说,Erosion/ 目录下任何 .swift / .m / .c / .h 文件都会被自动纳入编译,只有 Info.plist 被登记为 membershipExceptions(避免被打进资源副本)。这带来两个直接后果:
- 新增功能是「零工程文件成本」。往
Tweaks/里丢一个新目录、一个新 View,工程文件一个字节都不用改。所以把 18 个功能页塞进一仓,在工具链上几乎没有摩擦。 - 代价从工具转移到纪律。既然工程不强制你声明模块,那「哪些文件属于哪一层」就完全靠目录命名来约束。一旦有人把业务逻辑写进
Helpers/,编译器不会报警。
外部依赖同样克制。整个仓库的依赖清单不到十行:ZIPFoundation 走 Swift Package(在 PBXBuildFile 中以 productRef 引入,供存档打包使用),加一个显式链接的 MobileCoreServices.framework,路径直接指向 iPhoneOS27.0.sdk。剩下的全部是系统框架与私有符号。真正复杂的东西没有以「依赖」的形式进来,而是以「源码」的形式进来——这是全仓策略的核心取舍,下一节细说。
三、依赖不是引进来,而是抄进来:Exploits/ 如何当底座
Erosion/bridge.h 只有 28 行,却定义了整个工程与系统之间的全部接口面:四个自研头文件、CoreFoundation、以及两个手写声明的私有符号:
#import "Exploits/bad_query.h"
#import "Exploits/worse_query.h"
#import "Exploits/pathleak.h"
#import "Tweaks/MobileGestalt/MGImageReader.h"
SecTaskRef _Nullable SecTaskCreateFromSelf(CFAllocatorRef _Nullable allocator);
CFTypeRef _Nullable SecTaskCopyValueForEntitlement(SecTaskRef _Nonnull task, CFStringRef _Nonnull entitlement, CFErrorRef _Nullable * _Nullable error);
@interface LSApplicationWorkspace : NSObject
+ (instancetype)defaultWorkspace;
- (bool)openApplicationWithBundleID:(NSString*)bundleID;
@end
注意这里的设计:不导入任何私有 SDK 头文件,只声明「我需要的那几个符号」。这让桥接层保持稳定,即使系统版本变化、私有头缺失,也不会连锁崩掉整个编译。
真正的能力收束在 Exploits/ 的三个 C / Objective-C 文件上:bad_query.c 负责基础沙盒查询原语,worse_query.m 在上面构建可持久的查询句柄,pathleak.m 用于加速容器扫描。而 Swift 侧只在 WorseQuerySwift.swift 里包了一层 WorseQuery 类,把「拿到某个路径的读写权」抽象成唯一的方法 grantAccess(path:)。
这一层抽象的价值,用调用点数量就能说明:全仓库有 30 余处 wq.grantAccess(...),分布在文件浏览、状态栏、存档备份、缓存清理、壁纸、拨号盘、MobileGestalt、系统配置等模块,但没有一个模块直接去碰 worse_query() 这个 C 函数。所有模块看到的都是同一种返回形态:
let res: Int64 = worse_query(canonical, group, false, false)
switch res {
case -1: errorString = "无法访问 App Group"
case -2: errorString = "解析系统函数失败"
case -3: errorString = "创建查询句柄失败"
case -4: errorString = "创建符号链接失败"
case -5: errorString = "沙盒查询被拒绝"
case -6: errorString = "内核拒绝下发沙盒扩展令牌"
case -255: errorString = "目标路径不存在"
default: errorString = nil
}
错误码被统一翻译成中文,上层只需判断 (Bool, Int64, String)。更关键的是它内置了句柄生命周期管理:activeHandles: [String: Int64] 配合 NSLock,同一路径重复申请时先检查当前是否真的可读写,命中就复用旧句柄,替换时释放旧句柄。全局单例 wq 因此是有状态的——它是一个句柄池,而不是无状态工具函数。
App Group 的获取也是一个值得单拎出来的工程细节。第三方重签工具会随意注入 group.* 容器,硬编码必然失败。WorseQuerySwift.swift 采用了两级探测:先走 SecTaskCopyValueForEntitlement 读已签名 entitlements;失败则退回到纯 Swift 的 Mach-O 解析——自行遍历 LC_CODE_SIGNATURE 指向的 CS_SuperBlob,校验魔数 0xfade0cc0、找到 0xfade7171 的 entitlements blob,再反序列化成 plist。它还处理了 FAT_MAGIC_64 胖二进制与当前加载架构的匹配(用 _dyld_get_image_header(0) 的 cputype / cpusubtype 过滤),并且每次读取前都做 inRange 边界检查。
这段代码的存在,解释了为什么这个仓库不需要引入任何「签名解析库」:为了一个功能写 150 行解析器,比引入一个依赖更可控。这是全仓策略的典型样本——复杂度内部化,依赖外部化归零。
四、写入协议只有一个出口:WriteHelpers.swift
如果说 grantAccess 解决「能不能碰」,那 WriteHelpers.swift 解决的是「怎么碰才不出事」。整个仓库对系统文件的持久化写入,最终都收敛到同一个函数 writeFileAtomically(_:to:allowEmpty:)。
这个函数的实现顺序本身就是一份故障复盘记录:
// 1. 从偏移 0 直接 pwrite 覆盖(绝不先 ftruncate 到 0)
try pwriteAll(fd, data, startOffset: 0)
// 2. 仅当新数据更短时才裁剪尾部
if data.count < og.count {
guard ftruncate(fd, off_t(data.count)) == 0 else { throw fileWriteErr.truncate(errno: errno) }
}
// 3. 刷穿 APFS 与 NVMe 控制器缓存
guard fullFsyncSafe(fd) else { throw fileWriteErr.sync(errno: errno) }
// 4. 按描述符全量读回逐字节比对
guard lseek(fd, 0, SEEK_SET) == 0 else { throw fileWriteErr.verificationFailed }
let verify = try readAll(fd)
guard verify == data else { throw fileWriteErr.verificationFailed }
四个动作对应四类真实事故:预截断会留下 0 字节窗口(断电即空文件);不裁剪会把旧尾部残留成脏数据;不 F_FULLFSYNC 只 fsync 会把数据停在控制器缓存里;不读回校验则无法发现写了一半。出错路径上还有第五步——用 og(写入前读到的原始字节)原位回滚并再次 F_FULLFSYNC。
值得对照的是同文件里另一个函数 writeFileTemp,它走 replaceItemAt 的临时文件替换路径。两条路径的区别正是「Inode 与 _mobilegestalt POSIX 属主是否被保留」:替换会换掉 Inode,而系统缓存校验依赖原 Inode;原位覆盖不会。因此 MobileGestalt 的写入入口 mgWriteDetailed 在 GestaltHelpers.swift 里无条件走 writeFileAtomically,并在调用前再叠三道门:
let preCheck = mgValidatePlistData(data) // 结构校验
if case .failure(let cacheErr) = MGCacheDataCoordinator.shared
.validateTransition(from: liveDiskDict, to: targetDict) { ... } // 字节级差异白名单
try? originalBytes.write(to: MGURL.preApplyGestaltURL, ...) // 写前快照
mgExcludeFromCloudBackup(MGURL.preApplyGestaltURL) // 隔离 iCloud
这里出现了一个贯穿全仓的横切约定:任何落到 Documents/ 的敏感备份都要打上 isExcludedFromBackup。GestaltHelpers.swift 里的 mgExcludeFromCloudBackup(_:) 只有五行,却被状态栏备份、SpringBoard 备份、存档 zip、任意文件替换备份、PreApply 快照等十余处复用。备份路径也由集中常量定义,例如 MGURL.savedGestaltURL、SBURL.overlayBackupDir、CNURL.cloudConfigBackup,而不是各处 appendingPathComponent 硬拼。
「能力一个入口、写入一个出口、备份一个约定」,这三条就是单仓不失控的真正原因。目录只是表象。
五、结构开始承压的地方
这套结构在「加功能」方向极其顺手,但在「改结构」方向会很快撞墙。以下四处是仓库自身已经暴露出来的压力点。
第一面墙:双层 NavigationStack。 TweaksView.swift 的外层已经是 NavigationStack { List { NavigationLink(destination: ConfigView()) } },而作为 destination 的 ConfigView.swift 内部又写了一次 NavigationStack { List { ... } }。功能页把自己当成「独立可运行的根」来写,装配层又把它当子页推入,结果就是嵌套导航容器——标题栏、工具栏、返回手势的行为都变得依赖 SwiftUI 的兜底逻辑。这是「每个功能页自带壳」这一约定的直接副作用。
第二面墙:每个功能页都要重写一遍初始化样板。 打开任意一个 Tweaks 页面,几乎都能看到同一套三段式:申请权限 → 读原文件 → 填进 @State。ConfigView.doSetup() 就是标准样本:
if !fm.isWritableFile(atPath: CNURL.sharedDevConfig.path) {
let res = wq.grantAccess(path: FSURL.configProfiles.path)
if !res.0 { Alertinator.shared.alert(title: "获取写入权限失败!", body: AppMsg.opFailed); return }
}
// 记录「原本是否存在」以便精确还原,再读取、填充 @State
StatusBarView、SpringBoardTweakView、PosterBoardView、CacheCleanerView 各自复制了结构相同、字段不同的版本(StatusBarView 一页就有 11 处 grantAccess)。这里缺一层「可写资源」的抽象:如果有一个 GuardedFile / GuardedPlist 类型,把「授权、存在性快照、原厂备份、云备份隔离、读回」打包,18 个功能页能砍掉大量重复代码,也顺带把「是否已备份」的判断统一掉。
第三面墙:单 target 带来的编译与预览耦合。 工程只有一个 target,MobileGestalt/ 一个目录就占了约 2670 行(GestaltView 807 + MGCacheLayout 599 + GestaltHelpers 489 + GestaltStore 380 + CustomKeyView 238 + MGImageReader 156+),接近全仓四分之一。任何一次改动都触发整 target 重编。同时 #Preview 只有 ContentView 一处,ErosionManager.shared / GestaltStore.shared / Alertinator.shared 三层单例加上文件级全局 wq,让单个页面的 SwiftUI Preview 基本不可用——预览进程里没有 App Group、没有沙盒穿透、没有系统文件。功能越多,这个「不可预览面积」越大。
第四面墙:文案与键值两套「常量」不对齐。 好消息是作者确实做了常量收敛:AppMsg 在 ErosionManager.swift,MGMsg / MGKey 在 GestaltStore.swift,CNMsg 在 ConfigView.swift,混淆键还都带了英文注释(如 appIntell = "A62OafQ85EJAiiqKn4agtg" // DeviceSupportsGenerativeModelSystems)。坏消息是收敛只做到了「每模块各自一个 enum」:状态栏页的说明文案仍然内联在 PlainToggle 的 infoMessage 字符串里,CNMsg 与 MGMsg 互不知道对方存在。工程 developmentRegion 只有 zh-Hans,一旦要出多语言,这些散落的字符串就是主要工作量。
还有一层不那么显性但更硬的墙:MobileGestalt 键名永远是静态清单。槽位偏移已经通过运行时扫描 /usr/lib/libMobileGestalt.dylib 的 64 字节查询描述符动态解析(MGCacheLayout.swift 里 scan 找 22 字符混淆键 → +0x3A 取 Int16 槽位 → +0x3C 校验 query type 为 11),这部分做得相当克制;但 MGKey 里那几十个混淆键仍然要靠人肉维护。系统一升级,槽位能自动跟上,键名清单跟不跟得上则是另一回事。
六、结论:单仓是果,不是因
把整套功能塞进一个仓库之所以成立,不是因为「iOS 工具就该这么写」,而是因为三件事恰好同时为真:
- 共享的是能力,不是业务。 所有功能真正复用的只有
grantAccess与writeFileAtomically两个入口,其余互不依赖。共享面窄,所以同仓不会产生循环依赖。 - 工程文件被降级成目录约定。 文件系统同步组让「加文件」零成本,代价是模块边界只能靠命名维持——目前靠
Tweaks/、Helpers/、Exploits/三层命名撑住了。 - 风险处置被集中到少数几处。 写入协议、云备份隔离、备份完整性摘要(
mgComputeSHA256Hex+OriginalGestalt.sha256)、跨版本/跨机型还原的四重指纹校验(CacheVersion、CacheUUID、CacheData长度、ProductType),全部只在一个地方实现。护栏集中,是单仓能承受这么多高危操作的先决条件。
如果要继续长大,最先该动的不是拆包,而是补上那块一直缺的抽象:把「授权 → 快照 → 备份 → 原位写 → 读回 → 回滚」抽成一个资源层,让 18 个功能页从「各自跟系统打交道」变成「消费一个受控资源」。工程可以继续是一个 target、一个仓库;真正需要分层的,是每个功能页反复重写的那段样板代码。到那一步,「把整套功能塞进一个仓库」才从一次大胆的取舍,变成一种可复制的方法。