macOS 安装与快速上手
苹果电脑版（macOS）已正式发布：Apple 芯片与 Intel 双版本，界面、AI 面板与全部内置工具完整可用。本文覆盖从下载、安装、系统授权，到升级、备份、排错的全部内容——按顺序读完，零踩坑。
急着用？三步走：① 确认芯片 → ② 下载对应包、解压后双击「首次启动.command」→ ③ 打开后完成两项系统授权。细节都在下面。
一、先确认你的电脑（30 秒）
打开 屏幕左上角的苹果菜单 → 关于本机，看两项：
| 看什么 | 在哪里 | 怎么选 |
|---|---|---|
| 芯片 | 「芯片」一栏 | Apple M1/M2/M3/M4… → 下载 arm64 包；Intel Core / i5 / i7 / i9 / Xeon → 下载 x64 包 |
| 系统版本 | 「macOS」一栏 | 需要 macOS 11 (Big Sur) 或更高；更老的系统请先升级系统 |
二、下载
官方链接（浏览器直接打开，自动就近节点加速，点开即下）：
- Apple 芯片（M 系列）：https://gh555.com/dl/qqqide-mac-arm64
- Intel 芯片：https://gh555.com/dl/qqqide-mac-x64
两个链接都是「稳定别名」，永远指向最新发布版，可以收藏。下载约 260 MB，解压后约 1.1 GB，安装过程中建议预留 3 GB 磁盘空间。
无需预先安装 Python、git 等任何东西——运行所需的全部组件都已内置。
三、安装（首次三步）
第 1 步：解压
双击下载的 qqqide-mac-arm64.tar.gz（Intel 为 qqqide-mac-x64.tar.gz），macOS 会自动解压出同名文件夹，里面包含：
qqqide.app—— 主程序qqqide-data/—— 数据与运行组件（全部在这里）首次启动.command—— 一键启动脚本（首次必用）README-使用说明.txt—— 同内容的简要说明
第 2 步：把整个文件夹移到固定位置
建议移到「应用程序」或任意长期保留的位置（不要留在「下载」里，容易被随手清理）。
⚠️ 必须整个文件夹一起移动：
qqqide.app和qqqide-data是搭档，必须保持在同一层。只把qqqide.app单独拖出来 = 应用找不到自己的数据。 建议放在本地磁盘，避免放进 iCloud / 网盘同步目录（大目录同步可能造成异常）。
第 3 步：双击「首次启动.command」
第一次启动请双击 「首次启动.command」（而不是直接双击 app）。它会自动完成三件事：
- 移除下载隔离标记 —— 系统不再把 qqqide 当「来路不明」的下载拦截；
- 创建本地签名证书（仅第一次）—— 只在你电脑本地生成，不联网、不需要苹果账号；它让系统「认得」这个应用，使系统授权在以后升级时无需重设；
- 签名并启动 qqqide——首次签名约 1–2 分钟。
窗口里会滚动输出进度文字，完成后自动打开应用。以后日常启动就简单了：直接双击 qqqide.app。
若双击「首次启动.command」提示"无法打开"：这是对下载脚本的一次性保护——右键点它 → 选「打开」→ 在弹窗里再点一次「打开」。 喜欢终端：
cd到解压出的文件夹，执行bash "首次启动.command"，可在终端看到完整日志。
首次打开可能遇到的弹窗（逐个说明）
- 「"qqqide" 想访问"桌面"文件夹」 → 点「允许」。编辑器、文件浏览需要读取你打开的文件；其他文件夹的弹窗同理；
- 安静地直接打开 → 正常，继续；
- 没走脚本、直接双击了 app 并提示「无法验证开发者」 → 点「取消」，改用「首次启动.command」；或到 系统设置 → 隐私与安全性 → 拉到底部 → 点「仍要打开」。
万一被误报"已损坏"（别慌，也千万别删）
个别情况下（下载中断、第三方解压工具差异），双击可能弹出「qqqide.app 已损坏，无法打开。你应该将它移到废纸篓」——这是系统对「已签名但未公证」应用的误报，不是真损坏，不要点"移到废纸篓"。按顺序处理：
- 先跑一次「首次启动.command」（多数情况直接解决）；
- 仍报错：打开「终端」，执行（把路径换成你的实际位置）：
xattr -dr com.apple.quarantine ~/Applications/qqqide-mac-arm64/qqqide.app然后重新双击启动脚本；
- 还是不行：截图发我们（见第九节）。
四、系统授权（首次一次，升级不重设）
应用打开后，有两个功能需要 macOS 的隐私授权（这是 macOS 的安全设计，Windows 不需要；不授权 = 对应功能不可用，不是故障）：
| 功能 | 需要的授权 | 授权路径 |
|---|---|---|
| 窗口编队全局热键（按住空格 + 1/2/q/w/a/s/z/x 召回窗口） | 输入监控 | 系统设置 → 隐私与安全性 → 输入监控 |
| 窗口布局工具（悬停窗口连按 3 次 W / X） | 辅助功能 | 系统设置 → 隐私与安全性 → 辅助功能 |
操作步骤：
- 打开对应面板，在列表里找到 qqqide 并勾选；
- 列表里没有 qqqide → 点面板下方的 ➕，在弹出的选择框里选择你的
qqqide.app； - 两个都勾好后，完全退出 qqqide（菜单
Cmd+Q）再重新打开一次，授权即生效。
升级后要重新授权吗？ 不需要——本地签名证书让系统始终认识你的 qqqide；同一台电脑上升级版本、换新包，授权都保留。（仅换电脑、重装系统、手动删过证书时需要重勾一次。） 小提示：授权完成后，请不要再移动 app 的位置（移动后系统可能重新询问）。
五、认识界面（快速上手）
首次打开会有「我是专家…同意并继续」确认框，点「同意并继续」进入。
主界面分四块：左侧 A 区（内置工具：搜索 / git / 终端 / Roam 文件中枢等）、中间 X 区（编辑器）、右侧 AI 面板（可开左右翼变为三面板）、顶部菜单栏。
- 语言：自动跟随系统语言（支持 13 种），也可点顶栏的语言按钮手动切换；
- 登录：AI 对话与计费需要账号——点界面上的「登录」，按提示在浏览器里完成，完成后应用自动同步登录状态。
macOS 版与 Windows 版能力一致，这几项特别提一下：
- 内置终端 kmd：支持 zsh / bash 双标签页（qmd 为 Windows 专有的全交互终端，macOS 上自动隐藏；需要 vim/top 这类全交互程序时请用系统终端）；
- Finder 复制 → 直接粘贴：访达里复制文件后，可直接粘贴进编辑器与 Roam；
- 状态栏内存 / CPU 监控：实时显示整个启动包的资源占用；
- 窗口编队、3W/3X 窗口布局、剪贴板历史（kope-a）等组件全部就位。
推荐继续读：
六、升级到新版本
macOS 版更新 = 整包替换，数据完全保留：
- 从第二节的链接下载最新版；
- 解压出新文件夹；
- 用新包里的
qqqide.app和qqqide-data/engines覆盖你目录里的同名项（先在访达里把旧的删除再拖入新的，确保没有新旧混杂）； - 双击（新包里的）「首次启动.command」（证书已存在，这一步很快）。
⚠️
qqqide-data/Data目录不要动——那是你的全部数据；升级只换qqqide.app+qqqide-data/engines两件。 升级后一般无需重新授权（见第四节）；若系统重新询问，重新勾选一次即可。
七、数据、备份与卸载
| 位置 | 内容 | 说明 |
|---|---|---|
qqqide-data/（与 app 同级） | 全部应用数据 + 运行组件 | 备份 = 复制它；换电脑迁移也只带它（连同 app 一起） |
~/Library/Application Support/qqqide/ | 系统级偏好（窗口编队、搜索与浏览历史等） | 可选备份 |
| 钥匙串「钥匙串访问」 | 本地签名证书「qqqide Local Sign」 | 无需备份；删除它系统会重新询问授权 |
卸载：退出 qqqide → 把整个文件夹移到废纸篓；想更彻底：再删 ~/Library/Application Support/qqqide，并把「钥匙串访问」里的 qqqide Local Sign 删除。
隐私说明：qqqide 只读写你主动打开、授权访问的文件夹；上述目录之外不会碰你的文件。
八、排坑大全（按症状查）
1. 双击「首次启动.command」没反应或提示"无法打开"
右键 →「打开」→ 再点「打开」。仍不行：终端执行 chmod +x "首次启动.command" 后再双击。
2. 双击 app 提示"已损坏" 见第三节「万一被误报已损坏」——先跑「首次启动.command」，不要点"移到废纸篓"。
3. 提示"无法验证开发者" 系统设置 → 隐私与安全性 → 拉到底 →「仍要打开」；或改用「首次启动.command」启动。
4. 双击后一直没出现窗口
首次启动需要 1–2 分钟（签名 + 初始化 + 后台补齐组件）且需要联网，先耐心等等；超过 5 分钟：把 qqqide-data/Data/Logs/ 下 bootstrap.log 的最后几行发我们。
5. 按住空格 + 1（或 q / w / …）没有召回窗口 ① qqqide 是否正在运行；② 「输入监控」是否已勾选（第四节）且重启过一次 qqqide；③ 用法是「按住空格不放，再按一下槽位键」；④ 第 9 个及以后没有编队的窗口无法召回。
6. 悬停窗口连按 3 次 W / X 没反应 ① 「辅助功能」授权（第四节）；② 要悬停在非当前焦点的窗口上；③ 是「快速连按 3 次」，不是长按。
7. 左侧工具显示"未启动"（kope-a / window-there）
点旁边的开关按钮；或重启一次 qqqide（首次启动时组件可能稍晚自动拉起）。持续失败：把 qqqide-data/Data/Logs/ 里的 goods-*.log 发我们。
8. AI 面板 / 登录 / 页面内容加载不出来（网络像是断的） 先检查 系统设置 → 网络 → 代理：如果开着「指向本机 / 局域网某端口」的代理，而那个代理软件（加速类工具等）又没在运行，请把代理关掉再试。这是最常见的网络干扰源。
9. 界面上的快捷键写的是 Ctrl，我按 Cmd 行吗？ 行。Ctrl 与 Cmd 是等效的（界面统一显示为 Ctrl）。
10. 首次启动后没声音 检查系统音量与输出设备；应用内也有音量开关。
11. 装错了芯片版本会怎样？ 启动会直接报架构不符、无法打开，换另一个包即可。M 系列请用 arm64（用 Rosetta 运行 x64 包会明显变慢，不推荐）。
12. 下载到一半断了 / 解压报错 重新下载即可（解压失败通常是文件不完整）。两个下载链接支持断点续传与就近加速。
13. macOS 10.15 及更老的系统能装吗？ 暂不支持，需要 macOS 11 或更高版本。
14. 打开后界面异常，或提示找不到数据
检查 qqqide.app 与 qqqide-data 是否在同一文件夹里——如果曾被分开移动过，把它们放回同一层再启动。
15. 想反馈问题，需要提供什么？ 见第九节。
九、反馈与日志
反馈问题时请附上（越全越好）：
- 整屏截图（含菜单栏）；
- 关于本机截图（芯片 + 系统版本）；
- 日志：
qqqide-data/Data/Logs/下的bootstrap.log、_py_broker.log、goods-*.log； - 崩溃报告（如闪退）：访达 → 前往 → 前往文件夹 → 输入
~/Library/Logs/DiagnosticReports，取最新的 qqqide / Electron 相关文件。
通过官网 gh555.com 的联系方式发给我们。