gcusage 0.1.0 → 0.1.2

package/README.md

@@ -19,25 +19,32 @@ Gemini CLI 用量统计工具 / Usage report for Gemini CLI
 		"enabled": true,
 		"target": "local",
 		"otlpEndpoint": "",
-		"outfile": "/Users/enxianzhou/.gemini/telemetry.log",
+    "outfile": "/Users/<yourname>/.gemini/telemetry.log",
 		"logPrompts": false
 	}
 }
 ```
 
-## 安装与构建 / Install & Build
+说明：
+- 必须开启 telemetry 并指定 `outfile`，否则不会生成 `telemetry.log`
+- 使用绝对路径可避免 `~` 或相对路径导致写入失败
+- `outfile` 路径必须与 `gcusage` 读取路径一致（默认读取 `~/.gemini/telemetry.log`）
+- 日志包含完整响应内容，建议使用 `trim` 进行瘦身
+- Windows 示例路径：`C:\\Users\\<yourname>\\.gemini\\telemetry.log`
 
-```bash
-npm install
-npm run build
-```
+## 使用方式 / Usage
+
+已发布版本：`gcusage@0.1.0`
+npm 包地址： https://www.npmjs.com/package/gcusage
+
+## 系统支持 / Platform
 
-## 基本用法 / Basic Usage
+- 支持：macOS / Linux / Windows
 
 默认输出最近 6 天（含今天）的日统计：
 
 ```bash
-node dist/index.js
+npx gcusage
 ```
 
 输出：每天一行，展示 Models 列（多模型换行）与各类型 token 总量。
@@ -45,7 +52,7 @@ node dist/index.js
 按 session 输出（当天每个 session 一行）：
 
 ```bash
-node dist/index.js --period session
+npx gcusage --period session
 ```
 
 输出：当天每个 session 的最终累计值。
@@ -53,7 +60,7 @@ node dist/index.js --period session
 按周（显示该周内每天数据）：
 
 ```bash
-node dist/index.js --period week
+npx gcusage --period week
 ```
 
 输出：当前周（周一开始）内每日数据。
@@ -61,7 +68,7 @@ node dist/index.js --period week
 按月（显示该月内每天数据）：
 
 ```bash
-node dist/index.js --period month
+npx gcusage --period month
 ```
 
 输出：当前月内每日数据。
@@ -69,7 +76,7 @@ node dist/index.js --period month
 从指定日期开始统计一周：
 
 ```bash
-node dist/index.js --period week --since 2026-01-01
+npx gcusage --period week --since 2026-01-01
 ```
 
 输出：从 2026-01-01 开始的 7 天数据。
@@ -77,7 +84,7 @@ node dist/index.js --period week --since 2026-01-01
 指定范围（覆盖 week/month 计算范围）：
 
 ```bash
-node dist/index.js --period month --since 2026-01-01 --until 2026-01-15
+npx gcusage --period month --since 2026-01-01 --until 2026-01-15
 ```
 
 输出：2026-01-01 到 2026-01-15 的每日数据。
@@ -85,7 +92,7 @@ node dist/index.js --period month --since 2026-01-01 --until 2026-01-15
 过滤模型或类型：
 
 ```bash
-node dist/index.js --model gemini-2.5-flash-lite --type input
+npx gcusage --model gemini-2.5-flash-lite --type input
 ```
 
 输出：只统计指定模型与类型的数据。
@@ -111,7 +118,7 @@ Date | Models | Input | Output | Thought | Cache | Tool | Total Tokens
 仅保留 token 相关数据（覆盖原文件）：
 
 ```bash
