CompozyOS桌面应用部署指南：macOS与Linux安装、自动更新与深度链接配置-育师

CompozyOS桌面应用部署指南：macOS与Linux安装、自动更新与深度链接配置

【免费下载链接】compozyAn operating system for AI agents. Plug in the agent CLIs you already use (Claude Code, Codex, Gemini CLI, Cursor) and they become a team: they split the work, hand tasks to each other, run automated on jobs and loops, and share one project memory. You steer everything from the browser.项目地址: https://gitcode.com/gh_mirrors/co/compozy

CompozyOS是一个面向 AI 智能体的"操作系统"：把你已经在用的智能体 CLI（Claude Code、Codex、Gemini CLI、Cursor 等）接入同一个守护进程，让它们组队分工、互相交接任务、跑定时作业与循环（Loops），并共享一份项目记忆，全部操作都可以通过浏览器或桌面端完成。本指南带你完成CompozyOS 桌面应用部署，覆盖 macOS 与 Linux 的安装、自动更新机制和深度链接配置。

📦 桌面端与安装方式总览

CompozyOS 的桌面壳基于 Electron 构建（见 desktop/package.json），它内嵌了 Go 编写的守护进程二进制，首次启动时会自动完成运行时引导，连接本机的compozy守护进程，因此你只需要一次安装，即可获得完整的"桌面应用 + 守护进程 + Web 控制台"体验。

当前 v0.3 处于 beta 阶段，推荐两种安装方式：

方式	命令	适用场景
官方安装脚本	`curl -fsSL https://compozy.com/install.sh \\| sh`	macOS / Linux，自动校验 Sigstore 来源
NPM 全局安装	`npm install -g @compozy/cli@beta`	已有 Node 环境的用户

⚠️ 注意：Homebrew 配方在 v0.3 beta 期间仍停留在已弃用的 v0.2 线，详见 docs/release/homebrew-beta-notice.md。compozy官方配方将在 v0.3.0 正式版回归。

也支持从源码构建桌面端（仓库克隆地址：https://gitcode.com/gh_mirrors/co/compozy）：

git clone https://gitcode.com/gh_mirrors/co/compozy cd compozy make dev

🍎 macOS 一键安装步骤

macOS 发布产物为dmg与zip两种格式，定义在 desktop/electron-builder.yml 中：

DMG：标准双击安装，适合普通用户；
ZIP：供自动更新流程使用，更新时会校验包内 zip 完整性（校验逻辑见 desktop/src/release/mac-zip.ts 与 desktop/scripts/verify-mac-update-zip.ts）。

安装后首次启动会触发以下引导流程：

解析用户主目录下的~/.compozy作为运行目录（路径解析逻辑见 desktop/src/home.ts）；
启动内嵌的compozy运行时二进制，写入app.json、app.sock、app.token等应用记录；
打开产品窗口，通过控制通道与守护进程通信。

macOS 构建启用了加固运行时（hardenedRuntime），并使用 asar 完整性校验，安全性开箱即得。

🐧 Linux 最快安装方法

Linux 发布产物为AppImage与deb（见 desktop/electron-builder.yml 的linux段）。一个值得注意的细节：构建配置启用了静态 AppImage 运行时，这意味着你的机器无需再安装 libfuse2这类系统依赖，下载即可运行。

AppImage：下载后赋予可执行权限，直接双击运行，适合不想污染系统的用户；
deb：sudo dpkg -i CompozyOS-*.deb，适合希望纳入包管理器管理的用户。

Linux 下桌面应用的可执行名为compozyos，桌面快捷方式名会自动与桌面文件同步（syncDesktopName: true）。

🔄 CompozyOS桌面应用自动更新机制

桌面端内置了完整的自动更新消费者，核心实现在 desktop/src/update/app-update-consumer.ts。对普通用户来说，你只需要知道它"稳"：

看门狗超时：安装应用阶段有 10 分钟看门狗、安装器交接阶段有 5 分钟看门狗，超时会自动接管处理，避免更新卡死；
租约续期：更新过程中每 30 秒续租一次，防止多个更新操作互相踩踏；
失败自愈：如果安装中断，下次启动会进入"恢复安装"或"静默失败"分支，自动修复到一致状态；
版本校验：下载完成后会比对版本号，不匹配的包会被直接拒绝。

更新包通过通用发布源（publish.provider: generic，见 desktop/electron-builder.yml）分发，频道清单由 desktop/scripts/prepare-channel-manifests.ts 生成。发布流水线必须按desktop-build → desktop-smoke → desktop-publish的顺序执行并全部通过，流程说明见 docs/release/v0.3-single-cut.md。

🔗 深度链接配置：一键直达任意页面

CompozyOS 桌面端注册了自定义协议，让你可以从浏览器、终端或其他工具一键唤起桌面应用并直达指定页面：

环境	协议方案	示例
正式版	`compozyos`	`compozyos://open/sessions/abc?tab=logs`
开发版	`compozyos-dev`	`compozyos-dev://open/tasks`

协议解析与安全校验实现在 desktop/src/deep-links/deep-link.ts，要点：

只接受compozyos://open<路径>形式的链接，并保留查询参数；
恶意路径全部拒绝：http://、//evil.com、../遍历、空字符等都会安全回退到默认视图（测试覆盖见 desktop/src/deep-links/tests/deep-link.test.ts）；
最新链接获胜：应用就绪前连续收到的多个深度链接，只消费最后一条，避免窗口连环跳转；
启动参数中的深度链接只取最后一个，方便compozyos://open/tasks <应用路径>这类命令行用法。

实际使用场景：把compozyos://open/sessions/<会话ID>放进书签或脚本，即可从任意地方"召唤"出对应的会话页面。

✅ 部署验证与常见问题排查

安装完成后，用以下三条命令验证运行状态（结构化 JSON 输出便于脚本消费）：

compozy status # 查看守护进程状态 compozy version # 确认版本号 compozy doctor -o json # 全面体检

常见问题速查：

问题	排查方向
桌面端启动后无法连接守护进程	确认`~/.compozy/app.json`与`app.sock`是否存在（见 desktop/src/home.ts）
查看启动日志	`~/.compozy/logs/desktop-bootstrap.jsonl`与`desktop.log`
更新失败	检查`~/.compozy/update-operation.json`中的操作状态
端口冲突	用`COMPOZY_HOME`环境变量指定隔离目录，再启动
深度链接无反应	确认使用的是正式版（`compozyos`）而非开发版（`compozyos-dev`）协议