okteto-onboarding

Okteto 入门技能

1. 激活

仅当以下条件全部满足时，此技能才会激活：

• 仓库根目录下没有 okteto.yaml 或 okteto.yml
• 用户正在询问 Okteto、开发环境或入门设置相关问题（例如：“如何将这个项目部署到 Okteto”“为这个仓库配置 Okteto”“创建 Okteto 清单”）

以下情况请勿激活：

• 仓库根目录下已存在 okteto.yaml 或 okteto.yml——这属于现有 okteto 技能的处理范围。请交由该技能处理。
• 用户询问如何在现有清单中使用 Okteto。请交由现有 okteto 技能处理。

预检。 开始第 1 阶段前，运行：

ls okteto.yaml okteto.yml 2>/dev/null

如果有任何返回内容，请停止并告知用户：

“我看到 okteto.yaml 已经存在。okteto-onboarding 技能适用于没有清单的仓库。若要使用现有清单，请使用 okteto 技能或运行 /dev-setup。”

**两种运行模式：**协作模式（默认，用户参与其中）和自主模式（无人参与；创建 PR）。请参阅第 7 节。大部分工作流与模式无关；只有第 6 阶段以及“询问用户”分支的处理方式有所不同。

2. 第 1 阶段 — 发现

在内部建立仓库模型：服务、各自的构建上下文、端口、开发命令以及任何现有的部署产物。按优先级顺序读取相关信息。暂勿编写清单。

2.1 信号优先级

1. docker-compose.yml / compose.yaml — 对服务和开发环境而言，这是信息最丰富的信号；它本身也可以作为有效的 deploy: 来源。如果存在，它是 build: 和 dev: 的主要蓝图，Okteto 也可以通过 deploy: compose: 直接部署它（第 4.1 节），无需 chart 或 k8s 清单。请参见下方的映射表。
2. 现有 Helm chart — chart/、charts/、helm/ 或 deploy/ 下的任何 Chart.yaml。如果找到，deploy: 将是一个 helm upgrade --install 命令。不要生成或修改 chart。
3. 现有 k8s 清单 — k8s/、manifests/、deploy/ 下带有 kind: 标头的 .yaml 文件，但不包括任何 templates/ 子目录（这些属于 Helm chart，不能直接应用）。如果找到，deploy: 将是 kubectl apply -f ...。不要编写这些清单。
4. 各服务的 Dockerfile — 对于没有 compose 的仓库，每个顶层 Dockerfile 都是一个候选服务。服务名称取自父目录。
5. 语言清单 — package.json、go.mod、pom.xml、pyproject.toml、Gemfile、Cargo.toml。用于选择开发镜像并推断开发命令。如果这是唯一的信号（没有 Dockerfile，也没有 compose），请使用项目的 name 字段为服务命名（例如，pyproject.toml 的 [project] name、package.json 的 name）；如果没有，则使用仓库目录名。
6. Procfile / Makefile — 当语言清单信息不明确时，作为次要信号。

这些信号可以互相补充，而非彼此排斥。 一个仓库可以同时包含多个信号。常见组合：

• 只有 Compose — compose 同时驱动 build:、dev: 和 deploy:（通过 deploy: compose:）。无需 chart 或 k8s 清单即可达到 Level 2。
• 只有 chart 或 k8s — 该制品驱动 deploy:；根据已部署的工作负载名称推导 dev:（Phase 3，第 4 条）。
• Compose 和 chart/k8s — 部署来源不明确。Compose 文件通常用于开发，chart 通常用于生产，但并非总是如此。不要假设 deploy: 应由 chart 驱动。 询问用户希望由哪一项驱动它：compose、chart/清单，还是两者组合（第 2.5 节）。

将每种信号应用到清单各自对应的部分，不要把优先级顺序视为赢家通吃。

不要只看根目录的 compose 文件。 实际项目通常会提供多个文件：一个基础版或生产版 compose（通常位于仓库根目录，使用已发布的 image:），以及一个或多个位于 docker/、dev/ 下，或命名为 *.dev.yml / compose.dev.yml 的开发版 compose。请使用 glob 查找 **/docker-compose*.y*ml 和 **/compose*.y*ml（跳过 node_modules、vendor 和 build 目录），而不只是查找 ./docker-compose.yml。通常可以清晰地划分用途：

