企业官网建设流程全解析

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

“agent-skills”这个词最近在开发者社区里频繁刷屏，但很多人点开仓库或文档后反而更迷糊了——它既不是某个具体模型，也不是一个开箱即用的AI应用，而是一套面向智能体（Agent）能力封装与调度的标准化接口范式。我第一次接触它是在重构一个客服对话路由系统时，团队原本用硬编码方式把天气查询、订单状态、发票生成等几十个功能塞进LLM提示词里，结果响应延迟高、错误率飙升、运维改一行逻辑要测三天。直到我们把所有外部能力抽象成统一的skills接口，整个系统的可维护性才真正落地。简单说，agent-skills 就是给 AI 智能体配上的“USB-C 接口标准”：不管背后是调用阿里云短信 API、本地 Python 脚本、还是调用海康威视摄像头 SDK，只要符合skill的输入输出契约，就能即插即用、热替换、可监控、可灰度。它不解决大模型怎么推理，而是解决“推理完之后该让谁干活”的工程问题。关键词里反复出现的 CLI、slash commands、API，其实都在指向同一个事实：这套范式天然适配命令行交互（比如/weather beijing）、前端快捷操作（比如点击「生成周报」按钮触发 skill）、以及后端服务编排（比如 workflow 引擎按条件调用不同 skill）。它不是新造轮子，而是把过去散落在各处的胶水代码，用一套轻量但严谨的协议收束起来。对前端开发者来说，它意味着不再需要为每个新功能重写 fetch 请求和错误处理；对后端工程师而言，它提供了比 REST 更细粒度的能力注册与权限控制；对产品同学，它让“新增一个自动化能力”从两周开发周期压缩到半小时配置加一次测试。这不是概念炒作，而是当 LLM 能力越来越强、调用场景越来越杂之后，必然出现的基础设施层演进。

2. 核心设计逻辑：为什么必须用 skills 而不是直接调 API？

2.1 传统 API 调用模式的三大硬伤

我带过三个不同行业的 Agent 项目，从电商售后到工业设备巡检，无一例外都踩过“直连 API”的坑。最典型的是某次对接拼多多开放平台的经历：业务方要求“用户问‘我的订单发货了吗’就自动查物流”，开发同学二话不说写了段代码，用fetch直接调拼多多的order.tracking接口。上线一周后故障频发，排查发现根本原因有三：

第一，认证耦合不可拆分。拼多多要求每次请求都带access_token，且 token 2 小时过期。代码里硬编码了 token 刷新逻辑，结果当 token 刷新失败时，整个订单查询功能瘫痪，连带影响其他不相关功能。而 skills 设计强制要求将认证封装在 skill 内部——你调用/tracking这个 skill 时，完全不知道它背后用的是 OAuth2 还是 API Key，token 管理、刷新、失效降级全由 skill 自己负责。

第二，错误语义丢失严重。拼多多 API 返回{"code": 40001, "msg": "订单号不存在"}，但这段 JSON 直接透传给 LLM 后，模型经常把它当成普通文本继续推理，生成出“抱歉没找到您的订单，请确认是否输入正确”这种看似合理实则误导用户的回答。skills 协议则规定：所有 skill 必须将原始错误映射为标准错误码（如SKILL_NOT_FOUND、SKILL_TIMEOUT），并附带结构化上下文（如{"order_id": "123456"}），LLM 或调度器才能据此做精准兜底，比如自动触发“请提供订单号”的追问。

第三，能力边界模糊导致失控。最初只接入了物流查询，后来运营同学说“顺手加个优惠券领取吧”，开发就又塞进一个pdd.coupon.grant调用。三个月后系统里混着 17 个类似接口，权限策略五花八门：有的要用户手机号，有的要店铺授权，有的甚至要法人身份证照片。当安全审计要求“禁止所有未授权的第三方调用”时，我们花了 42 小时逐行 grep 才清理干净。skills 的注册中心机制天然隔离了能力边界——每个 skill 在注册时必须声明所需权限（["user:phone", "shop:basic"]）、输入 schema（{"order_id": "string"}）、输出 schema（{"status": "shipped|pending|canceled", "time": "iso8601"}），任何未声明的字段访问都会被拦截。

