@migor/agentia 0.7.1 → 0.7.2

package/dist/integrations/metrics.js

@@ -1,24 +1,7 @@
-import { capabilityKindOf } from '../core/trace.js';
-import { percentile } from '../core/stats.js';
-/**
- * OTLP metrics 导出失败（带数值 `status`）。
- *
- * 为什么不能抛裸 `Error`：`engine/errors.ts` 的分类是鸭子类型，只看数据属性。
- * 裸 Error 会被判 `unknown` + `retryable:false` —— 宿主在 `onExportError` 里拿不到
- * status，也就没法区分「collector 拒收（4xx，改配置）」与「collector 挂了（5xx，等它回来）」。
- * 形状与 `otlp.ts` 的 `OtlpExportError` 一致（同层两处导出器不该有两种错误形状）。
- *
- * 注：本处抛错由 `onExportError` 接住并按「观测失败不得击穿业务」吞掉 —— 带 status 是为了
- * **可判断**，不是为了让谁重试。
- */
-export class MetricsExportError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.name = 'MetricsExportError';
-        this.status = status;
-    }
-}
+import { MetricsState } from './metrics-state.js';
+import { renderPrometheus } from './metrics-render.js';
+import { flushOtlpMetrics } from './metrics-otlp.js';
+export { MetricsExportError } from './metrics-otlp.js';
 const DEFAULT_WINDOW = 1024;
 const DEFAULT_MAX_CAPABILITIES = 200;
 /** 模型 id 实际就那么几个，默认给 50 已经很宽（够覆盖多版本并存的灰度期） */
@@ -29,150 +12,6 @@ const DEFAULT_MAX_SCORES = 200;
 export const DEFAULT_BUCKETS = [
     25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000,
 ];
