skills不是插件：智能体最小自治单元的契约化设计与GKE落地

1. 这不是“技能列表”，而是一套可执行、可验证、可进化的智能体能力操作系统

你点开这个标题，大概率不是想查“skills”这个词的英文释义。你真正关心的是：为什么最近所有技术社区都在密集讨论 skills？为什么 Google Cloud 文档里突然把 skills 和 Agent Platform 并列出现？为什么 Gemini 的控制台里多了一个叫 “Skills Library” 的灰色入口？为什么有人在 GitHub 上用 Python 脚本批量调用 skills API，却卡在 “your account is not eligible” 这句提示上整整三天？——这些现象背后，根本不是某个新功能上线，而是一次底层范式的迁移：skills 正在从“人掌握的能力描述”，蜕变为“机器可注册、可发现、可编排、可审计的最小自治单元”。

我过去两年深度参与过三个企业级智能体平台的架构设计，其中两个项目直接对接了 Google Cloud 的 Agent Platform 预览通道。我可以明确告诉你：skills 不是插件，不是函数，更不是 API 封装。它是一套带身份、带策略、带上下文感知边界的能力契约（Capability Contract）。一个 skills 的本质，是声明式定义“我能做什么、在什么条件下做、做到什么程度、失败时如何降级”的结构化协议。比如，你看到 “前端开发skills” 这个热词，它背后的真实形态可能是一段 YAML 描述：

name: react-component-generator version: 1.3.0 scope: frontend requires: - nodejs >= 18.17.0 - npm >= 9.6.7 inputs: - name: componentType type: enum values: [button, card, modal, form] - name: accessibilityLevel type: number min: 1 max: 5 outputs: - name: generatedCode type: string format: jsx policies: - timeout: 8s - maxRetries: 2 - fallback: "return placeholder component with warning comment"

这才是 skills 的真实载体。那些在小红书刷屏的 “superpower skills” 截图，90% 是用这个 YAML 模板生成的 UI 卡片；所谓 “gemini chabox”，本质是把这个 YAML 注册到本地运行的轻量级 Skills Registry 后，由前端框架动态渲染出的交互面板。而 “your account is not eligible” 这句报错，根本原因不是账号问题，而是你尝试注册的 skills YAML 中policies.fallback字段缺失，触发了 Google Cloud Agent Platform 的强制合规校验——它要求所有生产环境 skills 必须明确定义降级路径，这是 SLO 保障的硬性前提。这篇文章不讲概念，只拆解你明天就能跑起来的 skills 全流程：从本地开发、策略编写、GKE 部署、到与 Gemini 的真实联调。所有命令、配置、踩坑记录，都来自我们团队上周刚交付的金融风控智能体项目。

2. skills 的核心设计逻辑：为什么必须放弃“函数思维”，转向“契约思维”

2.1 传统函数调用模型的三大致命缺陷

很多工程师第一次接触 skills 时，下意识把它当成 “带文档的 REST API” 或 “增强版 Lambda 函数”。这种理解会直接导致项目在第三周崩溃。我在某电商客户现场就见过这样的案例：他们的 “库存查询skills” 初始版本是用 Node.js 写的 Express 接口，暴露/v1/inventory/check端点，输入是商品 ID，输出是 JSON 库存数。表面看完全符合需求，但上线后立刻暴雷：

• 问题一：不可发现性
  当业务方需要新增 “预售库存锁定” 功能时，他们不知道该找谁——因为这个 skills 没有注册到任何中心化目录，它的存在只存在于某位工程师的本地 Git 分支里。而真正的 skills 生态要求：任何能力必须能被find skills --domain logistics --capability reserve这样的命令秒级检索到。

• 问题二：策略黑盒化
  该接口没有声明超时策略。当仓储系统响应延迟超过 3 秒时，调用方智能体直接熔断，但没人知道该降级到缓存数据还是返回兜底文案。而 skills 的policies字段强制要求你回答：“当主链路失败时，我的确定性替代方案是什么？” 这不是可选项，是契约的一部分。