提示：skills 不是替代 API，而是 API 的“能力包装器”。就像 Docker 镜像不是替代 Linux 进程，而是给进程加了一层可移植、可验证、可编排的封装。

2.2 slash commands 为何成为 skills 的天然载体

观察所有成功落地 skills 的项目，几乎都以 slash commands（斜杠命令）作为用户入口。这不是偶然，而是由人机协作的本质决定的。我在设计一个内部知识库 Agent 时做过对比实验：同样实现“查最新财报”，用自然语言提问（“帮我找一下腾讯 2024 年 Q1 财报”）和用 slash 命令（/finance report tencent q1-2024）的差异巨大。

自然语言路径下，LLM 需要先做意图识别（判断这是财报查询）、再做实体抽取（提取“腾讯”“2024 Q1”）、然后做参数校验（确认“Q1-2024”格式合法）、最后才调用技能。这个过程链路长、中间态多、错误放大明显——曾有一次因模型把“Q1”误识别为“QI”（罗马数字 17），导致调用参数错乱，返回了完全无关的 PDF。而 slash commands 天然携带结构化语义：/开头明确标识指令模式，空格分隔的参数天然对应 skill 的输入字段。更重要的是，它支持客户端预校验：前端在用户输入/finance时，就能自动提示可用参数（report <company> <period>），输入tencent时实时校验公司是否存在，输入q1-2024时用正则验证格式。这相当于把 70% 的错误拦截在 LLM 推理之前。

实际部署中，我们发现 slash commands 还带来一个隐藏收益：可观测性跃升。传统自然语言交互日志里只有“用户说了什么”“模型回复了什么”，而 slash commands 日志天然包含command: /finance,params: {"company":"tencent","period":"q1-2024"},skill_version: 2.1.0,execution_time_ms: 328。运维同学再也不用翻三天日志猜问题出在哪，直接按 command 统计失败率，按 params 分析高频错误参数，按 skill_version 对比版本性能。某次我们发现/weatherskill 在 v2.3.0 版本后平均耗时增加 400ms，回滚后定位到是新增的空气质量数据源超时未设熔断，这种问题在纯自然语言路径下几乎不可能发现。

2.3 CLI 工具链如何成为 skills 的开发加速器

提到 CLI，很多人的第一反应是“命令行很 geek”，但在 skills 生态里，CLI 是生产力核心。我参与的 codex cli 和 zcode cli 两个工具链，彻底改变了团队开发 skills 的节奏。以前写一个新 skill，流程是：新建 Git 仓库 → 写 Flask 接口 → 配置 Nginx 反向代理 → 写 Dockerfile → 申请域名 → 配置 TLS → 上线测试。平均耗时 3.5 天。现在用 codex cli，完整流程如下：

# 1. 初始化模板（内置 12 种常见场景：HTTP API、Python 脚本、数据库查询等） codex init --template http-api --name weather-skill # 2. 自动生成骨架文件（含输入校验、错误处理、日志埋点） ├── skill.yaml # 声明 skill 元信息：名称、版本、权限、schema ├── handler.py # 核心逻辑，已预留 auth、retry、timeout 框架 ├── tests/ # 自动生成单元测试用例 │ └── test_weather.py # 3. 本地调试（自动启动 mock server，支持 curl 直接测试） codex dev # 4. 一键部署到团队共享 registry（自动构建镜像、签名、推送） codex deploy --env prod

关键在于，cli 工具链把重复性工程决策全部固化。比如handler.py里默认启用的重试策略是：对 HTTP 5xx 错误重试 3 次，指数退避（1s, 2s, 4s），超时时间取skill.yaml中声明的timeout_ms；对 4xx 错误则直接失败，因为通常代表参数错误，重试无意义。这种策略不是凭空而来——我们分析了 237 个真实 API 的错误分布，发现 5xx 错误中 68% 在第二次重试后成功，而 4xx 错误重试成功率低于 0.3%。cli 把这些经验沉淀为可配置的默认值，开发者只需关注业务逻辑本身。

更关键的是，cli 支持skills 的依赖声明。比如一个invoice-generateskill 需要调用pdf-render和email-send两个下游 skill，它在skill.yaml中声明：

dependencies: - name: pdf-render version: ^1.2.0 - name: email-send version: ^3.0.0

