企业官网建设流程全解析

1. 项目概述：当“skills”不再只是简历上的单词，而成为可执行、可编排、可演化的智能体能力单元

最近两周，我在三个不同客户的现场调试环境时，连续被问到同一个词：“skills”——不是HR在看简历时扫过的那个泛泛而谈的软技能列表，也不是培训课上PPT里带箭头图标的“沟通力/领导力/执行力”三件套。而是开发者指着终端里刚跑起来的一段YAML配置文件说：“这个web-scraper-skill怎么没触发重试逻辑？”是产品经理拿着Figma原型追问：“如果用户说‘帮我对比这三家酒店的价格’，我们能不能让price-comparison-skill自动调用飞猪+携程+美团的API，再生成表格？”是运维同事深夜发来截图：“GKE集群里这个k8s-resource-validator-skill突然开始疯狂打日志，但Pod状态全是Running，查不到报错堆栈。”

这就是当下真实发生的转变：“skills”正在从抽象能力描述，蜕变为可版本化、可依赖管理、可独立部署、可被LLM动态路由调用的最小功能单元。它不是新概念，但正经历一次关键性重构——不再是函数式封装（如def send_email()），而是具备上下文感知、输入契约校验、失败回退策略、可观测埋点、权限沙箱隔离的声明式能力模块。你看到的热搜词里反复出现的Gemini Code Assist、Claude Agent Skills、Genkit Skills，本质都是同一范式的不同实现入口：把“人能做的事”，拆解成机器可理解、可组合、可审计的原子能力块。

核心关键词skills在此语境下，已脱离传统语义，特指基于大模型智能体（Agent）架构下的可插拔能力组件。它必须满足五个硬性条件：① 有明确定义的输入Schema（JSON Schema格式）；② 有明确的输出契约（非自由文本，而是结构化响应或状态码）；③ 内置超时与重试机制（非靠上层调度器兜底）；④ 支持细粒度权限控制（如仅允许访问特定GCP项目下的Cloud Storage bucket）；⑤ 可独立运行于隔离环境（Docker容器或GKE Pod），不依赖主Agent进程内存。

为什么这个转变如此关键？我拿一个真实案例说明：某电商客户原先用单体Python脚本处理“用户退货请求”，包含OCR识别运单、调用物流API查轨迹、校验退货政策、生成退款单、通知客服——所有逻辑耦合在一个函数里。当需要接入新的快递公司时，整个脚本要停机修改、全量测试、重新部署。而采用Skills架构后，他们只新增了一个sf-express-tracker-skill，定义好输入是运单号、输出是物流节点数组，其他环节完全不动。上线耗时从3天压缩到47分钟，且旧技能yto-tracker-skill仍并行服务存量订单。这才是“skills”在工程层面的真实价值：不是炫技的AI玩具，而是降低系统熵增的基础设施。

适合谁参考这篇内容？如果你正面临以下任一场景，这篇就是为你写的：

• 正在评估Genkit或LangChain等框架，但卡在“如何把业务逻辑合理切分成skill”这一步；
• 已部署GKE集群，想让LLM Agent调用内部微服务，却苦于权限管控和错误传播混乱；
• 在Gemini Code Assist中看到“Custom Skills”选项但无法启用，提示your account is not eligible，想搞清背后的技术准入条件；
• 做前端开发，需要把find skills这类搜索功能嵌入管理后台，但发现官方SDK文档里只有模糊的“register skill”接口，没有实际数据结构示例。

接下来，我会以一个可完整复现的weather-forecast-skill为例，从设计哲学到GKE部署，手把手拆解Skills落地的全部关节。不讲虚的，只讲你在Kubernetes里敲命令时真正需要知道的细节。

2. Skills架构设计与选型逻辑：为什么不用纯函数封装，而必须走声明式+容器化路线

2.1 技术选型背后的三个不可妥协约束

很多团队初期会尝试用简单函数封装能力，比如写个get_weather(city: str) -> dict，然后注册到Agent框架里。我见过至少7个团队踩过这个坑，最终都推倒重来。根本原因在于，Skills不是函数，而是服务契约（Service Contract）。它必须同时满足三个硬性约束，而纯函数无法承载：

