drawdown-circuit-breaker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Drawdown Circuit Breaker

回撤熔断机制

Overview

概述

Evaluate whether the trader should take new trade risk today based on account-level realized P&L and recent terminal trade outcomes. This skill reads trader-memory-core thesis YAML files only. It produces a

circuit_breaker_decision

artifact that complements the market-side

exposure_decision

from exposure-coach.

The circuit breaker is a recommendation and recordkeeping tool. It does not replace human judgment, and it does not enforce broker-side blocks or automated order rejection.

基于账户级realized P&L和近期终端交易结果，评估交易者今日是否应承担新的交易风险。该技能仅读取trader-memory-core的thesis YAML文件，生成

circuit_breaker_decision

工件，作为exposure-coach提供的市场端

exposure_decision

的补充。

熔断机制是一个建议和记录工具，它不会替代人工判断，也不会强制执行经纪商端的限制或自动拒绝订单。

When to Use

使用场景

Before screening or sizing any new swing trade candidate
After a losing trade or partial trim to check whether a cooldown is active
During daily planning when trader-memory-core contains recent closed or partially closed positions
As a workflow gate before swing-opportunity-daily proceeds to candidate generation
When reviewing whether daily, weekly, or monthly loss limits have been breached

在筛选或确定任何新波段交易候选标的之前
在亏损交易或部分减仓后，检查是否处于冷却期
当trader-memory-core包含近期平仓或部分平仓头寸时，用于每日规划
作为工作流关卡，在swing-opportunity-daily生成候选标的之前运行
检查每日、每周或每月亏损限额是否已被突破

Prerequisites

前置条件

Python 3.9+
Local trader-memory-core thesis YAML files, usually under
```
state/theses/
```
Account size in dollars
No API keys or network access required

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

Workflow

工作流程

Step 1: Read Trader Memory State

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

Point the script at the thesis state directory:

bash

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

The script scans every

th_*.yaml

file and reads realized P&L from each thesis

status_history[]

ledger entry. It does not use

_index.json

for P&L, because the index is a lightweight lookup file and does not contain the required realized-P&L ledger.

If the state directory is missing or is an empty directory, the skill returns

TRADING_ALLOWED

with

data_quality: EMPTY_STATE

so a new user is not blocked by the absence of history. If the configured state path exists but is not a directory, the skill fails closed as incomplete state data.

If state exists but a thesis, ledger event, or terminal result must be skipped or conflicts with another recorded value, the skill fails closed with

data_quality: PARTIAL

recommendation: HALTED

, and an

incomplete_state_data

rule. Repair the warnings and rerun before taking new risk. The one recoverable exception is a finite terminal

outcome.pnl_dollars

fallback for a legacy thesis with no realized-P&L ledger entry; it remains visible as

PARTIAL

but does not by itself override the calculated recommendation. For

ACTIVE

PARTIALLY_CLOSED

CLOSED

, and

INVALIDATED

theses, each history event must be an object with a recognized

status

and parseable

at

, and the last history status must match the thesis status.

ACTIVE

and

PARTIALLY_CLOSED

theses must also carry entry actuals;

PARTIALLY_CLOSED

must carry a position. Malformed, stale, or skeletal lifecycle history disqualifies terminal fallback and halts. Ledger-shaped events whose

realized_pnl

is missing, untyped, or non-finite also halt instead of being coerced.

将脚本指向thesis状态目录：

bash

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[]

分类账条目读取realized P&L。它不会使用

_index.json

获取盈亏数据，因为该索引是轻量级查找文件，不包含所需的已实现盈亏分类账。

如果状态目录缺失或为空，该技能会返回

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

状态的thesis必须包含头寸信息。格式错误、过时或不完整的生命周期历史会取消终端回退资格并触发停止。分类账格式的事件若缺失

realized_pnl

、类型错误或为非有限值，也会触发停止，而非强制转换。

Step 2: Evaluate Circuit Breaker Rules

步骤2：评估熔断规则

The default rules are:

Rule	Default	Triggered State	Release
Max daily loss	2.0% of account	HALTED	Next ET weekday
Losing streak cooldown	2 terminal losing theses	COOLDOWN	24 hours after latest loss exit
Weekly drawdown halt	5.0% of account	HALTED	Next Monday ET
Monthly drawdown halt	8.0% of account	HALTED	First day of next month ET

Day, week, and month boundaries use

America/New_York

. Date-only producer timestamps from

trader-memory-core

are counted on the named ET date. Set

--as-of

for deterministic evaluation; date-only

--as-of

values cover the full ET day, while timestamp values exclude future events after that time:

bash

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/

默认规则如下：

