crm-cleanup 技能实战：基于 HubSpot 的 CRM 数据清洗四步流程与审批机制解析

crm-cleanup 技能实战：基于 HubSpot 的 CRM 数据清洗四步流程与审批机制解析

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins

导读

crm-cleanup是 small-business 插件 中面向 HubSpot CRM 的专项清洗技能：当用户输入/crm-cleanup或说出"清理一下 CRM""HubSpot 太乱了""有僵死商机"时，它会自动对商机（deals）、联系人（contacts）和缺失字段进行全量体检，然后只执行所有者在逐条审批中明确同意的修改。读完本文你将掌握：如何调用该技能并按--scope精确圈定扫描范围、四步清洗流程的每一步产出什么、所有"只读不改、改必审批"的安全边界，以及底层crm-maintenance技能如何通过 hubspot-fields.md、cleanup-checklist.md 和 gotchas.md 支撑这套规则。

一、技能定位：crm-cleanup 与 crm-maintenance 的分工

在 small-business/README.md 的命令清单中，/crm-cleanup被定义为"HubSpot hygiene: stale deals, duplicates, missing fields — fixes what you approve"（HubSpot 卫生：僵死商机、重复联系人、缺失字段——修复你批准的部分），所需连接器为HubSpot，底层调用的技能是crm-maintenance。

两者的关系是：

• crm-maintenance是通用性维护技能，涵盖三条路径——邮件路径（记录邮件活动）、通话路径（记录通话活动）、清理路径（审计商机并提议更新），详见 crm-maintenance/SKILL.md；
• crm-cleanup是面向清理场景的专用入口。它的 SKILL.md 明确写道："Run a HubSpot hygiene pass using thecrm-maintenanceskill cleanup workflow."——即复用crm-maintenance的清理工作流，但省去了意图识别步骤：用户既然输入了/crm-cleanup，就立刻执行，不再询问"你想做什么"。

从仓库结构看（见 crm-maintenance 目录），crm-maintenance提供了完整的参考体系：字段清单（reference/hubspot-fields.md）、清理检查表（reference/cleanup-checklist.md）、易错点（reference/gotchas.md）以及三个完整场景示例（reference/examples/）。crm-cleanup正是在这套体系之上的"一键全量体检"入口。

二、参数解析：用--scope圈定扫描范围

技能声明段（YAML frontmatter）给出了触发语义：

name: crm-cleanup description: Scans HubSpot for stale deals, duplicate contacts, and missing fields, then fixes what the owner approves. Accepts optional scope argument for deals, contacts, or all. allowed-tools: Read, WebFetch, Bash

运行时唯一需要解析的参数是--scope：

默认值为all，即输入/crm-cleanup时不带参数就执行全量清洗。参数可以按需裁剪，避免在只关心联系人重复时把整个商机库也翻一遍。另外注意allowed-tools限定为Read、WebFetch、Bash——这是一个只读为主、写操作必须经由审批的工具面。

三、Step 1：僵死商机扫描（stale deals）

当--scope包含deals时，执行商机审计：

1. 拉取全部开放式商机（open deals）——注意不是历史已关闭商机，聚焦当前还在管线中的机会；
2. 标记僵死商机：以hs_lastactivitydate为准，判断最近14 天内是否有任何活动（邮件、通话、会议、备注）。无活动即标记为 stale；
3. 逐条展示僵死商机详情：商机名称、阶段（stage）、最近活动日期、关联联系人、金额（amount）；
4. 为每条僵死商机提出处置建议，四种可选动作：
   • 更新 next-step（下一步行动字段hs_next_step）
   • 变更阶段（dealstage）
   • 追加一条备注（note）
   • 标记为 close-lost（输单）

关键纪律：在做出任何修改之前，必须先完整展示僵死商机清单，等待所有者过目。

这里的字段口径可以从 hubspot-fields.md 得到印证：hs_lastactivitydate正是该技能用来"检测僵死商机"的字段，属于 Deals 只读字段之一；而"最近 14 天"的窗口与crm-maintenance清理路径中"拉取最近 14 天邮件线程和日历事件"的上下文窗口完全一致（见 crm-maintenance/SKILL.md），保证"商机看似无活动"和"邮箱日历里其实有互动"两种信号可以被交叉验证。

字段写入边界：根据 hubspot-fields.md，清理路径下 Deals 仅允许在获批后写入hs_next_step、closedate、amount和联系人关联；dealstage、pipeline、hubspot_owner_id及任何自定义属性在清理过程中严禁写入，它们是所有者管理的字段。

四、Step 2：重复联系人扫描（duplicate contacts）

当--scope包含contacts时，执行联系人去重：

