powerquant-cli 0.2.6__py3-none-any.whl

pqdata/schema/history_schema.py

@@ -0,0 +1,61 @@
+"""回放准备所需的市场事实；事件与时间片仍由量化端组织。"""
+
+from datetime import date
+from decimal import Decimal
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from pqdata.schema.adjustment_schema import AdjustmentFactorResponse
+from pqdata.schema.corporate_action_schema import CorporateActionResponse
+from pqdata.schema.reference_schema import (
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+    TradingRuleResponse,
+)
+
+
+class DailyFactResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    instrument_id: str
+    trade_date: date
+    suspension_status: Literal["none", "full_day", "intraday"] | None
+    special_type: Literal["Normal", "ST", "StarST"] | None = None
+    special_type_source: str | None = None
+    limit_up: Decimal | None = None
+    limit_dn: Decimal | None = None
+    extra: dict[str, Any] | None = None
+    source_provider: str
+
+    @property
+    def is_st(self) -> bool | None:
+        """未知保持 None，调用方不能把缺少数据当成正常。"""
+        return None if self.special_type is None else self.special_type != "Normal"
+
+    @property
+    def is_suspended(self) -> bool | None:
+        """只判断全天停牌；False 不表示全天每一分钟都可交易。"""
+        return None if self.suspension_status is None else self.suspension_status == "full_day"
+
+
+class HistoryFactsQuery(BaseModel):
+    instrument_id: str
+    start: date
+    end: date
+    revision: str | None = None
+
+    @model_validator(mode="after")
+    def validate_range(self) -> "HistoryFactsQuery":
+        if not 0 <= (self.end - self.start).days <= 3660:
+            raise ValueError("History facts range must be between zero and ten years")
+        return self
+
+
+class HistoryFacts(BaseModel):
+    revision: str
+    instrument: InstrumentResponse
+    calendar: list[TradingCalendarDayResponse]
+    trading_rules: list[TradingRuleResponse]
+    daily_facts: list[DailyFactResponse]
+    adjustment_factors: list[AdjustmentFactorResponse]
+    corporate_actions: list[CorporateActionResponse]

pqdata/schema/pit_daily_window.py

