powerquant-cli 0.2.6__py3-none-any.whl

quant_cli/app/factor/service/local_selection_service.py

@@ -0,0 +1,139 @@
+"""离线选股用例：资格与快照校验在应用层，评分只调用核心。"""
+
+from datetime import datetime, time
+from zoneinfo import ZoneInfo
+
+from quant_core.app.factor.factor_dependency import build_factor_selection
+from quant_core.app.factor.interface.public.factor_local import LocalFactorStore
+from quant_core.app.factor.schema.selection_report import build_selection_report
+from quant_core.app.factor.schema.selection_types import (
+    FactorWeight,
+    NeutralizationMethod,
+    SelectionDefinition,
+)
+from quant_core.common.local_run import LocalRunRecord, RunStatus, content_digest
+
+from quant_cli.app.data.service.dataset_load_service import load_dataset
+from quant_cli.app.factor.interface.local_selection_store import LocalSelectionStore
+from quant_cli.app.factor.schema.local_selection_schema import LocalSelectionRequest
+from quant_cli.app.factor.service.local_factor_query_service import build_local_factor_query
+from quant_cli.app.factor.service.local_factor_service import load_factor_result
+
+
+async def compute_local_selection(
+    request: LocalSelectionRequest,
+    factor_store: LocalFactorStore,
+) -> LocalRunRecord:
+    """计算不创建连接；使用单一运行和单一完整行情快照。"""
+    record = LocalRunRecord(request=request.model_dump(mode="json"))
+    try:
+        market, _ = load_dataset(request.manifest_path, request.max_rows)
+        digest = content_digest(request.manifest_path.read_text(encoding="utf-8"))
+        factor_run, values = load_factor_result(factor_store, request.factor_run_uuid)
+        if factor_run.provenance.get("manifest_digest") != digest:
+            raise ValueError("因子与选股输入快照不同")
+        if factor_run.provenance.get("market_revision") != market.revision:
+            raise ValueError("因子与选股行情修订不同")
+        if not set(request.instrument_ids).issubset(factor_run.request.get("instrument_ids", ())):
+            raise ValueError("选股股票池不属于因子运行")
+        if (
+            not market.start.astimezone(ZoneInfo("Asia/Shanghai")).date()
+            <= request.target_as_of
+            <= market.end.astimezone(ZoneInfo("Asia/Shanghai")).date()
+        ):
+            raise ValueError("选股日期超出已准备快照")
+        query, aliases = await build_local_factor_query(
+            factor_run, values, market, market.end.date()
+        )
+        if any(f.name not in aliases for f in request.factors):
+            raise ValueError("因子运行不包含所需名称")
+        if any(f.transform.neutralization != NeutralizationMethod.NONE for f in request.factors):
+            raise ValueError("当前快照未准备行业/市值暴露，不能执行中性化")
+        definition = SelectionDefinition(
+            factors=tuple(
+                FactorWeight(aliases[f.name], f.weight, f.direction, f.transform)
+                for f in request.factors
+            ),
+            top_n=request.top_n,
+            missing_policy=request.missing_policy,
+        )
+        universe = []
+        exclusions = []
+        for iid in sorted(request.instrument_ids):
+            info = await market.get_instrument(iid)
+            reason = None
+            if info.listed_date is None:
+                reason = "unknown_listing"
+            elif info.listed_date > request.target_as_of or (
+                info.delisted_date and info.delisted_date < request.target_as_of
+            ):
+                reason = "not_listed"
+            facts = await market.list_daily_facts(iid, request.target_as_of, request.target_as_of)
+            if len(facts) != 1:
+                reason = reason or "unknown_status"
+            else:
+                fact = facts[0]
+                if request.exclude_st:
+                    if fact.special_type is None:
+                        reason = reason or "unknown_special_treatment"
+                    elif fact.is_st:
+                        reason = reason or "special_treatment"
+                if request.exclude_suspended:
+                    if fact.suspension_status is None:
+                        reason = reason or "unknown_suspension"
+                    elif fact.suspension_status != "none":
+                        reason = reason or "suspended"
+                if request.exclude_limit_up:
+                    cn = ZoneInfo("Asia/Shanghai")
+                    bars = await market.list_bars(
+                        iid,
+                        "1d",
+                        max(market.start, datetime.combine(request.target_as_of, time.min, cn)),
+                        min(market.end, datetime.combine(request.target_as_of, time.max, cn)),
+                        limit=2,
+                    )
+                    if fact.limit_up is None or len(bars) != 1:
+                        reason = reason or "unknown_price_limit"
+                    elif bars[0].close >= fact.limit_up:
+                        reason = reason or "at_limit_up"
+            if reason:
+                exclusions.append({"instrument_id": iid, "reason": reason})
+            else:
+                universe.append(iid)
+        snapshot = await query.get_snapshot(
+            [f.identity for f in definition.factors],
+            universe,
+            request.decision_time,
+            target_as_of=request.target_as_of,
+            dataset_revision=str(factor_run.uuid),
+        )
+        result = build_factor_selection().select(definition, universe, snapshot)
+        report = build_selection_report(definition, universe, snapshot, result).model_dump(
+            mode="json"
+        )
+        report["qualification_excluded"] = exclusions
+        report["requested_universe_size"] = len(request.instrument_ids)
+        record.provenance = {
+            "manifest_digest": digest,
+            "market_revision": market.revision,
+            "factor_run_uuid": str(factor_run.uuid),
+            "input_digest": factor_run.provenance["input_digest"],
+            "definition_digest": factor_run.provenance["definition_digest"],
+            "selection_request_digest": content_digest(request.model_dump_json()),
+            "facts_basis": "current_revision_history; historical knowledge revisions unavailable",
+        }
+        record.result = report
+    except Exception as exc:
+        record.status, record.error = RunStatus.FAILED, str(exc)
+    return record
+
+
+async def run_local_selection(
+    request: LocalSelectionRequest,
+    factor_store: LocalFactorStore,
+    selection_store: LocalSelectionStore,
+) -> LocalRunRecord:
+    """完成计算后短事务归档；保存失败向调用方传播。"""
+    record = await compute_local_selection(request, factor_store)
+    selection_store.save(record)
+    return record

