第10练题目解析——以Q-Macro组合为例

用 AI 和 vibe coding 搭建宏观驱动 ETF 策略，零代码、零投资基础也能上手的端到端实战教程

🛠 第一部分：题目解析与开发流程

📝 题目解析

"如果今天是 2025 年 12 月 31 日，请基于最新宏观经济数据和政策文件（本练习已为你准备好了部分数据），自动选出最值得投资的 ETF 组合，并解释为什么。"

这个题目包含四个关键任务：

读宏观：识别当前经济处于复苏/过热/滞胀/衰退哪个阶段？
读政策：最近一个月政府重点支持哪些产业？（如新能源、AI、高股息等）
看市场：哪些 ETF 流动性好、不拥挤、适合买入？
配组合：综合以上信息，动态分配股票/债券/商品 ETF 权重，并生成报告。

在本练习中，我们不讲技术细节，而是展示思考路径——如何把一个模糊想法，拆解成可执行的模块，并用 AI 工具逐个实现。我们采用 "小步快跑、模块拼装、AI 辅助" 的开发方式，具体流程如下：

调研与策略设计：使用网页版 Qwen Max（千问-Qwen官网）进行宏观经济和投资策略调研，设计整体策略框架
Prompt 编写：针对每个功能模块编写详细的开发Prompt，指导AI编程助手进行代码实现
模块拼装：每个模块独立开发、独立测试，确保功能完整后再集成
AI 辅助编码：让 LLM 当"实习生"，负责写初稿、打标签、写报告等重复性工作
人工决策与校验：人只做关键决策和结果校验，比如"这个宏观状态判断对吗？"

整个过程就像搭乐高，每个模块都是一个小积木，最后拼成完整策略。通过这种方式，即使是编程新手也能快速构建复杂的投资系统。

📁 详细的开发Prompt和对话请查看：开发Prompt 文件夹，包含了每个模块的详细开发过程和与AI的交互对话。

🗺 开发流程图（小白友好版）

📚 关键开发步骤（按时间顺序）

步骤	任务内容与重要性	对应文件	开发Prompt	学习要点
1️⃣ 搭骨架	创建 `src/`, `scripts/`, `data/` 目录，让项目"看起来像回事"，便于后续填充	`src/`, `scripts/`, `data/` 目录	`开发Prompt/01新建架构.md`	项目结构设计，模块化思维
2️⃣ 拉数据	用 AKShare 自动下载 CPI、PMI 等，数据是策略的地基，必须先有	`scripts/fetch_macro_data.py`	`开发Prompt/02数据层搭建.md`	数据获取方法，API调用
3️⃣ 处理数据	统一宏观数据时间格式，确保数据格式一致，便于分析	`scripts/process_macro_data.py`	`开发Prompt/03处理宏观数据时间格式.md`	数据预处理，时间序列处理
4️⃣ 判断宏观状态	写 `macro_regime.py`，四象限分类，解决"现在该不该买股票"这个核心问题	`src/core/macro_regime.py`	`开发Prompt/04模块1宏观状态与景气度开发.md`	经济周期判断，四象限模型
5️⃣ 筛ETF	写 `market_calibration.py`，过滤流动性差的，避免选到"僵尸ETF"	`src/core/market_calibration.py`	`开发Prompt/05模块3ETF初步筛选.md`	流动性分析，拥挤度指标
6️⃣ 给ETF打标签	用 LLM 自动分类 500 只 ETF，让机器理解"这只ETF属于AI还是光伏"	`src/agents/theme_mapper.py`	`开发Prompt/07ETF投资主题与分类AI生成.md`	文本分类，标签体系设计
7️⃣ 读政策	让 LLM 分析政府文件，提取前5大主题，实现"政策驱动"的轮动逻辑	`src/agents/policy_interpreter.py`	`开发Prompt/10模块2政策本文分析AI生成.md`	自然语言处理，信息提取
8️⃣ 拼组合	写 `portfolio_builder.py`，动态配权，把宏观+政策+市场三要素融合	`src/core/portfolio_builder.py`	`开发Prompt/06模块4ETF组合构建.md`	资产配置，权重计算
9️⃣ 写报告	用 LLM 生成月度投资报告，让策略可解释、可信任	`src/agents/report_writer.py`	`开发Prompt/11投资策略报告生成.md`	报告生成，策略归因
🔟 批量+回测	一键跑全年 + 生成净值曲线，验证策略是否真的有效	`scripts/run_all_pipline.py`, `scripts/run_backtest.py`	`开发Prompt/09第一次系统集成.md`	批量处理，回测分析

🏗 第二部分：最终完整项目架构展示

现在你看到的是一个生产就绪级的策略系统。以下是它的完整面貌。

📁 项目结构

Q-Macro/
├── data/                  # 宏观数据 + ETF数据
│   ├── etf/               # ETF量价与基本信息
│   │   ├── etf_2025_ohlcva.csv        # ETF量价数据
│   │   ├── etf_basic.csv              # ETF基本信息
│   │   ├── processed_etf_basic.csv     # LLM打标签结果
│   │   └── tag_analysis.txt           # 标签分析结果
│   ├── macro_data/        # 原始宏观指标（CPI、PMI等）
│   ├── processed_macro_data/ # 处理后的时间对齐数据
│   └── policy_texts/      # 政策文本数据
│       └── govcn_2025.csv              # 2025年政策文件
├── src/                   # 核心源码
│   ├── core/              # 策略核心逻辑（纯Python）
│   │   ├── macro_regime.py        # 宏观状态识别
│   │   ├── market_calibration.py  # ETF流动性与拥挤度校准
│   │   └── portfolio_builder.py   # 动态组合构建
│   └── agents/            # LLM智能体
│       ├── policy_interpreter.py  # 政策翻译官
│       ├── theme_mapper.py        # ETF标签工程师
│       └── report_writer.py       # 归因分析师
├── scripts/               # 可执行脚本
│   ├── fetch_macro_data.py        # 从AKShare拉取宏观数据
│   ├── process_macro_data.py      # 处理宏观数据时间格式
│   ├── run_monthly_pipeline.py    # 单月策略执行
│   ├── run_all_pipline.py         # 批量跑全年
│   ├── parse_portfolios_to_csv.py # JSON → CSV 转换
│   └── run_backtest.py            # 回测入口
├── portfolios/            # 输出：每月ETF组合（JSON）
├── reports/               # 输出：每月投资报告（Markdown）
├── results/               # 回测结果：净值/图表/指标
│   └── backtest_results/
│       ├── charts/        # 回测图表
│       ├── metrics.txt    # 回测指标
│       ├── nav_series.csv # 净值序列
│       ├── positions.csv  # 持仓记录
│       └── trade_records.csv # 交易记录
├── 开发Prompt/            # 开发过程记录
├── Q-Macro.py             # 一键运行入口
├── README.md              # 项目说明
├── .env.example           # 环境变量示例文件
├── .gitignore             # Git忽略文件
├── position.csv           # 持仓数据
├── pyproject.toml         # 项目配置文件
└── uv.lock                # 依赖锁定文件

🧩 核心功能亮点

功能	技术实现	教学价值	应用场景
宏观状态识别	PMI + CPI + PPI 四象限模型	理解美林时钟简化版，掌握经济周期判断方法	判断当前是否适合买股票
政策主题提取	LLM 分析政府文件，输出 top5 主题	学会用 AI 处理非结构化文本，提取关键信息	捕捉政策热点，提前布局
ETF智能打标	三级标签体系（资产/主题/子主题）	构建自己的"ETF知识图谱"，理解ETF分类	快速找到符合主题的ETF
拥挤度校准	成交量 Z-score 调整权重	避免追高热门ETF，理解市场情绪指标	控制风险，避免高位接盘
动态资产配置	股/债/商品比例随宏观状态变化	掌握风险预算思想，学习资产配置原理	适应不同经济环境
LLM生成报告	自动撰写归因分析	提升策略可信度与可解释性，学会表达投资逻辑	向他人解释投资决策
一键回测	基于 GeneralBacktest 包	验证策略是否"纸上谈兵"，理解回测指标含义	检验策略有效性
基准比较	与全天候组合（股债商固定权重）比较	评估策略相对表现，理解超额收益概念	衡量策略优劣