规则	默认值	触发状态	解除条件
每日最大亏损	账户的2.0%	HALTED	下一个美国东部时间工作日
连败冷却机制	2个终端亏损thesis	COOLDOWN	最新亏损平仓后24小时
每周回撤停止	账户的5.0%	HALTED	下一个美国东部时间周一
每月回撤停止	账户的8.0%	HALTED	下一个月的第一天（美国东部时间）

日、周、月的边界使用

America/New_York

时区。来自

trader-memory-core

的仅日期生成时间戳按指定的美国东部时间日期计算。设置

--as-of

参数可进行确定性评估；仅日期的

--as-of

值覆盖完整的美国东部时间当日，而时间戳值会排除该时间之后的未来事件：

bash

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/

Step 3: Override Thresholds When Needed

步骤3：按需覆盖阈值

Override individual thresholds on the CLI:

bash

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

Or provide a JSON config file:

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 arguments override config-file values.

通过CLI覆盖单个阈值：

bash

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配置文件：

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参数会覆盖配置文件中的值。

Step 4: Interpret the Decision

步骤4：解读决策结果

Use the generated decision as a gate for new trade risk:

Recommendation	Meaning
TRADING_ALLOWED	No circuit breaker rule is active; new trade risk may proceed through the rest of the workflow
COOLDOWN	Do not open new positions; continue managing existing positions and review the recent losses
HALTED	Stop new entries because a drawdown limit is active or account-state data is incomplete; repair/rerun any data warnings before proceeding

Existing position management remains a human decision. The circuit breaker is designed to prevent new risk escalation after realized damage, not to force liquidation.

Time-based rules carry an ISO 8601

active_until

. The non-time-based

incomplete_state_data

rule uses

active_until: null

; its Markdown report says the halt lasts until the state is repaired and the decision is rerun.

将生成的决策结果作为新交易风险的关卡：

建议	含义
TRADING_ALLOWED	无熔断规则触发；新交易风险可继续执行后续工作流
COOLDOWN	不要开新仓；继续管理现有头寸并复盘近期亏损
HALTED	因回撤限额触发或账户状态数据不完整，停止新入场操作；在继续之前需修复/重新运行任何数据警告

现有头寸的管理仍由人工决定。熔断机制旨在防止已造成亏损后风险进一步升级，而非强制平仓。

基于时间的规则会包含ISO 8601格式的

active_until

。非时间相关的

incomplete_state_data

规则使用

active_until: null

；其Markdown报告显示停止状态会持续到状态修复并重新运行决策为止。

Output Format

输出格式

The script writes

circuit_breaker_decision_YYYY-MM-DD_HHMMSS.json

and, unless

--json-only

is set, a matching markdown report.

json

{
  "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."
}

脚本会生成

circuit_breaker_decision_YYYY-MM-DD_HHMMSS.json

文件，除非设置了

--json-only

参数，否则还会生成对应的Markdown报告。

json

{
  "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."
}

Resources

资源

```
scripts/check_circuit_breaker.py
```
- Main CLI and rule engine
```
references/circuit_breaker_framework.md
```
- Rule definitions, defaults, and data-source notes

skills/trader-memory-core/schemas/thesis.schema.json

- Source schema for thesis state

```
scripts/check_circuit_breaker.py
```
- 主CLI和规则引擎
```
references/circuit_breaker_framework.md
```
- 规则定义、默认值和数据源说明

skills/trader-memory-core/schemas/thesis.schema.json

- thesis状态的源schema

Key Principles

核心原则

Realized damage only - Use recorded realized P&L, not unrealized P&L or thesis-level cumulative fields for daily calculations.
Survival first - A circuit breaker exists to prevent escalation after losses.
Advisory, not automatic execution - The output informs the workflow gate; it does not place, cancel, or block broker orders.
Fail closed on incomplete state - Empty state allows a new user to begin, but malformed, discarded, conflicting, or non-finite risk data returns
```
PARTIAL
```
+
```
HALTED
```
without crashing. A finite legacy outcome fallback is reported as recoverable
```
PARTIAL
```
and remains non-blocking.

仅考虑已实现亏损 - 每日计算使用记录的realized P&L，而非未实现盈亏或thesis级别的累计字段。
生存优先 - 熔断机制的存在是为了防止亏损后风险升级。
仅提供建议，不自动执行 - 输出结果用于工作流关卡；不会下单、取消订单或阻止经纪商订单。
状态不完整时返回关闭状态 - 空状态允许新用户开始使用，但格式错误、已丢弃、冲突或非有限的风险数据会返回
```
PARTIAL
```
+
```
HALTED
```
，且不会崩溃。有限的旧版结果回退会被报告为可恢复的
```
PARTIAL
```
，且不会阻止操作。