Send crisis plugin alerts by email

.github/workflows/sync-cloud-run-env.yml

@@ -33,6 +33,14 @@ jobs:
       SCHWAB_MIN_RESERVED_CASH_USD: ${{ vars.SCHWAB_MIN_RESERVED_CASH_USD }}
       SCHWAB_RESERVED_CASH_RATIO: ${{ vars.SCHWAB_RESERVED_CASH_RATIO }}
       SCHWAB_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD: ${{ vars.SCHWAB_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD }}
+      CRISIS_ALERT_EMAIL_TO: ${{ vars.CRISIS_ALERT_EMAIL_TO }}
+      CRISIS_ALERT_EMAIL_FROM: ${{ vars.CRISIS_ALERT_EMAIL_FROM }}
+      CRISIS_ALERT_SMTP_HOST: ${{ vars.CRISIS_ALERT_SMTP_HOST }}
+      CRISIS_ALERT_SMTP_PORT: ${{ vars.CRISIS_ALERT_SMTP_PORT }}
+      CRISIS_ALERT_SMTP_USERNAME: ${{ vars.CRISIS_ALERT_SMTP_USERNAME }}
+      CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME: ${{ vars.CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME }}
+      CRISIS_ALERT_SMTP_STARTTLS: ${{ vars.CRISIS_ALERT_SMTP_STARTTLS }}
+      CRISIS_ALERT_SMTP_SSL: ${{ vars.CRISIS_ALERT_SMTP_SSL }}
       # Optional strategy overrides; leave unset to inherit the UsEquityStrategies profile defaults.
       INCOME_THRESHOLD_USD: ${{ vars.INCOME_THRESHOLD_USD }}
       QQQI_INCOME_RATIO: ${{ vars.QQQI_INCOME_RATIO }}
@@ -43,6 +51,7 @@ jobs:
       TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
       SCHWAB_API_KEY: ${{ secrets.SCHWAB_API_KEY }}
       SCHWAB_APP_SECRET: ${{ secrets.SCHWAB_APP_SECRET }}
+      CRISIS_ALERT_SMTP_PASSWORD: ${{ secrets.CRISIS_ALERT_SMTP_PASSWORD }}
     steps:
       - name: Check whether env sync is enabled
         id: config
@@ -266,6 +275,16 @@ jobs:
             remove_secret_vars+=("SCHWAB_APP_SECRET")
           fi
 
+          if [ -n "${CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME:-}" ]; then
+            secret_pairs+=("CRISIS_ALERT_SMTP_PASSWORD=${CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME}:latest")
+          elif [ -n "${CRISIS_ALERT_SMTP_PASSWORD:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_SMTP_PASSWORD=${CRISIS_ALERT_SMTP_PASSWORD}")
+            remove_secret_vars+=("CRISIS_ALERT_SMTP_PASSWORD")
+          else
+            remove_env_vars+=("CRISIS_ALERT_SMTP_PASSWORD")
+            remove_secret_vars+=("CRISIS_ALERT_SMTP_PASSWORD")
+          fi
+
           if [ -n "${SCHWAB_FEATURE_SNAPSHOT_PATH:-}" ]; then
             env_pairs+=("SCHWAB_FEATURE_SNAPSHOT_PATH=${SCHWAB_FEATURE_SNAPSHOT_PATH}")
           else
@@ -308,6 +327,48 @@ jobs:
             remove_env_vars+=("SCHWAB_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD")
           fi
 
