dx-project-create

创建新的 Salesforce 项目

通过向导引导用户搭建新的 Salesforce DX 项目，将当前会话移入新项目，将其连接到组织，并为开发进行配置。按顺序执行每个步骤，在执行任何会更改环境的操作前先征求用户确认。

salesforce-development 插件的 MCP 服务（salesforce-api-context、salesforce-metadata-experts、salesforce-lsp）由已安装的插件提供，而非项目提供，因此会话移入新项目后，它们仍会自动保持可用。无需复制项目专属的 .mcp.json。

步骤 1：选择项目模板

此技能会搭建 CLI 提供的所有模板，包括 React/Angular UI-bundle 应用——创建项目是核心能力，不应仅仅为了选择模板就要求安装单独的插件。（项目创建后，experience-ui-bundle-* 技能负责构建完善应用——页面、组件、样式、部署——但初始搭建就在此处进行，无论是否安装了该插件。）

实时从 CLI 读取模板集合——绝不要将其硬编码，因为 Salesforce 会不断添加模板，预置列表会过时：

sf template generate project --help

解析 -t, --template=<option> 行中的 <options: a|b|c|…> 列表——这些用竖线分隔的名称就是权威模板集合。截至撰写本文时，CLI 提供八种模板，均在此处搭建：standard、empty、analytics、agent，以及 UI-bundle 系列 reactinternalapp、reactexternalapp、angularinternalapp、angularexternalapp（React/Angular × 内部/外部受众）。以实时解析结果为准；此处的列表仅在解析失败时作为后备。

先判断是否符合意图快捷规则。 只有当请求明确对应且仅对应一个模板时，才使用快捷规则。选择不明确时，转到选择器以便询问用户——绝不要猜测。以下情况可直接确定 {template}：

• 请求明确提到非 UI 模板：“空白/最小化项目” → empty；“分析项目” → analytics；“Agent 项目” → agent；“标准项目” → standard。
• 请求是 UI-bundle 应用，且框架和受众均明确 → 对应的 UI 模板（例如“内部 React 应用” → reactinternalapp，“面向客户的 Angular 门户” → angularexternalapp）。内部 = 面向员工/已通过身份验证；外部 = 面向客户/合作伙伴，且需要登录流程。

应用描述不等于模板名称。“给我做一个个人待办事项应用”“库存跟踪器”“团队 CRM”描述的是要构建什么，而非选择哪个模板——它们不能确定模板，因此不符合快捷规则。无论看起来多么显而易见，都不要根据应用用途推断为 standard（或任何其他模板）：standard 是选择器的默认选项，并不意味着可以跳过选择器。用户没有指定模板或框架时，必须显示选择器，让用户选择——擅自假定模板正是此步骤要避免的问题。

其他情况一律进入选择器，包括：

• 只说“新建项目”或“创建 Salesforce 项目”，没有指定模板（选择器默认选中 Standard）；

• 描述了应用，但没有指定模板或框架（“待办事项应用”“库存跟踪器”）——显示选择器；绝不要假定应用用途对应某个模板；以及

• 只指定了部分信息的 UI 应用——例如“创建 React 应用”，但没有指定受众。绝不要假定受众。如果已知框架但未指定受众，则跳过顶层选择器，直接进入下方的框架/受众追问，以收集缺失的信息。 否则，提出一个 AskUserQuestion——“项目类型是什么？”（单选，四个选项）。AskUserQuestion 最多只能提供四个选项，因此选择器只展示最常被请求的四种类型；empty 会被有意排除在选择器之外，只有通过上述意图快捷方式（“empty/minimal project”）才能选择。这是有意为之——empty 是很少被选用的基础项目模板，用四个稀缺选项中的一个来提供它，会挤掉常见选项。想要使用它的用户只需说出名称，快捷方式就会直接解析到该模板。

• Standard → standard（默认）——通用的 force-app 元数据项目（Apex、LWC、对象、流程）。

