用途：追踪对冲基金在农产品期货的持仓变化，把 CFTC Commitments of Traders（COT）非商业部位、出口需求、USDA 数据与美元、原油、金属等宏观指标整合为可交易叙事与信号。
主要能力：按 CFTC 原生分组（Grains、Oilseeds、Meats、Softs、Fiber、Dairy）计算净部位周变化与总流量；用历史分位数估算 buying_firepower（1 - net_pos_percentile），判断基金加码空间；整合 DXY、WTI、金属计算 macro_tailwind_score；因 COT 只到周二，周三至周五用价格动能、未平仓变化与宏观共振作代理证据；输出周流量时序、最新状态、火力分数、宏观评分、可交易 call 与信心、图表标注及风险提示，并可生成 Bloomberg 风格图表。
使用方式：进入 scripts 目录后安装依赖并运行主分析脚本，例如 pip install pandas numpy requests yfinance pyarrow，再执行 python analyze_positioning.py --start 2023-01-01；可视化用 python visualize_flows.py --weeks 52，输出 output/agri_fund_positioning_YYYY-MM-DD.png。数据来自 CFTC Socrata API，脚本无模拟数据。
适用场景：农产品期货资金流监控、周度 COT 更新后的信号检查、宏观与基本面交叉验证、图表重建与叙事规则化。
限制：COT 截止周二、周五发布，周中需依赖代理证据；USDA 报告等基本面事件可能反转叙事；火力与宏观评分基于历史分位与设定窗口，参数如 lookback_weeks_firepower 默认 156 周，需按需调整。具体收费、平台支持与效果暂未提供。