204 lines
9.5 KiB
Markdown
204 lines
9.5 KiB
Markdown
# AI 使用手册（Arbitrage Engine）
|
||
|
||
> 面向 Codex / OpenClaw / 其他 AI 助手。
|
||
> 目标：让 AI 在本项目中 **安全、可预期、可回溯** 地修改代码，而不是“乱改一通”。
|
||
|
||
本项目的**唯一权威系统说明**是：`docs/arbitrage-engine-full-spec.md`。
|
||
本手册描述：AI 进入项目时的阅读顺序、允许/禁止修改的范围，以及每次改动必须遵守的流程。
|
||
|
||
---
|
||
|
||
## 1. 进入项目前必须阅读的内容
|
||
|
||
在对本项目做任何非文档类修改之前，AI 必须先做下面几件事：
|
||
|
||
1. 打开并理解 `docs/arbitrage-engine-full-spec.md` 中至少以下章节：
|
||
- 项目概述、技术栈
|
||
- 数据库结构（尤其是 `strategies` / `signal_indicators` / `paper_trades`）
|
||
- 信号引擎（signal_engine）逻辑
|
||
- paper trading 行为与 PnL 计算
|
||
2. 浏览以下后端文件的结构（无需逐行记住）：
|
||
- `backend/main.py`（FastAPI 路由与业务分层）
|
||
- `backend/signal_engine.py`（信号引擎与策略工厂）
|
||
- `backend/paper_monitor.py`（模拟盘平仓逻辑）
|
||
3. 浏览前端入口结构：
|
||
- `frontend/app/` 下的页面目录（尤其是 `/strategy-plaza` / `/signals` / `/paper`）
|
||
|
||
如发现文档与代码实际行为有冲突，应**优先相信 full-spec**，并在必要时向人类维护者报告。
|
||
|
||
---
|
||
|
||
## 2. 修改范围：可以动什么 / 不可以动什么
|
||
|
||
为减少细节 bug 和隐性破坏，本项目对 AI 的修改范围划分为三类：
|
||
|
||
- `允许自由修改`：只要本地检查通过即可。
|
||
- `允许修改，但需要特别小心`：需要有清晰计划 + 局部验证。
|
||
- `禁止修改，除非任务明确要求且更新了 full-spec`。
|
||
|
||
下面按类型具体说明。
|
||
|
||
### 2.1 允许自由修改的内容（默认安全区）
|
||
|
||
这些改动一般不会破坏系统核心语义，可以在合理前提下自由进行：
|
||
|
||
1. **文档与注释**
|
||
- 新增或修改 Markdown 文档（除非明确标为“权威规范”，如 full-spec）。
|
||
- 在代码中添加/改进注释，不改变实际逻辑。
|
||
2. **测试代码**
|
||
- 新增/改进单元测试、集成测试、前端测试。
|
||
- 修复由于实现变化导致的测试用例不匹配（前提是确认测试的预期确实已变化）。
|
||
3. **前端 UI 层展示**
|
||
- 不改变 API 调用与数据结构的前提下：
|
||
- 布局调整、视觉优化、文案修改。
|
||
- 新增只读型组件（图表、表格、标签等）。
|
||
4. **纯新增的本地脚本与工具**
|
||
- 放在 `scripts/` 或明确的工具目录里，用于开发、调试、分析（不接入生产 PM2 流程）。
|
||
5. **无行为变更的小型重构**
|
||
- 拆分过长函数、提取私有辅助函数。
|
||
- 增加类型标注、引入更严格的 linters（在配置合理的前提下）。
|
||
|
||
### 2.2 可以修改但需要特别小心的内容（受控区）
|
||
|
||
这类改动一旦出错，会引入细节 bug 或统计偏差，但不至于破坏整个系统结构。修改前必须：
|
||
|
||
1. 在回答中给出**明确的改动计划**（改哪些文件、改变哪些行为）。
|
||
2. 改完后尽量做局部验证（至少跑相关命令 / 人工检查相关页面）。
|
||
|
||
受控区包括：
|
||
|
||
1. **现有 API 的实现细节**
|
||
- 位于 `backend/main.py` 中的 `/api/*` 路由实现。
|
||
- 允许：
|
||
- 优化 SQL 查询；
|
||
- 修复明显的边界条件 bug；
|
||
- 增加非破坏性字段（向响应 json 增加可选字段）。
|
||
- 不允许：
|
||
- 静默改变已有字段的含义（例如把 `score` 从 0–100 改成 0–1）。
|
||
- 在无任务说明的前提下移除现有字段。
|
||
2. **前端与现有 API 的交互逻辑**
|
||
- 包括 `frontend/app/*` 中对 `/api/*` 的调用与数据展示逻辑。
|
||
- 修改前需确认：
|
||
- 请求路径、查询参数、响应结构与 full-spec 和实际后端实现一致。
|
||
3. **信号引擎的非核心逻辑**
|
||
- `backend/signal_engine.py` 中：
|
||
- 日志输出格式；
|
||
- 错误处理与异常保护；
|
||
- 非打分核心的辅助逻辑（例如冷启动保护、调试输出等）。
|
||
- 修改“评分公式”“门控条件”的逻辑时，属于 **禁止区**（见 2.3）。
|
||
4. **paper trading 的展示与统计层**
|
||
- 后端统计接口（如 `/api/paper/stats`、`/api/paper/stats-by-strategy`）的实现细节；
|
||
- 前端 `/paper` 以及策略广场中与统计展示相关的逻辑。
|
||
- 改动时需确认：
|
||
- 不改变 `pnl_r` / `status` 的语义；
|
||
- 汇总方式与 full-spec 中定义的规则保持一致。
|
||
|
||
### 2.3 禁止修改的内容（红线区）
|
||
|
||
以下内容 **默认禁止 AI 修改**。
|
||
只有在任务说明/人类明确要求的情况下，才可以动，并且必须同步更新 `arbitrage-engine-full-spec.md` 中对应章节。
|
||
|
||
1. **数据库结构与关键字段语义**
|
||
- 表结构（尤其是）：
|
||
- `strategies`
|
||
- `signal_indicators`
|
||
- `paper_trades`
|
||
- `agg_trades`
|
||
- `liquidations`
|
||
- `market_indicators`
|
||
- 禁止：
|
||
- 修改已有字段的含义；
|
||
- 删除字段；
|
||
- 改名字段；
|
||
- 在没有文档更新的前提下添加字段。
|
||
- 如确需变更，必须：
|
||
- 在任务文档中有清晰需求；
|
||
- 编写迁移 SQL 并在 full-spec 中更新结构说明。
|
||
2. **核心业务指标的定义与计算方式**
|
||
- 包括但不限于：
|
||
- `pnl_r` 的计算规则；
|
||
- `status` 枚举值含义（`tp` / `sl` / `sl_be` / `timeout` / `signal_flip` 等）；
|
||
- 胜率、盈亏比、权益曲线的汇总算法；
|
||
- 信号评分各层（direction/environment/auxiliary/momentum）的含义与权重机制。
|
||
- 如果任务要求调整这些规则，必须：
|
||
- 明确标注新旧行为差异；
|
||
- 说明对历史数据/统计的影响；
|
||
- 更新 full-spec 中对应章节。
|
||
3. **信号引擎核心打分/开仓/平仓逻辑**
|
||
- `evaluate_factory_strategy`（内部别名 `evaluate_v53`，原 `_evaluate_v53`）/ V5.4 策略工厂中的核心决策逻辑，包括：
|
||
- 门控系统（5 个 Gate）的通过/否决条件；
|
||
- 各层得分的具体计算公式；
|
||
- `entry_score` / `flip_threshold` 等核心阈值的语义；
|
||
- 开仓价/SL/TP 的确定方式；
|
||
- `paper_open_trade` / `paper_monitor` 中判定触发 TP1/TP2/SL/timeout 的条件。
|
||
- 除非任务明确指出“需要调整策略模型/打分方式”，否则 AI 不应主动更改这些部分。
|
||
4. **策略 ID / 名称约定与历史数据映射**
|
||
- `strategies.strategy_id`（UUID）与 `paper_trades.strategy_id`、`signal_indicators.strategy_id` 的关联关系；
|
||
- `strategy` 字段中已有的命名约定（例如 `custom_` 前缀）。
|
||
- 禁止：
|
||
- 修改已有策略的 `strategy_id`；
|
||
- 静默重命名已有策略的 `strategy` 文本值；
|
||
- 移除 `custom_` 策略路由或相关兼容逻辑。
|
||
5. **认证与安全配置**
|
||
- `auth.py` 中的认证逻辑和权限控制；
|
||
- JWT Secret、数据库连接信息、PM2 配置等运维层配置。
|
||
- AI 不应在代码中硬编码新的敏感信息，也不应修改现有的密钥配置。
|
||
|
||
---
|
||
|
||
## 3. 每次修改必须遵守的流程（AI 视角）
|
||
|
||
无论修改的是允许区还是受控区，AI 在本项目中的工作流程应遵循：
|
||
|
||
1. **确认任务范围**
|
||
- 从用户指令或任务文档中提取：
|
||
- 要实现/修复的目标；
|
||
- 涉及的页面/API/模块。
|
||
2. **查阅相关文档**
|
||
- 总是先查 `docs/arbitrage-engine-full-spec.md`；
|
||
- 如涉及信号引擎/策略工厂/模拟盘，需额外查阅对应的 GUIDE 文档（如果存在）。
|
||
3. **列出改动计划**
|
||
- 在回答中简要列出：
|
||
- 计划修改的文件；
|
||
- 每个文件预期的改动类型（bugfix/重构/新增功能）。
|
||
4. **实施改动（保持最小必要范围）**
|
||
- 避免“一次改太多文件”；
|
||
- 避免引入与任务无关的重构。
|
||
5. **本地验证**
|
||
- 尽量运行至少以下检查之一（视任务而定）：
|
||
- 后端：相关单测 / 手工调用关键 API；
|
||
- 前端：`npm run build` 或启动本地开发服务器检查关键页面；
|
||
- 如无法真实运行，至少从代码结构和文档上做自洽性检查。
|
||
6. **更新文档（如必要）**
|
||
- 若改动影响 full-spec 中描述的行为/结构，必须同步更新 full-spec；
|
||
- 若改动属于策略/信号模型的重大变更，应在决策记录中添加条目（例如 `DECISIONS.md`）。
|
||
|
||
---
|
||
|
||
## 4. 冲突处理原则
|
||
|
||
当出现以下冲突时，AI 应遵循：
|
||
|
||
1. **代码 vs full-spec**
|
||
- 如果代码实现与 full-spec 的描述不一致：
|
||
- 默认以 full-spec 为“期望行为”；
|
||
- 优先考虑修代码使其符合 full-spec；
|
||
- 如判断 full-spec 已过时，应在回答中明确提出，并建议人类确认后更新文档。
|
||
2. **用户即时指令 vs 文档约束**
|
||
- 如果用户指令要求做的事情与本手册“禁止修改”部分冲突：
|
||
- AI 必须在回答中提醒用户这是“红线操作”；
|
||
- 只有在用户明确确认且任务需求足够清晰时，才执行，并同步修改 full-spec。
|
||
|
||
---
|
||
|
||
## 5. 总结
|
||
|
||
本手册的核心目的只有一个：
|
||
|
||
> 让本项目在 AI 长期参与维护的前提下，仍然保持：
|
||
> - 核心业务逻辑不被轻易破坏；
|
||
> - 历史数据和统计口径具有可比性；
|
||
> - 每一次变更都有据可查、可解释。
|
||
|
||
如果本手册与 `arbitrage-engine-full-spec.md` 或实际代码行为存在不一致，应优先保持三者的一致性，并在必要时征求人类维护者的确认。
|