hubspot-search-deals

用途

hubspot-search-deals 是一个专门用于在 HubSpot CRM 中搜索交易（Deals）的技能。当用户表达“search deals”“find deal”“lookup deal”“deals over $X”“search for [deal]”等意图时，该技能会被加载，帮助用户快速定位符合条件的交易记录。

主要能力

按交易名称搜索：使用 CONTAINS_TOKEN 操作符进行部分匹配。
按最低金额筛选：使用 GTE（大于或等于）操作符。
组合搜索：同时指定名称和最低金额，并可设置返回结果数量上限。
结果按创建日期排序，最新创建的排在最前。
输出格式为 JSON，包含总数、结果列表（含交易 ID、属性如 dealname、amount、dealstage、closedate，以及交易 URL）。
提供格式化显示，便于阅读。

使用方式

预检查

运行前需执行配置检查：

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_deals.py \
  --name "Enterprise" \
  --json

按最低金额搜索

python 00-system/skills/hubspot/hubspot-master/scripts/search_deals.py \
  --min-amount 10000 \
  --json

组合搜索

python 00-system/skills/hubspot/hubspot-master/scripts/search_deals.py \
  --name "Acme" \
  --min-amount 50000 \
  --limit 20 \
  --json

输出格式示例

{
  "total": 5,
  "results": [
    {
      "id": "5840795376",
      "properties": {
        "dealname": "Acme Corp - Enterprise",
        "amount": "50000",
        "dealstage": "qualifiedtobuy",
        "closedate": "2025-03-15T00:00:00Z"
      },
      "url": "https://app.hubspot.com/..."
    }
  ]
}

显示格式示例

Found 5 deals matching "Enterprise" (min $10,000):

1. Acme Corp - Enterprise
   Amount: $50,000
   Stage: Qualified to Buy
   Close Date: 2025-03-15
   ID: 5840795376

2. Enterprise Package - Tech Inc
   Amount: $25,000
   Stage: Contract Sent
   ...

适用场景

销售人员在 HubSpot CRM 中快速查找特定名称或金额范围的交易。
需要批量筛选高价值交易（如金额超过某阈值）时。
与其他 HubSpot 技能（如 hubspot-list-deals、hubspot-update-deal、hubspot-create-deal）配合使用，形成完整的工作流。

限制

需要有效的 HubSpot 配置和访问令牌。
需要 crm.objects.deals.read 权限范围。
可能遇到速率限制（429 错误），需等待后重试。
名称搜索为部分匹配，金额筛选为大于或等于。
结果数量可通过 --limit 参数控制。

错误处理

错误	解决方案
401	无效令牌 - 重新运行设置
403	缺少 crm.objects.deals.read 权限范围
429	速率限制 - 等待并重试

技能介绍

用途