• Agentforce agent → agent——附带一个示例 Local Info Agent。

• CRM Analytics → analytics（Tableau CRM）——添加 waveTemplates 目录。

• React / Angular UI app → UI bundle 入门模板。此选项需要指定框架和受众，因此再提出一个后续 AskUserQuestion（“选择 UI 框架和受众”，四个选项），直接映射到 {template}：

  • React — 内部 → reactinternalapp · React — 外部 → reactexternalapp
  • Angular — 内部 → angularinternalapp · Angular — 外部 → angularexternalapp
  • 内部 = 面向员工／已通过身份验证；外部 = 面向客户／合作伙伴，带有登录、注册和个人资料功能。

解析后的模板为 {template}，并传入第 3 步。如果实时 CLI 添加了新模板，请在此处添加（或者，如果它也是很少被选用的模板，则将其设为意图快捷方式关键词，而不是添加第五个选择器选项）。

步骤 2：选择项目名称

提示用户输入项目名称。它会成为新目录的名称，并插入到下面的 shell 命令中，因此任何命令使用它之前，都必须进行严格验证——绝不能直接传递未经处理的名称。

先按允许列表检查，再拒绝并重新提示。 仅接受符合 ^[A-Za-z0-9][A-Za-z0-9_-]*$ 的名称——由字母、数字、_ 和 - 组成，且以字母或数字开头。任何其他内容（空格、/ 等路径分隔符、开头为 . 或 ..，或 ; | & $ > < ( ) \ " '等 shell 元字符）都无效：说明原因并重新询问。像proj;rm -rf ~这样的名称绝不能传入命令。作为纵深防御，下面的命令也会用引号括起"{name}"`——但真正的防护措施是验证，而不是加引号。

步骤 3：生成项目

生成前先验证——在确认以下各项之前，请勿运行命令：

• ☐ 即将插入的 {name} 是通过步骤 2 允许列表验证的确切值（^[A-Za-z0-9][A-Za-z0-9_-]*$），而不是原始、经过重新编辑或由用户回显的字符串。如果它从未通过验证，请返回步骤 2。
• ☐ {template} 是 CLI 在步骤 1 中公布的选项之一。
• ☐ 当前工作目录中不存在 {name}/ 目录——如果该目录已存在，生成操作会失败（或有覆盖现有项目的风险）。请先用 [ -e "{name}" ] 检查；如果目录存在，请勿覆盖：告知用户，并返回步骤 2 使用其他名称。

在当前工作目录中运行：

sf template generate project -t {template} -n "{name}"

此命令会在当前工作目录下创建新的 {name}/ 目录。（sf project generate 是此命令已弃用的别名——请优先使用 template generate project。）无需执行扁平化步骤——与生成到现有目录中的流程不同，此命令会创建一个全新的 {name}/，其 sfdx-project.json 已位于会话将迁入的根目录中。

UI 捆绑模板包含 npm 依赖项——但请勿替用户安装。 React/Angular 起始模板在安装 npm 依赖项之前无法运行（预览、构建和 lint 都会失败），而且存在多个 package.json 文件——项目根目录和每个 UI 捆绑包各有一个——每个都需要单独安装。首次安装是耗时较长的步骤（需要数分钟），延迟会很明显，因此应由开发者明确决定，而不是由此技能在未经询问时执行。请勿自行运行 npm install。相反，如果 {template} 是 UI 捆绑模板（react*/angular*），请在结束消息中告知用户依赖项尚未安装，并提供他们准备好后可运行的命令（请参阅结束消息中的 UI 捆绑提示）。

步骤 4：将会话迁移到新项目中

现代版 Claude Code（v2.1.169+）可以就地将当前会话迁移到新目录中，无需打开新终端或重新启动，且会保留对话历史记录。告诉用户运行：

/cd {name}

这会迁移会话：加载新目录中的 CLAUDE.md，将项目存储移至该目录（这样 --resume/--continue 就能找到它），并将当前工作目录设为项目根目录，因此剩余的所有 sf 命令都可以直接运行 sf ...，无需路径前缀。

