JustinGamer191/Holo

# Holo Holo 是一款实验性的原生 macOS 实用工具，可以将 MacBook 周围的桌面立刻变成四个可分配的点击区域。它通过选定的 Mac 麦克风进行监听，从短暂的脉冲窗口中提取声学特征，在本地对区域进行分类，并执行分配给该区域的操作。 这种拓扑结构特意设定为四个广泛的区域： ``` Display side Left Rear ┌─────────────┐ Right Rear │ MacBook │ Left Front └─────────────┘ Right Front Trackpad side ``` Holo 是一个研究原型。自动化的 DSP 测试已经通过，但其实际可用性仍必须在每台真实的 MacBook、桌面、房间以及笔记本电脑的摆放位置上进行测量。如果没有保存来自该设置的 60 次点击评估记录，则不作出任何物理准确性的声明。 逐项要求的验证记录位于 [ACCEPTANCE.md](ACCEPTANCE.md) 中。 ## 已实现的功能 - 四个固定区域：MacBook 两侧的后部和前部区域。 - 显式武装的校准：每个区域包含十个被接受的样本，总计 40 个，针对微弱、嘈杂或削波的点击提供明确的重试指导。 - 校准一致性检查，可识别并能在保存前重新校准最弱的区域。 - 自适应流式起始检测、持续声音抑制以及固定的 90 毫秒分析窗口。 - 被动点击声学、可选的主动声学探测以及混合模式。 - 稳健的特征归一化，由最近样本新颖性检查、歧义拒绝、分布外拒绝和可选的负样本支持的经过正则化的线性区域模型。 - 每个配置文件对应的操作：仅可视化、播放声音、复制或朗读文本、打开网站、运行快捷指令、打开应用程序或项目、执行 shell 命令或捕获屏幕截图。新区域默认设为仅可视化，直到用户分配了具体的副作用。 - 引导式的 60 次点击留出评估，包含各区域准确率、延迟、拒绝的点击数和混淆矩阵。 - 保存的评估历史会在重新启动后恢复，并限定在生成它的桌面配置文件范围内。 - 信号诊断、带标签的特征捕获、方法比较、JSON/CSV 报告以及可选的原始调试 WAV 捕获。 - 沙盒化，本地持久化。默认情况下会丢弃原始音频。 - Core Audio 路由验证要求每种模式都使用内置麦克风，并且主动或混合感知需要使用内置扬声器。 ## 系统要求 - macOS 14 或更高版本。 - 推荐使用 Xcode 26 来处理当前项目。该应用在 macOS 26 上使用 Liquid Glass 按钮样式，在较旧的受支持系统上使用原生的带边框控件。 - [XcodeGen](https://github.com/yonaskolb/XcodeGen) 用于从 `project.yml` 重新生成 `Holo.xcodeproj`。 - 一台选中了内置麦克风的 MacBook。外部输入会被拒绝，而不是默默地改变已校准的信号路径。 - 主动和混合感知还需要选择 MacBook 扬声器作为输出设备。被动感知不会发出探测音。 ## 构建 在更改 `project.yml` 后生成 Xcode 项目： ``` xcodegen generate ``` 然后打开 `Holo.xcodeproj`，选择 `Holo` scheme，并在 My Mac 上运行它。新安装的应用在校准开始或用户明确按下“继续”时会请求麦克风权限；它不会仅仅因为窗口打开就弹出提示。 启动 Holo 时，请使用 Xcode 常规的 **Sign to Run Locally** 构建。`CODE_SIGNING_ALLOWED=NO` 仅用于非 GUI 验证；其精简的 bundle 缺少音频输入权限，不应被启动。本地的临时签名构建在其二进制文件发生更改后可能仍需要再次征得同意；选择 Apple Development 团队可在每次重新构建时为 macOS 提供稳定的签名身份。在一次构建中，Holo 会合并并发的麦克风启动和授权请求，并且其 bundle 禁止应用程序重复运行实例。 非签名的命令行构建适用于 CI 或本地验证： ``` xcodebuild \ -project Holo.xcodeproj \ -scheme Holo \ -configuration Debug \ -derivedDataPath /tmp/HoloDerived \ CODE_SIGNING_ALLOWED=NO \ build ``` ## 校准 1. 将 MacBook 放置在使用期间保持不变的位置。移动或旋转它会改变声学路径并使配置文件失效。 2. 打开校准并描述桌面、表面和 MacBook 的位置。 3. 除非“诊断”已经在完全相同的设置上比较过各种方法，否则请保持选中“被动点击声学”。 4. 开始校准。Holo 会自动准备并武装高亮显示的区域。 5. 等待“准备中”变为“监听中”，然后进行十次自然点击，期间稍微停顿一下。将点击分布在发光区域周围，而不是重复点击一个精确的点。 6. 微弱、被掩盖或削波的点击不会被添加；Holo 会解释是需要更用力敲击、等待安静，还是使用更轻的力度。 7. 在接受十个样本后，该区域会解除武装。在短暂的过渡期间移动到下一个高亮显示的区域；Holo 会自动武装它。在过渡期间发出的声音会被忽略。如果监听已暂停，恢复后请使用可见的“武装”控制。 8. 如果最新样本不一致，使用“撤销”或对该区域使用“重做”。 9. 查看留一法校准一致性。如果结果较弱，在保存前重做识别出的区域。 10. 保存 40 个样本的配置文件并分配其四个操作。 在四个区域完成后，说话、打字、触摸笔记本电脑和房间噪音可以被收集为负样本。建议收集说话样本：正常说话几秒钟，Holo 将仅记录通过冲击门的声音峰值。负样本不需要通过“干净点击”质量门是有意为之的。除非单独启用了原始调试记录，否则仅保留其特征向量。 来自过时的六区域和九区域拓扑的配置文件会被有意忽略。请重新校准，而不是尝试将旧样本重新解释为新的物理区域。 在校准、准确性测试或感知比较处于活动状态时，不相关的侧边栏目标和配置文件切换将被禁用。请先取消或完成引导式捕获。暂停麦克风会解除所有待处理的捕获，包括拒绝训练。切换配置文件绝不会重新开启已暂停的麦克风；只有显式开始引导式捕获才会恢复它。 ## 分配操作 操作包含按侧分组的精确四行。更改会在进行时保存到选定的配置文件中，并且每个配置好的操作都有一个内联的测试按钮。 - 仅可视化会高亮显示接受的区域，而不产生副作用。 - 播放声音使用可用的 macOS 系统声音。 - 复制文本将配置的文本写入粘贴板。 - 朗读文本使用本地语音合成器。 - 打开网站接受 HTTP 或 HTTPS 地址。 - 运行快捷指令通过系统快捷指令 URL scheme 打开指定的快捷指令。 - 打开或聚焦应用为用户选择的应用程序存储一个应用作用域的安全书签。 - 打开文件或文件夹为用户选择的项目存储一个应用作用域的安全书签。 - 运行 shell 命令通过 `/bin/zsh` 在 Holo 的沙盒权限下执行配置的命令。 - 屏幕截图到剪贴板捕获整个显示器，而不保存文件。 - 选择屏幕截图到剪贴板调用标准的交互式区域选择工具。 只有在选中“桌面”并且分类被接受时，操作才会运行。校准、配置文件编辑、诊断、准确性报告和操作编辑器会抑制自动副作用；编辑器的内联“测试”按钮保持显式。被拒绝、有歧义、微弱、削波或分布外的事件不会触发任何操作。分配后，shell 命令会自动运行，因此命令应该可以安全重复，且不应依赖于交互式终端。当操作首次打开受保护的项目或捕获屏幕时，macOS 可能会请求访问权限。快捷指令是组合多步骤工作流的推荐方式，例如打开 Claude 并启动用户自定义的语音流程。 ## 支持的表面 实际目标是稳定、坚硬的桌面，点击会在这种桌面上产生可重复的共振：实木、工程木、层压板和类似坚硬的表面是最佳候选者。玻璃、金属、空心、非常大、机械耦合或严重阻尼的桌面属于实验性的，需要建立它们自己的测量配置文件。软垫、移动的笔记本电脑支架以及在正常使用下会发生移动的桌面不在受支持的假设范围内。 支持程度由在确切设置上完成的准确性测试决定，而不是仅仅依靠材料名称。没有任何桌面材料被宣布为全局支持。 ## 评估 评估独立于校准，并使用新的点击。它引导每个区域进行十五次点击，总计 60 次。每个区域必须武装，防止在用户准备好之前将移动和界面声音计入其中。在武装状态下发出的检测事件即使被分类器拒绝也会被包含在内；因此，被拒绝的点击被计为不正确。响应延迟的计算从音频点击缓冲区的单调 `AVAudioTime` 主机时间戳开始，贯穿特征提取、主线程交接和分类过程。 原型验收目标是： - 在均衡的 60 次点击会话中，总体准确率至少达到 80%。 - 中位数响应延迟低于 200 毫秒。 - 在 30 分钟的运行期间没有崩溃或无限内存增长。 应用程序将每次完成的评估保存为 JSON 和 CSV。报告包括各区域的准确率、4x4 混淆矩阵、被拒绝的列、置信度和响应延迟。重新启动后会恢复所选配置文件的最新保存报告；来自另一桌面的报告绝不会作为当前结果显示。来自过时拓扑的报告将被跳过。如果任何一个文件无法保存，屏幕会将该结果标记为仅内存。无效的主机时钟时间戳将被导出为 `INVALID` 并阻止达到延迟目标。校准交叉验证仅作为诊断显示；它不能替代留出评估。 ## 感知方法 被动点击声学是默认方法，不会播放声音。特征提取器结合了时间形状、频带、log-mel/MFCC 风格的系数，以及选定输入通道暴露的任何空间差异。 主动声学探测每 120 毫秒发出一次低振幅 15.5–21 kHz 啁啾声，并增加响应相关特征。混合结合了这两种特征集。笔记本电脑扬声器、麦克风、采样率、听觉范围和桌面几何形状各不相同，因此探测可能会被过滤、无效或隐约可听。绝不假设它优于被动感知。 在捕获开始之前，Holo 会读取默认的 Core Audio 输入/输出传输类型。内置麦克风是强制性的；主动和混合还需要内置扬声器输出。违反此策略的路由更改会立即停止捕获和探测。 当扬声器探测处于活动状态时，底部状态栏会明确显示。 起始检测从 0.75 秒的房间学习期开始，然后在要求短暂、高对比度起始的同时调整其本底噪声。第二道门会审查完整的 90 毫秒候选项，并拒绝其有效持续时间、滞后能量和早期微弱集中度明显类似于持续语音的事件。被拒绝的持续事件在其不应期内也会更新自适应下限，防止对话反复重新武装捕获。单独的低通路径可防止高频探测触发自身的捕获。接受的窗口保留未触碰的全频带通道，用于主动响应特征提取。 诊断可以为每种方法在每个区域收集三次点击——总计 36 个样本——并比较留一法准确率和 DSP 处理延迟。每一组都是显式武装的。测量到的最高分数将成为下次校准的建议策略，但该结果绑定于测量它的桌面配置文件，不能暗中影响另一个配置文件。 ## 架构 ``` AVAudioEngine input → adaptive impulse detector → 90 ms multichannel window → full-event impact / sustained-sound gate → passive / active feature extraction → regularized zone model + nearest-example rejection gates → accepted four-zone decision → local action dispatcher ``` - `Sources/HoloCore` 包含引导式捕获协议、检测器、FFT 和特征提取、分类器、持久化模型、诊断、评估报告和 WAV 写入器。它没有 SwiftUI 依赖。 - `Sources/HoloApp` 包含音频捕获、应用状态、本地操作调度和原生 SwiftUI 界面。 - `Sources/HoloSoak` 是一个非 GUI 的合成 DSP 压力测试运行器。 - `Sources/HoloRouteCheck` 是对当前 Core Audio 输入/输出传输策略的非 GUI 检查。 - `Tests/HoloCoreTests` 涵盖引导式会话总数和顺序、引导式捕获质量门、自适应房间噪声抑制、麦克风请求合并、分块检测器到分类器的流水线、注入的主动探测恢复、共享频谱分析、硬件路由策略、经过验证的本地操作计划、负样本和歧义拒绝、评估历史、严格的配置文件持久化、WAV 输出以及精确的四区域拓扑。 每个检测到的窗口使用一个共享的功率谱进行分类、主动响应频段和诊断，而不是重复进行相同的 FFT。捕获生成会丢弃由已经停止的音频路由或策略排队的观察结果。 界面原理和源研究位于 [DESIGN.md](DESIGN.md) 中。核心规则是系统材料和 Liquid Glass 支持导航和控件；它们不是内容的装饰。桌面映射使用两条连续的双区域轨道，而不是四个悬浮卡片。UI 有意避免使用霓虹渐变、便当盒式的指标卡片、过多的圆角容器、无用指标以及持续的装饰性运动。 ## 隐私和存储 音频处理在 Mac 上进行。Holo 不会上传音频、特征、配置文件或报告。当然，分配的网站或应用程序操作可以打开相应的外部目标。 默认情况下： - 检测器仅保留足够用于预卷和一个 90 毫秒分析窗口的内存音频。 - 原始窗口在特征提取后被丢弃。 - 配置文件存储特征向量和分类器参数，而不是录音。 - 调试记录在每次启动默认处于禁用状态。 Holo 仅使用一个应用程序窗口，因为只有一个麦克风引擎和一个引导式会话状态。关闭该窗口会终止 Holo，防止麦克风捕获在没有应用内活动指示器的情况下继续进行。 当在“诊断”中启用“保留 90 毫秒调试记录”时，每个检测到的窗口都会以 float WAV 格式保存在本地，直到用户将其删除。在保留功能启用时，UI 会显示持久的红色隐私警告。如果重新启动后仍有捕获的记录，橙色的“已保存音频”指示器和删除控件将保持可见，即使此时新的音频正在被丢弃。 Application Support 包含： ``` Holo/Profiles/ feature-only profile JSON Holo/Evaluations/ JSON and CSV evaluation reports Holo/approach-comparison.json latest sensing comparison Holo/DebugCaptures/ opt-in raw WAV windows only ``` 由于应用程序是沙盒化的，在正常的签名构建中，这些路径位于 Holo 的应用程序容器内。 ## 自动化验证 在 macOS 26.5.2 上进行的最新自动化检查： - Debug 和 Release 应用构建：通过，无源代码警告。 - 静态分析器：通过。 - 单元测试：68 个通过，0 个失败，0 个跳过。 - 在生产置信度阈值下加速混合四区域合成压力测试：0.8 秒内处理 5,000 个事件；4,500/4,500 个区域点击正确，500/500 个微弱、嘈杂、削波、schema 不匹配或分布外的挑战被拒绝；零错误接受；RSS 6.7 → 7.0 MB (+0.3 MB)。 - 早先的全正向 30 分钟合成挂钟压力测试：17,186 个事件；17,186 个正确，0 个被拒绝，0 个错误；RSS 6.7 → 6.4 MB (−0.3 MB)。这早于当前的四区域拓扑，仅作为历史稳定性证据予以保留。 - 只读路由检查：MacBook Pro 麦克风和 MacBook Pro 扬声器均报告为内置；被动、主动和混合模式准备就绪。 运行单元测试套件： ``` xcodebuild \ -project Holo.xcodeproj \ -scheme Holo \ -configuration Debug \ -derivedDataPath /tmp/HoloDerived \ CODE_SIGNING_ALLOWED=NO \ test ``` 无需打开 GUI 即可构建并运行合成压力测试： ``` xcodebuild \ -project Holo.xcodeproj \ -scheme HoloSoak \ -configuration Release \ -derivedDataPath /tmp/HoloSoakDerived \ CODE_SIGNING_ALLOWED=NO \ build DYLD_FRAMEWORK_PATH=/tmp/HoloSoakDerived/Build/Products/Release \ /tmp/HoloSoakDerived/Build/Products/Release/HoloSoak --duration 1800 ``` 合成运行器会测试特征提取、分类、拒绝门、有限值检查和驻留内存行为。它不测试 AVAudioEngine、麦克风权限、真实的房间噪音、物理桌面变异性或操作调度。 无需打开 Holo 或请求麦克风权限即可检查当前的内置硬件路由： ``` xcodebuild \ -project Holo.xcodeproj \ -scheme HoloRouteCheck \ -configuration Debug \ -derivedDataPath /tmp/HoloRouteDerived \ CODE_SIGNING_ALLOWED=NO \ build DYLD_FRAMEWORK_PATH=/tmp/HoloRouteDerived/Build/Products/Debug \ /tmp/HoloRouteDerived/Build/Products/Debug/HoloRouteCheck ``` ## 已知限制 - 配置文件特定于一台 MacBook、表面、房间布局和笔记本电脑位置。Holo 拒绝外部输入设备，因为它们会改变感知路径。 - 内置麦克风 API 可能会暴露一个聚合通道，而不是独立的物理阵列元件。 - 柔软、不稳定、非常大、严重阻尼或嘈杂的表面可能无法产生可分离的区域。 - 短促的辅音、打字、触摸笔记本电脑、掉落的物体以及附近的撞击可能类似于点击。持续声音门和特定于配置文件的负样本可减少误报，但无法保证完全没有。 - 校准质量取决于一致的自然点击。UI 会防止未武装的声音被添加，但它无法得知用户是否点击了预期的物理位置。 - 主动探测是实验性的，在某些硬件上可能会被过滤或听见。 - 80% 和 200 毫秒的目标仍必须通过针对每个目标设置的真实留出会话来证明。 - 自动化压力测试结果不能替代在目标 Mac 上进行的 30 分钟实时麦克风和操作调度运行。 ## 在声明原型已验证之前 对于每种受支持的 Mac/桌面组合： 1. 在具有代表性的安静和嘈杂环境中运行诊断。 2. 在最终的 MacBook 位置校准所有四个区域。 3. 运行一次全新的均衡的 60 次点击评估，并保留其 JSON/CSV 报告。 4. 确认总体准确率至少达到 80%，中位数响应时间低于 200 毫秒。 5. 运行实时应用 30 分钟，进行具有代表性的点击、对话、打字、触摸笔记本电脑和背景噪音，同时监控崩溃、误触发和内存。 在这些物理检查完成之前，应将 Holo 描述为功能性的实验软件，而不是经过验证的声学输入设备。

标签：Apex, macOS原生应用, 人机交互, 效率工具, 敲击检测, 机器学习, 音频信号处理