Skip to main content

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 编码助手协作约定)
  • 内置全局亮色/暗色主题切换
  • 可选内置终端(--terminal)
  • 可选日志中心(--logs,后端日志实时推送到界面,排障不用登机器)
  • 通用设置页(yaml 加一行"值 + 行尾 # 显示名"即自动出表单,注释回填不丢失;secrets.yaml 的 key 自动渲染为密码框)
  • 可选应用内自动更新(--update,飞书云盘发布 + 版本检查 + 下载校验 + 自动安装)
  • 可选 CSV 测试引擎(--csv-test,产测专用:CSV 定义测试项、人工确认、PASS 判定、HTML 报告归档与历史查看)
  • 可选飞书登录(--feishu-auth,OAuth 扫码登录 + 单会话制 + 可开关的强制登录墙,多人协作/服务器部署用)
  • 可选飞书群通知(--feishu-notify,webhook 只发文字 / 自建应用可发文件附件,产测归档自动推送,业务可直接调用)
  • 可选飞书多维表格(--feishu-bitable,数据写入多维表格:自动建字段/附件上传/wiki 链接解析,产测勾选推送,业务可直接调用)
  • 特权操作免密提权标配(Linux polkit,管理员组无感、无密码落盘;helper 白名单执行器)
  • 可选自定义应用图标(--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

# 带内置终端
xb init demo --terminal

# 带日志中心
xb init demo --logs

# 启用应用内自动更新(Ubuntu 更新安装走 polkit 免密提权,管理员组无感)
xb init demo --update

# 启用 CSV 测试引擎(产测:测试项 CSV + 人工确认 + HTML 报告)
xb init demo --csv-test

# 带自定义图标
xb init demo --icon ~/icons/app.png

cd demo
# 启动开发环境(自动完成:依赖同步、Git hooks 安装、polkit 特权入口部署)
xb dev

# 查看状态
xb dev status

# 停止
xb dev stop

交互式配置表单

xb init 会在创建前显示一个单屏配置表单,回车即按当前值创建:

  xb init demo — 应用配置
  ↑↓ 移动 · 空格 勾选/取消 · 选中后直接输入 · 回车 开始创建
  ────────────────────────────────────────────────────────
❯ [ ] 应用显示名 : Demo
  [ ] 端口(后端/前端) : 8000 / 8001
  [ ] 内置终端  ✘  (Web 终端组件)
  [ ] 应用内更新  ✘  (Ubuntu 更新安装走 polkit 免密提权)
  [ ] 日志中心  ✘  (实时查看后端日志,排障刚需)
  [ ] CSV 测试引擎  ✘  (产测专用:测试项 CSV + HTML 报告)
  [ ] 应用图标 : 使用默认
  [ ] 跳过依赖安装  ✘  (离线环境可跳过)
  • --name/--port/--terminal/--update/--logs/--csv-test/--feishu-auth/--feishu-notify/--feishu-bitable/--icon/--skip-install 传了的参数 直接预填进表单并勾上,回车即确认,老用法不受影响
  • 文本行(显示名/端口/图标)勾选时若仍是默认值则自动清空,直接输入即可
  • stdin 非终端时(脚本/CI 管道调用)自动跳过表单,沿用 CLI 参数

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。 后端、Vite 与终端 WebSocket 默认仅允许本机访问并校验页面 Origin; 在补齐身份认证前不要改为 0.0.0.0 暴露到局域网。

Electron 二进制镜像通过 ELECTRON_MIRROR 环境变量注入。 若安装过程被网络中断,生成项目的 electron/prepare.js 会在 npm start 或 npm run build 前自动检查并补装 缺失的 Electron 二进制。

xb init 自动行为:

  • 执行 npm install(frontend + electron),生成 package-lock.json 离线环境可加 --skip-install 跳过,稍后手动安装
    • 生成的项目用 nrm 管理 npm 源:xb init 安装依赖前与 build.py 构建前都会自动 nrm test 测速所有内置源并切换 到最快的(未安装 nrm 时自动全局安装);项目不放 .npmrc,npm 源完全由 nrm 全局管理
    • electron 约 200MB 二进制走华为云镜像下载
    • uv 源同样自动优化:首次依赖同步(dev.py)与后端构建(build.py -b/-a) 前并行实测各镜像(要求最终 HTTP 200),自动切换到最快可用源(约 1-6 秒,纯标准库实现,无需额外工具)
    • 若安装失败或超时,会打印提示但不中断项目创建,可稍后手动重试
  • 执行 git init 并提交首个 commit(包含所有文件和 lock 文件)
  • 若检测到 PyPI 有新版 xb,会询问是否先升级再创建项目
  • 若系统未安装 git 或未配置 user.name/user.email,打印警告但不阻塞

命令一览

命令 说明
xb init <name> [--name 显示名] [--port 9000] [--terminal] [--update] [--logs] [--csv-test] [--feishu-auth] [--feishu-notify] [--feishu-bitable] [--icon PATH] [--skip-install] 初始化项目
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 [--fix] 检查开发环境;--fix 自动安装 nrm/uv、交互式配置 git 身份
xb --upgrade / 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)