第一，跨语言互操作性约束。你的Agent可能用Python写的，但天气服务是Java团队维护的Spring Boot应用，财务审批流程是遗留的.NET Core系统。如果Skills只是Python函数，那意味着所有能力都得用Python重写——这在现实企业中等于宣告项目死刑。而声明式Skills通过标准化的HTTP/gRPC接口+OpenAPI Schema暴露能力，Java服务只要提供符合/v1/skills/weather-forecast路径的REST API，就能被任何语言的Agent调用。我参与的一个银行项目，Skills目录里同时存在Python（风控模型）、Go（支付网关）、Rust（加密计算）三种实现，它们共享同一套输入输出Schema，Agent完全无感。

第二，运行时隔离性约束。这是GKE部署的核心前提。想象一下：某个pdf-parser-skill因第三方库bug导致内存泄漏，如果它和主Agent进程共享内存空间，整个Agent服务就会OOM崩溃。而Skills作为独立Pod部署在GKE中，Kubernetes的cgroup限制能天然隔离资源，配合Liveness Probe自动重启故障Pod，不影响其他Skills。更关键的是，隔离带来权限精细化——你可以为db-query-skill单独绑定GCP Service Account，只授予其访问特定Cloud SQL实例的权限；而email-sender-skill则绑定另一个SA，仅允许调用SendGrid API。这种权限粒度，在单进程架构里根本无法实现。

第三，可观测性契约约束。Skills必须自带标准监控指标，否则在生产环境就是黑盒。我们要求每个Skill容器启动时，必须暴露/metrics端点（Prometheus格式），包含skill_invocation_total{skill_name="weather-forecast",status_code="200"}、skill_duration_seconds_bucket{skill_name="weather-forecast",le="1.0"}等指标。这些指标由GKE集群的Stackdriver自动采集，无需Agent代码额外埋点。当weather-forecast-skill的95分位延迟突然从300ms飙升到2.1s，运维能立刻定位到是Pod所在Node的磁盘IO瓶颈，而不是在Agent日志里大海捞针。

2.2 Genkit vs LangChain：Skills抽象层的本质差异

当前主流框架对Skills的支持，表面相似，底层哲学截然不同。我用一张表对比关键差异：

选择Genkit的核心理由，不是因为它“是Google的”，而是它把Skills当作基础设施而非代码库来设计。比如它的skill.yaml强制要求timeout_ms，这看似增加开发负担，实则避免了线上事故：曾有个团队用LangChain开发stock-price-skill，未设超时，当金融API响应慢时，Agent线程池被占满，整个服务雪崩。而Genkit在skill.yaml里写死timeout_ms: 5000，超过5秒直接返回{"error": "TIMEOUT", "code": "SKILL_TIMEOUT"}，上层Agent可立即降级为缓存数据。

提示：如果你的团队尚未使用GCP，别急着否定Genkit。它的Skills定义规范（YAML Schema）是开源的，你可以用它设计自己的Skills契约，再用K8s Operator实现调度——这才是真正吃透架构的方法。

2.3 Gemini Code Assist的Skills准入机制解析

热搜词里高频出现的your account is not eligible for gemini code assist for individuals at this time，本质是Google对Skills能力边界的严格管控。这不是Bug，而是设计使然。Gemini Code Assist的Skills功能，仅对满足以下全部条件的账户开放：

1. GCP项目已启用Billing Account（非免费额度，需真实信用卡绑定）；
2. 项目已启用Genkit API（genkit.googleapis.com）；
3. 用户角色拥有roles/genkit.admin或更高权限（注意：Editor角色不够）；
4. 项目所属组织层级未禁用AI服务（企业客户常在Org Policy中设置constraints/aiplatform.allowedServices）。

我帮客户排查时发现，90%的“not eligible”错误源于第3条。很多人以为Project Owner就足够，但Genkit Admin权限需显式授予。正确操作是：进入GCP Console → IAM & Admin → Grant Access → 输入用户邮箱 → 选择角色Genkit Admin→ 保存。切记不要勾选“Include permissions from basic roles”，这会导致权限继承混乱。

更深层的原因在于，Gemini Code Assist的Skills不是独立服务，而是Genkit框架的轻量级客户端。当你在VS Code里点击“Add Skill”，它实际是在后台调用Genkit的/v1/skills:registerAPI，将本地YAML提交到GCP项目。如果权限不足，API直接返回403，前端就显示那个提示。所以，与其反复刷新页面，不如打开浏览器开发者工具，抓包看Network Tab里register请求的响应体——里面会有精确的权限缺失提示，比前端文案详细十倍。

3. Skills核心细节解析：从YAML定义到GKE部署的完整链路

3.1weather-forecast-skill的YAML定义详解

我们以一个真实的weather-forecast-skill为例，这是我在某出行App项目中交付的生产级Skills。它的skill.yaml文件如下（已脱敏）：

