powerquant-cli 0.2.7__tar.gz → 0.2.8__tar.gz

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: powerquant-cli
-Version: 0.2.7
+Version: 0.2.8
 Summary: Power Quant local research CLI
 Project-URL: Repository, https://github.com/Kepler452Byte/power-quant
 License-Expression: LicenseRef-PowerQuant-Proprietary AND MIT
@@ -14,6 +14,7 @@ Requires-Dist: numpy<3,>=2
 Requires-Dist: pandas<4,>=3
 Requires-Dist: polars<2,>=1.36
 Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: pyyaml<7,>=6
 Requires-Dist: scipy<2,>=1.17
 Requires-Dist: typer>=0.27.2
 Requires-Dist: tzdata>=2026.3
@@ -51,7 +52,7 @@ pq config show
 
 家庭 LAN 可配置 `http://192.168.8.142:18026/market/api/v1`；公网 IP 临时入口为 `http://82.157.167.33/market/api/v1`。公网 HTTP 会明文传输 Token，只适合已明确接受风险的临时接入；长期公网访问使用可信 HTTPS 或 SSH/WireGuard 加密链路。直接使用 `https://82.157.167.33` 与现有域名证书不匹配。
 
-配置保存在当前系统用户的 `~/.powerquant/config.json`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
+配置保存在当前系统用户的 `~/.powerquant/config.yml`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
 
 每项配置按环境变量 > 用户文件 > 默认值解析。默认地址为 `http://localhost:8002/api/v1`，默认 Token 为空。环境变量只影响当前终端及其启动的子进程，不改文件；显式空 Token 环境变量会覆盖已保存密钥。
 
@@ -81,6 +82,18 @@ pq data prepare --config prepare.json
 
 密钥到期或撤销后在线准备会失败，已下载快照仍可离线使用。行情密钥不用于定义发布；发布定义另使用 PQ_QUANT_URL/PQ_QUANT_TOKEN。默认本地目录为 ~/.powerquant。
 
+## Agent 使用
+
+命令结果与帮助统一输出 JSON；错误以单行 JSON 写入 stderr，保留业务错误码、消息和 request_id，并返回非零退出码。
+
+```sh
+pq resource list
+pq resource show skills/pq-connection
+pq resource export --directory pq-agent-resources
+```
+
+Skill 和提示词仅供按需查看、导出，不自动安装；资源模块可独立移除。行情运维通过 PQData API/MCP 提交任务，不通过本地 CLI 或 SSH 操作服务。
+
 ## Python
 
 公开请求模型与调用入口位于 quant_cli.api，与 CLI 使用同一应用服务。

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/README.md

@@ -30,7 +30,7 @@ pq config show
 
 家庭 LAN 可配置 `http://192.168.8.142:18026/market/api/v1`；公网 IP 临时入口为 `http://82.157.167.33/market/api/v1`。公网 HTTP 会明文传输 Token，只适合已明确接受风险的临时接入；长期公网访问使用可信 HTTPS 或 SSH/WireGuard 加密链路。直接使用 `https://82.157.167.33` 与现有域名证书不匹配。
 
-配置保存在当前系统用户的 `~/.powerquant/config.json`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
+配置保存在当前系统用户的 `~/.powerquant/config.yml`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
 
 每项配置按环境变量 > 用户文件 > 默认值解析。默认地址为 `http://localhost:8002/api/v1`，默认 Token 为空。环境变量只影响当前终端及其启动的子进程，不改文件；显式空 Token 环境变量会覆盖已保存密钥。
 
@@ -60,6 +60,18 @@ pq data prepare --config prepare.json
 
 密钥到期或撤销后在线准备会失败，已下载快照仍可离线使用。行情密钥不用于定义发布；发布定义另使用 PQ_QUANT_URL/PQ_QUANT_TOKEN。默认本地目录为 ~/.powerquant。
 
