knowledge-work-plugins 中小企业 Business Pulse 数据源映射实战:QuickBooks、HubSpot、Gmail 等连接器的并行指标拉取指南

原创2026-09-14 22:39:062,216 阅读
文章标签:人工智能AI 技能插件系统提示工程企业应用协同办公

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 中与数据源拉取直接相关的四条:

  1. QuickBooks 返回意外状态——空响应/同步中/鉴权错误不算"无数据"。必须显式标注 "n/a — QuickBooks unavailable" 并写入附录,防止老板误判后白费时间重连。
  2. Gmail 中途鉴权失败——静默跳过 Watch List,附录记录原因,其余段落不受影响。老板得到的是"知情而非惊吓"。
  3. 拉取前征求许可——技能被调用即代表数据拉取已被默许,问"要不要我查 QuickBooks"会摧毁技能的自主价值,属反模式。
  4. 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" 等话术获取窄口径版本。

登录后查看全文
knowledge-work-plugins