nltbuild

nltbuild 是面向 Python / 混合仓库的构建与发布辅助工具：根据项目结构自动选择构建策略（UV、Poetry、旧式 PyPI 脚本、package.json 前端包及混合模式等），串联版本递增、构建、安装校验、发布与 Git 标签等常见流程。

特性

• 多构建策略：按仓库布局自动匹配 UVBuild、PoetryBuild、PypiBuild、NpmFrontendBuild、UvNpmHybridBuild 等实现，无需手写切换逻辑。
• 版本同步：以根目录 pyproject.toml 的 [project].version 为主源时，可将版本同步到仓内其它带 version 的 pyproject.toml 与 package.json（含子目录）。
• 依赖与工具链：内置对 uv、ruff 等工具的调用约定；日志通过 nltlog，Shell 流程通过 funshell。
• Git 工作流：pull / push / tags 等与远程协作；push 在提交阶段优先用 aicommits 生成说明，未安装时自动回退到默认信息。
• 失败即中止：任一 shell 步骤返回非 0 即抛出 ShellCommandError 并以非 0 码退出，构建失败不会继续推送或打标签。
• 维护命令：clean 与 clean-history 会改写 Git 状态或强制重写远程历史，使用前请确认团队规范与备份策略。

系统要求

• Python 3.9+
• Git（版本管理与标签推送）
• 可选：aicommits（npm install -g aicommits）。装了则 push 用它生成提交信息，没装则回退到 message 参数的值，不影响流程。

安装

从 PyPI 安装

pip install nltbuild

从源码安装

git clone https://github.com/farfarfun/nltbuild.git
cd nltbuild
pip install .

使用 uv 时，可在克隆后执行 uv sync 或 uv pip install -e . 进行可编辑安装。

命令一览

在项目根目录执行（入口由 pyproject.toml 的 [project.scripts] 注册为 nltbuild）：

命令名中的下划线会被 typer 转成连字符，因此是 clean-history 而非 clean_history。

版本

nltbuild upgrade

自增规则为 128 进制进位：patch 满 128 向 minor 进位，minor 满 128 向 major 进位。

1.6.54  → 1.6.55
1.6.127 → 1.7.0
1.127.127 → 2.0.0

版本号会写回根 pyproject.toml，并同步到仓内所有带 version 字段的 pyproject.toml 与 package.json（含 extbuild/ exts/ 子目录）。非三段版本按缺位补 0 处理（1.0 视作 1.0.0）；1.0.0rc1 这类预发布后缀会被丢弃并打印告警。

CLI 未提供「写入指定版本号」参数，需要固定版本时请直接编辑清单文件。

Git

nltbuild pull

# 默认每 20 个文件一次提交
nltbuild push

# 自定义每个提交的文件数
nltbuild push --batch-size 50

# 指定提交信息（未安装 aicommits 时生效）；注意这里是选项而非位置参数
nltbuild push --message "fix: typo"

push 会先执行 git reset 清空暂存区再按批次重新 add，已手工 git add 的内容会被一并纳入分批提交。

构建与发布

# 完整流水线
nltbuild build

# release 是 build 的别名，两者完全等价
nltbuild release

# 仅构建并安装到当前环境，不发布、不推送
nltbuild install

build 依次触发：pull → upgrade → 清理 → 构建 → 安装校验 → 发布 → 清理 → push → tags。实际命令序列取决于选中的 Build 类型。任一步失败会立即中止，不会继续 push 或打标签。

维护类（高风险）

nltbuild clean          # 重建索引，使新增的 .gitignore 规则生效
nltbuild clean-history  # 抹掉全部历史与标签并强推，不可恢复且无二次确认

发布凭据

uv publish 的凭据从 ~/.pypirc 读取。服务器名的选取顺序为：pyproject.toml 中 [[tool.uv.index]] 的 name > ~/.pypirc 里 [distutils].index-servers 的首项 > 默认 pypi。

[distutils]
index-servers = pypi

[pypi]
username = __token__
password = pypi-AgEIcHl...

凭据以 UV_PUBLISH_TOKEN / UV_PUBLISH_USERNAME / UV_PUBLISH_PASSWORD / UV_PUBLISH_URL 环境变量传给 uv，不会出现在命令行参数中（否则完整命令行会通过进程表对本机所有用户可见）。

CI 环境可以不放 .pypirc，直接导出这些环境变量即可：

export UV_PUBLISH_TOKEN=pypi-AgEIcHl...
nltbuild build

错误处理

所有 shell 步骤经 run_checked() 执行，退出码非 0 即抛 ShellCommandError，进程以非 0 码退出。这意味着 nltbuild build 在构建或发布失败时不会再继续 push 和 tags，可直接用于 CI 的失败判定。

配置说明

• Python 项目：在根目录 pyproject.toml 中维护 [project].version 与依赖；UV 类构建会读写该版本并同步到其它清单。
• 纯前端 / 子包：在对应 package.json 中可使用 nltbuild 字段（对象或 true）扩展行为（例如自定义 build 命令、cleanDirs 等），具体逻辑见源码中 NpmFrontendBuild。

构建类型的判定顺序见 src/nltbuild/core/registry.py 中的注册表；无需再使用旧文档中的 [tool.funbuild] 等虚构段名。

集成组件

• uv — 包管理与构建
• ruff — Lint / 格式化（按项目配置使用）
• typer（typer-slim）— CLI 框架
• aicommits — 默认与 push 流水线集成的提交信息生成（以本机 CLI 为准）

仓库布局（摘要）

nltbuild/
├── src/
│   └── nltbuild/
│       ├── core/       # 构建注册与各策略实现
│       └── tool/       # 附加工具入口
├── tests/              # 单元测试
├── pyproject.toml
└── README.md

参与贡献

1. Fork nltbuild
2. 新建分支并提交变更
3. 发起 Pull Request

本地开发示例：

git clone https://github.com/farfarfun/nltbuild.git
cd nltbuild
uv pip install -e .
# 或: pip install -e .

# 跑测试
python -m pytest tests/ -q

# 格式化与静态检查
ruff format .
ruff check . --fix

许可证

本项目以 MIT 许可证 发布。

链接

• 源码仓库
• PyPI：nltbuild
• Issues

维护者

• 牛哥 — niuliangtao@qq.com
• farfarfun — farfarfun@qq.com

若 nltbuild 对你有帮助，欢迎点个 Star。