用途：为 NodeJS-Starter-V1 项目提供数据库支撑的指标埋点规范，覆盖指标类型、命名约定、时序聚合查询，以及可选的 OpenTelemetry 导出，适配无服务器环境。
主要能力：定义三类指标——计数器（单调递增，按事件插入、COUNT 求总量）、仪表（时点值，UPSERT 最新值生效）、直方图（分布值，按观测插入并做分位数查询）。计数器与直方图写入 metrics_events，仪表写入 metrics_gauges。命名遵循 {domain}{entity}{measurement}[_{unit}]，如 agent_run_total、api_request_duration_ms、llm_cost_usd。提供 MetricsRegistry 封装，含 increment()、observe()、set_gauge() 三个方法；支持用 BaseHTTPMiddleware 记录 api_request_total 与 api_request_duration_ms，并扩展 AgentMetrics 记录 agent_run_total 与 agent_run_duration_ms。聚合方面支持按分钟/小时/天分桶的时序统计（count、sum、avg、min、max）与 p50/p90/p95/p99 分位数计算，并可暴露 /metrics/summary 汇总端点。前端可复用 MetricTile 组件与代理路由，按 30 秒轮询或使用 Supabase Realtime。
使用方式：建表 metrics_events 与 metrics_gauges，通过 MetricsRegistry 单例埋点，查询时惰性聚合；可选配置 OTEL_EXPORTER_OTLP_ENDPOINT 启用 OTel 导出。
限制：不适用于日志记录、仪表盘 UI 设计、错误响应格式化或周期性聚合调度（应分别使用 structured-logging、dashboard-patterns、error-taxonomy、cron-scheduler）。避免在无服务器中使用内存计数器或 Prometheus 抓取端点。建议用 cron 任务清理超过 90 天的 metrics_events。指标记录失败不得中断请求。