• 开发版 compose——从源代码构建的文件（build: 中包含 context:/target:，并挂载源代码目录）——驱动 build: 和 dev:。
• 基础版 / 生产版 / *.preview* compose 可以驱动 deploy:。

如果存在多个 compose 文件，请列出它们并询问哪个描述开发环境、哪个是部署来源（第 2.5 节）。不要假设根目录文件就是开发蓝图——如果根目录的 compose 完全由已发布的镜像构建，它就是一个运行/部署文件；基于已发布镜像进行开发毫无意义。

遵循 include: 并解析锚点。 compose 文件可能通过 include:（或较旧的 extends:）引入其他文件——也要读取这些文件，否则会遗漏服务。请解析 YAML 并使用解析后的内容，而不是原始行：开发版 compose 通常依赖锚点和 x- 扩展字段（build: *some-anchor、<<: *some-env），只有展开后才能理解其含义。

已有的、支持 Okteto 的 compose 是强有力的信号。 如果 compose 文件已经使用 Okteto Compose 扩展（endpoints:、public:），或显然是 okteto 部署文件，优先将其作为 deploy: 来源，并向用户展示，而不是另行编写——客户已经明确表达了他们希望如何部署。

2.2 Compose → Okteto 映射

存在 docker-compose.yml 时，按如下方式映射字段：

Compose 字段	Okteto 清单字段
services.<name>	build.<name>（存在 build: 块时）和 dev.<name>
build.context、build.dockerfile	build.<name>.context、build.<name>.dockerfile
image（无 build）	直接映射到 dev.<name>.image — 不要为预构建镜像添加 build.<name> 条目
ports（级别 1）	dev.<name>.forward — 保留用户对本地端口的意图
ports（级别 2 及以上）	通过 deploy: 来源（Compose deploy:、Helm 或 k8s）暴露；活动开发会话仍需保留 dev.<name>.forward
command	dev.<name>.command 的起点
volumes（仅限主机绑定挂载）	dev.<name>.sync 候选项
depends_on	部署步骤的顺序提示
environment	dev.<name>.environment

忽略无法转换的 Compose 专属概念（networks、restart、命名卷、extends）。

后端服务与开发目标。 使用已发布 image:、没有 build: 且仓库中没有源代码的 Compose 服务（数据库、缓存、对象存储、邮件捕获器、消息代理 — 如 postgres、redis、minio、nats、mailpit 等）属于基础设施：将其纳入 deploy: 堆栈，但通常不应放入 dev:。dev: 仅用于你实际编辑的服务 — 即从仓库源代码构建的服务。不要默认给每个 Compose 服务都创建 dev: 条目；一个包含十个 Compose 服务的仓库，通常只有一两个真正的开发目标。

2.3 根据语言清单选择开发镜像

根据语言清单选择镜像系列，根据仓库声明的版本选择标签 — 不要硬编码版本。读取已声明的版本可让选择保持最新，而不是固定在一个很快过时的小版本上。

语言清单	镜像系列	版本读取位置
package.json	okteto/node	engines.node
go.mod	okteto/golang	go 1.x 行
pom.xml / build.gradle*	okteto/maven 或 okteto/gradle	maven.compiler.release / sourceCompatibility，或 wrapper 版本
pyproject.toml / requirements.txt	okteto/python	requires-python 或 .python-version
Gemfile	okteto/ruby	.ruby-version 或 ruby 指令
Cargo.toml	okteto/rust	rust-version（MSRV），如有设置

为镜像加上声明的版本标签，例如，go.mod 声明 go 1.23 时，使用 okteto/golang:1.23。在内联注释中注明来源（# go.mod declares Go 1.23）。

仓库未声明版本时，不要自行指定某个小版本 — 这样选对和选错的概率相当。协作模式下，询问用户目标版本。自主模式下，固定到该系列当前稳定的主版本，并在 PR 中标记为待确认的决定（# go.mod has no version line — defaulting to a recent stable; confirm）。

