企业官网建设流程全解析

1. 项目概述：当“skills”不再是个模糊标签，而是一套可定义、可组合、可部署的智能体能力单元

最近翻看团队内部的周报和协作平台里的需求池，“skills”这个词出现频率高得有点反常——不是在HR的胜任力模型里，也不是在培训计划PPT中，而是在工程师写的PR描述、产品经理的PRD备注、甚至运维同学的告警日志里。比如：“已为订单履约Agent新增inventory-check-skill-v2.3，支持跨仓实时锁库存”；又或者：“payment-retry-skill触发阈值从3次调整为5次，避免短时网络抖动误判”。这让我意识到，我们正在经历一个隐性但关键的范式迁移：“skills”正从人力资源领域的抽象能力描述，蜕变为工程系统中可版本化、可灰度发布、可独立监控的最小功能原子。它不是API，不是微服务，也不是传统插件；它是面向智能体（Agent）运行时环境设计的、带上下文感知与执行约束的能力封装体。核心关键词如Google Cloud、GKE、Gemini、Agent Platform，恰恰勾勒出这个演进的技术坐标系：底层是云原生基础设施（GKE），中间是大模型驱动的智能体编排层（Agent Platform），上层是具体能力实现（skills），而Gemini则作为推理引擎深度嵌入其中——它不直接暴露给终端用户调用，而是作为skills内部的“思考内核”，负责将自然语言指令转化为结构化动作序列。所以，当你看到热搜里反复出现的“gemini登录”“your account is not eligible for gemini code assist”，背后其实是开发者在尝试接入这个能力底座时，遭遇了权限模型、配额策略与技能注册流程的三重卡点。这不是一个简单的工具安装问题，而是一个新软件范式的准入门槛。本文要讲的，就是如何绕过这些表层噪音，直击本质：在GKE集群上，基于Google Cloud Agent Platform SDK，构建一个可被Gemini原生调用、具备完整生命周期管理的skills工程体系。适合已经跑通基础LLM API调用、熟悉Kubernetes部署流程、正着手搭建内部Agent平台的中高级工程师与技术负责人。你不需要从零造轮子，但必须理解每个齿轮咬合的物理逻辑。

2. 整体架构设计与技术选型逻辑：为什么是GKE + Agent Platform + Gemini，而不是其他组合？

2.1 架构分层：从“能用”到“稳用”的三层跃迁

很多团队初期会陷入一个典型误区：把skills简单等同于一个HTTP接口封装。比如写个Python脚本调用Gemini API生成SQL，再用Flask包一层，就宣称“我们有了skills”。这在POC阶段可行，但一旦进入生产环境，立刻暴露出四个致命短板：无状态漂移、无执行上下文、无权限隔离、无可观测性。真正的skills架构必须解决这四个问题，因此我坚持采用三层解耦设计：

• 最底层：GKE集群作为能力执行沙盒
  所有skills必须以Pod形式在GKE中独立运行。这不是为了“上云而上云”，而是利用Kubernetes原生的资源隔离（CPU/Memory Limit）、网络策略（NetworkPolicy禁止Pod间直连）、服务发现（Headless Service提供稳定DNS）三大能力，确保一个skills的崩溃、内存泄漏或恶意请求，绝不会波及另一个。我见过太多团队用单体Node.js服务承载所有skills，结果一个正则表达式回溯攻击就拖垮整个Agent网关。GKE的Horizontal Pod Autoscaler（HPA）还能根据/healthz探针响应延迟自动扩缩容，这对处理Gemini推理的突发流量至关重要——毕竟模型调用不是线性增长，而是呈脉冲式爆发。

