hubspot-connect

用途

HubSpot Connect 是一个面向用户的 HubSpot CRM 集成元技能（meta-skill），为所有 HubSpot CRM 操作提供单一入口。它遵循 master/connect 模式，引用 hubspot-master 以复用共享脚本和参考文档。

主要能力

该技能覆盖以下 HubSpot CRM 操作：

联系人（Contacts）：列表、创建、更新、搜索
公司（Companies）：列表、创建、搜索
交易（Deals）：列表、创建、更新、搜索
关联（Associations）：获取已链接的记录
互动（Engagements）：邮件、通话、备注、会议

触发方式

当用户说出以下内容时加载此技能：

"hubspot" / "hubspot crm"
"list contacts" / "show contacts"
"create contact" / "add contact"
"search contacts" / "find contact"
"list companies" / "show companies"
"create company" / "add company"
"list deals" / "show deals" / "show pipeline"
"create deal" / "new opportunity"
"log email" / "log call" / "add note"
任何与 CRM 相关的查询

使用方式

预检（始终首先运行）

在执行任何 HubSpot 操作之前，先验证配置：

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

根据配置状态采取相应动作：

proceed_with_operation：配置正常，继续操作
prompt_for_access_token：向用户索取访问令牌，保存到 .env
create_env_file：创建包含令牌的 .env 文件
add_missing_scopes：引导用户在 HubSpot 中添加权限范围
verify_token：令牌存在但无效

初始设置

若需要设置，向用户展示完整的 HubSpot 私有应用设置指南，包括：

创建私有应用（Settings → Integrations → Private Apps → Create a private app）
选择所需权限范围（scopes），包括 CRM 必需权限（contacts、companies、deals 的 read/write）以及可选的互动权限（emails、calls、notes、meetings 的 read/write）
获取访问令牌（以 pat-na1-... 或 pat-eu1-... 开头），并安全保存

用户提供令牌后，写入 .env：

HUBSPOT_ACCESS_TOKEN=pat-na1-xxx

然后重新运行配置检查以验证。

处理 403 Forbidden（缺少权限范围）

若设置后出现 403 错误，说明缺少权限范围。需引导用户前往 HubSpot 设置 → Integrations → Private Apps，点击对应应用，在 Scopes 标签页添加缺失的权限范围，提交更改，并复制新的访问令牌（更新权限范围后令牌会变化），更新 .env 后重试。

工作流

工作流 0：配置检查（自动）

触发：任何操作之前
脚本：check_hubspot_config.py --json
输出：配置状态、所需操作

工作流 1：列出联系人

触发："list contacts"、"show contacts"、"get contacts"
脚本：list_contacts.py --json

工作流 2：创建联系人

触发："create contact"、"add contact"、"new contact"
必需：邮箱；可选：名、姓、电话、公司
脚本：create_contact.py --email "user@example.com" --firstname "John" --lastname "Doe" --json

工作流 3：搜索联系人

触发："search contacts"、"find contact"、"lookup contact"
脚本：search_contacts.py --email "john@example.com" --json 或 search_contacts.py --name "John" --json

工作流 4：更新联系人

触发："update contact"、"edit contact"、"modify contact"
必需：联系人 ID
脚本：update_contact.py --id 12345 --phone "+1234567890" --json

工作流 5：列出公司

触发："list companies"、"show companies"
脚本：list_companies.py --json

工作流 6：创建公司

触发："create company"、"add company"、"new company"
脚本：create_company.py --name "Acme Corp" --domain "acme.com" --industry "Technology" --json

工作流 7：搜索公司

触发："search companies"、"find company"
脚本：search_companies.py --name "Acme" --json

工作流 8：列出交易

触发："list deals"、"show deals"、"show pipeline"
脚本：list_deals.py --json

工作流 9：创建交易

触发："create deal"、"add deal"、"new deal"、"new opportunity"
脚本：create_deal.py --name "Enterprise Deal" --amount 50000 --stage "qualifiedtobuy" --json

工作流 10：更新交易

触发："update deal"、"edit deal"、"change deal stage"
脚本：update_deal.py --id 12345 --stage "closedwon" --json

工作流 11：搜索交易

触发："search deals"、"find deal"
脚本：search_deals.py --name "Enterprise" --min-amount 10000 --json

工作流 12：获取关联

触发："get associations"、"linked records"、"related contacts"、"contacts on deal"
脚本：get_associations.py --object-type deals --object-id 12345 --to-type contacts --json

工作流 13：互动操作

列出邮件：list_emails.py --json
记录邮件：log_email.py --subject "Follow up" --body "Meeting follow-up email" --json
列出通话：list_calls.py --json
记录通话：log_call.py --title "Sales Call" --body "Discussed pricing" --duration 30 --json
列出备注：list_notes.py --json
创建备注：create_note.py --body "Important note about this contact" --json
列出会议：list_meetings.py --json
创建会议：create_meeting.py --title "Product Demo" --body "Demo of new features" --start "2025-12-15T14:00:00Z" --end "2025-12-15T15:00:00Z" --json

智能路由

根据用户提到的短语将请求路由到对应工作流，例如：

"list contacts"、"show contacts" → 工作流 1
"create contact"、"add contact" → 工作流 2
"search contacts"、"find contact" → 工作流 3
"update contact"、"edit contact" → 工作流 4
"list companies"、"show companies" → 工作流 5
"create company"、"add company" → 工作流 6
"search companies"、"find company" → 工作流 7
"list deals"、"show pipeline" → 工作流 8
"create deal"、"new opportunity" → 工作流 9
"update deal"、"change stage" → 工作流 10
"search deals"、"find deal" → 工作流 11
"associations"、"linked records" → 工作流 12
"emails"、"calls"、"notes"、"meetings" → 工作流 13

错误处理

常见错误及解决方案：

401 Unauthorized：令牌无效，检查 HUBSPOT_ACCESS_TOKEN
403 Forbidden：缺少权限范围，需添加到私有应用
404 Not Found：记录不存在
409 Conflict：记录重复，先搜索
429 Rate Limited：等待后重试

出错时加载 hubspot-master/references/error-handling.md，显示用户友好的消息，并在可能时提供修复方案。

上下文缓存

列出记录后，在会话中缓存，例如将联系人列表存入对话上下文。当用户说 "update John Doe" 时，匹配到缓存中的联系人 ID。

适用场景

适用于需要通过自然语言与 HubSpot CRM 交互的场景，包括管理联系人、公司、交易记录，查询关联关系，以及记录邮件、通话、备注和会议等互动。

限制

需要先完成 HubSpot 私有应用设置并配置访问令牌与权限范围
部分操作（如互动记录）需要额外的可选权限范围
更新权限范围后访问令牌会变化，需重新更新 .env
受 HubSpot API 速率限制影响（429 错误需等待重试）

版本

版本：1.0；创建日期：2025-12-13；状态：Production Ready。