Linux 安装与快速上手

Linux 版（x64）已发布：界面、AI 面板与全部内置工具完整可用。本文覆盖从下载、安装，到升级、备份、排错的全部内容——按顺序读完，零踩坑。

急着用？三步走：① 确认是 64 位系统 → ② 下载、解压出 qqqide 文件夹 → ③ 在终端里运行 首次启动.sh。细节都在下面。

一、先确认你的系统（30 秒）

本版本面向 64 位（x86_64）Linux 桌面：

看什么	怎么确认	怎么选
架构	终端执行 `uname -m`	显示 `x86_64` → 可以安装；显示 `aarch64` → 暂不支持（后续版本）
发行版 / 库版本	终端执行 `ldd --version`	glibc 2.28 或更高（Ubuntu 20.04+ / Debian 11+ / 主流新版发行版均满足）；已在 Ubuntu 24.04 实机验证

无需预先安装 Python、git 等任何东西——运行所需的全部组件都已内置（含文件管理器可选的 libxcb-cursor0，首次启动会自动补装）。

二、下载

官方链接（浏览器直接打开，自动就近节点加速，点开即下）：

Linux x64：https://gh555.com/dl/qqqide-linux-x64

这是「稳定别名」，永远指向最新发布版，可以收藏。下载约 235–250 MB，解压后约 1.1 GB，建议预留 3 GB 磁盘空间。

三、安装（首次三步）

第 1 步：解压

在下载目录执行：

tar -xzf qqqide-linux-x64.tar.gz

解压后你会得到一个 qqqide 文件夹——安装包自带这层文件夹：无论用什么工具、解压到哪里，都只会解出这一个文件夹，程序与数据永不散落。里面包含：

qqqide —— 主程序
qqqide-data/ —— 数据与运行组件（全部在这里）
首次启动.sh —— 一键启动脚本（首次必用）
安装桌面图标.sh —— 可选：把 qd (qqqide) 加进应用菜单
README-使用说明.txt —— 同内容的简要说明

第 2 步：把整个文件夹移到固定位置

建议移到 ~/Applications 或任意长期保留的位置（不要留在 下载 里，容易被随手清理）。

⚠️ 必须整个文件夹一起移动：qqqide 与 qqqide-data 是搭档，必须保持在同一层。建议放在本地磁盘，避免放进同步盘目录（大目录同步可能造成异常）。

第 3 步：运行「首次启动.sh」

在终端里执行（推荐，能看到完整过程）：

cd qqqide
bash 首次启动.sh

任意位置运行也可以；在文件管理器里双击选择「在终端中运行」同样有效。

首次启动它会自动完成三件事（每一步都会提示，需要一次管理员密码用于系统级修复）：

补装系统依赖 —— libxcb-cursor0（界面组件需要；已安装则自动跳过）；
修复浏览器沙箱权限 —— 给 chrome-sandbox 设置一次性的 root 权限（Linux 解压归档文件会丢失这一位，修好后长期有效）；
启动 qd (qqqide)。

以后日常启动：直接运行文件夹里的 ./qqqide，或者先跑一次「安装桌面图标.sh」，之后在应用菜单里搜索 qqqide 启动。

想装进应用菜单：bash 安装桌面图标.sh —— 会在应用列表里创建 qd (qqqide) 入口（卸载即删除 ~/.local/share/applications/qqqide.desktop）。

首次打开可能遇到的情况

第一次启动稍慢（数秒到十几秒）：正在初始化本地运行环境，正常；
没有出现窗口：先等待约 10 秒；仍无窗口见第八节排坑；
首次打开会有「我是专家…同意并继续」确认框，点「同意并继续」进入。

四、系统权限说明

与 macOS 不同，Linux 不需要任何系统隐私授权——窗口编队全局热键（按住空格 + 1/2/q/w/a/s/z/x 召回窗口）与窗口布局工具（悬停窗口连按 3 次 W / X）开箱即用，无需勾选任何面板。

说明：应用与内置组件统一使用 X11（XWayland）兼容层运行——在 Wayland 桌面（GNOME / KDE 默认）上由系统自动提供，剪贴板、全局热键等功能均正常工作，无需手动切换会话。

五、认识界面（快速上手）

主界面分四块：左侧 A 区（内置工具：搜索 / git / 终端 / Roam 文件中枢等）、中间 X 区（编辑器）、右侧 AI 面板（可开左右翼变为三面板）、顶部菜单栏。

语言：自动跟随系统语言（支持 13 种），也可点顶栏的语言按钮手动切换；
登录：AI 对话与计费需要账号——点界面上的「登录」，按提示在浏览器里完成，完成后应用自动同步登录状态。

Linux 版与 Windows / macOS 版能力一致，这几项特别提一下：

内置终端 kmd：支持 bash / zsh 标签页（qmd 为 Windows 专有的全交互终端，Linux 上自动隐藏；需要 vim/top 这类全交互程序时请用系统终端）；
文件管理器复制 → 直接粘贴：在文件管理器里复制文件后，可直接粘贴进编辑器与 Roam；删除文件默认移入系统回收站（可还原）；
状态栏内存 / CPU 监控：实时显示整个启动包的资源占用；
窗口编队、3W/3X 窗口布局、剪贴板历史（kope-a）等组件全部就位——键盘玩法详见窗口编队与窗口布局。

