Metadata-Version: 2.4
Name: awesome-trading-strategy
Version: 0.1.0
Summary: Awesome Trading Strategy Skill - CLI tool for strategy management, journals, and signals
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: ccxt>=4.5.44
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0

# Trading Strategy (交易策略管理工具)

一个自动化命令行 (CLI) 工具，用于管理你的交易策略、记录交易日志以及生成交易表现复盘报告。

目前该项目使用 [`uv`](https://github.com/astral-sh/uv) 进行环境和依赖管理。`uv` 是一个极其快速的 Python 包和项目管理器。

## 核心功能

- **策略管理**：创建、查看、更新和列出你的各种交易策略。
- **交易日志 (Journaling)**：详细记录你执行的每一笔交易，包括进出场逻辑、盈亏 (PnL)、多维度打分和情绪状态。
- **报告与复盘**：根据已记录的交易事实，自动生成每周和每月的复盘日志与相关统计指标。
- **信号生成**：基于技术指标自动生成买卖信号，支持双均线、海龟交易、组合策略等。

## 安装指南

### 方式一：开发模式 (推荐)

请确保你已经安装了 `uv` 工具，然后在这个项目根目录下执行以下命令：

```bash
uv sync
```

### 方式二：正式安装

通过 pip 安装发布版本：

```bash
pip install trading-strategy

# 首次使用需初始化用户数据目录
awesome-trading-strategy init
```

*(注意：本项目要求 Python 3.12 及以上版本)*

## 运行模式

本项目支持两种运行模式，数据存储位置不同：

| 模式 | 触发条件 | 数据目录 |
|------|---------|---------|
| **开发模式** | `uv run` 或 `pip install -e .` 且当前目录有 `trading.yaml` | 项目目录 `./data/` |
| **安装模式** | `pip install` 后在任意目录运行 | 用户目录 `~/.awesome-trading-strategy/` |

### 数据目录结构

```
# 开发模式 - 项目目录
./configs/
├── trading.yaml           # 主配置
├── signal-params.yaml     # 信号参数
└── macro_state.yaml       # 宏观风控状态
./data/
├── journals/{YYYY-MM}/    # 交易日志
├── signals/{YYYY-MM}/     # 信号记录
├── strategies/custom/     # 自定义策略 (动态加载)
└── reviews/               # 复盘报告

# 安装模式 - 用户目录 (~/.awesome-trading-strategy/)
结构同上，init 时从项目 configs/ 复制默认配置
```

## 使用方法

### 开发模式

```bash
uv run python -m scripts.cli --help
```

### 安装模式

```bash
awesome-trading-strategy --help
```

### 常用命令示例

**1. 创建新交易策略**
```bash
# 开发模式
uv run python -m scripts.cli create-strategy --name "均线突破" --type "趋势" --markets "加密货币" --timeframes "1H,4H" --entry "价格突破阻力位" --stop "放在近期波段低点下方"

# 安装模式
awesome-trading-strategy create-strategy --name "均线突破" --type "趋势" --markets "加密货币" --timeframes "1H,4H" --entry "价格突破阻力位" --stop "放在近期波段低点下方"
```

**2. 列出所有策略**
```bash
uv run python -m scripts.cli list-strategies --status active
```

**3. 查看某个策略详情**
```bash
uv run python -m scripts.cli get-strategy --name "均线突破"
```

**4. 更新一个策略**
```bash
uv run python -m scripts.cli update-strategy --name "均线突破" --status active --reason "策略已回测，准备部署实盘"
```

**5. 记录一笔真实交易 (日志)**
```bash
uv run python -m scripts.cli record-trade --symbol "BTCUSDT" --direction "long" --entry-price "60000" --exit-price "65000" --strategy "均线突破" --size "0.1"
```

**6. 查询过去的交易记录**
```bash
uv run python -m scripts.cli query-journals --strategy "均线突破" --result "win"
```

**7. 生成复盘报告**
```bash
uv run python -m scripts.cli generate-review --type weekly --week "this"
uv run python -m scripts.cli generate-review --type monthly --month "last"
```

### 全局可选参数

- `--format [json|markdown]`：选择终端的文本输出格式 (默认格式是 `json`)。
- `--config`：提供一个自定义 `.yaml` 配置文件的路径。

例如 (使用 Markdown 格式让输出更易读)：
```bash
uv run python -m scripts.cli --format markdown list-strategies
```

## 项目结构概览

```
trading-strategy/
├── scripts/                # 核心 Python 模块
│   ├── __init__.py
│   ├── cli.py              # 命令行入口
│   ├── config.py           # 配置加载器
│   ├── strategy_manager.py # 策略管理
│   ├── journal_manager.py  # 日志管理
│   ├── signal_manager.py   # 信号管理
│   ├── signal_engine.py    # 信号引擎
│   ├── risk_filter.py      # 风控过滤
│   ├── review_generator.py # 复盘生成
│   └── resources/          # 包内置资源 (随包安装)
│       └── templates/      # 模板文件
├── configs/                # 配置文件
│   ├── trading.yaml        # 主配置
│   ├── signal-params.yaml  # 信号参数
│   └── macro_state.yaml    # 宏观风控状态
├── data/                   # 数据存储 (开发模式)
│   ├── journals/
│   ├── signals/
│   ├── strategies/custom/
│   └── reviews/
├── references/             # 文档说明
├── examples/               # 示例数据
├── docs/                   # 文档
└── pyproject.toml          # 项目配置
```

---

## 信号系统

### 内置策略

| 策略名称 | 说明 | 适用场景 |
|----------|------|----------|
| `ma_crossover` | 双均线交叉（纯K线分析） | 趋势行情 |
| `ma_position_aware` | 持仓感知均线策略 | 结合实际仓位决策 |
| `turtle` | 海龟交易/唐奇安通道 | 突破行情 |
| `rsi` | RSI 超买超卖 | 震荡行情 |
| `macd` | MACD 交叉 | 趋势确认 |
| `bollinger` | 布林带突破 | 波动率交易 |
| `composite` | 技术+新闻组合 | 需要消息面过滤 |

### 信号生成示例

```bash
# 1. 首先获取市场数据（需要安装 ccxt: uv add ccxt）
uv run python scripts/fetch_data.py --symbol BTC/USDT --timeframe 4h --output data/btc_latest.yaml

# 2. 生成信号
uv run python -m scripts.cli generate-signals \
  --symbols "BTC/USDT" \
  --strategy ma_crossover \
  --data-file data/btc_latest.yaml \
  --save

# 2b. 多文件导入（K线+新闻自动合并）
uv run python -m scripts.cli generate-signals \
  --symbols "BTC/USDT" \
  --strategy news_sentiment \
  --data-file data/btc_latest.yaml \
  --data-file data/news.yaml \
  --save

# 3. 查看历史信号
uv run python -m scripts.cli list-signals --symbol BTC/USDT
```

### 风控管理

```bash
# 查看当前风控状态
uv run python -m scripts.cli get-macro-state

# 暂停所有交易
uv run python -m scripts.cli set-macro-state --risk-on false

# 恢复交易
uv run python -m scripts.cli set-macro-state --risk-on true
```

---

## 文档索引

### 新手必读

| 文档 | 说明 |
|------|------|
| [新手完全指南](docs/beginner-guide.md) | 从零开始使用本项目的完整教程 |
| [系统完整指南](docs/system-guide.md) | **核心文档**：所有功能模块详解、业务逻辑、功能关联图谱 |
| [数据导入规范](docs/data-import-spec.md) | 详细的数据格式说明和获取方法 |
| [策略迭代指南](docs/strategy-iteration-guide.md) | 如何持续优化和迭代策略 |

### 测试数据

| 文件 | 说明 |
|------|------|
| [examples/README.md](examples/README.md) | 测试数据索引 |
| [examples/ma_crossover_long.yaml](examples/ma_crossover_long.yaml) | 双均线做多信号示例 |
| [examples/position_aware_example.yaml](examples/position_aware_example.yaml) | 持仓感知策略示例 |
| [examples/turtle_long.yaml](examples/turtle_long.yaml) | 海龟策略突破示例 |
| [examples/composite_blocked.yaml](examples/composite_blocked.yaml) | 组合策略过滤示例 |

### 参考文档

| 文档 | 说明 |
|------|------|
| [信号使用指南](references/signal-usage-guide.md) | 信号系统详细说明 |
| [数据适配指南](references/data-adapter-guide.md) | 数据适配器开发指南 |
| [策略模板](references/strategy-template.md) | 创建策略的模板 |
| [交易日志模板](references/journal-template.md) | 交易日志格式 |

---

## 快速开始

```bash
# 1. 安装依赖
uv sync

# 2. 列出可用策略引擎
uv run python -m scripts.cli list-strategy-engines

# 3. 使用示例数据测试
uv run python -m scripts.cli generate-signals \
  --symbols "BTC/USDT" \
  --strategy ma_crossover \
  --data-file examples/ma_crossover_long.yaml

# 3b. 多文件导入示例（新闻情绪策略）
uv run python -m scripts.cli generate-signals \
  --symbols "BTC/USDT,ETH/USDT" \
  --strategy news_sentiment \
  --data-file examples/news_sentiment_test.yaml

# 4. 创建你的第一个策略
uv run python -m scripts.cli create-strategy \
  --name "我的策略" \
  --type "趋势" \
  --markets "加密货币" \
  --timeframes "4H" \
  --entry "突破前高" \
  --stop "放在支撑位下方"
```

---

## 许可证

MIT License