/cd 是客户端侧的迁移操作：它不会触发任何钩子，也不会让你获得发言回合，因此用户一运行它，会话就会立即静默——这是预期行为，并非卡住。但这也意味着，你发给用户的、包含 /cd 的那条消息会是你接下来最后一句话，直到用户再次发言，因此该消息必须以告知用户如何继续的提示结尾。可以用类似这样的一行收尾：

进入项目后，只要说 “下一步是什么”（或“连接一个 org”），我就会接着帮你。

说“下一步是什么”会重新激活此会话并显示旅程提示，引导至下一步（验证 org）。绝不要暗示 /cd 之后会话会自行继续——它不会。

用户重新激活会话后，用一句简短的话确认已完成迁移（例如“你现在已进入 {name}。”），然后继续步骤 5。不要运行 sf-context detect 或 check-tools 来“重新显示”横幅：将 detect 作为工具调用会输出原始钩子 JSON（而非渲染后的横幅），并且插件会自行显示横幅——它每个会话只显示一次 HEADLESS 身份信息（在用户首次询问 Salesforce 时、会话开始时，或用户首次询问方向时），并会在用户询问“我在哪里”/“下一步是什么”时显示旅程提示。用户可随时通过 /salesforce-development:setup 按需运行开发环境健康检查。

较旧版 Claude Code 的回退方案（早于 v2.1.169）：/cd 会返回 Unknown command。这种情况下，用户必须在新目录中重新启动：

cd "{name}" && claude

salesforce-development 插件是通过 marketplace 全局安装的，因此在新目录中启动新会话时会自动加载该插件并触发 SessionStart——横幅和健康检查会自动出现，无需手动调用 sf-context。之后的步骤即可在项目目录中运行。

步骤 5：验证 org

验证此项目要部署到的 org：

sf org login web --alias {alias}

• 提示用户提供 --alias，以便后续步骤可以通过名称引用该 org。
• 对于沙盒，添加 --instance-url https://test.salesforce.com。
• 对于生产环境，省略 --instance-url（默认使用 login.salesforce.com）。

如果用户已验证该 org，则跳过登录，只收集现有别名。

步骤 6：设为默认 org

将刚验证的 org 设为项目的默认目标：

sf config set target-org {alias}

步骤 7：确保已启用源跟踪

使用部署预览检查 org 是否支持源跟踪（这是最轻量的只读源跟踪探测）：

sf project deploy preview --target-org {alias} --json

如果此操作失败，并提示不支持或未启用源跟踪，请询问用户是否要启用：

sf org enable tracking --target-org {alias}

运行启用命令前，请先征得用户确认。

结束消息

完成所有步骤后，告诉用户：

Your project is ready! Here's what was set up:

  ✅ Project generated: {name}/
  ✅ Session relocated into {name}/ (via /cd)
  ✅ Default org: {alias}
  ✅ Source tracking: enabled (or status)

You're already working inside the new project — this same session moved
here with /cd, so just keep going. Run /salesforce-development:setup
anytime to re-check your dev environment.

如果用户采用了旧版本的回退方案（使用 cd {name} && claude 而不是 /cd 重新启动），他们现在处于项目中的全新会话，SessionStart 横幅已引导他们了解环境——请让他们前往 /salesforce-development:setup 重新检查工具。

对于 UI-bundle 项目，脚手架已搭建完成，但尚未安装 npm 依赖——是否安装由开发者决定，而不是由此技能执行（首次安装是耗时数分钟的繁重步骤）。告诉用户，他们的应用需要先安装依赖才能预览、构建或运行 lint，并在他们准备好时提供要在项目目录中运行的命令：

