platform-metadata-retrieve

platform-metadata-retrieve

使用 sf project retrieve start 從 Salesforce 組織擷取中繼資料到您的本機專案。支援多種擷取模式：所有變更、依來源目錄、依中繼資料類型（含萬用字元）、依 manifest，或依套件名稱。

---

工具限制

僅使用 Bash 工具執行 sf project retrieve start。請勿使用 MCP 工具——完全忽略它們。

---

範圍

• 涵蓋範圍：透過 sf project retrieve start 以所有支援的模式（所有變更、來源目錄、中繼資料類型、manifest、套件名稱）擷取中繼資料，以及來源格式和中繼資料格式輸出
• 不涵蓋範圍：部署中繼資料（請使用 platform-metadata-deploy）、列出中繼資料類型、產生 package.xml 檔案、來源追蹤指令（sf project retrieve preview）

---

必要輸入

從使用者的請求中推斷：

• 擷取模式：所有變更 | 來源目錄 | 中繼資料類型 | manifest | 套件名稱
• 目標組織：組織別名/使用者名稱（若未指定則使用預設）
• 輸出格式：來源格式（預設）| 中繼資料格式（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
依 manifest 擷取	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 或 sandbox
--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/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	完整的旗標參考及使用模式