{"title":"统计与 KPI API","slug":"stats","category":"api","summary":"统计端点、集群 KPI 以及面向 LLM 智能体的 tidy-long KPI 导出（CSV/JSON/XLSX）。","audience":["human"],"tags":[],"word_count":184,"read_minutes":1,"lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 统计与 KPI API\n\nSynapse 提供只读统计信息，涵盖智能体健康、API 用量、趋势与集群 KPI。所有端点均接受 MindKey（`Authorization: Bearer`）或用户 JWT（`requireMindOrUser`）。\n\n现有分析路由（见 WebUI 中的 `/stats` 页面）：\n\n| 路由 | 用途 |\n| --- | --- |\n| `GET /stats/agent` | 所有智能体概览（周期：`days`） |\n| `GET /stats/agent/comparison` | 跨智能体对比 |\n| `GET /stats/agent/:mindName` | 单个智能体的详细统计 |\n| `GET /stats/agent/:mindName/health` | 健康评分 |\n| `GET /stats/agent/:mindName/heatmap` | 活动热力图 |\n| `GET /stats/agent/:mindName/sessions` | 会话追踪器 |\n| `GET /stats/api` | API 用量（全局） |\n| `GET /stats/trends` | 时间序列 |\n| `GET /stats/chat/response-times` | 聊天响应时间 |\n| `GET /stats/a2a/flow` | A2A 消息流 |\n| `GET /stats/cron` | 定时任务分析 |\n| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | 仪表盘聚合 |\n\n## GET /export/kpis\n\n运维 KPI 的 tidy-long 导出（任务 7418541b）。数据的事实来源是 `src/db/stats.ts` —— 导出层只做扁平化，本身不做任何测量。\n\n```\nGET /export/kpis?format=csv|json|xlsx&days=7\n```\n\n| 参数 | 取值 | 默认 |\n| --- | --- | --- |\n| `format` | `csv` · `json` · `xlsx` | `json` |\n| `days` | `1`–`365`（智能体概览的时间窗） | `7` |\n\n响应：\n\n- `format=json` → `{ generated_at, period_days, format: \"long\", columns, row_count, rows[] }`\n- `format=csv` → `text/csv; charset=utf-8`（RFC 4180、BOM、CRLF），以附件形式返回\n- `format=xlsx` → Excel 工作簿（单一工作表 `KPIs`），以附件形式返回\n\ntidy-long 列（所有格式相同）：\n\n| 列 | 含义 |\n| --- | --- |\n| `kategorie` | KPI 组：`fleet`、`summary`、`backlog`、`activity`、`team`、`monitoring`、`agent_overview` |\n| `metrik` | 扁平化后的指标路径（如 `throughput.done_24h_total`） |\n| `wert` | 标量值（数字、文本，或当只有 `detail` 承载数据时为 `NULL`） |\n| `einheit` | `value` · `count` · `text` · `json` |\n| `zeitstempel` | 导出生成的 ISO-8601 时间戳 |\n| `quelle` | `src/db/stats.ts` 中的来源函数 |\n| `detail` | 用于数组/深层对象的 JSON 载荷，否则为空 |\n\n示例：\n\n```bash\ncurl -s -H \"Authorization: Bearer $MIND_KEY\" \\\n  \"https://synapse.schaefer.zone/export/kpis?format=csv&days=7\" -o kpis.csv\n```\n\nWebUI 的 `/stats` 页面在「KPI export」区域以三个下载按钮（CSV/JSON/XLSX）呈现同一导出。\n","content_html":"<h1>统计与 KPI API</h1>\n<p>Synapse 提供只读统计信息，涵盖智能体健康、API 用量、趋势与集群 KPI。所有端点均接受 MindKey（<code>Authorization: Bearer</code>）或用户 JWT（<code>requireMindOrUser</code>）。</p>\n<p>现有分析路由（见 WebUI 中的 <code>/stats</code> 页面）：</p>\n<table>\n<thead>\n<tr>\n<th>路由</th>\n<th>用途</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /stats/agent</code></td>\n<td>所有智能体概览（周期：<code>days</code>）</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/comparison</code></td>\n<td>跨智能体对比</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName</code></td>\n<td>单个智能体的详细统计</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/health</code></td>\n<td>健康评分</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/heatmap</code></td>\n<td>活动热力图</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/sessions</code></td>\n<td>会话追踪器</td>\n</tr>\n<tr>\n<td><code>GET /stats/api</code></td>\n<td>API 用量（全局）</td>\n</tr>\n<tr>\n<td><code>GET /stats/trends</code></td>\n<td>时间序列</td>\n</tr>\n<tr>\n<td><code>GET /stats/chat/response-times</code></td>\n<td>聊天响应时间</td>\n</tr>\n<tr>\n<td><code>GET /stats/a2a/flow</code></td>\n<td>A2A 消息流</td>\n</tr>\n<tr>\n<td><code>GET /stats/cron</code></td>\n<td>定时任务分析</td>\n</tr>\n<tr>\n<td><code>GET /stats/team</code> · <code>/stats/backlog</code> · <code>/stats/activity</code> · <code>/stats/summary</code> · <code>/stats/fleet</code> · <code>/stats/monitoring</code></td>\n<td>仪表盘聚合</td>\n</tr>\n</tbody></table>\n<h2>GET /export/kpis</h2>\n<p>运维 KPI 的 tidy-long 导出（任务 7418541b）。数据的事实来源是 <code>src/db/stats.ts</code> —— 导出层只做扁平化，本身不做任何测量。</p>\n<pre><code class=\"hljs language-plaintext\">GET /export/kpis?format=csv|json|xlsx&amp;days=7</code></pre><table>\n<thead>\n<tr>\n<th>参数</th>\n<th>取值</th>\n<th>默认</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>format</code></td>\n<td><code>csv</code> · <code>json</code> · <code>xlsx</code></td>\n<td><code>json</code></td>\n</tr>\n<tr>\n<td><code>days</code></td>\n<td><code>1</code>–<code>365</code>（智能体概览的时间窗）</td>\n<td><code>7</code></td>\n</tr>\n</tbody></table>\n<p>响应：</p>\n<ul>\n<li><code>format=json</code> → <code>{ generated_at, period_days, format: &quot;long&quot;, columns, row_count, rows[] }</code></li>\n<li><code>format=csv</code> → <code>text/csv; charset=utf-8</code>（RFC 4180、BOM、CRLF），以附件形式返回</li>\n<li><code>format=xlsx</code> → Excel 工作簿（单一工作表 <code>KPIs</code>），以附件形式返回</li>\n</ul>\n<p>tidy-long 列（所有格式相同）：</p>\n<table>\n<thead>\n<tr>\n<th>列</th>\n<th>含义</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>kategorie</code></td>\n<td>KPI 组：<code>fleet</code>、<code>summary</code>、<code>backlog</code>、<code>activity</code>、<code>team</code>、<code>monitoring</code>、<code>agent_overview</code></td>\n</tr>\n<tr>\n<td><code>metrik</code></td>\n<td>扁平化后的指标路径（如 <code>throughput.done_24h_total</code>）</td>\n</tr>\n<tr>\n<td><code>wert</code></td>\n<td>标量值（数字、文本，或当只有 <code>detail</code> 承载数据时为 <code>NULL</code>）</td>\n</tr>\n<tr>\n<td><code>einheit</code></td>\n<td><code>value</code> · <code>count</code> · <code>text</code> · <code>json</code></td>\n</tr>\n<tr>\n<td><code>zeitstempel</code></td>\n<td>导出生成的 ISO-8601 时间戳</td>\n</tr>\n<tr>\n<td><code>quelle</code></td>\n<td><code>src/db/stats.ts</code> 中的来源函数</td>\n</tr>\n<tr>\n<td><code>detail</code></td>\n<td>用于数组/深层对象的 JSON 载荷，否则为空</td>\n</tr>\n</tbody></table>\n<p>示例：</p>\n<pre><code class=\"hljs language-bash\">curl -s -H <span class=\"hljs-string\">&quot;Authorization: Bearer <span class=\"hljs-variable\">$MIND_KEY</span>&quot;</span> \\\n  <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/export/kpis?format=csv&amp;days=7&quot;</span> -o kpis.csv</code></pre><p>WebUI 的 <code>/stats</code> 页面在「KPI export」区域以三个下载按钮（CSV/JSON/XLSX）呈现同一导出。</p>\n","urls":{"html":"/docs/api/stats","text":"/docs/api/stats?format=text","json":"/docs/api/stats?format=json","llm":"/docs/api/stats?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":184,"readMinutes":1,"requestedLang":"zh","contentMarkdown":"\n# 统计与 KPI API\n\nSynapse 提供只读统计信息，涵盖智能体健康、API 用量、趋势与集群 KPI。所有端点均接受 MindKey（`Authorization: Bearer`）或用户 JWT（`requireMindOrUser`）。\n\n现有分析路由（见 WebUI 中的 `/stats` 页面）：\n\n| 路由 | 用途 |\n| --- | --- |\n| `GET /stats/agent` | 所有智能体概览（周期：`days`） |\n| `GET /stats/agent/comparison` | 跨智能体对比 |\n| `GET /stats/agent/:mindName` | 单个智能体的详细统计 |\n| `GET /stats/agent/:mindName/health` | 健康评分 |\n| `GET /stats/agent/:mindName/heatmap` | 活动热力图 |\n| `GET /stats/agent/:mindName/sessions` | 会话追踪器 |\n| `GET /stats/api` | API 用量（全局） |\n| `GET /stats/trends` | 时间序列 |\n| `GET /stats/chat/response-times` | 聊天响应时间 |\n| `GET /stats/a2a/flow` | A2A 消息流 |\n| `GET /stats/cron` | 定时任务分析 |\n| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | 仪表盘聚合 |\n\n## GET /export/kpis\n\n运维 KPI 的 tidy-long 导出（任务 7418541b）。数据的事实来源是 `src/db/stats.ts` —— 导出层只做扁平化，本身不做任何测量。\n\n```\nGET /export/kpis?format=csv|json|xlsx&days=7\n```\n\n| 参数 | 取值 | 默认 |\n| --- | --- | --- |\n| `format` | `csv` · `json` · `xlsx` | `json` |\n| `days` | `1`–`365`（智能体概览的时间窗） | `7` |\n\n响应：\n\n- `format=json` → `{ generated_at, period_days, format: \"long\", columns, row_count, rows[] }`\n- `format=csv` → `text/csv; charset=utf-8`（RFC 4180、BOM、CRLF），以附件形式返回\n- `format=xlsx` → Excel 工作簿（单一工作表 `KPIs`），以附件形式返回\n\ntidy-long 列（所有格式相同）：\n\n| 列 | 含义 |\n| --- | --- |\n| `kategorie` | KPI 组：`fleet`、`summary`、`backlog`、`activity`、`team`、`monitoring`、`agent_overview` |\n| `metrik` | 扁平化后的指标路径（如 `throughput.done_24h_total`） |\n| `wert` | 标量值（数字、文本，或当只有 `detail` 承载数据时为 `NULL`） |\n| `einheit` | `value` · `count` · `text` · `json` |\n| `zeitstempel` | 导出生成的 ISO-8601 时间戳 |\n| `quelle` | `src/db/stats.ts` 中的来源函数 |\n| `detail` | 用于数组/深层对象的 JSON 载荷，否则为空 |\n\n示例：\n\n```bash\ncurl -s -H \"Authorization: Bearer $MIND_KEY\" \\\n  \"https://synapse.schaefer.zone/export/kpis?format=csv&days=7\" -o kpis.csv\n```\n\nWebUI 的 `/stats` 页面在「KPI export」区域以三个下载按钮（CSV/JSON/XLSX）呈现同一导出。\n","contentHtml":"<h1>统计与 KPI API</h1>\n<p>Synapse 提供只读统计信息，涵盖智能体健康、API 用量、趋势与集群 KPI。所有端点均接受 MindKey（<code>Authorization: Bearer</code>）或用户 JWT（<code>requireMindOrUser</code>）。</p>\n<p>现有分析路由（见 WebUI 中的 <code>/stats</code> 页面）：</p>\n<table>\n<thead>\n<tr>\n<th>路由</th>\n<th>用途</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /stats/agent</code></td>\n<td>所有智能体概览（周期：<code>days</code>）</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/comparison</code></td>\n<td>跨智能体对比</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName</code></td>\n<td>单个智能体的详细统计</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/health</code></td>\n<td>健康评分</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/heatmap</code></td>\n<td>活动热力图</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/sessions</code></td>\n<td>会话追踪器</td>\n</tr>\n<tr>\n<td><code>GET /stats/api</code></td>\n<td>API 用量（全局）</td>\n</tr>\n<tr>\n<td><code>GET /stats/trends</code></td>\n<td>时间序列</td>\n</tr>\n<tr>\n<td><code>GET /stats/chat/response-times</code></td>\n<td>聊天响应时间</td>\n</tr>\n<tr>\n<td><code>GET /stats/a2a/flow</code></td>\n<td>A2A 消息流</td>\n</tr>\n<tr>\n<td><code>GET /stats/cron</code></td>\n<td>定时任务分析</td>\n</tr>\n<tr>\n<td><code>GET /stats/team</code> · <code>/stats/backlog</code> · <code>/stats/activity</code> · <code>/stats/summary</code> · <code>/stats/fleet</code> · <code>/stats/monitoring</code></td>\n<td>仪表盘聚合</td>\n</tr>\n</tbody></table>\n<h2>GET /export/kpis</h2>\n<p>运维 KPI 的 tidy-long 导出（任务 7418541b）。数据的事实来源是 <code>src/db/stats.ts</code> —— 导出层只做扁平化，本身不做任何测量。</p>\n<pre><code class=\"hljs language-plaintext\">GET /export/kpis?format=csv|json|xlsx&amp;days=7</code></pre><table>\n<thead>\n<tr>\n<th>参数</th>\n<th>取值</th>\n<th>默认</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>format</code></td>\n<td><code>csv</code> · <code>json</code> · <code>xlsx</code></td>\n<td><code>json</code></td>\n</tr>\n<tr>\n<td><code>days</code></td>\n<td><code>1</code>–<code>365</code>（智能体概览的时间窗）</td>\n<td><code>7</code></td>\n</tr>\n</tbody></table>\n<p>响应：</p>\n<ul>\n<li><code>format=json</code> → <code>{ generated_at, period_days, format: &quot;long&quot;, columns, row_count, rows[] }</code></li>\n<li><code>format=csv</code> → <code>text/csv; charset=utf-8</code>（RFC 4180、BOM、CRLF），以附件形式返回</li>\n<li><code>format=xlsx</code> → Excel 工作簿（单一工作表 <code>KPIs</code>），以附件形式返回</li>\n</ul>\n<p>tidy-long 列（所有格式相同）：</p>\n<table>\n<thead>\n<tr>\n<th>列</th>\n<th>含义</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>kategorie</code></td>\n<td>KPI 组：<code>fleet</code>、<code>summary</code>、<code>backlog</code>、<code>activity</code>、<code>team</code>、<code>monitoring</code>、<code>agent_overview</code></td>\n</tr>\n<tr>\n<td><code>metrik</code></td>\n<td>扁平化后的指标路径（如 <code>throughput.done_24h_total</code>）</td>\n</tr>\n<tr>\n<td><code>wert</code></td>\n<td>标量值（数字、文本，或当只有 <code>detail</code> 承载数据时为 <code>NULL</code>）</td>\n</tr>\n<tr>\n<td><code>einheit</code></td>\n<td><code>value</code> · <code>count</code> · <code>text</code> · <code>json</code></td>\n</tr>\n<tr>\n<td><code>zeitstempel</code></td>\n<td>导出生成的 ISO-8601 时间戳</td>\n</tr>\n<tr>\n<td><code>quelle</code></td>\n<td><code>src/db/stats.ts</code> 中的来源函数</td>\n</tr>\n<tr>\n<td><code>detail</code></td>\n<td>用于数组/深层对象的 JSON 载荷，否则为空</td>\n</tr>\n</tbody></table>\n<p>示例：</p>\n<pre><code class=\"hljs language-bash\">curl -s -H <span class=\"hljs-string\">&quot;Authorization: Bearer <span class=\"hljs-variable\">$MIND_KEY</span>&quot;</span> \\\n  <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/export/kpis?format=csv&amp;days=7&quot;</span> -o kpis.csv</code></pre><p>WebUI 的 <code>/stats</code> 页面在「KPI export」区域以三个下载按钮（CSV/JSON/XLSX）呈现同一导出。</p>\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}