+          if [ -n "${CRISIS_ALERT_EMAIL_TO:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_EMAIL_TO=${CRISIS_ALERT_EMAIL_TO}")
+          else
+            remove_env_vars+=("CRISIS_ALERT_EMAIL_TO")
+          fi
+
+          if [ -n "${CRISIS_ALERT_EMAIL_FROM:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_EMAIL_FROM=${CRISIS_ALERT_EMAIL_FROM}")
+          else
+            remove_env_vars+=("CRISIS_ALERT_EMAIL_FROM")
+          fi
+
+          if [ -n "${CRISIS_ALERT_SMTP_HOST:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_SMTP_HOST=${CRISIS_ALERT_SMTP_HOST}")
+          else
+            remove_env_vars+=("CRISIS_ALERT_SMTP_HOST")
+          fi
+
+          if [ -n "${CRISIS_ALERT_SMTP_PORT:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_SMTP_PORT=${CRISIS_ALERT_SMTP_PORT}")
+          else
+            remove_env_vars+=("CRISIS_ALERT_SMTP_PORT")
+          fi
+
+          if [ -n "${CRISIS_ALERT_SMTP_USERNAME:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_SMTP_USERNAME=${CRISIS_ALERT_SMTP_USERNAME}")
+          else
+            remove_env_vars+=("CRISIS_ALERT_SMTP_USERNAME")
+          fi
+
+          if [ -n "${CRISIS_ALERT_SMTP_STARTTLS:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_SMTP_STARTTLS=${CRISIS_ALERT_SMTP_STARTTLS}")
+          else
+            remove_env_vars+=("CRISIS_ALERT_SMTP_STARTTLS")
+          fi
+
+          if [ -n "${CRISIS_ALERT_SMTP_SSL:-}" ]; then
+            env_pairs+=("CRISIS_ALERT_SMTP_SSL=${CRISIS_ALERT_SMTP_SSL}")
+          else
+            remove_env_vars+=("CRISIS_ALERT_SMTP_SSL")
+          fi
+
           if [ -n "${INCOME_THRESHOLD_USD:-}" ]; then
             env_pairs+=("INCOME_THRESHOLD_USD=${INCOME_THRESHOLD_USD}")
           fi

README.md

@@ -72,6 +72,14 @@ Each HTTP request runs one broker execution cycle. The Cloud Scheduler cron shou
 | `GOOGLE_CLOUD_PROJECT` | GCP project ID |
 | `STRATEGY_PROFILE` | Strategy profile selector. Set explicitly per deployment to one `runtime_enabled` `us_equity` profile. |
 | `SCHWAB_STRATEGY_PLUGIN_MOUNTS_JSON` | Optional Schwab-side strategy plugin mount JSON. Prefer this Schwab-specific variable; `STRATEGY_PLUGIN_MOUNTS_JSON` is only a shared fallback. |
+| `CRISIS_ALERT_EMAIL_TO` | Optional comma/semicolon/newline-separated recipients for escalated crisis-plugin email alerts. Email is skipped when unset. |
+| `CRISIS_ALERT_EMAIL_FROM` | Optional sender address for crisis-plugin email alerts. |
+| `CRISIS_ALERT_SMTP_HOST` | Optional SMTP host for crisis-plugin email alerts. |
+| `CRISIS_ALERT_SMTP_PORT` | Optional SMTP port; defaults to `587`. |
+| `CRISIS_ALERT_SMTP_USERNAME` | Optional SMTP username. |
+| `CRISIS_ALERT_SMTP_PASSWORD` | Optional SMTP password. For Cloud Run, prefer `CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME` in env sync. |
+| `CRISIS_ALERT_SMTP_STARTTLS` | Optional STARTTLS toggle; defaults to `true`. |
+| `CRISIS_ALERT_SMTP_SSL` | Optional implicit SMTP SSL toggle; defaults to `false`. |
 | `SCHWAB_MIN_RESERVED_CASH_USD` | Optional platform cash-reserve floor in USD. Default policy: keep `3% of total equity` with no fixed USD floor. Runtime formula: `max(floor, ratio * total_equity)`. |
 | `SCHWAB_RESERVED_CASH_RATIO` | Optional platform cash-reserve ratio. Default policy: keep `3% of total equity` with no fixed USD floor. Runtime formula: `max(floor, ratio * total_equity)`. |
 | `SCHWAB_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` | Safe-haven/cash-sweep target values below this USD amount are kept as cash instead of buying BOXX/BIL. Default `1000`. |