-/** 超过基数上限后新键的兜底标签（能力 / 模型 / 评分三个维度共用） */
-const OTHER_LABEL = '__other__';
-/**
- * 折叠计数最多记这么多个**不同**键（每个维度各一本）。计数只用于报警「基数爆了」，
- * 不值得为它留一本无界的账 —— 那等于把上限又拆掉一角。正常上限（50~200）下这个数
- * 远够用：真要记满，说明键空间已经失控，此时「≥1024」和精确值一样能说明问题。
- */
-const MAX_DROPPED_TRACKING = 1024;
-/**
- * 标签基数配额：三个维度共用的「有界键空间」。
- *
- * 键第一次出现且在额度内 → 分到自己的标签（**永远认自己**，不会时而被折叠时而不折叠）；
- * 超限 → 归入 `OTHER_LABEL`。
- *
- * 被折叠的键记进 `over`，只为回答「多少个**不同**的键被折叠了」；这本账自身也有界
- * （`MAX_DROPPED_TRACKING`），满了以后 `dropped` 是下界。
- */
-class KeyBudget {
-    max;
-    assigned = new Set();
-    over = new Set();
-    constructor(max) {
-        this.max = max;
-    }
-    /** 取键的标签：额度内原样返回，超限返回 `OTHER_LABEL` */
-    take(key) {
-        if (this.assigned.has(key))
-            return key;
-        if (this.assigned.size < this.max) {
-            this.assigned.add(key);
-            return key;
-        }
-        if (this.over.size < MAX_DROPPED_TRACKING)
-            this.over.add(key);
-        return OTHER_LABEL;
-    }
-    /** 被折叠的**不同**键数（记满 `MAX_DROPPED_TRACKING` 后为下界） */
-    get dropped() {
-        return this.over.size;
-    }
-    /** 清空配额（`reset()` 用）—— 与 `capabilities` / `models` / `scores` 三张表同步清 */
-    reset() {
-        this.assigned.clear();
-        this.over.clear();
-    }
-}
-/**
- * 时长统计：环形窗口（算窗口内精确分位）+ 累积直方图（算可聚合的 bucket）。
- * run / 能力 / 模型共用同一个实现，保证三种粒度的口径与取整完全一致。
- */
-class DurationStat {
-    windowSize;
-    bounds;
-    ring = [];
-    cursor = 0;
-    /** 每桶非累积计数：counts[i] 对应 le = bounds[i]；末位是 +Inf 桶 */
-    counts;
-    total = 0;
-    sum = 0;
-    constructor(windowSize, bounds) {
-        this.windowSize = windowSize;
-        this.bounds = bounds;
-        this.counts = new Array(bounds.length + 1).fill(0);
-    }
-    add(ms) {
-        this.total++;
-        this.sum += ms;
-        if (this.ring.length < this.windowSize)
-            this.ring.push(ms);
-        else {
-            this.ring[this.cursor] = ms;
-            this.cursor = (this.cursor + 1) % this.windowSize;
-        }
-        let i = 0;
-        while (i < this.bounds.length && ms > this.bounds[i])
-            i++;
-        this.counts[i]++;
-    }
-    get count() {
-        return this.total;
-    }
-    get sumMs() {
-        return this.sum;
-    }
-    get windowSamples() {
-        return this.ring.length;
-    }
-    /**
-     * 窗口内精确分位（Prometheus 的 quantile 语义：取第 ceil(q·n) 个样本）。
-     * 算法单源在 `core/stats.ts` —— 与 `report.ts` 的时长 p50/p95 必须同口径，
-     * 否则同一条 trace 在看板与报告里会有两个 p95。
-     */
-    percentile(q) {
-        if (this.ring.length === 0)
-            return 0;
-        const sorted = [...this.ring].sort((a, b) => a - b);
-        return percentile(sorted, q);
-    }
-    /** 累积 bucket 计数（长度 = bounds+1，末位为 +Inf = count）—— Prometheus 文本语义 */
-    cumulative() {
-        const out = [];
-        let running = 0;
-        for (const c of this.counts) {
-            running += c;
-            out.push(running);
-        }
-        return out;
-    }
-    /** 每桶**非累积**计数 —— OTLP histogram 的 bucketCounts 语义（与 cumulative() 千万别混用） */
-    perBucket() {
-        return [...this.counts];
-    }
-    get boundsList() {
-        return this.bounds;
-    }
-    reset() {
-        this.ring.length = 0;
-        this.cursor = 0;
-        this.counts.fill(0);
-        this.total = 0;
-        this.sum = 0;
-    }
-}
-/** run 时长：取根 span（`trace.rootSpanId`）的起止；根没收尾（如 sink 在失败路径拿到半截）时返回 undefined */
-function runDurationMs(trace) {
-    const root = trace.spans.find((s) => s.spanId === trace.rootSpanId);
-    if (!root || root.endedAt === undefined)
-        return undefined;
-    return root.endedAt - root.startedAt;
-}
-function num(v) {
-    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
-}
-/**
- * 评分键 → 指标标签。键有两种形态：**折叠桶**（`__other__`，整个键就是标签，不含 `\t`）
- * 与正常的 `name\tsource`（source 缺省为 ''）。两个出口（Prometheus 文本 / OTLP）共用一处
- * 解码 —— 各切各的必然有一处把折叠桶切成乱码。
- */
-function scoreLabels(key) {
-    if (key === OTHER_LABEL)
-        return { name: OTHER_LABEL, source: '' };
-    const tab = key.indexOf('\t');
-    return { name: key.slice(0, tab), source: key.slice(tab + 1) };
-}
 export function metricsSink(opts = {}) {
     const format = opts.export ?? 'prometheus';
     if (format !== 'prometheus' && format !== 'otlp') {
@@ -210,478 +49,32 @@ export function metricsSink(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 10_000;
     const serviceName = opts.serviceName ?? 'agentia';
     const startedAtMs = Date.now();
-    let runs = 0;
-    let failed = 0;
-    let costUsd = 0;
-    const tokens = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
-    const runStat = new DurationStat(windowSize, buckets);
-    const capabilities = new Map();
-    const models = new Map();
-    /** 评分累加器：key = `${name}\t${source}`（source 缺省 ''；\t 不会出现在正常评分名里，做天然分隔符） */
-    const scores = new Map();
-    // 三个维度的键空间都封在这些配额里 —— 没有它们，三张 Map 与各自的时长窗口都是无界的
-    const capBudget = new KeyBudget(maxCapabilities);
-    const modelBudget = new KeyBudget(maxModels);
-    const scoreBudget = new KeyBudget(maxScores);
-    const newCapability = () => ({
-        calls: 0,
-        errors: 0,
-        stat: new DurationStat(windowSize, buckets),
-        tokens: null,
-        costUsd: null,
+    const state = new MetricsState({
+        windowSize,
+        maxCapabilities,
+        maxModels,
+        maxScores,
+        labelMode,
+        buckets,
     });
-    /** 能力标签分配：labelMode 决定粒度，capBudget 决定基数上限 */
-    const labelFor = (kind, name) => {
-        if (labelMode === 'none')
-            return null;
-        if (labelMode === 'kind')
-            return kind;
-        return capBudget.take(`${kind}:${name}`);
-    };
-    const accumulate = (trace) => {
-        runs++;
-        if (trace.status === 'error')
-            failed++;
-        const u = trace.totalUsage;
-        tokens.input += u.inputTokens;
-        tokens.output += u.outputTokens;
-        tokens.cacheRead += u.cacheReadTokens;
-        tokens.cacheCreation += u.cacheCreationTokens;
-        if (u.costEstimate != null)
-            costUsd += u.costEstimate;
-        const d = runDurationMs(trace);
-        if (d !== undefined)
-            runStat.add(d);
-        // —— 评分（R7）：只认根 span 的 score 事件（attachScore 的写入位置）；
-        // body 宽容读取 —— name 不是 string / value 不是有限 number 就跳过，观测不击穿业务
-        const rootSpan = trace.spans.find((s) => s.spanId === trace.rootSpanId);
-        if (rootSpan) {
-            for (const e of rootSpan.events) {
-                if (e.name !== 'score')
-                    continue;
-                const body = e.body;
-                if (!body || typeof body !== 'object')
-                    continue;
-                if (typeof body.name !== 'string')
-                    continue;
-                if (typeof body.value !== 'number' || !Number.isFinite(body.value))
-                    continue;
-                const source = typeof body.source === 'string' ? body.source : '';
-                const key = scoreBudget.take(`${body.name}\t${source}`);
-                const acc = scores.get(key) ?? { value: 0, count: 0, sum: 0 };
-                acc.value = body.value; // gauge 语义：覆盖为最近一次
-                acc.count++;
-                acc.sum += body.value;
-                scores.set(key, acc);
-            }
-        }
-        for (const span of trace.spans) {
-            if (span.kind === 'capability') {
-                const label = labelFor(capabilityKindOf(span), span.name);
-                // 时长与错误无论哪种 labelMode 都要累计；labelMode:'none' 时整块跳过
-                if (label !== null) {
-                    const acc = capabilities.get(label) ?? newCapability();
-                    acc.calls++;
-                    if (span.status === 'error')
-                        acc.errors++;
-                    if (span.endedAt !== undefined)
-                        acc.stat.add(Math.max(0, span.endedAt - span.startedAt));
-                    // capability.usage = 子孙 llm.turn 聚合（tracer 写入）；工具没有这个语义
-                    if (span.usage) {
-                        const sum = span.usage.inputTokens +
-                            span.usage.outputTokens +
-                            span.usage.cacheReadTokens +
-                            span.usage.cacheCreationTokens;
-                        acc.tokens = (acc.tokens ?? 0) + sum;
-                        if (span.usage.costEstimate != null)
-                            acc.costUsd = (acc.costUsd ?? 0) + span.usage.costEstimate;
-                    }
-                    capabilities.set(label, acc);
-                }
-                continue;
-            }
-            if (span.kind === 'llm.turn') {
-                const model = modelBudget.take(span.name);
-                const acc = models.get(model) ?? {
-                    turns: 0,
-                    tokens: 0,
-                    costUsd: 0,
-                    unpricedTurns: 0,
-                    stat: new DurationStat(windowSize, buckets),
-                };
-                acc.turns++;
-                if (span.usage) {
-                    acc.tokens +=
-                        span.usage.inputTokens +
-                            span.usage.outputTokens +
-                            span.usage.cacheReadTokens +
-                            span.usage.cacheCreationTokens;
-                    if (span.usage.costEstimate != null)
-                        acc.costUsd += span.usage.costEstimate;
-                    else
-                        acc.unpricedTurns++; // 有计量却算不出成本 = 模型不在价格表内
-                }
-                if (span.endedAt !== undefined)
-                    acc.stat.add(Math.max(0, span.endedAt - span.startedAt));
-                models.set(model, acc);
-                // 普通工具的耗时/成败在 turn 的 tool.output 事件上（E1）—— 能力指标的另一路数据源
-                for (const e of span.events) {
-                    if (e.name !== 'tool.output')
-                        continue;
-                    const body = e.body;
-                    if (!body || typeof body !== 'object' || typeof body.tool !== 'string')
-                        continue;
-                    const label = labelFor('tool', body.tool);
-                    if (label === null)
-                        continue;
-                    const tacc = capabilities.get(label) ?? newCapability();
-                    tacc.calls++;
-                    if (body.ok === false)
-                        tacc.errors++;
-                    tacc.stat.add(Math.max(0, num(body.durationMs)));
-                    capabilities.set(label, tacc);
-                }
-            }
-        }
-    };
-    const snapshot = () => {
-        const capabilityOut = {};
-        if (labelMode !== 'none') {
-            for (const [label, acc] of capabilities) {
-                capabilityOut[label] = {
-                    calls: acc.calls,
-                    errors: acc.errors,
-                    latencyP50: acc.stat.percentile(0.5),
-                    latencyP95: acc.stat.percentile(0.95),
-                    tokens: acc.tokens,
-                    costUsd: acc.costUsd,
-                };
-            }
-        }
-        const modelOut = {};
-        for (const [model, acc] of models) {
-            modelOut[model] = {
-                turns: acc.turns,
-                tokens: acc.tokens,
-                costUsd: acc.costUsd,
-                unpricedTurns: acc.unpricedTurns,
-                latencyP50: acc.stat.percentile(0.5),
-                latencyP95: acc.stat.percentile(0.95),
-            };
-        }
-        const scoreOut = {};
-        for (const [key, acc] of scores) {
-            // 折叠桶没有 `name@source` 可黏（也不该有），原样以 `__other__` 出
-            if (key === OTHER_LABEL) {
-                scoreOut[OTHER_LABEL] = { ...acc };
-                continue;
-            }
-            const { name, source } = scoreLabels(key);
-            scoreOut[source === '' ? name : `${name}@${source}`] = { ...acc };
-        }
-        return {
-            runs,
-            failed,
-            latencyP50: runStat.percentile(0.5),
-            latencyP95: runStat.percentile(0.95),
-            tokens: tokens.input + tokens.output + tokens.cacheRead + tokens.cacheCreation,
-            costUsd,
-            capabilities: capabilityOut,
-            models: modelOut,
-            scores: scoreOut,
-            droppedCapabilities: capBudget.dropped,
-            droppedModels: modelBudget.dropped,
-            droppedScores: scoreBudget.dropped,
-        };
-    };
-    /**
-     * 一个指标家族的完整块：HELP/TYPE 各**恰好一行**，后接全部样本行。
-     * expfmt 对同名指标的第二条 HELP/TYPE 是**硬错误**（整次 scrape 失败），
-     * 所以家族头必须集中在这里发一次，绝不能让每条样本自带；同名指标也只能有一种 TYPE
-     * （histogram 与分位 gauge 因此拆成 `*_duration_ms` 与 `*_duration_ms_last` 两个名字）。
-     */
-    const family = (name, type, help, samples) => `# HELP ${name} ${help}\n# TYPE ${name} ${type}\n${samples.join('\n')}\n`;
-    /** Prometheus label 值转义：\、"、换行必须转义，否则一个含引号的能力名/模型名就损坏整页 exposition */
-    const escLabel = (v) => v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-    /** 一个 stat 的 histogram 样本（bucket 累积 + sum + count），labels 形如 `{k="v"}` */
-    const histogramSamples = (name, stat, labels = '') => {
-        const inner = labels ? labels.slice(1, -1) + ',' : ''; // 去掉外层 {} 再补逗号
-        const at = (extra) => `{${inner}${extra}}`;
-        const out = [];
-        const cum = stat.cumulative();
-        for (let i = 0; i < stat.boundsList.length; i++) {
-            out.push(`${name}_bucket${at(`le="${stat.boundsList[i]}"`)} ${cum[i]}`);
-        }
-        out.push(`${name}_bucket${at(`le="+Inf"`)} ${stat.count}`);
-        out.push(`${name}_sum${labels} ${stat.sumMs}`);
-        out.push(`${name}_count${labels} ${stat.count}`);
-        return out;
-    };
-    const render = () => {
-        const out = [];
-        out.push(family(`${p}runs_total`, 'counter', 'run 总数（成功 + 失败）', [`${p}runs_total ${runs}`]));
-        out.push(family(`${p}runs_failed_total`, 'counter', '失败的 run 数（trace.status=error）', [
-            `${p}runs_failed_total ${failed}`,
-        ]));
-        out.push(family(`${p}tokens_total`, 'counter', 'token 累计（kind 分项：input / output / cache_read / cache_creation）', [
-            `${p}tokens_total{kind="input"} ${tokens.input}`,
-            `${p}tokens_total{kind="output"} ${tokens.output}`,
-            `${p}tokens_total{kind="cache_read"} ${tokens.cacheRead}`,
-            `${p}tokens_total{kind="cache_creation"} ${tokens.cacheCreation}`,
-        ]));
-        out.push(family(`${p}cost_usd_total`, 'counter', '累计成本估算（美元）', [
-            `${p}cost_usd_total ${costUsd}`,
-        ]));
-        // 基数上限的**可见性**：被折叠掉的不同键数。与 `snapshot()` 的同名字段一一对应 ——
-        // 此前只有 snapshot() 有、render() 没有，于是「按文档把 metricsSink 接到 /metrics」的部署
-        // **完全看不见折叠发生**（静默丢失）；而同一份文件对「算不出成本的 turn」专门发了
-        // `model_unpriced_turns_total`，口径不一致。
-        // 与 unpriced 不同：**恒定发三行**（不是 >0 才发）—— 「0 → N」这个变化本身就是要告警的信号。
-        out.push(family(`${p}dropped_keys`, 'gauge', '因基数上限被折叠的不同键数（kind 分项）', [
-            `${p}dropped_keys{kind="capability"} ${capBudget.dropped}`,
-            `${p}dropped_keys{kind="model"} ${modelBudget.dropped}`,
-            `${p}dropped_keys{kind="score"} ${scoreBudget.dropped}`,
-        ]));
-        // 时长：histogram（可跨实例聚合）+ 窗口内精确分位（单实例好读），两种口径并存。
-        // 分位 gauge 必须用另一个名字 `*_last` —— 同名指标只允许一种 TYPE，
-        // 先发 histogram 再发 gauge 会被 expfmt 判硬错误，整次 scrape 失败。
-        out.push(family(`${p}run_duration_ms`, 'histogram', 'run 时长（毫秒）', [
-            ...histogramSamples(`${p}run_duration_ms`, runStat),
-        ]));
-        out.push(family(`${p}run_duration_ms_last`, 'gauge', 'run 时长分位（毫秒，滑动窗口内精确值）', [
-            `${p}run_duration_ms_last{quantile="0.5"} ${runStat.percentile(0.5)}`,
-            `${p}run_duration_ms_last{quantile="0.95"} ${runStat.percentile(0.95)}`,
-        ]));
-        // —— 能力维度（E2）：同一家族的样本跨 label 聚合，家族头只发一次 ——
-        const capLabels = [...capabilities.keys()].sort();
-        if (capLabels.length > 0) {
-            const calls = [];
-            const errors = [];
-            const durations = [];
-            const durationQuantiles = [];
-            const capabilityTokens = [];
-            const capabilityCosts = [];
-            for (const label of capLabels) {
-                const acc = capabilities.get(label);
-                const lv = escLabel(label);
-                const l = `{capability="${lv}"}`;
-                calls.push(`${p}capability_calls_total${l} ${acc.calls}`);
-                errors.push(`${p}capability_errors_total${l} ${acc.errors}`);
-                durations.push(...histogramSamples(`${p}capability_duration_ms`, acc.stat, l));
-                durationQuantiles.push(`${p}capability_duration_ms_last{capability="${lv}",quantile="0.5"} ${acc.stat.percentile(0.5)}`, `${p}capability_duration_ms_last{capability="${lv}",quantile="0.95"} ${acc.stat.percentile(0.95)}`);
-                if (acc.tokens !== null)
-                    capabilityTokens.push(`${p}capability_tokens_total${l} ${acc.tokens}`);
-                if (acc.costUsd !== null)
-                    capabilityCosts.push(`${p}capability_cost_usd_total${l} ${acc.costUsd}`);
-            }
-            out.push(family(`${p}capability_calls_total`, 'counter', '能力调用次数', calls));
-            out.push(family(`${p}capability_errors_total`, 'counter', '能力失败次数', errors));
-            out.push(family(`${p}capability_duration_ms`, 'histogram', '能力调用耗时（毫秒）', durations));
-            out.push(family(`${p}capability_duration_ms_last`, 'gauge', '能力调用耗时分位（窗口内精确值）', durationQuantiles));
-            if (capabilityTokens.length > 0) {
-                out.push(family(`${p}capability_tokens_total`, 'counter', 'skill/subagent 的子孙 token 合计', capabilityTokens));
-            }
-            if (capabilityCosts.length > 0) {
-                out.push(family(`${p}capability_cost_usd_total`, 'counter', 'skill/subagent 的估算成本（美元）', capabilityCosts));
-            }
-        }
-        // —— 模型维度（E3）——
-        const modelNames = [...models.keys()].sort();
-        if (modelNames.length > 0) {
-            const turns = [];
-            const modelTokens = [];
-            const modelCosts = [];
-            const unpriced = [];
-            const durations = [];
-            const durationQuantiles = [];
-            for (const model of modelNames) {
-                const acc = models.get(model);
-                const mv = escLabel(model);
-                const l = `{model="${mv}"}`;
-                turns.push(`${p}model_turns_total${l} ${acc.turns}`);
-                modelTokens.push(`${p}model_tokens_total${l} ${acc.tokens}`);
-                modelCosts.push(`${p}model_cost_usd_total${l} ${acc.costUsd}`);
-                if (acc.unpricedTurns > 0)
-                    unpriced.push(`${p}model_unpriced_turns_total${l} ${acc.unpricedTurns}`);
-                durations.push(...histogramSamples(`${p}model_duration_ms`, acc.stat, l));
-                durationQuantiles.push(`${p}model_duration_ms_last{model="${mv}",quantile="0.5"} ${acc.stat.percentile(0.5)}`, `${p}model_duration_ms_last{model="${mv}",quantile="0.95"} ${acc.stat.percentile(0.95)}`);
-            }
-            out.push(family(`${p}model_turns_total`, 'counter', '模型往返次数', turns));
-            out.push(family(`${p}model_tokens_total`, 'counter', '模型 token 合计（四类之和）', modelTokens));
-            out.push(family(`${p}model_cost_usd_total`, 'counter', '模型估算成本（美元，仅已定价部分）', modelCosts));
-            if (unpriced.length > 0) {
-                out.push(family(`${p}model_unpriced_turns_total`, 'counter', '算不出成本的 turn 数（模型不在价格表内）', unpriced));
-            }
-            out.push(family(`${p}model_duration_ms`, 'histogram', '模型往返耗时（毫秒）', durations));
-            out.push(family(`${p}model_duration_ms_last`, 'gauge', '模型往返耗时分位（窗口内精确值）', durationQuantiles));
-        }
-        // —— 评分维度（R7）：gauge 记最近一次值、counter 记条数，label 为 name × source ——
-        if (scores.size > 0) {
-            const gaugeSamples = [];
-            const counterSamples = [];
-            for (const key of [...scores.keys()].sort()) {
-                const acc = scores.get(key);
-                const { name, source } = scoreLabels(key);
-                const l = `{name="${escLabel(name)}",source="${escLabel(source)}"}`;
-                gaugeSamples.push(`${p}score${l} ${acc.value}`);
-                counterSamples.push(`${p}score_total${l} ${acc.count}`);
-            }
-            out.push(family(`${p}score`, 'gauge', '最近一次评分（label 为评分维度与来源）', gaugeSamples));
-            out.push(family(`${p}score_total`, 'counter', '评分条数', counterSamples));
-        }
-        return out.join('');
-    };
-    // —— OTLP/JSON 导出（E5）——
-    // epoch 毫秒 ×1e6 ≈ 1.7e18 > 2^53，double 直接乘会丢精度 —— 必须先取整再转 BigInt
-    const nanos = (ms) => String(BigInt(Math.round(ms)) * 1000000n);
-    const strAttr = (key, v) => ({ key, value: { stringValue: v } });
-    const buildOtlpPayload = () => {
-        const now = nanos(Date.now());
-        const start = nanos(startedAtMs);
-        const s = snapshot();
-        const metricTable = new Map();
-        /** 查表取已建 Metric，没有则建；同名只保留首次的 description（冲突描述本身是 semantic error） */
-        const takeMetric = (name, help) => {
-            let m = metricTable.get(name);
-            if (!m) {
-                m = { name, description: help };
-                metricTable.set(name, m);
-            }
-            return m;
-        };
-        const sum = (name, value, help, attrs, monotonic = true) => {
-            const m = takeMetric(name, help);
-            m.sum ??= { aggregationTemporality: 2, isMonotonic: monotonic, dataPoints: [] };
-            m.sum.dataPoints.push({
-                attributes: attrs,
-                startTimeUnixNano: start,
-                timeUnixNano: now,
-                asInt: String(value),
-            });
-        };
-        // 浮点指标（成本）必须走 asDouble —— OTLP 的 asInt 是 string 编码 int64，
-        // 塞浮点（如 0.25）会让 collector 直接拒收整批数据
-        const sumDouble = (name, value, help, attrs) => {
-            const m = takeMetric(name, help);
-            m.sum ??= { aggregationTemporality: 2, isMonotonic: true, dataPoints: [] };
-            m.sum.dataPoints.push({
-                attributes: attrs,
-                startTimeUnixNano: start,
-                timeUnixNano: now,
-                asDouble: value,
-            });
-        };
-        // gauge 没有理由只收 int：评分值是浮点，统一走 asDouble
-        const gauge = (name, value, help, attrs) => {
-            const m = takeMetric(name, help);
-            m.gauge ??= { dataPoints: [] };
-            m.gauge.dataPoints.push({
-                attributes: attrs,
-                startTimeUnixNano: start,
-                timeUnixNano: now,
-                asDouble: value,
-            });
-        };
-        const hist = (name, stat, help, attrs) => {
-            const m = takeMetric(name, help);
-            m.histogram ??= { aggregationTemporality: 2, dataPoints: [] };
-            m.histogram.dataPoints.push({
-                attributes: attrs,
-                startTimeUnixNano: start,
-                timeUnixNano: now,
-                count: stat.count,
-                sum: stat.sumMs,
-                // OTLP 的 bucketCounts 是每桶**非累积**计数（Prometheus 文本才是累积语义）
-                bucketCounts: stat.perBucket(),
-                explicitBounds: [...stat.boundsList],
-            });
-        };
-        sum(`${p}runs_total`, s.runs, 'run 总数', []);
-        sum(`${p}runs_failed_total`, s.failed, '失败的 run 数', []);
-        // tokens_total：四类 kind 分项收进**同一个** Metric；description 与 Prometheus 侧
-        // render() 的 family() 统一成同一句总述（同名 Metric 各带一份描述是 semantic error）
-        const tokensHelp = 'token 累计（kind 分项：input / output / cache_read / cache_creation）';
-        sum(`${p}tokens_total`, tokens.input, tokensHelp, [strAttr('kind', 'input')]);
-        sum(`${p}tokens_total`, tokens.output, tokensHelp, [strAttr('kind', 'output')]);
-        sum(`${p}tokens_total`, tokens.cacheRead, tokensHelp, [strAttr('kind', 'cache_read')]);
-        sum(`${p}tokens_total`, tokens.cacheCreation, tokensHelp, [strAttr('kind', 'cache_creation')]);
-        sumDouble(`${p}cost_usd_total`, s.costUsd, '累计成本估算（美元）', []);
-        hist(`${p}run_duration_ms`, runStat, 'run 时长（毫秒）', []);
-        for (const label of [...capabilities.keys()].sort()) {
-            const acc = capabilities.get(label);
-            const attrs = [strAttr('capability', label)];
-            sum(`${p}capability_calls_total`, acc.calls, '能力调用次数', attrs);
-            sum(`${p}capability_errors_total`, acc.errors, '能力失败次数', attrs);
-            hist(`${p}capability_duration_ms`, acc.stat, '能力调用耗时（毫秒）', attrs);
-            if (acc.tokens !== null)
-                sum(`${p}capability_tokens_total`, acc.tokens, '子孙 token 合计', attrs);
-            if (acc.costUsd !== null)
-                sumDouble(`${p}capability_cost_usd_total`, acc.costUsd, '估算成本（美元）', attrs);
-        }
-        for (const model of [...models.keys()].sort()) {
-            const acc = models.get(model);
-            const attrs = [strAttr('model', model)];
-            sum(`${p}model_turns_total`, acc.turns, '模型往返次数', attrs);
-            sum(`${p}model_tokens_total`, acc.tokens, '模型 token 合计', attrs);
-            sumDouble(`${p}model_cost_usd_total`, acc.costUsd, '模型估算成本（美元）', attrs);
-            if (acc.unpricedTurns > 0) {
-                sum(`${p}model_unpriced_turns_total`, acc.unpricedTurns, '未定价 turn 数', attrs);
-            }
-            hist(`${p}model_duration_ms`, acc.stat, '模型往返耗时（毫秒）', attrs);
-        }
-        for (const key of [...scores.keys()].sort()) {
-            const acc = scores.get(key);
-            const { name, source } = scoreLabels(key);
-            const attrs = [strAttr('name', name), strAttr('source', source)];
-            gauge(`${p}score`, acc.value, '最近一次评分', attrs);
-            sum(`${p}score_total`, acc.count, '评分条数', attrs);
-        }
-        // 基数上限可见性（与 Prometheus 侧 `*_dropped_keys{kind=…}` 同名同义）：
-        // 三个 kind 收进同一个 gauge Metric
-        const droppedHelp = '因基数上限被折叠的不同键数';
-        gauge(`${p}dropped_keys`, capBudget.dropped, droppedHelp, [strAttr('kind', 'capability')]);
-        gauge(`${p}dropped_keys`, modelBudget.dropped, droppedHelp, [strAttr('kind', 'model')]);
-        gauge(`${p}dropped_keys`, scoreBudget.dropped, droppedHelp, [strAttr('kind', 'score')]);
-        const metrics = [...metricTable.values()];
-        const resourceAttrs = [
-            strAttr('service.name', serviceName),
-            ...Object.entries(opts.resourceAttributes ?? {}).map(([k, v]) => strAttr(k, v)),
-        ];
-        return {
-            resourceMetrics: [
-                {
-                    resource: { attributes: resourceAttrs },
-                    scopeMetrics: [{ scope: { name: 'agentia' }, metrics }],
-                },
-            ],
-        };
-    };
+    const snapshot = () => state.snapshot();
+    const render = () => renderPrometheus(state, p);
     const flush = async () => {
         if (format !== 'otlp')
             return; // prometheus 模式：拉取式，无主动导出
-        let payload;
-        try {
-            payload = buildOtlpPayload();
-        }
-        catch (e) {
-            opts.onExportError?.(e);
-            return;
-        }
-        try {
-            const res = await fetch(`${otlpEndpoint}/v1/metrics`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body: JSON.stringify(payload),
-                ...(timeoutMs > 0 ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
-            });
-            if (!res.ok) {
-                const text = (await res.text()).slice(0, 200);
-                throw new MetricsExportError(res.status, `OTLP metrics 导出失败: HTTP ${res.status} ${text}`);
-            }
-        }
-        catch (e) {
-            opts.onExportError?.(e); // 观测失败不得击穿业务
-        }
+        await flushOtlpMetrics(state, {
+            prefix: p,
+            serviceName,
+            startedAtMs,
+            // 构造期校验保证 otlp 模式下 endpoint 必填
+            endpoint: otlpEndpoint,
+            timeoutMs,
+            // exactOptionalPropertyTypes：可选字段不能赋 undefined，只能条件展开
+            ...(opts.resourceAttributes !== undefined
+                ? { resourceAttributes: opts.resourceAttributes }
+                : {}),
+            ...(opts.onExportError !== undefined ? { onExportError: opts.onExportError } : {}),
+        });
     };
     const timer = format === 'otlp' && intervalMs > 0
         ? setInterval(() => {
@@ -692,7 +85,7 @@ export function metricsSink(opts = {}) {
     timer?.unref?.();
     return {
         export(trace) {
-            accumulate(trace);
+            state.accumulate(trace);
             // intervalMs=0：立即导出并由框架 await；否则只累加，定时器负责导出
             if (format === 'otlp' && intervalMs === 0)
                 return flush();
@@ -706,20 +99,7 @@ export function metricsSink(opts = {}) {
                 clearInterval(timer);
         },
         reset() {
-            runs = 0;
-            failed = 0;
-            costUsd = 0;
-            tokens.input = 0;
-            tokens.output = 0;
-            tokens.cacheRead = 0;
-            tokens.cacheCreation = 0;
-            runStat.reset();
-            capabilities.clear();
-            models.clear();
-            scores.clear();
-            capBudget.reset();
-            modelBudget.reset();
-            scoreBudget.reset();
+            state.reset();
         },
     };
 }