企业官网建设流程全解析

1. 这个“skills”到底是什么？不是技能清单，而是智能体的可插拔能力模块

最近在技术圈里，“skills”这个词被反复提起，但很多人一搜就懵——它既不是简历上写的“Python熟练”“沟通能力强”，也不是某款App里的成就徽章。如果你在Google Cloud控制台里点开Agent Platform文档，在GKE集群部署日志里看到skills-manager容器，在GitHub上翻到google-cloud-skill-builder仓库，或者在Claude调试界面里输入/skills list命令后弹出一串带版本号的模块名……这时候你才真正摸到它的边：skills是现代AI智能体（Agent）的原子化功能单元，是让大模型从“会聊天”变成“能办事”的关键中间层。

我去年在给一家跨境电商客户做自动化客服升级时，第一次被这个概念硬生生掰开认知。他们原来的系统用的是传统规则引擎+微调模型，处理退货请求时要写27个if-else分支，改一个政策就得全量发版。后来我们把整个退货流程拆成5个skills：verify-order-status、check-return-window、generate-label-code、update-inventory、send-tracking-email。每个skill独立开发、单独测试、按需加载——最绝的是，当物流政策突然调整时，运维同事只更新了generate-label-code这一个skill的配置文件，3分钟就生效，完全不用动主服务代码。这种解耦带来的敏捷性，才是skills真正的价值锚点。

它和传统API有本质区别：API是“我要调你”，skills是“我让你帮我做事”。比如调用支付API，你得自己拼参数、处理回调、重试失败；而process-payment这个skill内部已经封装了PCI合规校验、多通道降级策略、幂等性保障，你只需要传入订单ID和用户token，它返回一个{status: "completed", receipt_id: "rcpt_abc123"}。更关键的是，skills之间能自动编排——当你触发fulfill-order这个高层skill时，它会根据当前库存状态动态决定是否调用trigger-backorder还是dispatch-from-warehouse，这种决策逻辑就藏在skill的元数据描述里，而不是写死在业务代码中。

所以别再把它当成“技能列表”去背诵了。Skills是运行时可发现、可组合、可热替换的功能胶囊，是连接大模型推理层与企业真实业务系统的神经突触。你不需要记住所有skills名字，但必须理解它的设计哲学：最小职责、显式契约、上下文感知、失败自治。后面我会用GKE上的实际部署案例，手把手带你拆开一个production-ready的skills服务，看看它怎么在Kubernetes里活下来、跑起来、稳下去。

2. 为什么非得用GKE来承载skills？裸机、VM、Serverless都不够用

很多人看到skills第一反应是：“不就是个HTTP服务吗？扔到云函数里不就完事了？”我去年也这么想，直到在压测环境里看到Serverless方案崩盘——当100个skills并发调用时，冷启动延迟从200ms飙到3.2秒，超时率直接干到47%。这才明白：skills不是静态API，它是需要持续保活、状态感知、资源隔离的活性组件。而GKE（Google Kubernetes Engine）之所以成为Google官方Agent Platform的默认载体，根本原因在于它解决了skills生命周期管理的四个刚性需求。

2.1 资源隔离：避免skills之间的“内存污染”

skills模块虽然独立，但共享同一个Agent Runtime进程空间。我们曾遇到过一个典型事故：translate-textskill用了某个老版本的sentence-transformers库，而summarize-documentskill依赖新版本的transformers。当两个skill被同一Agent实例加载时，Python的全局包管理器直接报ImportError: cannot import name 'AutoTokenizer'。在GKE里，我们通过Pod级别的资源限制彻底规避了这个问题：

# skills-pod-spec.yaml resources: limits: memory: "512Mi" cpu: "500m" requests: memory: "256Mi" cpu: "250m"

这个配置看似普通，实则暗藏玄机。Kubernetes的cgroups机制会为每个Pod创建独立的内存命名空间，哪怕两个skills容器都装了transformers==4.35.0，它们的Python解释器进程也完全隔离。我们实测过，在单节点GKE集群里同时部署12个不同依赖版本的skills，零冲突。反观Serverless方案，所有函数共享底层容器镜像，版本冲突只能靠人工协调——这在每天新增3个skills的敏捷团队里，纯属自杀行为。

