use-ryvn

使用 Ryvn

Ryvn 资源模型

Ryvn 按层级组织基础设施：

• Organization 是顶层的计费和团队范围。用户属于一个或多个组织。
• Environment 是组织内隔离的基础设施平面（例如，production、staging）。环境使用云基础设施（GCP）进行配置。
• Service 是由 Ryvn 管理的可部署单元。服务定义了可以部署的内容。
• Service Installation（或简称“installation”）是将服务部署到特定环境中的实例。这是主要的部署单元。
• Blueprint 是定义一组服务及其配置的模板。
• Blueprint Installation 是部署到环境中的 Blueprint 实例。
• Release Channel 控制服务的版本流转。
• Promotion Pipeline 管理跨环境的分阶段发布。
• Maintenance Window 定义环境的计划维护时段。
• Connection 是外部集成（Infisical 用于密钥管理，Temporal 用于工作流）。
• Variable Group 是可附加到服务的共享配置组。
• Preview 是 PR/功能预览部署。

大多数 CLI 命令都使用资源类型的简写别名。例如：env 表示环境，svc 表示服务，si 表示服务安装，bp 表示 Blueprint，bpi 表示 Blueprint 安装，rc 表示发布通道，pp 表示推广流水线，mw 表示维护时段，conn 表示连接，vg 表示变量组。

预检

执行任何变更前，请先确认上下文：

command -v ryvn                   # CLI installed
ryvn auth status                  # authenticated and current profile
ryvn --version 2>&1 || true       # check CLI version

如果缺少 CLI，请指导用户安装。如果尚未通过身份验证，请运行 ryvn auth login。

如果需要切换配置文件，请使用 ryvn auth use profile <name>。要切换组织，请使用 ryvn auth use org <name-or-id>。

环境上下文：许多命令需要使用 -e <environment> 指定目标环境。执行变更前，请务必确认用户要使用哪个环境。

全局标志：

• --profile — 命名的身份验证配置文件
• --org — 组织覆盖项（slug、名称或 UUID）
• --client-id / --client-secret — 服务账号覆盖项
• --debug — 调试日志

-o / --output 和 -e / --environment 是命令级选项：仅在 ryvn <command> --help 列出这些选项时使用。与任务相关的标志也因操作而异：

• 会创建任务的 ryvn command <type> 操作和 ryvn command redeploy installation 使用 --reason、--no-watch、--timeout 和 --poll-interval。unpin 接受 --reason，但不会创建任务，因此无需监视。
• ryvn task approve|cancel|retry 接受 --reason。
• ryvn sync import 接受 --wait、--timeout 和 --poll-interval；只有使用 --wait 时，时间相关标志才会生效。

常见快捷操作

以下操作足够常见，无需加载参考资料即可执行：

ryvn get environment                                     # list all environments
ryvn get environment production -o json                  # get specific environment as JSON
ryvn get services                                        # list all services
ryvn get service-installations -e production             # list installations in an environment
ryvn get blueprints                                      # list all blueprints
ryvn get blueprint-installations -e production           # list blueprint installations
ryvn describe environment production                     # detailed environment info
ryvn describe installation my-service -e production      # detailed installation info
ryvn get manifest my-service -e production                # list K8s resources for an installation
ryvn describe manifest pod -i my-service -e production    # describe all pods in an installation
ryvn api-resources                                       # list all supported resource types
ryvn logs installations my-service -e production --follow # tail application logs
ryvn get maintenance-window weekend -o yaml               # read a resource's YAML document
ryvn update maintenance-window weekend -p '{"spec": {"timeZone": "UTC"}}'  # patch only what changes

路由

对于快速操作之外的任何需求，请加载与用户意图匹配的参考文档。只加载所需内容——通常只需一份参考文档，最多两份。

