powerquant-cli 0.2.6__py3-none-any.whl

quant_cli/app/research/service/local_research_service.py

@@ -0,0 +1,101 @@
+"""本地研究检验与比较，因子值只引用，不在研究表重复保存。"""
+
+import logging
+from dataclasses import asdict
+from typing import Protocol
+from uuid import UUID
+
+from quant_core.app.factor.interface.public.factor_diagnostics import IFactorDiagnostics
+from quant_core.app.factor.interface.public.factor_local import LocalFactorStore
+from quant_core.app.factor.schema.diagnostic_types import CrossSection
+from quant_core.common.local_run import LocalRunRecord, RunStatus, json_value
+
+from quant_cli.app.factor.local_factor_dependency import load_factor_result
+from quant_cli.app.research.schema.local_research_schema import LocalEvaluationRequest
+from quant_cli.common.utils.runtime_environment import runtime_versions
+
+
+class LocalResearchStore(Protocol):
+    def save(self, record: LocalRunRecord) -> None: ...
+    def get(self, run_uuid: UUID) -> LocalRunRecord: ...
+
+
+def evaluate_local_factor(
+    request: LocalEvaluationRequest, factor_store: LocalFactorStore, diagnostics: IFactorDiagnostics
+) -> LocalRunRecord:
+    """只接受显式未来标签，不把标签传回因子或策略输入。"""
+    record = LocalRunRecord(
+        request=request.model_dump(mode="json"), provenance={"environment": runtime_versions()}
+    )
+    try:
+        factor_run, result = load_factor_result(factor_store, request.factor_run_uuid)
+        values = result.get(request.factor_name)
+        if values is None:
+            raise ValueError("因子名称不属于指定运行")
+        revision = factor_run.provenance.get("market_revision")
+        if not revision or any(label.data_revision != revision for label in request.labels):
+            raise ValueError("研究标签与因子必须使用同一明确的行情修订")
+        seen = set()
+        grouped: dict = {}
+        for label in request.labels:
+            key = (label.decision_time, label.instrument_id)
+            if key in seen or key not in values:
+                raise ValueError("标签重复或不属于指定因子的计算样本")
+            seen.add(key)
+            scores, returns = grouped.setdefault(label.decision_time, ({}, {}))
+            value = values[key]
+            if value is not None and label.value is not None:
+                scores[label.instrument_id] = value
+                returns[label.instrument_id] = label.value
+        if not grouped or not any(scores for scores, _ in grouped.values()):
+            raise ValueError("没有可检验的因子与标签配对")
+        report = diagnostics.analyze(
+            tuple(
+                CrossSection(ts.date(), scores, returns)
+                for ts, (scores, returns) in sorted(grouped.items())
+            ),
+            quantiles=request.quantiles,
+        )
+        record.provenance.update(
+            factor_run_uuid=str(factor_run.uuid),
+            input_digest=factor_run.provenance["input_digest"],
+            definition_digest=factor_run.provenance["definition_digest"],
+            market_revision=revision,
+            manifest_digest=factor_run.provenance.get("manifest_digest"),
+        )
+        record.result = json_value(asdict(report))
+    except Exception as exc:
+        logging.getLogger(__name__).exception("本地计算失败")
+        record.status, record.error = RunStatus.FAILED, str(exc)
+    return record
+
+
+def compare_local_research(store: LocalResearchStore, run_uuids: tuple[UUID, ...]) -> dict:
+    """展示实验结果并核对标签和样本口径，差异不静默当成可比较。"""
+    if not 2 <= len(run_uuids) <= 100:
+        raise ValueError("需选择 2 至 100 次研究运行")
+    records = [store.get(key) for key in run_uuids]
+    reasons = []
+    first = records[0]
+    for record in records:
+        if record.status != RunStatus.COMPLETED:
+            reasons.append("failed_run")
+        if record.request.get("labels") != first.request.get("labels"):
+            reasons.append("labels_differ")
+        if record.request.get("quantiles") != first.request.get("quantiles"):
+            reasons.append("quantiles_differ")
+        for field in ("manifest_digest", "market_revision"):
+            if record.provenance.get(field) != first.provenance.get(field):
+                reasons.append(f"{field}_differs")
+        for field in ("start", "end"):
+            if record.request.get(field) != first.request.get(field):
+                reasons.append(f"{field}_differs")
+        if ("labels" in record.request) != ("labels" in first.request):
+            reasons.append("research_kind_differs")
+        if record.provenance.get("input_digest") != first.provenance.get("input_digest"):
+            reasons.append("inputs_differ")
+    return {
+        "comparable": not reasons,
+        "reasons": sorted(set(reasons)),
+        "runs": [record.model_dump(mode="json") for record in records],
+    }

