drawdown-circuit-breaker

回撤熔断器

概述

根据账户级已实现盈亏和近期终结交易结果，评估交易者今天是否应承担新的交易风险。此技能仅读取 trader-memory-core thesis YAML 文件。它会生成 circuit_breaker_decision 产物，与 exposure-coach 提供的市场侧 exposure_decision 相辅相成。

熔断器是一种建议和记录工具。它不能取代人工判断，也不会强制执行经纪商端的拦截或自动拒单。

适用场景

• 在筛选或确定任何新波段交易候选的仓位规模之前
• 交易亏损或部分减仓后，检查冷静期是否生效
• 在每日规划期间，若 trader-memory-core 中包含近期已平仓或部分平仓的持仓
• 作为工作流关卡，在 swing-opportunity-daily 继续生成候选之前进行检查
• 审查每日、每周或每月亏损限额是否已超出

前提条件

• Python 3.9+
• 本地 trader-memory-core thesis YAML 文件，通常位于 state/theses/ 下
• 以美元计的账户规模
• 无需 API 密钥或网络访问

工作流

步骤 1：读取交易者记忆状态

将脚本指向 thesis 状态目录：

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --state-dir state/theses \
  --account-size 100000 \
  --output-dir reports/

脚本会扫描每个 th_*.yaml 文件，并从每个 thesis 的 status_history[] 账本条目中读取已实现盈亏。它不会使用 _index.json 计算盈亏，因为该索引只是轻量级查找文件，不包含所需的已实现盈亏账本。

验证每个文件后，脚本会按照区分大小写、去除首尾空白的 thesis_id 对有效 thesis 分组。如果两个或更多有效文件具有相同 ID，脚本会将整个重复组排除在盈亏和连败计算之外，报告每个实际源路径，并返回 PARTIAL + HALTED，直到修复重复状态并重新运行决策。metrics.theses_scanned 仅统计已接受且 ID 唯一的 thesis。

如果状态目录不存在或为空目录，此技能会返回 TRADING_ALLOWED，并设置 data_quality: EMPTY_STATE，避免新用户因缺少历史记录而受阻。如果配置的状态路径存在但不是目录，此技能会将其视为不完整状态数据并安全停止。

如果状态存在，但必须跳过某个 thesis、账本事件或终结结果，或者其值与其他记录冲突，此技能会安全停止，并返回 data_quality: PARTIAL、recommendation: HALTED 和 incomplete_state_data 规则。修复警告后重新运行，再承担新的风险。唯一可恢复的例外是：对于没有已实现盈亏账本条目的旧版 thesis，可使用有限的终结 outcome.pnl_dollars 作为回退值；该情况仍会标记为 PARTIAL，但本身不会覆盖计算所得的建议。对于 ACTIVE、PARTIALLY_CLOSED、CLOSED 和 INVALIDATED thesis，每个历史事件都必须是包含可识别 status 和可解析 at 的对象，且最后一条历史状态必须与 thesis 状态一致。ACTIVE 和 PARTIALLY_CLOSED thesis 还必须包含实际入场信息；PARTIALLY_CLOSED 还必须包含持仓。生命周期历史记录格式错误、过时或不完整时，不符合终结回退条件，且会导致熔断。缺少 realized_pnl、类型不正确或值非有限的账本格式事件，也会导致熔断，而不会被强制转换。

步骤 2：评估熔断器规则

默认规则如下：

规则	默认值	触发状态	解除条件
每日最大亏损	账户的 2.0%	HALTED	下一个 ET 工作日
连续亏损冷却	连续 2 个最终亏损论点	COOLDOWN	最新一次亏损平仓 24 小时后
每周回撤暂停	账户的 5.0%	HALTED	下周一 ET
每月回撤暂停	账户的 8.0%	HALTED	下个月 1 日 ET

日、周和月的边界均使用 America/New_York。trader-memory-core 提供的仅包含日期的时间戳按所标注的 ET 日期计入。设置 --as-of 可进行确定性评估；仅包含日期的 --as-of 值涵盖整个 ET 日期，而时间戳值会排除该时间之后发生的事件：

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --state-dir state/theses \
  --account-size 100000 \
  --as-of 2026-07-02T12:00:00-04:00 \
  --output-dir reports/

