qatlas-cli 0.24.0__tar.gz

qatlas_cli-0.24.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+# Release pipeline: tag push (v*) → build sdist/wheel → PyPI.
+#
+# PyPI publication uses Trusted Publishing via OIDC — no API token is
+# stored anywhere. PyPI verifies the GitHub OIDC token against a
+# per-project Trusted Publisher config that must match:
+#
+#   PyPI project name:    qatlas-cli
+#   Owner:                IAI-USTC-Quantum
+#   Repository name:      qatlas-cli
+#   Workflow filename:    release.yml
+#   Environment name:     pypi
+#
+# One-time setup: configure the publisher at
+#   https://pypi.org/manage/project/qatlas-cli/settings/publishing/
+# and create a GitHub Environment named `pypi` in repo Settings
+# (no secrets / approval reviewers needed — the name itself is the
+# match key for the OIDC token).
+#
+# `skip-existing: true` makes re-runs against an already-published
+# version a no-op.
+
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/qatlas-cli/
+    permissions:
+      contents: read  # checkout the tagged ref
+      id-token: write # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Verify tag matches pyproject version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PYPROJECT_VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "$TAG" != "$PYPROJECT_VERSION" ]; then
+            echo "tag v$TAG does not match pyproject version $PYPROJECT_VERSION" >&2
+            exit 1
+          fi
+
+      - name: Build Python distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Silent no-op on re-runs against already-published versions.
+          skip-existing: true

qatlas_cli-0.24.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+
+# Virtualenvs
+.venv/
+.venv-*/
+venv/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

qatlas_cli-0.24.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.22.1
+
+- 客户端/服务端兼容策略调整：由「客户端 x.y ≥ 服务端 x.y」改为「**(major, minor)
+  相同即兼容**」，patch 位随意漂移（如 qatlasd 0.22.4 ↔ qatlas-cli 0.22.3）。
+  两个方向不一致都会给 stderr 警告（带双方版本号与建议动作）；写请求遇更新的
+  服务端仍硬失败（exit code 4）。
+- 升级提示由过时的 `pip install --upgrade quantum-atlas` 改为
+  `uv tool upgrade qatlas-cli`。
+- 与 qatlasd 0.22.x 任意 patch 版本兼容（本次 patch 发布即为该契约的演练）。
+
+## 0.22.0
+
+- 仓库迁移至 IAI-USTC-Quantum/qatlas-cli；安装方式与版本血统继承自
+  主仓 `quantum-atlas` 包。
+- 新增 PyPI Trusted Publishing 发布流程（tag `v*` 触发）。
+
+## 0.21.0a3
+
+- CLI 从主仓 QuantumAtlas 拆分为独立仓库；版本号自主仓 `quantum-atlas`
+  包的 0.21.0a3 继承延续，不重新从 0.x 计数。
+- 安装方式与拆分前一致：`uv tool install qatlas-cli`（PyPI）。
+- 发布流程：commitizen（`cz bump`，tag 格式 `v<version>`）打 tag 后由
+  `.github/workflows/release.yml` 经 PyPI Trusted Publishing 自动发布。
+
+## v0.24.0 (2026-09-07)
+
+### Feat
+
+- **paper**: get metadata 子命令——按 qa_/arXiv/DOI 拉取论文元数据
+
+## v0.23.0 (2026-08-29)
+
+### Feat
+
+- qatlas rag 命令的插件提示
+
+## v0.22.1 (2026-08-26)
+
+### Feat
+
+- x.y compatibility policy; drop paper-get-pdf; add paper-get-images
+
+## v0.22.0 (2026-08-25)
+
+### Fix
+
+- **ci**: grant contents:read so actions/checkout can fetch the tag
+
+## v0.21.0a3 (2026-08-25)