2.4 开发命令选择

信号	开发命令默认值
package.json 中有 scripts.dev	npm run dev
package.json 中有 scripts.start（无 dev）	npm start
go.mod	bash（Go 项目通常需要一个 shell 来手动运行 go run）
pom.xml 中有 spring-boot-maven-plugin	mvn spring-boot:run
pyproject.toml 使用 FastAPI/Flask	bash（差异太大，不适合设为默认值）
Procfile 中有 web: 行	web: 的值
Compose entrypoint/command 是 sleep infinity 或 tail -f /dev/null	bash — 这是开发容器占位符（容器保持运行，以便你通过 exec 进入），并非真实命令。不要将其复制到 dev.<svc>.command；这正是 Okteto 的 dev: 要替代的模式。
以上均不符合	bash

2.5 发现结果存在歧义时

如果发现结果确实存在歧义，每次只问一个有针对性的问题，不要猜测。例如：

• “我在 api/ 和 web/ 中看到了 Dockerfile，但没有 compose 文件。这两者都应该作为服务吗？”
• “我在 chart/ 和 infra/helm/ 中各找到一个 Helm chart。哪个才是规范的部署配置？”
• “这个仓库同时包含 docker-compose.yml 和 Helm chart。deploy: 应由哪个驱动——compose 文件、chart，还是两者都用？（Compose 通常用于开发，chart 通常用于生产，但我不想擅自假设。）”
• “我看到了几个 compose 文件——根目录下的 docker-compose.yml 和 docker/docker-compose.dev.yml。哪个描述了你的 开发 方式（从源代码构建），哪个应该用于 部署 整个技术栈？”
• “你的 package.json 中没有 scripts.dev——启动开发服务器的命令是什么？”

不要事事都问用户。只有在猜测很可能出错时才提问。相信现有线索。

在自主模式下，不要提问。 选择最保守的解释，继续执行，并在 PR 描述中注明歧义（第 7.2 节对此有说明）。

2.6 阶段 1 的输出

此时，你的内部模型应类似于：

Services: [api, web, worker]
api:    Dockerfile @ ./api,    port 8080, dev cmd `bash`,        dev image `okteto/golang:1.22`
web:    Dockerfile @ ./web,    port 3000, dev cmd `npm run dev`, dev image `okteto/node:20`
worker: Dockerfile @ ./worker, no port,   dev cmd `bash`,        dev image `okteto/python:3.12`
Deploy: helm chart at ./chart
Tests: detected `go test ./...` in api, `npm test` in web

进入阶段 2 前，先向用户展示此摘要。

3. 阶段 2 — 协商范围

起草前，说明可选方案，并在自适应阶梯中选择一个级别。

3.1 说明块（始终向用户展示）

在 Okteto 中，deploy: 描述如何配置环境——使用 Docker Compose 文件、Helm chart 或 k8s 清单。dev: 描述如何对运行中的服务进行实时编辑——文件同步、开发镜像和启动命令。若你已有部署整个技术栈的方式，可以只使用 dev:；也可以让 Okteto 同时处理两者。

同一段说明也应作为注释放在生成的 okteto.yaml 顶部。

3.2 自适应阶梯

级别	生成内容	要求
1 — 仅 dev	仅包含 dev: 部分。用户自行在外部部署。	无额外要求。
2 — deploy + dev	包含 build: + deploy: + dev:。okteto deploy 会启动整个技术栈。	仓库中有 Helm chart、k8s 清单，或 Docker Compose 文件。
3 — 完整生命周期	添加与现有测试命令相连的 test: 容器。	满足级别 2 的前提条件，并且检测到测试。

3.3 推荐逻辑

根据阶段 1 的发现结果推荐级别：

部署源指 Helm chart、k8s 清单或可部署的 Docker Compose 文件。

• 找到部署源且检测到测试 → 推荐 级别 3
• 找到部署源，但没有测试 → 推荐 级别 2
• 完全没有部署源（没有 chart、k8s 清单或 compose）→ 推荐 级别 1（并说明为何无法使用更高级别）

