flu-cli 0.0.5 → 2.0.0

package/CLI.md

@@ -0,0 +1,349 @@
+# Flu-CLI v2 命令参考
+
+> Flutter MVVM 脚手架工具 - 快速生成项目和代码
+
+## 快速开始
+
+```bash
+# 创建新项目
+flu-cli new my_app
+
+# 添加页面
+flu-cli add page home
+
+# 查看帮助
+flu-cli --help
+```
+
+## 命令列表
+
+### 1. `new` - 创建项目
+
+创建一个新的 Flutter 项目，支持多种模板和状态管理器。
+
+**用法:**
+```bash
+flu-cli new [项目名称] [选项]
+flu-cli n [项目名称]  # 简写
+```
+
+**选项:**
+- `-t, --template <type>` - 模板类型: `lite`, `modular`, `clean`
+- `-s, --state <type>` - 状态管理器: `default`, `provider`, `getx`, `riverpod`
+- `-d, --dir <path>` - 项目存放目录（默认：当前目录）
+- `--no-cache` - 不使用缓存，强制从 Git 拉取
+- `--remote` - 使用远程 Gitee 模板（默认使用本地模板）
+
+**示例:**
+```bash
+# 交互式创建（推荐）
+flu-cli new
+
+# 指定项目名和模板
+flu-cli new my_app -t lite
+
+# 指定状态管理器
+flu-cli new my_app -s getx
+
+# 完整配置
+flu-cli new my_app -t modular -s provider -d ~/projects
+```
+
+---
+
+### 2. `add` - 添加组件
+
+在当前项目中添加各种代码组件。
+
+**用法:**
+```bash
+flu-cli add <类型> <名称> [选项]
+flu-cli a <类型> <名称>  # 简写
+```
+
+**支持的类型及别名:**
+
+| 类型 | 别名 | 说明 |
+|------|------|------|
+| `page` | `p` | 页面组件 |
+| `widget` | `w` | 通用组件 |
+| `component` | `c` | 业务组件 |
+| `viewmodel` | `v` | ViewModel |
+| `service` | `s` | 服务层 |
+| `model` | `m` | 数据模型 |
+| `module` | `mod` | 完整功能模块 |
+
+**选项:**
+- `-f, --feature <name>` - 所属功能模块（仅 modular/clean 模式）
+- `--stateful` - 创建 StatefulWidget
+- `--stateless` - 强制创建 StatelessWidget
+- `--list-page` - 创建列表页 (BaseListPage)
+- `--no-vm` - 不生成 ViewModel（仅 page 类型）
+- `--type <type>` - Service 类型: `api`, `storage`, `auth`（仅 service 类型）
+- `--json <file>` - 从 JSON 文件生成（仅 model 类型）
+- `--list` - 查看支持的类型列表
+
+**示例:**
+```bash
+# 添加页面（自动生成 ViewModel）
+flu-cli add page home
+flu-cli add p home  # 简写
+
+# 添加列表页
+flu-cli add page user_list --list-page
+
+# 添加无状态页面
+flu-cli add page about --stateless --no-vm
+
+# 添加组件
+flu-cli add widget custom_button
+flu-cli add w custom_button  # 简写
+
+# 添加 Service
+flu-cli add service api --type api
+flu-cli add s auth --type auth  # 简写 + 指定类型
+
+# 添加 Model
+flu-cli add model user
+flu-cli add m user  # 简写
+
+# 在功能模块下添加（modular/clean 模式）
+flu-cli add page product -f shop
+```
+
+---
+
+### 3. `templates` - 模板管理
+
+查看可用模板列表或指定模板的详细信息。
+
+**用法:**
+```bash
+flu-cli templates [模板名称]
+flu-cli t [模板名称]  # 简写
+```
+
+**示例:**
+```bash
+# 查看所有模板
+flu-cli templates
+
+# 查看指定模板详情
+flu-cli templates lite
+flu-cli t modular  # 简写
+```
+
+---
+
+### 4. `generate-sm` - 生成状态管理代码
+
+为现有项目生成状态管理适配与配置。
+
+**用法:**
+```bash
+flu-cli generate-sm <类型>
+flu-cli g <类型>  # 简写
+```
+
+**选项:**
+- `-d, --dir <path>` - 项目目录（默认：当前目录）
+- `-m, --module <name>` - 模块名称（modular/clean 支持分模块适配器）
+
+**示例:**
+```bash
+# 生成 Provider 状态管理
+flu-cli generate-sm provider
+
+# 生成 GetX 状态管理
+flu-cli g getx  # 简写
+```
+
+---
+
+### 5. `sync-snippets` - 同步代码片段
+
+将最新的标准 VS Code 代码片段同步到当前项目。
+
+**用法:**
+```bash
+flu-cli sync-snippets
+flu-cli sync  # 简写
+```
+
+**说明:**
+- 该命令会覆盖项目的 `.vscode/dart.code-snippets` 文件。
+- 新项目创建时会自动同步，无需手动执行。
+
+**示例:**
+```bash
+# 同步标准代码片段
+flu-cli sync-snippets
+```
+
+---
+
+### 6. `update-templates` - 更新模板缓存
+
+更新本地模板缓存到最新版本。
+
+**用法:**
+```bash
+flu-cli update-templates [模板名称]
+flu-cli u [模板名称]  # 简写
+```
+
+**选项:**
+- `--force` - 强制刷新并清理未跟踪文件
+
+**示例:**
+```bash
+# 更新所有模板
+flu-cli update-templates
+
+# 更新指定模板
+flu-cli u lite  # 简写
+
+# 强制刷新
+flu-cli update-templates --force
+```
+
+---
+
+### 7. `cache` - 缓存管理
+
+管理本地模板缓存。
+
+**用法:**
+```bash
+flu-cli cache <action>
+flu-cli c <action>  # 简写
+```
+
+**支持的操作:**
+- `clean` - 清理缓存
+
+**示例:**
+```bash
+# 清理缓存
+flu-cli cache clean
+flu-cli c clean  # 简写
+```
+
+---
+
+### 8. `completion` - 自动补全
+
+生成 Shell 自动补全脚本（支持 Bash/Zsh）。
+
+**用法:**
+```bash
+flu-cli completion
+flu-cli comp  # 简写
+```
+
+**安装方法:**
+```bash
+# Zsh
+flu-cli completion >> ~/.zshrc
+source ~/.zshrc
+
+# Bash
+flu-cli completion >> ~/.bashrc
+source ~/.bashrc
+```
+
+---
+
+## 常见工作流
+
+### 创建新项目
+```bash
+flu-cli new my_app
+cd my_app
+flutter pub get
+flu-cli add page home
+flu-cli add page user_list --list-page
+```
+
+### 在现有项目中使用
+```bash
+cd existing_project
+
+# 同步代码片段
+flu-cli sync-snippets
+
+# 添加组件
+flu-cli add page settings
+flu-cli add service api --type api
+```
+
+### Modular 架构项目
+```bash
+flu-cli new my_app -t modular
+cd my_app
+
+# 在 shop 模块下添加页面
+flu-cli add page product -f shop
+flu-cli add page cart -f shop
+
+# 在 user 模块下添加页面
+flu-cli add page profile -f user
+```
+
+---
+
+## 全局选项
+
+所有命令都支持以下选项：
+- `-V, --version` - 查看版本号
+- `-h, --help` - 查看帮助信息
+
+**示例:**
+```bash
+flu-cli --version
+flu-cli add --help
+```
+
+---
+
+## 配置文件
+
+Flu-CLI 会在以下位置存储配置：
+- **缓存目录**: `~/.flu-cli/cache/`
+- **配置文件**: `~/.flu-cli/config.json`
+
+---
+
+## 故障排除
+
+### 命令卡住
+如果命令执行过程中卡住，可以：
+1. 按 `Ctrl+C` 中止
+2. 运行 `flu-cli cache clean` 清理缓存
+3. 重新执行命令
+
+### 模板拉取失败
+```bash
+# 清理缓存后重试
+flu-cli cache clean
+flu-cli new my_app
+
+# 或使用本地模板（开发环境）
+flu-cli new my_app --no-cache
+```
+
+### 代码片段不生效
+```bash
+# 重新同步代码片段
+flu-cli sync-snippets
+
+# 重启 VS Code 后生效
+```
+
+---
+
+## 更多帮助
+
+- 查看具体命令帮助：`flu-cli <command> --help`
+- 项目文档：[flu-cli 文档站](https://your-docs-url)
+- 问题反馈：[GitHub Issues](https://github.com/your-repo/issues)

package/README.md

@@ -1,303 +1,86 @@
-# Flu CLI 工具
+# flu-cli v2.0
 
-> **flu-cli** 是一个强大的 Flutter 项目脚手架工具，可以帮助您快速创建和配置项目。
+> 🚀 **活跃开发中** - Flutter MVVM 脚手架工具
 
-[![npm version](https://img.shields.io/npm/v/flu-cli.svg)](https://www.npmjs.com/package/flu-cli)
-[![license](https://img.shields.io/npm/l/flu-cli.svg)](https://gitee.com/tengteng_fan/flutter-cli/blob/main/LICENSE)
-[![downloads](https://img.shields.io/npm/dm/flu-cli.svg)](https://www.npmjs.com/package/flu-cli)
+## ✨ 特性
 
-## 📋 目录
-
--   [🚀 快速开始](#-快速开始)
--   [📦 安装](#-安装)
--   [🛠️ 使用方法](#️-使用方法)
-    -   [交互式向导](#交互式向导)
-    -   [项目模版对比](#项目模版对比)
-    -   [命令行创建](#命令行创建)
--   [📁 项目结构](#-项目结构)
--   [🏃 运行与调试](#-运行与调试)
--   [📚 进阶指南](#-进阶指南)
--   [🔧 兼容性说明](#-兼容性说明)
-
-## 🚀 快速开始
-
-```bash
-# 全局安装
-npm install -g flu-cli
-
-# 创建项目
-flu-cli
-
-# 或使用 npx（无需安装）
-npx flu-cli
-```
+- 🎯 **交互式创建** - `flu new` 命令提供友好的交互式体验
+- 🔧 **代码生成** - `flu add` 快速生成页面、组件、服务等（支持别名）
+- 📦 **多种模板** - lite、modular、clean 三种架构模板
+- 🎮 **状态管理** - 支持 default、provider、getx、riverpod
+- 📝 **基于 Snippets** - 可自定义 VSCode 代码片段
+- 🎨 **列表页支持** - `--list-page` 自动生成 Page/ViewModel/Model
+- 🚀 **智能补全** - Shell 自动补全（Zsh/Bash）
+- 🌏 **中文友好** - 全中文提示和文档
 
 ## 📦 安装
 
-您可以通过以下方式安装 flu-cli：
-
-| 安装方式       | NPM                      | PNPM                  | Yarn                      |
-| -------------- | ------------------------ | --------------------- | ------------------------- |
-| **全局安装**   | `npm install -g flu-cli` | `pnpm add -g flu-cli` | `yarn global add flu-cli` |
-| **项目内安装** | `npm install flu-cli`    | `pnpm add flu-cli`    | `yarn add flu-cli`        |
-
-> 💡 **推荐使用全局安装**，这样可以在任何地方使用 `flu-cli` 命令。
-
-## 🛠️ 使用方法
-
-### 交互式向导
-
-flu-cli 附带一个命令行设置向导，它将帮助您构建一个基本项目。安装后，您可以通过运行以下命令启动向导：
-
-```bash
-# 如果全局安装
-flu-cli
-
-# 或者使用 npx
-npx flu-cli
-```
-
-运行向导后，根据提示输入项目信息，如项目名称、包名、项目类型、模板类型、状态管理方案等。向导会自动生成项目结构并配置相关文件。
-
-<details>
-<summary>📋 向导示例（点击展开）</summary>
-
-```bash
-欢迎使用 火之夜工作室 Flutter 项目创建工具
-
-? 请选择项目类型: (Use arrow keys)
-❯ 应用 (app)
-  模块 (module)
-  原生插件 (plugin)
-  插件 (package)
-
-? 请选择项目模版: (Use arrow keys)
-  only (main.dart)
-  min (项目结构、路由管理、主题管理、状态管理、工具集)
-  normal (项目结构、路由管理、主题管理、状态管理、工具集、UI 组件库)
-❯ pro (项目结构、路由管理、主题管理、状态管理、工具集、UI 组件库、网络请求、数据缓存、示例模块)
-
-? 请选择状态管理: (Use arrow keys)
-❯ state (State)
-  get (GetX)
-
-? 请输入新项目名称（小写字母、数字和下划线）: (hzy_example_project)
-? 请输入 Flutter SDK 路径（留空使用系统默认）:
-? 请输入包名: (com.example.hzy_example_project)
-? 请输入项目存放路径: (默认: 当前目录)
-
-⚠️  警告: 目标目录 hzy_example_project 已存在!
-? 是否覆盖？ (y/N)
-
-? 请选择要打开项目的 IDE: (Use arrow keys)
-❯ Visual Studio Code
-  Android Studio
-  打开文件夹
-  不打开
-```
-
-</details>
-
-### 项目模版对比
-
-| 功能特性                 | 🔹 only | 🔸 min | 🔶 normal | 🔥 pro |
-| :----------------------- | :-----: | :----: | :-------: | :----: |
-| **基础入口 (main.dart)** |   ✅    |   ✅   |    ✅     |   ✅   |
-| **标准项目结构**         |   ❌    |   ✅   |    ✅     |   ✅   |
-| **路由管理系统**         |   ❌    |   ✅   |    ✅     |   ✅   |
-| **主题管理系统**         |   ❌    |   ✅   |    ✅     |   ✅   |
-| **状态管理方案**         |   ❌    |   ✅   |    ✅     |   ✅   |
-| **开发工具集**           |   ❌    |   ✅   |    ✅     |   ✅   |
-| **UI 组件库**            |   ❌    |   ❌   |    ✅     |   ✅   |
-| **网络请求框架**         |   ❌    |   ❌   |    ❌     |   ✅   |
-| **数据持久化**           |   ❌    |   ❌   |    ❌     |   ✅   |
-
-#### 模版说明
-
--   🔹 **only**：仅保留最小运行单元（适合验证核心功能）
--   🔸 **min**：三大基石（路由/主题/状态管理）
--   🔶 **normal**：增加 UI 组件库（提升开发效率）
--   🔥 **pro**：完整解决方案（含网络层+数据持久化）
-
-> 📖 想了解更多项目模版区别，请查看 [项目模版详细说明](http://huozhiye.cn/flu-cli/guide/project-template.html)。
-
-### 命令行创建
-
-可以直接通过命令行参数指定所有配置，无需交互式输入：
-
-#### 基本语法
-
 ```bash
-flu-cli create [options]
-```
-
-#### 使用示例
-
-##### 🔥 Pro 模版（推荐）
-
-```bash
-flu-cli create -t app -m pro -s GetX -n my_flutter_app -p com.example.myapp -d ~/projects -i vscode
-```
-
-##### 🔶 Normal 模版
-
-```bash
-flu-cli create -t module -m normal -s state -n my_flutter_module -p com.example.mymodule -d ~/projects -i android_studio
-```
-
-##### 🔸 Min 模版
-
-```bash
-flu-cli create -t app -m min -n quick_start -p com.example.quick -d ~/projects
-```
-
-##### 🔹 Only 模版
-
-```bash
-flu-cli create -t app -m only -n quick_start -p com.example.quick -d ~/projects
+npm install -g flu-cli
 ```
 
-##### 默认配置（使用向导）
+## 🚀 快速开始
 
 ```bash
-flu-cli create
-```
+# 创建新项目
+flu-cli new my_app
+# 或使用别名
+flu n my_app
 
-#### 参数说明
+# 指定模板和状态管理
+flu n my_app -t modular -s getx
 
-| 参数                  | 说明             | 可选值                                              | 必选 | 示例                   |
-| :-------------------- | :--------------- | :-------------------------------------------------- | :--- | :--------------------- |
-| `-t, --project-type`  | 项目类型         | `app`, `module`, `package`, `plugin`                | ✅   | `-t app`               |
-| `-m, --template-type` | 模板类型         | `only`, `min`, `normal`, `pro`                      | ✅   | `-m pro`               |
-| `-s, --state-manager` | 状态管理方案     | `state`, `GetX`, `Riverpod`                         | ❌   | `-s GetX`              |
-| `-n, --project-name`  | 项目名称         | 小写字母、数字和下划线组合                          | ✅   | `-n my_app`            |
-| `-p, --package-name`  | 包名             | 类似 Java 包名格式                                  | ✅   | `-p com.example.myapp` |
-| `-d, --parent-dir`    | 存放目录         | 绝对路径或相对路径                                  | ❌   | `-d ~/projects`        |
-| `-i, --ide`           | IDE 选择         | `vscode`, `android_studio`, `open_folder`, `manual` | ❌   | `-i vscode`            |
-| `-f, --flutter-sdk`   | Flutter SDK 路径 | 默认为系统环境变量中的 flutter                      | ❌   | `-f /path/to/flutter`  |
-| `-h, --help`          | 显示帮助信息     | -                                                   | ❌   | `--help`               |
+# 添加页面（自动生成 ViewModel）
+cd my_app
+flu add page home
+# 或使用别名
+flu a p home
 
-> 📚 有关更多命令行用法的文档，请参阅 [CLI 参考文档](http://huozhiye.cn/flu-cli/eg/cli-des.html)。
+# 添加列表页（自动生成 Page + ViewModel + Model）
+flu a p user_list --list-page
 
-## 📁 项目结构
+# 添加服务
+flu a s api --type api
 
-以下是基于 **GetX** 的完整商业项目结构，清晰的项目结构有助于团队协作和代码维护。
+# 同步代码片段
+flu sync-snippets
 
+# 生成自动补全脚本
+flu-cli completion >> ~/.zshrc && source ~/.zshrc
 ```
-📦 your_project_name/
-├── 📁 .vscode/                    # VS Code 配置文件
-│   ├── 📄 extensions.json         # 插件推荐
-│   ├── 📄 launch.json             # 调试配置
-│   ├── 📄 settings.json           # 编辑器设置
-│   └── 📄 dart.code-snippets      # 代码片段
-├── 📁 assets/                      # 静态资源文件
-│   ├── 📁 fonts/                  # 字体文件
-│   ├── 📁 images/                 # 图片资源
-│   └── 📁 json/                   # 本地数据
-├── 📁 lib/                        # 项目核心代码
-│   ├── 📁 common/                 # 公共组件和工具
-│   ├── 📁 config/                 # 应用配置
-│   ├── 📁 eg_module/              # 示例模块
-│   ├── 📁 init/                   # 初始化逻辑
-│   ├── 📄 main.dart               # 应用入口文件
-│   ├── 📁 models/                 # 数据模型
-│   ├── 📁 network/                # 网络请求
-│   ├── 📁 pages/                  # 页面文件
-│   ├── 📁 tools/                  # 工具类
-│   ├── 📁 vm/                     # 视图模型
-│   └── 📁 widgets/                # UI 组件
-├── 📄 pubspec.yaml                # 项目配置文件
-├── 📄 analysis_options.yaml       # 代码分析配置
-└── 📄 README.md                   # 项目说明文档
-```
-
-### 📋 目录说明
-
-| 目录/文件         | 说明         | 用途                               |
-| ----------------- | ------------ | ---------------------------------- |
-| 📁 `.vscode/`     | VS Code 配置 | 包含编辑器配置、调试设置和代码片段 |
-| 📁 `assets/`      | 静态资源     | 存放图片、字体、本地数据等资源文件 |
-| 📁 `lib/common/`  | 公共模块     | 公共组件、工具类、常量定义         |
-| 📁 `lib/config/`  | 应用配置     | 环境配置、主题配置、路由配置       |
-| 📁 `lib/network/` | 网络层       | HTTP 请求、API 接口、数据处理      |
-| 📁 `lib/pages/`   | 页面         | 应用的各个页面和子页面             |
-| 📁 `lib/widgets/` | UI 组件      | 可复用的自定义 Widget 组件         |
-| 📁 `lib/models/`  | 数据模型     | 实体类、数据传输对象               |
-| 📁 `lib/vm/`      | 视图模型     | 状态管理、业务逻辑处理             |
-
-## 🏃 运行与调试
-
-### 基本运行步骤
-
-```bash
-# 1. 进入项目目录
-cd /your_project_path/your_project_name
-
-# 2. 获取依赖包
-flutter pub get
-
-# 3. 运行项目（开发模式）
-flutter run
-
-# 4. 构建发布版本
-flutter build apk  # Android
-flutter build ios  # iOS
-```
-
-### 🛠️ 开发工具推荐
-
-| 工具                     | 用途           | 推荐指数   |
-| ------------------------ | -------------- | ---------- |
-| 🔧 **VS Code**           | 轻量级编辑器   | ⭐⭐⭐⭐⭐ |
-| 🔧 **Android Studio**    | 功能完整的 IDE | ⭐⭐⭐⭐   |
-| 🔧 **Flutter Inspector** | UI 调试工具    | ⭐⭐⭐⭐⭐ |
-| 🔧 **Dart DevTools**     | 性能分析工具   | ⭐⭐⭐⭐   |
-
-## 📚 进阶指南
-
-🎉 恭喜您完成了 `flu-cli` 的基础配置！
-
-### 🚀 推荐后续操作
-
--   📖 **深入学习**：查看 [高级特性文档](http://huozhiye.cn/flu-cli/tutorial/base-normal-ui.html)
--   🤝 **项目模版**：访问 [仓库](https://gitee.com/tengteng_fan/hzy_basic_project)
--   📚 **官方文档**：[flu-cli 完整文档](http://huozhiye.cn/flu-cli/)
--   💬 **社区支持**：加入开发者交流群
-
-### 📖 相关资源
-
--   [Flutter 官方文档](https://flutter.dev/docs)
--   [GetX 状态管理](https://github.com/jonataslaw/getx)
--   [Dart 语言指南](https://dart.dev/guides)
-
----
 
-## 🔧 兼容性说明
+## 📚 命令别名
 
-### 系统要求
+### add 类型别名
+- `p` = page
+- `w` = widget  
+- `c` = component
+- `v` = viewmodel
+- `s` = service
+- `m` = model
+- `mod` = module
 
-| 环境            | 最低版本      | 推荐版本      | 状态    |
-| --------------- | ------------- | ------------- | ------- |
-| 🐦 **Flutter**  | 3.0.0+        | 3.16.0+       | ✅ 支持 |
-| 🟢 **Node.js**  | 14.0.0+       | 18.0.0+       | ✅ 支持 |
-| 🖥️ **操作系统** | -             | -             | -       |
-| └─ Windows      | 10+           | 11            | ✅ 支持 |
-| └─ macOS        | 10.14+        | 13.0+         | ✅ 支持 |
-| └─ Linux        | Ubuntu 18.04+ | Ubuntu 22.04+ | ✅ 支持 |
+### 顶级命令别名
+- `n` = new
+- `a` = add
+- `t` = templates
+- `g` = generate-sm
+- `u` = update-templates
+- `c` = cache
+- `sync` = sync-snippets
+- `comp` = completion
 
-### 📱 目标平台
+## 📚 文档
 
--   ✅ **Android** 5.0+ (API 21+)
--   ✅ **iOS** 11.0+
--   ✅ **Web** (Chrome, Safari, Firefox)
--   ✅ **Desktop** (Windows, macOS, Linux)
+- [CLI 命令参考](./CLI.md) - 详细命令说明
+- [完整文档](http://huozhiye.cn/flu-cli/) - 主文档站
 
----
+## 🔗 相关链接
 
-<div align="center">
+- [模板对比](http://huozhiye.cn/flu-cli/guide/templates/template-comparison)
+- [最佳实践](http://huozhiye.cn/flu-cli/best-practices/custom-templates)
+- [从 V1 迁移](http://huozhiye.cn/flu-cli/examples/migration)
 
-**🎉 祝您使用 `flu-cli` 开发愉快！**
-[![Gitee Stars](https://gitee.com/tengteng_fan/flutter-cli/badge/star.svg?theme=dark)](https://gitee.com/tengteng_fan/flutter-cli)
-[![Gitee Forks](https://gitee.com/tengteng_fan/flutter-cli/badge/fork.svg?theme=dark)](https://gitee.com/tengteng_fan/flutter-cli)
+## 📄 许可
 
-</div>
+MIT License - Copyright © 2025 火之夜工作室