智能体发现

WorldMonitor 的构建理念是智能体原生。一个自主智能体——Claude、Cursor、MCP 客户端，或你自己的 LangChain / LangGraph 工作流——可以从一个根 URL 开始，发现它所需的一切：REST 架构、MCP 传输、OAuth 流程、技能包和人类可读的简报。无需任何先验知识。只需 GET https://worldmonitor.app/。

唯一需要记住的 URL

https://worldmonitor.app/

HTTP 响应携带一个 RFC 8288 Link: 头部，其 rel 值指向下方每一个机器可读的接口。一个跟随链接的智能体无需硬编码任何路径即可解析全貌。

curl -sI https://worldmonitor.app/ | grep -i '^link:'

你会看到类似以下的条目：

Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
      </openapi.json>; rel="service-desc"; type="application/json",
      </openapi.yaml>; rel="service-desc"; type="application/vnd.oai.openapi",
      </docs/documentation>; rel="service-doc"; type="text/html",
      </api/health>; rel="status"; type="application/json",
      </.well-known/oauth-protected-resource>; rel="...oauth-protected-resource",
      </.well-known/oauth-authorization-server>; rel="...oauth-authorization-server",
      </.well-known/mcp/server-card.json>; rel="mcp-server-card"; anchor="/mcp",
      </.well-known/agent-skills/index.json>; rel="agent-skills-index"; type="application/json"

发现端点

端点	标准	返回内容
`/.well-known/api-catalog`	RFC 9727	JSON 链接集，打包了所有其他发现 URL——如果你只想要一次请求和一张地图，从这里开始
`/openapi.yaml`	OpenAPI 3.1	单一打包规范，覆盖所有 REST 服务（Conflict、Resilience、Market、Economic、Maritime、Aviation、Climate……）——可喂给任何代码生成器
`/openapi.json`	OpenAPI 3.1	压缩 JSON 打包，面向只解析 JSON 的工具与扫描器。操作、参数、请求体与响应与 `/openapi.yaml` 完全一致；为控制在扫描器的响应体大小上限内，共享结构以 `$ref` 合并，并省略任何操作都无法引用到的组件 schema
`/.well-known/mcp/server-card.json`	MCP	传输方式（`streamableHttp`）、端点、OAuth 资源、作用域、流式、能力标志
`/.well-known/oauth-authorization-server`	RFC 8414	OAuth 2.1 授权服务器元数据（PKCE、DCR、令牌端点）
`/.well-known/oauth-protected-resource`	RFC 9728	`https://worldmonitor.app/mcp` 的资源元数据
`/.well-known/mcp/docs-server-card.json`	MCP	`/docs/mcp` 处文档 MCP 服务器的服务器卡片（见下文）——与上面的数据服务器卡片相互独立
`/.well-known/agent-card.json`	A2A	`/a2a` JSON-RPC 接待智能体的 Agent Card（见下文）——传输方式、协议版本、技能，无需认证
`/.well-known/http-message-signatures-directory`	RFC 9421 / Web Bot Auth	Ed25519 公钥目录（`application/http-message-signatures-directory+json`），供第三方验证源自 WorldMonitor 的签名自动化请求。密钥携带滚动 24 小时 `nbf`/`exp` 窗口；缓存 `public, max-age=3600`
`/.well-known/agent-skills/index.json`	（自定义）	预打包智能体技能索引（`fetch-country-brief`、`fetch-resilience-score`……）——每个技能都是一份自包含的配方
`/llms.txt`	llmstxt.org	LLM 友好的 markdown 简报——概述、能力、链接
`/llms-full.txt`	（扩展）	长格式变体，覆盖所有数据层、面板和数据源
`/api/health`	（自定义）	按密钥的种子状态、新鲜度、记录计数——智能体可据此门控抓取