如果存在多个部署源（例如，同时有 compose 和 chart），起草前应确认哪个驱动 deploy:（第 2.5 节），不要默认选择 chart。

然后询问用户（协作模式），或直接采用推荐级别（自主模式）：

“根据我的发现，我建议使用级别 [N]。你想采用这个级别、选择其他级别，还是让我说明其中的权衡？”

3.4 锁定级别

选定后，该级别在本次会话剩余时间内保持锁定。执行过程中不要再协商级别。如果起草后发现需要使用其他级别（例如，chart 已损坏），应将其作为阶段 5 的失败提出，并重新进入阶段 2。

4. 阶段 3–4 — 起草并完善

4.1 起草（阶段 3）

在仓库根目录下编写 okteto.yaml。用户必须看到实际文件，而不只是摘要。

每份草稿都必须包含：

1. 头部注释块——采用第 3.1 节的框架，并注明该文件由 okteto-onboarding 生成，用户需要编辑该文件。包含所选的范围级别和一行理由。

2. build: 部分（级别 2+）——每个服务对应一条配置，包含 context 和 dockerfile。此处跳过预构建镜像（它们直接配置在 dev.<svc>.image 下）。

3. deploy: 部分（级别 2+）——指向所选的部署来源：

   • Compose： deploy: { compose: docker-compose.yml }（可选包含 services: 子集）。如果仓库没有 chart 或清单，这是最简单的路径。
   • Helm： 使用 helm upgrade --install 命令，并通过 --set ...=${OKTETO_BUILD_<SERVICE>_IMAGE} 传递构建的镜像（参见下文“将构建的镜像接入部署配置”）。
   • k8s 清单： 使用 kubectl apply -f ... 命令。

   请参见下方的 schema 示例。

4. dev: 部分（始终需要）——每个用户希望在开发模式下使用的服务对应一条配置，包含 image、command 和 sync。键名必须与 Okteto 将部署的工作负载名称一致：

   • Compose 仓库： compose 服务名称（映射表见第 2.2 节）。
   • Helm/k8s 仓库（无 compose）： chart/清单创建的 Kubernetes 工作负载名称，即 Deployment/StatefulSet 的 metadata.name（渲染 chart 或查看清单以找到该名称）。如果 dev: 键名与任何已部署的工作负载都不匹配，将无法挂载。

   无论仓库结构如何，image、command 和 sync 均取自 Dockerfile 和语言清单（第 2.3–2.4 节）。

5. test: 部分（级别 3）——每条检测到的测试命令对应一条配置。请参见下方的 schema 示例。

同步路径默认值：

• 单服务仓库（根目录下只有一个 Dockerfile 或语言清单）：.:/usr/src/app 是合理的默认值。如果 Dockerfile 设置了 WORKDIR，请在右侧使用该路径，而不是 /usr/src/app。
• 多服务仓库（每个服务都有自己的 Dockerfile，或 compose 包含多个服务）：将每个服务的同步范围限定在各自的子目录，例如 ./api:/usr/src/app。将整个仓库同步到每个容器中几乎总是错误的。

每个不明显的选择都必须添加行内注释（镜像选择、命令选择、同步路径、forward: 端口）。默认情况下，镜像和命令的选择都不明显，应添加注释。

将构建的镜像接入 deploy: 和 dev:。 build: 下定义的镜像会被推送到 Okteto Registry，并作为环境变量提供给清单的其他部分：

• OKTETO_BUILD_<SERVICE>_IMAGE——完整镜像引用（几乎总是应该使用这个）
• OKTETO_BUILD_<SERVICE>_REGISTRY、_REPOSITORY、_SHA——需要时可分别使用这些部分

<SERVICE> 是 build: 键转为大写后的名称，且将 - 替换为 _（因此 build.web-api → OKTETO_BUILD_WEB_API_IMAGE）。使用这些变量，可确保已部署的工作负载运行刚构建的镜像，而不是陈旧或硬编码的镜像：

