akquant 0.2.51__tar.gz → 0.3.2__tar.gz

akquant-0.3.2/.gitignore

@@ -0,0 +1,49 @@
+# ── 构建产物 ──
+target/
+build/
+dist/
+site/
+refs/
+*.egg-info/
+
+# ── Python ──
+__pycache__/
+*.so
+*.dylib
+*.dSYM/
+*.pyd
+*.pdb
+
+# ── 环境 / 依赖 ──
+.env
+.venv
+venv/
+uv.lock
+
+# ── IDE / 编辑器 ──
+.idea/
+.vscode/
+.trae/
+*.swp
+
+# ── 操作系统 ──
+.DS_Store
+
+# ── 日志 ──
+*.log
+*.err
+
+# ── 本地配置 ──
+.cargo/config.toml
+CLAUDE.md
+
+# ── 本地数据 ──
+/data_catalog/
+
+# ── AI 工作流文档（内部，不公开）──
+docs/superpowers
+
+# ── 私有 broker 已拆分为独立包（akquant-qmf / akquant-middleware，独立私有仓）──
+
+# ── 外部前置机/回测服务子项目（vendored，独立仓库，不纳入本仓版本管理）──
+/vendor/

{akquant-0.2.51 → akquant-0.3.2}/CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `BacktestConfig` 新增 `days_per_year`（年化天数因子，默认 252；数字货币 24/7 市场可设 365）与 `risk_free_rate`（年化无风险利率，默认 0.0）两个字段，用于参数化 Sharpe/Sortino/波动率等风险指标的年化口径。`risk_free_rate` 默认 0 不改变任何现有数值。
 
 ### Changed
+- **`buy`/`sell`/`submit_order` 返回类型变更（破坏性）**：三者现统一返回 `OrderReceipt`（原为 `str` 订单号），回测与实盘（`broker_live`）两种模式返回类型一致；实盘 `submit_order` 此前会将多腿委托（如反手拆分的平仓+开仓、开平分离）收窄为单一 id 字符串，现已修复为返回携带全部腿 id 的完整 `OrderReceipt`。取单个订单 id 用 `receipt.primary`（首腿 broker_order_id，兼容旧用法），取全部腿 id 用 `receipt.order_ids`；`str(receipt)` 取 `group_id`（逻辑委托的客户端订单号），关联成交请用 `trade.group_id` 而非逐个 order_id 比对；新增 `cancel_group(group_id)` 用于一次性撤销一个逻辑委托的全部腿。
 - **回测指标口径变更（破坏性）**：Sharpe / Sortino 比率的分子改为「日收益算术均值 × `days_per_year`」做年化，替代原先的 CAGR（复合年化），与 pyfolio/empyrical/quantstats 等主流实现一致，并与分母 `√days_per_year` 的年化口径匹配。升级后历史报告的 Sharpe/Sortino 数值会变化，不可直接与旧版逐值对比；UPI 与 Calmar 仍沿用 CAGR 口径。
 - 策略交易日边界回调已硬切改名：`before_trading(trading_date, timestamp)` 更名为 `on_before_trading(trading_date, timestamp)`，`after_trading(trading_date, timestamp)` 更名为 `on_after_trading(trading_date, timestamp)`。
 - 旧回调名不再保留兼容别名；升级到当前版本后，若策略仍实现 `before_trading` / `after_trading`，将不会再被框架触发，请同步迁移到新名称。

{akquant-0.2.51 → akquant-0.3.2}/Cargo.lock

