Document virtualenv setup commands

Author: jjckson

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+.env

README.md

@@ -1 +1,108 @@
-# 1
+# 量化交易自动化流水线
+
+本项目提供一个端到端的自动化交易流程示例，涵盖以下四个核心阶段：
+
+1. 每 3 分钟通过 Futu OpenAPI 采集行情与账户信息。
+2. 将原始数据整理成结构化的 Prompt 载荷。
+3. 将 Prompt 发送至兼容 DeepSeek 的大语言模型获取交易决策。
+4. 根据决策结果调用 Futu 交易接口自动下单。
+
+> **免责声明：** 本项目仅用于学习与技术验证，真实资金交易存在重大风险，请谨慎使用。
+
+## 项目结构
+
+```
+src/
+├── main.py                # 命令行入口，负责流程编排
+└── trading_bot/
+    ├── __init__.py        # 包装对外可用的公共接口
+    ├── data_fetcher.py    # Futu 行情与账户数据采集逻辑
+    ├── data_models.py     # 组件间共享的 Pydantic 数据模型
+    ├── indicators.py      # 技术指标计算工具
+    ├── llm_client.py      # DeepSeek/OpenAI API 调用封装
+    ├── order_executor.py  # 下单与交易模式控制
+    └── scheduler.py       # 异步调度器，协调周期性任务
+```
+
+## 安装
+
+1. 在终端创建并激活 Python 3.10 及以上版本的虚拟环境：
+
+   ```bash
+   python -m venv .venv
+   # Linux / macOS
+   source .venv/bin/activate
+   # Windows PowerShell
+   .\.venv\Scripts\Activate.ps1
+   ```
+
+2. 安装项目依赖：
+
+   ```bash
+   pip install -e .
+   ```
+
+3. 确保本地已启动并可访问 Futu OpenD 服务。
+
+## 环境配置
+
+将 `env.example` 复制为 `.env`，并根据实际情况填写变量：
+
+- `DEEPSEEK_API_KEY`：DeepSeek 兼容接口的 API Key（若未设置则回退至 `OPENAI_API_KEY`）。
+- `DEEPSEEK_API_BASE_URL`：自定义 DeepSeek API 地址（可选）。
+- `FUTU_HOST`：Futu OpenD 服务的主机名或 IP。
+- `FUTU_QUOTE_PORT` / `FUTU_TRADE_PORT`：OpenD 暴露的行情与交易端口。
+- `FUTU_OPENAPI_APP_ID` / `FUTU_OPENAPI_APP_SECRET`：富途牛牛提供的 OpenAPI 应用凭证。
+- `FUTU_TRADE_PASSWORD`：解锁真实交易所需的交易密码（仅在实盘模式必填）。
+- `FUTU_TRADING_MODE`：交易模式，`paper` 表示模拟交易，`live` 表示真实交易（默认 `paper`）。
+- `FUTU_TRADING_MARKET`：交易市场，支持 `hk`（港股）、`us`（美股）和 `cn`（A 股）。
+- `FUTU_ACCOUNT_ID`：在存在多个交易账户时指定具体账户（可选）。
+- `POLL_INTERVAL_SECONDS`：默认轮询周期（秒），当未通过 CLI 指定时使用。
+- `HK_SYMBOLS`：逗号分隔的港股代码列表，例如 `HK.00700,HK.00005`。
+- `CN_SYMBOLS`：逗号分隔的 A 股代码列表，例如 `SH.000300,SZ.000001`。
+- `US_SYMBOLS`：逗号分隔的美股代码列表，例如 `US.AAPL,US.MSFT`。
+
+## 使用说明
+
+通过命令行运行交易循环，并指定需要跟踪的股票代码：
+
+```bash
+python -m trading_bot.main SH.000300
+```
+
+常用命令行参数：
+
+- `--interval`：轮询周期（秒），默认 180。
+- `--language`：Prompt 语言，可选 `en` 或 `zh`。
+- `--host` / `--quote-port` / `--trade-port`：Futu OpenD 连接参数。
+- `--trading-mode`：`paper` 或 `live`，切换模拟/实盘环境。
+- `--trading-market`：订单路由市场，支持 `hk`、`us`、`cn`。
+- `--trade-password`：交易密码（若未设置则回退至 `FUTU_TRADE_PASSWORD`）。
+- `--account-id`：指定使用的 Futu 账户 ID（若未设置则回退至 `FUTU_ACCOUNT_ID`）。
+- `--log-level`：日志等级。
+
+当命令行未显式传入股票代码时，程序会依次读取环境变量 `HK_SYMBOLS`、`CN_SYMBOLS` 与 `US_SYMBOLS` 作为默认跟踪列表。
+
+按下 `Ctrl+C` 可以安全退出循环。
+
+## 扩展方向
+
+- 通过继承 `PromptFormatter` 自定义 Prompt 模板或语言风格。
+- 在 `OrderExecutor` 中加入风控或仓位管理策略以增强安全性。
+- 扩展 `TradingScheduler`，将行情与决策结果落盘持久化或推送到外部系统。
+
+## 测试
+
+安装开发依赖并运行自动化测试：
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+如只需验证语法，可执行：
+
+```bash
+python -m compileall src
+```
+