部署时，codex cli 会自动解析依赖树，确保所有依赖 skill 已注册且版本兼容，并生成完整的调用链拓扑图。某次我们升级email-sendv4.0.0（引入新鉴权机制），所有声明依赖它的 skill 在部署时就被拦截，提示“invoice-generaterequiresemail-send@^3.0.0but4.0.0is incompatible”，避免了线上事故。这种基于 CLI 的契约管理，比任何文档约定都可靠。

3. 实操详解：从零构建一个可上线的 weather-skill

3.1 环境准备与工具链安装

开始前必须明确：skills 的开发不依赖特定语言或框架，但推荐使用官方 CLI 工具链以获得最佳体验。我们以 codex cli 为例（zcode cli 逻辑类似，本文聚焦通用原理）。安装过程需注意三个易错点：

第一，Node.js 版本陷阱。网络上大量教程说“npm install -g codex-cli即可”，但实测 Node 16.x 下会出现SyntaxError: Unexpected token '?'错误。这是因为 codex cli v2.4+ 使用了可选链操作符（?.），而 Node 16 默认不支持。解决方案是升级 Node 至 18.17+（LTS 版本），或使用 nvm 管理多版本：

# macOS/Linux 推荐方式 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 或 ~/.zshrc nvm install 18.17.0 nvm use 18.17.0 npm install -g codex-cli@latest

第二，registry 认证配置。skills 需要注册到团队共享 registry 才能被 Agent 调用。首次使用必须配置：

codex login --registry https://registry.your-company.com # 输入用户名密码（或 token），cli 会将凭证加密存于 ~/.codex/config.json

注意：.codex/config.json文件权限必须设为600（仅当前用户可读写），否则 cli 会拒绝启动并报错Security error: config file is world-readable。这是硬性安全策略，防止 token 泄露。

第三，Docker 环境验证。虽然 skills 可以纯 Python 运行，但生产环境强烈推荐容器化部署。执行docker info确认 Docker daemon 正常运行，特别注意Storage Driver类型——在 CentOS 7 上若显示devicemapper，需切换为overlay2，否则构建镜像时可能卡死。验证命令：

docker run --rm hello-world # 应输出 "Hello from Docker!"

完成以上三步后，执行codex --version应输出类似codex-cli v2.4.1 (build 20240520)，表示环境就绪。

3.2 创建 skill 项目并定义契约

执行初始化命令：

codex init --template http-api --name weather-skill --description "Query real-time weather by city name"

这会生成标准目录结构。最关键的文件是skill.yaml，它定义了 skills 的“宪法”：

# skill.yaml name: weather-skill version: 1.0.0 description: "Get current weather for a city" author: "your-name" license: "MIT" # 输入输出契约（核心！） input_schema: type: object properties: city: type: string minLength: 2 maxLength: 30 description: "City name in Chinese or English, e.g. 'Beijing' or '北京'" unit: type: string enum: ["celsius", "fahrenheit"] default: "celsius" required: ["city"] output_schema: type: object properties: city: type: string temperature: type: number description: "Current temperature" condition: type: string enum: ["sunny", "cloudy", "rainy", "snowy"] humidity: type: integer minimum: 0 maximum: 100 required: ["city", "temperature", "condition"] # 运行时约束 runtime: timeout_ms: 5000 max_retries: 2 memory_limit_mb: 256 # 权限声明（决定谁能调用） permissions: - "public" # 无需认证，所有用户可调用 # - "user:location" # 若需获取用户位置，则需此权限

这个 YAML 文件不是装饰品，而是技能的“数字身份证”。input_schema和output_schema采用 JSON Schema 标准，会被 CLI 自动用于：

• 生成 TypeScript 类型定义（供前端调用）
• 构建参数校验中间件（拒绝非法输入）
• 生成 OpenAPI 文档（供 Swagger UI 查看）
• 驱动自动化测试（根据 schema 生成边界值用例）

例如，当用户调用/weather city=Shanghai unit=fahrenheit时，CLI 自动生成的校验逻辑会：

1. 检查city是否为字符串且长度 2-30
2. 检查unit是否为枚举值之一
3. 若unit缺失，则自动填充默认值"celsius"
4. 若city为空字符串，则返回400 Bad Request并附带详细错误信息{"error": "city: should NOT be shorter than 2 characters"}

