用途
该技能用于创建和操作单服务器 Basecamp ONCE 部署，配合 Green 使用。它面向 colors.yml 配置、构建、dry-run、资源开通、删除和状态查询等部署工作流。
主要能力
- 使用部署目录中自带的 green 启动器，基于 Babashka 运行，并解析不可变的包依赖。
- 通过 colors-compute 管理单台主机，由该库负责提供商选择、凭据、节点状态和加密 SSH 资源。
- ONCE 负责工作流范围与 agent 生命周期，同时负责应用配置、SMTP、DNS 和 GitHub 发布。
- 将 Basecamp ONCE 固定为 v0.3.3。真实创建会安装 Linux amd64 或 arm64 发布二进制，并校验固定的 SHA-256；当现有二进制不同时会替换。
- 托管后台服务通过 ONCE_NO_SELF_UPDATE=1 禁用二进制自更新，并在二进制或服务配置变化时重启。
- 应用镜像的 auto_update 和备份仍然可用。
- 支持通过 smtp-dmarc-policy 选择性启用 DMARC 管理，包括提供商限制、报告地址、现有记录导入，以及移除管理时保留 DNS 记录。
- 支持 GitHub 持续部署，需参考 github-deploy.md。
使用方式
- 修改期望状态前先阅读 configuration.md。
- 为应用仓库添加持续部署时阅读 github-deploy.md。
- 初始化时保留现有期望状态和不相关文件；复制自带启动器、赋予可执行权限，并用非密钥设置创建或修订 colors.yml。忽略生成输出和私有环境文件。
- 使用 ./green build 和 ./green create --dry-run 进行验证。这些命令不联系提供商，也不证明凭据或实时健康状态。
- 真实创建或删除需要用户授权；若任务已有授权则无需再次询问。
- 使用 ./green describe 查看已记录的 compute 状态和应用检查；它通过库读取 compute，并在 SSH 前要求已验证地址。
- 使用启动器的 ssh 命令进行限定范围的 agent 操作；仅使用裸别名不够。
- 构建产物分别渲染在 .colors/build/<profile>/ 下。
适用场景
- 单服务器 Basecamp ONCE 部署的创建、构建、dry-run、开通、删除和状态查询。
- 需要配置 colors.yml、SMTP、DNS、DMARC 策略或 GitHub 持续部署的场景。
- 需要固定 ONCE 版本并管理单台主机 compute 资源的部署。
限制与注意事项
- 密钥保存在 COLORS_PAR_* 环境变量中；只询问变量名及是否已设置，绝不询问值。不要读取 .envrc.private 或私钥。绝不将生成的 .colors/ 作为源读取或编辑。一次部署只使用一种 color。
- 该包是破坏性的、仅限全新环境的 v2 实现。要求 compute-api-version: 2、全新身份和全新状态根。现有部署保留其固定启动器且不受影响。不要添加迁移、采用或兼容工具。
- 必须提供并安全备份 COLORS_PAR_ONCE_SSH_PASSPHRASE；绝不要替换它以重新生成授权。
- 在期望状态中保持 compute-prevent-destroy: true；已授权的删除可在该次调用中使用 COLORS_PAR_COMPUTE_PREVENT_DESTROY=false。
- 创建会先验证、收敛 compute，然后处理 SMTP、DNS、验证和应用配置。compute 所有权失败会停止后续资源创建。删除会加载已记录的 compute 清单，撤回已发布的凭据和 SSH 配置，移除 DNS 和 SMTP，然后销毁 compute 及任何提供商注册。加密 SSH 授权在 compute 删除后保留。
- 升级二进制不会重建应用容器；v0.3.3 的 BASE_URL 环境变量仅在容器重建时才会到达现有应用。ONCE 版本由包固定，不是 colors.yml 设置。
- 不要向该包添加 compute 模板或提供商分支；更新其依赖以获得提供商支持。
- 若 tofu 缺失，请将 OpenTofu 加入 PATH 后重试。在此仓库中，使用 devenv shell -- green/green ssh。独立启动器需要在其调用 shell 的 PATH 中有 OpenTofu。
- 当 compute 库识别到 Google invalid_rapt 重新认证时，错误会指出该问题并说明如何通过 gcloud auth application-default login 续订本地用户 Application Default Credentials，或通过其自身认证方法续订已配置凭据。ONCE 不会自动启动登录或重试操作。结构化输出保持抑制以保护凭据和状态；若没有可识别的诊断，消息会明确说明无法安全识别底层原因。
- 创建和构建会在远程 Ansible 之前串行化包拥有的 SSH 别名阶段。本地所有权检查失败会停止应用收敛；GitHub 发布保留在远程收敛之后。
- 对于命名了 GitHub 仓库的应用，在添加其工作流前先确认持续部署是否属于用户请求的一部分。确认目标仓库匹配 owner/repo；部署仓库可能是不同的检出。
- 计算命令失败时会报告生命周期阶段、安全命令前缀、解析后的可执行文件和退出状态（若可用），以及经过清理的 stderr。缺少可执行文件、进程启动失败和超时各有不同解释；未知或较旧的诊断保留其原始消息。对于 ssh，连接前失败以 Cannot prepare SSH access 开头。