# emst

基于[东方财富](https://quote.eastmoney.com/)数据的**多市场股票数据**和**快讯新闻**工具，支持**实时数据流**推送。

[![npm version](https://img.shields.io/npm/v/emst.svg)](https://www.npmjs.com/package/emst)
[![npm](https://img.shields.io/npm/dm/emst.svg)](https://www.npmjs.com/package/emst)

> 🌍 **多市场**（A股/港股/美股） | 📊 **股票数据** | 📰 **快讯新闻** | ⚡ **实时数据流**（SSE）

## 快速开始

### 安装

```bash
npm install -g emst
```

### 核心用法

```bash
# 多市场股票数据（A股自动检测，港股/美股需指定 --market）
emst stock fetch --symbol 688005              # A股
emst stock fetch --symbol 00700 --market 116  # 港股
emst stock fetch --symbol AAPL --market 105   # 美股
emst stock fetch --symbol SPY --market 107    # 美股ETF

# 获取实时行情
emst stock quote --symbol 688005

# 实时数据流（SSE）- 实时推送行情、分时走势、成交明细
emst stock stream --symbol 688005
emst stock stream --symbol 688005 --types quote,trend,detail

# 快讯新闻
emst news list                              # 获取快讯列表
emst news stream                            # 实时新闻流（SSE）

# 自选股管理
emst stock watchlist add 688005
emst stock watchlist sync
```

## 核心功能

### 🌍 多市场支持

支持 **A股、港股、美股** 三大市场，A股自动识别市场，统一接口获取数据。支持股票、指数、基金和ETF。

### 📊 股票数据

- **历史K线数据**：日线、周线、月线及日内数据（5分钟/15分钟/30分钟/60分钟）
- **实时行情**：REST API 获取实时行情快照
- **灵活筛选**：日期范围、复权类型（不复权/前复权/后复权）
- **多格式导出**：JSON、CSV 格式

### ⚡ 实时数据流（SSE）

支持实时推送**行情、分时走势、成交明细**，可同时订阅多种数据类型。

### 📰 快讯新闻

支持获取和实时推送财经快讯，可按分类筛选。

### 🛠️ 便捷工具

- **自选股管理**：批量管理股票，一键同步数据
- **智能缓存**：自动缓存，增量更新，提升效率

## 安装

### npm 安装（推荐）

```bash
npm install -g emst
```

### 源码安装

```bash
git clone https://github.com/Algovate/emst.git
cd emst
npm install && npm run build
```

> **提示**：全局安装后可直接使用 `emst` 命令。源码运行使用 `npm run start --`。

## 使用方法

详细使用方法请参阅 [使用示例文档](docs/examples.md)。

### 常用命令

| 命令 | 说明 | 示例 |
|------|------|------|
| `stock fetch` | 获取K线数据 | `emst stock fetch --symbol 688005` |
| `stock quote` | 获取实时行情 | `emst stock quote --symbol 688005` |
| `stock stream` | 实时数据流（SSE） | `emst stock stream --symbol 688005` |
| `news list` | 获取快讯列表 | `emst news list` |
| `news stream` | 实时新闻流 | `emst news stream` |
| `watchlist` | 自选股管理 | `emst stock watchlist add 688005` |

### 常用参数

- `-s, --symbol <symbol>`: 股票代码（必需）
- `--market <market>`: 市场代码（0=深圳，1=上海，105=美股，107=美股ETF，116=港股），A股自动检测
- `--timeframe <timeframe>`: 时间周期（daily/weekly/monthly/5min/15min/30min/60min）
- `--start/--end <date>`: 日期范围（YYYYMMDD）
- `--output <path>`: 输出文件（.csv 自动识别为 CSV 格式）
- `--format <format>`: 输出格式（json/table/text）

完整命令行选项请参阅 [使用示例文档](docs/examples.md)。

## 数据存储

数据存储在 `.emst/` 目录：

- **自选股**：`.emst/watchlist.json`
- **缓存数据**：`.emst/cache/`

默认启用智能缓存，自动检查有效性并增量更新。详情请参阅 [缓存机制文档](docs/cache.md)。

## 数据格式

K线数据包含 `date`, `open`, `close`, `high`, `low`, `volume`, `amount` 等字段。详细格式说明请参阅 [API 文档](docs/api.md)。

## 作为库使用

emst 可以作为 Node.js 库导入使用，不会触发 CLI 代码执行：

```typescript
import { 
  EastMoneyCrawler,
  Market,
  addToWatchlist,
  syncWatchlist,
  getCachedData
} from 'emst';

// 创建爬虫实例
const crawler = new EastMoneyCrawler();

// 获取股票数据
const data = await crawler.fetchKlineData({
  symbol: '688005',
  market: Market.Shanghai,
  timeframe: 'daily'
});

// 使用自选股和缓存功能
addToWatchlist('688005', Market.Shanghai);
const results = await syncWatchlist({ timeframe: 'daily' });
const cached = getCachedData('688005', Market.Shanghai, 'daily');
```

详细 API 文档请参阅 [API 文档](docs/api.md)。

## 文档

- **[使用示例](docs/examples.md)** - 详细使用方法、场景示例和脚本集成
- [API 文档](docs/api.md) - 完整的编程式 API 参考
- [缓存机制](docs/cache.md) - 缓存系统详细说明
- [自选股管理](docs/watchlist.md) - 自选股功能详解