名称： salesforce
描述： "通过 Salesforce CLI (sf) 查询和管理 Salesforce CRM 数据。运行 SOQL/SOSL 查询、检查对象架构、创建/更新/删除记录、批量导入/导出、执行 Apex、部署元数据以及发起原始 REST API 调用。"
主页： https://developer.salesforce.com/tools/salesforcecli
元数据： {"clawdbot":{"emoji":"☁️","requires":{"bins":["sf"]},"install":[{"id":"npm","kind":"node","package":"@salesforce/cli","bins":["sf"],"label":"安装 Salesforce CLI (npm)"}]}}

Salesforce 技能

使用 Salesforce CLI (sf) 与 Salesforce 组织交互。使用前必须先完成身份验证。始终添加 --json 参数以获取结构化输出。

如果 sf 二进制文件不可用，可通过 npm (npm install -g @salesforce/cli) 安装，或从 https://developer.salesforce.com/tools/salesforcecli 下载。安装后，立即使用 sf org login web 进行身份验证以连接到 Salesforce 组织。

身份验证与组织管理

登录（打开浏览器）

sf org login web --alias my-org

其他登录方式：

# 基于 JWT 的登录（适用于 CI/自动化）
sf org login jwt --client-id <consumer-key> --jwt-key-file server.key --username user@example.com --alias my-org

# 使用现有访问令牌登录
sf org login access-token --instance-url https://mycompany.my.salesforce.com

# 通过 SFDX 授权 URL 登录（从文件读取）
sf org login sfdx-url --sfdx-url-file authUrl.txt --alias my-org

管理组织

# 列出所有已认证的组织
sf org list --json

# 显示默认组织的信息（访问令牌、实例 URL、用户名）
sf org display --json

# 显示特定组织的信息
sf org display --target-org my-org --json

# 显示包含 SFDX 授权 URL 的详细信息（敏感信息 - 包含刷新令牌）
sf org display --target-org my-org --verbose --json

# 在浏览器中打开组织
sf org open
sf org open --target-org my-org

# 登出
sf org logout --target-org my-org

配置与别名

# 设置默认目标组织
sf config set target-org my-org

# 列出所有配置变量
sf config list

# 获取特定配置值
sf config get target-org

# 设置别名
sf alias set prod=user@example.com

# 列出别名
sf alias list

数据查询 (SOQL)

通过默认 API 执行标准 SOQL 查询：

# 基础查询
sf data query --query "SELECT Id, Name, Email FROM Contact LIMIT 10" --json

# WHERE 子句
sf data query --query "SELECT Id, Name, Amount, StageName FROM Opportunity WHERE StageName = 'Closed Won'" --json

# 关系查询（父到子）
sf data query --query "SELECT Id, Name, (SELECT LastName, Email FROM Contacts) FROM Account LIMIT 5" --json

# 关系查询（子到父）
sf data query --query "SELECT Id, Name, Account.Name FROM Contact" --json

# LIKE 文本搜索
sf data query --query "SELECT Id, Name FROM Account WHERE Name LIKE '%Acme%'" --json

# 日期过滤
sf data query --query "SELECT Id, Name, CreatedDate FROM Lead WHERE CreatedDate = TODAY" --json

# ORDER BY + LIMIT
sf data query --query "SELECT Id, Name, Amount FROM Opportunity ORDER BY Amount DESC LIMIT 20" --json

# 包含已删除/归档的记录
sf data query --query "SELECT Id, Name FROM Account" --all-rows --json

# 从文件读取查询
sf data query --file query.soql --json

# Tooling API 查询（元数据对象，如 ApexClass、ApexTrigger）
sf data query --query "SELECT Id, Name, Status FROM ApexClass" --use-tooling-api --json

# 输出到 CSV 文件
sf data query --query "SELECT Id, Name, Email FROM Contact" --result-format csv --output-file contacts.csv

# 指定目标组织
sf data query --query "SELECT Id, Name FROM Account" --target-org my-org --json

对于返回超过 10,000 条记录的查询，请改用 Bulk API：

sf data export bulk --query "SELECT Id, Name, Email FROM Contact" --output-file contacts.csv --result-format csv --wait 10
sf data export bulk --query "SELECT Id, Name FROM Account" --output-file accounts.json --result-format json --wait 10

文本搜索 (SOSL)

SOSL 可跨多个对象同时搜索：

# 跨对象搜索文本
sf data search --query "FIND {John Smith} IN ALL FIELDS RETURNING Contact(Name, Email), Lead(Name, Email)" --json

# 仅在名称字段中搜索
sf data search --query "FIND {Acme} IN NAME FIELDS RETURNING Account(Name, Industry), Contact(Name)" --json

# 从文件读取搜索
sf data search --file search.sosl --json

# 输出到 CSV
sf data search --query "FIND {test} RETURNING Contact(Name)" --result-format csv

单记录操作

获取记录

# 通过记录 ID
sf data get record --sobject Contact --record-id 003XXXXXXXXXXXX --json

# 通过字段匹配（类似 WHERE）
sf data get record --sobject Account --where "Name=Acme" --json

# 通过多个字段（包含空格的字段值需用单引号）
sf data get record --sobject Account --where "Name='Universal Containers' Phone='(123) 456-7890'" --json

创建记录（需先向用户确认）

sf data create record --sobject Contact --values "FirstName='Jane' LastName='Doe' Email='jane@example.com'" --json

sf data create record --sobject Account --values "Name='New Company' Website=www.example.com Industry='Technology'" --json

# Tooling API 对象
sf data create record --sobject TraceFlag --use-tooling-api --values "DebugLevelId=7dl... LogType=CLASS_TRACING" --json

更新记录（需先向用户确认）

# 通过 ID
sf data update record --sobject Contact --record-id 003XXXXXXXXXXXX --values "Email='updated@example.com'" --json

# 通过字段匹配
sf data update record --sobject Account --where "Name='Old Acme'" --values "Name='New Acme'" --json

# 多个字段
sf data update record --sobject Account --record-id 001XXXXXXXXXXXX --values "Name='Acme III' Website=www.example.com" --json

删除记录（需用户明确确认）

# 通过 ID
sf data delete record --sobject Account --record-id 001XXXXXXXXXXXX --json

# 通过字段匹配
sf data delete record --sobject Account --where "Name=Acme" --json

批量数据操作 (Bulk API 2.0)

适用于大型数据集（数千到数百万条记录）：

批量导出

# 导出到 CSV
sf data export bulk --query "SELECT Id, Name, Email FROM Contact" --output-file contacts.csv --result-format csv --wait 10

# 导出到 JSON
sf data export bulk --query "SELECT Id, Name FROM Account" --output-file accounts.json --result-format json --wait 10

# 包含软删除的记录
sf data export bulk --query "SELECT Id, Name FROM Account" --output-file accounts.csv --result-format csv --all-rows --wait 10

# 恢复超时的导出作业
sf data export resume --job-id 750XXXXXXXXXXXX --json

批量导入

# 从 CSV 导入
sf data import bulk --file accounts.csv --sobject Account --wait 10

# 恢复超时的导入作业
sf data import resume --job-id 750XXXXXXXXXXXX --json

批量更新插入

sf data upsert bulk --file contacts.csv --sobject Contact --external-id Email --wait 10

批量删除

# 删除 CSV 中列出的记录（CSV 必须包含 Id 列）
sf data delete bulk --file records-to-delete.csv --sobject Contact --wait 10

树形导出/导入（用于关联记录）

# 将关联记录导出为 JSON 树形格式
sf data export tree --query "SELECT Id, Name, (SELECT Name, Email FROM Contacts) FROM Account" --json

# 使用计划文件导出（适用于多个对象）
sf data export tree --query "SELECT Id, Name FROM Account" --plan --output-dir export-data

# 从树形 JSON 文件导入
sf data import tree --files Account.json,Contact.json

# 使用计划定义文件导入
sf data import tree --plan Account-Contact-plan.json

架构检查

# 描述对象（字段、关系、选择列表值）
sf sobject describe --sobject Account --json

# 描述自定义对象
sf sobject describe --sobject MyCustomObject__c --json

# 描述 Tooling API 对象
sf sobject describe --sobject ApexClass --use-tooling-api --json

# 列出所有对象
sf sobject list --json

# 仅列出自定义对象
sf sobject list --sobject custom --json

# 仅列出标准对象
sf sobject list --sobject standard --json

执行 Apex 代码

# 从文件执行 Apex
sf apex run --file script.apex --json

# 交互式运行（输入代码，按 Ctrl+D 执行）
sf apex run

# 运行 Apex 测试
sf apex run test --test-names MyTestClass --json

# 获取测试结果
sf apex get test --test-run-id 707XXXXXXXXXXXX --json

# 查看 Apex 日志
sf apex list log --json
sf apex get log --log-id 07LXXXXXXXXXXXX

REST API（高级）

发起任意经过身份验证的 REST API 调用：

# GET 请求
sf api request rest 'services/data/v62.0/limits' --json

# 列出 API 版本
sf api request rest '/services/data/' --json

# 通过 REST 创建记录
sf api request rest '/services/data/v62.0/sobjects/Account' --method POST --body '{"Name":"REST Account","Industry":"Technology"}' --json

# 通过 REST 更新记录 (PATCH)
sf api request rest '/services/data/v62.0/sobjects/Account/001XXXXXXXXXXXX' --method PATCH --body '{"BillingCity":"San Francisco"}' --json

# GraphQL 查询
sf api request graphql --body '{"query":"{ uiapi { query { Account { edges { node { Name { value } } } } } } }"}' --json

# 自定义请求头
sf api request rest '/services/data/v62.0/limits' --header 'Accept: application/xml'

# 将响应保存到文件
sf api request rest '/services/data/v62.0/limits' --stream-to-file limits.json

元数据部署与检索

# 将元数据部署到组织
sf project deploy start --source-dir force-app --json

# 部署特定的元数据组件
sf project deploy start --metadata ApexClass:MyClass --json

# 从组织检索元数据
sf project retrieve start --metadata ApexClass --json

# 检查部署状态
sf project deploy report --job-id 0AfXXXXXXXXXXXX --json

# 生成新的 Salesforce DX 项目
sf project generate --name my-project

# 列出组织中的元数据组件
sf project list ignored --json

诊断

# 运行 CLI 诊断
sf doctor

# 检查 CLI 版本
sf version

# 查看新功能
sf whatsnew

常用 SOQL 模式

-- 记录计数
SELECT COUNT() FROM Contact WHERE AccountId = '001XXXXXXXXXXXX'

-- 聚合查询
SELECT StageName, COUNT(Id), SUM(Amount) FROM Opportunity GROUP BY StageName

-- 日期字面量
SELECT Id, Name FROM Lead WHERE CreatedDate = LAST_N_DAYS:30

-- 子查询（半连接）
SELECT Id, Name FROM Account WHERE Id IN (SELECT AccountId FROM Contact WHERE Email LIKE '%@acme.com')

-- 多态查找
SELECT Id, Who.Name, Who.Type FROM Task WHERE Who.Type = 'Contact'

-- 多个 WHERE 条件
SELECT Id, Name, Amount FROM Opportunity WHERE Amount > 10000 AND StageName != 'Closed Lost' AND CloseDate = THIS_QUARTER

操作准则

• 始终使用 --json 以获取结构化、可解析的输出。
• 切勿在未经用户明确确认的情况下创建、更新或删除记录。执行前需描述操作并征得同意。
• 切勿在未经用户明确请求并确认具体记录的情况下删除记录。
• 切勿在用户未审查文件/查询并确认的情况下进行批量删除或批量导入。
• 在查询中使用 LIMIT 以避免数据量过大。从 LIMIT 10 开始，如果用户需要更多数据再增加。
• 对于超过 10,000 条记录的查询，请使用 sf data export bulk 而非 sf data query。
• 当用户要求“查找”或“搜索”单个对象时，使用 SOQL WHERE ... LIKE '%term%'。当需要跨多个对象搜索时，使用 sf data search 执行 SOSL。
• 当用户有多个组织时，使用 --target-org <alias>；如果组织不明确，请询问用户。
• 如果身份验证失败或会话过期，引导用户执行 sf org login web。
• Bulk API 2.0 对 SOQL 有限制（不支持 COUNT() 等聚合函数）。对于此类查询，请使用标准的 sf data query。
• 描述对象 (sf sobject describe) 时，JSON 输出可能非常庞大。应向用户总结关键字段、必填字段和关系，而不是直接输出原始内容。