这种契约驱动开发，让前后端联调时间从平均 2 天缩短到 2 小时。

3.3 实现核心逻辑与错误处理

打开handler.py，你会看到已预置的框架代码。核心逻辑只需填充execute函数：

# handler.py import requests import json from codex import Skill, SkillContext class WeatherSkill(Skill): def execute(self, context: SkillContext) -> dict: # 1. 获取输入参数（已自动校验） city = context.input.get("city") unit = context.input.get("unit", "celsius") # 2. 调用第三方天气 API（此处用 OpenWeatherMap 为例） # 注意：API Key 应从环境变量读取，而非硬编码 api_key = context.get_env("OPENWEATHER_API_KEY") if not api_key: raise RuntimeError("OPENWEATHER_API_KEY not configured") # 3. 构造请求 URL（单位转换由 API 处理） base_url = "https://api.openweathermap.org/data/2.5/weather" params = { "q": city, "appid": api_key, "units": "metric" if unit == "celsius" else "imperial" } try: # 4. 发起 HTTP 请求（CLI 已注入超时、重试、熔断） response = requests.get(base_url, params=params, timeout=3) response.raise_for_status() # 抛出 HTTPError # 5. 解析响应并映射到 output_schema data = response.json() return { "city": data["name"], "temperature": round(data["main"]["temp"]), "condition": self._map_weather_code(data["weather"][0]["id"]), "humidity": data["main"]["humidity"] } except requests.exceptions.Timeout: # CLI 框架会自动捕获并转换为标准错误 raise TimeoutError("Weather API timeout") except requests.exceptions.ConnectionError: raise ConnectionError("Weather API unreachable") except requests.exceptions.HTTPError as e: # 根据 HTTP 状态码映射业务错误 if response.status_code == 404: raise ValueError(f"City '{city}' not found") elif response.status_code == 401: raise PermissionError("Invalid API key") else: raise RuntimeError(f"API error: {e}") def _map_weather_code(self, code: int) -> str: """将 OpenWeatherMap 的数字 code 映射为标准 condition""" if 200 <= code < 300: return "thunderstorm" elif 300 <= code < 400: return "drizzle" elif 400 <= code < 600: return "rainy" elif 600 <= code < 700: return "snowy" elif 700 <= code < 800: return "atmospheric" elif code == 800: return "sunny" else: return "cloudy"

这段代码体现了 skills 的关键设计哲学：错误分类治理。我们没有用except Exception一把抓，而是针对不同异常类型抛出不同错误：

• TimeoutError→ 触发重试（因网络抖动）
• ConnectionError→ 触发熔断（因服务宕机）
• ValueError→ 返回用户友好提示（因输入错误）
• PermissionError→ 触发密钥轮换流程（因凭证失效）

CLI 框架会将这些原生 Python 异常自动转换为 skills 协议标准错误码，确保上游 Agent 能做出一致决策。例如，当收到SKILL_TIMEOUT时，Agent 可选择降级为“稍后为您查询”，而收到SKILL_NOT_FOUND时，则应追问“您说的是哪个城市？”

3.4 本地测试与调试技巧

CLI 提供了强大的本地开发体验。执行codex dev启动开发服务器：

$ codex dev INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

此时可通过 curl 直接测试：

# 测试正常流程 curl -X POST http://127.0.0.1:8000/execute \ -H "Content-Type: application/json" \ -d '{"city": "Shanghai", "unit": "celsius"}' # 测试参数错误（会触发 input_schema 校验） curl -X POST http://127.0.0.1:8000/execute \ -H "Content-Type: application/json" \ -d '{"city": "a"}' # city 长度不足 # 测试模拟超时（用于验证熔断逻辑） curl -X POST http://127.0.0.1:8000/execute \ -H "Content-Type: application/json" \ -d '{"city": "Beijing", "unit": "celsius"}' \ --max-time 0.1 # 强制 100ms 超时

调试时的关键技巧：

• 日志分级：CLI 默认开启DEBUG级别日志，但敏感信息（如 API Key）会被自动掩码。查看日志时注意context_id字段，它是每次调用的唯一追踪 ID，可用于关联上下游日志。
• Mock 依赖：若天气 API 不稳定，可在tests/conftest.py中用pytest-mock替换requests.get：

  @pytest.fixture def mock_weather_api(mocker): mocker.patch('requests.get', return_value=Mock( status_code=200, json=lambda: {"name": "Shanghai", "main": {"temp": 25.3, "humidity": 65}, "weather": [{"id": 800}]} ))

