AeroSpace 架构解析SPM 模块划分、UNIX Socket 客户端/服务器通信与命令子系统实现【免费下载链接】AeroSpaceAeroSpace is an i3-like tiling window manager for macOS项目地址: https://gitcode.com/GitHub_Trending/ae/AeroSpace本篇技术指南以仓库内 dev-docs/architecture.md 为骨架结合源码逐层拆解 AeroSpacemacOS 上的 i3 风格平铺窗口管理器的整体架构包括基于 Swift Package ManagerSPM的工程组织方式、aerospaceCLI 客户端与AeroSpace.app服务器之间的 UNIX Socket 通信协议、命令子系统与 TOML 配置解析子系统的实现链路以及树模型与布局子系统的模块边界。读完本文你将掌握该项目的模块划分、请求/应答数据流以及如何在此基础上定位、阅读与扩展各功能模块的源码。一、架构文档核心定义SPM 是什么架构文档开篇即给出一个贯穿全文的定义SPM.Swift package manager and Swift build tool. In other words,swiftCLI toolSPMSwift Package Manager既是包管理器也是 Swift 构建工具即swift命令行工具。这个定义之所以重要是因为 AeroSpace 的整个工程组织都建立在 SPM 之上绝大部分代码由Package.swift管理仅在最外层用 Xcode 工程做 macOS App Bundle 的封装。因此理解 SPM 的 target/product 概念是读懂本项目架构的第一步。二、高层工程基础设施SPM 为主、Xcode 为辅的双轨结构架构文档将项目拆分为以下几个顶层组成部分对应仓库根目录下的实际目录组件仓库路径职责主体源码Sources/AeroSpace 绝大多数源码由 SPM 管理App Bundle 服务器Sources/AppBundle/AeroSpace.app服务器本体。技术上是一个 SPM library暴露给 Xcode App Bundle 启动器CLI 客户端Sources/Cli/aerospace命令行客户端纯 SPM 构建不依赖 Xcode共享代码Sources/Common/服务器与客户端共享的代码主要是命令行参数解析与工具函数Xcode 启动壳xcode/AeroSpace.xcodeproj定义 Xcode 工程的入口由 xcode/project.yml 骨架生成测试Sources/AppBundleTests/测试代码文档docs/站点与 man page 的 Asciidoc 文档源2.1 为什么需要 SPM 与 Xcode 双轨架构文档明确解释了这种“双轨”设计的原因这是理解整个工程组织方式的关键Xcode 工程难以脱离 Xcode 本身进行维护且 Swift LSP 不支持 Xcode 工程只支持 SPM 工程但 SPM 无法构建 macOS App即 “App Bundle”它只能定义 library 和构建 CLI 应用因此所有代码被尽可能下沉到Sources/下的 SPM “library” 中Xcode 工程只保留最薄的启动壳。在 Package.swift 中可以看到这条边界的具体体现products: [ .executable(name: aerospace, targets: [Cli]), // Dont use this build for release, use xcode instead .executable(name: AeroSpaceApp, targets: [AeroSpaceApp]), // We only need to expose this as a product for xcode .library(name: AppBundle, targets: [AppBundle]), ],其中aerospace可执行文件由Clitarget 产出AeroSpaceApp可执行文件是服务器的 SPM 侧入口而AppBundle以 library 形式暴露给 Xcode 工程使用。依赖方面AppBundle引入了HotKey快捷键绑定、ISSoundAdditions音量控制、TOMLDecoder配置解析与swift-collections并通过PrivateApitarget 将私有_AXUIElementGetWindow函数暴露给 Swift。从源码结构推断仓库中的xcode/目录即架构文档所述xcode-app-bundle-launcher与../AeroSpace.xcodeproj在当前仓库中的落点Xcode 工程模型由xcode/project.yml骨架生成xcode/AeroSpace.xcodeproj是生成产物仅用于 release 构建脚本。三、客户端/服务器交互基于 UNIX Socket 的请求应答协议架构文档给出了本项目最核心的运行模型aerospaceCLI binary is client.AeroSpace.appis server. Client and server talk to each other via predefined UNIX file.CLI 客户端与 App 服务器通过一个预定义的 UNIX 文件UNIX domain socket通信。每次执行一条 CLI 命令文档给出的流程是参数由客户端解析解析错误被报告传入-h/--help时显示帮助参数解析成功后参数被发送给服务器服务器再次解析参数并执行命令服务器将 stdout、stderr 和退出码返回给客户端客户端展示 stdout、stderr并以请求的退出码结束进程。3.1 客户端入口Cli/_main.swift上述流程在 Sources/Cli/_main.swift 中有完整实现。Main.main()的处理顺序与架构文档一一对应空参数 /--help分别以退出码 2 与 0 打印 usage--version/-v连接服务器获取serverVersionAndHash打印客户端与服务器两端的版本若两端cliClientVersionAndHash与serverVersionAndHash不一致会提示“AeroSpace client/server versions dont match”及修复建议参数解析调用parseCmdArgs(args)这里有一个值得注意的优化——true与false命令在客户端直接退出根本不与服务器通信case .cmd(_ as TrueCmdArgs): exit(ConditionalExitCode._true.rawValue) case .cmd(_ as FalseCmdArgs): exit(ConditionalExitCode._false.rawValue)建立连接NWConnection(to: NWEndpoint.unix(path: socketPath), using: .tcp)连接预定义的 UNIX socket若连接失败提示 “Cant connect to AeroSpace server. Is AeroSpace.app running?”stdin 处理仅在显式传入--stdin标志或兼容旧版本的隐式场景时读取标准输入并设有 1000 行上限环境变量注入从进程环境读取AEROSPACE_WINDOW_ID与AEROSPACE_WORKSPACE随请求一起发送这是--window-id/--workspace类命令的工作基础发送请求并读取应答run()将ClientRequest(args:stdin:windowId:workspace:)原子写入连接随后阻塞读取ServerAnswer的 JSON 应答subscribe特例订阅类命令走runSubscribe()的持续读循环逐条打印服务器推送的事件。3.2 服务器入口UNIX Socket 监听循环服务器侧对应 Sources/AppBundle/server.swift 中的startUnixSocketServer()先用FileManager.removeItem清理残留 socket 文件再通过NWListener以requiredLocalEndpoint .unix(path: socketPath)监听每个新连接在全局队列上启动一个异步任务处理。newConnection(_:)实现了带版本握手的请求循环协议版本握手客户端先写入一个UInt32版本号服务器无条件回写SOCKET_PROTOCOL_VERSION版本不一致则直接断开。该常量定义于 Sources/Common/model/clientServer.swift当前值为1请求解码逐条读取数据并ClientRequest.decodeJson解码为结构化请求subscribe分流subscribe命令没有对应的Command实现在解析普通命令之前被单独处理为长连接推送服务开关检查通过RunSessionGuard.isServerEnabled判断服务器是否被enable命令禁用禁用时拒绝执行并提示可用aerospace enable on恢复命令执行parseCommand解析出命令后在runLightSession中调用command.run(env, CmdStdin(request.stdin))应答组装将exitCode、stdout、stderr与serverVersionAndHash打包成ServerAnswer写回客户端。3.3 通信协议的数据结构Sources/Common/model/clientServer.swift 定义了这条链路上最关键的两个类型ServerAnswerexitCode、stdout、stderr、serverVersionAndHash四个字段ClientRequestargs原始参数数组、stdin、windowId、workspace。其中windowId/workspace采用“双重 Optional”UInt32??编码以便在 JSON 中表达显式的null——服务器会校验这两个字段是否缺失并提示客户端转发AEROSPACE_WINDOW_ID、AEROSPACE_WORKSPACE环境变量。需要说明的是该类型同时保留了一个标记为periphery:ignore的command字段源码注释表明它是为兼容旧服务器保留的未使用字段。因此协议版本检查SOCKET_PROTOCOL_VERSION是客户端与服务器兼容性的第一道防线两端的版本哈希对比则作为第二道提示。四、Commands 子系统从 argv 到命令执行的完整链路架构文档将 Commands 子系统标记为todo仅留下两个指向Sources/AppBundle/command/与Sources/Common/cmdArgs/的引用。这两个目录恰好揭示了该子系统的核心设计——命令的参数定义CmdArgs放在 Common 供双端共享命令的运行时实现Command放在 AppBundle 由服务器持有。4.1 命令注册表CmdKind所有命令以枚举CmdKind的形式集中登记在 Sources/Common/cmdArgs/cmdArgsManifest.swift每个 case 的rawValue即 CLI 子命令名。当前包含的命令有balance-sizes、close、close-all-windows-but-current、config、debug-windows、echo、enable、eval、exec-and-forget、false、flatten-workspace-tree、focus、focus-back-and-forth、focus-monitor、fullscreen、join-with、layout、list-apps、list-exec-env-vars、list-modes、list-monitors、list-windows、list-workspaces、macos-native-fullscreen、macos-native-minimize、mode、move、move-mouse、move-node-to-monitor、move-node-to-workspace、move-workspace-to-monitor、reload-config、resize、run-callback、split、subscribe、summon-workspace、swap、test、test-not、trigger-binding、true、volume、workspace、workspace-back-and-forth。initSubcommands()将每个 kind 映射到对应的SubCommandParser并保留了两个向后兼容的别名move-through指向move与move-workspace-to-display指向move-workspace-to-monitor。exec-and-forget在initSubcommands()中被显式跳过因为它需要单独处理。4.2 参数解析层parseCmdArgs 与 CmdArgs 协议客户端侧入口是 Sources/Common/cmdArgs/parseCmdArgs.swift 的parseCmdArgs(_:)取出首个参数作为子命令名在subcommandParsers注册表中查找对应解析器找不到则返回Unrecognized subcommand失败。每个命令的参数类型遵循CmdArgs协议核心约束包括associatedtype ExitCodeType: ExitCode BinaryExitCode命令可自定义退出码语义如true/false/test等条件命令static var parser: CmdParserSelf声明式的参数解析器var commonState: CmdArgsCommonState携带windowId、workspaceName、explicitStdinFlag等公共状态。CmdParser结构体由flags选项字典、positionalArgs位置参数列表与conflictingOptions互斥选项集合组成帮助文本与命令种类则由CmdStaticInfo承载。解析结果统一收敛为 ParsedCmd.swift 中的三态枚举public enum ParsedCmdT: Sendable: Sendable { case cmd(T) // 解析成功 case help(String) // 请求帮助 case failure(CmdParsingFailure) // 解析失败 }4.3 运行时执行层Command 协议服务器侧的 Sources/AppBundle/command/Command.swift 定义了执行层的Command协议protocol Command: AeroAny, Equatable, Sendable { associatedtype T: CmdArgs var args: T { get } MainActor func run(_ env: CmdEnv, _ io: CmdIo) async - T.ExitCodeType /// We should reset closedWindowsCache when the command can potentially change the tree var shouldResetClosedWindowsCache: Bool { get } }run被标注为MainActor说明命令执行统一发生在主线程这保证了窗口树等共享状态的线程安全。shouldResetClosedWindowsCache与树模型子系统的closedWindowsCache联动——当命令可能改变窗口树时需要重置该缓存见 Sources/AppBundle/tree/frozen/closedWindowsCache.swift。4.4 服务器侧命令解析parseCommand服务器并不直接调用parseCmdArgs而是先经 Sources/AppBundle/command/parseCommand.swift 做一次 shell 语义的词法/语法解析lexAndParseShell()实现位于 Sources/AppBundle/shell/以支持、||等组合命令再对每条原子命令调用parseCommand(args)func parseCommand(_ args: [String]) - ParsedCmdany Command { parseCmdArgs(args.slice).flatMap { $0.toCommand() } }这里可以看到两个安全边界exec-and-forget只在allowExecAndForget为真时允许且其 bash 脚本内容不经过 shell 解析器eval嵌套执行被禁止“Illegal eval (Tip: nested evals are forbidden)”。这解释了为什么exec-and-forget与eval需要特殊对待——它们引入了任意脚本执行能力。4.5 新增命令的检查清单架构文档为新增命令给出了一个 checklist同样是当前仓库可验证的规范文档在 docs/aerospace-*.adoc 与 docs/commands.adoc 中补充说明文档目录中每个命令对应一个aerospace-command.adoc文件检查--window-id与--workspace标志对命令是否适用更新 shell 补全grammar/commands-bnf-grammar.txt。命令实现与参数定义的对应关系可以以focus为例印证参数解析parseFocusCmdArgs在 Sources/Common/cmdArgs/impl/FocusCmdArgs.swift运行时实现 Sources/AppBundle/command/impl/FocusCommand.swift测试在 Sources/AppBundleTests/command/FocusCommandTest.swift三处构成“定义—实现—测试”的完整闭环。五、TOML Config 解析子系统架构文档同样将本子系统标记为todo仅引用Sources/AppBundle/config/。从源码结构看该目录下集中了配置的完整处理链路Config.swift 与 ConfigFile.swift配置数据模型与配置文件定位parseConfig.swiftTOML 文本到配置模型的总解析入口各专项解析器parseGaps.swift间距、parseKeyMapping.swift键位映射、parseOnWindowDetected.swift窗口出现回调、parseWorkspaceToMonitorAssignment.swift工作区到显示器分配、parseFocusFollowsMouse.swift鼠标跟随焦点、parseExecEnvVariables.swift执行环境变量HotkeyBinding.swift 与 Mode.swift热键绑定与模式mode的定义ConfigFileWatcher.swift配置文件热重载startAtLogin.swift开机自启。配置采用 TOML 格式Package.swift中固定依赖TOMLDecoder 0.4.4。服务器的启动参数支持--config-path path指定配置路径优先级高于~/.aerospace.toml与${XDG_CONFIG_HOME}/aerospace/aerospace.toml以及--read-only禁用窗口管理仅保留debug-windows等查询命令这两项在 Sources/AppBundle/initAppBundle.swift 的initServerArgs()中解析。完整的默认配置示例见 docs/config-examples/default-config.tomli3 风格配置见 docs/config-examples/i3-like-config-example.toml。六、Tree Model 与 Layout 子系统6.1 Tree Model窗口树的领域模型Sources/AppBundle/tree/是窗口树tiling tree的领域模型所在架构文档将其标记为todo。从目录与源码结构看其核心类型包括TreeNode.swift 与 TreeNodeCases.swift树节点的基类与分派TilingContainer.swift平铺容器对应 tiling 层级Window.swift、MacWindow.swift、AbstractApp.swift、MacApp.swift窗口与应用抽象Workspace.swift 与 WorkspaceEx.swift工作区FloatingWindowsContainer.swift 与 MacosUnconventionalWindowsContainer.swift浮动窗口与非常规窗口容器normalizeContainers.swift容器规范化frozen/冻结视图FrozenWorld/FrozenTreeNode与closedWindowsCache用于渲染与缓存失效。工作区初始化在服务器启动时通过Workspace.garbageCollectUnusedWorkspaces()与focusWorkspace()完成见 initAppBundle.swift其测试位于 Sources/AppBundleTests/tree/。6.2 Layout布局递归与刷新Sources/AppBundle/layout/只包含两个文件职责非常聚焦layoutRecursive.swift对窗口树递归计算每个节点的目标矩形Rectrefresh.swift将布局结果应用到真实窗口。布局与刷新由 Sources/AppBundle/layout/refresh.swift 配合 Sources/AppBundle/normalizeLayoutReason.swift 与 Sources/AppBundle/runLoop.swift 驱动。布局模式的判定还体现在启动时的“智能布局”逻辑中initAppBundle.swift 的smartLayoutAtStartup()根容器子节点数不超过 3 时使用tiles平铺超过则使用accordion手风琴布局。七、服务器启动时序initAppBundle将各子系统串起来的服务器启动流程位于 Sources/AeroSpaceApp/AeroSpaceApp.swiftmain入口该文件在 SPM 与 Xcode 工程间共享与 Sources/AppBundle/initAppBundle.swift注册终止处理器、标记非 CLI 模式initServerArgs()解析服务器启动参数--config-path、--read-only、--version等waitForAccessibilityPermission等待辅助功能Accessibility权限授权debug 构建下向已有的 release 服务器发送enable offtoggleReleaseServerIfDebug避免双实例冲突bootstrapConfig_nonCancellable加载默认配置并校验安装完整性随后reloadConfig加载用户配置startUnixSocketServer()启动 socket 服务器即第三节所述的通信入口GlobalObserver.initObserver()初始化全局观察者对应 Sources/AppBundle/GlobalObserver.swift监听应用与窗口事件初始化工作区并聚焦默认工作区执行runHeavyCompleteRefreshSession(.startup)完成首次全量布局刷新随后执行配置中的after-startup-command。需要补充说明的是--read-only模式同时会影响toggleReleaseServerIfDebug与服务器对命令的接受行为因此在调试阶段用只读模式排查查询类命令是安全的。八、测试与文档体系的落点架构文档将 Sources/AppBundleTests/ 列为测试目录将 docs/ 列为文档源目录Asciidoc 格式同时用于生成站点与 man page。当前仓库的证据包括测试按子系统组织命令测试在 Sources/AppBundleTests/command/如 FocusCommandTest.swift、ListWindowsTest.swift配置解析测试在 Sources/AppBundleTests/config/shell 解析测试在 Sources/AppBundleTests/shell/ShellLexerTest.swift 等客户端/服务器协议测试在 Sources/AppBundleTests/model/ClientServerTest.swift测试基础设施包括 Sources/AppBundleTests/testUtil.swift、Sources/AppBundleTests/assert.swift以及用于构造窗口树夹具的 Sources/AppBundleTests/tree/TestApp.swift 与 Sources/AppBundleTests/tree/TestWindow.swift文档侧每个命令对应一个docs/aerospace-command.adocdocs/commands.adoc汇总命令总览docs/guide.adoc为用户指南。九、小结一张图读懂 AeroSpace 架构综合上述分析AeroSpace 的整体架构可以概括为一条清晰的分层链路工程层SPM 定义Common共享→Cli客户端→AppBundle服务器 library→AeroSpaceApp可执行壳Xcode 工程仅作为 release App Bundle 的薄封装传输层客户端与服务器通过预定义 UNIX socket 通信SOCKET_PROTOCOL_VERSION握手保证协议兼容ClientRequest/ServerAnswer完成 JSON 请求应答subscribe退化为长连接推送命令层CmdKind注册表 CmdArgs参数模型 CmdParser声明式解析服务器侧再经Command协议在主线程执行exec-and-forget/eval设有额外安全边界领域层TOML 配置解析Sources/AppBundle/config/、窗口树模型Sources/AppBundle/tree/、布局递归与刷新Sources/AppBundle/layout/各自内聚为独立子系统由initAppBundle在启动时按固定时序装配。对于希望深入参与该项目的开发者架构文档中标记为todo的四个子系统Commands、TOML Config、Tree Model、Layout恰好是最佳的源码阅读入口——以本文梳理的模块边界与文件索引为地图即可从aerospace focus这样的单条命令出发沿“参数解析 → socket 传输 → 服务端解析 → 命令执行 → 布局刷新”的调用链逐层钻取。【免费下载链接】AeroSpaceAeroSpace is an i3-like tiling window manager for macOS项目地址: https://gitcode.com/GitHub_Trending/ae/AeroSpace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考