步骤 3：按需覆盖阈值

在 CLI 中覆盖单个阈值：

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --account-size 100000 \
  --max-daily-loss-pct 1.5 \
  --losing-streak-n 3 \
  --cooldown-hours 48 \
  --weekly-drawdown-pct 4 \
  --monthly-drawdown-pct 6

也可以提供 JSON 配置文件：

{
  "max_daily_loss_pct": 1.5,
  "losing_streak_n": 3,
  "cooldown_hours": 48,
  "weekly_drawdown_pct": 4.0,
  "monthly_drawdown_pct": 6.0
}

CLI 参数优先于配置文件中的值。

步骤 4：解读决策

将生成的决策用作新增交易风险的关卡：

建议	含义
TRADING_ALLOWED	没有启用任何熔断器规则；新增交易风险可继续进入工作流的后续步骤
COOLDOWN	不要开立新仓位；继续管理现有仓位并审查近期亏损
HALTED	因回撤限额已触发或账户状态数据不完整，停止开立新仓；继续操作前修复数据警告或重新运行

现有仓位的管理仍由人工决定。熔断器旨在已发生实际损失后防止新增风险升级，而非强制平仓。

基于时间的规则包含 ISO 8601 格式的 active_until。非时间类规则 incomplete_state_data 使用 active_until: null；其 Markdown 报告会说明，暂停状态将持续到状态修复并重新运行决策为止。

输出格式

脚本会写入 circuit_breaker_decision_YYYY-MM-DD_HHMMSS.json，除非设置了 --json-only，否则还会生成对应的 Markdown 报告。

{
  "schema_version": "1.0",
  "generated_at": "2026-07-02T16:00:00+00:00",
  "as_of_date": "2026-07-02",
  "recommendation": "COOLDOWN",
  "triggered_rules": [
    {
      "rule": "losing_streak_cooldown",
      "threshold": 2,
      "observed": 2,
      "active_until": "2026-07-02T15:30:00-04:00",
      "detail": "2 consecutive losing closes; last loss exit 2026-07-01T15:30:00-04:00."
    }
  ],
  "metrics": {
    "realized_pnl_today": 0.0,
    "realized_pnl_wtd": -250.0,
    "realized_pnl_mtd": -250.0,
    "consecutive_losses": 2,
    "last_loss_exit_at": "2026-07-01T15:30:00-04:00",
    "theses_scanned": 12
  },
  "account_size": 100000.0,
  "config": {
    "max_daily_loss_pct": 2.0,
    "losing_streak_n": 2,
    "cooldown_hours": 24.0,
    "weekly_drawdown_pct": 5.0,
    "monthly_drawdown_pct": 8.0
  },
  "data_quality": "OK",
  "warnings": [],
  "rationale": "Recent losing closes triggered a cooldown. Avoid new entries until the cooldown expires."
}

交易所日历约定

运行检查器前，请先安装 requirements.txt。每日、每周和每月的暂停日期均依据实际 XNYS 交易日确定。active_until 保持兼容：暂停将在下一个符合条件的交易日 00:00 America/New_York 结束，而非在该交易日开盘时结束。使用 --as-of 可进行确定性评估。

资源

• scripts/check_circuit_breaker.py - 主 CLI 和规则引擎
• references/circuit_breaker_framework.md - 规则定义、默认值和数据源说明
• skills/trader-memory-core/schemas/thesis.schema.json - 论点状态的源架构

核心原则

1. 仅依据已实现损失 - 每日计算使用记录的已实现盈亏，而非未实现盈亏或论点级累计字段。
2. 生存优先 - 熔断器旨在防止亏损后风险进一步升级。
3. 仅提供建议，不自动执行 - 输出用于工作流关卡，不会下达、取消或拦截经纪商订单。
4. 状态不完整时采取保守处理 - 空状态允许新用户开始使用，但格式错误、已丢弃、相互冲突或非有限的风险数据会返回 PARTIAL + HALTED，且不会导致崩溃。有限的旧版结果回退值会报告为可恢复的 PARTIAL，且不会阻止操作。