⚙️ 运行环境契约（最高优先级，先于本文其余内容执行）

本技能可能运行在 QuantBot（QwenPaw 容器） 或宿主机/本地 Claude Code。执行前先探测环境（which docker、API 连通性），并遵守以下映射规则：

1. 后端 API 地址：QwenPaw / 容器网络内一律用 http://quantmind:8000（quantmind 是 docker 网络别名）；仅宿主机调试用 http://127.0.0.1:8000。正文中出现的 127.0.0.1:8000、localhost:800x，在 QwenPaw 环境下自动替换为 http://quantmind:8000。
2. 取数脚本执行：凡 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 本地直接跑。
3. 报告落盘：股票报告页可见的 MD/PDF 报告，直接写 /data/reports/trading_agents/{市场或类别}/{股票名}/（QwenPaw 对 /app/db 有写权限，直接写文件，不要 docker cp）；过程数据 facts 写 /data/reports/<类别>/（/data 可写）。
4. MD → PDF 转换（按优先级降级）： ① docker exec -w /app quantmind python3 backend/scripts/md_to_pdf_report.py <输入.md> <输出.pdf>（研报级排版，首选）； ② docker 不可用时，改用 QwenPaw 内置 pdf 技能把 MD 转成 PDF； ③ 两者都不可用则只交付 MD，并明确告知用户 PDF 未能生成及原因。
5. 本文中的 ~/.claude、cp -r ... ~/.claude/skills 等说明仅适用于本地 Claude Code 维护者，QuantBot 不要执行。

quantdb-fields — QuantDB 字段单位速查手册

用 QuantDB 数据做任何分析/回测/报告前必读。所有单位均为 2026-08 直接读本地 parquet 实测验证（不是照抄文档）。 单位搞错的后果：成交额差 1 万倍、股息率差 100 倍、换手率差 100 倍—— 分析结论全部作废。

一、通用规则（先记这个）

二、1_kline_data 日线（daily_forward / daily_backward / daily_unadjusted）

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_

逐笔成交 trade_

tick_data 十档盘口快照（18 列）

⚠️ 三个必踩的坑

1. 沪/深成交量双口径：逐笔成交 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 或直接与日线对账。
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/股·万元）区分。
3. 价格=未复权真实成交：有除权除息时与前复权日线差一个复权因子 （实测 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 指数日线（⚠️ 与个股相反）

反推：指数平均股价 = close×100/(close×volume/amount) = close×100/19808 ≈ 19.8 元/股，符合 A 股平均股价，故 volume 必为手。

五、5_technical_derived 技术衍生

valuation（估值）

technical_indicators（技术指标）

market_sentiment（市场情绪）

六、6_ml_datasets 因子

features_daily（技术+估值合并表）

l1_factors（一级因子，decimal 为主）

l2_factors（二级因子，flow 金额注意）

七、PG 表 stock_daily_latest（API 服务数据源）

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 把部分字段缩放后输出：

⚠️ fundFlow 类别内单位不一致：flowSuperNet 是元，其余 flow* 是百万元。skill 分析时要统一换算后再比。

九、3_financial_data 财务数据

十、2_base_sector

十一、其他数据集

十二、已知数据缺口（2026-08 实测）

1. min1/min5 分钟线停更（最新 2026-07-24）
2. l2_factors 分区停更 —— 已恢复（2026-08-19 实测至 20260818）
3. hsgt_north 北向明细停更（2024-08，改季度披露所致）
4. instrument_detail HqDate 滞后（20260720）
5. dt=20260729~20260802 个股日线有同步缺口（非交易日+同步中断） 5b. valuation dt=20260813 只有 101 行（同步缺口，dividend_rate 全 NaN），features_daily 同日 5543 行正常
6. technical_indicators.return_1d/return_20d 全 NaN
7. stock_daily_latest 的 turnover_rate/flow_net_amount/main_flow 常为 NULL
8. l2_data 原始逐笔仅 20260511 单日 —— 万得按日 7z 手动导入（wind_l2_import.py），非自动日更
9. tick_data 单位混源 —— wind=股/万元，旧同步=手/元，对账前勿直接用

十三、分析前检查清单

• 确认数据源是 parquet 还是 PG/API（单位体系不同）
• symbol 格式匹配数据源（parquet 后缀 / PG 前缀）
• 成交量：个股=股，指数=手
• 成交额：万元（API 输出已缩放为亿/百万）
• 波动率：technical_indicators 是 %，l1 是小数（差 100 倍）
• 股息率：valuation.dividend_rate 是 % 百分数值（0.148=0.148%），不是小数
• close 口径：technical_indicators 是后复权，valuation 是不复权
• 市值：parquet 是元，instrument_detail 是亿元/万股，API 是亿元
• 财务：financials 是元，instrument_detail J_* 是万元
• 用前查数据最新日期（分钟线、l2、hsgt 都可能已停更）
• L2 原始逐笔（l2_data）：先查日期覆盖（当前仅 20260511 单日），价格是未复权，逐笔求和沪≈日线量/深≈2×，别当成交量
• tick_data：先拿最后一条快照对账日线（wind=股/万元 vs 旧同步=手/元，单位混源）