---
name: shdata-cli
description: 使用上海数据观察官方 shdata CLI 查询上海统计年鉴长期指标、年鉴版本、二维表格及已授权导出。
homepage: https://shdata.watch/cli
---

# 上海数据观察 CLI

当用户需要查询上海历年统计指标、年鉴版本或年鉴二维表格时使用本 Skill。

## 安装与能力边界

要求 Node.js 20+：

```bash
npm install -g @shdata-watch/cli
```

`shdata` 是只读查询与导出客户端，不提供资料整理、内部同步、发布、运营或权限修改能力。不要尝试调用 `/v1/ops`、账户管理或未公开的内部路径。

## 鉴权

- 核心指标预览无需登录。
- 交互环境运行 `shdata login`，由用户在浏览器确认授权。
- 无人值守环境仅从 `SHDATA_API_KEY` 环境变量读取专业版密钥。
- 不要求用户在对话或命令参数中粘贴密钥，不输出凭据文件内容。

## 查询步骤

1. 不确定指标 ID 时，先运行：

   ```bash
   shdata metrics list "常住人口" --format json
   ```

2. 找到指标 ID 后读取具体年份数据：

   ```bash
   shdata metrics get population --from-year 2020 --to-year 2024 --format json
   ```

3. 需要原始年鉴表时，专业版可先检索再读取：

   ```bash
   shdata tables search "常住人口" --edition-year 2025 --format json
   shdata tables get 2025 C0105-b8062731 1 --format json
   ```

4. 大批量分析优先创建 CSV 或 Parquet 导出，不循环抓取接口：

   ```bash
   shdata exports create comparable-series csv
   shdata exports list
   shdata exports download EXPORT_ID --output comparable-series.csv
   ```

## 输出与引用

默认保留完整 JSON envelope，包括 `meta.accessTier`、`meta.truncated`、来源版本和生成时间。若 `truncated` 为 `true`，明确告诉用户结果是权限范围内的预览，不推断缺失年份。

回答具体数值时同时保留：

- 指标名称
- 统计年份
- 数值与单位
- `editionYear`
- `sourcePageId` 或 `sourceUrl`

表格结果可能含口径注释和多层表头，不要仅凭列位置猜测含义。

## 错误处理

- 退出码 2：命令或参数错误，先查看 `shdata --help`。
- 退出码 3：登录失效，交互环境运行 `shdata login`。
- 退出码 4：权限不足，说明需要专业会员，不尝试绕过。
- 退出码 5：达到调用额度，停止重试。
- 退出码 6：服务暂不可用，可稍后重试一次。