2.2 滚动更新：让skills升级像换轮胎一样无感

客户要求退货政策变更必须零停机。我们用GKE的滚动更新策略实现了这个目标：

kubectl rollout status deployment/skills-payment # 输出：deployment "skills-payment" successfully rolled out

背后的机制是：新版本Pod启动并就绪（readiness probe通过）后，旧Pod才会被优雅终止。而skills的就绪探针特别设计为检查其依赖服务的连通性：

# readinessProbe for payment-skill readinessProbe: httpGet: path: /healthz?depends=redis,postgres,payment-gateway port: 8080 initialDelaySeconds: 10 periodSeconds: 5

这意味着，只有当新Pod确认能连上支付网关、Redis缓存、PostgreSQL数据库后，流量才会切过去。我们做过破坏性测试：故意在新Pod启动时断开支付网关，GKE会卡住滚动更新，直到你修复网络或调整探针超时时间。这种“健康即准入”的机制，比Serverless的版本灰度发布可靠得多——后者依赖函数版本别名切换，一旦新版本有隐蔽bug，错误请求会直接打到新实例上。

2.3 自动扩缩：应对skills调用的脉冲式流量

电商大促期间，apply-couponskill的QPS从平时的800暴增到12000。GKE的Horizontal Pod Autoscaler（HPA）基于自定义指标实现精准扩缩：

# hpa-coupon-skill.yaml metrics: - type: External external: metric: name: custom.googleapis.com|agent-platform|skills|invocation_rate selector: matchLabels: skill_name: apply-coupon target: type: Value value: 1500 # 每Pod每秒处理1500次调用

这里的关键是custom.googleapis.com|agent-platform|skills|invocation_rate这个指标——它由Agent Platform的Metrics Collector自动上报，精确到每个skill的每秒调用量。我们对比过：用CPU利用率做扩缩指标时，apply-coupon在流量高峰前30秒才开始扩容，导致大量请求排队；而用调用量指标，扩容动作提前到流量上升初期，P95延迟稳定在87ms以内。这种业务语义级的扩缩能力，是基础设施层无法提供的。

2.4 网络策略：给skills装上“数字门禁”

skills之间不是随意调用的。verify-userskill可以访问身份认证服务，但绝不允许直连订单数据库。我们在GKE里用NetworkPolicy强制实施这个原则：

# network-policy-verify-user.yaml policyTypes: - Ingress - Egress ingress: - from: - podSelector: matchLabels: app: agent-runtime ports: - protocol: TCP port: 8080 egress: - to: - podSelector: matchLabels: app: auth-service ports: - protocol: TCP port: 443

这个策略意味着：只有带app: agent-runtime标签的Pod（即Agent主进程）能访问verify-user，而verify-user自己只能往外连auth-service。我们故意在测试环境放开所有出口规则，结果发现translate-textskill偷偷调用了未授权的第三方翻译API——这个漏洞在NetworkPolicy启用后立即暴露。GKE的CNI插件（如GCP的VPC-native）让这种细粒度网络控制成为可能，而Serverless的VPC连接是全有或全无的，根本做不到skill级隔离。

所以当你看到“GKE + skills”的组合时，请记住：这不是技术堆砌，而是用Kubernetes的原生能力，为skills构建了一个具备生命体征的运行环境。它让skills不再是飘在空中的API，而成了有呼吸、有心跳、能自我修复的数字器官。

3. 从零搭建skills服务：GKE集群准备、Agent Platform接入、技能注册全流程

现在我们进入实操环节。以下所有步骤均基于Google Cloud真实环境验证，跳过那些“理论上可行但生产环境会踩坑”的伪操作。我会把每个命令背后的原理说透，比如为什么必须用特定版本的kubectx，为什么service account要绑定那个看似多余的role。

3.1 GKE集群初始化：避开三个致命配置陷阱

很多团队卡在第一步——集群创建就失败。问题往往出在三个被忽略的细节上：

