@x-otto/plugin-weather 0.1.0-alpha.0

package/plugin.ts

@@ -0,0 +1,52 @@
+/**
+ * plugin.ts —— plugin-weather 代码式插件入口（RFC-105 D4 tools 轴）。
+ *
+ * 单一工具 `get_weather`：经 Open-Meteo 免费 API（geocoding + forecast，无需 API key）
+ * 拿城市当前天气 + 未来 3 天预报，`details` 字段携带结构化数据供 `renderers/weather.ts`
+ * 消费（RFC-105 D6 渲染器型：`matcher.toolName='get_weather'` 接管该工具结果的终端展示，
+ * 见 otto-plugin.json 的 `contributes.renderers`）。
+ *
+ * 为什么不用 a2uiComponents 轴（终局 review endgame-2026-07-23 补充术语澄清——`a2uiComponents`
+ * 与下方 `contributes.a2uiRenderers`（见 extensions/plugin-deploy-kit 的 RFC-210 D5 用法）是
+ * 两条不同的贡献点，本节讨论的是前者）：a2ui 组件由模型输出的 `a2ui` 内容块触发渲染，但当前
+ * 协议层（`@x-otto/interchange` message.ts）的 `AssistantMessage.content`/`ToolResultMessage.content`
+ * 均不含 `A2uiContent`——只有 `UserMessage.content` 支持，意味着工具结果无法产出 a2ui 块
+ * 触发渲染（无真实生产者）。`contributes.renderers` 轴（按 `matcher` 接管 `tool_result`
+ * 消息渲染）今天完整可用，且语义上更贴切"格式化某个工具结果的展示方式"这个场景。若未来
+ * 协议层扩展 `ToolResultMessage.content` 支持 `A2uiContent`，本渲染器可迁移为
+ * `contributes.a2uiRenderers`（对齐 plugin-deploy-kit 的 `get_deploy_status` 范式）。
+ */
+import { definePlugin } from '@x-otto/plugin'
+import { fetchCurrentWeatherAndForecast } from './src/open-meteo-client'
+import { weatherToolParamsSchema, type WeatherToolParams } from './src/schema'
+
+export default definePlugin(() => ({
+  tools: [
+    {
+      name: 'get_weather',
+      description:
+        'Get the current weather and 3-day forecast for a city. Uses Open-Meteo (no API key required).',
+      parameters: weatherToolParamsSchema,
+      async execute(args: unknown) {
+        const { city } = args as WeatherToolParams
+        const data = await fetchCurrentWeatherAndForecast(city)
+        if (!data) {
+          return {
+            content: [{ type: 'text', text: `City not found: "${city}"` }],
+            isError: true,
+          }
+        }
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `${data.city}: ${data.current.temperature}°C, ${data.current.description}`,
+            },
+          ],
+          // details 携带结构化数据，供 renderers/weather.ts 渲染函数消费（不经过文本解析）。
+          details: data,
+        }
+      },
+    },
+  ],
+}))

package/src/open-meteo-client.ts