+## Agent 使用
+
+命令结果与帮助统一输出 JSON；错误以单行 JSON 写入 stderr，保留业务错误码、消息和 request_id，并返回非零退出码。
+
+```sh
+pq resource list
+pq resource show skills/pq-connection
+pq resource export --directory pq-agent-resources
+```
+
+Skill 和提示词仅供按需查看、导出，不自动安装；资源模块可独立移除。行情运维通过 PQData API/MCP 提交任务，不通过本地 CLI 或 SSH 操作服务。
+
 ## Python
 
 公开请求模型与调用入口位于 quant_cli.api，与 CLI 使用同一应用服务。

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/bundled/pqdata/client.py

@@ -101,7 +101,25 @@ class MarketClient:
             await response.aclose()
             await asyncio.sleep(delay)
         if not response.is_success:
-            raise MarketAPIError(response.status_code, response.headers.get("x-request-id"))
+            code: str | int | None = None
+            message: str | None = None
+            request_id = response.headers.get("x-request-id")
+            if "application/json" in response.headers.get("content-type", ""):
+                try:
+                    error = response.json()
+                except ValueError:
+                    error = None
+                if isinstance(error, dict):
+                    candidate = error.get("error_code", error.get("code"))
+                    if isinstance(candidate, (str, int)) and not isinstance(candidate, bool):
+                        code = candidate
+                    candidate = error.get("message")
+                    if isinstance(candidate, str) and 0 < len(candidate) <= 512:
+                        message = candidate
+                    candidate = error.get("request_id")
+                    if isinstance(candidate, str) and len(candidate) <= 128:
+                        request_id = request_id or candidate
+            raise MarketAPIError(response.status_code, request_id, code=code, message=message)
         try:
             return TypeAdapter(response_type).validate_json(response.content)
         except ValidationError as error:

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/bundled/pqdata/exceptions.py

@@ -4,10 +4,14 @@
 class MarketAPIError(Exception):
     """服务拒绝请求；保留状态码和可追踪的请求 ID，不暴露凭据。"""
 
-    def __init__(self, status_code: int, request_id: str | None = None) -> None:
+    def __init__(self, status_code: int, request_id: str | None = None,
+                 *, code: str | int | None = None, message: str | None = None) -> None:
         self.status_code = status_code
         self.request_id = request_id
-        super().__init__(f"Market request failed (HTTP {status_code}, request_id={request_id})")
+        self.code = code if code is not None else f"HTTP_{status_code}"
+        self.message = message or f"行情请求失败（HTTP {status_code}）"
+        super().__init__(self.message)
+
 
 
 class MarketProtocolError(Exception):

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "powerquant-cli"
-version = "0.2.7"
+version = "0.2.8"
 description = "Power Quant local research CLI"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "LicenseRef-PowerQuant-Proprietary AND MIT"
 license-files = ["LICENSE", "licenses/LICENSE.vnpy"]
-dependencies = ["pydantic>=2.5,<3", "polars>=1.36,<2", "numpy>=2,<3", "scipy>=1.17,<2", "pandas>=3,<4", "tzdata>=2026.3", "typer>=0.27.2", "httpx>=0.28,<1", "duckdb>=1.4,<2", "filelock>=3.20,<4"]
+dependencies = ["pydantic>=2.5,<3", "polars>=1.36,<2", "numpy>=2,<3", "scipy>=1.17,<2", "pandas>=3,<4", "tzdata>=2026.3", "typer>=0.27.2", "httpx>=0.28,<1", "duckdb>=1.4,<2", "filelock>=3.20,<4", "pyyaml>=6,<7"]
 
 [project.urls]
 Repository = "https://github.com/Kepler452Byte/power-quant"

powerquant_cli-0.2.8/src/quant_cli/app/agent_resource/cli/resource_cli.py