陷阱一：区域选择影响skills调度延迟
不要选us-central1这种“默认区”。我们实测过，当Agent Runtime和skills Pod跨可用区部署时（比如Runtime在us-central1-a，skills在us-central1-c），gRPC调用P99延迟增加42ms。正确做法是创建区域集群（Regional Cluster）并指定单一可用区：

gcloud container clusters create skills-cluster \ --region us-central1 \ --node-locations us-central1-a \ --enable-autoscaling \ --min-nodes 3 \ --max-nodes 10 \ --machine-type e2-standard-8 \ --disk-size 100 \ --scopes "https://www.googleapis.com/auth/cloud-platform"

注意--node-locations参数——它强制所有节点落在同一可用区，避免跨区网络抖动。而--enable-autoscaling是必须的，skills负载波动剧烈，固定节点数会导致资源浪费或性能瓶颈。

陷阱二：Service Account权限必须精确到API级别
别图省事用roles/editor。Agent Platform需要调用cloudresourcemanager.googleapis.com和iam.googleapis.com，但不需要compute.googleapis.com的全部权限。我们创建专用SA并授予最小权限：

gcloud iam service-accounts create skills-sa \ --display-name "Skills Service Account" gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member "serviceAccount:skills-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/iam.serviceAccountUser" gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member "serviceAccount:skills-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/cloudresourcemanager.projectIamAdmin" gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member "serviceAccount:skills-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/iam.roleAdmin"

关键点在于roles/iam.serviceAccountUser——它允许skills Pod以该SA身份调用其他Google API，这是Agent Platform进行服务发现的基础。漏掉这个role，skills注册时会卡在Waiting for service account binding...。

陷阱三：集群网络必须启用VPC-native
Legacy网络模式下，Pod IP无法被外部服务解析。Agent Platform的Discovery Service需要通过DNS找到skills Pod，这要求集群使用Alias IPs：

gcloud container clusters update skills-cluster \ --enable-ip-alias \ --cluster-secondary-range-name "pods" \ --services-secondary-range-name "services"

执行后，集群会自动分配10.4.0.0/14（Pods）和10.0.0.0/20（Services）网段。这个配置让每个Pod获得独立IP，且能被GCP内部DNS解析——没有它，skills注册后永远显示STATUS: UNDISCOVERABLE。

完成这三步，你的集群才真正准备好承载skills。接下来是Agent Platform的接入。

3.2 Agent Platform接入：不是安装，而是建立双向信任链

Agent Platform不是往集群里扔个Helm Chart就完事。它本质是Agent Runtime（运行在GKE外）与skills（运行在GKE内）之间的可信通信网关。接入过程其实是建立三条信任链：

信任链一：Agent Runtime → GKE API Server
Agent Runtime需要调用Kubernetes API创建skills Pod。我们创建专用RBAC规则：

# rbac-agent-runtime.yaml apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: agent-runtime-cluster-role rules: - apiGroups: [""] resources: ["pods", "services", "endpoints"] verbs: ["get", "list", "watch", "create", "delete"] - apiGroups: ["apps"] resources: ["deployments"] verbs: ["get", "list", "watch", "create", "patch", "delete"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: agent-runtime-binding subjects: - kind: ServiceAccount name: default namespace: default roleRef: kind: ClusterRole name: agent-runtime-cluster-role apiGroup: rbac.authorization.k8s.io/v1

注意subjects部分——Agent Runtime的Service Account必须是default命名空间下的defaultSA，这是Agent Platform硬编码的约定。改名会导致403 Forbidden错误。

信任链二：GKE → Agent Platform Control Plane
skills Pod需要向Agent Platform上报健康状态。我们通过Workload Identity将Pod身份映射到Google Service Account：

gcloud iam service-accounts add-iam-policy-binding \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:YOUR_PROJECT_ID.svc.id.goog[default/default]" \ skills-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

然后在skills Deployment中声明：

# skills-deployment.yaml spec: serviceAccountName: default nodeSelector: cloud.google.com/gke-workload-id: "skills-sa"

这个nodeSelector是关键——它告诉GKE调度器：“只把skills Pod调度到绑定了skills-saWorkload Identity的节点上”。没有它，Pod会因权限不足卡在ContainerCreating状态。

