trade

基于长桥 OpenAPI 的量化交易与信号项目。当前默认策略为 CallMacd（自选股 MACD 扫描 + 飞书通知）。

更完整的架构说明见 DESIGN.md。

安装

使用本机 python3 / pip 安装依赖（不创建虚拟环境）：

cd /Users/lyoid/code/trade   # 换成你的项目路径
./scripts/setup_venv.sh      # python3 -m pip install -r requirement.txt
./scripts/verify_env.sh      # 按 requirement.txt 检查依赖是否已安装

日常命令：

python3 main.py --once
./scripts/run_callmacd_once.sh

配置（环境变量）

所有配置均通过环境变量加载，不再使用 config.yaml。首次克隆后：

cp .env.example .env
# 编辑 .env，填入长桥与飞书凭证及 TRADE_LOG_PATH
python3 scripts/check_config.py   # 校验配置是否完整

python main.py 与 config.py 会自动读取项目根目录下的 .env（若存在）；cron 脚本 run_callmacd_once.sh 也会 source .env。

.env 已在 .gitignore 中，切勿提交。

必填环境变量

变量	说明
LONGPORT_APP_KEY	长桥 App Key
LONGPORT_APP_SECRET	长桥 App Secret
LONGPORT_ACCESS_TOKEN	长桥 Access Token
FEISHU_APP_ID	飞书应用 ID
FEISHU_APP_SECRET	飞书应用 Secret
FEISHU_OPEN_ID	飞书接收人 open_id

常用可选变量

变量	默认值	说明
TRADE_LOG_PATH	./log	日志目录
TRADE_LOG_NAME	CallMacd	日志文件名
TRADE_STRATEGY_NAME	CallMacd	策略名
TRADE_STRATEGY_PERIOD_1/2/3	12/26/9	MACD 周期
TRADE_STOCK_ID	—	逗号分隔标的（NetTrader/MACD 用）
TRADE_SCHEDULER_ENABLED	false	内置定时调度
TRADE_SCHEDULER_RUN_TIMES	09:35:00,21:25:00	内置调度时点（文档参考）
TRADE_CALLMACD_CRON_HK_HOUR/MIN	9 / 35	cron 港股/A股扫描（北京时间）
TRADE_CALLMACD_CRON_US_HOUR/MIN	21 / 25	cron 美股开盘前扫描（北京时间）
TRADE_RISK_ENABLED	true	下单策略风控开关
TRADE_RISK_MAX_ORDER_AMOUNT	10000	单笔最大股数
TRADE_RISK_MAX_POSITION_PER_SYMBOL	0	单标的持仓上限（0=不限）
TRADE_RISK_MAX_PORTFOLIO_SYMBOLS	0	最大持仓标的数（0=不限）
TRADE_RISK_MAX_DAILY_LOSS_AMOUNT	0	单日最大亏损金额（0=不限）
TRADE_RISK_MAX_DAILY_LOSS_PCT	0	单日最大亏损比例（0=不限）
TRADE_CALLMACD_MAX_WORKERS	4	CallMacd 并行扫描线程数
TRADE_CALLMACD_SCAN_DELAY	0	串行模式逐标的间隔（秒）

完整列表见 .env.example。基本面框架见 docs/FUNDAMENTAL.md。

python3 scripts/fundamental_report.py 01810.HK --output

运行测试

python3 -m unittest discover -s tests -v

若密钥曾出现在 git 历史中，请在长桥 / 飞书控制台轮换后再写入 .env。

CallMacd 定时运行（系统 cron）

CallMacd 通过 系统 cron 在工作日两个时点各执行一次，不使用 main.py 内置常驻调度（TRADE_SCHEDULER_ENABLED=false）。

时间（北京时间）	说明
09:35	港股 / A 股 开盘后扫描（9:30 开盘，留 5 分钟等 K 线稳定）
21:25	美股 常规盘开盘前扫描（夏令时约美东 9:25，开盘 9:30 前）

非交易时段的标的会在当次任务内自动跳过；9:35 主要扫港/A 股，21:25 主要扫美股盘前。

安装 cron

cd /path/to/trade
./scripts/install_callmacd_cron.sh

安装后 crontab -l 应包含：

# trade CallMacd
# HK/A-share after open (Beijing 9:35)
35 9 * * 1-5 /path/to/trade/scripts/run_callmacd_once.sh
# US before regular open (Beijing 21:25, ~9:25 ET DST)
25 21 * * 1-5 /path/to/trade/scripts/run_callmacd_once.sh

仅在工作日（周一～周五）触发。时间可在 .env 中覆盖：

