myqcd 0.1.0__tar.gz

myqcd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZhangXin8069
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

myqcd-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+recursive-include myqcd *.py
+include myqcd/py.typed
+
+prune myqcd/testing
+prune .pytest_cache
+global-exclude AGENTS.md
+global-exclude *.pyc

myqcd-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: myqcd
+Version: 0.1.0
+Summary: Executable audits for lattice-QCD formulas, operator construction, and Feynman diagram structure.
+Author: ZhangXin8069
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.itp.ac.cn/zhangxin8069/MyQCD
+Project-URL: 国内镜像 (Gitee), https://gitee.com/zhangxin8069/MyQCD
+Project-URL: 国际镜像 (GitHub), https://github.com/zhangxin8069/MyQCD
+Project-URL: Documentation, https://myqcd.readthedocs.io/
+Project-URL: Issues, https://gitlab.itp.ac.cn/zhangxin8069/MyQCD/-/issues
+Keywords: lattice-qcd,qcd,operator-construction,feynman-diagrams,sympy,physics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy>=1.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# MyQCD
+
+MyQCD 是 PyQCD 格点 QCD 物理的可执行公式审计库：把报告中的结构公式拆成
+SymPy 可检查推导、来源索引与独立的算符/费曼图层。它不复制上游 GPL 或无许可证
+源码，所有新实现均以数学恒等式与精确代数测试为证据。
+
+## 安装
+
+```bash
+pip install myqcd
+```
+
+唯一运行依赖是 `sympy`。Python 3.10 及以上可用；当前完整测试在 Python 3.12
+（SymPy 1.14）上执行。
+
+## 能力
+
+| 模块 | 作用 |
+|---|---|
+| `myqcd.audit` | 核心公式检查、论文显示公式索引与 JSON 报告 |
+| `myqcd.pyqcd_theory_audit` | PyQCD 的 gamma、顶点、Wilson 线、Clover、Jackknife、ratio、混合方案与量纲审计 |
+| `myqcd.derivations` | 格点规范场、梯度流、LaMET、PDF/TMD、重正化与统计的 SymPy 推导 |
+| `myqcd.formula_registry` | 公式到报告、来源行号与推导入口的注册表 |
+| `myqcd.latex_inventory` | 论文 LaTeX 显示公式清单 |
+| `myqcd.wick` | 精确味道 Wick 配对与 Grassmann 重排符号 |
+| `myqcd.gamma` | PyQCD DeGrand--Rossi gamma 基、0..17 索引、迹定理、16 个 Dirac 基与 H/T/C 符号 |
+| `myqcd.color` | SU(3) 生成元、结构常数、对称常数、Casimir 与颜色 Fierz 恒等式 |
+| `myqcd.operators` | 16 个 Dirac 双线性结构、精确分解、宇称/C 分类、量纲与 PyQCD 索引映射 |
+| `myqcd.feynman` | 费曼图数据结构、QCD 顶点/传播子规则清单、Wick 配对图与圈数 |
+| `myqcd.diagram_export` | 零依赖导出 TikZ-Feynman、Graphviz DOT 与 SVG |
+| `myqcd.operator_audit` | 算符/图构建一键审计 |
+
+## 入口
+
+```bash
+python -m myqcd
+python -m myqcd.operator_audit --root .
+python -m myqcd.pyqcd_theory_audit --root .
+```
+
+`python -m myqcd` 需要源码仓库中的 `refer/papers/INDEX.md`；纯安装环境请使用
+`python -m myqcd.operator_audit`，它只依赖包内代码与 SymPy。
+
+## 证据边界
+
+- `verified` 只表示写明的代数、量纲、有限维代理或组合恒等式通过。
+- 不声称完成非阿贝尔圈积分、非微扰矩阵元、真实系综、GPU 数值、soft/rapidity
+  闭环或连续极限。
+- 颜色约定：`myqcd.color` 使用厄米归一化 `Tr[T^aT^b] = +δ^{ab}/2`；历史
+  `derivations.py` 中的 SU(3) 推导使用反厄米 `-δ^{ab}/2`，两套约定不可混用。
+- 费曼图导出只保证组合结构与字符串格式，不证明具体图的对称因子或圈积分结果。
+
+## 仓库与文档
+
+- 主仓库：<https://gitlab.itp.ac.cn/zhangxin8069/MyQCD>
+- Gitee 镜像：<https://gitee.com/zhangxin8069/MyQCD>
+- GitHub 镜像（由 Gitee 自动同步）：<https://github.com/zhangxin8069/MyQCD>
+- 文档：<https://myqcd.readthedocs.io/>
+
+外部参考库以只读 Git 子模块固定在 `refer/git-rep/`，来源、提交与许可证见
+`docs/absorb_reference_libraries_20261109.md`。
+
+## 许可
+
+MIT。见 `LICENSE`。