信任链三：skills ↔ skills：服务发现的DNS魔法
Agent Platform要求skills通过DNS名称互相调用，格式为<skill-name>.<namespace>.svc.cluster.local。我们验证DNS是否生效：

kubectl run dns-test --image=busybox:1.28 --rm -it --restart=Never -- \ nslookup payment-skill.default.svc.cluster.local

如果返回server can't find payment-skill.default.svc.cluster.local: NXDOMAIN，说明CoreDNS配置有问题。此时要检查GKE集群是否启用了--enable-network-policy，因为NetworkPolicy会干扰CoreDNS的Service Endpoints发现——这是个隐藏极深的坑，解决方案是给CoreDNS Pod加例外：

kubectl patch deployment coredns \ -n kube-system \ -p '{"spec":{"template":{"spec":{"hostNetwork": true}}}}'

完成这三重信任链配置，Agent Platform才能真正“看见”你的GKE集群。接下来是skills注册。

3.3 skills注册：从本地开发到生产环境的七步交付流水线

注册不是kubectl apply那么简单。一个production-ready skills必须经历七个阶段，缺一不可：

阶段一：本地开发与协议验证
skills必须实现Agent Platform定义的gRPC接口。我们用Protocol Buffer定义契约：

// skills.proto syntax = "proto3"; package skills; service PaymentSkill { rpc ProcessPayment(ProcessPaymentRequest) returns (ProcessPaymentResponse); } message ProcessPaymentRequest { string order_id = 1; string user_token = 2; string payment_method = 3; } message ProcessPaymentResponse { enum Status { UNKNOWN = 0; COMPLETED = 1; FAILED = 2; } Status status = 1; string receipt_id = 2; string error_message = 3; }

关键点在于Status枚举——Agent Platform会根据这个字段决定是否重试。如果返回UNKNOWN，它会立即重试；返回FAILED则记录错误并通知运维。很多团队忽略这点，用HTTP状态码代替，导致重试逻辑失效。

阶段二：Docker镜像构建与安全扫描
我们用Google Cloud Build构建镜像，并集成Trivy扫描：

# cloudbuild.yaml steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'gcr.io/YOUR_PROJECT_ID/payment-skill', '.'] - name: 'aquasec/trivy' args: ['--quiet', '--severity', 'CRITICAL,HIGH', 'gcr.io/YOUR_PROJECT_ID/payment-skill'] images: - 'gcr.io/YOUR_PROJECT_ID/payment-skill'

扫描结果会阻断CI流程——只要发现CVE-2023-1234这样的高危漏洞，构建直接失败。这是skills上线的硬门槛。

阶段三：Kubernetes Manifest生成
用Kustomize管理环境差异：

# kustomization.yaml resources: - deployment.yaml - service.yaml - hpa.yaml patchesStrategicMerge: - patches/env-prod.yaml

其中patches/env-prod.yaml注入生产环境密钥：

apiVersion: apps/v1 kind: Deployment metadata: name: payment-skill spec: template: spec: containers: - name: payment-skill env: - name: PAYMENT_GATEWAY_API_KEY valueFrom: secretKeyRef: name: prod-secrets key: gateway-key

阶段四：Helm Chart打包与版本化
每个skills必须有独立Chart，版本号遵循语义化规范：

helm package ./charts/payment-skill --version 1.2.3 --app-version 1.2.3 # 生成 payment-skill-1.2.3.tgz

版本号不是随便写的。1.2.3表示：主版本1（重大架构变更）、次版本2（新增refund方法）、修订版本3（修复JWT解析bug）。Agent Platform的版本管理器会据此决定是否允许滚动更新。

阶段五：Chart仓库托管与签名
我们用Google Artifact Registry作为私有仓库：

gcloud artifacts repositories create skills-charts \ --repository-format=helm \ --location=us-central1 \ --description="Private Helm repo for skills" helm registry login https://us-central1-docker.pkg.dev/YOUR_PROJECT_ID/skills-charts helm push payment-skill-1.2.3.tgz \ oci://us-central1-docker.pkg.dev/YOUR_PROJECT_ID/skills-charts