▶️ 如何运行

1. 环境准备

# 安装依赖（需 Python 3.8+）
uv sync

# 配置 .env 文件（示例）
echo "LLM_API_KEY=your_api_key" >> .env
echo "MODEL_NAME=Qwen/Qwen3-Next-80B-A3B-Instruct" >> .env
echo "LLM_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1" >> .env

2. 一键运行完整流程

# 执行完整流程：批量策略生成 → 持仓转换 → 回测
python Q-Macro.py

# 仅运行回测（跳过步骤1和2）
python Q-Macro.py --only-backtest

# 跳过回测（仅生成策略）
python Q-Macro.py --skip-backtest

3. 查看结果

投资组合：portfolios/portfolio_result_2025-12-31.json
策略报告：reports/investment_report_2025-12-31.md
回测图表：results/backtest_results/charts/
绩效指标：results/backtest_results/metrics.txt

🚀 第三部分：轮到你了！

（一）基础任务（必做）

Task1: 投资策略与代码框架设计

任务目标：

理解基于宏观视角的大类资产配置策略设计思路，掌握国内主流券商在大类资产配置上的核心方法论
学习如何从券商研报中提炼关键信息，包括经济周期划分、政策信号解读、资产排序逻辑等
掌握ETF投资组合框架的设计方法，学会将抽象的资产配置建议转化为具体的ETF标的选择
理解量化策略的模块化架构设计，掌握各模块的输入输出定义和数据流转关系
学习如何构建完整、可编码、可回测的量化策略体系，为后续模块的具体实现奠定基础

一问投资策略：

我正在构建一套基于宏观视角的大类资产配置策略。请帮我系统梳理国内主流券商近期发布的宏观与大类资产配置类研报，完成以下任务：

综述与提炼：总结这些机构在大类资产配置上的核心方法论（例如经济周期划分、政策信号解读、资产排序逻辑、战术调整规则等）；

横向对比：指出不同券商框架的共性与差异，尤其关注其对“股、债、商品、现金”四类资产的配置优先级判断依据；

ETF 化改造：基于上述方法论，设计一个可落地的 ETF 投资组合框架——即如何将抽象的“股票/债券/商品”配置建议，转化为具体的宽基 ETF、行业 ETF 或商品 ETF 标的，并考虑流动性、跟踪误差与交易成本；

附简要示例：以当前宏观环境（如 2026 年初）为例，演示该 ETF 配置框架的实际应用。

请确保内容逻辑严谨、来源可靠，并突出“从宏观研判到 ETF 执行”的完整链条。

二问代码框架：

请将前述基于券商宏观大类资产配置方法论所构建的 ETF 投资策略，进一步发展为一个完整、可编码、可回测的量化策略体系。我希望你从模块化架构的角度出发，详细说明：

整体策略框架：策略的逻辑流程与核心组成部分（如宏观状态识别、政策主题提取、ETF 筛选、权重分配、再平衡机制等）；

每个模块的输入与输出：明确各模块接收什么数据（格式、频率、来源）；输出什么结构（如信号、分数、权重向量等）；

模块间如何衔接与传递信息：说明各模块之间的依赖关系，以及数据是如何在模块之间流动的；

列出所需数据清单：如宏观数据（如 PMI、CPI、PPI、社融、利率等）；政策文本（如政府工作报告、央行公告、部委文件等）；ETF 市场数据（如价格、成交量、规模、跟踪误差、成分股等）；是否需要另类数据（如舆情、资金流等）？

代码实现建议：初期可偏向复杂但完备的设计，后续我会根据实际资源和目标进行简化或裁剪。重点是确保逻辑闭环、数据可得、模块解耦。

三问技术路线：

在当前这套宏观驱动的 ETF 配置策略中，我计划对部分模块引入基于大语言模型（LLM）的智能体（Agent）来增强灵活性与语义理解能力，而其他模块则采用确定性规则或硬编码逻辑以保证稳定性与可解释性。请你结合各步骤及其子模块的任务性质，分析并建议：

哪些环节更适合由 LLM Agent 执行？例如：涉及非结构化文本理解（如政策文件解读、主题提取），需要模糊推理、上下文整合或动态生成解释，规则难以穷举但存在人类专家经验

哪些环节更适合硬编码（规则/公式/传统量化方法）？例如：输入输出关系明确、逻辑固定（如经济指标计算、权重归一化），对可复现性、低延迟或监管合规有较高要求，数据高度结构化且已有成熟建模方法（如动量、波动率、拥挤度计算）

特别关注边界场景：是否存在某些模块“看似适合 LLM，实则硬编码更优”（或反之）？请说明理由。

请基于策略全流程（宏观状态判断 → 政策主题解析 → ETF 筛选 → 组合构建 → 报告生成）逐环节评估，并给出优先级建议。

四问落地方案：

我已确认采用前述宏观驱动的 ETF 配置策略方案。现在请为该项目设计一个简洁、清晰、可直接用于开发的代码与文件架构，并以 Markdown 格式 输出，确保 Vibe Coding 类 AI能准确解析并自动生成初始项目骨架。

技术约束如下：

包管理与环境管理：使用 UV（uv pip install / uv venv）

智能体（Agent）开发：基于 LangChain 最新稳定版本（支持 LLM 路由、工具调用、记忆等）

数据源：仅依赖 AKShare + 本地已有的政策文本、ETF 量价及基本信息数据

架构原则：简单优先，避免过度工程化；模块解耦但不过度抽象；优先保证可运行性

请输出内容包括：

项目根目录结构（含关键文件/文件夹说明）

各核心模块的职责简述（如 macro_analyzer.py、policy_agent.py、etf_selector.py 等）

必要的配置文件示例（如 pyproject.toml 的依赖声明、.env 占位符等）

入口脚本建议（如 run_strategy.py 或 CLI 命令）

目标是让 AI 能根据这份 Markdown 一键生成可运行的最小可行项目（MVP）骨架，后续再逐步填充逻辑。

由此得到本项目的核心文件：开发Prompt/01新建架构.md、Q-Macro.py（一键运行入口）、scripts/run_monthly_pipeline.py（单月策略执行）

设计思路：采用模块化设计，将复杂的投资策略拆解为多个独立模块，每个模块负责特定功能；同时确保数据流清晰，从数据获取到策略生成再到结果输出，形成完整的数据处理 pipeline；并引入AI辅助，将LLM应用于政策分析、ETF打标和报告生成等需要自然语言处理的环节；最后注重可扩展性，为每个模块设计明确的输入输出接口，便于单独测试和替换。

策略运行流程解析：

# 完整策略流水线
def run_monthly_pipeline(target_date):
    # 步骤1：拉取宏观数据 - 从AKShare获取PMI、CPI、PPI等宏观指标
    # 步骤2：处理宏观数据时间格式 - 统一时间格式，便于后续分析
    # 步骤3：识别宏观状态 - 基于四象限模型判断当前经济周期
    # 步骤4：ETF流动性筛选与拥挤度检测 - 确保选择流动性好、不拥挤的ETF
    # 步骤5：政策文本分析与主题提取 - 用LLM分析政府文件，提取投资主题
    # 步骤6：ETF智能打标 - 为ETF建立三级标签体系，便于主题匹配
    # 步骤7：构建投资组合 - 基于宏观状态、政策主题和市场条件构建组合
    # 步骤8：生成投资报告 - 用LLM生成详细的投资策略报告
    # 步骤9：保存结果 - 保存组合权重和投资报告
    pass

