企业官网建设流程全解析

1. 什么是 agent-skills：一个被严重低估的工程化接口层

“agent-skills”这个词最近在开发者社区里频繁刷屏，但它既不是某个新出的开源框架，也不是某家大厂刚发布的闭源产品。它本质上是一套面向智能体（Agent）能力封装与调用的标准化工程实践范式——你可以把它理解成“给大模型装上可插拔的工具手”。我从2022年就开始在内部项目中构建类似机制，当时叫“toolchain adapter”，后来团队统一改名叫“skills”，再往后演进到“agent-skills”，不是为了赶时髦，而是因为这个词精准击中了三个核心痛点：可发现、可组合、可验证。

它和 CLI（命令行界面）深度耦合，但绝不是简单的“把函数包装成命令”。真正的 agent-skills 是一套带元数据描述、输入校验、执行沙箱、错误归因和可观测性的轻量级服务契约。比如你写一个weatherskill，它不能只是调用一次 OpenWeather API 就完事；它必须声明自己依赖哪些环境变量（如WEATHER_API_KEY），接受什么格式的输入（{"city": "shanghai", "unit": "c"}），返回什么结构（{"temp": 23.4, "condition": "partly cloudy"}），超时多久（默认 5s），失败后是否重试（最多 2 次），以及如何将错误映射成用户能懂的语言（“城市名未识别”而非 “HTTP 404”）。这些信息不是注释，而是被解析器读取并用于自动路由、权限控制和调试追踪的结构化字段。

为什么 slash commands（斜杠命令）会成为主流载体？因为它是目前最接近自然语言交互与确定性执行之间平衡点的设计。/translate zh2en "你好"这种写法，既保留了人类表达意图的自由度（比纯 JSON 更易写），又规避了 LLM 自由生成带来的不可控风险（比纯 prompt 更可靠）。我在做客服 Agent 重构时对比过：用纯 prompt 调用翻译功能，错误率高达 17%（模型漏掉参数、拼错语言码、擅自加解释文本）；换成/translateskill 后，错误率压到 0.3%，且所有异常都能准确定位到是 API key 过期还是 rate limit 触发。

这套范式正在快速下沉到前端开发场景。不是说前端要写 Python backend，而是通过 zcode cli 或 codex cli 这类工具链，在本地一键生成符合 OpenAPI 3.0 规范的 skill 描述文件（YAML），再用 Vite 插件自动注入到 React 组件中，让<SkillButton name="summarize" />这样的组件能直接触发后端 skill 执行，并自带 loading 状态、错误 toast 和结果缓存。这已经不是“调用 API”，而是把远程能力变成前端可复用的 UI 原子单元。

对 API 使用者来说，“agent-skills”意味着告别碎片化集成。你不再需要为每个服务单独写 auth 逻辑、重试策略、降级 fallback；所有 skill 都遵循同一套契约，客户端 SDK 只需实现一次通用 dispatcher，就能调度天气、翻译、数据库查询、甚至本地 PDF 解析等异构能力。我在给一家跨境电商做订单分析 Agent 时，用 3 天时间集成了 7 个不同供应商的 API（物流轨迹、关税计算、库存同步、汇率转换、多语言翻译、图片水印、邮件模板渲染），全部通过统一的skill://协议注册，没有一行重复的网络请求胶水代码。

2. 核心设计逻辑：为什么 agent-skills 不是 API 的简单别名

2.1 技术分层的本质差异：从 endpoint 到 capability

很多人第一反应是：“不就是封装 API 吗？我早就在做了。” 这是个典型误区。API 是 endpoint 导向的，关注“怎么调通”；agent-skills 是 capability 导向的，关注“怎么用好”。举个具体例子：

• 一个典型的/v1/translateAPI 文档会告诉你：

  • 请求方法：POST
  • URL：https://api.example.com/v1/translate
  • Header：Authorization: Bearer xxx
  • Body：{"text": "...", "source_lang": "...", "target_lang": "..."}

