用 HubSpot CLI 批量查找不完整记录、规范化字段…

当需要清理 CRM 联系人/公司/交易数据（补全缺失字段、统一字段值、合并重复记录、审计属性）时使用。

适用场景

解决思路

1. 先阅读 bulk-operations/SKILL.md，掌握 JSONL 管道、批量读取、分页以及 dry-run/digest/confirm 门控，这些适用于下面所有命令。
2. 不要猜测属性名，先用 `hubspot properties list --type contacts --format table` 列出属性；用 `hubspot properties list --type contacts | jq -c 'select(.type=="enumeration") | {name, label}'` 筛选枚举属性；对 companies、deals 或自定义类型（`hubspot objects types`）同理。
3. 查找不完整记录：`!name` 表示 NOT_HAS_PROPERTY（缺失或为空），裸 `name` 表示 HAS_PROPERTY；同一个 `--filter` 内用 `AND` 连接，多个 `--filter` 之间是 OR。例如 `hubspot objects search --type contacts --filter "!email" --properties firstname,lastname,company`、`--filter "!phone AND !mobilephone"`、`--filter "!hubspot_owner_id"`。结果超过 100 条时使用 bulk-operations 中的分页循环。
4. 规范化字段值：先 search，再用 `jq` 重塑，然后管道到 `update`；始终先加 `--dry-run`，超过 100 行时按 bulk-operations 升级到 digest/confirm；重塑模式参考 bulk-operations/resources/json-patterns.md。例如把多种拼写统一为规范值：`hubspot objects search --type contacts --filter "company~acme" | jq -c '{id, properties:{company:"Acme Corporation"}}' | hubspot objects update --type contacts --dry-run`；邮箱转小写：`hubspot objects search --type contacts --filter "email" --properties email | jq -c '{id, properties:{email: (.properties.email | ascii_downcase)}}' | hubspot objects update --type contacts --dry-run`。
5. 用 `hubspot objects merge` 去重：secondary 会被合并进 primary 并删除，不可逆，适用 dry-run/digest/confirm 门控。单对合并：`hubspot objects merge --type contacts --primary 149 --secondary 425 --dry-run`，执行时去掉 `--dry-run`（≤100 对）。批量合并：在 stdin 上管道传入 JSONL `{"primary":"...","secondary":"..."}`（省略 `--primary`/`--secondary`）。
6. 去重必须分页：`objects search` 每次最多 100 行，`jq -s` 会把单个流全部读入内存，直接对原始 search 运行会静默漏掉跨页的重复项。先用 bulk-operations/SKILL.md 的分页循环收集完整集合写入 `/tmp/contacts.jsonl`，再从文件去重：`jq -s -c 'group_by(.properties.email)[] | select(length > 1) | sort_by(.id | tonumber) | .[0].id as $p | .[1:][] | {primary: $p, secondary: .id}' /tmp/contacts.jsonl | hubspot objects merge --type contacts --dry-run | tee /tmp/merge-preview.jsonl`。超过 100 对时，从 `BulkData` 行提取 `digest` 和 `impact.records_affected`，用 `--digest`/`--confirm` 重新管道运行同一生产者。
7. 审计属性：`hubspot properties list`（以及 `get`、`batch-read`）每行输出 `{name, label, type, fieldType, groupName}`；CLI 目前不暴露枚举选项值，需从真实记录（`hubspot objects search ... --properties <enum>`）或 HubSpot UI 读取。按组统计属性数量：`hubspot properties list --type contacts | jq -rs 'group_by(.groupName) | map({group: .[0].groupName, count: length}) | .[]'`；列出所有枚举属性：`hubspot properties list --type contacts | jq -c 'select(.type=="enumeration") | {name, label, fieldType}'`；创建 DQ 标记属性：`hubspot properties create --type contacts --name dq_missing_phone --label "DQ: Missing Phone" --prop-type string --field-type text`，然后用第 2 节的规范化模式设置它。
8. 恢复：合并不可逆。任何合并后，用 `hubspot history --since 1h` 获取审计轨迹；如果方向错了，从 UI 的回收站恢复 secondary。

适用边界 · 注意事项

• 没有安装并认证 HubSpot CLI 时无法使用。
• 合并操作不可逆，未确认主/次记录方向前不要执行。
• 枚举选项值无法从 CLI 属性列表读取，需要真实记录或 HubSpot UI 才能获取。