@@ -30,7 +30,7 @@ dependencies = [
 
 [[package]]
 name = "akquant"
-version = "0.2.51"
+version = "0.3.2"
 dependencies = [
  "anyhow",
  "chrono",
@@ -692,9 +692,9 @@ dependencies = [
 
 [[package]]
 name = "ethnum"
-version = "1.5.2"
+version = "1.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ca81e6b4777c89fd810c25a4be2b1bd93ea034fbe58e6a75216a34c6b82c539b"
+checksum = "40404c3f5f511ec4da6fe866ddf6a717c309fdbb69fbbad7b0f3edab8f2e835f"
 
 [[package]]
 name = "event-listener"

{akquant-0.2.51 → akquant-0.3.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "akquant"
-version = "0.2.51"
+version = "0.3.2"
 edition = "2024"
 description = "High-performance quantitative trading framework based on Rust and Python"
 license = "MIT"

{akquant-0.2.51 → akquant-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akquant
-Version: 0.2.51
+Version: 0.3.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
@@ -222,8 +222,8 @@ min_margin_level                        68.587671
 
 AKQuant 提供了两组复杂订单助手，减少手写订单联动逻辑：
 
-*   `create_oco_order_group(first_order_id, second_order_id, group_id=None)`：将两个订单绑定为 OCO，任一成交后自动撤销另一单。
-*   `place_bracket_order(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...)`：一次性提交 Bracket 结构；进场成交后自动挂出止损/止盈，并在双退出单场景下自动绑定 OCO。
+*   `place_oco(first_order_id, second_order_id, group_id=None)`：将两个订单绑定为 OCO，任一成交后自动撤销另一单。
+*   `place_bracket(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...)`：一次性提交 Bracket 结构；进场成交后自动挂出止损/止盈，并在双退出单场景下自动绑定 OCO。
 
 ```python
 from akquant import OrderStatus, Strategy
@@ -236,7 +236,7 @@ class BracketHelperStrategy(Strategy):
         if self.get_position(bar.symbol) > 0 or self.entry_order_id:
             return
 
-        self.entry_order_id = self.place_bracket_order(
+        self.entry_order_id = self.place_bracket(
             symbol=bar.symbol,
             quantity=100,
             stop_trigger_price=bar.close * 0.98,

{akquant-0.2.51 → akquant-0.3.2}/README.md

@@ -167,8 +167,8 @@ min_margin_level                        68.587671
 
 AKQuant 提供了两组复杂订单助手，减少手写订单联动逻辑：
 
-*   `create_oco_order_group(first_order_id, second_order_id, group_id=None)`：将两个订单绑定为 OCO，任一成交后自动撤销另一单。
-*   `place_bracket_order(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...)`：一次性提交 Bracket 结构；进场成交后自动挂出止损/止盈，并在双退出单场景下自动绑定 OCO。
+*   `place_oco(first_order_id, second_order_id, group_id=None)`：将两个订单绑定为 OCO，任一成交后自动撤销另一单。
+*   `place_bracket(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...)`：一次性提交 Bracket 结构；进场成交后自动挂出止损/止盈，并在双退出单场景下自动绑定 OCO。
 
 ```python
 from akquant import OrderStatus, Strategy
@@ -181,7 +181,7 @@ class BracketHelperStrategy(Strategy):
         if self.get_position(bar.symbol) > 0 or self.entry_order_id:
             return
 
-        self.entry_order_id = self.place_bracket_order(
+        self.entry_order_id = self.place_bracket(
             symbol=bar.symbol,
             quantity=100,
             stop_trigger_price=bar.close * 0.98,

{akquant-0.2.51 → akquant-0.3.2}/docs/en/advanced/live_functional_quickstart.md

@@ -45,7 +45,7 @@ def initialize(ctx):
     ctx.sent = False
 
 def on_bar(ctx, bar):
-    if not ctx.sent and hasattr(ctx, "submit_order"):
+    if not ctx.sent and getattr(ctx, "broker_ready", False):
         ctx.submit_order(
             symbol=bar.symbol,
             side="Buy",
@@ -72,9 +72,11 @@ runner.run(duration="30s", show_progress=False)
 
 ## 4. Common troubleshooting
 
-- `submit_order not injected yet`
-  - Cause: trader gateway binding is not ready.
-  - Fix: guard with `hasattr(ctx, "submit_order")` before placing.
+- `submit_order` not ready yet
+  - Cause: the trader gateway has not finished connecting/logging in.
+  - Fix: guard with `if getattr(ctx, "broker_ready", False):` before placing
+    (readiness is decided by LiveRunner's heartbeat poll; submitting before
+    ready raises a clear error).
 - `duplicate active client_order_id`
   - Cause: reused active client id.
   - Fix: generate a fresh `client_order_id` for each new order.

{akquant-0.2.51 → akquant-0.3.2}/docs/en/advanced/llm.md

@@ -36,11 +36,11 @@ Your task is to write trading strategies or backtest scripts based on user requi
         *   `self.order_target_percent(target, symbol)`: Adjust position to target percentage.
         *   `self.order_target_value(target, symbol)`: Adjust position to target value.
     *   **Position**: `self.get_position(symbol)` returns current holding (float). `self.position.entry_price` or `self.ctx.get_position_entry_price(symbol)` returns runtime average entry price.
-    *   **Account**: `self.ctx.cash`, `self.get_portfolio_value()`, `self.get_account()`.
+    *   **Account**: `self.ctx.cash`, `self.equity`, `self.get_account()`.
 
 4.  **Indicators**:
     *   Prefer using `akquant.indicators` (e.g., `SMA`, `RSI`).
-    *   Register in `__init__` or `on_start`: `self.sma = SMA(20); self.register_indicator("sma", self.sma)`.
+    *   Register in `__init__` or `on_start`: `self.sma = SMA(20); self.register_precomputed_indicator("sma", self.sma)`.
     *   Access value via `self.sma.value`.
 
 5.  **Backtest Execution**:

{akquant-0.2.51 → akquant-0.3.2}/docs/en/advanced/warm_start.md

@@ -94,7 +94,7 @@ def on_start(self):
     else:
         self.log("Resumed from snapshot. Indicators retained.")
 
-    self.register_indicator("sma", self.sma)
+    self.register_precomputed_indicator("sma", self.sma)
     self.subscribe(self.symbol)
 ```
 
@@ -122,7 +122,7 @@ class MyStrategy(Strategy):
     def on_start(self):
         if not self.is_restored:
             self.sma = SMA(10)
-        self.register_indicator("sma", self.sma)
+        self.register_precomputed_indicator("sma", self.sma)
 
 # ... run phase 1 ...
 save_snapshot(engine, strategy, "checkpoint.pkl")

{akquant-0.2.51 → akquant-0.3.2}/docs/en/guide/examples.md

@@ -479,7 +479,7 @@ The `examples/` directory contains more scripts demonstrating AKShare integratio
     *   Prints `bundle.metadata` to confirm the custom broker is resolved by factory.
 
 *   **[43_target_weights_rebalance.py](https://github.com/akfamily/akquant/blob/main/examples/43_target_weights_rebalance.py)**:
-    *   Demonstrates TopN dynamic weights: rank symbols by momentum, select winners, then rebalance with `order_target_weights`.
+    *   Demonstrates TopN dynamic weights: rank symbols by momentum, select winners, then rebalance with `rebalance_weights`.
     *   Shows practical usage of `liquidate_unmentioned` and `rebalance_tolerance`, then prints `selected_history` / `final_positions` / `final_equity`.
 
 *   **[46_broker_profile_demo.py](https://github.com/akfamily/akquant/blob/main/examples/46_broker_profile_demo.py)**:

{akquant-0.2.51 → akquant-0.3.2}/docs/en/guide/strategy.md

@@ -81,7 +81,7 @@ Notes:
 * `on_reject` is emitted once per order id when the order first becomes `Rejected`.
 * `on_pre_open` is emitted once per trading day before the first regular bar/tick callback of that day.
 * `on_before_trading` is emitted once per local trading date when the regular trading session starts; on the default backtest path this session is usually exposed as `Continuous`.
-* `on_before_trading` / `on_daily_rebalance` always use a "previous trading day / previous snapshot only" visibility model; inside these callbacks, `get_history()`, `get_account()`, and `get_portfolio_value()` must not expose the current day's new bar or the current day's updated account view.
+* `on_before_trading` / `on_daily_rebalance` always use a "previous trading day / previous snapshot only" visibility model; inside these callbacks, `get_history()`, `get_account()`, and `equity` must not expose the current day's new bar or the current day's updated account view.
 * `on_daily_rebalance_after_bar` runs after the framework has seen the first complete cross-symbol slice for the trading day; inside this callback, current-day history and the current account snapshot are visible.
 * `on_after_trading` is emitted once per local trading date when leaving the regular trading session, or on the next event if day rollover occurs first.
 * Inside `on_pre_open`, plain `buy/sell/order_target_*` calls automatically resolve to `price_basis=open, bar_offset=1, temporal=same_cycle` unless an explicit `fill_policy` is provided.
@@ -531,7 +531,7 @@ In AKQuant, order status transitions are as follows:
     Converts to a market order when the market price touches the trigger price (`trigger_price`).
     ```python
     # Stop Sell (Market) when price drops below 140
-    self.stop_sell(symbol="AAPL", quantity=100, trigger_price=140.0)
+    self.sell(symbol="AAPL", quantity=100, trigger_price=140.0)
     ```
 *   **Target Orders**:
     Automatically calculates buy/sell quantities to adjust the position to a target value.
@@ -544,7 +544,7 @@ In AKQuant, order status transitions are as follows:
     ```
     Rebalance multiple symbols with a single target-weight call:
     ```python
-    self.order_target_weights(
+    self.rebalance_weights(
         target_weights={"AAPL": 0.4, "MSFT": 0.3, "GOOGL": 0.2},
         liquidate_unmentioned=True,
         rebalance_tolerance=0.01,
@@ -769,7 +769,7 @@ Notes:
 
 - Opening a futures position does not deduct full notional from cash the way a spot buy does.
 - For futures, use `equity` for net account value, `used_margin` for margin usage, and `notional_value` for leverage exposure.
-- If you only need one "current total equity" number, prefer `get_portfolio_value()`, which is aligned with `get_account()["equity"]`.
+- If you only need one "current total equity" number, prefer `equity`, which is aligned with `get_account()["equity"]`.
 
 ## 6. Using High-Performance Indicators {: #indicatorset }
 
@@ -914,10 +914,10 @@ class IntradayStrategy(Strategy):
 
 AKQuant provides helper APIs for linked order management:
 
-*   `self.create_oco_order_group(first_order_id, second_order_id, group_id=None)`
+*   `self.place_oco(first_order_id, second_order_id, group_id=None)`
     *   Binds two orders as OCO (One-Cancels-the-Other).
     *   Once either order is filled, the peer order is canceled automatically.
-*   `self.place_bracket_order(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...)`
+*   `self.place_bracket(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...)`
     *   Submits a bracket structure in one call.
     *   After entry fill, stop-loss and take-profit exits are submitted automatically; when both exits exist, they are linked as OCO.
 
@@ -932,7 +932,7 @@ class BracketHelperStrategy(Strategy):
         if self.get_position(bar.symbol) > 0 or self.entry_order_id:
             return
 
-        self.entry_order_id = self.place_bracket_order(
+        self.entry_order_id = self.place_bracket(
             symbol=bar.symbol,
             quantity=100,
             stop_trigger_price=bar.close * 0.98,

{akquant-0.2.51 → akquant-0.3.2}/docs/en/reference/api.md

@@ -832,19 +832,20 @@ Note: if you do not pass an explicit `fill_policy` here, the framework defaults
 *   `self.position`: Position object for current symbol, with `size` and `available` properties.
 *   `self.now`: Current backtest time (`pd.Timestamp`).
 *   `self.runtime_config`: Runtime behavior config object (`StrategyRuntimeConfig`).
-*   `self.enable_precise_day_boundary_hooks`: Enable boundary timer based precise day hooks (default `False`). This switch changes trigger precision only; it does not change the visibility window of `get_history()`, `get_account()`, or `get_portfolio_value()` inside `on_before_trading` / `on_daily_rebalance`.
+*   `self.enable_precise_day_boundary_hooks`: Enable boundary timer based precise day hooks (default `False`). This switch changes trigger precision only; it does not change the visibility window of `get_history()`, `get_account()`, or `equity` inside `on_before_trading` / `on_daily_rebalance`.
 *   `self.portfolio_update_eps`: Snapshot threshold; changes below it skip `on_portfolio_update` (default `0.0`).
 *   `self.error_mode`: Error handling mode, `"raise"` or `"continue"` (default `"raise"`).
 *   `self.re_raise_on_error`: Whether to re-raise user callback exception after `on_error` (default `True`).
 
 **Trading Methods:**
 
-*   `buy(symbol, quantity, price=None, ...)`: Buy. Market order if `price` is not specified.
-*   `sell(symbol, quantity, price=None, ...)`: Sell.
+*   `buy(symbol, quantity, price=None, trigger_price=None, ...)`: Buy (open long / close short).
+    *   Market order if `price` is not specified.
+    *   Limit order if `price` is specified.
+    *   Stop order (Stop Market) if `trigger_price` is specified.
+*   `sell(symbol, quantity, price=None, trigger_price=None, ...)`: Sell (close long / open short). Same parameters as above.
 *   `short(symbol, quantity, price=None, ...)`: Short sell.
 *   `cover(symbol, quantity, price=None, ...)`: Buy to cover.
-*   `stop_buy(symbol, trigger_price, quantity, ...)`: Stop buy (Stop Market). Triggers a market buy order when price breaks above `trigger_price`.
-*   `stop_sell(symbol, trigger_price, quantity, ...)`: Stop sell (Stop Market). Triggers a market sell order when price drops below `trigger_price`.
 *   `submit_order(..., order_type="StopTrail", trail_offset=..., trail_reference_price=None)`: Submit a trailing stop order. `trail_offset` must be greater than 0.
 *   `submit_order(..., order_type="StopTrailLimit", price=..., trail_offset=..., trail_reference_price=None)`: Submit a trailing stop-limit order. `price` and `trail_offset` are required.
 *   `submit_order(..., broker_options={...})`: Optional broker extension fields passthrough (backtest currently records them on `order.broker_options` for debugging/audit).
@@ -852,7 +853,7 @@ Note: if you do not pass an explicit `fill_policy` here, the framework defaults
 *   `place_trailing_stop_limit(symbol, quantity, price, trail_offset, side="Sell", trail_reference_price=None, ...) -> str`: Helper for trailing stop-limit orders, promoted to limit order when triggered.
 *   `order_target_value(target_value, symbol, price=None)`: Adjust position to target value.
 *   `order_target_percent(target_percent, symbol, price=None)`: Adjust position to target account percentage.
-*   `order_target_weights(target_weights, price_map=None, liquidate_unmentioned=False, allow_leverage=False, rebalance_tolerance=0.0, ...)`: Rebalance a multi-asset portfolio by target weights.
+*   `rebalance_weights(target_weights, price_map=None, liquidate_unmentioned=False, allow_leverage=False, rebalance_tolerance=0.0, ...)`: Rebalance a multi-asset portfolio by target weights.
     *   `target_weights` is `{symbol: weight}` and by default requires total weight `<= 1.0`.
     *   `liquidate_unmentioned=True` sets all existing non-mentioned positions to target `0`.
     *   Orders are submitted in sell-first then buy-second order to reduce cash-lock conflicts.
@@ -860,8 +861,8 @@ Note: if you do not pass an explicit `fill_policy` here, the framework defaults
 *   `close_position(symbol)`: Close position for a specific instrument.
 *   `cancel_order(order_id: str)`: Cancel a specific order.
 *   `cancel_all_orders(symbol)`: Cancel all pending orders for a specific instrument. If `symbol` is omitted, cancels all orders.
-*   `create_oco_order_group(first_order_id, second_order_id, group_id=None) -> str`: Create an OCO order group. Once one order is filled, the peer order is canceled automatically.
-*   `place_bracket_order(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...) -> str`: Create a bracket order. The entry order is submitted first, then stop-loss/take-profit exits are submitted after entry fill; if both exits exist, they are linked as OCO automatically.
+*   `place_oco(first_order_id, second_order_id, group_id=None) -> str`: Create an OCO order group. Once one order is filled, the peer order is canceled automatically.
+*   `place_bracket(symbol, quantity, entry_price=None, stop_trigger_price=None, take_profit_price=None, ...) -> str`: Create a bracket order. The entry order is submitted first, then stop-loss/take-profit exits are submitted after entry fill; if both exits exist, they are linked as OCO automatically.
 
 **Data & Utilities:**
 
@@ -869,17 +870,17 @@ Note: if you do not pass an explicit `fill_policy` here, the framework defaults
 *   `get_history_df(count, symbol) -> pd.DataFrame`: Get history data DataFrame (OHLCV).
 *   `get_position(symbol) -> float`: Get current position size. This still returns a numeric quantity, not an object.
 *   `get_available_position(symbol) -> float`: Get available position size.
-*   `get_positions() -> Dict[str, float]`: Get all positions by symbol.
+*   `positions -> Dict[str, float]`: Get all positions by symbol (read-only property).
 *   `self.position.entry_price -> float`: Get the current symbol's average entry price via the `Position` helper.
 *   `self.position.avg_price -> float`: Alias of `entry_price`.
 *   `ctx.get_position_entry_price(symbol) -> float`: Get the current average entry price for one symbol.
 *   `ctx.get_position_entry_prices() -> Dict[str, float]`: Get current average entry prices for all symbols.
-*   `get_cash() -> float`: Get current available cash.
+*   `cash -> float`: Get current available cash (read-only property).
 *   `get_account() -> Dict[str, float]`: Get an account snapshot. Common fields include `cash`, `equity`, `market_value`, `notional_value`, `frozen_cash`, `margin`, `used_margin`, `free_margin`, `unrealized_pnl`, `borrowed_cash`, `short_market_value`, `maintenance_ratio`, `account_mode`, `accrued_interest`, and `daily_interest`.
     *   In cash / spot-style accounts, `market_value` usually represents marked position value.
     *   In futures margin accounts, `equity` is account equity, `used_margin` is margin in use, `notional_value` is futures notional exposure, and `unrealized_pnl` is marked floating PnL. Futures trades do not deduct full notional from `cash` the way spot buys do, and notional exposure is not mirrored into `market_value` as if it were spot inventory.
     *   `cash` is the cash balance; `free_margin` (= `equity - used_margin`) is the amount actually available to open new positions and matches the `Available` value shown in the rejection log when an order is rejected. In futures margin accounts, opening a position does not deduct margin from `cash`, so `cash` is usually larger than `free_margin`; in stock cash accounts the two are equal.
-    *   Inside strategy callbacks, prefer `get_portfolio_value()` when you only need current total equity; it is aligned with `get_account()["equity"]`.
+    *   Inside strategy callbacks, prefer `equity` when you only need current total equity; it is aligned with `get_account()["equity"]`.
 *   `get_order(order_id) -> Order`: Get details of a specific order.
 *   `get_open_orders(symbol) -> List[Order]`: Get list of open orders.
 *   `subscribe(instrument_id: str)`: Subscribe to market data. Must be called explicitly for multi-asset backtesting or live trading to receive `on_tick`/`on_bar` callbacks.

{akquant-0.2.51 → akquant-0.3.2}/docs/en/start/quickstart.md

@@ -367,7 +367,7 @@ result = run_backtest(data=df, strategy=MetaQuickStrategy, config=config)
 
 ## Complex Orders in 30 Seconds
 
-If you need an entry + stop-loss + take-profit flow with automatic OCO linkage, use `place_bracket_order` directly:
+If you need an entry + stop-loss + take-profit flow with automatic OCO linkage, use `place_bracket` directly:
 
 ```python
 from akquant import OrderStatus, Strategy
@@ -379,7 +379,7 @@ class BracketQuickStrategy(Strategy):
     def on_bar(self, bar):
         if self.get_position(bar.symbol) > 0 or self.entry_order_id:
             return
-        self.entry_order_id = self.place_bracket_order(
+        self.entry_order_id = self.place_bracket(
             symbol=bar.symbol,
             quantity=100,
             stop_trigger_price=bar.close * 0.98,

{akquant-0.2.51 → akquant-0.3.2}/docs/en/textbook/07_futures.md

@@ -51,11 +51,11 @@ Low-level Engine API naming:
 ## Futures Margin Account Snapshot Semantics
 
 Under AKQuant's futures margin-account semantics, read `get_account()` and
-`get_portfolio_value()` like this:
+`equity` like this:
 
 - `cash`: cash balance. Opening a futures position does not deduct full notional
   the way a spot buy does; cash mainly reflects fees and realized cash flows.
-- `equity`: account equity. `get_portfolio_value()` is aligned with this field.
+- `equity`: account equity. This is the `equity` property.
 - `used_margin` / `margin`: margin currently in use.
 - `free_margin`: available margin (`equity - used_margin`), i.e. the amount
   actually usable to open new positions. When an order is rejected for

akquant-0.3.2/docs/zh/advanced/adding_a_broker.md

@@ -0,0 +1,245 @@
+# 如何新增一个 Broker
+
+本页说明 akquant broker 网关层的插件契约：新增一个 broker 需要实现哪些接口、
+声明哪些能力、以及如何把下单请求路由到具体柜台。目标是让接入者不修改
+`akquant.gateway` 核心代码即可插入一个新的交易通道。
+
+如果只是想在不改内置工厂分支的前提下注册一个 broker，先看
+[自定义 Broker 注册](custom_broker_registry.md)；本页补充的是"网关本身怎么写"。
+
+## 总览：五步契约
+
+1. 写 **builder** 函数，通过 `register_broker(name, builder)` 注册（或者内置
+   broker 直接放进 `python/akquant/gateway/brokers/builtins.py`，由
+   `register_builtin_brokers()` 统一注册）。
+2. 声明 **`BrokerCapability`**：`broker_extra_fields` 列出本 broker 允许的
+   订单专属字段，`features` 声明任意能力标志。
+3. 继承 **`TraderGatewayBase`** 实现必需方法。
+4. 在 `place_order` 里按 `req.asset_type` 路由品种、从 `req.extra` 取专属
+   字段，并维护 broker 订单号与 `client_order_id` 的映射。
+5. 纯交易 broker（不接行情）令 `GatewayBundle(market_gateway=None, ...)`，
+   行情继续走 akquant 现有 `DataFeed`。
+
+## 1. Builder：注册入口
+
+Builder 是一个可调用对象，签名固定为：
+
+```python
+def builder(
+    feed: DataFeed,
+    symbols: Sequence[str],
+    use_aggregator: bool,
+    **kwargs: Any,
+) -> GatewayBundle:
+    ...
+```
+
+- 第三方/内部 broker：调用 `register_broker(name, builder)`（来自
+  `akquant.gateway`），注册后 `create_gateway_bundle(broker=name, ...)` 会
+  优先解析到它。
+- 想合并进内置分支的 broker：把 builder 函数加进
+  `python/akquant/gateway/brokers/builtins.py`，并在
+  `register_builtin_brokers()` 里追加一行 `register_broker("xxx", _build_xxx)`。
+
+Builder 内部通常做三件事：校验必填 `kwargs`、构造 `TraderGateway`（以及可选的
+`MarketGateway`）、把 `trader_gateway.get_capabilities()` 的结果写入
+`GatewayBundle.trader_capabilities`，供上层校验 `extra` 字段用。
+
+## 2. 声明 `BrokerCapability`
+
+`BrokerCapability`（`from akquant.gateway.broker_models import BrokerCapability`）
+是一个 frozen dataclass，描述这个 broker 的执行语义边界：
+
+- `broker_extra_fields: tuple[str, ...]`：策略下单时通过
+  `submit_order(..., extra={...})` 传入的柜台专属字段，必须在这里声明；
+  未声明的 key 会在校验时被拒绝（`validate_broker_extra` 会抛
+  `RuntimeError`，列出未声明字段与已声明集合）。
+- `features: frozenset[str]`：任意能力标志的开放集合，用于策略侧按需探测
+  "这个 broker 支不支持某个特性"，不做强类型约束。
+- 其余字段（`position_effect`、`reduce_only`、`supports_short_sell`、
+  `supported_position_effects` 等）描述开平仓/做空等语义是否可用，按 broker
+  实际能力如实填写即可，不确定的保持默认值（保守）。
+
+`TraderGateway` 协议要求实现 `get_capabilities() -> BrokerCapability`，
+通常返回一个模块级的 `default_capability()` 单例：
+
+```python
+def default_capability() -> BrokerCapability:
+    return BrokerCapability(
+        broker_name="mybroker",
+        broker_extra_fields=("account_id", "order_style"),
+        features=frozenset({"supports_stop_limit"}),
+    )
+```
+
+## 3. 继承 `TraderGatewayBase`
+
+`from akquant.gateway.trader_base import TraderGatewayBase` 提供了所有
+broker 共享的管件：回调注册、id 反查表、以及默认的
+`heartbeat`/`sync_open_orders`/`sync_today_trades` 实现。子类只需要实现
+`TraderGateway` 协议中还缺的部分：
+
+必须实现：
+
+- `connect()` / `disconnect()` / `start()` —— 生命周期
+- `place_order(req) -> str` / `cancel_order(broker_order_id)`
+- `query_order(broker_order_id)` / `query_trades(since=None)`
+- `query_account()` / `query_positions()`
+- `get_capabilities() -> BrokerCapability`
+
+基类已提供、通常不需要重写：
+
+- 回调注册：`on_order` / `on_trade` / `on_execution_report`
+- id 反查：`record_broker_order(broker_order_id, client_order_id)` /
+  `client_order_id_for(broker_order_id)`
+- 分发：`_emit_order` / `_emit_trade` / `_emit_exec_from_order`
+- 默认实现：`heartbeat()`（恒真）、`sync_open_orders()` /
+  `sync_today_trades()`（空列表）—— 如果 broker 支持断线补齐，覆盖这两个
+  方法即可。
+
+## 4. `place_order` 里的路由与 id 映射
+
+`UnifiedOrderRequest` 里的 `asset_type` 用来在 `place_order` 内部路由到不同
+品种的下单通道（例如证券 vs 期货）；`extra: dict[str, Any]` 携带的是
+`BrokerCapability.broker_extra_fields` 里声明过的柜台专属字段，直接从
+`req.extra` 取值即可（上层已按声明集合校验过，未声明的 key 不会出现）。
+
+下单成功后，用 `self.record_broker_order(broker_order_id, req.client_order_id)`
+记录柜台委托号到策略 `client_order_id` 的映射；收到委托/成交回报时，用
+`self.client_order_id_for(broker_order_id)` 反查回 `client_order_id`，再拼成
+统一模型对象经 `self._emit_order(...)` / `self._emit_trade(...)` /
+`self._emit_exec_from_order(...)` 分发给策略层回调。
+
+## 5. 纯交易 broker：行情走现有 feed
+
+如果新 broker 只做交易、不提供行情（多数国内前置机/柜台都是这种情况），
+builder 返回的 `GatewayBundle` 里 `market_gateway=None` 即可，行情继续由
+akquant 现有的 `DataFeed` 提供：
+
+```python
+return GatewayBundle(
+    market_gateway=None,
+    trader_gateway=trader_gateway,
+    trader_capabilities=trader_gateway.get_capabilities(),
+    metadata={"broker": "mybroker"},
+)
+```
+
+## 最小骨架
+
+```python
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from akquant import DataFeed
+from akquant.gateway import register_broker
+from akquant.gateway.broker_models import (
+    BrokerCapability,
+    UnifiedAccount,
+    UnifiedOrderRequest,
+    UnifiedOrderSnapshot,
+    UnifiedPosition,
+    UnifiedTrade,
+)
+from akquant.gateway.protocols import GatewayBundle
+from akquant.gateway.trader_base import TraderGatewayBase
+
+
+def default_capability() -> BrokerCapability:
+    return BrokerCapability(
+        broker_name="mybroker",
+        broker_extra_fields=("account_id",),
+        features=frozenset(),
+    )
+
+
+class MyTraderGateway(TraderGatewayBase):
+    """最小可运行的 TraderGateway 骨架。"""
+
+    def __init__(self, capability: BrokerCapability | None = None) -> None:
+        super().__init__()
+        self._capability = capability or default_capability()
+
+    def connect(self) -> None:
+        ...  # 登录/建立会话
+
+    def disconnect(self) -> None:
+        ...  # 释放连接
+
+    def start(self) -> None:
+        ...  # 建立推送长连、开始分发回报
+
+    def get_capabilities(self) -> BrokerCapability:
+        return self._capability
+
+    def place_order(self, req: UnifiedOrderRequest) -> str:
+        # 按 req.asset_type 路由品种；req.extra 取柜台专属字段。
+        account_id = req.extra.get("account_id")
+        broker_order_id = self._send_order_to_broker(req, account_id)
+        if broker_order_id:
+            self.record_broker_order(broker_order_id, req.client_order_id)
+        return broker_order_id
+
+    def cancel_order(self, broker_order_id: str) -> None:
+        ...  # 调用柜台撤单接口
+
+    def query_order(self, broker_order_id: str) -> UnifiedOrderSnapshot | None:
+        ...  # 查询单笔委托并转换为 UnifiedOrderSnapshot
+
+    def query_trades(self, since: int | None = None) -> list[UnifiedTrade]:
+        ...  # 查询成交并转换为 UnifiedTrade 列表
+
+    def query_account(self) -> UnifiedAccount | None:
+        ...  # 查询资金账户
+
+    def query_positions(self) -> list[UnifiedPosition]:
+        ...  # 查询持仓
+
+    def _on_broker_push(self, event: str, data: dict[str, Any]) -> None:
+        # 收到推送后：反查 client_order_id，再分发给策略层回调。
+        broker_order_id = str(data.get("order_id", ""))
+        client_order_id = self.client_order_id_for(broker_order_id)
+        if event == "order_update":
+            snapshot = self._parse_order(data, client_order_id)
+            self._emit_order(snapshot)
+            self._emit_exec_from_order(snapshot)
+        elif event == "trade_update":
+            self._emit_trade(self._parse_trade(data, client_order_id))
+
+    def _send_order_to_broker(
+        self, req: UnifiedOrderRequest, account_id: Any
+    ) -> str:
+        raise NotImplementedError
+
+    def _parse_order(
+        self, data: dict[str, Any], client_order_id: str
+    ) -> UnifiedOrderSnapshot:
+        raise NotImplementedError
+
+    def _parse_trade(self, data: dict[str, Any], client_order_id: str) -> UnifiedTrade:
+        raise NotImplementedError
+
+
+def build_mybroker(
+    feed: DataFeed, symbols: Sequence[str], use_aggregator: bool, **kwargs: Any
+) -> GatewayBundle:
+    _ = (feed, symbols, use_aggregator)
+    trader_gateway = MyTraderGateway()
+    return GatewayBundle(
+        market_gateway=None,  # 纯交易 broker：行情走 akquant 现有 feed
+        trader_gateway=trader_gateway,
+        trader_capabilities=trader_gateway.get_capabilities(),
+        metadata={"broker": "mybroker"},
+    )
+
+
+register_broker("mybroker", build_mybroker)
+```
+
+## 参考实现与相关文档
+
+- [自定义 Broker 注册](custom_broker_registry.md) —— `register_broker` /
+  `create_gateway_bundle` 等注册 API 的详细说明。
+- [Broker Capability Matrix](broker_capability_matrix.md) —— 各内置 broker
+  的能力矩阵与统一错误规范，声明 `BrokerCapability` 前建议先对照。

{akquant-0.2.51 → akquant-0.3.2}/docs/zh/advanced/live_functional_quickstart.md

@@ -45,7 +45,7 @@ def initialize(ctx):
     ctx.sent = False
 
 def on_bar(ctx, bar):
-    if not ctx.sent and hasattr(ctx, "submit_order"):
+    if not ctx.sent and getattr(ctx, "broker_ready", False):
         ctx.submit_order(
             symbol=bar.symbol,
             side="Buy",
@@ -72,9 +72,10 @@ runner.run(duration="30s", show_progress=False)
 
 ## 4. 常见排查
 
-- `submit_order 尚未注入`
-  - 原因：网关尚未完成交易侧绑定。
-  - 处理：在 `on_bar` 中 `hasattr(ctx, "submit_order")` 判定后再下单。
+- `submit_order` 尚未就绪
+  - 原因：交易网关尚未完成连接/登录。
+  - 处理：在 `on_bar` 中用 `if getattr(ctx, "broker_ready", False):` 门首单
+    （broker 就绪由 LiveRunner 的 heartbeat 轮询裁定；就绪前调用会抛清晰错误）。
 - `duplicate active client_order_id`
   - 原因：重复提交活跃 client id。
   - 处理：每次下单生成新的 `client_order_id`。