@@ -82,6 +90,8 @@ Each HTTP request runs one broker execution cycle. The Cloud Scheduler cron shou
 
 Strategy plugin mount JSON belongs to platform/deployment configuration, not strategy code. It decides which plugin artifacts this runtime reads, and must not set `mode`; the plugin artifact is self-identifying and carries the effective mode. Invalid plugin mount config is recorded in the runtime report diagnostics and does not block the base strategy cycle.
 
+When the `crisis_response_shadow` plugin is mounted, the normal Telegram cycle message still includes the compact plugin line. If the plugin signal escalates beyond `no_action` (for example `canonical_route=true_crisis`, `suggested_action=defend`/`blocked`, or `would_trade_if_enabled=true`), the service also sends an independent crisis email when the `CRISIS_ALERT_*` SMTP settings are complete.
+
 Only `GLOBAL_TELEGRAM_CHAT_ID` and `NOTIFY_LANG` are good candidates for cross-project sharing. `TELEGRAM_TOKEN`, Schwab API credentials, and other runtime secrets should remain repository-specific.
 
 The Schwab OAuth token payload is read from Secret Manager secret `schwab_token`.
@@ -109,6 +119,7 @@ Recommended setup:
   - `STRATEGY_PROFILE` (set explicitly to one enabled profile: `global_etf_rotation`, `mega_cap_leader_rotation_top50_balanced`, `russell_1000_multi_factor_defensive`, `tqqq_growth_income`, `soxl_soxx_trend_income`, or `tech_communication_pullback_enhancement`)
   - Optional: `SCHWAB_FEATURE_SNAPSHOT_PATH`, `SCHWAB_FEATURE_SNAPSHOT_MANIFEST_PATH`, `SCHWAB_STRATEGY_CONFIG_PATH` for feature-snapshot profiles
   - Optional: `SCHWAB_STRATEGY_PLUGIN_MOUNTS_JSON` for strategy plugin artifact mounts. Do not include `mode` in this platform mount JSON.
+  - Optional crisis email alerts: `CRISIS_ALERT_EMAIL_TO`, `CRISIS_ALERT_EMAIL_FROM`, `CRISIS_ALERT_SMTP_HOST`, `CRISIS_ALERT_SMTP_PORT`, `CRISIS_ALERT_SMTP_USERNAME`, `CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME`, `CRISIS_ALERT_SMTP_STARTTLS`, `CRISIS_ALERT_SMTP_SSL`
   - Optional: `SCHWAB_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` for the platform cash/BOXX small-notional cutoff.
   - Optional: `INCOME_THRESHOLD_USD` (strategy override only)
   - Optional: `QQQI_INCOME_RATIO` (strategy override only)
@@ -118,6 +129,7 @@ Recommended setup:
   - Optional fallback only: `TELEGRAM_TOKEN`
   - Optional fallback only: `SCHWAB_API_KEY`
   - Optional fallback only: `SCHWAB_APP_SECRET`
