Back to Details

sf-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

sf-deploy: Comprehensive Salesforce DevOps Automation

sf-deploy：全面的Salesforce DevOps自动化方案

Expert Salesforce DevOps engineer specializing in deployment automation, CI/CD pipelines, and metadata management using Salesforce CLI (sf v2).
专业的Salesforce DevOps工程师，擅长使用Salesforce CLI（sf v2）实现部署自动化、CI/CD流水线搭建与元数据管理。

Core Responsibilities

核心职责

  1. Deployment Management: Execute, validate, and monitor deployments (metadata, Apex, LWC)
  2. DevOps Automation: CI/CD pipelines, automated testing, deployment workflows
  3. Org Management: Authentication, scratch orgs, environment management
  4. Quality Assurance: Tests, code coverage, pre-production validation
  5. Troubleshooting: Debug failures, analyze logs, provide solutions
  1. 部署管理：执行、验证并监控元数据、Apex、LWC的部署
  2. DevOps自动化：CI/CD流水线、自动化测试、部署工作流
  3. 组织管理：身份验证、临时组织（scratch orgs）、环境管理
  4. 质量保障：测试、代码覆盖率、预生产验证
  5. 故障排查：调试部署失败、分析日志并提供解决方案

⚠️ CRITICAL: Orchestration Order

⚠️ 重要提示：编排顺序

┌─────────────────────────────────────────────────────────────────────────────┐
│  sf-metadata → sf-flow → sf-deploy → sf-data                               │
│                              ▲                                              │
│                         YOU ARE HERE                                        │
└─────────────────────────────────────────────────────────────────────────────┘
Deploy order WITHIN sf-deploy: Objects/Fields → Permission Sets → Apex → Flows (Draft) → Activate Flows
PhaseMetadata TypeWhy This Order
1Custom Objects/FieldsEverything references these
2Permission SetsFLS requires fields to exist
3Apex Classes@InvocableMethod needed before Flows
4Flows (as Draft)Flows reference fields and Apex
5Activate FlowsSafe to activate after validation
See 
docs/orchestration.md
for detailed deployment workflows and agent deployment patterns.
┌─────────────────────────────────────────────────────────────────────────────┐
│  sf-metadata → sf-flow → sf-deploy → sf-data                               │
│                              ▲                                              │
│                         当前位置                                        │
└─────────────────────────────────────────────────────────────────────────────┘
sf-deploy内部的部署顺序：对象/字段 → 权限集 → Apex → 流程（草稿状态） → 激活流程
阶段元数据类型顺序原因
1自定义对象/字段所有组件都依赖这些基础元素
2权限集字段级安全（FLS）要求字段已存在
3Apex类流程需要先部署包含@InvocableMethod的Apex类
4流程（草稿状态）流程会引用字段和Apex类
5激活流程验证通过后再激活更安全
详细部署工作流与Agent部署模式请查看
docs/orchestration.md
。

🔑 Key Insights for Deployment

🔑 部署关键要点

Always Use --dry-run First

始终先使用--dry-run进行验证

bash
undefined
bash
undefined

CORRECT: Validate before deploying

正确操作：先验证再部署

sf project deploy start --dry-run --source-dir force-app --target-org alias sf project deploy start --source-dir force-app --target-org alias
sf project deploy start --dry-run --source-dir force-app --target-org alias sf project deploy start --source-dir force-app --target-org alias

WRONG: Deploying without validation

错误操作：直接部署不验证

sf project deploy start --source-dir force-app --target-org alias # Risky!
undefined
sf project deploy start --source-dir force-app --target-org alias # 存在风险！
undefined

Deploy Permission Sets After Objects

权限集需在对象部署后再部署

Common Error:
Error: In field: field - no CustomObject named ObjectName__c found
Solution: Deploy objects first, THEN permission sets referencing them.
常见错误：
Error: In field: field - no CustomObject named ObjectName__c found
解决方案：先部署对象，再部署引用该对象的权限集。

Flow Activation (4-Step Process)

流程激活（四步流程）

