@dao-style/cli

DAO Style 项目的命令行工具 - 提供项目脚手架、模板生成和依赖管理功能。

🚀 Features

• NPM Template System: 使用 @dao-style-template/ 组织下的 npm 包作为模板
• Version Management: 模板版本自动写入 devDependencies，支持版本追踪
• Smart Upgrade: 检测可升级的模板版本，支持三方合并和冲突解决
• Post-install Tasks: 自动执行模板的安装后任务
• Template Cache: 智能缓存下载的模板，提升性能

前置要求

• Node.js >= 20.0.0
• pnpm >= 9.0.0

安装

npm install -g @dao-style/cli
或
pnpm add -g @dao-style/cli

📦 Template System

NPM Templates

项目使用 @dao-style-template/ 组织下的 npm 包作为模板：

• @dao-style-template/base - 基础项目结构
• @dao-style-template/lint - ESLint 和代码格式化配置
• @dao-style-template/ci - CI/CD 配置

Version Management

模板的具体版本会自动写入项目的 devDependencies：

{
  "devDependencies": {
    "@dao-style-template/base": "1.0.0",
    "@dao-style-template/lint": "1.2.0",
    "@dao-style-template/ci": "1.1.0"
  }
}

🛠️ Commands

创建新项目

project-name 为项目名称，无需包含 ui ，ui 会根据项目名称自动生成。

dao create <project-name> [options]

基础用法

dao create my-app

创建新项目，自动：

• 下载最新版本的模板
• 生成项目文件
• 将模板版本写入 devDependencies
• 设置 postinstall 钩子

可选参数

| 参数 | 简写 | 说明 | 默认值 | | --------------------------- | ---- | ------------------------------------------------------------- | -------- | | --initial-branch <branch> | -b | 设置初始分支名称 | master | | --local | - | 使用本地模板（开发调试用） | - | | --all-templates | - | 选择所有可用模板 | - | | --answer <templatePrompt> | - | 提供模板提示的答案，格式：template.prompt=value，可重复使用 | - |

高级用法示例

1. 使用所有模板并预设答案

dao create test --all-templates \
  --answer base.packages=@dao-style/core,@dao-style/extend,@dao-style/biz \
  --answer base.port=8100

这个命令会：

• 创建名为 test 的项目
• 应用所有可用的模板
• 预设 base 模板的 packages 参数为 @dao-style/core,@dao-style/extend,@dao-style/biz
• 预设 base 模板的 port 参数为 8100

2. 自定义初始分支

dao create my-app --initial-branch main

3. 使用本地模板（开发调试）

dao create test-project --local

查看模板状态

dao list

查看当前项目安装的模板版本和可用更新：

📦 Installed Templates:

  base: 1.0.0 → 1.2.0 (update available)
  lint: 1.1.0 (up to date)
  ci: 1.0.0 → 1.1.0 (update available)

💡 Run "dao upgrade" to update templates.

升级模板

dao upgrade [options]

升级项目中的模板到最新版本，支持智能三方合并和冲突解决。

可选参数

| 参数 | 说明 | 默认值 | | --------- | -------------------------- | ------ | | --local | 使用本地模板（开发调试用） | - |

基础用法

dao upgrade

该命令会：

1. 检查 Git 状态 - 确保工作目录干净（可用 --force 跳过）
2. 检测可用更新 - 扫描所有已安装模板的新版本
3. 选择升级模板 - 交互式选择要升级的模板
4. 处理模板提示 - 智能判断是否需要重新回答 prompts
5. 执行三方合并 - 自动合并文件变更
6. 解决冲突 - 自动或手动解决冲突
7. 更新依赖 - 更新 package.json 并执行 pnpm install

⚠️ 升级注意事项

升级前的建议

1. 提交所有更改 - 升级前确保所有代码已提交到 Git
2. 创建备份分支 - 建议创建备份分支： git checkout -b backup-before-upgrade
3. 了解变更内容 - 使用 dao list 查看可用更新
4. 测试升级结果 - 升级后运行测试确保功能正常

升级后的操作

1. 解决冲突 - 如果有冲突，先解决所有冲突标记
2. 运行开发服务器 - pnpm serve 确保项目能正常启动
3. 执行 Lint 检查 - pnpm lint 确保代码规范
4. 运行测试 - pnpm test:unit 确保功能正常
5. 提交更改 - git add . 和 git commit -m "chore: upgrade templates"

升级流程示例

$ dao upgrade

# 1. 检查 Git 状态
✓ Working directory is clean

# 2. 检测可用更新
📦 Available updates:
  - base: 1.0.0 → 1.2.0 (update available)
  - lint: 1.1.0 → 1.3.0 (update available)
  - ci: 1.0.0 (up to date)

