统计与 KPI API

1 分钟 · 184 字中文

统计端点、集群 KPI 以及面向 LLM 智能体的 tidy-long KPI 导出（CSV/JSON/XLSX）。

Synapse 提供只读统计信息，涵盖智能体健康、API 用量、趋势与集群 KPI。所有端点均接受 MindKey（Authorization: Bearer）或用户 JWT（requireMindOrUser）。

现有分析路由（见 WebUI 中的 /stats 页面）：

路由	用途
`GET /stats/agent`	所有智能体概览（周期：`days`）
`GET /stats/agent/comparison`	跨智能体对比
`GET /stats/agent/:mindName`	单个智能体的详细统计
`GET /stats/agent/:mindName/health`	健康评分
`GET /stats/agent/:mindName/heatmap`	活动热力图
`GET /stats/agent/:mindName/sessions`	会话追踪器
`GET /stats/api`	API 用量（全局）
`GET /stats/trends`	时间序列
`GET /stats/chat/response-times`	聊天响应时间
`GET /stats/a2a/flow`	A2A 消息流
`GET /stats/cron`	定时任务分析
`GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring`	仪表盘聚合

GET /export/kpis

运维 KPI 的 tidy-long 导出（任务 7418541b）。数据的事实来源是 src/db/stats.ts —— 导出层只做扁平化，本身不做任何测量。

GET /export/kpis?format=csv|json|xlsx&days=7

参数	取值	默认
`format`	`csv` · `json` · `xlsx`	`json`
`days`	`1`–`365`（智能体概览的时间窗）	`7`

响应：

format=json → { generated_at, period_days, format: "long", columns, row_count, rows[] }
format=csv → text/csv; charset=utf-8（RFC 4180、BOM、CRLF），以附件形式返回
format=xlsx → Excel 工作簿（单一工作表 KPIs），以附件形式返回

tidy-long 列（所有格式相同）：

列	含义
`kategorie`	KPI 组：`fleet`、`summary`、`backlog`、`activity`、`team`、`monitoring`、`agent_overview`
`metrik`	扁平化后的指标路径（如 `throughput.done_24h_total`）
`wert`	标量值（数字、文本，或当只有 `detail` 承载数据时为 `NULL`）
`einheit`	`value` · `count` · `text` · `json`
`zeitstempel`	导出生成的 ISO-8601 时间戳
`quelle`	`src/db/stats.ts` 中的来源函数
`detail`	用于数组/深层对象的 JSON 载荷，否则为空

示例：

curl -s -H "Authorization: Bearer $MIND_KEY" \
  "https://synapse.schaefer.zone/export/kpis?format=csv&days=7" -o kpis.csv

WebUI 的 /stats 页面在「KPI export」区域以三个下载按钮（CSV/JSON/XLSX）呈现同一导出。