qatlas_cli-0.24.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: qatlas-cli
+Version: 0.24.0
+Summary: Command-line client for QuantumAtlas (qatlas CLI)
+Author: IAI-USTC-Quantum
+Keywords: cli,client,papers,quantum
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: pydantic-settings<3,>=2.0.0
+Requires-Dist: pydantic<3,>=2.5.0
+Requires-Dist: pyyaml<7,>=6.0.1
+Requires-Dist: requests<3,>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qatlas-cli — QuantumAtlas 的命令行客户端
+
+> QuantumAtlas 的 `qatlas` 命令行客户端：面向用户侧的论文获取、贡献上传、
+> 本地解析等工作流，通过 HTTP 与服务端 qatlasd 交互。本仓库是主仓
+> QuantumAtlas 拆出的独立私有仓库，只保留客户端与本地工具，不含服务端代码。
+
+所有服务端通信都是 `requests` 直发的 HTTP 调用，无重量级 SDK 依赖。
+
+## 安装
+
+> **安装方式变更**：本包拆分自主仓的 `quantum-atlas` Python 包（0.21.0a3 起
+> CLI 不再随主包发布）。PyPI 包名由 `quantum-atlas` 改为 **`qatlas-cli`**，
+> 版本号从 0.21.0a3 延续（首个独立发布为 0.22.0）。之前用
+> `uv tool install quantum-atlas` 安装的用户，改用下面的命令即可，
+> 已有配置（`~/.config/qatlas/config.yaml`、PAT 等）不受影响。
+
+从 PyPI 安装为全局 CLI 工具（推荐，与拆分前 `quantum-atlas` 的安装方式一致）：
+
+```bash
+# 推荐：uv 全局工具（隔离环境 + 升级方便）
+uv tool install qatlas-cli
+
+# 或 pipx
+pipx install qatlas-cli
+
+# 或 plain pip
+pip install qatlas-cli
+
+qatlas --help
+```
+
+也可以直接从 GitHub 安装：
+
+```bash
+uv tool install --from git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-cli.git qatlas-cli
+```
+
+本地 editable 安装（开发用）：
+
+```bash
+git clone git@github.com:IAI-USTC-Quantum/qatlas-cli.git
+cd qatlas-cli
+uv sync --extra dev          # 项目内 .venv，editable 安装本包
+# 或装入当前环境：
+uv pip install -e .
+```
+
+## 命令概览
+
+```
+qatlas config   # 管理用户级配置文件（~/.config/qatlas/config.yaml）
+qatlas auth     # 管理各 host 的 PAT / session token（login / status / token / logout）
+qatlas paper    # 论文元数据（JSON）/ markdown / 图片 zip 拉取（markdown 静默 fetch + LRO 轮询；PDF 交付已在服务端停用）
+qatlas contrib  # 贡献者工作流：上传 PDF（contrib pdf）或本地跑 MinerU 再推送（contrib mineru）
+qatlas parser   # 抓取并解析 arXiv 论文（本地工作区命令）
+```
+
+别名：`papers` → `paper`，`parse` → `parser`。
+
+```bash
+qatlas auth login                                   # 设备码 / PAT 登录
+qatlas paper get markdown quant-ph/9508027 --output paper.md
+qatlas paper get metadata quant-ph/9508027          # 论文元数据（JSON：paper_id / ids / title / authors / assets；不含 abstract）
+qatlas contrib pdf quant-ph/9508027v1 --pdf paper.pdf
+qatlas contrib mineru 2501.00010v1
+```
+
+`search` 命令由独立插件 qatlas-search 提供（仓库 IAI-USTC-Quantum/qatlas-search），
+`rag` 命令由独立插件 qatlas-rag 提供（仓库 IAI-USTC-Quantum/qatlas-rag）；
+未安装时 `qatlas search` 或 `qatlas rag` 会给出对应的安装提示。
+
+### 插件机制
+
+第三方包可以通过 entry point 组 **`qatlas.plugins`** 注册插件，向 CLI 贡献
+顶层命令或 `contrib` 子命令。插件协议（基类 `QatlasPlugin` 与
+`CommandSpec`）定义在 `qatlas/client/plugins/base.py`：
+
+```toml
+# 插件包自己的 pyproject.toml
+[project.entry-points."qatlas.plugins"]
+myplugin = "my_package.qatlas_plugin:plugin"
+```
+
+内置命令优先于插件命令；插件不可用时会被静默跳过，不影响 CLI 本体。
+
+## 版本与兼容性
+
+qatlas-cli 与服务端 qatlasd **各自独立演进版本号**，兼容协议是：
+
+> **两者的 `(major, minor)` 相同即兼容**，patch 位随意漂移。
+> 兼容性修复只 bump patch，例如 qatlasd `0.22.4` ↔ qatlas-cli `0.22.3` 是
+> 受支持的配对；而 `0.23.x` 服务端配 `0.22.x` 客户端则不兼容。
+
+运行行为：CLI 每个请求带 `X-Qatlas-Client-Version` 头，服务端响应带
+`X-Qatlas-Server-Version` 头，客户端据此比较：
+
+- `(major, minor)` 一致：静默通过（patch 差异不算事）；
+- 服务端更新且为写操作：硬失败（exit code 4），提示 `uv tool upgrade qatlas-cli`；
+- 服务端更新且为读操作：stderr 警告一次，继续执行；
+- 客户端更新：stderr 警告一次（提示运维方升级 qatlasd），继续执行；
+- 响应无版本头（0.8.0 之前的老服务端）：跳过协商。
+
+完整策略见主仓文档：
+[QuantumAtlas 版本与兼容策略](https://github.com/IAI-USTC-Quantum/QuantumAtlas/blob/main/docsite/dev/versioning.rst)。
+
+## 配置
+
+用户级配置位于 `~/.config/qatlas/config.yaml`（首次运行非 `config` 命令时
+自动创建），顶层 `server_url` / `token` 等字段供各客户端命令读取。环境变量
+`QATLAS_*` 系列可覆盖对应配置；`QATLAS_SKIP_DOTENV=1` 跳过仓库 `.env` 加载。
+
+## 开发与测试
+
+```bash
+uv sync --extra dev
+uv run pytest -q        # 默认全离线；真打外网的用例标了 network，需 -m network 显式开启
+```
+
+测试覆盖：CLI 命令分发与版本解析、auth（设备码登录 / token 存储，mock HTTP）、
+paper / contrib / config 命令行为（mock 服务端）、parser 的 arXiv 抓取与
+MinerU 客户端（固定 fixture / mock）。带 `network` 标记的 live 用例默认跳过。

qatlas_cli-0.24.0/README.md

@@ -0,0 +1,121 @@
+# qatlas-cli — QuantumAtlas 的命令行客户端
+
+> QuantumAtlas 的 `qatlas` 命令行客户端：面向用户侧的论文获取、贡献上传、
+> 本地解析等工作流，通过 HTTP 与服务端 qatlasd 交互。本仓库是主仓
+> QuantumAtlas 拆出的独立私有仓库，只保留客户端与本地工具，不含服务端代码。
+
+所有服务端通信都是 `requests` 直发的 HTTP 调用，无重量级 SDK 依赖。
+
+## 安装
+
+> **安装方式变更**：本包拆分自主仓的 `quantum-atlas` Python 包（0.21.0a3 起
+> CLI 不再随主包发布）。PyPI 包名由 `quantum-atlas` 改为 **`qatlas-cli`**，
+> 版本号从 0.21.0a3 延续（首个独立发布为 0.22.0）。之前用
+> `uv tool install quantum-atlas` 安装的用户，改用下面的命令即可，
+> 已有配置（`~/.config/qatlas/config.yaml`、PAT 等）不受影响。
+
+从 PyPI 安装为全局 CLI 工具（推荐，与拆分前 `quantum-atlas` 的安装方式一致）：
+
+```bash
+# 推荐：uv 全局工具（隔离环境 + 升级方便）
+uv tool install qatlas-cli
+
+# 或 pipx
+pipx install qatlas-cli
+
+# 或 plain pip
+pip install qatlas-cli
+
+qatlas --help
+```
+
+也可以直接从 GitHub 安装：
+
+```bash
+uv tool install --from git+ssh://git@github.com/IAI-USTC-Quantum/qatlas-cli.git qatlas-cli
+```
+
+本地 editable 安装（开发用）：
+
+```bash
+git clone git@github.com:IAI-USTC-Quantum/qatlas-cli.git
+cd qatlas-cli
+uv sync --extra dev          # 项目内 .venv，editable 安装本包
+# 或装入当前环境：
+uv pip install -e .
+```
+
+## 命令概览
+
+```
+qatlas config   # 管理用户级配置文件（~/.config/qatlas/config.yaml）
+qatlas auth     # 管理各 host 的 PAT / session token（login / status / token / logout）
+qatlas paper    # 论文元数据（JSON）/ markdown / 图片 zip 拉取（markdown 静默 fetch + LRO 轮询；PDF 交付已在服务端停用）
+qatlas contrib  # 贡献者工作流：上传 PDF（contrib pdf）或本地跑 MinerU 再推送（contrib mineru）
+qatlas parser   # 抓取并解析 arXiv 论文（本地工作区命令）
+```
+
+别名：`papers` → `paper`，`parse` → `parser`。
+
+```bash
+qatlas auth login                                   # 设备码 / PAT 登录
+qatlas paper get markdown quant-ph/9508027 --output paper.md
+qatlas paper get metadata quant-ph/9508027          # 论文元数据（JSON：paper_id / ids / title / authors / assets；不含 abstract）
+qatlas contrib pdf quant-ph/9508027v1 --pdf paper.pdf
+qatlas contrib mineru 2501.00010v1
+```
+
+`search` 命令由独立插件 qatlas-search 提供（仓库 IAI-USTC-Quantum/qatlas-search），
+`rag` 命令由独立插件 qatlas-rag 提供（仓库 IAI-USTC-Quantum/qatlas-rag）；
+未安装时 `qatlas search` 或 `qatlas rag` 会给出对应的安装提示。
+
+### 插件机制
+
+第三方包可以通过 entry point 组 **`qatlas.plugins`** 注册插件，向 CLI 贡献
+顶层命令或 `contrib` 子命令。插件协议（基类 `QatlasPlugin` 与
+`CommandSpec`）定义在 `qatlas/client/plugins/base.py`：
+
+```toml
+# 插件包自己的 pyproject.toml
+[project.entry-points."qatlas.plugins"]
+myplugin = "my_package.qatlas_plugin:plugin"
+```
+
+内置命令优先于插件命令；插件不可用时会被静默跳过，不影响 CLI 本体。
+
+## 版本与兼容性
+
+qatlas-cli 与服务端 qatlasd **各自独立演进版本号**，兼容协议是：
+
+> **两者的 `(major, minor)` 相同即兼容**，patch 位随意漂移。
+> 兼容性修复只 bump patch，例如 qatlasd `0.22.4` ↔ qatlas-cli `0.22.3` 是
+> 受支持的配对；而 `0.23.x` 服务端配 `0.22.x` 客户端则不兼容。
+
+运行行为：CLI 每个请求带 `X-Qatlas-Client-Version` 头，服务端响应带
+`X-Qatlas-Server-Version` 头，客户端据此比较：
+
+- `(major, minor)` 一致：静默通过（patch 差异不算事）；
+- 服务端更新且为写操作：硬失败（exit code 4），提示 `uv tool upgrade qatlas-cli`；
+- 服务端更新且为读操作：stderr 警告一次，继续执行；
+- 客户端更新：stderr 警告一次（提示运维方升级 qatlasd），继续执行；
+- 响应无版本头（0.8.0 之前的老服务端）：跳过协商。
+
+完整策略见主仓文档：
+[QuantumAtlas 版本与兼容策略](https://github.com/IAI-USTC-Quantum/QuantumAtlas/blob/main/docsite/dev/versioning.rst)。
+
+## 配置
+
+用户级配置位于 `~/.config/qatlas/config.yaml`（首次运行非 `config` 命令时
+自动创建），顶层 `server_url` / `token` 等字段供各客户端命令读取。环境变量
+`QATLAS_*` 系列可覆盖对应配置；`QATLAS_SKIP_DOTENV=1` 跳过仓库 `.env` 加载。
+
+## 开发与测试
+
+```bash
+uv sync --extra dev
+uv run pytest -q        # 默认全离线；真打外网的用例标了 network，需 -m network 显式开启
+```
+
+测试覆盖：CLI 命令分发与版本解析、auth（设备码登录 / token 存储，mock HTTP）、
+paper / contrib / config 命令行为（mock 服务端）、parser 的 arXiv 抓取与
+MinerU 客户端（固定 fixture / mock）。带 `network` 标记的 live 用例默认跳过。

qatlas_cli-0.24.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "qatlas-cli"
+# Version lineage continues from the main-repo `quantum-atlas` package
+# (the CLI was split out at 0.21.0a3); do not restart from 0.x.
+version = "0.24.0"
+description = "Command-line client for QuantumAtlas (qatlas CLI)"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "IAI-USTC-Quantum" }]
+keywords = ["quantum", "papers", "cli", "client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+# Deliberately thin: all server communication is plain `requests` HTTP —
+# no heavyweight SDK dependencies.
+dependencies = [
+    "requests>=2.31.0,<3",
+    "pyyaml>=6.0.1,<7",
+    "platformdirs>=4,<5",
+    "pydantic>=2.5.0,<3",
+    "pydantic-settings>=2.0.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+qatlas = "qatlas.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qatlas"]
+
+# Commitizen: `cz bump` bumps [project].version via the uv provider and
+# tags v<version>; the tag push triggers .github/workflows/release.yml.
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_scheme = "pep440"
+version_provider = "uv"
+update_changelog_on_bump = true
+major_version_zero = true
+annotated_tag = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Live-network tests are opt-in: the default run must be fully offline.
+addopts = "-m 'not network'"
+markers = [
+    "network: opt-in tests that call real external APIs",
+    "e2e: end-to-end tests that load the repository .env and exercise real external services",
+]

qatlas_cli-0.24.0/src/qatlas/__init__.py

@@ -0,0 +1,48 @@
+"""
+QuantumAtlas - AI 驱动的量子算法开发辅助系统
+
+核心功能：从论文到可执行量子代码的完整转化链路
+"""
+
+from __future__ import annotations
+
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+def _version_from_pyproject() -> str:
+    """Read [project].version from the nearest repo-root pyproject.toml.
+
+    Supports both the legacy flat layout (``qatlas/`` at the repo root,
+    pyproject at ``parents[1]``) and the src layout (``src/qatlas/``,
+    pyproject at ``parents[2]``).
+    """
+    here = Path(__file__).resolve()
+    for parent in (here.parents[1], here.parents[2]):
+        pyproject = parent / "pyproject.toml"
+        if not pyproject.is_file():
+            continue
+        with pyproject.open("rb") as f:
+            data = tomllib.load(f)
+        try:
+            return str(data["project"]["version"])
+        except KeyError:
+            continue
+    raise FileNotFoundError("no pyproject.toml with [project].version found")
+
+
+def _resolve_version() -> str:
+    """Prefer repo pyproject when present, else installed distribution metadata."""
+    try:
+        return _version_from_pyproject()
+    except (FileNotFoundError, KeyError, OSError):
+        try:
+            return version("qatlas-cli")
+        except PackageNotFoundError:
+            return "0+unknown"
+
+
+__version__ = _resolve_version()
+
+__all__ = ["__version__"]