KPI 警报系统技能

面向企业财务健康状况的自动化 KPI 监控与阈值警报系统。支持从 QuickBooks Online（QBO）、Google Sheets 或 CSV 导出文件中拉取数据，执行规则评估，并向 Telegram / Slack / 邮件发送警报。

支持的 KPI 指标

配置步骤

1. 定义 KPI 配置

为客户端或事务所创建一个 YAML 配置文件：

# kpi-config-clientname.yaml
client: "Acme Corp"
alert_channels:
  - type: telegram
    target: "@irfan_dm"  # 或频道 ID
  - type: slack
    webhook: "https://hooks.slack.com/services/..."
  - type: email
    to: "imussa@precisionledger.io"

kpis:
  ar_aging_90plus:
    label: "AR 90+ Days"
    source: qbo  # 或 sheets、csv
    threshold_red: 15000
    threshold_yellow: 8000
    message: "AR aging 90+ days is ${value} — collections action needed"

  cash_runway_months:
    label: "Cash Runway"
    source: qbo
    threshold_red: 3
    threshold_yellow: 6
    direction: below  # 当数值低于阈值时触发警报（默认为 above）
    message: "Cash runway is {value} months — review burn rate immediately"

  revenue_growth_mom:
    label: "MoM Revenue Growth"
    source: sheets
    sheet_id: "1BxiM..."
    tab: "P&L Summary"
    cell_range: "C5"
    threshold_red: -5
    threshold_yellow: 0
    direction: below
    message: "Revenue growth is {value}% MoM — investigate pipeline"

  gross_margin_pct:
    label: "Gross Margin %"
    source: qbo
    threshold_red: 30
    threshold_yellow: 40
    direction: below
    message: "Gross margin at {value}% — below target of 40%"

2. 数据源集成

QuickBooks Online（通过 QBO Automation 技能）

# 拉取当月利润表摘要
qbo report pl --period this-month --format json > /tmp/pl-current.json

# 拉取应收账款账龄报告
qbo report ar-aging --format json > /tmp/ar-aging.json

# 拉取资产负债表以计算流动性比率
qbo report balance-sheet --period this-month --format json > /tmp/bs-current.json

Google Sheets（通过 gog 技能）

# 读取已命名的数据范围
gog sheets read --id SHEET_ID --range "KPI Dashboard!B2:C20"

CSV / Excel 导出文件

将导出文件置于统一路径，并在配置中引用：

source: csv
file: "/tmp/monthly-export-2026-03.csv"
column: "AR_90plus"
row_filter: "Month=March"

3. KPI 评估逻辑

核心算法（Python 伪代码供参考）：

def evaluate_kpi(config, value):
    direction = config.get("direction", "above")
    
    if direction == "above":
        if value >= config["threshold_red"]:
            return "RED", config["message"].format(value=value)
        elif value >= config["threshold_yellow"]:
            return "YELLOW", config["message"].format(value=value)
    else:  # below
        if value <= config["threshold_red"]:
            return "RED", config["message"].format(value=value)
        elif value <= config["threshold_yellow"]:
            return "YELLOW", config["message"].format(value=value)
    
    return "GREEN", None

def run_kpi_check(config_path):
    config = load_yaml(config_path)
    alerts = []
    
    for kpi_id, kpi_config in config["kpis"].items():
        value = fetch_kpi_value(kpi_config)  # 从 QBO / Sheets / CSV 拉取
        status, message = evaluate_kpi(kpi_config, value)
        
        if status in ["RED", "YELLOW"]:
            alerts.append({
                "kpi": kpi_config["label"],
                "status": status,
                "value": value,
                "message": message
            })
    
    return alerts

4. 警报格式化

Telegram 消息格式：

🚨 KPI ALERT — Acme Corp
Date: March 15, 2026

🔴 AR 90+ Days: $18,500
   → Collections action needed immediately

🟡 Gross Margin: 38%
   → Below 40% target — review COGS

✅ Cash Runway: 8.2 months
✅ Revenue Growth: +4.2% MoM