• 而一个translateskill 的描述文件（skill.yaml）则包含：

  name: translate version: 1.2.0 description: "将文本从源语言翻译为目标语言，支持 128 种语言对" author: "dev-team@company.com" category: "nlp" input_schema: type: object required: [text, target_lang] properties: text: type: string maxLength: 5000 source_lang: type: string enum: ["auto", "zh", "en", "ja", "ko", "fr", "de", "es"] default: "auto" target_lang: type: string enum: ["zh", "en", "ja", "ko", "fr", "de", "es"] format: type: string enum: ["text", "html", "markdown"] default: "text" output_schema: type: object properties: translated_text: type: string detected_source_lang: type: string confidence: type: number minimum: 0 maximum: 1 execution: timeout_ms: 8000 max_retries: 2 retry_delay_ms: 500 backoff_factor: 1.5 dependencies: - env: TRANSLATE_API_KEY - env: TRANSLATE_BASE_URL - package: requests>=2.28.0 permissions: - network: https://api.example.com/** - storage: /tmp/translate-cache/

看到区别了吗？API 文档只解决“能不能调”，skill 描述解决的是“该不该调、怎么调、调坏了怎么办”。它把隐含的业务约束（如最大文本长度）、运维要求（超时重试）、安全边界（网络白名单）、依赖管理（环境变量和包版本）全部显式化、结构化。这不是文档升级，而是工程契约的升维。

2.2 CLI 作为技能生命周期管理中枢的必然性

为什么所有主流 agent-skills 生态都强绑定 CLI 工具（zcode cli、codex cli、boos cli）？因为 skill 的生命周期远不止“写完就用”。它包含：开发 → 测试 → 注册 → 发布 → 版本管理 → 权限配置 → 监控告警 → 下线回收。这些操作如果全靠 Web UI 或手动脚本，效率极低且极易出错。

以codex cli为例，它的核心命令链路是：

# 1. 初始化新 skill（自动生成骨架+测试用例+CI 配置） codex init --name=pdf-extract --category=document # 2. 本地开发并实时调试（自动启动 mock server + hot reload） codex dev # 3. 运行单元测试 + 集成测试（内置 fixture 数据库） codex test # 4. 构建可部署包（包含依赖锁定、二进制打包、签名） codex build # 5. 推送到 registry（支持私有 Nexus 或公共 Hub） codex publish --registry=https://hub.myorg.com # 6. 在目标环境安装（自动处理依赖、权限、systemd service） codex install --env=prod --version=1.2.0 pdf-extract

这个流程的关键在于CLI 不是命令集合，而是 skill 生命周期的状态机驱动器。比如codex test不仅运行 pytest，还会：

• 自动注入 mock credentials（避免测试污染真实 API）
• 启动临时 SQLite DB 模拟外部依赖
• 生成覆盖率报告并高亮未覆盖的 error path
• 对比 baseline 输出，检测语义回归（如翻译结果是否显著偏离）

我在给金融客户做风控 Agent 时，曾用codex test --mode=fuzz对credit-scoreskill 进行模糊测试：自动生成 10 万组边界值输入（负数年龄、超长身份证号、空字符串姓名），发现 3 个深层 bug（整数溢出导致评分翻倍、正则表达式回溯爆炸、缓存键冲突）。这种深度验证，是传统 API 测试工具根本做不到的。

2.3 Slash Commands：人机协作的最小语义单元

Slash commands 表面看是语法糖，实则是人机协作协议的物理载体。它的设计哲学是：用最简符号承载最明确意图。/符号天然具有“主动发起”、“非对话延续”的语义，这与 Agent 的“执行模式”完美契合。对比其他交互形式：

• 自然语言指令（如“帮我查下北京今天天气”）：LLM 需要先做意图识别（intent classification），再提取参数（slot filling），最后路由到对应模块。这个过程有延迟、有歧义、有幻觉风险。实测中，同等复杂度指令下，slash command 的首字节响应快 320ms，意图识别准确率高 22%。

• 按钮式 UI（如“翻译”按钮）：缺乏参数表达能力。用户无法指定源语言、目标语言、格式，只能走预设路径，灵活性差。

• 纯 API 调用（如 POST /api/skills/translate）：需要用户懂技术细节，违背“低门槛接入”原则。

而/weather beijing这种写法，把意图（weather）、主体（beijing）、动作（query）全部压缩在一个原子操作里。更关键的是，它支持渐进式增强：

• 基础版：/weather（自动定位）
• 进阶版：/weather shanghai celsius（指定城市和单位）
• 专业版：/weather --forecast=3days --alerts=true shanghai（带 flag 的结构化参数）

这种设计让 skill 既能被普通用户无脑使用，又能被高级用户精确控制，还便于日志分析（所有/weather调用可统一归类，无需 NLP 解析）。

2.4 Skills Registry：能力市场的基础设施