Task2: 数据层搭建

任务目标：

系统调研AKShare数据源，掌握其支持的宏观经济指标、市场指数、资金面指标等数据类型
学习如何使用AKShare库从官方数据源获取最新的宏观经济数据，包括PMI、CPI、PPI等关键指标
掌握数据预处理技术，包括时间格式统一、数据质量检查和缺失值处理
理解如何基于数据可得性调整策略框架，学会删除或替换依赖非AKShare数据的模块
学习数据存储和管理方法，掌握将获取的数据保存为CSV文件并进行有效管理
培养数据驱动的思维方式，学会根据数据质量和可用性调整策略逻辑
为后续的宏观状态识别和投资组合构建模块提供高质量、一致性的数据基础

核心提问：

我计划基于 AKShare 作为主要数据源来实现前述宏观驱动的 ETF 配置策略。目前我本地已具备以下三类数据：政策文本（如政府工作报告、部委文件等）、ETF 量价数据（日频价格、成交量等）、ETF 基本信息（代码、名称、跟踪指数、规模、费率等）。请帮我：

系统调研 AKShare 当前（截至 2026 年）支持获取哪些与宏观大类资产配置相关的数据，包括但不限于：宏观经济指标（如 PMI、CPI、PPI、GDP、社融、M2、利率、汇率等）、股票/债券/商品市场指数行情（用于代理大类资产表现）、资金面或流动性指标（如 DR007、国债收益率曲线等）、行业或风格指数数据（如申万行业、中信风格指数等）

明确标注哪些关键数据 AKShare 无法提供（例如高频资金流、机构持仓变化、另类舆情数据等）；

根据上述调研结果，对原策略框架进行适配性调整：删除或替换所有依赖非 AKShare 数据的模块或逻辑；确保最终策略仅使用 AKShare 可获取 + 我本地已有的数据源；若某环节因数据缺失需简化（如用 CPI+PPI 代替完整周期模型），请说明替代方案及其合理性。目标是形成一个数据可得、逻辑自洽、可完全本地复现的策略版本。

核心文件：scripts/fetch_macro_data.py、scripts/process_macro_data.py

设计思路：数据是策略的地基，必须先有高质量的数据才能进行后续分析。本模块负责从AKShare等数据源自动下载CPI、PMI、PPI等宏观经济指标，并统一处理时间格式，确保数据的一致性和可用性。

实现原理：

数据获取：使用AKShare库从官方数据源获取最新的宏观经济数据
数据存储：将获取的数据保存为CSV文件，便于后续处理
时间格式统一：处理不同数据源的时间格式差异，确保数据的一致性
数据质量检查：检查数据的完整性和合理性，处理可能的缺失值

模块框架：

def fetch_macro_data():
    """
    从AKShare获取宏观经济数据
    - 输入：无
    - 输出：保存到data/macro_data目录
    """
    # 1. 获取PMI数据
    # 2. 获取CPI数据
    # 3. 获取PPI数据
    # 4. 获取工业增加值数据
    # 5. 保存数据
    pass

def process_macro_data():
    """
    处理宏观数据时间格式
    - 输入：data/macro_data目录下的原始数据
    - 输出：保存到data/processed_macro_data目录
    """
    # 1. 读取原始数据
    # 2. 统一时间格式
    # 3. 处理缺失值
    # 4. 保存处理后的数据
    pass

Task3: 宏观状态识别模块搭建

任务目标：

理解宏观状态四象限模型的实现逻辑，掌握复苏/过热/滞胀/衰退四个经济周期阶段的划分方法
学习如何基于PMI、CPI、PPI等宏观指标判断当前经济所处的周期阶段
掌握景气度得分的计算方法，学会生成一个连续的、反映经济环境对股票投资友好程度的评分
理解动量分析技术，学会计算增长和通胀的动量变化，为投资决策提供更多维度的参考
掌握模块接口设计方法，学会设计清晰的输入输出结构，与后续模块解耦
学习如何验证宏观状态判断的合理性，掌握与官方周期划分对比、逻辑一致性检查等验证方法
为投资组合构建模块提供关键的宏观状态信号，奠定资产配置决策的基础

核心提问：

我计划优先开发宏观状态判断模块，作为整个ETF配置策略的起点。请帮我设计一个详细、可落地的开发方案，包括：

如何基于PMI、CPI、PPI等宏观指标划分复苏/过热/滞胀/衰退四个经济周期阶段？

如何计算一个连续的景气度得分，反映经济环境对股票投资的友好程度？

如何计算增长和通胀的动量变化，为投资决策提供更多维度的参考？

如何设计模块的输入输出接口，确保与后续模块解耦？

如何验证宏观状态判断的合理性，确保模块输出的可靠性？

核心文件：src/core/macro_regime.py

设计思路：

简化版美林时钟：基于PMI（经济增长）和CPI（通胀）的组合来划分经济状态
多指标验证：同时使用PMI、CPI、PPI和工业增加值等多个宏观指标
动量分析：不仅关注当前状态，还计算增长和通胀的动量变化
权益友好度评分：生成一个综合评分，反映当前环境对股票投资的友好程度

实现原理：

数据获取与处理：读取并统一处理不同宏观指标的时间格式
状态判断：根据PMI和CPI的组合判断经济状态
动量计算：计算近3个月的指标变化趋势
评分生成：基于多个因素生成0-1之间的权益友好度评分

模块框架：

def detect_macro_regime_and_score(target_date, macro_data_dir="data/processed_macro_data", fallback_to_last=True):
    """
    基于目标日期，识别当前宏观状态并生成景气度评分
    - 输入：目标日期
    - 输出：包含regime、momentum、score等字段的字典
    """
    # 1. 读取并处理PMI、CPI、PPI、工业增加值数据
    # 2. 找到不晚于目标日期的最新数据
    # 3. 计算四象限状态（复苏/过热/滞胀/衰退）
    # 4. 计算增长动量和通胀动量
    # 5. 生成权益友好度评分
    # 6. 返回结果
    pass

# 核心判断逻辑
# growth = (pmi > 50.0) or (industrial_yoy > 5.0)
# inflation = (cpi_yoy > 2.5) or (ppi_yoy > 0.0)
# if growth and inflation: regime = "overheat"
# elif growth and not inflation: regime = "recovery"
# elif not growth and inflation: regime = "stagflation"
# else: regime = "recession"

学习引导：理解宏观状态识别是整个策略的基础，它决定了大类资产的配置比例。通过调整阈值和添加新的宏观指标，可以优化状态判断的准确性。

Task4: 市场校准（ETF初步筛选）模块搭建

任务目标：

理解ETF流动性筛选的实现逻辑，掌握如何计算和评估ETF的流动性指标
学习拥挤度检测技术，掌握使用成交量Z-score方法识别交易拥挤的ETF
掌握风险控制方法，学会通过流动性筛选避免选择"僵尸ETF"，通过拥挤度检测避免追高热门ETF
理解调整因子的生成和应用方法，学会对拥挤的ETF应用权重调整
掌握模块接口设计，学会设计清晰的输入输出结构，与后续的投资组合构建模块对接
学习如何基于市场条件调整筛选参数，平衡流动性和可选ETF数量
为投资组合构建模块提供经过风险校准的ETF池，确保选择的ETF既具有足够的流动性，又不会过度拥挤

核心提问：

我计划开发一个市场校准模块，用于ETF的初步筛选，确保选择的ETF既具有足够的流动性，又不会过度拥挤。请帮我设计一个详细的实现方案，包括：

如何计算和评估ETF的流动性指标，避免选择"僵尸ETF"？

如何使用成交量Z-score方法识别交易拥挤的ETF，避免追高热门ETF？

