wl_cli（wl CLI）

wl_cli 是一个以 Click 构建的命令行工具（入口 wl），面向 Python 项目的初始化、构建、 测试、格式化、lint、清理与质量门等日常开发工作流。发行物是纯 Python wheel （py3-none-any），安装与运行都不需要 Rust 工具链；Rust 扩展是可选的诊断件， 缺失时自动回落纯 Python 实现。

功能概览

命令行别名：b→build、c→clean、f→format、i→init。 完整命令参考见 CLI_COMMANDS.md。

环境要求

• Python >= 3.11（纯 Python 路径，安装与运行都不需要 Rust/cargo）
• 包管理器推荐 uv

平台支持矩阵

同一个 py3-none-any wheel 覆盖以上全部平台。平台报告由 wl_cli.platform.platform_payload() 统一产出 （platform / python / native_extension / supported / reason）， 其中 native_extension 只作诊断——Rust 扩展可选，缺失不影响 supported。

安装

稳定版（PyPI）

pip install py-wlcli

按需安装可选 extra：pip install "py-wlcli[lfs]"（LFS watch）、 pip install "py-wlcli[test]"（测试套件）、pip install "py-wlcli[dev]"（开发工具）。 详见安装文档。

开发版（从源码）

# 以 GitLab 为主仓（origin），GitHub 为镜像
git clone https://gitlab.gewinnrobo.com/Humuyuan/wl-cli.git
cd wl_cli
uv pip install -e ".[dev,test]"

GitHub 镜像：https://github.com/CharlieZi/wl-cli.git

快速开始

wl --help       # 查看帮助
wl init         # 初始化项目
wl build        # 构建
wl test         # 运行测试
wl format       # 格式化代码
wl lint         # 代码质量检查

测试与质量门

wl test              # 运行全部测试
wl test --cover      # 覆盖率（阈值 70%）
wl test -s           # 逐个测试文件运行，首个失败即停
pytest tests/ -v     # 指定文件（pytest 直跑）

提交前请确保 pre-commit 通过（ruff、codespell、lockfile 一致性等）。 开发约束详见 CLAUDE.md， 贡献流程见 CONTRIBUTING.md。

文档

• CLI_COMMANDS.md — 命令参考
• CONTEXT.md — 架构术语（Click 迁移语境）
• docs/ — 设计、ADR、章节与 CICD/发布文档
• 安装文档 — 安装细节与 shell 补全

架构速览

Click CLI（src/wl_cli/cli_click.py 经 setup_commands() 直接注册）→ 各命令实现（commands/<group>/）→ 业务逻辑。 Rust 扩展是可选的诊断件：src/wl_cli/lib/rust_utils.py 在 wl_cli_native 不可用时回落纯 Python；发行 wheel 不包含任何原生二进制。 架构演进背景见 Click 迁移设计。

许可证

MIT，见 LICENSE。