+  - Optional fallback only: `CRISIS_ALERT_SMTP_PASSWORD`
 - **Shared Variables already supported**
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`
@@ -187,6 +199,14 @@ Telegram 通知包含结构化的调仓和心跳消息，支持中英文切换
 | `GOOGLE_CLOUD_PROJECT` | GCP 项目 ID |
 | `STRATEGY_PROFILE` | 策略档位选择。每个部署都要显式设置；当前已启用值包括 `global_etf_rotation`、`mega_cap_leader_rotation_top50_balanced`、`russell_1000_multi_factor_defensive`、`tqqq_growth_income`、`soxl_soxx_trend_income` 和 `tech_communication_pullback_enhancement` |
 | `SCHWAB_STRATEGY_PLUGIN_MOUNTS_JSON` | 可选的 Schwab 侧策略插件挂载 JSON。优先使用这个 Schwab 专用变量；`STRATEGY_PLUGIN_MOUNTS_JSON` 只作为共享 fallback。 |
+| `CRISIS_ALERT_EMAIL_TO` | 可选的危机插件升级邮件收件人，支持逗号、分号或换行分隔。不配置则跳过邮件。 |
+| `CRISIS_ALERT_EMAIL_FROM` | 可选的危机插件升级邮件发件人。 |
+| `CRISIS_ALERT_SMTP_HOST` | 可选的危机插件升级邮件 SMTP host。 |
+| `CRISIS_ALERT_SMTP_PORT` | 可选的 SMTP 端口，默认 `587`。 |
+| `CRISIS_ALERT_SMTP_USERNAME` | 可选的 SMTP 用户名。 |
+| `CRISIS_ALERT_SMTP_PASSWORD` | 可选的 SMTP 密码。Cloud Run env sync 建议配置 `CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME`。 |
+| `CRISIS_ALERT_SMTP_STARTTLS` | 可选，是否使用 STARTTLS，默认 `true`。 |
+| `CRISIS_ALERT_SMTP_SSL` | 可选，是否使用隐式 SMTP SSL，默认 `false`。 |
 | `SCHWAB_MIN_RESERVED_CASH_USD` | 可选的平台保留现金下限，单位 USD。默认策略是：不设置固定 USD 下限，仅保留 `总资产 3%`。运行时公式：`max(下限, 比例 * 总资产)`。 |
 | `SCHWAB_RESERVED_CASH_RATIO` | 可选的平台保留现金比例。默认策略是：不设置固定 USD 下限，仅保留 `总资产 3%`。运行时公式：`max(下限, 比例 * 总资产)`。 |
 | `SCHWAB_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD` | `BOXX`/`BIL` 等避险现金替代标的目标金额低于该 USD 门槛时保留现金，不买入。默认 `1000`。 |
@@ -197,6 +217,8 @@ Telegram 通知包含结构化的调仓和心跳消息，支持中英文切换
 
 策略插件挂载 JSON 属于平台/部署配置，不属于策略代码。它只决定当前 runtime 读取哪些插件 artifact，不能在挂载里设置 `mode`；插件 artifact 自带身份和有效 mode。插件挂载配置错误会写入 runtime report diagnostics，不阻断基础策略运行周期。
 
+如果挂载了 `crisis_response_shadow` 插件，常规策略周期 Telegram 仍会包含插件摘要行。当插件信号升级到非 `no_action`（例如 `canonical_route=true_crisis`、`suggested_action=defend`/`blocked`，或 `would_trade_if_enabled=true`）时，只要 `CRISIS_ALERT_*` SMTP 配置完整，服务还会额外发一封独立危机邮件。
+
 如果你在多个 quant 仓库之间保留一层共享配置，通常只建议共享 `GLOBAL_TELEGRAM_CHAT_ID` 和 `NOTIFY_LANG`。`TELEGRAM_TOKEN`、Schwab API key 这些仍然应该由这个仓库自己管理。
 
 Schwab OAuth token payload 当前从 Secret Manager 的 `schwab_token` 里读取。
@@ -224,6 +246,7 @@ Schwab OAuth token payload 当前从 Secret Manager 的 `schwab_token` 里读取
   - `STRATEGY_PROFILE`（显式设置为任一已启用 profile：`global_etf_rotation`、`mega_cap_leader_rotation_top50_balanced`、`russell_1000_multi_factor_defensive`、`tqqq_growth_income`、`soxl_soxx_trend_income` 或 `tech_communication_pullback_enhancement`）
   - 可选：`SCHWAB_FEATURE_SNAPSHOT_PATH`、`SCHWAB_FEATURE_SNAPSHOT_MANIFEST_PATH`、`SCHWAB_STRATEGY_CONFIG_PATH`，用于 feature-snapshot 策略
   - 可选：`SCHWAB_STRATEGY_PLUGIN_MOUNTS_JSON`，用于策略插件 artifact 挂载。不要在这个平台挂载 JSON 里放 `mode`
+  - 可选危机插件邮件告警：`CRISIS_ALERT_EMAIL_TO`、`CRISIS_ALERT_EMAIL_FROM`、`CRISIS_ALERT_SMTP_HOST`、`CRISIS_ALERT_SMTP_PORT`、`CRISIS_ALERT_SMTP_USERNAME`、`CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME`、`CRISIS_ALERT_SMTP_STARTTLS`、`CRISIS_ALERT_SMTP_SSL`
   - 可选：`SCHWAB_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`，用于平台层现金/BOXX 小额门槛
   - 可选：`INCOME_THRESHOLD_USD`（仅策略 override）
   - 可选：`QQQI_INCOME_RATIO`（仅策略 override）
@@ -233,6 +256,7 @@ Schwab OAuth token payload 当前从 Secret Manager 的 `schwab_token` 里读取
   - 仅保留为 fallback：`TELEGRAM_TOKEN`
   - 仅保留为 fallback：`SCHWAB_API_KEY`
   - 仅保留为 fallback：`SCHWAB_APP_SECRET`
+  - 仅保留为 fallback：`CRISIS_ALERT_SMTP_PASSWORD`
 - **已支持的共享 Variables**
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`