Flows deploy as Draft by default. Activation steps:
  1. Deploy with 
    <status>Draft</status>
  2. Verify: 
    sf project deploy report --job-id [id]
  3. Edit XML: 
    Draft
    → 
    Active
  4. Redeploy
Why? Draft lets you verify before activating; if activation fails, flow still exists.
Common Errors: "Flow is invalid" (deploy objects first) | "Insufficient permissions" (check Manage Flow) | "Version conflict" (deactivate old version)
流程默认以草稿状态部署，激活步骤如下：
  1. 以
    <status>Draft</status>
    状态部署流程
  2. 验证部署状态：
    sf project deploy report --job-id [id]
  3. 编辑XML：将
    Draft
    改为
    Active
  4. 重新部署
原因：草稿状态可在激活前验证流程；若激活失败，流程仍会保留。
常见错误："Flow is invalid"（需先部署对象）| "Insufficient permissions"（检查Manage Flow权限）| "Version conflict"（先停用旧版本）

FLS Warning After Deployment

部署后的FLS警告

⚠️ Deployed fields may be INVISIBLE without FLS!
After deploying custom objects/fields:
  1. Deploy Permission Set granting field access
  2. Assign Permission Set to user: 
    sf org assign permset --name PermSetName --target-org alias
  3. Verify field visibility
⚠️ 部署的字段可能因FLS设置不可见！
部署自定义对象/字段后：
  1. 部署包含字段访问权限的权限集
  2. 为用户分配权限集：
    sf org assign permset --name PermSetName --target-org alias
  3. 验证字段可见性

CLI Version (CRITICAL)

CLI版本（重要）

This skill uses 
sf
CLI (v2.x), NOT legacy 
sfdx
(v1.x)
Legacy sfdx (v1)Modern sf (v2)
--checkonly
/ 
--check-only
--dry-run
sfdx force:source:deploy
sf project deploy start
本技能使用
sf
CLI（v2.x），而非旧版
sfdx
（v1.x）
旧版sfdx（v1）新版sf（v2）
--checkonly
/ 
--check-only
--dry-run
sfdx force:source:deploy
sf project deploy start

Prerequisites

前置条件

Before deployment, verify:
bash
sf --version              # Requires v2.x
sf org list               # Check authenticated orgs
test -f sfdx-project.json # Valid SFDX project
部署前请验证以下内容：
bash
sf --version              # 需为v2.x版本
sf org list               # 检查已认证的组织
test -f sfdx-project.json # 验证是否为有效的SFDX项目

Deployment Workflow (5-Phase)

部署工作流（五阶段）

Phase 1: Pre-Deployment Analysis

阶段1：部署前分析

Gather via AskUserQuestion: Target org, deployment scope, validation requirements, rollback strategy.
Analyze:
  • Read 
    sfdx-project.json
    for package directories
  • Glob for metadata: 
    **/force-app/**/*.{cls,trigger,xml,js,html,css}
  • Grep for dependencies
TodoWrite tasks: Validate auth, Pre-tests, Deploy, Monitor, Post-tests, Verify
通过询问用户收集信息：目标组织、部署范围、验证要求、回滚策略。
分析内容：
  • 读取
    sfdx-project.json
    获取包目录
  • 匹配元数据：
    **/force-app/**/*.{cls,trigger,xml,js,html,css}
  • 排查依赖关系
待办任务：验证身份、预测试、部署、监控、后测试、验证

Phase 2: Pre-Deployment Validation

阶段2：部署前验证

bash
sf org display --target-org <alias>                    # Check connection
sf apex test run --test-level RunLocalTests --target-org <alias> --wait 10  # Local tests
sf project deploy start --dry-run --test-level RunLocalTests --target-org <alias> --wait 30  # Validate
bash
sf org display --target-org <alias>                    # 检查连接状态
sf apex test run --test-level RunLocalTests --target-org <alias> --wait 10  # 运行本地测试
sf project deploy start --dry-run --test-level RunLocalTests --target-org <alias> --wait 30  # 执行验证

Phase 3: Deployment Execution

阶段3：执行部署

Commands by scope:
bash
undefined
按范围分类的命令：
bash
undefined

Full metadata

全量元数据部署

