knowledge-work-plugins 小企业现金流快照技能:基于 QuickBooks 与 PayPal 数据的 30/60/90 天现金流预测实战指南
knowledge-work-plugins 小企业现金流快照技能:基于 QuickBooks 与 PayPal 数据的 30/60/90 天现金流预测实战指南
导读
cash-flow-snapshot 是 knowledge-work-plugins 仓库中 small-business 插件内置的一项现金流预测技能:它读取 QuickBooks、PayPal、Stripe、Square 等连接器或 CSV 上传的应收(AR)、应付(AP)与历史回款时序数据,产出带百分比方差置信区间和具名风险标志的 30/60/90 天现金流预测,并以"聊天摘要 + 可下载 XLSX 工作簿"双通道交付。读完本文,你将掌握从数据源识别、历史回款节奏计算、置信区间公式、风险命名到 XLSX 三表结构输出的完整实现链路,并理解其底层边界条件与失败模式。
一、技能定位与触发场景
该技能的核心产出是30/60/90 天现金流预测:对每个时间窗口给出期望净现金流、低带与高带估计,并对具体的流动性风险逐条命名。其典型用户问题是:
- "Will I make payroll next month?"(下个月发得出工资吗)
- "Forecast my cash flow"(预测我的现金流)
- "Will I make payroll" / 提到 "runway"(现金跑道)
- "Cash crunch"(现金吃紧)
在 small-business/README.md 中,该技能作为多个工作流的基础构件出现:/plan-payroll(现金流预测 + 逾期发票催收,确保工资有保障)、/month-heads-up(30 天现金流前瞻与早期风险标志)、/quarterly-review(季度业务回顾)。技能本身是只读的:不执行任何破坏性操作,因此生成预测前无需审批门(approval gate)。
兼容性前提:需要 QuickBooks MCP、PayPal MCP、Stripe MCP、Square MCP 中的一个或多个,或在无连接器时回退到 CSV 文件上传;输出环节依赖 xlsx 技能(文档中读取 xlsx/SKILL.md 的约定详见 cash-flow-snapshot/SKILL.md)。
二、六步工作流全解析
Step 1 — 识别可用数据源
按下述优先级尝试连接器:
- QuickBooks — AR 账龄、AP 与固定成本的主要来源;
- PayPal — 交易历史与结算时序;
- Stripe — 收款与付款历史;
- Square — 销售与付款历史;
- CSV 上传 — 无连接器时的回退方案。
若没有连接器在线且无文件附件,应向用户说明:请连接数据源或上传 CSV(收入/支出表格数据,任意合理格式均可)。必须在输出中注明实际使用的数据源——数据源集合直接影响置信区间的宽度:仅依赖 CSV 而无实时 AP/固定成本数据时,区间会比正常更宽(见第五步"No-connector warning")。
Step 2 — 拉取数据
来自 QuickBooks:
- AR 账龄报告:客户名、发票金额、发票日期、到期日、逾期天数;
- AP:供应商名、应付金额、到期日;
- 经常性固定成本:租金、工资、订阅(查找重复发生的交易)。
来自 PayPal / Stripe / Square:
- 结算历史:交易日期、金额、结算日期;
- 用结算滞后(交易日期 → 付款日期)计算每个数据源的平均付款延迟与方差。
来自 CSV 上传:
- 按收入/支出表格数据解析;
- 必填列(列名可灵活):date(日期)、amount(金额)、type(类型:income/expense)、description(描述);
- 若列含义存在歧义,展示表头行并请用户确认映射,而不是静默猜测。
Step 3 — 计算历史回款时序
对每个 AR 客户(或 CSV 中的收入来源)计算:
- 平均付款滞后(mean payment lag)——发票/交易日期到实际到账的平均天数;
- 付款方差(payment variance)——最近 6~12 笔付款的滞后天数标准差;
- 方差用于设置置信区间宽度(见 Step 4)。
数据不足的兜底规则:若某客户付款记录少于 3 笔,则以总体均值作为点估计,并施加默认 ±30% 方差区间;而当 CSV 数据足够(每个来源 ≥3 笔付款)时,必须从实际付款方差计算区间,不得默认 ±30%。
Step 4 — 构建 30/60/90 天预测
三个时间窗口:0–30 天、31–60 天、61–90 天。每个窗口计算:
| 行项目 | 计算方法 |
|---|---|
| 期望流入(Expected inflows) | 窗口内到期的 AR,按平均付款滞后调整 |
| 期望流出(Expected outflows) | 窗口内到期的 AP + 落在窗口内的固定成本 |
| 净现金头寸(Net cash position) | 流入 − 流出 |
| 置信区间(Confidence band) | ± 加权平均付款方差(以期望流入的百分比表示) |
置信区间公式(原文档完整继承):
band_pct = weighted_avg_stddev_days / avg_payment_lag_days
low = net_cash × (1 − band_pct)
high = net_cash × (1 + band_pct)
band_pct 四舍五入到一位小数,上限 ±50%:更高的方差意味着数据过稀、不足以建模,此时不再扩大区间,而是转为风险标志(见 Step 5)。
Step 5 — 命名具体风险
扫描使低带估计为负或造成流动性危机的条件,对每条风险输出一行标志:
- 迟付客户风险(Late-payer risk):"Customer X historically pays 18 days late; that shifts their $8,400 invoice out of the 30-day window into day 48."(客户 X 历史上平均迟付 18 天,其 $8,400 发票从 30 天窗口滑出到第 48 天。)
- 工资发放危机(Payroll crunch):"Payroll ($22,000) hits April 15. Low-band cash on hand April 14: $19,200. Shortfall risk: $2,800."(工资 $22,000 于 4 月 15 日到期,4 月 14 日低带现金余额 $19,200,缺口风险 $2,800。)
- 数据稀薄警告(Thin data warning):"Only 2 payments on record for Customer Y — confidence band set to default ±30%."(客户 Y 仅有 2 笔付款记录,置信区间设为默认 ±30%。)
- 无连接器警告(No-connector warning):"Running on CSV data only — no real-time AP or recurring cost data. Confidence bands are wider than normal."(仅基于 CSV 数据运行,无实时 AP 或经常性成本数据,置信区间比正常更宽。)
风险最多取严重度前 5 条(按美元影响金额从大到小排序)。
Step 6 — 交付双通道输出
聊天摘要(始终生成):
Cash Flow Snapshot — [日期范围]
Source(s): [使用的连接器]
Expected Low High
30-day net: $X,XXX $X,XXX $X,XXX
60-day net: $X,XXX $X,XXX $X,XXX
90-day net: $X,XXX $X,XXX $X,XXX
⚠ Risks flagged: [数量]
• [风险 1]
• [风险 2]
...
XLSX 工作簿(始终生成):生成前先读取 xlsx/SKILL.md(该技能的约定见 cash-flow-snapshot/SKILL.md,同一仓库中 month-end-prep 与 close-month 也引用该输出约定)。工作簿含三个 Sheet:
- Summary —— 30/60/90 预测表与置信区间。每个窗口行下方内嵌展开子行,展示构成其流入(绿色)与流出(红色)的逐笔交易,使估算在不离开 Summary 表的情况下即可审计。
- Detail —— 全部交易按窗口分组、组内按日期排序;含组内累计净额列(窗口内累计流入减流出),每个窗口底部有小计行(总流入、总流出、净额)。已发生的历史交易单独放在底部区域置灰以供参考。即使某窗口为空也必须保留行,显示 "No transactions in this window" 占位行。
- Risks —— 被标记的风险,附美元影响额与受影响窗口。
文件命名为 cash-flow-snapshot-[YYYY-MM-DD].xlsx。
交付后提醒(每次都要附上):
"This forecast is based on [sources listed]. It is not a substitute for accounting advice — verify with your bookkeeper before making financing decisions." (本预测基于所列数据源,不能替代会计建议——在做出融资决策前请与你的簿记员核实。)
三、参考文件与边界条件(gotchas)
技能附带 reference/gotchas.md,记录了连接器异常与边界条件的五种典型失败模式,按 Good/Bad 对照给出处理规范:
- QuickBooks AR 账龄包含已收款项:账龄导出有时会包含余额为 $0 的已全额收款发票,直接计入会虚增流入预测。规范做法是过滤
balance_due > 0的 AR 行;若连接器不暴露balance_due,则先从发票总额中减去已知的 PayPal/Stripe 结算额再纳入。 - PayPal 结算滞后因交易类型而异:纠纷、新卖家、高额交易会被 PayPal 不同地冻结资金,不能用统一的 1–2 个工作日假设。应基于交易历史中的实际
transaction_date → completed_date对计算结算滞后,并按客户或交易类型分别计算均值与标准差。 - CSV 列名跨会计导出不一致:QuickBooks 导出用 "Transaction Date / Amount / Transaction Type",Wave 用 "Date / Amount / Account Type",硬性匹配会静默失败。应对列头做模糊匹配(date → transaction date → txn date;amount → debit/credit;type → category → account type),并先向用户展示表头行、确认映射后再计算——一次提问胜过一次静默的错误预测。
- 固定成本藏在一次性 AP 条目中:许多小企业并不一致地给固定成本打标签,租金可能以每月一笔供应商账单的形式出现。应查找同一供应商、相近金额(±10%)且连续出现 ≥3 个月以上的 AP 条目,将其视为经常性固定成本纳入预测,并向用户确认:"I'm treating these as fixed monthly costs — does that look right?"(我正将这些视为月度固定成本——看起来对吗?)
- 平均付款滞后为零时置信区间公式失效:Square POS 等即时结算客户的平均滞后为 0,直接相除会除零或产生无限区间。当平均滞后 ≤1 天时,直接将
band_pct设为 5%(低方差、近似即时结算),不做除法。
四、完整算例(worked example)
reference/examples/worked-example.md 给出了端到端算例,可验证每个步骤的输出形态。
场景:小型服务企业,连接 QuickBooks + PayPal,3 个活跃客户,月度工资、办公室租金。
输入数据(来自连接器)
AR 账龄(QuickBooks):
| Customer | Invoice | Amount | Due Date | Days Outstanding |
|---|---|---|---|---|
| Acme Corp | INV-112 | $8,400 | Apr 10 | 12 |
| BlueSky LLC | INV-108 | $14,200 | Apr 22 | 0 |
| Crestwood Inc | INV-115 | $6,000 | May 5 | — |
历史付款滞后(来自 PayPal 结算):
| Customer | Mean Lag | Std Dev | Payments on Record |
|---|---|---|---|
| Acme Corp | 18 days | 4 days | 11 |
| BlueSky LLC | 7 days | 2 days | 8 |
| Crestwood Inc | 12 days | 5 days | 6 |
固定成本(QuickBooks 经常性 AP):工资 $22,000(4 月 15 日扣款);租金 $3,200(5 月 1 日);软件订阅 $480(5 月 1 日)。
Step 3 输出 — 调整后到账日期:Acme 发票到期 4/10 + 18 天滞后 → 4/28 到账;BlueSky 到期 4/22 + 7 天 → 4/29 到账;Crestwood 到期 5/5 + 12 天 → 5/17 到账。
Step 4 输出 — 30/60/90 预测:加权平均标准差 3.6 天、加权平均滞后 12.7 天,band_pct = 3.6 / 12.7 = 28.3%(保留一位小数,且未触发 ±50% 上限与 ±30% 默认值):
| Window | Expected Inflows | Expected Outflows | Net | Low (−28%) | High (+28%) |
|---|---|---|---|---|---|
| 0–30d | $22,600 | $22,000 | +$600 | −$5,928 | +$7,128 |
| 31–60d | $6,000 | $3,680 | +$2,320 | +$1,670 | +$2,970 |
| 61–90d | $0 | $0 | $0 | — | — |
注意 30 天窗口:期望净额虽为正 $600,但低带为 −$5,928——这正是命名风险与区间并存的用意,避免被点估计的乐观表象误导。
Step 5 输出 — 风险标志:
- 工资发放危机:工资 $22,000 于 4/15 到期,而两笔 AR 到账均在 4/28–29,4/14 前低带流入为 $0,缺口风险高达 $22,000。建议:在 4/14 前与 Acme、BlueSky 确认回款时间。
- 迟付客户风险:Acme Corp 平均迟付 18 天,其 $8,400 发票(4/10 到期)被推至 4/28——落在工资发放之后。
Step 6 输出 — 聊天摘要(完整格式见 worked-example.md):输出 Cash Flow Snapshot — Apr 23 → Jul 21, 2026,Source(s): QuickBooks, PayPal;三窗口净额与低/高带;2 条风险逐条列出;注明 "Confidence band: ±28% (based on historical payment variance across 3 customers)";末尾附簿记核实的免责提醒。XLSX 文件名为 cash-flow-snapshot-2026-04-23.xlsx,含 Summary / Detail / Risks 三个 Sheet。
五、仓库中的落地位置与自定义建议
- 技能主文件:small-business/skills/cash-flow-snapshot/SKILL.md(含完整 frontmatter 的 name/description/compatibility 元数据,供 Agent 路由识别);
- 边界条件手册:small-business/skills/cash-flow-snapshot/reference/gotchas.md(连接器返回异常数据或方差极端时加载);
- 输出形态算例:small-business/skills/cash-flow-snapshot/reference/examples/worked-example.md(为新数据形态建模输出格式时加载);
- 插件层说明:small-business/README.md(技能在 15 个工作流中的组合方式,如
/plan-payroll、/month-heads-up)。
安装方式(Claude Code):claude plugin marketplace add anthropics/knowledge-work-plugins 后执行 claude plugin install small-business@knowledge-work-plugins。按 README 的自定义建议,可在 business-pulse 与 cash-flow-snapshot 中调整告警阈值以匹配你的业务规模,并将连接器替换为实际使用的工具。
结语
cash-flow-snapshot 的可贵之处在于它把"现金流预测"拆解为可审计、可复现的六步流水线:以历史回款方差驱动置信区间(而非拍脑袋的 ±30%),以具名风险取代模糊警告,以带逐笔明细的 XLSX 保证每个数字都可追溯。对小企业主而言,它回答的是最紧迫的问题——"下个月发得出工资吗";对 Agent 开发者而言,它是一个把数据源协商、统计建模、风险命名与多格式交付完整封装的优秀技能范本。