# skill.yaml name: weather-forecast version: "1.0.2" description: "Get 3-day weather forecast for a city using OpenWeatherMap API" input_schema: type: object properties: city: type: string description: "City name in English, e.g. 'Shanghai'" minLength: 2 maxLength: 50 units: type: string enum: ["metric", "imperial"] default: "metric" required: ["city"] output_schema: type: object properties: city: type: string country: type: string forecasts: type: array items: type: object properties: date: type: string format: date temperature: type: number description: "Temperature in selected units" condition: type: string humidity: type: integer minimum: 0 maximum: 100 required: ["city", "country", "forecasts"] timeout_ms: 8000 error_handling: retry_on: - "5xx" - "timeout" max_retries: 2 fallback: type: "static" value: city: "Unknown" country: "XX" forecasts: [] required_permissions: - "https://www.googleapis.com/auth/cloud-platform" - "https://www.googleapis.com/auth/storage.objectViewer" health_check_path: "/healthz" metrics_endpoint: "/metrics"

这个YAML文件不是随便写的，每个字段都有强工程意义：

• input_schema和output_schema采用JSON Schema Draft-07标准，不是为了校验，而是为了生成SDK。Genkit CLI会根据此Schema自动生成TypeScript客户端（供前端调用）和Python SDK（供Agent调用）。比如前端开发者只需import { WeatherForecastInput } from '@genkit/skills';，IDE就能智能提示city字段必填，units只能选metric或imperial——这比写一堆JSDoc注释可靠得多。

• timeout_ms: 8000的设定有计算依据：OpenWeatherMap API的P95响应时间是1200ms，我们按5倍冗余设为6000ms，再加2000ms缓冲应对网络抖动。永远不要凭感觉设超时值，我见过太多团队设成30000，结果一次DNS故障就让整个Agent卡死半分钟。

• error_handling.fallback的static类型，意味着当重试失败后，Skill不抛异常，而是返回预设的兜底数据。这对用户体验至关重要——用户问“北京天气”，总比返回“服务暂时不可用”要友好。更高级的fallback类型还有delegate（委托给另一个Skill）和prompt（让LLM生成拟人化回复），但生产环境慎用，容易失控。

• required_permissions字段是GCP IAM的直译。当这个Skill部署到GKE时，Genkit Operator会自动创建一个Service Account，并绑定这些权限。注意：这里写的权限必须小于等于GCP项目级别的IAM策略。比如项目Policy禁止storage.objectViewer，那么即使YAML写了，Operator也会创建失败并报错。

3.2 Docker镜像构建：为什么必须用多阶段构建

Skills容器镜像不是简单的python:3.11-slim+pip install。我们采用严格的多阶段构建，确保生产镜像纯净且安全：

# Dockerfile # 构建阶段：安装依赖并编译 FROM python:3.11-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir --user -r requirements.txt # 运行阶段：仅复制必要文件 FROM gcr.io/distroless/python3-debian12 WORKDIR /app COPY --from=builder /root/.local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages COPY --from=builder /root/.local/bin /usr/local/bin COPY . . # 删除所有非运行时文件 RUN rm -rf /app/tests /app/docs /app/.git # 安全加固 USER 1001:1001 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD curl -f http://localhost:8080/healthz || exit 1 EXPOSE 8080 CMD ["python", "main.py"]

关键点解析：

• 基础镜像选择distroless：这是Google开源的无发行版镜像，不含shell、包管理器、甚至/bin/sh。攻击者即使突破容器，也无法执行ls或cat命令。相比python:3.11-slim（含200+个二进制文件），distroless镜像大小仅12MB，漏洞CVE数量为0。

• USER指令强制非root：USER 1001:1001让进程以非特权用户运行。GKE默认启用Pod Security Admission（PSA），拒绝runAsRoot: true的Pod。很多团队卡在这步，因为旧Dockerfile习惯用root用户启动。

• HEALTHCHECK精准配置：--start-period=5s给Skill初始化留出时间（比如加载ML模型），--retries=3避免瞬时网络抖动导致误判。我见过团队把start-period设为0，结果Skill还没连上Redis就触发健康检查失败，Pod反复重启。

• requirements.txt必须锁定版本：我们的requirements.txt不是requests，而是requests==2.31.0。用pip freeze > requirements.txt生成，杜绝依赖漂移。某次升级urllib3到1.26.16后，OpenWeatherMap API的SSL握手失败，就是因为新版本改变了TLS参数。