如何生成和应用调整因子，对拥挤的ETF进行权重调整？

如何设计模块的输入输出接口，确保与后续的投资组合构建模块对接？

如何基于市场条件调整筛选参数，平衡流动性和可选ETF数量？

核心文件：src/core/market_calibration.py

设计思路：

流动性保障：确保选择的ETF有足够的成交量和成交额，避免流动性风险
拥挤度控制：检测并避免选择交易过于拥挤的ETF，防止高位接盘
数据驱动：基于客观的量价数据进行筛选，避免主观判断
调整因子：对拥挤的ETF应用权重调整因子，降低其在组合中的比重

实现原理：

流动性筛选：计算ETF的20日均成交额，筛选出超过阈值的ETF
拥挤度检测：使用成交量的Z-score方法，比较近期（5日）与长期（120日）的成交量
调整因子生成：对拥挤的ETF生成小于1的调整因子，非拥挤的ETF保持1的因子

模块框架：

def calibrate_etf_market_conditions(target_date, etf_price_path="data/etf/etf_2025_ohlcva.csv", min_avg_amount=1e4, crowded_z_threshold=1.5):
    """
    基于目标日期，对ETF进行市场校准
    - 输入：目标日期
    - 输出：包含liquid_etfs和crowded_adjustments的字典
    """
    # 1. 读取ETF量价数据
    # 2. 找到实际交易日
    # 3. 按ETF代码分组处理
    # 4. 计算20日均成交额，筛选流动性好的ETF
    # 5. 计算成交量Z-score，检测拥挤度
    # 6. 生成拥挤度调整因子
    # 7. 返回结果
    pass

# 拥挤度计算逻辑
# z_score = (vol_5d - vol_120d_mean) / vol_120d_std
# if z_score > crowded_z_threshold: crowded_adjustments[ticker] = 0.75
# else: crowded_adjustments[ticker] = 1.0

学习引导：市场校准是控制风险的重要环节。通过流动性筛选，我们避免了选择"僵尸ETF"；通过拥挤度检测，我们避免了追高热门ETF。理解这两个概念对于构建稳健的投资组合至关重要。

Task5: 政策解读模块解析

任务目标：

理解LLM政策文本分析和主题提取的实现原理，掌握AI辅助政策分析的方法
学习如何使用LangChain构建Prompt，引导LLM从非结构化政策文本中提取关键信息
掌握逐条分析和统计聚合技术，学会对多条政策文本进行系统分析并汇总结果
理解置信度计算方法，学会评估政策主题的重要性和可靠性
掌握备用机制设计，学会在LLM分析失败时提供默认的主题推荐，确保系统可靠性
学习模块接口设计，学会设计清晰的输入输出结构，与投资组合构建模块对接
为投资组合构建模块提供政策主题信号，帮助捕捉政策热点，提前布局相关ETF

核心提问：

我计划开发一个政策解读模块，使用LLM分析政府文件并提取投资主题。请帮我设计一个详细的实现方案，包括：

如何使用LangChain构建有效的Prompt，引导LLM从非结构化政策文本中提取关键信息？

如何对多条政策文本进行逐条分析和统计聚合，提高主题提取的准确性？

如何计算政策主题的置信度，评估其重要性和可靠性？

如何设计备用机制，在LLM分析失败时提供默认的主题推荐？

如何设计模块的输入输出接口，确保与投资组合构建模块的有效对接？

核心文件：src/agents/policy_interpreter.py

设计思路：

AI辅助分析：利用LLM的自然语言处理能力，从非结构化的政策文本中提取关键信息
逐条分析：对每条政策文本单独进行分析，确保分析的细致性
统计聚合：通过统计方法汇总多条政策的分析结果，提高准确性
备用机制：当LLM分析失败时，提供默认的主题推荐，确保系统可靠性

实现原理：

政策文本加载：加载目标日期前30天的政策文本片段
LLM分析：使用LangChain构建Prompt，调用LLM对每条政策进行分析
主题提取：从LLM输出中提取推荐的投资主题
置信度计算：统计每个主题的出现次数和置信度
结果排序：按照置信度排序，选择前5个最重要的主题

模块框架：

def interpret_policy(policy_path, target_date, macro_context, max_retries=2):
    """
    主函数：调用LLM解析政策信号，逐条处理政策文本
    - 输入：政策文件路径、目标日期、宏观状态
    - 输出：包含top_5_themes和analysis_summary的字典
    """
    # 1. 加载近期政策片段
    # 2. 初始化LLM
    # 3. 构建单条政策分析的Prompt
    # 4. 逐条分析政策文本
    # 5. 计算主题分布和置信度
    # 6. 按照置信度排序，选择前5个主题
    # 7. 构建最终结果
    pass

# 备用方案
def _fallback_signal(macro_context):
    # 默认启用主题分析，返回通用的主题推荐
    pass

学习引导：政策解读是策略的重要组成部分，它帮助我们捕捉政策热点，提前布局。通过LLM分析政策文本，我们可以更快速、更全面地理解政策导向。理解Prompt的构建和LLM输出的处理方法，是掌握这一模块的关键。

Task6: ETF主题映射模块解析

任务目标：

理解ETF智能打标的三级标签体系实现，掌握资产大类 → 主题 → 子主题的精细化分类方法
学习如何使用Pydantic模型定义和验证标签格式，确保标签的一致性和正确性
掌握LLM辅助打标技术，学会构建结构化的Prompt，引导LLM基于ETF名称和跟踪指数进行智能分类
理解批量处理和增量更新机制，学会对大量ETF进行高效打标，避免重复工作
掌握错误处理方法，学会对打标失败的ETF返回合理的默认标签
学习模块接口设计，学会设计清晰的输入输出结构，与投资组合构建模块对接
为投资组合构建模块提供结构化的ETF标签数据，实现政策主题与具体ETF的精准匹配

核心提问：

我计划开发一个ETF主题映射模块，使用LLM为ETF添加三级标签体系。请帮我设计一个详细的实现方案，包括：

如何设计一个合理的三级标签体系（资产大类 → 主题 → 子主题），实现ETF的精细化分类？

如何使用Pydantic模型定义和验证标签格式，确保标签的一致性和正确性？

如何构建结构化的Prompt，引导LLM基于ETF名称和跟踪指数进行智能分类？

如何实现批量处理和增量更新机制，对大量ETF进行高效打标，避免重复工作？

如何设计错误处理机制，对打标失败的ETF返回合理的默认标签？

核心文件：src/agents/theme_mapper.py

设计思路：

三级标签体系：构建资产大类 → 主题 → 子主题的三级标签结构，实现精细化分类
Pydantic验证：使用Pydantic模型确保标签格式的一致性和正确性
LLM辅助打标：利用LLM的理解能力，基于ETF名称和跟踪指数对ETF进行智能分类
批量处理：支持对大量ETF进行批量打标，提高效率
增量更新：支持从已有的打标结果继续处理，避免重复工作

实现原理：

数据准备：读取ETF基本信息，包括名称、跟踪指数等
LLM打标：构建结构化的Prompt，让LLM生成符合要求的标签
结果验证：使用Pydantic模型验证LLM输出的标签格式
错误处理：对打标失败的ETF返回默认标签
结果保存：将打标结果保存到CSV文件，供后续模块使用

模块框架：

# Pydantic 输出模型
class ETFTag(BaseModel):
    asset_class: Literal["股票", "债券", "商品", "货币", "其他"]
    theme: str  # 第二级分类：如宽基、行业主题等
    sub_theme: str  # 第三级分类：行业主题下的详细主题

def tag_single_etf(etf_row, max_retries=2):
    """
    对单只ETF打标签，失败返回默认值
    - 输入：ETF基本信息行
    - 输出：包含asset_class、theme、sub_theme的字典
    """
    # 1. 构建LLM调用链
    # 2. 调用LLM生成标签
    # 3. 处理解析错误
    # 4. 返回标签结果
    pass

