flu-cli 2.0.0 → 2.0.2

package/CLI.md

@@ -15,26 +15,42 @@ flu-cli add page home
 flu-cli --help
 ```
 
+## 新增特性（v2）
+
+-   自定义模板管理：支持从本地目录或 Git 仓库添加模板，并在交互式创建时与内置模板一起选择。
+-   项目生成配置：支持在项目根使用 `.flu-cli.json` 配置生成器默认行为（路径、页面类型、是否绑定 ViewModel 等）。
+-   生成联动：CLI 与 VSCode 扩展均会读取 `.flu-cli.json`，保持生成路径与风格一致。
+-   Riverpod 原生支持：可选择 Riverpod 状态管理并生成原生风格的 VM/页面（如果模板包含入口片段会自动包裹 `ProviderScope`）。
+
 ## 命令列表
 
 ### 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 模板（默认使用本地模板）
+
+-   `-t, --template <type>` - 模板类型: `lite`, `modular`, `clean`
+-   `-s, --state <type>` - 状态管理器: `default`, `provider`, `getx`, `riverpod`
+-   `-d, --dir <path>` - 项目存放目录（默认：当前目录）
+-   `--no-cache` - 不使用缓存，强制从 Git 拉取
+-   `--remote` - 使用远程 Gitee 模板（默认使用本地模板）
+
+**说明:**
+
+-   交互式创建时会展示“内置模板 + 你通过 `template add` 保存的自定义模板”，可直接选择。
+-   模板复制后会执行占位符替换（如 `{{projectName}}`、`{{package_name}}`）并校正 `pubspec.yaml` 的 `name`。
+-   已存在 `.flu-cli.json` 的项目中再次生成文件时，会遵循其中的路径与风格设置。
 
 **示例:**
+
 ```bash
 # 交互式创建（推荐）
 flu-cli new
@@ -56,6 +72,7 @@ flu-cli new my_app -t modular -s provider -d ~/projects
 在当前项目中添加各种代码组件。
 
 **用法:**
+
 ```bash
 flu-cli add <类型> <名称> [选项]
 flu-cli a <类型> <名称>  # 简写
@@ -63,27 +80,34 @@ flu-cli a <类型> <名称>  # 简写
 
 **支持的类型及别名:**
 
-| 类型 | 别名 | 说明 |
-|------|------|------|
-| `page` | `p` | 页面组件 |
-| `widget` | `w` | 通用组件 |
-| `component` | `c` | 业务组件 |
-| `viewmodel` | `v` | ViewModel |
-| `service` | `s` | 服务层 |
-| `model` | `m` | 数据模型 |
-| `module` | `mod` | 完整功能模块 |
+| 类型        | 别名  | 说明         |
+| ----------- | ----- | ------------ |
+| `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` - 查看支持的类型列表
+
+-   `-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` - 查看支持的类型列表
+
+**说明:**
+
+-   若项目根存在 `.flu-cli.json`，`add` 会遵循其中的路径与默认类型（如 `generators.page.path`、`defaultType`、`withViewModel`）。
+-   在 `modular/clean` 模板下可用 `-f <feature>` 指定模块以生成到模块目录结构（如 `lib/features/user/...`）。
 
 **示例:**
+
 ```bash
 # 添加页面（自动生成 ViewModel）
 flu-cli add page home
@@ -111,6 +135,25 @@ flu-cli add m user  # 简写
 flu-cli add page product -f shop
 ```
 
+### 2.5 `service` - 服务层
+
+生成 API、存储等服务。
+
+**选项:**
+
+-   `-f, --feature <name>` - 指定功能模块
+-   `--type <type>` - 服务类型: api, storage, auth (默认: api) [**已废弃**: 默认生成基础 Service 结构]
+
+**示例:**
+
+```bash
+# 生成 User 服务
+flu-cli add service user
+
+# 在 auth 模块中生成 AuthService
+flu-cli add service auth --feature auth
+```
+
 ---
 
 ### 3. `templates` - 模板管理
@@ -118,12 +161,14 @@ flu-cli add page product -f shop
 查看可用模板列表或指定模板的详细信息。
 
 **用法:**
+
 ```bash
 flu-cli templates [模板名称]
 flu-cli t [模板名称]  # 简写
 ```
 
 **示例:**
+
 ```bash
 # 查看所有模板
 flu-cli templates
@@ -135,67 +180,119 @@ flu-cli t modular  # 简写
 
 ---
 
-### 4. `generate-sm` - 生成状态管理代码
+### 9. `template` - 自定义模板管理（新增）
 
-为现有项目生成状态管理适配与配置。
+用于管理你自己的项目模板，支持从本地目录或 Git 仓库新增模板，并持久化到 `~/.flu-cli/config.json`。在交互式创建项目时，这些模板会与内置模板一起展示并可直接选择。
 
 **用法:**
