dsh-key-usage 0.0.0-stage → 0.1.0

package/lib/index.js

@@ -0,0 +1,42 @@
+/**
+ * dsh-key-usage 服务端入口：挂载只读 HTTP 路由，向客户端提供
+ * 用量台账、通道配置、余额快照与会话用量的聚合数据。
+ *
+ * 数据来源：
+ * - 台账 / 快照 / 通道配置：本地文件只读；
+ * - 项目、会话、按小时：宿主 sessionPersistence 的只读 handle；
+ * - 余额与订阅窗口：优先查各通道官方接口（凭据经宿主 credentials seam 解析，
+ *   不落盘、不进日志、不返回给客户端），失败时回落到本地快照。
+ */
+import { mountKeyUsageRoutes } from './routes.js';
+import { createLiveQuotaService } from './live-quota.js';
+import { createSessionSource } from './sessions.js';
+export const name = 'dsh-key-usage';
+export function apply(ctx) {
+    // 会话服务是可选依赖：用 get 惰性取，缺了也只是会话相关页面显示空态
+    const sessionSource = createSessionSource({
+        get: (serviceName) => (typeof ctx.get === 'function' ? ctx.get(serviceName) : undefined),
+    });
+    // 凭据同样只在真正查询余额时经宿主 seam 解析；拿不到就回落快照
+    const liveQuota = createLiveQuotaService({
+        resolveCredential: async (reference) => {
+            const credentials = (typeof ctx.get === 'function' ? ctx.get('credentials') : undefined);
+            if (credentials !== undefined && typeof credentials.resolve === 'function') {
+                try {
+                    const hit = await credentials.resolve(reference);
+                    if (hit !== null && typeof hit.value === 'string' && hit.value.trim() !== '')
+                        return hit.value.trim();
+                }
+                catch {
+                    // 继续尝试进程环境变量
+                }
+            }
+            // 兜底：宿主把凭据放在进程环境里时直接取（只读环境变量，不碰任何凭据文件）
+            const fromEnv = process.env[reference];
+            return typeof fromEnv === 'string' ? fromEnv.trim() : '';
+        },
+    });
+    ctx.inject(['webServer'], (host) => {
+        host.effect(() => mountKeyUsageRoutes(host.webServer, sessionSource, liveQuota), 'dsh-key-usage: http routes');
+    });
+}

package/lib/ledger.js