sf project deploy start --target-org <alias> --wait 30
sf project deploy start --target-org <alias> --wait 30

Specific components

特定组件部署

sf project deploy start --source-dir force-app/main/default/classes --target-org <alias>
sf project deploy start --source-dir force-app/main/default/classes --target-org <alias>

Manifest-based

基于清单的部署

sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30

Quick deploy (after validation)

快速部署（需先完成验证）

sf project deploy quick --job-id <validation-job-id> --target-org <alias>

Handle failures: Parse errors, identify failed components, suggest fixes.
sf project deploy quick --job-id <validation-job-id> --target-org <alias>

处理部署失败：解析错误信息、定位失败组件、提供修复建议。

Phase 4: Post-Deployment Verification

阶段4：部署后验证

bash
sf project deploy report --job-id <job-id> --target-org <alias>
Verify components, run smoke tests, check coverage.
bash
sf project deploy report --job-id <job-id> --target-org <alias>
验证组件状态、运行冒烟测试、检查代码覆盖率。

Phase 5: Documentation

阶段5：文档记录

Provide summary with: deployed components, test results, coverage metrics, next steps.
See examples/deployment-report-template.md for output format.
Deployment Variants: Production (full + RunAllTests), Hotfix (targeted + RunLocalTests), CI/CD (scripted + gates), Scratch (push source).
[Beta] 
--test-level RunRelevantTests
— Runs only tests relevant to changed components (Spring '26 / API v66.0 only). Not GA; use 
RunLocalTests
for production deploys.
提供部署总结，包含：已部署组件、测试结果、覆盖率指标、下一步操作建议。
输出格式示例请查看examples/deployment-report-template.md。
部署变体：生产环境（全量+RunAllTests）、热修复（定向+RunLocalTests）、CI/CD（脚本化+关卡）、临时组织（推送源码）。
[Beta版] 
--test-level RunRelevantTests
— 仅运行与变更组件相关的测试（仅Spring '26 / API v66.0+支持）。生产部署请使用
RunLocalTests
。

CLI Reference

CLI参考

Deploy: 
sf project deploy start [--dry-run] [--source-dir <path>] [--manifest <xml>] [--test-level <level>]
Quick: 
sf project deploy quick --job-id <id>
| Status: 
sf project deploy report
Test: 
sf apex test run --test-level RunLocalTests
| Coverage: 
sf apex get test --code-coverage
Org: 
sf org list
| 
sf org display
| 
sf org create scratch [--snapshot <name>]
| 
sf org open
Metadata: 
sf project retrieve start
| 
sf org list metadata --metadata-type <type>
Debug: 
sf project deploy start --dev-debug
— Show which files are ignored during deploy/retrieve (v2.117.7+)
部署：
sf project deploy start [--dry-run] [--source-dir <path>] [--manifest <xml>] [--test-level <level>]
快速部署：
sf project deploy quick --job-id <id>
| 状态查询：
sf project deploy report
测试：
sf apex test run --test-level RunLocalTests
| 覆盖率：
sf apex get test --code-coverage
组织管理：
sf org list
| 
sf org display
| 
sf org create scratch [--snapshot <name>]
| 
sf org open
元数据：
sf project retrieve start
| 
sf org list metadata --metadata-type <type>
调试：
sf project deploy start --dev-debug
— 显示部署/检索过程中被忽略的文件（v2.117.7+）

Error Handling

错误处理

ErrorCauseSolution
FIELD_CUSTOM_VALIDATION_EXCEPTIONValidation rule blockingDeactivate rules or use valid test data
INVALID_CROSS_REFERENCE_KEYMissing dependencyInclude dependencies in deploy
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITYTrigger/validation errorReview trigger logic, check recursion
TEST_FAILURETest class failureFix test or code under test
INSUFFICIENT_ACCESSPermission issueVerify user permissions, FLS
错误类型原因解决方案
FIELD_CUSTOM_VALIDATION_EXCEPTION验证规则阻止部署停用规则或使用合法测试数据
INVALID_CROSS_REFERENCE_KEY缺少依赖组件将依赖项包含在部署范围内
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY触发器/验证错误检查触发器逻辑、排查递归问题
TEST_FAILURE测试类执行失败修复测试类或被测试代码
INSUFFICIENT_ACCESS权限问题验证用户权限、字段级安全（FLS）

Flow-Specific Errors

流程专属错误

ErrorCauseSolution
"Element X is duplicated"Elements not alphabetically orderedReorder Flow XML elements
"Element bulkSupport invalid"Deprecated element (API 60.0+)Remove 
<bulkSupport>
"Error parsing file"Malformed XMLValidate XML syntax
错误类型原因解决方案
"Element X is duplicated"元素未按字母顺序排列重新排序Flow XML元素
"Element bulkSupport invalid"元素已废弃（API 60.0+）删除
<bulkSupport>
标签
"Error parsing file"XML格式错误验证XML语法

Failure Response

失败响应流程

  1. Parse error output, identify failed components
  2. Explain error in plain language
  3. Suggest specific fixes with code examples
  4. Provide rollback options if needed
  1. 解析错误输出，定位失败组件
  2. 用通俗语言解释错误原因
  3. 提供包含代码示例的具体修复方案
  4. 必要时提供回滚选项

Best Practices

最佳实践

  • Always validate first: Use 
    --dry-run
    for production
  • Appropriate test levels: RunLocalTests (deploy), RunAllTests (packages)
  • Code coverage: >75% for production, >90% recommended
  • Use manifests: 
    package.xml
    for controlled deployments
  • Version control: Commit before deploying, tag releases
  • Incremental deploys: Small, frequent changes over large batches
  • Sandbox first: Always test before production
  • Backup metadata: Retrieve before major deployments
  • Quick deploy: Use for validated changesets
  • 始终先验证：生产环境部署必须使用
    --dry-run
  • 选择合适的测试级别：RunLocalTests（普通部署）、RunAllTests（包部署）
  • 代码覆盖率：生产环境要求>75%，推荐>90%
  • 使用清单文件：通过
    package.xml
    实现可控部署
  • 版本控制：部署前提交代码、为版本打标签
  • 增量部署：优先小批量频繁变更，而非大规模一次性部署
  • 先在沙箱测试：生产部署前必须在沙箱验证
  • 备份元数据：重大部署前先导出元数据
  • 快速部署：已验证的变更集使用快速部署

Trigger Deployment Safety

触发器部署安全

💡 See 
docs/trigger-deployment-safety.md
for comprehensive guide.
💡 详细指南请查看
docs/trigger-deployment-safety.md
。

Pre-Deployment Guardrails

部署前防护措施

Before deploying triggers, verify:
CheckCommand/Action
Trigger chain analysisMap all triggers firing together
Cascade failure reviewIdentify atomic vs independent processes
Async decouplingUse Queueable/Events for external calls
Savepoint usageVerify explicit atomicity where needed
Test coverageInclude cascade success/failure tests
部署触发器前请验证以下内容：
检查项命令/操作
触发器链分析梳理所有联动触发的触发器
级联失败风险评估区分原子流程与独立流程
异步解耦外部调用使用Queueable/Events
Savepoint使用验证验证关键场景的显式原子性设置
测试覆盖率包含级联成功/失败场景的测试

Common Trigger Cascade Risks

常见触发器级联风险

RiskSymptomSolution
External callout in triggerCascade failure from HTTP timeoutMove to Queueable
Shared exception handlingOne failure rolls back allIsolate with try-catch or async
Recursive triggersStack overflow or DML errorsUse static flag recursion guard
Order-dependent triggersInconsistent behaviorDocument and test trigger order
风险症状解决方案
触发器中包含外部调用HTTP超时导致级联失败迁移至Queueable
共享异常处理逻辑单个失败导致全部回滚使用try-catch隔离或异步处理
递归触发器栈溢出或DML错误使用静态标志防止递归
触发器顺序依赖行为不一致记录并测试触发器执行顺序

Pre-Deployment Checklist

部署前检查清单

TRIGGER SAFETY CHECKLIST:
□ Identify all triggers in deployment
□ Map trigger chains (which triggers fire together)
□ Verify cascade behavior is intentional
□ Check for external callouts → should be async
□ Confirm savepoint usage for atomic operations
□ Test both success and failure cascade scenarios
□ Validate with --dry-run before production deploy
触发器安全检查清单：
□ 识别部署中的所有触发器
□ 梳理触发器联动关系（哪些触发器会同时触发）
□ 验证级联行为是否符合预期
□ 检查外部调用是否已异步化
□ 确认关键操作的Savepoint使用
□ 测试级联成功与失败场景
□ 生产部署前用--dry-run验证

Recommended Async Patterns

推荐的异步模式

apex
// BAD: Synchronous external call in trigger
trigger AccountTrigger on Account (after insert) {
    ExternalService.sync(Trigger.new);  // Failure cascades
}

// GOOD: Async decoupling
trigger AccountTrigger on Account (after insert) {
    if (canEnqueueJob()) {
        System.enqueueJob(new AccountSyncQueueable(Trigger.newMap.keySet()));
    }
}
apex
// 错误示例：触发器中同步调用外部服务
trigger AccountTrigger on Account (after insert) {
    ExternalService.sync(Trigger.new);  // 失败会导致级联回滚
}

// 正确示例：异步解耦
trigger AccountTrigger on Account (after insert) {
    if (canEnqueueJob()) {
        System.enqueueJob(new AccountSyncQueueable(Trigger.newMap.keySet()));
    }
}

CI/CD Integration

CI/CD集成

Standard pipeline workflow:
  1. Authenticate (JWT/auth URL)
  2. Validate metadata
  3. Static analysis (PMD, ESLint)
  4. Dry-run deployment
  5. Run tests + coverage check
  6. Deploy if validation passes
  7. Notify
See examples/deployment-workflows.md for scripts.
标准流水线工作流：
  1. 身份验证（JWT/认证URL）
  2. 元数据验证
  3. 静态分析（PMD、ESLint）
  4. 预部署验证（dry-run）
  5. 运行测试+覆盖率检查
  6. 验证通过后执行部署
  7. 发送通知
脚本示例请查看examples/deployment-workflows.md。

Edge Cases

边缘场景

  • Large deployments: Split into batches (limit: 10,000 files / 39 MB)
  • Test timeout: Increase wait time or run tests separately
  • Namespace conflicts: Handle managed package issues
  • API version: Ensure source/target compatibility
  • 大规模部署：拆分批次（限制：10000个文件 / 39 MB）
  • 测试超时：增加等待时间或单独运行测试
  • 命名空间冲突：处理托管包相关问题
  • API版本：确保源码与目标组织API版本兼容

Cross-Skill Dependency Checklist

跨技能依赖检查清单

Before deploying, verify these prerequisites from other skills:
DependencyCheck CommandRequired For
TAF Package
sf package installed list --target-org alias
TAF trigger pattern (sf-apex)
Custom Objects/Fields
sf sobject describe --sobject ObjectName --target-org alias
Apex/Flow field references
Trigger_Action__mdtCheck Setup → Custom Metadata TypesTAF trigger execution
Queues
sf data query --query "SELECT Id,Name FROM Group WHERE Type='Queue'"
Flow queue assignments
Permission Sets
sf org list metadata --metadata-type PermissionSet
FLS for custom fields
Common Cross-Skill Issues:
Error MessageMissing DependencySolution
Invalid type: MetadataTriggerHandler
TAF PackageInstall apex-trigger-actions package
Field does not exist: Field__c
Custom Field or FLSDeploy field or create Permission Set
No such column 'Field__c'
Field-Level SecurityAssign Permission Set to running user
SObject type 'Object__c' not supported
Custom ObjectDeploy object via sf-metadata first
Queue 'QueueName' not found
Queue MetadataDeploy queue via sf-metadata first
部署前请验证其他技能提供的前置条件：
依赖项检查命令/操作用途
TAF包
sf package installed list --target-org alias
TAF触发器模式（sf-apex）
自定义对象/字段
sf sobject describe --sobject ObjectName --target-org alias
Apex/流程字段引用
Trigger_Action__mdt检查设置 → 自定义元数据类型TAF触发器执行
队列
sf data query --query "SELECT Id,Name FROM Group WHERE Type='Queue'"
流程队列分配
权限集
sf org list metadata --metadata-type PermissionSet
自定义字段的FLS设置
常见跨技能问题：
错误信息缺失依赖解决方案
Invalid type: MetadataTriggerHandler
TAF包安装apex-trigger-actions包
Field does not exist: Field__c
自定义字段或FLS部署字段或创建权限集
No such column 'Field__c'
字段级安全为运行用户分配权限集
SObject type 'Object__c' not supported
自定义对象先通过sf-metadata部署对象
Queue 'QueueName' not found
队列元数据先通过sf-metadata部署队列

sf-ai-agentscript Integration (Agent DevOps)

sf-ai-agentscript集成（Agent DevOps）

Complete DevOps guide: See 
docs/agent-deployment-guide.md
for comprehensive agent deployment documentation.
完整DevOps指南：Agent部署详细文档请查看
docs/agent-deployment-guide.md
。

Agent Metadata Types

Agent元数据类型

Metadata TypeDescription
Bot
Top-level chatbot definition
BotVersion
Version configuration
GenAiPlannerBundle
Reasoning engine (LLM config)
GenAiPlugin
Topic definition
GenAiFunction
Action definition
元数据类型描述
Bot
顶级聊天机器人定义
BotVersion
版本配置
GenAiPlannerBundle
推理引擎（LLM配置）
GenAiPlugin
主题定义
GenAiFunction
动作定义

Agent Pseudo Metadata Type

Agent伪元数据类型

The 
Agent
pseudo type syncs all agent components at once:
bash
undefined
Agent
伪类型可同步所有Agent组件：
bash
undefined

Retrieve agent + all dependencies from org

从组织中获取Agent及所有依赖项

sf project retrieve start --metadata Agent:[AgentName] --target-org [alias]
sf project retrieve start --metadata Agent:[AgentName] --target-org [alias]

Deploy agent metadata to org

将Agent元数据部署到组织

sf project deploy start --metadata Agent:[AgentName] --target-org [alias]
undefined
sf project deploy start --metadata Agent:[AgentName] --target-org [alias]
undefined

Agent Lifecycle Commands

Agent生命周期命令

bash
undefined
bash
undefined

Activate agent (makes available to users)

激活Agent（对用户可见）

sf agent activate --api-name [AgentName] --target-org [alias]
sf agent activate --api-name [AgentName] --target-org [alias]

Deactivate agent (REQUIRED before making changes)

停用Agent（修改前必须执行）

sf agent deactivate --api-name [AgentName] --target-org [alias]
sf agent deactivate --api-name [AgentName] --target-org [alias]

Preview agent (simulated mode - safe testing)

预览Agent（模拟模式 - 安全测试）

sf agent preview --api-name [AgentName] --target-org [alias]
sf agent preview --api-name [AgentName] --target-org [alias]

Preview agent (live mode - real Apex/Flows)

预览Agent（实时模式 - 调用真实Apex/流程）

sf agent preview --api-name [AgentName] --use-live-actions --target-org [alias]
sf agent preview --api-name [AgentName] --use-live-actions --target-org [alias]

Validate Agent Script syntax

验证Agent Script语法

sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias]
undefined
sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias]
undefined

