powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/research/service/research_service.py

@@ -0,0 +1,171 @@
+"""可信本机研究代码的唯一运行入口。"""
+
+import hashlib
+import inspect
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Any
+from uuid import uuid4
+
+from quant_core.app.data.interface.market_data_query import IMarketDataQuery
+from quant_core.app.data.interface.market_revision_query import IMarketRevisionQuery
+from quant_core.app.factor.constants import FactorFreshness
+from quant_core.app.factor.interface.public.factor_query import IFactorQuery
+from quant_core.app.factor.schema.factor_contract import FactorIdentity, FactorSnapshot, FactorValue
+from quant_core.app.research.interface.research_dataset import (
+    IResearchDatasetBuilder,
+    IResearchDatasetFactory,
+)
+from quant_core.app.research.interface.research_evaluation import IResearchEvaluation
+from quant_core.app.research.schema.research_schema import (
+    ResearchEvidence,
+    ResearchRunRecord,
+    ResearchRunRequest,
+    ResearchWorkspace,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ResearchContext:
+    """研究代码只通过公开查询契约读取历史事实。"""
+
+    market: IMarketDataQuery
+    factors: IFactorQuery | None
+    start: date
+    end: date
+    datasets: IResearchDatasetBuilder | None = None
+    evaluation: IResearchEvaluation | None = None
+
+
+class _TrackedFactorQuery:
+    """仅在研究代码实际读取因子时将其版本记入运行证据。"""
+
+    def __init__(self, query: IFactorQuery) -> None:
+        self._query = query
+        self.used = False
+        self.revisions: set[str] = set()
+
+    def _track(self, values: tuple[FactorValue, ...], requested_revision: str | None) -> None:
+        if requested_revision is not None:
+            self.revisions.add(requested_revision)
+        self.revisions.update(value.provenance.dataset_revision or "0-legacy" for value in values)
+
+    async def get_snapshot(
+        self,
+        identities: list[FactorIdentity],
+        instrument_ids: list[str],
+        decision_time: datetime,
+        *,
+        target_as_of: date | None = None,
+        freshness: FactorFreshness = FactorFreshness.EXACT,
+        dataset_revision: str | None = None,
+    ) -> FactorSnapshot:
+        self.used = True
+        snapshot = await self._query.get_snapshot(
+            identities,
+            instrument_ids,
+            decision_time,
+            target_as_of=target_as_of,
+            freshness=freshness,
+            dataset_revision=dataset_revision,
+        )
+        self._track(snapshot.values, dataset_revision)
+        return snapshot
+
+    async def get_series(
+        self,
+        identity: FactorIdentity,
+        instrument_id: str,
+        start: datetime,
+        end: datetime,
+        decision_time: datetime,
+        *,
+        dataset_revision: str | None = None,
+    ) -> tuple[FactorValue, ...]:
+        self.used = True
+        values = await self._query.get_series(
+            identity,
+            instrument_id,
+            start,
+            end,
+            decision_time,
+            dataset_revision=dataset_revision,
+        )
+        self._track(values, dataset_revision)
+        return values
+
+
+async def execute_research(
+    request: ResearchRunRequest,
+    market: IMarketDataQuery,
+    revisions: IMarketRevisionQuery,
+    *,
+    workspace: ResearchWorkspace | None = None,
+    factors_query: IFactorQuery | None = None,
+    dataset_factory: IResearchDatasetFactory | None = None,
+    evaluation: IResearchEvaluation | None = None,
+) -> ResearchRunRecord:
+    """执行显式研究定义并返回记录，不读取或保存管理数据库。"""
+    if request.research_id and workspace is None:
+        raise ValueError("已注册研究需先显式加载定义")
+    source = workspace.python_source if workspace else request.python_source
+    assert source is not None
+    parameters = {**(workspace.default_parameters if workspace else {}), **request.parameters}
+    config = {
+        "start": request.start.isoformat(),
+        "end": request.end.isoformat(),
+        "parameters": parameters,
+    }
+    data_revisions: dict[str, str] = {}
+    result: ResearchEvidence | None = None
+    error: str | None = None
+    factors = _TrackedFactorQuery(factors_query) if factors_query is not None else None
+    datasets = dataset_factory(factors) if dataset_factory and factors else None
+    try:
+        spec = ResearchWorkspace(
+            research_id=workspace.research_id if workspace else "temporary",
+            name=workspace.name if workspace else "临时研究",
+            python_source=source,
+        )
+        spec.validate_source()
+        data_revisions = await revisions.snapshot(request.start, request.end)
+        namespace: dict[str, Any] = {"__name__": "research_user_code"}
+        exec(compile(source, "<research>", "exec"), namespace)
+        callback = namespace["run"]
+        value = callback(
+            ResearchContext(
+                market,
+                factors,
+                request.start,
+                request.end,
+                datasets,
+                evaluation,
+            ),
+            parameters,
+        )
+        if inspect.isawaitable(value):
+            value = await value
+        result = ResearchEvidence.model_validate(value)
+        if result.sample_start != request.start or result.sample_end != request.end:
+            raise ValueError("研究输出的样本区间与运行请求不一致")
+        result.model_dump(mode="json")
+    except Exception as exc:
+        result = None
+        error = f"{type(exc).__name__}: {exc}"
+    if factors is not None and factors.used:
+        data_revisions["factor"] = ",".join(sorted(factors.revisions)) or "no_values"
+    if datasets is not None:
+        data_revisions.update(datasets.revisions)
+    record = ResearchRunRecord(
+        uuid=str(uuid4()),
+        status="completed" if result is not None else "failed",
+        research_id=request.research_id,
+        source_kind="workspace" if workspace else "temporary",
+        source_snapshot=source,
+        source_digest=hashlib.sha256(source.encode("utf-8")).hexdigest(),
+        config_snapshot=config,
+        data_revisions=data_revisions,
+        result=result,
+        error=error,
+    )
+    return record

quant_core/app/strategy/SPEC.md

@@ -0,0 +1,215 @@
+# Strategy Domain SPEC
+
+> Strategy 域的架构 SSOT：领域模型、边界、契约与演进范围以本文件为准。
+> 字段级语义见各 schema 模块 docstring；决策背景见根 [DECISIONS.md](../../DECISIONS.md)。
+> **P1 已 Freeze（2026-09-03）**：本域达到 Backtest 准入状态；后续只做增量扩展，不阻塞 Backtest。
+
+## 1. 领域定位与公式
+
+Strategy 域建立 **统一策略生产体系**：Human / Agent / Python（未来 MyLanguage / UI DSL）
+都生产同一个 Canonical Definition，Runtime 稳定执行它们。
+
+```text
+Strategy Domain =
+    Authoring（多入口 → 同一 Canonical Definition）
+  + Factor Definition / Runtime / Result
+  + Screener
+  + Strategy Definition / Runtime
+  + Signal
+  + Validation（Definition / Runtime 两层）
+  + Evaluation（契约；绩效计算归 Backtest）
+  + Human Review（Agent Artifact 进 Paper/Live 的硬门槛）
+```
+
+核心定位：**Agent First ≠ Agent Direct Execution**——Agent 负责 Generate / Analyze /
+Iterate，但任何 Quant Artifact 都不得绕过 Canonical Contract → Validation → Backtest →
+Human Approval 进入 Live。
+
+## 2. 领域模型：Definition / Runtime / Result
+
+Factor 与 Strategy 都遵循同一模式：
+
+```text
+Definition（是什么、怎么算）        Runtime（执行）              Result
+FactorDefinition        →   FactorService(FactorRuntime)  →   FactorResult
+StrategyDefinition      →   StrategyRuntimeService        →   Signal
+```
+
+**Screener 不是 Strategy 的必经阶段**——它是域内候选集生成能力，只有横截面类策略经过它：
+
+```text
+Cross-sectional：Market → Factor → Screener → Strategy → Signal
+Single Instrument Timing：BarEvent → Strategy → Signal（完全不经过 Screener）
+```
+
+禁止把 Domain 硬编码成 Factor → Screener → Strategy → Signal 的单一路径。
+
+## 3. P1 真实执行模型（重要声明）
+
+```text
+StrategyDefinition（Canonical Artifact / Metadata / 声明式 Contract）
+        +
+Python Native Strategy Implementation（StrategyProtocol 实现）
+        ↓
+StrategyRuntimeService
+        ↓
+Signal
+```
+
+> **P1 的 `StrategyDefinition` 是 Canonical Artifact、Metadata 与声明式 Contract；
+> 实际执行由 Python Native Strategy implementation 承载。P1 不宣称已经实现完整的
+> Definition-driven execution。**
+
+Definition 回答「这个策略是什么」，Implementation 回答「P1 当前如何执行它」；
+二者通过 `StrategyDefinition.implementation_ref`（dotted path）显式关联，不靠文件名猜测。
+Definition → Compiler/Interpreter → Executable Strategy 的演进属 Agent DSL / MyLanguage /
+UI DSL 阶段（P2+），届时新增编译入口而非第二套 Runtime。
+
+## 4. 硬规则
+
+1. **Definition / Runtime / Result 概念分离**：Definition 是 Artifact（非运行实例、非 Signal）。
+2. **所有 Authoring 入口收敛到 Canonical Definition**：不建立 Agent 专属策略模型、
+   不为 DSL 建第二套 Runtime。MyLanguage 是 Authoring Adapter（Parser → AST → Definition），
+   禁止直接驱动 Backtest Engine。
+3. **Strategy 只产生 Signal，不产生 Broker Order**：Strategy 回答「应该做什么」，
+   Execution / Backtest 回答「怎么成交」。资产变化只发生在
+   `Signal → Backtest/Execution → Order → Fill → Portfolio Update` 链路上。
+4. **Strategy 环境无关**：市场时间只认 `event_time`（业务代码禁止
+   `datetime.now()`/`datetime.utcnow()`/`time.time()`）；
+   数据只经 `StrategyContext` 注入的 Port（禁止直连 AKShare / Repository / DB / Broker）；
+   同一 Definition 在 Backtest / Paper / Live 下业务逻辑不变（环境由 `StrategyRunMode` 表达，
+   不混入 StrategyStatus）。
+5. **非结构化输入必须先转 Canonical FactorResult**：禁止 Strategy 内部直接 prompt LLM、
+   自由文本决定买卖；FactorResult 的 NULL = 不可计算（禁止 0 填充，与 Market NULL 语义一致）。
+   Strategy 不得重复计算 FactorService 已有的因子（含 MA 等参考线）。
+6. **状态与环境分离**：`StrategyStatus` / `FactorStatus` 描述 Artifact 生命周期；
+   `StrategyRunMode` 描述运行环境。
+7. **Agent Artifact 可追溯**：Definition 携带 authoring_source / created_by /
+   parent_version / implementation_ref。
+8. **Human Approval 是 Paper/Live 的前置条件**（领域规则，不是 UI 细节）。
+9. **Screener 契约唯一**：`ScreenerService` 的运行输入就是 Canonical `ScreenerSpec`
+   （来自 `StrategyDefinition.screening_rules`），不存在 Definition 一套声明模型、
+   Runtime 另一套临时 dict 模型。
+
+## 5. StrategyContext 状态职责表
+
+| 载体 | 归属 | 允许 | 禁止 |
+|---|---|---|---|
+| `StrategyContext.state` | Strategy 自己 | last_signal_time / consecutive_count / trailing_state / 自定义计数器 | **cash / position quantity / available quantity / cost basis / equity** |
+| `StrategyContext.portfolio` | Portfolio / Backtest（只读注入） | 经 `PortfolioReaderProtocol` 读取持仓与资金 | 任何修改（无写方法） |
+
+```python
+class PortfolioReaderProtocol(Protocol):
+    async def get_position(self, instrument_id: str) -> PositionView | None: ...
+    async def get_cash(self) -> CashView: ...
+```
+
+只读、最小化。禁止提前设计完整 Portfolio Domain / 多账户 / Broker account / 对账。
+
+## 6. 目录与职责
+
+```text
+app/strategy/
+├── constants.py                  # 枚举（Type/Style/Status/RunMode/Signal…）
+├── exceptions.py                 # 域内异常
+├── schema/
+│   ├── factor_schema.py          # FactorDefinition / FactorResult
+│   ├── strategy_schema.py        # StrategyDefinition / RuleCondition / ScreenerSpec
+│   ├── screener_schema.py        # ScreenerRequest（spec: ScreenerSpec）/ ScreenerResult
+│   ├── signal_schema.py          # Signal
+│   └── portfolio_schema.py       # PositionView / CashView（只读视图）
+├── service/
+│   ├── expression.py             # 受限公式解释器（ref/ma + 算术，ast 白名单）
+│   ├── factor_service.py         # Factor Runtime：注册 Definition → 计算 FactorResult
+│   ├── screener_service.py       # ScreenerSpec 驱动：Universe → Filter → Rank → Top N
+│   ├── strategy_protocol.py      # StrategyProtocol / StrategyContext / PortfolioReader
+│   └── strategy_runtime_service.py
+└── strategies/
+    └── momentum_volume_breakout.py   # P1 Demo（Python Native，公式移植自 FactorHub）
+```
+
+**StrategyRuntimeService 职责**（收口）：
+
+```text
+├── 接收 MarketEvent 或完整 MarketTimeSlice（不做 Bar-centric 假设）
+├── 构造 StrategyContext
+├── 调度 required Factor（经 StrategyFactorProviderProtocol）
+├── 调用 Strategy implementation（on_bar / on_session）
+├── 收集 Signal
+└── 维护 strategy-local runtime state
+```
+
+Backtest 的稳定调度边界是单时间片入口：
+
+```text
+MarketTimeSlice@T
+       |
+       v
+run_slice(time_slice) → list[Signal]
+       |
+       v
+Backtest 执行 Fill / 更新 Portfolio
+       |
+       v
+MarketTimeSlice@T+1 读取更新后的只读 PortfolioView
+```
+
+`run_slice()` 在该片回调全部完成后立即返回 Signal Batch，不产生 Order/Fill、
+不修改 Portfolio。`run_slices()` 只是复用 `run_slice()` 的整段回放便利包装；需要在
+片间形成 Portfolio 反馈的 Backtest 必须逐片调用 `run_slice()`。
+
+它不是「加载窗口 Bar 的服务」——拉窗口只是 Context 装配的实现细节。
+未知事件按契约忽略；默认消费**已通过运行环境前置验证的数据**（Backtest 启动前经
+`IMarketDataVerification` 检查），不在 `on_bar()` 内重复 `verify_bars()`。
+
+## 7. 对 Market 的依赖边界
+
+只允许依赖 Market 跨域稳定 Port（见 [market/SPEC.md](../market/SPEC.md) §4）：
+
+- `IMarketDataQuery`（Pull 行情窗口；经 StrategyContext.market）
+- `IMarketEventSource`（事件流输入）
+- `MarketTimeSlice`（Backtest 注入的完整同市场时刻信息集；时间片 Source 由 Backtest 编排）
+- `IMarketDataVerification`（由 Backtest 前置调用，Strategy 不逐 bar 调用）
+
+禁止依赖：Market Repository / Adapter / AKShare / MarketSyncService / Database / Broker。
+
+## 8. 与 Backtest / Research 的边界
+
+- Backtest 消费 Strategy Runtime 的 Signal 流，负责 Order / Fill / Commission /
+  Slippage / SimulatedPortfolio / Metrics；禁止复制 Strategy 逻辑。
+  Signal 契约禁止包含 broker_order_id / fill_price / commission / slippage / account_id。
+  Backtest 准入链：`BacktestRequest → ensure_backtest_data_ready → MarketTimeSlice Replay →
+  StrategyRuntime.run_slice → Signal Batch → Order → Simulated Fill → SimulatedPortfolio → Metrics`；
+  每片完成 Portfolio 更新后才能处理下一片。
+- Research 可消费 Definition / FactorResult / Signal / 回测结果做解释；
+  自然语言结论不得污染 FactorResult / Signal 契约。
+
+## 9. Validation 两层
+
+| 层 | 检查内容 | 现状 |
+|---|---|---|
+| Definition Validation（静态） | identity/version 格式（Field pattern）、styles 合法、expression/implementation_ref 互斥、规则组非空且 left 非空、required_factors 引用合法（传入已注册因子集校验） | 已实现（`validate_definition()`） |
+| Runtime/Data Validation | 因子窗口是否足够（→ FactorResult NULL）；Market Data 健康检查归 Backtest 前置 Guard | 已实现 / 前置 Guard 已具备 |
+
+不引入通用 Rule Engine。
+
+## 10. 实现范围
+
+- **P1（已实现，FROZEN）**：六契约（StrategyDefinition / FactorDefinition / FactorResult /
+  Signal / StrategyContext / StrategyProtocol）、ScreenerSpec 统一驱动 ScreenerService、
+  PortfolioReader 最小契约、受限 expression 解释器、FactorService（momentum_20d /
+  volume_ratio_5d / ma_close_10，公式移植自 FactorHub）、StrategyRuntimeService（事件调度 +
+  portfolio 注入 + strategy-local state + 单时间片 `run_slice()` 反馈边界）、MomentumVolumeBreakout Demo、
+  Deterministic Replay E2E（两次运行业务结果一致）。
+- **P2+（不阻塞 Backtest）**：Agent Authoring 入口、Strategy/Factor 持久化与生命周期 API、
+  Backtest 调用入口与 Evaluation Contract、Human Review lifecycle、MyLanguage Adapter、
+  非结构化 Factor（TEXT + confidence）、on_quote/on_news 回调、Paper/Live。
+- **明确不做**：通用 Strategy IR、Visual Builder、AutoML、遗传规划、Multi-Agent 策略委员会、
+  复杂 Workflow Engine、通用 Event Bus。
+
+## 11. 边界检查
+
+```bash
+# app/strategy/ 业务代码中 grep akshare|ts_code|sqlalchemy|datetime.now|time.time
+# 必须为 0 命中（文档性注释提及"禁止…"除外）
+```

quant_core/app/strategy/__init__.py

@@ -0,0 +1 @@
+"""Strategy Domain：Authoring + Factor + Screener + Strategy + Signal（见 SPEC.md）"""

quant_core/app/strategy/constants.py

@@ -0,0 +1,87 @@
+"""
+Strategy 域常量与枚举
+
+概念分层（SSOT 见 SPEC）：
+- Definition / Runtime / Result 三层分离：Factor 与 Strategy 都遵循
+  Definition（是什么、怎么算）→ Runtime（执行）→ Result（Canonical
+  FactorValue / Signal，R2-1 起因子值唯一形态是 quant_core.app.factor.FactorValue）。
+- 状态（StrategyStatus / FactorStatus）描述 Artifact 生命周期；
+  运行环境（StrategyRunMode）单独定义——同一 Definition 在不同环境下业务逻辑不变。
+"""
+
+from enum import Enum
+
+
+class StrategyType(str, Enum):
+    """策略决策范式（不是风格：Momentum/Value 等属 StrategyStyle）"""
+
+    SELECTION = "selection"  # 选股型
+    TIMING = "timing"  # 择时型
+    CROSS_SECTIONAL = "cross_sectional"  # 横截面因子排名 / 多因子
+    EVENT_DRIVEN = "event_driven"  # 新闻 / 公告 / 市场事件驱动
+    PORTFOLIO = "portfolio"  # 组合权重 / 再平衡
+
+
+class StrategyStyle(str, Enum):
+    """策略风格 Tag（一个策略可含多个 Style）"""
+
+    MOMENTUM = "momentum"
+    TREND = "trend"
+    MEAN_REVERSION = "mean_reversion"
+    BREAKOUT = "breakout"
+    VALUE = "value"
+    QUALITY = "quality"
+    GROWTH = "growth"
+    VOLATILITY = "volatility"
+    EVENT = "event"
+    MULTI_FACTOR = "multi_factor"
+
+
+class StrategyStatus(str, Enum):
+    """Strategy Artifact 生命周期（运行环境见 StrategyRunMode，不得混入）"""
+
+    DRAFT = "draft"
+    VALIDATING = "validating"
+    BACKTESTED = "backtested"
+    REVIEW_REQUIRED = "review_required"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    PAPER = "paper"
+    LIVE = "live"
+    ARCHIVED = "archived"
+
+
+class StrategyRunMode(str, Enum):
+    """Runtime 运行环境：Definition 不变，只换运行环境与 EventSource"""
+
+    RESEARCH = "research"
+    BACKTEST = "backtest"
+    PAPER = "paper"
+    LIVE = "live"
+
+
+class AuthoringSource(str, Enum):
+    """Artifact 生产入口（Agent First：Agent 与 Human 走同一 Canonical Definition）"""
+
+    HUMAN = "human"
+    AGENT = "agent"
+    PYTHON = "python"
+    MYLANGUAGE = "mylanguage"  # Authoring Language Adapter，reserved
+    DSL = "dsl"
+
+
+class SignalType(str, Enum):
+    """信号类型（Strategy 产生的 Canonical Decision Result）"""
+
+    ENTER = "enter"
+    EXIT = "exit"
+    HOLD = "hold"
+    WATCH = "watch"
+
+
+class SignalSide(str, Enum):
+    """信号方向（A股 V1：LONG / NONE；SHORT reserved）"""
+
+    LONG = "long"
+    NONE = "none"
+    SHORT = "short"  # reserved

quant_core/app/strategy/exceptions.py

@@ -0,0 +1,32 @@
+"""Strategy 域业务异常（Common 拥有机制，Domain 拥有语义）"""
+
+from quant_core.common.exceptions.base import AppException, ConflictException, ValidationException
+
+
+class StrategyPublicationConflict(ConflictException):
+    error_code = "STRATEGY_PUBLICATION_CONFLICT"
+
+
+class PublishedStrategyNotFound(AppException):
+    error_code = "PUBLISHED_STRATEGY_NOT_FOUND"
+    http_status = 404
+
+
+class StrategyValidationException(ValidationException):
+    """Strategy/Factor Definition 校验失败（Definition Validation 层）"""
+
+    error_code = "STRATEGY_VALIDATION_ERROR"
+    http_status = 422
+
+    def __init__(self, message: str = "策略定义校验失败"):
+        super().__init__(message)
+
+
+class StrategyNotRegisteredException(AppException):
+    """指定策略未注册"""
+
+    error_code = "STRATEGY_NOT_REGISTERED"
+    http_status = 404
+
+    def __init__(self, strategy_id: str):
+        super().__init__(f"strategy 未注册: {strategy_id}")

quant_core/app/strategy/interface/public/portfolio_construction.py

@@ -0,0 +1,19 @@
+"""策略组合构建公共接口；不产生订单或修改资产。"""
+
+from decimal import Decimal
+from typing import Protocol
+
+from quant_core.app.factor.schema.selection_types import SelectionResult
+from quant_core.app.strategy.schema.portfolio_target import PortfolioConstraints, TargetPortfolio
+
+
+class IPortfolioConstruction(Protocol):
+    def build(
+        self,
+        selection: SelectionResult,
+        constraints: PortfolioConstraints,
+        *,
+        current_weights: dict[str, Decimal] | None = None,
+        industries: dict[str, str] | None = None,
+        holding_sessions: dict[str, int] | None = None,
+    ) -> TargetPortfolio: ...

quant_core/app/strategy/interface/public/strategy.py

@@ -0,0 +1,30 @@
+"""Public Python strategy callback contract."""
+
+from typing import Any, Protocol, runtime_checkable
+
+from quant_core.app.data.schema.event_schema import BarEvent, TradingSessionEvent
+from quant_core.app.strategy.schema.signal_schema import Signal
+from quant_core.app.strategy.strategy_context import StrategyContext
+
+
+@runtime_checkable
+class IStrategy(Protocol):
+    """策略实现契约（Python Native 策略的第一入口）
+
+    所有入口（Human / Agent / MyLanguage）最终编译为同一个 Canonical
+    StrategyDefinition；Python Native 策略额外实现本 Protocol 以被 Runtime 执行。
+    """
+
+    def definition(self) -> Any:
+        """返回策略的 Canonical StrategyDefinition"""
+        ...
+
+    async def on_bar(self, event: BarEvent, context: "StrategyContext") -> list[Signal]:
+        """Bar 事件驱动的决策入口"""
+        ...
+
+    async def on_session(
+        self, event: TradingSessionEvent, context: "StrategyContext"
+    ) -> list[Signal]:
+        """Session 事件驱动的决策入口"""
+        ...

quant_core/app/strategy/interface/public/strategy_market_query.py

@@ -0,0 +1,53 @@
+"""策略已绑定决策时点的行情读取面，不暴露完整 Market 生产能力。"""
+
+from collections.abc import Sequence
+from datetime import date, datetime
+from typing import Protocol
+
+from quant_core.app.data.schema.adjustment_schema import AdjustedBarSeries, BarViewRequest
+from quant_core.app.data.schema.market_schema import (
+    BarResponse,
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+)
+
+
+class IStrategyMarketQuery(Protocol):
+    async def get_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> Sequence[BarResponse]: ...
+
+    async def get_adjusted_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        view: BarViewRequest,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> AdjustedBarSeries: ...
+
+    async def get_instrument(self, instrument_id: str) -> InstrumentResponse: ...
+
+    async def list_instruments_on(
+        self, on_date: date, limit: int = 10000
+    ) -> list[InstrumentResponse]: ...
+
+    async def search_instruments(
+        self,
+        keyword: str | None = None,
+        instrument_type: str | None = None,
+        exchange: str | None = None,
+        limit: int = 100,
+    ) -> list[InstrumentResponse]: ...
+
+    async def is_trading_day(self, exchange: str, trade_date: date) -> bool: ...
+
+    async def list_trading_days(
+        self, exchange: str, start: date, end: date
+    ) -> list[TradingCalendarDayResponse]: ...

quant_core/app/strategy/interface/public/strategy_portfolio_reader.py

@@ -0,0 +1,33 @@
+"""Async portfolio view consumed by strategies."""
+
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.portfolio.ledger_schema import PositionLotSnapshot
+from quant_core.app.portfolio.portfolio_schema import PortfolioSnapshot
+from quant_core.app.strategy.schema.portfolio_schema import CashView, PositionView
+
+
+@runtime_checkable
+class IStrategyPortfolioReader(Protocol):
+    """持仓/资金只读能力（V1 由 Backtest 模拟持仓实现；可选依赖）
+
+    最小读取边界：Strategy 可以读取持仓与资金，但不能拥有或修改——
+    资产变化只发生在 Signal → Backtest/Execution → Order → Fill →
+    Portfolio Update 链路上。禁止在此扩展多账户/Broker account/对账。
+    """
+
+    async def get_position(self, instrument_id: str) -> PositionView | None:
+        """单个标的持仓视图（未持仓返回 None）"""
+        ...
+
+    async def get_cash(self) -> CashView:
+        """可用资金视图"""
+        ...
+
+    async def get_snapshot(self) -> PortfolioSnapshot:
+        """当前账户总值和持仓市值的公开只读快照。"""
+        ...
+
+    async def get_position_lots(self) -> tuple[PositionLotSnapshot, ...]:
+        """当前持仓的真实成交批次，包含取得时间和剩余数量。"""
+        ...

quant_core/app/strategy/interface/strategy_factor_reader.py

@@ -0,0 +1,19 @@
+"""Strategy consumes already-published PIT factor values; it never computes them."""
+
+from datetime import datetime
+from typing import Protocol
+
+from quant_core.app.factor.schema.factor_contract import FactorValue
+
+
+class IStrategyFactorReader(Protocol):
+    async def read_many(
+        self,
+        factor_names: tuple[str, ...],
+        instrument_ids: tuple[str, ...],
+        decision_time: datetime,
+    ) -> dict[str, dict[str, FactorValue]]: ...
+
+    async def read(
+        self, factor_name: str, instrument_id: str, decision_time: datetime
+    ) -> FactorValue | None: ...