shipcli 0.0.1__tar.gz

shipcli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CaffeineOddity
+
+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.

shipcli-0.0.1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: shipcli
+Version: 0.0.1
+Summary: Pure Python CLI scaffold and delivery tool.
+Author: CaffeineOddity
+License-Expression: MIT
+Keywords: cli,scaffold,pyinstaller,release,tooling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: build
+Requires-Dist: pyinstaller>=6.0; extra == "build"
+Provides-Extra: publish
+Requires-Dist: twine>=5.1.0; extra == "publish"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=9.0.0; extra == "dev"
+Dynamic: license-file
+
+# shipcli
+
+`shipcli` 是一个纯 Python 的 CLI 脚手架与交付工具，用来初始化、构建、发布、安装和升级命令行项目。
+
+## 特性
+
+- 用 `shipcli init <path>` 快速生成新的 Python CLI 项目
+- 用 `shipcli build` / `shipcli build --release` 生成 dev 或 release 版的 wheel/sdist 分发文件
+- 用 `shipcli publish` 把 release 版本发布到 GitHub Release 或 PyPI
+- `shipcli upgrade` / `uninstall` 只管 shipcli 自身；项目 CLI（如 demo-cli）用其自带命令管理
+- 默认以当前目录作为项目目录，也支持 `--project <path>` 跨目录操作
+- 初始化后的项目默认包含 `help`、`version`、`upgrade`、`uninstall` 命令示例
+
+## 命令作用范围
+
+| 命令 | 作用对象 |
+|------|---------|
+| `init` / `build` / `install` / `publish` | 目标项目（当前目录或 `--project`，如 demo-cli） |
+| `upgrade` / `uninstall` | shipcli 自身 |
+
+若要升级或卸载某个项目 CLI（如 demo-cli），应先 `install` 安装它，再用其自带命令：`demo-cli upgrade` / `demo-cli uninstall`。
+
+## 安装
+
+### 首次安装（开发）
+
+shipcli 未发布到 PyPI 前，从本地仓库安装：
+
+```bash
+git clone <your-repo-url>
+cd shipcli
+python3 -m pip install -e .   # editable 安装，改代码即生效
+```
+
+安装完成后：
+
+```bash
+shipcli --help
+shipcli --version             # 形如：shipcli 0.0.1 (editable)
+```
+
+`--version` / `--help` 会标注当前安装形态：`editable`（editable 安装）、`installed`（pip 正式安装）、`binary`（PyInstaller 二进制）。
+
+### 安装 build 产物
+
+`shipcli build` 产出 wheel/sdist 后，可直接装本地 wheel（模拟用户从 PyPI 安装）：
+
+```bash
+shipcli build --release
+python3 -m pip install .build/dist/0.0.1/dist/*.whl
+```
+
+## 快速开始
+
+```bash
+shipcli init demo-cli
+
+cd demo-cli
+shipcli build                    # dev 构建，产出 <version>.devN
+shipcli build --release          # release 构建，产出发布版 wheel/sdist
+shipcli publish --github --pypi  # 发布到 GitHub Release + PyPI
+```
+
+也支持不切目录，直接指定目标项目：
+
+```bash
+shipcli build --project ./demo-cli
+shipcli publish --project ./demo-cli --github --github-repo owner/demo-cli
+```
+
+## 构建
+
+`shipcli build` 产出标准的 Python 分发文件（wheel/sdist），不再依赖 PyInstaller：
+
+- **dev 构建**（`shipcli build`）：版本号 `<base>.devN`（如 `0.0.1.dev1`），build 号自动 +1。用于本地验证。
+- **release 构建**（`shipcli build --release`）：版本号取配置中的 `version`（如 `0.0.1`）。
+- **版本递增**（`--increase <major|minor|patch>`）：构建前把版本号指定位 +1（低位归零）并重置 build，可与 `--release` 同用。
+
+版本号唯一真源是 `build.config.json` 的 `version`；release 构建会自动同步到 `pyproject.toml`，构建时会写入包 `__init__.py` 的 `__version__`。
+
+```bash
+shipcli build                              # dev 构建
+shipcli build --release                    # release 构建
+shipcli build --increase patch             # patch+1 后 dev 构建
+shipcli build --increase minor --release   # minor+1 后 release 构建
+```
+
+产物目录结构：
+
+```text
+.build/dist/<version>/dist/
+├── <name>-<version>-py3-none-any.whl
+└── <name>-<version>.tar.gz
+```
+
+## 升级 shipcli 自身
+
+```bash
+shipcli upgrade                       # 从 PyPI 升级到最新发布版
+shipcli upgrade --version 0.0.1       # 从 PyPI 升级到指定发布版
+shipcli upgrade --local .             # 从本地项目 build 产物升级（取最新版本）
+shipcli upgrade --local . --version 0.0.1.dev1   # 指定本地 build 产物版本
+shipcli uninstall                     # 卸载 shipcli（pip 卸载 + 清理本地痕迹）
+```
+
+dev 版不上 PyPI，仅本地安装/升级：先 `shipcli build` 产出 dev wheel，再用 `shipcli upgrade --local .` 装上。
+
+## 发布
+
+- `shipcli publish` 只做发布，不负责构建
+- 发布前先执行 `shipcli build --release`
+- 发布到 GitHub Release：上传 wheel/sdist 及各自的 `.sha256` 校验文件
+- 发布到 PyPI：上传 wheel/sdist
+- GitHub 凭证只从环境变量读取：`SHIPCLI_GITHUB_TOKEN` 或 `GITHUB_TOKEN`
+- GitHub 仓库可通过 `--github-repo` 传入，或设置 `SHIPCLI_GITHUB_REPO` / `GITHUB_REPOSITORY`
+- PyPI 凭证只从环境变量读取：`SHIPCLI_PYPI_TOKEN`，也兼容现有 `TWINE_PASSWORD`
+- `publish` 只支持 release 版本，不接受 dev 版本
+
+```bash
+cd demo-cli
+
+# 发布本地已构建的 release 分发文件到 GitHub Release + PyPI
+shipcli build --release
+SHIPCLI_GITHUB_TOKEN=... SHIPCLI_PYPI_TOKEN=... \
+shipcli publish --github --pypi --github-repo owner/demo-cli
+```
+
+## 初始化后的目录结构
+
+执行 `shipcli init demo-cli` 后，默认会生成：
+
+```text
+demo-cli/
+├── build.config.json
+├── README.md
+├── demo_cli/
+│   ├── __init__.py
+│   ├── __main__.py
+│   ├── cli.py
+│   └── commands/
+│       ├── __init__.py
+│       ├── help.py
+│       ├── version.py
+│       ├── upgrade.py
+│       └── uninstall.py
+└── tests/
+    └── test_cli.py
+```
+
+## 开发验证
+
+```bash
+python3 -m pytest
+shipcli build --release
+```