Run by: Sam Ledger / PrecisionLedger

Slack 格式（含附件）：

{
  "attachments": [
    {
      "color": "#ff0000",
      "title": "🔴 AR 90+ Days — $18,500",
      "text": "Collections action needed. 90+ day bucket exceeds $15,000 threshold.",
      "footer": "KPI Alert System | PrecisionLedger",
      "ts": 1742076000
    }
  ]
}

5. 使用 OpenClaw Cron 进行调度

月度 KPI 检查（每月 1 日上午 9 点 CST）：

{
  "name": "Monthly KPI Check — Acme Corp",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 1 * *",
    "tz": "America/Chicago"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "Run KPI alert check for Acme Corp using kpi-config-acme.yaml. Pull QBO AR aging and P&L, evaluate thresholds, and send alerts to the configured channels."
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce"
  }
}

周度现金跑道检查（每周一上午 8 点 CST）：

{
  "name": "Weekly Cash Runway Check",
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * 1",
    "tz": "America/Chicago"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "Check cash runway and burn rate for all active clients. Alert if any client is below 6 months runway."
  },
  "sessionTarget": "isolated"
}

示例提示词

配置

“为我的客户 TechStartup LLC 配置 KPI 警报。当应收账款账龄达 90 天、烧钱率超过 $40k/月，或现金跑道低于 4 个月时，在 Telegram 上通知我。”

手动检查

“立即对 Acme Corp 执行一次 KPI 检查，并告诉我哪些阈值已被突破。”

阈值调整

“将 TechStartup 的毛利率警报阈值更新为：黄色预警线设为 45%，红色警戒线设为 35%。”

报告生成

“为所有活跃客户生成一份周度 KPI 汇总报告，并发布至 #weekly-metrics Telegram 频道。”

KPI 计算参考

Cash Runway（现金跑道）

Runway (months) = Current Cash Balance / Average Monthly Burn Rate
Average Monthly Burn = (Cash 3 months ago - Cash today) / 3

Days Sales Outstanding（DSO，应收账款周转天数）

DSO = (Accounts Receivable / Revenue) × 30

Burn Rate（烧钱率）

Net Burn = Total Cash Outflows - Total Cash Inflows (monthly)
Gross Burn = Total Cash Outflows only (monthly)

Current Ratio（流动比率）

Current Ratio = Current Assets / Current Liabilities

AR Aging Concentration Risk（应收账款账龄集中风险）

90+ Day Concentration = AR 90+ days / Total AR × 100
Alert when concentration > 20%

多客户监控模式

适用于管理多个客户的事务所：

# master-kpi-config.yaml
clients:
  - name: "Acme Corp"
    config: "./clients/acme/kpi-config.yaml"
    qbo_realm: "123456789"
  
  - name: "TechStartup LLC"
    config: "./clients/techstartup/kpi-config.yaml"
    qbo_realm: "987654321"
    
  - name: "Retail Co"
    config: "./clients/retailco/kpi-config.yaml"
    data_source: csv
    csv_path: "/data/retailco/monthly-export.csv"

循环处理模式示例：

“检查 master-kpi-config.yaml 中所有客户的 KPI 阈值，并将警报汇总为一条 Telegram 消息，按客户分组呈现。”

负向边界 — 不应使用本技能的场景

• 实时股票/加密货币价格警报 → 应使用 defi-position-tracker 或专用市场数据流
• 实时 BI 看板（图表、下钻分析）→ 应使用 Power BI、Looker 或 Metabase
• ERP 系统（SAP、Oracle、NetSuite）→ 需要专用 API 连接器，不适用本技能
• 亚分钟级警报（高频交易信号）→ 本技能延迟等级不适用
• PTIN 监管的税务分析 → 应使用 qbo-to-tax-bridge（仅限 Moltlaunch 服务）
• 面向客户的自动化报表 → 发送至外部前须经 Irfan 批准
• 向 QBO 写入操作 → 默认为只读；记账凭证需明确审批

集成技术栈

警报严重性指南

KPI Alert System — PrecisionLedger 技能 v1.0.0