没有 registry，skills 就是散落的孤岛。一个健壮的 skills registry 必须解决四个问题：发现、信任、兼容、治理。

• 发现：不是简单关键词搜索。好的 registry 支持语义搜索（如搜“提取 PDF 表格”，能命中pdf-table-extract、document-parse、ocr-scan等不同 skill），基于 embedding 相似度而非字符串匹配。我们内部 registry 还支持“场景推荐”：当你注册了invoice-ocrskill，系统会自动提示“您可能还需要tax-calculation和bank-transfer”。

• 信任：每个 skill 必须附带 verifiable signature（用开发者私钥签名），registry 验证后才允许安装。同时强制要求提供：

  • SBOM（Software Bill of Materials）清单，列出所有依赖包及 CVE 风险
  • 性能基线报告（P95 延迟、内存占用、QPS）
  • 安全审计摘要（是否访问敏感 API、是否写入磁盘、是否启用 debug 模式）

• 兼容：registry 不是仓库，而是适配器中心。当deepseek-officialAPI 更新 v3 接口时，旧版deepseek-chatskill 仍能通过 registry 自动加载兼容层（adapter），无需用户重装。这种“接口演化透明化”极大降低维护成本。

• 治理：支持细粒度权限控制。比如financenamespace 下的 skills 只能被finance-teamgroup 安装；production环境禁止安装dev-only标记的 skill；所有database-write类 skill 必须经过 DBA 审批才能发布。我们在银行项目中，用这套机制将 200+ 个 skills 的上线周期从平均 5.2 天缩短到 0.8 天。

3. 实操落地：从零构建一个可生产的 weather skill

3.1 环境准备与工具链初始化

不要跳过这一步。很多团队失败就败在环境不一致。我推荐的最小可行环境是：

• 操作系统：Ubuntu 22.04 LTS 或 macOS Monterey+（Windows 用户请用 WSL2）
• Python：3.10（必须，因部分 LLM 库不兼容 3.11）
• Node.js：18.x（用于前端集成和 CLI 工具）
• Docker：24.0+（用于隔离测试环境）

首先安装codex cli（这是目前生态最成熟的工具，比 zcode cli 更稳定，比 boos cli 功能更全）：

# 注意：不要用 npm install -g codex-cli，官方已弃用全局安装 curl -fsSL https://get.codex.dev | bash # 安装后会提示添加 PATH，务必执行 export PATH="$HOME/.codex/bin:$PATH" # 验证 codex --version # 应输出 v2.4.1+

提示：如果国内下载慢，可替换镜像源。在~/.codex/config.yaml中添加：

registry: mirror: https://mirrors.tuna.tsinghua.edu.cn/codex-hub/ cache_dir: /data/codex-cache

这能将首次安装时间从 12 分钟缩短到 90 秒。

初始化项目前，先创建专用工作区：

mkdir -p ~/projects/agent-skills && cd ~/projects/agent-skills # 创建虚拟环境（强烈建议，避免包冲突） python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip setuptools wheel

3.2 Skill 开发：从骨架到可执行代码

运行初始化命令：

codex init --name=weather --category=iot --description="获取全球城市实时天气与预报"

这会生成标准目录结构：

weather/ ├── skill.yaml # 核心契约定义 ├── main.py # 主执行逻辑 ├── tests/ # 测试用例 │ ├── __init__.py │ └── test_weather.py ├── fixtures/ # 测试数据（mock API 响应） │ └── openweather.json ├── requirements.txt # 运行时依赖 └── README.md

编辑skill.yaml，填充关键字段：

name: weather version: 1.0.0 description: "获取全球城市实时天气与预报，支持 20 万+ 城市" author: "your-name@company.com" category: "iot" input_schema: type: object required: [city] properties: city: type: string minLength: 2 maxLength: 100 description: "城市名称（支持中文、英文、拼音）" units: type: string enum: ["metric", "imperial", "kelvin"] default: "metric" days: type: integer minimum: 1 maximum: 16 default: 1 output_schema: type: object properties: location: type: object properties: name: {type: string} country: {type: string} timezone: {type: integer} current: type: object properties: temp_c: {type: number} condition: {type: string} humidity: {type: integer} wind_kph: {type: number} forecast: type: array items: type: object properties: date: {type: string, format: "date"} day: type: object properties: maxtemp_c: {type: number} mintemp_c: {type: number} condition: {type: string} execution: timeout_ms: 10000 max_retries: 3 retry_delay_ms: 1000 dependencies: - env: OPENWEATHER_API_KEY permissions: - network: https://api.openweathermap.org/**

