xb - 前后端打包构建工具
xb(PyPI: xb-init)是一个基于 uv 又类似 uv 的项目管理工具,专为快速初始化 UV + FastAPI + Vue3 + Electron 桌面应用而生。一条命令拉起完整工程脚手架,开发、构建、版本管理一站式搞定。
核心特性
- 一键初始化完整项目结构(
xb init demo) - UV + FastAPI + Vue3 + Electron 开箱即用
- 自动安装前端和 Electron 依赖(
npm install,内置国内镜像源) - 自动
git init并提交首个 commit(含 lock 文件) - 自动生成
AGENTS.md(AI 编码助手协作约定) - 内置全局亮色/暗色主题切换
- 可选 sudo 免密配置(
--sudoers) - 可选内置终端(
--terminal) - 可选应用内自动更新(
--update,飞书云盘发布 + 版本检查 + 下载校验 + 自动安装) - 可选自定义应用图标(
--icon) - 内置开发、构建、版本管理命令
- 自动版本检查与一键升级(
xb --upgrade) - 环境诊断(
xb doctor) - Linux DEB 与 Windows NSIS 安装支持
安装
# 安装 uv(若已有可跳过)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 方式一:从 PyPI 安装(推荐)
uv tool install xb-init
# 方式二:从源码安装
git clone -b release_v0 https://github.com/xuebli/xb.git
cd xb
uv sync
uv tool install .
# 验证
xb --help
快速开始
# 创建项目
xb init demo
# 带 sudo 免密配置
xb init demo --sudoers
# 带内置终端
xb init demo --terminal
# 同时启用终端和 sudo 免密配置
xb init demo --terminal --sudoers
# 启用应用内自动更新(自动附带 --sudoers 免密,输入 sudo 密码即可)
xb init demo --update
# 带自定义图标
xb init demo --icon ~/icons/app.png
cd demo
# 启动开发环境
xb dev
# 查看状态
xb dev status
# 停止
xb dev stop
Windows PowerShell 也可以直接运行生成项目脚本:
Set-Location demo
python .\dev.py start
python .\dev.py status
python .\dev.py stop
使用 --terminal 时,Windows 终端使用 PowerShell + ConPTY,支持上下箭头
命令历史、复制粘贴、Tab 补全和 Ctrl+C;Ubuntu/Debian 使用 bash + Unix PTY。
Electron 二进制镜像通过 ELECTRON_MIRROR 环境变量注入。
若安装过程被网络中断,生成项目的
electron/prepare.js 会在 npm start 或 npm run build 前自动检查并补装
缺失的 Electron 二进制。
xb init自动行为:
- 执行
npm install(frontend + electron),生成package-lock.json- 执行
git init并提交首个 commit(包含所有文件和 lock 文件)- 若检测到 PyPI 有新版 xb,会询问是否先升级再创建项目
- 若系统未安装 git 或未配置
user.name/user.email,打印警告但不阻塞
命令一览
| 命令 | 说明 |
|---|---|
xb init <name> [--sudoers] [--terminal] [--update] [--icon PATH] |
初始化项目 |
xb dev [start|stop|status] |
启动/停止/查看开发环境 |
xb build [all|frontend|backend|electron] |
构建项目 |
xb build -f / -b / -e / -a |
构建快捷 flag |
xb version [patch|minor|major] |
读取或更新版本号 |
xb doctor |
检查开发环境 |
xb --upgrade |
升级 xb 到 PyPI 最新版本 |
应用图标
# 显式指定图标
xb init demo --icon ./my-icon.png
# 不指定时自动查找以下约定路径:
# ./app-icon.png, ./icon.png, ./<package>.png,
# ./assets/app-icon.png, ./assets/icon.png, ./resources/icon.png
应用内自动更新(--update)
xb init demo --update 会让生成的项目内置与 leo_stm32_board_test 同源的自动更新能力,
以飞书云盘的一个文件夹作为发布"货架":
生成内容:
| 位置 | 职责 |
|---|---|
backend/api/update/ |
更新接口(检查 / 信息 / 下载 / 进度 / 安装) |
backend/services/updater.py |
版本比较、信息拉取、下载校验、配置备份迁移、安装 |
backend/services/feishu_client.py |
飞书接口封装(文件夹列举、并发下载) |
backend/managers/secret_obfuscator.py |
敏感值混淆(obf1:,防围观级别) |
backend/app_version.py |
后端版本号(version_manager 提交时自动同步) |
frontend/src/components/UpdateChecker.vue |
版本号徽章 + 更新弹窗 + 进度条 |
frontend/src/composables/useUpdate.js |
定时检查 / 下载进度轮询 |
scripts/feishu_upload.py |
发版端:安装包与版本信息上传飞书 |
configs/config_changes.json |
配置迁移清单(顶层 key 是版本号) |
build.py |
增加 --upload-only 与构建后发布编排 |
发版流程: 在 configs/secrets.yaml 填 feishu.app_id / app_secret /
update_folder_url → ./build.py -a → 确认上传。构建时敏感键自动混淆进
secrets.yaml.example 随包分发,构建结束 example 恢复为留空模板。
客户端: 启动时 / 每小时 / 点版本号徽章时检查更新;发现新版本后下载
(4 线程分块 + SHA256 校验 + .part 防半截包)→ 备份配置 → 按
config_changes.json 迁移 → Ubuntu 趁应用存活时免密 sudo dpkg -i
(--update 默认附带 --sudoers 免密),Windows 等退出后静默安装。
飞书侧准备: 开放平台建自建应用 → 开通 drive:drive 权限并发布 →
建云盘文件夹,完整链接填入 update_folder_url。开发模式(源码运行)不支持
应用内更新,检查接口返回 packaged: false。
生成的项目结构
demo/
├── pyproject.toml # Python 依赖(uv 管理)
├── AGENTS.md # AI 编码助手协作约定
├── README.md # 项目说明(含三种启动方式详解)
├── .gitignore
├── backend/ # FastAPI 后端
│ ├── main.py # FastAPI 入口(lifespan / CORS / SPA 兜底)
│ ├── backend_build.py # PyInstaller 打包脚本
│ ├── api/ # API 路由层
│ └── managers/ # 基础设施单例
├── frontend/ # Vue 3 前端
│ ├── package.json
│ ├── package-lock.json
│ ├── vite.config.js
│ └── src/
├── electron/ # Electron 主进程
│ ├── package.json
│ ├── package-lock.json
│ ├── main.js
│ └── resources/ # icon + Linux DEB hooks
├── version/ # 版本管理(pre-commit hook)
├── configs/ # 配置文件
├── datas/ # 运行时数据(gitignore)
├── dev.py # 开发脚本(Windows/Linux)
├── build.py # 打包脚本(Windows/Linux)
└── .venv # Python 虚拟环境
xb 工具自身结构
xb/
├── cli.py # CLI 入口(Click + Rich)
├── __init__.py # 版本号
├── commands/ # 子命令实现
│ ├── init.py # 初始化(升级检查、图标、npm install、git init)
│ ├── dev.py # 开发环境管理
│ ├── build.py # 构建
│ ├── version.py # 版本管理
│ ├── doctor.py # 环境诊断
│ └── upgrade.py # 升级 xb
├── templates/ # Jinja2 项目模板
│ ├── backend/
│ ├── frontend/
│ ├── electron/
│ ├── configs/
│ ├── scripts/
│ ├── version/
│ └── root/
└── utils/
├── template_engine.py # 模板渲染引擎
├── validators.py # 包名校验
├── click_helpers.py # 中文化 Help 输出
└── version_check.py # PyPI 版本检查(24h 缓存)
环境要求
- Python: 3.12+
- Node.js: 16+
- npm: 8+
- uv: 已安装
- OS: Windows 10/11 或 Ubuntu/Debian
- Windows 终端: 使用
--terminal时自动安装 Windows 专用pywinpty
Windows 可使用 Python、Node.js、npm 和 uv 的官方安装方式或 winget 安装。
Ubuntu/Debian 可使用系统包管理器或官方安装方式。
使用 xb doctor 可一键检查所有环境依赖。
许可证
MIT
Metadata
Release files for xb-init 2.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xb_init-2.2.3.tar.gz | 4.7 MB | Without provenance | Details for xb_init-2.2.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xb_init-2.2.3-py3-none-any.whl | Python 3 | none | any | Details for xb_init-2.2.3-py3-none-any.whl |
Total release size: 4.9 MB
Release files / xb_init-2.2.3.tar.gz
| Download URL | xb_init-2.2.3.tar.gz |
|---|---|
| Size | 4.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7be3ba1d971abd3fe92f8f3067faa3fb26c3ba73d350b6162519c448638feb27
|
|
BLAKE2b-256 checksum How to use checksums |
5f692c521c45e154a1b9a5a1ae4ecba4febb27557dd292aa5429cea6db72fe46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / xb_init-2.2.3-py3-none-any.whl
| Download URL | xb_init-2.2.3-py3-none-any.whl |
|---|---|
| Size | 181.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c8af3eb0ef742028d5f873bcb7b46bdfed1c5ac9165e7567320692f870867b91
|
|
BLAKE2b-256 checksum How to use checksums |
d31f5f4da0dbab42d957c220121816766099a6395859234be423342cd9c68333
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for xb-init 2.2.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.