AI 使用手册（Arbitrage Engine）

面向 Codex / OpenClaw / 其他 AI 助手。
目标：让 AI 在本项目中 安全、可预期、可回溯 地修改代码，而不是“乱改一通”。

本项目的唯一权威系统说明是：docs/arbitrage-engine-full-spec.md。
本手册描述：AI 进入项目时的阅读顺序、允许/禁止修改的范围，以及每次改动必须遵守的流程。

1. 进入项目前必须阅读的内容

在对本项目做任何非文档类修改之前，AI 必须先做下面几件事：

打开并理解 docs/arbitrage-engine-full-spec.md 中至少以下章节：
- 项目概述、技术栈
- 数据库结构（尤其是 strategies / signal_indicators / paper_trades）
- 信号引擎（signal_engine）逻辑
- paper trading 行为与 PnL 计算
浏览以下后端文件的结构（无需逐行记住）：
- backend/main.py（FastAPI 路由与业务分层）
- backend/signal_engine.py（信号引擎与策略工厂）
- backend/paper_monitor.py（模拟盘平仓逻辑）
浏览前端入口结构：
- frontend/app/ 下的页面目录（尤其是 /strategy-plaza / /signals / /paper）

如发现文档与代码实际行为有冲突，应优先相信 full-spec，并在必要时向人类维护者报告。

2. 修改范围：可以动什么 / 不可以动什么

为减少细节 bug 和隐性破坏，本项目对 AI 的修改范围划分为三类：

允许自由修改：只要本地检查通过即可。
允许修改，但需要特别小心：需要有清晰计划 + 局部验证。
禁止修改，除非任务明确要求且更新了 full-spec。

下面按类型具体说明。

2.1 允许自由修改的内容（默认安全区）

这些改动一般不会破坏系统核心语义，可以在合理前提下自由进行：

文档与注释
- 新增或修改 Markdown 文档（除非明确标为“权威规范”，如 full-spec）。
- 在代码中添加/改进注释，不改变实际逻辑。
测试代码
- 新增/改进单元测试、集成测试、前端测试。
- 修复由于实现变化导致的测试用例不匹配（前提是确认测试的预期确实已变化）。
前端 UI 层展示
- 不改变 API 调用与数据结构的前提下：
  - 布局调整、视觉优化、文案修改。
  - 新增只读型组件（图表、表格、标签等）。
纯新增的本地脚本与工具
- 放在 scripts/ 或明确的工具目录里，用于开发、调试、分析（不接入生产 PM2 流程）。
无行为变更的小型重构
- 拆分过长函数、提取私有辅助函数。
- 增加类型标注、引入更严格的 linters（在配置合理的前提下）。

2.2 可以修改但需要特别小心的内容（受控区）

这类改动一旦出错，会引入细节 bug 或统计偏差，但不至于破坏整个系统结构。修改前必须：

在回答中给出明确的改动计划（改哪些文件、改变哪些行为）。
改完后尽量做局部验证（至少跑相关命令 / 人工检查相关页面）。

受控区包括：