@@ -0,0 +1,163 @@
+/**
+ * 用量台账读取与聚合：解析 ~/.dsh/dsh-usage/usage-ledger.json，
+ * 提供范围聚合、按模型/通道拆分、年度热力图序列。
+ * 纯函数实现，便于离线测试（不触达真实家目录）。
+ */
+/** 安全读取并解析台账文件；不存在或损坏时返回 null，由调用方决定空态。 */
+export function readLedger(ledgerPath, readFile) {
+    const raw = readFile(ledgerPath);
+    if (raw === null)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || typeof parsed.days !== 'object')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** 台账按天遍历（含端点），dateKey 形如 2026-10-13。 */
+export function forEachDay(ledger, fromDate, toDate, callback) {
+    const start = new Date(fromDate + 'T00:00:00Z');
+    const end = new Date(toDate + 'T00:00:00Z');
+    for (let time = start.getTime(); time <= end.getTime(); time += 86400000) {
+        const dateKey = new Date(time).toISOString().slice(0, 10);
+        const channels = ledger.days[dateKey];
+        if (channels)
+            callback(dateKey, channels);
+    }
+}
+function addToAccumulator(target, entry) {
+    target.calls += entry.calls;
+    target.inputTokens += entry.inputTokens;
+    target.outputTokens += entry.outputTokens;
+    target.cacheReadTokens += entry.cacheReadTokens;
+    target.cacheWriteTokens += entry.cacheWriteTokens;
+    target.reasoningTokens += entry.reasoningTokens;
+    target.cost += entry.cost;
+}
+function emptyAccumulator() {
+    return { calls: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0, cost: 0 };
+}
+/** 范围聚合：可选限定通道（provider id 列表），返回总计与逐日序列。 */
+export function aggregateRange(ledger, fromDate, toDate, providerFilter) {
+    const totals = emptyAccumulator();
+    const days = [];
+    forEachDay(ledger, fromDate, toDate, (dateKey, channels) => {
+        const dayAccumulator = emptyAccumulator();
+        const dayModels = [];
+        for (const [provider, models] of Object.entries(channels)) {
+            if (providerFilter !== null && !providerFilter.includes(provider))
+                continue;
+            for (const [model, entry] of Object.entries(models)) {
+                addToAccumulator(dayAccumulator, entry);
+                dayModels.push({ provider, model, date: dateKey, ...structuredClone(entry) });
+            }
+        }
+        if (dayModels.length === 0)
+            return;
+        addToAccumulator(totals, dayAccumulator);
+        days.push({
+            date: dateKey,
+            provider: '',
+            ...dayAccumulator,
+            models: dayModels.sort((first, second) => (second.inputTokens + second.outputTokens + second.cacheReadTokens) - (first.inputTokens + first.outputTokens + first.cacheReadTokens)),
+        });
+    });
+    return { totals: { date: '', ...totals }, days };
+}
+/** 年度热力图数据：起止范围内每天的总 tokens 与按模型拆分。 */
+export function buildHeatmap(ledger, fromDate, toDate) {
+    const result = [];
+    forEachDay(ledger, fromDate, toDate, (dateKey, channels) => {
+        const modelMap = new Map();
+        let dayTotal = 0;
+        for (const [provider, models] of Object.entries(channels)) {
+            for (const [model, entry] of Object.entries(models)) {
+                const totalTokens = entry.inputTokens + entry.outputTokens + entry.cacheReadTokens;
+                if (totalTokens <= 0)
+                    continue;
+                dayTotal += totalTokens;
+                const key = provider + '|' + model;
+                const bucket = modelMap.get(key);
+                if (bucket)
+                    bucket.totalTokens += totalTokens;
+                else
+                    modelMap.set(key, { provider, model, totalTokens });
+            }
+        }
+        if (dayTotal <= 0)
+            return;
+        result.push({
+            date: dateKey,
+            totalTokens: dayTotal,
+            models: [...modelMap.values()].sort((first, second) => second.totalTokens - first.totalTokens),
+        });
+    });
+    return result;
+}
+/** 按通道汇总指定范围（展示口径 tokens 不含 cacheWrite）。 */
+export function summarizeByProvider(ledger, fromDate, toDate) {
+    const byProvider = new Map();
+    forEachDay(ledger, fromDate, toDate, (_dateKey, channels) => {
+        for (const [provider, models] of Object.entries(channels)) {
+            let summary = byProvider.get(provider);
+            if (summary === undefined) {
+                summary = { provider, calls: 0, tokens: 0, cost: 0 };
+                byProvider.set(provider, summary);
+            }
+            for (const entry of Object.values(models)) {
+                summary.calls += entry.calls;
+                summary.tokens += entry.inputTokens + entry.outputTokens + entry.cacheReadTokens;
+                summary.cost += entry.cost;
+            }
+        }
+    });
+    return [...byProvider.values()];
+}
+/**
+ * 从台账反推模型均价表（`provider|model` 与退化到 `model` 两种键）。
+ * 台账只有「当天该模型的成本合计」，没有单价表，所以会话/项目成本只能估算，
+ * 展示时必须标注口径（见页脚口径说明）。
+ */
+export function buildPriceTable(ledger) {
+    const table = new Map();
+    const add = (key, tokens, cost) => {
+        const entry = table.get(key);
+        if (entry === undefined)
+            table.set(key, { tokens, cost });
+        else {
+            entry.tokens += tokens;
+            entry.cost += cost;
+        }
+    };
+    for (const channels of Object.values(ledger.days)) {
+        for (const [provider, models] of Object.entries(channels)) {
+            for (const [model, entry] of Object.entries(models)) {
+                const tokens = entry.inputTokens + entry.outputTokens + entry.cacheReadTokens;
+                if (tokens <= 0 || entry.cost <= 0)
+                    continue;
+                add(provider + '|' + model, tokens, entry.cost);
+                add(model, tokens, entry.cost);
+            }
+        }
+    }
+    return table;
+}
+/** 用均价表估算一组模型行的成本；没有任何可比价时返回 null（界面显示 —）。 */
+export function estimateCost(models, priceTable) {
+    let total = 0;
+    let matched = false;
+    for (const row of models) {
+        if (row.tokens <= 0)
+            continue;
+        const price = priceTable.get(row.provider + '|' + row.model) ?? priceTable.get(row.model);
+        if (price === undefined || price.tokens <= 0)
+            continue;
+        total += row.tokens * (price.cost / price.tokens);
+        matched = true;
+    }
+    return matched ? Math.round(total * 100) / 100 : null;
+}