3.3 GKE部署配置：Service与Ingress的协同设计

Skills部署到GKE不是简单kubectl apply -f deployment.yaml。它需要Service、Ingress、NetworkPolicy三层协同，才能既安全又可用：

# k8s/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: weather-forecast-skill labels: app: weather-forecast-skill spec: replicas: 3 selector: matchLabels: app: weather-forecast-skill template: metadata: labels: app: weather-forecast-skill annotations: # 启用GCP托管服务网格的自动注入 sidecar.istio.io/inject: "true" spec: serviceAccountName: weather-forecast-sa # 关联Service Account containers: - name: skill image: gcr.io/my-project/weather-forecast-skill:v1.0.2 ports: - containerPort: 8080 env: - name: OPENWEATHER_API_KEY valueFrom: secretKeyRef: name: weather-secrets key: api-key resources: requests: memory: "128Mi" cpu: "100m" limits: memory: "256Mi" cpu: "200m" --- # k8s/service.yaml apiVersion: v1 kind: Service metadata: name: weather-forecast-skill spec: selector: app: weather-forecast-skill ports: - port: 80 targetPort: 8080 type: ClusterIP # 仅集群内访问 --- # k8s/ingress.yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: weather-forecast-ingress annotations: # 启用Cloud Armor WAF防护 cloud.google.com/app-protocols: '{"https":"HTTPS"}' # 启用IAP（Identity-Aware Proxy）认证 beta.cloud.google.com/backend-config: '{"default": "iap-backendconfig"}' spec: rules: - host: skills.mycompany.com http: paths: - path: /v1/skills/weather-forecast pathType: Prefix backend: service: name: weather-forecast-skill port: number: 80

部署要点：

• Service类型必须为ClusterIP：Skills是Agent的后端依赖，绝不应暴露公网。LoadBalancer或NodePort会绕过GCP的安全网关，违反企业安全策略。

• Ingress的pathType: Prefix是关键：Skills的API路径是/v1/skills/{name}，Agent调用时会拼接完整URL。如果设为Exact，则/v1/skills/weather-forecast/healthz会404，因为路径不完全匹配。Prefix确保所有子路径（/healthz,/metrics）都能被正确路由。

• IAP（Identity-Aware Proxy）是必备项：它在Ingress层验证用户身份，无需Skills代码处理JWT解析。Agent调用Skills时，GCP自动在请求头注入X-Goog-Authenticated-User-Email，Skills只需校验该邮箱是否在白名单内。比自己实现OAuth2.0省心百倍，且支持MFA。

• NetworkPolicy必须显式定义：GKE默认允许所有Pod互通，这很危险。我们添加了NetworkPolicy，只允许agent-namespace的Pod访问skills-namespace的Skills Service：

# k8s/network-policy.yaml apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: allow-agent-to-skills spec: podSelector: matchLabels: app: weather-forecast-skill ingress: - from: - namespaceSelector: matchLabels: name: agent-namespace ports: - protocol: TCP port: 80

4. 实操过程：从本地开发到GKE生产环境的全流程

4.1 本地开发调试：Genkit Dev Server的隐藏技巧

Genkit的genkit dev命令不只是启动服务器，它提供了三个被文档严重低估的调试能力：

第一，实时OpenAPI文档生成。启动后访问http://localhost:3000/api-docs，你会看到完整的Swagger UI，包含：

• 所有Skills的POST /v1/skills/{name}:invoke接口；
• 每个Skill的input_schema渲染为交互式表单；
• 点击“Try it out”可直接发送测试请求，无需Postman。

第二，请求重放（Replay）功能。在http://localhost:3000/trace页面，所有调用都会被记录。点击某次调用，能看到：

• 完整的HTTP请求头（含Authorization）；
• Skill的输入JSON（已格式化）；
• Skill的输出JSON（含@timestamp等元数据）；
• 最关键的是：点击“Replay”按钮，可一键重放该请求。当线上出现偶发错误时，你可以在本地复现，比看日志快十倍。

第三，Mock模式开关。在genkit.dev.yaml中添加：

mock: enabled: true skills: - name: "weather-forecast" response: | { "city": "Shanghai", "country": "CN", "forecasts": [ {"date": "2024-06-15", "temperature": 28.5, "condition": "Sunny", "humidity": 65} ] }

这样，weather-forecast-skill永远返回固定数据，不受OpenWeatherMap API限流影响。开发Agent逻辑时，可以完全隔离外部依赖。

注意：Mock模式仅在genkit dev下生效，生产环境自动禁用，无需额外配置。

