AgileBuilder logoAgileBuilder
返回文档

核心概念

一篇讲清 AgileBuilder 的资源、模板、变量、Hooks、空间与 MCP，以及开源版与云端的能力边界

本篇解释 AgileBuilder 的六个核心概念，以及开源 CLI 与云端服务之间的能力边界。

资源（Resource）

资源是 AgileBuilder 管理的基本单位，只有两种类型：

类型用途
template（模板）指向一个 Git 仓库（可选分支与子目录），用于 ag create 生成项目
doc（文档）Markdown 或纯文本内容，作为规范与参考材料；同时可作为 MCP resource 暴露给 AI 工具

资源隶属于某个空间：本地资源保存在 ~/.agilebuilder/v2/resources/local.json，云端资源保存在对应空间中并在多设备间同步。

管理资源的命令统一在 ag res 下：list / search / get / add / edit / remove，详见 CLI 参考与资源管理。

模板（Template）

模板 = 一个 Git 仓库 + 一个 .agilebuilder.config.yaml 配置文件。

模板仓库的根目录（或用 source.subdir 指定的子目录）中放置 .agilebuilder.config.yaml，声明模板名称、变量、文件匹配规则和 Hooks：

version: '1.0'
name: service-template
description: Service starter
source:
  subdir: template
variables:
  enabled: true
  filePatterns:
    mode: include
    patterns:
      - "**/*.ts"
      - "package.json"
  inquirerQuestions:
    - name: appName
      type: input
      message: Application name
      required: true
hooks:
  after_write:
    scriptType: shell
    script: npm install
    errorHandling: warn

要点：

  • 没有配置文件的仓库也能用——CLI 会按默认配置继续并输出警告
  • .agilebuilder.config.yaml 本身不会复制到生成的项目中
  • 二进制文件不渲染，直接复制；默认跳过 .git 目录（--keep-git 可保留）

模板制作的完整指南见创建模板与模板配置。

变量（Variables）

模板通过变量实现"同一模板、不同输出"：

  • 文件内容用 EJS 渲染，默认分隔符为 %，占位符形如 <%= appName %>；支持 if、循环等完整 EJS 语法
  • 文件路径也参与渲染，支持 {{ variableName }} 写法和 EJS 表达式
  • 内置命名转换辅助函数：camelCase、pascalCase、kebabCase、snakeCase、uppercase、lowercase，如 <%= pascalCase(appName) %>

生成时变量的取值优先级（--vars 文件 > --var 参数；其余未提供的变量先取模板配置中的默认值，仍缺失的再通过交互录入补充）：

  1. --vars <path> JSON 文件中的变量
  2. 重复传入的 --var key=value（覆盖 --vars 中的同名变量）
  3. 模板问题中定义的默认值（仅补缺）
  4. --interactive 交互式录入（仅补缺）

详细语法见模板语法。

Hooks

Hooks 是模板定义的、在项目文件写入后执行的自动化动作。当前版本的能力边界：

  • 仅支持 after_write 一个时机
  • 仅支持 scriptType: shell，脚本在生成的目标目录中执行
  • 默认不执行：需要 --allow-hooks 显式授权，或将 template.allowHooksDefault 配置为 true
  • errorHandling：stop 失败即中止；warn / continue 记录后跳过

详见模板 Hooks。

空间（Space）

空间是资源的容器，也是开源版与云端的分界线：

本地空间 local云端空间（个人 / 团队）
来源CLI 内置，无需登录AgileBuilder Cloud，需 ag login
存储本机 ~/.agilebuilder/v2云端，多设备同步
结构扁平资源列表，不支持目录支持目录树（--parent-id）
写入权限无限制免费版只读；Trial / Pro 可写
协作无成员、角色、权限管理（团队空间）

用 ag space list / ag space use <id> / ag space current 管理当前空间；当前空间决定 res 命令的作用对象和 create <resource-id> 的解析范围。

MCP 的角色

MCP（Model Context Protocol）是 AgileBuilder 与 AI 工具之间的桥梁。包内置一个 stdio server：

agilebuilder-mcp

在 Cursor、Claude Code、Codex 等支持 MCP 的工具中配置后，AI 可以：

  • 通过 MCP tools 查询资源（list_resources / search_resources / get_resource）并创建项目（create_project）
  • 通过 MCP resources 直接阅读你的规范文档（agilebuilder://local/docs/<id>、agilebuilder://cloud/docs/<id> 等）

MCP server 与 CLI 使用同一个当前空间：CLI 里切换到团队空间，AI 读到的就是团队空间的资源。AgileBuilder 本身不调用任何大模型，它只负责把模板和规范送到 AI 手边。配置方法见 MCP 集成。

能力边界一览

能力开源 CLI云端 Cloud
从 Git URL 创建项目✅✅
模板变量 / Hooks / MCP server✅✅
本地资源管理✅—
云端资源管理与多设备同步—免费版只读，Trial/Pro 可写
团队空间、角色权限、操作日志—团队版订阅
资源广场发布—Pro / 团队版

下一步