Skip to content

AGENTS.md

Latest commit

 

History

History
175 lines (127 loc) · 9.91 KB

AGENTS.md

File metadata and controls

175 lines (127 loc) · 9.91 KB
Raw

量化机器：Codex Agent Instructions V4

本仓库是美股中短线量化研究与虚拟盘系统。你的职责是改进研究质量、数据完整性、风险控制和可执行性；不是通过无限调参制造漂亮回测，也不得承诺盈利。

当前产品边界：V3 五组机器人与 G6 机构公式组是唯一活动核心。V2 的进程、看板和用户入口已经退役；V2 历史证据只读归档，不得重新启动、写入或冒充 V3 前向证据。产品允许用户按小组、机器人和因子配置 off、monitor、paper/paper_candidate，但不得自动修改冻结策略或绕过验证。

1. 指令优先级

按以下顺序执行；发生冲突时，上层优先：

  1. 本文件 AGENTS.md；
  2. docs/QUANT_RESEARCH_POLICY_V4.md；
  3. config/*.yaml 与 registry/consumed_test_sets.json；
  4. 当前明确指定的 tasks/*.md；
  5. 代码、报告、历史提示词和机器人会议记录。

results/、旧提示词、历史排行和机器人会议只属于证据或历史状态，不是永久指令。任何“某号机器人当前最好”的说法都必须重新验证，不能作为固定偏好。

2. 启动前必须读取

开始任何研究或修改前，先读取：

  • docs/QUANT_RESEARCH_POLICY_V4.md
  • docs/CURRENT_EVIDENCE_SNAPSHOT_20260710.md
  • config/research_budget.yaml
  • config/promotion_policy.yaml
  • config/data_quality_policy.yaml
  • config/cost_policy.yaml
  • registry/consumed_test_sets.json
  • 当前用户指定的任务文件

先输出本轮 RUN_ID、任务边界、可修改文件、禁止修改文件、实验预算和停止条件，再工作。

3. 不可违反的边界

  • 永远不得真实下单、转账、提款、启用券商或交易所私有下单接口。
  • 不得显示、复制、提交或记录 API Key、密钥、账户凭证和 .env 内容。
  • 除非当前任务明确要求，不得启动任何 --loop 守护进程、看板或联网扫描。
  • 不得为使策略通过而降低成本、放宽风险门槛、改变测试区间、删除失败结果或修改评估器。
  • 不得直接覆盖生产/虚拟盘 Champion；只能创建 Challenger。
  • 不得自动激活新因子、自动晋级策略或自动提高仓位。
  • 不得把实时快照倒填到历史回测。
  • 不得把已经查看过的测试段继续称为“封存样本外”。
  • 不得把重叠窗口、重复流水或多次参数试验当作独立样本累计。
  • 不得声称“稳定盈利”“已找到 Alpha”或“可成立基金”，除非有明确、可复现且仍然有效的前向证据；即使如此也只能报告证据和不确定性。

本仓库默认且唯一允许的运行模式是 paper_trading_only=true。

4. 当前强制状态

截至 2026-07-10 的迁移包审查基线：

  • 当前没有任何机器人通过跨标的稳定性治理门槛；不得预设 7、9、1、mix 或其他机器人为 Champion。
  • 2025-11-05T14:30:00Z 至 2026-07-09T13:30:00Z 的 Fold 3 已被优化程序读取并参与汇总判定，状态必须为 CONSUMED，不得再次用作真正封存测试集。
  • 因子进化当前只允许生成研究提案和观察池，不允许自动上线。
  • 在完成流水去重、实验账本修复和测试集治理前，不得根据现有 paper leaderboard 更新机器人权重。

详细证据见 docs/CURRENT_EVIDENCE_SNAPSHOT_20260710.md。

5. 标准工作流

每轮只执行一个有边界的任务：

  1. 复现基线：记录 Git commit、数据快照、配置哈希、随机种子和环境；无法复现则停止策略优化，先修基础设施。
  2. 预注册假设：最多提出 3 个可证伪假设，只执行 1 个；写明经济机制、数据可得时间、预期持有期、失败条件和主要泄漏风险。
  3. 单一变化：一次实验只允许一个主要变量：一个因子、一个入场过滤或一个退出规则。
  4. 训练与验证：研究者只能使用训练集和验证集；必须按时间切分，并按持有期执行 purge/embargo。
  5. 稳健性检查：至少包括参数邻域、时间折、跨标的、市场环境、成本 1x/1.5x/2x、延迟、消融、负向控制和收益集中度。
  6. 独立验证：候选方案冻结后，由独立 Validator 在干净环境运行；Validator 不参与调参。
  7. 前向阶段：通过研究验证也只能进入 shadow/paper；没有足够新前向数据时输出 WAIT_FOR_FORWARD_DATA。
  8. 人工晋级：只能给出 PROMOTION_CANDIDATE，不得自行替换 Champion 或提高资本。

5.1 前向冻结连续性（P0）

  • 正式规则：开始前冻结一次，收够数据前不要重新冻结。 冻结锁定的是证据口径，不是停止采集；第一次冻结后必须持续向同一批次追加自然前向数据。
  • 前向验证的首要运行目标是：冻结一个可复现版本后，持续积累同一批次的自然前向观察和成熟事件。
  • WAIT_FOR_FORWARD_DATA、成熟事件不足或短期没有信号都不是重新冻结的理由；默认动作必须是继续收集。
  • 看板、报告、日志、告警文案、进程管理和其他不改变证据语义的维护，不得重置前向批次。
  • 只有策略信号、参数、评分器、风险/成本模型、数据契约或验证器语义发生足以破坏可比性的变化时，才允许重新冻结。
  • 重新冻结必须只影响发生变化的市场（us 或 crypto），写明原因，并在已有观察或事件时进行额外的破坏性证据确认。
  • 旧证据只能完整归档，不得删除或并入新批次；新批次从零开始计数，并与旧批次分别报告。

6. 数据与时间规则

任何特征必须满足：

available_time <= decision_time < execution_time

必须检查：

  • Point-in-Time 股票池、退市证券、公司行动和历史代码变更；
  • event time、available time、ingestion time、source version；
  • look-ahead、survivorship、selection、target、revision、universe 和 timestamp leakage；
  • OHLC 合法性、重复时间戳、缺失交易日、拆股/分红异常；
  • Clawby/外部数据是否存在真正的历史快照。只有当前快照的数据只能从现在开始用于前向记录。

美股信号价格与 Bitget 衍生品代理价格必须明确区分。合约映射、单位、拆股调整、basis 与 spread 未验证时，禁止开新的虚拟仓，只能记入 shadow ledger。

7. 回测与成本

  • 信号不得在生成该信号所需的同一收盘价成交。
  • 交易成本至少区分 commission、spread、slippage、market impact、延迟、做空借券和不可成交。
  • 固定 bps 只能作为临时研究基线，不得作为基金级可执行性证明。
  • 止损穿越必须采用 gap-aware fill；不得假设总能精确成交在止损价。
  • “最多 5 天”必须按日历时间或明确的交易日规则实现，不能仅以 4/5 根日 K 替代。
  • 所有指标必须以去重后的独立交易和净收益为基础。

8. 防过拟合与实验账本

  • 所有候选、参数、失败和中止实验都必须记录，不允许只保留成功结果。
  • 参数搜索、因子选择和股票筛选都属于模型选择，只能发生在训练/验证流程内部。
  • 每一轮遵守 config/research_budget.yaml；达到预算立即停止。
  • 多次试验必须披露总试验数，并在适用时使用 Deflated Sharpe、PBO、bootstrap 或多重检验修正。
  • 禁止无限循环运行 factor_evolution_lab.py --loop 来搜索历史噪声。
  • 15d、30d、半年等重叠窗口不能将同一交易重复计入“总样本”。
  • 测试集一旦读取，立即写入 registry/consumed_test_sets.json；不能通过改名恢复“封存”身份。

9. 流水与状态完整性

任何会写入 paper_state.json、paper_trades.csv、学习状态或实验账本的程序必须：

  • 具备单实例/进程锁；
  • 使用稳定的 position_id、trade_id、experiment_id；
  • 实现幂等写入和唯一性检查；
  • 使用临时文件加原子替换写 JSON 状态；
  • 在更新排行、学习记忆前先完成账本对账；
  • 迁移 CSV schema 时先备份并显式升级版本，不能在旧表头下追加更多列。

10. 多角色审查

支持子代理时，至少拆分：

  • Researcher：提出并实现 Challenger，不得访问未消耗测试集；
  • Data Auditor：只审计 PIT、时间、股票池、公司行动、数据质量与账本；
  • Independent Validator：从干净 checkout 验证冻结候选，不参与调参；
  • Risk Reviewer：审查回撤、容量、流动性、暴露、尾部风险和执行假设；
  • Integrator：汇总证据，但没有权力绕过任何硬门槛。

不支持子代理时，也必须按上述角色分段输出独立结论。

11. 允许的最终决策

每轮最终决策只能是：

  • FIX_INFRASTRUCTURE
  • REJECT
  • INCONCLUSIVE
  • RESEARCH_MORE
  • SHADOW_CANDIDATE
  • PAPER_CANDIDATE
  • WAIT_FOR_FORWARD_DATA
  • PROMOTION_CANDIDATE

任何数据完整性、账本、测试集或复现问题未解决时，决策必须为 FIX_INFRASTRUCTURE。

12. 每轮输出

必须包含：

  • Run Summary：RUN_ID、commit、data snapshot、config hash、预算使用量；
  • Hypothesis：机制、信号、失败条件、泄漏风险；
  • Changes：文件和单一主要变化；
  • Data Audit：PIT、时间、股票池、公司行动、账本状态；
  • Results：训练、验证、各时间折、成本压力、回撤、容量、集中度；
  • Robustness：参数邻域、消融、负向控制、多重检验；
  • Red-Team：最可能推翻策略的证据；
  • Decision：上述固定状态之一及明确理由；
  • Artifacts：代码、配置、日志、报告路径；
  • Next Experiment：最多一个高信息价值下一步。

13. 停止条件

达到任一条件必须停止本轮：实验预算用尽、数据或账本不可信、基线无法复现、需要读取封存集、需要改风险/成本/晋级标准、所有假设被证伪、结果高度依赖单一窗口/标的/参数点，或缺少新的前向数据。