推荐继续读：

六、升级到新版本

当前 Linux 版通过整包替换升级（数据完全保留）：

从第二节的链接下载最新版；解压出新的 qqqide 文件夹；
用新包里的程序文件覆盖你目录里的旧程序（主程序 qqqide、resources/、lib*.so、locales/ 等；qqqide-data 整个目录不要动）；
直接启动（沙箱与依赖修复已生效过，无需重跑首次脚本）。

⚠️ qqqide-data/Data 目录是你的全部数据；升级只换程序目录内容。应用内自动更新将在后续版本提供——届时像 Windows / macOS 版一样，升级全程无需手动操作。

七、数据、备份与卸载

位置	内容	说明
`qqqide-data/`（与主程序同级）	全部应用数据 + 运行组件	备份 = 复制它；换电脑迁移也只带它（连同程序一起）
`~/.local/share/qqqide/`	系统级偏好（窗口编队、搜索与浏览历史等）	可选备份
`~/.local/share/kope-a/`	剪贴板历史（kope-a）	可选备份

卸载：退出 qd (qqqide) → 删掉整个 qqqide 文件夹；想更彻底：再删 ~/.local/share/qqqide 与 ~/.local/share/kope-a。

隐私说明：qd (qqqide) 只读写你主动打开、授权访问的文件夹；上述目录之外不会碰你的文件。

八、排坑大全（按症状查）

1. bash 首次启动.sh 提示权限不足 / 无法执行 执行 chmod +x 首次启动.sh 后再运行；或在文件管理器里选择「在终端中运行」。

2. 首次启动时 sudo 提示要密码 沙箱修复需要一次管理员权限（chown root + chmod 4755）。输入你的登录密码即可（输入时不显示字符，正常）。没有 sudo 权限的账号会在提示后以降级模式启动，界面功能不受影响。

3. 提示缺少 libxcb-cursor0 / 界面组件起不来 首启脚本会自动补装（Debian / Ubuntu：sudo apt-get install -y libxcb-cursor0；Fedora：sudo dnf install xcb-util-cursor；Arch：sudo pacman -S xcb-util-cursor）。

4. 运行后一直没出现窗口 ① 首次启动需要数秒初始化，先等等；② 终端里看有没有报错输出；③ 把 qqqide-data/Data/Logs/ 下 boot.log 的最后几行发我们。

5. 左侧工具显示"未启动"（kope-a / window-there） 点旁边的开关按钮启动；或重启一次 qd (qqqide)。持续失败：把 qqqide-data/Data/Logs/ 里的 goods-*.log 发我们。

6. 按住空格 + 1（或 q / w / …）没有召回窗口 ① qd (qqqide) 是否正在运行；② 用法是「按住空格不放，再按一下槽位键」；③ 第 9 个及以后没有编队的窗口无法召回；④ 完整玩法见窗口编队与窗口布局。（Linux 无需任何系统授权。）

7. 悬停窗口连按 3 次 W / X 没反应 ① 要悬停在非当前焦点的窗口上；② 是「快速连按 3 次」，不是长按；③ 完整玩法见窗口编队与窗口布局。

8. AI 面板 / 登录 / 页面内容加载不出来（网络像是断的） 先检查系统代理设置：如果开着「指向本机 / 局域网某端口」的代理而代理软件没在运行，请把代理关掉再试。这是最常见的网络干扰源。

9. 界面上的快捷键写的是 Ctrl，有其它版本吗？ Linux 上就是 Ctrl（与 Windows 一致；macOS 版对应 Cmd）。

10. 首次启动后没声音 检查系统音量与输出设备（pavucontrol 等）；应用内也有音量开关。

11. 双击程序没反应 / 提示无法执行 到终端里运行 ./qqqide，观察报错输出；多数情况是文件丢失了可执行位——执行 chmod +x qqqide 后再试。

12. 我的发行版不是 Ubuntu 能用吗？ 可以。要求：x86_64 + glibc 2.28+，桌面在 X11 / XWayland 下运行。已在 Ubuntu 24.04 完成全链验证；其他主流发行版请把遇到的问题反馈给我们。

13. Wayland 会话下功能正常吗？ 正常。应用与内置组件统一走 XWayland（系统自动提供），剪贴板、热键、窗口管理均工作。

14. 想反馈问题，需要提供什么？ 见第九节。

九、反馈与日志

反馈问题时请附上（越全越好）：

整屏截图；
系统信息：终端执行 uname -a 与 cat /etc/os-release 的输出；
日志：qqqide-data/Data/Logs/ 下的 boot.log、_py_broker.log、goods-*.log；
启动输出：从终端直接运行 ./qqqide 时打印的内容（如有）。

通过官网 gh555.com 的联系方式发给我们。

安装与快速上手