资源管理

AgileBuilder CLI 把可复用的开发资产统一管理为“资源”。资源有两种类型：

类型	说明
template	指向一个 Git 仓库的指针：仓库 URL、分支（默认 main）、可选的仓库内子目录。用于 ag create 创建项目。
doc	Markdown 或纯文本内容，作为 CLI 管理的参考材料；同时通过 MCP resources 暴露给 AI 智能体。

资源保存在“工作空间”里。AgileBuilder 有两类工作空间：

• 本地工作空间（local）：内置，无需登录。资源保存在本机 ~/.agilebuilder/v2/resources/local.json，是扁平列表，不支持目录树。
• Cloud 工作空间：来自 AgileBuilder Cloud，需要先 ag login。支持目录（--parent-id），可与团队共享。

当前工作空间决定 res 命令和 create <resource-id> 读写哪里的资源。

选择与切换工作空间

ag space list            # 列出本地与 Cloud 工作空间
ag space list --refresh  # 重新拉取 Cloud 工作空间列表（登录后第一次使用建议执行）
ag space current         # 查看当前工作空间
ag space use local       # 使用本地工作空间
ag space use <space-id>  # 切换到 Cloud 工作空间

如果只想对某个 Cloud 工作空间执行单次操作而不切换当前工作空间，用 --space-id：

ag res list --space-id <space-id>
ag res add template --space-id <space-id> --name api --git-url https://github.com/example/api-template.git
ag res remove <resource-id> --space-id <space-id> --yes

登记模板资源

模板资源本质上是一条 Git 仓库记录。把一个团队模板登记进本地工作空间：

ag space use local
ag res add template \
  --name service-template \
  --git-url https://github.com/example/service-template.git \
  --branch main \
  --subdir templates/node \
  --description "Node.js service starter" \
  --tags "node,service"

选项说明：

选项	是否必填	说明
--name <name>	是	资源名称。
--git-url <url>	是	Git 仓库 URL。
--branch <branch>	否	默认值 main。
--subdir <path>	否	仓库内模板目录（一个仓库放多个模板时使用）。
--parent-id <id>	否	父目录节点 ID，仅 Cloud 可用。
--space-id <id>	否	目标工作空间，默认当前工作空间。
--description <text>	否	资源描述。
--tags <tags>	否	逗号分隔的标签。
--json	否	输出 JSON。

登记模板只是把指针存下来，不会克隆仓库；真正的克隆发生在 ag create 时。

登记文档资源

文档资源承载团队规范、架构说明、API 约定等知识材料。内容可以来自文件或直接传入文本，二者至少提供一个：

ag res add doc \
  --name architecture-notes \
  --file ./docs/architecture.md \
  --format markdown \
  --tags "docs,architecture"

ag res add doc --name api-conventions --content "# API 规范 ..."

选项	是否必填	说明
--name <name>	是	资源名称。
--file <path>	与 --content 二选一	从文件读取内容。
--content <text>	与 --file 二选一	直接传入文本内容。
--uri <uri>	否	文档 URI，本地文档默认 local-doc://<name>。
--format <format>	否	markdown 或 text，默认 markdown。
--parent-id <id>	否	仅 Cloud 可用。
--space-id <id>	否	默认当前工作空间。
--description <text>	否	资源描述。
--tags <tags>	否	逗号分隔的标签。
--json	否	输出 JSON。

文档资源的价值在于可以被 AI 智能体消费：通过 agilebuilder-mcp，文档以 MCP resources 形式暴露（URI 形如 agilebuilder://local/docs/<id> 与 agilebuilder://cloud/docs/<id>），智能体在生成代码前可以先读取团队约定。详见 MCP 集成。

列出、搜索与查看

ag res list                       # 当前工作空间的全部资源
ag res list --type template       # 只看模板
ag res search auth                # 按关键字搜索
ag res search auth --type doc     # 只在文档中搜索
ag res get 1                      # 查看资源详情

res 可写作 resource，list 可写作 ls。列出的每条条目带有资源 ID，create 和 get/edit/remove 都用它引用资源。

从模板资源创建项目

ag create 1 --target ./my-app

CLI 会按资源记录的 Git URL、分支和子目录浅克隆模板，渲染变量后写入目标目录。创建时可以用 --branch、--subdir 临时覆盖资源记录，用 --var/--vars/--interactive 传入模板变量。完整选项见 CLI 命令参考；模板本身的制作方式见 制作你的第一个模板。

编辑与删除

ag res edit 1 --name new-name --description "Updated"
ag res edit 1 --tags "backend,starter"
ag res edit 2 --file ./README.md --format markdown   # 更新文档内容
ag res remove 1 --yes

校验规则：

• 至少传入一个可编辑字段。
• --file 与 --content 不能同时使用。
• 模板专属字段（--git-url、--branch、--subdir）不能用于文档资源，反之亦然。
• --parent-id 仅 Cloud 资源可用。
• 删除必须显式传入 --yes 确认。

给脚本与 AI 智能体的 JSON 输出

所有 res 子命令都支持 --json，输出结构化结果，错误带 code / message / suggestion / category 字段：

ag res list --json
ag res search auth --type doc --json
ag res rm 1 --yes --json

协议细节与错误码表见 CLI 命令参考。

已知限制

• 本地工作空间是扁平列表，不支持目录；目录组织仅在 Cloud 工作空间可用。
• Cloud 操作依赖后端 API 可用性与当前用户权限。