期货投研 Skill（futures-research）

基于 iFinD + AKShare + blogwatcher + Wind 的期货单品种 / 跨品种投研 Agent skill。 按"七段"框架（真实合约 / 数据截止 / 方向判断(日线+分钟K) / 产业基本面分析(含品种产业链匹配) / 另类数据(持仓+新闻) / 判断准则(证据立场+失效条件)）生成研究报告。

本机环境（2026-08-03 实测）

• Python 单环境通吃：D:\PYScripts\VnpyEnv\Scripts\python.exe
• 已装依赖：akshare 1.18.46、pandas 2.3.3、matplotlib 3.10、WindPy
• 工作目录：D:\PYScripts\20260802FutureAgent\.codex\skills\futures-research
• 所有取数/绘图/报告脚本统一用上述 python 运行，不要再切换 hermes venv / anaconda

Python 环境变量（调用前必须确认）

本 skill 依赖大量第三方包（akshare / pandas / matplotlib / WindPy 等）， 安装或调用前必须先询问用户使用哪个 Python 虚拟环境。

• 本机默认：D:\PYScripts\VnpyEnv\Scripts\python.exe（已装 akshare 1.18.46、pandas 2.3.3、matplotlib 3.10、WindPy）
• 统一变量：$PYTHON，所有命令示例中的 $PYTHON 均指该路径
• 配置写入 skill_config.json 的 python_bin 字段；用户指定其他环境时改该字段
• 不要再用 python3 / D:\anaconda3\python.exe 等硬编码路径

确认流程（安装 skill 或调用 skill 前必做）

1. 询问用户本次使用哪个 Python 虚拟环境；用户未指定时读取 skill_config.json 的 python_bin
2. 检查该环境是否已装本次所需依赖：akshare / pandas / matplotlib / WindPy
3. 所有命令示例中的 $PYTHON 替换为该路径执行

skill_config.json 示例：

{
  "python_bin": "D:\\PYScripts\\VnpyEnv\\Scripts\\python.exe",
  "note": "本机 Python 虚拟环境；调用 skill 前请与用户确认，用户指定其他环境时改此字段。"
}

数据源配置（重点）

1. iFinD QuantAPI（日线 + 现货/基差/结算/持仓时序）

项目	配置
refresh_token 文件	futures-research\refresh_token.txt（已 gitignore，不会入库）
access_token 文件	自动写 futures-research\ifind_token.txt（约 7 天有效，可自动换）
有效期	refresh_token 约 1 个月；过期后须从同花顺客户端重新生成
获取方式	同花顺客户端「超级命令 → 工具 → refresh_token 查询」复制 JWT 长串

配置方法：

# 把 refresh_token（JWT 长串）写入
Set-Content -LiteralPath D:\PYScripts\20260802FutureAgent\futures-research\refresh_token.txt -Value "你的JWT长串" -NoNewline

取数命令（脚本会自动换 access_token，不要覆盖 refresh_token.txt）：

python references\ifind_fundamentals_ts.py `
  --token D:\PYScripts\20260802FutureAgent\futures-research\refresh_token.txt `
  --codes LC00.GFE:碳酸锂连续 `
  --start 2025-07-01 --end 2026-08-02 `
  --out data\lc_ifind_fundamentals.json --realtime

2. AKShare（免配置）

• VnpyEnv 已装 akshare，无需安装或登录
• 使用 lc_data_full.py / lc_daily_fetch.py / macro_fetch.py / intl_fetch.py 等直接取数
• 网络受限时需提权联网（沙箱默认禁止外网）

3. blogwatcher-cli（新闻，SSH 镜像到本机）

项目	配置
远端主机	jack-lin-sparrow@100.103.212.99（Tailscale 可达）
远端库	/home/jack-lin-sparrow/.blogwatcher-cli/blogwatcher-cli.db（SQLite，13 源，2.4 万篇）
本机缓存	data\cache\blogwatcher-cli.db（scp 拉取）
SSH 私钥	futures-research\.ssh\blogwatcher_ed25519（无口令；.gitignore 已排除 .ssh/）
检索脚本	references\news_search_blogwatcher.py

首次配置（把公钥追加到 Ubuntu）：

type "D:\PYScripts\20260802FutureAgent\.codex\skills\futures-research\.ssh\blogwatcher_ed25519.pub" | ssh jack-lin-sparrow@100.103.212.99 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

使用命令（--refresh 先拉最新库，再本地检索）：