-node dist/index.js trim
+npx gcusage trim
 ```
 
 输出：`telemetry.log` 体积显著减小，统计不受影响。

package/dist/core/aggregate.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSessionSummaries = buildSessionSummaries;
+exports.toSessionTotals = toSessionTotals;
+exports.aggregateSessionsToDay = aggregateSessionsToDay;
+exports.aggregateByDay = aggregateByDay;
+exports.aggregateBySession = aggregateBySession;
+exports.addTypeValue = addTypeValue;
+exports.sumAll = sumAll;
+exports.sumTotals = sumTotals;
+const time_1 = require("./utils/time");
+function buildSessionSummaries(points) {
+    const sessionMap = new Map();
+    for (const p of points) {
+        if (!p.sessionId)
+            continue;
+        const entry = sessionMap.get(p.sessionId);
+        const modelTypeKey = `${p.model}||${p.type}`;
+        if (!entry) {
+            const map = new Map();
+            map.set(modelTypeKey, { timestampMs: p.timestampMs, value: p.value, type: p.type });
+            sessionMap.set(p.sessionId, {
+                sessionStartMs: p.timestampMs,
+                models: new Set([p.model]),
+                lastByModelType: map
+            });
+            continue;
+        }
+        entry.sessionStartMs = Math.min(entry.sessionStartMs, p.timestampMs);
+        entry.models.add(p.model);
+        const last = entry.lastByModelType.get(modelTypeKey);
+        if (!last || p.timestampMs >= last.timestampMs) {
+            entry.lastByModelType.set(modelTypeKey, { timestampMs: p.timestampMs, value: p.value, type: p.type });
+        }
+    }
+    const summaries = [];
+    for (const [sessionId, entry] of sessionMap.entries()) {
+        const totals = { input: 0, output: 0, thought: 0, cache: 0, tool: 0 };
+        for (const item of entry.lastByModelType.values()) {
+            addTypeValue(totals, item.type, item.value);
+        }
+        summaries.push({
+            sessionId,
+            sessionStartMs: entry.sessionStartMs,
+            models: entry.models,
+            input: totals.input,
+            output: totals.output,
+            thought: totals.thought,
+            cache: totals.cache,
+            tool: totals.tool
+        });
+    }
+    summaries.sort((a, b) => a.sessionStartMs - b.sessionStartMs || a.sessionId.localeCompare(b.sessionId));
+    return summaries;
+}
+function toSessionTotals(summary) {
+    return {
+        date: (0, time_1.toDateKey)(summary.sessionStartMs),
+        sessionId: summary.sessionId,
+        models: summary.models,
+        input: summary.input,
+        output: summary.output,
+        thought: summary.thought,
+        cache: summary.cache,
+        tool: summary.tool
+    };
+}
+function aggregateSessionsToDay(summaries) {
+    const map = new Map();
+    for (const s of summaries) {
+        const dateKey = (0, time_1.toDateKey)(s.sessionStartMs);
+        let row = map.get(dateKey);
+        if (!row) {
+            row = {
+                date: dateKey,
+                models: new Set(),
+                input: 0,
+                output: 0,
+                thought: 0,
+                cache: 0,
+                tool: 0
+            };
+            map.set(dateKey, row);
+        }
+        for (const m of s.models)
+            row.models.add(m);
+        row.input += s.input;
+        row.output += s.output;
+        row.thought += s.thought;
+        row.cache += s.cache;
+        row.tool += s.tool;
+    }
+    const rows = Array.from(map.values());
+    rows.sort((a, b) => a.date.localeCompare(b.date));
+    return rows;
+}
+function aggregateByDay(points) {
+    const map = new Map();
+    for (const p of points) {
+        const dateKey = (0, time_1.toDateKey)(p.timestampMs);
+        let row = map.get(dateKey);
+        if (!row) {
+            row = {
+                date: dateKey,
+                models: new Set(),
+                input: 0,
+                output: 0,
+                thought: 0,
+                cache: 0,
+                tool: 0
+            };
+            map.set(dateKey, row);
+        }
+        row.models.add(p.model);
+        addTypeValue(row, p.type, p.value);
+    }
+    const rows = Array.from(map.values());
+    rows.sort((a, b) => a.date.localeCompare(b.date));
+    return rows;
+}
+function aggregateBySession(points) {
+    const map = new Map();
+    for (const p of points) {
+        if (!p.sessionId)
+            continue;
+        const dateKey = (0, time_1.toDateKey)(p.timestampMs);
+        const key = `${dateKey}||${p.sessionId}`;
+        let row = map.get(key);
+        if (!row) {
+            row = {
+                date: dateKey,
+                sessionId: p.sessionId,
+                models: new Set(),
+                input: 0,
+                output: 0,
+                thought: 0,
+                cache: 0,
+                tool: 0
+            };
+            map.set(key, row);
+        }
+        row.models.add(p.model);
+        addTypeValue(row, p.type, p.value);
+    }
+    const rows = Array.from(map.values());
+    rows.sort((a, b) => {
+        if (a.date !== b.date)
+            return a.date.localeCompare(b.date);
+        return a.sessionId.localeCompare(b.sessionId);
+    });
+    return rows;
+}
+function addTypeValue(target, type, value) {
+    if (type === "input")
+        target.input += value;
+    else if (type === "output")
+        target.output += value;
+    else if (type === "thought")
+        target.thought += value;
+    else if (type === "cache")
+        target.cache += value;
+    else if (type === "tool")
+        target.tool += value;
+}
+function sumAll(row) {
+    return row.input + row.output + row.thought + row.cache + row.tool;
+}
+function sumTotals(totals) {
+    return totals.input + totals.output + totals.thought + totals.cache + totals.tool;
+}

package/dist/core/commands/trim.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTrim = runTrim;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const messages_1 = require("../../messages");
+const split_1 = require("../logs/split");
+const metrics_1 = require("../metrics");
+async function runTrim() {
+    const logPath = path_1.default.join(os_1.default.homedir(), ".gemini", "telemetry.log");
+    const backupPath = path_1.default.join(os_1.default.homedir(), ".gemini", "telemetry.log.bak");
+    try {
+        const stat = await fs_1.default.promises.stat(logPath);
+        if (!stat.isFile()) {
+            console.error(messages_1.MESSAGES.NO_TELEMETRY);
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(messages_1.MESSAGES.NO_TELEMETRY);
+        process.exit(1);
+    }
+    await fs_1.default.promises.copyFile(logPath, backupPath);
+    const content = await fs_1.default.promises.readFile(logPath, "utf8");
+    const objects = (0, split_1.splitJsonObjects)(content);
+    const lastPoints = new Map();
+    for (const objText of objects) {
+        let obj;
+        try {
+            obj = JSON.parse(objText);
+        }
+        catch {
+            continue;
+        }
+        const points = (0, metrics_1.extractTokenUsageDataPoints)(obj);
+        for (const dp of points) {
+            const sessionId = (0, metrics_1.readSessionId)(dp) || "no-session";
+            const model = (0, metrics_1.readAttributeValueFromDataPoint)(dp, "model") || "unknown";
+            const type = (0, metrics_1.readAttributeValueFromDataPoint)(dp, "type") || "unknown";
+            const time = (0, metrics_1.readTimestampMs)(dp);
+            if (time === null)
+                continue;
+            const key = `${sessionId}||${model}||${type}`;
+            const prev = lastPoints.get(key);
+            if (!prev || time >= prev.timestampMs) {
+                lastPoints.set(key, { timestampMs: time, dataPoint: dp });
+            }
+        }
+    }
+    const dataPoints = Array.from(lastPoints.values()).map((v) => v.dataPoint);
+    const minimalBlock = {
+        descriptor: { name: "gemini_cli.token.usage" },
+        dataPoints
+    };
+    const outputText = JSON.stringify(minimalBlock);
+    await fs_1.default.promises.writeFile(logPath, outputText, "utf8");
+    await fs_1.default.promises.unlink(backupPath);
+    console.log(messages_1.MESSAGES.TRIM_DONE);
+}

package/dist/core/logs/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findLogFiles = findLogFiles;
+exports.parseLogFile = parseLogFile;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const metrics_1 = require("../metrics");
+const split_1 = require("./split");
+async function findLogFiles() {
+    const logPath = path_1.default.join(os_1.default.homedir(), ".gemini", "telemetry.log");
+    try {
+        const stat = await fs_1.default.promises.stat(logPath);
+        if (stat.isFile())
+            return [logPath];
+    }
+    catch {
+        return [];
+    }
+    return [];
+}
+async function parseLogFile(filePath) {
+    const points = [];
+    const content = await fs_1.default.promises.readFile(filePath, "utf8");
+    const objects = (0, split_1.splitJsonObjects)(content);
+    for (const objText of objects) {
+        let obj;
+        try {
+            obj = JSON.parse(objText);
+        }
+        catch {
+            continue;
+        }
+        const extracted = (0, metrics_1.extractMetricPoints)(obj);
+        if (extracted.length > 0) {
+            points.push(...extracted);
+        }
+    }
+    return points;
+}

package/dist/core/logs/split.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitJsonObjects = splitJsonObjects;
+function splitJsonObjects(input) {
+    const results = [];
+    let depth = 0;
+    let inString = false;
+    let escapeNext = false;
+    let start = -1;
+    for (let i = 0; i < input.length; i += 1) {
+        const ch = input[i];
+        if (inString) {
+            if (escapeNext) {
+                escapeNext = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escapeNext = true;
+                continue;
+            }
+            if (ch === "\"") {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === "\"") {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            if (depth === 0) {
+                start = i;
+            }
+            depth += 1;
+            continue;
+        }
+        if (ch === "}") {
+            if (depth > 0) {
+                depth -= 1;
+                if (depth === 0 && start >= 0) {
+                    const chunk = input.slice(start, i + 1).trim();
+                    if (chunk)
+                        results.push(chunk);
+                    start = -1;
+                }
+            }
+        }
+    }
+    return results;
+}

package/dist/core/metrics/index.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractMetricPoints = extractMetricPoints;
+exports.extractTokenMetricBlocks = extractTokenMetricBlocks;
+exports.extractTokenUsageDataPoints = extractTokenUsageDataPoints;
+exports.readAttributeValueFromDataPoint = readAttributeValueFromDataPoint;
+exports.readSessionId = readSessionId;
+exports.buildPointFromDataPoint = buildPointFromDataPoint;
+exports.readNumberValue = readNumberValue;
+exports.readTimestampMs = readTimestampMs;
+exports.readAttributes = readAttributes;
+exports.readAttributeValue = readAttributeValue;
+const METRIC_NAME = "gemini_cli.token.usage";
+function extractMetricPoints(root) {
+    const points = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node)
+            continue;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                stack.push(item);
+            continue;
+        }
+        if (typeof node !== "object")
+            continue;
+        const obj = node;
+        const name = typeof obj.name === "string" ? obj.name : null;
+        const descriptorName = obj.descriptor && typeof obj.descriptor === "object"
+            ? typeof obj.descriptor.name === "string"
+                ? obj.descriptor.name
+                : null
+            : null;
+        if (name === METRIC_NAME || descriptorName === METRIC_NAME) {
+            const dataPoints = obj.dataPoints;
+            if (Array.isArray(dataPoints)) {
+                for (const dp of dataPoints) {
+                    const metric = buildPointFromDataPoint(dp);
+                    if (metric)
+                        points.push(metric);
+                }
+            }
+        }
+        for (const value of Object.values(obj)) {
+            stack.push(value);
+        }
+    }
+    return points;
+}
+function extractTokenMetricBlocks(root) {
+    const blocks = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node)
+            continue;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                stack.push(item);
+            continue;
+        }
+        if (typeof node !== "object")
+            continue;
+        const obj = node;
+        const name = typeof obj.name === "string" ? obj.name : null;
+        const descriptorName = obj.descriptor && typeof obj.descriptor === "object"
+            ? typeof obj.descriptor.name === "string"
+                ? obj.descriptor.name
+                : null
+            : null;
+        if (name === METRIC_NAME || descriptorName === METRIC_NAME) {
+            const dataPoints = obj.dataPoints;
+            if (Array.isArray(dataPoints)) {
+                blocks.push({
+                    descriptor: { name: METRIC_NAME },
+                    dataPoints
+                });
+            }
+        }
+        for (const value of Object.values(obj)) {
+            stack.push(value);
+        }
+    }
+    return blocks;
+}
+function extractTokenUsageDataPoints(root) {
+    const points = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node)
+            continue;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                stack.push(item);
+            continue;
+        }
+        if (typeof node !== "object")
+            continue;
+        const obj = node;
+        const name = typeof obj.name === "string" ? obj.name : null;
+        const descriptorName = obj.descriptor && typeof obj.descriptor === "object"
+            ? typeof obj.descriptor.name === "string"
+                ? obj.descriptor.name
+                : null
+            : null;
+        if (name === METRIC_NAME || descriptorName === METRIC_NAME) {
+            const dataPoints = obj.dataPoints;
+            if (Array.isArray(dataPoints)) {
+                for (const dp of dataPoints) {
+                    if (dp && typeof dp === "object")
+                        points.push(dp);
+                }
+            }
+        }
+        for (const value of Object.values(obj)) {
+            stack.push(value);
+        }
+    }
+    return points;
+}
+function readAttributeValueFromDataPoint(dp, key) {
+    const attrs = readAttributes(dp.attributes);
+    return attrs[key] || null;
+}
+function readSessionId(dp) {
+    const attrs = readAttributes(dp.attributes);
+    return attrs["session.id"] || attrs["session_id"] || null;
+}
+function buildPointFromDataPoint(dataPoint) {
+    if (!dataPoint || typeof dataPoint !== "object")
+        return null;
+    const dp = dataPoint;
+    const value = readNumberValue(dp);
+    if (value === null)
+        return null;
+    const timestampMs = readTimestampMs(dp);
+    if (timestampMs === null)
+        return null;
+    const attrs = readAttributes(dp.attributes);
+    const model = attrs.model || attrs["model"] || "unknown";
+    const type = attrs.type || attrs["type"] || "unknown";
+    const sessionId = attrs["session.id"] || attrs["session_id"] || null;
+    return {
+        timestampMs,
+        model,
+        type,
+        sessionId,
+        value
+    };
+}
+function readNumberValue(dp) {
+    const asInt = dp.asInt;
+    const asDouble = dp.asDouble;
+    const value = dp.value;
+    if (typeof asInt === "number")
+        return asInt;
+    if (typeof asDouble === "number")
+        return asDouble;
+    if (typeof value === "number")
+        return value;
+    if (typeof asInt === "string") {
+        const n = Number(asInt);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    return null;
+}
+function readTimestampMs(dp) {
+    const timeUnixNano = dp.timeUnixNano;
+    const endTimeUnixNano = dp.endTimeUnixNano;
+    const timeUnix = dp.timeUnix;
+    const time = dp.time;
+    const endTime = dp.endTime;
+    const startTime = dp.startTime;
+    if (Array.isArray(endTime) && endTime.length >= 2) {
+        const sec = Number(endTime[0]);
+        const nsec = Number(endTime[1]);
+        if (!Number.isNaN(sec) && !Number.isNaN(nsec)) {
+            return sec * 1000 + Math.floor(nsec / 1e6);
+        }
+    }
+    if (Array.isArray(startTime) && startTime.length >= 2) {
+        const sec = Number(startTime[0]);
+        const nsec = Number(startTime[1]);
+        if (!Number.isNaN(sec) && !Number.isNaN(nsec)) {
+            return sec * 1000 + Math.floor(nsec / 1e6);
+        }
+    }
+    const candidate = typeof timeUnixNano === "string" || typeof timeUnixNano === "number"
+        ? timeUnixNano
+        : typeof endTimeUnixNano === "string" || typeof endTimeUnixNano === "number"
+            ? endTimeUnixNano
+            : typeof timeUnix === "string" || typeof timeUnix === "number"
+                ? timeUnix
+                : typeof time === "string" || typeof time === "number"
+                    ? time
+                    : null;
+    if (candidate === null)
+        return null;
+    const num = Number(candidate);
+    if (Number.isNaN(num))
+        return null;
+    if (num > 1e15) {
+        return Math.floor(num / 1e6);
+    }
+    if (num > 1e12) {
+        return Math.floor(num / 1e3);
+    }
+    return Math.floor(num);
+}
+function readAttributes(attrs) {
+    if (!attrs)
+        return {};
+    if (Array.isArray(attrs)) {
+        const result = {};
+        for (const item of attrs) {
+            if (!item || typeof item !== "object")
+                continue;
+            const obj = item;
+            const key = typeof obj.key === "string" ? obj.key : null;
+            if (!key)
+                continue;
+            const value = obj.value;
+            const strValue = readAttributeValue(value);
+            if (strValue !== null)
+                result[key] = strValue;
+        }
+        return result;
+    }
+    if (typeof attrs === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(attrs)) {
+            const strValue = readAttributeValue(value);
+            if (strValue !== null)
+                result[key] = strValue;
+        }
+        return result;
+    }
+    return {};
+}
+function readAttributeValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    if (!value || typeof value !== "object")
+        return null;
+    const obj = value;
+    const stringValue = obj.stringValue;
+    if (typeof stringValue === "string")
+        return stringValue;
+    const intValue = obj.intValue;
+    if (typeof intValue === "string" || typeof intValue === "number") {
+        return String(intValue);
+    }
+    const doubleValue = obj.doubleValue;
+    if (typeof doubleValue === "string" || typeof doubleValue === "number") {
+        return String(doubleValue);
+    }
+    return null;
+}