长桥 VA 定投策略系统

基于长桥证券 OpenAPI 的 Value Averaging (价值平均法) 定投策略系统，使用 TypeScript + Node.js 开发。

项目简介

本项目实现了一个智能定投系统，采用 Value Averaging (VA) 策略替代传统的固定金额定投 (DCA)。VA 策略能够根据市场波动自动调整投资金额，在市场下跌时增加投入，在市场上涨时减少投入，从而获得更好的长期收益。

核心功能

• ✅ VA 策略计算：自动计算每月应投入金额
• ✅ 智能下单：使用 Maker 订单（买一价/卖一价）降低交易成本
• ✅ 账户管理：查询账户余额、持仓信息
• ✅ 实时行情：获取股票实时报价
• ✅ 回测分析：对比 VA 和 DCA 策略的历史表现
• ✅ 模拟交易：支持模拟运行，避免误操作

投资标的

默认投资三只美国指数 ETF：

• QQQM.US - Invesco NASDAQ 100 ETF
• SPYM.US - SPDR Portfolio S&P 500 ETF
• INDA.US - iShares MSCI India ETF

每月每只股票目标增长 150 美元（可配置）。

技术栈

• 语言: TypeScript
• 运行时: Node.js
• SDK: 长桥 OpenAPI SDK
• 依赖管理: npm
• 日期处理: date-fns
• 环境变量: dotenv

安装

前置要求

• Node.js >= 14.x
• npm >= 6.x
• 长桥证券账户
• 长桥 OpenAPI 权限

方式一：本地开发安装

1. 克隆项目

git clone https://github.com/cosin2077/longbridge-va.git
cd longbridge

2. 安装依赖

npm install

3. 配置环境变量

复制 .env.example 为 .env：

cp .env.example .env

编辑 .env 文件，填入你的长桥 API 凭证：

# 长桥 OpenAPI 配置
# 访问 https://open.longbridge.com/account 获取 API 凭证
LONGPORT_APP_KEY=your_app_key_here
LONGPORT_APP_SECRET=your_app_secret_here
LONGPORT_ACCESS_TOKEN=your_access_token_here

# 投资配置
SYMBOLS=QQQM.US,SPYM.US,INDA.US
MONTHLY_TARGET_PER_SYMBOL=150

# 回测配置
DEFAULT_BACKTEST_PERIODS=6m,1y,3y,5y,10y

4. 编译项目

npm run build

方式二：全局安装（推荐）

如果你想将工具作为全局命令使用，可以进行全局安装：

1. 克隆并编译项目

git clone https://github.com/cosin2077/longbridge-va.git
cd longbridge
npm install
npm run build

2. 全局安装

npm link

或者直接从 npm 安装（如果已发布）：

npm install -g longbridge-va

3. 配置环境变量

在你的主目录或项目目录创建 .env 文件：

cp .env.example ~/.lva.env
# 或者
cp .env.example .env

编辑环境变量文件，填入你的长桥 API 凭证。

4. 使用全局命令

安装后，你可以在任何目录使用 lva 命令：

lva account
lva quotes
lva invest
lva backtest

使用说明

🚀 快速开始（推荐）

对于新用户，推荐使用一键启动命令，无需手动初始化：

# 模拟模式（推荐先测试）
npm run cli auto
# 或全局安装后
lva auto

# 实际交易模式
npm run cli auto --real
# 或全局安装后
lva auto --real

这个命令会：

1. 自动检测是否已初始化，如果没有则引导你完成初始化
2. 显示定投配置（股票列表、每月目标金额等）
3. 获取并显示当前账户信息和持仓
4. 要求你确认配置
5. 自动启动 daemon，开始长期自动定投

一条命令，从零到自动定投！

🤖 自动定投 Daemon（核心功能）

Daemon 是本系统的核心功能，用于实现长期无人值守的自动定投。

什么是 Daemon？

Daemon 是一个后台进程，会按照预设的时间规则自动执行定投任务。你只需要启动一次，它就会持续运行数月甚至数年，每月自动检查条件并执行定投。

适用场景：

• ✅ 长期定投（10-20 年）
• ✅ 无需每月手动操作
• ✅ 自动化投资，省时省力

启动 Daemon

方式一：一键启动（推荐）