Full Agent Deployment Workflow

完整Agent部署工作流

bash
undefined
bash
undefined

1. Deploy Apex classes (if any)

1. 部署Apex类（如有）

sf project deploy start --metadata ApexClass --target-org [alias]
sf project deploy start --metadata ApexClass --target-org [alias]

2. Deploy Flows

2. 部署流程

sf project deploy start --metadata Flow --target-org [alias]
sf project deploy start --metadata Flow --target-org [alias]

3. Validate Agent Script

3. 验证Agent Script

sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias]
sf agent validate authoring-bundle --api-name [AgentName] --target-org [alias]

4. Publish agent

4. 发布Agent

sf agent publish authoring-bundle --api-name [AgentName] --target-org [alias]
sf agent publish authoring-bundle --api-name [AgentName] --target-org [alias]

5. Preview (simulated mode)

5. 预览（模拟模式）

sf agent preview --api-name [AgentName] --target-org [alias]
sf agent preview --api-name [AgentName] --target-org [alias]

6. Activate

6. 激活Agent

sf agent activate --api-name [AgentName] --target-org [alias]
undefined
sf agent activate --api-name [AgentName] --target-org [alias]
undefined

Modifying Existing Agents

修改现有Agent

⚠️ Deactivation Required: You MUST deactivate an agent before modifying topics, actions, or system instructions.
bash
undefined
⚠️ 必须先停用：修改主题、动作或系统指令前，必须先停用Agent。
bash
undefined

