based

based 是一个本地模板 CLI，用于把项目模板添加到当前目录或指定目录。

当前版本只支持本地模板仓库。核心命令是 based add，它表达的是“把一个模板能力添加到某个目录”，因此同一个目标目录可以多次添加不同模板。

English | 简体中文

安装

npm install -g @chin0102/based-cli

安装后检查命令：

based --help
based add --help

快速开始

1. 准备一个本地模板仓库：

~/workspace/based-templates/
└─ node-api/
   ├─ template/
   │  ├─ package.json
   │  └─ README.md
   └─ meta.json

2. 配置模板仓库路径：

based config set templatesDir ~/workspace/based-templates

3. 查看模板列表：

based list

4. 添加模板到当前目录：

based add node-api

5. 添加模板到指定目录：

based add node-api ./apps/api

命令

based add

把本地模板添加到目标目录。

based add
based add <template>
based add <template> <targetDir>

参数：

• template：模板名称，对应模板仓库中的一级目录名。
• targetDir：目标目录。不传时默认使用当前工作目录。

示例：

based add
based add vue-admin
based add vue-admin ./apps/admin

行为说明：

• 不传 template 时，会交互式选择模板。
• 不传 targetDir 时，会添加到当前工作目录。
• 目标目录不存在时会自动创建。
• 目标目录已存在时不会删除目录，而是把模板内容合并进去。
• 同一个目标目录可以多次执行 based add。
• 新文件会直接写入。
• 已存在且内容相同的文件会跳过。
• 已存在且内容不同的文件会进入冲突处理。

冲突策略：

based add vue-admin ./apps/admin --skip-existing
based add vue-admin ./apps/admin --overwrite

• 默认：交互选择覆盖、跳过或终止。
• --skip-existing：遇到冲突文件时跳过。
• --overwrite：遇到冲突文件时覆盖。

based add 只处理模板中同路径的文件，不会删除目标目录中的其他文件。

based list

列出当前配置的本地模板仓库中的模板。

based list

输出示例：

node-api     Node API template
vue-admin    Vue admin template

只有包含 template/ 目录的一级子目录才会被识别为模板。

based config

管理 CLI 本地配置。

based config set templatesDir ~/workspace/based-templates
based config get templatesDir
based config list

配置文件默认存放在：

~/.based/config.json

配置示例：

{
  "templatesDir": "~/workspace/based-templates"
}

测试或 CI 可以通过环境变量覆盖配置目录：

BASED_CONFIG_DIR=/tmp/based-config based list

模板仓库结构

模板仓库是一个普通本地目录，每个一级子目录代表一个模板。

推荐结构：

~/workspace/based-templates/
├─ vue-admin/
│  ├─ template/
│  │  ├─ .codex/
│  │  │  └─ skills/
│  │  │     └─ vue-admin/
│  │  │        └─ SKILL.md
│  │  ├─ package.json
│  │  ├─ src/
│  │  └─ README.md
│  └─ meta.json
│
└─ node-api/
   ├─ template/
   │  ├─ package.json
   │  └─ src/
   └─ meta.json

规则：

• 模板必须包含 template/ 目录。
• template/ 目录中的内容会被复制到目标目录。
• meta.json 可选，但推荐提供。
• 模板名称使用目录名，例如 vue-admin。
• 模板文件可以包含项目级 Codex Skill，例如 .codex/skills/vue-admin/SKILL.md。

meta.json

meta.json 用于描述模板、交互参数和渲染规则。

完整示例：

{
  "name": "vue-admin",
  "description": "Vue admin template",
  "prompts": [
    {
      "name": "projectName",
      "type": "input",
      "message": "Project name",
      "default": "my-app",
      "required": true
    },
    {
      "name": "description",
      "type": "input",
      "message": "Description",
      "default": "A new project"
    },
    {
      "name": "packageManager",
      "type": "list",
      "message": "Package manager",
      "choices": ["pnpm", "npm", "yarn"],
      "default": "pnpm"
    }
  ],
  "render": {
    "content": {
      "include": [
        "package.json",
        "README.md",
        "src/**/*.ts"
      ],
      "exclude": [
        "src/vendor/**"
      ]
    },
    "path": {
      "include": [
        "{{projectName}}.config.js",
        "src/{{moduleName}}/**"
      ]
    }
  }
}