# 模拟模式
npm run cli auto
lva auto

# 实际交易模式
npm run cli auto --real
lva auto --real

方式二：手动启动（需要先 init）

# 先初始化
npm run cli init
lva init

# 再启动 daemon
npm run cli daemon start
lva daemon start

# 实际交易模式
npm run cli daemon start --real
lva daemon start --real

执行规则

Daemon 会在以下时间自动执行定投：

• 定时规则：每月 1-7 号的工作日（周一到周五）10:00
• 智能调度：如果 1 号是周末，会自动延迟到下一个工作日执行

为什么是 1-7 号？

• 确保每月都能执行（即使 1 号是周末）
• 在月初执行，符合定投习惯
• 每月只执行一次（通过条件检查保证）

执行条件检查

每次定时触发时，Daemon 会自动检查以下条件，只有全部满足才会执行定投：

1. ✅ 是否已初始化：检查定投状态是否已设置
2. ✅ 今天是否已定投：防止同一天重复定投
3. ✅ 距离上次定投的时间：至少间隔 25 天（防止频繁定投）
4. ✅ 是否为交易日：周末不执行（可扩展为检查节假日）
5. ✅ 账户余额：至少有 $100 余额

如果任何条件不满足，会跳过本次定投并记录原因到日志。

查看 Daemon 状态

npm run cli daemon status
lva daemon status

显示信息：

• 运行状态（运行中/已停止）
• 启动时间
• 最后检查时间
• 最后定投时间
• 进程 PID

停止 Daemon

在运行 daemon 的终端按 Ctrl+C 即可优雅停止。

日志文件

所有 daemon 的运行日志都会保存到 investment-daemon.log 文件中，包括：

• 每次检查的时间和结果
• 定投执行的详细过程
• 错误和异常信息

查看日志：

# 查看完整日志
cat investment-daemon.log

# 实时查看日志
tail -f investment-daemon.log

# 查看最后 50 行
tail -n 50 investment-daemon.log

日志示例

[2024-12-01 10:00:00] ========== 开始执行定投任务 ==========
[2024-12-01 10:00:00] 检查是否满足定投条件...
[2024-12-01 10:00:00] 跳过定投: 今天是周日，非交易日（周末不开市）
[2024-12-01 10:00:00] ========== 定投任务结束 ==========

[2024-12-02 10:00:00] ========== 开始执行定投任务 ==========
[2024-12-02 10:00:00] 检查是否满足定投条件...
[2024-12-02 10:00:00] ✓ 满足定投条件，开始执行定投...
[2024-12-02 10:00:00]   - 距离上次定投: 30 天
[2024-12-02 10:00:00]   - 账户余额: $5000.00
[2024-12-02 10:00:05] ✓ 定投执行成功
[2024-12-02 10:00:05] ========== 定投任务结束 ==========

使用 PM2 管理 Daemon（推荐）

对于长期运行，建议使用 PM2 进程管理器：

1. 安装 PM2

npm install -g pm2

2. 启动 Daemon

# 模拟模式
pm2 start "npm run cli auto" --name longbridge-va

# 实际交易模式
pm2 start "npm run cli auto -- --real" --name longbridge-va

# 或使用全局命令
pm2 start "lva auto --real" --name longbridge-va

3. 常用 PM2 命令

# 查看运行状态
pm2 status

# 查看日志
pm2 logs longbridge-va

# 重启
pm2 restart longbridge-va

# 停止
pm2 stop longbridge-va

# 删除
pm2 delete longbridge-va

# 保存配置（开机自启）
pm2 save
pm2 startup

4. 监控和管理

# 实时监控
pm2 monit

# 查看详细信息
pm2 show longbridge-va

使用系统 Cron（替代方案）

如果不想保持进程运行，可以使用系统的 cron 定时任务：

Linux/Mac 示例：

# 编辑 crontab
crontab -e

# 添加以下行（每月 1 号 10:00 执行）
0 10 1 * * cd /path/to/longbridge-va && npm run cli invest --real >> /path/to/longbridge-va/cron.log 2>&1

# 或使用全局命令
0 10 1 * * lva invest --real >> ~/longbridge-va-cron.log 2>&1

注意：

