alibabacloud-iqs-weather-query

IQS 天气查询 - 7 天天气预报

使用阿里云 IQS 网页搜索（UnifiedSearch）和页面读取（ReadPageBasic）功能，查询任意城市的 7 天天气预报。

底层服务： alibabacloud-iqs-search

混合解析策略：

• 已知网站（weather.cma.cn、weather.com.cn）：专用解析器提取结构化 JSON → parseMode: "structured"
• 未知网站：ReadPage 提取主要内容（readabilityMode: article），返回带有提取提示的原始文本 → parseMode: "raw"，Agent（大模型）直接解读

输出字段	描述
parseMode	"structured"（已解析的 JSON）或 "raw"（供 Agent 解读的文本）
weather	天气状况（晴、多云、雨等）
temperature	温度范围
windSpeed	风速／风力等级
windDirection	风向

---

环境配置

预检查：必须配置 ALIYUN_IQS_API_KEY

if [ -z "$ALIYUN_IQS_API_KEY" ]; then echo "API Key 未配置"; else echo "API Key 已配置(已脱敏)"; fi

如果输出为“API Key 未配置”，则表示尚未配置 API Key。

如何获取 ALIYUN_IQS_API_KEY： 请参阅 Aliyun IQS Documentation

配置环境变量（任选其一）：

选项 1：临时配置（仅当前终端会话有效）

export ALIYUN_IQS_API_KEY="your-api-key-here"

选项 2：永久配置（推荐）

添加到 ~/.zshrc 或 ~/.bashrc：

export ALIYUN_IQS_API_KEY="your-api-key-here"

运行 source ~/.zshrc 或 source ~/.bashrc 以使配置生效。

替代方案： 将 API Key 放入 ~/.alibabacloud/iqs/env 文件：

ALIYUN_IQS_API_KEY=your-api-key-here

---

工作流

User Input (city name)
        │
        ▼
┌─────────────────────────┐
│ Step 1: UnifiedSearch    │  Search: "{city} 天气预报 未来7天"
│ (Web Search)            │  Priority: weather.cma.cn > weather.com.cn
└──────────┬──────────────┘
           │ Best weather URL
           ▼
┌─────────────────────────┐
│ Step 2: ReadPageBasic    │  Known site → readabilityMode: normal
│ (Page Reading)          │  Unknown site → readabilityMode: article
└──────────┬──────────────┘
           │ Page content
           ▼
     Known site?
      ╱        ╲
    YES          NO
     │            │
     ▼            ▼
  Parser       Return rawText
  Router       + hint for agent
     │         (parseMode: raw)
     ▼
  Structured JSON
  (parseMode: structured)

---

用法

前置条件

• Node.js >= 18（需要原生 fetch 支持）
• 无需安装其他 npm 依赖

执行查询

node scripts/weather.mjs <city>

示例：

node scripts/weather.mjs 北京
node scripts/weather.mjs 上海
node scripts/weather.mjs 杭州
node scripts/weather.mjs Tokyo

输出格式

结构化模式（已知网站——解析成功）：

{
  "success": true,
  "data": {
    "city": "北京",
    "parseMode": "structured",
    "queryTime": "2026-03-26T10:00:00.000Z",
    "forecastDays": 7,
    "forecast": [
      {
        "date": "3月26日",
        "weather": "晴",
        "temperature": "5°C ~ 18°C",
        "windDirection": "北风",
        "windSpeed": "3-4级"
      }
    ],
    "source": "https://weather.cma.cn/..."
  }
}

原始模式（未知网站——由 Agent 解读文本）：

{
  "success": true,
  "data": {
    "city": "北京",
    "parseMode": "raw",
    "hint": "以下是北京天气网页的正文内容，请从中提取未来7天的天气预报信息...",
    "rawText": "北京天气预报\n今天 晴 18°C/5°C ...",
    "evolveHint": "[持续进化] 当前站点 \"example.com\" 没有匹配的解析器...",
    "source": "https://example.com/weather/beijing"
  }
}

---

使用的 IQS API

API	端点	用途	文档
UnifiedSearch	cloud-iqs.aliyuncs.com/search/unified	搜索天气网页	Doc
ReadPageBasic	cloud-iqs.aliyuncs.com/readpage/scrape	读取并解析天气网页	Doc

搜索优先网站（配有专用解析器）：

1. weather.cma.cn（中国气象局）— parseCmaWeather → readabilityMode: normal
2. baidu.weather.com.cn / sq.weather.com.cn（中国天气网移动版）— parseBaiduWeatherComCn → readabilityMode: normal
3. weather.com.cn（中国天气网的其他所有子域名）— parseWeatherComCn → readabilityMode: normal
4. 其他网站 — 无解析器，返回原始文本 → readabilityMode: article（提取的正文更简洁）

---

