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 <alias>" 错误	组织别名不存在或未认证——使用 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/沙盒）上检测到本地和远程之间的冲突——手动解决冲突或使用 --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	完整的标志参考及使用模式