nofx/docs/stock-trading-design.md

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

核心实现：

// 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）
• 同时支持美股+港股
• 专为程序化交易设计
• 文档完善，中文友好

核心实现：

// 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 是为加密货币合约设计的（做多/做空/杠杆），股票交易需要扩展：

// 方案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 工具扩展

// 新增 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. 汇率 — 港股/美股涉及外汇，需要考虑汇率展示