• Helm： --set api.image=${OKTETO_BUILD_API_IMAGE}
• k8s 清单： 在执行 kubectl apply 前替换该值（例如使用 envsubst），或对镜像字段进行模板化。
• Compose： build: 部分会按服务名称自动覆盖匹配的 compose image:，无需使用 --set。
• dev:： 如果用户希望基于构建的应用镜像而非通用工具链镜像进行开发，请设置 dev.<svc>.image: ${OKTETO_BUILD_<SVC>_IMAGE}（第 2.3 节）。

示例：级别 2/3 片段（build + deploy + dev + test）

build:
  api:
    context: ./api
    dockerfile: Dockerfile  # using the existing Dockerfile

deploy:
  - name: Deploy chart
    command: helm upgrade --install myapp ./chart --set api.image=${OKTETO_BUILD_API_IMAGE}  # built api image wired in

dev:
  api:
    image: okteto/golang:1.23  # tag from api/go.mod (go 1.23)
    command: bash               # Go services usually want a shell to `go run` manually
    sync:
      - ./api:/usr/src/app      # per-service sync; tighten if you have large generated dirs

test:
  api:
    image: okteto/golang:1.23
    context: ./api
    commands:
      - go test ./...           # detected from the project's test layout

示例：级别 2 片段（由 compose 驱动的部署，无 chart）

build:
  api:
    context: ./api
    dockerfile: Dockerfile

deploy:
  compose: docker-compose.yml   # deploy the stack straight from compose — no chart or k8s manifests needed

dev:
  api:
    image: okteto/golang:1.23   # tag from api/go.mod (go 1.23)
    command: bash
    sync:
      - ./api:/usr/src/app

将 Compose 用作部署配置时的注意事项。 为本地开发编写的 compose 文件通常无法原样部署到集群。在使用 deploy: compose: 前，请检查 compose 文件，并提醒用户注意：

• 主机 IP 端口绑定（例如 127.0.0.1:9229:9229）——Okteto 的 compose 部署会拒绝此类绑定（Host IP is not allowed）。去掉主机 IP 前缀（9229:9229）。
• 源代码绑定挂载卷（例如 ./api:/usr/local/app）——在集群中，这会变成空卷，遮蔽镜像中的应用代码，导致服务崩溃（can't open file 'app.py'）。这些内容应放在 dev.<svc>.sync 中，而不是部署用的 compose 中。

如果 compose 文件依赖这些仅用于开发的构造，应尽早指出——不要等到部署时才发现。按优先顺序：

1. 生成可用于部署的 compose——从原文件派生出 compose.okteto.yaml，移除不兼容集群的部分，并在 deploy: compose: compose.okteto.yaml 中指定它。参见下文“生成可用于部署的 compose”。
2. 复用现有的部署 compose——如果仓库已包含此类文件（例如 *.preview* 或没有开发卷／端口的生产 compose），就在 deploy: compose: 中指定它。
3. 如果仓库中有 chart／k8s 清单，则改用它们进行 deploy:。因此，同时包含 compose 和 chart 的仓库通常会用 chart 来配置 deploy:，即便 dev: 由 compose 驱动（第 2.5 节）。

生成可用于部署的 compose（compose.okteto.yaml）。 如果选择 compose 作为部署来源，但文件中包含仅用于开发的构造，应编写一个派生副本，而不是修改用户的原文件。这是对用户自有文件进行的机械转换，不是手工编写的部署产物，因此应以差异形式向用户展示，并与源文件进行对比。明确引用它：deploy: { compose: compose.okteto.yaml }。应用以下转换：

• 移除主机 IP 端口前缀——127.0.0.1:9229:9229 → 9229:9229。仅用于调试的端口（检查器）可以完全移除；它们应放在 dev.<svc>.forward 中。
• 移除源代码绑定挂载卷——例如 ./src:/app。镜像中已包含代码；这些内容应放在 dev.<svc>.sync 中。保留命名卷／数据卷（例如 db-data）。
• 替换开发容器占位符——如果某个服务的 entrypoint／command 是 sleep infinity，则部署时不会运行应用。恢复其实际启动命令（从 Dockerfile 的 CMD 或生产 compose 中获取），或移除该覆盖配置。