@@ -0,0 +1,108 @@
+/**
+ * open-meteo-client.ts —— Open-Meteo API 客户端（geocoding + forecast，免费、无需 API key）。
+ * 两次请求：① geocoding 把城市名解析为经纬度；② forecast 用经纬度拿当前天气 + 3 天预报。
+ * 网络/解析失败一律返回 `null`（fail-soft，由 plugin.ts 转成 `isError:true` 的 ToolResult，
+ * 不抛异常——工具执行层的既有约定，见 `@x-otto/interchange AgentTool.execute` 契约）。
+ */
+import { describeWeatherCode } from './weather-codes'
+import type { WeatherData } from './types'
+
+const GEOCODING_URL = 'https://geocoding-api.open-meteo.com/v1/search'
+const FORECAST_URL = 'https://api.open-meteo.com/v1/forecast'
+const REQUEST_TIMEOUT_MS = 10_000
+
+interface GeocodingResult {
+  latitude: number
+  longitude: number
+  name: string
+  country?: string
+}
+
+async function geocodeCity(city: string, signal: AbortSignal): Promise<GeocodingResult | null> {
+  const url = new URL(GEOCODING_URL)
+  url.searchParams.set('name', city)
+  url.searchParams.set('count', '1')
+  url.searchParams.set('language', 'en')
+  url.searchParams.set('format', 'json')
+
+  const res = await fetch(url, { signal })
+  if (!res.ok) return null
+  const data = (await res.json()) as { results?: GeocodingResult[] }
+  return data.results?.[0] ?? null
+}
+
+interface ForecastResponse {
+  current?: {
+    temperature_2m: number
+    weather_code: number
+    wind_speed_10m: number
+    relative_humidity_2m: number
+  }
+  daily?: {
+    time: string[]
+    temperature_2m_max: number[]
+    temperature_2m_min: number[]
+    weather_code: number[]
+  }
+}
+
+async function fetchForecast(
+  latitude: number,
+  longitude: number,
+  signal: AbortSignal,
+): Promise<ForecastResponse | null> {
+  const url = new URL(FORECAST_URL)
+  url.searchParams.set('latitude', String(latitude))
+  url.searchParams.set('longitude', String(longitude))
+  url.searchParams.set('current', 'temperature_2m,weather_code,wind_speed_10m,relative_humidity_2m')
+  url.searchParams.set('daily', 'temperature_2m_max,temperature_2m_min,weather_code')
+  url.searchParams.set('timezone', 'auto')
+  url.searchParams.set('forecast_days', '3')
+
+  const res = await fetch(url, { signal })
+  if (!res.ok) return null
+  return (await res.json()) as ForecastResponse
+}
+
+/**
+ * 城市名 → 天气数据。城市未找到 / 网络失败 / 响应结构不符 一律返回 `null`（fail-soft）。
+ */
+export async function fetchCurrentWeatherAndForecast(city: string): Promise<WeatherData | null> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
+  try {
+    const location = await geocodeCity(city, controller.signal)
+    if (!location) return null
+
+    const forecast = await fetchForecast(location.latitude, location.longitude, controller.signal)
+    if (!forecast?.current || !forecast.daily) return null
+
+    const currentInfo = describeWeatherCode(forecast.current.weather_code)
+
+    return {
+      city: location.name,
+      country: location.country,
+      current: {
+        temperature: Math.round(forecast.current.temperature_2m * 10) / 10,
+        humidity: forecast.current.relative_humidity_2m,
+        windSpeed: forecast.current.wind_speed_10m,
+        description: currentInfo.description,
+        icon: currentInfo.icon,
+      },
+      forecast: forecast.daily.time.map((date, i) => {
+        const info = describeWeatherCode(forecast.daily!.weather_code[i] ?? -1)
+        return {
+          date,
+          tempMax: Math.round((forecast.daily!.temperature_2m_max[i] ?? 0) * 10) / 10,
+          tempMin: Math.round((forecast.daily!.temperature_2m_min[i] ?? 0) * 10) / 10,
+          description: info.description,
+          icon: info.icon,
+        }
+      }),
+    }
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timeout)
+  }
+}

package/src/schema.ts

@@ -0,0 +1,17 @@
+/**
+ * schema.ts —— `get_weather` 工具参数 schema（`PluginTool.parameters` 只要求 `safeParse`
+ * 接口，zod schema 天然兼容，装载器不下沉具体协议类型）。
+ */
+import { z } from 'zod'
+
+export const weatherToolParamsSchema = z.object({
+  // max(200)：真实城市名远短于此（已知最长地名约 85 字符），上限只为防御纵深——
+  // 拦截异常/失控模型输出的超长字符串直接拼进 geocoding 请求 URL（独立审核 R3 发现）。
+  city: z
+    .string()
+    .min(1)
+    .max(200)
+    .describe('City name to look up weather for, e.g. "Beijing" or "Tokyo"'),
+})
+
+export type WeatherToolParams = z.infer<typeof weatherToolParamsSchema>

