experience-ui-bundle-project-generate

使用 UI Bundle 模板

在从头构建 Salesforce UI bundle 应用之前，先向用户提供一个预构建的入门模板。Salesforce CLI 可通过一条命令生成这些模板——一个完整、可部署的 SFDX 项目（UI bundle + 工具链 + npm run setup 自动化脚本）。从入门模板开始，比手动搭建更快，也更不容易出错。

CLI 命令为 sf template generate project。

第 1 步：提供选择

确定框架。 通常，调用上下文已经确定了框架——要么由调用此技能的根技能/协调器技能传入，要么在用户请求中说明。使用该框架。

此技能支持的框架，恰好是 <SKILL_DIR>/references/ 下的参考文件，每个文件的名称格式为 <framework>-project-generate.md（例如，react → <SKILL_DIR>/references/react-project-generate.md）。这是唯一可信来源——添加框架只需添加参考文件，无需更改此处内容。

• 如果已知框架——打开 <SKILL_DIR>/references/<framework>-project-generate.md。
• 如果框架未知（独立运行时无人说明框架）——列出 <SKILL_DIR>/references/，从每个文件名中去掉 -project-generate.md 后缀，得出支持的框架列表，并请用户从中选择。如果用户指定的框架没有对应的参考文件，则此处不支持该框架——将任务交给 experience-ui-bundle-app-coordinate，从头搭建。

每个参考文件都会列出该框架的 --template 标志及每个入门模板包含的内容。根据用户群体（内部还是外部）选择合适的模板。

如果用户更愿意从头开始（或没有合适的模板），则在此处停止，让 experience-ui-bundle-app-coordinate 搭建新项目。此技能为可选项——不要强制使用模板。

用户选定后，在第 2 步中使用所选的 --template 标志。

步骤 2：将项目生成到目标根目录

项目内容必须直接生成到目标根目录 $DEST——因此 sfdx-project.json 位于 $DEST/sfdx-project.json，且不会多出一层包装子目录。sf template generate project 总会将输出嵌套在 --name 子目录中，因此 <SKILL_DIR>/scripts/generate-project.mjs 会将项目生成到 $DEST，将子目录中的内容平铺到 $DEST（遇到冲突时覆盖已有内容），并删除现在已空的子目录——整个过程都通过 Node 的 fs/child_process API 完成，因此在 Windows cmd/PowerShell 上的运行方式与在 macOS/Linux/Git Bash 上相同。

• <SKILL_DIR> = 此技能自身目录的绝对路径，即包含此 SKILL.md 的文件夹；请从上下文中的技能路径解析
• $NAME — 项目名称（仅限字母数字字符，不含空格、连字符、下划线或特殊字符）。请向用户询问。它也会作为 UI bundle 的名称，因此会显示在项目中。
• $DEST — 内容生成到的目标根目录（当前目录请使用 .）。
• $TEMPLATE — 步骤 1 中所选框架参考中的 --template 标志值（例如 reactinternalapp）。

运行脚本时，请将 $NAME、$DEST 和 $TEMPLATE 替换为实际的字面值——不要使用 shell 变量赋值或插值（NAME=... / $NAME / %NAME% / $env:NAME），因为这些语法在 bash、cmd 和 PowerShell 中各不相同，而此命令必须能在这三种环境中运行：

node "<SKILL_DIR>/scripts/generate-project.mjs" "<name>" "<dest>" "<template>"

成功时，脚本会打印 OK: project root landed at <dest> (...) 并以状态码 0 退出。如果 sf template generate project 失败、生成的项目中没有 sfdx-project.json，或平铺操作未留下有效的项目根目录，脚本会以非零状态码退出并输出清晰的 stderr 错误信息——请停止操作并报告失败，不要继续。

sfdx-project.json 必须位于 $DEST/sfdx-project.json。项目还包含 package.json、force-app/main/default/uiBundles/$NAME/（UI bundle）、scripts/、config/ 和 README.md。有关 bundle 的具体内容，请参阅步骤 1 中的框架参考。

步骤 3：安装依赖项（由你执行——不要交付尚未安装依赖项的项目）

如果生成的项目不包含 node_modules，请在交付项目之前自行安装依赖项——全新的模板在安装依赖项之前无法运行（预览、构建和 lint 都会失败）。用户应收到一个可立即开始开发的项目。

有多个 package.json 文件，每个文件都需要单独安装：

• 项目根目录（$DEST/package.json）；以及
• $DEST/force-app/main/default/uiBundles/$NAME/ 下的 UI bundle 目录——预览服务器加载的工具链位于此处，因此这里也必须有 node_modules。

<SKILL_DIR>/scripts/install-deps.mjs 会分别在根目录以及每个包含 package.json 的 UI bundle 中运行 npm install（通过 Node 的 child_process 并显式指定 cwd，不使用 cd && shell 链接），然后验证所有执行了安装的目录中是否都生成了 node_modules：

node "<SKILL_DIR>/scripts/install-deps.mjs" "<dest>"

将步骤 2 中 $DEST 的字面值替换 <dest>。成功时，脚本会打印 OK: all dependencies installed. 并以状态码 0 退出；否则会以非零状态码退出，并列出安装失败项的汇总信息。首次安装 bundle 是耗时较长的步骤；请稍等片刻。如果安装失败，请报告失败——不要交付只安装了一部分依赖项的项目。

第 4 步：确认并移交

install-deps.mjs 已在第 3 步中打印验证摘要（根目录和每个 UI bundle 的 node_modules）。若要自行查看生成的项目，请使用自己的文件列表和读取工具，而不要使用 shell ls——无论底层使用哪种 OS shell，效果都相同。

项目现在已准备好进行开发和部署。如果模板中有 README.md，请查看其中是否为用户提供了额外步骤或指南。

接下来，使用其他 ui-bundle 技能（experience-ui-bundle-frontend-generate、experience-ui-bundle-salesforce-data-access、experience-ui-bundle-deploy 等）继续开发这个已搭建好脚手架的项目——脚手架搭建和依赖安装都已完成。

注意事项

• 这些入门模板十分精简——没有预置示例数据或自定义对象。请使用其他 ui-bundle 技能完成其余部分。
• 这些模板使用 uiBundles 元数据约定。UI bundle 目录和 meta XML 均以你通过 --name 传入的项目名称命名。
• 如果标志名称发生变化，sf template generate project --help 会列出所有可用模板。