@@ -0,0 +1,16 @@
+"""Market-owned daily price windows for downstream PIT calculations."""
+
+from datetime import date
+
+from pydantic import BaseModel, ConfigDict
+
+from pqdata.schema.adjustment_schema import AdjustedBarResponse
+
+
+class PITDailyWindow(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    as_of: date
+    anchor_date: date
+    bars: tuple[AdjustedBarResponse, ...]
+    input_digest: str

pqdata/schema/query_schema.py

@@ -0,0 +1,53 @@
+"""研究与历史数据读取的显式请求契约。"""
+
+from datetime import date
+
+from pydantic import AwareDatetime, BaseModel, Field, model_validator
+
+from pqdata.schema.adjustment_schema import BarViewRequest
+from pqdata.schema.bar_schema import BarFrequency
+
+
+class InstrumentRangeQuery(BaseModel):
+    instrument_ids: list[str] = Field(min_length=1, max_length=10000)
+    start: date
+    end: date
+
+    @model_validator(mode="after")
+    def validate_range(self) -> "InstrumentRangeQuery":
+        if self.start > self.end:
+            raise ValueError("start must not be after end")
+        return self
+
+
+class BarWindowQuery(BaseModel):
+    instrument_id: str
+    frequency: BarFrequency
+    start: AwareDatetime | None = None
+    end: AwareDatetime | None = None
+    limit: int = Field(default=1000, ge=1, le=100000)
+    view: BarViewRequest | None = None
+
+
+class PITWindowQuery(BaseModel):
+    instrument_id: str
+    days: list[date] = Field(min_length=1, max_length=2000)
+    next_days: list[date] = Field(min_length=1, max_length=2000)
+    lookback: int = Field(ge=1, le=2000)
+
+    @model_validator(mode="after")
+    def validate_days(self) -> "PITWindowQuery":
+        if len(self.days) != len(self.next_days):
+            raise ValueError("days and next_days must have equal length")
+        if self.days != sorted(set(self.days)):
+            raise ValueError("days must be strictly increasing")
+        if any(next_day <= day for day, next_day in zip(self.days, self.next_days, strict=True)):
+            raise ValueError("next_days must follow corresponding days")
+        return self
+
+
+class DataHealthQuery(BaseModel):
+    instrument_id: str
+    frequency: BarFrequency = "1d"
+    start: AwareDatetime
+    end: AwareDatetime

pqdata/schema/quote_schema.py

@@ -0,0 +1,73 @@
+"""
+Market Schema - Quote / DailyBasic / Sector 的响应模型
+"""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class QuoteResponse(BaseModel):
+    """最新行情快照响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    timestamp: datetime = Field(..., description="快照时间（事件时间）")
+    last: Decimal = Field(..., description="最新价")
+    open: Decimal | None = Field(None, description="今日开盘价")
+    high: Decimal | None = Field(None, description="今日最高价")
+    low: Decimal | None = Field(None, description="今日最低价")
+    previous_close: Decimal | None = Field(None, description="昨收价")
+    volume: int = Field(..., description="累计成交量（share）")
+    amount: Decimal | None = Field(None, description="累计成交额（CNY）")
+    bid_price_1: Decimal | None = Field(None, description="买一价")
+    bid_volume_1: int | None = Field(None, description="买一量（share）")
+    ask_price_1: Decimal | None = Field(None, description="卖一价")
+    ask_volume_1: int | None = Field(None, description="卖一量（share）")
+    status: str | None = Field(None, description="交易状态")
+
+
+class DailyBasicResponse(BaseModel):
+    """日频基础指标响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    trade_date: date = Field(..., description="交易日")
+    turnover_rate: Decimal | None = Field(None, description="换手率（%，1.23=1.23%）")
+    turnover_rate_free: Decimal | None = Field(None, description="自由流通换手率（%）")
+    volume_ratio: Decimal | None = Field(None, description="量比")
+    pe: Decimal | None = Field(None, description="市盈率（NULL=不可计算，如亏损）")
+    pe_ttm: Decimal | None = Field(None, description="市盈率TTM")
+    pb: Decimal | None = Field(None, description="市净率")
+    ps: Decimal | None = Field(None, description="市销率")
+    ps_ttm: Decimal | None = Field(None, description="市销率TTM")
+    dividend_yield: Decimal | None = Field(None, description="股息率（%）")
+    dividend_yield_ttm: Decimal | None = Field(None, description="股息率TTM（%）")
+    total_shares: Decimal | None = Field(None, description="总股本（share）")
+    float_shares: Decimal | None = Field(None, description="流通股本（share）")
+    free_float_shares: Decimal | None = Field(None, description="自由流通股本（share）")
+    total_market_cap: Decimal | None = Field(None, description="总市值（CNY）")
+    circulating_market_cap: Decimal | None = Field(None, description="流通市值（CNY）")
+
+
+class SectorResponse(BaseModel):
+    """板块响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    sector_id: str = Field(..., description="Canonical板块ID")
+    name: str = Field(..., description="名称")
+    sector_type: str = Field(..., description="类型")
+    source: str = Field(..., description="分类体系来源")
+
+
+class SectorMembershipResponse(BaseModel):
+    """标的-板块关系响应"""
+
+    instrument_id: str = Field(..., description="Canonical标的ID")
+    sector_id: str = Field(..., description="Canonical板块ID")
+    effective_from: date = Field(..., description="生效日期（含）")
+    effective_to: date | None = Field(None, description="失效日期（含）；NULL=当前有效")

pqdata/schema/reference_schema.py

@@ -0,0 +1,48 @@
+"""标的、交易规则与日历的公开数据响应。"""
+
+from datetime import date
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class InstrumentResponse(BaseModel):
+    """标的响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+    instrument_id: str = Field(..., description="Canonical标的ID，如CN.XSHE.000001")
+    symbol: str = Field(..., description="交易代码")
+    name: str = Field(..., description="名称")
+    instrument_type: str = Field(..., description="标的类型")
+    exchange: str = Field(..., description="交易所")
+    board: str | None = Field(None, description="板块")
+    currency: str = Field(..., description="计价货币")
+    status: str = Field(..., description="状态")
+    listed_date: date | None = Field(None, description="上市日期")
+    delisted_date: date | None = Field(None, description="退市日期")
+
+
+class TradingRuleResponse(BaseModel):
+    """某标的在一个业务日期区间内生效的交易规则。"""
+
+    model_config = ConfigDict(from_attributes=True, frozen=True)
+    instrument_id: str
+    effective_from: date
+    effective_to: date | None = None
+    min_buy_quantity: int = Field(..., gt=0)
+    buy_quantity_step: int = Field(..., gt=0)
+    min_sell_quantity: int = Field(..., gt=0)
+    sell_quantity_step: int = Field(..., gt=0)
+    tick_size: Decimal = Field(..., gt=0)
+    settlement_days: int = Field(..., ge=0)
+
+
+class TradingCalendarDayResponse(BaseModel):
+    """交易日历响应"""
+
+    model_config = ConfigDict(from_attributes=True)
+    exchange: str = Field(..., description="交易所")
+    trade_date: date = Field(..., description="日期")
+    is_open: bool = Field(..., description="是否交易日")
+    previous_open_date: date | None = Field(None, description="上一个交易日")
+    next_open_date: date | None = Field(None, description="下一个交易日")

pqdata/schema/reliability_schema.py

@@ -0,0 +1,152 @@
+"""
+Market Data Reliability Schema - Sync 结果与 Dataset 健康契约
+
+SSOT 语义见 SPEC「Market Data 可靠性」与 DATA-DICTIONARY §5。
+核心原则：
+- "同步成功" != Provider 请求成功；必须 = 转换成功 + 数据合法 + 无重复 +
+  目标区间完整 + 结果可追溯（MarketSyncResult 结构化表达）。
+- Verify 只证明 "Observed Canonical Data 是否覆盖 Expected Timeline"，
+  不负责猜测 Missing 的业务原因（停牌/零成交属 Trading Status，future）。
+"""
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SyncIssueCode(str, Enum):
+    """结构化问题码（issues 摘要用，禁止只返回 "sync success" 文本）"""
+
+    INVALID_OHLC = "INVALID_OHLC"
+    NON_POSITIVE_PRICE = "NON_POSITIVE_PRICE"
+    NEGATIVE_VOLUME = "NEGATIVE_VOLUME"
+    NEGATIVE_AMOUNT = "NEGATIVE_AMOUNT"
+    INVALID_TIMESTAMP = "INVALID_TIMESTAMP"
+    INVALID_INSTRUMENT_ID = "INVALID_INSTRUMENT_ID"
+    INVALID_TRADING_DAY = "INVALID_TRADING_DAY"  # 交易日语义违反 TradingCalendar
+    MISSING_BAR = "MISSING_BAR"  # Expected Timeline 上的缺口（unexplained）
+    MISSING_ADJUSTMENT_FACTOR = "MISSING_ADJUSTMENT_FACTOR"
+    MISSING_DATASET_COVERAGE = "MISSING_DATASET_COVERAGE"
+    DUPLICATE_BAR = "DUPLICATE_BAR"  # 同批内重复（唯一键冲突，跳过）
+    PROVIDER_ERROR = "PROVIDER_ERROR"
+
+
+class SyncStatus(str, Enum):
+    """Sync 结果状态
+
+    SUCCESS = 目标同步区间成功且验证通过；
+    PARTIAL = 有数据写入，但存在缺口或非法数据；
+    FAILED  = 同步任务无法形成可用结果。
+    不因为写入了一部分数据就返回 SUCCESS。
+    """
+
+    SUCCESS = "SUCCESS"
+    PARTIAL = "PARTIAL"
+    FAILED = "FAILED"
+
+
+class SyncIssue(BaseModel):
+    """单条结构化问题摘要"""
+
+    code: SyncIssueCode
+    instrument_id: str | None = None
+    timestamp: datetime | None = None
+    detail: str | None = Field(None, description="补充说明（如失败原因原文）")
+
+
+class MarketSyncResult(BaseModel):
+    """Sync 稳定结果对象（可追溯：请求区间 + 各阶段计数 + 状态 + 问题摘要）
+
+    字段按真实实现裁剪：V1 Provider 为 ON CONFLICT DO NOTHING 幂等 upsert，
+    updated_count 恒为 0（重复数据走 skipped）。
+    """
+
+    dataset: str
+    provider: str | None = None
+    instrument_id: str | None = Field(None, description="单标的同步时有值")
+    frequency: str | None = None
+    requested_start: date | None = None
+    requested_end: date | None = None
+    fetched_count: int = Field(0, description="Provider 返回条数")
+    normalized_count: int = Field(0, description="Mapper 转换成功条数")
+    inserted_count: int = Field(0, description="新插入条数")
+    updated_count: int = Field(0, description="更新条数（V1 幂等 upsert 恒为 0）")
+    skipped_count: int = Field(0, description="重复/无需写入条数")
+    invalid_count: int = Field(0, description="校验拒绝条数")
+    missing_count: int = Field(0, description="Completeness Check 发现的缺口数")
+    started_at: datetime
+    finished_at: datetime | None = None
+    status: SyncStatus = SyncStatus.FAILED
+    issues: list[SyncIssue] = Field(default_factory=list, description="结构化问题摘要（限量）")
+
+
+class DatasetHealth(str, Enum):
+    """Dataset 健康状态（Verify 产出）
+
+    HEALTHY    = 请求区间完整且合法，可以消费；
+    PARTIAL    = 有数据但目标区间存在缺口（unexplained missing，含疑似停牌日）；
+    STALE      = 结构正确且完整，但未更新到要求的新鲜度（V1 不产出，预留枚举位）；
+    INVALID    = 存在违反 Canonical 数据规则的数据；
+    NOT_SYNCED = 请求区间基本没有本地数据。
+    """
+
+    HEALTHY = "HEALTHY"
+    PARTIAL = "PARTIAL"
+    STALE = "STALE"
+    INVALID = "INVALID"
+    NOT_SYNCED = "NOT_SYNCED"
+
+
+class DatasetHealthResult(BaseModel):
+    """Verify 结果（只检查，绝不触发 Sync）
+
+    完整性验证单位：instrument_id + frequency + requested time range。
+    missing 明细只返回限量样本（missing_count 是权威计数）。
+    """
+
+    dataset: str
+    instrument_id: str
+    frequency: str
+    requested_start: datetime
+    requested_end: datetime
+    health: DatasetHealth
+    expected_count: int = Field(0, description="Expected Timeline 应有 Bar 数")
+    actual_count: int = Field(0, description="本地实际 Bar 数")
+    missing_count: int = 0
+    invalid_count: int = 0
+    latest_timestamp: datetime | None = None
+    dataset_revision: str | None = Field(
+        None, description="本次验证所见内容版本；必须进入缓存键/回测结果"
+    )
+    issues: list[SyncIssue] = Field(default_factory=list)
+
+
+def issue_code_from_reason(reason: str) -> SyncIssueCode:
+    """Validator 失败原因字符串 → 结构化问题码（未知原因归入 INVALID_OHLC）"""
+    mapping: dict[str, SyncIssueCode] = {
+        "high_lt_max_open_close": SyncIssueCode.INVALID_OHLC,
+        "low_gt_min_open_close": SyncIssueCode.INVALID_OHLC,
+        "non_positive_price": SyncIssueCode.NON_POSITIVE_PRICE,
+        "negative_volume": SyncIssueCode.NEGATIVE_VOLUME,
+        "negative_amount": SyncIssueCode.NEGATIVE_AMOUNT,
+        "naive_timestamp": SyncIssueCode.INVALID_TIMESTAMP,
+        "invalid_instrument_id": SyncIssueCode.INVALID_INSTRUMENT_ID,
+    }
+    return mapping.get(reason, SyncIssueCode.INVALID_OHLC)
+
+
+def to_issue(reason: str, instrument_id: str, timestamp: datetime | None) -> SyncIssue:
+    """Validator 失败原因 → SyncIssue 的统一入口"""
+    return SyncIssue(
+        code=issue_code_from_reason(reason),
+        instrument_id=instrument_id,
+        timestamp=timestamp,
+        detail=reason,
+    )
+
+
+def health_payload(result: DatasetHealthResult) -> dict[str, Any]:
+    """DatasetHealthResult 的可 JSON 化视图（API/日志复用）"""
+    return result.model_dump(mode="json")

quant_cli/api.py

@@ -0,0 +1,39 @@
+"""Stable local Python use cases; importing performs no I/O."""
+
+from quant_core.app.factor.schema.local_factor_schema import LocalFactorRequest
+
+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.data.schema.dataset_request_schema import DatasetPrepareRequest
+from quant_cli.app.data.service.dataset_load_service import load_dataset
+from quant_cli.app.data.service.dataset_prepare_service import prepare_dataset
+from quant_cli.app.factor.local_factor_dependency import (
+    build_local_factor_store,
+    build_local_selection_store,
+)
+from quant_cli.app.factor.schema.local_selection_schema import (
+    LocalSelectionFactor,
+    LocalSelectionRequest,
+)
+from quant_cli.app.factor.service.local_factor_service import compute_local_factor, run_local_factor
+from quant_cli.app.factor.service.local_selection_service import (
+    compute_local_selection,
+    run_local_selection,
+)
+
+__all__ = [
+    "build_local_factor_store",
+    "build_local_selection_store",
+    "DatasetPrepareRequest",
+    "LocalBacktestRequest",
+    "prepare_dataset",
+    "load_dataset",
+    "LocalFactorRequest",
+    "LocalSelectionFactor",
+    "LocalSelectionRequest",
+    "compute_local_factor",
+    "run_local_factor",
+    "compute_local_selection",
+    "run_local_selection",
+    "run_local_backtest",
+]

quant_cli/app/backtest/cli/local_backtest_cli.py

@@ -0,0 +1,72 @@
+"""本地策略回测命令；不加载管理数据库入口。"""
+
+import asyncio
+from pathlib import Path
+from typing import Annotated
+from uuid import UUID
+
+import typer
+
+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.utils.cli_utils import cli_errors, output
+
+app = typer.Typer(help="本地策略回测", no_args_is_help=True)
+
+
+@app.command("run")
+@cli_errors
+def run(
+    config: Annotated[Path, typer.Option(exists=True)],
+    source: Annotated[Path | None, typer.Option(exists=True)] = None,
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    import json
+
+    payload = json.loads(config.read_text(encoding="utf-8"))
+    if source is not None:
+        payload["source"] = source.read_text(encoding="utf-8")
+    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)
+
+
+@app.command("get")
+@cli_errors
+def get(
+    run: Annotated[UUID, typer.Option()],
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    output(build_local_backtest_store(database).get(run))
+
+
+@app.command("list")
+@cli_errors
+def list_runs(
+    limit: int = 20,
+    offset: int = 0,
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    output(
+        [
+            row.model_dump(mode="json")
+            for row in build_local_backtest_store(database).list_runs(limit, offset)
+        ]
+    )
+
+
+@app.command("compare")
+@cli_errors
+def compare(
+    run: Annotated[list[UUID], typer.Option()],
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    """比较多次本地回测。"""
+    from quant_cli.app.backtest.service.local_backtest_service import compare_backtest_records
+
+    store = build_local_backtest_store(database)
+    output(compare_backtest_records(tuple(store.get(key) for key in run)))

quant_cli/app/backtest/local_backtest_dependency.py

@@ -0,0 +1,10 @@
+"""本地回测归档组装。"""
+
+from pathlib import Path
+
+from quant_cli.app.backtest.repository.backtest_local_repository import BacktestLocalRepository
+
+
+def build_local_backtest_store(path: Path) -> BacktestLocalRepository:
+    """返回本地回测存取。"""
+    return BacktestLocalRepository(path)

quant_cli/app/backtest/local_backtest_schema.py

@@ -0,0 +1,49 @@
+"""本地回测输入，策略源码与数据快照显式提供。"""
+
+from decimal import Decimal
+from pathlib import Path
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from quant_core.app.backtest.schema import BacktestConfig
+from quant_core.app.data.schema.adjustment_schema import BarViewRequest
+from quant_core.app.strategy.schema.strategy_publication_schema import PublishedStrategy
+
+
+class LocalBacktestRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    config: BacktestConfig
+    source: str = ""
+    publication: PublishedStrategy | None = None
+    factor_view: BarViewRequest = Field(default_factory=BarViewRequest)
+    exclude_st: bool = False
+    manifest_path: Path
+    parameters: dict = Field(default_factory=dict)
+    factor_run_uuid: UUID | None = None
+    factor_artifact_path: Path | None = None
+    slippage_bps: Decimal = Field(default=Decimal(0), ge=0, allow_inf_nan=False)
+    max_rows: int = Field(default=1000000, ge=1)
+
+    @model_validator(mode="after")
+    def one_factor_source(self) -> "LocalBacktestRequest":
+        if bool(self.source) == (self.publication is not None):
+            raise ValueError("必须且只能提供本地策略源码或已发布策略")
+        if self.publication is not None:
+            spec = self.publication.definition
+            if spec.strategy_id != self.config.strategy_id:
+                raise ValueError("回测策略 ID 与发布定义不同")
+            if self.parameters and self.parameters != spec.parameters:
+                raise ValueError("发布策略参数不可静默覆盖，请发布新版本")
+            if spec.universe and set(spec.universe) != set(self.config.instrument_ids):
+                raise ValueError("股票池与发布策略不同")
+            if not spec.factor_refs and (self.factor_run_uuid or self.factor_artifact_path):
+                raise ValueError("发布策略未声明因子依赖，不能注入因子结果")
+        if self.factor_run_uuid and self.factor_artifact_path:
+            raise ValueError("因子运行和独立产物只能指定一种")
+        return self
+
+    @field_validator("manifest_path")
+    @classmethod
+    def absolute_manifest(cls, value: Path) -> Path:
+        """归档固定路径，避免重启后工作目录变化影响定位。"""
+        return value.expanduser().resolve()

quant_cli/app/backtest/repository/backtest_local_repository.py

@@ -0,0 +1,67 @@
+"""backtest 本地运行存取；短事务由本地连接上下文管理。"""
+
+from pathlib import Path
+from uuid import UUID
+
+from quant_core.common.local_run import LocalRunRecord
+
+from quant_cli.common.database.duckdb_connection import local_transaction
+
+
+class BacktestLocalRepository:
+    """只维护本领域的运行记录，查询使用数据库分页。"""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def save(self, record: LocalRunRecord) -> None:
+        with local_transaction(self.path) as connection:
+            connection.execute("""CREATE TABLE IF NOT EXISTS backtest_local_run (
+                id BIGINT PRIMARY KEY, uuid UUID UNIQUE NOT NULL,
+                created_at TIMESTAMPTZ NOT NULL, document JSON NOT NULL)""")
+            existing = connection.execute(
+                "SELECT document FROM backtest_local_run WHERE uuid = ?", [str(record.uuid)]
+            ).fetchone()
+            if existing is not None:
+                if LocalRunRecord.model_validate_json(existing[0]) != record:
+                    raise ValueError("同一运行 UUID 的记录不可覆盖")
+                return
+            connection.execute(
+                """INSERT INTO backtest_local_run
+                SELECT COALESCE(MAX(id), 0) + 1, ?, ?, ? FROM backtest_local_run""",
+                [str(record.uuid), record.created_at, record.model_dump_json()],
+            )
+
+    def get(self, run_uuid: UUID) -> LocalRunRecord:
+        if not self.path.is_file():
+            raise ValueError("运行记录不存在")
+        with local_transaction(self.path, read_only=True) as connection:
+            if not connection.execute(
+                "SELECT 1 FROM information_schema.tables WHERE table_name = ?",
+                ["backtest_local_run"],
+            ).fetchall():
+                raise ValueError("运行记录不存在")
+            row = connection.execute(
+                "SELECT document FROM backtest_local_run WHERE uuid = ?", [str(run_uuid)]
+            ).fetchone()
+        if row is None:
+            raise ValueError("运行记录不存在")
+        return LocalRunRecord.model_validate_json(row[0])
+
+    def list_runs(self, limit: int = 20, offset: int = 0) -> list[LocalRunRecord]:
+        if not 1 <= limit <= 1000 or offset < 0:
+            raise ValueError("分页参数非法")
+        if not self.path.is_file():
+            return []
+        with local_transaction(self.path, read_only=True) as connection:
+            if not connection.execute(
+                "SELECT 1 FROM information_schema.tables WHERE table_name = ?",
+                ["backtest_local_run"],
+            ).fetchall():
+                return []
+            rows = connection.execute(
+                """SELECT document FROM backtest_local_run
+                ORDER BY id DESC LIMIT ? OFFSET ?""",
+                [limit, offset],
+            ).fetchall()
+        return [LocalRunRecord.model_validate_json(row[0]) for row in rows]