# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个基于crewAI框架构建的ETF基金投资分析团队系统。项目使用Python 3.12-3.14版本，使用UV作为依赖管理工具。系统通过多个AI代理协作完成ETF数据获取、技术指标分析、投资建议生成和报告汇总。

## 架构概览

### 核心组件
1. **多代理系统** (`src/investment_team/crew.py`):
   - `InvestmentTeam`: 正常ETF筛选团队，包含预测分析师代理
   - `InvestmentTeamWithSummary`: 汇总分析团队，包含汇总分析师代理
   - 使用YAML配置文件定义代理和任务 (`config/agents.yaml`, `config/tasks.yaml`)

2. **数据处理层** (`src/investment_team/utils/`):
   - `etf_data.py`: ETF数据获取（使用雪球 API：kline 历史K线 + quotec 实时行情，无头浏览器获取 cookie）
   - `etf_indicators.py`: 技术指标计算
   - `csv_utils.py`: CSV文件读写
   - `logger.py`: 日志工具

3. **配置管理** (`src/investment_team/config/`):
   - `llm_config.py`: LLM模型配置（支持OpenAI兼容API）
   - `agents.yaml`: 代理角色定义
   - `tasks.yaml`: 任务定义
   - `funds.yaml`: 基金列表配置

4. **运行控制** (`src/investment_team/main.py`):
   - 支持多种运行模式：正常分析、仅生成CSV、从CSV生成报告、归档汇总
   - 支持并行调用大模型
   - 支持归档和汇总功能

### 文件组织
- `out/`: 当前运行结果输出目录（按日期组织）
- `archive/`: 历史分析结果归档目录
- `knowledge/`: 知识库目录（用户偏好设置）
- `scripts/`: 辅助脚本目录

## 常用命令

### 环境设置
```bash
# 安装依赖（使用UV）
crewai install

# 安装无头浏览器 Chromium（用于访问雪球网获取 cookie，供 K 线与实时行情接口使用）
playwright install chromium

# 激活虚拟环境
source .venv/bin/activate
```

### 运行项目
```bash
# 使用主启动脚本（推荐）
./start.sh <count> [--a|--archive|-a] [--s|--with-summary|-s]

# 示例：
./start.sh 1                    # 执行1次分析
./start.sh 2 --a                # 执行2次分析，归档
./start.sh 1 --s                # 执行1次分析，完成后汇总
./start.sh 2 --a --s            # 执行2次分析，归档，完成后汇总

# 仅生成CSV文件（不调用大模型）
./start.sh --csv-only [--a|--archive|-a]
# 输出完整字段的 CSV：使用 --full-fields、-F 或 --csv-full
./start.sh --csv-only --full-fields [--a|--archive|-a]

# 从CSV文件生成报告
./start.sh --csv <csv_path> [--count <count>] [--a|--archive|-a] [--s|--with-summary|-s]

# 从归档执行汇总分析
./start.sh --date <YYYYMMDD> 或 ./start.sh -d <YYYYMMDD>
```

### 直接使用Python模块
```bash
# 正常分析流程
python -m investment_team.main --count 1 --archive --with-summary

# 从CSV文件生成报告
python -m investment_team.main --csv-file out/20260113/20260113_161427_etf_all_data.csv --count 2 --archive --with-summary

# 从归档执行汇总分析
python -m investment_team.main --date 20260109
```

### 测试
```bash
# 运行ETF数据获取测试（需要网络连接）
python -m src.investment_team.tests.test_etf_data

# 运行ETF数据列测试
python -m src.investment_team.tests.test_etf_data_columns
```

## 配置说明

### 环境变量 (`.env`文件)
```bash
# OpenAI兼容API配置
OPENAI_API_KEY=your_api_key
OPENAI_API_BASE=https://api.gpt.ge/v1  # 默认代理服务地址

# 模型配置
PREDICTION_MODEL=gpt-4.1              # 预测分析师使用的模型
SUMMARY_MODEL=gpt-4.1                 # 汇总分析师使用的模型（可选，默认使用PREDICTION_MODEL）
```

### 基金列表配置
- 主配置文件: `src/investment_team/config/funds.yaml`
- 基金列表文件: `src/investment_team/config/fundList.txt`
- 支持多个基金列表文件，通过`--fund-list`参数指定

### LLM配置 (`src/investment_team/config/llm_config.py`)
- 使用OpenAI兼容格式调用大模型
- 支持角色特定的温度设置：
  - 预测分析师: temperature=1.0, max_tokens=25000
  - 汇总分析师: temperature=1.0, max_tokens=25000
- 禁用stop words支持以兼容某些API服务

## 开发注意事项

### 代码结构
1. **代理定义**: 使用`@CrewBase`装饰器定义代理类，通过YAML配置文件管理代理属性
2. **任务定义**: 使用`@task`装饰器定义任务，任务描述支持占位符替换
3. **数据流**: 数据通过`@before_kickoff`装饰器注入到任务上下文中
4. **输出管理**: 输出文件路径通过`generate_output_file_path`函数生成，支持时间戳和线程名

### 并行处理
- 使用`ThreadPoolExecutor`实现并行大模型调用
- 每个线程生成独立的报告文件，文件名包含线程名和时间戳
- 支持汇总分析，将多个并行分析结果合并为综合报告

### 归档系统
- 所有输出文件按日期归档到`archive/`目录
- 支持从归档目录重新执行汇总分析
- 归档文件名格式: `YYYYMMDD_HHMMSS_<thread_name>_etf_selection_report.md`

### 日志系统
- 使用统一的日志工具记录执行过程
- 日志文件保存在`out/<date>/`目录下
- 日志包含时间戳、线程名、调用索引等信息

## 故障排除

### 常见问题
1. **API调用失败**: 检查`.env`文件中的API配置，确保网络连接正常
2. **数据获取失败**: 数据来源为雪球（xueqiu）。首次运行或 cookie 失效时程序会用无头浏览器访问雪球获取 cookie；若失败可尝试有头浏览器验证（见 COOKIE_SETUP.md）。请求报错时完整请求报文会写入日志便于排查。
3. **内存不足**: 大量ETF数据可能导致内存压力，可减少`limit`参数或使用`--csv-only`模式
4. **文件路径错误**: 确保项目根目录结构正确，输出目录有写入权限

### 调试建议
- 启用详细日志: `verbose=True`已在代理配置中启用
- 查看完整prompt: 程序会自动保存完整prompt到输出目录
- 检查CSV文件: 使用`--csv-only`模式生成CSV文件，验证数据获取是否正常

## 扩展开发

### 添加新代理
1. 在`src/investment_team/crew.py`中添加新的`@agent`方法
2. 在`src/investment_team/config/agents.yaml`中配置代理属性
3. 在`src/investment_team/config/tasks.yaml`中配置相关任务

### 添加新任务
1. 在`src/investment_team/crew.py`中添加新的`@task`方法
2. 在`src/investment_team/config/tasks.yaml`中配置任务属性
3. 更新`@before_kickoff`方法以准备任务数据

### 添加新数据源
1. 在`src/investment_team/utils/`目录下创建新的数据获取模块
2. 集成到`fetch_all_funds_data`函数中
3. 更新数据格式化逻辑以支持新数据字段