application/runtime_strategy_adapters.py

@@ -7,6 +7,12 @@
 from typing import Any
 
 from quant_platform_kit.common.runtime_inputs import build_semiconductor_rotation_indicators_from_history
+from quant_platform_kit.common.strategy_plugins import (
+    build_strategy_plugin_alert_messages,
+    build_strategy_plugin_notification_lines,
+    should_alert_strategy_plugin_signal,
+    translate_strategy_plugin_value,
+)
 from quant_platform_kit.strategy_contracts import build_account_state_from_portfolio_snapshot
 
 
@@ -53,26 +59,20 @@ def attach_strategy_plugin_report(self, report, *, signals, error: str | None =
             report.setdefault("diagnostics", {})["strategy_plugin_error"] = error
 
     def translate_strategy_plugin_value(self, category: str, raw_value: str | None) -> str:
-        value = str(raw_value or "").strip() or "unknown"
-        key = f"strategy_plugin_{category}_{value}"
-        translated = self.translator(key)
-        return translated if translated != key else value
+        return translate_strategy_plugin_value(category, raw_value, translator=self.translator)
 
     def build_strategy_plugin_notification_lines(self, signals) -> tuple[str, ...]:
-        lines = []
-        for signal in signals:
-            route = signal.canonical_route or "unknown_route"
-            action = signal.suggested_action or "unknown_action"
-            lines.append(
-                self.translator(
-                    "strategy_plugin_line",
-                    plugin=self.translate_strategy_plugin_value("name", signal.plugin),
-                    mode=self.translate_strategy_plugin_value("mode", signal.effective_mode),
-                    route=self.translate_strategy_plugin_value("route", route),
-                    action=self.translate_strategy_plugin_value("action", action),
-                )
-            )
-        return tuple(lines)
+        return build_strategy_plugin_notification_lines(signals, translator=self.translator)
+
+    def should_alert_strategy_plugin_signal(self, signal) -> bool:
+        return should_alert_strategy_plugin_signal(signal)
+
+    def build_strategy_plugin_alert_messages(self, signals):
+        return build_strategy_plugin_alert_messages(
+            signals,
+            translator=self.translator,
+            strategy_label=self.strategy_profile,
+        )
 
     def fetch_reference_history(self, market_data_port):
         available_inputs = set(self.available_inputs)

main.py

@@ -16,6 +16,7 @@
     build_strategy_display_name,
     build_translator,
 )