错误处理

错误代码	描述	解决方案
CREDENTIALS_MISSING	未配置 API Key	设置 ALIYUN_IQS_API_KEY 环境变量
NO_RESULTS	未找到天气结果	检查城市名称是否正确
QUERY_FAILED	API 调用失败	检查网络并验证凭据
PARSE_FAILED	无法从网页解析天气数据	目标网站的页面结构可能已更改；请更新相应解析器或添加新的解析器（参见“扩展”部分）

最佳实践

1. 国内天气查询使用中文城市名称，以提高准确性
2. 需要 Node.js >= 18——使用原生 fetch API，无需 npm install
3. 缓存注意事项——ReadPage 未设置 maxAge，始终获取最新数据
4. 可扩展的解析器——每个天气网站都有自己的解析器；注册到 PARSER_REGISTRY 即可添加新网站

---

持续进化

此技能旨在随着时间不断自我改进。当脚本遇到未知的网站格式（没有匹配的解析器）时，会返回 parseMode: "raw"，并包含 evolveHint 字段。

当 parseMode 为 "raw" 时，Agent 的行为：

1. 首先：回答用户——使用大模型理解，从 rawText 中提取天气信息，并立即回复用户。
2. 然后：进化——读取 evolveHint，分析 rawText 的格式模式，然后编写新的解析器函数并将其注册到 PARSER_REGISTRY（请参阅下文的扩展部分）。这样，下次遇到相同的网站格式时，就会直接进入 structured 模式。

First query for unknown site:
  search → readpage → no parser match → raw mode → agent answers user
                                                  → agent writes new parser ← evolveHint

Subsequent queries for same site:
  search → readpage → parser match → structured mode → direct JSON output

要点： 每搜索一座新城市，这项技能都会变得更智能。每次遇到原始模式，都是添加新解析器的机会，可逐步覆盖更多网站格式。

---

扩展：添加新的天气网站解析器

脚本采用解析器注册表模式。每个天气网站都有专用的解析器函数，路由器会根据 URL 自动分发。要为新网站添加支持，请按以下 3 个步骤操作：

步骤 1：编写解析器函数

在 scripts/weather.mjs 中添加新的解析器函数。它必须接受 (content, city) 并返回标准格式：

function parseMyNewSite(content, city) {
  const forecast = [];

  // Parse the text content from ReadPage for this specific site
  // Extract: date, weather, temperature, windDirection, windSpeed
  // ...your parsing logic here...

  return {
    city,
    queryTime: new Date().toISOString(),
    forecastDays: Math.min(forecast.length, 7),
    forecast: forecast.slice(0, 7),
    raw: forecast.length === 0 ? content.substring(0, 2000) : undefined,
  };
}

每个预报项目的返回格式：

字段	类型	示例
date	字符串	"04/07 星期二"
weather	字符串	"晴转多云"
temperature	字符串	"5°C ~ 18°C"
windDirection	字符串	"北风"
windSpeed	字符串	"3-4级"

步骤 2：在 PARSER_REGISTRY 中注册

将解析器添加到 weather.mjs 顶部的注册表数组中。顺序很重要——位置越靠前，优先级越高：

const PARSER_REGISTRY = [
  { pattern: 'weather.cma.cn',          parser: parseCmaWeather },
  { pattern: 'baidu.weather.com.cn',    parser: parseBaiduWeatherComCn },
  { pattern: 'sq.weather.com.cn',       parser: parseBaiduWeatherComCn },
  { pattern: 'weather.com.cn',          parser: parseWeatherComCn },
  { pattern: 'mynewsite.com',           parser: parseMyNewSite },    // ← Add here
];

步骤 3：添加到搜索优先列表（可选）

如果希望新网站在搜索结果中获得优先级，请将其添加到 PREFERRED_WEATHER_SITES：

const PREFERRED_WEATHER_SITES = [
  'weather.cma.cn',
  'weather.com.cn',
  'mynewsite.com',           // ← Add here
];

路由器的工作方式

parseWeatherData(content, city, url)
  │
  ├─ URL contains "weather.cma.cn"?          → parseCmaWeather(content, city)
  ├─ URL contains "baidu.weather.com.cn"?    → parseBaiduWeatherComCn(content, city)
  ├─ URL contains "sq.weather.com.cn"?       → parseBaiduWeatherComCn(content, city)
  ├─ URL contains "weather.com.cn"?          → parseWeatherComCn(content, city)
  ├─ URL contains "mynewsite.com"?           → parseMyNewSite(content, city)
  │
  └─ No match or result < 3 days?           → return rawText + hint (agent interprets)

提示： 在编写解析器之前，可使用 ReadPage API 和 node -e "..." 获取并检查新网站的原始文本格式。可参考现有解析器（parseCmaWeather、parseWeatherComCn）。