openchoreo-developer

OpenChoreo 开发者指南

通过控制平面 MCP 服务，帮助应用开发者在 OpenChoreo 上发布并运维服务。通过 MCP 探查实时平台形态；只有任务需要时才查阅详细参考资料。

步骤 0 — 确认 MCP 连接

运行 list_namespaces。如果无法访问该工具，请告知用户需要按照 https://openchoreo.dev/docs/ai/mcp-servers/ 配置 openchoreo-cp MCP 服务，然后停止。

步骤 1 — 加载概念（必须）

在进行任何其他操作之前，完整阅读 ./references/concepts.md。 这不是可选步骤，即使任务看起来很简单也必须阅读——凭记忆处理会出错。每个会话只需加载一次；如果发现自己尚未加载就开始操作，请停止并立即加载。

然后加载与任务匹配的参考资料：

• 首次部署（尚无 Project，或首次接触 OpenChoreo）→ ./references/getting-started.md
• 处理现有 Component → 直接查看匹配的操作指南。要为现有 Component 选择 BYO 还是源代码构建，请运行 get_component 并检查 spec.workflow：存在 → build-from-source.md，不存在 → deploy-prebuilt-image.md。

步骤 2 — 加载平台任务所需的 PE 技能

如果请求涉及 ProjectType / ComponentType / ResourceType / Trait / Workflow（或集群变体），或涉及 此技能无法完成的任务 下的任何内容，还需加载 ../openchoreo-platform-engineer/SKILL.md。如果未安装 PE 技能，请升级处理。

此技能可以完成的工作

• 项目 — 创建、更新。create_project 可选用 type_name / type_kind / parameters 引用由 PE 编写的 (Cluster)ProjectType；若省略，则默认使用 default ProjectType。项目的单元必须先在各环境中部署，其组件才能部署 → 参见 deploy-and-promote.md 中的 部署项目单元。
• 组件 — 创建、更新；使用 patch_component 更新 auto_deploy / parameters / traits / workflow / 元数据。
  • BYO 镜像 → deploy-prebuilt-image.md
  • 源码构建 → build-from-source.md
• 工作负载 — 镜像、端口、端点、环境变量、文件 → configure-workload.md
• 附加 Traits — 从平台目录中选择 → configure-workload.md
• 连接组件 — 端点依赖；平台会注入环境变量 → connect-components.md
• 使用资源 — 托管基础设施依赖（数据库、队列、缓存）；平台通过 dependencies.resources[] 将输出注入为环境变量和文件挂载 → use-a-resource.md
• SecretReferences — CRUD + secretKeyRef 使用 → manage-secrets.md。ClusterSecretStore 由 PE 管理。
• 部署和晋升 — 在各环境中部署项目单元（create_project_release_binding，由控制器固定版本），然后将 ComponentRelease 绑定到某个环境，并沿 DeploymentPipeline 晋升二者 → deploy-and-promote.md
• 按环境覆盖配置 — 在 ReleaseBinding 上配置副本数、资源、环境变量、Trait 配置 → override-per-environment.md
• 软取消部署 / 回滚 — 使用 update_release_binding release_state: Undeploy，或重新绑定到先前的 ComponentRelease。
• 硬删除开发者资源 — delete_component、delete_workload、delete_release_binding、delete_project、delete_component_release。此操作具有破坏性；请先确认。不支持 delete_namespace — 由 PE 处理。
• 检查运行时 — Component / ReleaseBinding 的 status.conditions[] 和 status.endpoints[]；使用 get_resource_tree 将绑定映射到渲染后的 K8s 资源；使用 get_resource_events / get_resource_logs 获取 Pod 级证据；WorkflowRun 日志和事件 → inspect-and-debug.md
• 发现平台资源（只读）— ProjectTypes、ComponentTypes、ResourceTypes、Traits、Workflows、Environments、DeploymentPipelines、planes。

此技能无法完成的工作

平台侧工作：编写 ProjectTypes / ComponentTypes / ResourceTypes / Traits / Workflows、Environments、DeploymentPipelines、planes，配置授权、网关 / secret-store / IdP，设置可观测性，以及进行较长时间范围的日志 / 指标 / 追踪查询（可通过 get_resource_events / get_resource_logs 查看 Pod 级事件和当前日志）。

如果已安装，请加载 ../openchoreo-platform-engineer/SKILL.md；否则，请告知用户联系平台工程师升级处理。PE 职责范围目录：https://openchoreo.dev/docs/platform-engineer-guide/。

工具范围

一个 MCP 服务：openchoreo-cp。在本技能中，工具均以裸名称引用（例如 get_component）；你的 Agent 会添加前缀（Claude Code 使用 mcp__openchoreo-cp__<tool>）。

ComponentType / ResourceType / Trait / Workflow 和 plane 工具均已合并作用域：通过一个 scope 参数调用——"namespace"（默认值），或针对平台级 Cluster* 资源使用 "cluster"。本技能始终使用规范名称 + scope。旧的 *_cluster_* 名称仍作为已弃用别名保留（v1.1 中显示提示横幅，v1.2 中隐藏，v1.3 中移除），也可在 v1.1 服务端上使用——但建议优先使用规范形式。