env.example

@@ -0,0 +1,24 @@
+# Copy this file to .env and fill in the required values.
+
+# DeepSeek / OpenAI configuration
+DEEPSEEK_API_KEY=your-deepseek-api-key
+DEEPSEEK_API_BASE_URL=https://api.deepseek.com
+
+# Futu OpenD connection settings and API credentials
+FUTU_HOST=127.0.0.1
+FUTU_QUOTE_PORT=11111
+FUTU_TRADE_PORT=11111
+FUTU_OPENAPI_APP_ID=your-opend-app-id
+FUTU_OPENAPI_APP_SECRET=your-opend-app-secret
+FUTU_TRADE_PASSWORD=your-trading-password
+FUTU_TRADING_MODE=paper
+FUTU_TRADING_MARKET=hk
+FUTU_ACCOUNT_ID=
+
+# Default polling interval in seconds for the trading loop
+POLL_INTERVAL_SECONDS=180
+
+# Comma-separated symbol lists for each market (use official codes)
+HK_SYMBOLS=HK.00700,HK.00005
+CN_SYMBOLS=SH.000300,SZ.000001
+US_SYMBOLS=US.AAPL,US.MSFT

pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "trading-bot"
+version = "0.1.0"
+description = "Automated trading pipeline integrating Futu market data, prompt generation, LLM decisioning, and order execution."
+requires-python = ">=3.10"
+authors = [
+  { name = "Automated Agent" }
+]
+dependencies = [
+  "futu-api>=7.2.4600",
+  "pydantic>=2.7",
+  "openai>=1.3",
+  "httpx>=0.27",
+  "python-dotenv>=1.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4"
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

src/main.py

@@ -0,0 +1,183 @@
+"""Command line entry point for the automated trading workflow."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import signal
+from contextlib import suppress
+from typing import List, Optional
+
+from dotenv import load_dotenv
+
+from trading_bot import (
+    DeepSeekLLMClient,
+    FutuDataFetcher,
+    OrderExecutor,
+    PromptFormatter,
+    TradingScheduler,
+)
+from trading_bot.order_executor import resolve_trading_market, resolve_trading_mode
+
+LOGGER = logging.getLogger(__name__)
+
+
+def parse_args(argv: List[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Automated trading pipeline")
+    parser.add_argument("symbols", nargs="*", help="Symbols to monitor, e.g. SH.000300")
+    parser.add_argument("--interval", type=int, default=None, help="Polling interval in seconds")
+    parser.add_argument("--language", choices=["en", "zh"], default="en", help="Prompt language")
+    parser.add_argument("--host", default=None, help="Futu OpenD host")
+    parser.add_argument("--quote-port", type=int, default=None, help="Futu quote port")
+    parser.add_argument("--trade-port", type=int, default=None, help="Futu trade port")
+    parser.add_argument("--log-level", default="INFO", help="Logging level")
+    parser.add_argument(
+        "--trading-mode",
+        choices=["paper", "live"],
+        default=None,
+        help="Trading environment to use (paper or live)",
+    )
+    parser.add_argument(
+        "--trading-market",
+        choices=["hk", "us", "cn"],
+        default=None,
+        help="Market to route orders to",
+    )
+    parser.add_argument(
+        "--trade-password",
+        default=None,
+        help="Trading password to unlock the account",
+    )
+    parser.add_argument(
+        "--account-id",
+        default=None,
+        help="Specific trading account identifier",
+    )
+    return parser.parse_args(argv)
+
+
+def _get_int_setting(env_name: str, cli_value: int | None, default: int) -> int:
+    if cli_value is not None:
+        return cli_value
+    env_value = os.getenv(env_name)
+    if env_value is None or env_value.strip() == "":
+        return default
+    try:
+        return int(env_value)
+    except ValueError as exc:
+        raise ValueError(f"Environment variable {env_name} must be an integer, got {env_value!r}") from exc
+
+
+def _get_str_setting(env_name: str, cli_value: Optional[str], default: Optional[str] = None) -> Optional[str]:
+    if cli_value is not None and cli_value.strip() != "":
+        return cli_value
+    env_value = os.getenv(env_name)
+    if env_value is None or env_value.strip() == "":
+        return default
+    return env_value
+
+
+def _resolve_symbols(cli_symbols: List[str]) -> List[str]:
+    if cli_symbols:
+        return cli_symbols
+    symbols: List[str] = []
+    for env_name in ("HK_SYMBOLS", "CN_SYMBOLS", "US_SYMBOLS"):
+        env_value = os.getenv(env_name, "")
+        symbols.extend([s.strip() for s in env_value.split(",") if s.strip()])
+    if symbols:
+        return symbols
+    raise ValueError(
+        "No symbols specified. Provide symbols via CLI arguments or set HK_SYMBOLS/CN_SYMBOLS/US_SYMBOLS in the environment."
+    )
+
+
+async def main_async(args: argparse.Namespace) -> None:
+    logging.basicConfig(level=getattr(logging, args.log_level.upper(), logging.INFO))
+    load_dotenv()
+
+    host = args.host or os.getenv("FUTU_HOST", "127.0.0.1")
+    quote_port = _get_int_setting("FUTU_QUOTE_PORT", args.quote_port, 11111)
+    trade_port = _get_int_setting("FUTU_TRADE_PORT", args.trade_port, 11111)
+    interval = _get_int_setting("POLL_INTERVAL_SECONDS", args.interval, 180)
+    symbols = _resolve_symbols(args.symbols)
+    trading_mode = _get_str_setting("FUTU_TRADING_MODE", args.trading_mode, "paper")
+    trading_market = _get_str_setting("FUTU_TRADING_MARKET", args.trading_market, "hk")
+    trade_password = _get_str_setting("FUTU_TRADE_PASSWORD", args.trade_password)
+    account_id = _get_str_setting("FUTU_ACCOUNT_ID", args.account_id)
+    futu_app_id = _get_str_setting("FUTU_OPENAPI_APP_ID", None)
+    futu_app_secret = _get_str_setting("FUTU_OPENAPI_APP_SECRET", None)
+
+    data_fetcher = FutuDataFetcher(host=host, quote_port=quote_port, account_port=trade_port)
+    prompt_formatter = PromptFormatter(language=args.language)
+    llm_client = DeepSeekLLMClient()
+    order_executor = OrderExecutor(
+        host=host,
+        port=trade_port,
+        trd_env=resolve_trading_mode(trading_mode or "paper"),
+        trd_market=resolve_trading_market(trading_market or "hk"),
+        trade_password=trade_password,
+        account_id=account_id,
+        app_id=futu_app_id,
+        app_secret=futu_app_secret,
+    )
+    scheduler = TradingScheduler(
+        data_fetcher=data_fetcher,
+        prompt_formatter=prompt_formatter,
+        llm_client=llm_client,
+        order_executor=order_executor,
+        symbols=symbols,
+        interval_seconds=interval,
+    )
+
+    loop = asyncio.get_running_loop()
+    stop_event = asyncio.Event()
+
+    def _handle_stop(*_: object) -> None:
+        LOGGER.info("Received stop signal. Shutting down...")
+        stop_event.set()
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, _handle_stop)
+
+    scheduler_task = asyncio.create_task(scheduler.start())
+    stop_task = asyncio.create_task(stop_event.wait())
+
+    done, pending = await asyncio.wait({scheduler_task, stop_task}, return_when=asyncio.FIRST_COMPLETED)
+    if stop_task in done:
+        LOGGER.info("Stop event acknowledged.")
+    if scheduler_task in done:
+        exc = scheduler_task.exception()
+        if exc:
+            raise exc
+
+    stop_event.set()
+    await scheduler.stop()
+    scheduler.shutdown()
+
+    for task in pending:
+        task.cancel()
+        with suppress(asyncio.CancelledError):
+            await task
+    scheduler_task.cancel()
+    with suppress(asyncio.CancelledError):
+        await scheduler_task
+    stop_task.cancel()
+    with suppress(asyncio.CancelledError):
+        await stop_task
+
+
+def main() -> None:
+    args = parse_args()
+    try:
+        asyncio.run(main_async(args))
+    except KeyboardInterrupt:
+        LOGGER.info("Interrupted by user")
+    except ValueError as exc:
+        LOGGER.error("%s", exc)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":
+    main()

src/trading_bot/__init__.py

@@ -0,0 +1,23 @@
+"""Trading bot package integrating data collection, prompt formatting, LLM decisioning, and order execution."""
+
+from .data_models import MarketDataPayload, AccountData, TradingDecision, OrderRequest, OrderResponse
+from .data_fetcher import FutuDataFetcher
+from .prompt_formatter import PromptFormatter
+from .llm_client import DeepSeekLLMClient
+from .order_executor import OrderExecutor, resolve_trading_market, resolve_trading_mode
+from .scheduler import TradingScheduler
+
+__all__ = [
+    "MarketDataPayload",
+    "AccountData",
+    "TradingDecision",
+    "OrderRequest",
+    "OrderResponse",
+    "FutuDataFetcher",
+    "PromptFormatter",
+    "DeepSeekLLMClient",
+    "OrderExecutor",
+    "resolve_trading_mode",
+    "resolve_trading_market",
+    "TradingScheduler",
+]