hubspot-list-contacts

用途

hubspot-list-contacts 是一个专门用于从 HubSpot CRM 列出联系人的技能。当用户表达“list contacts”“show contacts”“get contacts”“hubspot contacts”等意图时，该技能会被加载，用于获取并展示 HubSpot 中的联系人数据。

主要能力

列出 HubSpot CRM 中的联系人，返回分页的联系人列表。
每个联系人包含 id、properties（如 email、firstname、lastname、phone、company）以及指向 HubSpot 记录页面的 url。
支持通过参数控制返回数量与分页。
输出为 JSON 格式，便于后续处理。
提供面向用户的展示格式，将结果整理为带编号的列表。

使用方式

预检查

运行前需执行配置检查：

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

如果 ai_action 不是 proceed_with_operation，则需按照 hubspot-connect 设置指南完成配置。

基本列出（默认 10 个联系人）

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

指定数量

python 00-system/skills/hubspot/hubspot-master/scripts/list_contacts.py --limit 25 --json

分页（使用游标）

python 00-system/skills/hubspot/hubspot-master/scripts/list_contacts.py --after "cursor_value" --json

输出格式

{
  "results": [
    {
      "id": "12345",
      "properties": {
        "email": "john@example.com",
        "firstname": "John",
        "lastname": "Doe",
        "phone": "+1234567890",
        "company": "Acme Corp"
      },
      "url": "https://app.hubspot.com/contacts/.../record/0-1/12345"
    }
  ],
  "paging": {
    "next": {
      "after": "cursor_for_next_page"
    }
  }
}

展示格式

向用户展示结果时使用如下格式：

Found {count} contacts:

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

2. Jane Smith
   Email: jane@example.com
   ...

适用场景

需要快速查看 HubSpot CRM 中的联系人列表。
需要按数量或分页方式获取联系人数据。
需要将联系人信息以结构化 JSON 或可读列表形式呈现。

限制与错误处理

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

技能介绍

用途