+
 ```bash
-flu-cli generate-sm <类型>
-flu-cli g <类型>  # 简写
+flu-cli template                # 查看所有自定义模板（同 list）
+flu-cli template list           # 列出所有模板
+flu-cli template add <id> <source> [选项]
+flu-cli template remove <id>
 ```
 
 **选项:**
-- `-d, --dir <path>` - 项目目录（默认：当前目录）
-- `-m, --module <name>` - 模块名称（modular/clean 支持分模块适配器）
+
+-   `--local` 使用本地目录作为模板（`source` 为路径）
+-   `-n, --name <name>` 显示名称（可选）
+-   `-b, --branch <branch>` Git 模板分支（默认 `main`）
+-   `-d, --description <text>` 模板描述
+-   `-f, --force` 覆盖已存在的同名模板
 
 **示例:**
+
 ```bash
-# 生成 Provider 状态管理
-flu-cli generate-sm provider
+# 添加本地模板
+flu-cli template add my-lite /path/to/my-template --local -n "我的 Lite 模板" -d "带业务框架的轻量模板"
 
-# 生成 GetX 状态管理
-flu-cli g getx  # 简写
+# 添加 Git 模板
+flu-cli template add company-clean https://github.com/org/clean-template.git -b main -n "公司 Clean 模板"
+
+# 列出/移除模板
+flu-cli template list
+flu-cli template remove my-lite
 ```
 
+**说明:**
+
+-   模板会缓存到 `~/.flu-cli/templates/<id>/`，创建项目时会从缓存复制。
+-   交互式 `flu-cli new` 会把自定义模板和内置模板一起展示，并支持预览说明。
+-   选择 Git 模板时会从远端克隆到缓存目录；选择本地模板时会直接复制到缓存目录。
+
 ---
 
-### 5. `sync-snippets` - 同步代码片段
+### 10. `config` - 项目生成配置（新增）
 
-将最新的标准 VS Code 代码片段同步到当前项目。
+初始化并管理项目根目录下的 `.flu-cli.json`，用于声明生成器的默认行为（路径、页面类型、是否绑定 ViewModel 等）。VSCode 扩展与 v2 的生成命令都会读取该文件。
 
 **用法:**
+
 ```bash
-flu-cli sync-snippets
-flu-cli sync  # 简写
+flu-cli config init [选项]
 ```
 
-**说明:**
-- 该命令会覆盖项目的 `.vscode/dart.code-snippets` 文件。
-- 新项目创建时会自动同步，无需手动执行。
+**选项:**
+
+-   `-d, --dir <path>` 目标项目目录（默认当前目录）
+-   `-f, --force` 覆盖已存在的配置文件
 
 **示例:**
+
 ```bash
-# 同步标准代码片段
-flu-cli sync-snippets
+# 在当前项目生成配置
+flu-cli config init
+
+# 指定项目目录并覆盖旧配置
+flu-cli config init -d ~/projects/my_app -f
+```
+
+**.flu-cli.json 示例（简化）:**
+
+```json
+{
+    "generators": {
+        "page": {
+            "path": "lib/pages",
+            "defaultType": "stateful",
+            "withViewModel": true
+        },
+        "viewModel": {
+            "path": "lib/viewmodels"
+        },
+        "model": {
+            "path": "lib/models"
+        }
+    }
+}
 ```
 
+**说明:**
+
+-   初始化时会根据项目模板（lite/modular/clean）生成匹配的默认路径。
+-   VSCode 插件的“生成文件”命令会优先使用 `.flu-cli.json` 中的设置，无需每次选择类型。
+-   可在自定义模板中提供示例 `.flu-cli.json`，在创建后运行 `flu-cli config init -f` 以覆盖为团队约定。
+
 ---
 
-### 6. `update-templates` - 更新模板缓存
+### 5. `update-templates` - 更新模板缓存
 
 更新本地模板缓存到最新版本。
 
 **用法:**
+
 ```bash
 flu-cli update-templates [模板名称]
 flu-cli u [模板名称]  # 简写
 ```
 
 **选项:**
-- `--force` - 强制刷新并清理未跟踪文件
+
+-   `--force` - 强制刷新并清理未跟踪文件
 
 **示例:**
+
 ```bash
 # 更新所有模板
 flu-cli update-templates
@@ -209,20 +306,23 @@ flu-cli update-templates --force
 
 ---
 
-### 7. `cache` - 缓存管理
+### 6. `cache` - 缓存管理
 
 管理本地模板缓存。
 
 **用法:**
+
 ```bash
 flu-cli cache <action>
 flu-cli c <action>  # 简写
 ```
 
 **支持的操作:**
-- `clean` - 清理缓存
+
+-   `clean` - 清理缓存
 
 **示例:**
+
 ```bash
 # 清理缓存
 flu-cli cache clean
