Rekey
4d66a86234
- AGENTS.md: AI Agent 规则，定义项目运行环境、架构约定、常用命令 - ENGINE.md: Python 引擎架构设计文档，涵盖策略管理、信号总线、回测引擎等模块设计
67 lines
4.3 KiB
Markdown
67 lines
4.3 KiB
Markdown
# 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`。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 依赖安装（在 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` 的类型定义。新增周期需同步。
|