knowledge-work-plugins 之 crm-maintenance：用 Cowork Skill 实现 HubSpot CRM 免人工维护的自动化实践指南

knowledge-work-plugins 之 crm-maintenance：用 Cowork Skill 实现 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

本篇指南系统讲解 knowledge-work-plugins 仓库中小型企业（small-business）插件内的crm-maintenanceSkill：它如何在不打开 HubSpot 的情况下，基于邮件与日历上下文自动创建/更新联系人、记录通话与邮件活动、审计并标记过时商机（deal）。读完本文你将掌握该 Skill 的三条工作路径（Email / Call / Cleanup）、完整的字段与活动类型白名单、每步操作的审批门禁（Approval Gate），以及如何结合/crm-cleanup命令执行全量 CRM 卫生检查。

一、Skill 定位：做“数据录入终结者”，而非“全权接管 CRM”

crm-maintenance是 small-business 插件 15 个基础技能（Skills）之一，其核心设计理念在 SKILL.md 的元信息中写得很直白：

Keeps HubSpot current without the owner opening it: creates and updates contacts and deals from email and calendar context, logs notes and calls, and flags stale records. The "stop doing data entry" skill.

也就是说，它的目标是让小型企业主无需打开 HubSpot 界面，就能让 CRM 保持最新：从邮件线程和日历事件中提取上下文，解析正确的联系人与商机，写入活动记录，并标记过时数据。使用场景由 README 归纳为四类触发语："update the CRM"、"log a call"、"clean up HubSpot"、"add context to a deal"。

边界与适用前提：

• 该 Skill 是只读优先 + 最小写入的代理流程：仅在用户明确要求时写活动；清理路径（cleanup）下只提出修改建议，未经批准绝不写入。
• 它不负责删除任何记录、不自动改商机阶段、不自动创建商机——这些红线在“审批门禁”一节会详细展开。
• 它依赖 HubSpot 连接器作为数据源，可选接 Gmail / Google Calendar 提供邮件与日历上下文（见 README 中的工具连接要求）。
• 如果你需要的是“扫描全库的过时商机、重复联系人、缺失字段”这类批量卫生巡检，应使用更高层的/crm-cleanup命令（见本文第六节），它内部正是调用crm-maintenance的清理工作流。

二、Quick Start：从用户一句话到 CRM 更新完成

SKILL.md 给出了最精简的运行模型：从被引用的邮件或日历事件中拉取上下文 → 解析出正确的 HubSpot 联系人与商机 → 记录活动 → 汇报变更。以“记录通话”为例，它的理想执行流如下：

User: "log this call to the Acme deal" → Read the most recent completed calendar event → Confirm attendees map to the Acme deal's contacts → Write a call activity on the Acme deal → Report: "Logged call to Acme Q2 Expansion. [deal link]"

注意这个链路里的三个关键判断点：

1. 取哪个日历事件——用户没有显式指定时，回退到最近 24 小时内已结束的会议，且必须与用户确认后再继续；
2. 参会人是否属于该商机——确认联系人映射关系，避免把无关的人关联到商机上；
3. 写入什么、写到哪里——调用活动（Call engagement）必须同时关联商机和至少一个联系人。

三、核心工作流：三条路径的意图识别、上下文收集与执行

SKILL.md 将整个流程划分为 6 个步骤，其中第一步“意图识别”决定了后续走哪条路径。

3.1 第一步：识别意图（三条路径）

若意图不明确（例如只说“update HubSpot”却没有附带邮件/会议/商机引用），必须先向用户询问走哪条路径，不得擅自猜测。

3.2 第二步：收集上下文（各路径差异显著）

• Email 路径：读取整个线程（主题、参与者、最近 1–3 条消息），识别主要的外部联系人。
• Call 路径：读取日历事件（标题、参会人、时间、描述）；未指定事件时，取最近 24 小时内最近一次已结束的会议，并在继续前与用户确认。
• Cleanup 路径：拉取商机全貌（阶段、金额、预计结单日期、下一步动作、关联联系人、近 60 天活动），再拉取该商机联系人近 14 天的邮件线程与日历事件作为审计证据。

3.3 第三步：解析联系人与商机（核心解析逻辑）

对 Email / Call 路径，解析顺序固定为：