现在编写main.py。关键原则：绝不硬编码 API URL 或密钥，所有外部依赖必须通过环境变量注入：

import os import json import requests from typing import Dict, Any from urllib.parse import urlencode def execute(input_data: Dict[str, Any]) -> Dict[str, Any]: """ Weather skill 主执行函数 input_data: 符合 input_schema 的字典 返回: 符合 output_schema 的字典 """ # 1. 参数校验（自动校验已在 CLI 层完成，此处做业务校验） city = input_data.get("city", "").strip() if not city: raise ValueError("city 参数不能为空") # 2. 构建 API 请求 base_url = os.getenv("OPENWEATHER_API_KEY", "https://api.openweathermap.org/data/2.5") api_key = os.getenv("OPENWEATHER_API_KEY") if not api_key: raise RuntimeError("缺少 OPENWEATHER_API_KEY 环境变量") # 获取当前天气 current_params = { "q": city, "appid": api_key, "units": input_data.get("units", "metric") } current_url = f"{base_url}/weather?{urlencode(current_params)}" try: # 使用 requests session 复用连接 session = requests.Session() session.headers.update({"User-Agent": "Codex-Skill/1.0"}) # 当前天气 current_resp = session.get(current_url, timeout=8) current_resp.raise_for_status() current_data = current_resp.json() # 预报天气（如果需要） forecast_data = None if input_data.get("days", 1) > 1: forecast_params = { "q": city, "appid": api_key, "units": input_data.get("units", "metric"), "cnt": min(16, input_data.get("days", 5)) } forecast_url = f"{base_url}/forecast?{urlencode(forecast_params)}" forecast_resp = session.get(forecast_url, timeout=8) forecast_resp.raise_for_status() forecast_data = forecast_resp.json() # 3. 结构化输出（严格遵循 output_schema） result = { "location": { "name": current_data["name"], "country": current_data["sys"]["country"], "timezone": current_data["timezone"] }, "current": { "temp_c": current_data["main"]["temp"], "condition": current_data["weather"][0]["description"], "humidity": current_data["main"]["humidity"], "wind_kph": current_data["wind"]["speed"] * 3.6 } } if forecast_data: # 解析 forecast 数据（OpenWeather 的 forecast 是每 3 小时一条，需聚合为每日） daily_forecast = {} for item in forecast_data["list"]: date = item["dt_txt"].split()[0] if date not in daily_forecast: daily_forecast[date] = { "maxtemp_c": item["main"]["temp_max"], "mintemp_c": item["main"]["temp_min"], "condition": item["weather"][0]["main"] } else: daily_forecast[date]["maxtemp_c"] = max( daily_forecast[date]["maxtemp_c"], item["main"]["temp_max"] ) daily_forecast[date]["mintemp_c"] = min( daily_forecast[date]["mintemp_c"], item["main"]["temp_min"] ) result["forecast"] = [ {"date": k, "day": v} for k, v in daily_forecast.items() ] return result except requests.exceptions.Timeout: raise TimeoutError("OpenWeather API 请求超时") except requests.exceptions.ConnectionError: raise ConnectionError("无法连接到 OpenWeather API") except requests.exceptions.HTTPError as e: if e.response.status_code == 404: raise ValueError(f"未找到城市: {city}") elif e.response.status_code == 401: raise PermissionError("OpenWeather API Key 无效") else: raise RuntimeError(f"API 错误: {e.response.status_code}") except KeyError as e: raise RuntimeError(f"API 响应格式异常，缺少字段: {e}") except Exception as e: raise RuntimeError(f"未知错误: {str(e)}")

3.3 测试驱动开发：不只是跑通，更要跑稳

codex test默认运行 pytest，但我们需要补充三类测试：

1. 单元测试（验证核心逻辑）：

