okteto

Okteto 开发环境技能

你是一名在 Okteto 驱动的开发环境中工作的 AI Agent。此技能涵盖两种操作模式：

1. 协作模式——开发者正在与你协作
2. 自主模式——你独立工作（例如，由工单、PR 或 CI 流水线触发）

操作规则

以下五条规则可以避免最常见的问题。此技能的其余部分会详细说明这些规则。

1. 首先阅读 okteto.yaml。 从中确定服务、构建和测试——绝不要将名称硬编码。
2. 绝不运行 okteto up。 此命令需要交互操作，会一直挂起。协作模式下由用户运行；自主模式下不应运行。
3. 只能通过 Okteto 修改集群。 使用 okteto build 和 okteto deploy——绝不要使用本地 docker build 或 kubectl apply/helm upgrade。只读的 kubectl/helm 命令（get、describe、logs、events、helm status）可用于诊断。
4. 一个工作树对应一个命名空间。 在 git 工作树中工作时，请创建专用命名空间，并在每条命令中传入 -n <ns>（请参阅工作树隔离）。
5. 未经授权，绝不销毁资源。 运行 okteto destroy 和 okteto namespace delete 需要明确的策略或指示（请参阅清理和拆除）。

步骤 1：了解项目

阅读项目根目录中的 okteto.yaml。它是以下信息的事实来源：

• 构建：哪些服务有容器镜像
• 部署：如何部署服务（通常使用 Helm chart）
• 开发：哪些服务支持开发模式、它们的镜像、同步路径和命令
• 测试：有哪些可用的测试容器，以及它们的运行方式

解析此文件，了解项目的服务、语言和结构。不要假定服务名称是固定的——始终从 okteto.yaml 中确定。

步骤 2：确定操作模式

协作模式——开发者会参与其中并运行交互式命令。在以下情况使用此模式：

• 用户正在 IDE 或终端中与你聊天
• 有人请你协助调试、设置或开发某项服务

自主模式——你独立完成整个工作流程。在以下情况使用此模式：

• 由工单触发（Jira、Linear、GitHub Issue 等）
• 作为 CI/CD 流水线的一部分运行
• 执行过程中预计不会有人介入

---

协作模式

环境设置

1. 检查先决条件：运行 okteto version 和 okteto context show
2. 隔离工作树（如适用）：如果这是一个 git 工作树，请按照工作树隔离创建一个命名空间，并在以下每条命令中添加 -n <ns>
3. 部署：运行 okteto deploy --wait，以构建镜像并部署所有服务
4. 显示端点：运行 okteto endpoints 以显示公共 URL
5. 指导用户：通过 okteto up <service> 在指定服务上开始开发

okteto up 规则

okteto up 需要交互操作，必须由用户在其终端中运行。 它会在开发容器中打开 shell，并实时同步文件。绝不要自行运行——无论是作为后台任务、使用 &，还是以其他任何方式。请改为告知用户：

Run this in your terminal: okteto up <service>

如果你正在隔离工作树（请参阅工作树隔离），请附上命名空间，以便用户连接到正确的环境：

Run this in your terminal: okteto up <service> -n <ns>

与开发者协作

用户运行 okteto up <service> 后：

• 运行诊断：使用 okteto exec -- <command> 在开发容器中执行命令
• 读取已同步的文件：使用 Read 工具检查同步到集群的代码
• 分析粘贴的输出：用户遇到错误时，可以粘贴终端输出
• 检查日志：使用 okteto logs <service> 查看容器日志
• 运行测试：使用 okteto test <test-name> 运行 okteto.yaml 中定义的测试容器

你是在协助用户完成工作流程，而不是试图查看他们的终端会话。

调试模式

情况	操作
用户要求运行测试	okteto exec -- make test 或适合相应语言的命令
用户粘贴错误信息	阅读相关代码，分析并提出修复方案
用户问“为什么会失败？”	通过 okteto exec 运行诊断
用户修改源代码	更改会自动同步；帮助他们运行后续步骤
用户更改构建输入（Dockerfile、依赖项、okteto.yaml）	不会同步任何内容——需要重新构建并验证（参见哪些更改需要重新构建，而非同步）
用户要求运行端到端测试	根据 okteto.yaml 运行 okteto test <test-name>

哪些更改需要重新构建，而非同步

文件同步只涵盖运行中的容器在运行时读取的内容。它不涵盖任何在构建时打包到镜像中的内容。更改以下任意内容后，环境都会过时，直到重新构建：

