mirror of
https://github.com/NoFxAiOS/nofx.git
synced 2026-07-06 20:41:14 +08:00
docs: stock trading design + add Alpaca/LongPort tasks to self-drive queue
- Comprehensive design doc: US/HK/A-share trading API comparison - Phase 1: Alpaca (US stocks) - paper trading first - Phase 2: LongPort (HK stocks) - Phase 3: A-share via Stock Connect - 10 new [PENDING] tasks for self-drive cron
This commit is contained in:
shinchan-zhai
204
docs/stock-trading-design.md
Normal file
204
docs/stock-trading-design.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# NOFXi 股票交易能力设计方案
|
||||
|
||||
> 创建: 2026-03-23 13:00
|
||||
> 状态: 方案设计阶段
|
||||
> 目标: 让 NOFXi 具备美股、港股、A股的实际交易能力
|
||||
|
||||
## 一、市场分析
|
||||
|
||||
| 市场 | 难度 | 合规要求 | 交易时段 | 结算 |
|
||||
|------|------|---------|---------|------|
|
||||
| 美股 | ⭐⭐ | 较宽松，API 友好 | 盘前4:00-9:30 / 正常9:30-16:00 / 盘后16:00-20:00 ET | T+1 |
|
||||
| 港股 | ⭐⭐⭐ | 需持牌券商 | 9:30-12:00 / 13:00-16:00 HKT | T+2 |
|
||||
| A股 | ⭐⭐⭐⭐⭐ | 极其严格，程序化交易有准入门槛 | 9:30-11:30 / 13:00-15:00 CST | T+1（卖出T+0到账） |
|
||||
|
||||
## 二、券商/API 选型对比
|
||||
|
||||
### 美股交易
|
||||
|
||||
| 方案 | 优点 | 缺点 | API 风格 | 费用 |
|
||||
|------|------|------|---------|------|
|
||||
| **Alpaca** ⭐推荐 | REST API 极其简洁，Paper Trading 免费，支持盘前盘后，Go SDK | 仅美股 | REST + WebSocket | 免佣金 |
|
||||
| **Interactive Brokers (IBKR)** | 全球市场（美/港/A股通），最全面 | API 复杂(TWS/Gateway)，需要本地运行 | Java/C++/Python/REST | 低佣金 |
|
||||
| **Tradier** | REST API 友好 | 仅美股，知名度低 | REST | $0 佣金(Sandbox) |
|
||||
|
||||
### 港股交易
|
||||
|
||||
| 方案 | 优点 | 缺点 | API 风格 | 费用 |
|
||||
|------|------|------|---------|------|
|
||||
| **LongPort (长桥)** ⭐推荐 | 专为程序化设计，Go/Rust SDK，美股+港股 | 需开户 | REST + WebSocket + gRPC | 低佣 |
|
||||
| **Futu OpenD (富途)** | 中文社区大，港股+美股+A股 | 需运行 OpenD 网关 | TCP Protocol + REST | 低佣 |
|
||||
| **Tiger (老虎)** | 美股+港股，Python SDK | API 不如长桥 | REST | 中等 |
|
||||
| **IBKR** | 通过港股通可交易 | 设置复杂 | 同上 | 低佣 |
|
||||
|
||||
### A股交易
|
||||
|
||||
| 方案 | 优点 | 缺点 | 合规风险 |
|
||||
|------|------|------|---------|
|
||||
| **Futu OpenD** | 有 A 股通道（沪港通/深港通） | 需 OpenD 网关，间接交易 | 低 |
|
||||
| **IBKR 沪港通** | 通过港股通交易 A 股 | 品种有限 | 低 |
|
||||
| **掘金量化 / QMT** | 国内正规量化平台 | 需机构资质或高门槛 | 合规 |
|
||||
| **通达信/同花顺接口** | 直接对接国内券商 | 灰色地带，券商可能封号 | ⚠️ 高风险 |
|
||||
|
||||
## 三、推荐架构
|
||||
|
||||
### Phase 1: 美股交易（Alpaca）— 2-3天
|
||||
```
|
||||
用户 → NOFXi Agent → trader/alpaca/ → Alpaca API
|
||||
(Paper → Live)
|
||||
```
|
||||
**为什么选 Alpaca：**
|
||||
- REST API 极简，和 NOFX 现有 Trader 接口完美匹配
|
||||
- Paper Trading 环境免费，0 风险测试
|
||||
- 支持盘前盘后交易
|
||||
- 免佣金
|
||||
- Go HTTP 调用即可，无需 SDK
|
||||
|
||||
**核心实现：**
|
||||
```go
|
||||
// trader/alpaca/trader.go
|
||||
type AlpacaTrader struct {
|
||||
apiKey string
|
||||
apiSecret string
|
||||
baseURL string // paper-api.alpaca.markets or api.alpaca.markets
|
||||
client *http.Client
|
||||
}
|
||||
|
||||
// 实现 Trader interface
|
||||
func (t *AlpacaTrader) OpenLong(symbol string, qty float64, leverage int) (map[string]interface{}, error)
|
||||
func (t *AlpacaTrader) CloseLong(symbol string, qty float64) (map[string]interface{}, error)
|
||||
func (t *AlpacaTrader) GetPositions() ([]map[string]interface{}, error)
|
||||
func (t *AlpacaTrader) GetBalance() (map[string]interface{}, error)
|
||||
func (t *AlpacaTrader) GetMarketPrice(symbol string) (float64, error)
|
||||
// ... 美股不支持做空和杠杆（或通过 margin 账户）
|
||||
```
|
||||
|
||||
**Alpaca API 核心端点：**
|
||||
- `POST /v2/orders` — 下单
|
||||
- `GET /v2/positions` — 持仓
|
||||
- `GET /v2/account` — 余额
|
||||
- `DELETE /v2/orders/{id}` — 撤单
|
||||
- `GET /v2/assets/{symbol}/bars` — K线
|
||||
|
||||
### Phase 2: 港股交易（LongPort）— 3-5天
|
||||
```
|
||||
用户 → NOFXi Agent → trader/longport/ → LongPort OpenAPI
|
||||
```
|
||||
**为什么选长桥：**
|
||||
- 官方 Go SDK（github.com/longportapp/openapi-go）
|
||||
- 同时支持美股+港股
|
||||
- 专为程序化交易设计
|
||||
- 文档完善，中文友好
|
||||
|
||||
**核心实现：**
|
||||
```go
|
||||
// trader/longport/trader.go
|
||||
type LongPortTrader struct {
|
||||
config *longport.Config
|
||||
tradeCtx *trade.TradeContext
|
||||
quoteCtx *quote.QuoteContext
|
||||
market string // "US" or "HK"
|
||||
}
|
||||
```
|
||||
|
||||
**需要注意：**
|
||||
- 股票交易没有"做空"概念（需要融券，门槛高）
|
||||
- 没有杠杆概念（除融资融券）
|
||||
- 需要改造 Trader interface，增加股票买卖方法或适配现有接口
|
||||
- 委托类型：限价单/市价单/条件单
|
||||
|
||||
### Phase 3: A股交易（长期规划）
|
||||
**推荐路径：** 通过 LongPort 或 IBKR 的沪港通/深港通通道
|
||||
- 不建议直接对接国内券商 API（合规风险大）
|
||||
- 先支持沪港通标的（300+ 只大盘股）
|
||||
- 未来考虑接入正规量化平台（掘金/QMT）
|
||||
|
||||
## 四、Trader Interface 适配
|
||||
|
||||
当前 interface 是为**加密货币合约**设计的（做多/做空/杠杆），股票交易需要扩展：
|
||||
|
||||
```go
|
||||
// 方案A: 扩展现有 interface（推荐）
|
||||
// 股票交易映射到现有接口：
|
||||
// OpenLong → 买入（leverage=1）
|
||||
// CloseLong → 卖出
|
||||
// OpenShort → 融券卖出（如果支持）
|
||||
// CloseShort → 买入平仓
|
||||
// 杠杆固定为 1（现金账户）
|
||||
|
||||
// 方案B: 新增 StockTrader interface
|
||||
type StockTrader interface {
|
||||
Buy(symbol string, qty float64, orderType string, limitPrice float64) (OrderResult, error)
|
||||
Sell(symbol string, qty float64, orderType string, limitPrice float64) (OrderResult, error)
|
||||
GetQuote(symbol string) (Quote, error)
|
||||
GetPositions() ([]StockPosition, error)
|
||||
GetBalance() (StockBalance, error)
|
||||
GetOrders() ([]StockOrder, error)
|
||||
CancelOrder(orderID string) error
|
||||
}
|
||||
```
|
||||
|
||||
**推荐方案A**：复用现有 interface，stock trader 内部做映射。这样 Agent 的 tool calling、Web UI、Telegram 全部零改动就能支持股票。
|
||||
|
||||
## 五、Agent 工具扩展
|
||||
|
||||
```go
|
||||
// 新增 LLM 工具
|
||||
"buy_stock" → 买入股票（市价/限价）
|
||||
"sell_stock" → 卖出股票
|
||||
"stock_order" → 查看委托状态
|
||||
"cancel_order" → 撤单
|
||||
|
||||
// 或者复用现有 execute_trade 工具，通过 symbol 前缀区分：
|
||||
// "AAPL" → Alpaca
|
||||
// "0700.HK" → LongPort HK
|
||||
// "600519.SH" → LongPort A股通
|
||||
```
|
||||
|
||||
## 六、数据增强
|
||||
|
||||
| 数据 | 来源 | 用途 |
|
||||
|------|------|------|
|
||||
| 实时行情 | 新浪财经（已有） + Alpaca/LongPort WebSocket | 盘中实时价格 |
|
||||
| 盘前盘后 | 新浪（已有） + Alpaca extended hours | 盘前盘后交易 |
|
||||
| 财报日历 | Yahoo Finance / Alpaca | 财报预警 |
|
||||
| 新闻 | Alpha Vantage / Alpaca News API | 个股新闻 |
|
||||
| 基本面 | Yahoo Finance / LongPort | PE/PB/市值等 |
|
||||
|
||||
## 七、开发计划
|
||||
|
||||
### Sprint 1: Alpaca Paper Trading（P0，2-3天）
|
||||
- [ ] trader/alpaca/ 基础结构
|
||||
- [ ] 实现 Trader interface（Buy/Sell 映射到 OpenLong/CloseLong）
|
||||
- [ ] Paper Trading 环境对接
|
||||
- [ ] Agent 工具适配（识别股票 symbol 自动路由到 Alpaca）
|
||||
- [ ] 前端展示股票持仓
|
||||
- [ ] 集成测试：从对话到下单全流程
|
||||
|
||||
### Sprint 2: Alpaca Live Trading + 行情增强（P1，2天）
|
||||
- [ ] Live API 对接
|
||||
- [ ] 盘前盘后交易支持
|
||||
- [ ] WebSocket 实时行情
|
||||
- [ ] 委托类型：限价单、止损单
|
||||
- [ ] 风控：单笔金额限制、日亏损限制
|
||||
|
||||
### Sprint 3: LongPort 港股（P2，3-5天）
|
||||
- [ ] trader/longport/ 基础结构
|
||||
- [ ] Go SDK 集成
|
||||
- [ ] 港股交易流程
|
||||
- [ ] 港股行情接入
|
||||
- [ ] 港股持仓管理
|
||||
|
||||
### Sprint 4: A股通道（P3，探索）
|
||||
- [ ] 通过 LongPort/IBKR 沪港通
|
||||
- [ ] A股特殊规则（T+1、涨跌停、集合竞价）
|
||||
- [ ] A股行情增强
|
||||
|
||||
## 八、风险与注意事项
|
||||
|
||||
1. **资金安全** — 所有交易必须经过确认流程，和加密货币一样
|
||||
2. **合规** — 不碰灰色地带，只用正规券商 API
|
||||
3. **交易规则差异** — 股票无 24h 交易，需处理休市/停牌
|
||||
4. **结算周期** — 美股 T+1，港股 T+2，买入后不能立即卖出（Day Trade 规则）
|
||||
5. **Pattern Day Trader** — 美股 margin 账户 5 天内 ≥4 次日内交易需 $25K 最低资金
|
||||
6. **汇率** — 港股/美股涉及外汇，需要考虑汇率展示
|
||||
Reference in New Issue
Block a user