platform-metadata-retrieve

platform-metadata-retrieve

使用 sf project retrieve start 将 Salesforce 组织中的元数据检索到本地项目。支持多种检索模式：所有更改、按源目录、按元数据类型（支持通配符）、按清单或按包名称。

---

工具限制

仅使用 Bash 工具执行 sf project retrieve start。不要使用 MCP 工具——完全忽略它们。

---

范围

• 范围内：通过 sf project retrieve start 以所有支持的模式检索元数据（所有更改、源目录、元数据类型、清单、包名称），以及输出源格式和元数据格式
• 范围外：部署元数据（使用 platform-metadata-deploy）、列出元数据类型、生成 package.xml 文件、源跟踪命令（sf project retrieve preview）

---

必需输入

根据用户请求推断：

• 检索模式：所有更改 | 源目录 | 元数据类型 | 清单 | 包名称
• 目标组织：组织别名/用户名（未指定时使用默认值）
• 输出格式：源格式（默认） | 元数据格式（ZIP）
• 其他选项：忽略冲突、输出目录、等待时间、API 版本

---

工作流

1. 将用户请求与以下命令模式匹配
2. 通过 Bash 工具执行 sf project retrieve start，并使用适当的标志和 --json 标志
3. 返回结果，包括检索到的组件数量和文件路径

命令模式

用户意图	通过 Bash 工具执行
检索所有远程更改	sf project retrieve start --json
按源目录检索	sf project retrieve start --source-dir <path> --target-org <alias> --json
按元数据类型检索	sf project retrieve start --metadata <MetadataType:Name> --target-org <alias> --json
按带通配符的元数据类型检索	sf project retrieve start --metadata '<MetadataType:Pattern*>' --target-org <alias> --json
检索多种元数据类型	sf project retrieve start --metadata <Type1> --metadata <Type2> --target-org <alias> --json
按清单检索	sf project retrieve start --manifest <path/to/package.xml> --target-org <alias> --json
按包名称检索	sf project retrieve start --package-name <PackageName> --target-org <alias> --json
检索为元数据格式（ZIP）	sf project retrieve start --source-dir <path> --target-metadata-dir <output> --unzip --target-org <alias> --json
忽略冲突	sf project retrieve start --source-dir <path> --ignore-conflicts --target-org <alias> --json

---

规则 / 限制

限制	原因
始终使用 --json 标志	提供结构化输出，便于可靠解析和处理错误
必须在 Salesforce 项目内运行	命令要求仓库根目录下存在 sfdx-project.json
必须为通配符模式加引号	Shell 展开会破坏未加引号的通配符，例如 ApexClass:My*
不能将 --manifest 与 --metadata 或 --source-dir 混用	这些标志互斥——命令会报错
检索所有更改需要源跟踪	生产组织不支持源跟踪——必须使用其他检索模式
--ignore-conflicts 仅适用于可跟踪的组织	对生产组织无效；仅适用于 scratch 组织/沙盒
--output-dir 必须位于项目目录内	命令会验证输出路径是否位于项目边界内
--output-dir 不能与包目录匹配	如果目标与 sfdx-project.json 中的 packageDirectories 匹配，命令会失败
默认等待时间为 33 分钟	对于大型检索，使用 --wait 标志覆盖此设置
检索包仅供参考	检索到的包元数据不应添加到用于开发的源代码控制中
检索 CustomField 时会自动包含 CustomObject	检索 CustomField 时，CLI 会自动添加 CustomObject，以获取完整上下文

---

故障排除

问题	解决方法
"This command is required to run from within an SFDX project"	当前目录不是 Salesforce 项目目录 — 使用 cd 切换到包含 sfdx-project.json 的项目根目录
"No org found for " error	组织别名不存在或尚未通过身份验证 — 使用 sf org list 验证
"This org does not support source tracking"	生产组织不支持“检索所有更改”模式 — 改用 --source-dir、--metadata 或 --manifest
"ERROR running project retrieve start: Cannot mix --manifest with --metadata or --source-dir"	移除冲突的标志 — 仅使用一种检索模式
通配符模式未检索到任何内容	模式未加引号 — 使用单引号括起：'ApexClass:My*'
"The package directory path in sfdx-project.json does not exist"	输出目录与包目录冲突 — 使用其他路径
"Output directory must be inside the project"	--output-dir 路径位于项目边界之外 — 使用项目内的相对路径
检索超时	对于大型元数据集，使用 --wait 60 延长等待时间
检索到的文件覆盖了本地更改	使用 --output-dir 将内容检索到单独的位置，或先提交本地更改
出现包含冲突表的 SourceConflictError	在支持跟踪的组织（scratch/sandbox）中检测到本地与远程冲突 — 手动解决冲突，或使用 --ignore-conflicts 强制覆盖

---

输出预期

该命令会返回包含已检索组件详细信息的 JSON 输出。

响应结构请参阅 examples/success_output.json 和 examples/error_output.json。

---

跨技能集成

需求	委派给
将元数据部署到组织	platform-metadata-deploy 技能
预览检索操作但不执行	执行 sf project retrieve preview --target-org <alias> --json
列出可用的元数据类型	执行 sf org list metadata-types --target-org <alias> --json

---

参考文件索引

文件	阅读时机
examples/success_output.json	了解成功检索时的响应结构
examples/error_output.json	处理常见错误情况
references/retrieval_modes.md	详细了解所有检索模式及其适用场景
references/cli_flags.md	查看完整的标志参考及用法模式