用途
Maestro 用于在 Kubernetes 上编排开发者环境。项目由 Go API 与 Rust CLI 组成，运行在 GKE（生产/预发）和 k3d（本地，通过 Tilt）上。本技能适用于开发 Maestro 项目时，包括 K8s Pod 管理、Tilt 本地开发、GKE 部署、Go+Rust 代码生成、n8n 工作流或 Maestro CLI 开发等场景。
项目结构
项目根目录为 /Users/joe/dev/maestro/，包含：
- api/：Go API 服务器（K8s Pod 生命周期、n8n、E2E 运行器）
- cli/：Rust CLI（maestro 二进制、认证、Pod 命令）
- infra/：Terraform 与 Helm charts
- tilt/：Tiltfiles 与本地开发配置
- Makefile：build、test、lint、dev-setup、install-hooks
本地开发（Tilt）
常用命令：
- tilt up：启动 k3d 集群及所有服务
- tilt logs -f <resource>：流式查看日志
- tilt trigger <resource>：强制重建某个资源
- tilt down：拆除（安全——仅限本地）
Tilt 会监视源文件并在变更时重建容器。应让 Tilt 管理重建，不要手动重启服务。
GKE 上下文
认证（每会话一次或令牌过期时）：
gcloud auth login
gcloud container clusters get-credentials main-0 --region us-east1 --project toptal-maestro
验证：
kubectl config current-context
# → gke_toptal-maestro_us-east1_main-0
切回本地 k3d：
kubectl config use-context k3d-maestro
常用 kubectl 操作
- kubectl get pods -n sessions：列出活跃会话 Pod
- kubectl logs -n sessions <pod> --tail=100：查看 Pod 日志
- kubectl describe pod -n sessions <pod>：查看事件、资源限制、状态
- kubectl port-forward svc/maestro-api 8080:8080 -n maestro：本地访问 API
- kubectl get events -n sessions --sort-by=.lastTimestamp：查看最近事件
安全规则
- 绝不在没有 --selector 或明确 Pod 名称的情况下删除 Pod：可能终止活跃开发会话
- 绝不在 sessions 命名空间运行 kubectl delete all：会销毁所有活跃环境
- 在任何 docker rm/stop 前检查 $MAESTRO_CONTAINER_ID：可能终止自己的容器
- 基础设施变更（Terraform/Helm）：先提出计划并获得批准（参见 infrastructure-plan-first 技能）
- 绝不重置共享服务凭据：会影响所有开发者
Go 约定
- 接口定义在使用方（而非实现包中）
- 错误使用 %w 包装以便链式检查
- 所有服务/处理方法第一个参数为 Context
- 提交前运行 go test ./... -race
- api/ 包覆盖率 ≥80%
Rust CLI 约定
- Edition 2024，六边形架构（cli/domain/、cli/adapters/）
- cargo clippy -- -D warnings 与 cargo fmt 必须通过
- 认证令牌通过 keyring crate（操作系统钥匙串）存储，绝不使用明文
构建与测试
- make build：构建 API + CLI
- make test：运行所有测试
- make lint：go vet + cargo clippy
- make install-hooks：pre-commit、pre-push
常见问题
- Colima 未运行：colima start
- gcloud 认证过期：gcloud auth login
- kubectl 上下文错误：gcloud container clusters get-credentials main-0 --region us-east1 --project toptal-maestro
- Tilt 文件监视限制：ulimit -n 10000
- maestro 认证过期：MAESTRO_API_URL=https://api.maestro-staging.toptal.net maestro auth login