aria-code 0.52.0__py3-none-any.whl

aria_code/brokers/automation.py

@@ -0,0 +1,193 @@
+"""Controlled auto-execution for strategy / alert-driven trading.
+
+OFF BY DEFAULT. An order auto-executes only when EVERY gate passes:
+
+  1. Global kill-switch off  — ARIA_DRY_RUN not set        (brokers.trading.global_dry_run)
+  2. Automation enabled      — automation.enabled=true      (per-broker opt-in)
+  3. Risk/exec passed        — preview.can_execute is True   (no execution_blockers;
+                                covers read_only / live-without-allow_live_trade)
+  4. Direction/symbol allow  — within allowed_sides / allowed_symbols
+  5. Value & rate limits     — max_order_value, max_orders_per_day,
+                                max_orders_per_symbol_per_day
+
+Otherwise the order is LEFT AS A DRAFT (the existing semi-auto behaviour) and the
+skip is audited. Every decision — execute or skip — is written to the trade audit
+log so there is a full paper trail.
+
+This module never lowers an existing guard: it ADDS gates on top of the normal
+preview → risk → confirm pipeline (auto-execution simply supplies the confirm).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from .trading import (
+    TRADE_AUDIT_PATH,
+    _audit,
+    execute_order_preview,
+    global_dry_run,
+    load_order_preview,
+)
+
+
+@dataclass(frozen=True)
+class AutoExecutePolicy:
+    """Per-broker automation policy. Disabled unless explicitly turned on."""
+    enabled: bool = False
+    max_order_value: float = 0.0          # 0 = no extra cap beyond risk rules
+    max_orders_per_day: int = 10
+    max_orders_per_symbol_per_day: int = 3
+    allowed_sides: tuple[str, ...] = ("buy", "sell")
+    allowed_symbols: tuple[str, ...] = ()  # empty = all symbols allowed
+
+    @classmethod
+    def from_config(cls, config: Dict[str, Any] | None) -> "AutoExecutePolicy":
+        auto = ((config or {}).get("automation") or {})
+        if not isinstance(auto, dict):
+            return cls()
+        sides = auto.get("allowed_sides") or ["buy", "sell"]
+        syms = auto.get("allowed_symbols") or []
+        return cls(
+            enabled=bool(auto.get("enabled", False)),
+            max_order_value=float(auto.get("max_order_value", 0.0) or 0.0),
+            max_orders_per_day=int(auto.get("max_orders_per_day", 10) or 0),
+            max_orders_per_symbol_per_day=int(auto.get("max_orders_per_symbol_per_day", 3) or 0),
+            allowed_sides=tuple(str(s).lower() for s in sides),
+            allowed_symbols=tuple(str(s).upper() for s in syms),
+        )
+
+
+@dataclass
+class AutoExecuteDecision:
+    allowed: bool
+    reasons: List[str] = field(default_factory=list)
+
+
+def _order_from_preview(preview: Dict[str, Any]) -> Dict[str, Any]:
+    return ((preview.get("order_plan") or {}).get("estimated_order") or {})
+
+
+def _order_value(order: Dict[str, Any]) -> float:
+    for key in ("value", "notional", "amount"):
+        try:
+            v = float(order.get(key) or 0)
+            if v > 0:
+                return v
+        except (TypeError, ValueError):
+            pass
+    try:
+        return float(order.get("price") or 0) * float(order.get("quantity") or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def evaluate_auto_execute(
+    preview: Dict[str, Any],
+    policy: AutoExecutePolicy,
+    *,
+    dry_run: bool,
+    executed_today: int = 0,
+    executed_today_symbol: int = 0,
+) -> AutoExecuteDecision:
+    """Pure gate evaluation. Returns allowed=True only if ALL gates pass."""
+    reasons: List[str] = []
+    if dry_run:
+        reasons.append("ARIA_DRY_RUN 全局冻结，禁止自动执行")
+    if not policy.enabled:
+        reasons.append("自动执行未开启 (automation.enabled=false)")
+    if not preview.get("can_execute"):
+        blockers = preview.get("execution_blockers") or []
+        reasons.append("风控/执行未通过: " + ("; ".join(str(b) for b in blockers[:3]) or "can_execute=false"))
+
+    order = _order_from_preview(preview)
+    side = str(order.get("side") or preview.get("side") or "").lower()
+    sym = str(order.get("symbol") or preview.get("symbol") or "").upper()
+
+    if policy.allowed_sides and side and side not in policy.allowed_sides:
+        reasons.append(f"方向 {side} 不在允许列表 {list(policy.allowed_sides)}")
+    if policy.allowed_symbols and sym and sym not in policy.allowed_symbols:
+        reasons.append(f"标的 {sym} 不在自动交易白名单")
+
+    val = _order_value(order)
+    if policy.max_order_value and val > policy.max_order_value:
+        reasons.append(f"单笔金额 {val:.2f} 超过上限 {policy.max_order_value:.2f}")
+    if policy.max_orders_per_day and executed_today >= policy.max_orders_per_day:
+        reasons.append(f"已达当日自动单上限 {policy.max_orders_per_day}")
+    if policy.max_orders_per_symbol_per_day and executed_today_symbol >= policy.max_orders_per_symbol_per_day:
+        reasons.append(f"{sym} 已达当日自动单上限 {policy.max_orders_per_symbol_per_day}")
+
+    return AutoExecuteDecision(allowed=(not reasons), reasons=reasons)
+
+
+def _count_auto_executed_today(broker_id: str, symbol: Optional[str] = None) -> int:
+    """Count successful auto-executions today (from the trade audit log)."""
+    if not TRADE_AUDIT_PATH.exists():
+        return 0
+    today = datetime.now(timezone.utc).date()
+    sym = (symbol or "").upper()
+    n = 0
+    try:
+        for line in TRADE_AUDIT_PATH.read_text(encoding="utf-8").splitlines():
+            try:
+                row = json.loads(line)
+            except Exception:
+                continue
+            if row.get("event") != "auto_execute" or not row.get("success"):
+                continue
+            if broker_id and row.get("broker_id") != broker_id:
+                continue
+            if sym and str(row.get("symbol") or "").upper() != sym:
+                continue
+            ts = row.get("ts")
+            if ts and datetime.fromtimestamp(int(ts), tz=timezone.utc).date() != today:
+                continue
+            n += 1
+    except Exception:
+        return n
+    return n
+
+
+def run_auto_execute(
+    broker: Any,
+    preview_id: str,
+    policy: Optional[AutoExecutePolicy] = None,
+) -> Dict[str, Any]:
+    """Auto-execute a preview iff all gates pass; otherwise leave it as a draft.
+
+    Returns a dict with ``auto_executed`` / ``skipped`` and the gate ``reasons``.
+    """
+    preview = load_order_preview(preview_id)
+    if not preview:
+        return {"success": False, "error": f"preview not found: {preview_id}"}
+
+    if policy is None:
+        policy = AutoExecutePolicy.from_config(getattr(broker, "config", {}) or {})
+
+    broker_id = getattr(broker, "broker_id", "")
+    symbol = str(preview.get("symbol") or _order_from_preview(preview).get("symbol") or "")
+    decision = evaluate_auto_execute(
+        preview, policy,
+        dry_run=global_dry_run(),
+        executed_today=_count_auto_executed_today(broker_id),
+        executed_today_symbol=_count_auto_executed_today(broker_id, symbol),
+    )
+
+    if not decision.allowed:
+        _audit({"event": "auto_execute_skipped", "preview_id": preview_id,
+                "broker_id": broker_id, "symbol": symbol.upper(),
+                "reasons": decision.reasons, "auto": True})
+        return {"success": False, "auto_executed": False, "skipped": True,
+                "reasons": decision.reasons, "preview_id": preview_id}
+
+    result = execute_order_preview(broker, preview_id, confirmed=True)
+    success = bool(result.get("success"))
+    _audit({"event": "auto_execute", "preview_id": preview_id,
+            "broker_id": broker_id, "symbol": symbol.upper(),
+            "success": success, "auto": True})
+    result["auto_executed"] = success
+    return result

aria_code/brokers/base.py

@@ -0,0 +1,231 @@
+"""
+brokers/base.py — 券商接入统一接口
+====================================
+所有券商适配器继承 BrokerBase，对外暴露统一 schema，
+上层代码不关心底层是 XTQuant / IBKR / Alpaca / 富途 / 老虎。
+
+数据类：
+    AccountInfo     账户资金汇总
+    Position        持仓明细
+    Order           订单记录
+    OrderResult     下单结果
+    PortfolioSummary 持仓组合摘要
+
+抽象接口：
+    connect()           建立连接
+    disconnect()        断开连接
+    account_info()      账户资金
+    positions()         当前持仓
+    orders(status)      历史/活跃订单
+    place_order(...)    下单（需用户二次确认，不在此层执行）
+    cancel_order(id)    撤单
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# ── 统一数据 Schema ────────────────────────────────────────────────────────────
+
+@dataclass
+class AccountInfo:
+    broker_id:       str            # 配置中的 id 字段
+    broker_type:     str            # xtquant / ibkr / alpaca …
+    label:           str            # 用户自定义别名
+    account_id:      str            # 账户号（脱敏后展示末4位）
+    currency:        str   = "CNY"
+    total_assets:    float = 0.0    # 总资产
+    cash:            float = 0.0    # 可用现金
+    market_value:    float = 0.0    # 持仓市值
+    frozen:          float = 0.0    # 冻结资金
+    pnl_today:       float = 0.0    # 当日盈亏
+    pnl_total:       float = 0.0    # 累计盈亏
+    pnl_pct:         float = 0.0    # 持仓收益率(%)
+    risk_level:      str   = ""     # low / medium / high
+    extra:           Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def masked_account(self) -> str:
+        return f"****{self.account_id[-4:]}" if len(self.account_id) > 4 else "****"
+
+
+@dataclass
+class Position:
+    symbol:          str
+    name:            str   = ""
+    quantity:        float = 0.0    # 持仓数量（股/手）
+    available_qty:   float = 0.0    # 可卖数量
+    cost_price:      float = 0.0    # 持仓均价
+    current_price:   float = 0.0    # 最新价
+    market_value:    float = 0.0    # 市值
+    pnl:             float = 0.0    # 盈亏金额
+    pnl_pct:         float = 0.0    # 盈亏比例(%)
+    currency:        str   = "CNY"
+    market:          str   = ""     # a_share / us / hk / crypto
+    extra:           Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Order:
+    order_id:        str
+    symbol:          str
+    name:            str   = ""
+    side:            str   = ""     # buy / sell
+    order_type:      str   = ""     # limit / market / stop
+    quantity:        float = 0.0
+    filled_qty:      float = 0.0
+    price:           float = 0.0    # 委托价
+    avg_price:       float = 0.0    # 成交均价
+    status:          str   = ""     # open / filled / cancelled / partial
+    created_at:      str   = ""
+    updated_at:      str   = ""
+    currency:        str   = "CNY"
+    extra:           Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class OrderResult:
+    success:         bool
+    order_id:        str   = ""
+    message:         str   = ""
+    broker_id:       str   = ""
+
+
+@dataclass
+class PortfolioSummary:
+    broker_id:       str
+    positions:       List[Position]     = field(default_factory=list)
+    total_assets:    float              = 0.0
+    total_market_value: float           = 0.0
+    cash:            float              = 0.0
+    total_pnl:       float              = 0.0
+    total_pnl_pct:   float              = 0.0
+    top_holding:     Optional[Position] = None
+    currency:        str                = "CNY"
+
+
+# ── 抽象基类 ───────────────────────────────────────────────────────────────────
+
+class BrokerBase(ABC):
+    """所有券商适配器的抽象基类。"""
+
+    broker_type: str = "base"       # 子类覆盖: xtquant / ibkr / alpaca …
+    broker_name: str = "券商"        # 展示名称
+    market:      str = "CN"         # CN / US / HK / GLOBAL
+    read_only:   bool = False       # True = 只支持查询，不支持下单
+
+    def __init__(self, broker_id: str, config: Dict[str, Any]):
+        self.broker_id = broker_id
+        self.config    = config
+        self.label     = config.get("label", broker_id)
+        self._connected = False
+
+    # ── 连接管理 ──────────────────────────────────────────────────────────────
+
+    @abstractmethod
+    def connect(self) -> bool:
+        """建立连接。返回 True 表示成功。"""
+
+    def disconnect(self) -> None:
+        """断开连接（默认空实现，子类可覆盖）。"""
+        self._connected = False
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    # ── 健康检查 / 自动重连 ────────────────────────────────────────────────────
+
+    def ping(self) -> bool:
+        """轻量存活探测。默认信任连接标志；拥有实时 socket/API 的子类**应覆盖**
+        此方法做真实探测（如 ib.isConnected()、富途 context keepalive），
+        以便检测到静默断开的连接并触发重连。"""
+        return self._connected
+
+    def ensure_connected(self, retries: int = 1) -> bool:
+        """确保连接可用，断开则自动重连。返回 True 表示可用。
+
+        长驻场景（daemon）应在每次券商操作前调用：FutuOpenD / IB Gateway /
+        websocket 掉线时透明重连，而不是静默失败到下一次调用才报错。"""
+        if self._connected and self.ping():
+            return True
+        self._connected = False
+        for _ in range(max(1, retries + 1)):
+            try:
+                if self.connect():
+                    return True
+            except Exception:
+                pass
+        return False
+
+    # ── 账户查询 ──────────────────────────────────────────────────────────────
+
+    @abstractmethod
+    def account_info(self) -> AccountInfo:
+        """返回账户资金汇总。"""
+
+    @abstractmethod
+    def positions(self) -> List[Position]:
+        """返回当前持仓列表。"""
+
+    @abstractmethod
+    def orders(self, status: str = "all", limit: int = 50) -> List[Order]:
+        """
+        返回订单列表。
+        status: "open" | "filled" | "cancelled" | "all"
+        """
+
+    # ── 交易操作（需上层二次确认后才调用）──────────────────────────────────────
+
+    def place_order(
+        self,
+        symbol:     str,
+        side:       str,        # "buy" | "sell"
+        quantity:   float,
+        order_type: str = "limit",
+        price:      float = 0.0,
+        **kwargs: Any,
+    ) -> OrderResult:
+        """
+        下单接口。默认返回不支持，子类覆盖。
+        ⚠️  此方法只应在用户明确确认后被调用。
+        """
+        if self.read_only:
+            return OrderResult(success=False, message=f"{self.broker_name} 为只读模式，不支持下单")
+        return OrderResult(success=False, message="此券商暂不支持程序化下单")
+
+    def cancel_order(self, order_id: str) -> bool:
+        """撤单。返回 True 表示成功。"""
+        return False
+
+    # ── 工具方法 ─────────────────────────────────────────────────────────────
+
+    def portfolio_summary(self) -> PortfolioSummary:
+        """构建持仓摘要（默认实现，子类可覆盖）。"""
+        try:
+            acct = self.account_info()
+            pos  = self.positions()
+            top  = max(pos, key=lambda p: abs(p.market_value), default=None) if pos else None
+            total_pnl = sum(p.pnl for p in pos)
+            total_mv  = sum(p.market_value for p in pos)
+            pnl_pct   = (total_pnl / (total_mv - total_pnl) * 100) if (total_mv - total_pnl) > 0 else 0.0
+            return PortfolioSummary(
+                broker_id=self.broker_id,
+                positions=pos,
+                total_assets=acct.total_assets,
+                total_market_value=acct.market_value,
+                cash=acct.cash,
+                total_pnl=total_pnl,
+                total_pnl_pct=pnl_pct,
+                top_holding=top,
+                currency=acct.currency,
+            )
+        except Exception as e:
+            return PortfolioSummary(broker_id=self.broker_id)
+
+    def __repr__(self) -> str:
+        status = "connected" if self._connected else "disconnected"
+        return f"<{self.__class__.__name__} id={self.broker_id!r} {status}>"

