trade/AGENTS.md

trade — 数字货币量化交易系统

Python + TypeScript (Bun) 混合架构：数据层 TS 采集行情入库，业务层 Python 跑策略/回测/风控。

项目

• data/：TypeScript (Bun)，行情采集、K 线合成、数据写入 TimescaleDB。workdir 必须是 data/。
• engine/：Python 3.10+，策略引擎、回测、信号分发。workdir 必须是 engine/，导入用 from common import ...。
• 两模块通过 Redis Pub/Sub 通信（设计阶段，尚未实现）。
• 数据库：TimescaleDB（Docker Compose 启动，端口 5432）。配置在根 env.yaml。

命令

# 基础设施
docker compose up -d                              # 启动 TimescaleDB + Adminer(:8080)

# data/ (TS) — 必须先 cd data
cd data && bun install                            # 安装依赖
bun run data/run/exchange.ts --concurrency 2      # 拉取历史 K 线
bun run data/run/build_aggregates_sql.ts           # 连续聚合刷新 (dry-run)
bun run data/run/build_aggregates_sql.ts --execute # 实际执行聚合刷新
bun run lint                                      # eslint
bun run format                                    # prettier
bun run build                                     # tsc 类型检查

架构

data/                          engine/
  exchanges/rest.ts   Binance    common/base.py      策略基类
  types/base.ts       类型定义    common/models.py    Pydantic 数据模型
  types/kline.ts      K线类型     common/logger.py    日志
  entities/           TypeORM    backtest/           回测引擎
  run/exchange.ts     拉取入口    indicators/        技术指标
  run/build_aggregates_sql.ts    example/           策略示例+回测脚本

• K 线复合主键：[exchange, symbol, interval, time]，TimescaleDB 超表按 time 分区。
• synchronize: false：TypeORM 不自动 sync schema，改实体需手动迁移。
• @timescaledb/typeorm 是 v0.0.1 实验版，连续聚合用原生 SQL 视图（klines_5m / klines_15m 等）。
• TS 侧价格字段为 string（精度），Python 侧 Pydantic field_validator 转 float。
• KLINE_INTERVAL_MS 定义在 data/exchanges/rest.ts 和 data/types/kline.ts 两处，新增周期需同步。

约定

• 中文优先：所有回答和推理用中文；代码、标识符、文件名、技术术语保持原文。
• 运行时是 Bun，不是 Node.js：TS 执行用 bun run <file>，禁止 node/npm/npx。
• workdir 严格分离：TS 命令在 data/，Python 命令在 engine/。package.json 在 data/ 中。
• 先确认再动手：涉及多文件或架构决策时先出方案等用户点头。不做未要求的改动。
• 一次改一处：逐步 edit_file，不批量 multi_edit。改完让用户看到再继续。
• 拒绝时先问原因：操作被 declined 不要立即换方式重试。
• 配置单一源：env.yaml 是 TS 和 Python 共享的唯一配置，含 API Key，禁止硬编码密钥。
• Python 虚拟环境：engine/.venv/，未安装依赖（pydantic 等）需先 pip install。

现状

• ✅ TS 数据模块：配置加载、TypeORM 实体、Binance REST K 线拉取+UPSERT、连续聚合刷新。
• ❌ 未实现：WebSocket 行情、K 线合成管道、Redis 发布、策略管理器、信号总线、回测引擎、参数优化器、风控、交易执行、API 网关。
• ❌ 无测试、无 CI。
• data/run/main.ts 不存在，dev/start 脚本指向未创建文件。

注意事项

• env.yaml 含明文密钥且被 git 追踪，不可提交到公开仓库。
• 数据库当前指向远程 10.0.0.7，本地开发改 env.yaml 中 host 为 localhost。
• db/pgsql/ 是 Docker volume 数据目录，已在 .gitignore。