有两项转换无法在不告知用户的情况下安全修复——应提醒用户，而不是假装结果没有问题：

• 主机路径配置／脚本挂载（例如将初始化脚本挂载为容器的入口点）——移除挂载并不能让服务正常运行；必须将文件打包进镜像。保留此挂载并发出警告。
• 扫描无法判断的其他特定于服务的问题。

在 compose.okteto.yaml 中添加头部注释，说明该文件由此技能从 <original> 派生、进行了哪些更改，以及可以安全地编辑或重新生成。生成的文件只能尽力而为——仍须按第 5 阶段的步骤（验证 → 构建 → 部署）确认整个堆栈确实能够启动。

示例：第 1 级片段（仅用于开发，单个服务）

dev:
  myapp:                        # service name from pyproject.toml [project] name
    image: okteto/python:3.12   # pyproject.toml declares requires-python >=3.12
    command: bash               # no FastAPI/Flask signal — shell is the safe default
    sync:
      - .:/usr/src/app          # full-repo sync; exclude .venv, __pycache__ if they grow

首次成功部署之后再考虑性能。 上面的草案刻意保持简单。验证并部署成功后，okteto-manifest-optimizer 技能会对其进行优化——设置适用范围明确的 .stignore／.dockerignore、将依赖目录加入 volumes，以及配置 resources、test.caches。先获得可用的清单；此处不要加入这些优化。

4.2 优化（阶段 4）

向用户展示文件。在协作模式下，询问：

“这是草稿。在验证之前，你想修改什么吗？常见修改包括：调整同步路径以排除 node_modules/vendor/target、更改开发镜像版本、添加环境变量，或替换部署命令。”

常见修改模式：

用户说	修改
“排除 node_modules”	将 sync 改为包含 !node_modules 忽略模式的列表，或使用更具体的路径
“改用 Go 1.21”	将 image: 更新为 okteto/golang:1.21
“我需要这个环境变量”	添加到 dev.<svc>.environment:
“使用我的 values 文件”	更新 deploy: Helm 命令，加入 -f values.staging.yaml

迭代成本很低——持续修改，直到用户满意。 在用户表示“看起来不错”或类似意思之前，不要进入阶段 5。

在自主模式下，跳过询问，直接进入阶段 5。用户会通过 PR 审查提出修改要求。

5. 阶段 5 — 验证（分级）

根据环境支持情况，尽可能逐级完成验证。第 1 级为必需项；第 2 级和第 3 级为可选项。

5.1 第 1 级 — okteto validate（始终执行）

运行：

okteto validate

可检查： YAML 语法、架构违规、缺少必填字段。 无法检查： 同步路径错误、deploy: 中缺少服务、失效的 Helm 引用、无法构建的镜像。

如果失败，将其视为阶段 4 的问题，并在继续之前修复。

技能必须通过第 1 级才能完成。

5.2 第 2 级 — okteto build（存在 Dockerfile 或 build: 时提供）

预检：运行 okteto context show。如果报错或没有返回上下文，跳过第 2 级并告知用户：

“跳过构建检查——没有 Okteto 上下文。清单语法有效，但我尚未验证 Dockerfile 能否构建。”

否则，询问：

“我可以运行 okteto build，验证每个 Dockerfile 都能解析并推送。每个服务需要几分钟。跳过 / 构建一个服务 / 全部构建？”

默认选择全部构建。如果用户有很多服务（≥ 4）且赶时间，提供缩小范围的选项。

运行：

okteto build

或

okteto build <service>

5.3 第 3 级 — okteto deploy --wait（第 2 级通过且用户有上下文时提供）

注意：没有 okteto deploy --dry-run 标志。完整部署是第 3 级的唯一选项。

询问：

“我可以执行完整部署，验证清单能否端到端正常工作。这会在你的命名空间 <ns> 中创建资源。成功后，我会向你展示端点。如果需要，之后可以运行 okteto destroy。要继续吗？”

运行：