package/src/types.ts

@@ -0,0 +1,27 @@
+/**
+ * types.ts —— get_weather 工具 `details` 字段的结构化数据形状（工具 execute 产出 →
+ * renderers/weather.ts 消费，两侧共享同一份类型，`entry` 编译产物是独立文件，靠此接口
+ * 保证字段契约一致，不依赖运行时校验）。
+ */
+export interface DailyForecast {
+  /** ISO 日期（YYYY-MM-DD）。 */
+  date: string
+  tempMax: number
+  tempMin: number
+  description: string
+  icon: string
+}
+
+export interface WeatherData {
+  city: string
+  country?: string
+  current: {
+    temperature: number
+    humidity: number
+    windSpeed: number
+    description: string
+    icon: string
+  }
+  /** 未来 3 天预报（含当天），按日期升序。 */
+  forecast: DailyForecast[]
+}

package/src/weather-codes.ts

@@ -0,0 +1,45 @@
+/**
+ * weather-codes.ts —— WMO weather interpretation codes → 人类可读描述 + emoji 图标。
+ * 数据来源：Open-Meteo API 文档（WMO Weather interpretation codes (WW)）。
+ */
+export interface WeatherCodeInfo {
+  description: string
+  icon: string
+}
+
+const WMO_CODE_TABLE: Record<number, WeatherCodeInfo> = {
+  0: { description: 'Clear sky', icon: '☀️' },
+  1: { description: 'Mainly clear', icon: '🌤️' },
+  2: { description: 'Partly cloudy', icon: '⛅' },
+  3: { description: 'Overcast', icon: '☁️' },
+  45: { description: 'Fog', icon: '🌫️' },
+  48: { description: 'Depositing rime fog', icon: '🌫️' },
+  51: { description: 'Light drizzle', icon: '🌦️' },
+  53: { description: 'Moderate drizzle', icon: '🌦️' },
+  55: { description: 'Dense drizzle', icon: '🌧️' },
+  56: { description: 'Light freezing drizzle', icon: '🌧️' },
+  57: { description: 'Dense freezing drizzle', icon: '🌧️' },
+  61: { description: 'Slight rain', icon: '🌧️' },
+  63: { description: 'Moderate rain', icon: '🌧️' },
+  65: { description: 'Heavy rain', icon: '🌧️' },
+  66: { description: 'Light freezing rain', icon: '🌧️' },
+  67: { description: 'Heavy freezing rain', icon: '🌧️' },
+  71: { description: 'Slight snow fall', icon: '🌨️' },
+  73: { description: 'Moderate snow fall', icon: '🌨️' },
+  75: { description: 'Heavy snow fall', icon: '❄️' },
+  77: { description: 'Snow grains', icon: '❄️' },
+  80: { description: 'Slight rain showers', icon: '🌦️' },
+  81: { description: 'Moderate rain showers', icon: '🌧️' },
+  82: { description: 'Violent rain showers', icon: '⛈️' },
+  85: { description: 'Slight snow showers', icon: '🌨️' },
+  86: { description: 'Heavy snow showers', icon: '❄️' },
+  95: { description: 'Thunderstorm', icon: '⛈️' },
+  96: { description: 'Thunderstorm with slight hail', icon: '⛈️' },
+  99: { description: 'Thunderstorm with heavy hail', icon: '⛈️' },
+}
+
+const UNKNOWN_CODE_INFO: WeatherCodeInfo = { description: 'Unknown', icon: '❔' }
+
+export function describeWeatherCode(code: number): WeatherCodeInfo {
+  return WMO_CODE_TABLE[code] ?? UNKNOWN_CODE_INFO
+}