+from quant_platform_kit.notifications.email import send_smtp_email
 from quant_platform_kit.schwab import (
     fetch_account_snapshot,
     fetch_default_daily_price_history_candles,
@@ -88,6 +89,14 @@ def _optional_symbol_env(name: str) -> str | None:
 STRATEGY_PROFILE = RUNTIME_SETTINGS.strategy_profile
 STRATEGY_DISPLAY_NAME = RUNTIME_SETTINGS.strategy_display_name
 NOTIFY_LANG = RUNTIME_SETTINGS.notify_lang
+CRISIS_ALERT_EMAIL_TO = getattr(RUNTIME_SETTINGS, "crisis_alert_email_to", ())
+CRISIS_ALERT_EMAIL_FROM = getattr(RUNTIME_SETTINGS, "crisis_alert_email_from", None)
+CRISIS_ALERT_SMTP_HOST = getattr(RUNTIME_SETTINGS, "crisis_alert_smtp_host", None)
+CRISIS_ALERT_SMTP_PORT = getattr(RUNTIME_SETTINGS, "crisis_alert_smtp_port", 587)
+CRISIS_ALERT_SMTP_USERNAME = getattr(RUNTIME_SETTINGS, "crisis_alert_smtp_username", None)
+CRISIS_ALERT_SMTP_PASSWORD = getattr(RUNTIME_SETTINGS, "crisis_alert_smtp_password", None)
+CRISIS_ALERT_SMTP_STARTTLS = getattr(RUNTIME_SETTINGS, "crisis_alert_smtp_starttls", True)
+CRISIS_ALERT_SMTP_SSL = getattr(RUNTIME_SETTINGS, "crisis_alert_smtp_ssl", False)
 t = build_translator(NOTIFY_LANG)
 signal_text = build_signal_text(t)
 strategy_display_name = build_strategy_display_name(t)(
@@ -267,6 +276,35 @@ def build_strategy_plugin_notification_lines(signals) -> tuple[str, ...]:
     return build_strategy_adapters().build_strategy_plugin_notification_lines(signals)
 
 
+def build_strategy_plugin_alert_messages(signals):
+    return build_strategy_adapters().build_strategy_plugin_alert_messages(signals)
+
+
+def send_crisis_alert_email(alert_message) -> bool:
+    return send_smtp_email(
+        subject=alert_message.subject,
+        body=alert_message.body,
+        smtp_host=CRISIS_ALERT_SMTP_HOST,
+        smtp_port=CRISIS_ALERT_SMTP_PORT,
+        sender=CRISIS_ALERT_EMAIL_FROM,
+        recipients=CRISIS_ALERT_EMAIL_TO,
+        username=CRISIS_ALERT_SMTP_USERNAME,
+        password=CRISIS_ALERT_SMTP_PASSWORD,
+        use_starttls=CRISIS_ALERT_SMTP_STARTTLS,
+        use_ssl=CRISIS_ALERT_SMTP_SSL,
+    )
+
+
+def publish_strategy_plugin_alerts(signals) -> int:
+    sent_count = 0
+    for alert_message in build_strategy_plugin_alert_messages(signals):
+        if send_crisis_alert_email(alert_message):
+            sent_count += 1
+    if sent_count:
+        print(f"strategy_plugin_alert_email_sent count={sent_count}", flush=True)
+    return sent_count
+
+
 def persist_execution_report(report, *, dry_run_only_override: bool | None = None):
     return build_composer(dry_run_only_override=dry_run_only_override).build_reporting_adapters().persist_execution_report(report)
 
@@ -360,6 +398,8 @@ def _handle_schwab_cycle(*, dry_run_only_override: bool | None = None, response_
             message="Starting strategy precheck" if dry_run_only_override else "Starting strategy execution",
             execution_window="precheck" if dry_run_only_override else "execution",
         )
+        if dry_run_only_override is None:
+            publish_strategy_plugin_alerts(strategy_plugin_signals)
         run_strategy_core(
             client,
             None,