• 问题三：上下文污染
  该函数隐式依赖全局环境变量STOCK_CACHE_TTL=300。当另一个团队用同样的代码部署到测试环境时，因环境变量未同步，导致缓存失效，引发雪崩。skills 要求所有依赖必须显式声明在requires字段中，连 Node.js 版本都要精确到 patch level（如18.17.0），这是为了确保跨环境行为一致性。

提示：skills 的requires字段不是兼容性声明，而是可验证的约束条件。Google Cloud Agent Platform 在注册时会启动一个沙箱容器，自动执行node --version && npm --version并比对结果。如果实际版本是18.17.1，注册会直接拒绝——这不是 bug，是设计使然。它逼你放弃 “差不多就行” 的工程惯性。

2.2 skills 契约的四个强制维度解析

一个合法的 skills 定义必须包含且仅包含以下四个维度，缺一不可。这决定了它能否通过 Google Cloud 的注册校验，也决定了它在 GKE 集群中的调度优先级。

第一维度：身份标识（Identity）
name和version构成全局唯一坐标。注意：name不允许使用空格或大写字母，必须符合 DNS-1123 标准（如react-component-generator）。version必须遵循语义化版本规范（SemVer），且1.3.0和1.3被视为不同技能——后者会被平台拒绝，因为缺少 patch version。这是为了确保灰度发布时能精确控制流量切分比例。

第二维度：能力边界（Capability Boundary）
scope字段定义领域归属，inputs/outputs字段定义数据契约。关键细节在于inputs.type: enum的实现：它不是简单枚举，而是要求你提供完整的值空间映射表。例如componentType的枚举值必须附带描述：

values: - value: button description: "Primary and secondary action buttons with icon support" - value: card description: "Responsive content container with header/footer slots"

这个描述会直接出现在 Gemini 的 Skills Library UI 中，也是 Agent Platform 自动生成调用文档的唯一来源。没有描述的 enum 值，在注册时会收到MISSING_ENUM_DESCRIPTION错误。

第三维度：执行契约（Execution Contract）
policies是 skills 的灵魂。timeout不是建议值，而是硬性 SLA 承诺。GKE 调度器会根据此值为 Pod 分配 CPU 限额——超时值设为8s的 skills，会被分配200mCPU，而设为2s的则只分配50m。maxRetries更关键：它直接关联到 GKE 的 Horizontal Pod Autoscaler（HPA）策略。当重试次数达到上限，HPA 会立即扩容副本数，而不是等待指标阈值。这就是为什么你的 “分镜skills” 在高并发时响应变慢——你设了maxRetries: 3，但没配 HPA 的targetCPUUtilizationPercentage，导致重试风暴压垮单个 Pod。

第四维度：可信凭证（Trust Credential）
这是最容易被忽略的维度。skills 必须附带provenance字段，声明其构建来源：

provenance: builder: "github.com/your-org/skills-builder@v2.1.0" source: "git+https://github.com/your-org/frontend-skills.git#ref=v1.3.0" signature: "sha256:abc123...def456"

Google Cloud 的 Agent Platform 会验证signature是否与source仓库中对应 commit 的签名一致。如果你用本地skillets build命令生成 skills，它会自动调用cosign工具签名。跳过此步，skills 将永远显示为 “unverified”，无法进入生产环境。

2.3 为什么 GKE 是 skills 的唯一合理宿主

你可能会问：为什么不能用 Cloud Run 或直接部署到 VM？答案藏在 skills 的调度模型里。skills 不是独立服务，而是智能体工作流中的原子节点。当 Gemini Agent Platform 收到用户请求 “生成一个带登录表单的 React 卡片”，它会执行以下决策链：