4.2 CI/CD流水线：GitHub Actions自动化发布

Skills的CI/CD不能简单复制Web应用流程。我们设计了四阶段流水线，确保每次发布都经过严格验证：

# .github/workflows/skills-ci.yml name: Skills CI/CD on: push: branches: [main] paths: - 'skills/weather-forecast/**' - 'skills/**/skill.yaml' jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Validate YAML Schema run: | pip install pyyaml jsonschema python -c " import yaml, jsonschema, sys with open('skills/weather-forecast/skill.yaml') as f: data = yaml.safe_load(f) schema = { 'type': 'object', 'required': ['name', 'input_schema', 'output_schema'], 'properties': { 'name': {'type': 'string'}, 'input_schema': {'type': 'object'}, 'output_schema': {'type': 'object'} } } jsonschema.validate(instance=data, schema=schema) " - name: Run Unit Tests run: pytest skills/weather-forecast/tests/ build: needs: test runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Build Docker Image run: | cd skills/weather-forecast docker build -t gcr.io/${{ secrets.GCP_PROJECT_ID }}/weather-forecast-skill:${{ github.sha }} . - name: Push to GCR run: | gcloud auth configure-docker docker push gcr.io/${{ secrets.GCP_PROJECT_ID }}/weather-forecast-skill:${{ github.sha }} deploy-staging: needs: build runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Deploy to Staging GKE run: | gcloud container clusters get-credentials staging-cluster --region us-central1 --project ${{ secrets.GCP_PROJECT_ID }} sed -i "s/:latest/:${{ github.sha }}/g" k8s/staging/weather-forecast.yaml kubectl apply -f k8s/staging/weather-forecast.yaml deploy-prod: needs: deploy-staging runs-on: ubuntu-latest if: github.event_name == 'push' && github.ref == 'refs/heads/main' steps: - uses: actions/checkout@v4 - name: Manual Approval Required # 此处可集成Slack通知或GitHub Environments审批 run: echo "Production deploy requires manual approval" - name: Deploy to Prod GKE run: | gcloud container clusters get-credentials prod-cluster --region us-central1 --project ${{ secrets.GCP_PROJECT_ID }} sed -i "s/:latest/:${{ github.sha }}/g" k8s/prod/weather-forecast.yaml kubectl apply -f k8s/prod/weather-forecast.yaml

流水线设计哲学：

• YAML Schema验证是第一道门：防止skill.yaml语法错误导致后续步骤失败。我们用Python脚本做校验，比用yamllint更精准，能检查业务规则（如timeout_ms必须大于0）。

• Staging环境必须与Prod完全一致：k8s/staging/weather-forecast.yaml和k8s/prod/weather-forecast.yaml除了replicas和resources外，其他字段100%相同。很多团队在Staging用replicas: 1，Prod用replicas: 3，结果Staging测不出并发问题。

• Prod部署强制人工审批：最后一行if: github.event_name == 'push' && github.ref == 'refs/heads/main'确保只有main分支推送才触发，但真正的闸门是“Manual Approval Required”。我们把它对接到Slack，运维收到消息后，需在指定频道回复/approve weather-forecast才执行。

4.3 GKE生产环境监控：Stackdriver指标实战

Skills部署后，监控不是“看看CPU是否爆了”，而是围绕Skills契约设计指标。我们在Stackdriver中创建了三个核心Dashboard：

Dashboard 1：Skills健康度概览

• skills_health_status：自定义指标，值为1（健康）或0（不健康），基于/healthz探针结果聚合；
• skills_p95_latency_ms：按Skill名称分组的95分位延迟；
• skills_error_rate_percent：5xx响应数 / 总请求数 * 100。

Dashboard 2：输入质量分析

• skills_input_validation_errors：因input_schema校验失败的请求数（如city为空字符串）；
• skills_input_size_bytes：输入JSON的平均字节数，突增可能意味着恶意构造的大Payload。

Dashboard 3：权限审计

• skills_permission_denied_count：GCP IAM拒绝计数，关联required_permissions字段；
• skills_service_account_rotation_days：Service Account密钥距上次轮换的天数，超90天标红。

最关键的告警规则是：当skills_p95_latency_ms> 2000ms持续5分钟，且skills_error_rate_percent< 1%，则触发“性能退化”告警，而非“服务中断”。因为前者意味着Skill本身没问题，可能是下游API变慢，需要联系OpenWeatherMap团队；后者才是紧急事件。