1. Deactivate

1. 停用Agent

sf agent deactivate --api-name [AgentName] --target-org [alias]
sf agent deactivate --api-name [AgentName] --target-org [alias]

2. Make changes to Agent Script

2. 修改Agent Script

3. Re-publish

3. 重新发布

sf agent publish authoring-bundle --api-name [AgentName] --target-org [alias]
sf agent publish authoring-bundle --api-name [AgentName] --target-org [alias]

4. Re-activate

4. 重新激活

sf agent activate --api-name [AgentName] --target-org [alias]
undefined
sf agent activate --api-name [AgentName] --target-org [alias]
undefined

Sync Agent Between Orgs

跨组织同步Agent

bash
undefined
bash
undefined

1. Retrieve from source org

1. 从源组织获取Agent

sf project retrieve start --metadata Agent:[AgentName] --target-org source-org
sf project retrieve start --metadata Agent:[AgentName] --target-org source-org

2. Deploy dependencies to target org first

2. 先将依赖项部署到目标组织

sf project deploy start --metadata ApexClass,Flow --target-org target-org
sf project deploy start --metadata ApexClass,Flow --target-org target-org

3. Deploy agent metadata

3. 部署Agent元数据到目标组织

sf project deploy start --metadata Agent:[AgentName] --target-org target-org
sf project deploy start --metadata Agent:[AgentName] --target-org target-org

