hubspot-search-companies

用途

该技能专门用于在 HubSpot CRM 中搜索公司记录。当用户需要查找特定公司时，可以通过名称或域名进行检索，快速获取公司的基本信息。

主要能力

• 按名称搜索：使用 --name 参数，支持部分匹配（CONTAINS_TOKEN 操作符）。
• 按域名搜索：使用 --domain 参数，同样支持部分匹配。
• 限制结果数量：通过 --limit 参数指定返回的最大结果数。
• JSON 输出：结果以 JSON 格式返回，包含公司总数和结果列表，每个结果包含公司 ID、属性（名称、域名、行业、城市等）以及 HubSpot 链接。
• 错误处理：针对常见错误（如 401 无效令牌、403 缺少权限、429 速率限制）提供相应的解决建议。

使用方式

预检查

在运行搜索之前，需要执行配置检查：

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_companies.py \
  --name "Acme" \
  --json

按域名搜索

python 00-system/skills/hubspot/hubspot-master/scripts/search_companies.py \
  --domain "acme.com" \
  --json

带限制的搜索

python 00-system/skills/hubspot/hubspot-master/scripts/search_companies.py \
  --name "Tech" \
  --limit 20 \
  --json

输出格式

{
  "total": 3,
  "results": [
    {
      "id": "6493611979",
      "properties": {
        "name": "Acme Corp",
        "domain": "acme.com",
        "industry": "Technology",
        "city": "San Francisco"
      },
      "url": "https://app.hubspot.com/..."
    }
  ]
}

显示格式

Found 3 companies matching "Acme":

1. Acme Corp
   Domain: acme.com
   Industry: Technology
   City: San Francisco
   ID: 6493611979

2. Acme Industries
   Domain: acmeindustries.com
   ...

适用场景

• 当用户说“搜索公司”、“查找公司”、“查询公司”或“搜索[公司名]”时。
• 需要快速获取 HubSpot 中公司记录的基本信息。
• 作为其他 HubSpot 操作（如创建公司、获取关联）的前置步骤。

限制

• 需要有效的 HubSpot 访问令牌和 crm.objects.companies.read 权限范围。
• 搜索基于部分匹配，可能返回多个结果。
• 受 HubSpot API 速率限制影响，遇到 429 错误需等待后重试。
• 该技能仅用于搜索，不包含创建或更新公司的功能。

相关技能

• hubspot-list-companies：列出所有公司。
• hubspot-create-company：如果未找到则创建公司。
• hubspot-get-associations：获取公司联系人。