xb-init 2.0.5__tar.gz → 2.2.2__tar.gz

{xb_init-2.0.5 → xb_init-2.2.2}/.gitignore

@@ -1,38 +1,38 @@
-# Python
-__pycache__/
-*.pyc
-*.pyo
-*.pyd
-.Python
-*.so
-*.egg
-*.egg-info/
-dist/
-build/
-.eggs/
-
-# Virtual environments
-.venv/
-venv/
-ENV/
-env/
-
-# uv
-.uv/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-.DS_Store
-
-# Testing
-.pytest_cache/
-.coverage
-htmlcov/
-
-# Local dev
-*.log
-.env
-.env.local
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+.uv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Local dev
+*.log
+.env
+.env.local

{xb_init-2.0.5 → xb_init-2.2.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: xb-init
-Version: 2.0.5
+Version: 2.2.2
 Summary: Project management tool for UV + FastAPI + Vue3 + Electron desktop applications
-Project-URL: Homepage, https://github.com/yourusername/xb
-Project-URL: Documentation, https://github.com/yourusername/xb#readme
-Project-URL: Repository, https://github.com/yourusername/xb.git
-Project-URL: Issues, https://github.com/yourusername/xb/issues
-Author-email: XB Team <xb@example.com>
+Project-URL: Homepage, https://github.com/xuebli/xb
+Project-URL: Documentation, https://github.com/xuebli/xb#readme
+Project-URL: Repository, https://github.com/xuebli/xb.git
+Project-URL: Issues, https://github.com/xuebli/xb/issues
+Author-email: xuebli <17639393047@163.com>
 License: MIT
 Keywords: cli,electron,fastapi,project-management,vue3
 Classifier: Development Status :: 3 - Alpha
@@ -43,6 +43,7 @@ Description-Content-Type: text/markdown
 - 内置全局亮色/暗色主题切换
 - 可选 sudo 免密配置（`--sudoers`）
 - 可选内置终端（`--terminal`）
+- 可选应用内自动更新（`--update`，飞书云盘发布 + 版本检查 + 下载校验 + 自动安装）
 - 可选自定义应用图标（`--icon`）
 - 内置开发、构建、版本管理命令
 - 自动版本检查与一键升级（`xb --upgrade`）
@@ -83,6 +84,9 @@ xb init demo --terminal
 # 同时启用终端和 sudo 免密配置
 xb init demo --terminal --sudoers
 
+# 启用应用内自动更新（自动附带 --sudoers 免密，输入 sudo 密码即可）
+xb init demo --update
+
 # 带自定义图标
 xb init demo --icon ~/icons/app.png
 
@@ -110,14 +114,18 @@ python .\dev.py stop
 使用 `--terminal` 时，Windows 终端使用 PowerShell + ConPTY，支持上下箭头
 命令历史、复制粘贴、Tab 补全和 Ctrl+C；Ubuntu/Debian 使用 bash + Unix PTY。
 
-Electron 二进制镜像通过 `ELECTRON_MIRROR` 环境变量注入，不向 `.npmrc`
-写 npm 不识别的自定义键。若安装过程被网络中断，生成项目的
+Electron 二进制镜像通过 `ELECTRON_MIRROR` 环境变量注入。
+若安装过程被网络中断，生成项目的
 `electron/prepare.js` 会在 `npm start` 或 `npm run build` 前自动检查并补装
 缺失的 Electron 二进制。
 
 > **`xb init` 自动行为**：
 > - 执行 `npm install`（frontend + electron），生成 `package-lock.json`
->   - 生成的 `.npmrc` 已配好华为云镜像；electron 约 200MB 二进制也走镜像下载
+>   - 生成的项目用 [nrm](https://github.com/Pana/nrm) 管理 npm 源：`xb init`
+>     安装依赖前与 `build.py` 构建前都会自动 `nrm test` 测速所有内置源并切换
+>     到最快的（未安装 nrm 时自动全局安装）；项目不放 `.npmrc`，npm 源完全由
+>     nrm 全局管理
+>   - electron 约 200MB 二进制走华为云镜像下载
 >   - 若安装失败或超时，会打印提示但不中断项目创建，可稍后手动重试
 > - 执行 `git init` 并提交首个 commit（包含所有文件和 lock 文件）
 > - 若检测到 PyPI 有新版 xb，会询问是否先升级再创建项目
@@ -127,7 +135,7 @@ Electron 二进制镜像通过 `ELECTRON_MIRROR` 环境变量注入，不向 `.n
 
 | 命令 | 说明 |
 |------|------|
-| `xb init <name> [--sudoers] [--terminal] [--icon PATH]` | 初始化项目 |
+| `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 |
@@ -146,6 +154,39 @@ xb init demo --icon ./my-icon.png
 # ./assets/app-icon.png, ./assets/icon.png, ./resources/icon.png
 ```
 
+## 应用内自动更新（`--update`）
+
+`xb init demo --update` 会让生成的项目内置与 [leo_stm32_board_test](../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`。
+
 ## 生成的项目结构
 
 ```
@@ -162,13 +203,11 @@ demo/
 ├── frontend/               # Vue 3 前端
 │   ├── package.json
 │   ├── package-lock.json
-│   ├── .npmrc              # npm 镜像源（华为云）
 │   ├── vite.config.js
 │   └── src/
 ├── electron/               # Electron 主进程
 │   ├── package.json
 │   ├── package-lock.json
-│   ├── .npmrc              # npm + electron 二进制镜像源
 │   ├── main.js
 │   └── resources/          # icon + Linux DEB hooks
 ├── version/                # 版本管理（pre-commit hook）

{xb_init-2.0.5 → xb_init-2.2.2}/README.md

@@ -1,197 +1,236 @@
-# xb - 前后端打包构建工具
-
-**xb**（PyPI: `xb-init`）是一个基于 `uv` 又类似 `uv` 的项目管理工具，专为快速初始化 **UV + FastAPI + Vue3 + Electron** 桌面应用而生。一条命令拉起完整工程脚手架，开发、构建、版本管理一站式搞定。
-
-![首页截图](docs/screenshot.png)
-
-## 核心特性
-
-- 一键初始化完整项目结构（`xb init demo`）
-- UV + FastAPI + Vue3 + Electron 开箱即用
-- 自动安装前端和 Electron 依赖（`npm install`，内置国内镜像源）
-- 自动 `git init` 并提交首个 commit（含 lock 文件）
-- 自动生成 `AGENTS.md`（AI 编码助手协作约定）
-- 内置全局亮色/暗色主题切换
-- 可选 sudo 免密配置（`--sudoers`）
-- 可选内置终端（`--terminal`）
-- 可选自定义应用图标（`--icon`）
-- 内置开发、构建、版本管理命令
-- 自动版本检查与一键升级（`xb --upgrade`）
-- 环境诊断（`xb doctor`）
-- Linux DEB 与 Windows NSIS 安装支持
-
-## 安装
-
-```bash
-# 安装 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
-```
-
-## 快速开始
-
-```bash
-# 创建项目
-xb init demo
-
-# 带 sudo 免密配置
-xb init demo --sudoers
-
-# 带内置终端
-xb init demo --terminal
-
-# 同时启用终端和 sudo 免密配置
-xb init demo --terminal --sudoers
-
-# 带自定义图标
-xb init demo --icon ~/icons/app.png
-
-cd demo
-
-# 启动开发环境
-xb dev
-
-# 查看状态
-xb dev status
-
-# 停止
-xb dev stop
-```
-
-Windows PowerShell 也可以直接运行生成项目脚本：
-
-```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` 环境变量注入，不向 `.npmrc`
-写 npm 不识别的自定义键。若安装过程被网络中断，生成项目的
-`electron/prepare.js` 会在 `npm start` 或 `npm run build` 前自动检查并补装
-缺失的 Electron 二进制。
-
-> **`xb init` 自动行为**：
-> - 执行 `npm install`（frontend + electron），生成 `package-lock.json`
->   - 生成的 `.npmrc` 已配好华为云镜像；electron 约 200MB 二进制也走镜像下载
->   - 若安装失败或超时，会打印提示但不中断项目创建，可稍后手动重试
-> - 执行 `git init` 并提交首个 commit（包含所有文件和 lock 文件）
-> - 若检测到 PyPI 有新版 xb，会询问是否先升级再创建项目
-> - 若系统未安装 git 或未配置 `user.name/user.email`，打印警告但不阻塞
-
-## 命令一览
-
-| 命令 | 说明 |
-|------|------|
-| `xb init <name> [--sudoers] [--terminal] [--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 最新版本 |
-
-## 应用图标
-
-```bash
-# 显式指定图标
-xb init demo --icon ./my-icon.png
-
-# 不指定时自动查找以下约定路径：
-# ./app-icon.png, ./icon.png, ./<package>.png,
-# ./assets/app-icon.png, ./assets/icon.png, ./resources/icon.png
-```
-
-## 生成的项目结构
-
-```
-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
-│   ├── .npmrc              # npm 镜像源（华为云）
-│   ├── vite.config.js
-│   └── src/
-├── electron/               # Electron 主进程
-│   ├── package.json
-│   ├── package-lock.json
-│   ├── .npmrc              # npm + electron 二进制镜像源
-│   ├── 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
+# xb - 前后端打包构建工具
+
+**xb**（PyPI: `xb-init`）是一个基于 `uv` 又类似 `uv` 的项目管理工具，专为快速初始化 **UV + FastAPI + Vue3 + Electron** 桌面应用而生。一条命令拉起完整工程脚手架，开发、构建、版本管理一站式搞定。
+
+![首页截图](docs/screenshot.png)
+
+## 核心特性
+
+- 一键初始化完整项目结构（`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 安装支持
+
+## 安装
+
+```bash
+# 安装 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
+```
+
+## 快速开始
+
+```bash
+# 创建项目
+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 也可以直接运行生成项目脚本：
+
+```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`
+>   - 生成的项目用 [nrm](https://github.com/Pana/nrm) 管理 npm 源：`xb init`
+>     安装依赖前与 `build.py` 构建前都会自动 `nrm test` 测速所有内置源并切换
+>     到最快的（未安装 nrm 时自动全局安装）；项目不放 `.npmrc`，npm 源完全由
+>     nrm 全局管理
+>   - electron 约 200MB 二进制走华为云镜像下载
+>   - 若安装失败或超时，会打印提示但不中断项目创建，可稍后手动重试
+> - 执行 `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 最新版本 |
+
+## 应用图标
+
+```bash
+# 显式指定图标
+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](../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