快速开始 · 开源版

本篇带你在不注册任何账号的情况下完成第一次项目生成。开源版的全部本地功能永久免费（MIT 协议），数据只存在你自己的电脑上。

第 1 步：安装 CLI

npm install -g agilebuilder
ag --version

要求 Node.js ≥ 20 且本机装有 Git，详见安装。

第 2 步：从 Git 模板直接创建项目

任何公开可访问的 Git 仓库都可以作为模板来源，无需提前登记：

ag create --git-url https://github.com/example/template.git --target ./my-app

常用选项（--branch 指定分支、--subdir 使用仓库内子目录作为模板根、--var 传入模板变量，均可选）：

ag create --git-url https://github.com/example/template.git \
  --target ./my-app \
  --branch main \
  --subdir templates/node \
  --var appName=my-app \
  --var useAuth=true

执行后 CLI 会克隆模板仓库、渲染变量（EJS 语法，如 <%= appName %>），把结果写入 --target 目录。目标目录已存在且非空时，需要显式加 --overwrite。

交互式录入变量

模板作者在 .agilebuilder.config.yaml 中定义了问题时，加 --interactive 可以让 CLI 逐项提示你输入缺失的变量：

ag create --git-url https://github.com/example/template.git \
  --target ./my-app --interactive

第 3 步：登记常用模板，下次一键创建

每次都输完整 Git 地址太麻烦。用 ag res add 把模板登记到本地工作空间：

ag space use local    # 使用内置本地工作空间（默认即是，无需登录）

ag res add template \
  --name web-app \
  --git-url https://github.com/example/template.git \
  --branch main \
  --tags "web,starter"

之后用资源 ID 或名称即可创建项目：

ag res list                 # 查看已登记的模板，找到序号/ID
ag create 1 --target ./my-app --var appName=my-app

其他常用的本地资源命令：

ag res search web           # 按关键词搜索
ag res get 1                # 查看详情
ag res edit 1 --name new-name
ag res remove 1 --yes       # 删除需要显式确认

第 4 步（可选）：允许模板 Hooks

模板可以定义生成后执行的 Hook（目前仅支持 after_write 的 shell 脚本，例如在生成目录里自动执行 npm install）。出于安全考虑，Hook 默认不执行，需要显式授权：

ag create 1 --target ./my-app --allow-hooks

如果你信任自己维护的模板，可以把默认行为改为允许：

ag config set template.allowHooksDefault true

开源版能做什么、不能做什么

能力	开源版（本地）
从 Git URL / 本地资源创建项目	✅
模板变量渲染、Hooks	✅
本地模板/文档资源管理	✅
MCP server 供 AI 工具调用	✅
云端空间、多设备同步	❌（需注册并登录，见专业版快速开始）
团队共享模板库	❌（见团队版快速开始）

下一步

• 核心概念 — 理解资源、变量、Hooks 与空间
• 创建模板 — 把自己的项目做成模板
• MCP 集成 — 让 AI 工具调用你的模板库