1. 这不是“技能列表”而是一套可编排、可验证、可演化的智能体能力操作系统最近在多个技术社区和内部项目复盘会上我反复听到一个词被高频提起skills。它不再指代简历上那行静态的“Python/React/Docker”而是出现在 GKE 集群日志里、Gemini API 的请求体中、Agent Platform 的 YAML 配置文件里甚至在前端开发同学调试控制台时console.log 输出的不再是 data而是 skillResult。这个词正在从 HR 简历筛选术语快速蜕变为工程系统里的第一等公民First-Class Citizen——它有输入契约、输出 Schema、执行上下文、失败重试策略、可观测性埋点还能被动态注册、版本灰度、权限隔离。我去年主导过三个基于 skills 架构落地的生产级项目一个是金融风控场景的多模型协同决策引擎另一个是制造业设备预测性维护的边缘-云协同 agent 网络第三个是教育 SaaS 中面向教师的 AI 助手能力插件市场。这三个完全不同的领域最终都收敛到同一套设计范式skills 不是函数不是 API不是微服务而是一个带生命周期管理的、具备语义边界的可组合计算单元。它解决的核心问题非常朴素当一个 agent 需要调用“查天气”、“生成周报”、“比对合同条款”这些动作时系统如何确保每次调用都具备确定性、可观测性、可审计性且不因底层模型升级或服务迁移而失效答案不是写死逻辑而是定义 skills。你可能已经注意到热词里反复出现的 “claude agent skills: a first principles deep dive” 和 “reasonix 如何安装新 skills”。这背后反映的是行业共识的形成——大家不再争论“要不要用 skills”而是在争“怎么定义 skills 的边界”、“如何验证 skills 的鲁棒性”、“怎样让非 AI 工程师也能安全地贡献 skills”。这不是语法糖而是架构层的基础设施升级。它直接决定了你的 agent 系统是能跑通 demo还是能扛住每天百万次调用、支持 300 业务方按需组装、经得起合规审计的生产系统。接下来的内容我会以一个真实上线的 GKE Gemini API Agent Platform 的 skills 框架为例从零开始拆解这套能力操作系统的全部设计细节、实操陷阱和避坑经验。所有内容均来自我们团队在 2024 年 Q2 完成的 v1.2 版本迭代已稳定运行 187 天日均处理 42.6 万次 skills 调用。2. skills 架构设计为什么必须放弃“函数即能力”的旧范式2.1 传统函数调用模式的三大致命缺陷很多团队一开始会把 skills 理解为“封装好的函数”比如写一个 get_weather(city: str) - dict。这种思路在原型阶段看似高效但一旦进入真实业务场景立刻暴露出结构性缺陷契约漂移Contract Drift当后端天气服务从 OpenWeatherMap 切换到自建气象 API 时返回字段从 {“temp”: 25.3} 变为 {“temperature_celsius”: 25.3, “humidity_percent”: 68}。上游 agent 逻辑若直接解析字段就会崩溃。而 skills 的核心价值之一就是隔离这种底层变更。真正的 skills 必须声明明确的输入/输出 Schema并在 gateway 层做字段映射与类型校验而非把适配逻辑散落在各处 agent 代码里。上下文污染Context Contamination一个用于“生成会议纪要”的 skills需要访问用户日历、邮件、会议录音转文本结果。如果把它写成普通函数调用方就必须手动拼装这三类数据并传入。这导致 agent 编排逻辑高度耦合无法复用。skills 必须自带 context resolver 机制——它声明自己需要哪些 context 类型如 calendar_events, email_threads, speech_transcripts由统一的 context broker 按需注入agent 只需声明依赖不关心数据来源。可观测性黑洞Observability Black Hole函数调用日志只记录“get_weather called with Beijing”但无法回答“这次调用是否命中缓存”、“响应时间 800ms 是因为网络延迟还是模型推理慢”、“失败是因为 API key 过期还是城市名拼写错误”。skills 必须内置结构化日志、指标latency p95, success_rate、链路追踪trace_id 关联上下游且这些元数据必须与 skills 的 identityname version强绑定才能实现精准归因。提示我们曾在一个客户项目中将 47 个原有函数直接包装为 skills上线后发现 63% 的告警无法定位到具体 skills 实例。根本原因在于这些“伪 skills”没有声明 context 依赖导致 context broker 无法注入 trace_id整个调用链断裂。重构后平均故障定位时间从 42 分钟降至 3.7 分钟。2.2 skills 的四层架构模型从语义定义到物理执行我们最终采用的架构并非凭空设计而是对 Google Cloud Agent Platform 文档中 “Skill as a Service” 概念的工程化落地并针对 GKE 环境做了深度适配。它分为四个严格分层的平面语义层Semantic Layer这是 skills 的“身份证”。每个 skills 由唯一 URI 标识如skills://finance/risk-assessment/v1.2。它不包含任何代码只定义input_schema: JSON Schema 描述合法输入如要求amount字段必须是 number 且 0output_schema: 同样用 JSON Schema 描述期望输出结构context_requirements: 声明所需 context 类型及最小版本如[user_profilev2, transaction_historyv3]capabilities: 声明该 skills 具备的能力标签如[realtime, gdpr_compliant, low_latency]供 agent planner 动态匹配契约层Contract Layer这是 skills 的“法律文书”。它将语义层的声明转化为可执行的契约。在 GKE 上我们使用 Kubernetes Custom Resource Definition (CRD)SkillDefinition来承载。一个典型的 CRD 实例如下apiVersion: agentplatform.cloud.google.com/v1 kind: SkillDefinition metadata: name: risk-assessment-v12 namespace: finance-prod spec: uri: skills://finance/risk-assessment/v1.2 inputSchemaRef: https://schemas.example.com/risk-input-v1.json outputSchemaRef: https://schemas.example.com/risk-output-v1.json contextRequirements: - type: user_profile minVersion: v2 - type: transaction_history minVersion: v3 capabilities: - realtime - gdpr_compliant runtime: image: gcr.io/my-project/risk-assessment:v1.2.3 resources: limits: memory: 512Mi cpu: 500m这个 CRD 被 skills registry controller 监听一旦创建就自动触发后续流程。执行层Execution Layer这是 skills 的“身体”。它是一个独立的、无状态的容器化服务部署在 GKE 上。关键设计原则是单职责每个 pod 只运行一个 skills 实例不共享进程。无状态所有状态如缓存、session必须外置到 Redis 或 Cloud Memorystore。健康探针完备liveness/readiness probe 必须检查 skills 自身的 readiness如模型加载完成、连接池就绪而非仅检查 HTTP 端口。标准化入口所有 skills 容器暴露/execute端点接收标准化的 execution request含 input payload, context bundle, trace headers。治理层Governance Layer这是 skills 的“监管机构”。它由三个核心组件构成Registry: 存储所有 SkillDefinition CRD 及其版本历史提供查询 API。Broker: 接收 agent 的 skills 调用请求根据 URI 解析出目标 SkillDefinition验证输入/输出 Schema注入 context路由到对应 GKE service并收集 metrics。Auditor: 对所有 skills 调用进行采样审计检查是否符合 GDPR/PCI-DSS 等合规要求如敏感字段是否脱敏、是否越权访问 context。这四层之间通过清晰的接口契约解耦。语义层定义“是什么”契约层定义“在哪里”执行层定义“怎么做”治理层定义“谁来管”。这种分离使得我们可以独立升级某一层而不影响其他层——例如更新 Gemini API 的调用方式执行层只需重新构建镜像并更新 CRD 的image字段无需修改 agent 代码或 registry schema。2.3 为什么选择 GKE 而非 ServerlessGKE 的独特优势解析热词中频繁出现 GKE绝非偶然。我们在选型时对比了 Cloud Run、Cloud Functions 和 GKE最终锁定 GKE原因在于它完美契合 skills 架构对确定性、可观测性、资源隔离的严苛要求确定性冷启动Deterministic Cold StartCloud Run 的冷启动时间波动极大200ms ~ 5s而 skills 调用对延迟极其敏感尤其在实时风控场景。GKE 的 node pool 预热 HPAHorizontal Pod Autoscaler配置minReplicas: 3确保任何时候都有至少 3 个 warm pod 待命。实测数据显示GKE 上 skills 的 P95 延迟稳定在 320ms ± 15ms而 Cloud Run 在流量突增时 P95 延迟飙升至 1.8s。精细化资源隔离Granular Resource Isolationskills 的资源需求差异巨大。一个“文本摘要” skills 可能只需 128Mi 内存而一个“视频帧分析” skills 则需要 8Gi 内存和 GPU。GKE 的 node pool 可以按需配置不同规格的节点如 CPU-optimized, Memory-optimized, GPU-enabled并将特定 skills 的 Deployment 绑定到对应 node pool。我们为高负载 skills 单独创建了gpu-pool并设置nodeSelector和tolerations彻底避免资源争抢。Serverless 平台无法提供这种粒度的硬件级隔离。原生可观测性集成Native Observability IntegrationGKE 与 Cloud Operations原 Stackdriver深度集成。skills 的 container logs 自动打上cluster_name,namespace,pod_name,container_name等 labelsmetrics如container_cpu_usage_seconds_total天然关联到具体的 Deployment 和 Pod。我们在此基础上为每个 skills 添加了 custom metricskills_execution_duration_seconds并通过 Prometheus Operator 抓取实现了 per-skill 的 P95/P99 延迟监控。这种开箱即用的集成远超 Serverless 平台需要手动配置 log router 和 metric exporter 的复杂度。灵活的网络策略Flexible Network Policiesskills 往往需要访问内部数据库、消息队列或 legacy 系统。GKE 的 NetworkPolicy 可以精确控制每个 skills 的 pod 只能访问指定的 Service CIDR 或外部 IP 段。例如risk-assessmentskills 的 NetworkPolicy 明确禁止访问互联网只允许连接postgres-finance和redis-cache两个 Service。这种细粒度的网络控制在 Serverless 环境中要么不可用要么需要复杂的 VPC Connector 配置且难以审计。实操心得我们最初尝试将部分低频 skills 部署到 Cloud Run期望节省成本。但很快发现当risk-assessmentskills 因冷启动失败而 fallback 到 Cloud Run 时其延迟抖动导致整个风控决策链路超时。最终我们统一迁移到 GKE并通过合理的minReplicas和targetCPUUtilizationPercentage设为 60%配置在保证 SLA 的前提下整体资源成本反而降低了 12%因为避免了大量因超时重试产生的无效计算。3. skills 开发实操从定义到上线的完整流水线3.1 定义 skills用 YAML 和 JSON Schema 写“能力宪法”skills 的定义不是写代码而是写一份严谨的“能力宪法”。这个过程必须由 AI 工程师和领域专家共同完成确保语义准确、契约完备。我们使用一套内部工具skilldef-cli来辅助生成和校验。第一步创建skilldef.yaml。以risk-assessment为例# skilldef.yaml uri: skills://finance/risk-assessment/v1.2 name: Risk Assessment Engine description: Evaluates credit risk for loan applications using transaction history and user profile. version: 1.2 input: schemaRef: ./schemas/input.json examples: - amount: 50000 currency: USD purpose: home_improvement output: schemaRef: ./schemas/output.json examples: - riskScore: 0.72 riskCategory: medium explanation: High recent transaction volume in gambling category. contextRequirements: - type: user_profile minVersion: v2 description: Contains users age, income, employment status, and KYC status. - type: transaction_history minVersion: v3 description: Last 90 days of transactions, enriched with merchant categories. capabilities: - realtime - gdpr_compliant - audit_trail_required第二步编写input.json和output.jsonSchema。这是最关键的一步直接决定 skills 的健壮性。我们强制要求所有 Schema 使用$ref引用公共库避免重复定义// schemas/input.json { $schema: https://json-schema.org/draft/2020-12/schema, $id: https://schemas.example.com/risk-input-v1.json, type: object, properties: { amount: { type: number, minimum: 100, multipleOf: 1 }, currency: { type: string, enum: [USD, EUR, GBP] }, purpose: { type: string, enum: [home_improvement, education, debt_consolidation, other] } }, required: [amount, currency, purpose], additionalProperties: false }第三步用skilldef-cli validate校验。该工具会检查 URI 格式是否符合skills://domain/name/vmajor.minor规范下载并验证schemaRef是否可访问且格式正确检查examples是否符合 Schema 定义使用 AJV 库确保contextRequirements中的type在全局 context catalog 中注册注意我们曾因一个input.json中amount字段漏写了minimum: 100导致 skills 在接收到amount: 0时下游模型返回 NaN进而引发整个风控链路中断。skilldef-cli的强制校验将这类问题拦截在定义阶段避免了上线后的灾难性故障。3.2 开发 skills 执行体一个遵循标准协议的 Go 服务skills 的执行体Executor是一个标准的 HTTP 服务必须严格遵守skills-execution-protocol-v1。我们提供了一个 Go SDKgithub.com/ourorg/skills-sdk-go它封装了所有 boilerplate 代码开发者只需关注核心逻辑。一个典型的risk-assessmentexecutor 主文件如下package main import ( context log net/http time sdk github.com/ourorg/skills-sdk-go github.com/ourorg/skills-sdk-go/metrics ) func main() { // 初始化 SDK自动注入 tracing, logging, metrics skill : sdk.NewSkill(risk-assessment-v12) // 注册 /execute handlerSDK 自动处理 request parsing, schema validation, context injection skill.HandleExecute(func(ctx context.Context, req *sdk.ExecutionRequest) (*sdk.ExecutionResponse, error) { // 1. 从 req.Input 解析结构化输入 var input struct { Amount float64 json:amount Currency string json:currency Purpose string json:purpose } if err : req.Input.Unmarshal(input); err ! nil { return nil, sdk.NewValidationError(invalid input: %w, err) } // 2. 从 req.Context 获取所需数据 profile, ok : req.Context.Get(user_profile).(*UserProfile) if !ok { return nil, sdk.NewContextError(user_profile not found or invalid type) } history, ok : req.Context.Get(transaction_history).(*TransactionHistory) if !ok { return nil, sdk.NewContextError(transaction_history not found or invalid type) } // 3. 核心业务逻辑调用 Gemini API 进行风险评估 // 注意这里使用 Gemini API 的 structured output mode确保输出严格符合 output schema geminiResp, err : callGeminiRiskModel(ctx, input, profile, history) if err ! nil { return nil, sdk.NewExecutionError(gemini call failed: %w, err) } // 4. 构建响应SDK 自动进行 output schema validation resp : sdk.ExecutionResponse{ Output: geminiResp, Metadata: map[string]interface{}{ model_version: gemini-1.5-pro-001, execution_time_ms: time.Since(req.StartTime).Milliseconds(), }, } return resp, nil }) // 启动 HTTP serverSDK 自动添加 /healthz, /readyz, /metrics 端点 log.Fatal(http.ListenAndServe(:8080, skill.Handler())) }关键点解析Schema Validation 是 SDK 的责任不是开发者的req.Input.Unmarshal(input)会自动根据input.jsonSchema 进行校验非法输入直接返回 400。Context Injection 是透明的req.Context.Get(user_profile)返回的已经是反序列化后的*UserProfile结构体开发者无需关心数据如何从 Kafka 或 BigQuery 加载。Structured Output 是底线我们强制要求所有调用 Gemini API 的 skills必须使用其response_mime_type: application/json和response_schema参数让模型直接输出 JSON避免后期 parse 错误。callGeminiRiskModel函数内部封装了这一逻辑。Metadata 是可观测性的基石resp.Metadata中的execution_time_ms会被 SDK 自动上报为 Prometheus metricmodel_version会作为 log field 记录用于后续 A/B 测试分析。3.3 构建与部署GKE 上的 CI/CD 流水线详解我们的 CI/CD 流水线完全基于 GitHub Actions Google Cloud Build GKE目标是一次提交自动完成定义校验、镜像构建、CRD 更新、蓝绿发布、金丝雀验证。流水线步骤分解Code Checkout Lint检出代码运行golangci-lint和jsonschema-validator。Skill Definition Validation执行skilldef-cli validate --file skilldef.yaml。Docker Image Build使用 Cloud Build 构建 executor 镜像并打上sha256:commit-hash和v1.2.3双标签。CRD Generation Applyskilldef-cli generate-crd --file skilldef.yaml skilldef-cr.yaml然后kubectl apply -f skilldef-cr.yaml。这一步会触发 skills registry controller。GKE Deploymentkubectl apply -f k8s/deployment.yaml其中deployment.yaml的image字段引用上一步构建的镜像。Canary Release新版本 skills 默认部署到canarynamespace。我们有一个canary-controller它会将 5% 的流量路由到canarynamespace 的 skills。监控其success_rate必须 99.5%和latency_p95必须 400ms。如果连续 5 分钟达标则自动将productionnamespace 的 Deployment 更新为新镜像。如果任一指标不达标则自动回滚并发送 Slack 告警。deployment.yaml的关键配置apiVersion: apps/v1 kind: Deployment metadata: name: risk-assessment-v12 namespace: canary spec: replicas: 3 selector: matchLabels: app: risk-assessment version: v12 template: metadata: labels: app: risk-assessment version: v12 annotations: prometheus.io/scrape: true prometheus.io/port: 8080 spec: nodeSelector: cloud.google.com/gke-nodepool: cpu-pool # 绑定到 CPU 优化型节点池 tolerations: - key: skills-type operator: Equal value: cpu-intensive effect: NoSchedule containers: - name: executor image: gcr.io/my-project/risk-assessment:v1.2.3 ports: - containerPort: 8080 resources: requests: memory: 256Mi cpu: 200m limits: memory: 512Mi cpu: 500m livenessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /readyz port: 8080 initialDelaySeconds: 5 periodSeconds: 5实操心得我们曾因忘记在deployment.yaml中设置resources.limits导致一个高内存消耗的 skills 在节点上 OOM进而触发 kubelet 驱逐造成短暂服务中断。从此我们强制要求所有 skills 的 Deployment 必须显式声明requests和limits并在 CI 流水线中加入kubectl describe pod检查确保配置生效。3.4 Agent Platform 集成让 skills 成为 agent 的“肌肉”skills 本身是被动的只有被 agent 调用才有价值。Google Cloud Agent Platform 的Tool Calling机制是连接二者的桥梁。关键在于如何将 skills 的 URI 映射为 Agent Platform 可识别的Tool。我们开发了一个skills-bridge服务它监听 Agent Platform 的tool_use事件并执行以下转换URI 解析skills://finance/risk-assessment/v1.2→tool_name: risk_assessment_v12参数映射将 Agent Platform 的tool_input一个 flat dict根据 skills 的input_schema反序列化为结构化对象。Context 注入根据 skills 的context_requirements从统一 context store 中获取数据并注入到 execution request 中。结果标准化将 skills 的ExecutionResponse.Output提取为 Agent Platform 期望的tool_result格式。一个典型的tool_use事件 payload{ tool_call_id: call_abc123, name: risk_assessment_v12, input: { amount: 50000, currency: USD, purpose: home_improvement } }skills-bridge会将其转换为对 skills broker 的调用POST https://broker.skills.internal/execute Content-Type: application/json { skill_uri: skills://finance/risk-assessment/v1.2, input: {amount: 50000, currency: USD, purpose: home_improvement}, context: { user_profile: {age: 35, income: 85000, kyc_status: verified}, transaction_history: [{merchant: Casino XYZ, category: gambling, amount: -2500}] } }这个 bridge 服务本身也部署在 GKE 上其 Deployment 配置了priorityClassName: high-priority确保在集群资源紧张时它能优先获得调度保障 agent 的响应速度。4. skills 运维与治理生产环境中的血泪教训4.1 Skills Registry不只是存储更是能力市场的“交易所”Skills Registry 不是一个简单的 YAML 存储库而是一个具备完整生命周期管理的“能力交易所”。它的核心功能包括版本管理支持v1.2.0,v1.2.1,v1.2.2的并存。Agent 可以声明依赖skills://finance/risk-assessment/v1.2语义化版本registry 会自动解析到最新的 patch 版本v1.2.2前提是它通过了所有兼容性测试。依赖图谱Dependency Graphregistry 会自动分析每个 skills 的context_requirements构建出完整的 context 依赖图。当user_profilev3发布时registry 能立即列出所有需要升级的 skills并触发自动化测试。能力市场Marketplace提供 Web UI让非技术人员如产品经理、风控专家可以浏览所有已注册 skills查看其 description、input/output examples、SLA 指标P95 latency, success rate。申请试用某个 skills填写业务场景和预期调用量由平台管理员审批。查看 skills 的调用排行榜了解哪些能力最被业务方需要。我们曾遇到一个典型问题一个名为fraud-detection的 skills其context_requirements中声明了[user_behaviorv1]但user_behaviorv1的 schema 中有一个字段last_login_ip是 string 类型。后来user_behavior升级到v2将last_login_ip改为ip_addressobject。由于fraud-detection没有及时更新其context_requirements它继续请求v1但 context broker 为了向后兼容返回了v2的数据导致 skills 解析失败。Registry 的依赖图谱功能让我们能在user_behaviorv2发布前就扫描出所有依赖v1的 skills并强制要求它们完成兼容性验证。4.2 Context Brokerskills 的“中央情报局”Context Broker 是 skills 架构中最容易被低估却最关键的组件。它负责将分散在各个数据源BigQuery, Cloud SQL, Pub/Sub的 context按需、安全、高效地聚合并注入到 skills 调用中。其核心设计原则按需加载On-Demand LoadingBroker 不会预加载所有 context。它只根据 skills 的context_requirements动态构造一个 GraphQL 查询从 federated data sources 中 fetch 所需字段。例如risk-assessment只需要user_profile.age和transaction_history.last_30_daysBroker 就只查询这两个字段避免了全量数据拉取的性能浪费。缓存策略Cache Strategy对高频、低变的 context如user_profileBroker 使用 Redis 缓存TTL 设为 1 小时。对实时性要求高的 context如transaction_history则绕过缓存直连 source。权限代理Permission ProxyBroker 在注入 context 前会检查调用 skills 的 agent 的 service account 是否拥有访问该 context 的 IAM 权限。例如marketing-agent的 SA 没有bigquery.tables.getData权限即使它请求user_profileBroker 也会返回 403。一个真实的故障案例某天凌晨risk-assessmentskills 的成功率从 99.8% 骤降至 42%。排查发现是transaction_history数据源的 BigQuery 表发生了 schema change新增了一个merchant_category_code字段而risk-assessment的input_schema没有更新。Broker 在将数据注入 skills 时因为input_schema严格禁止additionalProperties导致整个 execution request 被拒绝。我们立即在 registry 中将risk-assessment的context_requirements临时降级为[transaction_historyv2]一个兼容旧 schema 的版本同时通知数据团队修复。这个快速降级能力正是 registry 和 broker 协同的价值。4.3 Auditor合规性不是事后补救而是嵌入式基因在金融和医疗等强监管行业skills 的每一次调用都可能成为审计证据。Auditor 组件不是简单的日志收集器而是嵌入式合规引擎。它的工作流程采样对所有 skills 调用按 1% 的比例进行全量采样可配置。解析提取skill_uri,input,output,context脱敏后以及trace_id。规则引擎应用预定义的合规规则GDPR Rule: 检查input和output中是否包含PII个人身份信息字段如ssn,email,phone。如果存在必须确认output_schema中该字段标记为sensitive: true且output中的值已被SHA256哈希。PCI-DSS Rule: 检查input中是否包含card_number如果是必须确认skill_uri的capabilities包含pci_compliant且该 skills 的 Deployment 配置了securityContext.runAsNonRoot: true。告警与阻断发现违规立即发送告警并可配置为自动阻断后续调用block_on_violation: true。我们曾用 Auditor 发现一个严重问题一个用于“生成营销文案”的 skills其input包含了用户姓名和邮箱但output_schema没有标记为 sensitive导致生成的文案中直接包含了原始邮箱。Auditor 的规则引擎在首次采样时就捕获了此违规并自动阻断了该 skills 的所有调用避免了潜在的数据泄露。4.4 常见问题速查表与独家避坑指南问题现象根本原因排查步骤解决方案我们的独家技巧skills 调用返回 404 Not FoundSkillDefinitionCRD 未被 registry controller 正确处理或uri字段拼写错误1.kubectl get skilldefinition -n ns确认 CRD 存在2.kubectl logs -n skills-system deploy/skills-registry查看 controller 日志3.curl -v https://broker.skills.internal/v1/skills/uri测试 broker 解析修正uri字段确保符合规范检查 registry controller 的 RBAC 权限在skilldef-cli中加入--dry-run模式它会模拟 controller 的解析过程提前暴露 URI 格式错误skills 执行超时HTTP 504skills 容器内业务逻辑耗时过长或 context broker 响应慢1.kubectl top pods -n skill-ns查看 CPU/Memory 使用率2.kubectl logs pod-name -n skill-ns | grep execution_time_ms查看实际执行时间3.kubectl logs -n skills-system deploy/context-broker | grep skill-uri查看 context 加载耗时优化业务逻辑为 context broker 添加更激进的缓存增加 skills 的timeoutSeconds在 skills SDK 中我们为HandleExecute函数增加了ctx, cancel : context.WithTimeout(ctx, 30*time.Second)并确保所有下游调用如 Gemini API都使用此ctx避免 goroutine 泄漏skills 输出不符合 schemaGemini API 的 structured output mode 未启用或模型返回了非法 JSON1.kubectl logs pod-name -n skill-ns | grep output_validation_failed2. 检查callGeminiRiskModel函数中是否设置了response_mime_type和response_schema强制在所有 Gemini 调用中启用 structured output在 SDK 中添加output_schema的 runtime validation我们开发了一个schema-validator-middleware它在 skills SDK 的ExecutionResponse序列化前用 AJV 再次校验确保 100% 符合 schema校验失败则 panic 并记录详细错误agent 调用 skills 后无响应skills-bridge服务异常或 Agent Platform 的tool_use事件未被正确路由1.kubectl get pods -n skills-bridge确认 bridge pod 状态2.kubectl logs -n skills-bridge deploy/skills-bridge查看是否有tool_use事件丢失3. 在 Agent Platform 控制台检查tool_use事件的 delivery status重启 bridge pod检查 Agent Platform 的 webhook 配置是否指向正确的 bridge endpoint我们为skills-bridge添加了 dead letter queue (DLQ)所有无法处理的tool_use事件都会被持久化到 Pub/Sub topic供人工排查避免事件丢失最后分享一个小技巧我们为每个 skills 创建了一个专属的 debug