# 3. 选择要升级的模板
? Select templates to upgrade:
  ◉ base Template (1.0.0 → 1.2.0)
  ◉ lint Template (1.1.0 → 1.3.0)
  ◯ ci Template (up to date)

# 4. 处理 prompts（如果模板 prompts 有变化）
Processing base prompts...
? Select packages: @dao-style/core, @dao-style/extend
? Port number: 8100

# 5. 执行升级
✓ Updated: src/main.ts
✓ Merged: vite.config.ts
⚠ Merged with conflicts: .eslintrc.js
✓ Added: src/types/global.d.ts
✓ Deleted: old-config.js

# 6. 更新 package.json
✓ Updated: package.json

# 7. 安装依赖
✓ Dependencies installed

# 如果有冲突
⚠ Upgrade completed with conflicts in the below files. Please resolve them and commit the changes:
- .eslintrc.js

Opening conflicts in VS Code...

🔄 升级机制详解

Prompt 智能处理

升级时会智能判断是否需要重新回答 prompts：

场景 1：Prompts 完全相同

• 行为：只询问一次，使用新版本的 prompts
• 原因：避免重复输入相同的问题

场景 2：Prompts 不同

• 行为：分别询问原始版本和目标版本的 prompts
• 原因：需要分别计算原始和目标的模板渲染结果

场景 3：新增模板

• 行为：只询问新模板的 prompts
• 原因：原始版本不存在该模板

场景 4：移除模板

• 行为：只询问原始模板的 prompts
• 原因：需要计算原始版本用于三方合并

文件处理策略

升级过程会根据不同情况采取不同的处理策略：

1. SKIP（跳过）

• 本地文件与目标文件相同 → 已是最新
• 合并后无变化 → 无需更新
• 模板未变且本地已删除 → 尊重本地删除
• 本地修改过的文件，模板已删除 → 保留本地修改

2. UPDATE（直接更新）

• 本地文件与原始模板相同 → 直接用新模板覆盖

✓ Updated: src/main.ts

3. MERGE（合并）

• 本地有修改，模板也有更新 → 执行三方合并
• 无冲突时自动合并

✓ Merged: vite.config.ts

4. MERGE with CONFLICTS（冲突合并）

• 合并时发现冲突 → 生成冲突标记

⚠ Merged with conflicts: .eslintrc.js

5. ADD（新增）

• 新模板添加的文件

✓ Added: src/types/global.d.ts

6. DELETE（删除）

• 模板删除了文件，且本地未修改

✓ Deleted: old-config.js

二进制文件处理

升级过程能正确处理二进制文件（图片、字体等）：

• 识别：根据文件扩展名识别（.png, .jpg, .ttf, .woff 等）
• 编码：使用 base64 编码处理
• 比较：通过内容哈希判断是否相同
• 合并：冲突时默认使用新版本

Three-way Merge（三方合并）

升级过程使用智能三方合并算法，比较三个版本的文件，实际使用的是 git 命令 git merge-file <Local> <Original> <Target> 来执行三方合并。

        ┌─────────────┐
        │   Original  │  ← 之前安装的模板版本
        │  (Base 版本) │
        └──────┬──────┘
               │
       ┌───────┴───────┐
       ↓               ↓
┌──────────┐    ┌──────────┐
│  Local   │    │  Target  │
│ (当前版本) │    │ (新模板版本)│
└──────────┘    └──────────┘
       │               │
       └───────┬───────┘
               ↓
        ┌──────────┐
        │  Merged  │  ← 合并结果
        └──────────┘

冲突解决

当自动合并失败时，会在文件中生成冲突标记：

<<<<<<< HEAD
// 当前项目的代码
const config = {
  port: 8080,
  old: 'value'
};
=======
// 新模板的代码  
const config = {
  port: 8100,
  new: 'value',
  updated: true
};
>>>>>>> template

解决冲突的步骤：

1. 自动打开编辑器 - 如果安装了 VS Code，会自动打开冲突文件
2. 手动解决冲突 - 编辑文件，删除冲突标记，保留需要的代码
3. 测试验证 - 确保项目能正常运行
4. 提交更改 - git add . 和 git commit

贡献

开发

运行以下命令将会将本地的 dao 命令自动的 link 到全局，同时在退出时会自动取消 link

pnpm dev # 运行开发环境，会监听文件变动并重新编译

模板调试

将模板挂载全局 https://gitlab.daocloud.cn/ndx/frontend-engineering/vue-cli-plugins/dao-style-template#%E5%BC%80%E5%8F%91%E5%91%BD%E4%BB%A4

# create
dao create test-project --local

# list
dao list --local

# upgrade
dao upgrade --local