# tests/test_weather.py import pytest from unittest.mock import patch, MagicMock from weather.main import execute class TestWeatherSkill: @patch('weather.main.requests.Session') def test_execute_success(self, mock_session): # Mock 成功响应 mock_resp = MagicMock() mock_resp.json.return_value = { "name": "Shanghai", "sys": {"country": "CN"}, "timezone": 28800, "main": {"temp": 23.4, "humidity": 65, "temp_max": 25.1, "temp_min": 21.2}, "weather": [{"description": "partly cloudy"}], "wind": {"speed": 3.2} } mock_session.return_value.get.return_value = mock_resp mock_session.return_value.get.return_value.status_code = 200 # 设置环境变量 import os os.environ["OPENWEATHER_API_KEY"] = "test-key" # 执行 result = execute({"city": "Shanghai"}) # 断言 assert result["location"]["name"] == "Shanghai" assert result["current"]["temp_c"] == 23.4 assert result["current"]["humidity"] == 65 def test_execute_missing_city(self): with pytest.raises(ValueError) as exc_info: execute({}) assert "city 参数不能为空" in str(exc_info.value) def test_execute_no_api_key(self): # 清除环境变量 import os os.environ.pop("OPENWEATHER_API_KEY", None) with pytest.raises(RuntimeError) as exc_info: execute({"city": "Beijing"}) assert "缺少 OPENWEATHER_API_KEY" in str(exc_info.value)

2. 集成测试（验证真实 API 调用）：

# tests/integration_test.py import pytest import os from weather.main import execute @pytest.mark.integration def test_weather_real_api(): # 仅在 CI 环境或手动指定时运行 if not os.getenv("RUN_INTEGRATION_TESTS"): pytest.skip("跳过集成测试") # 使用测试 API Key（OpenWeather 提供免费 tier） os.environ["OPENWEATHER_API_KEY"] = "YOUR_TEST_KEY" try: result = execute({"city": "Beijing", "days": 3}) assert "location" in result assert "current" in result assert len(result.get("forecast", [])) >= 2 except Exception as e: # 网络不稳定时允许失败，但记录日志 pytest.skip(f"集成测试跳过: {e}")

3. 性能与边界测试（验证鲁棒性）：

# tests/performance_test.py import time import pytest from weather.main import execute def test_weather_timeout_handling(): """测试超时处理""" start = time.time() try: # 传入一个故意超时的 mock（实际中用 httpx 的 timeout 控制） execute({"city": "very-long-city-name-that-does-not-exist" * 100}) except Exception as e: assert "超时" in str(e) or "Timeout" in str(e) end = time.time() assert (end - start) < 10.5 # 留 500ms 缓冲 def test_weather_long_city_name(): """测试长城市名处理""" long_city = "a" * 101 # 超过 maxLength with pytest.raises(ValueError): execute({"city": long_city})

运行测试：

# 运行单元测试（快速） codex test --mode=unit # 运行集成测试（需设置环境变量） export RUN_INTEGRATION_TESTS=1 codex test --mode=integration # 运行性能测试 codex test --mode=performance

3.4 构建、发布与部署：生产就绪的完整链路

构建可部署包：

# codex build 会做： # 1. 安装 requirements.txt 中所有依赖到隔离环境 # 2. 打包 main.py 和 skill.yaml 到单个 zip # 3. 生成 SHA256 校验和 # 4. 签名（需配置 GPG key） codex build --output=dist/weather-1.0.0.zip # 查看构建产物详情 codex inspect dist/weather-1.0.0.zip

发布到私有 registry：

# 先登录（registry 地址在 ~/.codex/config.yaml 中配置） codex login --registry=https://hub.internal.company.com # 发布（自动上传并生成版本索引） codex publish --registry=https://hub.internal.company.com \ --package=dist/weather-1.0.0.zip \ --tag=stable

在目标服务器部署：

# 登录目标环境 ssh prod-server # 安装 skill（自动处理依赖、创建 systemd service、设置 log rotation） codex install --registry=https://hub.internal.company.com \ --name=weather \ --version=1.0.0 \ --env=prod # 查看服务状态 systemctl status codex-weather # 查看实时日志 journalctl -u codex-weather -f

此时，skill 已作为独立服务运行，可通过 HTTP 或 gRPC 调用：

# HTTP 方式（适合前端或 curl 测试） curl -X POST http://localhost:8000/skill/weather \ -H "Content-Type: application/json" \ -d '{"city": "Shanghai", "units": "metric"}' # gRPC 方式（适合高性能后端调用） # protoc 生成 client，调用 Execute 方法

4. 常见问题与实战排错指南

4.1 “No API key for provider route” 类错误的根因分析

这类错误（如llm-deepseek: no api key for provider route "deepseek-official"）在日志中高频出现，但根源往往不在 skill 本身。我整理了 5 类典型场景及排查路径：

