hubspot-search-contacts

用途

hubspot-search-contacts 是一个专门用于在 HubSpot CRM 中搜索联系人的技能。当用户表达“search contacts”“find contact”“lookup contact”“search for [name]”等意图时，可加载该技能来执行联系人查找。

主要能力

按邮箱搜索联系人（精确匹配，使用 EQ 操作符）
按姓名搜索联系人（部分匹配，使用 CONTAINS_TOKEN 操作符）
按公司搜索联系人（部分匹配，使用 CONTAINS_TOKEN 操作符）
组合多个筛选条件，条件之间以 AND 逻辑组合
通过 --limit 参数限制返回结果数量
以 JSON 格式输出结果，包含总数、结果列表（含 id、properties、url）
提供便于阅读的展示格式，列出匹配联系人的姓名、邮箱、公司和 ID

使用方式

运行前需先执行配置检查：

python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json

如果 ai_action 不是 proceed_with_operation，则需按照 hubspot-connect 设置指南进行操作。

按邮箱搜索：

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --email "john@example.com" \
  --json

按姓名搜索：

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --name "John" \
  --json

按公司搜索：

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --company "Acme" \
  --json

组合搜索并限制数量：

python 00-system/skills/hubspot/hubspot-master/scripts/search_contacts.py \
  --name "John" \
  --company "Acme" \
  --limit 20 \
  --json

输出格式示例：

{
  "total": 5,
  "results": [
    {
      "id": "12345",
      "properties": {
        "email": "john@example.com",
        "firstname": "John",
        "lastname": "Doe",
        "company": "Acme Corp"
      },
      "url": "https://app.hubspot.com/..."
    }
  ]
}

展示格式示例：

Found 5 contacts matching "John":

1. John Doe
   Email: john@example.com
   Company: Acme Corp
   ID: 12345

2. Johnny Smith
   Email: johnny@corp.com
   Company: Tech Inc
   ID: 12346
   ...

搜索行为

姓名搜索使用 CONTAINS_TOKEN 操作符（部分匹配）
邮箱搜索使用 EQ 操作符（精确匹配）
公司搜索使用 CONTAINS_TOKEN 操作符（部分匹配）
多个筛选条件以 AND 逻辑组合

错误处理

401：令牌无效，需重新运行设置
403：缺少 crm.objects.contacts.read 权限范围
429：触发速率限制，需等待后重试

适用场景

适用于需要在 HubSpot CRM 中快速查找、定位联系人的场景，例如按邮箱确认联系人是否存在、按姓名或公司模糊查找相关联系人，以及为后续更新或创建操作做准备。

限制

该技能依赖 HubSpot 连接配置，运行前必须通过配置检查；需要具备 crm.objects.contacts.read 权限范围；可能受到 HubSpot API 速率限制影响。其他限制暂未提供。

技能介绍

用途