1. 按邮箱搜索联系人（大小写不敏感精确匹配，详见第五节 gotcha 1）；
2. 若联系人不存在，可从邮件签名或日历邀请数据中创建——但写入前必须在对话中宣布创建动作；
3. 商机解析顺序（四层递进）：
   • (a) 用户显式指定的商机，直接命中；
   • (b) 该联系人唯一未关闭的商机；
   • (c) 在联系人所有未关闭商机中，用邮件主题或会议标题做模糊匹配——写入前需确认；
   • (d) 仍无匹配则询问用户；
   • 任何情况下都不得自动创建商机。

在执行任何写入之前，先阅读 字段与活动类型参考 确认字段名、活动类型与关联规则；如果去重或商机解析存在歧义，先查阅 gotchas 清单。

3.4 第四步：执行动作（各路径的写入差异）

• Email 路径：写入 Email engagement 活动。hs_email_subject取线程主题，hs_email_text写简洁摘要而非完整线程，hs_timestamp取最新一条消息的时间。完整示例见 log-email-happy-path.md。
• Call 路径：写入 Call engagement 活动。hs_call_title取事件标题，hs_call_body写入可得笔记，hs_call_duration取自日历，hs_timestamp取事件开始时间。含“联系人缺失需创建”场景的完整示例见 log-call-happy-path.md。
• Cleanup 路径：按 清理检查清单 逐字段走查，组装“拟变更清单”，以当前值 → 建议值的并排形式展示，只写入用户批准的项目。完整示例见 cleanup-deal.md。

3.5 第五步与第六步：审批门禁与结果汇报

• 审批门禁：联系人创建与活动记录写入前需宣布、写入后需汇报结果；清理类修改则必须等用户逐项批准后才动手。
• 结果汇报：告诉用户“写入了什么、还挂着哪些待办”，尽可能附带受影响商机的 HubSpot 链接，保持简短。

四、字段、活动类型与关联规则：唯一的读写白名单

hubspot-fields.md 是理解该 Skill 安全边界的关键：只有清单中列出的字段在此 Skill 的读写范围内，HubSpot 中其余一切字段一律不动。

4.1 联系人（Contacts）——写入字段

规则：不写任何其他联系人属性。Owner、lifecycle stage、lead source 属于用户托管字段，绝不覆盖。

4.2 联系人（Contacts）——读取字段（用于查找）

• email：搜索键，大小写不敏感精确匹配；
• firstname·lastname·company：用于歧义解析时向用户展示；
• hs_object_id：用于与商机、活动的关联。

4.3 商机（Deals）——读取字段（清理与解析路径通用）

4.4 商机（Deals）——写入字段（仅清理路径 + 用户批准）

红线：清理过程中绝不写dealstage、pipeline、hubspot_owner_id或任何自定义属性——这些归 Owner 托管。

4.5 活动（Activities）——写入类型

规则：使用 HubSpot 标准 engagement 词汇，不得发明自定义活动类型。

4.6 关联规则

• 每条活动必须同时关联商机和至少一个联系人；
• 若在记录活动过程中即时创建了联系人，应在同一次操作中将其关联到商机，使活动同时出现在联系人与商机的时间线上；
• 除非该联系人的确是该邮件线程或会议的真实参与者，否则不得在活动记录流程中把联系人关联到商机。

五、反模式清单：五个最容易污染 CRM 的“坑”

gotchas.md 采用“为什么重要 → ✗ Bad → ✓ Good”的对比模式，总结了该 Skill 最容易产出坏数据（bad CRM data）的五类边缘场景。这是判断 Skill 行为是否合格的行为准则，也直接约束了任何基于该 Skill 的二次实现。

5.1 大小写差异导致重复联系人

HubSpot 按精确邮箱匹配去重：Sarah.Lin@acme.com与sarah.lin@acme.com被视为两个不同联系人。若按原大小写搜索“无匹配”就创建新联系人，会在 Owner 已有记录时静默产生重复，摧毁信任。

• ✗ 错误示范：按Sarah.Lin@acme.com搜索无匹配，直接新建联系人 Sarah Lin。
• ✓ 正确示范：查找前一律将邮箱归一化为小写，搜索sarah.lin@acme.com；并先宣布再写入，让 Owner 有机会发现漏网情况。

5.2 把完整邮件线程塞进活动正文