quant_cli/app/job/cli/local_job_cli.py

@@ -0,0 +1,69 @@
+"""独立 Worker 命令，不实现调度中心。"""
+
+import asyncio
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from quant_core.common.local_run import RunStatus
+
+from quant_cli.app.job.schema.local_job_schema import LocalJobRequest
+from quant_cli.app.job.service.local_job_service import execute_local_job
+from quant_cli.common.constants import DEFAULT_DATABASE_PATH
+from quant_cli.common.utils.cli_utils import cli_errors, output
+
+app = typer.Typer(help="独立 Worker 执行与产物输出", no_args_is_help=True)
+
+
+@app.command("execute")
+@cli_errors
+def execute(
+    config: Annotated[Path, typer.Option(exists=True)], output_dir: Annotated[Path, typer.Option()]
+) -> None:
+    record, path = asyncio.run(
+        execute_local_job(
+            LocalJobRequest.model_validate_json(config.read_text(encoding="utf-8")), output_dir
+        )
+    )
+    output({"run_uuid": str(record.uuid), "status": record.status.value, "artifact": str(path)})
+    if record.status == RunStatus.FAILED:
+        raise typer.Exit(1)
+
+
+@app.command("import")
+@cli_errors
+def import_artifact(
+    artifact: Annotated[Path, typer.Option(exists=True)],
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    """单一归档进程导入 Worker 结果，拒绝损坏或未知格式。"""
+    import json
+
+    from quant_core.common.local_run import LocalRunRecord, content_digest
+
+    from quant_cli.app.backtest.local_backtest_dependency import build_local_backtest_store
+    from quant_cli.app.factor.local_factor_dependency import (
+        build_local_factor_store,
+        import_factor_artifact,
+    )
+    from quant_cli.app.research.local_research_dependency import build_local_research_store
+
+    text = artifact.read_text(encoding="utf-8")
+    envelope = json.loads(text)
+    if envelope.get("format_version") != 1:
+        raise ValueError("不支持的产物版本")
+    canonical = json.dumps(envelope["payload"], sort_keys=True, ensure_ascii=False, allow_nan=False)
+    if envelope.get("sha256") != content_digest(canonical):
+        raise ValueError("产物摘要不匹配")
+    kind = envelope.get("kind")
+    if kind == "factor":
+        record = import_factor_artifact(text, build_local_factor_store(database))
+    elif kind in ("research", "backtest"):
+        record = LocalRunRecord.model_validate(envelope["payload"]["record"])
+        if kind == "research":
+            build_local_research_store(database).save(record)
+        else:
+            build_local_backtest_store(database).save(record)
+    else:
+        raise ValueError("不支持的产物类型")
+    output(record)

quant_cli/app/job/schema/local_job_schema.py

@@ -0,0 +1,11 @@
+"""调度无关的本地 Worker 请求。"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+class LocalJobRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    kind: Literal["factor", "research", "backtest"]
+    request: dict

quant_cli/app/job/service/local_job_service.py

@@ -0,0 +1,60 @@
+"""调度无关的 Worker 执行入口；只写独立产物，不写共享 DuckDB。"""
+
+import json
+from pathlib import Path
+
+from quant_core.app.factor.schema.factor_artifact_schema import FactorArtifact, FactorArtifactValue
+from quant_core.app.factor.schema.local_factor_schema import LocalFactorRequest
+from quant_core.common.local_run import LocalRunRecord, content_digest
+
+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 compute_local_factor
+from quant_cli.app.job.schema.local_job_schema import LocalJobRequest
+from quant_cli.app.research.schema.local_research_schema import LocalPythonResearchRequest
+from quant_cli.app.research.service.local_research_execution_service import run_local_research
+
+
+async def execute_local_job(job: LocalJobRequest, output_dir: Path) -> tuple[LocalRunRecord, Path]:
+    """执行独立任务并原子发布产物；上层调度负责重试、领取与状态登记。"""
+    if job.kind == "factor":
+        record, values = await compute_local_factor(LocalFactorRequest.model_validate(job.request))
+        payload = FactorArtifact(
+            record=record,
+            values=tuple(
+                FactorArtifactValue(
+                    name=name, as_of=timestamp, instrument_id=instrument, value=value
+                )
+                for name, cells in values.items()
+                for (timestamp, instrument), value in cells.items()
+            ),
+        ).model_dump(mode="json")
+    elif job.kind == "research":
+        research = LocalPythonResearchRequest.model_validate(job.request)
+        record = await run_local_research(
+            research.research,
+            research.manifest_path,
+            research.max_rows,
+            factor_artifact_path=research.factor_artifact_path,
+        )
+        payload = {"record": record.model_dump(mode="json")}
+    else:
+        request = LocalBacktestRequest.model_validate(job.request)
+        if request.factor_run_uuid is not None:
+            raise ValueError("离线 Worker 回测需先提供独立因子产物，不能读取共享研究库")
+        record = await run_local_backtest(request)
+        payload = {"record": record.model_dump(mode="json")}
+    text = json.dumps(payload, sort_keys=True, ensure_ascii=False, allow_nan=False)
+    envelope = {
+        "format_version": 1,
+        "kind": job.kind,
+        "sha256": content_digest(text),
+        "payload": payload,
+    }
+    output_dir.mkdir(parents=True, exist_ok=True)
+    target = output_dir / f"{record.uuid}.json"
+    temporary = target.with_suffix(".tmp")
+    with temporary.open("x", encoding="utf-8") as stream:
+        json.dump(envelope, stream, ensure_ascii=False, allow_nan=False)
+    temporary.replace(target)
+    return record, target

quant_cli/app/quant_cli.py

@@ -0,0 +1,49 @@
+"""Quant 统一命令注册；领域业务逻辑留在所属模块。"""
+
+import shutil
+from importlib.resources import files
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from quant_cli.app.backtest.cli.local_backtest_cli import app as backtest
+from quant_cli.app.data.cli.data_cli import app as data
+from quant_cli.app.factor.cli.local_factor_cli import app as factor
+from quant_cli.app.job.cli.local_job_cli import app as job
+from quant_cli.app.research.cli.local_research_cli import app as research
+from quant_cli.app.strategy.cli.strategy_cli import app as strategy
+from quant_cli.common.utils.platform_utils import configure_utf8_output
+
+app = typer.Typer(help="Power Quant 本地研究与计算", no_args_is_help=True)
+app.add_typer(data, name="data")
+app.add_typer(job, name="job")
+app.add_typer(factor, name="factor")
+app.add_typer(research, name="research")
+app.add_typer(backtest, name="backtest")
+app.add_typer(strategy, name="strategy")
+
+
+@app.command()
+def examples(
+    directory: Annotated[Path, typer.Option("--directory")] = Path("powerquant-examples"),
+) -> None:
+    """导出随包示例到新目录，保留现有文件避免覆盖用户配置。"""
+    if directory.exists():
+        raise typer.BadParameter("目标目录已存在，请指定新目录")
+    source = files("quant_cli").joinpath("examples")
+    if not source.is_dir():
+        # 开发源码入口与 wheel 都引用同一份 examples，不生成重复示例。
+        source = Path(__file__).resolve().parents[3] / "examples"
+    shutil.copytree(str(source), directory)
+    typer.echo(str(directory.resolve()))
+
+
+def main() -> None:
+    """安装后的 pq 命令入口。"""
+    configure_utf8_output()
+    app()
+
+
+if __name__ == "__main__":
+    main()

quant_cli/app/research/cli/local_research_cli.py

@@ -0,0 +1,93 @@
+"""本地研究检验与比较命令。"""
+
+from pathlib import Path
+from typing import Annotated
+from uuid import UUID
+
+import typer
+from quant_core.app.factor.factor_dependency import build_factor_diagnostics
+
+from quant_cli.app.factor.local_factor_dependency import build_local_factor_store
+from quant_cli.app.research.local_research_dependency import build_local_research_store
+from quant_cli.app.research.schema.local_research_schema import LocalEvaluationRequest
+from quant_cli.app.research.service.local_research_service import (
+    compare_local_research,
+    evaluate_local_factor,
+)
+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("evaluate")
+@cli_errors
+def evaluate(
+    config: Annotated[Path, typer.Option(exists=True)],
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    request = LocalEvaluationRequest.model_validate_json(config.read_text(encoding="utf-8"))
+    record = evaluate_local_factor(
+        request, build_local_factor_store(database), build_factor_diagnostics()
+    )
+    build_local_research_store(database).save(record)
+    output(record)
+
+
+@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:
+    output(compare_local_research(build_local_research_store(database), tuple(run)))
+
+
+@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_research_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_research_store(database).list_runs(limit, offset)
+        ]
+    )
+
+
+@app.command("run")
+@cli_errors
+def run(
+    config: Annotated[Path, typer.Option(exists=True)],
+    manifest: Annotated[Path, typer.Option(exists=True)],
+    factor_run: Annotated[UUID | None, typer.Option()] = None,
+    max_rows: int = 1000000,
+    database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
+) -> None:
+    """执行可信研究 Python 请求，默认归档结果。"""
+    import asyncio
+
+    from quant_core.app.research.schema.research_schema import ResearchRunRequest
+
+    from quant_cli.app.research.service.local_research_execution_service import run_local_research
+
+    request = ResearchRunRequest.model_validate_json(config.read_text(encoding="utf-8"))
+    record = asyncio.run(
+        run_local_research(
+            request, manifest, max_rows, build_local_factor_store(database), factor_run
+        )
+    )
+    build_local_research_store(database).save(record)
+    output(record)

quant_cli/app/research/local_research_dependency.py

@@ -0,0 +1,10 @@
+"""本地研究组装。"""
+
+from pathlib import Path
+
+from quant_cli.app.research.repository.research_local_repository import ResearchLocalRepository
+
+
+def build_local_research_store(path: Path) -> ResearchLocalRepository:
+    """返回本地研究存取。"""
+    return ResearchLocalRepository(path)

quant_cli/app/research/repository/research_local_repository.py

@@ -0,0 +1,67 @@
+"""research 本地运行存取；短事务由本地连接上下文管理。"""
+
+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 ResearchLocalRepository:
+    """只维护本领域的运行记录，查询使用数据库分页。"""
+
+    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 research_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 research_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 research_local_run
+                SELECT COALESCE(MAX(id), 0) + 1, ?, ?, ? FROM research_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 = ?",
+                ["research_local_run"],
+            ).fetchall():
+                raise ValueError("运行记录不存在")
+            row = connection.execute(
+                "SELECT document FROM research_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 = ?",
+                ["research_local_run"],
+            ).fetchall():
+                return []
+            rows = connection.execute(
+                """SELECT document FROM research_local_run
+                ORDER BY id DESC LIMIT ? OFFSET ?""",
+                [limit, offset],
+            ).fetchall()
+        return [LocalRunRecord.model_validate_json(row[0]) for row in rows]

quant_cli/app/research/schema/local_research_schema.py

@@ -0,0 +1,26 @@
+"""本地研究输入：引用已归档因子运行，标签独立传入。"""
+
+from pathlib import Path
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+from quant_core.app.research.schema.dataset_schema import ResearchLabel
+from quant_core.app.research.schema.research_schema import ResearchRunRequest
+
+
+class LocalEvaluationRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    factor_run_uuid: UUID
+    factor_name: str
+    labels: tuple[ResearchLabel, ...]
+    quantiles: int = Field(default=5, ge=2, le=100)
+
+
+class LocalPythonResearchRequest(BaseModel):
+    """独立 Worker 的 Python 研究请求。"""
+
+    model_config = ConfigDict(extra="forbid")
+    research: ResearchRunRequest
+    manifest_path: Path
+    max_rows: int = Field(default=1000000, ge=1)
+    factor_artifact_path: Path | None = None

quant_cli/app/research/service/local_research_execution_service.py

@@ -0,0 +1,105 @@
+"""本地 Python 研究运行，复用管理入口的研究执行函数。"""
+
+from datetime import date
+from pathlib import Path
+from uuid import UUID
+
+from quant_core.app.factor.factor_dependency import build_factor_diagnostics, build_factor_selection
+from quant_core.app.factor.interface.public.factor_local import LocalFactorStore
+from quant_core.app.research.adapter.market_label_query import MarketLabelQuery
+from quant_core.app.research.schema.research_schema import ResearchRunRequest
+from quant_core.app.research.service.research_dataset_service import ResearchDatasetService
+from quant_core.app.research.service.research_evaluation_service import ResearchEvaluationService
+from quant_core.app.research.service.research_service import execute_research
+from quant_core.common.local_run import LocalRunRecord, RunStatus, content_digest
+
+from quant_cli.app.data.service.dataset_load_service import load_dataset
+from quant_cli.app.factor.local_factor_dependency import (
+    build_local_factor_query,
+    decode_factor_artifact,
+    load_factor_result,
+)
+from quant_cli.common.utils.runtime_environment import runtime_versions
+
+
+class SnapshotRevision:
+    """已加载快照的修订查询，不访问外部系统。"""
+
+    def __init__(self, revision: str, first: date, last: date) -> None:
+        self.revision, self.first, self.last = revision, first, last
+
+    async def snapshot(self, start: date, end: date) -> dict[str, str]:
+        if start < self.first or end > self.last:
+            raise ValueError("研究范围超出输入快照")
+        return {"market": self.revision}
+
+
+async def run_local_research(
+    request: ResearchRunRequest,
+    manifest: Path,
+    max_rows: int,
+    factor_store: LocalFactorStore | None = None,
+    factor_run_uuid: UUID | None = None,
+    factor_artifact_path: Path | None = None,
+) -> LocalRunRecord:
+    """显式研究源码、市场快照和可选因子运行，返回待归档记录。"""
+    manifest = manifest.expanduser().resolve()
+    record = LocalRunRecord(
+        request={
+            **request.model_dump(mode="json"),
+            "manifest_path": str(manifest),
+            "max_rows": max_rows,
+            "factor_artifact_path": str(factor_artifact_path.resolve())
+            if factor_artifact_path
+            else None,
+            "factor_run_uuid": str(factor_run_uuid) if factor_run_uuid else None,
+        },
+        provenance={"environment": runtime_versions()},
+    )
+    try:
+        market, _ = load_dataset(manifest, max_rows)
+        record.provenance.update(
+            manifest_digest=content_digest(manifest.read_text(encoding="utf-8")),
+            market_revision=market.revision,
+        )
+        factors = None
+        if factor_run_uuid and factor_artifact_path:
+            raise ValueError("只允许一个因子结果来源")
+        if factor_run_uuid or factor_artifact_path:
+            if factor_artifact_path:
+                factor_record, values = decode_factor_artifact(
+                    factor_artifact_path.read_text(encoding="utf-8")
+                )
+                if factor_record.status != RunStatus.COMPLETED:
+                    raise ValueError("因子产物未成功")
+            else:
+                if factor_store is None or factor_run_uuid is None:
+                    raise ValueError("因子运行需要显式读取能力")
+                factor_record, values = load_factor_result(factor_store, factor_run_uuid)
+            record.provenance["factor_run_uuid"] = str(factor_record.uuid)
+            if factor_record.provenance["market_revision"] != market.revision:
+                raise ValueError("研究与因子使用的行情修订不同")
+            factors, _ = await build_local_factor_query(
+                factor_record, values, market, market.end.date()
+            )
+        result = await execute_research(
+            request,
+            market,
+            SnapshotRevision(market.revision, market.start.date(), market.end.date()),
+            factors_query=factors,
+            dataset_factory=lambda factors: ResearchDatasetService(
+                factors, MarketLabelQuery(market)
+            ),
+            evaluation=ResearchEvaluationService(
+                build_factor_selection(), build_factor_diagnostics()
+            ),
+        )
+        record.result = result.model_dump(mode="json")
+        if result.error:
+            record.status, record.error = RunStatus.FAILED, result.error
+    except Exception as exc:
+        import logging
+
+        logging.getLogger(__name__).exception("本地研究执行失败")
+        record.status, record.error = RunStatus.FAILED, str(exc)
+    return record