Send crisis plugin alerts by email

Use shared QuantPlatformKit strategy-plugin alert helpers and send independent SMTP email alerts for escalated crisis plugin signals.

Author: Pigbibi

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

@@ -34,13 +34,22 @@ jobs:
       IBKR_MIN_RESERVED_CASH_USD: ${{ vars.IBKR_MIN_RESERVED_CASH_USD }}
       IBKR_RESERVED_CASH_RATIO: ${{ vars.IBKR_RESERVED_CASH_RATIO }}
       IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD: ${{ vars.IBKR_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 }}
       # Strategy-owned defaults continue to come from UsEquityStrategies; this workflow only syncs platform/runtime inputs.
       EXECUTION_REPORT_GCS_URI: ${{ vars.EXECUTION_REPORT_GCS_URI }}
       IB_GATEWAY_ZONE: ${{ vars.IB_GATEWAY_ZONE }}
       IB_GATEWAY_IP_MODE: ${{ vars.IB_GATEWAY_IP_MODE }}
       GLOBAL_TELEGRAM_CHAT_ID: ${{ vars.GLOBAL_TELEGRAM_CHAT_ID }}
       NOTIFY_LANG: ${{ vars.NOTIFY_LANG }}
       TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
+      CRISIS_ALERT_SMTP_PASSWORD: ${{ secrets.CRISIS_ALERT_SMTP_PASSWORD }}
     steps:
       - name: Check whether env sync is enabled
         id: config
@@ -273,6 +282,16 @@ jobs:
             remove_secret_vars+=("TELEGRAM_TOKEN")
           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 "${IB_GATEWAY_ZONE:-}" ]; then
             env_pairs+=("IB_GATEWAY_ZONE=${IB_GATEWAY_ZONE}")
           else
@@ -345,6 +364,48 @@ jobs:
             remove_env_vars+=("IBKR_RESERVED_CASH_RATIO")
           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 "${EXECUTION_REPORT_GCS_URI:-}" ]; then
             env_pairs+=("EXECUTION_REPORT_GCS_URI=${EXECUTION_REPORT_GCS_URI}")
           else

README.md

@@ -112,6 +112,14 @@ For IBKR, keep `paper` as a single account-group entry. If you later add live ac
 | `TELEGRAM_TOKEN` | Yes | Telegram bot token. For Cloud Run, prefer a Secret Manager reference instead of a literal env var. |
 | `GLOBAL_TELEGRAM_CHAT_ID` | Yes | Telegram chat ID used by this service. |
 | `NOTIFY_LANG` | No | `en` (default) or `zh` |
+| `CRISIS_ALERT_EMAIL_TO` | No | Comma/semicolon/newline-separated recipients for escalated crisis-plugin email alerts. Email is skipped when unset. |
+| `CRISIS_ALERT_EMAIL_FROM` | No | Sender address for crisis-plugin email alerts. |
+| `CRISIS_ALERT_SMTP_HOST` | No | SMTP host for crisis-plugin email alerts. |
+| `CRISIS_ALERT_SMTP_PORT` | No | SMTP port; defaults to `587`. |
+| `CRISIS_ALERT_SMTP_USERNAME` | No | Optional SMTP username. |
+| `CRISIS_ALERT_SMTP_PASSWORD` | No | Optional SMTP password. For Cloud Run, prefer `CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME` in env sync. |
+| `CRISIS_ALERT_SMTP_STARTTLS` | No | Whether to use STARTTLS; defaults to `true`. |
+| `CRISIS_ALERT_SMTP_SSL` | No | Whether to use implicit SMTP SSL; defaults to `false`. |
 
 The selected account-group entry must provide at least:
 
@@ -207,6 +215,8 @@ Current behavior is fail-fast:
 - missing account-group config source → startup error
 - missing key fields in the selected group (`ib_gateway_instance_name`, `ib_gateway_mode`, `ib_client_id`) → startup error
 
+When `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON` includes the `crisis_response_shadow` plugin, the normal strategy-cycle Telegram 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.
+
 ### GitHub-managed Cloud Run env sync
 
 If code deployment still uses Google Cloud Trigger, but you want GitHub to be the single source of truth for runtime env vars, this repo now includes `.github/workflows/sync-cloud-run-env.yml`. The workflow now also emits `RUNTIME_TARGET_JSON`, so the control plane carries a structured runtime target alongside the legacy `STRATEGY_PROFILE` selector.