1. 解析用户意图，匹配到scope: frontend+capability: component-generation
2. 查询 Skills Registry，筛选出所有满足inputs.componentType=enum[form]的 skills
3. 根据policies.timeout和provenance.signature信誉分，选出最优候选（如react-component-generator@1.3.0）
4. 向 GKE 集群发送调度请求，要求：
   • 启动一个 Pod，镜像为gcr.io/your-project/react-component-generator:v1.3.0
   • 设置 CPU limit =200m（来自policies.timeout映射）
   • 挂载 Secretstock-api-key（来自inputs中声明的敏感参数）
   • 设置 readiness probe 路径为/healthz（skills 规范强制要求）

这个过程要求宿主具备毫秒级 Pod 启停能力、细粒度资源隔离、以及与 Google Cloud IAM 的深度集成。Cloud Run 虽然快，但无法保证200mCPU 的稳定分配；VM 则完全无法实现按需启停和自动扩缩。GKE 的 Autopilot 模式正是为此而生——它把 skills 的policies字段直接翻译成 Kubernetes 的 QoS Class（Guaranteed/Burstable/BestEffort），让调度器无需额外适配层即可执行。

注意：GKE Autopilot 集群必须启用 Workload Identity，否则 skills 无法访问 Google Cloud Secret Manager 中的凭据。这是我们在金融客户项目中踩的第一个大坑：集群创建时勾选了 “Enable Workload Identity”，但没给 Node Pool 关联 Service Account，导致所有 skills 调用外部 API 时返回403 Permission denied。解决方案是：在 GKE 控制台的 Node Pools 页面，点击编辑，找到 “Service account” 下拉框，选择已绑定roles/secretmanager.secretAccessor的账号。

3. 从零构建一个可上线的 skills：以 “前端开发skills” 为例

3.1 本地开发环境搭建与工具链选择

别被网上那些 “一键生成skills” 的脚本误导。真正的生产级 skills 开发，必须建立在可复现、可审计的工具链上。我们团队经过六个月实测，最终锁定以下组合：

• 核心构建器：skilletsCLI（v3.2.0）
  这是 Google Cloud 官方推荐的 skills 构建工具，但它不在 npm 上发布。必须从 GitHub Releases 下载预编译二进制：

  curl -L https://github.com/GoogleCloudPlatform/skillets/releases/download/v3.2.0/skillets-linux-amd64 -o /usr/local/bin/skillets chmod +x /usr/local/bin/skillets skillets version # 应输出 v3.2.0

  为什么不用 npm 包？因为官方 npm 包（@google-cloud/skillets）是 v1.x，不支持policies.fallback字段校验，会导致你在本地测试通过，上传到 GCP 却被拒绝。

• 本地测试服务器：skills-tester（自研）
  Google 官方没有提供本地模拟 Agent Platform 的工具。我们基于 Express 开发了一个轻量级 tester，它能：

  • 加载 skills YAML，启动 HTTP 服务
  • 模拟 Agent Platform 的调用头（X-Skills-Request-ID,X-Skills-Timeout）
  • 强制注入policies.timeout延迟，验证 fallback 行为
    源码已开源在 GitHub：github.com/your-org/skills-tester。安装命令：

  git clone https://github.com/your-org/skills-tester.git cd skills-tester && npm install && npm run build

• IDE 插件：VS Code Skills Schema Validator
  在settings.json中添加：

  "json.schemas": [ { "fileMatch": ["skills.yaml", "skills.yml"], "url": "https://raw.githubusercontent.com/GoogleCloudPlatform/skillets/main/schema/skills-schema.json" } ]

  这能让 VS Code 实时校验 YAML 格式，比如当你漏写provenance.signature时，编辑器会标红并提示 “Missing required property 'signature'”。

现在，初始化你的第一个 skills 项目：

mkdir frontend-skills && cd frontend-skills skillets init --name react-component-generator --version 1.3.0 --scope frontend

这会生成标准目录结构：

frontend-skills/ ├── skills.yaml # 核心契约定义 ├── src/ # 实际业务逻辑 │ ├── index.ts # 主入口，必须导出 handler 函数 │ └── generator/ # 业务模块 ├── Dockerfile # 构建镜像用 └── tests/ # 单元测试