def batch_tag_etfs(input_path="data/etf/etf_basic.csv", output_path="data/etf/processed_etf_basic.csv"):
    """
    批量打标签并保存
    """
    # 1. 读取ETF基本信息
    # 2. 逐行处理ETF，调用tag_single_etf
    # 3. 保存结果
    pass

学习引导：ETF智能打标是连接政策主题和具体ETF的桥梁。通过三级标签体系，我们构建了自己的"ETF知识图谱"，使得系统能够根据政策主题自动找到相关的ETF。理解标签体系的设计和LLM打标的实现，对于后续的组合构建至关重要。

Task7: 投资组合构建模块解析

任务目标：

理解动态资产配置的实现逻辑，掌握基于宏观状态的四象限模型调整股/债/商品配置比例的方法
学习如何结合政策解读模块提取的主题，选择符合政策导向的ETF
掌握权重分配技术，学会在各类资产内部进行合理的权重分配，应用拥挤度调整
理解分层配置策略，学会在股票部分采用宽基ETF（60%）+ 主题ETF（40%）的配置方法
掌握模块接口设计，学会整合宏观状态、政策主题和市场条件等多个模块的输出
学习如何验证投资组合的合理性，确保资产配置符合当前经济环境和政策导向
构建最终的投资组合，为投资者提供具体、可执行的ETF配置建议

核心提问：

我计划开发一个投资组合构建模块，整合宏观状态、政策主题和市场条件等多个模块的输出，构建ETF投资组合。请帮我设计一个详细的实现方案，包括：

如何基于宏观状态的四象限模型调整股/债/商品的配置比例？

如何结合政策解读模块提取的主题，选择符合政策导向的ETF？

如何在各类资产内部进行合理的权重分配，应用拥挤度调整？

如何实现股票部分的分层配置策略（宽基ETF 60% + 主题ETF 40%）？

如何设计模块的输入输出接口，确保与其他模块的有效整合？

核心文件：src/core/portfolio_builder.py

设计思路：

宏观驱动：基于宏观状态的四象限模型，动态调整股/债/商品的配置比例
政策导向：结合政策解读模块提取的主题，选择符合政策导向的ETF
风险控制：应用市场校准模块的拥挤度调整因子，降低拥挤ETF的权重
分层配置：在股票部分，采用宽基ETF（60%）+ 主题ETF（40%）的分层配置策略
灵活性：支持在不同经济环境下的资产配置调整

实现原理：

基础权重确定：根据当前宏观状态，从预设的基础权重表中获取初始配置比例
权重动态调整：基于权益友好度评分，动态调整股票权重
ETF筛选：根据标签体系筛选宽基ETF和主题ETF
权重分配：在各类资产内部进行权重分配，应用拥挤度调整
结果归一化：确保所有ETF的权重总和为1

模块框架：

# 四象限资产配置基础权重
REGIME_BASE_WEIGHTS = {
    "recovery": {"stock": 0.7, "bond": 0.2, "commodity": 0.1},
    "overheat": {"stock": 0.6, "bond": 0.1, "commodity": 0.3},
    "stagflation": {"stock": 0.3, "bond": 0.3, "commodity": 0.4},
    "recession": {"stock": 0.4, "bond": 0.5, "commodity": 0.1}
}

def build_portfolio(macro_state, market_cond, current_themes=None, etf_meta_path="data/etf/processed_etf_basic.csv"):
    """
    构建ETF投资组合
    - 输入：宏观状态、市场条件、当前推荐主题
    - 输出：包含target_weights和reasons的字典
    """
    # 1. 确定大类资产基础权重
    # 2. 动态调节股票权重
    # 3. 筛选宽基ETF
    # 4. 筛选主题ETF
    # 5. 分配债券与商品ETF
    # 6. 内部权重分配（宽基60%+主题40%）
    # 7. 应用拥挤度调整
    # 8. 归一化与清理
    # 9. 构建返回结果
    pass

学习引导：投资组合构建是整个策略的核心环节，它将宏观分析、政策解读和市场校准的结果整合起来，形成最终的投资建议。理解资产配置的逻辑和权重分配的方法，是掌握投资策略构建的关键。

Task8: 报告生成模块解析

任务目标：

理解LLM自动生成投资策略报告的实现原理，掌握AI辅助报告写作的方法
学习如何使用Pydantic模型定义输入数据结构，确保数据的一致性和正确性
掌握结构化报告生成技术，学会生成包含宏观状态、政策解读、市场条件、投资组合和决策总结的完整报告
理解分部分生成和报告组装方法，学会将各模块的分析结果整合成连贯的报告
掌握回退机制设计，学会在LLM调用失败时提供基于模板的简单报告，确保系统可靠性
学习Markdown格式报告的生成方法，提高报告的可读性和专业性
为投资者提供清晰、专业、可理解的投资策略报告，增强策略的可信度和可执行性

核心提问：

我计划开发一个报告生成模块，使用LLM自动生成投资策略报告。请帮我设计一个详细的实现方案，包括：

如何使用Pydantic模型定义输入数据结构，确保数据的一致性和正确性？

如何构建有效的Prompt，引导LLM生成专业、详细的投资策略报告？

如何实现分部分生成和报告组装，将各模块的分析结果整合成连贯的报告？

如何设计回退机制，在LLM调用失败时提供基于模板的简单报告？

如何生成Markdown格式的报告，提高报告的可读性和专业性？

核心文件：src/agents/report_writer.py

设计思路：

结构化报告：生成包含宏观状态、政策解读、市场条件、投资组合和决策总结的完整报告
LLM辅助写作：利用LLM的表达能力，生成专业、详细的分析内容
数据驱动：基于前面模块的分析结果，确保报告内容的一致性和准确性
回退机制：当LLM调用失败时，提供基于模板的简单报告，确保系统可靠性
Markdown格式：生成结构化的Markdown格式报告，便于阅读和分享

实现原理：

数据模型定义：使用Pydantic模型定义输入数据的结构
LLM初始化：初始化LLM模型，准备用于生成报告内容
分部分生成：分别生成宏观状态、政策解读、市场条件和投资组合的详细分析
报告组装：将各部分内容组装成完整的Markdown格式报告
错误处理：处理LLM调用失败的情况，使用回退方案

模块框架：

# 数据模型
class MacroState(BaseModel):
    regime: str  # 当前经济周期
    equity_friendly_score: float  # 权益友好度评分
    growth_momentum: float  # 增长动量
    inflation_momentum: float  # 通胀动量

class Portfolio(BaseModel):
    stocks: List[Dict[str, Any]]  # 股票ETF权重
    bonds: List[Dict[str, Any]]  # 债券ETF权重
    commodities: List[Dict[str, Any]]  # 商品ETF权重

def generate_monthly_report(target_date, macro_state, policy_signal, market_cond, portfolio):
    """
    生成月度投资策略报告
    - 输入：目标日期、宏观状态、政策信号、市场条件、投资组合
    - 输出：完整的投资策略报告（Markdown格式）
    """
    # 1. 生成详细的宏观状态描述
    # 2. 生成详细的政策解读
    # 3. 生成详细的市场条件分析
    # 4. 生成详细的投资组合描述
    # 5. 生成投资决策总结
    # 6. 构建完整报告
    pass

学习引导：报告生成模块是策略的"门面"，它将复杂的分析结果转化为易于理解的投资建议。通过LLM生成专业的投资报告，不仅提高了策略的可解释性，也增强了投资者对策略的信任度。理解如何构建有效的Prompt来引导LLM生成高质量的报告，是掌握这一模块的关键。

Task9: 回测模块解析

任务目标：

