@tsa-group/claude-usage 0.3.0

package/dist/events.js

@@ -0,0 +1,448 @@
+/**
+ * 本機資料 → wire schema 的**唯一權威映射層**（token_events 與 limit_snapshots 兩條流）。
+ *
+ * Per-event token extraction from Claude Code JSONL — the ONE authoritative extractor.
+ * 其他模組一律 import 這裡，不要各自再寫一份：這個專案已經為「同一份映射存兩份」
+ * 付過三次代價（三份 extractor、兩份 severity 映射、schema 與 .proto 各一份），
+ * 其中一次讓 stg.v_sessions.message_count 高估了 6.73 倍（4568 vs 實際 679）。
+ *
+ * 四個實測依據：
+ *   1. 去重鍵是 (message_id, requestId) 複合鍵。單用 message_id 會漏重試產生的
+ *      重複；實測 2,121 筆原始只有 550 個 distinct 複合鍵（高估 4.06 倍）。
+ *   2. cache_creation 必須拆 5m / 1h。1h 是 base x2、5m 是 base x1.25，實測用量幾乎
+ *      全落 1h，合成一個數字套 5m 費率會低估約 37.5%。
+ *   3. subagent 在 projects 底下深一層的 subagents/agent-*.jsonl，且 isSidechain=true
+ *      只出現在那些檔案裡，目錄走訪是發現機制、isSidechain 是佐證。
+ *   4. usage.iterations[] 與 top-level 相等（1505/1505 筆長度為 1），top-level 是
+ *      rollup，永不加總 iterations。
+ *
+ * 增量游標（per-file byte offset，存 ~/.claude-usage/cursor.json）：
+ *   JSONL 是 append-only，所以記「這個檔讀到第幾個 byte」就能精確只讀新增部分，
+ *   不需要時間戳 lookback（時間戳 lookback 會因為 JSONL 非嚴格時間遞增而漏資料，
+ *   或為了保險而重送整個 lookback 窗）。兩個必須處理的邊界：
+ *     - 尾端半行：daemon 可能在 Claude Code 正在寫一行的中間讀檔，只吃到最後一個
+ *       換行為止，offset 不越過不完整的行。
+ *     - 檔案縮小（compaction/改寫）：size < offset 時整檔重讀，產生的重複由 BQ 的
+ *       stg 去重 view 吸收。
+ *
+ * 為什麼到處是 nn(...)：Python 的 dict.get() 缺鍵回 None，序列化成 "k": null；
+ * JS 的 obj?.k 缺鍵回 undefined，而 JSON.stringify 會把整個 key 丟掉。對 server 來說
+ * 兩者都是 NULL，但差異測試會整排噴紅、也讓「這個欄位到底有沒有被送過」變得說不
+ * 清楚。統一轉成 null，wire payload 就與 Python 版逐欄一致。
+ */
+import { closeSync, openSync, readSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { cursorPath, healthPath, projectsDir, snapPath } from "./paths.js";
+import { h16, readJson, writeJsonAtomic } from "./util.js";
+const nn = (v) => (v === undefined ? null : v);
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+// ───────────────────────────── 檔案發現 ─────────────────────────────
+/**
+ * 主 session 檔 + subagent 檔。subagent 深一層，且只有那裡有 isSidechain。
+ *
+ * 刻意手寫走訪而不用 fs.globSync：後者要 Node 22+，而這兩個 pattern 深度固定、
+ * 十幾行就寫完。為此把同事的 Node 版本下限抬高兩個大版本並不划算。
+ */
+export function files() {
+    const root = projectsDir();
+    const out = [];
+    let projects;
+    try {
+        projects = readdirSync(root, { withFileTypes: true })
+            // glob 的 * 不匹配以 . 開頭的名字，readdirSync 會。不濾掉的話兩個實作看到的
+            // 檔案集合就不同，而讀取順序會影響去重的「第一筆勝出」。
+            .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+            .map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    for (const p of projects) {
+        const pdir = join(root, p);
+        let entries;
+        try {
+            entries = readdirSync(pdir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            // projects/<proj>/*.jsonl -- 主 session
+            if (e.isFile() && e.name.endsWith(".jsonl") && !e.name.startsWith(".")) {
+                out.push(join(pdir, e.name));
+            }
+            // projects/<proj>/<sub>/subagents/agent-*.jsonl -- subagent
+            if (e.isDirectory() && !e.name.startsWith(".")) {
+                const sub = join(pdir, e.name, "subagents");
+                try {
+                    for (const f of readdirSync(sub, { withFileTypes: true })) {
+                        if (f.isFile() && f.name.startsWith("agent-") && f.name.endsWith(".jsonl")) {
+                            out.push(join(sub, f.name));
+                        }
+                    }
+                }
+                catch {
+                    // 沒有 subagents 目錄是常態
+                }
+            }
+        }
+    }
+    return out.sort();
+}
+export const emptyCursor = () => ({ files: {}, snapshots: 0 });
+export function loadCursor() {
+    const c = readJson(cursorPath());
+    if (!isObj(c))
+        return emptyCursor();
+    // v1 是扁平形狀 {path: offset}，要遷移。不遷移的話既有安裝會把全部歷史重讀一次。
+    if (!("files" in c)) {
+        const f = {};
+        for (const [k, v] of Object.entries(c)) {
+            if (typeof v === "number" && Number.isInteger(v))
+                f[k] = v;
+        }
+        return { files: f, snapshots: 0 };
+    }
+    return {
+        files: isObj(c["files"]) ? c["files"] : {},
+        snapshots: typeof c["snapshots"] === "number" ? c["snapshots"] : 0,
+    };
+}
+export function saveCursor(cur) {
+    // key 排序讓檔案 diff 穩定（游標檔會被人打開來看）。atomic rename：半寫的游標
+    // 會讓下一輪漏資料或重讀全部歷史。
+    const sorted = {
+        files: Object.fromEntries(Object.entries(cur.files).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+        snapshots: cur.snapshots,
+    };
+    writeJsonAtomic(cursorPath(), sorted);
+}
+/**
+ * 讀 append-only JSONL 從 offset 之後的完整行。
+ * 這是整個增量機制的唯一原語（session 檔與 usage_snapshots.jsonl 共用）。
+ * 兩個邊界都在這裡處理，錯了是靜默漏資料 -- 見 test/events.test.ts case 3/4/5。
+ */
+export function tailFile(path, offset = 0) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return { rows: [], offset: null };
+    }
+    if (offset > size)
+        offset = 0; // 檔案被改寫/截斷，整檔重讀，重複交給 view
+    if (offset === size)
+        return { rows: [], offset };
+    let buf;
+    let fd;
+    try {
+        fd = openSync(path, "r");
+        buf = Buffer.allocUnsafe(size - offset);
+        const got = readSync(fd, buf, 0, size - offset, offset);
+        if (got < buf.length)
+            buf = buf.subarray(0, got);
+    }
+    catch {
+        return { rows: [], offset };
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // 關檔失敗不該影響已讀到的資料
+            }
+        }
+    }
+    const nl = buf.lastIndexOf(0x0a);
+    if (nl < 0)
+        return { rows: [], offset }; // 沒有完整行，offset 不前進，下輪再看
+    const consumed = buf.subarray(0, nl + 1);
+    const rows = [];
+    // 換行不可能出現在 UTF-8 多位元組序列中間，所以先整段解碼再切行是安全的。
+    for (const line of consumed.toString("utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const o = JSON.parse(line);
+            if (isObj(o))
+                rows.push(o);
+        }
+        catch {
+            continue; // 壞行跳過，不讓一行毀掉整批
+        }
+    }
+    return { rows, offset: offset + consumed.length };
+}
+/** cursor=null 表示全掃；給物件則只讀各檔新增部分。 */
+function scan(cursor) {
+    const incremental = cursor !== null;
+    const cur = cursor ?? {};
+    const newCursor = {};
+    const rows = [];
+    for (const path of files()) {
+        const start = incremental ? (cur[path] ?? 0) : 0;
+        const { rows: got, offset } = tailFile(path, start);
+        if (offset === null)
+            continue; // 檔案消失，從游標移除
+        newCursor[path] = offset;
+        rows.push(...got);
+    }
+    return { rows, newCursor };
+}
+/** JSONL row 轉 token_events 列，或 null（非推論列）。欄位名即 wire schema 的欄位名。 */
+export function toEvent(o) {
+    const m = isObj(o["message"]) ? o["message"] : {};
+    const u = m["usage"];
+    const mid = m["id"];
+    if (!isObj(u) || typeof mid !== "string" || !mid)
+        return null;
+    const ts = o["timestamp"];
+    if (typeof ts !== "string" || !ts)
+        return null;
+    const model = (nn(m["model"]) ?? null);
+    if (model === "<synthetic>")
+        return null; // Claude Code 內部佔位，非真實推論
+    const cc = isObj(u["cache_creation"]) ? u["cache_creation"] : {};
+    const std = isObj(u["server_tool_use"]) ? u["server_tool_use"] : {};
+    const otd = isObj(u["output_tokens_details"]) ? u["output_tokens_details"] : {};
+    return {
+        message_id: mid,
+        request_id: nn(o["requestId"]),
+        session_id: (o["sessionId"] !== undefined
+            ? nn(o["sessionId"])
+            : nn(o["session_id"])),
+        ts,
+        model,
+        input_tokens: nn(u["input_tokens"]),
+        output_tokens: nn(u["output_tokens"]), // 已含 thinking_tokens
+        thinking_tokens: nn(otd["thinking_tokens"]), // output 子集，不可相加
+        cache_read_tokens: nn(u["cache_read_input_tokens"]),
+        cache_write_5m_tokens: nn(cc["ephemeral_5m_input_tokens"]),
+        cache_write_1h_tokens: nn(cc["ephemeral_1h_input_tokens"]),
+        web_search_requests: nn(std["web_search_requests"]),
+        web_fetch_requests: nn(std["web_fetch_requests"]),
+        service_tier: nn(u["service_tier"]),
+        speed: nn(u["speed"]),
+        effort: nn(o["effort"]),
+        // 這兩欄是 bool(...) 不是 get(...)：缺鍵時是 false，不是 null。
+        // 寫成 null 會讓 BQ 的 NOT COALESCE(is_api_error, FALSE) 行為改變。
+        is_sidechain: Boolean(o["isSidechain"]),
+        is_api_error: Boolean(o["isApiErrorMessage"]),
+        entrypoint: nn(o["entrypoint"]),
+        cc_version: nn(o["version"]),
+        attribution_skill: nn(o["attributionSkill"]),
+        attribution_mcp_server: nn(o["attributionMcpServer"]),
+        attribution_mcp_tool: nn(o["attributionMcpTool"]),
+        project_hash: h16(o["cwd"]), // 不送原始路徑（可能含客戶名）
+        git_branch: nn(o["gitBranch"]),
+    };
+}
+const scopeModelOf = (l) => {
+    const sc = isObj(l["scope"]) ? l["scope"] : {};
+    const md = isObj(sc["model"]) ? sc["model"] : {};
+    return nn(md["display_name"]);
+};
+/**
+ * usage_snapshots.jsonl 一列轉 limit_snapshots 列。欄位名即 wire schema 的欄位名。
+ *
+ * user_id / device_id / ingest_at 由 server 端填。client 不自報身份，那是 device_key
+ * 推導出來的，也是唯一擋得住偽造的方向。
+ *
+ * severity 純量欄位：severity 是 Anthropic 自己的判定（normal|warning|critical），
+ * 門檻未公開，我們不能用 utilization% 自己算，只能照抄。原本這個值只在 limits[]
+ * 陣列裡，BQ 端要 UNNEST 才讀得到，Looker Studio 幾乎等於讀不到。在這裡攤平成純量，
+ * 映射就只有這一份。
+ *
+ * limits[] 照樣整包送，未來 Anthropic 新增 limit kind 時不必改 schema 也不丟資料。
+ * 實測固定 3 筆（session / weekly_all / weekly_scoped），scope 是物件不是純量，
+ * 只有 weekly_scoped 帶 scope.model.display_name。
+ */
+export function toLimitSnapshot(o) {
+    const u = isObj(o["usage"]) ? o["usage"] : {};
+    const fh = isObj(u["five_hour"]) ? u["five_hour"] : {};
+    const sd = isObj(u["seven_day"]) ? u["seven_day"] : {};
+    const rawLimits = Array.isArray(u["limits"]) ? u["limits"] : [];
+    const byKind = new Map();
+    for (const l of rawLimits) {
+        if (isObj(l) && typeof l["kind"] === "string")
+            byKind.set(l["kind"], l);
+    }
+    const sess = byKind.get("session") ?? {};
+    const wall = byKind.get("weekly_all") ?? {};
+    const wsc = byKind.get("weekly_scoped") ?? {};
+    return {
+        // severity / weekly_scoped 純量（攤平自 limits[]）
+        five_hour_severity: nn(sess["severity"]),
+        seven_day_severity: nn(wall["severity"]),
+        // weekly_scoped 是只存在於 limits[] 的第三個指標（per-model 週上限）：
+        // 它不在 usage.five_hour 也不在 usage.seven_day，攤平之前沒有純量路徑讀得到。
+        weekly_scoped_utilization: nn(wsc["percent"]),
+        weekly_scoped_severity: nn(wsc["severity"]),
+        weekly_scoped_model: scopeModelOf(wsc),
+        weekly_scoped_resets_at: nn(wsc["resets_at"]),
+        captured_at: nn(o["collected_at"]),
+        five_hour_utilization: nn(fh["utilization"]),
+        five_hour_resets_at: nn(fh["resets_at"]),
+        seven_day_utilization: nn(sd["utilization"]),
+        seven_day_resets_at: nn(sd["resets_at"]),
+        extra_usage_enabled: nn((isObj(u["extra_usage"]) ? u["extra_usage"] : {})["is_enabled"]),
+        limits: rawLimits.filter(isObj).map((l) => ({
+            kind: nn(l["kind"]),
+            group: nn(l["group"]),
+            percent: nn(l["percent"]),
+            severity: nn(l["severity"]),
+            resets_at: nn(l["resets_at"]),
+            is_active: nn(l["is_active"]),
+            scope_model: scopeModelOf(l),
+            scope_surface: nn((isObj(l["scope"]) ? l["scope"] : {})["surface"]),
+        })),
+        http_status: nn(o["http_status"]),
+        seat_tier: nn(o["tier"]), // keychain rateLimitTier，utilization% 的分母
+        subscription: nn(o["subscription"]),
+        cred_source: nn(o["cred_source"]), // keychain | file
+    };
+}
+/**
+ * usage_snapshots.jsonl 的增量讀取。
+ * 舊版每次 report 重送全部快照（每約 16 分鐘一筆，一年 3 萬筆每 tick 全送）。
+ * 同一個 tailFile 機制解掉。
+ */
+export function snapshotsIncremental(offset = 0) {
+    const { rows, offset: off } = tailFile(snapPath(), offset);
+    return {
+        rows: rows.filter((o) => o["collected_at"]).map(toLimitSnapshot),
+        offset: off === null ? offset : off,
+    };
+}
+// ─────────────────────────── 去重與公開 API ───────────────────────────
+/**
+ * rows 轉 event 列表。dedupe=true 時做 (message_id, request_id) 去重。
+ *
+ * client 端去重只在本批次內有效。同一個複合鍵可能散落在不同批次（實測重複可達
+ * 9 次），跨批次去重是 BQ stg view 的職責。client 端去重是省頻寬的優化，
+ * 不是正確性保證。
+ */
+function dedupeRows(rows, since = null, dedupe = true) {
+    const seen = new Set();
+    const out = [];
+    for (const o of rows) {
+        const e = toEvent(o);
+        if (e === null)
+            continue;
+        if (dedupe) {
+            // 分隔用的空白不會出現在 uuid 型的 id 裡，所以不會有 key 碰撞。
+            const key = `${e.message_id} ${e.request_id ?? ""}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+        }
+        // since 過濾在去重之後：被 since 濾掉的事件仍然佔用了它的去重鍵。
+        // 對調順序會讓「同鍵但較晚的那筆」意外通過，與 Python 版行為不同。
+        if (since && e.ts <= since)
+            continue;
+        out.push(e);
+    }
+    // ISO-8601 字串比較即時間序（同 Python）。JS 的 sort 自 ES2019 起保證穩定。
+    out.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+    return out;
+}
+/** 全掃。給檢視用。dedupe=false 保留原始重複。 */
+export function extract(since = null, dedupe = true) {
+    return dedupeRows(scan(null).rows, since, dedupe);
+}
+/**
+ * 只讀游標之後的新增行。
+ * 呼叫端負責在上傳成功後才 saveCursor()。先存游標再上傳失敗會永久丟掉那批資料
+ * （本機 JSONL 是唯一來源，沒有第二次機會）。
+ */
+export function extractIncremental(cursorFiles) {
+    const cur = cursorFiles ?? loadCursor().files;
+    const { rows, newCursor } = scan(cur);
+    return { events: dedupeRows(rows), newCursor };
+}
+/**
+ * 由 per-event 資料回推 session 摘要，不需要再掃一次檔案。
+ *
+ * session_id 跨 compaction/resume 不穩定（實測兩檔同 started_at、message_count
+ * 1053 vs 1120），session 數會高估。增量模式下 message_count 只是這批的計數，
+ * BQ 的 stg.v_sessions 已改為只取維度、量測全部從 v_token_events 推導。
+ */
+export function sessionsFrom(events) {
+    const agg = new Map();
+    for (const e of events) {
+        const sid = e.session_id;
+        if (!sid)
+            continue;
+        let s = agg.get(sid);
+        if (!s) {
+            s = {
+                session_id: sid,
+                started_at: e.ts,
+                ended_at: e.ts,
+                message_count: 0,
+                models: [],
+                _models: new Set(),
+                project_hash: e.project_hash,
+                git_branch: e.git_branch,
+                cc_version: e.cc_version,
+                entrypoint: e.entrypoint,
+            };
+            agg.set(sid, s);
+        }
+        if (e.ts < s.started_at)
+            s.started_at = e.ts;
+        if (e.ts > s.ended_at)
+            s.ended_at = e.ts;
+        s.message_count += 1;
+        if (e.model)
+            s._models.add(e.model);
+    }
+    return [...agg.values()].map(({ _models, ...s }) => ({ ...s, models: [..._models].sort() }));
+}
+// ─────────────────────────── health 投影 ───────────────────────────
+/**
+ * health.json 的哪些 key 會上報。用白名單而不是整包送：health.json 是 daemon 的
+ * 私有狀態檔，未來加的欄位（例如本機除錯用的路徑）不該自動流到 server 去。
+ * 欄位名與 server 端 client_health 的欄位一對一。
+ */
+export const HEALTH_FIELDS = [
+    "last_tick_at",
+    "ticks",
+    "last_sample_at",
+    "last_sample_status",
+    "last_ok_at",
+    "last_ok_at_backfilled",
+    "consecutive_failures",
+    "first_failure_at",
+    "last_upload_state",
+    "last_error",
+    "unhealthy",
+    "warning",
+];
+/**
+ * ~/.claude-usage/health.json 轉 client_health 列（或 null）。
+ *
+ * 這一條流的存在理由：fact 表上「機器沒開」和「採樣壞了」長得一模一樣，兩者都是
+ * 「沒有新資料」。2026-08-22 那次就是後者 -- token 過期後 daemon 每 5 分鐘照跑、
+ * 照寫 log，17.6 小時一筆快照都沒進來，而使用者完全無感。所以 client 每個 tick 都
+ * 送這個心跳，就算沒有任何新事件也送（見 upload.report）。
+ *
+ * warning 是 client 端已經算好的人話原因（health.healthWarning），不是讓 server
+ * 再推一次。判斷邏輯只該有一份，而它需要本機才有的上下文。
+ */
+export function healthPayload() {
+    const h = readJson(healthPath());
+    if (!isObj(h) || Object.keys(h).length === 0)
+        return null;
+    const out = {};
+    for (const k of HEALTH_FIELDS) {
+        // 值為 null/undefined 的欄位省略（server 端就是 NULL）。
+        // 注意 false 與 0 必須保留 -- unhealthy=false 是有意義的值。
+        if (h[k] !== undefined && h[k] !== null)
+            out[k] = h[k];
+    }
+    return out;
+}

package/dist/health.js

@@ -0,0 +1,95 @@
+/**
+ * daemon 自身的健康狀態（~/.claude-usage/health.json）。
+ *
+ * 這整個檔案是 2026-08-22 那次事故的直接產物：token 過期後 daemon 每 5 分鐘照跑、
+ * 照寫 log，launchd 顯示 runs=556 / last exit code=0（作業系統層面完全健康），
+ * 但 17.6 小時一筆快照都沒進來，而使用者完全無感。
+ *
+ * 教訓寫在這裡免得再犯：**「背景任務已註冊且 exit 0」不能當成「有資料進來」的
+ * 代理指標 —— 必須量測資料本身。**
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { healthPath, snapPath } from "./paths.js";
+import { parseIso, readJson, writeJsonAtomic } from "./util.js";
+/** fetch 的結束碼轉可讀狀態。分開記錄是重點：「token 過期」與「網路壞掉」的處置完全不同。 */
+export const STATUS_BY_CODE = {
+    0: "ok",
+    2: "token_expired",
+    3: "no_token",
+    4: "http_error",
+    5: "network_error",
+};
+/** 連續失敗幾次 / 幾小時沒成功，就算不健康 */
+export const WARN_FAILURES = 3;
+export const WARN_STALE_HOURS = 6;
+/** usage_snapshots.jsonl 的最後一行（本機最新一筆快照） */
+export function lastSnapshot() {
+    const p = snapPath();
+    if (!existsSync(p))
+        return null;
+    let last = null;
+    try {
+        for (const line of readFileSync(p, "utf8").split("\n")) {
+            if (line.trim())
+                last = line;
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!last)
+        return null;
+    try {
+        return JSON.parse(last);
+    }
+    catch {
+        return null;
+    }
+}
+export function loadHealth() {
+    const h = readJson(healthPath()) ?? {};
+    // health.json 是後來才加的。首次執行時若沒有 last_ok_at，從既有快照回填 --
+    // 否則會對一台其實採了 100+ 筆的機器報「從未成功採樣過」，那是會誤導人的訊息。
+    if (h.last_ok_at === undefined) {
+        const snap = lastSnapshot();
+        const t = snap?.["collected_at"];
+        if (typeof t === "string" && t) {
+            h.last_ok_at = t;
+            h.last_ok_at_backfilled = true; // 標明這不是真的成功紀錄
+        }
+    }
+    return h;
+}
+/** Atomic write。health 追蹤本身**絕不可以**弄壞 daemon，所以吞掉所有例外。 */
+export function saveHealth(h) {
+    try {
+        writeJsonAtomic(healthPath(), h);
+    }
+    catch {
+        // 寫不進去也要讓 daemon 跑完這一輪
+    }
+}
+/**
+ * 這台裝置的採樣是不是壞了？回人看得懂的原因，或 null。
+ *
+ * 這個判斷刻意留在 client：它需要本機才有的上下文（連續失敗次數、距上次成功幾
+ * 小時），而同一個判斷只該有一份實作 —— server 收到的 `warning` 就是這裡算好的，
+ * 不會再推一次。
+ */
+export function healthWarning(h) {
+    const cf = h.consecutive_failures ?? 0;
+    if (cf >= WARN_FAILURES) {
+        return `連續 ${cf} 次採樣失敗 (${h.last_sample_status}) 自 ${h.first_failure_at}`;
+    }
+    const ok = parseIso(h.last_ok_at);
+    if (ok) {
+        const hrs = (Date.now() - ok.getTime()) / 3_600_000;
+        if (hrs >= WARN_STALE_HOURS) {
+            return `已 ${hrs.toFixed(1)} 小時沒有成功採樣（最後成功 ${h.last_ok_at}）`;
+        }
+    }
+    else if (h.last_sample_at) {
+        return "從未成功採樣過";
+    }
+    return null;
+}