# 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` 或实际代码行为存在不一致，应优先保持三者的一致性，并在必要时征求人类维护者的确认。