Quileg HID文档 · 随安装包分发
运行方式：常驻与退出
关窗为什么不退出、自启动怎么工作、什么算「忙」。
适用：Quileg HID 0.5.0+。相关：
app/README.md（界面，源码仓库）、MCP 接入说明（MCP-SETUP.md）
App 同时是设备控制台和AI 的 MCP 接口，所以窗口只是它的一部分。这里定义 「窗口 / 进程 / 服务」的关系，以及关窗、退出、登录启动的行为。
1. 三层模型
| 层 | 内容 | 关窗 | 退出 |
|---|---|---|---|
| 服务 | hidagent :8890、UxPlay、板子 TCP 7300、MCP | 不动 | 停 |
| 窗口 | 镜像、设备、日志 | 隐藏 | 关 |
| 入口 | GUI、HIDBridge --mcp（宿主拉起） | 不受影响 | --mcp 独立进程 |
结论：关窗 ≠ 退出。默认点红叉只是把窗口收起来，服务继续跑。
2. 设置项与默认值
⌘, → 运行方式：
| 设置 | 选项 | 默认 | 生效 |
|---|---|---|---|
| 开机时自动启动 | 开 / 关 | 关 | 保存时写/删 LaunchAgent |
| 启动时 | 显示窗口 / 仅后台启动 | 显示窗口 | 下次启动 |
| 关闭窗口时 | 留在后台（Dock）/ 每次询问 / 直接退出 | 留在后台 | 立即 |
| 退出确认 | 仅在忙时 / 总是 / 从不 | 仅在忙时 | 立即 |
首次隐藏会弹一次说明「仍在后台运行」，之后不再弹（
hide_hint_shown）。
3. 行为矩阵
| 操作 | 空闲 | 忙 | 刷固件 |
|---|---|---|---|
| 红叉 | 隐藏窗口 | 隐藏窗口（不打断） | 拒绝 |
⌘Q / 文件→退出 | 直接退出 | 弹确认，列出原因 | 拒绝 |
| 点 Dock 图标 | 恢复窗口 | 恢复窗口 | — |
| 登录启动 | 不显示窗口（--background） | — | — |
| 第二次启动 | 唤醒已有实例后退出 | 同左 | — |
退出确认文案会列原因，例如：
退出 Quileg HID？
现在退出会打断：
· 板子已连接
· AI 最近 12 秒有操作
退出后会停止 MCP 接口、投屏和板子连接。
[继续运行] [仍然退出]4. 什么算「忙」
core/lifecycle.py: busy_reasons()：
- 板子已连接（
/api/status的device） - 正在投屏（
screen） - iPhone 键鼠已连接（
ble.connected=1） - AI 任务在跑（
agent.running） - 最近 90 秒有动作类 API 调用（
last_action_age，服务端只统计POST /api/*， 不把 GUI 自己的GET /api/status、/api/frame.jpg轮询算进去） - 操作队列有正在执行/排队
- 校准或设备初始化窗口开着
刷固件是硬阻塞：_flashing 时红叉和 ⌘Q 都直接拒绝。
5. 开机自启动
- 写入
~/Library/LaunchAgents/com.huijiang.hidbridge.plist：ProgramArguments = [<App 可执行文件>, --background]、RunAtLoad=true、KeepAlive=false； launchctl bootstrap gui/$UID/bootout生效；- 仅安装版可用（源码运行没有稳定可执行路径，复选框会禁用）；
- 移动 App 后重新开一次设置保存即可重写路径；关闭开关会删 plist。
6. 单实例
- GUI 启动时对
~/Library/Application Support/HIDBridge/gui.lock加flock； - 拿不到锁 → 认为是第二次启动：
open已有 App（触发tk::mac::ReopenApplication显示窗口）后退出； - 锁随进程退出自动释放，不需要清理；
HIDBridge --mcp不走这把锁，允许多个 MCP 宿主各自拉起。
7. 还没做（P2）
菜单栏常驻（NSStatusItem、无 Dock 图标）需要 PyObjC/Swift 桥和额外的签名/公证回归， 当前先用 Dock 图标；需要时再加「显示窗口 / 设备状态 / 退出」菜单。
8. 验收
- [ ] 红叉 → 窗口消失、Dock 图标在、
:8890仍可访问；点 Dock 恢复 - [ ] 空闲
⌘Q→ 直接退出，8890/7300释放 - [ ] 板子连接时
⌘Q→ 弹确认，取消后窗口还在、服务没断 - [ ] 刷固件时红叉/
⌘Q→ 拒绝 - [ ] 开自启动 → 重启后后台起服务、不弹窗口；关闭后 plist 消失
- [ ] 连点两次启动 → 只有一个进程
本页内容与安装包内文档同源，版本见 VERSION.txt。未在页面上展示的细节，可在 Releases 页下载的 DMG 中找到完整原文。