diff --git a/AGENTS.md b/AGENTS.md index a36ea4d..bc93be4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,35 +1,142 @@ # Repository Guidelines -## Project Structure & Module Organization -The Bun entry point (`index.ts`) lives at the repo root for quick CLI smoke checks. All production code is under `src/`: +## Package Manager -- `src/strategy/` gathers every live trading engine (`maker`, `offset-maker`, `trend`). Shared helpers for strategy wiring sit in `src/strategy/common/`. -- `src/core/` keeps order coordination plus shared libs used by multiple strategies. -- `src/exchanges/` exposes the adapters and REST/websocket clients. -- `src/ui/` implements the Ink dashboards for each strategy (they remain independent dashboards). -- `src/logging/` contains the trade log helper. -- `src/utils/` and `src/config.ts` hold cross-cutting utilities and runtime config. -- `docs/` stores reference material, while `tests/` contains Vitest suites. +**必须使用 Bun** — 本项目使用 Bun 作为包管理器和运行时。所有命令都必须用 bun 执行，**不要使用 npm、yarn 或 npx**。 -## Build, Test, and Development Commands -- `bun install` – install dependencies. -- `bun run index.ts` – launch the CLI menu. -- `bun x vitest run` – execute the full test suite; `bun x vitest --watch` for incremental runs. +## Project Structure -Strategy-specific scripts still execute through the CLI; there is no separate `legacy/` workspace. +入口 `index.ts` 在仓库根目录，用于 CLI 启动。所有生产代码在 `src/` 下： -## Coding Style & Naming Conventions -Use modern TypeScript with ES modules, two-space indentation, and sorted imports (external → internal). Favor `camelCase` for variables/functions and `PascalCase` for classes/enums. Place new strategies under `src/strategy/`, shared utilities under `src/utils/` or `src/strategy/common/` when they only apply to strategies. Keep comments focused on non-obvious trading logic. +``` +src/ +├── config.ts # 运行时配置（GridConfig、MakerPointsConfig 等） +├── runtime-errors.ts # 全局错误处理 +├── index.tsx # Ink 渲染入口 +├── cli/ # CLI 参数解析与策略启动 +│ ├── args.ts +│ ├── command-executor.ts +│ ├── command-parser.ts +│ ├── command-types.ts +│ └── strategy-runner.ts +├── core/ # 订单协调 + 共享库 +│ ├── order-coordinator.ts # 限价单/市价单统一下单（锁、去重、速率控制） +│ └── lib/ +│ ├── order-plan.ts +│ ├── orders.ts +│ └── rate-limit.ts +├── exchanges/ # 交易所适配器（每个子目录含 adapter/gateway/order） +│ ├── adapter.ts # ExchangeAdapter 接口 +│ ├── adapter-utils.ts # 适配器工具函数 +│ ├── types.ts # CreateOrderParams、Order、AccountSnapshot 等公共类型 +│ ├── order-schema.ts # BaseOrderIntent、LimitOrderIntent 等 +│ ├── order-handlers.ts # 通用 order handler 工厂 +│ ├── order-router.ts # 按交易所分发订单处理 +│ ├── create-adapter.ts # 工厂函数 +│ ├── resolve-from-env.ts +│ ├── dry-run-adapter.ts # 模拟适配器 +│ ├── aster/ # Aster 交易所 +│ ├── backpack/ # Backpack 交易所 +│ ├── binance/ # Binance 交易所（CCXT） +│ ├── grvt/ # GRVT 交易所 +│ ├── lighter/ # Lighter 交易所（含签名/nonce/字节处理） +│ ├── nado/ # Nado 交易所 +│ ├── paradex/ # Paradex 交易所 +│ └── standx/ # StandX 交易所 +├── strategy/ # 所有策略引擎 +│ ├── maker-engine.ts # Maker 做市策略 +│ ├── maker-points-engine.ts # MakerPoints 积分做市策略 +│ ├── maker-points-logic.ts # MakerPoints 纯逻辑（可单独测试） +│ ├── offset-maker-engine.ts # 偏移做市策略 +│ ├── trend-engine.ts # 趋势跟踪策略 +│ ├── grid-engine.ts # 网格交易策略（LevelState + clientOrderId 恢复） +│ ├── basis-arb-engine.ts # 基差套利策略 +│ ├── swing-engine.ts # 波段交易策略 +│ ├── swing-logic.ts # 波段纯逻辑 +│ ├── guardian-engine.ts # 监控守护策略 +│ ├── liquidity-maker-engine.ts # 流动性做市策略 +│ └── common/ # 策略共享辅助 +│ ├── binance-depth.ts # Binance 深度分析 +│ ├── binance-rsi.ts # Binance RSI 指标 +│ ├── event-emitter.ts # 策略事件发射器 +│ ├── grid-storage.ts # 网格状态磁盘持久化 +│ ├── session-volume.ts # 会话成交量统计 +│ └── subscriptions.ts # WebSocket 安全订阅 +├── ui/ # Ink 仪表盘（每个策略独立 App） +│ ├── App.tsx +│ ├── GridApp.tsx +│ ├── MakerApp.tsx +│ ├── MakerPointsApp.tsx +│ ├── OffsetMakerApp.tsx +│ ├── TrendApp.tsx +│ ├── BasisApp.tsx +│ ├── SwingApp.tsx +│ ├── GuardianApp.tsx +│ ├── LiquidityMakerApp.tsx +│ └── components/ +├── logging/ # 交易日志 +│ └── trade-log.ts +├── notifications/ # Telegram 通知 +│ ├── index.ts +│ ├── telegram.ts +│ └── types.ts +├── i18n/ # 国际化 +│ └── index.ts +└── utils/ # 跨领域工具 + ├── math.ts, format.ts, price.ts, depth.ts + ├── errors.ts, risk.ts, pnl.ts + ├── strategy.ts, order-status.ts, security.ts + ├── copyright.ts + └── standx-token-expiry.ts +``` -## Testing Guidelines -Vitest powers unit/integration tests. Co-locate new tests next to their subject using `.test.ts`. Strategies should have coverage for order lifecycle, risk guards, and websocket edge cases. Run `bun x vitest --watch` during development for fast feedback. +辅助目录： +- `tests/` — Vitest 测试套件（大部分测试在此，少量与逻辑共处于 `src/`） +- `docs/` — 交易所 API 参考文档 +- `scripts/` — 一次性脚本（密钥派生等） +- `skills/` — AI 助手技能配置 -## Commit & Pull Request Guidelines -Follow lightweight Conventional Commits (e.g. `feat: add hedging status panel`). Scope each commit to a single module or strategy. PRs should include: -- Summary of changes. -- Validation notes (commands run, environments touched). -- Relevant logs or screenshots for behavior changes. -Link issues/tasks when available. +## Commands + +```bash +bun install # 安装依赖 +bun run dev # 启动 CLI 菜单（等同于 bun run index.ts） +bun run test # 执行全部测试（bun x vitest run） +bun x vitest --watch # 增量测试 +bun x tsc --noEmit # 类型检查（无 typecheck 脚本，直接用 tsc） +bun run lint # oxlint 检查 +bun run lint:fix # oxlint 自动修复 +``` + +⚠️ **不要用 `bun test`** — 那是 Bun 内置 runner，不支持 `vi.resetModules()`、`vi.waitFor()` 等 Vitest API。必须用 `bun run test`。 + +## Coding Style + +- 现代 TypeScript + ES modules，严格模式（`strict: true`） +- 两空格缩进，imports 按 external → internal 排序 +- 变量/函数用 `camelCase`，类/枚举用 `PascalCase` +- 新策略放 `src/strategy/`，策略共享工具放 `src/strategy/common/` +- 跨领域工具放 `src/utils/` +- 注释只写非显而易见的交易逻辑 +- JSX 用于 Ink UI 组件（`react-jsx`） + +## Testing + +Vitest 驱动所有测试。测试文件两种位置： +- `tests/.test.ts` — 大部分测试 +- `src//.test.ts` — 纯逻辑单元测试（如 `maker-points-logic.test.ts`、`swing-logic.test.ts`） + +策略测试应覆盖：订单生命周期、风控守卫、WebSocket 边界情况、状态恢复。 + +## Commit Guidelines + +Conventional Commits（`feat:` / `fix:` / `refactor:` / `test:`），每次提交作用域限单个模块或策略。 ## Environment & Secrets -Duplicate `.env.example` to `.env` and populate API keys (Aster/GRVT) before running strategies. Do not commit secrets—use local `.env` or deployment secret managers. Rotate keys if they leak into logs or backups. + +复制 `.env.example` 为 `.env` 填入 API 密钥。**不要读取、打印或提交 `.env` 和任何密钥。** 泄露立即轮换。 + +## Safety + +- 永远不要读取、运行、打印或访问 `.env` 或任何 secrets +- 代码中遇到项目依赖时，先查版本再查文档，避免过时知识导致错误 diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 4ed7881..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,12 +0,0 @@ -# RitMEX Bot - Claude Instructions - -## Package Manager - -**必须使用 Bun** - 这个项目使用 Bun 作为包管理器和运行时。所有能用 bun 执行的命令都必须使用 bun： - -- 安装依赖: `bun install` -- 运行脚本: `bun run