理解策略回测和绩效评估的实现原理，掌握从ETF价格数据和每月持仓数据计算策略净值的方法
学习如何与基准指数进行比较，评估策略的相对表现
掌握多指标评估技术，学会计算年化收益率、最大回撤、夏普比率、波动率等关键回测指标
理解可视化技术，学会生成回测图表，直观展示策略表现
掌握结果保存和管理方法，学会将回测结果保存为文件，便于后续分析和分享
学习如何验证回测结果的合理性，确保回测过程的准确性和可靠性
为策略优化提供数据支持，通过回测结果识别策略的优势和不足

核心提问：

我计划开发一个回测模块，用于评估ETF投资策略的绩效。请帮我设计一个详细的实现方案，包括：

如何从ETF价格数据和每月持仓数据计算策略的净值曲线？

如何与基准指数进行比较，评估策略的相对表现？

如何计算年化收益率、最大回撤、夏普比率、波动率等关键回测指标？

如何生成回测图表，直观展示策略表现？

如何验证回测结果的合理性，确保回测过程的准确性和可靠性？

核心文件：scripts/run_backtest.py

设计思路：

完整回测：从ETF价格数据和每月持仓数据出发，计算策略的完整净值曲线
基准比较：与全天候组合（股债商固定权重）进行比较，评估策略的相对表现
多指标评估：计算年化收益率、最大回撤、夏普比率、波动率等多个回测指标
可视化：生成回测图表，直观展示策略表现
结果保存：将回测结果保存为文件，便于后续分析和分享

实现原理：

数据准备：读取ETF价格数据和每月持仓数据
权重计算：根据每月持仓数据，计算每日的持仓权重
收益计算：基于每日权重和ETF收益率，计算策略的每日收益率
净值计算：累积每日收益率，计算策略和基准的净值曲线
指标计算：计算各种回测指标，评估策略的风险收益特征
结果输出：生成图表并保存回测结果

模块框架：

def run_backtest():
    """
    回测入口函数
    - 读取每月持仓数据
    - 计算策略净值
    - 计算回测指标
    - 生成回测图表
    - 保存回测结果
    """
    # 1. 读取ETF价格数据
    # 2. 读取每月持仓数据
    # 3. 计算每日持仓权重
    # 4. 计算策略每日收益率
    # 5. 计算策略净值
    # 6. 计算基准净值
    # 7. 计算回测指标
    # 8. 生成回测图表
    # 9. 保存回测结果
    pass

学习引导：回测是验证策略有效性的重要环节。通过回测，我们可以评估策略在历史数据上的表现，了解其风险收益特征。理解回测的基本原理和常见指标，对于构建和优化投资策略至关重要。

Task10: 运行与调试

任务目标：

掌握项目的运行方法，学会使用不同的运行模式执行策略，包括完整流程、仅回测、仅生成策略等
学习如何通过命令行参数控制运行流程的各个环节，提高运行效率
掌握快速调试技术，学会跳过耗时的LLM相关步骤，加快调试速度
理解环境配置方法，学会通过 .env 文件配置不同的LLM模型和API参数
掌握调试技巧，学会查看投资报告、分析错误信息、逐步调试等方法
学习如何验证运行结果的合理性，确保策略执行的正确性
为项目的实际部署和日常运行做好准备，确保系统的稳定性和可靠性

核心提问：

我计划为ETF投资策略项目设计一个运行与调试框架，确保系统能够稳定运行并便于调试。请帮我设计一个详细的实现方案，包括：

如何设计不同的运行模式，满足完整流程、仅回测、仅生成策略等不同需求？

如何通过命令行参数控制运行流程的各个环节，提高运行效率？

如何实现快速调试技术，跳过耗时的LLM相关步骤，加快调试速度？

如何通过 .env 文件配置不同的LLM模型和API参数，提高系统的灵活性？

如何设计调试技巧和方法，帮助开发者快速定位和解决问题？

设计思路：

灵活运行：提供多种运行模式，满足不同的使用场景
参数控制：通过命令行参数，控制运行流程的各个环节
快速调试：支持跳过耗时的LLM相关步骤，加快调试速度
环境配置：通过 .env 文件配置不同的LLM模型和API参数

运行命令解析：

# 执行完整流程：批量策略生成 → 持仓转换 → 回测
python Q-Macro.py

# 仅运行回测（跳过步骤1和2）
python Q-Macro.py --only-backtest

# 跳过回测（仅生成策略）
python Q-Macro.py --skip-backtest

调试技巧详解：

加快调试速度：使用 --only-backtest 参数跳过LLM相关步骤，避免API调用延迟
模型选择：在 .env 文件中配置不同的LLM模型，比较不同模型的效果
结果分析：查看 reports/ 目录下的投资报告，理解策略逻辑和决策依据
错误定位：检查命令输出的错误信息，定位问题所在
逐步调试：先单独运行各个模块，再运行完整流程，逐步定位问题

（二）进阶任务（选做）

数据层优化：
- 添加美国利率数据、原油价格数据等全球宏观指标
- 接入另类数据，如舆情数据、资金流数据等
- 优化数据预处理流程，提高数据质量和一致性
宏观状态判断优化：
- 调整PMI、CPI、PPI的阈值，优化经济周期划分准确性
- 加入更多宏观指标，如社融、M2、工业增加值等
- 实现增长和通胀的动量分析，提高状态判断的前瞻性
市场校准模块优化：
- 调整ETF流动性筛选阈值，平衡流动性和可选ETF数量
- 改进拥挤度检测算法，优化Z-score计算方法
- 加入更多市场情绪指标，如VIX、成交额占比等
政策解读模块优化：
- 优化LangChain Prompt设计，提高LLM主题提取准确性
- 实现多源政策文本融合分析，提高主题提取的全面性
- 设计更精细的主题分类体系，增强与ETF标签的匹配度
投资组合构建优化：
- 调整不同宏观状态下的资产配置权重，适应不同市场环境
- 优化股票部分的分层配置策略，调整宽基和主题ETF的权重比例
- 实现风险预算模型，基于风险贡献分配权重
回测与绩效评估优化：
- 实现更精细的回测指标计算，如索提诺比率、卡玛比率等
- 与多个基准指数进行比较，全面评估策略表现
- 实现策略归因分析，识别收益来源和风险因素
策略风险管理：
- 添加止损、止盈机制，控制最大回撤
- 实现动态仓位管理，根据市场 volatility 调整仓位
- 设计压力测试框架，评估策略在极端市场环境下的表现
系统功能扩展：
- 添加行业轮动策略或因子模型，丰富策略体系
- 为策略添加简单的Web界面，便于操作和监控
- 实现策略组合构建，分散风险，提高稳定性
结果分析与优化：
- 建立系统化的策略评估框架，从多个维度评估策略表现
- 基于回测结果识别策略优势和不足，确定优化方向
- 实现参数敏感性分析，找到最优参数组合
- 建立持续优化机制，定期评估和调整策略

（三）创意任务（挑战）

RAG增强政策解读：
- 构建政策文本知识库，实现检索增强生成
- 实现多轮对话式政策分析，提高主题提取的深度和准确性
- 设计基于RAG的政策演变追踪系统，捕捉政策趋势变化
DeepAgent深度分析：
- 实现多层次的宏观经济分析，从全球到行业再到个股
- 构建自适应学习系统，根据历史预测误差自动调整分析模型
- 设计情景分析引擎，模拟不同宏观场景下的资产表现
Agentic因子挖掘：
- 实现智能体驱动的因子挖掘系统，自动发现有效的ETF选择因子
- 构建因子评估和组合优化框架，提高因子模型的稳定性
- 设计动态因子权重调整机制，适应不同市场环境
多智能体辩论或协作：
- 实现多个专业智能体（宏观分析、政策解读、市场校准、组合构建）的协作系统
- 设计智能体辩论机制，通过不同视角的碰撞提高决策质量
- 构建智能体投票和权重分配系统，整合多源信息
将策略接入BOT：
- 开发部署飞书或微信BOT，实现策略状态查询和手动干预
- 设计自动化报告推送功能，定期发送投资策略报告
- 实现语音交互功能，支持通过语音指令查询策略信息和执行操作