resource 工具集（面向开发者，默认启用）涵盖 Resource 的 CRUD，以及对 (Cluster)ResourceType 的合并作用域读取。ResourceReleaseBinding 和 ProjectReleaseBinding 的 CRUD 均与 ReleaseBinding 一起位于 deployment 工具集中。resource_release_binding 的创建/更新调用用于将 Resource 部署到环境中（或提升）；project_release_binding 的创建/更新调用对项目的 cell 执行相同操作。这里的 (Cluster)ProjectType 仅供读取（list_project_types / get_project_type / get_project_type_schema，可感知 scope）——其编写工作由 PE 负责。

工作方式

• 实时集群输出优先于记忆。 先通过 MCP 探索；不要猜测可用的 ComponentType / Trait / Workflow / Environment / 字段名称。
• 先看架构再编写。 从零编写 spec 前，先调用 get_workload_schema，或使用 scope: "cluster" 调用 get_component_type_schema / get_trait_schema，以获取平台级标准。

稳定护栏

• 所有工作都通过控制平面 MCP 服务进行。如果任务无法通过 MCP 完成，则属于平台侧工作——请移交。
• 第三方／公共应用：默认使用自带镜像。 使用第三方 Dockerfile 进行源码构建时，常会因 ARG BUILDPLATFORM 失败（退出码为 125）。如果看到这种情况，请立即切换到自带镜像。
• **部署任何第三方应用之前：**获取官方清单并提取所有必需的环境变量——依赖项会注入服务地址，但不会注入 PORT、功能标志或供应商 SDK 禁用标志。
• 已交接的迁移计划就是规范。 用户提供迁移／入门计划时，应依照计划确定命名空间、环境变量的放置位置（静态 Workload 环境变量还是每个环境的 workloadOverrides）以及接线决策。只有明确说明时才能偏离——在采取行动之前，务必说明要更改什么以及原因，绝不能悄悄替换。
• 类型应适配应用，绝不要为了适配已提供的类型而重塑应用。 如果计划（或应用）需要未安装的 ComponentType／ResourceType／Trait，或者已提供但不符合要求的类型，正确做法是自行创建——加载 ../openchoreo-platform-engineer/SKILL.md 并创建适用的类型。不要通过以下方式绕过差距：因为已提供的 ResourceType 不合适，就把托管依赖重新建模为普通 Component（它仍然是 Resource——应创建能满足该依赖需求的 ResourceType）；因为没有已提供的 Trait，就舍弃应用所需的能力（应创建 Trait）；或者强行让工作负载使用形状或默认值不合适的已提供 ComponentType（应创建 ComponentType）。只有在已提供的类型确实满足约定时才复用。应由需求决定类型，而不是反过来。
• 根据源定义设置资源，而不是使用 ComponentType 的默认值。 使用工作负载源代码中声明的 requests／limits（CPU 和内存都要设置）。如果源代码没有声明，则根据工作负载类别选择合理的默认值——绝不要继承通用 CT 的默认值，这些默认值通常只适用于演示，且资源配置不足。创建 CT 时，应将合理的默认值写入其 environmentConfigs；否则，通过 ReleaseBinding 的每环境配置来设置。
• 注入的连接值是字面值——不会进行 $(VAR) 插值。 依赖项的 envBindings 会将每个连接值（address／host／port／basePath）作为字面值注入你指定的环境变量；平台不会展开其他环境变量值中的 shell／Kubernetes $(VAR) 引用，因此 value: "http://$(HOST):$(PORT)" 会原样传入容器。绑定应用实际读取的环境变量。如果应用需要注入变量无法直接提供的拼接字符串（完整 URI、不带 scheme 的裸 host:port，或 scheme 前缀），则应将拼接后的值设为字面环境变量——通常通过每环境的 workloadOverride 使用解析后的地址，而不是引用 $(VAR)。
• 缺少工具意味着版本不匹配，而非工具不存在。 找不到文档中提及的 MCP 工具时，应先检查服务版本与集群版本是否一致，再判断该功能不存在——向用户报告版本不匹配，然后回退或升级处理。

反模式

• 跳过操作指南。 进行任何新操作之前（本轮中新建 CRD 类型、生命周期操作、运行时检查），先重新扫描上方的操作指南索引，加载匹配的操作指南（调用一次 Read），然后再调用 MCP / kubectl。跳过这一步会导致 kubectl 调用失败，也会错过已有的 MCP 工具。仅了解相关概念还不够——操作指南会按顺序列出正确的工具调用。
• 在检查已被证据指向的资源之前，就运行所有发现调用。
• 当 get_*_schema / get_* 能揭示当前结构时，仍凭记忆编写规格。
• 猜测已部署的 URL，而不是读取 ReleaseBinding.status.endpoints[]。
• 证据已指向其他问题后，仍将平台侧故障视为仅与应用有关的问题。
• 为已有预构建镜像的第三方应用创建源码构建组件。
• 在同一项目中的服务间依赖上设置 visibility: external——默认值是 project。
• 将 Ready=True 等同于“正常工作”。 Ready 表示已完成协调，并不表示功能正常。持续崩溃重启的容器可能会反复变为 Ready，而运行稳定的容器也可能在配置错误时处于 Ready 状态（环境变量绑定到了错误的名称、依赖解析不到任何地址）。请通过 get_resource_tree → get_resource_events / get_resource_logs 确认，并实际访问端点。