myqcd-0.1.0/README.md

@@ -0,0 +1,65 @@
+# MyQCD
+
+MyQCD 是 PyQCD 格点 QCD 物理的可执行公式审计库：把报告中的结构公式拆成
+SymPy 可检查推导、来源索引与独立的算符/费曼图层。它不复制上游 GPL 或无许可证
+源码，所有新实现均以数学恒等式与精确代数测试为证据。
+
+## 安装
+
+```bash
+pip install myqcd
+```
+
+唯一运行依赖是 `sympy`。Python 3.10 及以上可用；当前完整测试在 Python 3.12
+（SymPy 1.14）上执行。
+
+## 能力
+
+| 模块 | 作用 |
+|---|---|
+| `myqcd.audit` | 核心公式检查、论文显示公式索引与 JSON 报告 |
+| `myqcd.pyqcd_theory_audit` | PyQCD 的 gamma、顶点、Wilson 线、Clover、Jackknife、ratio、混合方案与量纲审计 |
+| `myqcd.derivations` | 格点规范场、梯度流、LaMET、PDF/TMD、重正化与统计的 SymPy 推导 |
+| `myqcd.formula_registry` | 公式到报告、来源行号与推导入口的注册表 |
+| `myqcd.latex_inventory` | 论文 LaTeX 显示公式清单 |
+| `myqcd.wick` | 精确味道 Wick 配对与 Grassmann 重排符号 |
+| `myqcd.gamma` | PyQCD DeGrand--Rossi gamma 基、0..17 索引、迹定理、16 个 Dirac 基与 H/T/C 符号 |
+| `myqcd.color` | SU(3) 生成元、结构常数、对称常数、Casimir 与颜色 Fierz 恒等式 |
+| `myqcd.operators` | 16 个 Dirac 双线性结构、精确分解、宇称/C 分类、量纲与 PyQCD 索引映射 |
+| `myqcd.feynman` | 费曼图数据结构、QCD 顶点/传播子规则清单、Wick 配对图与圈数 |
+| `myqcd.diagram_export` | 零依赖导出 TikZ-Feynman、Graphviz DOT 与 SVG |
+| `myqcd.operator_audit` | 算符/图构建一键审计 |
+
+## 入口
+
+```bash
+python -m myqcd
+python -m myqcd.operator_audit --root .
+python -m myqcd.pyqcd_theory_audit --root .
+```
+
+`python -m myqcd` 需要源码仓库中的 `refer/papers/INDEX.md`；纯安装环境请使用
+`python -m myqcd.operator_audit`，它只依赖包内代码与 SymPy。
+
+## 证据边界
+
+- `verified` 只表示写明的代数、量纲、有限维代理或组合恒等式通过。
+- 不声称完成非阿贝尔圈积分、非微扰矩阵元、真实系综、GPU 数值、soft/rapidity
+  闭环或连续极限。
+- 颜色约定：`myqcd.color` 使用厄米归一化 `Tr[T^aT^b] = +δ^{ab}/2`；历史
+  `derivations.py` 中的 SU(3) 推导使用反厄米 `-δ^{ab}/2`，两套约定不可混用。
+- 费曼图导出只保证组合结构与字符串格式，不证明具体图的对称因子或圈积分结果。
+
+## 仓库与文档
+
+- 主仓库：<https://gitlab.itp.ac.cn/zhangxin8069/MyQCD>
+- Gitee 镜像：<https://gitee.com/zhangxin8069/MyQCD>
+- GitHub 镜像（由 Gitee 自动同步）：<https://github.com/zhangxin8069/MyQCD>
+- 文档：<https://myqcd.readthedocs.io/>
+
+外部参考库以只读 Git 子模块固定在 `refer/git-rep/`，来源、提交与许可证见
+`docs/absorb_reference_libraries_20261109.md`。
+
+## 许可
+
+MIT。见 `LICENSE`。

