Document market regime control plan

Author: Pigbibi

README.zh-CN.md

@@ -26,6 +26,7 @@ Brokers、Schwab、LongBridge、Firstrade 等平台仓库只负责加载 artifac
 - `crisis_response_shadow`：面向杠杆美股策略的黑天鹅防守观察插件。它只写入 shadow-mode artifact，不调用券商接口。
   可选启用 AI shadow audit：AI 只审计证据一致性和数据缺口，不改写确定性路线、不下单、不改仓位；默认优先尝试本机 Codex，失败后可走 OpenAI-compatible 或 Anthropic fallback endpoint。
 - `macro_risk_governor`：面向 TQQQ 的确定性宏观降杠杆插件。它按价格趋势、实现波动、VIX、信用相对压力和可选外部金融压力字段打分，输出 `leverage_scalar` / `risk_asset_scalar` 给显式 opt-in 的策略运行时消费。五角大楼比萨指数这类 OSINT 字段只作为 watch-only 证据，不进入可执行分数。
+- `market_regime_control`：统一确定性 facade，汇总 crisis、macro 和 TACO 信号，输出版本化的 `notification` 和 `position_control`。杠杆策略可直接消费仓位控制，股票/ETF 轮动策略通过本地风险缩放策略消费；TACO 在统一插件里保持通知-only，并会被危机和宏观降风险路线 veto。设计说明见 [Market Regime Control 统一插件方案](docs/market-regime-control-plan.zh-CN.md)。
 - `taco_rebound_shadow`：仅适用于 TQQQ 的事件反弹上下文通知插件。它只写入人工复核 artifact，不给仓位大小建议，也不改动配置或账户分配。缓和/降温事件会先保持 watch-only，只有事件后价格反弹确认通过后才触发人工复核通知，以减少过早抄底提醒。
   该插件也可选启用同样的 shadow-only AI audit，但 AI 只复核事件来源和反弹证据质量。
 - TACO panic-rebound 研究、组合回测和 overlay 对比也归属本仓库；snapshot pipeline 仓库只保留兼容入口。

docs/market-regime-control-plan.zh-CN.md