@@ -231,17 +331,19 @@ flu-cli c clean  # 简写
 
 ---
 
-### 8. `completion` - 自动补全
+### 7. `completion` - 自动补全
 
 生成 Shell 自动补全脚本（支持 Bash/Zsh）。
 
 **用法:**
+
 ```bash
 flu-cli completion
 flu-cli comp  # 简写
 ```
 
 **安装方法:**
+
 ```bash
 # Zsh
 flu-cli completion >> ~/.zshrc
@@ -254,9 +356,26 @@ source ~/.bashrc
 
 ---
 
+## 常见问题 (FAQ)
+
+**Q: `add page` 默认生成的代码不符合我的项目结构怎么办？**
+
+A: Flu CLI 是为特定架构（MVVM + Provider）设计的。如果您使用完全自定义的架构，建议：
+
+1. 使用 `--no-vm` 仅生成页面。
+2. 或者，Fork 本项目并修改模板代码以适配您的团队规范。
+3. 利用 VSCode 插件自带的代码片段 (Snippets) 快速编写代码，而不是依赖 CLI 生成。
+
+**Q: 为什么生成的 Service 很简单？**
+
+A: 我们移除了原来复杂的 Service 模板，只生成最基础的类结构。这样您可以自由选择使用 `http`, `dio` 还是其他网络库，而不受 CLI 预设逻辑的限制。
+
+---
+
 ## 常见工作流
 
 ### 创建新项目
+
 ```bash
 flu-cli new my_app
 cd my_app
@@ -265,19 +384,56 @@ flu-cli add page home
 flu-cli add page user_list --list-page
 ```
 
+### 使用自定义模板创建项目
+
+````bash
+# 添加模板（本地或 Git）
+flu-cli template add my-lite /path/to/my-template --local
+# 或
+flu-cli template add company-clean https://github.com/org/clean-template.git -b main
+
+# 交互式选择自定义模板并创建
+flu-cli new
+
+# 初始化项目生成配置（让 VSCode/CLI 生成遵循你的路径约定）
+flu-cli config init
+
+### 基于配置快速生成页面/VM
+```bash
+# 初始化配置后：
+flu-cli add page home            # 路径/类型按 .flu-cli.json 生效
+flu-cli add viewmodel home       # VM 路径按配置生效
+flu-cli add model user           # Model 路径按配置生效
+````
+
+### 更新模板缓存与故障排除
+
+```bash
+# 更新缓存到最新
+flu-cli update-templates [模板ID]
+
+# 模板拉取失败或缓存异常
+flu-cli cache clean
+flu-cli new my_app --no-cache
+```
+
+````
+
 ### 在现有项目中使用
+
 ```bash
 cd existing_project
 
-# 同步代码片段
-flu-cli sync-snippets
+# 初始化配置文件
+flu-cli config init
 
 # 添加组件
 flu-cli add page settings
-flu-cli add service api --type api
-```
+flu-cli add service api
+````
 
 ### Modular 架构项目
+
 ```bash
 flu-cli new my_app -t modular
 cd my_app
@@ -295,10 +451,12 @@ flu-cli add page profile -f user
 ## 全局选项
 
 所有命令都支持以下选项：
-- `-V, --version` - 查看版本号
-- `-h, --help` - 查看帮助信息
+
+-   `-V, --version` - 查看版本号
+-   `-h, --help` - 查看帮助信息
 
 **示例:**
+
 ```bash
 flu-cli --version
 flu-cli add --help
@@ -309,20 +467,24 @@ flu-cli add --help
 ## 配置文件
 
 Flu-CLI 会在以下位置存储配置：
-- **缓存目录**: `~/.flu-cli/cache/`
-- **配置文件**: `~/.flu-cli/config.json`
+
+-   **缓存目录**: `~/.flu-cli/cache/`
+-   **配置文件**: `~/.flu-cli/config.json`
 
 ---
 
 ## 故障排除
 
 ### 命令卡住
+
 如果命令执行过程中卡住，可以：
+
 1. 按 `Ctrl+C` 中止
 2. 运行 `flu-cli cache clean` 清理缓存
 3. 重新执行命令
 
 ### 模板拉取失败
+
 ```bash
 # 清理缓存后重试
 flu-cli cache clean
@@ -333,17 +495,18 @@ flu-cli new my_app --no-cache
 ```
 
 ### 代码片段不生效
-```bash
-# 重新同步代码片段
-flu-cli sync-snippets
 
-# 重启 VS Code 后生效
-```
+VSCode 扩展使用**动态代码片段**功能，会根据项目配置自动适配：
+
+1. 确保已安装 Flu CLI VSCode 扩展
+2. 打开 `.dart` 文件时扩展会自动激活
+3. 代码片段会根据 `.flu-cli.json` 配置动态显示
+4. 如果看不到代码片段，尝试重启 VSCode
 
 ---
 
 ## 更多帮助
 