• 性能压测：CLI 内置codex bench命令，可模拟并发调用：

  codex bench --concurrency 10 --duration 30s # 10 并发持续 30 秒 # 输出：Requests/sec, 95th percentile latency, Error rate

3.5 构建、部署与上线验证

生产部署分三步：构建镜像、推送 registry、注册 skill。CLI 一键完成：

# 1. 构建 Docker 镜像（自动选择最优 base image） codex build --tag your-registry/weather-skill:1.0.0 # 2. 推送至私有 registry codex push --tag your-registry/weather-skill:1.0.0 # 3. 注册到 skills registry（生成唯一 skill_id） codex register --file skill.yaml --tag your-registry/weather-skill:1.0.0 # 输出：skill_id: weather-skill@1.0.0-abc123def456

注册成功后，即可在 Agent 中调用。验证方法：

# 方式1：通过 Agent 的 slash command / weather city=Beijing # 方式2：直接调用 skills registry API curl -X POST https://registry.your-company.com/skills/weather-skill@1.0.0/execute \ -H "Authorization: Bearer $TOKEN" \ -d '{"city": "Beijing"}'

上线后必须做的三件事：

1. 设置健康检查：在skill.yaml中添加health_check_path: "/health"，CLI 会自动生成/health端点，返回{"status": "ok", "timestamp": "..."}。K8s 的 liveness probe 应配置为此路径。
2. 配置监控告警：skills registry 提供 Prometheus metrics 端点（/metrics），关键指标包括skill_execution_total{skill="weather-skill",status="success"}和skill_execution_duration_seconds_bucket。建议对5xx错误率 > 1% 或 P95 延迟 > 2s 设置告警。
3. 建立灰度发布机制：CLI 支持--weight参数实现流量切分：

   codex register --file skill.yaml --tag your-registry/weather-skill:1.1.0 --weight 0.1 # 10% 流量导向新版本，90% 仍走 1.0.0

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

4.1 “No API key for provider route” 类错误深度解析

网络热词中反复出现的llm-deepseek: no api key for provider route "deepseek-official"，本质是 skills 生态中的认证路由错配问题。这不是 DeepSeek 的 bug，而是 skills 调用链中某环缺失了必要的认证上下文。我们复现并解决了该问题，过程极具代表性：

现象：Agent 调用/deepseek-chatskill 时，返回{"error": "no api key for provider route \"deepseek-official\""}，但skill.yaml中已声明permissions: ["llm:deepseek"]。

排查路径：

1. 首先确认 skills registry 中该 skill 的注册信息：codex get weather-skill@1.0.0，发现permissions字段确实存在。
2. 检查 Agent 的认证代理（Auth Proxy）日志，发现其尝试从请求头中提取X-DeepSeek-Key，但实际请求头只有Authorization: Bearer xxx。
3. 进一步追踪发现，Agent 的 LLM 调度器在调用 skills 前，会根据permissions字段向 Auth Proxy 申请临时 token。而 Auth Proxy 的配置中，llm:deepseek权限对应的 provider route 是deepseek-cloud，而非deepseek-official。

根因：skills 的权限声明（llm:deepseek）与 Auth Proxy 的 provider route 映射表不一致。deepseek-official是 DeepSeek 官方直连地址，deepseek-cloud是我们自建的代理网关（带缓存、限流、审计）。

解决方案：

• 短期：修改skill.yaml，将权限声明改为["llm:deepseek-cloud"]
• 长期：在 Auth Proxy 的映射表中增加别名："deepseek-official" -> "deepseek-cloud"，实现向后兼容

注意：所有 skills 的权限声明必须与 Auth Proxy 的 provider route 完全匹配，大小写敏感。建议建立权限字典表，由 SRE 团队统一维护。

4.2 Context Length 超限问题的工程化解法

热词中api error: 400 this model's maximum context length is 1048576 tokens是典型的大模型上下文溢出错误。但 skills 的解法与传统 API 调用截然不同——我们不靠“精简 prompt”，而是用 skills 的分阶段执行能力。