• 使用 cron 时，需要手动执行 invest 命令而不是 daemon start
• Cron 不会自动检查条件（如是否为交易日），需要依赖程序内部的检查逻辑
• 建议使用 PM2 方案，更可靠且易于管理

📋 命令行接口

项目提供了完整的 CLI 工具，支持以下命令：

0. 初始化定投状态（手动初始化）

npm run cli init
# 或全局安装后
lva init

注意：如果使用 auto 命令，无需手动运行 init。

首次使用前必须运行此命令，设置定投开始日期。如果你已有持仓，请输入实际开始定投的日期，系统会根据此日期计算投资月数。

1. 查看定投状态

npm run cli status
# 或全局安装后
lva status

显示当前定投状态：

• 定投开始日期
• 当前投资月数
• 已定投次数
• 最后定投日期

2. 查询账户信息

npm run cli account
# 或全局安装后
lva account

显示：

• 现金余额
• 总资产
• 持仓列表（股票代码、数量、市值、成本）

3. 查询实时行情

npm run cli quotes
# 或全局安装后
lva quotes

显示配置的股票的实时行情：

• 最新价
• 买一价
• 卖一价

4. 执行 VA 定投

模拟运行（推荐先使用）：

npm run cli invest
# 或全局安装后
lva invest

实际交易：

npm run cli invest --real
# 或全局安装后
lva invest --real

执行流程：

1. 检查定投状态是否已初始化
2. 显示当前定投状态（开始日期、投资月数等）
3. 获取当前账户信息和持仓
4. 获取实时行情
5. 计算 VA 策略（目标价值 vs 当前市值）
6. 生成交易计划并显示
7. 等待用户确认（实际交易模式）
8. 下单（使用限价单，买入用买一价，卖出用卖一价）
9. 等待订单成交
10. 更新定投记录

5. 运行回测分析

使用默认周期（6个月、1年、3年、5年、10年）：

npm run cli backtest
# 或全局安装后
lva backtest

指定回测周期：

npm run cli backtest --period=1y,3y,5y
# 或全局安装后
lva backtest --period=1y,3y,5y

自定义日期范围：

npm run cli backtest --start=2020-01-01 --end=2023-12-31
# 或全局安装后
lva backtest --start=2020-01-01 --end=2023-12-31

回测输出：

• VA 策略收益情况
• DCA 策略收益情况
• 两种策略对比分析
• 年化收益率对比

5. 显示帮助信息

npm run cli help
# 或全局安装后
lva help

VA 策略原理

什么是 Value Averaging？

Value Averaging（价值平均法）是一种改进的定投策略：

1. 设定目标价值路径：每月目标价值增长固定金额（如 150 美元）
2. 动态调整投入：
   • 第 N 个月的目标价值 = N × 月度目标增长额
   • 实际投入 = 目标价值 - 当前持仓市值
3. 市场适应性：
   • 市场下跌时，当前市值低于目标，自动增加投入
   • 市场上涨时，当前市值接近或超过目标，减少投入甚至卖出

VA vs DCA 对比

| 特性 | VA (价值平均法) | DCA (固定金额定投) | |------|----------------|-------------------| | 投入金额 | 动态调整 | 固定不变 | | 市场下跌 | 增加投入，低位多买 | 固定投入 | | 市场上涨 | 减少投入，高位少买 | 固定投入 | | 长期收益 | 通常更高 | 稳定但较低 | | 资金需求 | 需要灵活资金 | 固定预算 |

项目结构

longbridge/
├── src/
│   ├── api/                    # API 客户端
│   │   └── longbridge-client.ts
│   ├── backtest/               # 回测引擎
│   │   └── backtest-engine.ts
│   ├── config/                 # 配置管理
│   │   └── index.ts
│   ├── strategy/               # 策略实现
│   │   ├── value-averaging.ts  # VA 策略
│   │   └── trade-executor.ts   # 交易执行
│   ├── types/                  # 类型定义
│   │   └── index.ts
│   ├── utils/                  # 工具函数
│   │   └── formatter.ts
│   └── index.ts                # 主程序入口
├── .env.example                # 环境变量模板
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

开发指南

代码规范

• 遵循 TypeScript 严格模式
• 使用 ESLint 和 Prettier 格式化代码
• 遵循 SOLID 原则
• 模块化设计，职责单一

