Metadata-Version: 2.5
Name: powerquant-cli
Version: 0.2.10
Summary: Power Quant local research CLI
Project-URL: Repository, https://github.com/Kepler452Byte/power-quant
License-Expression: LicenseRef-PowerQuant-Proprietary AND MIT
License-File: LICENSE
License-File: licenses/LICENSE.vnpy
Requires-Python: >=3.12
Requires-Dist: duckdb<2,>=1.4
Requires-Dist: filelock<4,>=3.20
Requires-Dist: httpx<1,>=0.28
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
Description-Content-Type: text/markdown

# Power Quant CLI

本地行情准备、因子计算、选股、研究及策略回测；结果保存在本地 DuckDB 和文件。

## 安装

推荐通过 uv 安装独立工具环境：

```sh
uv tool install --python 3.12 powerquant-cli
pq --help
uv tool upgrade powerquant-cli
```

也支持在 Python 3.12+ 环境通过 `pip install powerquant-cli` 安装。

## 接入行情

向管理员申请账户及具备 `market:read` 权限的平台 API Token。登录 JWT 不用于行情请求。

首次配置一次，之后新开终端、切换目录仍可使用：

```sh
pq config set --market-url 'https://powerquant.cn/market/api/v1'
pq config token
pq config show
```

`token` 命令隐藏输入密钥，不加 `Bearer`，避免写入命令历史。`show` 显示地址、配置来源和是否已配置 Token，不显示密钥原文或前缀。

家庭 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.yml`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。

每项配置按环境变量 > 用户文件 > 默认值解析。默认地址为 `http://localhost:8002/api/v1`，默认 Token 为空。环境变量只影响当前终端及其启动的子进程，不改文件；显式空 Token 环境变量会覆盖已保存密钥。

PowerShell 临时覆盖示例：

```powershell
$env:MARKET_BASE_URL="http://192.168.8.142:18026/market/api/v1"
$env:MARKET_API_TOKEN="管理员签发的完整平台Token"
```

删除已保存的配置：

```sh
pq config unset market-token
pq config unset market-url
```

随后准备本地行情快照：

```sh
pq examples --directory powerquant-examples
cd powerquant-examples/selection
pq data prepare --config prepare.json
```

按实际覆盖调整 prepare.json 的股票和日期，将返回的 data.manifest_path 写入 compute.json、select.json；按示例 README 执行 compute、select 和 backtest。不同使用目的的快照须分别通过完整性检查。

密钥到期或撤销后在线准备会失败，已下载快照仍可离线使用。行情密钥不用于定义发布；发布定义另使用 PQ_QUANT_URL/PQ_QUANT_TOKEN。默认本地目录为 ~/.powerquant。

## Agent 使用

命令结果统一输出 JSON `{status,data}`；错误以 JSON 写入 stderr，保留业务错误码、消息和 request_id，并返回非零退出码。

```sh
pq --version
pq skill list
pq skill show pq-bootstrap
pq skill check
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 提交任务。

`pq upgrade` 先预览，再用 `--confirm --expected-plan <expected_plan>` 启动后台升级；通过 `pq agent upgrade-status <operation_id>` 查询结果。升级沿用 uv tool 或 pipx 安装渠道，并同步已登记的资源目录。`pq upgrade --skip-package` 仅同步资源。独立资源同步使用 `pq agent sync`，同样先预览再确认。

## 依赖生命周期

ApplicationContainer 接收 ApplicationSettings，按需组装明确的因子、回测、研究应用 Service，CLI 从 ctx.obj 获取。Service 依赖由构造函数显式传入；不维护通用 Repository 缓存、不查询全局容器、不在缺少上下文时静默创建容器。MarketClient 按需创建并由调用方 async with 关闭，本地 Repository 使用短事务。配置、帮助和资源查看不初始化数据库或联网。

## Python

公开请求模型与调用入口位于 quant_cli.api，与 CLI 使用同一应用服务。

## 使用许可

自有代码采用随包附带的专有许可证：允许安装、查看源码、为自用进行修改，以及商业使用；未经书面授权不得再分发或转售本软件及其修改版本。第三方组件保留各自许可证。行情访问仍需要有效 Token；本许可证不授予行情数据的使用或再分发权。