@@ -0,0 +1,31 @@
+"""可移除的资源命令；与核心计算命令无依赖。"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from quant_cli.app.agent_resource.service.resource_service import ResourceService
+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, help="按需查看与导出随包 Skill 和提示词", no_args_is_help=True)
+
+
+@app.command("list", cls=Command)
+@cli_errors
+def list_resources() -> None:
+    output({"items": ResourceService().list()})
+
+
+@app.command("show", cls=Command)
+@cli_errors
+def show_resource(name: str) -> None:
+    output(ResourceService().show(name))
+
+
+@app.command("export", cls=Command)
+@cli_errors
+def export_resources(directory: Annotated[Path, typer.Option("--directory")]) -> None:
+    output(ResourceService().export(directory))

powerquant_cli-0.2.8/src/quant_cli/app/agent_resource/service/resource_service.py

@@ -0,0 +1,77 @@
+"""可选 Agent 资源读取与安全导出，不修改 Agent 配置。"""
+
+import shutil
+from importlib.resources import files
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+class ResourceService:
+    """仅管理随包资源，不联网、不读数据库。"""
+
+    def _root(self) -> Any:
+        return files("quant_cli").joinpath("resources")
+
+    def list(self) -> list[dict[str, str]]:
+        result = []
+        root = self._root()
+        if not root.is_dir():
+            return result
+        for kind in ("skills", "prompts"):
+            folder = root.joinpath(kind)
+            if folder.is_dir():
+                for item in sorted(folder.iterdir(), key=lambda entry: entry.name):
+                    path = item.joinpath("SKILL.md") if item.is_dir() else item
+                    if path.is_file():
+                        result.append(
+                            {
+                                "name": item.name,
+                                "kind": kind,
+                                "path": f"{kind}/{item.name}",
+                                "description": self._description(path.read_text(encoding="utf-8")),
+                            }
+                        )
+        return result
+
+    @staticmethod
+    def _description(text: str) -> str:
+        for line in text.splitlines():
+            if line.startswith("description:"):
+                return line.partition(":")[2].strip().strip('"')
+        return next((line.lstrip("# ") for line in text.splitlines() if line.strip()), "")
+
+    def show(self, name: str) -> dict[str, str]:
+        path = PurePosixPath(name)
+        if (
+            path.is_absolute()
+            or ".." in path.parts
+            or len(path.parts) != 2
+            or path.parts[0] not in ("skills", "prompts")
+            or "\\" in name
+        ):
+            raise ValueError("资源路径必须是 skills/<名称> 或 prompts/<名称>")
+        item = self._root().joinpath(*path.parts)
+        content = item.joinpath("SKILL.md") if item.is_dir() else item
+        if not content.is_file():
+            raise ValueError("资源不存在")
+        return {"path": name, "content": content.read_text(encoding="utf-8")}
+
+    def export(self, destination: Path) -> dict[str, str]:
+        # 必须新目录：不覆盖、不合并用户内容。独占创建防止并发覆盖。
+        destination.mkdir(parents=True, exist_ok=False)
+        try:
+            self._copy(self._root(), destination)
+        except BaseException:
+            shutil.rmtree(destination)
+            raise
+        return {"directory": str(destination.resolve())}
+
+    def _copy(self, source: Any, destination: Path) -> None:
+        for item in source.iterdir():
+            target = destination / item.name
+            if item.is_dir():
+                target.mkdir()
+                self._copy(item, target)
+            else:
+                with target.open("xb") as stream:
+                    stream.write(item.read_bytes())

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/src/quant_cli/app/backtest/cli/local_backtest_cli.py

@@ -7,19 +7,19 @@ 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.command_error_handler import CommandGroup
+from quant_cli.common.command_help import Command
 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 = typer.Typer(cls=CommandGroup, help="本地策略回测", no_args_is_help=True)
 
 
-@app.command("run")
+@app.command("run", cls=Command)
 @cli_errors
 def run(
+    ctx: typer.Context,
     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,
@@ -30,23 +30,26 @@ def run(
     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)
+    record = asyncio.run(
+        ctx.obj.backtest_service.run(request, database, ctx.obj.factor_service.store(database))
+    )
     output(record)
 
 
-@app.command("get")
+@app.command("get", cls=Command)
 @cli_errors
 def get(
+    ctx: typer.Context,
     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))
+    output(ctx.obj.backtest_service.store(database).get(run))
 
 
-@app.command("list")
+@app.command("list", cls=Command)
 @cli_errors
 def list_runs(
+    ctx: typer.Context,
     limit: int = 20,
     offset: int = 0,
     database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
@@ -54,19 +57,20 @@ def list_runs(
     output(
         [
             row.model_dump(mode="json")
-            for row in build_local_backtest_store(database).list_runs(limit, offset)
+            for row in ctx.obj.backtest_service.store(database).list_runs(limit, offset)
         ]
     )
 
 
-@app.command("compare")
+@app.command("compare", cls=Command)
 @cli_errors
 def compare(
+    ctx: typer.Context,
     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)
+    store = ctx.obj.backtest_service.store(database)
     output(compare_backtest_records(tuple(store.get(key) for key in run)))

powerquant_cli-0.2.8/src/quant_cli/app/backtest/service/backtest_application_service.py

@@ -0,0 +1,29 @@
+"""Backtest 应用服务组装，存储路径由调用方显式指定。"""
+
+from collections.abc import Callable
+from pathlib import Path
+
+from quant_core.app.factor.interface.public.factor_local import LocalFactorStore
+from quant_core.common.local_run import LocalRunRecord
+
+from quant_cli.app.backtest.local_backtest_schema import LocalBacktestRequest
+from quant_cli.app.backtest.repository.backtest_local_repository import BacktestLocalRepository
+
+
+class BacktestApplicationService:
+    def __init__(self, store_factory: Callable[[Path], BacktestLocalRepository]) -> None:
+        self._store_factory = store_factory
+
+    def store(self, path: Path) -> BacktestLocalRepository:
+        """组装短事务存储，不缓存连接或隐式选择路径。"""
+        return self._store_factory(path)
+
+    async def run(
+        self, request: LocalBacktestRequest, path: Path, factor_store: LocalFactorStore
+    ) -> LocalRunRecord:
+        """回测并归档，因子依赖由组合根显式传入。"""
+        from quant_cli.app.backtest.service.local_backtest_service import run_local_backtest
+
+        record = await run_local_backtest(request, factor_store)
+        self.store(path).save(record)
+        return record

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/src/quant_cli/app/config/config_cli.py

@@ -5,6 +5,8 @@ from typing import Annotated
 
 import typer
 
+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
 from quant_cli.config.connection_config import (
     get_config_path,
@@ -13,7 +15,7 @@ from quant_cli.config.connection_config import (
     update_saved_config,
 )
 
-app = typer.Typer(help="保存和查看当前用户的行情连接配置", no_args_is_help=True)
+app = typer.Typer(cls=CommandGroup, help="保存和查看当前用户的行情连接配置", no_args_is_help=True)
 
 
 class ConfigKey(StrEnum):
@@ -21,7 +23,7 @@ class ConfigKey(StrEnum):
     MARKET_TOKEN = "market-token"
 
 
-@app.command("set")
+@app.command("set", cls=Command)
 @cli_errors
 def set_config(
     market_url: Annotated[str, typer.Option("--market-url", "--url", help="行情 API 基础地址")],
@@ -31,7 +33,7 @@ def set_config(
     output({"status": "saved", "path": str(get_config_path()), "key": "market_url"})
 
 
-@app.command("token")
+@app.command("token", cls=Command)
 @cli_errors
 def set_token() -> None:
     """隐藏输入平台 Token，避免写入命令历史与进程参数。"""
@@ -40,7 +42,7 @@ def set_token() -> None:
     output({"status": "saved", "path": str(get_config_path()), "key": "market_token"})
 
 
-@app.command("show")
+@app.command("show", cls=Command)
 @cli_errors
 def show_config() -> None:
     """展示已保存和当前生效的配置、来源；不输出密钥原文或前缀。"""
@@ -63,7 +65,7 @@ def show_config() -> None:
     )
 
 
-@app.command("unset")
+@app.command("unset", cls=Command)
 @cli_errors
 def unset_config(key: ConfigKey) -> None:
     """删除一项已保存配置，环境变量覆盖仍然有效。"""

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/src/quant_cli/app/data/cli/data_cli.py

@@ -6,19 +6,21 @@ from typing import Annotated
 
 import typer
 
-from quant_cli.app.data.data_dependency import build_market_query
 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.common.command_error_handler import CommandGroup
+from quant_cli.common.command_help import Command
 from quant_cli.common.constants import DEFAULT_DATASETS_DIR
 from quant_cli.common.utils.cli_utils import cli_errors, output
 
-app = typer.Typer(help="行情快照准备与校验", no_args_is_help=True)
+app = typer.Typer(cls=CommandGroup, help="行情快照准备与校验", no_args_is_help=True)
 
 
-@app.command("prepare")
+@app.command("prepare", cls=Command)
 @cli_errors
 def prepare(
+    ctx: typer.Context,
     config: Annotated[Path, typer.Option(exists=True)],
     cache_dir: Annotated[Path, typer.Option()] = DEFAULT_DATASETS_DIR,
 ) -> None:
@@ -26,7 +28,7 @@ def prepare(
     request = DatasetPrepareRequest.model_validate_json(config.read_text(encoding="utf-8"))
 
     async def execute() -> str:
-        async with build_market_query() as client:
+        async with ctx.obj.market_client() as client:
             result = await prepare_dataset(
                 client,
                 instrument_ids=request.instrument_ids,
@@ -45,7 +47,7 @@ def prepare(
     output({"manifest_path": asyncio.run(execute())})
 
 
-@app.command("verify")
+@app.command("verify", cls=Command)
 @cli_errors
 def verify(manifest: Annotated[Path, typer.Option(exists=True)], max_rows: int = 1000000) -> None:
     market, _ = load_dataset(manifest, max_rows)
@@ -59,7 +61,7 @@ def verify(manifest: Annotated[Path, typer.Option(exists=True)], max_rows: int =
     )
 
 
-@app.command("audit")
+@app.command("audit", cls=Command)
 @cli_errors
 def audit(
     manifest: Annotated[Path, typer.Option(exists=True)],

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/src/quant_cli/app/data/data_dependency.py

@@ -29,7 +29,4 @@ def load_backtest_market(manifest_path: Path, max_rows: int) -> BacktestMarketCo
 def build_market_query() -> MarketClient:
     """显式在线准备入口，配置仅为服务地址与令牌。"""
     connection = resolve_market_connection()
-    return MarketClient(
-        connection.url,
-        token=connection.token,
-    )
+    return MarketClient(connection.url, token=connection.token)

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/src/quant_cli/app/factor/cli/factor_definition_cli.py

@@ -9,15 +9,17 @@ import typer
 from quant_core.app.factor.schema.factor_computation_schema import FactorComputationSpec
 from quant_core.app.factor.schema.factor_publication_schema import PublishedFactor
 
+from quant_cli.common.command_error_handler import CommandGroup
+from quant_cli.common.command_help import Command
 from quant_cli.common.http.definition_client import request_definition, save_definition
 from quant_cli.common.utils.cli_utils import cli_errors, output
 
-app = typer.Typer(help="因子定义发布、查询与获取", no_args_is_help=True)
+app = typer.Typer(cls=CommandGroup, help="因子定义发布、查询与获取", no_args_is_help=True)
 Server = Annotated[str, typer.Option(envvar="PQ_QUANT_URL")]
 Token = Annotated[str, typer.Option(envvar="PQ_QUANT_TOKEN", help="建议由环境变量提供令牌")]
 
 
-@app.command("publish")
+@app.command("publish", cls=Command)
 @cli_errors
 def publish(
     config: Annotated[Path, typer.Option(exists=True)],
@@ -38,7 +40,7 @@ def publish(
     output(result.model_dump(mode="json"))
 
 
-@app.command("list")
+@app.command("list", cls=Command)
 @cli_errors
 def list_definitions(
     server: Server, token: Token, name: str | None = None, limit: int = 100, offset: int = 0
@@ -50,7 +52,7 @@ def list_definitions(
     output(request_definition(server, token, "GET", "/factor/definitions", params=params))
 
 
-@app.command("fetch")
+@app.command("fetch", cls=Command)
 @cli_errors
 def fetch(
     name: str,

{powerquant_cli-0.2.7 → powerquant_cli-0.2.8}/src/quant_cli/app/factor/cli/local_factor_cli.py

@@ -10,20 +10,21 @@ from quant_core.app.factor.schema.local_factor_schema import LocalFactorRequest
 
 from quant_cli.app.factor.cli.factor_definition_cli import app as definitions
 from quant_cli.app.factor.cli.local_selection_cli import register_selection_commands
-from quant_cli.app.factor.local_factor_dependency import build_local_factor_store
-from quant_cli.app.factor.service.local_factor_service import run_local_factor
+from quant_cli.common.command_error_handler import CommandGroup
+from quant_cli.common.command_help import Command
 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 = typer.Typer(cls=CommandGroup, help="本地因子计算与归档", no_args_is_help=True)
 
 app.add_typer(definitions, name="definition")
 register_selection_commands(app)
 
 
-@app.command("compute")
+@app.command("compute", cls=Command)
 @cli_errors
 def compute(
+    ctx: typer.Context,
     config: Annotated[Path, typer.Option(exists=True)],
     source: Annotated[Path | None, typer.Option(exists=True)] = None,
     definition: Annotated[list[Path] | None, typer.Option(exists=True)] = None,
@@ -47,21 +48,23 @@ def compute(
             for path in definition
         ]
     request = LocalFactorRequest.model_validate(payload)
-    output(asyncio.run(run_local_factor(request, build_local_factor_store(database))))
+    output(asyncio.run(ctx.obj.factor_service.run(request, database)))
 
 
-@app.command("get")
+@app.command("get", cls=Command)
 @cli_errors
 def get(
+    ctx: typer.Context,
     run: Annotated[UUID, typer.Option()],
     database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
 ) -> None:
-    output(build_local_factor_store(database).get(run))
+    output(ctx.obj.factor_service.store(database).get(run))
 
 
-@app.command("list")
+@app.command("list", cls=Command)
 @cli_errors
 def list_runs(
+    ctx: typer.Context,
     limit: int = 20,
     offset: int = 0,
     database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
@@ -69,14 +72,15 @@ def list_runs(
     output(
         [
             row.model_dump(mode="json")
-            for row in build_local_factor_store(database).list_runs(limit, offset)
+            for row in ctx.obj.factor_service.store(database).list_runs(limit, offset)
         ]
     )
 
 
-@app.command("import")
+@app.command("import", cls=Command)
 @cli_errors
 def import_artifact(
+    ctx: typer.Context,
     artifact: Annotated[Path, typer.Option(exists=True)],
     database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
 ) -> None:
@@ -85,18 +89,19 @@ def import_artifact(
 
     output(
         import_factor_artifact(
-            artifact.read_text(encoding="utf-8"), build_local_factor_store(database)
+            artifact.read_text(encoding="utf-8"), ctx.obj.factor_service.store(database)
         )
     )
 
 
-@app.command("values")
+@app.command("values", cls=Command)
 @cli_errors
 def values(
+    ctx: typer.Context,
     run: Annotated[UUID, typer.Option()],
     limit: int = 100,
     offset: int = 0,
     database: Annotated[Path, typer.Option(envvar="PQ_LOCAL_DATABASE")] = DEFAULT_DATABASE_PATH,
 ) -> None:
     """分页查询归档因子值。"""
-    output(build_local_factor_store(database).list_values(run, limit, offset))
+    output(ctx.obj.factor_service.store(database).list_values(run, limit, offset))