【免费下载链接】lil-agentstiny AI companions that live on your macOS dock项目地址https://gitcode.com/gh_mirrors/li/lil-agents点击查看免费下载lil-agents 是一款小巧的 macOS 应用让 Bruce 和 Jazz 两个可爱的 AI 伴侣角色住在你的 Dock 上方来回散步点击它们即可打开 Claude Code、OpenAI Codex 等 AI 终端聊天。角色站在 Dock 上就必须时刻感知屏幕环境全屏应用、多显示器、Dock 自动隐藏……每一种场景下角色该出现还是该隐藏这篇文章带你完整读懂 LilAgents/DockVisibility.swift 的判断逻辑以及它是如何做到Dock 自动隐藏时角色依然优雅显示、全屏时自动退场的。问题起点角色站在 Dock 上环境却在不停变化lil-agents 的角色本质是悬浮在 Dock 区域上方的透明动画窗口。这个位置带来一个天然的难题角色的可见区域完全取决于操作系统留给 Dock 的空间。在 macOS 里屏幕有两种关键矩形矩形含义frame整块屏幕的完整物理区域visibleFrame扣除 Dock、菜单栏等系统占用后的可用区域由此可以推出三种典型场景Dock 固定在底部/左右visibleFrame会在对应一侧缩进角色照常站在 Dock 上方全屏应用visibleFrame与frame完全重合Dock 和菜单栏都不可见角色没有立足之地Dock 自动隐藏Auto Hide平时visibleFrame底部不缩进但用户把鼠标滑到底部时 Dock 会浮现——角色此时反而应该显示。第三种场景正是标题里的问题Dock 自动隐藏时角色为什么不该消失核心规则DockVisibility 用两个矩形做出判断全部判断逻辑集中在 LilAgents/DockVisibility.swift一共只有两个静态函数非常精炼。规则一Dock 是否正在占用屏幕空间screenHasVisibleDockReservedArea通过对比两个矩形判断 Dock 是否在底部或左右两侧预留了区域static func screenHasVisibleDockReservedArea( screenFrame: CGRect, visibleFrame: CGRect ) - Bool { visibleFrame.minX screenFrame.minX || visibleFrame.minY screenFrame.minY || visibleFrame.maxX screenFrame.maxX }三个条件分别对应Dock 在左侧、Dock 在底部、Dock 在右侧。只要有一处缩进就说明 Dock 可见角色应当显示。规则二Dock 不可见时还要看三个条件当规则一不成立Dock 没有占用空间时进入shouldShowCharacters的兜底判断let menuBarVisible visibleFrame.maxY screenFrame.maxY return dockAutohideEnabled isMainScreen menuBarVisible也就是说Dock 虽被隐藏但同时满足以下三点角色仍然显示用户开启了 Dock 自动隐藏dockAutohideEnabled当前是主屏幕isMainScreen菜单栏可见visibleFrame.maxY screenFrame.maxY——这条同时排除了全屏应用场景。 为什么这样设计自动隐藏时用户随时可能唤起 Dock角色提前站岗在 Dock 原本的位置等 Dock 滑出时角色恰好在其上方体验无缝衔接而全屏时菜单栏也不可见三个条件不成立角色自然退场。Dock 自动隐藏时角色为何不消失三个关键细节判断公式只是骨架真正的工程价值在 LilAgents/LilAgentsController.swift 的配套细节里。细节一直接读取系统偏好判断自动隐藏开关dockAutohideEnabled()LilAgentsController.swift#L136-L139从com.apple.dock这个系统偏好套件中读取autohide键值private func dockAutohideEnabled() - Bool { let dockDefaults UserDefaults(suiteName: com.apple.dock) return dockDefaults?.bool(forKey: autohide) ?? false }这保证判断结果与系统设置 → 桌面与程序坞 → 自动隐藏与显示程序坞完全一致用户在系统里切换开关后角色行为立刻跟随。细节二小心NSScreen.main这个陷阱多屏用户常遇到一个诡异 Bug点击副屏上的窗口主屏上的角色突然消失。原因藏在这段注释里LilAgentsController.swift#L164-L167// Prefer the screen that currently shows the dock (bottom inset in visibleFrame). // NSScreen.main changes with keyboard focus and must NOT be used here — clicking a // secondary display switches NSScreen.main to that display, causing characters on // the dock screen to be incorrectly hidden.activeScreen的选屏策略是**谁在显示 Dock 就用谁**而不是跟随键盘焦点用户通过菜单栏手动指定了屏幕pinnedScreenIndex→ 锁定该屏幕永远显示角色否则找第一块visibleFrame有 Dock 缩进的屏幕Dock 自动隐藏导致没人占坑时退而求其次——找菜单栏在顶部留了空间的屏幕作为主屏。这套优先级让角色在多显示器、外接显示器、焦点切换时都稳定站在正确的位置。细节三隐藏时记账回来时不穿帮进入全屏时角色被hideForEnvironment()隐藏WalkerCharacter.swift#L191-L202。如果只是一次简单隐藏角色恢复后会出现瞬移——散步进度、思考气泡时间全乱了。showForEnvironmentIfNeeded()WalkerCharacter.swift#L204-L229的处理很巧妙把隐藏掉的时长补偿回所有动画计时器let hiddenDuration CACurrentMediaTime() - hiddenAt walkStartTime hiddenDuration pauseEndTime hiddenDuration completionBubbleExpiry hiddenDuration lastPhraseUpdate hiddenDuration隐藏前角色在散步退出全屏回来后它恰好从应该走到的位置继续走对话气泡的时间戳也不会错乱。对用户来说就像角色去趟洗手间又自然地走回来一样。用单元测试把每种屏幕场景钉死这套可见性逻辑配了一份完整的测试Tests/DockVisibilityTests.swift。它用一个 1440×900 的虚拟屏幕覆盖了 6 种组合场景场景期望行为Dock 固定在底部✅ 显示角色Dock 固定在左侧✅ 显示角色Dock 固定在右侧✅ 显示角色全屏Dock 与菜单栏均不可见❌ 隐藏角色自动隐藏开启 主屏 菜单栏可见✅ 显示角色自动隐藏开启 副屏❌ 保持隐藏测试通过Tests/main.swift直接驱动运行任何一个分支被改坏都会立刻在 CI 中暴露——这正是纯几何 纯布尔设计的好处核心逻辑与 UI 彻底解耦可以脱离屏幕直接验证。小结从 DockVisibility 学到的多屏适配思路lil-agents 处理 Dock 自动隐藏与多屏问题的思路对任何需要在特定屏幕区域安家的 macOS 应用都有参考价值能用系统事实就不用猜测Dock 缩进量、autohide开关都是操作系统给出的确定信号直接消费即可把核心判断抽成纯函数DockVisibility不依赖任何 UI只比较两个矩形因此可测试、可复用警惕隐式APINSScreen.main跟随键盘焦点的语义在多屏下是隐蔽的 Bug 源显式按显示 Dock 的屏幕选择更可靠隐藏不等于消失把隐藏时长补偿回动画状态角色回归时体验才连贯。想继续深入可以看看角色窗口与动画的实现 LilAgents/WalkerCharacter.swift、整体调度与 Dock 几何计算 LilAgents/LilAgentsController.swift以及项目说明 CLAUDE.md。lil-agents 遵循 MIT 协议源码结构清晰非常适合作为 macOS 多屏适配的学习样本。赞分享【免费下载链接】lil-agentstiny AI companions that live on your macOS dock项目地址https://gitcode.com/gh_mirrors/li/lil-agents点击查看免费下载相关推荐lil-agents 代码原理如何精准计算 Dock 几何并让角色无缝行走lil agents 代码原理如何精准计算 Dock 几何并让角色无缝行走 lil agents 是一款运行在 macOS Dock 上方的微型 AI 陪伴应智能隐藏功能深度解析Dash to Dock如何自动躲避窗口Dash to Dock是GNOME桌面环境中最受欢迎的扩展之一它的智能隐藏Intellihide功能让dock栏能够自动躲避窗口为用户提供更加流畅的桌桌面应用如何在Steam Deck上玩安卓游戏SteamOS-Waydroid-Installer 一键装好安卓系统如何在Steam Deck上玩安卓游戏SteamOS Waydroid Installer 一键装好安卓系统 Steam Deck 想玩安卓游戏怎么办Ste创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考