4. Publish agent in target org

4. 在目标组织发布Agent

sf agent publish authoring-bundle --api-name [AgentName] --target-org target-org
sf agent publish authoring-bundle --api-name [AgentName] --target-org target-org

5. Activate in target org

5. 在目标组织激活Agent

sf agent activate --api-name [AgentName] --target-org target-org
undefined
sf agent activate --api-name [AgentName] --target-org target-org
undefined

Agent-Specific CLI Reference

Agent专属CLI参考

CommandDescription
sf agent publish authoring-bundle --api-name X
Publish authoring bundle
sf agent publish authoring-bundle --api-name X --skip-retrieve
Publish without retrieving metadata (CI/CD)
sf agent activate --api-name X
Activate published agent
sf agent deactivate --api-name X
Deactivate agent for changes
sf agent preview --api-name X
Preview agent behavior
sf agent validate authoring-bundle --api-name X
Validate Agent Script syntax
sf org open agent --api-name X
Open in Agentforce Builder
sf org open authoring-bundle
Open Agentforce Studio list view (v2.121.7+)
sf agent generate authoring-bundle --api-name X
Generate authoring bundle scaffolding
sf agent generate authoring-bundle --api-name X --skip-retrieve
Generate without retrieving from org
sf project retrieve start --metadata Agent:X
Retrieve agent + components
sf project deploy start --metadata Agent:X
Deploy agent metadata
命令描述
sf agent publish authoring-bundle --api-name X
发布创作包
sf agent publish authoring-bundle --api-name X --skip-retrieve
不获取元数据直接发布（CI/CD场景）
sf agent activate --api-name X
激活已发布的Agent
sf agent deactivate --api-name X
停用Agent以进行修改
sf agent preview --api-name X
预览Agent行为
sf agent validate authoring-bundle --api-name X
验证Agent Script语法
sf org open agent --api-name X
在Agentforce Builder中打开
sf org open authoring-bundle
打开Agentforce Studio列表视图（v2.121.7+）
sf agent generate authoring-bundle --api-name X
生成创作包脚手架
sf agent generate authoring-bundle --api-name X --skip-retrieve
不从组织获取元数据直接生成
sf project retrieve start --metadata Agent:X
获取Agent及关联组件
sf project deploy start --metadata Agent:X
部署Agent元数据

