1. 项目概述一个为AI编程助手打造的macOS动态岛式控制塔如果你和我一样日常开发中同时开着Claude Code、Cursor、GitHub Copilot等多个AI编程助手那你一定经历过这种混乱每个助手都在不同的终端标签页或IDE窗口里运行你需要不停地切换、查看状态、响应权限请求或回答问题。这种上下文切换不仅打断心流还容易遗漏关键信息。Tower Island正是为了解决这个痛点而生的。它是一个macOS原生应用灵感来源于iPhone的“动态岛”在你的屏幕顶部创建一个常驻的、可交互的浮动面板将所有AI编程助手的会话状态、请求和通知统一汇聚于此让你无需离开当前窗口就能掌控全局。简单来说Tower Island是一个AI编程助手的统一仪表盘和交互中心。它通过轻量级的钩子hooks系统实时监听你电脑上所有主流AI编程助手如Claude Code、Cursor、Codex、OpenCode等的活动。当一个助手开始思考、请求文件权限、需要你回答问题或展示执行计划时Tower Island会立即在顶部的“岛”上通过状态指示灯、通知音效和可展开的详细面板来提醒你。你可以直接在浮动面板上批准权限、回答问题、审阅计划甚至一键跳转到产生该请求的特定终端标签页。这极大地提升了使用多个AI助手协同工作时的效率和专注度。2. 核心设计思路与架构解析2.1 为什么选择“动态岛”模式在构思这样一个统一管理工具时UI形态的选择至关重要。传统的方案可能是独立的Dock应用窗口、菜单栏Menu Bar应用或通知中心插件。但Tower Island选择了模仿macOS刘海屏和iPhone动态岛的“药丸”形态这背后有几个关键的考量无侵入性与常驻可见性一个独立的窗口会占用宝贵的屏幕空间并且容易被其他窗口覆盖。菜单栏应用虽然常驻但交互需要点击信息展示面积有限。而动态岛形态悬浮在屏幕最顶部边缘几乎不占用有效工作区域同时其紧凑的“药丸”形态和状态指示灯蓝、绿、橙、红点能提供一种“余光可见”的信息密度让你在不聚焦它时也能感知到后台AI助手的状态变化。按需扩展的交互逻辑这是动态岛模式的核心优势。默认折叠时它只是一个显示状态的“药丸”。当你需要查看更多信息或进行交互时如鼠标悬停或点击面板会平滑地向下展开展示所有活跃会话的详细信息、权限请求或问题。交互完成后面板会自动收回。这种“收放自如”的特性完美匹配了AI助手交互“偶尔需要深度介入大部分时间只需概览”的使用模式。与macOS生态的融合从macOS Sonoma开始苹果在系统层面加强了对“台前调度”和顶部空间利用的引导。一个设计精良的顶部悬浮控件在视觉和交互逻辑上更符合现代macOS的应用设计语言减少了用户的认知负担。2.2 整体架构钩子、桥接与主应用的协同Tower Island的架构清晰地区分了数据采集、传输和展示三个层次确保了低侵入性和高可靠性。其核心是一个客户端-服务器模型但服务器是本地应用本身。[AI Agent (e.g., Claude Code)] - [Hook Script] - [DIBridge CLI] - [Unix Domain Socket] - [Tower Island App (SessionManager)]2.2.1 钩子注入与零配置这是用户体验的第一步也是Tower Island的亮点之一——“开箱即用”。ZeroConfigManager在应用首次启动时会主动扫描系统中已安装的、受支持的AI编程助手如通过检测~/.cursor、~/.vscode等目录。对于每个检测到的助手它会向该助手的配置文件如Cursor的hooks.jsonClaude Code的settings.json中插入一段预定义的钩子配置。例如给Cursor添加的钩子可能类似于{ hooks: { onToolUse: ~/.tower-island/bin/di-bridge --event tool_use --agent cursor --session-id {sessionId}, onPermissionRequest: ~/.tower-island/bin/di-bridge --event permission_request --agent cursor --session-id {sessionId} --data-json {\path\: \{path}\, \operation\: \{operation}\} } }这个钩子配置的本质是当特定事件如工具调用、权限请求发生时AI助手会执行一条命令行指令调用di-bridge这个桥接程序。注意这种自动注入配置的操作需要应用具有相应的磁盘访问权限。Tower Island在首次运行时通常会通过系统的权限API请求“辅助功能”或“完全磁盘访问”权限以确保配置能成功写入。如果自动配置失败用户也可以在应用的“代理”设置中手动触发或检查配置状态。2.2.2 轻量级桥接器di-bridge是一个用Swift编译的独立命令行工具安装在~/.tower-island/bin/目录下。它的职责非常单一接收来自AI助手钩子的调用解析命令行参数如事件类型、代理类型、会话ID和可能通过stdin或--data-json传递的JSON数据。将这些信息封装成一个结构化的DIMessage对象定义在共享模块DIShared中。通过一个预先约定好的Unix域套接字将这个消息发送给正在运行的Tower Island主应用。使用Unix域套接字而不是HTTP或WebSocket是出于性能和简洁性的考虑。它省去了网络端口绑定、序列化/反序列化可以直接传输二进制数据的 overhead是同一台机器上进程间通信IPC最高效的方式之一。2.2.3 主应用与实时会话管理主应用Tower Island.app在启动时会通过SocketServer监听上述Unix套接字。当di-bridge发来消息时SocketServer接收并解码为DIMessage然后交给核心的SessionManager处理。SessionManager是整个应用的状态中枢它维护着一个AgentSession对象的集合每个对象代表一个AI助手的一次独立对话或任务。根据收到的消息类型如session_start,tool_use,permission_request,session_end它创建、更新或移除对应的AgentSession。它管理会话的生命周期包括会话的活跃状态、完成后的留存时间根据用户配置等。任何状态变更都会立刻通过SwiftUI的Published属性包装器通知到所有相关的UI视图实现界面的实时刷新。2.2.4 交互式事件的响应循环对于需要用户交互的事件如权限请求、回答问题流程略有不同体现了设计的巧妙性AI助手触发钩子调用di-bridge。di-bridge向主应用发送permission_request或question消息然后自身进程会阻塞等待主应用的响应。主应用在UI上展示请求用户点击“批准”或输入答案。主应用将用户的决定通过另一个反向的套接字连接或直接向di-bridge进程的标准输入写入响应数据。di-bridge收到响应后将其输出到自己的标准输出。由于钩子调用本质是执行命令AI助手会读取di-bridge的标准输出来获取用户的决定从而继续执行。这个设计使得AI助手无需做任何适配就能通过标准的命令行输入输出与Tower Island进行复杂的交互。3. 功能特性深度剖析与实操指南3.1 统一仪表盘与实时状态监控安装并启动Tower Island后你会立刻在屏幕顶部中央看到一个细长的“药丸”。这个折叠视图是你的信息中枢。状态指示灯药丸上会显示彩色圆点。每个点代表一个活跃的AI助手会话。颜色语义如下蓝色助手正在“思考”或执行任务如tool_use事件。绿色任务成功完成session_end且状态为成功。橙色需要你的输入收到了question或plan_review事件。红色任务执行出错session_end且状态为错误。 你可以通过颜色和圆点数量瞬间了解后台有多少个助手在忙、是否有需要你处理的事情。悬停展开将鼠标移动到药丸上面板会优雅地向下展开显示所有活跃和近期完成的会话卡片。每张卡片包含会话标题通常是用户向AI助手提出的第一个问题或指令非常直观。代理图标与名称清晰标识是Claude Code、Cursor还是其他。工作空间路径该会话关联的项目目录方便你定位上下文。状态与时间当前状态及持续时间。实操心得建议在设置中将“自动折叠延迟”调整到一个适合自己的值比如5秒。这样在交互后面板有足够时间让你阅读信息又不会长时间遮挡内容。如果觉得频繁展开干扰可以开启“智能抑制”功能当你聚焦在AI助手所在的终端窗口时面板将不会自动展开。3.2 无缝的权限与问答交互这是Tower Island提升效率最显著的功能。以往当Claude Code请求读取某个文件或Cursor询问一个 clarifying question 时你必须切到对应的终端窗口去响应。现在当此类事件发生时Tower Island药丸上会亮起橙色指示灯并可能伴有特定的提示音效如经典的“硬币”声。展开面板你会看到对应的会话卡片高亮并内嵌了一个交互组件。对于权限请求会显示请求的操作读/写/执行和目标文件路径。你可以直接点击“批准”或“拒绝”。这个决定会立刻传回给AI助手。对于问题会显示AI助手提出的问题并提供一个文本框让你直接输入答案。输入后按回车或点击发送即可。整个过程你的视线和焦点无需离开当前正在编码的编辑器或浏览器。这种体验上的流畅感对于保持深度编程的专注度至关重要。3.3 精准的窗口跳转与多会话管理当你展开面板看到有3个Cursor会话在运行分别对应着不同的项目如何快速切换到其中一个只需点击该会话卡片。Tower Island的TerminalJumpManager会尝试执行一个“魔法”操作它会根据会话来源如特定的iTerm2窗口和标签页ID或VS Code的窗口信息使用AppleScript或MacOS的 Accessibility API尝试将你直接带到那个确切的终端标签页或IDE窗口。注意事项窗口跳转功能的精度取决于AI助手提供的上下文信息和macOS的权限。对于iTerm2如果钩子传递了准确的window_id和tab_id跳转会非常精准。对于其他终端或IDE可能会回退到激活对应应用窗口。确保Tower Island拥有“辅助功能”权限是此功能正常工作的前提。你可以在“系统设置 隐私与安全性 辅助功能”中添加Tower Island。Tower Island支持同一AI助手的多个并发会话。每个会话都有独立的ID和生命周期。在面板中它们会作为独立的卡片排列你可以清晰地看到每个会话在做什么、处于什么状态并进行独立交互。3.4 可配置的通知与音效为了避免不必要的干扰Tower Island允许你对通知进行精细控制。音效开关在设置中你可以为不同事件会话开始、完成、需要输入、错误单独开启或关闭8-bit风格的提示音。这些音效是程序生成的体积小巧且富有辨识度。会话留存你可以设置已完成会话绿色状态在面板上保留的时间从10秒到5分钟或选择“永不”自动移除。这对于事后回顾AI助手完成了哪些任务非常有用。智能抑制如前所述开启后当你正在使用某个AI助手所在的终端时该助手的事件将不会触发面板自动展开防止自己打断自己。4. 安装、配置与高级使用指南4.1 安装方式选择与避坑首选方案直接下载DMG这是最推荐的方式从项目的GitHub Releases页面下载最新的.dmg文件。打开后将Tower Island.app拖入“应用程序”文件夹即可。首次运行必遇的Gatekeeper问题 由于Tower Island未使用苹果官方的开发者证书签名这通常需要每年付费的开发者账号macOS的Gatekeeper安全机制会阻止其运行。解决方法有两种图形界面前往“系统设置 隐私与安全性”向下滚动通常会看到一个关于“Tower Island”已被阻止的提示旁边有“仍要打开”按钮。点击它即可。命令行在终端执行以下命令移除应用的隔离属性sudo xattr -cr /Applications/Tower\ Island.app安全提示xattr -cr命令会递归地清除扩展属性。请仅对从可信来源如项目官方GitHub下载的应用执行此操作。从源码构建适合开发者或想体验最新代码的用户。确保你的macOS在14.0以上Xcode命令行工具已安装。git clone https://github.com/g535879/TowerIsland.git cd TowerIsland bash Scripts/build.sh运行构建脚本后它会在.build/目录下生成应用并自动打开。构建脚本还会帮你安装配套的CLI工具。4.2 配套CLI工具的使用Tower Island安装后会在~/.tower-island/bin/目录下放置一个名为tower-island的CLI工具。它的主要作用是方便地检查更新和升级。将CLI加入PATH 构建脚本通常会提示你但如果没有可以手动将以下行添加到你的shell配置文件如~/.zshrc或~/.bash_profileexport PATH$HOME/.tower-island/bin:$PATH然后执行source ~/.zshrc使配置生效。使用CLI升级 确保你已安装GitHub官方CLI工具gh并已完成认证 (gh auth login)。之后只需运行tower-island upgrade该命令会自动从GitHub Releases拉取最新版本并完成升级比手动下载DMG再拖拽覆盖更方便。4.3 代理配置与故障排查理论上Tower Island的零配置管理在首次启动时会自动完成所有支持的AI助手的钩子配置。你可以在应用的“设置 代理”标签页查看和管理。常见问题可能原因与解决方案某个AI助手的事件未在Tower Island显示1.检查代理开关在Tower Island设置的“代理”页确保该助手已被启用。2.检查钩子配置前往该AI助手的配置目录如Cursor的~/.cursor/hooks.json查看钩子命令是否正确指向~/.tower-island/bin/di-bridge。3.检查权限确保Tower Island拥有读写该配置文件目录的权限。权限请求/问答交互无响应1.检查桥接器确认~/.tower-island/bin/di-bridge文件存在且可执行。2.检查Unix套接字Tower Island主应用必须正在运行才能监听套接字。重启Tower Island应用试试。3.查看日志Tower Island应用内可能有一个日志窗口或通过Console.app查看系统日志查看是否有错误信息。窗口跳转功能失效1.授予辅助功能权限这是最关键的一步。前往“系统设置 隐私与安全性 辅助功能”确保Tower Island在列表中且已被勾选。2.终端/IDE支持确认你的终端或IDE是否在Tower Island的精准跳转支持列表中如iTerm2支持最好。手动配置钩子示例以Cursor为例 如果自动配置失败你可以手动编辑~/.cursor/hooks.json确保包含类似以下内容具体路径请根据你的安装位置调整{ hooks: { onStart: ~/.tower-island/bin/di-bridge --event session_start --agent cursor --session-id {sessionId} --data-json {\prompt\: \{prompt}\, \workspace\: \{workspace}\}, onToolUse: ~/.tower-island/bin/di-bridge --event tool_use --agent cursor --session-id {sessionId}, onPermissionRequest: ~/.tower-island/bin/di-bridge --event permission_request --agent cursor --session-id {sessionId} --data-json {\path\: \{path}\, \operation\: \{operation}\}, onQuestion: ~/.tower-island/bin/di-bridge --event question --agent cursor --session-id {sessionId} --data-json {\question\: \{question}\}, onPlan: ~/.tower-island/bin/di-bridge --event plan_review --agent cursor --session-id {sessionId} --data-json {\plan\: \{plan}\}, onEnd: ~/.tower-island/bin/di-bridge --event session_end --agent cursor --session-id {sessionId} --data-json {\status\: \{status}\} } }5. 开发、测试与贡献指南5.1 项目结构与代码导读如果你对Tower Island的实现感兴趣或者想为其贡献代码了解其项目结构是第一步。它采用标准的Swift Package Manager结构模块划分清晰Sources/DIShared这是核心的数据协议层。定义了DIMessage枚举包含了所有可能从桥接器发送到主应用的消息类型如sessionStart,toolUse,permissionRequest等及其关联的数据结构。所有模块都依赖于此确保数据模型一致。Sources/DIBridge轻量级命令行工具。它的main.swift函数解析参数构造DIMessage然后通过SocketClient发送给主应用。对于需要响应的消息它会阻塞并等待回复。Sources/DynamicIsland主应用模块。采用经典的SwiftUI AppKit架构。TowerIslandApp.swift应用入口。NotchWindow.swift自定义的NSPanel窗口实现了浮动、置顶、可拖拽等特性。Managers/包含各种管理器是业务逻辑的核心。Models/数据模型如AgentSession。Views/所有SwiftUI视图结构清晰。5.2 运行测试套件项目包含一个强大的bash集成测试套件位于Scripts/目录下。在提交代码前运行测试是强制要求。运行完整测试# 首先确保Tower Island应用正在运行 bash Scripts/test-all.sh # 或者直接运行测试脚本同样要求应用运行 bash Scripts/test.shtest-all.sh脚本通常会先构建应用然后启动它再运行测试。运行特定测试模块 测试被分为多个模块M1, M2, ... Mxx每个模块测试一个特定功能。# 例如只测试消息编码和会话生命周期 bash Scripts/test.sh M1 M2 M3安装Git钩子自动化测试 为了避免忘记运行测试项目提供了Git钩子安装脚本bash Scripts/install-git-hooks.sh安装后每次执行git commit时都会自动触发test-all.sh只有所有测试通过提交才会成功。这保证了代码库的稳定性。5.3 如何添加对新AI代理的支持为Tower Island添加一个新的AI代理支持主要工作是两个方面在AgentType枚举中定义新类型在Sources/DynamicIsland/Models/AgentType.swift中添加一个新的case如case myNewAgent并完善其属性如显示名称、图标等。实现零配置逻辑在ZeroConfigManager中添加检测该代理是否安装的逻辑例如检查特定配置文件或目录是否存在。如果检测到则生成对应的钩子配置字符串并将其写入该代理的正确配置文件中。钩子命令的格式需要遵循该代理的钩子API规范。可选增强窗口跳转如果该代理运行在特定的终端或IDE中并且你希望实现精准跳转可能需要在TerminalJumpManager中添加针对该环境的AppleScript或API调用逻辑。整个过程的关键在于理解目标AI代理的钩子系统如何工作并确保di-bridge被正确调用并传递了必要的参数。5.4 调试技巧查看原始消息在开发时可以临时修改SocketServer或SessionManager的代码将接收到的原始DIMessage打印到控制台这有助于验证桥接器发送的数据是否正确。模拟桥接器调用你可以直接在终端中运行di-bridge命令来模拟一个AI代理事件这对于测试特定功能非常有用。例如~/.tower-island/bin/di-bridge --event session_start --agent cursor --session-id test-123 --data-json {prompt:Test prompt, workspace:~/Projects}使用Console.appmacOS自带的Console应用是查看系统日志和应用程序日志的利器。过滤进程名为“Tower Island”可以看到应用内部的详细日志输出如果项目打了日志的话。Tower Island作为一个开源项目其架构体现了macOS原生开发的优雅和效率。它将一个复杂的多进程通信和状态管理问题通过清晰的模块划分和巧妙的IPC设计简化了。对于使用多AI助手的重度开发者而言它从一个“锦上添花”的工具逐渐变成了提升工作流顺畅度的“必需品”。它的成功在于抓住了“状态聚合”和“原位交互”这两个关键需求并用一个高度契合macOS设计语言的方式实现了出来。如果你也厌倦了在多个终端窗口间疲于奔命不妨试试让Tower Island成为你的AI编程指挥中心。