hubspot-revops-skill

基于 HubSpot API 和 SQL 数据仓库构建收入分析基础设施。涵盖 ICP 验证、ML 线索评分、竞争情报、活动分析和销售管道预测，将 CRM 数据转化为可执行的情报产品。

<quick_start> Epiphan 原生路径（默认 — 无需 Private App）：

1. 读取 crm://schema.md（Epiphan AI 资源），然后针对 HubSpot 表（hubspot_contacts、hubspot_companies、hubspot_deals 等）使用 execute_sql / query_dataset 执行所有聚合查询。
2. 对于会生成人员或公司名单的用例（UC1 细分、UC2 评分线索）：通过 SQL 提取候选对象，然后对每一行运行 qualify_lead（Epiphan AI）— Gate Q — 再进行数据丰富、评分或纳入名单。
3. 丰富通过 Gate Q 的行：enrich_contact（Epiphan AI）→ Apollo apollo_people_match → Clay 瀑布流程。
4. 按用例交付（见下表）：XLSX/HTML、export_query_csv，或通过 hubspot_update_contact 写入 HubSpot 属性（先确认）。 仅当 MCP 无法访问所需内容时，才配置原始 SDK / Private App — 参见 reference/api-guide.md 附录。 </quick_start>

<house_rules> 面向客户的技能。输出前，按顺序执行各道检查关卡（详情：~/.claude/skills/epiphan-house-rules-skill/reference/gates.md）： S：在作出任何产品声明前，使用 search_product_catalog（Epiphan AI）或 Epiphan Knowledge 搜索。B：对每一条面向客户的文案使用 check_my_copy。 Q：提取候选对象后立即运行 qualify_lead，再进行分级、数据丰富或起草内容。D：外发文本必须成为 Gmail 草稿，绝不能直接发送。 标识符（所有者 ID、portal、电子邮件、席位）来自该技能中的 reference/identifiers.md — 请勿在此重复。 任一检查关卡失败时，遵循 reference/self-healing.md（重试、降级并标记、提醒 Tim、停止），并向 ~/.claude/skill-runs/.jsonl 追加一行。 </house_rules>

<success_criteria>

• 可通过 Epiphan AI execute_sql 访问数据仓库（先读取架构），并验证数据新鲜度（同步延迟 < 24h）
• 至少一个用例（ICP、评分、竞争、活动、预测）产出结果并生成具名交付成果
• 每个生成名单的输出（UC1、UC2）均逐行通过 qualify_lead；不在内联代码中重新实现 Golden Rules / ATL-BTL / AE-owner 逻辑
• 使用 200+ 个历史成交订单训练线索评分模型，并获得可衡量的 AUC
• 写回评分至 HubSpot 前先确认，并进行去重
• 写入 outcome sidecar 和运行日志行 </success_criteria>

HubSpot RevOps 分析

基于 HubSpot API 和 SQL 数据仓库的收入分析基础设施。 将 CRM 数据 → 分析 → 情报产品 → 收入影响串联起来。

范围： 专用于 HubSpot 的分析技术栈。基本 CRM 增删改查请使用 crm-integration-skill。通用仪表板请使用 data-analysis-skill。

---

设置清单

1. Epiphan AI 数据仓库（默认）

Tim 的 HubSpot 数据已复制到 Epiphan AI PostgreSQL 数据仓库。访问方式：

1. 读取 crm://schema.md（或使用 get_schema）— 猜测列名是查询失败的首要原因。
2. 使用 execute_sql 获取行数据（JSON，速度快）· 答案需要文件时使用 export_query_csv · 使用 query_dataset 查询已保存的数据集 · 仅当问题无法用 SQL 表达时才使用 ask_agent（速度慢且按量计费）。
3. 验证数据新鲜度：SELECT max(hs_lastmodifieddate) FROM hubspot_contacts — 延迟 > 24h → 将每项结果标记为过期。

2. Private App / 原始 SDK（附录 — 仅当 MCP 无法访问时使用）

reference/api-guide.md 中记录了 HubSpot Private App（contacts/companies/deals/owners/timeline scopes）和 Python SDK 模式。 以下用例均无需使用；请勿从这里开始。

---

核心用例

#	用例	输入	输出	工具	交付产物
1	ICP 验证	联系人 + 公司数据	细分转化率 + 经过筛选的目标名单	SQL → qualify_lead → Clay/Apollo	通过 export_query_csv/openpyxl 生成 XLSX（细分工作表 + 筛选后的联系人工作表）
2	潜在客户评分	历史交易	每位潜在客户的赢单概率（经过筛选）	SQL + ML → qualify_lead	写入 HubSpot 自定义属性（hubspot_update_contact，先确认）+ XLSX 审计表
3	竞争情报	交易成交原因	按竞争对手划分的赢单/失单情况	SQL	${CLAUDE_OUTPUTS_DIR:-./outputs/} 中的 HTML 矩阵 + 发送给 Tim 的 Slack 私信摘要
4	活动分析	互动数据	活动→结果的相关性	SQL	HTML 报告
5	销售管道预测	未成交交易 + 阶段历史	加权收入预测	SQL	XLSX 预测表（按阶段、按销售代表）+ 一段摘要