1. 检索疑似重复，判定标准有三种：
   • 邮箱完全相同（注意：HubSpot 对邮箱匹配是大小写敏感的，见下文"易错点"）
   • 姓名高度相似
   • 同一公司 + 相似姓名
2. 每组疑似重复并排展示两个记录：姓名、邮箱、公司、关联商机、最近活动；
3. 给出"保留哪条记录、合并哪些字段"的合并建议。

关键纪律：合并任何内容之前，必须先把所有重复组完整展示出来。

这里需要特别警惕一个来自 gotchas.md 的深层陷阱——HubSpot 的邮箱去重对大小写敏感：Sarah.Lin@acme.com和sarah.lin@acme.com会被视为两条不同的联系人，若查询时不做大小写归一化，就会在所有者已有一条联系人时"静默制造"一条重复，直接摧毁用户对技能的信任。因此规范的查重做法是：

查询前先将邮箱统一转为小写（case-insensitive lookup），并在创建联系人前先向所有者播报一行预告，让用户有机会拦截拼写差异或重复。

去重的底层哲学：永不自动合并

crm-cleanup的审批门禁（Approval gates）对联系人合并的态度是"绝不自动合并"（Never auto-merge duplicate contacts）：必须并排展示差异，且每一对都要单独等待批准。这与gotchas.md中对"自动创建商机"的警告同源——HubSpot 中的重复对象会把活动历史劈成两半、搅乱报表，所有者往往几周后看预测时才发觉出了问题。去重/合并属于"破坏性最小但恢复成本高"的操作，必须逐对确认。

五、Step 3：缺失必填字段扫描（missing required fields）

本步不依赖--scope，对商机和联系人同时体检：

商机侧（全部开放式商机）逐项检查：

• close date（预计成交日期closedate）
• amount（金额）
• deal stage（阶段）
• 关联联系人
• next-step / notes（下一步行动或备注）

联系人侧（与开放式商机关联的联系人）逐项检查：

• email（邮箱）
• company（公司）
• phone（电话）

产出形式：一张表格，列出"哪些记录缺了什么字段"。这一步只读、只展示，不做任何修改。

这张检查表的字段骨架，与 cleanup-checklist.md 中"针对单条商机的清理检查表"完全对应——hs_lastactivitydate、hs_next_step、dealstage、closedate、amount、关联联系人、备注卫生七项。区别在于：crm-cleanup是全量扫描（所有开放商机 + 关联联系人），而crm-maintenance的清理路径通常是单条商机审计（用户说"clean up HubSpot"或"is this deal up to date"时触发）。二者共享同一套字段口径与证据规则。

六、Step 4：应用获批的修复（Apply approved fixes）

这是全流程唯一的写操作环节：

1. 逐条过一遍 Step 1～Step 3 的每个发现项；
2. 只应用所有者明确批准的那部分修改——未批准的一律不动；
3. 每写入一条修改就立即汇报一条，并附上对应的 HubSpot 记录链接，方便所有者在 CRM 中直接核对。

cleanup-checklist.md对该环节的输出格式有更细的要求：每个发现项必须以编号列表呈现，包含三个要素——发现了什么（What was flagged）、证据是什么（The evidence，注明邮件主题 + 日期，或会议标题 + 日期）、建议动作（The proposed action，阶段变更则标注"flag only"）。然后等待逐项或批量批准，只写获批内容。

单条商机审计的完整示范

仓库中的 cleanup-deal.md 给出了一个把七项检查表完整跑在单条商机"Acme Q2 Expansion"上的例子，可以直观看到"提议 — 审批 — 选择性执行"的全貌：

• 商机现状：阶段 "Proposal Sent"，金额 $18K，close date 5月15日，next step "send pricing"，hs_lastactivitydate距今 22 天；
• 发现：4月18日 Sarah 的邮件确认了报价并说"legal review 结束后签约，预计 6 月中旬"；4月20日的会议出现了不在 HubSpot、也不在商机上的新联系人maria.chen@acme.com；
• 建议清单：① 补记两条未记录的活动（邮件 + 会议）→ 建议写入；②hs_next_step从 "send pricing" 改为 "wait for legal review sign-off" → 建议写入；③ 阶段无变化证据 →只标记不改；④ close date 5月15日 与"6月中旬"冲突 → 建议改为 6月15日；⑤ 金额 $18K 与报价一致 → 无动作；⑥ 创建 Maria Chen 联系人并关联商机 → 建议写入；⑦ 90 天内无冲突备注 → 无动作；
• 审批结果：所有者回复"除了第 4 项都同意——close date 先别动，她可能过于乐观"；
• 最终执行：只写获批的 ①②⑥，close date 保持原样，并在报告中明确列出"改了哪些、哪些按你的意思没改"，附带商机链接。