• 中间层：Google Cloud Agent Platform作为能力调度中枢
  这是区别于自研方案的核心。Agent Platform并非一个黑盒SaaS，而是一套可深度集成的SDK与控制平面。它的价值在于提供了skills注册中心（Registry）、意图路由引擎（Intent Router）、执行上下文注入器（Context Injector）三大能力。举个例子：当用户说“帮我对比上周和本月的销售数据”，Agent Platform会先解析出compare-sales-data这个意图，然后查询Registry确认哪个skills声明了对该意图的支持（比如sales-analytics-skill），再将用户当前的组织ID、时间范围偏好、数据源权限令牌等上下文信息，通过Envoy Sidecar注入到目标Pod的启动参数中。这个过程完全透明，开发者只需在skills代码里读取os.environ.get("CONTEXT_ORG_ID")即可。如果你试图用Nginx+Consul自己拼凑这套逻辑，光是意图歧义消解（比如“删除邮件”到底是删收件箱还是删草稿箱）就会耗费数月。

• 最上层：Gemini作为skills的“认知内核”，而非“对外接口”
  这是最常被误解的一点。热搜里大量“gemini登录失败”问题，根源在于用户试图让终端用户直接调用Gemini API。正确的做法是：Gemini只在skills Pod内部调用，且仅用于决策环节。比如code-review-skill接收到一段PR diff，它先用本地规则引擎做基础检查（行数超限？敏感词？），再将剩余内容喂给Gemini，要求其输出JSON格式的评审意见（{"severity": "high", "line": 42, "suggestion": "建议添加空指针检查"}）。Gemini的输出永远不直接返回给用户，而是由skills代码进行二次校验、脱敏、格式化后，才通过Agent Platform的Response Channel发出。这样既规避了Gemini的token限制与速率管控，又保证了输出的可控性与合规性。所谓“superpower skills”，本质是这种“规则引擎+大模型”的混合增强模式，而非单纯依赖大模型。

2.2 关键技术选型背后的硬性约束

选型从来不是比参数，而是比谁更扛得住生产环境的“毒打”。以下是几个关键决策点及其血泪教训：

• 为什么不用Cloud Run替代GKE？
  Cloud Run确实更轻量，但它的冷启动延迟（平均800ms）对交互式Agent场景是灾难。我们做过压测：当10个skills并发调用Gemini时，Cloud Run实例因内存不足频繁重启，导致context timeout错误率飙升至37%。而GKE的Pod预热机制（通过livenessProbe持续探测）能将首字节延迟稳定在120ms以内。更重要的是，Cloud Run不支持StatefulSet，而某些skills（如database-migration-skill）必须挂载持久卷保存迁移日志，这是硬性需求。

• 为什么Agent Platform SDK必须用Go版本，而非Python？
  官方虽提供多语言SDK，但Go版是唯一支持实时上下文流式注入的。Python版SDK在处理长对话时，会因GIL锁导致上下文更新延迟，造成skills看到的用户状态是3秒前的旧数据。我们在金融风控场景下实测过：当用户连续说“把转账限额提到5万”“不对，改成3万”“算了，还是2万吧”，Python版skills最终执行的是第一条指令，而Go版能精准捕获最后一次修改。这个差异在交易类应用中就是合规红线。

• Gemini模型版本选择：为什么锁定gemini-1.5-pro-001而非最新版？
  热搜里“gemini chabox”“gemini macbook下载”反映的是开发者对本地调试的渴望，但生产环境必须克制。gemini-1.5-pro-001是目前唯一通过Google Cloud SOC2 Type II认证的版本，其输出token具有确定性哈希（可通过response.candidates[0].content.parts[0].text的SHA256校验），这对审计日志留存至关重要。而测试版模型（如gemini-1.5-flash）的随机性会导致同一输入产生不同输出，无法满足金融、医疗行业的可追溯要求。我们曾因未锁定版本，在一次监管检查中被要求回溯3个月的所有AI决策，最终靠001版的确定性哈希才免于处罚。

3. 核心细节解析与实操要点：从注册到上线的12个关键节点

3.1 Skills注册：不是上传ZIP包，而是提交一份“能力契约”

在Agent Platform控制台点击“Register New Skill”，你以为只是填个名字和描述？错。这本质上是在签署一份运行时契约（Runtime Contract），它决定了skills在集群中的生存权。契约包含五个强制字段，缺一不可：

1. Intent Schema（意图模式）：必须用JSON Schema定义skills能响应的自然语言模式。例如sales-analytics-skill的Schema不能只写{"type": "object"}，而要精确到：

   { "type": "object", "properties": { "time_range": {"enum": ["last_week", "this_month", "custom"]}, "metrics": {"type": "array", "items": {"enum": ["revenue", "orders", "avg_order_value"]}}, "comparison": {"type": "boolean"} }, "required": ["time_range", "metrics"] }

   这个Schema会被Agent Platform编译成正则表达式树，用于在用户语句中快速匹配意图。如果写得太宽泛（如允许"time_range": "string"），会导致误触发；太狭窄（如只支持"last_week"），又会漏掉真实需求。我们的经验是：先收集1000条真实用户query，用spaCy做实体识别，再反向推导Schema边界。

2. Execution Constraints（执行约束）：定义skills的“行为红线”。包括：

   • max_execution_time_ms: 必须≤5000（Agent Platform默认超时是5秒，超时即强杀）
   • allowed_network_endpoints: 白名单URL，如["https://api.salesforce.com", "https://redshift-cluster.us-east-1.redshift.amazonaws.com"]。任何对非白名单域名的HTTP请求都会被Envoy Sidecar拦截并返回403。
   • memory_limit_mb: 必须≤1024（GKE默认Pod内存上限，超限触发OOMKilled）

3. Context Requirements（上下文依赖）：声明skills需要哪些用户上下文。比如hr-onboarding-skill必须声明["user_employee_id", "department_code", "manager_email"]。Agent Platform会在调用前验证这些字段是否存在于用户会话中，缺失则直接拒绝路由，避免skills内部做空指针判断。

4. Output Schema（输出规范）：定义skills返回给Agent Platform的结构。必须是严格JSON，且包含status（"success"/"error"）、data（业务数据）、suggested_next_steps（引导用户下一步的按钮数组）三个顶层字段。这是Agent Platform渲染UI的唯一依据。我们曾因data字段嵌套过深（>5层），导致前端解析超时，最终用jsonschema库在skills启动时做Schema校验才解决。

5. Health Check Endpoint（健康探针）：必须提供/healthz端点，返回{"status": "ok", "timestamp": "ISO8601"}。Agent Platform每10秒调用一次，连续3次失败则将该Pod从服务发现中剔除。注意：这个端点不能依赖外部服务（如DB连接），否则网络抖动会导致误判。我们用/healthz只检查本地goroutine数量和内存使用率，确保探针本身绝对轻量。

提示：契约提交后，Agent Platform会生成一个唯一的skill_id（如us-central1/sales-analytics-20240515），后续所有操作（部署、灰度、监控）都以此ID为索引。切勿手动修改ID，否则会导致历史调用链路断裂。

3.2 GKE集群配置：让Skills真正“扎根”云原生

Skills不是跑在虚拟机上的传统应用，它对Kubernetes的配置有特殊要求。以下是我们在线上集群中强制启用的七项配置，少一项都可能引发深夜告警：

• 启用Workload Identity（工作负载身份）：这是GKE与Google Cloud服务（如Secret Manager、Vertex AI）安全通信的基石。必须为每个skills命名空间创建专用ServiceAccount，并绑定IAM角色。例如sales-analytics-skill需要roles/secretmanager.secretAccessor角色来读取数据库密码。我们严禁使用defaultServiceAccount，因为它的权限过大，一旦Pod被攻破，攻击者可横向移动至整个项目。

• 配置ResourceQuota（资源配额）：为skills命名空间设置硬性上限：

  apiVersion: v1 kind: ResourceQuota metadata: name: skills-quota spec: hard: requests.cpu: "4" requests.memory: 8Gi limits.cpu: "8" limits.memory: 16Gi pods: "20"

  这防止某个skills因bug无限创建Pod耗尽集群资源。特别注意pods配额，我们线上曾因logging-skill的logrotate配置错误，导致单个Pod生成数千个临时文件，触发Kubelet的eviction机制，连带杀死同节点的其他skills。

• 部署Prometheus Operator与Custom Metrics Adapter：Skills的监控不能只看CPU/Memory。必须采集自定义指标：skills_execution_duration_seconds（执行耗时）、skills_intent_match_rate（意图匹配成功率）、skills_gemini_call_count（Gemini调用次数）。这些指标通过Prometheus Client库暴露，再经Custom Metrics Adapter转换为Kubernetes Metrics API，供HPA使用。没有这个，你的自动扩缩容就是盲人摸象。

• 启用NetworkPolicy（网络策略）：Skills Pod默认拒绝所有入站流量，只允许来自Agent Platform Ingress Controller的访问。出站流量则严格按契约中的allowed_network_endpoints放行。我们用kubebuilder自动生成NetworkPolicy YAML，确保每次skills更新时策略同步刷新。

• 配置Vertical Pod Autoscaler（VPA）：不同于HPA管副本数，VPA管单个Pod的资源请求。它会分析过去7天的资源使用曲线，自动调整requests.cpu/memory。这对Gemini密集型skills尤其重要——模型推理内存占用波动极大，固定配额要么浪费（低峰期），要么OOM（高峰期）。VPA的推荐值会写入PodTemplate，下次滚动更新时生效。

• 启用Container-Optimized OS（COS）镜像：GKE节点OS必须用COS而非Ubuntu。COS专为容器优化，内核模块精简，启动更快，且默认启用seccomp和apparmor安全策略。我们实测过：相同skills在COS上冷启动比Ubuntu快1.8倍，且docker stats显示内存碎片率低42%。

• 配置Cluster Autoscaler（集群自动扩缩容）：当所有节点资源利用率>70%时，自动添加新节点。但必须设置--balance-similar-node-groups=true，否则CA会不断在新老节点间迁移Pod，导致skills频繁重启。我们线上集群的CA配置中，min-nodes=3是底线，低于此数无法容忍单节点故障。

3.3 Skills代码实现：一个可复用的Go模板骨架

别被“skills开发”这个术语吓住。它本质就是一个符合特定接口规范的HTTP服务。以下是我们在生产环境验证过的Go模板，去掉业务逻辑后仅217行，却覆盖了90%的共性需求：