用例详情

UC1 — ICP 验证： 在 SQL 中联接联系人 + 公司 + 交易，按行业/规模/地理位置细分，并计算每个细分的转化率（聚合操作保留在 SQL 中）。当细分结果成为目标名单时，先对每个候选行运行 qualify_lead（Gate Q 会排除客户、渠道、仅产品互动者、由活跃 AE 负责的联系人和已抑制联系人；过期的 AE 潜在客户会标记为 STALE AE LEAD；等级依据判定结果确定），然后将剩余记录送入数据补全流程：

1. 使用 find-and-enrich-company 或 find-and-enrich-contacts-at-company 识别目标联系人
2. 使用 add-contact-data-points / add-company-data-points 将数据补全任务加入队列
3. 使用 get-task 轮询结果并检查 state: completed
4. 通过 API 或 Epiphan CRM 集成将补全后的数据写回 HubSpot

替代方案：使用 Apollo MCP（apollo_people_match）直接补全，无需等待流程完成。

UC2 — 潜在客户评分： 使用历史赢单/失单交易训练 GradientBoostingClassifier。特征：公司规模、行业、互动评分、销售管道中的天数、qualify_lead 等级。只对通过 Gate Q 的行评分；通过 hubspot_update_contact 将评分作为自定义属性写回 HubSpot（先确认，并按 hs_object_id 去重）。

UC3 — 竞争情报： 从交易的 closed_lost_reason 中提取竞争对手提及信息。按竞争对手构建赢单/失单矩阵。针对竞争导致客户流失的模式触发 webhook 警报。

UC4 — 活动分析： 分析邮件打开、会议预约、通话记录与交易结果之间的相关性。找出哪些活动真正推动了交易进展。

UC5 — 销售管道预测： 根据历史数据中各阶段的特定赢单率计算加权预测。将交易存续时间、推进速度和销售代表表现纳入考量。

参考： 每种用例的完整 SQL 模板请参阅 reference/sql-analytics.md。

---

潜在客户质量：Gate Q 负责执行黄金规则

qualify_lead 是此技能生成的所有名单（UC1 目标名单、UC2 评分潜在客户）的事实来源：客户、渠道合作伙伴、仅产品互动者、由活跃 AE 负责的联系人、已抑制联系人及重复项均以其判定为准，ATL/BTL 等级也来自同一次调用。完整规则文本和负责人 ID 位于 CLAUDE.md 的“Golden Rules”以及 house-rules 技能的 reference/identifiers.md 中；此处不重新实现这些规则。

只要 SQL 的筛选条件比 Gate 宽松（绝不能更严格），且 AE 条款遵循 90 天过期例外而非硬性排除，SQL 就可以预筛选，以减少进入 Gate Q 的候选数量：

-- candidate pre-filter only; qualify_lead still runs on every surviving row
WHERE lifecyclestage <> 'customer'
  AND COALESCE(device_count, 0) < 1
  AND COALESCE(is_channel, false) = false
  AND country IN ('United States', 'Canada')
  -- AE-owned: keep if last activity > 90 days (surfaces as STALE AE LEAD); drop if worked recently
  -- mirror of identifiers.md (Lex 82625923 NA-only, Ron 423155215 all, Phil 190030668 NA-only)
  AND NOT (hubspot_owner_id IN (82625923, 423155215, 190030668)
           AND notes_last_updated >= NOW() - INTERVAL '90 days')

上一版中的 hubspot_owner_id IN (…) 会被理解为仅将由目标 AE 负责的联系人纳入名单，并硬性排除过期联系人；这两点都与 2026-03-21 的过期 AE 例外相悖，因此现已移除。 若在生成名单的运行中无法使用 qualify_lead，则停止生成名单（仍可交付聚合结果），并通知 Tim。

---

HubSpot API 端点速查

对象	端点	主要操作
联系人	/crm/v3/objects/contacts	搜索、创建、更新、批量操作
公司	/crm/v3/objects/companies	搜索、关联到联系人
交易	/crm/v3/objects/deals	管道、阶段历史
互动	/crm/v3/objects/engagements	电子邮件、通话、会议
属性	/crm/v3/properties/{object}	自定义属性的 CRUD 操作
关联	/crm/v4/associations/{from}/{to}	对象关联
搜索	/crm/v3/objects/{object}/search	筛选 + 排序（最多 10k 条）

参考： 有关身份验证、SDK 模式和批量操作，请参阅 reference/api-guide.md。

---

SQL 对象模型速查

HubSpot 对象	SQL 表（典型）	主要列	关联键
联系人	hubspot.contacts	email, lifecycle_stage, lead_score	contact_id
公司	hubspot.companies	domain, industry, employee_count	company_id
交易	hubspot.deals	amount, stage, close_date, pipeline	deal_id
交易阶段	hubspot.deal_stage_history	stage, timestamp, duration	deal_id
互动	hubspot.engagements	type, created_at, contact_id	engagement_id
所有者	hubspot.owners	email, first_name, team	owner_id