@@ -0,0 +1,118 @@
+# Market Regime Control 统一插件方案
+
+本文档记录 `market_regime_control` 的当前设计边界、信号优先级、策略消费方式和回测结论。
+
+## 目标
+
+`market_regime_control` 是统一的确定性市场状态 facade。它把原来的危机防守、宏观降杠杆和 TACO 事件反弹通知汇总成一个版本化 artifact，供策略仓库统一消费。
+
+核心目标：
+
+- 在宏观环境恶化、系统性危机或泡沫破裂风险上升时，主动降低仓位和杠杆。
+- 保留 TACO 对假危机、事件缓和和反弹机会的通知能力，但不让它绕过危机防守。
+- 不依赖 AI 做交易决策。AI 只允许做 shadow-only 证据复核和通知辅助。
+- 输出稳定的 `market_regime_control.v1` schema，策略仓库按 schema 消费 `notification` 和 `position_control`。
+
+非目标：
+
+- 插件仓库不调用券商接口，不直接改账户分配。
+- OSINT 字段，例如五角大楼比萨指数，只能作为 watch-only evidence，不能直接进入可执行分数。
+- TACO 默认不增加仓位，不作为危机期间的抄底开关。
+
+## 组件职责
+
+`market_regime_control` 内部保留三个确定性组件：
+
+- `crisis_response_shadow`
+  负责硬危机防守。`true_crisis` 和泡沫脆弱性触发后，统一插件输出 `risk_off` / `defend`，仓位目标交给策略侧 opt-in 执行。
+- `macro_risk_governor`
+  负责宏观降杠杆。它看价格趋势、实现波动、VIX、信用相对压力和可选金融压力字段，输出 `risk_reduced` 或 `risk_off`。
+- `taco_rebound_shadow`
+  负责 TQQQ 事件反弹通知。它输出人工复核通知和本地 veto 线索，不直接提高仓位。
+
+统一插件输出四组主要字段：
+
+- `notification`
+  通知是否应该发出、路由来源、原因码和 veto 说明。
+- `position_control`
+  策略侧可消费的 `risk_budget_scalar`、`leverage_scalar`、`risk_asset_scalar`、`taco_allowed` 和 `blocked_actions`。
+- `component_signals`
+  子组件的压缩证据，便于通知和审计。
+- `execution_controls`
+  明确插件仓库只写 artifact，不允许券商下单或账户配置变更。
+
+## 仲裁优先级
+
+当前优先级按风险优先设计：
+
+1. `crisis_response_shadow` 的 `true_crisis` 或泡沫脆弱性优先级最高，输出 `risk_off`，并 veto TACO。
+2. `macro_risk_governor` 的 `crisis` 其次，输出 `risk_off`，并 veto TACO。
+3. `macro_risk_governor` 的 `delever` 输出 `risk_reduced`，降低杠杆或风险资产预算，并 veto TACO。
+4. 数据质量 kill switch 或组件 blocked 状态会阻断机会侧动作。
+5. 只有没有危机和宏观降风险时，TACO 才能输出 `opportunity_watch` 和人工复核通知。
+6. watch-only 信号只通知，不给仓位权限。
+
+这个顺序保证危机插件、宏观插件和 TACO 不冲突：防守优先，机会次之，通知和执行权限分离。
+
+## 策略消费方式
+
+策略仓库只挂载 `market_regime_control/latest_signal.json`，不再直接消费旧的三个插件。
+
+建议消费规则：
+
+- TQQQ 杠杆增长收益策略
+  默认消费 `position_control`。`risk_off` 降到现金类或非风险资产；`risk_reduced` 按策略配置降低杠杆或风险预算；TACO 只触发人工复核和本地 veto。
+- SOXL/SOXX 趋势收益策略
+  默认挂载统一插件。`risk_off` 生效；`risk_reduced` 可按配置选择通知-only 或部分降风险，避免过度干扰高波动半导体策略。
+- Global ETF、Russell 1000、Tech/Communication、Mega Cap 类轮动策略
+  默认支持统一插件。`risk_reduced` 建议做 50% 风险预算缩放，`risk_off` 建议归零风险资产预算。
+- DCA 或收入型低频策略
+  默认 notification-only，允许用户显式开启仓位影响。
+
+旧插件仍可运行历史回测和兼容输出，但新策略集成应优先挂载 `market_regime_control`。
+
+## 版本管理
+
+当前对外契约是：
+
+- 统一插件 schema：`market_regime_control.v1`
+- 仲裁器 schema：`market_regime_arbiter.v1`
+- 运行器总 schema：`strategy_plugins.v1`
+
+升级原则：
+
+- 向后兼容字段可以在 v1 内新增。
+- 删除字段、改变字段语义或改变默认执行权限，需要升级到 v2。
+- 策略仓库应按 `schema_version` 校验可消费版本，并在配置层保留 opt-in/opt-out。
+- 旧插件标记 deprecated successor 为 `market_regime_control`，但保留历史入口方便复现旧回测。
+
+## 回测结论
+
+真实产品短中周期和长周期合成代理都支持当前设计。
+
+TQQQ 2010-2026 真实产品窗口：
+
+- `cash_vol30_5_7_vol_confirmed` 方案相对基线 CAGR 提升约 `+1.03pp`。
+- 最大回撤改善约 `+0.29pp`。
+- COVID 窗口 CAGR 改善约 `+11.47pp`，最大回撤改善约 `+4.15pp`。
+
+1999-2026 QQQ 合成 3x 长周期代理：
+
+- 纯危机上下文版本：CAGR `14.78% -> 18.93%`，最大回撤 `-94.54% -> -87.63%`。
+- 增强泡沫脆弱性版本：CAGR `14.78% -> 19.87%`，最大回撤 `-94.54% -> -86.60%`。
+- 金融危机窗口：CAGR `-45.25% -> -27.65%`，最大回撤 `-59.87% -> -40.47%`。
+- 互联网泡沫破裂窗口：增强泡沫脆弱性后 CAGR `-67.78% -> -51.69%`，最大回撤改善约 `+7.94pp`。
+
+设计含义：
+
+- 金融危机主要由 `true_crisis` 路线负责，适合硬降风险。
+- 互联网泡沫不能只靠传统危机确认，需要保留泡沫脆弱性 route。
+- TACO 对这些长周期危机不是防守组件，应继续作为机会通知和人工复核组件。
+
+## 当前推荐默认值
+
+- 杠杆策略：默认挂载统一插件，允许 `risk_off` 生效。
+- 高波动行业杠杆策略：默认挂载统一插件，但 `risk_reduced` 是否影响仓位由策略配置控制。
+- 轮动策略：默认开启 50% risk scaling 和 `risk_off` 归零。
+- TACO：默认通知-only；只有没有危机和宏观降风险时才允许提示机会。
+- AI audit：默认不参与交易权限，只能写审计结论和通知证据。