详细原理与 AI 开发者注意事项见模板内 xb/templates/root/docs/自动更新说明.md (生成的项目会自带 docs/自动更新说明.md 与配图); Ubuntu polkit 免密提权的授权机制与调试方法见 xb/templates/root/docs/polkit免密提权说明.md。

xb init demo --update 会让生成的项目内置自动更新能力, 以飞书云盘的一个文件夹作为发布"货架":

生成内容:

位置 职责
backend/api/update/ 更新接口(检查 / 信息 / 下载 / 进度 / 安装)
backend/services/updater.py 版本比较、信息拉取、下载校验、配置备份迁移、安装
backend/services/feishu_client.py 飞书接口封装(文件夹列举、并发下载)
backend/managers/secret_obfuscator.py 敏感值混淆(obf1:,防围观级别)
backend/managers/privileged_manager.py polkit 特权客户端(pkexec 调 root 白名单执行器)
backend/app_version.py 后端版本号(version_manager 提交时自动同步)
frontend/src/components/version/UpdatePanel.vue 更新弹窗(版本信息 / 更新说明 / 迁移明细 / 进度条)
frontend/src/components/version/CommitHistoryPanel.vue 版本弹窗里的提交历史
frontend/src/components/GitVersionBadge.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 走 polkit 免密安装(授权规则由 DEB postinst 预部署,管理员组无感、无密码落盘),Windows 等退出后静默安装。

飞书侧准备: 开放平台建自建应用 → 开通 drive:drive 权限并发布 → 建云盘文件夹,完整链接填入 update_folder_url。开发模式(源码运行)不支持 应用内更新,检查接口返回 packaged: false。

深入文档

生成的项目自带 docs/ 说明文档,模板源文件在 xb/templates/root/docs/:

文档 内容
自动更新说明.md 应用内自动更新:发版流程、配置迁移清单、AI 开发者纪律
polkit免密提权说明.md Linux polkit 免密提权:安全模型、三件套部署、新增特权操作、排障
打包与运行路径说明.md 构建产物、DEB/NSIS 安装布局、运行时数据目录、三种运行形态判定
服务器部署说明.md 无头后端服务器部署:Ubuntu systemd / Windows 计划任务、日常管理、升级卸载(.j2 按项目渲染包名/端口)
密钥混淆说明.md 敏感值落盘混淆:SENSITIVE_TAGS 判断规则、obf1 格式、触发时机、防围观边界
csv测试引擎说明.md 产测 CSV 引擎:测试项格式、指令键注册、HTML 报告、纪律(--csv-test 项目)
飞书登录说明.md 飞书登录前提条件:开放平台建应用/网页应用/重定向白名单/发布、企业定制域名、单会话制、排障(--feishu-auth 项目,.j2 按项目渲染端口)
飞书通知说明.md 群通知双模式(webhook/自建应用+chat_id)、配置步骤、排障(--feishu-notify 项目)
飞书多维表格说明.md 多维表格上传:配置、完整写入链路(三重门/结构准备/附件并行)、字段映射、排障(--feishu-bitable 项目)
版本管理说明.md 版本号 single source of truth、三模态 bump 弹窗、手动 bump、hook 纪律

生成的项目结构

demo/
├── pyproject.toml          # Python 依赖(uv 管理)
├── AGENTS.md               # AI 编码助手协作约定
├── README.md               # 项目说明(含三种启动方式详解)
├── LICENSE                 # MIT 许可证
├── .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.png/icon.ico/icons/ 图标集 + systemd 单元模板 + Linux DEB hooks
├── version/                # 版本管理(pre-commit hook)
├── configs/                # 配置文件
├── datas/                  # 运行时数据(gitignore)
├── docs/                   # 说明文档(打包路径/自动更新/polkit 提权)
├── 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: 20.19+(推荐 22 LTS;模板前端使用 Vite 8,Node 18 及以下会构建报错)
  • npm: 10+
  • 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 3.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xb-init 3.2.0
File Size Uploaded Provenance Actions
xb_init-3.2.0.tar.gz 8.2 MB Without provenance Details for xb_init-3.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xb-init 3.2.0
File Interpreter ABI Platform Actions
xb_init-3.2.0-py3-none-any.whl Python 3 none any Details for xb_init-3.2.0-py3-none-any.whl

Total release size: 11.9 MB

Release files / xb_init-3.2.0.tar.gz

Download URL xb_init-3.2.0.tar.gz
Size 8.2 MB
Tags Source
SHA-256 checksum
How to use checksums
67bc9e00e7fad3dea5522963772e6760989cd9c27fe7f302dcd5c045c60dde69
BLAKE2b-256 checksum
How to use checksums
76facb2e718b7c207ab1f0c2c777f85fa9d2c80cefd3adabc3b2262bd7349b23
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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-3.2.0-py3-none-any.whl

Download URL xb_init-3.2.0-py3-none-any.whl
Size 3.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
13309d7b757b446973b95cfeaa03d30d418bf572dc5cea8c244e2068f74e045a
BLAKE2b-256 checksum
How to use checksums
d97a3bf479104dbcbc465248927537de42abd7ae47fc765935adc1690fb8f820
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","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 3.2.0

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page