AgileBuilder 模板就是一个普通的 Git 仓库，外加一份配置文件 .agilebuilder.config.yaml。你不需要学习新的工程结构——把一个能跑的项目改造成模板，通常只需要三步：抽变量、写配置、验证。

本教程把一个极简的 Node.js 服务改造成模板。

第 0 步：准备原始项目

假设你有一个可以直接运行的服务骨架：

my-service/
├── package.json
├── README.md
└── src/
    └── index.js

package.json 内容：

{
  "name": "my-service",
  "version": "1.0.0",
  "main": "src/index.js"
}

第 1 步：把硬编码换成变量

AgileBuilder 用 EJS 渲染文件内容，默认分隔符是 %，所以占位符写作 <%= 变量名 %>。把 package.json 里的名称改成变量：

{
  "name": "<%= appName %>",
  "version": "1.0.0",
  "main": "src/index.js"
}

README 里可以同时用变量和内置辅助函数：

# <%= pascalCase(appName) %>

A service generated with AgileBuilder.

文件路径也支持变量——用 {{变量名}} 写法。例如把 src/index.js 改名为 src/{{appName}}.js，生成时路径会按变量值渲染。语法细节见模板语法。

第 2 步：编写 .agilebuilder.config.yaml

在仓库根目录创建 .agilebuilder.config.yaml：

version: '1.0'
name: my-service-template
description: A minimal Node.js service template
variables:
  enabled: true
  delimiter: "%"
  filePatterns:
    mode: all
    patterns:
      - "**/*"
  inquirerQuestions:
    - name: appName
      type: input
      message: Application name
      required: true
      default: my-app

要点：

variables.enabled: true 才会启用变量渲染（含文件路径渲染）；缺省为 false。
filePatterns.mode: all 表示渲染所有非二进制文件；想精确控制渲染范围可改用 include / exclude，见文件匹配与 Hooks。
inquirerQuestions 定义交互问题，required: true 的变量缺失时生成会直接失败（TEMPLATE_VARS_MISSING），default 在变量缺失时兜底。

配置文件的完整 schema 见模板配置参考。

如果配置文件不存在，CLI 会按默认配置（不渲染变量、不执行 Hook）继续生成，并输出一条警告——所以模板一定要带上这份文件。

第 3 步：本地验证

ag create 从 Git 地址克隆模板，因此先把模板目录变成 Git 仓库并提交：

cd my-service
git init
git add .
git commit -m "feat: make it an AgileBuilder template"

然后用本地路径作为 --git-url 验证生成效果：

ag create --git-url ./my-service --target ./out \
  --var appName=order-service

打开 ./out 检查：package.json 里的名称应是 order-service，src/index.js 应渲染为 src/order-service.js。

试一次交互模式，体验 inquirerQuestions 的效果：

ag create --git-url ./my-service --target ./out2 --interactive

也可以把模板登记为本地资源后再创建（更接近团队实际用法）：

ag res add template --name my-service --git-url /absolute/path/to/my-service
ag res list
ag create 1 --target ./out3 --var appName=payment-service

第 4 步：发布给团队

把模板仓库推送到团队 Git 服务（GitHub、GitLab 或自建 Git），然后成员各自登记：

git remote add origin https://github.com/your-org/my-service-template.git
git push -u origin main

# 团队成员：
ag res add template \
  --name my-service \
  --git-url https://github.com/your-org/my-service-template.git \
  --branch main
ag create <resource-id> --target ./new-service

登录后还可以把模板登记到 Cloud 工作空间，团队共享一份资源列表，不必每人重复登记：

ag space use <space-id>
ag res add template --name my-service --git-url https://github.com/your-org/my-service-template.git

下一步

模板语法：条件、循环、6 个内置辅助函数、文件路径渲染。
模板配置参考：.agilebuilder.config.yaml 每个字段的完整说明。
文件匹配与 Hooks：精确控制渲染范围，在生成后执行 npm install 等脚本。