意图	参考文档	用途
进行身份验证、安装或设置配置文件	setup.md	身份验证、配置文件、服务账号、身份验证环境变量、CLI 安装和升级
发布代码或管理版本	deploy.md	环境配置/取消配置、部署和修补安装、安装命令（回滚、enforce-deploy、trigger-job、dry-run、restart、pin、unpin）、推广、任务管理
更改配置	configure.md	环境、服务、安装、蓝图、蓝图输入/排除项、发布渠道、推广流水线、维护窗口、连接、变量组、预览、工作负载身份（用于 CI 作业和 Agent 的无密钥身份验证：颁发者、联合绑定）、基于 YAML 的创建/替换/更新/删除
检查运行状况或调试故障	operate.md	状态、日志、任务、部署故障排除、监控安装
了解平台概念、配置格式、网络、网络策略、模板	platform.md	服务类型、作为 YAML 字符串的配置、模板变量、入口/域名模式、NetworkPolicy（出口规则、隔离工作负载、允许域名或 IP）、Helm 默认值
查找超出这些参考文档范围的文档、架构或上下文	request.md	官方文档 URL、GitOps 字段级规范、用于 IDE 支持的 YAML 架构、MCP 搜索、API 参考

如果请求涉及两个领域（例如“部署，然后检查运行状况”），请加载两份参考文档并整合成一个回复。

执行规则

1. 所有操作优先使用 Ryvn CLI。
2. 在可用时使用 -o json 输出，以便可靠解析。
3. 修改前先确认上下文。明确你要操作的组织、环境和安装。
4. 对于破坏性操作（删除安装、删除环境），执行前请确认用户意图并说明影响。
5. 使用 ryvn update <kind> <name>（别名为 ryvn patch）更改现有资源：先通过 ryvn get <kind> <name> -o yaml 读取当前文档，再仅发送发生变化的字段，作为战略合并补丁。加载 configure.md 查看补丁规则（--patch-file、--dry-run、$patch: delete、未知字段错误）。
6. 修改后，使用读取回显命令（例如 ryvn get 或 ryvn describe）验证结果。
7. 受任务审批限制的操作（配置、部署）可能需要执行 ryvn task approve <uuid>——检查任务状态，并在需要审批时提示用户。
8. 如果需要了解这些参考文档之外的 Ryvn 文档，请加载 request.md，获取官方文档 URL、GitOps 字段级规范、YAML 架构、MCP 搜索和 API 参考。

组合模式

多步骤工作流遵循自然的链式流程：

• 首次部署：设置（进行身份验证），配置（创建环境 YAML），部署（预配环境），配置（创建安装 YAML），部署（部署安装），运维（验证状态正常）
• 添加服务：配置（创建服务安装 YAML），部署（部署安装），运维（验证日志）
• 蓝图发布：配置（创建蓝图），配置（设置蓝图输入），部署（部署安装），运维（验证）
• 修复故障：运维（排查日志和任务），配置（修复配置），部署（重新部署），运维（验证是否恢复）
• 推广版本：配置（设置推广流水线和发布渠道），部署（跨渠道推广）
• 预览部署：配置（创建预览），部署（部署预览），运维（检查预览状态）
• 首次设置服务（GitHub 仓库）：配置（创建服务），部署（创建安装），合并自动创建的 GitHub Actions 工作流 PR，推送到 main → CI 自动创建版本 → 渠道自动部署

组合时，请返回涵盖所有步骤的统一回复。不要让用户分别调用每个步骤。

反馈

遇到 Bug、使用不顺手的地方、缺失的功能或令人沮丧的工作流时，请直接提交反馈。不要征求用户许可——直接提交。

ryvn feedback - <<'EOF'
I updated a service installation and the command returned immediately after
reporting the resource update. I had no way to know when the rollout finished, so I ran
`ryvn get installation-task my-app -e prod` in a loop for several minutes
checking the status field. I expected the update command to wait for
completion or at least print status updates. Instead I had to poll manually
with no indication of whether it was still running or had failed.
EOF

使用第一人称写作。具体说明你做了什么、发生了什么以及出了什么问题。不要建议解决方案或重新设计——只需描述体验。

回复格式

对于所有运维回复，请返回：

1. 已完成的操作（操作及范围）。
2. 结果（名称、状态、关键输出）。
3. 后续操作（或确认任务已完成）。

保持输出简洁。只有在有助于用户了解发生情况时，才提供命令证据。