⚙️ 运行环境契约（最高优先级，先于本文其余内容执行）
本技能可能运行在 QuantBot（QwenPaw 容器） 或宿主机/本地 Claude Code。执行前先探测环境（which docker、API 连通性），并遵守以下映射规则：
- 后端 API 地址：QwenPaw / 容器网络内一律用
http://quantmind:8000（quantmind 是 docker 网络别名）；仅宿主机调试用 http://127.0.0.1:8000。正文中出现的 127.0.0.1:8000、localhost:800x，在 QwenPaw 环境下自动替换为 http://quantmind:8000。
- 取数脚本执行：凡 import 了
pandas / duckdb / psycopg2 / numpy / sqlalchemy 等重依赖或 backend 包的脚本，必须在 quantmind 容器内执行（QwenPaw 本地 venv 无这些依赖）：docker cp <脚本路径> quantmind:/tmp/<脚本名> && docker exec -w /app quantmind python3 /tmp/<脚本名> <参数>
脚本源三选一：宿主机 repo skills/<name>/scripts/、QwenPaw 工作区 /app/working/workspaces/default/skills/<name>/scripts/、挂载目录 /quantmind/skills/<name>/scripts/。纯标准库脚本（无重依赖）可在 QwenPaw 本地直接跑。
- 报告落盘：股票报告页可见的 MD/PDF 报告，直接写
/data/reports/trading_agents/{市场或类别}/{股票名}/（QwenPaw 对 /app/db 有写权限，直接写文件，不要 docker cp）；过程数据 facts 写 /data/reports/<类别>/（/data 可写）。
- MD → PDF 转换（按优先级降级）：
①
docker exec -w /app quantmind python3 backend/scripts/md_to_pdf_report.py <输入.md> <输出.pdf>（研报级排版，首选）；
② docker 不可用时，改用 QwenPaw 内置 pdf 技能把 MD 转成 PDF；
③ 两者都不可用则只交付 MD，并明确告知用户 PDF 未能生成及原因。
- 本文中的
~/.claude、cp -r ... ~/.claude/skills 等说明仅适用于本地 Claude Code 维护者，QuantBot 不要执行。
quantdb-fields — QuantDB 字段单位速查手册
用 QuantDB 数据做任何分析/回测/报告前必读。所有单位均为
2026-08 直接读本地 parquet 实测验证（不是照抄文档）。
单位搞错的后果：成交额差 1 万倍、股息率差 100 倍、换手率差 100 倍——
分析结论全部作废。
一、通用规则（先记这个）
| 规则 |
说明 |
| 个股成交量 = 股 |
A 股 1 手 = 100 股，但 QuantDB 个股 kline 的 volume 单位就是股，不是手 |
| 个股成交额 = 万元 |
amount = 5828.37 表示 5828.37 万元（约 5828 万），不是元 |
| 指数成交量 = 手 |
index_daily.volume 单位是手（1 手 = 100 股），与个股相反！ |
| 市值 = 元 |
valuation 的 total_mv/float_mv 单位是元（工业富联 float_mv ≈ 1.31 万亿） |
| 比例字段 ≈ 小数或 % |
没有统一约定，按数据集查下表；% 的字段值 = 百分数（4.06 即 4.06%） |
| symbol 格式按数据源分 |
parquet 用后缀 601138.SH；PG 的 stock_daily_latest 用前缀 SH601138 |
| 验证公式 |
个股 close*volume/amount ≈ 1e4（股+万元）；指数 ≈ 2e4（手+万元） |
二、1_kline_data 日线（daily_forward / daily_backward / daily_unadjusted）
| 字段 |
单位 |
实测依据 |
volume |
股 |
601138 20260814 volume=4704920 股，amount=5828.37 万元，close*volume/amount≈1e4 |
amount |
万元 |
同上（close 66.19 × 470 万股 ≈ 3.1 亿 ≈ 31163 万元，与 amount 同量级吻合） |
open/high/low/close |
元（forward=前复权，backward=后复权，unadjusted=不复权） |
|
| 单位切换传闻 |
不存在。20260721 前后 amount 均为万元、volume 均为股。曾有记忆说 20260721 切换到"手/元"，实测已无此切换，按股/万元统一处理 |
|
min1/min5：同单位（volume=股、amount=万元），但数据停滞在 2026-07-24，用前先查最新日期。
三、L2 原始逐笔与十档盘口（1_kline_data/l2_data + tick_data，2026-08 新增）
万得(Wind) L2 数据，backend/scripts/wind_l2_import.py 从逐日 7z 压缩包（20260511.7z）导入。
当前实测只有 1 个交易日 20260511（order 1950 + trade 1721 = 3671 文件，部分标的仅其一），
用前先查日期覆盖：ls data/quantdb/1_kline_data/l2_data/ | grep -oE '[0-9]{8}' | sort -u。
文件命名：order_{code}_{date}.parquet / trade_{code}_{date}.parquet，code 为下划线格式
000001_SZ（对应后缀 000001.SZ）。time 单位统一为 UTC 毫秒（万得 hhmmssmmm 转 UTC，
北京 09:15:00 = 01:15:00 UTC），覆盖 09:15 集合竞价到 15:00 收盘。
逐笔委托 order_
| 字段 |
单位/格式 |
说明 |
time |
UTC ms |
09:15 集合竞价 → 15:00 收盘 |
order_id |
int |
交易所委托号（可与 trade_.ask_order_id/bid_order_id 配对） |
channel |
str |
委托编号 |
order_type |
str |
'0'=普通委托、'U'=撤单、'1'=其余 |
direction |
str |
'B'=买 / 'S'=卖 |
price |
元 |
万得 ×10000 → 元（已归一）；集合竞价未定价委托 price=0 |
volume |
股 |
|
逐笔成交 trade_
| 字段 |
单位/格式 |
说明 |
time |
UTC ms |
同上 |
trade_id |
int |
成交编号 |
trade_type |
str |
'C'=集合竞价成交 / '0'=连续竞价 |
direction |
str |
'B'/'S'/' '（集合竞价段=空格） |
price |
元，未复权 |
与 daily_unadjusted 对齐（实测 000001.SZ 20260511 末笔 11.28 = unadjusted close 11.28）；与 daily_forward 前复权 close 有除权差（有分红送转者差数十%） |
volume |
股 |
⚠️ 沪≈日线量、深≈2×日线量（见坑1） |
ask_order_id / bid_order_id |
int |
叫卖/叫买序号 → 配对逐笔↔委托 |
tick_data 十档盘口快照（18 列）
| 列 |
单位 |
说明 |
lastPrice/open/high/low/lastClose |
元 |
|
amount |
混源 |
⚠️ 见坑2 |
volume |
混源 |
当日累计成交量 |
pvolume |
笔 |
连续竞价成交笔数（wind 导入有值）；旧导入=0（可作来源判据） |
askPrice/bidPrice |
array(10) |
十档价，元 |
askVol/bidVol |
array(10) |
十档量，股 |
stockStatus |
int |
BS 标志 |
openInt/settlementPrice/lastSettlementPrice |
— |
期货占位字段，A股多为 0 |
⚠️ 三个必踩的坑
- 沪/深成交量双口径：逐笔成交 volume 求和，沪 SH = 日线 volume（实测 600714.SH 求和 34825501≈日线 34825500）；
深 SZ ≈ 1.8~2.1× 日线 volume（实测 002830 1.92×、300521 2.11×、000999 1.79×、000001 1.88×）。
→ 逐笔求和不能当当日成交量，深市除 ~2 或直接与日线对账。
- tick_data 单位混源：同一目录内单位不统一——wind_l2_import 导入的（如 20260511）volume=股、amount=万元；
更早 QuantDB tick 同步的（如 20260720）volume=手、amount=元。
实测：20260511 最后快照 volume 93186521≈日线 93186520 股、amount 104743.53≈104743.54 万；
20260720 volume 1567304 手×100=156730400 股、amount 1713460189 元=171346.02 万。
→ 用前必须拿最后一条快照对账日线，或按
pvolume（0=旧/手·元，>0=wind/股·万元）区分。
- 价格=未复权真实成交：有除权除息时与前复权日线差一个复权因子
（实测 002830.SZ 20260511 L2 末笔 24.08 vs 前复权 close 17.06）；算收益需先统一复权口径。
导入命令（手动增量，不吃 quantdb_daily_sync）
python backend/scripts/wind_l2_import.py --archive /path/to/20260511.7z # 全市场
python backend/scripts/wind_l2_import.py --archive ... --symbols 000001.SZ,600519.SH # 指定标的
python backend/scripts/wind_l2_import.py --archive ... --force # 覆盖重导
文件名即日期（20260511.7z → 20260511），流式逐股解压导入、可断点续跑（已存在三件套自动跳过）。
容器内 7z 默认 /opt/p7zip-legacy/bin/7z，数据目录自动探测 /data/quantdb 或本地 data/quantdb。
四、1_kline_data/index_daily 指数日线（⚠️ 与个股相反）
| 字段 |
单位 |
实测依据 |
volume |
手（×100=股） |
上证 000001.SH 20260814 volume=499525600 手 = 499.5 亿股（合理）；close*volume/amount=19808≈2e4 |
amount |
万元 |
99037192 万元 = 9903.7 亿元 ≈ 上证单日成交额 ✓ |
close |
点位 |
3927.18 |
反推：指数平均股价 = close×100/(close×volume/amount) = close×100/19808 ≈ 19.8 元/股，符合 A 股平均股价，故 volume 必为手。
五、5_technical_derived 技术衍生
valuation（估值）
| 字段 |
单位 |
注意 |
close |
元，不复权 |
601138 close=66.19（与 technical_indicators 的后复权 close=70.05 不同） |
total_mv / float_mv |
元 |
float_mv=1313480468277.96 ≈ 1.31 万亿 ✓ |
total_capital / circulating_capital |
股 |
19844092284 股 ≈ 198.4 亿股 |
net_profit_ttm / revenue_ttm / equity / annual_net_profit |
元 |
|
pe_ttm / pe_static / pb / ps_ttm |
倍 |
|
dividend_rate |
%（百分数值） |
0.148 = 0.148%！公式 = 近一年每10股派息/10/close×100。601138: 0.98/10/66.19×100=0.1481 ✓；600519: 51.98/10/1341.99×100=0.3873 ✓。把它当小数会差 100 倍 |
dividend_rate 口径切换 |
20260814 起 |
此前为小数口径（每10股派息/不复权close，如 0.98/65.60=0.01494）；20260814 起切换为百分数口径（×100）。同字段历史不连续，跨 20260814 分析需 ×10 归一 |
technical_indicators（技术指标）
| 字段 |
单位 |
陷阱 |
close |
后复权 |
601138=70.05，与不复权 66.19 不同；凡基于 close 算的指标都是后复权口径 |
volume_ma_3/5 |
股 |
|
amount_ma_5 |
万元 |
|
pct_change |
% |
1.4717 = 1.47% |
return_1d / return_20d |
缺失（NaN） |
别用，改用 pct_change |
vol_std_20 |
% |
4.0578 = 4.06%（l1 里同名字段是小数 0.0406，差 100 倍！） |
vol_atr_14 |
元 |
3.58 元（l1 同名字段也是元，一致） |
macd_hist / rsi_14 / kdj_* |
原始指标值 |
与 l1 一致 |
market_sentiment（市场情绪）
| 字段 |
单位 |
close |
不复权 |
turnover_rate 等比率 |
小数（0.02 = 2%） |
momentum_* |
%（百分数值） |
六、6_ml_datasets 因子
features_daily（技术+估值合并表，78 列，2026-09 起新增 30 列）
基础 46 个数值列单位与 technical_indicators / valuation 一致；新增 30 列全部以字符串存储，用前先转数值：
| 字段 |
单位 |
实测/注意 |
dividend_rate |
小数口径（无 ×100） |
与 valuation 不同！公式 = 每10股派息/不复权close（0.98/66.19=0.0148），从未切换口径。valuation 20260814 起是它的 10 倍。特征快照 generate_feature_snapshots.py 已 ×10 归一到百分数口径 |
total_mv / float_mv / pe / pb 等 |
与 valuation 完全一致 |
实测 601138 全部 ✓ |
total_cap_yi / float_mv_yi |
亿元 |
实测 ×1e8/total_mv=1.000、×1e8/float_mv=1.000（与本表 total_mv/float_mv（元）差 1e8） |
free_float_shares |
万股（自由流通股本） |
×1e4 转股；000001.SZ=816056.58 万股≈81.6 亿股（自由流通 < 流通股本，勿与 circulating_capital 混用） |
hs_turnover |
%（换手率） |
如 0.43 / 1.71，max≈76 |
zaf |
%（当日涨跌幅） |
与 pct_change 高度一致（corr=0.986，-0.93 vs -0.928） |
seal_strength |
无量纲（封板强度，≈1.0 封住） |
如 1.02 |
ever_zt_count / year_zt_days |
计数（整数） |
曾涨停次数 / 年内涨停天数 |
ipo_price |
元 |
发行价 |
zt_price / dt_price |
元（基于不复权价） |
涨停价/跌停价；⚠️ 与表内前复权 close 不同口径（勿直接比；000001.SZ: zt=13.04/dt=10.67 vs 前复权 close=18.16） |
beta_now |
无量纲（beta） |
与 beta_20 corr≈0.71（窗口/口径不同） |
dyna_pe / static_pe_ttm |
倍 |
⚠️ 含负哨兵（实测 -686 / -897），亏损股勿直接用 |
div_yield |
%（百分数值） |
5.14=5.14%；与本表 dividend_rate（小数 0.0508）差 100 倍 |
pb_mrq |
倍 |
≈pb（pb_mrq/pb median=1.000） |
list_date |
字符串 YYYYMMDD |
如 '19910403' |
industry_code / industry_name |
字符串 |
128 细分行业（X5001 / 全国性银行） |
sector_code |
字符串 |
如 881386 |
region_area_code / region_area_name |
字符串 |
32 地区板块（18 / 深圳板块） |
main_business |
中文文本 |
主营业务 |
in_hs300 / is_hsgt / is_margin / is_kcb_creatable / is_st / is_quit_risk / is_hk |
字符串 '0'/'1' |
标记位（转 int 后再过滤/统计） |
l1_factors（一级因子，decimal 为主）
| 字段 |
单位 |
收益率类 mom_ret_* |
小数（0.0147 = 1.47%） |
vol_std_* |
小数（0.0406 = 4.06%；与 technical_indicators 的 % 版本差 100 倍） |
vol_atr_14 |
元（3.55 元） |
fun_total_mv |
ln(市值元) —— 用时要 exp() |
| 分位数/percentile 字段 |
0~1 小数 |
liq_* / fun_turnover / fun_mv |
部分日期为 None，注意补缺 |
l2_factors（二级因子，flow 金额注意）
| 字段 |
单位 |
实测依据 |
flow_net_amount / flow_super_net / flow_large_net / flow_medium_net / flow_small_net |
元 |
600519 flow_net_amount=-274109797.7 元 = -2.74 亿；flow_net_amount/(amount×1e4)=flow_net_ratio ✓ |
flow_*_ratio |
小数 |
|
vol_turnover_total |
股 |
与 kline volume 完全相等 ✓ |
| 分区 |
已恢复日更（2026-08-19 实测至 20260818，flow_net 5098 distinct 有区分度） |
⚠️ 此前「停更 2026-02-27」结论过时；top 少数几只净流入会厂商同值（如 165564181），属口径非 bug |
七、PG 表 stock_daily_latest（API 服务数据源）
| 列 |
单位 / 格式 |
实测依据 |
symbol |
前缀格式 SH601138（不是 601138.SH） |
suffix 查询 0 行，prefix 查询 1072 万行 |
volume |
股 |
601138 max_volume=633217088 股 |
amount |
万元 |
601138 amount=5828.37，max_amount=3306339（万元） |
float_mv / total_mv |
元 |
float_mv=7095151630 元 |
turnover_rate / flow_net_amount / main_flow |
NULL（未灌） |
风险评分里"缺少换手率"由此而来 |
volume_ratio_5 |
倍（0.934） |
|
flow 灌入口径（update_sdl_complete_pipeline.py）：main_flow = flow_large_net_amount/1e6（百万元），flow_net_amount = flow_net_amount/1e6（百万元）——与 l2 parquet 的元不同，读 PG 时注意。
八、research API 换算表（/research/features 等接口返回）
API 层 _UNIT_SCALES 把部分字段缩放后输出：
| 输出字段 |
缩放 |
输出单位 |
例（600519 探针） |
totalMv / floatMv |
×1e-8 |
亿元 |
16775.97 亿 ✓ |
mainFlow / flowNetAmount / flowLargeNet / flowMediumNet / flowSmallNet |
×1e-6 |
百万元 |
flow_net_amount=-274.11（百万） |
flowSuperNet |
无缩放 |
元（bug！） |
flow_super_net=-6840376 元，与同类别其他字段差 1e6 |
turnoverRate |
— |
% 小数 |
0.00239 |
⚠️ fundFlow 类别内单位不一致：flowSuperNet 是元，其余 flow* 是百万元。skill 分析时要统一换算后再比。
九、3_financial_data 财务数据
| 数据集 |
字段 |
单位 |
balance / income / cashflow |
各科目 |
元 |
capital |
股本 |
股 |
holder_num |
股东户数 |
户 |
dividend_factors |
interest |
每10股派息（元）——600519 每10股派 51.98 元，601138 派 0.98 元。算每股股息要 /10 |
dividend_factors |
stockBonus / stockGift / allotNum |
每10股送/转/配股数 |
dividend_factors |
dr |
除权因子（复权用） |
十、2_base_sector
| 数据集 |
字段 |
单位 |
注意 |
instrument_detail |
Symbol |
后缀 601138.SH |
HqDate 停滞 20260720，市值/估值滞后 |
|
J_zgb / FreeLtgb |
万股（1984409.25 万股 = 198.4 亿股） |
与 valuation 的 circulating_capital(股) 差 1e4 |
|
J_yysy / J_jly / J_zzc 等 J_* |
万元（25107808 万 = 251 亿） |
与 financials 的元差 1e4 |
|
Zsz / Ltsz |
亿元（11211.91 亿 ✓） |
|
|
J_mgsy |
元（2.14 元/股） |
|
|
fHSL |
不明（0.56，非换手率%，与自算 0.74% 不符），别当换手率用 |
|
|
TotalBVol |
不明（43555，量级像手，但远小于全天量） |
L2 快照字段，非全天 |
|
DYRatio |
不可靠（600519=4.15 vs 真实 0.39%），别当股息率，用 valuation.dividend_rate |
|
|
Yield |
不明（6078.44），勿用 |
|
index_weights |
Weight |
% |
文件名 000300.SH.parquet 不是 000300.parquet |
trading_calendar |
TradingDate |
YYYYMMDD int |
|
十一、其他数据集
| 数据集 |
字段 |
单位 |
状态 |
margin_trading |
finance_* |
万元 |
|
|
slo_volume / slo_net |
股 |
|
hsgt_north |
holding_quantity 股 / holding_value 元 / 比率 % |
|
停滞 2024-08（北向改季度披露后） |
十二、已知数据缺口（2026-08 实测）
- min1/min5 分钟线停更（最新 2026-07-24）
l2_factors 分区停更 —— 已恢复（2026-08-19 实测至 20260818）- hsgt_north 北向明细停更（2024-08，改季度披露所致）
- instrument_detail HqDate 滞后（20260720）
- dt=20260729~20260802 个股日线有同步缺口（非交易日+同步中断）
5b. valuation dt=20260813 只有 101 行（同步缺口，dividend_rate 全 NaN），features_daily 同日 5543 行正常
- technical_indicators.return_1d/return_20d 全 NaN
- stock_daily_latest 的 turnover_rate/flow_net_amount/main_flow 常为 NULL
- l2_data 原始逐笔仅 20260511 单日 —— 万得按日 7z 手动导入（
wind_l2_import.py），非自动日更
- tick_data 单位混源 —— wind=股/万元，旧同步=手/元，对账前勿直接用
十三、分析前检查清单
qusong0627