HubSpot 活动是供快速扫读的信号面，不是转录存档。12 条消息的完整线程粘贴进去毫无可用性；三句话的“达成了什么”才可执行。

• ✓ 正确摘要示例：“Sarah confirmed scope for Q2 expansion — 50 seats, $18K ACV, start date June 1. She'll send the signed SOW by Friday. No open questions.”（命名了决策、数字和下一步）。

5.3 商机无法解析时自动创建商机

重复商机在 HubSpot 中极难解开——会分裂活动历史、干扰报表，Owner 往往几周后看预测不对才发现。正确做法是问，绝不在 Owner 不知情时新建商机：

No open deal found for Sarah Lin at Acme. Which deal should I log this to? Options: (1) Acme Q2 Expansion (closed-won Feb), (2) Acme Renewal 2027 (open). Or do you want to skip logging for now?

5.4 仅凭邮件措辞就推进商机阶段

“We're moving forward”不代表“进入 Closed Won”——客户可能指推进评估或采购流程，Owner 拥有 Skill 看不到的上下文。自动推进阶段会破坏管道（pipeline）。

• ✓ 正确做法：摆出证据、暂停写入。例如：“Flagging: the Apr 18 email from Sarah ('we're moving forward with the Anthropic evaluation') may indicate stage movement. Current stage is 'Proposal Sent.' Do you want to advance it? I won't change stage without your explicit go-ahead.”

5.5 清理时覆盖 Owner 设置的下一步动作

Owner 设置的hs_next_step可能反映电话、Slack 线程、私人笔记等 Skill 不可见的上下文，仅因一封邮件内容不同就覆盖等于抹掉真实工作。正确做法：展示当前值、显式提出建议、等待批准，例如：

hs_next_stepcurrently reads "wait for legal review" (set by you 3 days ago). The Apr 19 email from Sarah suggests a pricing review is also needed. Propose appending or replacing? Current → Proposed: "wait for legal review" → "wait for legal review; then schedule pricing review." Approve?

六、升级为批量巡检：/crm-cleanup命令

当用户说“clean up the CRM”“HubSpot is a mess”“stale deals”时，small-business/README.md 会路由到/crm-cleanup命令。该命令定义在 crm-cleanup/SKILL.md，本质是crm-maintenance清理工作流的批量执行器，其元信息允许Read, WebFetch, Bash三类工具，并明确指出“用户已输入 /crm-cleanup，跳过意图识别步骤，立即执行”。

/crm-cleanup支持可选--scope参数（默认all）：deals仅做商机审计、contacts仅做联系人去重、all两者都做。四步执行流程：

1. 扫描过时商机：拉取所有未关闭商机，标记近 14 天无任何活动（邮件/通话/会议/笔记）的商机；对每个过时商机展示名称、阶段、最后活动日期、关联联系人与金额，并建议动作（更新下一步、改阶段、加笔记或关 lost）。改动前先展示完整清单。
2. 扫描重复联系人：查找疑似重复（相同邮箱、相似姓名、同公司 + 相似姓名）；每组并排展示姓名、邮箱、公司、商机与最后活动，建议保留哪个、合并哪些字段。合并前展示全部重复组。
3. 扫描缺失必填字段：检查所有未关闭商机的 close date、amount、deal stage、关联联系人、next-step/notes；检查与未关闭商机关联的联系人的 email、company、phone。
4. 应用已批准的修改：逐条走查前三步发现，只应用 Owner 明确批准的项目，每项变更随附 HubSpot 链接即时汇报。

连接器失败处理：HubSpot 不可达时立即停止（该命令以 HubSpot 为唯一数据源），并提示“HubSpot isn't connected. Connect it in Cowork settings, then rerun /crm-cleanup.”。

该命令的审批门禁与 Skill 一致：绝不删除记录、绝不未经批准改阶段或关闭商机、绝不自动合并重复联系人（逐对并排展示、逐对等批准）、所有变更以“当前值 → 建议值”形式逐项等待批准。收尾输出汇总：X deals updated, Y contacts merged, Z fields filled，并附受影响记录链接。

七、走查三个工作示例：从 happy path 到完整清理

7.1 Email 路径 happy path：log-email-happy-path.md

场景：用户在查看主题为 “Acme Q2 pricing follow-up” 的邮件线程（含 3 条消息），联系人为已有的sarah.lin@acme.com，且只关联一个未关闭商机 “Acme Q2 Expansion”（Proposal Sent，$18K，5 月 15 日结单）。用户说“Add this thread to the deal.”

关键行为：意图识别为 Email 路径 → 读取线程（最新消息确认 50 seats @ $360/seat，周五发已签 SOW）→ 联系人存在、商机唯一，解析无歧义 → 写入 Email 活动（hs_email_subject=线程主题，hs_email_text=“Sarah confirmed 50 seats at $360/seat ($18K). Signed SOW coming Friday.”，hs_timestamp=昨日 16:12）→ 联系人已存在无需创建宣布 → 汇报含商机链接。

该示例说明“happy path”成立的条件：商机关联唯一无歧义、联系人已存在、线程主题可直接用作活动标题、摘要聚焦决策与数字而非全文转录。

7.2 Call 路径 + 缺失联系人：log-call-happy-path.md

场景：用户刚结束一场 30 分钟 Google Meet “Acme — technical deep dive”（10:00 开始），参会人有用户、sarah.lin@acme.com与ben.rivera@acme.com；Sarah 已在 “Acme Q2 Expansion” 商机上，Ben Rivera不在 HubSpot。用户只说“Log this call.”

关键行为：无指定事件 → 回退到最近 24 小时内最近一次已完成会议，并先确认（“Logging the 'Acme — technical deep dive' call from 10:00am this morning — correct?”）→ 查找ben.rivera@acme.com不存在 →先宣布创建（“Ben Rivera (ben.rivera@acme.com) isn't in HubSpot. Creating the contact and associating to the Acme Q2 Expansion deal.”）→ 创建联系人（email、firstname: Ben、lastname: Rivera、company 由邮箱域名推断为 Acme）并关联商机 → 写入 Call 活动（标题、body 为占位符“Meeting held; notes to be added.”并提示用户补充、时长 30 分钟、时间戳 10:00、关联 Sarah + Ben 两个联系人）→ 汇报中含“创建了新联系人 Ben Rivera”“body 是占位符，如需可补充笔记”等关键信息。

该示例演示了：未指定事件的回退逻辑、对推断上下文的确认、从邮箱域名推断公司、无会议笔记时用占位符 body 并通知用户、同一活动关联“已存在 + 新建”多个联系人。

7.3 Cleanup 路径：完整商机审计 cleanup-deal.md

场景：商机 “Acme Q2 Expansion”（阶段 Proposal Sent、$18K、5 月 15 日结单、next step “send pricing”、hs_lastactivitydate为 22 天前），关联 Sarah 与 Ben；近 14 天邮件含 4 月 18 日线程（Sarah 确认价格并说“we'll sign once our legal review wraps, should be mid-June”）；4 月 20 日 “Acme — legal review walkthrough” 会议出现新参会人maria.chen@acme.com（不在 HubSpot、不在商机上）。用户说“Clean up the Acme Q2 Expansion deal.”

Skill 在未写任何数据的情况下产出如下审查清单（这正是第七节检查清单的落地）：

1. 最后活动日期：商机显示 22 天前，但发现 4/18 邮件与 4/20 会议均未入账 → 建议补录为活动（无需动商机本身，记录活动会自动更新hs_lastactivitydate）。
2. Next-step：当前 “send pricing”，而 4/18 邮件表明价格已发出并获确认 → 建议改为 “wait for legal review sign-off”。
3. 阶段：无阶段移动证据（Sarah 说法律审查之后才签）→仅标记，不改。
4. Close date：当前 5/15，邮件说 “should be mid-June” → 建议 5/15 → 6/15。
5. Amount：$18K 与邮件确认的 50 seats × $360 一致 → 无需动作。
6. 关联联系人：Maria Chen 参加 4/20 会议但不在商机、不在 HubSpot → 建议创建联系人并关联商机。
7. 笔记卫生：近 90 天无冲突笔记 → 无需动作。

用户回复“除第 4 项外全部批准（close date 别动，她可能过于乐观）”。Skill 随后：补录 4/18 邮件与 4/20 会议活动、更新 next-step、不改 close date、创建 Maria Chen 并关联商机。最终汇报逐项列出已写入与未改动的项目。

该示例完整演示了：检查清单 7 项全部落地的输出格式（标记了什么、证据是什么——邮件主题 + 日期或会议标题 + 日期、建议动作或“仅标记”）、每项建议的“当前 → 建议”并排呈现、阶段变更被正确扣为仅标记、用户选择性批准时精确执行所选子集、联系人创建并入同一审批周期。

八、清理检查清单：七项审计维度的证据标准

cleanup-checklist.md 定义了清理路径必须逐项走查的七个维度，以及触发标记所需的证据。任何基于该 Skill 的清理流程都应照此执行，并以“编号列表 + 证据 + 建议动作”的格式呈现，逐项或批量征求批准。

1. 最后活动日期（hs_lastactivitydate）：商机最近活动是否早于关联联系人最近一次真实互动？若近 14 天存在比hs_lastactivitydate更新的邮件/会议，建议补录缺失活动（不要直接改商机，记录活动会自动刷新该字段）。
2. Next-step 字段（hs_next_step）：当前值是否仍反映最新邮件/会议达成的共识？证据如字段写着 “send pricing” 但后续邮件显示价格已发、或字段为空而会议明确约定了下一步 → 建议新值（若步骤已完成可建议清空），并排展示当前 → 建议。
3. 商机阶段（dealstage）：近期互动是否暗示阶段移动（proposal 已发、合同已签、输给竞对）？证据如 “we're moving forward”“we signed”“we went with [competitor]” 或会议频率变化 →仅标记，绝不自动改阶段，摆出证据交由用户决策。
4. 结单日期（closedate）：最新邮件/会议是否提及与当前值冲突的时间线？证据如 “pushing to Q3”“we'll sign by end of month”“delayed until next quarter” → 建议更新日期，并排展示。
5. 金额（amount）：最新互动是否提及不同规模？证据如定价邮件中的修订价格、会议扩大的范围或客户接受的缩减范围 → 建议更新金额，并排展示。
6. 关联联系人：近期与商机联系人互动的邮件/会议中，是否存在未关联到商机的人？证据如邮件抄送或会议参会人的域名与既有商机联系人同域但不在商机上 → 建议补充缺失联系人（若不存在则先在 HubSpot 创建）。
7. 笔记卫生：是否有超过 90 天、与当前商机状态明确冲突的笔记或活动？证据如写着 “customer is lost” 但商机仍处于未关闭阶段、或笔记中的合同金额已过时 →追加新笔记澄清当前状态，绝不编辑或删除旧笔记——只追加，不重写历史。

九、审批门禁总览：五条不可逾越的红线

无论是 Skill 直接触发还是经/crm-cleanup批量触发，SKILL.md 与 crm-cleanup/SKILL.md 共同定义了如下红线，这也是将该 Skill 接入自有 CRM 自动化流程时必须保留的安全护栏：

十、从源码结构看 Skill 的工程组织与二次实现要点

从仓库目录结构看，crm-maintenance采用“主流程 SKILL.md + 领域知识 reference + 示例 examples”的分层组织，这本身就是可复用的工程模式：

• small-business/skills/crm-maintenance/SKILL.md：可执行主流程（意图识别 → 上下文 → 解析 → 执行 → 门禁 → 汇报）；
• reference/hubspot-fields.md：字段/活动/关联规则的唯一事实来源（source of truth），保证主流程与参考文档不会各说各话；
• reference/cleanup-checklist.md：审计维度的证据标准，独立于执行流程，可单独复用；
• reference/gotchas.md：反模式行为准则，用 Bad/Good 对比约束输出质量；
• reference/examples/*.md：三条路径各一个可验证的端到端工作示例。

与之配套的/crm-cleanup命令（crm-cleanup/SKILL.md）则演示了“命令包装技能”的写法：命令负责批量扫描与参数解析（--scope），将具体字段审计委托给crm-maintenance的清理工作流，并继承其全部审批门禁。

十一、安装与启用

在 Cowork 中，从插件市场安装small-business插件即可获得crm-maintenanceSkill 与/crm-cleanup命令；使用 Claude Code 时可通过插件市场命令安装。使用前需在 Cowork 设置中连接HubSpot（必需），并建议连接Gmail / Google Calendar（可选）以提供邮件与日历上下文；/crm-cleanup要求 HubSpot 可达，否则命令会停止并提示先在 Cowork 设置中连接。安装完成后，直接对 Claude 说“log this call to the Acme deal”“update the CRM”“clean up HubSpot”即可触发对应路径。

【免费下载链接】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