主要技能定义（含 Frontmatter）、CLI 参考与 SOQL 模式

---
**名称：** salesforce
**描述：** 管理 Salesforce CRM - 查询记录，创建/更新联系人、客户、商机、潜在客户和案例。当用户询问 CRM 数据、销售管道、客户记录或 Salesforce 操作时使用。
**元数据：** {"moltbot":{"emoji":"☁️","requires":{"bins":["sf"],"env":["SALESFORCE_ACCESS_TOKEN"]},"primaryEnv":"SALESFORCE_ACCESS_TOKEN","install":[{"id":"npm","kind":"node","package":"@salesforce/cli","bins":["sf"],"label":"安装 Salesforce CLI (npm)"},{"id":"brew","kind":"brew","formula":"salesforce-cli","bins":["sf"],"label":"安装 Salesforce CLI (brew)"}]}}
**主页：** https://developer.salesforce.com/tools/salesforcecli
---

Salesforce CRM 技能

使用官方的 Salesforce CLI (sf) 和 REST API 与 Salesforce CRM 进行交互。

前提条件

1. Salesforce CLI (sf) 已通过 npm 或 Homebrew 安装。
2. 身份验证 已通过以下方式之一配置：
   • sf org login web (OAuth 浏览器流程 - 推荐用于交互式操作)
   • sf org login jwt (JWT，用于无头/自动化操作)
   • SALESFORCE_ACCESS_TOKEN 环境变量 (直接使用访问令牌)

快速参考

身份验证与组织管理

# 登录到组织 (打开浏览器)
sf org login web --alias myorg

# 使用 JWT 登录 (无头模式)
sf org login jwt --client-id <consumer-key> --jwt-key-file <path-to-key> --username <user> --alias myorg

# 列出已连接的组织
sf org list

# 设置默认组织
sf config set target-org myorg

# 显示组织信息
sf org display --target-org myorg

查询记录 (SOQL)

# 查询联系人
sf data query --query "SELECT Id, Name, Email, Phone FROM Contact LIMIT 10" --target-org myorg

# 带 WHERE 子句查询
sf data query --query "SELECT Id, Name, Amount, StageName FROM Opportunity WHERE StageName = 'Prospecting'" --target-org myorg

# 按名称查询客户
sf data query --query "SELECT Id, Name, Industry, Website FROM Account WHERE Name LIKE '%Acme%'" --target-org myorg

# 导出为 CSV
sf data query --query "SELECT Id, Name, Email FROM Contact" --result-format csv > contacts.csv

# 导出为 JSON
sf data query --query "SELECT Id, Name FROM Account" --result-format json

创建记录

# 创建联系人
sf data create record --sobject Contact --values "FirstName='John' LastName='Doe' Email='john.doe@example.com'" --target-org myorg

# 创建客户
sf data create record --sobject Account --values "Name='Acme Corp' Industry='Technology' Website='https://acme.com'" --target-org myorg

# 创建商机
sf data create record --sobject Opportunity --values "Name='Big Deal' AccountId='001XXXXXXXXXXXXXXX' StageName='Prospecting' CloseDate='2025-06-30' Amount=50000" --target-org myorg

# 创建潜在客户
sf data create record --sobject Lead --values "FirstName='Jane' LastName='Smith' Company='NewCo' Email='jane@newco.com' Status='Open - Not Contacted'" --target-org myorg

# 创建案例
sf data create record --sobject Case --values "Subject='Support Request' Description='Customer needs help' Status='New' Priority='Medium'" --target-org myorg

更新记录

# 更新联系人
sf data update record --sobject Contact --record-id 003XXXXXXXXXXXXXXX --values "Phone='555-1234' Title='VP Sales'" --target-org myorg

# 更新商机阶段
sf data update record --sobject Opportunity --record-id 006XXXXXXXXXXXXXXX --values "StageName='Negotiation/Review' Amount=75000" --target-org myorg

# 更新客户
sf data update record --sobject Account --record-id 001XXXXXXXXXXXXXXX --values "Description='Key strategic account'" --target-org myorg

删除记录

# 删除记录
sf data delete record --sobject Contact --record-id 003XXXXXXXXXXXXXXX --target-org myorg

# 通过查询批量删除 (谨慎操作!)
sf data delete bulk --sobject Lead --file leads-to-delete.csv --target-org myorg

批量操作

# 从 CSV 批量插入
sf data import bulk --sobject Contact --file contacts.csv --target-org myorg

# 从 CSV 批量更新
sf data upsert bulk --sobject Account --file accounts.csv --external-id Id --target-org myorg

# 检查批量作业状态
sf data bulk status --job-id <job-id> --target-org myorg

架构与元数据

# 描述对象 (获取字段)
sf sobject describe --sobject Account --target-org myorg

# 列出所有对象
sf sobject list --target-org myorg

# 获取字段详情
sf sobject describe --sobject Opportunity --target-org myorg | jq '.fields[] | {name, type, label}'

常用 SOQL 模式

销售管道报告

SELECT StageName, COUNT(Id) NumDeals, SUM(Amount) TotalValue
FROM Opportunity
WHERE IsClosed = false
GROUP BY StageName

近期活动

SELECT Id, Subject, WhoId, WhatId, ActivityDate
FROM Task
WHERE OwnerId = '<user-id>'
AND ActivityDate >= LAST_N_DAYS:7
ORDER BY ActivityDate DESC

按客户查看联系人

SELECT Account.Name, Id, Name, Email, Title
FROM Contact
WHERE Account.Name = 'Acme Corp'

未结案例

SELECT Id, CaseNumber, Subject, Status, Priority, CreatedDate
FROM Case
WHERE IsClosed = false
ORDER BY Priority, CreatedDate

按状态查看潜在客户

SELECT Status, COUNT(Id) Total
FROM Lead
WHERE IsConverted = false
GROUP BY Status

REST API (替代方案)

对于 CLI 未涵盖的操作，可使用 REST API 配合 curl：

# 设置变量
INSTANCE_URL="https://yourorg.salesforce.com"
ACCESS_TOKEN="$SALESFORCE_ACCESS_TOKEN"

# 通过 REST 查询
curl -s "$INSTANCE_URL/services/data/v59.0/query?q=SELECT+Id,Name+FROM+Account+LIMIT+5" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

# 通过 REST 创建记录
curl -s "$INSTANCE_URL/services/data/v59.0/sobjects/Contact" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"FirstName":"Test","LastName":"User","Email":"test@example.com"}'

错误处理

• INVALID_SESSION_ID: 令牌已过期。使用 sf org login web 重新认证。
• MALFORMED_QUERY: 检查 SOQL 语法。字符串使用单引号。
• ENTITY_IS_DELETED: 记录已被删除。更新前请先查询确认。
• REQUIRED_FIELD_MISSING: 检查对象的架构以确认必填字段。

提示

1. 使用别名: 登录时设置 --alias，然后使用 --target-org alias。
2. JSON 输出: 添加 --json 标志以便程序化解析。
3. 试运行: 在批量操作上使用 --dry-run 标志进行预览。
4. 字段名称: 使用 API 名称 (例如 FirstName)，而非标签 (例如 "First Name")。
5. 日期格式: 日期使用 YYYY-MM-DD，日期时间使用 YYYY-MM-DDThh:mm:ssZ。

限制

• 批量操作有每日 API 限制 (因 Salesforce 版本而异)。
• 某些对象 (例如 ContentDocument) 有特殊的处理要求。
• 复杂查询可能触及调控器限制。