myqcd-0.1.0/myqcd/__init__.py

@@ -0,0 +1,235 @@
+"""PyQCD 格点 QCD 物理公式与来源审计工具。
+
+本包把报告中的结构公式拆成两层：
+
+* :mod:`myqcd.derivations` 包含可在明确假设下由 SymPy 检查的解析推导；
+* :mod:`myqcd.latex_inventory` 对 50 篇中文论文源文件中的显示公式逐条建档。
+
+公式索引中的 ``unparsed`` 只表示尚未在不引入额外物理约定的情况下自动
+语义化，并不表示论文公式错误。
+"""
+
+__version__ = "0.1.0"
+
+from .derivations import (
+    DerivationResult,
+    derive_collins_soper_evolution,
+    derive_correlator_spectrum,
+    derive_diffusion_processes,
+    derive_gauge_flow_kernel,
+    derive_generating_functional,
+    derive_gradient_flow,
+    derive_gradient_flow_energy_density,
+    derive_heat_kernel_semigroup,
+    derive_gradient_flow_pole_cancellation,
+    derive_hmc_scalar,
+    derive_langevin_fokker_planck,
+    derive_boosted_smearing_width,
+    derive_lattice_dispersion_relations,
+    derive_lamet_matching,
+    derive_lamet_lightcone_kinematics,
+    derive_lattice_link,
+    derive_mcmc_autocorrelation,
+    derive_stout_smearing_su2,
+    derive_momentum_smearing_shift,
+    derive_mellin_convolution,
+    derive_nonperturbative_renormalization_conditions,
+    derive_normalizing_flow,
+    derive_pseudo_itd,
+    derive_pdf_moment_relations,
+    derive_phi4_lattice_observables,
+    derive_renormalization,
+    derive_tmd_fourier,
+    derive_quasi_pdf_tmd_relation,
+    derive_gpd_kinematics_and_matching,
+    derive_pion_da_normalization,
+    derive_tmd_soft_rge_consistency,
+    derive_target_mass_corrections,
+    derive_trivializing_map,
+    derive_trivializing_flow_factorization,
+    derive_euler_map_inverse_and_jacobian,
+    derive_qpdf_ppdf_fourier_inversion,
+    derive_flow_mcmc_balance,
+    derive_flowed_propagators,
+    derive_pseudo_pdf_ir_regulators,
+    derive_pseudo_pdf_one_loop,
+    derive_quark_gaussian_smearing,
+    derive_u1_gauge_invariance,
+    derive_u1_lattice_field_strength,
+    derive_u1_topological_charge,
+    derive_u1_compact_action,
+    derive_su3_generator_identities,
+    derive_su3_cayley_hamilton,
+    derive_correlated_chi_square_profile,
+    derive_ising_mean_field,
+    derive_ape_projection_su2,
+    derive_wilson_eigenvalue_statistics,
+    derive_wilson_fourier_endpoint,
+    derive_wilson_edge_universal_formulas,
+    derive_wilson_continuum_scale,
+    derive_two_dimensional_wilson_loop,
+    derive_instanton_holonomy_su2,
+    derive_grassmann_determinant_identity,
+    derive_wick_pairing_enumeration,
+    derive_wilson_gap_scaling,
+    derive_wilson_smearing_kernel,
+    derive_wilson_smearing_scaling,
+    derive_wilson_area_law,
+    derive_wilson_flow_five_dimensional,
+    derive_wilson_flow_runge_kutta,
+    derive_gradient_flow_duhamel_solution,
+    derive_wilson_flow_reference_scale,
+    derive_wilson_lattice_flow_monotonicity,
+    derive_flow_integral_ibp,
+    derive_gradient_flow_rg_log_recursion,
+    derive_gradient_flow_scheme_conversion,
+    derive_emt_operator_basis,
+    derive_ringed_fermion_normalization,
+    derive_emt_trace_anomaly,
+    derive_yang_mills_gradient_flow_emt,
+    derive_auxiliary_field_wilson_renormalization,
+    derive_ri_mom_ratio_renormalization,
+    derive_hybrid_renormalization,
+    derive_hybrid_momentum_matching_kernel,
+    derive_twist2_flowed_moment_matching,
+    derive_euclidean_lightcone_factorization,
+    derive_euclidean_ope_factorization,
+    derive_euclidean_renormalization_schemes,
+    derive_euclidean_lattice_data_window,
+    derive_isovector_pdf_extension,
+    derive_isovector_systematic_renorm_matching,
+    derive_quasi_pdf_all_order_renormalization,
+    derive_quasi_gluon_multiplicative_renormalization,
+    derive_power_corrections_renormalons_quasi,
+    derive_quasi_tmd_matching_and_cs_kernel,
+    derive_quasi_tmd_hard_kernel_i_epsilon,
+    derive_ri_xmom_renormalization_conditions,
+    derive_wilson_line_linear_counterterm,
+    derive_quasi_pdf_one_loop_matching_kernel,
+    derive_quasi_pdf_finite_momentum_one_loop_matching_kernel,
+    run_core_checks,
+)
+from .formula_registry import CORE_FORMULAS, FormulaSpec
+from .latex_inventory import (
+    FormulaRecord,
+    InventoryReport,
+    extract_display_formulas,
+    scan_refer_papers,
+)
+from .wick import (
+    FermionField,
+    WickPairing,
+    count_wick_pairings,
+    enumerate_wick_pairings,
+    fermion_fields,
+)
+
+__all__ = [
+    "CORE_FORMULAS",
+    "DerivationResult",
+    "FormulaRecord",
+    "FormulaSpec",
+    "FermionField",
+    "InventoryReport",
+    "WickPairing",
+    "count_wick_pairings",
+    "derive_correlator_spectrum",
+    "derive_diffusion_processes",
+    "derive_gauge_flow_kernel",
+    "derive_collins_soper_evolution",
+    "derive_generating_functional",
+    "derive_gradient_flow",
+    "derive_gradient_flow_energy_density",
+    "derive_heat_kernel_semigroup",
+    "derive_gradient_flow_pole_cancellation",
+    "derive_hmc_scalar",
+    "derive_langevin_fokker_planck",
+    "derive_boosted_smearing_width",
+    "derive_lattice_dispersion_relations",
+    "derive_lamet_matching",
+    "derive_lamet_lightcone_kinematics",
+    "derive_lattice_link",
+    "derive_mcmc_autocorrelation",
+    "derive_stout_smearing_su2",
+    "derive_momentum_smearing_shift",
+    "derive_mellin_convolution",
+    "derive_nonperturbative_renormalization_conditions",
+    "derive_normalizing_flow",
+    "derive_pseudo_itd",
+    "derive_pdf_moment_relations",
+    "derive_phi4_lattice_observables",
+    "derive_renormalization",
+    "derive_tmd_fourier",
+    "derive_quasi_pdf_tmd_relation",
+    "derive_gpd_kinematics_and_matching",
+    "derive_pion_da_normalization",
+    "derive_tmd_soft_rge_consistency",
+    "derive_target_mass_corrections",
+    "derive_trivializing_map",
+    "derive_trivializing_flow_factorization",
+    "derive_euler_map_inverse_and_jacobian",
+    "derive_qpdf_ppdf_fourier_inversion",
+    "derive_flow_mcmc_balance",
+    "derive_flowed_propagators",
+    "derive_pseudo_pdf_ir_regulators",
+    "derive_pseudo_pdf_one_loop",
+    "derive_quark_gaussian_smearing",
+    "derive_u1_gauge_invariance",
+    "derive_u1_lattice_field_strength",
+    "derive_u1_topological_charge",
+    "derive_u1_compact_action",
+    "derive_su3_generator_identities",
+    "derive_su3_cayley_hamilton",
+    "derive_correlated_chi_square_profile",
+    "derive_ising_mean_field",
+    "derive_ape_projection_su2",
+    "derive_wilson_eigenvalue_statistics",
+    "derive_wilson_fourier_endpoint",
+    "derive_wilson_edge_universal_formulas",
+    "derive_wilson_continuum_scale",
+    "derive_two_dimensional_wilson_loop",
+    "derive_instanton_holonomy_su2",
+    "derive_grassmann_determinant_identity",
+    "derive_wick_pairing_enumeration",
+    "derive_wilson_gap_scaling",
+    "derive_wilson_smearing_kernel",
+    "derive_wilson_smearing_scaling",
+    "derive_wilson_area_law",
+    "derive_wilson_flow_five_dimensional",
+    "derive_wilson_flow_runge_kutta",
+    "derive_gradient_flow_duhamel_solution",
+    "derive_wilson_flow_reference_scale",
+    "derive_wilson_lattice_flow_monotonicity",
+    "derive_flow_integral_ibp",
+    "derive_gradient_flow_rg_log_recursion",
+    "derive_gradient_flow_scheme_conversion",
+    "derive_emt_operator_basis",
+    "derive_ringed_fermion_normalization",
+    "derive_emt_trace_anomaly",
+    "derive_yang_mills_gradient_flow_emt",
+    "derive_auxiliary_field_wilson_renormalization",
+    "derive_ri_mom_ratio_renormalization",
+    "derive_hybrid_renormalization",
+    "derive_hybrid_momentum_matching_kernel",
+    "derive_twist2_flowed_moment_matching",
+    "derive_euclidean_lightcone_factorization",
+    "derive_euclidean_ope_factorization",
+    "derive_euclidean_renormalization_schemes",
+    "derive_euclidean_lattice_data_window",
+    "derive_isovector_pdf_extension",
+    "derive_isovector_systematic_renorm_matching",
+    "derive_quasi_pdf_all_order_renormalization",
+    "derive_quasi_gluon_multiplicative_renormalization",
+    "derive_power_corrections_renormalons_quasi",
+    "derive_quasi_tmd_matching_and_cs_kernel",
+    "derive_quasi_tmd_hard_kernel_i_epsilon",
+    "derive_ri_xmom_renormalization_conditions",
+    "derive_wilson_line_linear_counterterm",
+    "derive_quasi_pdf_one_loop_matching_kernel",
+    "derive_quasi_pdf_finite_momentum_one_loop_matching_kernel",
+    "extract_display_formulas",
+    "enumerate_wick_pairings",
+    "fermion_fields",
+    "run_core_checks",
+    "scan_refer_papers",
+]