package/lib/live-quota.js

@@ -0,0 +1,225 @@
+const REQUEST_TIMEOUT_MS = 6000;
+const MAX_RESPONSE_BYTES = 65536;
+const DEFAULT_TTL_MS = 60000;
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function textOf(value) {
+    if (typeof value === 'string' && value !== '')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return null;
+}
+/** OpenCode Go：GET https://opencode.ai/zen/go/v1/usage → usage.rolling / weekly / monthly。 */
+const OPENCODE_GO_SCHEME = {
+    url: () => 'https://opencode.ai/zen/go/v1/usage',
+    parse: (body) => {
+        const usage = isObject(body) && isObject(body.usage) ? body.usage : body;
+        if (!isObject(usage))
+            return { balance: null, windows: null };
+        const mapping = [['rolling', '5h'], ['weekly', 'week'], ['monthly', 'month']];
+        const windows = [];
+        for (const [sourceKey, windowKey] of mapping) {
+            const raw = usage[sourceKey];
+            if (!isObject(raw))
+                continue;
+            const percent = typeof raw.percent === 'number' ? raw.percent : Number(raw.percent);
+            if (!Number.isFinite(percent))
+                continue;
+            windows.push({
+                key: windowKey,
+                percent,
+                resetsAt: textOf(raw.resetsAt),
+                status: typeof raw.status === 'string' ? raw.status : null,
+            });
+        }
+        return { balance: null, windows: windows.length > 0 ? windows : null };
+    },
+};
+/** 官方余额类接口：GET {origin}<path>，凭据同为 Bearer。 */
+function balanceScheme(path, parse, fallbackOrigin) {
+    return {
+        url: (baseURL) => new URL(path, baseURL ?? fallbackOrigin).href,
+        parse: (body) => ({ balance: isObject(body) ? parse(body) : null, windows: null }),
+    };
+}
+const SCHEMES = {
+    'opencode-go': OPENCODE_GO_SCHEME,
+    // DeepSeek: GET {origin}/user/balance → balance_infos[{currency,total_balance,granted_balance,topped_up_balance}]
+    'deepseek-official': balanceScheme('/user/balance', (body) => {
+        const infos = Array.isArray(body.balance_infos) ? body.balance_infos : [];
+        const info = infos.find((entry) => isObject(entry) && entry.currency === 'CNY') ?? infos[0];
+        if (!isObject(info))
+            return null;
+        const balance = {};
+        const currency = textOf(info.currency);
+        const total = textOf(info.total_balance);
+        const granted = textOf(info.granted_balance);
+        const toppedUp = textOf(info.topped_up_balance);
+        if (currency !== null)
+            balance.currency = currency;
+        if (total !== null)
+            balance.totalBalance = total;
+        if (granted !== null)
+            balance.giftBalance = granted;
+        if (toppedUp !== null)
+            balance.topUpBalance = toppedUp;
+        return Object.keys(balance).length > 0 ? balance : null;
+    }, 'https://api.deepseek.com'),
+    // OpenRouter: GET {origin}/api/v1/credits（需要 Management Key）
+    openrouter: balanceScheme('/api/v1/credits', (body) => {
+        const data = isObject(body.data) ? body.data : null;
+        if (data === null)
+            return null;
+        const totalCredits = typeof data.total_credits === 'number' ? data.total_credits : null;
+        const totalUsage = typeof data.total_usage === 'number' ? data.total_usage : null;
+        if (totalCredits === null || totalUsage === null)
+            return null;
+        return { currency: 'USD', totalBalance: (totalCredits - totalUsage).toFixed(2) };
+    }, 'https://openrouter.ai'),
+    // Moonshot / Kimi: GET {origin}/v1/users/me/balance
+    moonshotai: balanceScheme('/v1/users/me/balance', (body) => {
+        const data = isObject(body.data) ? body.data : null;
+        if (data === null)
+            return null;
+        const balance = {};
+        const currency = textOf(data.currency);
+        const available = textOf(data.available_balance);
+        const cash = textOf(data.cash_balance);
+        const voucher = textOf(data.voucher_balance);
+        if (currency !== null)
+            balance.currency = currency;
+        if (available !== null)
+            balance.totalBalance = available;
+        if (voucher !== null)
+            balance.giftBalance = voucher;
+        if (cash !== null)
+            balance.topUpBalance = cash;
+        return Object.keys(balance).length > 0 ? balance : null;
+    }, 'https://api.moonshot.cn'),
+    // Z.AI / GLM: GET {origin}/api/paas/v4/balance
+    zai: balanceScheme('/api/paas/v4/balance', (body) => {
+        const data = isObject(body.data) ? body.data : null;
+        if (data === null)
+            return null;
+        const balance = { currency: 'CNY' };
+        const total = textOf(data.total_balance);
+        const available = textOf(data.available_balance);
+        if (total !== null)
+            balance.totalBalance = total;
+        if (available !== null)
+            balance.availableBalance = available;
+        return Object.keys(balance).length > 1 ? balance : null;
+    }, 'https://api.z.ai'),
+};
+/** provider id → 方案 id（事件里的 provider 可能是路由名，先取末段）。 */
+export function schemeIdOf(provider) {
+    const tail = provider.includes('/') ? provider.slice(provider.lastIndexOf('/') + 1) : provider;
+    if (tail === 'opencode-go' || tail === 'opencode')
+        return 'opencode-go';
+    if (tail === 'deepseek-official' || tail === 'deepseek')
+        return 'deepseek-official';
+    if (tail === 'openrouter')
+        return 'openrouter';
+    if (tail === 'moonshotai' || tail === 'moonshotai-cn' || tail === 'kimi' || tail === 'kimi-coding')
+        return 'moonshotai';
+    if (tail === 'zai' || tail === 'zai-coding-cn')
+        return 'zai';
+    return null;
+}
+async function queryOne(schemeId, apiKey, baseURL, fetchImpl) {
+    const scheme = SCHEMES[schemeId];
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(scheme.url(baseURL), {
+            headers: { Authorization: 'Bearer ' + apiKey, Accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (response.status === 401 || response.status === 403)
+            return { balance: null, windows: null, error: 'unauthorized' };
+        if (!response.ok)
+            return { balance: null, windows: null, error: 'http-' + String(response.status) };
+        const raw = await response.text();
+        if (raw.length > MAX_RESPONSE_BYTES)
+            return { balance: null, windows: null, error: 'too-large' };
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            return { balance: null, windows: null, error: 'bad-json' };
+        }
+        const parsed = scheme.parse(body);
+        if (parsed.balance === null && parsed.windows === null)
+            return { balance: null, windows: null, error: 'bad-json' };
+        return { ...parsed, error: null };
+    }
+    catch (error) {
+        const aborted = error instanceof Error && error.name === 'AbortError';
+        return { balance: null, windows: null, error: aborted ? 'timeout' : 'network' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 建立实时查询服务。
+ * @param resolver - 凭据解析（宿主 credentials seam）
+ * @param fetchImpl - 可注入的 fetch（测试用）
+ * @param ttlMs - 缓存有效期
+ */
+export function createLiveQuotaService(resolver, fetchImpl = fetch, ttlMs = DEFAULT_TTL_MS) {
+    let cache = new Map();
+    let inFlight = null;
+    const isStale = () => {
+        const now = Date.now();
+        for (const entry of cache.values())
+            if (now - entry.fetchedAt > ttlMs)
+                return true;
+        return cache.size === 0;
+    };
+    async function refresh(channels) {
+        const targets = channels
+            .map((channel) => ({ channel, schemeId: schemeIdOf(channel.provider) }))
+            .filter((entry) => entry.schemeId !== null);
+        const results = await Promise.all(targets.map(async ({ channel, schemeId }) => {
+            const apiKey = channel.apiKeyEnv === null ? '' : await resolver.resolveCredential(channel.apiKeyEnv);
+            const fetchedAt = Date.now();
+            if (apiKey === '') {
+                return [channel.provider, { provider: channel.provider, ok: false, error: 'no-key', fetchedAt, balance: null, windows: null }];
+            }
+            const outcome = await queryOne(schemeId, apiKey, channel.baseURL, fetchImpl);
+            return [channel.provider, {
+                    provider: channel.provider,
+                    ok: outcome.error === null,
+                    error: outcome.error,
+                    fetchedAt,
+                    balance: outcome.balance,
+                    windows: outcome.windows,
+                }];
+        }));
+        // 只保留本次仍然配置了的通道，并保留没有方案可查的旧条目以免频繁抖动
+        const next = new Map();
+        for (const [provider, result] of results)
+            next.set(provider, result);
+        for (const [provider, entry] of cache)
+            if (!next.has(provider))
+                next.set(provider, entry);
+        cache = next;
+        return cache;
+    }
+    return {
+        cached: () => cache,
+        refreshIfStale: async (channels, force = false) => {
+            if (isStale() || force) {
+                if (inFlight === null) {
+                    inFlight = refresh(channels).finally(() => { inFlight = null; });
+                }
+                return inFlight;
+            }
+            return cache;
+        },
+    };
+}

package/lib/merge.js

@@ -0,0 +1,156 @@
+import { attributeModelKey } from './session-usage.js';
+/** 把会话记录摊平成按天行（provider 用已知通道名归一）。 */
+export function sessionDayRows(records, knownProviders) {
+    const rows = [];
+    for (const record of records) {
+        for (const day of record.summary.days) {
+            for (const model of day.models) {
+                const attribution = attributeModelKey(model.key, knownProviders);
+                rows.push({
+                    date: day.date,
+                    provider: attribution.provider,
+                    model: attribution.model,
+                    calls: model.calls,
+                    inputTokens: model.buckets.inputTokens,
+                    outputTokens: model.buckets.outputTokens,
+                    cacheReadTokens: model.buckets.cacheReadTokens,
+                });
+            }
+        }
+    }
+    return rows;
+}
+const DAY_MS = 86400000;
+const MAX_RANGE_DAYS = 400;
+function dateKeysOf(from, to) {
+    if (from === '' || to === '')
+        return [];
+    const start = new Date(from + 'T00:00:00Z').getTime();
+    const end = new Date(to + 'T00:00:00Z').getTime();
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end < start)
+        return [];
+    const total = Math.min(Math.floor((end - start) / DAY_MS) + 1, MAX_RANGE_DAYS);
+    const keys = [];
+    for (let offset = 0; offset < total; offset += 1) {
+        keys.push(new Date(start + offset * DAY_MS).toISOString().slice(0, 10));
+    }
+    return keys;
+}
+function synthesizeDay(date, rows) {
+    // 同一天同一模型可能来自多个会话，必须先按 `provider|model` 合并，
+    // 否则热力图与每日细目会出现多条同名重复行。
+    const byModel = new Map();
+    let calls = 0;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    for (const row of rows) {
+        calls += row.calls;
+        inputTokens += row.inputTokens;
+        outputTokens += row.outputTokens;
+        cacheReadTokens += row.cacheReadTokens;
+        const key = row.provider + '|' + row.model;
+        const entry = byModel.get(key);
+        if (entry === undefined) {
+            byModel.set(key, {
+                date,
+                provider: row.provider,
+                model: row.model,
+                calls: row.calls,
+                inputTokens: row.inputTokens,
+                outputTokens: row.outputTokens,
+                cacheReadTokens: row.cacheReadTokens,
+                reasoningTokens: 0,
+                // 会话事件没有官方成本，成本列对这些天留 0，由界面按计费模式展示
+                cost: 0,
+            });
+            continue;
+        }
+        entry.calls += row.calls;
+        entry.inputTokens += row.inputTokens;
+        entry.outputTokens += row.outputTokens;
+        entry.cacheReadTokens += row.cacheReadTokens;
+    }
+    const models = [...byModel.values()];
+    return {
+        date,
+        provider: '',
+        calls,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        reasoningTokens: 0,
+        cost: 0,
+        models: models.sort((first, second) => (second.inputTokens + second.outputTokens + second.cacheReadTokens)
+            - (first.inputTokens + first.outputTokens + first.cacheReadTokens)),
+    };
+}
+/**
+ * 合并台账与会话序列（按天取舍）。
+ * @param ledgerDays - 台账范围聚合结果
+ * @param sessionRows - 会话事件摊平行（可先按通道过滤）
+ * @param from - 范围起始（含）
+ * @param to - 范围结束（含）
+ */
+export function mergeDailySeries(ledgerDays, sessionRows, from, to) {
+    const ledgerByDate = new Map(ledgerDays.map((day) => [day.date, day]));
+    const sessionByDate = new Map();
+    for (const row of sessionRows) {
+        const bucket = sessionByDate.get(row.date);
+        if (bucket === undefined)
+            sessionByDate.set(row.date, [row]);
+        else
+            bucket.push(row);
+    }
+    const days = [];
+    const sessionDates = [];
+    for (const date of dateKeysOf(from, to)) {
+        const ledgerDay = ledgerByDate.get(date);
+        if (ledgerDay !== undefined) {
+            days.push(ledgerDay);
+            continue;
+        }
+        const rows = sessionByDate.get(date);
+        if (rows === undefined || rows.length === 0)
+            continue;
+        sessionDates.push(date);
+        days.push(synthesizeDay(date, rows));
+    }
+    return { days, sessionDates };
+}
+/** 合并后的范围总计（展示口径 tokens 不含 cacheWrite）。 */
+export function totalsOfMerged(days) {
+    const totals = { date: '', calls: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, reasoningTokens: 0, cost: 0 };
+    for (const day of days) {
+        totals.calls += day.calls;
+        totals.inputTokens += day.inputTokens;
+        totals.outputTokens += day.outputTokens;
+        totals.cacheReadTokens += day.cacheReadTokens;
+        totals.reasoningTokens += day.reasoningTokens;
+        totals.cost += day.cost;
+    }
+    return totals;
+}
+/** 按通道汇总合并序列（总览「今日 / 近 30 天」用）。 */
+export function summarizeMergedByProvider(days, from, to) {
+    const byProvider = new Map();
+    for (const day of days) {
+        if (day.date < from || day.date > to)
+            continue;
+        for (const model of day.models) {
+            let summary = byProvider.get(model.provider);
+            if (summary === undefined) {
+                summary = { provider: model.provider, calls: 0, tokens: 0, cost: 0 };
+                byProvider.set(model.provider, summary);
+            }
+            summary.calls += model.calls;
+            summary.tokens += model.inputTokens + model.outputTokens + model.cacheReadTokens;
+            summary.cost += model.cost;
+        }
+    }
+    return [...byProvider.values()];
+}
+/** 会话记录里是否有指定日期的数据（总览标注来源用）。 */
+export function hasSessionDate(records, date) {
+    return records.some((record) => record.summary.days.some((day) => day.date === date && day.tokens > 0));
+}