现有 API 的实现细节
- 位于 backend/main.py 中的 /api/* 路由实现。
- 允许：
  - 优化 SQL 查询；
  - 修复明显的边界条件 bug；
  - 增加非破坏性字段（向响应 json 增加可选字段）。
- 不允许：
  - 静默改变已有字段的含义（例如把 score 从 0–100 改成 0–1）。
  - 在无任务说明的前提下移除现有字段。
前端与现有 API 的交互逻辑
- 包括 frontend/app/* 中对 /api/* 的调用与数据展示逻辑。
- 修改前需确认：
  - 请求路径、查询参数、响应结构与 full-spec 和实际后端实现一致。
信号引擎的非核心逻辑
- backend/signal_engine.py 中：
  - 日志输出格式；
  - 错误处理与异常保护；
  - 非打分核心的辅助逻辑（例如冷启动保护、调试输出等）。
- 修改“评分公式”“门控条件”的逻辑时，属于 禁止区（见 2.3）。
paper trading 的展示与统计层
- 后端统计接口（如 /api/paper/stats、/api/paper/stats-by-strategy）的实现细节；
- 前端 /paper 以及策略广场中与统计展示相关的逻辑。
- 改动时需确认：
  - 不改变 pnl_r / status 的语义；
  - 汇总方式与 full-spec 中定义的规则保持一致。

2.3 禁止修改的内容（红线区）

以下内容 默认禁止 AI 修改。
只有在任务说明/人类明确要求的情况下，才可以动，并且必须同步更新 arbitrage-engine-full-spec.md 中对应章节。

数据库结构与关键字段语义
- 表结构（尤其是）：
  - strategies
  - signal_indicators
  - paper_trades
  - agg_trades
  - liquidations
  - market_indicators
- 禁止：
  - 修改已有字段的含义；
  - 删除字段；
  - 改名字段；
  - 在没有文档更新的前提下添加字段。
- 如确需变更，必须：
  - 在任务文档中有清晰需求；
  - 编写迁移 SQL 并在 full-spec 中更新结构说明。
核心业务指标的定义与计算方式
- 包括但不限于：
  - pnl_r 的计算规则；
  - status 枚举值含义（tp / sl / sl_be / timeout / signal_flip 等）；
  - 胜率、盈亏比、权益曲线的汇总算法；
  - 信号评分各层（direction/environment/auxiliary/momentum）的含义与权重机制。
- 如果任务要求调整这些规则，必须：
  - 明确标注新旧行为差异；
  - 说明对历史数据/统计的影响；
  - 更新 full-spec 中对应章节。
信号引擎核心打分/开仓/平仓逻辑
- evaluate_factory_strategy（V5.4 策略工厂核心）中的核心决策逻辑，包括：
  - 门控系统（5 个 Gate）的通过/否决条件；
  - 各层得分的具体计算公式；
  - entry_score / flip_threshold 等核心阈值的语义；
  - 开仓价/SL/TP 的确定方式；
  - paper_open_trade / paper_monitor 中判定触发 TP1/TP2/SL/timeout 的条件。
- 除非任务明确指出“需要调整策略模型/打分方式”，否则 AI 不应主动更改这些部分。
策略 ID / 名称约定与历史数据映射
- strategies.strategy_id（UUID）与 paper_trades.strategy_id、signal_indicators.strategy_id 的关联关系；
- strategy 字段中已有的命名约定（例如 custom_ 前缀）。
- 禁止：
  - 修改已有策略的 strategy_id；
  - 静默重命名已有策略的 strategy 文本值；
  - 移除 custom_ 策略路由或相关兼容逻辑。
认证与安全配置
- auth.py 中的认证逻辑和权限控制；
- JWT Secret、数据库连接信息、PM2 配置等运维层配置。
- AI 不应在代码中硬编码新的敏感信息，也不应修改现有的密钥配置。

3. 每次修改必须遵守的流程（AI 视角）

无论修改的是允许区还是受控区，AI 在本项目中的工作流程应遵循：

确认任务范围
- 从用户指令或任务文档中提取：
  - 要实现/修复的目标；
  - 涉及的页面/API/模块。
查阅相关文档
- 总是先查 docs/arbitrage-engine-full-spec.md；
- 如涉及信号引擎/策略工厂/模拟盘，需额外查阅对应的 GUIDE 文档（如果存在）。
列出改动计划
- 在回答中简要列出：
  - 计划修改的文件；
  - 每个文件预期的改动类型（bugfix/重构/新增功能）。
实施改动（保持最小必要范围）
- 避免“一次改太多文件”；
- 避免引入与任务无关的重构。
本地验证
- 尽量运行至少以下检查之一（视任务而定）：
  - 后端：相关单测 / 手工调用关键 API；
  - 前端：npm run build 或启动本地开发服务器检查关键页面；
  - 如无法真实运行，至少从代码结构和文档上做自洽性检查。
更新文档（如必要）
- 若改动影响 full-spec 中描述的行为/结构，必须同步更新 full-spec；
- 若改动属于策略/信号模型的重大变更，应在决策记录中添加条目（例如 DECISIONS.md）。

4. 冲突处理原则

当出现以下冲突时，AI 应遵循：

代码 vs full-spec
- 如果代码实现与 full-spec 的描述不一致：
  - 默认以 full-spec 为“期望行为”；
  - 优先考虑修代码使其符合 full-spec；
  - 如判断 full-spec 已过时，应在回答中明确提出，并建议人类确认后更新文档。
用户即时指令 vs 文档约束
- 如果用户指令要求做的事情与本手册“禁止修改”部分冲突：
  - AI 必须在回答中提醒用户这是“红线操作”；
  - 只有在用户明确确认且任务需求足够清晰时，才执行，并同步修改 full-spec。

5. 总结

本手册的核心目的只有一个：

让本项目在 AI 长期参与维护的前提下，仍然保持：

核心业务逻辑不被轻易破坏；

历史数据和统计口径具有可比性；

每一次变更都有据可查、可解释。

如果本手册与 arbitrage-engine-full-spec.md 或实际代码行为存在不一致，应优先保持三者的一致性，并在必要时征求人类维护者的确认。

9.4 KiB Raw Blame History Unescape Escape