python references\news_search_blogwatcher.py --refresh --days 30 --max-hits 60 `
  --keyword 碳酸锂 --keyword 锂 --keyword 电池 --keyword 新能源 --keyword 广期所 `
  --keyword 消费税 --keyword 排产 --keyword 减产 `
  --out data\lc_news_blogwatcher.json

4. Wind（WindPy，半自动）

项目	配置
连接条件	Wind 终端打开并登录；VnpyEnv 已装 WindPy
自动化限制	⚠️ Codex CLI 运行在独立 Windows 账户 CodexSandboxOffline，WindPy 借终端会话不能跨用户，w.start() 恒报 Login Failed
解法	Agent 生成取数脚本（范式见 fix\wind_fetch_for_report.py），由用户在本人 PowerShell 会话执行一行命令，Agent 再读产出 JSON

Wind 取数脚本路径：fix\wind_fetch_for_report.py，输出 data\lc_wind_update_20260802.json。

5. SHMET 新闻（降级备份）

• 免配置：references\news_fetch_shmet.py
• 追加合并模式：默认合并进 data\lc_news_shmet.json（档案上限 200 条），防止覆盖式重跑丢新闻

具体使用方法（完整流程）

以下命令在 futures-research 目录下用 VnpyEnv python 执行。

# 1. 日线 OHLCV（AKShare 新浪主力连续）
python references\lc_daily_fetch.py --symbol lc0 --start 2024-01-01 --end 2026-08-02 --out data\lc_daily.json

# 2. 全量基本面：持仓/仓单/分钟线/期限结构/基差快照（AKShare）
python references\lc_data_full.py --date 2026-07-31 --variety 碳酸锂 --start 2026-07-01 --out data\lc_20260731.json

# 3. iFinD 现货/基差/结算/持仓时序（需 refresh_token）
python references\ifind_fundamentals_ts.py --token D:\PYScripts\20260802FutureAgent\futures-research\refresh_token.txt --codes LC00.GFE:碳酸锂连续 --start 2025-07-01 --end 2026-08-02 --out data\lc_ifind_fundamentals.json --realtime

# 4. 新闻（blogwatcher 优先；SHMET 可作备份）
python references\news_search_blogwatcher.py --refresh --days 30 --max-hits 60 --keyword 碳酸锂 --keyword 锂 --keyword 电池 --keyword 新能源 --keyword 广期所 --keyword 消费税 --keyword 排产 --keyword 减产 --out data\lc_news_blogwatcher.json

# 5. 宏观 + 国际（免登录）
python references\macro_fetch.py --out data\macro.json
python references\intl_fetch.py --out data\intl.json

# 6. 基差时序（AKShare 生意社通道；iFinD 通道已由第 3 步覆盖）
python references\basis_ts_fetch.py --variety 碳酸锂 --days 60 --cache-dir data\cache --out data\lc_basis_ts.json --img images\lc_basis_20260802.png

# 7. Wind（半自动：用户本人 PowerShell 运行一行）
D:\PYScripts\VnpyEnv\Scripts\python.exe D:\PYScripts\20260802FutureAgent\fix\wind_fetch_for_report.py

# 8. 生成七段报告（默认自动读 blogwatcher 新闻；可用 --out 指定输出）
python references\generate_lc_report.py --date 2026-08-02

报告结构

段	内容	来源
1	研究标的 + 真实合约识别	品种映射表
2	数据截止时间	元信息
3	方向判断（3.1 日线 + 3.2 期限结构 + 3.3 分钟K）	iFinD QuantAPI + AKShare
4	产业基本面分析（4.0 产业链速查 + 4.1-4.8 供需/库存/利润/期现/宏观）	Wind EDB + AKShare + blogwatcher
5	另类数据（持仓 + 新闻）	AKShare + blogwatcher
6	判断准则（证据立场 + 失效条件）	综合第 3-5 段推导

目录

futures-research/
├── SKILL.md                      # skill 主文档（七段模板 + 取数流程 + 品种产业链速查）
├── README.md                     # 本文件（环境 + 数据源配置 + 使用流程）
├── .ssh/                         # SSH 密钥（blogwatcher 拉取用，gitignore，绝不入库）
├── references/
│   ├── ifind_mcp_fetch.py        # iFinD QuantAPI 日线取数（refresh→access）
│   ├── ifind_fundamentals_ts.py  # iFinD 现货/基差/结算/持仓时序 + 实时快照
│   ├── lc_data_full.py           # 碳酸锂一键全量（持仓/仓单/分钟/期限结构/基差）
│   ├── lc_daily_fetch.py         # 日线 OHLCV（AKShare 新浪源）
│   ├── generate_lc_report.py     # 七段报告生成器（blogwatcher 新闻优先）
│   ├── macro_fetch.py            # 宏观：PMI/M2/CPI/美元指数
│   ├── intl_fetch.py             # 国际：LME 库存 + CFTC 持仓
│   ├── basis_ts_fetch.py         # 基差时序：逐日回刷+缓存+走势图
│   ├── news_fetch_shmet.py       # 新闻：SHMET 快讯（备份）
│   ├── news_search.py            # 旧版 blogwatcher 新闻检索（grep md，Linux）
│   ├── news_search_blogwatcher.py # 新版 blogwatcher SQLite 检索（SSH+scp，主力）
│   └── rolling_corr_plot.py      # 跨品种滚动相关性图
├── scripts/
│   └── gen_report_pdf.py         # PDF 排版（一次性脚本，勿用于新日期）
├── data/cache/                   # 本地缓存（blogwatcher db 等）
├── .env.example                  # 环境变量样例（复制为 .env 填真实值）
└── .gitignore

安全

• iFinD refresh_token：放 futures-research\refresh_token.txt，已 gitignore，绝不入库。 脚本自动换 access_token 写 ifind_token.txt，不会覆盖 refresh_token.txt。
• iFinD 账号密码：通过环境变量 IFIND_USER / IFIND_PWD 注入，不写入仓库。
• SSH 私钥：放 futures-research\.ssh\，已 gitignore；仅保留给 blogwatcher 拉取。
• Wind：不存密码；依赖用户本人的 Wind 终端登录会话。

数据可获取度体系

级别	含义	示例
✅	自动化可取	日线、持仓(GFEX)、仓单(GFEX/CZCE)、期限结构、分钟线、基差、宏观、LME/CFTC、blogwatcher 新闻
🔶	半自动 / 需用户会话	Wind EDB（本人跑一行脚本）、新能源车月频（8 月中旬发布）
❌	需付费终端，不得编造	开工率、社会库存(非交易所)、成本曲线、产业链利润、实时现货报价

⚠️ 门控红线：数据缺失时严禁用硬编码旧数字兜底，一律标注「数据缺口」。 两个接口陷阱：futures_inventory_em 必须显式传品种 symbol（默认是豆一）； futures_spot_price_previous 必须显式传交易日（默认 2024-04-30 陈旧快照）。