• Dockerfile 或 .dockerignore
• 依赖项清单（go.mod/go.sum、package.json、requirements.txt、pom.xml 等）
• 编译后的二进制文件，或构建步骤生成的任何内容
• okteto.yaml 本身

重新构建并确认其正常运行：

okteto build <service>      # rebuild the image through the Okteto Build Service
okteto deploy --wait        # redeploy with the new image

如果更改了 okteto.yaml，请在部署前运行 okteto validate 进行验证——错误的清单会在部署中途失败，导致环境只更新了一半：

okteto validate
okteto deploy --wait

无需等待请求，主动执行此操作。 Dockerfile 即使能在你的机器上构建，也仍可能在 Build Service 中失败——例如被 .dockerignore 排除的文件、缺失的 go.sum，或基础镜像无法满足的工具版本；只有构建才能发现这些问题。报告结果：成功时提供端点，失败时说明错误和修复方案。持续迭代，直至部署成功。

必需的子技能： 对于损坏或不健康的环境——CrashLoopBackOff、OOMKilled、ImagePullBackOff、Pod 卡在 Pending、部署失败或文件同步不起作用——请使用 okteto-debugging 技能。该技能包含完整的分诊算法，以及针对各种故障模式的操作手册。

---

自主模式

在没有开发人员参与的情况下运行时，你需要负责整个生命周期：环境设置、代码更改、验证和报告。不要使用 okteto up——它需要交互操作和人工参与。请改用 okteto deploy 部署完整环境，并使用 okteto test 进行验证。

工作流

1. 了解任务：阅读工单/问题，了解需要进行哪些更改以及验收标准。

2. 部署环境：

   • 运行 okteto context show，验证集群连接并查看当前活动的命名空间
   • 如果这是多个并行分支/工作树之一，请先创建隔离命名空间（参见工作树隔离），并在下方每条命令中传入 -n <ns>
   • 运行 okteto deploy --wait，启动所有服务
   • 运行 okteto endpoints，记录实时 URL，供之后验证使用

3. 修改代码：根据任务要求编辑相关源文件。使用 Read 工具、Grep 和 Glob 探索代码库。检查服务目录和 okteto.yaml，了解服务结构。

4. 重新构建并部署已更改的服务：

   • 如果修改了 okteto.yaml，请在部署前运行 okteto validate 进行验证——清单有误会导致部署中途失败，使环境处于半更新状态
   • 运行 okteto build <service>，仅重新构建已更改服务的镜像
   • 运行 okteto deploy --wait，使用更新后的镜像重新部署
   • 或者，如果只更改了一个服务，则可指定该服务：okteto build <service> && okteto deploy --wait
   • 对构建输入的任何更改都要执行此操作，包括 Dockerfile、.dockerignore、依赖清单、okteto.yaml，而不仅仅是源代码。在自主模式下不会进行同步；重新部署之前，环境都处于过时状态。

5. 验证：

   • 对 okteto.yaml 中的每个测试容器运行 okteto test <test-name>
   • 运行 okteto endpoints，并使用 curl 或类似工具对实时端点进行冒烟测试
   • 检查 okteto logs <service> --since 5m，查看已更改服务是否存在错误

6. 测试失败时继续迭代：

   • 阅读测试输出和日志，诊断失败原因
   • 修复代码，重新构建、重新部署并再次测试
   • 重复以上步骤，直到所有测试通过

7. 报告结果：总结所做的更改、通过的测试，并提供用于评审的实时环境 URL。附上任何相关日志输出或测试产物。

8. 清理：遵循下方清理和拆除部分中的规则。未经明确授权或预先制定清理策略，不得销毁环境。

自主模式示例

Trigger: Jira ticket "PROJ-123: Add rate limiting to /api/rentals endpoint"

Agent actions (worktree on branch proj-123, isolated namespace ns=proj-123):
  1. Read ticket for requirements and acceptance criteria
  2. okteto namespace create proj-123  -> isolated namespace for this worktree
  3. okteto deploy --wait -n proj-123  -> full environment running
  4. Read okteto.yaml, explore api/ directory
  5. Edit api/handlers/rentals.go      -> implement rate limiting
  6. Edit api/handlers/rentals_test.go  -> add unit tests
  7. okteto build api -n proj-123      -> rebuild the api service image
  8. okteto deploy --wait -n proj-123  -> redeploy with changes
  9. okteto test e2e -n proj-123       -> run e2e test suite
  10. okteto logs api --since 5m -n proj-123  -> check for runtime errors
  11. curl the live endpoint to verify rate limiting behavior
  12. Commit changes, open PR
  13. Report back to PROJ-123: changes made, tests passing, PR link, live URL