@@ -222,10 +232,12 @@ Recommended setup:
   - `ACCOUNT_GROUP` (recommended: `paper`)
   - `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME`
   - Optional: `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`, `IBKR_MIN_RESERVED_CASH_USD`, `IBKR_RESERVED_CASH_RATIO`, `IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
+  - 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`
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`
 - **Repository Secrets**
   - `TELEGRAM_TOKEN` (fallback only when `TELEGRAM_TOKEN_SECRET_NAME` is not set)
+  - `CRISIS_ALERT_SMTP_PASSWORD` (fallback only when `CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME` is not set)
 - **Optional transition Variables**
   - `IB_GATEWAY_ZONE`
   - `IB_GATEWAY_IP_MODE`
@@ -351,6 +363,14 @@ IBKR 账户
 | `TELEGRAM_TOKEN` | 是 | Telegram 机器人 Token。Cloud Run 上更推荐走 Secret Manager 引用，不要直接写成明文 env。 |
 | `GLOBAL_TELEGRAM_CHAT_ID` | 是 | 这个服务使用的 Telegram Chat ID。 |
 | `NOTIFY_LANG` | 否 | `en`（默认）或 `zh` |
+| `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`。 |
 
 选中的账号组配置里，至少要有：
 
@@ -412,6 +432,8 @@ IB_GATEWAY_IP_MODE=internal
 - 没有账号组配置来源 → 启动直接报错
 - 选中的账号组缺少关键字段（`ib_gateway_instance_name`、`ib_gateway_mode`、`ib_client_id`）→ 启动直接报错
 
+如果 `IBKR_STRATEGY_PLUGIN_MOUNTS_JSON` 挂载了 `crisis_response_shadow` 插件，常规策略周期 Telegram 仍会包含插件摘要行。当插件信号升级到非 `no_action`（例如 `canonical_route=true_crisis`、`suggested_action=defend`/`blocked`，或 `would_trade_if_enabled=true`）时，只要 `CRISIS_ALERT_*` SMTP 配置完整，服务还会额外发一封独立危机邮件。
+
 ### GitHub 统一管理 Cloud Run 环境变量
 
 如果代码部署继续走 Google Cloud Trigger，但你想把运行时环境变量统一放在 GitHub 管理，这个仓库现在提供了 `.github/workflows/sync-cloud-run-env.yml`。
@@ -427,10 +449,12 @@ IB_GATEWAY_IP_MODE=internal
   - `ACCOUNT_GROUP`（建议设为 `paper`）
   - `IB_ACCOUNT_GROUP_CONFIG_SECRET_NAME`
   - 可选：`IBKR_STRATEGY_PLUGIN_MOUNTS_JSON`、`IBKR_MIN_RESERVED_CASH_USD`、`IBKR_RESERVED_CASH_RATIO`、`IBKR_SAFE_HAVEN_CASH_SUBSTITUTE_THRESHOLD_USD`
+  - 可选危机插件邮件告警：`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`
   - `GLOBAL_TELEGRAM_CHAT_ID`
   - `NOTIFY_LANG`
 - **仓库级 Secrets**
   - `TELEGRAM_TOKEN`（仅在没设置 `TELEGRAM_TOKEN_SECRET_NAME` 时作为 fallback）
+  - `CRISIS_ALERT_SMTP_PASSWORD`（仅在没设置 `CRISIS_ALERT_SMTP_PASSWORD_SECRET_NAME` 时作为 fallback）
 - **可选过渡 Variables**
   - `IB_GATEWAY_ZONE`
   - `IB_GATEWAY_IP_MODE`

application/runtime_strategy_adapters.py

@@ -6,6 +6,12 @@
 from typing import Any
 
 import pandas as pd
+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,
+)
 
 
 @dataclass(frozen=True)
@@ -46,26 +52,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 get_historical_close(self, ib, symbol, duration="2 Y", bar_size="1 day"):
         series = self.fetch_historical_price_series_fn(

main.py

@@ -25,6 +25,7 @@
 from decision_mapper import map_strategy_decision
 from entrypoints.cloud_run import is_market_open_today
 from notifications.telegram import build_strategy_display_name, build_translator, send_telegram_message
+from quant_platform_kit.notifications.email import send_smtp_email
 from quant_platform_kit.common.runtime_assembly import build_runtime_assembly
 from quant_platform_kit.common.runtime_reports import (
     append_runtime_report_error,
@@ -232,6 +233,14 @@ def _env_flag(name: str) -> bool:
 TG_TOKEN = RUNTIME_SETTINGS.tg_token
 TG_CHAT_ID = RUNTIME_SETTINGS.tg_chat_id
 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)
 
 CASH_RESERVE_RATIO = STRATEGY_RUNTIME.cash_reserve_ratio
 CASH_RESERVE_FLOOR_USD = getattr(STRATEGY_RUNTIME, "cash_reserve_floor_usd", 0.0)
@@ -468,6 +477,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 build_account_notification_lines() -> tuple[str, ...]:
     account_ids = tuple(str(account_id).strip() for account_id in ACCOUNT_IDS if str(account_id).strip())
     if not account_ids:
@@ -601,6 +639,8 @@ def _handle_request(*, dry_run_only_override: bool | None = None, response_body:
             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)
         cycle_result = coerce_strategy_cycle_result(
             run_strategy_core(
                 strategy_plugin_signals=strategy_plugin_signals,

notifications/telegram.py

@@ -77,6 +77,12 @@
         "blend_gate_reason_bollinger_cap": "突破布林上轨",
         "blend_gate_reason_volatility_delever": "{symbol} {window} 日年化波动率 {volatility} 高于 {threshold}，SOXL 转向 {redirect_symbol}",
         "strategy_plugin_line": "🧩 插件：{plugin} | 状态：{route} | 提醒：{action}",
+        "strategy_plugin_alert_subject": "🚨 危机插件告警：{plugin} | {route}",
+        "strategy_plugin_alert_title": "🚨 【危机插件告警】",
+        "strategy_plugin_alert_strategy": "策略：{strategy}",
+        "strategy_plugin_alert_as_of": "信号时间：{as_of}",
+        "strategy_plugin_alert_would_trade": "若启用交易会操作：{value}",
+        "strategy_plugin_alert_source": "来源：{source}",
         "strategy_plugin_name_crisis_response_shadow": "危机观察通知",
         "strategy_plugin_mode_shadow": "影子观察",
         "strategy_plugin_route_no_action": "未触发危机",
@@ -192,6 +198,12 @@
         "blend_gate_reason_bollinger_cap": "price above upper band",
         "blend_gate_reason_volatility_delever": "{symbol} {window}d annualized volatility {volatility} is above {threshold}; redirect SOXL to {redirect_symbol}",
         "strategy_plugin_line": "🧩 Plugin: {plugin} | status: {route} | notice: {action}",
+        "strategy_plugin_alert_subject": "🚨 Crisis plugin alert: {plugin} | {route}",
+        "strategy_plugin_alert_title": "🚨 【Crisis Plugin Alert】",
+        "strategy_plugin_alert_strategy": "Strategy: {strategy}",
+        "strategy_plugin_alert_as_of": "Signal as-of: {as_of}",
+        "strategy_plugin_alert_would_trade": "Would trade if enabled: {value}",
+        "strategy_plugin_alert_source": "Source: {source}",
         "strategy_plugin_name_crisis_response_shadow": "Crisis Watch Notice",
         "strategy_plugin_mode_shadow": "shadow",
         "strategy_plugin_route_no_action": "no crisis detected",

requirements.txt

@@ -1,7 +1,7 @@
 flask
 gunicorn
-quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@9c4ea7878a08fb2f518c74c99bda68d8ef8fd0bb
-us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@ce7887482eeab7f519484610ee8b20cb7bc886a0
+quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@1b6febbba7df81179ad7579f430c26a811c0e1a8
+us-equity-strategies @ git+https://github.com/QuantStrategyLab/UsEquityStrategies.git@1636271a3e0c17fc0c5da363f67eabe114eeff48
 pandas
 numpy
 requests