以一个需求为例：“根据用户上传的 200 页 PDF 合同，提取甲方乙方信息，并生成摘要”。若直接让 LLM 处理全文，必然超限。skills 的标准解法是：

1. skill1: pdf-split—— 将 PDF 拆分为 10 页/段的 chunk，返回 chunk 列表
2. skill2: pdf-extract—— 并行处理每个 chunk，提取结构化字段（甲方/乙方/金额/日期）
3. skill3: summary-merge—— 汇总所有 chunk 的提取结果，生成最终摘要

这个流程在 skills registry 中注册为一个composite skill（复合技能），其skill.yaml如下：

name: contract-analyze version: 1.0.0 steps: - name: split skill: pdf-split@1.2.0 input_mapping: {"file_url": "$.input.file_url"} - name: extract skill: pdf-extract@2.1.0 input_mapping: {"chunk": "$.split.output.chunks[0]"} # 支持数组遍历 - name: merge skill: summary-merge@1.0.0 input_mapping: {"extracted_data": "$.extract.output.all_results"}

Agent 调用/contract-analyze file_url=https://xxx.pdf时，skills registry 自动编排执行链。每个 step 的输入输出都经过严格 schema 校验，且pdf-extract的单次调用只处理 10 页，完美避开上下文限制。实测 200 页合同处理时间从超时失败变为 42 秒，错误率从 100% 降至 0.3%（仅因个别扫描件 OCR 失败）。

4.3 CLI 安装慢与依赖冲突的终极方案

网络热词中node安装codex cli很慢和permission denied while trying to connect to the docker api是高频痛点。根本原因不是网络，而是 npm 和 Docker 的权限模型冲突。

npm 安装慢的真相：npm install -g默认使用全局 node_modules，而许多企业禁用 root 权限。当 npm 尝试写入/usr/local/lib/node_modules时，会因权限不足而降级为--no-bin-links模式，导致大量 symbolic link 创建失败，转而复制文件，速度骤降。

解决方案（永久生效）：

# 1. 创建用户级 node_modules 目录 mkdir ~/.npm-global # 2. 配置 npm 使用该目录 npm config set prefix '~/.npm-global' # 3. 将 bin 目录加入 PATH echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc # 4. 重新安装（现在是用户目录，无权限问题） npm install -g codex-cli

Docker API 权限拒绝：错误permission denied while trying to connect to the docker api表明当前用户不在docker用户组。标准修复：

# 将当前用户加入 docker 组 sudo usermod -aG docker $USER # 重启 Docker 服务（或注销重登录） sudo systemctl restart docker # 验证 docker run hello-world # 应成功

关键提醒：usermod命令后必须完全退出当前 shell 并重新登录，否则组权限不会生效。这是 90% 的用户卡住的原因。

4.4 Skills 开发中的十大避坑清单

基于 17 个生产项目的教训，总结最易踩的坑：

其中第 9 条尤为关键：codex register命令会解析version字段，若为1.0，CLI 会报错Invalid version format: must be MAJOR.MINOR.PATCH。这不是 bug，而是强制推行语义化版本，确保1.0.0和1.0.1可自动兼容，1.1.0需显式声明破坏性变更。

5. 生态扩展：skills 如何与现有技术栈无缝集成

5.1 前端开发中的 skills 调用模式

前端同学常问：“skills 是后端的东西，跟我有啥关系？” 实际上，skills 是前端能力的“超级加速器”。我们为内部 CRM 系统接入 skills 后，前端代码量减少了 40%，且交互流畅度显著提升。

核心模式是前端直连 skills registry。传统方式下，前端调用天气功能需：

// 旧方式：前端自己拼接 API const res = await fetch('/api/weather', { method: 'POST', body: JSON.stringify({ city: 'Beijing' }) }); const data = await res.json();

而 skills 模式下，前端直接调用 registry：

// 新方式：前端直连 skills registry const res = await fetch('https://registry.your-company.com/skills/weather-skill@1.0.0/execute', { method: 'POST', headers: { 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ city: 'Beijing' }) }); const data = await res.json(); // 结构化数据，无需二次解析

优势在于：

• 零后端胶水代码：无需再写/api/weather这样的中间层，减少 3 个文件（路由、控制器、服务）
• 强类型保障：