aria-code 4.1.3__py3-none-any.whl

brokers/base.py

@@ -0,0 +1,207 @@
+"""
+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
+
+    # ── 账户查询 ──────────────────────────────────────────────────────────────
+
+    @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}>"

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)

brokers/cn/__init__.py

@@ -0,0 +1,10 @@
+from .xtquant_broker   import XTQuantBroker
+from .easytrader_broker import EasyTraderBroker
+from .futu_broker       import FutuBroker
+from .tiger_broker      import TigerBroker
+from .longbridge_broker import LongbridgeBroker
+
+__all__ = [
+    "XTQuantBroker", "EasyTraderBroker",
+    "FutuBroker", "TigerBroker", "LongbridgeBroker",
+]

brokers/cn/easytrader_broker.py

@@ -0,0 +1,193 @@
+"""
+brokers/cn/easytrader_broker.py — EasyTrader 适配器
+=====================================================
+支持券商（通过客户端界面自动化）：
+    同花顺(ths)、通达信(tdx)、华泰(huatai)、国泰君安(guojun)、
+    银河证券(yh)、平安证券(pa)、招商证券(zszq)、雪球模拟(xq)
+
+安装：pip install easytrader
+文档：https://github.com/shidenggui/easytrader
+
+配置示例::
+
+    {
+      "id":           "ht_main",
+      "type":         "easytrader",
+      "label":        "华泰账户",
+      "broker_name":  "huatai",
+      "exe_path":     "C:\\华泰证券\\xiadan.exe",
+      "comm_password": "可选"
+    }
+
+注意：EasyTrader 通过操控客户端窗口，仅支持 Windows。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ..base import BrokerBase, AccountInfo, Position, Order, OrderResult
+
+
+class EasyTraderBroker(BrokerBase):
+    broker_type = "easytrader"
+    broker_name = "EasyTrader"
+    market      = "CN"
+
+    _BROKER_NAMES = {
+        "huatai": "华泰证券",
+        "guojun": "国泰君安",
+        "ths":    "同花顺",
+        "tdx":    "通达信",
+        "yh":     "银河证券",
+        "zszq":   "招商证券",
+        "xq":     "雪球模拟",
+    }
+
+    def __init__(self, broker_id: str, config: Dict[str, Any]):
+        super().__init__(broker_id, config)
+        self._broker_name  = config.get("broker_name", "ths")
+        self._exe_path     = config.get("exe_path", "")
+        self._comm_pwd     = config.get("comm_password", "")
+        self._client       = None
+        self.broker_name   = self._BROKER_NAMES.get(self._broker_name, self._broker_name)
+
+    def connect(self) -> bool:
+        try:
+            import easytrader
+        except ImportError:
+            raise ImportError("easytrader 未安装。请运行: pip install easytrader")
+
+        import sys
+        if sys.platform != "win32":
+            raise RuntimeError("EasyTrader 仅支持 Windows 系统")
+
+        try:
+            client = easytrader.use(self._broker_name)
+            if self._exe_path:
+                client.prepare(self._exe_path, comm_password=self._comm_pwd or None)
+            else:
+                client.prepare(comm_password=self._comm_pwd or None)
+            self._client    = client
+            self._connected = True
+            return True
+        except Exception as e:
+            raise RuntimeError(f"EasyTrader 连接失败: {e}") from e
+
+    def account_info(self) -> AccountInfo:
+        self._require_connected()
+        try:
+            bal = self._client.balance
+            total = float(bal.get("总资产", bal.get("资产", 0)))
+            cash  = float(bal.get("可用金额", bal.get("可用资金", 0)))
+            mv    = float(bal.get("证券市值", 0))
+            frozen= float(bal.get("冻结金额", 0))
+            pnl   = float(bal.get("盈亏金额", bal.get("参考盈亏", 0)))
+        except Exception as e:
+            raise RuntimeError(f"EasyTrader 账户资金查询失败: {e}") from e
+
+        return AccountInfo(
+            broker_id=self.broker_id,
+            broker_type=self.broker_type,
+            label=self.label,
+            account_id=self.config.get("account_id", ""),
+            currency="CNY",
+            total_assets=total,
+            cash=cash,
+            market_value=mv,
+            frozen=frozen,
+            pnl_today=pnl,
+        )
+
+    def positions(self) -> List[Position]:
+        self._require_connected()
+        try:
+            raw = self._client.position
+        except Exception as e:
+            raise RuntimeError(f"EasyTrader 持仓查询失败: {e}") from e
+
+        result = []
+        for row in (raw or []):
+            sym   = str(row.get("证券代码", row.get("股票代码", "")))
+            name  = str(row.get("证券名称", row.get("股票名称", "")))
+            qty   = float(row.get("持仓数量", row.get("持股数量", 0)))
+            avail = float(row.get("可用数量", row.get("可卖数量", 0)))
+            cost  = float(row.get("成本价",   row.get("持仓成本", 0)))
+            price = float(row.get("当前价",   row.get("最新价",   0)))
+            mv    = float(row.get("证券市值", row.get("参考市值",  0)))
+            pnl   = float(row.get("盈亏金额", row.get("参考盈亏",  0)))
+            pnl_pct = float(row.get("盈亏比例(%)", 0))
+            result.append(Position(
+                symbol=sym, name=name,
+                quantity=qty, available_qty=avail,
+                cost_price=cost, current_price=price,
+                market_value=mv, pnl=pnl, pnl_pct=pnl_pct,
+                currency="CNY", market="a_share",
+            ))
+        return result
+
+    def orders(self, status: str = "all", limit: int = 50) -> List[Order]:
+        self._require_connected()
+        try:
+            raw = self._client.today_entrusts
+        except Exception as e:
+            raise RuntimeError(f"EasyTrader 订单查询失败: {e}") from e
+
+        result = []
+        for row in (raw or [])[:limit]:
+            op = str(row.get("操作", ""))
+            side   = "buy" if "买" in op else "sell"
+            raw_st = str(row.get("状态",  row.get("委托状态", "")))
+            mapped = _easy_order_status(raw_st)
+            if status != "all" and mapped != status:
+                continue
+            result.append(Order(
+                order_id=str(row.get("委托编号", row.get("合同编号", ""))),
+                symbol=str(row.get("证券代码", "")),
+                name=str(row.get("证券名称", "")),
+                side=side,
+                order_type="limit",
+                quantity=float(row.get("委托数量", 0)),
+                filled_qty=float(row.get("成交数量", 0)),
+                price=float(row.get("委托价格", row.get("委托价",0))),
+                avg_price=float(row.get("成交均价", row.get("成交价",0))),
+                status=mapped,
+                created_at=str(row.get("委托时间", "")),
+                currency="CNY",
+            ))
+        return result
+
+    def place_order(self, symbol: str, side: str, quantity: float,
+                    order_type: str = "limit", price: float = 0.0, **kwargs) -> OrderResult:
+        self._require_connected()
+        try:
+            if side == "buy":
+                result = self._client.buy(security=symbol, price=price, amount=int(quantity))
+            else:
+                result = self._client.sell(security=symbol, price=price, amount=int(quantity))
+            oid = str(result.get("entrust_no", result.get("委托编号", "")))
+            return OrderResult(success=True, order_id=oid, broker_id=self.broker_id)
+        except Exception as e:
+            return OrderResult(success=False, message=str(e), broker_id=self.broker_id)
+
+    def cancel_order(self, order_id: str) -> bool:
+        self._require_connected()
+        try:
+            self._client.cancel_entrust(order_id)
+            return True
+        except Exception:
+            return False
+
+    def _require_connected(self):
+        if not self._connected or not self._client:
+            raise RuntimeError("EasyTrader 未连接，请先调用 connect()")
+
+
+def _easy_order_status(raw: str) -> str:
+    if any(x in raw for x in ("已成", "全部成交")):
+        return "filled"
+    if any(x in raw for x in ("部分成交",)):
+        return "partial"
+    if any(x in raw for x in ("已撤", "撤单", "废单")):
+        return "cancelled"
+    return "open"