🏆 第四部分：CUFEL-Q-Arena 项目介绍

ℹ️ 什么是 CUFEL-Q-Arena

CUFEL-Q Arena 是由中央财经大学金融学院人工智能实验室自主研发的 Agent驱动的智能投研竞技平台。平台创新性地将GPT-4、Qwen、DeepSeek等前沿大语言模型与量化投资策略深度融合，构建了一个多智能体协同决策、实时净值追踪、全流程回测验证的一体化投研竞技生态系统。本练习所用到的ETF数据、政策文本示例数据均来自CUFEL-Q Arena项目，所使用的GeneralBacktst回测模块由中央财经大学金融学院人工智能实验室人员开发。

核心功能：

海量数据支持：
- 历史行情数据：所有ETF的价格、成交量、成交额等历史数据
- 新闻和政策数据：财经新闻、政府文件、证监会公告等文本数据
- 分析指标数据：已经处理好的情绪分数、文本向量等高级数据
公平竞赛环境：
- 所有参赛者使用相同的历史数据进行回测
- 统一的评估指标和排名系统
- 透明的比赛规则和结果公示
完整的开发工具链：
- cufel-arena-agent 官方开发包
- 丰富的API文档和示例代码
- 本地测试和调试工具
多维度评估体系：
- 收益率评估：比较不同智能体的投资回报
- 风险控制评估：评估智能体的风险控制能力
- 策略创新性评估：鼓励开发新的投资策略和方法

🔄 如何将 Q-Macro 项目与 CUFEL-Q Arena 结合

你可以将 Q-Macro 项目的核心逻辑封装成一个参赛 Agent，参加 CUFEL-Q Arena 的比赛。这样不仅可以验证你的策略在不同市场环境下的表现，还可以与其他选手交流学习，共同提高投资策略的水平。

参赛步骤：

安装工具箱：
```
pip install cufel-arena-agent
```
创建你的 Agent：
- 在 ETFAgents/YourAgentName/ 目录下创建你的代码文件
- 写一个类，继承 ETFAgentBase 或 FOFAgentBase
- 实现 load_current_data 和 get_current_holdings 方法
封装 Q-Macro 逻辑：
- 将 Q-Macro 的宏观分析、政策解读、市场校准和组合构建逻辑集成到你的 Agent 中
- 确保你的 Agent 能在不同日期下正常工作
本地测试：
- 运行本地测试脚本，验证你的 Agent 是否能正常输出持仓
- 检查日期格式和持仓格式是否正确
提交到 Arena：
- 使用官方提供的打包工具打包你的 Agent
- 对接 Arena 平台管理员，上传你的 Agent
- 等待系统回测和评估结果

🔗 项目链接与风险提示

官方网站：CUFEL-Q Arena

风险提示：本平台所展示的所有策略回测、持仓记录及投资理念仅用于学术研究、教学演示与技术探索，不构成任何投资建议。历史回测表现不代表未来收益，市场有风险，投资需谨慎。本平台未开展任何实盘交易、代客理财或证券投资咨询业务，亦未向公众募集资金。请勿将本平台内容作为实际投资决策依据。

💬 常见问题

Q1：运行时提示缺少API Key怎么办？

A：在项目根目录创建 .env 文件，添加 LLM_API_KEY=your_api_key。如果没有API Key，可以使用 --only-backtest 参数跳过需要LLM的步骤。

Q2：回测结果不好怎么办？

A：回测结果不好是正常的，重点是理解策略逻辑。你可以尝试调整参数、修改策略逻辑，或者添加新的因子。记住，投资是一场马拉松，不是短跑。

Q3：如何添加新的ETF？

A：在 data/etf/etf_basic.csv 中添加新的ETF信息，然后运行 src/agents/theme_mapper.py 为新ETF打标签。

Q4：如何修改回测基准？

A：在 scripts/run_backtest.py 文件中修改 benchmark_weights 和 benchmark_name 参数。

Q5：项目运行很慢怎么办？

A：LLM调用是最耗时的部分。你可以使用 --only-backtest 参数跳过LLM相关步骤，或者使用更快的LLM模型。

Q6：如何理解宏观状态的四象限模型？

A：四象限模型是根据PMI（经济增长）和CPI（通胀）的组合来划分经济状态：

复苏：PMI↑，CPI↓ → 股票表现好
过热：PMI↑，CPI↑ → 商品表现好
滞胀：PMI↓，CPI↑ → 现金表现好
衰退：PMI↓，CPI↓ → 债券表现好

Q7：政策主题是如何提取的？

A：使用LLM分析政府文件，提取关键词和主题，然后通过频率统计和相关性分析，输出前5个最重要的主题。

Q8：如何评估策略的风险？

A：主要看三个指标：

最大回撤：历史上最大的亏损幅度
夏普比率：每承担一单位风险所获得的超额收益
波动率：策略收益的波动程度

当然可以！以下是针对你的 Q-Macro 项目 和 CUFEL-Q Arena 第10讲作业场景，特别为北航班学生和Agentic Asset Allocation 初学者量身定制的 新增常见问题（FAQ）及答案。这些问题聚焦于“交作业”“跑不通”“改不动”“怕出错”等真实痛点，语言直白、操作导向强。

Q9：我完全没装过 Python / uv ，怎么快速开始？

A：别慌！按顺序做这三步：

安装 Python 3.10+
- 去 python.org 下载安装（勾选 “Add to PATH”）
安装 uv（超快依赖管理器）
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
（Windows 用户可改用 pip install uv）

Q10：为什么我运行后 `portfolios/` 文件夹是空的？

A：大概率是因为你跳过了策略生成阶段。请检查你是否用了 --only-backtest。

✅ 正确流程：

# 先生成组合（需要 LLM 或已有 JSON）
python Q-Macro.py

# 再回测（或一步到位）
python Q-Macro.py

❌ 错误做法：
```
python Q-Macro.py --only-backtest  # 这个只读已有的 JSON
```
如果你没有 LLM API Key，但想看完整流程，我们提供了 预生成的示例组合（见 data/example_portfolios/），你可以手动复制到 portfolios/ 再运行 --only-backtest。

Q11：我想换一个 LLM（比如 DeepSeek 或 Ollama），怎么改？

A：项目设计时就支持灵活切换！你只需修改 .env 文件：

# 示例：使用 Ollama 本地模型
LLM_API_BASE=http://localhost:11434/v1
LLM_API_KEY=ollama
MODEL_NAME=llama3.1:8b

# 示例：使用 DeepSeek
LLM_API_BASE=https://api.deepseek.com/v1
LLM_API_KEY=your_deepseek_key
MODEL_NAME=deepseek-chat