package main import ( "context" "encoding/json" "fmt" "log" "net/http" "os" "time" "cloud.google.com/go/secretmanager/apiv1" "github.com/google/uuid" "google.golang.org/api/option" "google.golang.org/api/option/internaloption" ) // ExecutionRequest 是Agent Platform传入的标准结构 type ExecutionRequest struct { IntentID string `json:"intent_id"` Context map[string]interface{} `json:"context"` Input map[string]interface{} `json:"input"` SkillID string `json:"skill_id"` ExecutionID string `json:"execution_id"` } // ExecutionResponse 是skills必须返回的标准结构 type ExecutionResponse struct { Status string `json:"status"` Data interface{} `json:"data"` SuggestedNextSteps []struct { Label string `json:"label"` Action string `json:"action"` } `json:"suggested_next_steps"` Error string `json:"error,omitempty"` } func main() { http.HandleFunc("/execute", handleExecute) http.HandleFunc("/healthz", handleHealthz) port := os.Getenv("PORT") if port == "" { port = "8080" } log.Printf("Starting skills server on port %s", port) log.Fatal(http.ListenAndServe(fmt.Sprintf(":%s", port), nil)) } func handleExecute(w http.ResponseWriter, r *http.Request) { start := time.Now() defer func() { duration := time.Since(start).Seconds() // 上报自定义指标：skills_execution_duration_seconds{skill_id="sales-analytics"} log.Printf("Execution completed in %.3f seconds", duration) }() var req ExecutionRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { http.Error(w, "Invalid JSON", http.StatusBadRequest) return } // 1. 验证上下文完整性（契约要求的字段必须存在） requiredContext := []string{"user_employee_id", "department_code"} for _, key := range requiredContext { if _, ok := req.Context[key]; !ok { http.Error(w, fmt.Sprintf("Missing context: %s", key), http.StatusBadRequest) return } } // 2. 从Secret Manager安全获取凭证（非硬编码） creds, err := getSecretFromGCP("projects/123456/secrets/db-password/versions/latest") if err != nil { http.Error(w, "Failed to fetch secret", http.StatusInternalServerError) return } // 3. 执行核心业务逻辑（此处替换为你的代码） result, err := executeBusinessLogic(req.Input, creds) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } // 4. 构建标准响应 resp := ExecutionResponse{ Status: "success", Data: result, SuggestedNextSteps: []struct { Label string `json:"label"` Action string `json:"action"` }{ {Label: "查看详细报表", Action: "open-report-dashboard"}, {Label: "导出Excel", Action: "export-to-excel"}, }, } w.Header().Set("Content-Type", "application/json") json.NewEncoder(w).Encode(resp) } func handleHealthz(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") json.NewEncoder(w).Encode(map[string]string{ "status": "ok", "timestamp": time.Now().UTC().Format(time.RFC3339), }) } // getSecretFromGCP 演示如何安全获取密钥（生产环境必须用Workload Identity） func getSecretFromGCP(name string) (string, error) { ctx := context.Background() client, err := secretmanager.NewClient(ctx, option.WithCredentialsFile("/var/run/secrets/google/service-account.json")) if err != nil { return "", err } defer client.Close() req := &secretmanagerpb.AccessSecretVersionRequest{ Name: name, } result, err := client.AccessSecretVersion(ctx, req) if err != nil { return "", err } return string(result.Payload.Data), nil } // executeBusinessLogic 是你的业务核心，此处仅为示意 func executeBusinessLogic(input map[string]interface{}, dbPassword string) (map[string]interface{}, error) { // 实际代码：连接DB、调用Gemini、生成报告... return map[string]interface{}{ "report_url": "https://storage.googleapis.com/reports/20240515.pdf", "summary": "销售额环比增长12.3%", }, nil }

这个模板的关键设计哲学是：把所有非业务代码（认证、监控、健康检查、上下文验证）抽离成框架层，让开发者专注executeBusinessLogic这一函数。我们团队用此模板支撑了47个skills，平均开发周期从3人日压缩到0.5人日。注意几个魔鬼细节：

• /execute端点必须是POST方法，且必须接受JSON body。Agent Platform不支持GET传参，因为意图参数可能超长（如整段代码diff）。
• ExecutionID必须透传并记录。这是全链路追踪的TraceID，所有日志、Metrics、Span都需带上它。我们用log.Printf("[exec-%s] ...", req.ExecutionID)统一打点。
• Secret获取必须走GCP Secret Manager。绝不允许在环境变量中明文存储密码，这是Google Cloud安全审计的否决项。
• SuggestedNextSteps的Action字段必须是预定义枚举值。Agent Platform前端会根据此值渲染对应UI组件（如open-report-dashboard触发新Tab页，export-to-excel触发文件下载），自定义字符串会导致前端静默失败。

4. 实操过程与核心环节实现：从本地开发到灰度发布的全流程

4.1 本地开发：绕过Gemini配额限制的“影子模式”

热搜里“gemini登录失败”“account not eligible”等问题，根源在于Google Cloud对免费试用账户的严格配额管控。个人账户的Gemini API调用额度极低（通常<100次/天），根本不够本地调试。我们的解决方案是：在本地启动一个“影子Gemini服务”，模拟真实API行为，但返回预设的JSON响应。

步骤如下：

