用途：为 NodeJS-Starter-V1 项目提供标准化的应用指标采集、存储与查询模式，基于项目已有的 Supabase + PostgreSQL 数据库方案，适配 Vercel/无服务器环境，不依赖 Prometheus 抓取。
主要能力：支持三类指标——计数器（单调递增，按事件 INSERT，COUNT(*) 求总量）、仪表（时点值，UPSERT 最新值生效）、直方图（值分布，按观测 INSERT，支持百分位查询）。定义命名规范 {domain}{entity}{measurement}[_{unit}]，并给出标准指标清单（如 agent_run_total、api_request_duration_ms、llm_token_total、llm_cost_usd、cron_job_total、auth_login_total 等）。提供 MetricsRegistry 封装，含 increment()、observe()、set_gauge() 三个方法；支持时间序列分桶聚合与 p50/p90/p95/p99 百分位计算；提供 /metrics/summary 汇总端点；可选 OpenTelemetry 导出（仅在配置 OTEL_EXPORTER_OTLP_ENDPOINT 时启用）。
使用方式：通过 MetricsRegistry 单例记录指标；用 BaseHTTPMiddleware 在 API 路由记录 api_request_total 与 api_request_duration_ms；在 AgentMetrics.track_task_execution 中扩展记录 agent_run_total 与 agent_run_duration_ms。数据存入 metrics_events（计数器与直方图）和 metrics_gauges（仪表）两张表，并建立名称时间索引与 labels GIN 索引。前端通过代理路由转发请求，使用 MetricTile 组件展示，可 30 秒轮询或使用 Supabase Realtime。
适用场景：新增指标或 KPI、创建仪表盘数据源与分析端点、为 API 路由/智能体执行/后台任务埋点、查询时间序列趋势、设置告警阈值。
限制：不适用于添加日志语句（应使用 structured-logging）、设计仪表盘 UI 组件、格式化错误响应、调度周期性指标聚合（应使用 cron-scheduler）。需配置 90 天保留策略的 cron 清理任务，避免 metrics_events 无界增长。指标记录失败不得中断请求。时区存储为 UTC，显示时转换；llm_cost_usd 以美元存储，显示时转换为澳元。具体收费、价格与平台支持信息暂未提供。