npm install                                        # project root
for b in force-app/main/default/uiBundles/*/; do   # each UI bundle
  [ -f "$b/package.json" ] && ( cd "$b" && npm install )
done

然后添加一行，指向后续开发技能。根据框架指定指引，因为前端构建技能仅适用于 React：

• React（react* 模板）→ experience-ui-bundle-frontend-generate 用于构建页面/组件（该技能专用于 React/TypeScript——shadcn/ui、react-router、appLayout.tsx/routes.tsx），而 experience-ui-bundle-deploy 用于发布应用。
• Angular（angular* 模板）→ 没有 Angular 前端技能，因此不要指向 experience-ui-bundle-frontend-generate：它的前置条件要求存在 React appLayout.tsx/routes.tsx/src/components/ui/，会拒绝 Angular bundle。请根据 Angular 入门项目自己的 README/工具链来构建；experience-ui-bundle-deploy 仍可用于发布（部署与框架无关）。

无论哪种情况，这些技能都位于 experience-react/experience-lwc 插件中；如果用户没有这些插件，那只会影响构建应用，不影响脚手架搭建——他们现在拥有的项目已完整，可直接部署。

规则

• 按顺序执行各步骤；任何会更改环境的操作（登录、设为默认项、启用跟踪）前都要先确认。
• 插件的 MCP 服务来自已安装的插件，而不是项目——不要在新项目中创建或复制 .mcp.json（插件的配置使用 ${CLAUDE_PLUGIN_ROOT}，在项目级文件中无法解析）。
• 优先使用 /cd {name} 在当前会话中切换目录（Claude Code v2.1.169+）——技能无法代替用户切换会话目录，因此要指示用户运行该命令。只有在旧版本中 /cd 报告 Unknown command 时，才使用 cd {name} && claude 重新启动。
• 发给用户 /cd {name} 的消息将是你在用户再次发言前的最后一轮（/cd 不会触发钩子），因此消息必须以恢复对话的提示结尾——例如：“进入后，只要说‘下一步是什么’。”绝不要承诺 /cd 后会话会连接组织或自行继续；会话会保持静默，直到用户再次参与。
• /cd 后，不要运行 sf-context detect 或 check-tools 来“显示”横幅——作为工具运行的 detect 会输出原始 JSON，而插件会自行显示横幅（每个会话显示一次；在方向性问题中显示旅程提示）。只需用一句话确认目录已切换并继续。需要时可通过 /salesforce-development:setup 检查健康状态。
• 沙盒登录时，必须使用 --instance-url https://test.salesforce.com（CLI 默认指向生产环境）。
• 绝不要存储或显示访问令牌。
• 项目名称由用户提供，并会传入 shell 命令。使用前要先用 ^[A-Za-z0-9][A-Za-z0-9_-]*$ 验证；任何不符合的名称都要拒绝并重新询问。每条命令中都要将名称写成 "{name}"（包括 cd {name} && claude 备用方案）。像 proj;rm -rf ~ 这样的名称绝不能未经验证就直接插入命令——验证是防护措施，加引号则是额外保障。
• 对于只需验证工具配置的现有项目，使用 platform-environment-validate（或 /salesforce-development:setup）；对于现有项目的组织身份验证，使用 /salesforce-development:login。
• 本技能负责所有模板的全新项目创建，包括 React/Angular——用户要求从零“创建新项目”并完成端到端设置（脚手架、切换目录、连接组织、启用跟踪）时都由本技能负责。不要把最初的脚手架搭建交给其他插件。由本技能搭建脚手架，但绝不要替用户运行 npm install；安装 UI bundle 依赖应由开发者明确决定（在结束消息中提供相关命令）。然后引导用户使用 experience-ui-bundle-* 技能来构建和部署 UI 应用。唯一的界限是：如果搭建 UI bundle 脚手架只是构建 UI bundle 应用的一个组合步骤（由 experience-ui-bundle-app-coordinate 驱动，且不需要完整的项目设置），则应由 experience-ui-bundle-project-generate 负责，而不是本技能——这两个技能的描述中会相互注明不要触发。构建或编辑现有 UI bundle 应用始终由它们负责；全新项目创建则由本技能负责。