aria-code 4.1.3__py3-none-any.whl

apps/cli/commands/broker_cmds.py

@@ -0,0 +1,1154 @@
+"""BrokerCommandsMixin — /broker /account /positions /orders commands.
+
+Extracted from aria_cli.py. Module globals (HAS_RICH, console, etc.) are
+imported lazily inside each method body to avoid circular imports at load time.
+"""
+from __future__ import annotations
+
+
+class BrokerCommandsMixin:
+    """Mixin providing broker/account/positions/orders commands."""
+
+    async def cmd_broker(self, args: str):
+        """券商账户管理: /broker list | guide | doctor | services | connect <id> | add <type>"""
+        from aria_cli import HAS_RICH, console, Panel, rich_box, _HAS_BROKERS, _print_error
+        if not _HAS_BROKERS:
+            _print_error("brokers 模块未加载", "请确认 brokers/ 目录存在")
+            return
+
+        parts = args.strip().split(maxsplit=1)
+        sub   = parts[0].lower() if parts else "list"
+        rest  = parts[1].strip() if len(parts) > 1 else ""
+
+        if sub == "list":
+            await self._cmd_broker_list()
+        elif sub == "status":
+            await self._cmd_broker_status()
+        elif sub in ("guide", "matrix", "capabilities", "capability", "help"):
+            await self._cmd_broker_guide(rest)
+        elif sub in ("doctor", "check", "preflight"):
+            await self._cmd_broker_doctor(rest)
+        elif sub in ("services", "service", "usage"):
+            await self._cmd_broker_services()
+        elif sub == "connect":
+            await self._cmd_broker_connect(rest)
+        elif sub == "disconnect":
+            await self._cmd_broker_disconnect(rest)
+        elif sub in ("add", "new"):
+            await self._cmd_broker_add(rest)
+        elif sub == "remove":
+            await self._cmd_broker_remove(rest)
+        elif sub in ("default", "use"):
+            await self._cmd_broker_default(rest)
+        elif sub == "init":
+            await self._cmd_broker_init()
+        else:
+            if HAS_RICH:
+                console.print(Panel(
+                    "[dim]用法:[/dim]\n"
+                    "  [bold]/broker list[/bold]              — 显示所有已配置券商\n"
+                    "  [bold]/broker guide[/bold] [type]      — 查看券商能力矩阵和连接步骤\n"
+                    "  [bold]/broker doctor[/bold]            — 检查配置字段、SDK 和连接状态\n"
+                    "  [bold]/broker services[/bold]          — 查看券商数据如何进入分析/报告/交易计划\n"
+                    "  [bold]/broker connect[/bold] [id]     — 连接券商\n"
+                    "  [bold]/broker disconnect[/bold] [id]  — 断开连接\n"
+                    "  [bold]/broker status[/bold]           — 查看连接状态\n"
+                    "  [bold]/broker add[/bold] <type>       — 添加新券商配置\n"
+                    "  [bold]/broker remove[/bold] <id>      — 删除券商配置\n"
+                    "  [bold]/broker default[/bold] <id>     — 设置默认账户\n"
+                    "  [bold]/broker init[/bold]             — 输出所有类型的配置模板",
+                    title="[bold]/broker[/bold]",
+                    border_style="dim", box=rich_box.ROUNDED, padding=(0, 1),
+                ))
+
+    async def _cmd_broker_list(self):
+        from aria_cli import (HAS_RICH, console, Panel, rich_box,
+                              _list_broker_configs, _BROKERS_CONFIG_PATH, _get_broker_registry)
+        cfgs = _list_broker_configs()
+        if not cfgs:
+            await self._prompt_no_broker_action()
+            return
+
+        reg = _get_broker_registry()
+        if HAS_RICH:
+            from rich.table import Table
+            tbl = Table(title="[bold]已配置券商[/bold]", show_header=True, header_style="bold")
+            tbl.add_column("ID",      style="bold")
+            tbl.add_column("类型",    style="dim")
+            tbl.add_column("名称")
+            tbl.add_column("市场",    style="dim")
+            tbl.add_column("状态")
+            tbl.add_column("默认", justify="center")
+            for c in cfgs:
+                bid    = c.get("id", "")
+                btype  = c.get("type", "")
+                label  = c.get("label", bid)
+                b      = reg.get(bid) if reg else None
+                is_active = reg and reg.active() and reg.active().broker_id == bid
+                if b and b.is_connected:
+                    status = "[green]● 已连接[/green]"
+                else:
+                    status = "[dim]○ 未连接[/dim]"
+                market_map = {
+                    "xtquant":"A股","easytrader":"A股","futu":"港/美/A",
+                    "tiger":"美/港/A","longbridge":"港/美/A",
+                    "ibkr":"美股","alpaca":"美股","webull":"美股",
+                }
+                mkt    = c.get("market", market_map.get(btype, "—"))
+                default_mark = "[green]✓[/green]" if c.get("default") or is_active else ""
+                tbl.add_row(bid, btype, label, mkt, status, default_mark)
+            console.print(tbl)
+        else:
+            for c in cfgs:
+                print(f"  {c.get('id',''):<20} {c.get('type',''):<12} {c.get('label','')}")
+
+    async def _cmd_broker_status(self):
+        from aria_cli import HAS_RICH, console, _get_broker_registry
+        reg = _get_broker_registry()
+        connected = reg.list_connected() if reg else []
+        if not connected:
+            if HAS_RICH:
+                console.print("[dim]当前无已连接券商。运行 [bold]/broker connect[/bold] 建立连接。[/dim]")
+            else:
+                print("无已连接券商")
+            return
+        for b in connected:
+            try:
+                acct = b.account_info()
+                line = (
+                    f"[green]●[/green] [bold]{b.label}[/bold] ({b.broker_type})"
+                    f"  账户: {acct.masked_account}"
+                    f"  总资产: [bold]{acct.currency} {acct.total_assets:,.2f}[/bold]"
+                    f"  可用: {acct.cash:,.2f}"
+                )
+            except Exception as e:
+                line = f"[yellow]●[/yellow] [bold]{b.label}[/bold] ({b.broker_type})  [dim]查询失败: {e}[/dim]"
+            if HAS_RICH:
+                console.print(line)
+            else:
+                print(line)
+
+    async def _cmd_broker_guide(self, broker_type: str = ""):
+        """Show broker capability matrix or a single broker setup plan."""
+        from aria_cli import HAS_RICH, console, Panel, rich_box, _print_error
+        from brokers.capabilities import (
+            broker_connection_plan, broker_dependency_state,
+            get_broker_capability, list_broker_capabilities,
+        )
+        from brokers.config import get_broker_config
+
+        query = (broker_type or "").strip().split(maxsplit=1)[0].lower()
+        spec = get_broker_capability(query) if query else None
+        if query and not spec:
+            cfg = get_broker_config(query)
+            if cfg:
+                spec = get_broker_capability(str(cfg.get("type", "")))
+        if query and not spec:
+            _print_error(f"未知券商类型或配置 id: {query}", "运行 /broker guide 查看支持列表")
+            return
+
+        if spec:
+            dep = broker_dependency_state(spec)
+            lines = [
+                f"类型: {spec.broker_type}",
+                f"市场: {', '.join(spec.markets)}",
+                f"读取能力: {', '.join(spec.read_capabilities)}",
+                f"交易能力: {spec.trade_capability}",
+                f"SDK: {spec.sdk_module} / {spec.pip_package} "
+                f"({'已安装' if dep['installed'] else '未安装'})",
+                f"本地运行时: {spec.local_runtime}",
+                f"配置字段: {', '.join(spec.credential_fields)}",
+                "",
+                "接入步骤:",
+                *[f"  {idx}. {step}" for idx, step in enumerate(broker_connection_plan(spec.broker_type), 1)],
+                "",
+                "安全边界:",
+                *[f"  - {note}" for note in spec.safety_notes],
+            ]
+            if HAS_RICH:
+                console.print(Panel(
+                    "\n".join(lines),
+                    title=f"[bold]{spec.display_name}[/bold] 连接指南",
+                    border_style="blue",
+                    box=rich_box.ROUNDED,
+                    padding=(0, 1),
+                ))
+            else:
+                print("\n".join(lines))
+            return
+
+        specs = list_broker_capabilities()
+        if HAS_RICH:
+            from rich.table import Table
+            tbl = Table(
+                title="[bold]券商能力矩阵[/bold]",
+                show_header=True,
+                header_style="bold dim",
+                box=rich_box.ROUNDED,
+                border_style="dim",
+            )
+            tbl.add_column("Type", style="bold")
+            tbl.add_column("券商")
+            tbl.add_column("市场")
+            tbl.add_column("SDK")
+            tbl.add_column("交易")
+            tbl.add_column("运行时 / 凭证")
+            tbl.add_column("下一步")
+            for item in specs:
+                dep = broker_dependency_state(item)
+                sdk = f"{item.sdk_module} " + ("[green]✓[/green]" if dep["installed"] else "[yellow]未装[/yellow]")
+                trade = "[green]可交易[/green]" if item.can_trade else "[dim]只读[/dim]"
+                runtime = item.local_runtime.split("；", 1)[0]
+                tbl.add_row(
+                    item.broker_type,
+                    item.display_name,
+                    "/".join(item.markets),
+                    sdk,
+                    trade,
+                    runtime,
+                    f"/broker guide {item.broker_type}",
+                )
+            console.print(tbl)
+            console.print("[dim]配置路径: brokers.json；添加: /broker add <type>；体检: /broker doctor[/dim]")
+        else:
+            for item in specs:
+                print(
+                    f"{item.broker_type:<12} {item.display_name:<28} "
+                    f"{'/'.join(item.markets):<12} {item.pip_package:<14} {item.trade_capability}"
+                )
+
+    async def _cmd_broker_doctor(self, args: str = ""):
+        """Check configured broker fields, SDK availability, and connection state."""
+        from aria_cli import HAS_RICH, console, Panel, rich_box
+        from brokers.capabilities import broker_dependency_state, get_broker_capability
+        from brokers.config import BROKERS_CONFIG_PATH, list_broker_configs, validate_broker_config
+        from aria_cli import _get_broker_registry
+
+        cfgs = list_broker_configs()
+        reg = _get_broker_registry()
+        if not cfgs:
+            if HAS_RICH:
+                console.print(Panel(
+                    "尚未配置券商。\n\n"
+                    "先运行 /broker guide 选择券商类型，再运行 /broker add <type>。\n"
+                    f"配置文件: {BROKERS_CONFIG_PATH}",
+                    title="[bold]Broker Doctor[/bold]",
+                    border_style="yellow",
+                    box=rich_box.ROUNDED,
+                    padding=(0, 1),
+                ))
+            else:
+                print(f"尚未配置券商。配置文件: {BROKERS_CONFIG_PATH}")
+            return
+
+        rows = []
+        for cfg in cfgs:
+            broker_id = str(cfg.get("id", ""))
+            btype = str(cfg.get("type", ""))
+            spec = get_broker_capability(btype)
+            errors = validate_broker_config(cfg)
+            fatal = [err for err in errors if not str(err).startswith("⚠")]
+            warnings = [err for err in errors if str(err).startswith("⚠")]
+            dep = broker_dependency_state(spec) if spec else {
+                "installed": False,
+                "install_hint": "",
+                "module": "",
+                "package": "",
+            }
+            broker = reg.get(broker_id) if reg and broker_id else None
+            connected = bool(broker and broker.is_connected)
+            if fatal:
+                status = "fail"
+                next_step = fatal[0]
+            elif not dep["installed"]:
+                status = "warn"
+                next_step = str(dep["install_hint"] or f"安装 {dep['package']}")
+            elif warnings:
+                status = "warn"
+                next_step = warnings[0]
+            elif not connected:
+                status = "ready"
+                next_step = f"/broker connect {broker_id}"
+            else:
+                status = "ok"
+                next_step = "/account /positions"
+            rows.append({
+                "id": broker_id,
+                "type": btype,
+                "label": str(cfg.get("label", broker_id)),
+                "sdk": str(dep.get("module") or "—"),
+                "sdk_ok": bool(dep.get("installed")),
+                "connected": connected,
+                "status": status,
+                "next": next_step,
+            })
+
+        if HAS_RICH:
+            from rich.table import Table
+            tbl = Table(
+                title="[bold]Broker Doctor[/bold]",
+                show_header=True,
+                header_style="bold dim",
+                box=rich_box.ROUNDED,
+                border_style="dim",
+            )
+            tbl.add_column("ID", style="bold")
+            tbl.add_column("Type")
+            tbl.add_column("SDK")
+            tbl.add_column("连接")
+            tbl.add_column("状态")
+            tbl.add_column("下一步")
+            colors = {"ok": "green", "ready": "cyan", "warn": "yellow", "fail": "red"}
+            for row in rows:
+                color = colors.get(row["status"], "dim")
+                tbl.add_row(
+                    row["id"],
+                    row["type"],
+                    f"{row['sdk']} {'✓' if row['sdk_ok'] else '未装'}",
+                    "已连接" if row["connected"] else "未连接",
+                    f"[{color}]{row['status']}[/{color}]",
+                    row["next"],
+                )
+            console.print(tbl)
+            console.print(f"[dim]配置文件: {BROKERS_CONFIG_PATH}[/dim]")
+        else:
+            for row in rows:
+                print(f"{row['id']} {row['type']} {row['status']} next={row['next']}")
+
+    async def _cmd_broker_services(self):
+        """Show how broker data flows into Aria services."""
+        from aria_cli import HAS_RICH, console, rich_box
+        from brokers.capabilities import broker_service_playbook
+
+        rows = broker_service_playbook()
+        if HAS_RICH:
+            from rich.table import Table
+            tbl = Table(
+                title="[bold]券商数据与项目服务联动[/bold]",
+                show_header=True,
+                header_style="bold dim",
+                box=rich_box.ROUNDED,
+                border_style="dim",
+            )
+            tbl.add_column("服务", width=18)
+            tbl.add_column("命令 / 流程", width=42)
+            tbl.add_column("被哪些能力使用", width=34)
+            tbl.add_column("安全边界")
+            for row in rows:
+                tbl.add_row(row["service"], row["commands"], row["used_by"], row["guardrail"])
+            console.print(tbl)
+        else:
+            for row in rows:
+                print(f"{row['service']}: {row['commands']} | {row['guardrail']}")
+
+    async def _cmd_broker_connect(self, broker_id: str):
+        from aria_cli import (HAS_RICH, console, _list_broker_configs,
+                              _BROKERS_CONFIG_PATH, _get_broker_registry, _print_error)
+        cfgs = _list_broker_configs()
+        if not cfgs:
+            _print_error("尚未配置任何券商", f"请先编辑 {_BROKERS_CONFIG_PATH}")
+            return
+        if not broker_id:
+            from brokers.config import get_default_broker_config
+            cfg = get_default_broker_config()
+            if not cfg:
+                _print_error("未设置默认券商", "请用 /broker connect <id> 指定")
+                return
+            broker_id = cfg["id"]
+
+        reg = _get_broker_registry()
+        label = broker_id
+        try:
+            if HAS_RICH:
+                with console.status(f"[dim]正在连接 {broker_id}...[/dim]", spinner="dots"):
+                    import asyncio as _aio
+                    loop = _aio.get_event_loop()
+                    broker = await loop.run_in_executor(None, reg.connect, broker_id)
+            else:
+                broker = reg.connect(broker_id)
+            label = broker.label
+            msg = f"[green]✓[/green] 已连接 [bold]{label}[/bold] ({broker.broker_type})"
+            if HAS_RICH:
+                console.print(msg)
+            else:
+                print(f"已连接 {label}")
+        except Exception as e:
+            # If the failure is a missing broker SDK, give actionable guidance
+            # that ties into the dependency system (/install <pkg>).
+            _err = str(e)
+            _btype = ""
+            try:
+                _btype = next((c.get("type", "") for c in cfgs
+                               if c.get("id") == broker_id), "")
+            except Exception:
+                pass
+            _SDK_PKG = {
+                "longbridge": "longbridge", "ibkr": "ib_insync", "futu": "futu-api",
+                "tiger": "tigeropen", "alpaca": "alpaca-py", "webull": "webull",
+                "easytrader": "easytrader",
+            }
+            _pkg = _SDK_PKG.get(_btype, "")
+            # Primary signal: can we import the SDK module? If not, it's a
+            # missing-dependency failure regardless of the error message
+            # language (the SDK raises a localized "未安装" ImportError).
+            _is_missing_sdk = False
+            if _pkg:
+                _mod = {"longbridge": "longbridge", "ibkr": "ib_insync",
+                        "futu": "futu", "tiger": "tigeropen", "alpaca": "alpaca",
+                        "webull": "webull", "easytrader": "easytrader"}.get(_btype, _pkg)
+                try:
+                    import importlib as _il
+                    _il.import_module(_mod)
+                except Exception:
+                    _is_missing_sdk = True
+            if _is_missing_sdk:
+                # Put the actionable guidance in msg — _print_error's `context`
+                # arg is a category keyword, not free-text, so it won't render.
+                _print_error(
+                    f"连接失败: {label} — {_btype} SDK 未安装。"
+                    f"运行 /install {_pkg} 安装后重试（会先确认）。",
+                )
+            else:
+                _print_error(f"连接失败: {label}", _err or "未知错误（检查账户配置与网络）")
+
+    async def _cmd_broker_disconnect(self, broker_id: str):
+        from aria_cli import HAS_RICH, console, _get_broker_registry, _print_error
+        reg = _get_broker_registry()
+        if not broker_id:
+            b = reg.active() if reg else None
+            if not b:
+                _print_error("无活跃券商", "请指定 id：/broker disconnect <id>")
+                return
+            broker_id = b.broker_id
+        if reg:
+            reg.disconnect(broker_id)
+        msg = f"[dim]已断开连接: {broker_id}[/dim]"
+        if HAS_RICH:
+            console.print(msg)
+        else:
+            print(f"已断开: {broker_id}")
+
+    async def _cmd_broker_add(self, broker_type: str):
+        from aria_cli import (HAS_RICH, console, Panel, rich_box, _print_error,
+                              _supported_broker_types, _get_broker_template,
+                              _add_broker_cfg, _BROKERS_CONFIG_PATH)
+        from ui.picker import arrow_select
+
+        supported = _supported_broker_types()
+
+        # ── 按市场分组、固定宽度对齐 ─────────────────────────────────────────
+        # 每组: (分组标签, [broker_key, ...])
+        _GROUPS = [
+            ("仿盘",       ["paper"]),
+            ("A 股",       ["xtquant", "easytrader"]),
+            ("港股 / 美股", ["futu", "tiger", "longbridge"]),
+            ("美股 / 国际", ["ibkr", "alpaca", "webull"]),
+        ]
+        _CAT = {
+            "paper": "仿盘",
+            "xtquant": "A股",    "easytrader": "A股",
+            "futu": "港/美/A",   "tiger": "港/美/A",   "longbridge": "港/美/A",
+            "ibkr": "全球",      "alpaca": "美股",     "webull": "美股",
+        }
+
+        # ── 选择券商类型 ─────────────────────────────────────────────────────
+        if not broker_type or broker_type not in supported:
+            # Build ordered list with separators for display grouping.
+            # Separator entries have key=None and won't be assigned.
+            all_items = []  # (display_label, desc_str, key_or_None)
+            for g_label, g_keys in _GROUPS:
+                all_items.append((f"─── {g_label} ", "", None))
+                for k in g_keys:
+                    if k in supported:
+                        all_items.append((f"  {k:<12}", supported[k], k))
+
+            picker_options = [(label, desc) for label, desc, _ in all_items]
+            sep_indices    = {i for i, (_, _, key) in enumerate(all_items) if key is None}
+            key_at         = {i: key for i, (_, _, key) in enumerate(all_items) if key}
+
+            # Start cursor on first real entry (skip leading separator)
+            first_real = next((i for i in range(len(all_items)) if i not in sep_indices), 0)
+
+            if HAS_RICH:
+                console.print(
+                    "[bold]选择要添加的券商[/bold]  "
+                    "[dim]↑↓ 移动  Enter 确认  q 取消[/dim]"
+                )
+
+            # If user lands on a separator, nudge to the next real entry.
+            while True:
+                idx = _arrow_select(picker_options, selected=first_real,
+                                    title="", max_visible=12)
+                if idx < 0:
+                    return
+                if idx in sep_indices:
+                    # Find next real entry below; wrap to first if none
+                    nxt = next((i for i in range(idx + 1, len(all_items))
+                                if i not in sep_indices), first_real)
+                    first_real = nxt
+                    continue
+                broker_type = key_at[idx]
+                break
+
+        tmpl = _get_broker_template(broker_type)
+        if not tmpl:
+            _print_error(f"无法获取 {broker_type} 模板", "")
+            return
+
+        # ── 开户 & 凭证获取指南 ───────────────────────────────────────────
+        _GUIDE: dict[str, str] = {
+            "paper": (
+                "Aria 本地仿盘账户 — 无需真实券商\n\n"
+                "使用步骤：\n"
+                "  1. 运行 /paper start 100000 USD 创建本地仿盘账户\n"
+                "  2. 运行 /trade preview AAPL buy 10 190 生成订单预览\n"
+                "  3. 运行 /trade confirm <preview_id> 执行仿盘成交\n\n"
+                "数据位置：~/.arthera/paper_ledger.json"
+            ),
+            "alpaca": (
+                "Alpaca Markets — 免费美股/加密货币 API（支持模拟盘）\n\n"
+                "获取 API Key 步骤：\n"
+                "  1. 注册账号: https://app.alpaca.markets/signup\n"
+                "  2. 登录后进入 Paper Trading → API Keys\n"
+                "  3. 点击 [Generate New Key]，复制 Key 和 Secret\n"
+                "  4. 模拟盘(paper=true)无需入金即可使用\n"
+                "  5. 实盘：修改 paper=false 并完成入金认证\n\n"
+                "依赖：pip install alpaca-py"
+            ),
+            "tiger": (
+                "老虎证券 OpenAPI — 港股 / 美股\n\n"
+                "获取凭证步骤：\n"
+                "  1. 在老虎证券 App 开户并完成实名认证\n"
+                "  2. 访问开发者平台: https://quant.tigeropen.com\n"
+                "  3. 创建应用，获取 Tiger ID 和 RSA 密钥对\n"
+                "  4. 将私钥文件保存到 ~/.arthera/tiger_rsa.pem\n\n"
+                "依赖：pip install tigeropen"
+            ),
+            "longbridge": (
+                "长桥证券 OpenAPI — 港股 / 美股 / A股\n\n"
+                "获取凭证步骤：\n"
+                "  1. 在长桥 App 开户并完成入金\n"
+                "  2. 开发者中心: https://open.longportapp.com\n"
+                "  3. 创建应用获取 App Key、App Secret、Access Token\n\n"
+                "依赖：pip install longbridge"
+            ),
+            "ibkr": (
+                "Interactive Brokers TWS/Gateway — 全球市场\n\n"
+                "连接步骤：\n"
+                "  1. 开户: https://www.interactivebrokers.com\n"
+                "  2. 下载并启动 TWS 或 IB Gateway（保持后台运行）\n"
+                "  3. TWS → 配置 → API → 启用 Socket Client\n"
+                "     实盘端口 7496，模拟端口 7497\n"
+                "  4. Gateway 端口：实盘 4001，模拟 4002\n\n"
+                "依赖：pip install ib_insync"
+            ),
+            "futu": (
+                "富途牛牛 OpenAPI — 港股 / 美股\n\n"
+                "连接步骤：\n"
+                "  1. 在富途牛牛 App 开户\n"
+                "  2. 下载并启动 FutuOpenD\n"
+                "     (牛牛客户端 → 更多 → OpenD)\n"
+                "  3. OpenD 默认监听 127.0.0.1:11111，保持运行\n"
+                "  4. 开发者文档: https://openapi.futunn.com\n\n"
+                "依赖：pip install futu-api"
+            ),
+            "webull": (
+                "Webull — 美股（非官方 API，行情查询为主）\n\n"
+                "获取凭证步骤：\n"
+                "  1. 注册: https://www.webull.com\n"
+                "  2. 使用注册邮箱/手机号 + 密码即可\n"
+                "  3. device_id 首次留空，登录后自动填充\n"
+                "  4. 建议仅用于行情查询，下单功能稳定性有限\n\n"
+                "依赖：pip install webull"
+            ),
+            "xtquant": (
+                "迅投 XTQuant — A股（中信/华鑫/浙商等券商）\n\n"
+                "获取凭证步骤：\n"
+                "  1. 在支持的券商（中信/华鑫/浙商等）开户\n"
+                "  2. 从券商获取并安装 QMT 量化交易终端\n"
+                "  3. 登录 QMT 后保持运行\n"
+                "  4. account_id 即你的券商账号\n"
+                "  5. 仅支持 Windows / Linux (Wine)\n\n"
+                "依赖：pip install xtquant  (安装包需从券商获取)"
+            ),
+            "easytrader": (
+                "EasyTrader — A股（同花顺/通达信/华泰/国君等）\n\n"
+                "配置步骤：\n"
+                "  1. 安装对应券商的交易客户端\n"
+                "  2. broker_name 可选值:\n"
+                "     huatai / guojun / ths / tdx / yh / zszq / xq\n"
+                "  3. exe_path 填写客户端完整路径\n"
+                "  4. 使用时需保持客户端登录运行\n"
+                "  5. 仅支持 Windows\n\n"
+                "依赖：pip install easytrader"
+            ),
+        }
+
+        guide = _GUIDE.get(broker_type, "")
+        cat   = _CAT.get(broker_type, "")
+        if guide and HAS_RICH:
+            console.print(Panel(
+                guide,
+                title=f"[bold]{supported[broker_type]}[/bold]"
+                      + (f"  [dim]{cat}[/dim]" if cat else "")
+                      + "  —  开户 & 凭证获取指南",
+                border_style="blue", box=rich_box.ROUNDED, padding=(0, 2),
+            ))
+            try:
+                input("\n  [Enter] 继续填写配置   Ctrl+C 取消 › ")
+            except (EOFError, KeyboardInterrupt):
+                if HAS_RICH:
+                    console.print("[dim]已取消[/dim]")
+                return
+
+        # ── 对话式配置向导 ─────────────────────────────────────────────────
+        # 字段元组: (key, 说明, 默认值, 是否隐藏输入, 是否可选)
+        _WIZARD: dict[str, list[tuple]] = {
+            "alpaca": [
+                ("id",         "配置 ID (用于 /broker connect)",  "alpaca_paper", False, False),
+                ("label",      "显示名称",                         "Alpaca 模拟盘", False, False),
+                ("api_key",    "API Key",                          "",              False, False),
+                ("api_secret", "API Secret",                       "",              True,  False),
+                ("paper",      "模拟盘 (true=模拟 / false=实盘)",  "true",          False, False),
+            ],
+            "paper": [
+                ("id",            "配置 ID",        "paper_main", False, False),
+                ("label",         "显示名称",        "Aria 仿盘账户", False, False),
+                ("starting_cash", "初始资金",        "100000",     False, False),
+                ("currency",      "币种",            "USD",        False, False),
+            ],
+            "tiger": [
+                ("id",               "配置 ID",         "tiger_us",               False, False),
+                ("label",            "显示名称",         "老虎",                    False, False),
+                ("tiger_id",         "Tiger ID",         "",                       False, False),
+                ("account",          "账户号",            "",                       False, False),
+                ("private_key_path", "RSA 私钥路径",     "~/.arthera/tiger_rsa.pem", False, True),
+            ],
+            "longbridge": [
+                ("id",           "配置 ID",      "lb_main",  False, False),
+                ("label",        "显示名称",      "长桥",      False, False),
+                ("app_key",      "App Key",       "",          False, False),
+                ("app_secret",   "App Secret",    "",          True,  False),
+                ("access_token", "Access Token",  "",          True,  False),
+            ],
+            "ibkr": [
+                ("id",        "配置 ID",                                    "ibkr_main", False, False),
+                ("label",     "显示名称",                                    "盈透",       False, False),
+                ("host",      "TWS/Gateway 主机",                           "127.0.0.1", False, False),
+                ("port",      "端口 (TWS实盘=7496 模拟=7497 Gateway=4001)", "7496",       False, False),
+                ("client_id", "Client ID (每个连接唯一，整数)",               "1",          False, True),
+            ],
+            "futu": [
+                ("id",     "配置 ID",            "futu_main", False, False),
+                ("label",  "显示名称",            "富途",       False, False),
+                ("host",   "OpenD 主机",          "127.0.0.1", False, False),
+                ("port",   "OpenD 端口",          "11111",      False, False),
+                ("market", "市场 (HK / US / CN)", "HK",         False, True),
+            ],
+            "webull": [
+                ("id",        "配置 ID",      "webull_main", False, False),
+                ("label",     "显示名称",      "Webull",      False, False),
+                ("username",  "邮箱或手机号",  "",             False, False),
+                ("password",  "密码",          "",             True,  False),
+                ("device_id", "设备 ID",       "",             False, True),
+            ],
+            "xtquant": [
+                ("id",         "配置 ID",  "xt_main",  False, False),
+                ("label",      "显示名称",  "XTQuant",  False, False),
+                ("account_id", "账户号",    "",          False, False),
+            ],
+            "easytrader": [
+                ("id",          "配置 ID",    "et_main",                    False, False),
+                ("label",       "显示名称",    "EasyTrader",                 False, False),
+                ("broker_name", "券商名",      "huatai",                     False, False),
+                ("exe_path",    "客户端路径",   "C:\\华泰证券\\xiadan.exe",    False, True),
+            ],
+        }
+
+        fields = _WIZARD.get(broker_type, [])
+        total  = len(fields)
+
+        import getpass as _getpass
+
+        if HAS_RICH:
+            console.print(Panel(
+                f"[bold]{supported[broker_type]}[/bold]  配置向导  "
+                f"[dim]共 {total} 项[/dim]\n"
+                f"[dim]Enter = 使用括号内默认值  /  标注 (可选) 的字段可直接跳过[/dim]",
+                border_style="dim", box=rich_box.ROUNDED, padding=(0, 1),
+            ))
+            console.print()
+
+        filled = dict(tmpl)
+        for step, (key, label, default, secret, optional) in enumerate(fields, 1):
+            # Progress prefix: [1/5]
+            progress = f"[{step}/{total}]"
+            opt_tag  = "  (可选)" if optional else ""
+
+            if default:
+                prompt_str = f"  {progress} {label}{opt_tag} [{default}]: "
+            else:
+                prompt_str = f"  {progress} {label}{opt_tag}: "
+
+            try:
+                if secret:
+                    val = _getpass.getpass(prompt_str) or default
+                else:
+                    val = input(prompt_str).strip() or default
+            except (EOFError, KeyboardInterrupt):
+                if HAS_RICH:
+                    console.print("\n[dim]已取消[/dim]")
+                else:
+                    print("\n已取消")
+                return
+
+            # Type coercion
+            if key == "paper":
+                filled[key] = val.lower() not in ("false", "0", "no", "f")
+            elif key == "starting_cash" and val:
+                try:
+                    filled[key] = float(val)
+                except ValueError:
+                    filled[key] = val
+            elif key in ("port", "client_id") and val:
+                try:
+                    filled[key] = int(val)
+                except ValueError:
+                    filled[key] = val
+            elif val:
+                filled[key] = val
+
+        filled.pop("_comment", None)
+
+        # ── 保存配置 ──────────────────────────────────────────────────────
+        try:
+            _add_broker_cfg(filled)
+            broker_id = filled.get("id", broker_type)
+            if HAS_RICH:
+                console.print()
+                console.print(Panel(
+                    f"[green]✓ 已保存[/green]  {broker_id}  [dim]→ {_BROKERS_CONFIG_PATH}[/dim]",
+                    border_style="green", box=rich_box.ROUNDED, padding=(0, 1),
+                ))
+            else:
+                print(f"✓ 已保存 {broker_id}")
+        except Exception as exc:
+            _print_error(f"保存失败: {exc}", f"请手动编辑 {_BROKERS_CONFIG_PATH}")
+            return
+
+        # ── 保存后即刻连接 ────────────────────────────────────────────────
+        try:
+            ans = input(f"\n  是否立即尝试连接 {broker_id}? (y/N) › ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            ans = ""
+        if ans in ("y", "yes", "是"):
+            await self._cmd_broker_connect(broker_id)
+        else:
+            if HAS_RICH:
+                console.print(
+                    f"[dim]稍后可运行 [bold]/broker connect {broker_id}[/bold] 建立连接[/dim]"
+                )
+
+    async def _cmd_broker_remove(self, broker_id: str):
+        from aria_cli import HAS_RICH, console, _print_error, _remove_broker_cfg
+        if not broker_id:
+            _print_error("请指定要删除的券商 id", "/broker remove <id>")
+            return
+        removed = _remove_broker_cfg(broker_id)
+        if removed:
+            console.print(f"[dim]已删除券商配置: {broker_id}[/dim]") if HAS_RICH else print(f"已删除: {broker_id}")
+        else:
+            _print_error(f"未找到券商: {broker_id}", "")
+
+    async def _cmd_broker_default(self, broker_id: str):
+        from aria_cli import HAS_RICH, console, _print_error, _set_default_broker, _get_broker_registry
+        if not broker_id:
+            _print_error("请指定 id", "/broker default <id>")
+            return
+        ok = _set_default_broker(broker_id)
+        if ok:
+            reg = _get_broker_registry()
+            if reg:
+                reg.set_active(broker_id)
+            msg = f"[green]✓[/green] 默认账户已设为: [bold]{broker_id}[/bold]"
+            if HAS_RICH:
+                console.print(msg)
+            else:
+                print(f"默认账户: {broker_id}")
+        else:
+            _print_error(f"未找到券商: {broker_id}", "请先用 /broker add 添加")
+
+    async def _cmd_broker_init(self):
+        from aria_cli import HAS_RICH, console, Panel, rich_box, _BROKERS_CONFIG_PATH
+        from brokers.config import print_all_templates
+        if HAS_RICH:
+            console.print(Panel(
+                f"[dim]将以下内容保存到[/dim] [bold]{_BROKERS_CONFIG_PATH}[/bold] [dim]，填写实际凭证后运行 /broker connect 连接。[/dim]\n\n"
+                f"[dim](仅保留你需要的券商，删除不用的)[/dim]",
+                title="[bold]所有券商配置模板[/bold]",
+                border_style="dim", box=rich_box.ROUNDED, padding=(0, 1),
+            ))
+            from rich.syntax import Syntax
+            console.print(Syntax(print_all_templates(), "json", theme="monokai", line_numbers=False))
+        else:
+            print(print_all_templates())
+
+    async def cmd_account(self, args: str):
+        """显示账户资金汇总。"""
+        from aria_cli import _HAS_BROKERS, _print_error, _get_broker_registry, _print_broker_account
+        if not _HAS_BROKERS:
+            _print_error("brokers 模块未加载", "")
+            return
+        broker_id = args.strip()
+        reg = _get_broker_registry()
+        try:
+            broker = reg.get(broker_id) if broker_id else reg.active()
+            if not broker:
+                broker = await self._auto_connect_broker(broker_id)
+            if not broker:
+                return
+            import asyncio as _aio
+            acct = await _aio.get_event_loop().run_in_executor(None, broker.account_info)
+            _print_broker_account(acct)
+        except Exception as e:
+            _print_error(f"账户查询失败: {e}", "请检查券商连接状态 (/broker status)")
+
+    async def cmd_positions(self, args: str):
+        """显示当前持仓。"""
+        from aria_cli import (HAS_RICH, console, _null_ctx, _HAS_BROKERS,
+                              _print_error, _get_broker_registry, _print_broker_positions)
+        if not _HAS_BROKERS:
+            _print_error("brokers 模块未加载", "")
+            return
+        broker_id = args.strip()
+        reg = _get_broker_registry()
+        try:
+            broker = reg.get(broker_id) if broker_id else reg.active()
+            if not broker:
+                broker = await self._auto_connect_broker(broker_id)
+            if not broker:
+                return
+            import asyncio as _aio
+            with console.status("[dim]获取持仓...[/dim]", spinner="dots") if HAS_RICH else _null_ctx():
+                pos = await _aio.get_event_loop().run_in_executor(None, broker.positions)
+            _print_broker_positions(pos, broker.label, broker.config.get("currency","CNY"))
+        except Exception as e:
+            _print_error(f"持仓查询失败: {e}", "请检查券商连接状态 (/broker status)")
+
+    async def cmd_orders(self, args: str):
+        """显示订单记录。"""
+        from aria_cli import (HAS_RICH, console, _null_ctx, _HAS_BROKERS,
+                              _print_error, _get_broker_registry, _print_broker_orders)
+        if not _HAS_BROKERS:
+            _print_error("brokers 模块未加载", "")
+            return
+        parts     = args.strip().split()
+        status    = "all"
+        broker_id = ""
+        for p in parts:
+            if p in ("open", "filled", "cancelled", "all"):
+                status = p
+            else:
+                broker_id = p
+        reg = _get_broker_registry()
+        try:
+            broker = reg.get(broker_id) if broker_id else reg.active()
+            if not broker:
+                broker = await self._auto_connect_broker(broker_id)
+            if not broker:
+                return
+            import asyncio as _aio
+            with console.status("[dim]获取订单...[/dim]", spinner="dots") if HAS_RICH else _null_ctx():
+                orders = await _aio.get_event_loop().run_in_executor(
+                    None, lambda: broker.orders(status=status, limit=30)
+                )
+            _print_broker_orders(orders, broker.label, status)
+        except Exception as e:
+            _print_error(f"订单查询失败: {e}", "请检查券商连接状态 (/broker status)")
+
+    async def cmd_paper(self, args: str):
+        """本地仿盘账户: /paper start [cash] [currency] | account | positions | orders | reset."""
+        from aria_cli import HAS_RICH, console, _print_error
+        from brokers.config import add_broker_config, get_broker_config, set_default_broker
+        from brokers.paper_broker import PAPER_LEDGER_PATH, PaperBroker
+
+        parts = args.strip().split()
+        sub = parts[0].lower() if parts else "account"
+        rest = parts[1:]
+        broker_id = "paper_main"
+        cash = 100000.0
+        currency = "USD"
+        if rest:
+            try:
+                cash = float(rest[0])
+            except Exception:
+                pass
+        if len(rest) > 1:
+            currency = rest[1].upper()
+
+        if sub in ("start", "init", "reset"):
+            cfg = {
+                "id": broker_id,
+                "type": "paper",
+                "label": "Aria 仿盘账户",
+                "mode": "paper",
+                "starting_cash": cash,
+                "currency": currency,
+                "default": True,
+            }
+            add_broker_config(cfg)
+            set_default_broker(broker_id)
+            broker = PaperBroker(broker_id, cfg)
+            broker.reset(starting_cash=cash, currency=currency)
+            if HAS_RICH:
+                console.print(
+                    f"[green]✓[/green] 仿盘账户已初始化: [bold]{currency} {cash:,.2f}[/bold] "
+                    f"[dim]{PAPER_LEDGER_PATH}[/dim]"
+                )
+            else:
+                print(f"仿盘账户已初始化: {currency} {cash:,.2f} {PAPER_LEDGER_PATH}")
+            return
+
+        cfg = get_broker_config(broker_id)
+        if not cfg:
+            _print_error("尚未创建仿盘账户", "运行 /paper start 100000 USD")
+            return
+        broker = PaperBroker(broker_id, cfg)
+        broker.connect()
+        if sub in ("account", "status"):
+            from aria_cli import _print_broker_account
+            _print_broker_account(broker.account_info())
+        elif sub in ("positions", "pos"):
+            from aria_cli import _print_broker_positions
+            _print_broker_positions(broker.positions(), broker.label, broker.currency)
+        elif sub in ("orders", "order"):
+            from aria_cli import _print_broker_orders
+            _print_broker_orders(broker.orders(limit=30), broker.label, "all")
+        else:
+            if HAS_RICH:
+                console.print("[dim]用法: /paper start [cash] [currency] | account | positions | orders | reset[/dim]")
+            else:
+                print("Usage: /paper start [cash] [currency] | account | positions | orders | reset")
+
+    async def cmd_trade(self, args: str):
+        """两阶段交易: /trade mode | preview SYMBOL buy|sell QTY PRICE | confirm PREVIEW_ID | previews."""
+        from aria_cli import HAS_RICH, console, _print_error, _get_broker_registry
+        from brokers import (
+            OrderIntent, build_order_preview, execute_order_preview,
+            list_order_previews, policy_from_config,
+        )
+
+        parts = args.strip().split()
+        sub = parts[0].lower() if parts else "mode"
+        reg = _get_broker_registry()
+        broker = reg.active() if reg else None
+        if not broker:
+            try:
+                broker = reg.connect_default() if reg else None
+            except Exception as exc:
+                _print_error(f"无法连接默认账户: {exc}", "先运行 /paper start 或 /broker connect <id>")
+                return
+
+        if sub == "mode":
+            if not broker:
+                _print_error("无活跃账户", "先运行 /paper start 或 /broker connect <id>")
+                return
+            policy = policy_from_config(getattr(broker, "config", {}) or {}, getattr(broker, "broker_type", ""))
+            msg = (
+                f"账户: {broker.label} ({broker.broker_type})\n"
+                f"模式: {policy.mode}\n"
+                f"实盘允许: {policy.allow_live_trade}\n"
+                f"确认要求: {policy.require_confirm}\n"
+                f"单笔上限: {policy.max_order_value_weight:.1%}  单票仓位上限: {policy.max_single_position_weight:.1%}"
+            )
+            if HAS_RICH:
+                from aria_cli import Panel, rich_box
+                color = "red" if policy.mode == "live" else "green" if policy.mode == "paper" else "yellow"
+                console.print(Panel(msg, title="[bold]Trade Mode[/bold]", border_style=color, box=rich_box.ROUNDED))
+            else:
+                print(msg)
+            return
+
+        if sub in ("previews", "list"):
+            rows = list_order_previews(limit=10)
+            if HAS_RICH:
+                from rich.table import Table
+                from aria_cli import rich_box
+                tbl = Table(title="[bold]Trade Previews[/bold]", box=rich_box.ROUNDED, border_style="dim")
+                tbl.add_column("ID")
+                tbl.add_column("Mode")
+                tbl.add_column("Broker")
+                tbl.add_column("Order")
+                tbl.add_column("Status")
+                tbl.add_column("Can Exec")
+                for row in rows:
+                    intent = row.get("intent") or {}
+                    tbl.add_row(
+                        row.get("preview_id", ""),
+                        row.get("mode", ""),
+                        row.get("broker_label", ""),
+                        f"{intent.get('side','')} {intent.get('symbol','')} x {intent.get('quantity','')}",
+                        row.get("status", ""),
+                        "yes" if row.get("can_execute") else "no",
+                    )
+                console.print(tbl)
+            else:
+                for row in rows:
+                    print(row)
+            return
+
+        if sub == "confirm":
+            if not broker:
+                _print_error("无活跃账户", "先运行 /paper start 或 /broker connect <id>")
+                return
+            preview_id = parts[1] if len(parts) > 1 else ""
+            if not preview_id:
+                _print_error("请提供 preview_id", "/trade confirm <preview_id>")
+                return
+            result = execute_order_preview(broker, preview_id, confirmed=True)
+            if result.get("success"):
+                if HAS_RICH:
+                    console.print(
+                        f"[green]✓[/green] 订单已执行 [{result.get('mode')}] "
+                        f"{result.get('side')} {result.get('symbol')} x {result.get('qty')} "
+                        f"[dim]#{result.get('order_id')}[/dim]"
+                    )
+                else:
+                    print(result)
+            else:
+                _print_error(
+                    "订单未执行",
+                    "; ".join(result.get("execution_blockers") or [result.get("error", "unknown")]),
+                )
+            return
+
+        if sub == "preview":
+            order_parts = parts[1:]
+        else:
+            order_parts = parts
+        if len(order_parts) < 4:
+            _print_error("用法: /trade preview SYMBOL buy|sell QTY PRICE", "/trade preview AAPL buy 10 190")
+            return
+        if not broker:
+            _print_error("无活跃账户", "先运行 /paper start 或 /broker connect <id>")
+            return
+        symbol, side, qty_raw, price_raw = order_parts[:4]
+        try:
+            qty = float(qty_raw)
+            price = float(price_raw)
+        except Exception:
+            _print_error("数量和价格必须是数字", "/trade preview AAPL buy 10 190")
+            return
+        if side.lower() not in ("buy", "sell"):
+            _print_error("side 必须是 buy 或 sell", "/trade preview AAPL buy 10 190")
+            return
+        preview = build_order_preview(
+            broker,
+            OrderIntent(
+                symbol=symbol,
+                side=side,
+                quantity=qty,
+                price=price,
+                order_type="limit",
+                source="slash_trade",
+            ),
+        )
+        blockers = preview.get("execution_blockers") or []
+        if HAS_RICH:
+            from aria_cli import Panel, rich_box
+            status = "可执行" if preview.get("can_execute") else "不可执行"
+            body = (
+                f"preview_id: [bold]{preview.get('preview_id')}[/bold]\n"
+                f"模式: {preview.get('mode')}  账户: {preview.get('broker_label')}\n"
+                f"订单: {side.upper()} {symbol.upper()} x {qty:g} @ {price:g}\n"
+                f"状态: {status}\n"
+            )
+            if blockers:
+                body += "\n执行限制:\n" + "\n".join(f"  - {b}" for b in blockers)
+            body += "\n\n确认执行: /trade confirm " + str(preview.get("preview_id"))
+            console.print(Panel(body, title="[bold]Trade Preview[/bold]", border_style="yellow", box=rich_box.ROUNDED))
+        else:
+            print(preview)
+
+    async def _prompt_no_broker_action(self) -> None:
+        """未配置券商时显示可导航的操作菜单，选择后直接路由到对应功能。"""
+        from aria_cli import (HAS_RICH, console, Panel, rich_box, _BROKERS_CONFIG_PATH)
+        from ui.picker import arrow_select
+        import subprocess, sys as _sys
+
+        if HAS_RICH:
+            console.print(Panel(
+                "[yellow]尚未配置任何券商[/yellow]  —  请选择下一步操作：",
+                border_style="yellow", box=rich_box.ROUNDED, padding=(0, 1),
+            ))
+
+        actions = [
+            ("  添加新券商",       "交互式向导：选择券商 → 开户指引 → 填写凭证 → 一键连接"),
+            ("  手动编辑配置文件",  f"用系统编辑器打开 {_BROKERS_CONFIG_PATH}"),
+            ("  查看所有配置模板",  "输出全部券商的 JSON 模板供参考"),
+            ("  暂时跳过",         "关闭此菜单，稍后再配置"),
+        ]
+        idx = _arrow_select(actions, selected=0, title="", max_visible=6)
+
+        if idx == 0:
+            await self._cmd_broker_add("")
+        elif idx == 1:
+            try:
+                import pathlib as _pl, json as _json
+                from brokers.config import print_all_templates
+                path = _pl.Path(str(_BROKERS_CONFIG_PATH or
+                                    _pl.Path.home() / ".arthera" / "brokers.json"))
+                path.parent.mkdir(parents=True, exist_ok=True)
+
+                # Pre-populate with full commented template if file is empty/missing
+                needs_template = (
+                    not path.exists()
+                    or path.stat().st_size < 20
+                    or path.read_text(encoding="utf-8").strip() in ('', '{"brokers": []}')
+                )
+                if needs_template:
+                    path.write_text(print_all_templates(), encoding="utf-8")
+
+                subprocess.Popen(["open", str(path)])
+
+                if HAS_RICH:
+                    from rich.syntax import Syntax
+                    from ui.render.output import display_path as _display_path
+                    console.print()
+                    console.print(Panel(
+                        f"[bold]已在编辑器中打开:[/bold] {_display_path(path, fallback='config')}\n\n"
+                        f"[dim]文件已预填所有券商模板。\n"
+                        f"删除不需要的券商块，填写你的实际凭证后保存。[/dim]\n\n"
+                        f"[dim]保存后回到此终端，运行:[/dim]\n"
+                        f"  [bold]/broker connect <id>[/bold]   建立连接\n"
+                        f"  [bold]/broker list[/bold]           查看配置状态",
+                        title="[bold]手动编辑配置[/bold]",
+                        border_style="dim", box=rich_box.ROUNDED, padding=(0, 1),
+                    ))
+            except Exception as exc:
+                if HAS_RICH:
+                    console.print(f"[dim]配置文件路径: {_BROKERS_CONFIG_PATH}[/dim]")
+                    console.print(f"[red]打开失败: {exc}[/red]")
+        elif idx == 2:
+            await self._cmd_broker_init()
+        # idx == 3 or -1 → do nothing (skip)
+
+    async def _auto_connect_broker(self, broker_id: str):
+        """尝试自动连接；无配置时弹出操作菜单。"""
+        from aria_cli import (HAS_RICH, _print_error,
+                              _get_broker_registry, _list_broker_configs)
+        reg  = _get_broker_registry()
+        cfgs = _list_broker_configs()
+        if not cfgs:
+            await self._prompt_no_broker_action()
+            return None
+        target_id = broker_id or (cfgs[0].get("id", "") if cfgs else "")
+        if not target_id:
+            return None
+        try:
+            import asyncio as _aio
+            return await _aio.get_event_loop().run_in_executor(None, reg.connect, target_id)
+        except Exception as e:
+            _print_error(f"自动连接 {target_id} 失败: {e}",
+                         "请运行 /broker connect <id> 手动连接")
+            return None