（在单个非工作树检出目录中，省略 okteto namespace create 步骤和 -n 标志即可——使用上下文的默认命名空间。）

---

工作树隔离

Okteto 命名空间是隔离的基本单位——它包含 okteto deploy 创建的所有内容。命名空间取自当前活动的 Okteto 上下文（~/.okteto），该上下文是整台机器全局共享的，而不是按目录区分的。当你同时处理多个检出目录时，这一点就很重要。

单个主检出目录（而非工作树）可以使用其上下文的默认命名空间——无需 -n，也可以跳过本节。只有在并行检出目录或工作树可能相互冲突时，才需要使用专用命名空间。为简洁起见，本技能的其余部分省略了 -n；隔离工作树时，请在每条命令中添加该参数。

一个工作树 = 一个命名空间

如果你在 git 工作树（或同一仓库的任何其他检出目录）中工作，你与其他工作树共享同一个 okteto.yaml —— Helm 发布版本和资源名称也相同。如果两个工作树部署到同一个命名空间：

• 第二个 okteto deploy 会覆盖第一个工作树的环境，
• okteto endpoints / okteto logs 会返回错误工作树的数据，
• 在一个工作树中运行 okteto destroy 会拆除另一个工作树的环境。

为每个工作树分配自己的命名空间，彻底隔离它们。

检测工作树（不确定时，请检查）：

git rev-parse --git-common-dir   # differs from `git rev-parse --git-dir` -> you are in a linked worktree
git worktree list                # shows all worktrees of this repo
git branch --show-current        # the branch is a good basis for the namespace name

根据分支（或工作树目录）派生命名空间名称。Okteto 命名空间名称必须由小写字母数字字符和 - 组成，以字母数字字符开头和结尾，且最多 63 个字符（正则表达式 ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$）：

