flu-cli 0.0.5 → 2.0.1

package/CLI.md

@@ -0,0 +1,512 @@
+# Flu-CLI v2 命令参考
+
+> Flutter MVVM 脚手架工具 - 快速生成项目和代码
+
+## 快速开始
+
+```bash
+# 创建新项目
+flu-cli new my_app
+
+# 添加页面
+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 模板（默认使用本地模板）
+
+**说明:**
+
+-   交互式创建时会展示“内置模板 + 你通过 `template add` 保存的自定义模板”，可直接选择。
+-   模板复制后会执行占位符替换（如 `{{projectName}}`、`{{package_name}}`）并校正 `pubspec.yaml` 的 `name`。
+-   已存在 `.flu-cli.json` 的项目中再次生成文件时，会遵循其中的路径与风格设置。
+
+**示例:**
+
+```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` - 查看支持的类型列表
+
+**说明:**
+
+-   若项目根存在 `.flu-cli.json`，`add` 会遵循其中的路径与默认类型（如 `generators.page.path`、`defaultType`、`withViewModel`）。
+-   在 `modular/clean` 模板下可用 `-f <feature>` 指定模块以生成到模块目录结构（如 `lib/features/user/...`）。
+
+**示例:**
+
+```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
+```
+
+### 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` - 模板管理
+
+查看可用模板列表或指定模板的详细信息。
+
+**用法:**
+
+```bash
+flu-cli templates [模板名称]
+flu-cli t [模板名称]  # 简写
+```
+
+**示例:**
+
+```bash
+# 查看所有模板
+flu-cli templates
+
+# 查看指定模板详情
+flu-cli templates lite
+flu-cli t modular  # 简写
+```
+
+---
+
+### 9. `template` - 自定义模板管理（新增）
+
+用于管理你自己的项目模板，支持从本地目录或 Git 仓库新增模板，并持久化到 `~/.flu-cli/config.json`。在交互式创建项目时，这些模板会与内置模板一起展示并可直接选择。
+
+**用法:**
+
+```bash
+flu-cli template                # 查看所有自定义模板（同 list）
+flu-cli template list           # 列出所有模板
+flu-cli template add <id> <source> [选项]
+flu-cli template remove <id>
+```
+
+**选项:**
+
+-   `--local` 使用本地目录作为模板（`source` 为路径）
+-   `-n, --name <name>` 显示名称（可选）
+-   `-b, --branch <branch>` Git 模板分支（默认 `main`）
+-   `-d, --description <text>` 模板描述
+-   `-f, --force` 覆盖已存在的同名模板
+
+**示例:**
+
+```bash
+# 添加本地模板
+flu-cli template add my-lite /path/to/my-template --local -n "我的 Lite 模板" -d "带业务框架的轻量模板"
+
+# 添加 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 模板时会从远端克隆到缓存目录；选择本地模板时会直接复制到缓存目录。
+
+---
+
+### 10. `config` - 项目生成配置（新增）
+
+初始化并管理项目根目录下的 `.flu-cli.json`，用于声明生成器的默认行为（路径、页面类型、是否绑定 ViewModel 等）。VSCode 扩展与 v2 的生成命令都会读取该文件。
+
+**用法:**
+
+```bash
+flu-cli config init [选项]
+```
+
+**选项:**
+
+-   `-d, --dir <path>` 目标项目目录（默认当前目录）
+-   `-f, --force` 覆盖已存在的配置文件
+
+**示例:**
+
+```bash
+# 在当前项目生成配置
+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` 以覆盖为团队约定。
+
+---
+
+### 5. `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
+```
+
+---
+
+### 6. `cache` - 缓存管理
+
+管理本地模板缓存。
+
+**用法:**
+
+```bash
+flu-cli cache <action>
+flu-cli c <action>  # 简写
+```
+
+**支持的操作:**
+
+-   `clean` - 清理缓存
+
+**示例:**
+
+```bash
+# 清理缓存
+flu-cli cache clean
+flu-cli c clean  # 简写
+```
+
+---
+
+### 7. `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
+```
+
+---
+
+## 常见问题 (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
+flutter pub get
+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 config init
+
+# 添加组件
+flu-cli add page settings
+flu-cli add service 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
+```
+
+### 代码片段不生效
+
+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)