注意：所有环境变量必须在 skill 进程启动前注入。常见错误是只在 shell 中export，但 systemd service 启动时未继承。正确做法是在/etc/systemd/system/codex-weather.service中添加：

[Service] Environment="OPENWEATHER_API_KEY=your-real-key" Environment="NODE_ENV=production"

4.2 Slash Command 解析失败的 3 个隐蔽陷阱

Slash command 看似简单，但解析失败常因底层细节。以下是我在 12 个项目中踩过的坑：

陷阱 1：URL 编码污染用户输入/weather 北京，前端若直接encodeURIComponent整个字符串，会变成/weather%20%E5%8C%97%E4%BA%AC，后端解析时未 decode 就直接 split，导致city变成%E5%8C%97%E4%BA%AC。
✅ 正确做法：只对参数值 encode，命令本身不 encode。前端应：

const cmd = "/weather"; const args = ["北京"]; // 不 encode const fullCmd = `${cmd} ${args.map(a => encodeURIComponent(a)).join(" ")}`;

陷阱 2：空格处理歧义/translate en2zh hello world中，“hello world” 是一个参数还是两个？规范要求：用引号包裹多词参数。但很多 parser 未实现。
✅ 解决方案：在skill.yaml中声明arg_separator: " "，并在 parser 中实现引号感知：

import shlex # 正确解析：shlex.split("/translate en2zh 'hello world'") -> ['translate', 'en2zh', 'hello world']

陷阱 3：大小写敏感导致路由失败/WEATHER shanghai和/weather shanghai被视为不同命令。但 skill registry 通常按小写存储。
✅ 强制标准化：在 CLI 的 dispatch 层统一转小写：

command = raw_command.strip().split()[0].lower() # /WEATHER -> /weather

4.3 Performance 问题诊断：从 P95 延迟飙升说起

某次上线后，weatherskill 的 P95 延迟从 320ms 飙升到 2.1s。日志显示大量ConnectionError。排查过程如下：

1. 确认是否 DNS 问题：

   # 在 prod-server 上 time nslookup api.openweathermap.org # 结果：1200ms，正常应 <50ms → DNS 缓存失效

2. 检查 DNS 配置：

   cat /etc/resolv.conf # 发现 nameserver 是 8.8.8.8（被干扰） # 修复：改为公司内网 DNS echo "nameserver 10.0.0.1" | sudo tee /etc/resolv.conf

3. 验证连接池耗尽：

   # 查看 open file 数 lsof -i :443 | wc -l # 返回 1024，达到 ulimit ulimit -n # 显示 1024 # 修复：在 systemd service 中增加 # LimitNOFILE=65536

4. 最终根因：SSL 证书验证开销
   OpenWeather 的证书链很长，Python 默认验证耗时。添加verify=False会不安全，正确解法是：

   # 在 requests Session 中复用 SSL context import ssl from requests.adapters import HTTPAdapter from urllib3.util.ssl_ import create_urllib3_context class CustomHTTPAdapter(HTTPAdapter): def init_poolmanager(self, *args, **kwargs): context = create_urllib3_context() context.set_ciphers('DEFAULT@SECLEVEL=1') # 降级兼容老证书 kwargs['ssl_context'] = context return super().init_poolmanager(*args, **kwargs)

4.4 安全加固 checklist：生产环境必做 7 件事

1. 环境变量隔离：绝不将API_KEY写入代码或 git。使用.env.production文件，并在.gitignore中排除。
2. 最小权限原则：skill 的 Linux user 应为codex-weather（非 root），且只拥有/var/lib/codex/weather/目录权限。
3. 网络白名单：在skill.yaml中严格声明permissions.network，iptables 自动应用此策略。
4. 输入长度限制：在input_schema.maxLength中设合理上限（如城市名 ≤100 字符），防止 DoS。
5. 输出脱敏：skill 返回的output_schema中，敏感字段（如location.timezone）应标记"sensitive": true，registry 自动过滤。
6. 日志审计：所有 skill 调用必须记录user_id,skill_name,input_hash,duration_ms,status，留存 180 天。
7. 定期轮换密钥：用 HashiCorp Vault 管理OPENWEATHER_API_KEY，设置 90 天自动轮换，并在 skill 中实现热重载。

5. 生态扩展：如何让 skills 走出 CLI，融入更大系统

5.1 前端深度集成：从按钮到智能体验

skills 不该只在终端里用。我们用@codex/reactSDK 将其无缝注入前端：

// React 组件中 import