添加新功能

1. 在 src/types/index.ts 中定义类型
2. 在相应模块中实现功能
3. 在 src/index.ts 中添加 CLI 命令
4. 更新 README 文档

调试

使用 TypeScript 直接运行：

npm run dev

注意事项

⚠️ 重要提示

基础注意事项

1. 首次使用：推荐使用 auto 命令一键启动，或手动运行 init 命令初始化
2. 先模拟后实盘：首次使用务必先用模拟模式测试（不加 --real 参数）
3. API 权限：确保已开通长桥 OpenAPI 权限
4. 行情权限：确保有相应市场的行情权限
5. 资金管理：VA 策略需要预留足够的现金应对市场波动
6. 交易时间：注意美股交易时间（美东时间 9:30-16:00）
7. 频率限制：遵守长桥 API 调用频率限制

Daemon 相关注意事项

1. 时区问题

Daemon 的 cron 表达式使用服务器本地时间：

• 如果服务器在中国，10:00 是北京时间
• 美股交易时间是美东时间 9:30-16:00
• 北京时间 10:00 对应美东时间前一天 21:00（冬令时）或 22:00（夏令时）

建议：

• 将执行时间设置在美股交易时间内
• 例如：北京时间 22:00（美东时间 9:00）
• 可以在 src/index.ts 中修改 cron 表达式

2. 节假日处理

当前实现只检查周末，不包括美股节假日（如感恩节、圣诞节等）。

改进建议：

• 维护一个美股节假日列表
• 或调用长桥 API 检查市场状态
• 在 src/daemon/investment-checker.ts 的 isMarketDay() 方法中添加节假日检查

常见美股节假日：

• 新年（1月1日）
• 马丁·路德·金纪念日（1月第三个周一）
• 总统日（2月第三个周一）
• 耶稣受难日（复活节前的周五）
• 阵亡将士纪念日（5月最后一个周一）
• 独立日（7月4日）
• 劳动节（9月第一个周一）
• 感恩节（11月第四个周四）
• 圣诞节（12月25日）

3. 状态文件的重要性

定投状态保存在 .investment-state.json 文件中，包括：

• 定投开始日期
• 最后定投日期
• 定投次数
• 初始持仓

重要：

• ✅ 定期备份此文件
• ✅ 不要手动编辑此文件
• ❌ 如果文件丢失，可能导致重复定投或计算错误

备份建议：

# 定期备份
cp .investment-state.json .investment-state.json.backup

# 或使用 git 管理
git add .investment-state.json
git commit -m "Update investment state"

4. 进程管理

使用 PM2（推荐）：

• ✅ 自动重启（进程崩溃时）
• ✅ 日志管理
• ✅ 开机自启
• ✅ 监控和管理

使用系统 Cron：

• ✅ 不需要保持进程运行
• ❌ 需要手动配置
• ❌ 没有内置的条件检查

5. 日志管理

Daemon 日志会持续增长，建议定期清理或使用日志轮转：

手动清理：

# 清空日志
> investment-daemon.log

# 或删除旧日志
rm investment-daemon.log

使用 logrotate（Linux）：

# 创建 /etc/logrotate.d/longbridge-va
/path/to/longbridge-va/investment-daemon.log {
    daily
    rotate 30
    compress
    missingok
    notifempty
}

6. 错误恢复

如果 daemon 意外退出：

1. 检查日志：查看 investment-daemon.log 了解原因
2. 检查状态：运行 npm run cli status 确认状态正常
3. 重新启动：运行 npm run cli auto --real 或 pm2 restart longbridge-va

常见错误：

• API 连接失败：检查网络和 API 凭证
• 余额不足：检查账户余额
• 权限问题：检查 API 权限和行情权限

7. 安全建议

• ✅ 不要将 .env 文件提交到 git
• ✅ 定期更换 API 密钥
• ✅ 使用只读权限的 API 密钥进行测试
• ✅ 在生产环境使用环境变量而不是 .env 文件
• ✅ 定期检查账户交易记录

常见问题

基础问题

Q: 如何获取长桥 API 凭证？

A:

1. 登录长桥 App 完成开户
2. 访问 https://open.longbridge.com
3. 进入开发者平台，完成开发者认证
4. 获取 App Key、App Secret 和 Access Token