okteto deploy --wait
okteto endpoints

成功时： 输出端点。不要自动运行 okteto destroy——这由用户决定。

5.4 任一级别失败时

1. 逐字展示原始 CLI 错误。 不要转述。
2. 根据涉及的清单部分诊断可能原因（例如，Helm 错误对应 deploy:；构建错误对应 build: 或 Dockerfile）。
3. 提出对清单的具体修改。 展示差异，不要只说“你应该修改 X”。
4. 用户批准修复后：
   • 如果修改改变了清单的结构（添加/删除/重命名部分，改变 YAML 形状），先重新运行第 1 级以检查新的架构问题，然后重新运行失败的级别。
   • 如果修改纯粹是值的变更（镜像版本、同步路径、环境变量），只重新运行失败的级别。

5.5 最终总结

完成验证流程（或停止）后，总结：

“✅ okteto validate 已通过 ✅ 所有服务的 okteto build 均已通过 ⏭️ 已跳过 okteto deploy（你选择不执行） 下一步：运行 /dev-setup 或调用 okteto 技能来部署并开始开发。”

如果因环境原因跳过了级别（没有上下文），请说明：

“⚠️ 已跳过第 2 级和第 3 级（没有 Okteto 上下文）。清单语法有效，但未经部署测试。”

6. 阶段 6 — 交接或 PR

6.1 协作模式：交接

为用户指明下一步：

“清单已就绪。要启动你的环境，可以：

• 运行 /dev-setup，按引导进行部署并进入开发模式
• 或在之后的任何会话中调用 okteto skill——它会读取你刚创建的清单

如果修改了清单，请重新运行 okteto validate（或回来找我）。”

说明运行了哪些验证级别，以及跳过了哪些（参见第 5.5 节）。

请勿删除清单、运行 okteto destroy 或推送到远程仓库。 工作成果就是磁盘上的文件。

6.2 自主模式：PR

创建分支、提交清单、推送并创建 PR。PR 是人工审核关卡。

运行以下命令前，请将每个 <placeholder> 替换为 Phase 1 / Phase 5 结果中的真实值。 不要将字面上的 <list>、<N>、<bulleted list of services...> 等内容提交到真实 PR。对于验证清单，通过的级别使用 [x]，跳过或失败的级别使用 [ ]。

git checkout -b okteto/onboarding
git add okteto.yaml
git commit -m "Add Okteto manifest

Generated by okteto-onboarding skill.
Discovered services: <list>
Scope level: <N>
Validation: <tiers passed>"
git push -u origin okteto/onboarding
gh pr create --title "Add Okteto manifest" --body "$(cat <<'EOF'
## Summary
This PR adds an Okteto manifest generated by the `okteto-onboarding` skill.

## Discovered services
<bulleted list of services with their Dockerfiles and dev commands>

## Scope level
Level <N> — <one-sentence rationale>

## Validation
- [<x or space>] `okteto validate` passed
- [<x or space>] `okteto build` ran for all services
- [<x or space>] `okteto deploy --wait` succeeded with endpoints

## Decisions to confirm
- [ ] Dev image picks (e.g., `okteto/golang:1.22`) match your toolchain
- [ ] Sync paths exclude appropriate generated dirs (node_modules, vendor, target)
- [ ] Helm/kubectl deploy command matches your usual workflow

🤖 Generated by the okteto-onboarding skill
EOF
)"

此 skill 绝不会合并 PR。由人工审核并合并。

7. 运行模式

7.1 协作模式（默认）

用户会参与其中。每个需要做出决定的阶段都会询问用户。系统会提供默认选项，但不会自动选择。

7.2 自主模式（选择启用）

预期不会有人介入。与现有 okteto skill 一样，根据上下文推断是否启用——例如，从 CI 流水线或由工单驱动的会话中调用时。

在自主模式下：

