> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 官方 SDK

> 面向 Python、Ruby、Go 和 JavaScript 的零依赖 SDK —— 无需手写 HTTP 调用即可脚本化国家简报、风险评分、事件流与 MCP 工具，SDK 提供类型化响应、内置认证与自动重试，帮助开发者在数据管线、Notebook 与 agent 工作流中集成 World Monitor 情报能力。

World Monitor 在四个语言生态中提供官方客户端库。它们都是**零依赖**、MCP 优先的 [`worldmonitor` npm CLI](/docs/zh/cli) 镜像：[MCP 服务器](/docs/zh/mcp-overview)是实时且有文档的智能体接口（`tools/list` 公开；`get_sources` 是唯一无需凭据且不消耗每日配额的数据工具；其他所有承载数据的 `tools/call` 都需要订阅 API 密钥），此外每个 SDK 都配有一个小型 REST 备用通道，用于主机相对路径和自托管场景。

| 语言 | 软件包 | 安装 | 源码 |
| - | - | - | - |
| Python | [PyPI 上的 `worldmonitor-sdk`](https://pypi.org/project/worldmonitor-sdk/) | `pip install worldmonitor-sdk` | [`sdk/python/`](https://github.com/koala73/worldmonitor/tree/main/sdk/python) |
| Ruby | [RubyGems 上的 `worldmonitor`](https://rubygems.org/gems/worldmonitor) | `gem install worldmonitor` | [`sdk/ruby/`](https://github.com/koala73/worldmonitor/tree/main/sdk/ruby) |
| Go | [pkg.go.dev 上的 `github.com/koala73/worldmonitor/sdk/go`](https://pkg.go.dev/github.com/koala73/worldmonitor/sdk/go) | `go get github.com/koala73/worldmonitor/sdk/go` | [`sdk/go/`](https://github.com/koala73/worldmonitor/tree/main/sdk/go) |
| JavaScript / CLI | [npm 上的 `worldmonitor`](https://www.npmjs.com/package/worldmonitor) | `npm install worldmonitor` | [`cli/`](https://github.com/koala73/worldmonitor/tree/main/cli) |

## 查找并验证官方软件包

请使用表格中的完整包名。npm、PyPI 和 RubyGems 的项目元数据包含指向 `worldmonitor.app` 的链接；请将这些链接与上方列出的源码仓库进行比对。Python 包名是 `worldmonitor-sdk`。PyPI 上名为 `worldmonitor` 的包属于无关项目。

Go SDK 的模块路径是 `github.com/koala73/worldmonitor/sdk/go`，包名是 `worldmonitor`。Go 模块没有注册表主页字段。请通过上方链接的官方仓库核对模块路径，并检查 pkg.go.dev 页面上的产品链接。

* [在 pkg.go.dev 搜索 worldmonitor](https://pkg.go.dev/search?q=worldmonitor)。
* [查看 Go 模块代理上的最新发布元数据](https://proxy.golang.org/github.com/koala73/worldmonitor/sdk/go/@latest)。
* 在 Go 项目中运行 `go get github.com/koala73/worldmonitor/sdk/go` 安装。

Go 通过仓库标签（`sdk/go/vX.Y.Z`）和模块代理发布版本。代理查询成功表示版本可用；pkg.go.dev 搜索结果表示该包可以被搜索到。参见 [pkg.go.dev 如何添加软件包](https://pkg.go.dev/about#adding-a-package)。

## 共享设计

四个客户端都以各语言的原生命名方式暴露相同的接口：

* **任意 MCP 工具**——使用带命名参数的 `call_tool` / `CallTool`；返回结果是解包后的 JSON-RPC `result`。
* **精选辅助方法**，覆盖流量最高的工具：世界简报、国家简报/风险、市场、冲突、网络、新闻、灾害、制裁、预测、海事。
* **公开列表**——`list_tools`、`list_prompts`、`list_resources` 无需密钥。
* **REST 备用通道**——针对 `api.worldmonitor.app` 的 `get("/api/…")` 和 `health()`。
* **配置**方式：通过构造函数参数，或 `WORLDMONITOR_API_KEY`（别名 `WM_API_KEY`）、`WORLDMONITOR_BASE_URL` 和 `WORLDMONITOR_MCP_URL` 环境变量。
* **错误**分为两类：MCP 错误（JSON-RPC `error` 对象，认证失败会附带密钥提示）和 API 错误（非 2xx 传输）。
* 一个具描述性的 **User-Agent**（`worldmonitor-<lang>/<version>`）——API 边缘会拦截通用库代理，因此如果你 fork 了代码，请保留它。

每个工具都接受一个可选的 `jmespath` 参数用于[服务端投影](/docs/zh/mcp-jmespath)——通常可将响应大小削减 80–95%。

## Python

```python theme={null}
from worldmonitor_sdk import Client

client = Client(api_key="wm_...")  # or set WORLDMONITOR_API_KEY
client.list_tools()                # public — no key needed
client.country_risk("IR")
client.conflict_events(country="IR", limit=5)
client.call_tool("get_market_data", asset_class="crypto")
```

## Ruby

```ruby theme={null}
require "worldmonitor"

client = WorldMonitor::Client.new(api_key: "wm_...")
client.list_tools
client.country_risk("IR")
client.call_tool("get_market_data", asset_class: "crypto")
```

## Go

```go theme={null}
client := worldmonitor.New("wm_...") // "" reads WORLDMONITOR_API_KEY
tools, _ := client.ListTools(ctx)
risk, _ := client.CountryRisk(ctx, "IR", nil)
quotes, _ := client.CallTool(ctx, "get_market_data", worldmonitor.Args{"asset_class": "crypto"})
```

## JavaScript

该 npm 软件包同时充当[命令行客户端](/docs/zh/cli)和库：

```js theme={null}
import { parseArgs, planRequest } from 'worldmonitor';
import run from 'worldmonitor/run';
```

## 获取密钥

`get_sources` 是唯一无需凭据且不消耗每日配额的 `tools/call` 数据工具；匿名调用使用独立的失败关闭上限：每个 IP 每分钟 10 次。其他所有数据工具都需要订阅 API 密钥——在 [worldmonitor.app/pro](https://www.worldmonitor.app/pro) 生成一个。有关密钥、OAuth 和浏览器会话的区别，请参见[身份验证](/docs/zh/usage-auth)；各套餐的额度请参见[速率限制](/docs/zh/usage-rate-limits)。

## 发布（维护者）

各 SDK 独立管理版本。npm、Python 和 Ruby 使用 OIDC 可信发布；Go 使用仓库标签和公共模块代理。它们均无需长期有效的注册表令牌（npm 流程请参见 [CLI 发布手册](/docs/zh/releasing-cli)）：

* **Python：** 在 `sdk/python/pyproject.toml` 中提升 `version`，**并**在 `sdk/python/src/worldmonitor_sdk/__init__.py` 中提升 `__version__`，然后打上 `py-vX.Y.Z` 标签（工作流 `publish-python.yml`）。
* **Ruby：** 在 `sdk/ruby/lib/worldmonitor/version.rb` 中提升 `WorldMonitor::VERSION`，然后打上 `gem-vX.Y.Z` 标签（工作流 `publish-ruby.yml`）。
* **Go：** 在 `sdk/go/worldmonitor.go` 中提升 `Version`，然后打上 `sdk/go/vX.Y.Z` 标签（工作流 `publish-go.yml` 会验证并预热模块代理）。

`tests/sdk-packages.test.mjs` 检查包身份、版本声明、注册表元数据和发布工作流配置。