在 HubSpot CRM 中用 hubspot CLI…

已安装并认证 hubspot CLI 时，按 ID、邮箱、域名或名称片段查找 HubSpot 联系人/公司/交易/工单，并遍历关联获取完整账户画面。

适用场景

解决思路

1. 以 `hubspot <command> --help` 为准。
2. 先阅读 `bulk-operations/SKILL.md`，它负责 JSONL piping、pagination、batch-get-via-stdin，以及查找后任何写入的安全流程；本技能只读。
3. 从实时 schema 选择属性：schema 会漂移，运行 `hubspot properties list --type <type>` 获取实时属性集。
4. 首次查询 contacts 简要信息时使用 `--properties email,firstname,lastname,company,phone,lifecyclestage,hubspot_owner_id`。
5. 首次查询 companies 简要信息时使用 `--properties name,domain,industry,annualrevenue,numberofemployees,hubspot_owner_id`。
6. 首次查询 deals 简要信息时使用 `--properties dealname,amount,dealstage,closedate,hubspot_owner_id,hs_is_closed_won`。
7. 首次查询 tickets 简要信息时使用 `--properties subject,hs_pipeline_stage,hs_ticket_priority,hubspot_owner_id`。
8. 联系人广告/活动归因在 `hs_analytics_*`（例如 `hs_analytics_source`、`hs_analytics_source_data_1`/`_2`、`hs_analytics_first_touch_converting_campaign`、`hs_analytics_last_touch_converting_campaign`）；完整列表用 `hubspot properties list --type contacts | grep hs_analytics_`。
9. 按 ID 查找：一次批量调用最多约 100 个 ID：`hubspot objects get --type contacts 12345 67890 23456 --properties email,firstname,lastname,company,phone,lifecyclestage`。
10. 按 email/domain 精确查找：`email`/`domain` 是精确匹配，规范化为小写；多个 `--filter` 标志之间是 OR。
11. 按 email 精确查找联系人：`hubspot objects search --type contacts --filter "email=jane@acme.com" --properties email,firstname,lastname,company,lifecyclestage,hubspot_owner_id`。
12. 按 domain 精确查找公司：`hubspot objects search --type companies --filter "domain=acme.com" --properties name,domain,industry,annualrevenue,hubspot_owner_id`。
13. 一次查找多个 email（OR）：`hubspot objects search --type contacts --filter "email=alice@acme.com" --filter "email=bob@acme.com" --properties email,firstname`。
14. 按部分名称查找：`~` 是 CONTAINS_TOKEN，匹配整个按空格分隔的词；`dealname~acme` 能找到 "Acme Renewal" 但找不到 "AcmeCorp"；如需子字符串，管道到 `jq`；没有跨所有字段的全文搜索，必须选择属性。
15. 按部分名称查找交易并在客户端收窄：`hubspot objects search --type deals --filter "dealname~acme" --properties dealname,amount,dealstage | jq -c 'select(.properties.dealname | ascii_downcase | contains("acme corp"))'`。
16. 查找所有关联记录使用两次 CLI 调用，不要用 xargs：模式是 `associations list` → `jq -c '{id}'` → `objects get` batch；绝不要 `xargs -I{} hubspot objects get …`，那会为每条记录生成一个进程。
17. 在 `--from` 中使用复数（`contacts:`、`companies:`、`deals:`）；`--help` 显示单数，但只有复数能避免警告。
18. 查找某公司所有联系人：`hubspot associations list --from companies:67890 --to contacts | jq -c '{id}' | hubspot objects get --type contacts --properties email,firstname,lastname,jobtitle`。
19. 查找某联系人的 open deals（客户端过滤，因为 "open" 因 pipeline 而异）：`hubspot associations list --from contacts:12345 --to deals | jq -c '{id}' | hubspot objects get --type deals --properties dealname,amount,dealstage,hs_is_closed | jq -c 'select(.properties.hs_is_closed != "true")'`。
20. 获取一条记录及其关联：先取联系人，`contact_id=12345`，`hubspot objects get --type contacts $contact_id --properties email,firstname,lastname,company,lifecyclestage`。
21. 获取关联公司（通常一个）：`hubspot associations list --from contacts:$contact_id --to companies | jq -c '{id}' | head -1 | hubspot objects get --type companies --properties name,domain,industry,annualrevenue`。
22. 获取关联交易：`hubspot associations list --from contacts:$contact_id --to deals | jq -c '{id}' | hubspot objects get --type deals --properties dealname,amount,dealstage,closedate`。
23. Search 每页最多返回 100 条；需要更多时使用 `bulk-operations/SKILL.md` 中的分页循环。
24. `~` 基于 token；子字符串过滤在 search 之后用 `jq` 完成。
25. 如果查找结果要用于写入（update、delete、merge），遵循 `bulk-operations/SKILL.md` 中的 `--dry-run` → digest → `--confirm` 流程。

适用边界 · 注意事项

• 没有安装并认证 `hubspot` CLI，或没有 HubSpot CRM 访问权限时。
• 需要在所有字段做全文搜索时；本技能没有跨字段 full-text search，只能选择属性并在客户端用 `jq` 收窄。
• 执行写入（update、delete、merge）时；本技能只读，应转到 `bulk-operations/SKILL.md` 的安全流程。