myqcd-0.1.0/myqcd/__main__.py

@@ -0,0 +1,4 @@
+from .audit import main
+
+
+raise SystemExit(main())

myqcd-0.1.0/myqcd/audit.py

@@ -0,0 +1,213 @@
+"""命令行审计入口：核心 SymPy 检查 + 论文显示公式索引。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable, Sequence
+
+from .derivations import run_core_checks
+from .latex_inventory import (
+    InventoryReport,
+    scan_refer_papers as _scan_refer_papers,
+    write_inventory,
+)
+
+
+class _AppendPaperIDSource(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        sources = getattr(namespace, "paper_id_sources", None)
+        if sources is None:
+            sources = []
+            setattr(namespace, "paper_id_sources", sources)
+        source_type = "paper_ids" if option_string == "--paper-id" else "paper_id_file"
+        sources.append((source_type, values))
+
+
+def _normalize_paper_id_inputs(paper_ids: Iterable[str] | str | None) -> tuple[str, ...]:
+    if paper_ids is None:
+        return ()
+    if isinstance(paper_ids, str):
+        paper_ids = (paper_ids,)
+
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for paper_id in paper_ids:
+        for chunk in paper_id.split(","):
+            candidate = chunk.strip()
+            if candidate and candidate not in seen:
+                seen.add(candidate)
+                normalized.append(candidate)
+    return tuple(normalized)
+
+
+def _paper_ids_from_file(path: Path) -> tuple[str, ...]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise ValueError(f"无法读取 paper id 文件 {path}: {exc}") from exc
+
+    paper_ids: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        paper_ids.append(stripped)
+    return tuple(paper_ids)
+
+
+def _merge_paper_ids(
+    paper_ids: Iterable[str] | str | None = None,
+    paper_id_files: Iterable[Path | str] | None = None,
+) -> tuple[str, ...]:
+    sources: list[tuple[str, Iterable[str] | str | Path]] = []
+    if paper_ids is not None:
+        sources.append(("paper_ids", paper_ids))
+    if paper_id_files:
+        for file_path in paper_id_files:
+            sources.append(("paper_id_file", file_path))
+    return _merge_paper_id_sources(sources)
+
+
+def _merge_paper_id_sources(
+    paper_id_sources: Sequence[tuple[str, Iterable[str] | str | Path]]
+) -> tuple[str, ...]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for source_type, source_value in paper_id_sources:
+        if source_type == "paper_ids":
+            candidates = _normalize_paper_id_inputs(source_value)
+        elif source_type == "paper_id_file":
+            candidates = _paper_ids_from_file(Path(source_value))
+        else:
+            raise ValueError(f"不支持的 paper id 来源: {source_type}")
+        for candidate in candidates:
+            if candidate not in seen:
+                seen.add(candidate)
+                merged.append(candidate)
+    return tuple(merged)
+
+
+def _cli_error_message(exc: ValueError) -> str:
+    message = str(exc)
+    prefix = "paper_ids 中存在未收录的论文编号: "
+    if message.startswith(prefix):
+        return "不存在的 paper id: " + message[len(prefix) :]
+    return message
+
+
+def scan_refer_papers(
+    root: Path | str,
+    paper_ids: Iterable[str] | str | None = None,
+    paper_id_files: Iterable[Path | str] | None = None,
+) -> InventoryReport:
+    """扫描 refer/papers，并按 paper_id 过滤结果。"""
+
+    root_path = Path(root).resolve()
+    normalized_paper_ids = _merge_paper_ids(paper_ids=paper_ids, paper_id_files=paper_id_files)
+    if not normalized_paper_ids:
+        return _scan_refer_papers(root_path)
+    return _scan_refer_papers(root_path, paper_ids=normalized_paper_ids)
+
+
+def _unique_source_files(records) -> tuple[str, ...]:
+    return tuple(dict.fromkeys(record.source_file for record in records))
+
+
+def _build_audit_bundle(
+    root: Path | str,
+    paper_ids: Iterable[str] | str | None = None,
+    paper_id_files: Iterable[Path | str] | None = None,
+) -> tuple[Dict[str, Any], InventoryReport]:
+    core = run_core_checks()
+    requested_paper_ids = _merge_paper_ids(
+        paper_ids=paper_ids,
+        paper_id_files=paper_id_files,
+    )
+    inventory = scan_refer_papers(root, paper_ids=requested_paper_ids)
+    paper_filter = {
+        "enabled": bool(requested_paper_ids),
+        "requested_paper_ids": list(requested_paper_ids),
+        "requested_count": len(requested_paper_ids),
+        "selected_paper_count": inventory.paper_count,
+        "source_files": list(_unique_source_files(inventory.records)),
+    }
+    report = {
+        "status": "verified_core_with_unparsed_inventory"
+        if core["status"] == "verified"
+        else "failed",
+        "core": core,
+        "paper_ids": list(requested_paper_ids),
+        "paper_filter": paper_filter,
+        "inventory": {
+            "paper_count": inventory.paper_count,
+            "source_file_count": inventory.source_file_count,
+            "formula_count": inventory.formula_count,
+            "unparsed_count": inventory.unparsed_count,
+        },
+    }
+    return report, inventory
+
+
+def build_audit_report(
+    root: Path | str,
+    paper_ids: Iterable[str] | str | None = None,
+    paper_id_files: Iterable[Path | str] | None = None,
+) -> Dict[str, Any]:
+    report, _ = _build_audit_bundle(
+        root,
+        paper_ids=paper_ids,
+        paper_id_files=paper_id_files,
+    )
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.set_defaults(paper_id_sources=[])
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path(__file__).resolve().parents[1],
+        help="MyQCD 工作区根目录",
+    )
+    parser.add_argument(
+        "--paper-id",
+        action=_AppendPaperIDSource,
+        metavar="PAPER_ID",
+        help="可重复指定，或用逗号分隔多个编号，例如 --paper-id P01 --paper-id P02 或 --paper-id P01,P02",
+    )
+    parser.add_argument(
+        "--paper-id-file",
+        action=_AppendPaperIDSource,
+        type=Path,
+        metavar="PATH",
+        help="每行一个 paper id，支持空行和以 # 开头的注释",
+    )
+    parser.add_argument(
+        "--inventory-json",
+        type=Path,
+        help="可选：将逐公式索引写入指定 JSON 文件",
+    )
+    args = parser.parse_args()
+
+    try:
+        requested_paper_ids = _merge_paper_id_sources(
+            getattr(args, "paper_id_sources", ())
+        )
+        report, inventory = _build_audit_bundle(
+            args.root,
+            paper_ids=requested_paper_ids,
+        )
+    except ValueError as exc:
+        parser.exit(2, f"error: {_cli_error_message(exc)}\n")
+    if args.inventory_json is not None:
+        write_inventory(args.inventory_json, inventory)
+        report["inventory_json"] = str(args.inventory_json)
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0 if report["status"] != "failed" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())