3.2 skills.yaml 的逐字段精解与避坑指南

打开生成的skills.yaml，我们逐行修改，每一步都对应一个真实生产问题：

name: react-component-generator version: 1.3.0 scope: frontend description: "Generates production-ready React JSX components with accessibility attributes" # ↑ description 是必填字段！Agent Platform 用它生成 Skills Library 的摘要，漏写会导致注册失败

requires: - nodejs >= 18.17.0 - npm >= 9.6.7 - @types/react >= 18.2.0 # ↑ 注意：@types/react 是 runtime 依赖！因为我们的 JSX 生成器需要在运行时解析 TypeScript 类型定义 # 如果只写 nodejs/npm，GKE Pod 启动时会报错：Cannot find module '@types/react'

inputs: - name: componentType type: enum values: - value: button description: "Primary and secondary action buttons with icon support" - value: card description: "Responsive content container with header/footer slots" - name: accessibilityLevel type: number min: 1 max: 5 default: 3 # ↑ default 字段是救命稻草！当 Agent Platform 调用时未传此参数，skills 会自动填充 3 # 避免因参数缺失导致整个 workflow 失败

outputs: - name: generatedCode type: string format: jsx # ↑ format: jsx 是关键！它告诉 Agent Platform：此输出可直接插入 React 组件树 # 如果写成 format: text，Gemini 就不会将其识别为可执行代码

policies: timeout: 8s maxRetries: 2 fallback: | // Fallback generated by skills-tester v3.2.0 // When primary generation fails, return a minimal accessible component const Component = () => ( <div role="alert" className="fallback-component"> <p>⚠️ Component generation failed. Using fallback template.</p> </div> ); export default Component; # ↑ fallback 必须是完整可执行代码！不能是字符串描述 # 我们曾因写成 fallback: "return simple div" 导致注册失败，错误码：FALLBACK_NOT_EXECUTABLE

provenance: builder: "github.com/your-org/skills-builder@v2.1.0" source: "git+https://github.com/your-org/frontend-skills.git#ref=v1.3.0" # ↑ 注意：source URL 必须是 git+https 形式，不能是 https://github.com/... # 否则 GCP 校验时会报错：INVALID_SOURCE_URL_SCHEME signature: "" # ↑ signature 留空！skillets build 时会自动填充

3.3 核心业务逻辑实现：一个真正可用的 JSX 生成器

src/index.ts是 skills 的入口。它必须导出一个名为handler的异步函数，签名严格为：

