SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hubspot-master

hubspot-master

营销与增长

查看项目

更新于 10-15 08:15

技能介绍

用途

hubspot-master 是一个共享资源库，供 HubSpot 集成技能引用，本身不是面向用户的技能。它的目标是消除多个 HubSpot 技能之间的内容重复（安装说明、API 文档、认证流程、错误处理），把公共内容抽取到 hubspot-master/references/ 和 hubspot-master/scripts/，再由各技能引用，从而形成单一事实来源并减少每个技能占用的上下文。

主要能力

该库为以下 HubSpot 集成技能提供共享资源：hubspot-connect（HubSpot CRM 操作的元技能）、hubspot-list-contacts、hubspot-create-contact、hubspot-update-contact、hubspot-search-contacts、hubspot-list-companies、hubspot-create-company、hubspot-search-companies、hubspot-list-deals、hubspot-create-deal、hubspot-update-deal、hubspot-search-deals、hubspot-get-associations、hubspot-list-emails、hubspot-log-email、hubspot-list-calls、hubspot-log-call、hubspot-list-notes、hubspot-create-note、hubspot-list-meetings、hubspot-create-meeting。

共享资源分为两类：

references/ 目录：

  • setup-guide.md：完整安装向导，涵盖在 HubSpot 创建 Private App、配置所需 scopes、获取访问令牌、环境配置。
  • api-reference.md：HubSpot API 模式，涵盖基础 URL 与认证、所有 CRM 端点、请求/响应示例、常用属性名。
  • error-handling.md：排错，涵盖常见错误与解决方案、HTTP 错误码、校验错误处理、速率限制。
  • authentication.md：令牌管理，涵盖 Private App 设置、令牌格式与用法、安全最佳实践。

scripts/ 目录：

  • check_hubspot_config.py：预检校验，命令为 python check_hubspot_config.py [--json]，--json 可选，默认 False，用于输出结构化 JSON 供 AI 使用；退出码 0=已配置、1=部分配置、2=未配置。应在任何 HubSpot 操作之前首先运行，用于验证访问令牌是否已配置、诊断认证问题或检查是否需要安装。
  • setup_hubspot.py：交互式安装向导，命令为 python setup_hubspot.py，无参数，交互运行，引导完成 Private App 设置、测试连接并保存到 .env。适用于需要初始安装、check_hubspot_config.py 返回退出码 2 或用户需要重新配置凭据时。

CRM 操作脚本（联系人）：

  • list_contacts.py：列出联系人（GET /crm/v3/objects/contacts），参数 --limit（默认 10，最大 100）、--properties（默认 email,firstname,lastname）、--after（分页游标）、--json。
  • create_contact.py：创建联系人（POST /crm/v3/objects/contacts），参数 --email（必填）、--firstname、--lastname、--phone、--company、--json。
  • update_contact.py：更新联系人（PATCH /crm/v3/objects/contacts/{id}），参数 --id（必填）、--email、--firstname、--lastname、--phone、--json。
  • search_contacts.py：搜索联系人（POST /crm/v3/objects/contacts/search），参数 --email、--name、--company、--limit（默认 10）、--json。

CRM 操作脚本（公司）：

  • list_companies.py：列出公司（GET /crm/v3/objects/companies），参数 --limit、--properties、--after、--json。
  • create_company.py：创建公司（POST /crm/v3/objects/companies），参数 --name、--domain、--industry、--json。
  • search_companies.py：搜索公司（POST /crm/v3/objects/companies/search），参数 --name、--domain、--industry、--limit、--json。

CRM 操作脚本（交易）：

  • list_deals.py：列出交易（GET /crm/v3/objects/deals），参数 --limit、--properties、--after、--json。
  • create_deal.py：创建交易（POST /crm/v3/objects/deals），参数 --name、--amount、--stage、--pipeline、--json。
  • update_deal.py：更新交易（PATCH /crm/v3/objects/deals/{id}），参数 --id、--name、--amount、--stage、--json。
  • search_deals.py：搜索交易（POST /crm/v3/objects/deals/search），参数 --name、--stage、--min-amount、--max-amount、--limit、--json。

关联与互动脚本：

  • get_associations.py：获取关联（GET /crm/v4/objects/{type}/{id}/associations/{toType}），参数 --object-type、--object-id、--to-type、--json。
  • 互动类脚本：list_emails.py、log_email.py、list_calls.py、log_call.py、list_notes.py、create_note.py、list_meetings.py、create_meeting.py。

使用方式

用户不应直接加载本库，而应直接调用所需的特定 HubSpot 技能。当某个 HubSpot 技能因缺少配置而失败时，AI 应按以下智能错误检测流程处理：

第 1 步：运行带 JSON 输出的配置检查： python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json

第 2 步：解析 ai_action 字段：

  • proceed_with_operation：配置正常，继续原操作。
  • prompt_for_access_token：询问用户提供 HubSpot 访问令牌，并提示在 HubSpot 创建 Private App 获取。
  • create_env_file：创建 .env 文件并向用户索取凭据。
  • add_missing_scopes：引导用户在 HubSpot Private App 设置中添加 scopes。
  • verify_token：令牌存在但连接失败，需验证其正确性。

第 3 步：帮助用户修复问题。若 ai_action 为 prompt_for_access_token：告知用户 HubSpot 集成需要安装，需要 Private App 访问令牌；提示在 HubSpot 的 Settings → Integrations → Private Apps 创建；请用户粘贴以 'pat-' 开头的访问令牌；拿到后直接写入 .env：HUBSPOT_ACCESS_TOKEN=pat-na1-their-token-here；然后重新运行配置检查验证。

环境变量：.env 中需要 HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxxxxxxx。

API 基础 URL：所有 API 请求发送至 https://api.hubapi.com。

适用场景

适用于需要通过 HubSpot CRM 进行联系人、公司、交易、关联及互动（邮件、通话、笔记、会议）操作的集成场景，作为这些技能背后的共享配置、认证与 API 参考支撑。

限制

本库不是面向用户的技能，不应直接加载；用户应调用具体的 HubSpot 技能。资料未提供收费、价格、平台支持范围或效果方面的信息。