powerquant-cli 0.2.10__tar.gz → 0.2.11__tar.gz

{powerquant_cli-0.2.10 → powerquant_cli-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: powerquant-cli
-Version: 0.2.10
+Version: 0.2.11
 Summary: Power Quant local research CLI
 Project-URL: Repository, https://github.com/Kepler452Byte/power-quant
 License-Expression: LicenseRef-PowerQuant-Proprietary AND MIT
@@ -96,10 +96,22 @@ pq init
 
 `pq init` 先返回安装计划。使用返回的 `data.expected_plan` 执行 `pq init --confirm --expected-plan <expected_plan>`，默认安装到 Codex 的 `~/.agents/skills` 和 Claude Code 的 `~/.claude/skills`。可用 `--agent codex|claude|both` 选择客户端，或用 `--skills-dir` 指定项目目录。Hint 仅写入显式提供的 `--hint-file`，保留受管块外的内容。
 
-没有 Token 也可以初始化；需要连接行情时，按 bootstrap Skill 申请权限并通过 `pq config token` 安全录入。行情运维通过 PQData API/MCP 提交任务。
+没有 Token 也可以初始化；需要连接行情时，按 bootstrap Skill 申请权限并通过 `pq config token` 安全录入。行情运维使用 `pq operations`，通过 PQData API 提交任务。
 
 `pq upgrade` 先预览，再用 `--confirm --expected-plan <expected_plan>` 启动后台升级；通过 `pq agent upgrade-status <operation_id>` 查询结果。升级沿用 uv tool 或 pipx 安装渠道，并同步已登记的资源目录。`pq upgrade --skip-package` 仅同步资源。独立资源同步使用 `pq agent sync`，同样先预览再确认。
 
+## 数据运维
+
+`pq operations` 使用与行情读取相同的 market_url、平台 Token，需 market:operate 权限。入口包括 status、datasets、plan、submit、jobs 和 publish，详细参数通过各级 --help 发现。
+
+```sh
+pq operations status --start 2026-10-13 --end 2026-10-13
+pq operations datasets list
+pq operations jobs list --status running
+```
+
+所有写命令先返回 planned 和 data.expected_plan，再使用相同参数加 --confirm --expected-plan 确认。plan 确认只保存服务端计划；核对返回分片范围后，用 plan_uuid 与显式幂等键提交。submit、retry、publish 返回 submitted，任务 ID 在 data.result.job_uuid；之后用 jobs show/steps 跟踪终态并复查覆盖和版本。API 超时不自动重试或换幂等键。默认不等待、不运行本地 Worker，也不调度 Coding Agent。
+
 ## 依赖生命周期
 
 ApplicationContainer 接收 ApplicationSettings，按需组装明确的因子、回测、研究应用 Service，CLI 从 ctx.obj 获取。Service 依赖由构造函数显式传入；不维护通用 Repository 缓存、不查询全局容器、不在缺少上下文时静默创建容器。MarketClient 按需创建并由调用方 async with 关闭，本地 Repository 使用短事务。配置、帮助和资源查看不初始化数据库或联网。

{powerquant_cli-0.2.10 → powerquant_cli-0.2.11}/README.md

@@ -74,10 +74,22 @@ pq init
 
 `pq init` 先返回安装计划。使用返回的 `data.expected_plan` 执行 `pq init --confirm --expected-plan <expected_plan>`，默认安装到 Codex 的 `~/.agents/skills` 和 Claude Code 的 `~/.claude/skills`。可用 `--agent codex|claude|both` 选择客户端，或用 `--skills-dir` 指定项目目录。Hint 仅写入显式提供的 `--hint-file`，保留受管块外的内容。
 
-没有 Token 也可以初始化；需要连接行情时，按 bootstrap Skill 申请权限并通过 `pq config token` 安全录入。行情运维通过 PQData API/MCP 提交任务。
+没有 Token 也可以初始化；需要连接行情时，按 bootstrap Skill 申请权限并通过 `pq config token` 安全录入。行情运维使用 `pq operations`，通过 PQData API 提交任务。
 
 `pq upgrade` 先预览，再用 `--confirm --expected-plan <expected_plan>` 启动后台升级；通过 `pq agent upgrade-status <operation_id>` 查询结果。升级沿用 uv tool 或 pipx 安装渠道，并同步已登记的资源目录。`pq upgrade --skip-package` 仅同步资源。独立资源同步使用 `pq agent sync`，同样先预览再确认。
 
+## 数据运维
+
+`pq operations` 使用与行情读取相同的 market_url、平台 Token，需 market:operate 权限。入口包括 status、datasets、plan、submit、jobs 和 publish，详细参数通过各级 --help 发现。
+
+```sh
+pq operations status --start 2026-10-13 --end 2026-10-13
+pq operations datasets list
+pq operations jobs list --status running
+```
+
+所有写命令先返回 planned 和 data.expected_plan，再使用相同参数加 --confirm --expected-plan 确认。plan 确认只保存服务端计划；核对返回分片范围后，用 plan_uuid 与显式幂等键提交。submit、retry、publish 返回 submitted，任务 ID 在 data.result.job_uuid；之后用 jobs show/steps 跟踪终态并复查覆盖和版本。API 超时不自动重试或换幂等键。默认不等待、不运行本地 Worker，也不调度 Coding Agent。
+
 ## 依赖生命周期
 
 ApplicationContainer 接收 ApplicationSettings，按需组装明确的因子、回测、研究应用 Service，CLI 从 ctx.obj 获取。Service 依赖由构造函数显式传入；不维护通用 Repository 缓存、不查询全局容器、不在缺少上下文时静默创建容器。MarketClient 按需创建并由调用方 async with 关闭，本地 Repository 使用短事务。配置、帮助和资源查看不初始化数据库或联网。

{powerquant_cli-0.2.10 → powerquant_cli-0.2.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "powerquant-cli"
-version = "0.2.10"
+version = "0.2.11"
 description = "Power Quant local research CLI"
 readme = "README.md"
 requires-python = ">=3.12"

powerquant_cli-0.2.11/src/quant_cli/app/operations/cli/operations_cli.py

@@ -0,0 +1,272 @@
+"""Platform operations commands: parse inputs, invoke service and emit JSON."""
+
+from datetime import date
+from typing import Annotated
+
+import typer
+
+from quant_cli.app.cli_dependency import container
+from quant_cli.app.operations.schema.operation_schema import (
+    Dataset,
+    DateRange,
+    Mode,
+    PageInput,
+    PlanInput,
+    PublishInput,
+    RetryInput,
+    SubmitInput,
+)
+from quant_cli.common.command_error_handler import CommandGroup
+from quant_cli.common.command_help import Command
+from quant_cli.common.utils.cli_utils import cli_errors, output
+
+app = typer.Typer(cls=CommandGroup, no_args_is_help=True, help="数据运维：查询、计划与异步任务")
+datasets = typer.Typer(cls=CommandGroup, no_args_is_help=True, help="数据集与覆盖版本查询")
+jobs = typer.Typer(cls=CommandGroup, no_args_is_help=True, help="运维任务与分片管理")
+app.add_typer(datasets, name="datasets")
+app.add_typer(jobs, name="jobs")
+OptionString = Annotated[str, typer.Option()]
+OptionalString = Annotated[str | None, typer.Option()]
+
+
+def query(offset: int, limit: int, **filters) -> dict:
+    return {
+        **PageInput(offset=offset, limit=limit).model_dump(),
+        **{key: value for key, value in filters.items() if value is not None},
+    }
+
+
+@app.command("status", cls=Command)
+@cli_errors
+def data_status(ctx: typer.Context, start: OptionString, end: OptionString) -> None:
+    """检查指定日期范围的数据证据与缺口，不推断完整性。"""
+    request = DateRange.model_validate({"start": start, "end": end})
+    output(container(ctx).operations_service.data_status(request.model_dump(mode="json")))
+
+
+@datasets.command("list", cls=Command)
+@cli_errors
+def list_datasets(
+    ctx: typer.Context,
+    keyword: OptionalString = None,
+    publication_status: OptionalString = None,
+    coverage_status: OptionalString = None,
+    offset: int = 0,
+    limit: int = 20,
+) -> None:
+    """分页查询数据集，筛选由服务端执行。"""
+    output(
+        container(ctx).operations_service.datasets(
+            query(
+                offset,
+                limit,
+                keyword=keyword,
+                publication_status=publication_status,
+                coverage_status=coverage_status,
+            )
+        )
+    )
+
+
+@datasets.command("show", cls=Command)
+@cli_errors
+def show_dataset(ctx: typer.Context, name: Dataset) -> None:
+    """查看数据集分区规则、数据范围与版本状态。"""
+    output(container(ctx).operations_service.dataset(name.value))
+
+
+@datasets.command("versions", cls=Command)
+@cli_errors
+def dataset_versions(ctx: typer.Context, name: Dataset, offset: int = 0, limit: int = 20) -> None:
+    """分页查询已发布的数据集版本。"""
+    output(container(ctx).operations_service.dataset(name.value, "versions", query(offset, limit)))
+
+
+@datasets.command("coverage", cls=Command)
+@cli_errors
+def dataset_coverage(
+    ctx: typer.Context,
+    name: Dataset,
+    start: OptionalString = None,
+    end: OptionalString = None,
+    instrument_id: OptionalString = None,
+    status: OptionalString = None,
+    offset: int = 0,
+    limit: int = 20,
+) -> None:
+    """查询指定范围的覆盖凭证，缺口与未知状态保持原样。"""
+    dates = {}
+    for key, value in (("start", start), ("end", end)):
+        if value is not None:
+            dates[key] = date.fromisoformat(value).isoformat()
+    if start and end:
+        DateRange.model_validate({"start": start, "end": end})
+    output(
+        container(ctx).operations_service.dataset(
+            name.value,
+            "coverage",
+            query(offset, limit, **dates, instrument_id=instrument_id, status=status),
+        )
+    )
+
+
+@app.command("plan", cls=Command)
+@cli_errors
+def create_plan(
+    ctx: typer.Context,
+    mode: Annotated[Mode, typer.Option()],
+    start: OptionString,
+    end: OptionString,
+    dataset: Annotated[list[Dataset], typer.Option()],
+    instrument_id: Annotated[list[str] | None, typer.Option()] = None,
+    confirm: bool = False,
+    expected_plan: OptionalString = None,
+) -> None:
+    """预览同步范围；确认后保存服务端计划，不执行同步。"""
+    request = PlanInput.model_validate(
+        {
+            "mode": mode,
+            "start": start,
+            "end": end,
+            "datasets": dataset,
+            "instrument_ids": instrument_id or [],
+        }
+    )
+    output(
+        container(ctx).operations_service.plan(
+            request.model_dump(mode="json"), confirm, expected_plan
+        ),
+        status="applied" if confirm else "planned",
+    )
+
+
+@app.command("submit", cls=Command)
+@cli_errors
+def submit(
+    ctx: typer.Context,
+    plan_uuid: OptionString,
+    idempotency_key: OptionString,
+    concurrency: int = 4,
+    confirm: bool = False,
+    expected_plan: OptionalString = None,
+) -> None:
+    """预览提交已核对的计划；确认后异步返回 job_uuid。"""
+    request = SubmitInput.model_validate(
+        {"plan_uuid": plan_uuid, "idempotency_key": idempotency_key, "concurrency": concurrency}
+    )
+    output(
+        container(ctx).operations_service.submit(
+            request.model_dump(mode="json"), confirm, expected_plan
+        ),
+        status="submitted" if confirm else "planned",
+    )
+
+
+@jobs.command("list", cls=Command)
+@cli_errors
+def list_jobs(
+    ctx: typer.Context,
+    status: OptionalString = None,
+    kind: OptionalString = None,
+    dataset: OptionalString = None,
+    owner_user_uuid: OptionalString = None,
+    created_start: OptionalString = None,
+    created_end: OptionalString = None,
+    offset: int = 0,
+    limit: int = 20,
+) -> None:
+    """分页查询任务，可按状态、类型、数据集与所属用户筛选。"""
+    output(
+        container(ctx).operations_service.jobs(
+            query(
+                offset,
+                limit,
+                status=status,
+                kind=kind,
+                dataset=dataset,
+                owner_user_uuid=owner_user_uuid,
+                created_start=created_start,
+                created_end=created_end,
+            )
+        )
+    )
+
+
+@jobs.command("show", cls=Command)
+@cli_errors
+def show_job(ctx: typer.Context, job_uuid: str) -> None:
+    """查询任务详情与终态，提交成功不代表任务完成。"""
+    output(container(ctx).operations_service.job(job_uuid))
+
+
+@jobs.command("steps", cls=Command)
+@cli_errors
+def job_steps(
+    ctx: typer.Context,
+    job_uuid: str,
+    status: OptionalString = None,
+    dataset: OptionalString = None,
+    keyword: OptionalString = None,
+    offset: int = 0,
+    limit: int = 20,
+) -> None:
+    """分页查询分片进度与失败原因。"""
+    output(
+        container(ctx).operations_service.job(
+            job_uuid, "steps", query(offset, limit, status=status, dataset=dataset, keyword=keyword)
+        )
+    )
+
+
+@jobs.command("retry", cls=Command)
+@cli_errors
+def retry_job(
+    ctx: typer.Context,
+    job_uuid: str,
+    idempotency_key: OptionString,
+    stable_key: Annotated[list[str] | None, typer.Option()] = None,
+    concurrency: int = 4,
+    confirm: bool = False,
+    expected_plan: OptionalString = None,
+) -> None:
+    """预览并重试授权分片，保留明确的幂等键。"""
+    request = RetryInput(
+        idempotency_key=idempotency_key, stable_keys=stable_key, concurrency=concurrency
+    )
+    output(
+        container(ctx).operations_service.retry(
+            job_uuid, request.model_dump(mode="json", exclude_none=True), confirm, expected_plan
+        ),
+        status="submitted" if confirm else "planned",
+    )
+
+
+@jobs.command("cancel", cls=Command)
+@cli_errors
+def cancel_job(
+    ctx: typer.Context, job_uuid: str, confirm: bool = False, expected_plan: OptionalString = None
+) -> None:
+    """预览目标任务并确认取消，不隐式恢复任务。"""
+    output(
+        container(ctx).operations_service.cancel(job_uuid, confirm, expected_plan),
+        status="applied" if confirm else "planned",
+    )
+
+
+@app.command("publish", cls=Command)
+@cli_errors
+def publish(
+    ctx: typer.Context,
+    dataset: Annotated[list[Dataset], typer.Option()],
+    idempotency_key: OptionString,
+    confirm: bool = False,
+    expected_plan: OptionalString = None,
+) -> None:
+    """预览并发布已有数据版本；不隐式重新同步。"""
+    request = PublishInput(datasets=dataset, idempotency_key=idempotency_key)
+    output(
+        container(ctx).operations_service.publish(
+            request.model_dump(mode="json"), confirm, expected_plan
+        ),
+        status="submitted" if confirm else "planned",
+    )

powerquant_cli-0.2.11/src/quant_cli/app/operations/schema/operation_schema.py

@@ -0,0 +1,67 @@
+"""CLI input DTOs; the backend remains authoritative for domain rules."""
+
+from datetime import date
+from enum import StrEnum
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Mode(StrEnum):
+    BOOTSTRAP = "bootstrap"
+    UPDATE = "update"
+    REPAIR = "repair"
+    AUDIT = "audit"
+
+
+class Dataset(StrEnum):
+    INSTRUMENT = "instrument"
+    CODE_MAPPING = "instrument_code_mapping"
+    CALENDAR = "trading_calendar"
+    RULE = "trading_rule"
+    BAR = "bar"
+    DAILY_BASIC = "daily_basic"
+    DAILY_FACT = "instrument_daily_fact"
+    ADJUSTMENT = "adjustment_factor"
+    CORPORATE_ACTION = "corporate_action"
+
+
+class DateRange(BaseModel):
+    start: date
+    end: date
+
+    @model_validator(mode="after")
+    def ordered(self):
+        if self.start > self.end:
+            raise ValueError("start 不得晚于 end")
+        return self
+
+
+class PlanInput(DateRange):
+    mode: Mode
+    datasets: list[Dataset] = Field(min_length=1)
+    instrument_ids: list[str] = Field(default_factory=list)
+    frequency: str = "1d"
+
+
+class SubmitInput(BaseModel):
+    plan_uuid: UUID
+    idempotency_key: str = Field(min_length=1, max_length=128)
+    concurrency: int = Field(default=4, ge=1, le=32)
+
+
+class RetryInput(BaseModel):
+    idempotency_key: str = Field(min_length=1, max_length=128)
+    concurrency: int = Field(default=4, ge=1, le=32)
+    stable_keys: list[str] | None = Field(default=None, min_length=1)
+
+
+class PublishInput(BaseModel):
+    datasets: list[Dataset] = Field(min_length=1, max_length=9)
+    idempotency_key: str = Field(min_length=1, max_length=128)
+
+
+class PageInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    offset: int = Field(default=0, ge=0)
+    limit: int = Field(default=20, ge=1, le=100)

powerquant_cli-0.2.11/src/quant_cli/app/operations/service/operation_service.py

@@ -0,0 +1,113 @@
+"""Operations use cases and deterministic confirmation; no service-side execution."""
+
+import json
+from collections.abc import Callable
+from hashlib import sha256
+from typing import Any
+from urllib.parse import quote
+from uuid import UUID
+
+from quant_cli.common.http.operations_client import OperationsClient
+from quant_cli.common.operation_error import OperationError
+from quant_cli.config.connection_config import MarketConnection
+
+
+class OperationService:
+    def __init__(self, connection: Callable[[], MarketConnection], client: OperationsClient):
+        self.connection = connection
+        self.client = client
+
+    def _connection(self) -> MarketConnection:
+        connection = self.connection()
+        if not connection.token:
+            raise OperationError(
+                "缺少平台 Token：请申请 market:operate 权限并安全配置；参考 pq-bootstrap。",
+                "token-required",
+                2,
+            )
+        return connection
+
+    def _get(self, path: str, params: dict | None = None) -> Any:
+        c = self._connection()
+        return self.client.request(c.url, c.token, "GET", path, params=params)
+
+    def data_status(self, payload: dict) -> Any:
+        return self._get("/data-status", payload)
+
+    def datasets(self, query: dict) -> Any:
+        return self._get("/datasets", query)
+
+    def dataset(self, name: str, section: str = "", query: dict | None = None) -> Any:
+        return self._get(
+            "/datasets/" + quote(name, safe="") + ("/" + section if section else ""), query
+        )
+
+    def jobs(self, query: dict) -> Any:
+        return self._get("/jobs", query)
+
+    def job(self, job_uuid: str, section: str = "", query: dict | None = None) -> Any:
+        job_uuid = str(UUID(job_uuid))
+        return self._get("/jobs/" + job_uuid + ("/" + section if section else ""), query)
+
+    def _write(
+        self,
+        action: str,
+        path: str,
+        payload: dict,
+        confirm: bool,
+        expected_plan: str | None,
+        evidence: dict | None = None,
+    ) -> dict:
+        c = self._connection()
+        operation = {
+            "action": action,
+            "endpoint": c.url.rstrip("/") + "/operations" + path,
+            "payload": payload,
+            "evidence": evidence,
+        }
+        # Bind confirmation to both endpoint and identity without exposing credentials.
+        identity = sha256(c.token.encode()).hexdigest()
+        signature = sha256(
+            json.dumps({**operation, "identity": identity}, sort_keys=True).encode()
+        ).hexdigest()
+        if not confirm:
+            return {**operation, "expected_plan": signature, "write_performed": False}
+        if expected_plan != signature:
+            raise OperationError(
+                "操作预览已变化或缺少 expected_plan；请重新预览并确认。", "plan-conflict", 3
+            )
+        result = self.client.request(c.url, c.token, "POST", path, payload=payload)
+        return {"action": action, "result": result, "write_performed": True}
+
+    def plan(self, payload: dict, confirm: bool, expected_plan: str | None) -> dict:
+        return self._write("create_plan", "/plans", payload, confirm, expected_plan)
+
+    def submit(self, payload: dict, confirm: bool, expected_plan: str | None) -> dict:
+        return self._write("submit", "/jobs", payload, confirm, expected_plan)
+
+    def retry(self, job_uuid: str, payload: dict, confirm: bool, expected_plan: str | None) -> dict:
+        job_uuid = str(UUID(job_uuid))
+        detail = self.job(job_uuid)
+        evidence = {
+            "job_uuid": job_uuid,
+            "status": detail["status"],
+            "parameters": detail["parameters"],
+        }
+        return self._write(
+            "retry", "/jobs/" + job_uuid + "/retry", payload, confirm, expected_plan, evidence
+        )
+
+    def cancel(self, job_uuid: str, confirm: bool, expected_plan: str | None) -> dict:
+        job_uuid = str(UUID(job_uuid))
+        detail = self.job(job_uuid)
+        evidence = {
+            "job_uuid": job_uuid,
+            "status": detail["status"],
+            "parameters": detail["parameters"],
+        }
+        return self._write(
+            "cancel", "/jobs/" + job_uuid + "/cancel", {}, confirm, expected_plan, evidence
+        )
+
+    def publish(self, payload: dict, confirm: bool, expected_plan: str | None) -> dict:
+        return self._write("publish", "/dataset-publications", payload, confirm, expected_plan)

{powerquant_cli-0.2.10 → powerquant_cli-0.2.11}/src/quant_cli/app/quant_cli.py

@@ -12,6 +12,7 @@ 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.operations.cli.operations_cli import app as operations
 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.app.system.cli.config_cli import app as config
@@ -31,6 +32,7 @@ app = typer.Typer(
     no_args_is_help=True,
 )
 app.add_typer(data, name="data")
+app.add_typer(operations, name="operations")
 app.add_typer(job, name="job")
 app.add_typer(factor, name="factor")
 app.add_typer(research, name="research")

{powerquant_cli-0.2.10 → powerquant_cli-0.2.11}/src/quant_cli/application_container.py

@@ -13,12 +13,14 @@ from quant_cli.app.backtest.service.backtest_application_service import Backtest
 from quant_cli.app.factor.repository.factor_local_repository import FactorLocalRepository
 from quant_cli.app.factor.repository.selection_local_repository import SelectionLocalRepository
 from quant_cli.app.factor.service.factor_application_service import FactorApplicationService
+from quant_cli.app.operations.service.operation_service import OperationService
 from quant_cli.app.research.repository.research_local_repository import ResearchLocalRepository
 from quant_cli.app.research.service.research_application_service import ResearchApplicationService
 from quant_cli.app.system.service.bootstrap_service import BootstrapService
 from quant_cli.app.system.service.connection_service import ConnectionService
 from quant_cli.app.system.service.upgrade_service import UpgradeService
 from quant_cli.application_settings import ApplicationSettings
+from quant_cli.common.http.operations_client import OperationsClient
 from quant_cli.common.operation_error import OperationError
 from quant_cli.common.package_updater import PackageUpdater
 
@@ -35,6 +37,10 @@ class ApplicationContainer:
             self.agent_resource_service, PackageUpdater("powerquant-cli", "pq", settings.state_dir)
         )
 
+    @cached_property
+    def operations_service(self) -> OperationService:
+        return OperationService(self.settings.market_connection, OperationsClient())
+
     @cached_property
     def factor_service(self) -> FactorApplicationService:
         return FactorApplicationService(FactorLocalRepository, SelectionLocalRepository)

powerquant_cli-0.2.11/src/quant_cli/common/http/operations_client.py

@@ -0,0 +1,68 @@
+"""Bounded JSON transport for the platform operations HTTP contract."""
+
+from typing import Any
+
+import httpx
+from pqdata import MarketAPIError
+
+from quant_cli.common.operation_error import OperationError
+
+
+class OperationsClient:
+    def __init__(self, transport: httpx.BaseTransport | None = None):
+        self.transport = transport
+
+    def request(
+        self,
+        base_url: str,
+        token: str,
+        method: str,
+        path: str,
+        payload: dict | None = None,
+        params: dict | None = None,
+    ) -> Any:
+        try:
+            with httpx.Client(
+                timeout=60, follow_redirects=False, transport=self.transport
+            ) as client:
+                response = client.request(
+                    method,
+                    base_url.rstrip("/") + "/operations" + path,
+                    headers={"Authorization": "Bearer " + token},
+                    json=payload,
+                    params=params,
+                )
+        except httpx.TimeoutException as exc:
+            raise OperationError(
+                "运维请求超时；写请求可能已提交，请按原幂等键查询或重放，勿换键重复提交。",
+                "operations-timeout",
+                1,
+            ) from exc
+        except httpx.RequestError as exc:
+            raise OperationError(
+                "运维服务连接失败；检查地址与网络，不要输出 Token。", "operations-connection", 1
+            ) from exc
+        request_id = response.headers.get("X-Request-ID")
+        try:
+            document = response.json()
+        except ValueError:
+            document = None
+        success = 200 <= response.status_code < 300
+        if not success or (isinstance(document, dict) and document.get("code") != 0):
+            code: str | int = f"HTTP_{response.status_code}"
+            message = f"运维请求失败（HTTP {response.status_code}）"
+            if isinstance(document, dict):
+                candidate = document.get("error_code", document.get("code"))
+                if isinstance(candidate, (str, int)) and not isinstance(candidate, bool):
+                    code = candidate
+                value = document.get("message")
+                if isinstance(value, str) and len(value) <= 512:
+                    message = value
+                if not request_id and isinstance(document.get("request_id"), str):
+                    request_id = document["request_id"][:128]
+            # Never return an accidental credential echo from a remote response.
+            message = message.replace(token, "[redacted]")
+            raise MarketAPIError(response.status_code, request_id, code=code, message=message)
+        if not isinstance(document, dict) or document.get("code") != 0 or "data" not in document:
+            raise OperationError("运维响应不符合 JSON 契约", "operations-protocol", 1)
+        return document["data"]

{powerquant_cli-0.2.10 → powerquant_cli-0.2.11}/src/quant_cli/resources/agent_hint.md

@@ -1,7 +1,9 @@
 # Power Quant
 
-通过 pq --help 发现真实命令，pq --version 查看安装版本。按任务加载 pq-bootstrap（安装、连接）、pq-research（本地研究）或 pq-data-operations（API/MCP运维），不依次加载所有 Skill。
+通过 pq --help 发现真实命令，pq --version 查看安装版本。按任务加载 pq-bootstrap（安装、连接）、pq-research（本地研究）或 pq-data-operations（pq operations 数据运维），不依次加载所有 Skill。
 
 正常输出读取 stdout 的 status/data；错误读取 stderr 的 code/message/details/request_id 和退出码。缺 Token 时提示用户申请并安全配置，不将密钥写入命令参数、Hint或报告。
 
 资源安装和升级先核对预览，再在既有授权范围内确认。升级 started、运维任务已提交均不代表完成；查询最终状态和实际证据。数据覆盖未知时不报告完整。
+
+数据运维写操作先预览后确认，幂等键保持稳定；确认后的响应读取 data.result。CLI 不承担 Codex/Claude 会话调度。