diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 0b3eb8e..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,66 +0,0 @@ -# AGENTS.md - -## 最关键 - -- **运行时是 Bun，不是 Node.js**。执行 TS 文件用 `bun run `，不能用 `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` 的类型定义。新增周期需同步。 diff --git a/AGENTS/01-critical.md b/AGENTS/01-critical.md new file mode 100644 index 0000000..4b6e4f8 --- /dev/null +++ b/AGENTS/01-critical.md @@ -0,0 +1,7 @@ +# 最关键 + +- **中文优先**：所有回答和推理过程必须使用中文，代码、标识符、文件名、技术术语保持原文不翻译。 +- **运行时是 Bun，不是 Node.js**。执行 TS 文件用 `bun run `，不能用 `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`。 diff --git a/AGENTS/02-commands.md b/AGENTS/02-commands.md new file mode 100644 index 0000000..76199a9 --- /dev/null +++ b/AGENTS/02-commands.md @@ -0,0 +1,21 @@ +# 常用命令 + +```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 类型检查 +``` diff --git a/AGENTS/03-infrastructure.md b/AGENTS/03-infrastructure.md new file mode 100644 index 0000000..29036ae --- /dev/null +++ b/AGENTS/03-infrastructure.md @@ -0,0 +1,5 @@ +# 基础设施 + +- **数据库**：`docker compose up -d` 启动 TimescaleDB（端口 5432）+ Adminer（端口 8080）。 +- **配置源**：项目根目录 `env.yaml` 是 TS 和 Python 共享的唯一配置。`data/config/index.ts` 读取并校验它。 +- **数据库连接**：host 在 `env.yaml` 中配，当前指向 `10.0.0.7`（远程）。本地开发需改为 `localhost`。 diff --git a/AGENTS/04-architecture.md b/AGENTS/04-architecture.md new file mode 100644 index 0000000..0d78af0 --- /dev/null +++ b/AGENTS/04-architecture.md @@ -0,0 +1,6 @@ +# 架构约定 + +- **`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 要求分区列必须在主键中）。 diff --git a/AGENTS/05-python-engine.md b/AGENTS/05-python-engine.md new file mode 100644 index 0000000..3a23423 --- /dev/null +++ b/AGENTS/05-python-engine.md @@ -0,0 +1,7 @@ +# 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 转换。 diff --git a/AGENTS/06-project-status.md b/AGENTS/06-project-status.md new file mode 100644 index 0000000..fa949f6 --- /dev/null +++ b/AGENTS/06-project-status.md @@ -0,0 +1,6 @@ +# 项目现状 + +- **已实现**：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 配置文件。 diff --git a/AGENTS/07-caveats.md b/AGENTS/07-caveats.md new file mode 100644 index 0000000..2ab90dd --- /dev/null +++ b/AGENTS/07-caveats.md @@ -0,0 +1,7 @@ +# 注意事项 + +- **`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` 的类型定义。新增周期需同步。