Stock Ohlcs

# 查询单只股票 OHLC K 线

## 接口说明

| 项目     | 说明                                                                                                                                      |
|----------|-------------------------------------------------------------------------------------------------------------------------------------------|
| 接口名称 | 查询单只股票 OHLC K 线                                                                                                                    |
| 外部接口 | `/api/v2/stocks/:stock/ohlcs`                                                                                                             |
| 请求方式 | GET                                                                                                                                       |
| 适用场景 | 获取 A 股指定股票在指定周期、时间范围内的 K 线（开高低收、成交量、成交额等），支持日/周/月/年线，支持截止时间与条数限制；响应中附带 MA5/MA10/MA20 |

## 请求参数

说明：`stock` 为路径参数（必填），`span` 为必填项，`limit` 和 `until_ts_ms` 为可选项。

| 参数名      | 类型   | 是否必填 | 描述                                       | 取值示例                          | 备注                                                                                 |
|-------------|--------|----------|--------------------------------------------|-----------------------------------|--------------------------------------------------------------------------------------|
| stock       | string | 是       | 股票标的键（路径参数，带市场后缀）           | 688295.XSHG、000001.SZ、920036.BJ | 沪 .XSHG、深 .SZ、北交所 .BJ                                                          |
| span        | string | 是       | K 线周期                                   | DAY1                              | 可选值：DAY1（日线）、WEEK1（周线）、MONTH1（月线）、YEAR1（年线）                       |
| limit       | int    | 否       | 返回 K 线根数上限                          | 50                                | 不传则不限制条数，返回时间范围内全部 K 线，可能超过 2000 条；建议传 limit 且不超过 2000 |
| until_ts_ms | long   | 否       | 截止时间戳（毫秒），返回该时间点及之前的 K 线 | 1735689600000                     | 不传则截止到"当前"                                                                   |

## 执行方式

通过根目录的 `run.py` 调用（推荐）：

```bash
# 查询 688295.XSHG 最近 50 根日线
python <RUN_PY> stock-ohlcs --stock 688295.XSHG --span DAY1 --limit 50

# 查询 000001.SZ 周线（不限条数）
python <RUN_PY> stock-ohlcs --stock 000001.SZ --span WEEK1

# 查询截止某时间点前 24 根月线
python <RUN_PY> stock-ohlcs --stock 000001.SZ --span MONTH1 --limit 24 --until_ts_ms 1735689600000
```

> `<RUN_PY>` 为主 `SKILL.md` 同级的 `run.py` 绝对路径，参见主 SKILL.md 的「调用方式」说明。

## 响应结构

```json
{
    "has_last_empty": false,
    "prev_close": 45.2100,
    "ohlcs": [
        { "o": 45.30, "h": 46.10, "l": 44.80, "c": 45.90, "v": 1234567, "t": 56789012.34, "otm": 1735689600000, "ctm": 1735775999000 }
    ],
    "ma5":  [ { "p": 45.6800, "ctm": 1735775999000 } ],
    "ma10": [ { "p": 44.9200, "ctm": 1735775999000 } ],
    "ma20": [ { "p": 43.1500, "ctm": 1735775999000 } ]
}
```

### 根字段说明

| 字段名         | 类型    | 是否可为空 | 说明                                                   |
|----------------|---------|------------|--------------------------------------------------------|
| has_last_empty | boolean | 否         | 最后一根 K 线是否为"空"（未收盘）                        |
| prev_close     | float   | 是         | 昨收价（用于涨跌幅等计算），保留 4 位小数；无昨收时为 null |
| ohlcs          | array   | 否         | K 线列表，按时间正序；单条结构见下表                     |
| ma5            | array   | 否         | 5 周期均线点，与 ohlcs 对齐                             |
| ma10           | array   | 否         | 10 周期均线点                                          |
| ma20           | array   | 否         | 20 周期均线点                                          |

### Ohlc 单条结构（ohlcs 元素）

| 字段名 | 类型  | 是否可为空 | 说明                              | 单位 |
|--------|-------|------------|-----------------------------------|------|
| o      | float | 否         | 开盘价                            | 元   |
| h      | float | 否         | 最高价                            | 元   |
| l      | float | 否         | 最低价                            | 元   |
| c      | float | 否         | 收盘价                            | 元   |
| v      | long  | 否         | 成交量                            | 股   |
| t      | float | 否         | 成交额                            | 元   |
| otm    | long  | 否         | 该根 K 线周期开始时间（毫秒时间戳） | ms   |
| ctm    | long  | 否         | 该根 K 线周期结束时间（毫秒时间戳） | ms   |

### Ma 单条结构（ma5 / ma10 / ma20 元素）

| 字段名 | 类型  | 是否可为空 | 说明                                     | 单位 |
|--------|-------|------------|------------------------------------------|------|
| p      | float | 是         | 均线价格，保留 4 位小数；不足周期时为 null | 元   |
| ctm    | long  | 否         | 对应 K 线的结束时间（毫秒时间戳）          | ms   |

## 注意事项

- `stock` 与 `span` 为必填参数，`limit` 和 `until_ts_ms` 为可选参数
- 股票代码需携带市场后缀：沪市使用 `.XSHG`、深市使用 `.SZ`、北交所使用 `.BJ`
- `span` 可选值：`DAY1`（日线）、`WEEK1`（周线）、`MONTH1`（月线）、`YEAR1`（年线）
- 不传 `limit` 时可能返回超过 2000 条数据，建议指定 `limit` 且不超过 2000
- `prev_close` 可为 null（无昨收数据时）
- 均线 `p` 字段在不足周期时为 null，展示时需做空值处理
- 所有接口请求需携带 `X-Client-Name: ft-claw` 请求头
- 执行方式：脚本在输出前将接口返回的毫秒时间戳（ohlcs 的 otm/ctm、ma5/ma10/ma20 的 ctm）转为北京时间 ISO 字符串（YYYY-MM-DDTHH:mm:ss），便于大模型与用户直接阅读时间。
- 接口返回的是前复权数据，且不支持选择复权