quant_cli/app/strategy/cli/strategy_cli.py

@@ -0,0 +1,104 @@
+"""策略定义发布、查询、完整依赖下载和本地回测入口。"""
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Annotated
+from urllib.parse import quote
+
+import typer
+from quant_core.app.strategy.schema.python_strategy_schema import PythonStrategySpec
+from quant_core.app.strategy.schema.strategy_publication_schema import PublishedStrategy
+
+from quant_cli.app.backtest.local_backtest_dependency import build_local_backtest_store
+from quant_cli.app.backtest.local_backtest_schema import LocalBacktestRequest
+from quant_cli.app.backtest.service.local_backtest_service import run_local_backtest
+from quant_cli.app.factor.local_factor_dependency import build_local_factor_store
+from quant_cli.common.constants import DEFAULT_DATABASE_PATH
+from quant_cli.common.http.definition_client import request_definition, save_definition
+from quant_cli.common.utils.cli_utils import cli_errors, output
+
+app = typer.Typer(help="已发布策略管理与本地执行", no_args_is_help=True)
+Server = Annotated[str, typer.Option(envvar="PQ_QUANT_URL")]
+Token = Annotated[str, typer.Option(envvar="PQ_QUANT_TOKEN")]
+
+
+@app.command("publish")
+@cli_errors
+def publish(
+    config: Annotated[Path, typer.Option(exists=True)],
+    server: Server,
+    token: Token,
+    source: Annotated[Path | None, typer.Option(exists=True)] = None,
+) -> None:
+    """发布策略定义，不执行策略。"""
+    payload = json.loads(config.read_text(encoding="utf-8"))
+    if source is not None:
+        payload["python_source"] = source.read_text(encoding="utf-8")
+    spec = PythonStrategySpec.model_validate(payload)
+    result = PublishedStrategy.model_validate(
+        request_definition(
+            server, token, "POST", "/strategy/definitions", payload=spec.model_dump(mode="json")
+        )
+    )
+    output(result.model_dump(mode="json"))
+
+
+@app.command("list")
+@cli_errors
+def list_definitions(
+    server: Server, token: Token, strategy_id: str | None = None, limit: int = 100, offset: int = 0
+) -> None:
+    """分页查询策略定义。"""
+    params: dict[str, str | int] = {"limit": limit, "offset": offset}
+    if strategy_id is not None:
+        params["strategy_id"] = strategy_id
+    output(request_definition(server, token, "GET", "/strategy/definitions", params=params))
+
+
+@app.command("fetch")
+@cli_errors
+def fetch(
+    strategy_id: str,
+    server: Server,
+    token: Token,
+    destination: Annotated[Path, typer.Option()],
+    version: str = "latest",
+) -> None:
+    """保存包含全部固定因子定义的离线策略包。"""
+    result = PublishedStrategy.model_validate(
+        request_definition(
+            server,
+            token,
+            "GET",
+            f"/strategy/definitions/{quote(strategy_id, safe='')}/{quote(version, safe='')}",
+        )
+    )
+    save_definition(destination, result.model_dump(mode="json"))
+    output(
+        {
+            "path": str(destination.resolve()),
+            "version": result.definition.version,
+            "content_digest": result.content_digest,
+        }
+    )
+
+
+@app.command("run")
+@cli_errors
+def run(
+    config: Annotated[Path, typer.Option(exists=True)],
+    definition: Annotated[Path, typer.Option(exists=True)],
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    """执行已下载策略包，因子依赖本地计算，结果本地归档。"""
+    payload = json.loads(config.read_text(encoding="utf-8"))
+    if payload.get("source") or payload.get("publication"):
+        raise ValueError("策略执行配置不能同时提供源码或另一发布包")
+    payload["publication"] = PublishedStrategy.model_validate_json(
+        definition.read_text(encoding="utf-8")
+    ).model_dump(mode="json")
+    request = LocalBacktestRequest.model_validate(payload)
+    record = asyncio.run(run_local_backtest(request, build_local_factor_store(database)))
+    build_local_backtest_store(database).save(record)
+    output(record)

quant_cli/common/constants.py

@@ -0,0 +1,7 @@
+"""CLI 默认本地工作区路径。"""
+
+from pathlib import Path
+
+DEFAULT_WORKSPACE_DIR = Path.home() / ".powerquant"
+DEFAULT_DATABASE_PATH = DEFAULT_WORKSPACE_DIR / "workspace.duckdb"
+DEFAULT_DATASETS_DIR = DEFAULT_WORKSPACE_DIR / "datasets"

quant_cli/common/database/duckdb_connection.py

@@ -0,0 +1,30 @@
+"""本地分析库短事务；所有入口共用文件锁，禁止并发进程直接写同一文件。"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+import duckdb
+from filelock import FileLock
+
+
+@contextmanager
+def local_transaction(
+    path: Path, *, read_only: bool = False
+) -> Iterator[duckdb.DuckDBPyConnection]:
+    """持锁后打开连接；成功提交、异常回滚，不在计算期间占用写锁。"""
+    path = path.expanduser().resolve()
+    if read_only and not path.is_file():
+        raise FileNotFoundError(f"本地研究库不存在：{path}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with (
+        FileLock(str(path) + ".lock", timeout=10),
+        duckdb.connect(str(path), read_only=read_only) as connection,
+    ):
+        connection.execute("BEGIN TRANSACTION")
+        try:
+            yield connection
+            connection.execute("COMMIT")
+        except BaseException:
+            connection.execute("ROLLBACK")
+            raise

quant_cli/common/http/definition_client.py

@@ -0,0 +1,54 @@
+"""定义管理 API 的轻量 JSON 传输，不加载 Web 应用或数据库。"""
+
+import json
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+
+def request_definition(
+    server: str,
+    token: str,
+    method: str,
+    path: str,
+    *,
+    payload: dict | None = None,
+    params: dict | None = None,
+) -> Any:
+    """显式 URL 和 Bearer 令牌；不跟随可能泄漏令牌的重定向。"""
+    url = urlsplit(server)
+    if (
+        url.scheme not in {"http", "https"}
+        or not url.netloc
+        or url.username
+        or url.password
+        or url.query
+        or url.fragment
+    ):
+        raise ValueError("服务地址必须是无凭据的 HTTP(S) 基础 URL")
+    if not token:
+        raise ValueError("请通过 PQ_QUANT_TOKEN 提供认证令牌")
+    with httpx.Client(timeout=30, follow_redirects=False) as client:
+        response = client.request(
+            method,
+            server.rstrip("/") + path,
+            headers={"Authorization": f"Bearer {token}"},
+            json=payload,
+            params=params,
+        )
+    if response.status_code != 200:
+        raise ValueError(f"定义服务请求失败，HTTP {response.status_code}")
+    document = response.json()
+    if not isinstance(document, dict) or document.get("code") != 0 or "data" not in document:
+        raise ValueError("定义服务响应格式不合法")
+    return document["data"]
+
+
+def save_definition(path: Path, document: dict) -> None:
+    """下载定义不覆盖已有文件，避免正在引用的版本被静默替换。"""
+    text = json.dumps(document, ensure_ascii=False, allow_nan=False, indent=2)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("x", encoding="utf-8") as stream:
+        stream.write(text)

quant_cli/common/utils/cli_utils.py

@@ -0,0 +1,37 @@
+"""本地 CLI 的 JSON 输出和统一错误退出；日志只输出到 stderr。"""
+
+import functools
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+import typer
+from quant_core.common.local_run import LocalRunRecord, RunStatus
+
+
+def output(value: Any) -> None:
+    """输出一次机器可读结果；失败运行保留 UUID 并返回非零退出码。"""
+    document = value.model_dump(mode="json") if isinstance(value, LocalRunRecord) else value
+    typer.echo(json.dumps(document, ensure_ascii=False, default=str, allow_nan=False))
+    if isinstance(value, LocalRunRecord) and value.status == RunStatus.FAILED:
+        raise typer.Exit(1)
+
+
+def cli_errors(function: Callable) -> Callable:
+    """为各命令保留签名并翻译参数、计算或归档失败。"""
+
+    @functools.wraps(function)
+    def wrapped(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return function(*args, **kwargs)
+        except typer.Exit:
+            raise
+        except Exception as exc:
+            logging.getLogger(__name__).debug("CLI 执行失败", exc_info=True)
+            typer.echo(
+                json.dumps({"status": "failed", "error": str(exc)}, ensure_ascii=False), err=True
+            )
+            raise typer.Exit(1) from exc
+
+    return wrapped

quant_cli/common/utils/platform_utils.py

@@ -0,0 +1,11 @@
+"""CLI 标准流配置。"""
+
+import sys
+
+
+def configure_utf8_output() -> None:
+    """统一标准输出与错误输出编码。"""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8", errors="replace")

quant_cli/common/utils/runtime_environment.py

@@ -0,0 +1,12 @@
+"""CLI 发行版本与计算运行环境，独立于核心库的分发方式。"""
+
+import platform
+from importlib.metadata import version
+
+
+def runtime_versions() -> dict[str, str]:
+    """记录实际安装工具与数值依赖版本，供结果复现。"""
+    return {
+        "python": platform.python_version(),
+        **{name: version(name) for name in ("powerquant-cli", "polars", "numpy")},
+    }

quant_cli/examples/cached_factor_screen.py

@@ -0,0 +1,165 @@
+"""全市场缓存与本地公式验证：python -m examples.cached_factor_screen。"""
+
+import asyncio
+import json
+import os
+import platform
+import time
+from datetime import date, datetime
+from datetime import time as day_time
+from pathlib import Path
+from unittest.mock import patch
+from zoneinfo import ZoneInfo
+
+from pqdata import MarketClient
+from quant_core.app.factor.computation.factor_expression import MA, RANK, Factor
+
+from quant_cli.app.data.service.bar_cache_service import (
+    BarCacheQuery,
+    load_bar_snapshot,
+    prepare_bar_cache,
+)
+from quant_cli.app.factor.service.factor_data_prepare_service import execute_cached_factors
+from quant_cli.common.utils.platform_utils import configure_utf8_output
+
+
+class MeasuredClient(MarketClient):
+    """记录网络查询次数与反序列化后 JSON 大小，后者不是传输层字节数。"""
+
+    def __init__(self) -> None:
+        super().__init__(
+            os.getenv("MARKET_BASE_URL", "http://localhost:8002/api/v1"),
+            token=os.getenv("MARKET_API_TOKEN", ""),
+        )
+        self.download_pages = 0
+        self.content_checks = 0
+        self.payload_bytes = 0
+
+    async def query_bars(self, query):
+        result = await super().query_bars(query)
+        self.download_pages += 1
+        self.payload_bytes += len(result.model_dump_json().encode())
+        return result
+
+    async def describe_bars(self, query):
+        result = await super().describe_bars(query)
+        self.content_checks += 1
+        self.payload_bytes += len(result.model_dump_json().encode())
+        return result
+
+
+async def main() -> None:
+    """只读行情服务，保存本地证据；不发布因子或提交订单。"""
+    cn = ZoneInfo("Asia/Shanghai")
+    first, last = date(2026, 9, 23), date(2026, 9, 30)
+    output = Path(".cache/v021-factor-verification")
+    output.mkdir(parents=True, exist_ok=True)
+    async with MeasuredClient() as client:
+        catalog = await client.search_instruments(instrument_type="stock", limit=10000)
+        if len(catalog) >= 10000:
+            raise ValueError("目录达到上限，拒绝截断全市场")
+        unknown = [row.instrument_id for row in catalog if row.listed_date is None]
+        stocks = [
+            row
+            for row in catalog
+            if row.listed_date is not None
+            and row.listed_date <= last
+            and (row.delisted_date is None or row.delisted_date >= first)
+        ]
+        calendar_rows = await client.list_trading_days("XSHG", first, last)
+        calendar = tuple(
+            datetime.combine(row.trade_date, day_time(15), cn)
+            for row in calendar_rows
+            if row.is_open
+        )
+        if len(calendar) < 5:
+            raise ValueError("交易日不足以验证五日窗口")
+        universe = {
+            timestamp: tuple(
+                row.instrument_id
+                for row in stocks
+                if row.listed_date <= timestamp.date()
+                and (row.delisted_date is None or row.delisted_date >= timestamp.date())
+            )
+            for timestamp in calendar
+        }
+        query = BarCacheQuery(
+            instrument_ids=sorted(row.instrument_id for row in stocks),
+            frequency="1d",
+            start=datetime.combine(first, day_time.min, cn),
+            end=datetime.combine(last, day_time.max, cn),
+        )
+        metrics = []
+        for label in ("initial", "repeat"):
+            before = (client.download_pages, client.content_checks, client.payload_bytes)
+            started = time.perf_counter()
+            manifest = await prepare_bar_cache(client, query, output, 200000)
+            metrics.append(
+                {
+                    "label": label,
+                    "seconds": time.perf_counter() - started,
+                    "download_pages": client.download_pages - before[0],
+                    "content_checks": client.content_checks - before[1],
+                    "decoded_payload_bytes": client.payload_bytes - before[2],
+                }
+            )
+        assert metrics[1]["download_pages"] == 0
+    with patch("socket.socket", side_effect=AssertionError("offline computation used network")):
+        started = time.perf_counter()
+        result = execute_cached_factors(
+            {
+                "intraday_rank": RANK(Factor("close") / Factor("open") - 1),
+                "mean5": MA(Factor("close"), 5),
+            },
+            manifest,
+            calendar=calendar,
+            universe=universe,
+            start=calendar[-1],
+            end=calendar[-1],
+            max_rows=200000,
+        )
+        compute_seconds = time.perf_counter() - started
+        _, rows = load_bar_snapshot(manifest, 200000)
+    # 独立 Decimal 五日均值，不使用因子算子作为测试 oracle。
+    lookup = {(row.timestamp, row.instrument_id): row for row in rows}
+    checked = 0
+    for instrument in query.instrument_ids:
+        window = [lookup.get((timestamp, instrument)) for timestamp in calendar[-5:]]
+        if all(row is not None and not row.suspended for row in window):
+            expected = sum(row.close for row in window) / 5
+            actual = result.values["mean5"][(calendar[-1], instrument)]
+            if instrument in universe[calendar[-1]]:
+                assert actual is not None and abs(float(actual - expected)) < 1e-9
+                checked += 1
+    summary = {
+        "platform": platform.platform(),
+        "python": platform.python_version(),
+        "stock_catalog": len(catalog),
+        "unknown_listing": unknown,
+        "prepared_instruments": len(stocks),
+        "trading_days": len(calendar),
+        "bar_rows": len(rows),
+        "expected_grid": len(stocks) * len(calendar),
+        "missing_grid_rows": len(stocks) * len(calendar) - len(rows),
+        "independent_mean_checks": checked,
+        "non_null": {
+            name: sum(value is not None for value in values.values())
+            for name, values in result.values.items()
+        },
+        "metrics": metrics,
+        "offline_compute_seconds": compute_seconds,
+        "parquet_bytes": sum(path.stat().st_size for path in manifest.parent.glob("*.parquet")),
+        "manifest": str(manifest.resolve()),
+        "input_digest": result.input_digest,
+        "price_basis": "raw",
+        "historical_knowledge": "current revision only",
+    }
+    (output / "summary.json").write_text(
+        json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    configure_utf8_output()
+    asyncio.run(main())

quant_cli/examples/factors/ma_close_10.py

@@ -0,0 +1,10 @@
+"""最近 10 根日线收盘均价。"""
+
+from decimal import Decimal
+
+
+def compute(bars, parameters):
+    lookback = int(parameters.get("lookback", 10))
+    if len(bars) < lookback:
+        return None
+    return sum(Decimal(bar["close"]) for bar in bars[-lookback:]) / lookback

quant_cli/examples/factors/max_drawdown_20d.py

@@ -0,0 +1,18 @@
+"""最近 20 个交易日最大收盘回撤，取值范围 [-1, 0]。"""
+
+from decimal import Decimal
+
+
+def compute(bars, parameters):
+    lookback = int(parameters.get("lookback", 20))
+    if lookback < 2 or len(bars) < lookback:
+        return None
+    peak = Decimal("0")
+    worst = Decimal("0")
+    for bar in bars[-lookback:]:
+        close = Decimal(bar["close"])
+        if close <= 0:
+            return None
+        peak = max(peak, close)
+        worst = min(worst, close / peak - 1)
+    return worst

quant_cli/examples/factors/momentum_20d.py

@@ -0,0 +1,13 @@
+"""20 日动量：今日收盘价 / 20 个交易日前收盘价 - 1。"""
+
+from decimal import Decimal
+
+
+def compute(bars, parameters):
+    lookback = int(parameters.get("lookback", 21))
+    if len(bars) < lookback:
+        return None
+    previous = Decimal(bars[-lookback]["close"])
+    if previous == 0:
+        return None
+    return Decimal(bars[-1]["close"]) / previous - 1

quant_cli/examples/factors/multi_intraday_screen.py

@@ -0,0 +1,16 @@
+"""五日量价研究配方；日内比值避免跨日复权口径混用。"""
+
+from quant_core.app.factor.computation.factor_expression import MA, REF, STD, Factor
+
+close = Factor("close")
+open_price = Factor("open")
+high = Factor("high")
+low = Factor("low")
+volume = Factor("volume")
+intraday_return = close / open_price - 1
+factors = {
+    "close_pressure_5d": MA((close * 2 - high - low) / (high - low) * volume, 5) / MA(volume, 5),
+    "intraday_strength_5d": MA(intraday_return, 5),
+    "low_intraday_volatility_5d": -STD(intraday_return, 5),
+    "volume_expansion": volume / REF(MA(volume, 4), 1),
+}

quant_cli/examples/factors/risk_adjusted_momentum_20d.py

@@ -0,0 +1,18 @@
+"""20 日风险调整动量：区间收益 / 日收益总体标准差。"""
+
+from decimal import Decimal
+
+
+def compute(bars, parameters):
+    lookback = int(parameters.get("lookback", 21))
+    if lookback < 3 or len(bars) < lookback:
+        return None
+    closes = [Decimal(bar["close"]) for bar in bars[-lookback:]]
+    if any(close <= 0 for close in closes):
+        return None
+    returns = [closes[index] / closes[index - 1] - 1 for index in range(1, lookback)]
+    mean = sum(returns) / len(returns)
+    variance = sum((value - mean) ** 2 for value in returns) / len(returns)
+    if variance == 0:
+        return None
+    return (closes[-1] / closes[0] - 1) / variance.sqrt()

quant_cli/examples/factors/volume_ratio_5d.py

@@ -0,0 +1,14 @@
+"""5 日量比：当日成交量 / 最近 5 根日线平均成交量。"""
+
+from decimal import Decimal
+
+
+def compute(bars, parameters):
+    lookback = int(parameters.get("lookback", 5))
+    if len(bars) < lookback:
+        return None
+    volumes = [Decimal(bar["volume"]) for bar in bars[-lookback:]]
+    average = sum(volumes) / lookback
+    if average == 0:
+        return None
+    return volumes[-1] / average

quant_cli/examples/factors/volume_weighted_close_pressure.py

@@ -0,0 +1,14 @@
+"""五日成交量加权收盘强度；仅为研究配方，不代表收益有效性。"""
+
+from quant_core.app.factor.computation.factor_expression import MA, Factor
+
+close = Factor("close")
+high = Factor("high")
+low = Factor("low")
+volume = Factor("volume")
+
+# 日内比值避免跨日价格复权口径差异；零振幅窗口保持不可计算。
+close_pressure = (close * 2 - high - low) / (high - low)
+factors = {
+    "volume_weighted_close_pressure_5d": MA(close_pressure * volume, 5) / MA(volume, 5)
+}