CompozyOS：把 AI 代理从终端会话变成常驻服务

一个为代理准备的系统层，而不是又一个 CLI 包装

CompozyOS 解决的问题很具体：让 AI 代理像服务一样持续运行，而不是在终端里跑完一次就结束。README 说得很直白：任何人都能提示一个代理，但让代理持续工作仍然是工程问题，循环、触发器、cron、记忆、权限、审批、可观测性，还有把这些粘在一起的胶水脚本。CompozyOS 把这些堆栈打包成一个产品，一个守护进程，一个状态模型。它面向开发者和技术运营者，而不是普通用户。这个定位意味着它要求你理解守护进程、配置文件和权限模型，不是开箱即用的玩具。

守护进程是唯一的事实源，客户端只是视图

核心机制是 home-scoped daemon。人和代理通过公共控制面发送命令，守护进程解析工作区，应用权限和运行时策略，协调 ACP 代理，并持久化事件和资源状态。Web 和流式客户端读取的是守护进程拥有的真相，而不是维护一个并行模型。这意味着你关闭终端，会话和 Loop 运行不会消失，它们属于守护进程。这种设计解决了代理工作的持久性问题，但也引入了新的运维负担：你需要管理守护进程的生命周期。命令很直接：compozy daemon start、compozy status、compozy daemon stop。状态可以通过 -o json 输出，或者 HTTP/SSE、UDS、MCP 访问，方便其他程序集成。

配置的优先级和所有权，容易踩坑的地方

配置分三层：全局默认在 ~/.compozy/config.toml，工作区可以覆盖部分字段，通过 .compozy/config.toml。显式命令行标志优先于工作区配置，工作区配置优先于全局配置和内置默认。这个优先级链很清晰，但 README 特别警告：配置、凭据和 provider-home 策略有不同的所有者，不要复制 v0.2 的状态到 v0.3 的 home。这意味着升级不是拷贝文件，而是重新理解每个配置项的归属。实际操作时，用 compozy config path 查看位置，compozy config validate 检查有效性，compozy config show -o json 查看生效值。如果你从 v0.2 迁移，必须先读 MIGRATION_GUIDE.md，否则可能把旧配置带入新运行时，导致权限或凭据错位。

代理定义是可复用的对象，而不是每次重写的脚本

代理定义放在 ~/.compozy/agents/<name>/ 或 .compozy/agents/<name>/，每个定义包含 AGENT.md，还可以有 agent-local 的 mcp.json。工作区定义会整体覆盖全局定义，这意味着你不能部分覆盖，只能整体替换。设计上，代理是对象，你可以反复使用，而不是每次运行都重新写提示。命令 compozy agent list -o json 查看所有代理，compozy agent info general -o json 查看特定代理，compozy session new --agent general 启动新会话。这个模型让团队可以共享代理定义，但覆盖规则需要小心，一个工作区覆盖全局定义后，其他工作区不受影响，但如果你期望继承部分属性，这个设计会让你失望。

扩展系统：代码优先，但资源型扩展也可以

扩展通过声明的 provide surface 添加版本化资源和运行时行为。守护进程拥有发现、启用、信任决策、生命周期和钩子，扩展不能绕过公共运行时契约。构建一个扩展只需要三个命令：compozy extension init hello --template tool-provider-go 初始化，compozy extension dev hello 开发，compozy tool invoke ext__hello__search --workspace . --input '{"query":"compozy"}' 调用。可执行扩展是代码优先的，你在代码里声明一次工具，compozy extension build 生成清单。资源型扩展可以手写 extension.toml，不运行代码。SDK 有 npm 包 @compozy/extension-sdk 和 Go 包 github.com/compozy/compozy/sdk/go，版本与守护进程匹配。这个模型把扩展限制在显式契约内，减少了失控风险，但也意味着扩展不能做运行时允许范围之外的事。

本地优先的默认，但远程访问需要显式开启

CompozyOS 默认本地优先，一个 Go 二进制和 SQLite 存储，运行时状态留在操作者的机器上，除非配置了外部 provider 或扩展。远程访问通过 Gateway 实现，它配对设备，只暴露操作者启用的私有或公共表面。这意味着默认情况下，代理工作不会离开你的机器，这符合隐私和合规需求。但如果你需要团队协作或远程管理，必须主动配置 Gateway，这不是自动的。这种设计权衡很明确：安全默认，但增加了配置复杂度。Compozy Network 协议让会话可以发现对等节点、交换类型化消息、委托工作并用收据关闭，但这也是需要显式启用的功能。

任务 Schema v2：迁移是硬性的，不是可选的

v0.3 引入了 Task Schema v2。任务文件仍然是可移植的 Markdown，带类型化 frontmatter。但 v0.3 运行时把它们导入为持久任务，并通过 Loops 执行，它不会恢复 v0.2 的 tasks run 管线。这意味着如果你有 v0.2 的任务文件，不能直接运行，必须迁移。README 明确指向 MIGRATION_GUIDE.md，里面有确切的 schema 和命令变化。这是一个真实的断裂性变更，不是平滑升级。如果你在生产环境中依赖 v0.2 的任务自动化，迁移成本可能不小。另外，v0.3 是 beta，v0.2.15 产品已废弃，只维护关键修复在 legacy/v0.2 分支。Homebrew 公式在 beta 期间继续服务 v0.2，但 v0.3 稳定版发布后才会恢复。

安装途径和版本陷阱

安装方式有几种，但都有版本陷阱。官方安装脚本 curl -fsSL https://compozy.com/install.sh | sh 会固定最新 beta 并验证 Sigstore 来源。NPM 安装 npm install -g @compozy/cli@beta 需要显式 beta 标签。Go 安装时，go install github.com/compozy/compozy@<release-tag> 必须指定标签，因为 @latest 仍解析到 v0.2 稳定版。从源码构建是 git clone 然后 go build -o ./bin/compozy .。这个混乱的版本状态是 beta 期的正常现象，但如果你不仔细看文档，很容易装到旧版本。安装后，用 compozy daemon start 启动守护进程，然后 compozy status 检查状态。

编辑结论

CompozyOS 适合那些已经在使用 ACP 兼容代理 CLI，并且希望把代理工作从临时终端会话升级为可审计、可自动化的常驻任务的开发者和技术运维。它不适合只想要一个简单提示工具的人，也不适合不愿意维护一个守护进程和相关配置的用户。在采用之前，先确认你使用的代理 CLI 是否在官方支持的 ACP 兼容列表内，并阅读 MIGRATION_GUIDE.md，因为 v0.3 是 beta，且 v0.2 的 tasks run 管线已被移除，任务文件需要迁移。如果你需要远程访问，必须明确配置 Gateway，因为默认是本地优先，远程能力不会自动开启。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes