mcpField
D
data-enrichment

data-enrichment

github.com/hubspot数据与数据库281.7k 次安装今天更新
代码仓库

关于 data-enrichment

data-enrichment 是一项使用 HubSpot CLI 按自然键创建或更新 CRM 记录的技能，涵盖数据整理、安全预览及逐条结果处理，适用于联系人和公司数据。

主要功能

  1. 01按键 Upsert 联系人和公司
  2. 02用 jq 转换 CSV 或 JSONL
  3. 03通过 dry-run 和 digest 预览写入
  4. 04分离成功与失败记录
  5. 05修正后重试失败行

适用场景

  1. 01按电子邮件导入联系人数据
  2. 02按域名补充公司记录
  3. 03检查并重试批次失败行

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hubspot/agent-cli-skills --skill data-enrichment

安装后在 Claude Code 中输入/data-enrichment确认已加载。

详细介绍

前置要求：先阅读 bulk-operations/SKILL.md——JSONL 管道传输、dry-run/digest、历史记录和速率限制规范都在其中。本技能介绍在此基础上的按自然键 upsert 工作流。

核心操作：upsert，而非先搜索再创建

hubspot objects upsert --type X --id-property <natural-key> 从 stdin 读取 JSONL，并在一次 CLI 调用中逐行创建或更新（CLI 每个 API 请求批处理 100 行），以某个属性作为键（联系人使用 email，公司使用 domain）。没有竞态窗口，也无需分支处理。不要循环执行 search → 是否为空？→ create。

每行输入：{"id":"[email protected]","properties":{"firstname":"Jane","jobtitle":"VP"}} 每行输出：{"id":"123","ok":true,"data":{...}} 或 {"ok":false,"error":{...}}。输出顺序与输入一致。CLI 不会自行添加字段——data 是批量 upsert API 返回的原始结果行。

CSV/JSONL → upsert 流

使用 jq 重塑数据，使用 --dry-run 预览，然后执行。upsert 不可撤销，因此执行步骤要重新管道传入相同的输入，以及从预览行中提取的 --digest/--confirm（upsert 的 confirm 始终等于行数）。自然键务必转换为小写——CRM 会进行精确匹配。使用 hubspot properties list --type contacts 确认可用的属性名称；切勿硬编码列表。重塑方法请参阅 bulk-operations/resources/json-patterns.md。

# CSV → JSONL (any tool); example using csvkit
csvjson external.csv | jq -c '.[]' > external.jsonl

# Preview
cat external.jsonl \
| jq -c '{id:(.email|ascii_downcase), properties:{firstname:.first, lastname:.last, jobtitle:.title, company:.company}}' \
| hubspot objects upsert --type contacts --id-property email --dry-run \
| tee /tmp/upsert.preview.jsonl

# Lift the digest + confirm (present at every row count; upsert confirm = the row count)
digest=$(jq -r 'select(.digest != null) | .digest' /tmp/upsert.preview.jsonl)
confirm=$(jq -r 'select(.digest != null) | .target.id' /tmp/upsert.preview.jsonl)

# Execute — same pipeline, plus --digest/--confirm, capture results
cat external.jsonl \
| jq -c '{id:(.email|ascii_downcase), properties:{firstname:.first, lastname:.last, jobtitle:.title, company:.company}}' \
| hubspot objects upsert --type contacts --id-property email --digest "$digest" --confirm "$confirm" \
| tee /tmp/upsert.results.jsonl

公司：将参数替换为 --type companies --id-property domain，并在重塑时使用 .domain|ascii_downcase 作为 id。

处理每条记录的成功 / 错误输出

使用 jq 拆分输出，检查失败原因；修正输入后，只重试失败的记录：

jq -c 'select(.ok==true)'  /tmp/upsert.results.jsonl > /tmp/upsert.ok.jsonl
jq -c 'select(.ok==false)' /tmp/upsert.results.jsonl > /tmp/upsert.failed.jsonl
jq -r '.error.status' /tmp/upsert.failed.jsonl | sort | uniq -c   # status → count

CLI 不会标记行是新建还是更新。如果批量 upsert API 结果行包含 new 布尔值，可运行 jq -r '.data.new' /tmp/upsert.ok.jsonl | sort | uniq -c 来区分；否则，请比较 .data.createdAt 和 .data.updatedAt。

429 错误：拆分输入，并用较小的块重新运行（参见 bulk-operations 中关于速率限制的说明）。400 错误通常表示属性名称错误或枚举值无效——修正重塑逻辑，然后重新运行失败的输入。

破坏性操作安全措施

upsert 本身不会造成破坏，但回写可能覆盖已填充的字段。务必先执行 --dry-run 并抽查。批量删除或覆盖现有数据时，请遵循 bulk-operations/SKILL.md 中的 dry-run → digest → confirm 流程。恢复方法：hubspot history --since 1h。

不使用 upsert 进行匹配：OR 搜索 → 更新

如果只想读取匹配项（不回写），或自然键不是 CRM 属性，请使用重复的 --filter 标志——每个标志对应一个 OR 组。

已验证的上限：每次调用最多 5 个 OR 组。6 个及以上会返回 400 too many filterGroups (count: N, max allowed: 5)。每次分成 5 个处理：

# emails.txt: one lowercased email per line
xargs -n5 < emails.txt | while read -r e1 e2 e3 e4 e5; do
  args=()
  for e in "$e1" "$e2" "$e3" "$e4" "$e5"; do [ -n "$e" ] && args+=(--filter "email=$e"); done
  hubspot objects search --type contacts "${args[@]}" --properties email,firstname,company
done > /tmp/matches.jsonl

jq -c '{id, properties:{lifecyclestage:"marketingqualifiedlead"}}' /tmp/matches.jsonl \
| hubspot objects update --type contacts --dry-run

对于更大规模的按键丰富数据操作，优先使用 upsert——一条管道即可，无需计算分块方式。

评论

支持 Markdown