用途:维护 HubSpot CRM 数据质量,包括发现缺字段记录、批量规范化字段值、合并重复记录、审计自定义属性及枚举选项。使用前需先阅读 bulk-operations/SKILL.md,其 JSONL 管道、批量读取、分页与 dry-run/摘要/确认门控适用于以下所有命令。
主要能力与用法:
- 属性发现:不要猜测属性名,用 hubspot properties list --type contacts 列出,可配合 jq 筛选枚举类型;同样支持 companies、deals 及自定义类型。
- 查找不完整记录:!name 表示 NOT_HAS_PROPERTY(缺失或空),裸名称表示 HAS_PROPERTY;单个 --filter 内用 AND 连接,多个 --filter 之间为 OR。如 hubspot objects search --type contacts --filter "!email"。结果超过 100 条时需用 bulk-operations 的分页循环。
- 规范化字段值:搜索→用 jq 重塑→管道传入 update。update 不可逆,必须先 --dry-run,且任何行数都需走 dry-run→摘要→确认流程:先从预览 JSONL 中提取 digest 与 confirm(单条取记录 ID,批量取行数),再用相同输入加 --digest/--confirm 重新执行。
- 去重:hubspot objects merge 会把 secondary 合并进 primary 并删除 secondary,不可逆。单对用 --primary/--secondary,批量改用 stdin 管道 JSONL {"primary":"...","secondary":"..."}。必须分页收集完整数据后再去重,否则跨页重复会被遗漏。合并方向错误可从 UI 回收站恢复。
- 属性审计:properties list/get/batch-read 输出 name、label、type、fieldType、groupName、optionsDisplay;枚举选项值通过 properties options-list 查看,可用 options-create/update/delete 管理(delete 不可逆,需 digest/confirm,confirm 为选项值)。HubSpot 定义的只读选项属性会在调用 API 前拒绝增删改。
- 恢复:merge 后可用 hubspot history --since 1h 查看审计记录。
限制:搜索每次上限 100 行,jq -s 会一次性载入内存,直接对原始搜索结果去重会漏掉跨页重复;update 与 merge 均不可逆,必须遵守 dry-run 流程。其余细节暂未提供。