aria_code/brokers/capabilities.py

@@ -0,0 +1,264 @@
+"""Broker capability catalog and setup playbooks.
+
+This module is intentionally UI-free so CLI, daemon, docs, and tests can share
+one source of truth for supported broker connectors.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.util import find_spec
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class BrokerCapability:
+    broker_type: str
+    display_name: str
+    markets: tuple[str, ...]
+    sdk_module: str
+    pip_package: str
+    credential_fields: tuple[str, ...]
+    local_runtime: str
+    read_capabilities: tuple[str, ...]
+    trade_capability: str
+    safety_notes: tuple[str, ...]
+    setup_steps: tuple[str, ...]
+
+    @property
+    def can_trade(self) -> bool:
+        return self.trade_capability not in ("read_only", "unsupported")
+
+
+_BROKER_CAPABILITIES: tuple[BrokerCapability, ...] = (
+    BrokerCapability(
+        broker_type="paper",
+        display_name="Aria 本地仿盘账户",
+        markets=("美股", "港股", "A股", "加密货币"),
+        sdk_module="json",
+        pip_package="builtin",
+        credential_fields=("starting_cash", "currency"),
+        local_runtime="不需要真实券商或本地网关；订单写入本地 paper ledger。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="paper_trade",
+        safety_notes=("仿盘成交不触达真实市场。", "仍使用同一套风控、预览、确认和审计流程。"),
+        setup_steps=(
+            "运行 /paper start 100000 USD 创建本地仿盘账户。",
+            "运行 /broker connect paper_main 连接仿盘账户。",
+            "使用 /trade preview AAPL buy 10 190 生成订单预览，再 /trade confirm <preview_id>。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="xtquant",
+        display_name="迅投 XTQuant / QMT",
+        markets=("A股",),
+        sdk_module="xtquant",
+        pip_package="xtquant",
+        credential_fields=("account_id",),
+        local_runtime="QMT 量化终端需已登录并保持运行；主要面向 Windows。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="live_trade",
+        safety_notes=("实盘交易必须由 /broker_order 二次确认后执行。", "依赖包通常由券商提供，pip 可能不可直接安装。"),
+        setup_steps=(
+            "安装并登录券商 QMT/XTQuant 客户端。",
+            "运行 /broker add xtquant 填写 account_id。",
+            "运行 /broker connect <id>，再用 /account 与 /positions 验证。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="easytrader",
+        display_name="EasyTrader",
+        markets=("A股",),
+        sdk_module="easytrader",
+        pip_package="easytrader",
+        credential_fields=("broker_name", "exe_path"),
+        local_runtime="券商桌面交易客户端需已登录；主要面向 Windows。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="live_trade",
+        safety_notes=("属于客户端自动化路径，稳定性取决于券商客户端界面。",),
+        setup_steps=(
+            "安装并登录同花顺/通达信/华泰/国君等交易客户端。",
+            "运行 /broker add easytrader 填写 broker_name 与 exe_path。",
+            "先用 /account 只读校验，再启用交易。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="futu",
+        display_name="富途牛牛 OpenAPI",
+        markets=("港股", "美股", "A股"),
+        sdk_module="futu",
+        pip_package="futu-api",
+        credential_fields=("host", "port", "market"),
+        local_runtime="FutuOpenD 需在本机或局域网运行，默认 127.0.0.1:11111。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="live_trade",
+        safety_notes=("OpenD 的交易解锁、市场权限和账户类型会影响可用能力。",),
+        setup_steps=(
+            "安装 futu-api 并启动 FutuOpenD。",
+            "运行 /broker add futu 填写 host、port、market。",
+            "运行 /broker connect <id> 后检查 /positions 与 /orders。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="tiger",
+        display_name="老虎证券 OpenAPI",
+        markets=("美股", "港股", "A股"),
+        sdk_module="tigeropen",
+        pip_package="tigeropen",
+        credential_fields=("tiger_id", "private_key_path", "account"),
+        local_runtime="不需要本地网关，但需要开发者账号、账户号和 RSA 私钥。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="live_trade",
+        safety_notes=("私钥文件必须保存在本机，不要写入对话或日志。",),
+        setup_steps=(
+            "在老虎开放平台注册应用并保存 RSA 私钥。",
+            "运行 /broker add tiger 填写 tiger_id、account、private_key_path。",
+            "用 /broker doctor 检查依赖与字段，再 /broker connect <id>。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="longbridge",
+        display_name="长桥证券 OpenAPI",
+        markets=("港股", "美股", "A股"),
+        sdk_module="longbridge",
+        pip_package="longbridge",
+        credential_fields=("app_key", "app_secret", "access_token"),
+        local_runtime="不需要本地网关；需要长桥 OpenAPI App Key/Secret/Token。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="live_trade",
+        safety_notes=("Token 建议只保存在 brokers.json 或环境变量，不进入提示词。",),
+        setup_steps=(
+            "在长桥 OpenAPI 开发者中心创建应用。",
+            "运行 /broker add longbridge 填写 App Key、Secret、Access Token。",
+            "连接后使用 /account、/positions 校验账户数据。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="ibkr",
+        display_name="Interactive Brokers",
+        markets=("全球市场",),
+        sdk_module="ib_insync",
+        pip_package="ib_insync",
+        credential_fields=("host", "port", "client_id"),
+        local_runtime="TWS 或 IB Gateway 需已登录并开启 Socket API。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="live_trade",
+        safety_notes=("模拟端口通常为 7497/4002，实盘端口通常为 7496/4001。",),
+        setup_steps=(
+            "启动 TWS 或 IB Gateway，并启用 API Socket。",
+            "运行 /broker add ibkr 填写 host、port、client_id。",
+            "建议先连模拟盘，再切实盘端口。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="alpaca",
+        display_name="Alpaca Markets",
+        markets=("美股", "加密货币"),
+        sdk_module="alpaca",
+        pip_package="alpaca-py",
+        credential_fields=("api_key", "api_secret", "paper"),
+        local_runtime="不需要本地网关；支持 paper=true 模拟盘。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="paper_or_live_trade",
+        safety_notes=("默认建议使用 paper=true；实盘需确认账户权限。",),
+        setup_steps=(
+            "在 Alpaca 控制台生成 API Key/Secret。",
+            "运行 /broker add alpaca，优先选择 paper=true。",
+            "用 /broker connect <id> 与 /account 验证模拟盘。",
+        ),
+    ),
+    BrokerCapability(
+        broker_type="webull",
+        display_name="Webull",
+        markets=("美股",),
+        sdk_module="webull",
+        pip_package="webull",
+        credential_fields=("username", "password", "device_id"),
+        local_runtime="不需要本地网关；当前适配器默认只读。",
+        read_capabilities=("account", "positions", "orders"),
+        trade_capability="read_only",
+        safety_notes=("非官方 API，默认不开放程序化下单。",),
+        setup_steps=(
+            "安装 webull SDK 并准备登录凭证。",
+            "运行 /broker add webull。",
+            "仅用于 /account、/positions、/orders 只读查询。",
+        ),
+    ),
+)
+
+
+def list_broker_capabilities() -> tuple[BrokerCapability, ...]:
+    return _BROKER_CAPABILITIES
+
+
+def get_broker_capability(broker_type: str) -> BrokerCapability | None:
+    normalized = str(broker_type or "").strip().lower()
+    for spec in _BROKER_CAPABILITIES:
+        if spec.broker_type == normalized:
+            return spec
+    return None
+
+
+def broker_dependency_state(spec: BrokerCapability) -> dict[str, object]:
+    installed = bool(find_spec(spec.sdk_module))
+    return {
+        "broker_type": spec.broker_type,
+        "module": spec.sdk_module,
+        "package": spec.pip_package,
+        "installed": installed,
+        "install_hint": f"/install {spec.pip_package}" if not installed else "",
+    }
+
+
+def broker_connection_plan(broker_type: str) -> tuple[str, ...]:
+    spec = get_broker_capability(broker_type)
+    if not spec:
+        return (
+            "运行 /broker guide 查看支持的券商类型。",
+            "选择券商后运行 /broker add <type>。",
+        )
+    dep = broker_dependency_state(spec)
+    first = (
+        f"依赖已安装: {spec.sdk_module}"
+        if dep["installed"]
+        else f"安装依赖: /install {spec.pip_package}"
+    )
+    return (first, *spec.setup_steps, "常用服务: /account, /positions, /orders, /risk, /report")
+
+
+def broker_service_playbook() -> tuple[dict[str, str], ...]:
+    """Return user-facing broker-to-service usage flows."""
+
+    return (
+        {
+            "service": "账户与持仓",
+            "commands": "/broker connect <id> → /account → /positions → /orders",
+            "used_by": "LLM broker_query 工具、持仓风险分析、组合报告",
+            "guardrail": "只读查询，不触发交易",
+        },
+        {
+            "service": "策略到交易计划",
+            "commands": "/backtest → /signal → broker_order",
+            "used_by": "QuantEngine 信号、回测结果、Kelly/仓位测算",
+            "guardrail": "下单前必须展示订单计划并等待用户确认",
+        },
+        {
+            "service": "TradingView 告警联动",
+            "commands": "TradingView alert → Aria daemon webhook → 分析/通知/订单草案",
+            "used_by": "/tv、/daemon、webhook、通知渠道",
+            "guardrail": "Webhook 默认只生成分析和订单草案，不自动实盘下单",
+        },
+        {
+            "service": "报告与审计",
+            "commands": "/report, /dashboard, /export",
+            "used_by": "账户快照、持仓、行情、信号、风控、交易计划",
+            "guardrail": "报告落本地 artifacts；敏感字段脱敏",
+        },
+    )
+
+
+def filter_capabilities(names: Iterable[str]) -> tuple[BrokerCapability, ...]:
+    wanted = {str(name).strip().lower() for name in names if str(name).strip()}
+    if not wanted:
+        return list_broker_capabilities()
+    return tuple(spec for spec in _BROKER_CAPABILITIES if spec.broker_type in wanted)