头部可发现的静态资产（.well-known/*、/openapi.yaml、/openapi.json）提供 Access-Control-Allow-Origin: *，并以 public, max-age=3600 缓存——可以安全地记忆化。/api/health 使用常规 API CORS 允许列表，且未缓存（private, no-store），因为它反映实时种子新鲜度；智能体在需要基于数据可用性进行门控时应每次重新请求。

智能体前门

除静态发现文档外，还有若干专为智能体准备的实时端点。它们均为匿名且不消耗配额；各自拥有独立的每 IP 限流。

`GET|POST /ask` —— 自然语言路由（NLWeb）

NLWeb 风格的前门：发送一个问题，返回能回答它的 MCP 工具。接受 query（最长 2048 字符），可通过 JSON body、表单 body 或 ?query= 传入；可选 mode（默认 "list"）、query_id 和 streaming（也可由 Accept: text/event-stream 触发）。

curl -s https://worldmonitor.app/ask -H 'Content-Type: application/json' \
  -d '{"query": "台湾附近是否有异常军事空中活动？"}'

返回 { _meta, query_id, query, results[] }，每个 result 携带指向匹配 MCP 工具的 {url, name, site, score, description, schema_object}。流式模式发出 start → result → complete SSE 帧。不带 query 的探测返回 200 与使用指引而非错误；无匹配时返回单个指向 llms.txt 的结果，score: 0。限流：每 IP 每分钟 60 次（429 + Retry-After）。响应为 no-store。

`POST /a2a` —— A2A JSON-RPC 接待智能体

一个 A2A 协议智能体（卡片位于 /.well-known/agent-card.json，协议 0.3.0，传输 JSONRPC，无需认证）。支持带文本 part 的 message/send（最长 2048 字符）；回复一条智能体消息，包含一个文本 part 和一个数据 part {suggestedTools, howToCall, freshness?} —— 当消息询问陈旧度或种子健康时附带 freshness 信封。流式、推送通知与任务历史均声明为不支持并返回 -32004；限流以 JSON-RPC -32029 + Retry-After 呈现（每 IP 每分钟 60 次）。

`GET /agent/auth` —— 认证质询

始终返回 401，携带 WWW-Authenticate: Bearer realm="worldmonitor", resource_metadata="…" 头和一个 JSON body，链接 RFC 9728 资源元数据、RFC 8414 授权服务器元数据以及 /auth.md 技能。它存在的原因是：扫描器向 GET /mcp 探测 OAuth 质询时无法在那里得到（该动词保留给 SSE 握手）——请改为探测此 URL 来引导 OAuth 流程。

`/docs/mcp` —— 文档 MCP 服务器

面向文档本身的第二个独立 MCP 服务器（卡片位于 /.well-known/mcp/docs-server-card.json，协议 2025-06-18，streamable HTTP，无需认证）。它提供 search_world_monitor（文档知识库搜索，返回摘录与链接）和 query_docs_filesystem_world_monitor（对虚拟化的文档 + OpenAPI 文件系统进行只读 rg/ls/tree/cat/head）。POST body 上限 256 KiB（超出为 413）；限流每 IP 每分钟 60 次，以 JSON-RPC -32029 呈现。它是对上游文档提供方的一致性修复门面：tools/call 中携带 -32601/-32602 的 isError 结果会被提升为真正的顶层 JSON-RPC 错误。

Markdown 孪生页 —— `<任意页面>.md`

站点上的每个页面都有一个智能体可读的 markdown 孪生页：在路径后追加 .md（/pricing.md、/countries/tw.md，首页为 /home.md）。精选孪生页为静态文件，缓存 public, max-age=3600 且带 Access-Control-Allow-Origin: *；其余由孪生服务按需渲染（HTML 转为以标题为主的 markdown，JSON 转为围栏代码块，输出上限 80 KB），并携带 Link: <sibling>; rel="canonical" 头。.md 孪生页的 GET/HEAD 绕过 API 机器人门禁，因此普通 curl 无需浏览器 User-Agent 即可访问。

智能体演练

为每个服务代码生成 REST 客户端

# 1. Discover the bundled OpenAPI URL (linkset[0] enumerates every API via
#    RFC 9727 `item` links; select the REST API context object by anchor)
curl -s https://worldmonitor.app/.well-known/api-catalog \
  | jq -r '.linkset[] | select(.anchor == "https://api.worldmonitor.app/")."service-desc"[0].href'
# → https://www.worldmonitor.app/openapi.yaml

# 2. Generate clients
curl -s https://www.worldmonitor.app/openapi.yaml -o worldmonitor.openapi.yaml
npx @openapitools/openapi-generator-cli generate \
  -i worldmonitor.openapi.yaml -g typescript-fetch -o ./client

打包的规范在单个文档中覆盖了完整服务目录，因此一次代码生成即可为所有服务生成带类型的客户端。偏好维护好的包而非代码生成？官方 SDK 提供 Python、Ruby、Go 和 JavaScript 版本。

将 MCP 客户端连接到实时数据

# 1. Read the server card — this is the canonical descriptor for MCP
curl -s https://worldmonitor.app/.well-known/mcp/server-card.json
# → endpoint (https://worldmonitor.app/mcp), transport, OAuth scopes,
#   streaming support, and authorization_servers: ["https://api.worldmonitor.app"]

# 2. Fetch authorization-server metadata from that host
curl -s https://api.worldmonitor.app/.well-known/oauth-authorization-server
# → token / authorize / registration endpoints, PKCE required, etc.

/.well-known/oauth-protected-resource 也可用，但其 authorization_servers 字段是从请求的 Host 头派生的，因此每个源（apex、www、api）都报告自身——同源元数据，满足严格的 MCP 扫描器。实际 MCP 端点期望的跨源 auth-server URL 请使用 MCP 服务器卡片。或者完全跳过手动流程——大多数客户端（Claude Desktop、claude.ai、Cursor、MCP Inspector、Claude Code）直接接受 MCP URL 并自动运行发现 + OAuth：

https://worldmonitor.app/mcp

有关客户端特定的配置片段，请参见 MCP Server。

使用直接 API 密钥的服务端调用

如果你不想用 OAuth，REST 端点和 MCP 端点接受用户 API 密钥或运营商签发的企业密钥，置于 X-WorldMonitor-Key 中：

curl -s https://api.worldmonitor.app/api/resilience/v1/get-resilience-ranking \
  -H "X-WorldMonitor-Key: $WM_KEY"

PRO 订阅者可从 worldmonitor.app/pro 获取密钥。请参见身份验证。

即插即用智能体技能

/.well-known/agent-skills/index.json 列出了预打包的技能——每个都是一份自包含配方，智能体无需阅读 OpenAPI 即可消化。适用于你宁愿让智能体”获取国家简报”而非”阅读 OpenAPI 规范然后自己搞清楚”的窄任务。请参见 Agent Skills Catalog 获取每份配方的人类可读列表。当前目录涵盖国家简报、风险与韧性、咽喉要道、市场、网络、制裁、航空、军用航班、海上交通、能源冲击、贸易流、动荡、网络摄像头、气候灾害、健康告警和预报。

为什么这很重要

重点不在于新颖性——RFC 8414、8288、9727、9728 都很旧了。重点在于 WorldMonitor 的每一个接口（REST、MCP、OAuth、技能、LLM 简报）都可通过众所周知的约定从一个根 URL 访问，无需带外设置。一个智能体可以：

无需阅读我们的文档即可发现 API。
无需我们告知使用哪个 OAuth 流程即可完成身份验证。
根据自身偏好选择正确的传输方式（REST vs MCP）。
保持最新——当我们发布新服务时，打包的 /openapi.yaml 和 api-catalog 会在下次部署时反映出来。无需版本锁定，无需等待 SDK 发布周期（不过当维护好的包更合适时，也存在官方 SDK）。

入门

使用

平台与功能

情报与分析

工作流

地图图层

金融

面板 — AI 与 PRO

面板 — 数据与追踪

面板 — 目录

桌面应用

MCP 与集成

HTTP API

开发者指南

公司

法律

唯一需要记住的 URL

发现端点

智能体前门

`GET|POST /ask` —— 自然语言路由（NLWeb）

`POST /a2a` —— A2A JSON-RPC 接待智能体

`GET /agent/auth` —— 认证质询

`/docs/mcp` —— 文档 MCP 服务器

Markdown 孪生页 —— `<任意页面>.md`

智能体演练

为每个服务代码生成 REST 客户端

将 MCP 客户端连接到实时数据

使用直接 API 密钥的服务端调用

即插即用智能体技能

为什么这很重要

相关

​唯一需要记住的 URL

​发现端点

​智能体前门

​GET|POST /ask —— 自然语言路由（NLWeb）

​POST /a2a —— A2A JSON-RPC 接待智能体

​GET /agent/auth —— 认证质询

​/docs/mcp —— 文档 MCP 服务器

​Markdown 孪生页 —— <任意页面>.md

​智能体演练

​为每个服务代码生成 REST 客户端

​将 MCP 客户端连接到实时数据

​使用直接 API 密钥的服务端调用

​即插即用智能体技能

​为什么这很重要

​相关

唯一需要记住的 URL

发现端点

智能体前门

`GET|POST /ask` —— 自然语言路由（NLWeb）

`POST /a2a` —— A2A JSON-RPC 接待智能体

`GET /agent/auth` —— 认证质询

`/docs/mcp` —— 文档 MCP 服务器

Markdown 孪生页 —— `<任意页面>.md`

智能体演练

为每个服务代码生成 REST 客户端

将 MCP 客户端连接到实时数据

使用直接 API 密钥的服务端调用

即插即用智能体技能

为什么这很重要

相关