Package Management (2GP)

包管理（2GP）

CommandDescription
sf package convert --package <1GP-id>
Convert 1GP to 2GP package (GA, v2.92.7+)
sf package push-upgrade schedule
Schedule push upgrade
sf package push-upgrade abort --package-push-request-id <id>
Abort scheduled push
sf package push-upgrade list
List push upgrade requests
sf package push-upgrade report --package-push-request-id <id>
Get push upgrade status
sf package version retrieve --package <package-id> --output-dir <dir>
Retrieve 2GP package metadata (GA, v2.111.7+)
命令描述
sf package convert --package <1GP-id>
将1GP转换为2GP包（正式版，v2.92.7+）
sf package push-upgrade schedule
安排推送升级
sf package push-upgrade abort --package-push-request-id <id>
取消已安排的推送升级
sf package push-upgrade list
列出推送升级请求
sf package push-upgrade report --package-push-request-id <id>
获取推送升级状态
sf package version retrieve --package <package-id> --output-dir <dir>
获取2GP包元数据（正式版，v2.111.7+）

Deployment Script Template

部署脚本模板

Reusable multi-step deployment script: examples/deploy.sh
Deploys in order: Objects → Permission Sets → Apex (with tests) → Flows (Draft)
可复用的多阶段部署脚本：examples/deploy.sh
按以下顺序部署：对象 → 权限集 → Apex（含测试） → 流程（草稿状态）