TRADE_CALLMACD_CRON_HK_HOUR=9
TRADE_CALLMACD_CRON_HK_MIN=35
TRADE_CALLMACD_CRON_US_HOUR=21
TRADE_CALLMACD_CRON_US_MIN=25

然后重新执行 ./scripts/install_callmacd_cron.sh。

手动执行与查看日志

./scripts/run_callmacd_once.sh
tail -f log/cron.log

等价于：python main.py --once（单次扫描后退出）。

其他运行方式

# 常驻 + 每 10 秒轮询（不推荐用于 CallMacd，仅 NetTrader 等下单策略）
python main.py

---

注意事项

1. 环境变量与密钥

• 复制 .env.example 为 .env 并填入凭证；运行 python3 scripts/check_config.py 校验。
• .env 已 gitignore，不要提交到仓库。
• 长桥 access_token 有过期时间，过期后需更新 .env，否则 cron 任务会失败（错误见 log/cron.log）。

2. macOS 上 cron 可能不执行

macOS 对 cron 限制较严，若到点没有日志、任务未运行，请检查：

• 系统设置 → 隐私与安全性 → 完全磁盘访问：为 cron 或执行脚本的终端应用授权（视系统版本而定）。
• 本机是否使用 cron；部分环境更推荐 launchd，可自行编写 plist 调用 scripts/run_callmacd_once.sh。
• 用 crontab -l 确认任务已安装；修改脚本路径后需重新执行 ./scripts/install_callmacd_cron.sh。

3. 时区与夏令时

• cron 使用系统本地时间；请保证服务器时区为 Asia/Shanghai（北京时间）。

• 21:25 北京时间 ≈ 美东 9:25（夏令时），在常规盘 9:30 开盘前扫描。

• 美国 冬令时（约 11 月–3 月）请把 .env 改为 TRADE_CALLMACD_CRON_US_HOUR=22（22:25 北京时间 ≈ 9:25 ET），然后：

  ./scripts/install_callmacd_cron.sh

4. 非交易日与节假日

• CallMacd 在 is_tradings() 为假时（周末、港美节假日等）会 跳过本次扫描，不会发飞书，也不会长时间阻塞。
• 若 cron 在节假日仍触发，属于正常：进程会快速退出，仅写一条日志。

5. 日志路径

• 在 .env 中设置 TRADE_LOG_PATH 为本机路径，例如：

  TRADE_LOG_PATH=/Users/你的用户名/code/trade/log

• cron 专用追加日志：log/cron.log（由 scripts/run_callmacd_once.sh 写入）。

6. Python 环境

• 依赖安装：./scripts/setup_venv.sh（本机 python3 -m pip install -r requirement.txt，不建 venv）。
• 环境检查：./scripts/verify_env.sh（依赖包 + 环境变量）。
• run_callmacd_once.sh 与 cron 使用 PATH 中的 python3。
• 自选股较多时，单次扫描可能需 十余分钟，可看 log/cron.log 与 log/CallMacd.log 确认进度。

7. CallMacd 与下单

• CallMacd 只发飞书信号，不下单；main.py --once 不会初始化 OrderBook。
• 网格 / MACD 实盘下单策略请用 python main.py 常驻模式，并确认 TRADE_STRATEGY_NAME 与 TRADE_STOCK_ID 配置正确。

8. 修改定时时间

1. 修改 .env 中 TRADE_SCHEDULER_RUN_TIMES（文档用途）。
2. 修改 scripts/install_callmacd_cron.sh 里的 JOB_HK / JOB_US cron 表达式，或 scripts/callmacd.crontab.snippet。
3. 执行 ./scripts/install_callmacd_cron.sh 覆盖安装（脚本会去掉旧的 CallMacd 条目后重写）。

9. 内置调度（可选）

若不想用系统 cron，可将 .env 中 TRADE_SCHEDULER_ENABLED=true，然后长期运行：

python main.py

进程会按 run_times 等待到点再扫描。与系统 cron 二选一，避免重复执行。

---

相关文件

文件	说明
main.py	入口；--once 单次扫描
.env.example	环境变量模板（可提交）
.env	本地配置（gitignore，含密钥）
config.py	从环境变量构建 config 字典
scripts/check_config.py	校验必填环境变量
tests/	单元测试（config / 风控 / 信号状态）
scripts/run_callmacd_once.sh	cron 调用的包装脚本
scripts/install_callmacd_cron.sh	安装/更新 crontab
scripts/callmacd.crontab.snippet	crontab 示例片段
DESIGN.md	设计文档