knowledge-work-plugins 中小企业 Business Pulse 数据源映射实战:QuickBooks、HubSpot、Gmail 等连接器的并行指标拉取指南
knowledge-work-plugins 中小企业 Business Pulse 数据源映射实战:QuickBooks、HubSpot、Gmail 等连接器的并行指标拉取指南
<输出文章>
knowledge-work-plugins 中小企业 Business Pulse 数据源映射实战:QuickBooks、HubSpot、Gmail 等连接器的并行指标拉取指南
导读
本文以 knowledge-work-plugins 仓库中 business-pulse 技能 的 data_sources.md 为核心骨架,完整讲解 Business Pulse(经营脉搏)从"每个脉冲模块"到"具体 MCP 工具"的精确映射关系、各连接器的降级兜底策略,以及"单次并行批处理"的调度约定。读完本文,你将掌握:如何一次性并行拉取 QuickBooks 现金/收入、PayPal/Square/Stripe 销售、HubSpot 管道、Google Calendar 承诺、Gmail 紧急事项、Slack/Teams 内部信号与 Intercom/Zendesk 工单,如何在单个连接器故障时优雅降级而不阻塞整个脉冲,以及如何按风险扫描规则把原始数据升级为可执行的经营简报。
一、Business Pulse 是什么:一份数据、一个页面
在 small-business 插件 中,business-pulse 被定义为 15 个原子技能之一:输入一句"how's the business doing""catch me up",输出一份跨职能的一页式经营快照,覆盖现金(QuickBooks)、销售趋势(PayPal/Square)、管道动态(HubSpot)、本周承诺(Calendar)、紧急事项(Watch List,Gmail/Slack)以及"今天最该做的一件事"。该技能是 /monday-brief、/friday-brief、/quarterly-review 三个命令的核心引擎(见 small-business/README.md 的命令表),且没有必选连接器——只连了一个源就出一份部分脉冲,全栈连接就出全貌。
data_sources.md 正是这份技能的"数据路由表":它定义了每一个脉冲段落(pulse section)由哪个 MCP 工具产出、按什么过滤条件取数、失败时如何处理。核心约定只有一句话——所有调用必须在单个并行批次中分发,绝不串行拉取,因为串行会把一个 30 秒的技能拖成漫长等待(该警告同时出现在 SKILL.md 的 Step 1)。
二、Cash & Finance(QuickBooks):现金流与应收的取数映射
| 指标 | 工具 | 取数说明 |
|---|---|---|
| 现金 / 银行余额 | cash-flow-quickbooks-account |
取当前余额;如有上周数据则展示周环比(WoW)delta |
| 本月至今收入(MTD revenue) | profit-loss-quickbooks-account |
本月 vs. 上月对比 |
| 未结应收款(Outstanding receivables) | QuickBooks invoice list | 过滤出 open / 未支付发票 |
| 应收账龄(AR aging) | QuickBooks invoice list | 按逾期天数分组:0–30、31–60、61+ 天 |
| 逾期发票(Overdue invoices) | QuickBooks invoice list | 过滤出 due_date 超 30 天的发票;点名客户 + 金额 + 逾期天数 |
这两个 QuickBooks 工具在整个 small-business 技能集 中被反复复用:例如 margin-analyzer/SKILL.md 用 profit-loss-quickbooks-account 拉取收入与 COGS 计算单产品毛利,content-strategy/SKILL.md 用同一工具做行业上下文的 pre-flight。可见它在本插件中承担"财务数据的唯一权威来源"角色。
QB 状态兜底(重要):若 cash-flow-quickbooks-account 返回错误、空响应或 "not connected" 状态,则把整个 Cash 段落标记为 "n/a — QuickBooks unavailable" 并继续,不要重试。这条规则背后的坑位记录在 gotchas.md 的 "QuickBooks returns unexpected state" 条目:QuickBooks 可能返回空结果、同步进行中状态或鉴权错误而不抛出硬异常。若把"静默"当作"没有数据",脉冲会整个跳过 Cash 段落,老板会误以为 QuickBooks 从未连接,花 10 分钟去重连一个一直连着但只是处于瞬时状态的应用。正确做法是保留段落标题并显式标注原因,同时在附录记录 "Sources unavailable: QuickBooks — returned empty response"。
三、Revenue & Sales(PayPal / Square / Stripe):多渠道销售汇总
| 指标 | 工具 | 取数说明 |
|---|---|---|
| 7 天结算总额 | PayPal transactions | 对窗口内已完成的结算求和 |
| 销售趋势 | PayPal transactions | 本周 7 天 vs. 前 7 天,计算 delta |
| 失败 / 待处理交易 | PayPal transactions | 标记任何 > $200 的交易 |
| Square 结算 | Square(若已连接) | 与 PayPal 相同——求和 + 趋势 |
| Stripe 收入 | Stripe list_invoices(若已连接) |
窗口内已付发票 |
映射表给出的原则是"用当前可用的支付连接器":如果 PayPal 和 Square 都连了,就分别报告各源数据并给出合并值。注意这里对失败的阈值是 > $200 即标记,而在风险扫描段落(见下文)中失败支付 > $200 也被列为触发条件,而 thresholds.md 给出了更细的分级:任何失败交易 > $200 为 🟡 黄灯,任何失败交易 > $1,000 或 一周内 ≥3 次失败为 🔴 红灯。这与 SKILL.md Step 3 中 "Failed or pending PayPal/Square transactions > $500" 的表述略有出入,实际落地时应以 thresholds.md 的分级为准——这类跨文件口径差异正是读者配置时需要核对的地方。
四、Pipeline(HubSpot):管道健康度取数
| 指标 | 工具 | 取数说明 |
|---|---|---|
| 按阶段管道金额 | get_crm_objects type=deals |
按 deal stage 分组并汇总金额 |
| 本周成交 deal | search_crm_objects |
过滤窗口内 closedate,stage = closed-won |
| 变冷 deal | search_crm_objects |
过滤 hs_last_activity_date > 7 天前,且处于 open stage |
| 本周新线索 | search_crm_objects |
过滤窗口内 createdate |
| 停滞 / 滑期 deal | search_crm_objects |
open deal 且 closedate < 今天 |
HubSpot 是插件三大"核心工具"之一(见 small-business/README.md),这里的 get_crm_objects 与 search_crm_objects 是全插件通用的 CRM 读写入口(crm-maintenance、lead-triage 等技能同样依赖它)。在 Business Pulse 语境下,关键是把"管道覆盖率"算出来:加权管道金额 ÷ 月收入目标,其 🟢/🟡/🔴 阈值在 thresholds.md 中定义为 ≥2x 目标为绿、1–2x 为黄、<1x 为红(该目标标注为 # TODO: confirm target with owner,首次输出时须提示老板调参)。
五、Commitments(Google Calendar):本周与未来 7 天承诺
| 指标 | 工具 | 取数说明 |
|---|---|---|
| 本周关键事项 | list_events |
过滤到当前周;浮出客户会议、截止日期、重要约定 |
| 未来 7 天 | list_events |
前瞻视图;突出任何涉及外部人员的安排 |
该段落在输出模板(output_template.md)中对应 "📅 This Week" 一节,且明确限定 3–5 条上限,剔除纯内部日历噪音——这是"一页简报"纪律的体现:不是把日历全量倾倒,而是只保留对老板决策有意义的对外承诺。
六、Watch List(Gmail):紧急事项检索与静默降级
| 指标 | 工具 | 取数说明 |
|---|---|---|
| 紧急线程 | search_threads |
查询 is:important OR is:starred 最近 7 天 |
| 客户升级事件 | search_threads |
查询 "escalation""complaint""cancel""refund""urgent" 等词,最近 7 天 |
| 时效敏感请求 | search_threads |
is:unread + "deadline""ASAP""today" 等关键词 |
search_threads 同样是插件内的通用邮件检索入口(contract-review 的 gmail-fetch.md 用它按附件过滤检索合同邮件;customer-pulse/SKILL.md 用它拉取 refund cancel unhappy... 等负面关键词线程)。
Gmail 兜底(重要):如果 Gmail 调用报错(文档明言"auth flaky — this is a known issue"),则静默跳过 Watch List 段落,只在附录标注 "Gmail unavailable",绝不把错误抛到脉冲正文。这条规则在 gotchas.md 中有完整的好/坏对比:坏做法是正文中出现 "Error: Gmail authentication failed",让老板看到一台"坏掉的工具";好做法是照常输出其余所有段落,附录记为 "Gmail — auth error; Watch List unavailable this run"。这是"脉冲以已交付内容为先"原则的典型体现。
七、Internal Signals(Slack/Teams)与 Customer Support(Intercom/Zendesk)
| 段落 | 指标 | 工具 | 取数说明 |
|---|---|---|---|
| Internal Signals | 紧急线程 | Slack search(若连接) | 老板相关频道中带 @提及或紧急信号的线程 |
| Internal Signals | 行动项 | Slack search | 直接发给老板或标记需跟进的消息 |
| Customer Support | 未结工单 | Intercom search_conversations / Zendesk |
统计未结数;标记任何 > 48h 未解决 |
| Customer Support | 升级事件 | Intercom search_conversations |
过滤 priority 或 tagged escalation |
两段的共同纪律是"仅当连接器可用时才纳入,否则整个段落直接省略"。Intercom 的 search_conversations 在 customer-pulse/SKILL.md 中有更细的用法参考:先 search_conversations 拿到会话 ID 列表,再对每个 ID 调用 get_conversation 取完整 conversation_parts,且只保留 author.type === 'user' 的消息(排除 admin/bot),以提取客户原声——可作为深入使用 Intercom 的延伸阅读。
八、Risks scan:与指标拉取并行的风险扫描
风险扫描被要求"与指标拉取同时进行——不要等指标先跑完":
| 风险 | 来源 | 触发条件 |
|---|---|---|
| 逾期应收 | QuickBooks invoices | due_date 超 30 天且未支付 |
| 停滞 deal | HubSpot | open deal,7+ 天无活动 |
| 滑期 deal | HubSpot | open deal,closedate 已过去 |
| 紧急 Gmail 线程 | Gmail | is:important 或升级关键词 |
| 失败支付 | PayPal / Square | 失败或待处理 > $200 |
风险与指标的差异在于可执行性:SKILL.md Step 3 明确"每条风险必须点名具体记录和下一步动作"——"有一些逾期发票"是废话,而"Acme Corp 欠 $3,400,逾期 47 天,自 3 月 12 日以来无回复"才可执行。风险分层还影响整体状态汇总:在 thresholds.md 的 rollup 规则中,脉冲整体状态默认取最差段落状态,但若有任意一条风险点名了具体客户、带美元金额且截止日期在 7 天内,无论各段落颜色如何整体直接滚升为 🔴——这是把"名字 + 美元 + 期限"的规则从段落级提升到了简报级。
九、Parallelization:8–15 次并行的调度约定
收尾段落给出全文的执行约束:
- 上述全部调用应在一个单一工具调用批次中触发;
- 一份完整脉冲典型是 8–15 次并行调用;
- 若其中一个报错,其余照常执行,失败源出现在简报底部的 "Sources unavailable"(即附录)中。
这从调度层面解释了为何 data_sources.md 开头就强调"绝不串行":延迟是串行拉取的最大敌人,并行批量是让技能保持在"30 秒级体验"的关键。结合 SKILL.md 的 Step 1,八个连接器(QuickBooks、PayPal/Square、HubSpot、Google Calendar、Gmail、Slack/Teams、Intercom/Zendesk、Shopify/Square)全部"同时尝试",任何单一集成失败都不阻塞脉冲。
十、把数据源映射落到一页输出上
data_sources.md 只是路由层,它的产出最终要套进 output_template.md 的固定结构:# Business Pulse 头 + 整体状态 + TL;DR + 💰 Cash & Finance + 📈 Revenue & Sales + 🔮 Pipeline + 📅 This Week + ✉️ Watch List + ⚠️ #1 Priority + Appendix。映射关系与模板的对应是双向强制的:
- 模板中的每个
{{变量}}都必须由对应连接器的数据填充,连接器无数据就整节省略,绝不保留空标题; - 每个数字必须带环比 delta(箭头约定:▲ 升、▼ 降、▬ 平,delta 值紧随箭头),无历史基线时写 "(no prior baseline)" 而不是留空(见 SKILL.md 的 "What not to do");
- 阈值分级(🟢/🟡/🔴)由 thresholds.md 提供,默认值是保守起点,文档建议使用 4 周后重新校准——健康企业会感觉永远全绿,应当收紧到"老板真正想采取行动的位置";
- 附录须列出数据窗口、成功来源列表、不可用来源(含原因,如 "Gmail — auth error")、以及仍使用默认值的 TODO 阈值。
十一、常见故障模式速查
汇总 gotchas.md 中与数据源拉取直接相关的四条:
- QuickBooks 返回意外状态——空响应/同步中/鉴权错误不算"无数据"。必须显式标注 "n/a — QuickBooks unavailable" 并写入附录,防止老板误判后白费时间重连。
- Gmail 中途鉴权失败——静默跳过 Watch List,附录记录原因,其余段落不受影响。老板得到的是"知情而非惊吓"。
- 拉取前征求许可——技能被调用即代表数据拉取已被默许,问"要不要我查 QuickBooks"会摧毁技能的自主价值,属反模式。
- Slack 写操作需显式确认——Slack 写不在标准验证路径内且会广播到团队可见频道,必须在老板明确回复"要 + 频道名"后才执行(见 SKILL.md Step 5 的"只问一次"约定)。
十二、上手方式与调参路径
本技能无必选连接器、可优雅降级,是最容易先跑起来的一类技能。建议接入顺序参考 small-business/README.md:"先连一两个就能立刻看到价值"——优先 QuickBooks(财务全栈的基础)、PayPal(交易数据)与 HubSpot(CRM 管道),再按需补 Gmail、Google Calendar、Slack、Stripe/Square。安装后在 Claude Code 中执行:
claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install small-business@knowledge-work-plugins
随后用 "set me up" 触发 smb-onboard 完成业务上下文登记,再对老板说一句 "catch me up on the business" 即可体验并行拉取的一页脉冲。若要调参,改 thresholds.md 中的红黄绿切点(所有标注 # TODO: confirm with owner 的项会在首次输出时提示老板),并按 SKILL.md 的 Scope variants 用 "just cash""pipeline only""quick snapshot before a call" 等话术获取窄口径版本。