Generate Package Manifest

生成包清单

Auto-generate package.xml from source directory:
bash
undefined
从源码目录自动生成package.xml：
bash
undefined

Generate from source

从源码生成

sf project generate manifest --source-dir force-app --name manifest/package.xml
sf project generate manifest --source-dir force-app --name manifest/package.xml

Generate for specific metadata types

为特定元数据类型生成

sf project generate manifest
--metadata CustomObject:Account
--metadata ApexClass
--metadata Flow
--name manifest/package.xml
sf project generate manifest
--metadata CustomObject:Account
--metadata ApexClass
--metadata Flow
--name manifest/package.xml

Deploy using manifest

使用清单部署

sf project deploy start --manifest manifest/package.xml --target-org alias

**When to use manifest vs source-dir:**

| Scenario | Use | Command |
|----------|-----|---------|
| Deploy everything | `--source-dir` | `sf project deploy start --source-dir force-app` |
| Deploy specific components | `--manifest` | `sf project deploy start --manifest package.xml` |
| CI/CD pipelines | `--manifest` | Controlled, reproducible deployments |
| Development iteration | `--source-dir` | Quick local changes |

---
sf project deploy start --manifest manifest/package.xml --target-org alias

**何时使用manifest vs source-dir**：

| 场景 | 选择 | 命令 |
|----------|-----|---------|
| 部署全部内容 | `--source-dir` | `sf project deploy start --source-dir force-app` |
| 部署特定组件 | `--manifest` | `sf project deploy start --manifest package.xml` |
| CI/CD流水线 | `--manifest` | 可控、可重复的部署 |
| 开发迭代 | `--source-dir` | 快速部署本地变更 |

---

Notes

注意事项

  • CLI: Uses only 
    sf
    (v2) with modern flag syntax
  • Auth: Supports OAuth, JWT, Auth URL, web login
  • API: Uses Metadata API (not Tooling API)
  • Async: Use 
    --wait
    to monitor; most deploys are async
  • Limits: Be aware of Salesforce governor limits
  • CLI版本：仅使用
    sf
    （v2）及现代参数语法
  • 身份验证：支持OAuth、JWT、认证URL、网页登录
  • API使用：使用元数据API（而非工具API）
  • 异步处理：使用
    --wait
    参数监控部署；大部分部署为异步执行
  • 限制说明：注意Salesforce governor限制

License

许可证

MIT License. See LICENSE file. Copyright (c) 2024-2025 Jag Valaiyapathy
MIT许可证。详情请查看LICENSE文件。 版权所有 (c) 2024-2025 Jag Valaiyapathy