实操心得：Stackdriver的skills_p95_latency_ms指标，必须在Skill代码中手动埋点。Genkit不自动采集，因为延迟定义权在开发者手中——是request received到response sent，还是request received到LLM token generated？我们选择前者，因为它反映真实用户体验。

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

5.1 “Your account is not eligible”问题的终极排查清单

这个提示出现频率太高，我整理了一份按优先级排序的排查清单，每一条都来自真实故障：

1. 检查GCP项目是否启用了Genkit API
   进入GCP Console → APIs & Services → Library → 搜索Genkit API→ 点击启用。
   为什么重要：很多团队以为启用AI Platform就够了，但Genkit是独立API，需单独开启。

2. 验证Service Account权限
   运行命令：gcloud projects get-iam-policy YOUR_PROJECT_ID --flatten="bindings[].members" --format='table(bindings.role, bindings.members)' | grep genkit
   确保输出包含roles/genkit.admin和你的邮箱。

3. 确认组织策略未禁用
   运行：gcloud resource-manager org-policies list --organization=YOUR_ORG_ID | grep aiplatform
   如果返回constraints/aiplatform.allowedServices，说明企业管理员禁用了AI服务，需联系IT部门。

4. 检查Billing Account状态
   进入Billing → Overview → 查看Account Status。常见陷阱：信用卡过期、余额不足、账户被暂停。注意：免费额度不等于Billing Account启用。

5. 清除浏览器缓存并禁用插件
   这听起来像玄学，但真实发生过：某次Chrome插件（广告拦截器）篡改了X-Goog-AuthUser请求头，导致权限校验失败。用Incognito模式测试可快速排除。

5.2 GKE部署失败的五大高频原因

5.3 Skills调用超时的深度诊断法

当Agent报告weather-forecast-skill超时，不要急着调大timeout_ms。按顺序执行以下诊断：

1. 确认Skill自身延迟：kubectl logs POD_NAME | grep "invocation_id"，找duration_ms字段。如果<1000ms，说明Skill没问题，问题在Agent到Skill的网络。

2. 检查Service Mesh延迟：kubectl exec -it istio-proxy-POD_NAME -- pilot-agent request GET stats | grep "outbound|8080||weather-forecast-skill.skills-namespace.svc.cluster.local"，看cluster.outbound|8080||weather-forecast-skill.skills-namespace.svc.cluster.local.upstream_rq_time。如果>5000ms，说明Istio代理有问题。

3. 验证DNS解析：kubectl exec -it AGENT_POD_NAME -- nslookup weather-forecast-skill.skills-namespace.svc.cluster.local。如果超时，检查CoreDNS Pod状态。

4. 抓包分析：kubectl exec -it POD_NAME -- tcpdump -i any -w /tmp/capture.pcap port 8080，下载后用Wireshark分析TCP三次握手和TLS协商时间。

5. 最后才调大超时：如果以上都正常，且确认是OpenWeatherMap API本身慢，则在skill.yaml中将timeout_ms从8000改为12000，并同步更新Agent的调用超时。

5.4 前端find skills功能的实现要点

热搜词里“skills推荐”、“find skills”需求，本质是Skills Registry的前端展示。我们实现了一个轻量级Registry服务，关键代码如下：

// frontend/src/services/skillsRegistry.ts export interface Skill { name: string; version: string; description: string; inputSchema: Record<string, any>; // JSON Schema outputSchema: Record<string, any>; tags: string[]; } // 调用Skills Registry API export const searchSkills = async (query: string, tags?: string[]): Promise<Skill[]> => { const params = new URLSearchParams(); params.append('q', query); if (tags) tags.forEach(tag => params.append('tag', tag)); const response = await fetch(`/api/skills?${params}`, { headers: { 'Authorization': `Bearer ${getAuthToken()}` // 使用IAP JWT } }); return response.json(); }; // 在React组件中使用 const SkillsSearch = () => { const [results, setResults] = useState<Skill[]>([]); const [loading, setLoading] = useState(false); const handleSearch = async (e: FormEvent) => { e.preventDefault(); setLoading(true); try { const data = await searchSkills(query, ['weather', 'public-api']); setResults(data); } catch (err) { console.error('Search failed:', err); alert('Skills search unavailable'); } finally { setLoading(false); } }; };

前端要点：

• 必须用IAP JWT认证：getAuthToken()调用GCP的gapi.auth2.getAuthInstance().currentUser.get().getAuthResponse().id_token，确保前端请求也经过IAP校验。

• 搜索参数设计：q支持全文检索（Skill名称+描述