Q: VA 策略会不会导致投入过多？

A: VA 策略在市场持续下跌时确实会增加投入。建议：

• 设置合理的月度目标金额
• 预留足够的现金储备
• 定期评估和调整策略

Q: 为什么使用 Maker 订单？

A: Maker 订单（挂买一价/卖一价）可以：

• 避免因 spread 过大导致的损失
• 降低交易成本
• 提高成交质量

Q: 回测数据准确吗？

A: 回测使用长桥 API 提供的历史 K 线数据，数据质量较高。但请注意：

• 回测不考虑交易成本
• 历史表现不代表未来收益
• 仅供参考，不构成投资建议

Daemon 相关问题

Q: Daemon 会在什么时候执行定投？

A: Daemon 会在每月 1-7 号的工作日（周一到周五）10:00 执行。如果 1 号是周末，会自动延迟到下一个工作日。

Q: 如果 Daemon 意外停止了怎么办？

A:

1. 检查日志文件 investment-daemon.log 了解停止原因
2. 使用 npm run cli status 检查定投状态
3. 重新启动：npm run cli auto --real 或 pm2 restart longbridge-va
4. Daemon 会自动检查是否已定投，不会重复执行

Q: Daemon 会不会在同一天重复定投？

A: 不会。Daemon 有完善的检查机制：

• 检查今天是否已经定投过
• 检查距离上次定投是否超过 25 天
• 即使 daemon 重启或手动执行了 invest --real，也不会重复

Q: 如果 1 号是节假日怎么办？

A: 当前版本只检查周末，不检查节假日。如果 1 号是节假日：

• Daemon 会尝试执行，但可能因为市场关闭而失败
• 建议在 src/daemon/investment-checker.ts 中添加节假日列表
• 或者等待下个月（VA 策略允许偶尔跳过一个月）

Q: 如何查看 Daemon 的运行日志？

A:

# 查看完整日志
cat investment-daemon.log

# 实时查看日志
tail -f investment-daemon.log

# 查看最后 50 行
tail -n 50 investment-daemon.log

# 使用 PM2 查看日志
pm2 logs longbridge-va

Q: Daemon 占用多少资源？

A: 非常少。Daemon 大部分时间处于休眠状态，只在定时触发时才会执行检查和交易。通常占用：

• 内存：< 50MB
• CPU：几乎为 0（休眠时）
• 网络：仅在执行时调用 API

Q: 可以同时运行多个 Daemon 吗？

A: 不建议。多个 Daemon 可能导致：

• 重复定投
• 状态文件冲突
• 资源浪费

如果需要管理多个账户，建议：

• 为每个账户创建独立的项目目录
• 使用不同的 .env 文件
• 使用不同的 PM2 进程名

Q: 如何修改定投时间？

A: 编辑 src/index.ts 文件，找到 autoStart 或 startDaemon 方法中的 cron 表达式：

cronExpression: '0 10 1-7 * 1-5',  // 当前：每月 1-7 号的工作日 10:00

修改为你想要的时间，例如：

cronExpression: '0 22 1-7 * 1-5',  // 每月 1-7 号的工作日 22:00
cronExpression: '0 10 15 * *',     // 每月 15 号 10:00
cronExpression: '0 10 1,15 * *',   // 每月 1 号和 15 号 10:00

然后重新编译：

npm run build
pm2 restart longbridge-va

Q: 如何在服务器上部署 Daemon？

A: 推荐使用 PM2：

1. 在服务器上安装项目：

git clone https://github.com/cosin2077/longbridge-va.git
cd longbridge-va
npm install
npm run build

2. 配置环境变量：

cp .env.example .env
vim .env  # 填入 API 凭证

3. 使用 PM2 启动：

npm install -g pm2
pm2 start "npm run cli auto -- --real" --name longbridge-va
pm2 save
pm2 startup  # 配置开机自启

4. 监控和管理：

pm2 status
pm2 logs longbridge-va
pm2 monit

许可证

MIT License

免责声明

本项目仅供学习和研究使用，不构成任何投资建议。投资有风险，入市需谨慎。使用本工具进行实际交易的一切后果由用户自行承担。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

如有问题或建议，请提交 Issue。