1. 创建mock-gemini-server.go：

   package main import ( "encoding/json" "log" "net/http" "time" ) type MockResponse struct { Candidates []struct { Content struct { Parts []struct { Text string `json:"text"` } `json:"parts"` } `json:"content"` } `json:"candidates"` } func main() { http.HandleFunc("/v1beta/models/gemini-1.5-pro:generateContent", func(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") // 根据请求body中的prompt关键词返回不同响应 var req map[string]interface{} json.NewDecoder(r.Body).Decode(&req) prompt := req["contents"].([]interface{})[0].(map[string]interface{})["parts"].([]interface{})[0].(map[string]interface{})["text"].(string) var resp MockResponse switch { case contains(prompt, "SQL"): resp = MockResponse{Candidates: []struct{ Content struct{ Parts []struct{ Text string } } }{ {Content: struct{ Parts []struct{ Text string } }{Parts: []struct{ Text string }{{Text: `{"sql": "SELECT * FROM sales WHERE date > '2024-05-01'"}}}}}, }} case contains(prompt, "review"): resp = MockResponse{Candidates: []struct{ Content struct{ Parts []struct{ Text string } } }{ {Content: struct{ Parts []struct{ Text string } }{Parts: []struct{ Text string }{{Text: `{"severity": "medium", "line": 23, "suggestion": "添加错误处理"}`}}}}}, }} default: resp = MockResponse{Candidates: []struct{ Content struct{ Parts []struct{ Text string } } }{ {Content: struct{ Parts []struct{ Text string } }{Parts: []struct{ Text string }{{Text: `{"response": "I can help with SQL generation and code review."}`}}}}}, }} } json.NewEncoder(w).Encode(resp) }) log.Println("Mock Gemini server started on :8081") log.Fatal(http.ListenAndServe(":8081", nil)) } func contains(s, substr string) bool { return len(s) >= len(substr) && s[:len(substr)] == substr }

2. 在skills代码中，将Gemini API URL动态切换：

   // 在main.go中 var geminiEndpoint = "https://generativelanguage.googleapis.com/v1beta" if os.Getenv("ENV") == "local" { geminiEndpoint = "http://localhost:8081" }

3. 启动时指定环境：

   # 本地调试 ENV=local go run main.go # 生产部署 ENV=prod go run main.go

这个“影子模式”让我们彻底摆脱了配额限制。开发人员可以无限次测试各种prompt分支，而无需担心触发Google Cloud的配额告警。更重要的是，它强制团队在开发早期就思考：哪些prompt路径是高频的？哪些响应格式是必须兼容的？这些思考最终沉淀为Intent Schema的精确描述。

4.2 CI/CD流水线：从Git Push到GKE部署的5分钟自动化

Skills的发布必须像微服务一样可靠。我们使用Cloud Build构建CI/CD流水线，全程无人值守，平均耗时4分32秒。关键阶段如下：

其中最易被忽视的是第3步镜像构建。我们强制要求：

• 使用distroless基础镜像，剔除所有shell、包管理器，将攻击面缩小92%；
• 镜像大小上限120MB，超限则触发警告（过大镜像导致GKE节点拉取超时）；
• 构建时注入BUILD_TIME和GIT_COMMIT环境变量，写入二进制文件的/version端点，便于线上排查。

deployment.yaml也经过深度定制：

apiVersion: apps/v1 kind: Deployment metadata: name: sales-analytics-skill labels: app: sales-analytics-skill spec: replicas: 2 selector: matchLabels: app: sales-analytics-skill template: metadata: labels: app: sales-analytics-skill annotations: # 关键：启用PodDisruptionBudget，确保灰度期间至少1个Pod在线 pod.alpha.kubernetes.io/init-containers: '[{"name":"init","image":"gcr.io/my-project/skill-init:latest"}]' spec: serviceAccountName: sales-analytics-skill-sa # 绑定Workload Identity containers: - name: skill image: gcr.io/my-project/sales-analytics-skill:{{COMMIT_SHA}} ports: - containerPort: 8080 livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 5 periodSeconds: 5 resources: requests: cpu: "200m" memory: "512Mi" limits: cpu: "1" memory: "1Gi" # 关键：启用PodDisruptionBudget disruptionBudget: minAvailable: 1

这个配置确保了灰度发布的安全性：当新版本Pod启动时，K8s会先等待其readinessProbe通过，再将流量切过去；同时PodDisruptionBudget保证任何时候至少有1个旧版本Pod在线，直到新版本完全就绪。我们线上从未发生过灰度期间服务中断。

4.3 灰度发布与流量切分：用Istio实现0.1%到100%的渐进式上线

Skills上线最危险的时刻不是发布，而是“全量”。我们用Istio Service Mesh实现毫秒级流量切分，将风险降至最低：

1. 定义VirtualService（istio/virtualservice.yaml）：

   apiVersion: networking.istio.io/v1beta1 kind: VirtualService metadata: name: sales-analytics-skill spec: hosts: - sales-analytics-skill.my-namespace.svc.cluster.local http: - route: - destination: host: sales-analytics-skill subset: v1 weight: 999 # 99.9% - destination: host: sales-analytics-skill subset: v2 weight: 1 # 0.1%

2. 定义DestinationRule（istio/destinationrule.yaml）：

   apiVersion: networking.istio.io/v1beta1 kind: DestinationRule metadata: name: sales-analytics-skill spec: host: sales-analytics-skill subsets: - name: v1 labels: version: v1 - name: v2 labels: version: v2

3. 上线流程：

   • Step 1：部署v2版本Pod（带version: v2标签），但不修改VirtualService，此时100%流量仍在v1；
   • Step 2：将VirtualService中weight从999/1改为990/10（99%/1%），观察10分钟监控；
   • Step 3：若skills_execution_duration_secondsP95未升高、skills_intent_match_rate未下降，则逐步增加v2权重至50%、90%、100%；
   • Step 4：全程通过Grafana看板监控两个关键指标：istio_requests_total{destination_service="sales-analytics-skill", response_code=~"5.*"}（错误率）和istio_request_duration_seconds_bucket{destination_service="sales-analytics-skill", le="5.0"}（P95延迟）。

这个流程让我们在一次重大重构中，将线上事故率从历史平均3.2%降至0.07%。关键是：灰度不是功能开关，而是流量管道的精密调节阀。我们甚至为每个skills配置了独立的Prometheus告警规则，当v2版本错误率超过0.5%时，自动触发kubectl patch将权重切回v1。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 “Your account is not eligible for Gemini Code Assist” —— 权限模型的三重门

这个错误信息看似简单，实则是Google Cloud权限体系的集中爆发点。它背后有三个独立的校验门，必须全部通过：

最坑的是第三道门：即使你的ServiceAccount权限完美，只要发起请求的终端用户邮箱不在白名单，就会报这个错。我们曾为此折腾两天，最后发现是测试用的Gmail账号未被加入白名单。解决方案是：在Agent Platform的User Management中，将所有内部员工邮箱批量导入，并勾选Enable Gemini Access。

5.2 Skills执行超时（504 Gateway Timeout）—— 不是代码慢，是网络策略在作祟

当skills执行时间接近5秒时，Agent Platform会返回504。新手常以为是代码效率问题，实则90%是网络策略导致：

• 现象：skills日志显示Execution completed in 4.8 seconds，但Agent Platform返回504；
• 根因：GKE的NetworkPolicy默认拒绝所有出站流量，而skills内部调用Gemini API需要访问generativelanguage.googleapis.com:443；
• 验证：在skills Pod中执行curl -v https://generativelanguage.googleapis.com/v1beta/models，若返回Connection refused，即证实网络阻断；
• 修复：在NetworkPolicy中添加出口规则：

  egress: - to: - ipBlock: cidr: 0.0.0.0/0 ports: - protocol: TCP port: 443

  但更安全的做法是：只放行Google Cloud的IP范围（`gcloud compute networks subnets list --region=us-central1 --format="value(ipC