-- 查看具体命令帮助：`flu-cli <command> --help`
-- 项目文档：[flu-cli 文档站](https://your-docs-url)
-- 问题反馈：[GitHub Issues](https://github.com/your-repo/issues)
+-   查看具体命令帮助：`flu-cli <command> --help`
+-   项目文档：[flu-cli 文档站](https://your-docs-url)
+-   问题反馈：[GitHub Issues](https://github.com/your-repo/issues)

package/README.md

@@ -2,16 +2,18 @@
 
 > 🚀 **活跃开发中** - Flutter MVVM 脚手架工具
 
+> 💡 **推荐**: 使用 VSCode 开发？试试我们的 [VSCode 插件](https://marketplace.visualstudio.com/items?itemName=huoye-studio.flu-cli-vscode)，支持右键生成代码，体验更丝滑！
+
 ## ✨ 特性
 
-- 🎯 **交互式创建** - `flu new` 命令提供友好的交互式体验
-- 🔧 **代码生成** - `flu add` 快速生成页面、组件、服务等（支持别名）
-- 📦 **多种模板** - lite、modular、clean 三种架构模板
-- 🎮 **状态管理** - 支持 default、provider、getx、riverpod
-- 📝 **基于 Snippets** - 可自定义 VSCode 代码片段
-- 🎨 **列表页支持** - `--list-page` 自动生成 Page/ViewModel/Model
-- 🚀 **智能补全** - Shell 自动补全（Zsh/Bash）
-- 🌏 **中文友好** - 全中文提示和文档
+-   🎯 **交互式创建** - `flu new` 命令提供友好的交互式体验
+-   🔧 **代码生成** - `flu add` 快速生成页面、组件、服务等（支持别名）
+-   📦 **多种模板** - lite、modular、clean 三种架构模板
+-   🎮 **状态管理** - 支持 default、provider、getx、riverpod
+-   📝 **基于 Snippets** - 可自定义 VSCode 代码片段
+-   🎨 **列表页支持** - `--list-page` 自动生成 Page/ViewModel/Model
+-   🚀 **智能补全** - Shell 自动补全（Zsh/Bash）
+-   🌏 **中文友好** - 全中文提示和文档
 
 ## 📦 安装
 
@@ -52,35 +54,60 @@ flu-cli completion >> ~/.zshrc && source ~/.zshrc
 ## 📚 命令别名
 
 ### add 类型别名
-- `p` = page
-- `w` = widget  
-- `c` = component
-- `v` = viewmodel
-- `s` = service
-- `m` = model
-- `mod` = module
+
+-   `p` = page
+-   `w` = widget
+-   `c` = component
+-   `v` = viewmodel
+-   `s` = service
+-   `m` = model
+-   `mod` = module
 
 ### 顶级命令别名
-- `n` = new
-- `a` = add
-- `t` = templates
-- `g` = generate-sm
-- `u` = update-templates
-- `c` = cache
-- `sync` = sync-snippets
-- `comp` = completion
+
+-   `n` = new
+-   `a` = add
+-   `t` = templates
+-   `u` = update-templates
+-   `c` = cache
+-   `sync` = sync-snippets
+-   `comp` = completion
+
+## ❓ 获取帮助
+
+查看所有命令：
+
+```bash
+flu-cli --help
+```
+
+查看特定命令的详细用法：
+
+```bash
+flu add --help
+flu new --help
+```
 
 ## 📚 文档
 
-- [CLI 命令参考](./CLI.md) - 详细命令说明
-- [完整文档](http://huozhiye.cn/flu-cli/) - 主文档站
+-   [CLI 命令参考](http://huozhiye.cn/flu-cli/reference/cli-reference.html) - 详细命令说明
+-   [完整文档](http://huozhiye.cn/flu-cli/) - 主文档站
+
+## 💬 加入社区
+
+获取最新动态、反馈问题、定制化开发或与开发者直接交流，欢迎加入我们的微信群：
+
+> ![微信群二维码](https://gitee.com/flu-cli/flu-cli/raw/main/packages/vscode-extension/images/wechat-group.png)
+
+如果群二维码过期，请添加作者微信 `Huoye-TT` 备注 "flu-cli" 拉您入群。
 
 ## 🔗 相关链接
 
-- [模板对比](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)
+-   [模板对比](http://huozhiye.cn/flu-cli/guide/templates/template-comparison.html)
+-   [最佳实践](http://huozhiye.cn/flu-cli/best-practices/custom-templates.html)
+-   [从 V1 迁移](http://huozhiye.cn/flu-cli/examples/migration.html)
 
+ 
 ## 📄 许可
 
-MIT License - Copyright © 2025 火之夜工作室
+MIT License - Copyright © 2025 火叶工作室