这个例子完美演示了审批门禁的弹性：所有者可以按项选择性批准，技能必须精确尊重这个选择，而不是"批了一批就等于全批"。

七、连接器故障处理

技能对数据源有硬性依赖：如果 HubSpot 不可达，立即停止——本命令必须以 HubSpot 为数据源，没有降级路径。此时需要原样告知所有者：

"HubSpot isn't connected. Connect it in Cowork settings, then rerun /crm-cleanup." （HubSpot 未连接。请在 Cowork 设置中完成连接，然后重新运行 /crm-cleanup。）

这一处理与技能声明中allowed-tools: Read, WebFetch, Bash以及 README 中"HubSpot 是 CRM 类流程的核心连接器"的定位一致（见 small-business/README.md）：没有 HubSpot 数据，扫描和审批流程都无法展开，与其产生残缺结果，不如明确停止并给出恢复路径。

八、审批门禁：四条不可逾越的红线

crm-cleanup的安全模型可以浓缩为四条硬性规则，这也是整个清洗流程"可信赖"的根基：

1. 永不删除记录。无论是联系人、商机还是活动，一律不删。如果用户要求删除，明确告知技能不具备该能力，并引导其在 HubSpot 中操作；
2. 未经明确批准，永不改变商机阶段、永不关闭商机。即使证据看起来非常充分（比如邮件里说"we're moving forward"），也只能标记（flag）并延后（defer），把决定权留给所有者；
3. 绝不自动合并重复联系人。必须并排展示差异，每一对单独等待批准；
4. 所有修改都必须并排展示 diff。展示当前值 → 提议值，逐项等待批准后才能写入。

第 2 条背后的动机在 gotchas.md 中阐述得很透彻：客户邮件里写"we're moving forward"，不一定是"推进到 closed-won"——可能只是推进评估或采购环节，而所有者掌握着技能看不到的上下文（一通电话、一条 Slack、一条私人备注）。自动推进阶段会破坏整个管线（destructive to the pipeline）。正确的做法是："指出证据、扣住写入"（Surface the evidence, hold the write）。

同理，第 4 条还隐含了对"覆盖所有者手写字段"的防范：所有者手动设置的hs_next_step可能反映了技能不可见的上下文，覆盖它就是抹掉真实劳动。规范做法是展示当前值、明确提议（追加还是替换），并等待批准（见 gotchas.md 中"Overwriting an owner-set next-step"一节）。

九、输出规范：可追溯的清洗报告

清洗结束后，必须以总结收尾，格式为：

X deals updated, Y contacts merged, Z fields filled（X 条商机更新、Y 位联系人合并、Z 个字段补齐）

并附带受影响记录的链接。这样一份收尾报告同时满足三个目的：

• 数量可核对：所有者在 HubSpot 中能按数量反查，确认技能没有"多做"；
• 记录可追溯：每条改动都有 HubSpot 链接，与 Step 4"写一条报一条"的节奏形成闭环；
• 未改动可审计：被标记但未修改的项目（如阶段）同样值得让所有者知晓——参考cleanup-deal.md示例，报告中专门说明了"close date 按你的意思未改"和"阶段经核实与现状一致，无需变更"。

报告语言保持简短（Keep it short），这与 gotchas.md 中对活动正文的要求一脉相承——HubSpot 活动是"供快速扫读的信号面"而非"转录归档"，三句话的结论远胜于 1200 字的过程。

十、从指令到执行的纵深：整个技能链路的仓库脉络

如果希望深入理解crm-cleanup背后的实现细节，建议沿以下仓库路径逐层阅读：

值得留意的是，crm-cleanup所复用的"清理工作流"并非孤立的写操作，而是与crm-maintenance的邮件路径、通话路径共享同一套数据纪律：活动必须同时关联到商机和至少一个联系人；若在记录活动时顺带创建了联系人，必须在同一次操作中把该联系人关联到商机；但不要把非该邮件/会议参与者的联系人关联进商机（见 hubspot-fields.md 的关联规则）。这套规则保证了清洗过程中补录的活动，不会污染商机与联系人的关联关系。

结语

crm-cleanup是"权限最小化"与"流程确定性"结合的典型：四步扫描全部只读，唯一的写操作被压缩在 Step 4 且逐项审批；--scope让扫描范围可控；四条审批红线把删除、阶段变更、自动合并等高风险动作全部挡在"提议层"之外。对每天被僵死商机、重复联系人和空字段困扰的小型企业主来说，它把"清理 HubSpot"从一桩需要打开 CRM 逐条手动的苦差，变成了"看一遍建议清单、勾选同意、收一份可追溯报告"的十分钟例行事务。

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins