这是什么
量化研究的第一公里：一条命令，把 A 股数据变成本地规范 CSV。基于 BaoStock（证券宝）免费数据源，输出列名标准化（date/open/high/low/close/volume），拿来即用。
解决什么问题
- 各数据接口返回格式混乱（字符串数字、日期格式不一），每次都要写清洗代码
- 回测工具对数据格式有要求，二次加工费时
- 免费源常遇登录失效、断线，脚本一跑就断
核心能力
- 全品种数据：K线（日/周/月/分钟，前复权/后复权/不复权）、季频财务（盈利/成长/营运/偿债/现金流/杜邦）、指数成分（上证50/沪深300/中证500）、全市场证券列表、交易日历
- 自动标准化：字符串转数值、pandas 2.0 兼容、登录静默、断线重连
- 与回测技能直连：输出列名与《析衡量化·Vibe Trading 自然语言回测》直接对接，无需二次清洗
- 离线演示模式：未安装 baostock 或无网络时也能跑通全流程（演示数据）
快速开始（示例指令）
- "下载贵州茅台2020年至今的日线数据，前复权"
- "把沪深300成分股列表存成CSV"
- "取沪深300成分股最近三年的周线，喂给回测"
常见问题
Q: 需要付费数据账号吗？
不需要，基于 BaoStock 免费接口；安装 pip install baostock 即可。
Q: 没网/没装 baostock 会报错吗？
不会，自动进入离线演示模式，全流程可跑通，便于先验证用法。
Q: 下载中断了怎么办？
内置断线重连；重跑时已落盘的文件自动跳过，增量续传。
Q: 复权方式怎么选？
参数支持前复权/后复权/不复权；回测场景建议前复权。
更新日志
- v1.1.0：补齐详情页与 FAQ
- v1.0.1：Initial release
析衡量化 · 数据获取（xiheng-data-fetch）
把「我要数据」变成「已经在本地、格式正确、能直接回测的 CSV」。免费、无需 token，基于 BaoStock 证券数据平台。
描述需求 ──► 选择子命令 ──► 拉取/标准化 ──► CSV 落盘 ──► 直接喂给 xiheng-vibe-trading 回测
(口语化) (kline/…) (转数值·对齐列名) (本地缓存) (date,open,high,low,close,volume)
一、两分钟跑通
离线演示（不需要网络、不需要安装 baostock）
python scripts/xiheng_fetch.py demo --out-dir demo_data
生成 4 份确定性示例数据（3 只模拟股票日线 + 1 份指数基准），列结构与真实在线取数完全一致，用于验证管道、演示、教学。
在线取数（需先 pip install baostock）
# 1. 日线（后复权，回测口径）
python scripts/xiheng_fetch.py kline --codes sh.600519,sz.000001 \
--start 2020-01-01 --end 2026-09-19 --adjust 1 --out-dir data
# 2. 交易日历
python scripts/xiheng_fetch.py calendar --start 2026-01-01 --end 2026-12-31 --out calendar.csv
# 3. 沪深300 成分股
python scripts/xiheng_fetch.py members --index hs300 --out hs300.csv
# 4. 季频财务（盈利能力）
python scripts/xiheng_fetch.py financial --code sh.600519 --year 2025 --quarter 4 --kind profit --out profit.csv
# 5. 全市场证券列表（不传 --day 自动找最近交易日）
python scripts/xiheng_fetch.py stocks --out all_stocks.csv
二、子命令总表
| 子命令 | 作用 | 关键参数 | 输出 |
|---|---|---|---|
kline |
历史 K 线（股票/指数） | --codes 逗号分隔或 --codes-file 文件；--freq d/w/m/5/15/30/60；--adjust 1/2/3；--start/--end |
每只代码一个 CSV：sh_600519.csv |
calendar |
交易日历 | --start/--end |
calendar_date, is_trading_day |
stocks |
某交易日全部证券 | --day（缺省自动取最近交易日） |
code, tradeStatus, code_name |
members |
指数成分股 | --index hs300/sz50/zz500 |
code, code_name |
financial |
季频财务 | --code --year --quarter --kind profit/growth/operation/balance/cashflow/dupont |
对应指标字段 |
demo |
离线演示数据 | --out-dir |
3 股票 + 1 指数基准 CSV |
通用约定：日期一律 YYYY-MM-DD；代码格式 sh.600519 / sz.000001（交易所前缀.代码）；输出默认写到当前工作目录，不会写进 skill 目录；所有错误以中文提示 + 退出码 2 返回。
三、代码格式速查
| 市场 | 格式 | 示例 |
|---|---|---|
| 上交所 A 股 | sh.6xxxxx |
sh.600519 |
| 深交所主板 | sz.00xxxx |
sz.000001 |
| 创业板 | sz.30xxxx |
sz.300750 |
| 北交所 | bj.xxxxxx |
bj.430047 |
| 指数 | sh.000001(上证综指) sh.000300(沪深300) sh.000016(上证50) |
四、复权与频率口径（回测必读）
--adjust |
含义 | 用途 |
|---|---|---|
1 |
后复权 | 计算收益率、回测（推荐） |
2 |
前复权 | 看图、技术分析 |
3 |
不复权（默认） | 原始价格、核对除权事件 |
- 频率
d/w/m/5/15/30/60：指数只支持日/周/月，分钟线会返回空且不报错 --start不传时 BaoStock 默认从 2015-01-01 取；要更长历史必须显式传- 复权采用涨跌幅法，与通达信定点复权的绝对价格存在微小差异，跨平台对价注意口径
五、输出 CSV 规范与对接回测
kline 日线输出列：date, code, open, high, low, close, preclose, volume, amount, turn, pctChg, tradestatus, isST（分钟线为 date, time, code, open, high, low, close, volume, amount, adjustflag），数值列已自动 to_numeric，停牌日的空串已转 NaN。
对接 xiheng-vibe-trading：把 CSV 放好，直接
python <vibe-trading>/scripts/vibe_trade.py run --spec spec.json --data data/sh_600519.csv --html report.html
date/open/high/low/close/volume 列名即插即用；基准列写 benchmark（或单独基准 CSV）即可启用 Beta/Alpha/相关性分析。
六、十条实战坑（详见 references/baostock_api.md）
- 返回值全是字符串 → 本 skill 已自动转数值
- pandas ≥2.0 不能用
rs.get_data()→ 本 skill 已用手动逐行组装 start不传默认 2015-01-01 → 长历史显式传参- 回测务必后复权（
--adjust 1） - login/logout 会打印 → 本 skill 已静默
- 非线程安全 → 批量请用多进程，勿多线程共用连接
- 连接会过期 → 本 skill 已内置一次自动重登重试
- 指数无分钟线 → 返回空是正常现象
- 财务数据滞后 1～2 个月 → 财务因子按 pubDate 对齐防前视
- 高频拉取可能被限 IP（错误码 10001011）→ 批量下载控制节奏、增量更新
七、与同系列联动
> 本技能属于 析衡量化 系列，统一入口见 xiheng-quant-toolkit：
> series.py list 看系列全景，series.py route <场景> 定位技能，series.py chain <场景> 看整条调用链。
| 方向 | 技能 | 衔接方式 |
|---|---|---|
| 下游 | xiheng-vibe-trading 策略回测 |
产出的规范化行情 CSV 直接作为回测输入 |
| 下游 | xiheng-factor-orthogonalize 因子正交化 |
季频财务数据作为因子加工原料 |
| 上游 | — | 系列中的数据起点，无上游依赖 |
> 系列地图维护在 xiheng-quant-toolkit/assets/series.json；本技能在该地图中的条目（slug/stage/role/feeds/triggers）应保持同步。
八、离线自测（开箱即验）
python scripts/xiheng_fetch.py demo --out-dir demo_data # exit 0，生成 4 份 CSV
python scripts/xiheng_fetch.py demo --out-dir demo_data # 固定种子，两次输出逐字节一致
python scripts/xiheng_fetch.py kline --codes sh.600519 # 未装 baostock → 中文提示，exit 2
python scripts/xiheng_fetch.py members --index foo # 非法指数名 → 中文提示，exit 2
九、目录结构
xiheng-data-fetch/
├── SKILL.md # 本文件
├── scripts/
│ ├── xiheng_fetch.py # 主 CLI（6 个子命令）
│ ├── bs_client.py # BaoStock 会话封装（静默/重试/数值化）
│ └── make_sample_data.py # 离线演示数据生成器（固定种子）
├── references/
│ ├── baostock_api.md # BaoStock 全接口字段参考 + 坑位详解
│ └── pipeline.md # 数据管道与回测对接细节
└── assets/
└── codes_example.txt # 批量代码列表示例（--codes-file 用）