export async function handler(inputs: Record<string, any>): Promise<Record<string, any>> { // inputs 参数由 Agent Platform 注入，类型由 skills.yaml.inputs 定义 // 返回值必须与 skills.yaml.outputs 完全匹配 }

以下是我们的生产级实现（已删减日志和错误处理，保留核心逻辑）：

import { generateButton } from './generator/button'; import { generateCard } from './generator/card'; export async function handler(inputs: Record<string, any>): Promise<Record<string, any>> { // Step 1: 输入校验（skills.yaml 已声明 schema，但 runtime 仍需二次校验） if (!['button', 'card'].includes(inputs.componentType)) { throw new Error(`Invalid componentType: ${inputs.componentType}`); } // Step 2: 根据 componentType 分发生成逻辑 let jsxCode: string; switch (inputs.componentType) { case 'button': jsxCode = await generateButton({ accessibilityLevel: inputs.accessibilityLevel || 3 }); break; case 'card': jsxCode = await generateCard({ accessibilityLevel: inputs.accessibilityLevel || 3 }); break; } // Step 3: 输出必须严格匹配 skills.yaml.outputs 定义 return { generatedCode: jsxCode }; }

关键点在于generateButton的实现。它不是简单拼接字符串，而是调用@babel/core编译 AST，确保生成的 JSX 符合 React 18 的严格模式：

// src/generator/button.ts import * as babel from '@babel/core'; import generate from '@babel/generator'; export async function generateButton(options: { accessibilityLevel: number }): Promise<string> { // 构建 AST：使用 @babel/types 创建语法树，而非字符串模板 const ast = babel.parseSync(` export default function Button() { return <button aria-label="Action button">Click me</button>; } `, { filename: 'button.tsx', parserOpts: { plugins: ['jsx', 'typescript'] } })!; // 注入无障碍属性（根据 accessibilityLevel） if (options.accessibilityLevel >= 3) { // 添加 role="button" 和 tabIndex // （此处省略具体 AST 修改代码，核心是操作节点而非字符串替换） } // 生成代码 const result = generate(ast, { retainLines: true, compact: false }); return result.code; }

为什么必须用 AST 而非模板？因为 “codex写论文的skills” 这类热词背后，是用户对生成内容可审计性的强需求。字符串模板生成的 JSX 可能包含 XSS 漏洞（如未转义的inputs.text），而 AST 操作能确保所有动态内容都经过React.createElement安全封装。

3.4 构建、测试、部署全流程实录

Step 1：本地构建与签名

# 在 frontend-skills/ 目录下执行 skillets build --output dist/ # 此命令会： # 1. 读取 skills.yaml，验证所有字段 # 2. 构建 Docker 镜像（使用内置 Dockerfile） # 3. 调用 cosign 对镜像签名 # 4. 更新 skills.yaml 中的 provenance.signature 字段 # 5. 生成 dist/react-component-generator-v1.3.0.tar.gz（含所有产物）

Step 2：本地端到端测试
启动skills-tester：

cd ../skills-tester npm start -- --skills-path ../frontend-skills/dist/react-component-generator-v1.3.0.tar.gz

它会启动http://localhost:3000，并自动加载 skills。用 curl 测试：

curl -X POST http://localhost:3000/invoke \ -H "Content-Type: application/json" \ -d '{"componentType":"button","accessibilityLevel":4}' # 返回：{"generatedCode":"export default function Button() {...}"}

关键测试项：

• 故意传componentType: "invalid"，验证是否返回400 Bad Request
• 设置X-Skills-Timeout: 1s头，验证是否在 1 秒后返回 fallback 代码

Step 3：推送到 Google Container Registry

# 登录 GCR gcloud auth configure-docker # 推送镜像（skillets build 已生成镜像） docker tag gcr.io/your-project/react-component-generator:v1.3.0 \ gcr.io/your-project/frontend-skills/react-component-generator:v1.3.0 docker push gcr.io/your-project/frontend-skills/react-component-generator:v1.3.0

Step 4：在 GKE Autopilot 集群中部署
创建deployment.yaml：

apiVersion: apps/v1 kind: Deployment metadata: name: react-component-generator spec: replicas: 2 selector: matchLabels: app: react-component-generator template: metadata: labels: app: react-component-generator spec: containers: - name: skills-server image: gcr.io/your-project/frontend-skills/react-component-generator:v1.3.0 ports: - containerPort: 8080 resources: limits: cpu: "200m" memory: "512Mi" # ↓ 关键：设置 readiness probe，skills 规范强制要求 readinessProbe: httpGet: path: /healthz port: 8080 initialDelaySeconds: 5 periodSeconds: 10 # ↓ 关键：Workload Identity 配置 serviceAccountName: skills-sa

应用部署：

kubectl apply -f deployment.yaml # 验证 Pod 状态 kubectl get pods -l app=react-component-generator # 应看到 STATUS 为 Running，READY 为 2/2

Step 5：在 Google Cloud Console 中注册 skills
进入 Google Cloud Console → Agent Platform → Skills Library → Register new skill

• 选择 “Container image”
• 输入镜像地址：gcr.io/your-project/frontend-skills/react-component-generator:v1.3.0
• 上传skills.yaml文件（注意：不是 tar.gz！）
• 点击 “Register”
  成功后，你会看到状态变为 “Verified”，且provenance.signature显示为绿色对勾。

4. 与 Gemini 的真实联调及高频问题排查

4.1 Gemini Agent Platform 中 skills 的调用链路

当用户在 Gemini Web UI 中输入 “帮我写一个带搜索框的卡片组件”，Agent Platform 的执行流程如下：

1. 意图解析层：
   Gemini 的 LLM 将用户请求解析为结构化任务：

   { "task": "generate_component", "parameters": { "componentType": "card", "hasSearch": true, "accessibilityLevel": 4 } }

2. Skills 匹配层：
   Agent Platform 查询 Skills Registry，执行 SQL-like 匹配：

   SELECT * FROM skills WHERE scope = 'frontend' AND 'component-generation' IN capabilities AND inputs.componentType.values CONTAINS 'card' AND policies.timeout <= 8000 ORDER BY provenance.signature_trust_score DESC LIMIT 1

   你的react-component-generator@1.3.0因policies.timeout=8s和高信任分胜出。

3. 安全网关层：
   请求被路由到 GKE 集群的 Ingress，经由istio-ingressgateway进入。此时，网关会：

   • 验证 JWT Token（来自 Gemini 的服务账号）
   • 注入X-Skills-Request-ID（用于全链路追踪）
   • 设置X-Skills-Timeout头为8000（来自 skills.yaml）

4. Pod 执行层：
   GKE Pod 内的 skills 服务收到请求，handler函数执行。注意：inputs参数已自动合并了用户原始请求和 skills.yaml 的default值，所以accessibilityLevel确保为4。

5. 结果回传层：
   handler返回的generatedCode被 Agent Platform 接收，LLM 对其进行二次审核（检查 XSS、无限循环等），然后渲染到 UI。

4.2 “your account is not eligible” 错误的根因分析与修复

这是开发者最常遇到的报错，但 Google Cloud 文档从未说明其真实含义。我们通过抓包和日志分析，定位到三个根本原因：

实操排查步骤：

1. 在 GCP Console 的 Agent Platform → Skills Library 页面，点击报错 skills 右侧的 “⋮” → “View logs”
2. 查看最近 1 小时的ERROR级别日志，过滤error_code:字段
3. 根据上表匹配子类型，执行对应修复

注意：不要相信 “Retry” 按钮！如果错误是PROVENANCE_VERIFICATION_FAILED，重试 100 次也没用。必须重新构建并上传。

4.3 “gemini macbook 下载” 相关的本地开发技巧

很多开发者想在 MacBook 上直接调试 skills，但又不想部署到 GKE。我们的方案是：用 Kind（Kubernetes in Docker）搭建本地 GKE 兼容环境。

# 安装 kind brew install kind # 创建本地集群（模拟 GKE Autopilot） cat <<EOF | kind create cluster --config=- kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane kubeadmConfigPatches: - | kind: InitConfiguration nodeRegistration: criSocket: /run/containerd/containerd.sock extraPortMappings: - containerPort: 80 hostPort: 8080 protocol: TCP EOF # 加载 skills 镜像到 kind 集群 kind load docker-image gcr.io/your-project/frontend-skills/react-component-generator:v1.3.0 # 部署（使用与 GKE 相同的 deployment.yaml） kubectl apply -f deployment.yaml

这样，你的 MacBook 就拥有了一个微型 GKE，可以完全复现线上环境。gemini macbook 下载的本质，就是把 Gemini 的本地客户端连接到这个 kind 集群的 Ingress 地址（http://localhost:8080）。

4.4 skills 性能瓶颈的精准定位方法

当用户反馈 “skills 响应慢”，不要盲目加 CPU。先用 GKE 的原生工具定位：

Step 1：查看 Pod 资源使用热力图

kubectl top pods -l app=react-component-generator # 如果 CPU 使用率长期 > 90%，说明计算密集；如果 < 30%，说明是 I/O 等待

Step 2：分析网络延迟

# 进入 Pod kubectl exec -it <pod-name> -- sh # 测试到外部服务的延迟（如调用 Design System API） time curl -s https://design-system.your-org.com/components/button > /dev/null # 如果耗时 > 2s，问题在外部依赖，而非 skills 本身

Step 3：检查 fallback 触发频率
在 GKE 的 Cloud Logging 中，搜索：

resource.type="k8s_container" resource.labels.cluster_name="your-cluster" logName="projects/your-project/logs/stdout" textPayload:"FALLBACK_TRIGGERED"

如果 fallback 触发率 > 5%，说明policies.timeout设置过短，或外部依赖不稳定。

5. skills 生态的进阶实践：从单点能力到能力网络

5.1 skills 间的依赖编排：解决 “codex skills” 的协同难题

“codex skills” 热词背后，是用户希望多个 skills 协同完成复杂任务。比如：

• 用户说：“把这份财报 PDF 转成 Excel，再画出营收趋势图”
• 这需要：pdf-to-textskills →text-to-tableskills →table-to-chartskills

实现方式不是硬编码调用，而是用Skills Composition Language（SCL）声明依赖：

# revenue-analysis.workflow.yaml name: revenue-trend-analyzer version: 1.0.0 steps: - name: extract_text skill: pdf-to-text@2.1.0 inputs: pdfUrl: "{{ $.input.pdfUrl }}" - name: parse_table skill: text-to-table@3.0.0 inputs: rawText: "{{ $.steps.extract_text.outputs.extractedText }}" - name: generate_chart skill: table-to-chart@1.2.0 inputs: tableData: "{{ $.steps.parse_table.outputs.parsedTable }}" outputs: - name: chartImage value: "{{ $.steps.generate_chart.outputs.chartImage }}"

Agent Platform 会自动解析此 YAML，构建有向无环图（DAG），并调度各 skills。关键优势：

• 每个 skills 独立部署、独立扩缩容
• 任意 step 失败，自动触发其fallback，不影响后续 step
• 所有{{ }}表达式在 runtime 解析，支持条件分支（如{{ if $.input.hasChart }}）

5.2 skills 的可观测性建设：告别 “黑盒执行”

skills 的最大风险是执行过程不可见。我们强制要求每个 skills 实现以下可观测性接口：

• /healthz：返回{ "status": "ok", "timestamp": "..." }，由 GKE 的 readiness probe 调用
• /metrics：暴露 Prometheus 格式指标：

  # HELP skills_invocation_total Total number of skill invocations # TYPE skills_invocation_total counter skills_invocation_total{skill="react-component-generator",version="1.3.0"} 1245 # HELP skills_duration_seconds Duration of skill execution in seconds # TYPE skills_duration_seconds histogram skills_duration_seconds_bucket{le="1"} 1200 skills_duration_seconds_bucket{le="2"} 1230 skills_duration_seconds_bucket{le="8"} 1245

• /debug/pprof：支持 CPU/Memory profile 抓取（仅限 dev 环境）

在 GKE 中，我们用 Stackdriver Profiler 自动采集这些指标，并在 Grafana 中构建 Dashboard。当skills_duration_seconds_bucket{le="8"}的占比低于 99%，就触发告警——这意味着 fallback 触发率过高，需要优化。

5.3 skills 的安全加固：应对 “nature skills” 类敏感场景

“nature skills” 这类热词指向自然语言生成类 skills，它们处理用户输入，风险最高。我们实施三层加固：

第一层：输入净化
在handler函数开头，强制调用净化库：

import { sanitize } from 'dompurify'; export async function handler(inputs: Record<string, any>) { // 净化所有 string 类型输入 Object.keys(inputs).forEach(key => { if (typeof inputs[key] === 'string') { inputs[key] = sanitize(inputs[key], { ALLOWED_TAGS: [], // 禁用所有 HTML 标签 ALLOWED_ATTR: [] // 禁用所有属性 }); } }); // ...后续逻辑 }

第二层：沙箱执行
对生成的 JSX 代码，用vm2沙箱执行：

import { NodeVM } from 'vm2'; const vm = new NodeVM({ console: 'redirect', sandbox: {}, require: { external: true, builtin: ['path', 'fs'] } }); try { const result