deploying-laravel-cloud 是 Laravel 官方 agent-skills 中的一项部署技能，用于通过 cloud CLI 部署和管理运行在 Laravel Cloud 上的 Laravel 应用。
【用途】 当用户希望部署应用、发布到云端、创建或管理 Laravel Cloud 资源时使用。它覆盖从首次上线到日常运维的完整流程，并强调在不确定用户需求时先询问，而非直接执行命令。
【安装与鉴权】 安装：composer global require laravel/cloud-cli 鉴权：cloud auth -n。cloud auth 会打开浏览器；无法打开浏览器时，可设置环境变量 LARAVEL_CLOUD_TOKEN（会覆盖已保存的令牌，且不写入磁盘）。也可保存令牌：cloud auth:token --add --token=<token> -n，或管道方式：echo "$TOKEN" | cloud auth:token --add -n。
【命令模式】 命令遵循 CRUD 模式：resource:list、resource:get、resource:create、resource:update、resource:delete。可用资源包括 application、environment、instance、database-cluster、database、cache、bucket、domain、websocket-cluster、background-process、secret、command、deployment。部分资源有额外命令（如 domain:verify、database:open、instance:sizes、cache:types），可用 cloud -h 发现。文档强调不要硬编码命令签名，应始终运行 cloud <command> -h 在运行时查看选项。
【CLI 标志】 所有命令都应加 -n，防止 CLI 挂起；不要使用 -q 或 --silent，因为它们会抑制全部输出。各操作推荐标志组合：读取（:list、:get）用 --json -n；创建用 --json -n；更新用 --json -n --force；删除用 -n --force（不加 --json）；环境变量用 -n --force；部署/发布用 -n 并显式传入所有选项（不加 --json）。
【部署流程】 首次部署：cloud ship -n（用 cloud ship -h 查看选项）。已有应用：cloud deploy {app_name} {environment} -n --open，随后 cloud deploy:monitor -n。环境变量：cloud environment:variables -n --force。密钥：echo "$VALUE" | cloud secret:create --name=NAME --json -n，再 cloud environment-secret:attach。基础设施：cloud <resource>:create --json -n。Monorepo（应用位于子目录）时给 cloud ship 或 cloud application:create 加 --root-directory=<subdir>。自定义域名：cloud domain:create --json -n，再 cloud domain:verify -n。多步操作参见 reference/checklists.md。
【命令失败时】 读取错误输出；用 :list --json -n 或 :get --json -n 检查资源状态；鉴权错误则运行 cloud auth -n；修复后重跑命令；若同一错误修复一次后仍出现，应停止并询问用户。每次部署后都要运行 cloud deploy:monitor -n，若失败先向用户展示出错信息再尝试修复。
【子代理委派】 为保持主上下文窗口小，将高输出操作委派给子代理（Task 工具），只返回摘要。建议委派：cloud deploy:monitor -n、cloud deployment:get --json -n、cloud <resource>:list --json -n、通过 WebFetch 获取 https://cloud.laravel.com/docs/llms.txt 文档。保留在主上下文：:create、:delete、:update 等短命令、cloud deploy -n、以及需要结果立即用于下一步的命令。
【规则】 严格按步骤执行：标志选择、先部署后监控（不可跳过监控）、破坏性命令先与用户确认并等待批准、错误循环仅诊断一次后询问用户。需要判断的部分包括实例规格、区域、集群类型（未指定则询问用户）、按用户描述决定要配置哪些资源、配置顺序无严格要求、输出呈现方式按上下文决定。
【密钥】 密钥是跨组织共享并附加到环境的加密值，CLI 在本地加密，明文不会到达 API。常用命令：cloud secret:list --json -n；echo "$VALUE" | cloud secret:create --name=STRIPE_KEY --json -n；cloud environment-secret:attach {environment} {secretId} -n；cloud environment-secret:list {environment} --json -n。应使用管道传入值，--value= 会把明文留在 shell 历史和进程列表中。secret:update、secret:delete、environment-secret:attach 接收的是密钥 ID 而非名称（名称不唯一），ID 可从 cloud secret:list --json -n 读取。没有 secret:get，也无法从单个环境解除密钥附加；secret:delete 会删除并在所有位置解除。密钥功能需要 sodium PHP 扩展，其他命令不需要。
【远程访问】 Tinker（>= v0.2.0）：cloud tinker {environment} --code='Your PHP code here' --timeout=60 -n。--code 为要执行的 PHP 代码（非交互模式必填），--timeout 为等待输出的最大秒数（默认 60）。代码必须用 echo、dump 等显式输出结果，单独表达式不会产生输出。应始终传入 --code 和 -n 以避免交互提示。远程命令：cloud command:run {environment} --cmd='your command here' -n，--no-monitor 跳过实时输出流，--copy-output 复制输出到剪贴板。查看历史：cloud command:list {environment} --json -n 列出命令历史，cloud command:get {commandId} --json -n 获取某条命令的详情和输出。输出可能很长时，将 command:run 委派给子代理。
【计费与用量】 查看当前组织的账单和用量：cloud usage --json -n。--period=current|previous|1|2|3 指定计费周期（默认 current，1/2/3 为往回 N 个周期，最多 3；其他值报错）。--environment=<id> 过滤到单个环境。--detailed 包含按应用、按资源、按附加组件的细分。--json 为机器可读输出（始终与 -n 搭配）。常见查询：当前花费 cloud usage --json -n | jq '.currentSpendCents'；上月账单 cloud usage --period=previous --json -n；单环境完整细分 cloud usage --environment=<id> --detailed --json -n。所有金额以分为单位，各层级键名为 camelCase（如 currentSpendCents、bandwidth.allowanceBytes、databases[].totalCents、applications[].totalCostCents）。--detailed --json 的数据可能很大，建议委派给子代理。
【配置】 环境变量 LARAVEL_CLOUD_TOKEN 为 API 令牌，优先于已保存令牌（空值视为未设置）。全局配置 ~/.config/cloud/config.json 保存鉴权令牌和偏好。仓库本地 .cloud/config.json 保存应用和环境默认值（由 cloud repo:config {application} -n 设置）。CLI 参数会覆盖两个配置文件。repo:config 需传入应用，否则当组织有多个应用时在 -n 下会失败。部署命令不需要这些默认值，直接传入应用和环境即可。多个组织意味着多个已存 API 令牌，每条命令读取 .cloud/config.json 中的 organization_id 来选择；未设置则失败，可用 cloud repo:config {application} --organization=<id|name|slug> -n 设置。LARAVEL_CLOUD_TOKEN 只持有一个令牌，会自行选择组织；用 --organization 指定不同组织会失败，而不会回退到令牌所属组织。
【文档】 Laravel Cloud 文档：https://cloud.laravel.com/docs/llms.txt。当用户询问某项功能如何工作或需要解释时，用 WebFetch 获取该文档以提供准确回答。遇到困难时可获取该文档、运行 cloud <command> -h 查看选项、运行 cloud -h 发现命令。