Rewrite README with proper Markdown formatting

Fix broken code fences, replace ASCII box tables with GFM tables,
add ts_code filter docs for cache endpoint, add volume response example.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -9,89 +9,256 @@ pinned: false
 
 # Kronos Stock Predictor API
 
-Monte-Carlo probabilistic stock forecasting powered by
-[Kronos](https://arxiv.org/abs/2508.02739) — Tsinghua University's open-source
-financial K-line foundation model.
+基于[清华大学 Kronos 金融 K 线基础大模型](https://arxiv.org/abs/2508.02739)的 A 股概率预测 REST API。
 
-Data source: **Tushare Pro** (front-adjusted / qfq).
+- **数据源**：Tushare Pro，前复权（qfq）
+- **推理方式**：蒙特卡洛多次采样，输出预测方向、置信度及 95% 交易区间
+- **异步任务**：POST 提交 → 返回 `task_id` → GET 轮询结果
 
 ---
 
-## Endpoints
+## 模型信息
 
-### `POST /api/v1/predict`
+| 项目 | 值 |
+|---|---|
+| 模型 | [NeoQuasar/Kronos-base](https://huggingface.co/NeoQuasar/Kronos-base) |
+| 参数量 | 102.3M |
+| 架构 | Decoder-only Transformer |
+| 最大上下文 | 512 根 K 线 |
+| 预训练数据 | 全球 45 个交易所，120 亿根 K 线 |
+| 推理设备 | CUDA（若可用）/ CPU fallback |
 
-Submit a prediction job. Returns a `task_id` immediately.
+---
 
-**Request body**
+## 快速开始
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `ts_code` | string | — | Tushare stock code, e.g. `"600900.SH"` |
-| `lookback` | int | 512 | Historical bars to feed the model (1–512) |
-| `pred_len` | int | 5 | Future trading days to predict (1–60) |
-| `sample_count` | int | 30 | MC sampling iterations (1–100) |
-| `mode` | string | `"simple"` | `"simple"` or `"advanced"` |
-| `include_volume` | bool | false | Include volume CI in `advanced` mode |
+### 1. 提交预测任务
+
+```bash
+curl -X POST "https://yingfeng64-kronos-api.hf.space/api/v1/predict" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ts_code": "000063.SZ",
+    "lookback": 512,
+    "pred_len": 5,
+    "sample_count": 30,
+    "mode": "simple"
+  }'
+```
+
+```json
+{ "task_id": "550e8400-e29b-41d4-a716-446655440000" }
+```
+
+### 2. 轮询结果
+
+```bash
+curl "https://yingfeng64-kronos-api.hf.space/api/v1/predict/550e8400-e29b-41d4-a716-446655440000"
+```
+
+`status` 为 `"pending"` 时继续等待，变为 `"done"` 或 `"failed"` 后读取结果。
+
+### Python 一键轮询版
+
+```python
+import time, requests
+
+BASE = "https://yingfeng64-kronos-api.hf.space"
+
+resp = requests.post(f"{BASE}/api/v1/predict", json={
+    "ts_code": "000063.SZ",
+    "lookback": 512,
+    "pred_len": 5,
+    "sample_count": 30,
+})
+task_id = resp.json()["task_id"]
+
+while True:
+    r = requests.get(f"{BASE}/api/v1/predict/{task_id}").json()
+    if r["status"] in ("done", "failed"):
+        break
+    time.sleep(10)
+
+print(r["result"])
+```
+
+---
+
+## API 文档
+
+### `POST /api/v1/predict` — 提交单个预测任务
+
+**请求体**
+
+| 字段 | 类型 | 默认值 | 范围 | 说明 |
+|---|---|---|---|---|
+| `ts_code` | string | — | — | Tushare 股票代码，如 `"000063.SZ"` |
+| `lookback` | int | 512 | 20–512 | 回看历史 K 线根数 |
+| `pred_len` | int | 5 | 1–60 | 预测未来交易日数（建议 ≤ 30） |
+| `sample_count` | int | 30 | 1–100 | MC 蒙特卡洛采样次数 |
+| `mode` | string | `"simple"` | `simple` / `advanced` | 返回字段详细程度 |
+| `include_volume` | bool | false | — | `advanced` 模式下是否返回成交量预测 |
+
+**响应（`mode=simple`）**
 
 ```json
 {
-  "ts_code": "600900.SH",
-  "lookback": 512,
+  "ts_code": "000063.SZ",
+  "base_date": "2026-03-13",
   "pred_len": 5,
-  "sample_count": 30,
-  "mode": "simple"
+  "confidence": 95,
+  "confidence_warning": false,
+  "cached": false,
+  "cache_expires_at": "2026-03-16 15:00:00 UTC+08:00",
+  "direction": {
+    "signal": "bearish",
+    "probability": 0.4333
+  },
+  "summary": {
+    "mean_close": 36.35,
+    "range_low": 30.60,
+    "range_high": 40.01,
+    "range_width": 9.41
+  },
+  "bands": [
+    {
+      "date": "2026-03-16",
+      "step": 1,
+      "mean_close": 36.10,
+      "trading_low": 34.46,
+      "trading_high": 37.32,
+      "uncertainty": 0.0785
+    }
+  ]
 }
 ```
 
-**Response**
+**`mode=advanced` 在每个 `bands` 条目中追加**
+
+| 字段 | 说明 |
+|---|---|
+| `mean_open` / `mean_high` / `mean_low` | 预测开/高/低价均值 |
+| `close_ci_low` / `close_ci_high` | 收盘价 95% 置信区间 |
+
+当 `include_volume: true` 时额外返回顶层 `volume` 数组：
 
 ```json
-{ "task_id": "550e8400-e29b-41d4-a716-446655440000" }
+"volume": [
+  {
+    "date": "2026-03-16",
+    "mean_volume": 1050000,
+    "volume_ci_low": 820000,
+    "volume_ci_high": 1280000
+  }
+]
 ```
 
 ---
 
-### `GET /api/v1/predict/{task_id}`
+### `GET /api/v1/predict/{task_id}` — 查询单个任务结果
+
+**响应**
+
+| `status` | 含义 |
+|---|---|
+| `pending` | 正在计算 |
+| `done` | 完成，`result` 字段包含预测数据 |
+| `failed` | 失败，`error` 字段包含错误信息 |
+
+---
+
+### `POST /api/v1/predict/batch` — 批量提交
+
+一次提交最多 20 个预测请求，所有子任务并发入队。每个��任务参数与单个预测相同。
 
-Poll for results.
+```bash
+curl -X POST "https://yingfeng64-kronos-api.hf.space/api/v1/predict/batch" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "requests": [
+      {"ts_code": "000063.SZ", "pred_len": 5, "sample_count": 30},
+      {"ts_code": "600900.SH", "pred_len": 5, "sample_count": 30},
+      {"ts_code": "000001.SZ", "pred_len": 5, "sample_count": 30}
+    ]
+  }'
+```
+
+```json
+{
+  "batch_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "task_ids": ["aaa...", "bbb...", "ccc..."]
+}
+```
+
+---
+
+### `GET /api/v1/predict/batch/{batch_id}` — 查询批量进度
 
 ```json
 {
+  "batch_id": "xxxxxxxx-...",
   "status": "done",
-  "error": null,
-  "result": {
-    "ts_code": "600900.SH",
-    "base_date": "2026-03-13",
-    "pred_len": 5,
-    "confidence": 95,
-    "confidence_warning": false,
-    "direction": { "signal": "bullish", "probability": 0.73 },
-    "summary": {
-      "mean_close": 27.05,
-      "range_low": 25.80,
-      "range_high": 28.30,
-      "range_width": 2.50
-    },
-    "bands": [
-      {
-        "date": "2026-03-14",
-        "step": 1,
-        "mean_close": 26.88,
-        "trading_low": 26.20,
-        "trading_high": 27.55,
-        "uncertainty": 0.0504
-      }
-    ]
-  }
+  "total": 3,
+  "done": 3,
+  "failed": 0,
+  "tasks": [
+    {
+      "task_id": "aaa...",
+      "status": "done",
+      "result": { ... },
+      "error": null
+    }
+  ]
 }
 ```
 
-`status` is one of `"pending"` / `"done"` / `"failed"`.
+| `status` | 含义 |
+|---|---|
+| `pending` | 仍有子任务在计算 |
+| `done` | 全部成功 |
+| `partial` | 部分成功、部分失败 |
+| `failed` | 全部失败 |
 
 ---
 
-### `GET /health`
+### `GET /api/v1/cache` — 查看缓存状态
+
+列出有效缓存条目及剩余 TTL。
+
+| 参数 | 说明 |
+|---|---|
+| `ts_code`（可选） | 只返回该股票的缓存，不传则返回全部 |
+
+```bash
+# 查某只股票
+curl "https://yingfeng64-kronos-api.hf.space/api/v1/cache?ts_code=000063.SZ"
+
+# 查全部
+curl "https://yingfeng64-kronos-api.hf.space/api/v1/cache"
+```
+
+```json
+{
+  "count": 1,
+  "entries": [
+    {
+      "ts_code": "000063.SZ",
+      "lookback": 512,
+      "pred_len": 5,
+      "sample_count": 30,
+      "mode": "simple",
+      "include_volume": false,
+      "cached_at": "2026-03-16 10:23:00 UTC+08:00",
+      "expires_at": "2026-03-16 15:00:00 UTC+08:00",
+      "ttl_seconds": 17220
+    }
+  ]
+}
+```
+
+---
+
+### `GET /health` — 健康检查
 
 ```json
 { "status": "ok" }
@@ -99,9 +266,42 @@ Poll for results.
 
 ---
 
-## Notes
+## 响应字段说明
+
+| 字段 | 含义 |
+|---|---|
+| `base_date` | 预测所基于的最后一个历史 K 线日期 |
+| `direction.signal` | `"bullish"` / `"bearish"`，MC 样本中末日收盘价 > 当前收盘的比例决定 |
+| `direction.probability` | 看涨概率（0–1） |
+| `trading_low` | 该日预测最低价的 q2.5 分位数（95% 交易区间下沿） |
+| `trading_high` | 该日预测最高价的 q97.5 分位数（95% 交易区间上沿） |
+| `uncertainty` | `(trading_high − trading_low) / last_close`，无量纲不确定性 |
+| `confidence_warning` | `pred_len > 30` 时为 `true`，表示预测不确定性较大 |
+| `cached` | 结果是否来自缓存 |
+| `cache_expires_at` | 缓存失效时间（北京时间） |
+
+---
+
+## 缓存机制
+
+缓存 key 由 `(ts_code, lookback, pred_len, sample_count, mode, include_volume)` 六元组构成，失效时机为下一个 A 股交易日收盘（15:00 CST）。
+
+| 请求时间（CST） | 缓存过期时间 |
+|---|---|
+| 工作日 00:00–15:00 | 当日 15:00 CST |
+| 工作日 15:00 后 | 次个工作日 15:00 CST |
+| 周末 | 下周一 15:00 CST |
+| 法定节假日 | 不特殊处理（节假日无新数据，缓存命中结果正确） |
+
+缓存命中时响应时间 < 100ms，无需等待模型推理。
+
+---
+
+## 性能参考
+
+| 环境 | 单次采样 | 30 次 MC 总耗时 |
+|---|---|---|
+| RTX 3090 (CUDA) | ~230ms | ~7s |
+| CPU only | ~3–5s | ~2–5min |
 
-- **Direction signal**: based on the last predicted close vs. the last historical close across all MC samples.
-- **95 % trading band**: `trading_low` = q2.5 of daily predicted lows; `trading_high` = q97.5 of daily predicted highs.
-- **`confidence_warning: true`** when `pred_len > 30` (model uncertainty grows significantly beyond ~30 days).
-- CPU inference: ~3–5 s/sample → 30 samples ≈ 2–5 min. Consider selecting GPU hardware for production use.
+> 推荐选用 GPU 硬件以获得实用响应速度。首次冷启动需从 HuggingFace Hub 下载模型权重，约需 1–2 分钟。