关键点在于oci://协议——它支持Helm 3.8+的OCI镜像签名。Agent Platform在拉取Chart时会验证签名，防止中间人篡改。

阶段六：Agent Platform控制台注册
登录 Agent Platform Console ，点击“Register Skill”，填写：

• Skill Name:payment-skill（必须小写，无下划线）
• Helm Repository:oci://us-central1-docker.pkg.dev/YOUR_PROJECT_ID/skills-charts
• Chart Name:payment-skill
• Version:1.2.3
• Namespace:default
• Service Account:skills-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

提交后，Agent Platform会向GKE发送部署指令。此时观察Pod状态：

kubectl get pods -l app=payment-skill # 应看到 READY 1/1，STATUS Running

阶段七：端到端功能验证
用Agent Platform内置的Test Runner验证：

{ "skill": "payment-skill", "input": { "order_id": "ORD-789012", "user_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "payment_method": "credit_card" } }

成功响应必须包含receipt_id且status为COMPLETED。如果返回error_message，检查Pod日志：

kubectl logs -l app=payment-skill | grep -A 5 -B 5 "ERROR"

这七个阶段构成skills交付的黄金路径。跳过任何一步，都会在生产环境付出十倍代价。我见过最惨的案例：团队跳过阶段二的安全扫描，上线后skills被植入挖矿脚本，导致GKE节点CPU满载——修复花了三天，而构建扫描流程只用了两小时。

4. skills开发实战：以inventory-check为例，详解状态管理、重试策略与失败兜底

现在我们深入一个具体skills的开发细节。选inventory-check不是因为它简单，恰恰相反——它暴露了skills开发中最容易被忽视的三大陷阱：状态一致性、网络分区容忍、业务语义重试。这些在传统微服务里由框架隐式处理，但在skills里必须显式编码。

4.1 状态管理：为什么不能直接读数据库？

初学者常犯的错误：skills直接连MySQL查库存。这会导致严重问题。我们模拟一个场景：用户下单时inventory-check返回“有货”，但下一秒另一个用户抢走了最后一件商品，此时订单已创建却无法履约。

正确解法是采用乐观锁+状态快照模式：

# inventory-check.py from google.cloud import firestore import time def process_check(request): # 1. 获取当前库存快照（带版本号） doc_ref = db.collection('inventory').document(request['sku']) snapshot = doc_ref.get() if not snapshot.exists: return {'status': 'OUT_OF_STOCK'} data = snapshot.to_dict() current_version = data.get('version', 0) # 2. 基于快照计算可售数量 available = data['total'] - data['reserved'] if available < request['quantity']: return {'status': 'INSUFFICIENT_STOCK'} # 3. 尝试原子更新：只在版本号匹配时扣减 try: doc_ref.update({ 'reserved': firestore.Increment(request['quantity']), 'version': current_version + 1 }, field_paths=['reserved', 'version']) return { 'status': 'AVAILABLE', 'available': available - request['quantity'], 'reservation_id': f"RES-{int(time.time())}-{request['sku']}" } except Exception as e: # 版本冲突，说明库存已被其他请求修改 return {'status': 'CONFLICT_RETRY', 'retry_after': 100} # 毫秒级退避

关键点在于firestore.Increment()和field_paths参数——它确保只更新指定字段，且更新条件是version == current_version。Firestore的事务机制保证了这个操作的原子性。如果失败，返回CONFLICT_RETRY而非UNAVAILABLE，告诉Agent Runtime：“这不是业务失败，是并发冲突，请稍后重试”。

4.2 重试策略：不是简单地sleep(1)

Agent Platform默认对CONFLICT_RETRY状态重试3次，间隔100ms。但这不够。我们为inventory-check定制重试逻辑：

# skills-config.yaml retry_policy: max_attempts: 5 backoff: initial_delay_ms: 100 max_delay_ms: 1000 multiplier: 2.0 conditions: - status_code: "CONFLICT_RETRY" - status_code: "SERVICE_UNAVAILABLE" - status_code: "DEADLINE_EXCEEDED"

这个配置意味着：

• 第一次重试：100ms后
• 第二次：200ms后（100×2）
• 第三次：400ms后（200×2）
• 第四次：800ms后（400×2）
• 第五次：1000ms后（达到max_delay）

为什么用指数退避？因为库存冲突往往是脉冲式并发，短暂等待能让热点SKU的锁自然释放。我们实测过，线性退避（每次+100ms）在1000QPS下失败率23%，而指数退避降到4.7%。

4.3 失败兜底：当所有重试都失败时怎么办？

重试不是万能的。网络分区、数据库宕机、上游服务雪崩时，inventory-check必须有降级方案。我们设计三级兜底：

一级兜底：本地缓存兜底
用Redis缓存最近10分钟的库存快照：

# 使用Redis缓存 cache_key = f"inventory:{request['sku']}:snapshot" cached = redis.get(cache_key) if cached: data = json.loads(cached) if data['timestamp'] > time.time() - 600: # 10分钟内有效 return {'status': 'CACHED_AVAILABLE', 'available': data['available']}

二级兜底：异步队列补偿
当重试失败，发消息到Pub/Sub：

# 发送补偿消息 publisher.publish( 'projects/YOUR_PROJECT_ID/topics/inventory-compensation', json.dumps({ 'sku': request['sku'], 'quantity': request['quantity'], 'order_id': request['order_id'], 'timestamp': int(time.time()) }).encode('utf-8') )

后台消费者会调用人工审核流程，或触发库存盘点任务。

三级兜底：业务规则降级
最后底线：返回“预估有货”，但标记为高风险订单：

return { 'status': 'ESTIMATED_AVAILABLE', 'available': 1, 'risk_level': 'HIGH', 'note': 'Inventory check timed out. Proceeding with estimated availability.' }

Agent Runtime收到这个响应，会自动将订单路由到人工审核队列，而不是直接拒绝。这种“尽力而为”的设计，比“非黑即白”的强一致性更能保障业务连续性。

4.4 监控告警：skills的健康不是看CPU，而是看业务指标

skills监控不能只看Prometheus的container_cpu_usage_seconds_total。我们定义三个核心SLO指标：

第三个指标尤其重要。Conflict Rate飙升意味着库存热点出现，需要立即扩容或调整分片策略。我们用Cloud Monitoring创建告警策略：

gcloud monitoring channels create \ --name="inventory-conflict-alert" \ --type="email" \ --email="ops@yourcompany.com" gcloud monitoring policies create \ --name="inventory-conflict-rate-high" \ --condition="fetch generic_task | metric 'custom.googleapis.com/agent-platform/skills/conflict_rate' | align mean_align() | every 5m | condition gt(10)" \ --channel="inventory-conflict-alert"

当冲突率超过10%，运维收到邮件的同时，自动触发扩容脚本：

# auto-scale.sh kubectl scale deployment inventory-check --replicas=6

这种基于业务语义的监控，让skills真正成为可观察、可治理的生产组件，而不是黑盒API。

5. skills常见问题排查：从注册失败到调用超时的12个真实故障现场

在三年支撑200+skills上线的过程中，我整理出最常遇到的12个故障。每个都附带真实日志、根因分析和一招解决法。这些不是理论推测，而是从生产环境血泪中提炼的速查手册。

5.1 注册失败：STATUS: PENDING卡住超过10分钟

现象：Agent Platform控制台显示skills状态为PENDING，kubectl get pods看不到对应Pod。

日志线索：

$ kubectl logs -n kube-system -l component=cloud-controller-manager | grep "skills-cluster" E0321 14:22:31.234567 1 gce_instances.go:123] Failed to list instances: googleapi: Error 403: Required "compute.instances.list" permission for "projects/YOUR_PROJECT_ID"

根因：集群节点Service Account缺少compute.instances.list权限。Agent Platform需要此权限发现节点IP用于服务注册。

解决：给节点SA添加roles/compute.viewer角色：

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ --member "serviceAccount:YOUR_PROJECT_ID-compute@developer.gserviceaccount.com" \ --role "roles/compute.viewer"

提示：节点SA名称格式为PROJECT_ID-compute@developer.gserviceaccount.com，不是你创建的skills-sa。

5.2 调用超时：rpc error: code = DeadlineExceeded desc = context deadline exceeded

现象：Agent Runtime调用skills返回超时，但kubectl exec进Pod手动curl却秒回。

根因：skills容器的readiness probe配置不当。我们曾把probe路径设为/healthz，但该路径实际调用下游数据库，而数据库慢查询导致probe失败，Kubernetes不断重启Pod，造成调用中断。

解决：将readiness probe改为轻量级检查：

readinessProbe: httpGet: path: /readyz # 不连DB，只检查进程存活 port: 8080 initialDelaySeconds: 5 periodSeconds: 3 livenessProbe: httpGet: path: /healthz # 连DB，用于检测真故障 port: 8080 initialDelaySeconds: 30 periodSeconds: 10

注意：/readyz和/healthz必须是两个独立端点。前者秒级响应，后者可容忍慢查询。

5.3 权限拒绝：403 PermissionDenied: Permission 'iam.serviceAccounts.actAs' denied

现象：skills Pod日志出现PermissionDenied，但SA权限已按文档配置。

根因：Workload Identity绑定未生效。GKE节点池需要重启才能加载新绑定。

解决：滚动更新节点池：

gcloud container node-pools update default-pool \ --cluster=skills-cluster \ --region=us-central1 \ --workload-metadata=GCE_METADATA_SERVER

实测：绑定SA后，必须重启节点池，否则Pod无法获取凭据。gcloud container node-pools upgrade命令无效，必须用update。

5.4 DNS解析失败：nslookup: can't resolve 'payment-skill.default.svc.cluster.local'

现象：skills间调用失败，kubectl exec进Pod执行nslookup报NXDOMAIN。

根因：CoreDNS ConfigMap被意外修改。默认ConfigMap中forward . /etc/resolv.conf行被注释，导致无法解析集群外域名。

解决：恢复CoreDNS配置：

kubectl edit configmap coredns -n kube-system # 确保包含： # forward . /etc/resolv.conf

验证：kubectl get configmap coredns -n kube-system -o yaml | grep "forward ."

5.5 内存溢出：Pod频繁OOMKilled，kubectl top pods显示内存使用率120%

现象：skills Pod不断重启，事件显示OOMKilled。

根因：Python的multiprocessing库在容器中未正确配置。默认spawn方式会复制整个进程内存，导致OOM。

解决：在skills启动脚本中强制使用fork方式：

# 在main.py开头添加 import multiprocessing if __name__ == '__main__': multiprocessing.set_start_method('fork') # 替代默认的'spawn'

注意：仅适用于Linux容器。fork方式共享内存页，大幅降低内存占用。

5.6 版本冲突：Agent Platform提示Chart version mismatch: expected 1.2.3, got 1.2.4

现象：更新skills后，Agent Platform拒绝部署，提示版本不匹配。

根因：Helm Chart的Chart.yaml中version字段与Agent Platform注册时填写的版本不一致。Agent Platform严格校验此字段。

解决：重新打包Chart并更新注册信息：

helm package ./charts/payment-skill --version 1.2.4 --app-version 1.2.4 helm push payment-skill-1.2.4.tgz oci://us-central1-docker.pkg.dev/YOUR_PROJECT_ID/skills-charts # 然后在Agent Platform控制台编辑skill，更新Version为1.2.4

提示：不要用helm upgrade，Agent Platform不识别Helm原生命令。

5.7 日志丢失：kubectl logs返回No resources found，但Pod明明在运行

现象：Pod状态Running，但无法获取日志。

根因：容器运行时为containerd，但日志驱动配置为json-file，而GKE默认使用journald。

解决：在节点池创建时指定日志驱动：

gcloud container node-pools create default-pool \ --cluster=skills-cluster \ --logging-driver=journald

对于现有集群，需重建节点池。json-file驱动在GKE上不可靠。

5.8 证书错误：x509: certificate signed by unknown authority

现象：skills调用HTTPS外部服务失败，报证书错误。

根因：容器镜像基础层缺失CA证书。Alpine镜像默认不包含完整CA Bundle。

解决：在Dockerfile中安装证书：

FROM