Rekey
4d66a86234
- AGENTS.md: AI Agent 规则，定义项目运行环境、架构约定、常用命令 - ENGINE.md: Python 引擎架构设计文档，涵盖策略管理、信号总线、回测引擎等模块设计
4.3 KiB
4.3 KiB
AGENTS.md
最关键
- 运行时是 Bun，不是 Node.js。执行 TS 文件用
bun run <file>，不能用node、npm、npx。 - 双语言项目：
data/是 TypeScript (Bun)，engine/是 Python 3.10+。两个模块通过 Redis Pub/Sub 通信。 - data/ 必须在 data/ 目录下运行：
package.json在data/中，依赖安装到data/node_modules。命令如bun install、bun run lint需要workdir=data。 - engine/ 必须在 engine/ 目录下运行：Python 虚拟环境在
engine/.venv/，导入包使用相对路径（from common import Kline）。命令如python -c "from common import Kline"需要workdir=engine。
常用命令
# 依赖安装（在 data/ 目录下）
bun install
# 运行数据补全（拉取历史 K 线）
bun run data/run/exchange.ts --concurrency 2
# 运行连续聚合刷新（dry-run 看 SQL，加 --execute 实际执行）
bun run data/run/build_aggregates_sql.ts # 纯输出 SQL
bun run data/run/build_aggregates_sql.ts --execute # 实际刷新
bun run data/run/build_aggregates_sql.ts --start 2025-01 --end 2025-06 --execute
# 代码检查与格式化
bun run lint # eslint
bun run format # prettier
# 构建检查
bun run build # tsc 类型检查
基础设施
- 数据库：
docker compose up -d启动 TimescaleDB（端口 5432）+ Adminer（端口 8080）。 - 配置源：项目根目录
env.yaml是 TS 和 Python 共享的唯一配置。data/config/index.ts读取并校验它。 - 数据库连接：host 在
env.yaml中配，当前指向10.0.0.7（远程）。本地开发需改为localhost。
架构约定
synchronize: false：TypeORM 不会自动同步 schema。修改实体后需要手动迁移或手动改表。@timescaledb/typeorm是 v0.0.1 实验版。K 线实体的@Hypertable装饰器可能不稳定。标准 SQL 集成用 TimescaleDB 连续聚合视图（klines_5m、klines_15m等）。- 数据模型对齐：TS 侧
data/types/base.ts定义的类型与 Python 侧engine/common/models.py的 Pydantic 模型必须保持字段一致。TS 侧 K 线价格为string类型（精度），写库时Number()转换。 - K 线 4 列复合主键：
[exchange, symbol, interval, time]。K 线分区列是time（TimescaleDB 要求分区列必须在主键中）。
Python 引擎
- workdir 必须是 engine/：导入包使用
from common import ...（如from common import Kline, BaseStrategy）。 - 未完成模块：策略管理器、信号总线、回测引擎、参数优化器仅存在于
ENGINE.md设计文档中，尚未实现。当前仅common/base.py（策略基类）和common/models.py（数据模型）、common/logger.py（日志）可用。 - 引擎入口
engine/__init__.py导出Kline, KlineInterval, OrderBook, Ticker, Trade。 - 引擎配置在
engine/env.yaml（与根env.yaml不同，是引擎专属配置）。 - Pydantic v2 的
field_validator处理 TS 侧字符串 → Python float/int 转换。
项目现状
- 已实现：TS 数据模块的配置加载、TypeORM 实体、Binance REST K 线拉取与批量 UPSERT、连续聚合刷新脚本。
- 未实现：WebSocket 行情采集、K 线合成管道、Redis 发布、策略管理器、信号总线、回测、风控、交易执行、API 网关。这些在
README.md和engine/ENGINE.md中有详细设计文档。 data/run/main.ts不存在，dev脚本指向的文件尚未创建。当前实际可运行的入口是run/exchange.ts（数据补全）和run/build_aggregates_sql.ts（聚合刷新）。- 无测试、无 CI：
package.json定义了vitest脚本但测试尚未编写。无 CI 配置文件。
注意事项
data/exchanges/rest.ts包含硬编码的 Binance API Key（第 105-106 行），不要提交到公开仓库。env.yaml包含明文数据库密码且被 git 追踪，注意安全。- 未安装 Python 依赖（如 pydantic），
engine/目录有独立的.venv/。 db/pgsql/在.gitignore中，这是 TimescaleDB 数据目录（Docker volume 映射）。KLINE_INTERVAL_MS常量定义了两处：data/exchanges/rest.ts和data/types/kline.ts的类型定义。新增周期需同步。