字段说明：

• name：模板名称。当前主要用于描述，实际模板名称来自目录名。
• description：模板描述，会在 based list 中显示。
• prompts：添加模板时需要询问的参数。
• render.content：需要渲染文件内容的文件。
• render.path：需要渲染相对路径的文件或目录。

支持的 prompt 类型：

• input
• confirm
• list

如果没有 meta.json，或 meta.json 中没有 prompts，projectName 默认使用目标目录名称。

模板变量

模板变量使用 Handlebars 语法。

模板文件：

{
  "name": "{{projectName}}",
  "description": "{{description}}"
}

生成后：

{
  "name": "demo-app",
  "description": "Demo project"
}

文件名和目录名也可以使用变量：

template/
├─ {{projectName}}.config.js
└─ src/{{moduleName}}/

变量只会在 meta.json 中显式声明的范围内渲染。没有声明的文件内容和路径会原样复制。

渲染规则

CLI 不会猜测哪些文件应该渲染。模板作者必须在 meta.json 中明确声明。

渲染文件内容

{
  "render": {
    "content": ["package.json", "README.md", "src/**/*.ts"]
  }
}

渲染文件或目录路径

{
  "render": {
    "path": ["{{projectName}}.config.js", "src/{{moduleName}}/**"]
  }
}

使用 include 和 exclude

{
  "render": {
    "content": {
      "include": ["**/*"],
      "exclude": ["public/**", "**/*.png", "**/*.jpg"]
    },
    "path": {
      "include": ["**/{{projectName}}*"]
    }
  }
}

规则说明：

• glob 路径都相对于模板的 template/ 目录。
• render.content 匹配需要渲染内容的文件。
• render.path 匹配需要渲染相对路径的文件或目录。
• 规则值可以是 glob 字符串数组。
• 规则值也可以是包含 include 和 exclude 的对象。
• 未匹配 render.content 的文件会原样复制。
• 未匹配 render.path 的路径会保持原名。

包含 SKILL.md 的模板

如果模板希望同时向目标项目添加 Codex Skill，可以把 Skill 放在模板的 .codex/skills/ 目录下。

示例：

vue-admin/
├─ template/
│  └─ .codex/
│     └─ skills/
│        └─ vue-admin/
│           └─ SKILL.md
└─ meta.json

SKILL.md 示例：

# Vue Admin

Use this skill when working inside a project generated from the vue-admin template.

## Guidelines

- Follow the existing Vue component and routing structure.
- Put reusable UI in `src/components`.
- Put page-level views in `src/views`.
- Use the configured package manager: `{{packageManager}}`.

如果 SKILL.md 中包含变量，需要在 meta.json 中声明渲染：

{
  "render": {
    "content": [
      ".codex/skills/vue-admin/SKILL.md"
    ]
  }
}

如果 SKILL.md 不包含变量，可以不放进 render.content，它会原样复制。

常见用法

给已有项目添加能力模板

cd ./my-project
based add node-api
based add eslint-config --skip-existing
based add codex-skill

给 monorepo 子项目添加模板

based add vue-admin ./apps/admin
based add node-api ./apps/api

重复添加模板但保留已有文件

based add vue-admin ./apps/admin --skip-existing

明确覆盖模板冲突文件

based add vue-admin ./apps/admin --overwrite

当前限制

• 只支持本地模板仓库。
• 不支持 Git 或 NPM 模板源。
• 不支持远程模板注册中心。
• 不支持模板版本管理。
• 不支持模板缓存。

TODO

这些能力在文档中提到或隐含，但当前实现还不完整：

• 校验 meta.json，并为非法 prompts 或 render 规则提供清晰错误。
• 支持脚本和 CI 场景下的非交互参数，例如 --var projectName=demo。
• 当 render.content 指向二进制文件时提供更强保护。