shipcli-0.0.1/README.md

@@ -0,0 +1,155 @@
+# shipcli
+
+`shipcli` 是一个纯 Python 的 CLI 脚手架与交付工具，用来初始化、构建、发布、安装和升级命令行项目。
+
+## 特性
+
+- 用 `shipcli init <path>` 快速生成新的 Python CLI 项目
+- 用 `shipcli build` / `shipcli build --release` 生成 dev 或 release 版的 wheel/sdist 分发文件
+- 用 `shipcli publish` 把 release 版本发布到 GitHub Release 或 PyPI
+- `shipcli upgrade` / `uninstall` 只管 shipcli 自身；项目 CLI（如 demo-cli）用其自带命令管理
+- 默认以当前目录作为项目目录，也支持 `--project <path>` 跨目录操作
+- 初始化后的项目默认包含 `help`、`version`、`upgrade`、`uninstall` 命令示例
+
+## 命令作用范围
+
+| 命令 | 作用对象 |
+|------|---------|
+| `init` / `build` / `install` / `publish` | 目标项目（当前目录或 `--project`，如 demo-cli） |
+| `upgrade` / `uninstall` | shipcli 自身 |
+
+若要升级或卸载某个项目 CLI（如 demo-cli），应先 `install` 安装它，再用其自带命令：`demo-cli upgrade` / `demo-cli uninstall`。
+
+## 安装
+
+### 首次安装（开发）
+
+shipcli 未发布到 PyPI 前，从本地仓库安装：
+
+```bash
+git clone <your-repo-url>
+cd shipcli
+python3 -m pip install -e .   # editable 安装，改代码即生效
+```
+
+安装完成后：
+
+```bash
+shipcli --help
+shipcli --version             # 形如：shipcli 0.0.1 (editable)
+```
+
+`--version` / `--help` 会标注当前安装形态：`editable`（editable 安装）、`installed`（pip 正式安装）、`binary`（PyInstaller 二进制）。
+
+### 安装 build 产物
+
+`shipcli build` 产出 wheel/sdist 后，可直接装本地 wheel（模拟用户从 PyPI 安装）：
+
+```bash
+shipcli build --release
+python3 -m pip install .build/dist/0.0.1/dist/*.whl
+```
+
+## 快速开始
+
+```bash
+shipcli init demo-cli
+
+cd demo-cli
+shipcli build                    # dev 构建，产出 <version>.devN
+shipcli build --release          # release 构建，产出发布版 wheel/sdist
+shipcli publish --github --pypi  # 发布到 GitHub Release + PyPI
+```
+
+也支持不切目录，直接指定目标项目：
+
+```bash
+shipcli build --project ./demo-cli
+shipcli publish --project ./demo-cli --github --github-repo owner/demo-cli
+```
+
+## 构建
+
+`shipcli build` 产出标准的 Python 分发文件（wheel/sdist），不再依赖 PyInstaller：
+
+- **dev 构建**（`shipcli build`）：版本号 `<base>.devN`（如 `0.0.1.dev1`），build 号自动 +1。用于本地验证。
+- **release 构建**（`shipcli build --release`）：版本号取配置中的 `version`（如 `0.0.1`）。
+- **版本递增**（`--increase <major|minor|patch>`）：构建前把版本号指定位 +1（低位归零）并重置 build，可与 `--release` 同用。
+
+版本号唯一真源是 `build.config.json` 的 `version`；release 构建会自动同步到 `pyproject.toml`，构建时会写入包 `__init__.py` 的 `__version__`。
+
+```bash
+shipcli build                              # dev 构建
+shipcli build --release                    # release 构建
+shipcli build --increase patch             # patch+1 后 dev 构建
+shipcli build --increase minor --release   # minor+1 后 release 构建
+```
+
+产物目录结构：
+
+```text
+.build/dist/<version>/dist/
+├── <name>-<version>-py3-none-any.whl
+└── <name>-<version>.tar.gz
+```
+
+## 升级 shipcli 自身
+
+```bash
+shipcli upgrade                       # 从 PyPI 升级到最新发布版
+shipcli upgrade --version 0.0.1       # 从 PyPI 升级到指定发布版
+shipcli upgrade --local .             # 从本地项目 build 产物升级（取最新版本）
+shipcli upgrade --local . --version 0.0.1.dev1   # 指定本地 build 产物版本
+shipcli uninstall                     # 卸载 shipcli（pip 卸载 + 清理本地痕迹）
+```
+
+dev 版不上 PyPI，仅本地安装/升级：先 `shipcli build` 产出 dev wheel，再用 `shipcli upgrade --local .` 装上。
+
+## 发布
+
+- `shipcli publish` 只做发布，不负责构建
+- 发布前先执行 `shipcli build --release`
+- 发布到 GitHub Release：上传 wheel/sdist 及各自的 `.sha256` 校验文件
+- 发布到 PyPI：上传 wheel/sdist
+- GitHub 凭证只从环境变量读取：`SHIPCLI_GITHUB_TOKEN` 或 `GITHUB_TOKEN`
+- GitHub 仓库可通过 `--github-repo` 传入，或设置 `SHIPCLI_GITHUB_REPO` / `GITHUB_REPOSITORY`
+- PyPI 凭证只从环境变量读取：`SHIPCLI_PYPI_TOKEN`，也兼容现有 `TWINE_PASSWORD`
+- `publish` 只支持 release 版本，不接受 dev 版本
+
+```bash
+cd demo-cli
+
+# 发布本地已构建的 release 分发文件到 GitHub Release + PyPI
+shipcli build --release
+SHIPCLI_GITHUB_TOKEN=... SHIPCLI_PYPI_TOKEN=... \
+shipcli publish --github --pypi --github-repo owner/demo-cli
+```
+
+## 初始化后的目录结构
+
+执行 `shipcli init demo-cli` 后，默认会生成：
+
+```text
+demo-cli/
+├── build.config.json
+├── README.md
+├── demo_cli/
+│   ├── __init__.py
+│   ├── __main__.py
+│   ├── cli.py
+│   └── commands/
+│       ├── __init__.py
+│       ├── help.py
+│       ├── version.py
+│       ├── upgrade.py
+│       └── uninstall.py
+└── tests/
+    └── test_cli.py
+```
+
+## 开发验证
+
+```bash
+python3 -m pytest
+shipcli build --release
+```