# branch "feat/Rate_Limiting" -> "feat-rate-limiting"
ns=$(git branch --show-current | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/^-*//; s/-*$//' | cut -c1-50)

如果团队有命名约定（例如 agent-<branch> 或 <user>-<branch>），请遵循该约定。

创建一次，然后在每条命令中传入 -n

okteto namespace create <ns>     # creates it; reports if it already exists

然后，在本次会话的其余所有 Okteto 命令中传入 -n <ns>：

okteto deploy --wait -n <ns>
okteto build <service> -n <ns>
okteto endpoints -n <ns>
okteto logs <service> -n <ns>
okteto test <name> -n <ns>
okteto destroy -n <ns>

不要使用 okteto namespace use <ns> 来隔离工作树。 它会切换共享全局上下文中的活动命名空间；这会与同一台机器上的其他工作树或 Agent 产生竞争，还会悄悄重定向它们的命令。-n 标志仅对单次调用生效，且不会修改共享状态，因此可安全地并发使用。（只有在你仅有一个检出目录，且没有其他进程使用同一上下文时，才可以使用 okteto namespace use。）

---

清理和拆除

拆除环境和启动环境同样重要。请确保命令正确，也确保获得授权。

选择正确的命令

命令	功能	使用时机
okteto down	退出一个服务的开发模式；恢复原始部署。不会销毁环境。	开发者已完成对某个服务的迭代，但希望环境继续运行。
okteto destroy	拆除当前命名空间中由 okteto deploy 创建的所有资源。具有破坏性。	不再需要该环境，且已获准拆除。
okteto namespace delete <name>	删除整个命名空间及其中的所有内容。破坏性极大。	仅限 Agent 自己为隔离工作树创建的命名空间（参见工作树隔离），或根据用户的明确指示操作。绝不要在任务清理过程中删除共享或预先存在的命名空间。

常见错误是用户只想退出开发模式，却运行了 okteto destroy。如果不确定，安全的选择是 okteto down。

拆除隔离工作树的命名空间

如果你为工作树创建了专用命名空间（参见工作树隔离），那么完成工作且工作树即将移除时，你可以删除该命名空间：

okteto destroy -n <ns>           # remove the deployed resources
okteto namespace delete <ns>     # then remove the now-empty namespace you created

这是唯一一种无需单独指示就可以使用 okteto namespace delete 的情况——该命名空间由你创建，因此拆除它也是你的职责。这不会改变以下规则：不得删除你未创建的命名空间。

协作模式

不要自行运行 okteto destroy。将其作为建议提出，由开发者运行：

You're done with this environment. To tear it down, run:
  okteto destroy

如果开发者已明确完成某项服务的工作，Agent 可以运行 okteto down。

自主模式

仅在符合以下任一条件时运行 okteto destroy：

• 任务明确授权清理（例如，“PR 合并后销毁环境”）
• 仓库的 CLAUDE.md 或工单中记录了预先定义的清理策略
• 环境是临时的，且由流水线所有（例如，每次运行对应的预览环境）

如果以上条件均不适用，请让环境继续运行，并在报告中注明环境仍在运行，以及调用者可用于拆除环境的命令。让环境继续运行始终比销毁他人仍在依赖的环境更安全。

切勿这样做

• 删除并非由你创建的命名空间
• 未经明确指示，不要销毁共享环境或命名环境（例如，staging、dev）
• 出现问题时，不要将 okteto destroy 当作恢复步骤——先诊断问题

---

查找开发命令

查看每个服务的 okteto.yaml 中的 dev 部分。command 字段会说明服务如何启动：

• 如果是 command: bash，则需要手动构建并启动服务（检查服务目录中的 Makefile、package.json、pom.xml）
• 如果是 command: yarn start 或 command: mvn spring-boot:run，则服务会在开发模式下自动启动
• 检查服务目录中的 Makefile、package.json、pom.xml 或 go.mod，以确定可用的命令

CLI 快速参考

命令	协作模式	自主模式	用途
okteto deploy --wait	Agent	Agent	构建镜像并部署所有服务
okteto build <service>	Agent	Agent	构建并推送单个服务镜像
okteto up <service>	仅限用户	禁止	启动交互式开发容器
okteto down	Agent/用户	N/A	停止开发模式并恢复部署
okteto exec -- <cmd>	Agent	N/A	在活动开发容器中运行命令
okteto logs <service>	Agent	Agent	查看容器日志
okteto endpoints	Agent	Agent	列出公共 URL
okteto test <name>	Agent	Agent	从 okteto.yaml 启动测试容器
okteto destroy	用户	按策略执行	拆除所有资源
okteto doctor	Agent	Agent	生成诊断包
okteto status	Agent	N/A	检查文件同步进度
okteto validate	Agent	Agent	验证 okteto.yaml 清单语法
okteto context show	Agent	Agent	确认集群和命名空间
okteto namespace create <ns>	Agent	Agent	为工作树创建隔离命名空间
okteto namespace list	Agent	Agent	列出你有权访问的命名空间
okteto namespace delete <ns>	用户	仅限自行创建	删除命名空间（仅限你创建的命名空间）

**-n <ns> 标志：**上述每个命令（deploy、build、up、down、exec、logs、test、endpoints、destroy）都接受 -n <ns>，可在不更改当前上下文的情况下指定目标命名空间。请使用此标志，而不是 okteto namespace use，以隔离工作树（参见工作树隔离）。

应避免的常见错误

• 在自主模式下运行 okteto up：没有人可以与 shell 交互。请改用 okteto deploy + okteto build + okteto test。
• 在协作模式下以 Agent 身份运行 okteto up：它是交互式的。务必告知用户运行此命令。
• 忘记先部署：在进行任何验证或测试之前，先运行 okteto deploy。
• 未指定服务：有多个服务时，务必指定要使用的服务。
• 使用 kubectl/helm 修改集群：修改操作（kubectl apply、kubectl delete、helm upgrade 等）必须通过 okteto deploy 执行，以便 Okteto 跟踪资源。使用 kubectl/helm 进行只读诊断没有问题。
• 在本地构建 Docker 镜像：请使用 okteto build，以利用 Okteto Build Service。
• 硬编码服务名称：务必读取 okteto.yaml 以查找服务。
• 未经授权就销毁资源：在自主模式下，除非有明确的清理策略或指示，否则不要运行 okteto destroy。
• 多个工作树共用一个命名空间：两个工作树部署到同一命名空间会相互覆盖，而其中一个工作树运行 destroy 会清除另一个工作树的资源。请为每个工作树分配独立的命名空间（参见工作树隔离），并在每条命令中传入 -n <ns>。
• 使用 okteto namespace use 隔离并发工作：此命令会修改全局活动上下文，并与其他工作树/Agent 产生竞争。请改用每条命令的 -n <ns> 标志。