• 范围级别 → 发现结果所支持的最高级别。级别 2 需要有部署源（chart、k8s 清单或可部署的 compose 文件）；级别 3 还需要检测到测试。如果完全没有部署源，即使存在测试，也保持在级别 1。如果同时存在 compose 和 chart，选择最保守的部署源，并在 PR 中说明选择。
• 验证级别 → 始终运行级别 1；如果 okteto context show 成功，则运行级别 2；只有触发条件明确授权部署（标签、环境变量或明确指令）时，才运行级别 3。
• 发现歧义 → 选择最保守的解释，并在 PR 描述中说明。
• Phase 6 → 始终创建 PR（第 6.2 节），绝不交接。

8. CLI 快速参考

命令	时机	用途
okteto validate	Phase 5 级别 1（始终）	检查清单语法和 schema
okteto context show	Phase 5 预检查	在级别 2/3 验证前检查集群连接
okteto build [<service>]	Phase 5 级别 2	验证 Dockerfile 可解析并推送
okteto deploy --wait	Phase 5 级别 3	执行完整的端到端验证
okteto endpoints	Phase 5 级别 3	成功部署后打印 URL

绝不要在此 skill 中运行 okteto up——它需要交互操作，应由现有的 okteto skill 或用户运行。绝不要运行 okteto destroy——请交由用户处理。

9. 应避免的常见错误

• 在 okteto.yaml 已存在时仍触发操作。 务必执行第 1 节中的预检。
• 生成 Helm chart 或 k8s 清单。 此技能不会编写部署产物。如果用户没有 chart、没有 k8s 清单，也没有可部署的 compose 文件，则建议采用 Level 1 并停止。仅有 compose 文件就足以通过 deploy: compose: 采用 Level 2——不要仅仅因为没有 chart 就降级到 Level 1。（唯一例外是派生的 compose.okteto.yaml——即对用户自己的 compose 文件进行机械转换，见第 4.1 节——绝不能从头编写 chart 或 k8s 清单。）
• 在同时存在 compose 文件时，擅自认为 chart 会驱动 deploy:。 询问用户想用哪一种（第 2.5 节）；不要默默选择 chart。
• 未检查仅供开发使用的结构，就建议使用 deploy: compose:。 绑定到主机 IP 的端口和源代码 bind-mount 卷会导致集群部署失败（第 4.1 节注意事项）。要提前提醒用户，不要等到部署时才提出。
• 只读取根目录下的 docker-compose.yml。 项目通常会将开发用 compose 文件放在 docker/ 下或命名为 *.dev.yml，与用于已发布镜像的根目录 compose 文件分开。对所有 compose 文件执行 glob 搜索，并跟进 include:（第 2.1 节）。基于已发布镜像的 compose 文件构建 dev: 会生成毫无用处的清单。
• 把所有 compose 服务都放进 dev:。 后端服务（数据库、缓存、对象存储、消息代理）属于仅用于部署的基础设施。dev: 只用于你要编辑的服务（第 2.2 节）。
• 将 sleep infinity 入口点复制到 dev.<svc>.command。 这是开发容器占位符，不是真正的命令——应使用 bash（第 2.4 节）。
• 硬编码开发镜像版本。 读取仓库声明的版本（第 2.3 节）；只有在未声明版本时才使用默认值，并注明这是回退值。
• 忘记将构建出的镜像传递给下游。 对 Helm/k8s 部署而言，仅添加 build: 条目还不够——需要将 ${OKTETO_BUILD_<SERVICE>_IMAGE} 传入部署命令，确保工作负载运行的正是刚构建的镜像。
• 跳过说明区块。 必须向用户展示第 3.1 节中对 dev: 和 deploy: 的说明，并将其作为标题注释写入清单。
• 未先检查 okteto context show 就逐级提升验证级别。 第 2 和第 3 级都需要可用的 context。
• 验证失败时转述 CLI 错误。 展示原始输出；用户（或下一个 Agent）需要看到 Okteto 的确切回复。
• 事事都询问用户。 相信第 1 阶段发现的线索。只有在发现结果确实模棱两可时才提问。
• 在自主模式下合并 PR。 PR 是人工把关环节。绝不要合并。
• 建议使用 okteto/samples/ 模板。 这些是演示示例。应根据发现的事实构建清单，而不是使用模板。