shipcli-0.0.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shipcli"
+version = "0.0.1"
+description = "Pure Python CLI scaffold and delivery tool."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "CaffeineOddity" }
+]
+keywords = ["cli", "scaffold", "pyinstaller", "release", "tooling"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Utilities"
+]
+dependencies = []
+
+[project.optional-dependencies]
+build = [
+  "pyinstaller>=6.0"
+]
+publish = [
+  "twine>=5.1.0"
+]
+dev = [
+  "build>=1.2.2",
+  "pytest>=9.0.0"
+]
+
+[project.scripts]
+shipcli = "shipcli.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["shipcli*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shipcli-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shipcli-0.0.1/shipcli/__init__.py

@@ -0,0 +1,5 @@
+"""shipcli 包入口。"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.1"

shipcli-0.0.1/shipcli/__main__.py

@@ -0,0 +1,11 @@
+"""shipcli 模块入口。"""
+
+from __future__ import annotations
+
+import sys
+
+from shipcli.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shipcli-0.0.1/shipcli/builder.py

@@ -0,0 +1,220 @@
+"""shipcli 纯 Python 构建流程。
+
+方向 A：build 产出标准的 wheel/sdist（去掉 PyInstaller 二进制）。
+- debug 构建（`shipcli build`）产 dev 版 wheel，版本号 `<base>.devN`。
+- release 构建（`shipcli build --release`）产 release 版 wheel/sdist。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from shipcli.config import BuildConfig, config_path, load_config
+
+
+@dataclass(frozen=True)
+class BuildPlan:
+    """描述一次构建的关键路径与版本信息。"""
+
+    app_name: str
+    build_root: Path
+    dist_root: Path
+    product_dir: Path
+    dist_dir: Path
+    product_version: str
+    base_version: str
+    build_number: int
+    release: bool
+
+
+def bump_version(version: str, part: str) -> str:
+    """把语义版本号的指定位 +1，低位归零。"""
+    if part not in {"major", "minor", "patch"}:
+        raise ValueError("版本位仅支持 major / minor / patch")
+    segments = version.split(".")
+    if len(segments) != 3 or not all(seg.isdigit() for seg in segments):
+        raise ValueError(f"版本号不是标准的三段语义版本：{version}")
+    major, minor, patch = (int(seg) for seg in segments)
+    if part == "major":
+        major, minor, patch = major + 1, 0, 0
+    elif part == "minor":
+        minor, patch = minor + 1, 0
+    else:
+        patch += 1
+    return f"{major}.{minor}.{patch}"
+
+
+def resolve_build_plan(
+    project_root: Path,
+    config: BuildConfig,
+    release: bool = False,
+    increase: str | None = None,
+) -> BuildPlan:
+    """根据配置和参数生成本次构建计划。"""
+    if increase is not None:
+        base_version = bump_version(config["version"], increase)
+    else:
+        base_version = config["version"]
+
+    build_root = project_root / config["build_root"]
+    dist_root = build_root / "dist"
+    if release:
+        build_number = config["build"]
+        product_version = base_version
+    else:
+        build_number = config["build"] + 1
+        # PEP 440 规范的 dev 版本号：`<base>.devN`（可被 pip/PyPI 接受）。
+        product_version = f"{base_version}.dev{build_number}"
+
+    product_dir = dist_root / product_version
+    dist_dir = product_dir / "dist"
+    return BuildPlan(
+        app_name=config["app_name"],
+        build_root=build_root,
+        dist_root=dist_root,
+        product_dir=product_dir,
+        dist_dir=dist_dir,
+        product_version=product_version,
+        base_version=base_version,
+        build_number=build_number,
+        release=release,
+    )
+
+
+def run_build(
+    project_root: Path,
+    release: bool = False,
+    increase: str | None = None,
+) -> BuildPlan:
+    """生成本次构建的 wheel/sdist，并在 debug 构建成功后回写 build。"""
+    config = load_config(project_root)
+    if not (project_root / "pyproject.toml").is_file():
+        raise FileNotFoundError("未找到 pyproject.toml，无法构建分发文件")
+    if shutil_is_missing_python():
+        raise RuntimeError("未找到可用的 Python 解释器")
+
+    # --increase 先把 bump 后的版本与重置的 build=0 回写配置，再据此生成计划，
+    # 保证后续 dev 号、产物目录都基于新版本与新 build 号。
+    if increase is not None:
+        config["version"] = bump_version(config["version"], increase)
+        config["build"] = 0
+        _write_version_and_build(project_root, config["version"], config["build"])
+
+    plan = resolve_build_plan(project_root, config, release=release, increase=None)
+
+    plan.build_root.mkdir(parents=True, exist_ok=True)
+    if plan.product_dir.exists():
+        import shutil
+
+        shutil.rmtree(plan.product_dir)
+    plan.product_dir.mkdir(parents=True, exist_ok=True)
+
+    # release 构建需把版本同步到 pyproject.toml，再产 wheel/sdist；
+    # dev 构建也要把 dev 版号同步进 pyproject.toml，否则 wheel 版本号不对。
+    target_version = plan.base_version if plan.release else plan.product_version
+    _sync_pyproject_version(project_root, target_version)
+    _write_package_version(project_root, config, plan.product_version)
+    _build_distributions(project_root, plan)
+
+    if not plan.release:
+        _write_build_number(project_root, plan.build_number)
+    else:
+        # release 构建会改写版本相关文件，git 仓库下自动提交，
+        # 保证后续 publish 打的 tag 落在「版本号已更新」的完整 commit 上。
+        _maybe_commit_release(project_root, plan.base_version)
+    return plan
+
+
+def _maybe_commit_release(project_root: Path, version: str) -> None:
+    """release 构建后，若为 git 仓库且有改动，自动提交版本发布点。"""
+    from shipcli.publisher import git_commit_all, git_working_tree_clean, is_git_repo
+
+    if not is_git_repo(project_root):
+        return
+    if git_working_tree_clean(project_root):
+        return
+    git_commit_all(project_root, f"release v{version}")
+
+
+def shutil_is_missing_python() -> bool:
+    """检测当前解释器是否可用（保留可测试的薄封装）。"""
+    import shutil
+
+    return shutil.which(sys.executable) is None
+
+
+def _build_distributions(project_root: Path, plan: BuildPlan) -> None:
+    """调用 `python -m build` 生成 wheel/sdist 到 plan.dist_dir。"""
+    if importlib.util.find_spec("build") is None:
+        raise RuntimeError("未安装 build，请先执行 `python3 -m pip install build`")
+
+    plan.dist_dir.mkdir(parents=True, exist_ok=True)
+    command = [
+        sys.executable,
+        "-m",
+        "build",
+        "--outdir",
+        str(plan.dist_dir),
+        str(project_root),
+    ]
+    subprocess.run(command, check=True, cwd=project_root)
+    if not any(plan.dist_dir.glob("*.whl")):
+        raise RuntimeError(f"分发文件构建失败：{plan.dist_dir}")
+
+
+def _package_init_path(project_root: Path, config: BuildConfig) -> Path:
+    """根据构建入口推导包根目录下的 __init__.py 路径。"""
+    entry = config["entry"]
+    package = entry.split("/__main__.py", 1)[0] if entry.endswith("/__main__.py") else entry.rsplit("/", 1)[0]
+    return project_root / package / "__init__.py"
+
+
+def _write_package_version(project_root: Path, config: BuildConfig, version: str) -> None:
+    """把本次构建版本写入包 __init__.py 的 __version__，供打包后运行时读取。"""
+    path = _package_init_path(project_root, config)
+    if not path.is_file():
+        raise FileNotFoundError(f"包入口文件不存在：{path}")
+    text = path.read_text(encoding="utf-8")
+    pattern = re.compile(r'(?m)^(__version__\s*=\s*")([^"]*)("\s*)$')
+    if not pattern.search(text):
+        raise RuntimeError(f"{path} 缺少 __version__ 定义，无法写入版本号")
+    synced = pattern.sub(lambda m: f'{m.group(1)}{version}{m.group(3)}', text)
+    if synced != text:
+        path.write_text(synced, encoding="utf-8")
+
+
+def _sync_pyproject_version(project_root: Path, version: str) -> None:
+    """把目标版本同步到 pyproject.toml，保证 wheel 版本号正确。"""
+    path = project_root / "pyproject.toml"
+    if not path.is_file():
+        return
+    text = path.read_text(encoding="utf-8")
+    pattern = re.compile(r'(?m)^(\s*version\s*=\s*")([^"]*)("\s*)$')
+    if not pattern.search(text):
+        return  # 静态版本号缺失时跳过（可能用了动态版本，不强行改写）
+    synced = pattern.sub(lambda m: f'{m.group(1)}{version}{m.group(3)}', text)
+    if synced != text:
+        path.write_text(synced, encoding="utf-8")
+
+
+def _write_version_and_build(project_root: Path, version: str, build: int) -> None:
+    """更新 build.config.json 中的 version 与 build 字段。"""
+    path = config_path(project_root)
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    payload["version"] = version
+    payload["build"] = build
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def _write_build_number(project_root: Path, build_number: int) -> None:
+    """只更新 build.config.json 中的 build 字段。"""
+    path = config_path(project_root)
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    payload["build"] = build_number
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")