返回 项目首页。以下说明对应当前实现；开发过程中的验收记录另见 首版验证记录。
内置 3.5mm 智键的 macOS 菜单栏程序：为单击、双击和长按绑定键盘、多媒体、脚本或快捷指令动作，触发时用玻璃气泡显示动作名称，按下时右下角出现按压缩罩。需要 macOS 26。
开发运行：
swift run smartKey安装到 /Applications（release 打包、本机 ad-hoc 签名、注册登录项并启动）：
./scripts/install-app.sh只打包、不安装或启动：./scripts/build-app.sh，产物位于 .build/release-app/smartKey.app。
App 图标使用黑白圆环与圆点，资源位于 packaging/AppIcon.icns，菜单栏使用随系统外观适配的单色符号。修改图标几何后，运行 swift scripts/generate-app-icon.swift 重新生成 SVG、1024 像素 PNG 和包含各尺寸的 ICNS，再重新打包或安装。
从菜单栏打开「设置…」（⌘,），左侧为通用、动作配置、脚本管理。采用原生 macOS 设置窗口和公开 Liquid Glass API。已获辅助功能授权时，关闭设置后菜单栏程序继续运行；未授权时关闭最后一个窗口即退出。
每次启动若缺少辅助功能权限，都会进入授权引导。该权限用于发送键盘组合键、媒体控制等动作；应用统一要求获得辅助功能授权后才允许修改动作配置、管理脚本及执行动作。普通 Shell 脚本本身并不必然需要此系统权限，这里采用统一的应用功能门槛。「开始使用」在授权前不可点击。未授权时不创建菜单栏；只显示授权引导时不启动设备监听，直接关闭引导即退出应用。点击「打开通用设置」会先打开设置，再关闭引导；设置窗口可见期间正常监听设备插拔和音频变化，通用面板中的设备模式、音频输出和暂停动作等操作仍可使用。未授权时关闭或最小化设置即停止这一设备会话，重新打开窗口后重新读取当前连接与音频列表。此时可切换查看灰色的动作配置和脚本管理页面，页面中的按钮、编辑、导入及执行入口均禁用，保留页面滚动和脚本列表浏览，已保存的脚本与绑定保留。关闭最后一个设置窗口即退出，不留后台进程。运行中权限消失时，移除菜单栏并取消正在运行的动作；设置窗口可见时保留设备状态更新，没有可见窗口时显示通用设置，避免无界面驻留。权限恢复后自动解锁并启动菜单栏及设备监听，下一次启动仍缺权限时再次引导。
输入监控不作为启动前提，也不会因未授权而在设置页显示申请入口。仅在线控实际访问因权限被拒绝时弹出申请窗口；暂不授权或关闭后，同一次缺权状态不重复询问，重启后也保留此记录。授权恢复后若再次丢失，须再次发生实际访问阻碍才会重新询问一次。打包和安装脚本会写入新的安装标识，以重新计算输入监控的一次询问机会，但仍须先出现访问阻碍。设置页仅在检测到输入监控已授权时显示其状态；拒绝、未授权、授权消失时均隐藏。
点击「去授权…」只请求系统显示授权确认弹窗，由用户在系统弹窗中选择打开系统设置；应用不会自行提前跳转。若系统未显示弹窗，可另行点击「未看到弹窗？手动打开设置…」。在系统设置中开启“智键”或“smartKey”；列表中没有应用时可点击“+”添加。引导和「通用」页会自动刷新权限状态，也支持手动刷新。若系统要求退出并重新打开，请按提示操作。--settings-preview 不显示启动授权引导。
- 三种手势分别选择一个动作或「无」。初次运行全部为无，不产生未配置的系统操作；空绑定不弹动作气泡，按压缩罩保留。
- 每个动作名称最多 12 个计数单位，中文占 2 个单位。键盘/快捷指令的显示名称可修改，媒体使用操作名称，脚本名称同步用于绑定及气泡。气泡仅显示动作名称；运行状态和实际结果可在设置中查看。
- 键盘支持单键和组合键，点击录制后输入快捷键；测试时有 3 秒切换目标应用的时间。需要辅助功能授权，不自动授予系统权限。
- 多媒体支持播放/暂停、上一首、下一首、音量增减、输出静音。播放指令交给系统媒体路由；音量/静音要求当前输出设备支持对应软件控制，不代表麦克风静音。
- 双击绑定非空时自动开启，清空时自动关闭，
doubleClickEnabled自动同步为1/0。开启后单击等待双击窗口；关闭后单击松开即判定。此字段由绑定管理，不再作为独立用户开关。 - 长按到阈值执行一次，松开不补发单击，长按为空也不会回退触发单击。配置变更从下一个完整手势生效。
- 保留低频操作冷却，被冷却忽略的手势不排队。暂停动作会保留当前设备模式和音频保护。
脚本管理支持新建、拖入/导入、重命名、复制、删除和导出。导入复制到脚本库，不修改原文件；界面提供只读源码预览；编辑通过「使用默认应用打开」交给系统默认纯文本编辑应用，找不到时回退到 TextEdit。智键不内置源码编辑器。外部保存后自动刷新，试运行和物理触发均读取磁盘上最新保存的内容；未保存的编辑不会执行。
运行设置支持 zsh/bash、工作目录、环境变量和超时。首版后台非交互运行，同时最多一个脚本，不排队重复启动；支持停止、退出码和限量标准输出/错误。打开外部编辑器不会触发智键的运行器；「运行」与动作「测试」会真实执行脚本。
名称、说明、绑定、运行参数保存在 ~/Library/Application Support/smartKey/actions.json；脚本副本位于 Scripts/<UUID>/script.sh。导出的 .smartkeyscript 包包含内容与元信息，排除环境变量；普通 .sh 导出只包含内容。
详细运行语义、环境、版本恢复和源码扩展方式见 动作开发说明。
在「动作配置 → 选择动作」中选择「执行快捷指令」，展开列表选择本机快捷指令、设置显示名称和等待超时后保存。每次展开列表都会自动刷新；「打开快捷指令」仅启动系统快捷指令 App，无需先选择指令。绑定使用系统 ID，重命名不会改为执行同名指令；删除或未同步时保留原绑定，需刷新或重新选择。完整指令名称不受智键显示名称长度限制。
首版不传入额外内容，使用当前用户权限调用 macOS 自带的 /usr/bin/shortcuts。首次运行可能出现系统授权，交互式指令会等待用户输入。试运行会真实执行快捷指令。
同时最多一个由智键发起的快捷指令，重复触发不排队，与脚本各自独立。等待超时默认 300 秒，可设置 1–3600 秒；退出码 0 表示系统报告运行成功，错误详情可在执行结果中查看。停止等待、超时或退出智键只回收本地命令进程，快捷指令可能仍在系统中运行，必要时到快捷指令 App 检查。
布局与手势配置在 ~/Library/Application Support/smartKey/smartKey.conf。首次启动若该文件不存在，会把当前出厂配置写进去；之后启动会把模板里的新键和注释合并进去，已有取值不覆盖（双击开关由动作绑定管理）。改完保存即热更新，不必重启。仓库根目录的 smartKey.conf 只作出厂模板。
- 启动检查已插入的内置 3.5mm 设备，同时监听后续插拔。检测到插入时，右下角先播放黑色遮罩动画，再延迟显示设备类型选择气泡；时长见
insertionMaskDurationMs/insertionPopupDelayMs。 - 每次启动检测到设备或重新插入设备都进入设备选择流程。设置窗口可见且未最小化时，新流程嵌入「通用 → 设备」，否则使用右下角弹窗。流程开始后不切换容器：弹窗过程中打开设置仍在弹窗完成；关闭或最小化设置不会为设置内的待完成流程重新弹窗。设备类型焦点落在上次确认的选项上（首次默认为智键，跨启动持久化），超时按当前焦点项继续，时长见
deviceChoiceTimeoutMs。 - 选择「音频设备」时，如当前默认输出不是 3.5mm 耳机孔，则切换到该端口并读回确认；不独占、不响应智键线控。切换失败可重试。
- 配置音频输出前先排除 3.5mm 设备：仅剩一个可用输出时，跳过选择页并自动切换，读回确认后进入独占；多个输出时显示选择页，无可用输出时提示连接设备。自动切换失败或超时会返回选择页，等待用户重试。
- 音频选择采用系统原生「名称 / 类型」双列表格，设备列表随连接状态更新。列表不显示耳机端口，需选择内建扬声器、蓝牙、USB 等其他输出。点击「使用此设备」调用后端
SmartKeyService.setDefaultOutput(uid:)，读回确认后才调用setRemoteEnabled(true)。这里使用现有 Swift 公共接口，无需额外网络端口；只修改默认音频输出，不修改输入设备。 - 音频输出选择（弹窗和设置内一致）进入选择阶段时重新计满
deviceChoiceTimeoutMs，超时使用当时列表中的第一个可用输出（不使用历史预选或尚未确认的选中行）。0 关闭自动选择。列表为空时暂停倒计时，有输出重新出现后计满一次；切换失败后等待手动重试，不循环自动重试。关闭或最小化设置时，设置内的待选步骤立即按超时处理：设备类型使用当前焦点项，随后若需选择音频输出则立即使用第一项，不转成弹窗；即使配置为 0 也执行此次明确的超时处理。空列表保持等待，有设备出现后继续处理；正在进行的切换继续等待读回，切换失败后不自动重试。重新打开设置接续状态，不重启倒计时。 - 切换失败、没有其他音频设备时保留音频选择页。HID 连接错误使用独立提示，区分设备占用、访问被拒绝和等待设备；等待超过 5 秒显示提示，但继续发现设备，迟到的设备仍可自动恢复。支持重试和取消，取消仅停用智键，不切回耳机孔，也不回滚已成功的音频切换。
- 配置成功且 HID 独占成功后才接收按键。独占对象为
Transport=AudioConsumer Control，键盘 / 蓝牙 / USB 媒体键不会误触发。 - 拔出设备立即释放独占、关闭提示并取消倒计时；再次插入重新选择。工作期间后端守卫监听默认输出：若被切到 3.5mm 耳机孔，立刻拉回本次运行记录的最后合法输出并保持独占；该设备已不可用或切换失败时，暂停智键并进入音频选择流程，按新流程开始时的设置窗口可见状态选择容器。
- 菜单栏提供状态、「设置…」、「暂停/恢复动作」、「登录时打开」和「退出」。可在「设置 → 通用」切换设备类型。登录项注册仅对
/Applications中的应用副本生效，首次启动会尝试注册（系统设置 → 通用 → 登录项）。手动切换设备模式后，若进入音频输出选择，同样开始自动选择倒计时。 - 所有提示和遮罩优先显示在可用的内置屏幕，即使外接屏幕被设为主显示器。内置屏幕不可用时退回
CGMainDisplayID()对应的主显示器，不跟随鼠标或前台窗口。 - 设备类型和音频输出共用同一个弹窗，宽度统一使用原设备选择页的
setupChoiceWidthPt（默认 380 pt，另有两侧各 12 pt 的透明留白），设备选择页使用紧凑高度，音频输出页按表格高度预留空间。进入音频输出页时，保持宽度及底边位置不变，以约 240 毫秒动画向上拉高；开启系统“减少动态效果”时直接调整高度。窗口四边限制在屏幕可见区域内，内容过长时内部滚动。设置内采用常驻布局：上方始终保留设备模式切换，下方始终显示音频输出表格、状态和操作按钮。智键连接成功后可直接更换输出；未连接或普通音频设备模式下，表格保留但不可操作。已有弹窗流程期间设置内禁用重复操作。背景使用固定的系统背景色，与原生列表和按钮保持一致。 - 不推断“拔掉智键后”的系统输出。首次配置时，当前或本次运行中记录到的非耳机孔输出仅用于预选，多个输出时等待手动确认或倒计时结束；激活后切到耳机孔则由守卫静默拉回最后合法输出，不写入 conf。
- 气泡显示已绑定动作的短名称。下一次物理触发使用
bubbleRetriggerMs冷却（默认 20 ms，冷却期内的触发直接忽略）；触发新动作时，旧气泡立刻从当前位置收回，新气泡正常出现。每个气泡独立动画，执行器不依赖气泡窗口创建成功。试运行不受物理手势冷却影响。 - 黑色遮罩只跟按下 / 松开，与气泡是否在场无关。
- 手势、插入动画、选择超时和配置窗口尺寸见用户
smartKey.conf。用户上次选择的设备类型不写入 conf，由程序单独持久化。 - 卸载：取消「登录时打开」，再把
/Applications/smartKey.app移到废纸篓。
swift test 覆盖设备选择与输出守卫、手势会话、绑定/配置恢复、脚本包、外部保存、脚本超时/取消/大输出/进程组清理，快捷指令列表解析、按 ID 执行、失败/超时/重复触发，以及设置页面渲染。默认测试使用模拟设备与临时脚本，不修改真实音频路由或独占硬件；渲染结果输出到 /tmp/smartKey-*.png。实际插拔、媒体路由、系统授权、锁屏/恢复和按键仍需设备验收，详见 首版验证记录。
如果系统默认选中 Command Line Tools 且找不到 Testing 模块，可使用已安装的完整 Xcode：
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift testHID 回归测试（先退出正在运行的智键，包括 /Applications 那份；会短暂独占内置 Audio 线控三次，不切换音频路由）：
SMARTKEY_HID_INTEGRATION=1 DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test --filter realHIDCanRestartThreeTimes本机对照验证：旧实现第一次启动为 seized，第二、三次为 waiting；新实现三次均为 seized，停止后均为 idle。修复采用每次新建 HID 管理器、independentDevices 下单独独占设备、初始枚举补取及 common run-loop 模式；按键物理动作仍需单独验证。