模板配置参考

每个 AgileBuilder 模板在根目录放置一份配置文件。CLI 按以下顺序查找，取先命中的那个：

1. .agilebuilder.config.yaml
2. .agilebuilder.config.json

如果两者都不存在，生成流程使用默认配置继续执行并输出警告。默认配置等价于：variables.enabled: false、filePatterns.mode: all、patterns: ["**/*"]、delimiter: "%"、inquirerQuestions: []、无 Hook。

完整示例：

version: '1.0'
name: service-template
description: Service starter
source:
  subdir: template
variables:
  enabled: true
  delimiter: "%"
  filePatterns:
    mode: include
    patterns:
      - "**/*.ts"
      - "package.json"
  inquirerQuestions:
    - name: appName
      type: input
      message: Application name
      required: true
      default: my-app
    - name: useAuth
      type: confirm
      message: Enable authentication?
      default: true
    - name: runtime
      type: list
      message: Runtime
      choices:
        - node
        - bun
hooks:
  after_write:
    scriptType: shell
    script: npm install
    errorHandling: warn
market: {}

配置文件本身不会复制到生成结果中。

顶层字段

version

• 类型：字符串；缺省 '1.0'。
• 配置格式版本。当前 CLI 读取它但不按版本分支行为，建议固定写 '1.0'。

name / description

• 类型：字符串；可选。
• 模板的名称与描述，仅作元信息展示，不影响生成行为。

source

可选对象，描述模板文件在仓库内的位置。

字段	类型	说明
source.subdir	字符串	指向已获取模板目录内的实际模板文件根目录。当配置文件放在仓库根目录、而待生成文件在 template/ 等子目录时使用。
source.type	'git' 或 'editor'	保留字段。CLI 不根据它决定获取方式——模板来源由命令参数、资源定义或 Cloud 模板定义决定。

source.subdir 必须是相对路径，不允许绝对路径或 .. 段，否则报 TEMPLATE_SUBDIR_UNSAFE。

variables：变量渲染

variables 是对象，缺省时所有子字段取默认值。

variables.enabled

• 类型：布尔；默认 false。
• 总开关。为 true 时渲染文件内容，并同时渲染文件路径；为 false 时所有文件按原样复制。

variables.delimiter

• 类型：字符串；默认 "%"。
• EJS 分隔符，即 <% 与 %> 中间那个字符。默认 % 对应常见的 <%= appName %> 写法。若改为 ?，占位符就写作 <?= appName ?>。
• 兼容处理：误写成 "<%" 或 "%>" 会被自动归一化为 "%"。

variables.filePatterns

控制哪些文件参与内容渲染（详细匹配语义见 文件匹配与 Hooks）。

字段	类型	默认	说明
mode	all | include | exclude	all	all 渲染所有非二进制文件；include 只渲染匹配任一 pattern 的文件；exclude 渲染未匹配任何 pattern 的文件。非法值按 all 处理。
patterns	字符串数组	["**/*"]	minimatch 模式，与模板内相对路径匹配。空数组按 ["**/*"] 处理。

无论 mode 如何，二进制文件都直接复制、不渲染。

variables.inquirerQuestions

交互问题数组。每个问题定义一个变量，在 --interactive 模式下向用户提问，并提供默认值与必填校验。缺少 name 或 message 的条目会被忽略。

字段	类型	说明
name	字符串（必填）	变量名，即模板中 <%= name %> 引用的名字。
type	字符串	问题类型，仅支持 input、number、confirm、list、checkbox、password；缺省按 input 处理。
message	字符串（必填）	提问文案。
default	任意	默认值，仅在变量仍缺失时应用。
required	布尔	为 true 时，在写入文件前校验该变量必须非空，校验失败则中止生成并报 TEMPLATE_VARS_MISSING。
choices	数组	list / checkbox 的选项；元素可以是字符串或 { name, value } 对象。

各类型在交互模式下的行为：

type	交互控件	变量值类型
input	单行输入	字符串
number	数字输入	数值
confirm	是/否确认	布尔
list	单选列表	选中项的值
checkbox	多选列表	选中值数组
password	掩码输入	字符串

注意：问题类型只影响交互录入和默认值，不限制 --var / --vars 传入的值；--var 的值按标量规则解析（true/false/null/数字）。变量优先级见 CLI 命令参考。

hooks：生成后钩子

hooks 是以阶段名为键的对象。当前只处理 after_write 阶段，且只执行 scriptType: shell。

hooks:
  after_write:
    scriptType: shell
    script: npm install
    errorHandling: warn
    env:
      NPM_CONFIG_REGISTRY: https://registry.npmjs.org

字段	类型	默认	说明
scriptType	shell | nodejs | custom	shell	当前仅 shell 可执行；其他类型在授权后会报 HOOK_TYPE_UNSUPPORTED。
script	字符串（必填）	—	在目标目录中执行的 shell 命令。缺少 script 的 Hook 条目被忽略。
errorHandling	stop | warn | continue	stop	stop：Hook 失败即中止生成（HOOK_FAILED）；warn / continue：记录为跳过并继续。
env	键值对象	—	附加环境变量，与进程环境合并后传给 Hook。

Hook 默认不执行，需要 --allow-hooks 或 template.allowHooksDefault: true 显式授权；执行超时为 5 分钟。执行模型与安全设计见 文件匹配与 Hooks。

market：预留字段

• 类型：任意对象；可选。
• 为模板市场/资源广场预留的元数据位（如分类、图标、展示文案等）。CLI 读取并保留该字段，但生成流程不消费它。当前可以随意放置自己的扩展元数据，或留空。

归一化行为速查

CLI 加载配置时会做宽容归一化，了解这些规则可以避免意外：

• version 非字符串 → '1.0'。
• variables.enabled 非布尔 → false。
• filePatterns.mode 非法 → all；patterns 非数组 → ["**/*"]；数组中的非字符串项被丢弃。
• delimiter 为空或非字符串 → "%"；"<%" / "%>" → "%"。
• 问题缺少 name / message → 整条忽略；type 缺省 → input。
• Hook 缺少 script → 忽略；scriptType 非法 → shell；errorHandling 非法 → stop；env 中非字符串值被丢弃。
• 配置文件本身不是合法 YAML/JSON → 报 TEMPLATE_CONFIG_INVALID。