然后确保你的 src/agents/*.py 使用的是统一的 LLM 客户端（当前基于 openai 兼容接口），大多数开源模型都支持。

⚠️ 注意：不同模型输出稳定性不同，建议先用 --only-backtest 测试。

Q12：ETF 标签打错了怎么办？比如把“光伏”标成“新能源车”？

A：标签由 theme_mapper.py 通过 LLM 生成，你可以：

手动修正：直接编辑 data/etf/processed_etf_basic.csv；
改进 Prompt：打开 src/agents/theme_mapper.py，找到 system prompt，加入更明确的分类规则，例如：

“光伏 ETF 必须包含‘太阳能’‘硅片’‘组件’等关键词，不可与锂电池混淆。”
重新打标：运行：
```
python -m src.agents.theme_mapper
```

💡 小技巧：你可以只对新 ETF 打标，保留已有正确标签。

Q13：回测结果比基准差很多，是不是我做错了？

A：不一定！ 回测表现差 ≠ 代码错。

宏观策略本身就有周期性，在“震荡市”或“政策突变期”可能跑输；
重点看 逻辑是否自洽：报告里是否合理解释了配置理由？
一个好的策略不仅看收益，还看 风险控制、创新性、可解释性。

Q14：能不能不用 AKShare？我想用自己的数据源。

A：完全可以！只要你的数据格式对齐：

宏观数据需包含：date, pmi, cpi_yoy, ppi_yoy
ETF 量价数据需包含：date, symbol, open, high, low, close, volume, amount

🎉 结语

Q-Macro 项目不是一个完美的投资策略，而是一个学习工具。通过这个项目，你可以：

学会用 AI 辅助编程：不再害怕写代码，而是把AI当助手
理解宏观驱动的投资逻辑：从经济数据到投资决策的完整链条
掌握模块化开发方法：把复杂问题拆解成可解决的小问题
培养投资思维：学会分析经济环境、解读政策、评估市场风险
建立数据驱动的决策习惯：基于数据而非情绪做投资决策

💡 记住：投资是一场马拉松，不是短跑。 这个项目给你的不是"必胜策略"，而是"思考方法"。

现在，轮到你开始自己的 vibe coding 之旅了！你可以从本地运行 Q-Macro 项目开始，逐步优化你的策略，最终将其封装成一个参赛 Agent，参加 CUFEL-Q Arena 的比赛，与其他选手一较高下。

Happy investing! 🎶

—— 一个让小白也能玩转量化投资的起点

📁 开发Prompt

开发Prompt 文件夹包含了本项目的完整开发过程，记录了从项目初始化到各个模块实现的详细步骤和与AI的交互对话。

文件夹内容

文件名	开发内容	对应模块
`01新建架构.md`	项目目录结构设计	项目架构搭建
`02数据层搭建.md`	宏观数据获取脚本开发	数据获取模块
`03处理宏观数据时间格式.md`	宏观数据时间格式统一处理	数据处理模块
`04模块1宏观状态与景气度开发.md`	宏观状态识别与景气度评分	宏观状态模块
`05模块3ETF初步筛选.md`	ETF流动性筛选与拥挤度检测	市场校准模块
`06模块4ETF组合构建.md`	ETF投资组合构建与权重分配	组合构建模块
`07ETF投资主题与分类AI生成.md`	ETF主题分类与标签生成	ETF标签模块
`08ETF投资主题与分类AI生成改进.md`	ETF标签系统优化	ETF标签模块
`09第一次系统集成.md`	系统集成与批量回测	系统集成
`10模块2政策本文分析AI生成.md`	政策文本分析与主题提取	政策解读模块
`11投资策略报告生成.md`	投资策略报告自动生成	报告生成模块
`Qwen交互对话记录.pdf`	与Qwen Max的完整交互对话	策略调研与设计

如何使用

按顺序阅读：从 01新建架构.md 开始，按照开发顺序阅读，可以了解项目的完整构建过程
参考实现：每个Prompt文件都包含了具体的代码实现和开发思路，可以作为学习和参考的资料
复用Prompt：可以根据自己的需求修改Prompt，用于开发类似的功能模块
理解AI协作：通过查看与AI的交互对话，学习如何有效地与AI协作开发

教学价值

透明开发过程：展示了从0到1构建复杂项目的完整过程
AI协作范例：提供了与AI有效协作的实际案例
模块化开发思路：每个模块都有独立的开发文档，便于理解和学习
可复制的方法：通过学习这些Prompt，可以掌握用AI辅助开发的方法

这个文件夹是本项目的重要组成部分，对于希望深入了解项目开发过程的学习者来说，是非常有价值的学习资料。

🛠 第一部分：题目解析与开发流程​

📝 题目解析​

🗺 开发流程图（小白友好版）​

📚 关键开发步骤（按时间顺序）​

🏗 第二部分：最终完整项目架构展示​

📁 项目结构​

🧩 核心功能亮点​

▶️ 如何运行​

1. 环境准备​

2. 一键运行完整流程​

3. 查看结果​

🚀 第三部分：轮到你了！​

（一）基础任务（必做）​

Task1: 投资策略与代码框架设计​

Task2: 数据层搭建​

Task3: 宏观状态识别模块搭建​

Task4: 市场校准（ETF初步筛选）模块搭建​

Task5: 政策解读模块解析​

Task6: ETF主题映射模块解析​

Task7: 投资组合构建模块解析​

Task8: 报告生成模块解析​

Task9: 回测模块解析​

Task10: 运行与调试​

（二）进阶任务（选做）​

（三）创意任务（挑战）​

🏆 第四部分：CUFEL-Q-Arena 项目介绍​

ℹ️ 什么是 CUFEL-Q-Arena​

🔄 如何将 Q-Macro 项目与 CUFEL-Q Arena 结合​

🔗 项目链接与风险提示​

💬 常见问题​

Q1：运行时提示缺少API Key怎么办？​

Q2：回测结果不好怎么办？​

Q3：如何添加新的ETF？​

Q4：如何修改回测基准？​

Q5：项目运行很慢怎么办？​

Q6：如何理解宏观状态的四象限模型？​

Q7：政策主题是如何提取的？​

Q8：如何评估策略的风险？​

Q9：我完全没装过 Python / uv ，怎么快速开始？​

Q10：为什么我运行后 portfolios/ 文件夹是空的？​

Q11：我想换一个 LLM（比如 DeepSeek 或 Ollama），怎么改？​

Q12：ETF 标签打错了怎么办？比如把“光伏”标成“新能源车”？​

Q13：回测结果比基准差很多，是不是我做错了？​

Q14：能不能不用 AKShare？我想用自己的数据源。​

🎉 结语​

📁 开发Prompt​

文件夹内容​

如何使用​

教学价值​

🛠 第一部分：题目解析与开发流程

📝 题目解析

🗺 开发流程图（小白友好版）

📚 关键开发步骤（按时间顺序）

🏗 第二部分：最终完整项目架构展示

📁 项目结构

🧩 核心功能亮点

▶️ 如何运行

1. 环境准备

2. 一键运行完整流程

3. 查看结果

🚀 第三部分：轮到你了！

（一）基础任务（必做）

Task1: 投资策略与代码框架设计

Task2: 数据层搭建

Task3: 宏观状态识别模块搭建

Task4: 市场校准（ETF初步筛选）模块搭建

Task5: 政策解读模块解析

Task6: ETF主题映射模块解析

Task7: 投资组合构建模块解析

Task8: 报告生成模块解析

Task9: 回测模块解析

Task10: 运行与调试

（二）进阶任务（选做）

（三）创意任务（挑战）

🏆 第四部分：CUFEL-Q-Arena 项目介绍

ℹ️ 什么是 CUFEL-Q-Arena

🔄 如何将 Q-Macro 项目与 CUFEL-Q Arena 结合

🔗 项目链接与风险提示

💬 常见问题

Q1：运行时提示缺少API Key怎么办？

Q2：回测结果不好怎么办？

Q3：如何添加新的ETF？

Q4：如何修改回测基准？

Q5：项目运行很慢怎么办？

Q6：如何理解宏观状态的四象限模型？

Q7：政策主题是如何提取的？

Q8：如何评估策略的风险？

Q9：我完全没装过 Python / uv ，怎么快速开始？

Q10：为什么我运行后 `portfolios/` 文件夹是空的？

Q11：我想换一个 LLM（比如 DeepSeek 或 Ollama），怎么改？

Q12：ETF 标签打错了怎么办？比如把“光伏”标成“新能源车”？

Q13：回测结果比基准差很多，是不是我做错了？

Q14：能不能不用 AKShare？我想用自己的数据源。

🎉 结语

📁 开发Prompt

文件夹内容

如何使用

教学价值