关联模式： 联系人 → 关联 → 公司/交易（通过关联表）

---

集成点

技能	关系
crm-integration-skill	基础 CRUD 模式、身份验证设置
data-analysis-skill	可视化、Streamlit 仪表板
sales-revenue-skill	管道指标、MEDDIC 背景、预测
research-skill	市场/竞争研究方法
cost-metering-skill	跟踪 API 调用 + Clay 数据增强支出
prospect-research-to-cadence-skill	自动化交易流程、Golden Rules 筛选
deal-momentum-analyzer-skill	管道健康评分

MCP 集成点

MCP 连接器	可用工具
Epiphan AI (mcp__claude_ai_Epiphan_Ai__)	execute_sql, query_dataset, export_query_csv, get_schema, qualify_lead, enrich_contact, hubspot_search_companies, hubspot_search_contacts, hubspot_search_deals, hubspot_get_company, hubspot_get_contact, hubspot_get_deal, hubspot_update_contact, hubspot_create_list, crm_search_customers, crm_get_customer, crm_get_order, crm_get_customer_orders, analytics_get_device, analytics_search_by_email, ask_agent（AI 查询，只读）
Clay MCP	find-and-enrich-company, find-and-enrich-contacts-at-company, find-and-enrich-list-of-contacts, add-contact-data-points, add-company-data-points, get-task
Apollo	apollo_people_match, apollo_contacts_create, apollo_contacts_search, apollo_organizations_enrich, apollo_mixed_companies_search, apollo_emailer_campaigns_*

---

常见错误

错误	修复方法
超出每 10 秒 100 次请求的速率限制	使用批量端点，并添加指数退避
使用 Search API 获取超过 10k 条结果	切换到 SQL 数据仓库进行批量分析
硬编码属性内部名称	先获取属性定义：GET /crm/v3/properties/{object}
对象链接未使用关联 API	使用 v4 关联：POST /crm/v4/associations/{from}/{to}/batch/read
在 Postgres 中使用 SQL DATEDIFF	使用 AGE() 或 EXTRACT(EPOCH FROM ...)——参见方言说明
未处理 HubSpot 的 hs_object_id	属性请求中始终包含 hs_object_id
丰富数据后仍缺少电话号码	在 Apollo 之后使用 Clay 瀑布式流程：先用 Apollo（快速、免费），再使用 Clay MCP（find-and-enrich-contacts-at-company → add-contact-data-points → get-task）验证电话号码。Clay 汇总了 50 多家数据提供商，可实现较高的匹配率。
基于小型数据集训练评分模型	至少需要 200 笔已成交交易，才能获得可靠的 ML 评分
仅使用 Apollo 丰富数据时仍有数据缺失	使用 Clay MCP 作为备用方案：通过 find-and-enrich-company 创建 taskId，然后用 add-contact-data-points 补充电子邮件/电话/工作经历，并通过 get-task 轮询结果

---

工作流阶段

阶段 1：基础

1. 阅读 crm://schema.md；通过 list_tables 确认 HubSpot 表
2. 验证数据新鲜度（同步延迟）
3. 仅当 MCP 无法访问某个数据集时：按照 reference/api-guide.md 创建 Private App

阶段 2：分析

5. 构建 ICP 验证查询（UC1）
6. 创建销售管道速度仪表板（UC2、UC5）
7. 设置竞争情报跟踪（UC3）

阶段 3：智能分析

8. 使用历史交易训练潜在客户评分模型
9. 通过 API 将评分部署到 HubSpot
10. 构建数据丰富流水线（Clay → HubSpot）
11. 设置自动提醒和 Webhook

参考： ML 评分和 Clay 集成请参见 reference/enrichment-pipelines.md。 参考： 部署模式和成本估算请参见 reference/architecture.md。

<self_healing> success = 查询已运行、产物已交付、列表已通过门控。partial = 产物已交付，但某个阶段降级（已标记数据仓库延迟超过 24 小时、数据丰富层失败、未确认 HubSpot 写入、样本量不足以训练模型）——指出具体阶段。error = 未生成产物（重试后数据仓库仍无法访问、架构不匹配且未解决），或在生成列表的任务中 qualify_lead 不可用 → 停止生成列表。按照 ~/.claude/skills/epiphan-house-rules-skill/reference/self-healing.md 中的阶梯处理：退避后重试一次（速率限制/超时）→ 降级（仅用 SQL，跳过数据丰富）→ 提醒 Tim → 停止。每次运行都在 ~/.claude/skill-runs/hubspot-revops-skill.jsonl 中追加一行。 </self_healing>

输出结果旁车文件

最后一步，将以下内容写入 ~/.claude/skill-analytics/last-outcome-hubspot-revops-skill.json：

{"ts":"[UTC ISO8601]","skill":"hubspot-revops-skill","version":"<frontmatter version>","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"queries_executed":[n],"reports_generated":[n],"insights_found":[n],"rows_gated":[n],"excluded_by_qualify":[n],"stale_ae_surfaced":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果部分阶段失败但已生成结果，请使用状态 "partial"；error 必须指出具体阶段。只有未生成任何输出时才使用 "error"。