@dijkspicy/opencode-stats-reporter 0.1.0

package/contrib/opencode-session-reporter/session-usage-reporter.ts

@@ -0,0 +1,610 @@
+/**
+ * session-usage-reporter — opencode 客户端会话 token 用量上报插件
+ *
+ * 行为概要：
+ * - 在会话空闲（bus 事件 `session.idle`，或 `session.status` 且 `status.type === "idle"`）时，
+ *   读取该会话及其全部后代子会话的「已完成」助手消息 token 用量，按会话各自聚合为快照。
+ * - 父会话快照绝不并入子会话用量；每个会话（含子代理会话）都是独立记录。
+ * - token 口径原样分列上报（input / output / reasoning / cache.read / cache.write），
+ *   不在客户端做任何相加或换算（`output` 不含 reasoning，`input` 不含 cache.read）。
+ * - hook 只触发后台采集并入队，绝不等待网络；由后台 flush 统一 POST 到 SESSION_USAGE_ENDPOINT。
+ * - 有界内存队列（默认 500 条快照，溢出丢最旧）+ 指数退避（带抖动）+ AbortSignal.timeout 超时。
+ * - `dispose` 钩子在进程退出时以约 3 秒预算尽力刷新队列，超时即放弃，绝不阻塞退出。
+ * - 载荷不含任何消费者身份字段；身份完全由网关（key-auth 注入 X-Forward-Consumer）决定。
+ *
+ * 修订号（revision）选型：
+ *   直接使用「该会话已完成助手消息条数」。追加式会话中随时间单调递增；重复上报同一数值
+ *   对服务端幂等无害（upsert 按 (consumer, install_id, session_id) + 单调守卫）；若会话
+ *   压缩/删消息导致回退，服务端单调守卫会拒绝旧修订，数据不会倒退。
+ *
+ * 已在 opencode 1.18.33 上核实的 loader 行为（勿破坏）：
+ * - 本文件所有运行时导出必须都是函数，否则 loader 抛 "Plugin export is not a function"。
+ * - loader 会把【每一个】函数导出都当插件工厂调用一次（参数是插件输入
+ *   { client, project, worktree, directory, experimental_workspace, serverUrl, $ }），
+ *   并对返回值做 `V.event?.(...)` / `V.dispose?.()` 访问。
+ *   因此每个纯辅助导出在收到「插件输入形态」的首参时必须返回无害对象 `{}`，
+ *   绝不能抛错、返回 null 或 undefined（否则 `V.event?.` 会读到空值导致崩溃）。
+ *
+ * 安装：复制本文件到 ~/.config/opencode/plugins/（全局）或 <项目>/.opencode/plugins/（项目级）。
+ * 启用：设置环境变量 SESSION_USAGE_ENDPOINT（未设置时插件保持惰性）。
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { randomUUID } from "node:crypto"
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+
+// ---------------------------------------------------------------------------
+// 常量（模块私有：loader 要求所有导出必须是函数，因此常量一律不导出）
+// ---------------------------------------------------------------------------
+
+const SCHEMA_VERSION = 1
+const PLUGIN_VERSION = "0.1.0"
+/** 队列容量：最多积压 500 条会话快照，溢出丢最旧 */
+const QUEUE_CAP = 500
+/** 单次上报请求超时（AbortSignal.timeout） */
+const REQUEST_TIMEOUT_MS = 10_000
+/** 退避基值：第 n 次失败后延迟 ≈ RETRY_BASE_MS * 2^n，封顶 RETRY_MAX_MS，再乘 [0.5, 1.5) 抖动 */
+const RETRY_BASE_MS = 1_000
+const RETRY_MAX_MS = 5 * 60_000
+/** 入队后延迟 flush 的去抖窗口 */
+const FLUSH_DEBOUNCE_MS = 250
+/** dispose 刷新预算 */
+const DISPOSE_BUDGET_MS = 3_000
+/** 子会话递归深度上限（防御环/异常数据） */
+const MAX_SESSION_DEPTH = 32
+
+const INSTALL_ID_STATE_FILE = () => join(homedir(), ".local", "state", "opencode-session-reporter", "install_id")
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+// ---------------------------------------------------------------------------
+// 类型（type-only 导出在运行时会被擦除，不影响 loader 的「导出必须全是函数」校验）
+// ---------------------------------------------------------------------------
+
+export type UsageMessageInfo = {
+  id?: string
+  role?: string
+  modelID?: string
+  providerID?: string
+  mode?: string
+  tokens?: {
+    input?: number
+    output?: number
+    reasoning?: number
+    cache?: { read?: number; write?: number }
+  }
+  time?: { completed?: number | null }
+}
+
+/** `client.session.messages` 返回的条目中与本插件相关的最小形状 */
+export type UsageMessage = { info: UsageMessageInfo }
+
+/** 单个会话的用量快照（同时是上报载荷里 sessions 数组条目的线上格式） */
+export type SessionSnapshot = {
+  session_id: string
+  revision: number
+  model: string | null
+  agent: string | null
+  tokens_input: number
+  tokens_output: number
+  tokens_reasoning: number
+  tokens_cache_read: number
+  tokens_cache_write: number
+  message_count: number
+  session_created_at: number | null
+  last_activity_at: number | null
+}
+
+export type BoundedQueue = {
+  readonly capacity: number
+  readonly size: number
+  readonly dropped: number
+  push: (item: SessionSnapshot) => void
+  drainAll: () => SessionSnapshot[]
+  restore: (items: readonly SessionSnapshot[]) => void
+}
+
+export type ReportPayload = {
+  schema_version: number
+  install_id: string
+  reporter: { client: string; version: string }
+  sessions: SessionSnapshot[]
+}
+
+/** 本插件实际用到的 opencode SDK client 最小形状（便于 mock 测试） */
+export type ReporterClient = {
+  session: {
+    messages: (args: { path: { id: string }; query?: { directory?: string } }) => Promise<{ data?: unknown }>
+    children: (args: { path: { id: string }; query?: { directory?: string } }) => Promise<{ data?: unknown }>
+    get?: (args: { path: { id: string }; query?: { directory?: string } }) => Promise<{ data?: unknown }>
+  }
+}
+
+/** 可注入的定时器（测试用手动调度器替换，避免真实 setTimeout） */
+export type ReporterScheduler = (fn: () => void, delayMs: number) => () => void
+
+export type ReporterCoreOptions = {
+  client: ReporterClient
+  installId: string
+  endpoint?: string
+  directory?: string
+  reporterVersion?: string
+  authToken?: string
+  fetchFn?: typeof fetch
+  queue?: BoundedQueue
+  scheduler?: ReporterScheduler
+  flushDebounceMs?: number
+  requestTimeoutMs?: number
+  log?: (message: string, error?: unknown) => void
+  random?: () => number
+}
+
+export type ReporterCore = {
+  handleEvent: (event?: { type?: unknown; properties?: unknown }) => Promise<void>
+  collectSession: (sessionID: string) => Promise<void>
+  flushOnce: () => Promise<boolean>
+  disposeFlush: (budgetMs?: number) => Promise<void>
+  readonly queue: BoundedQueue
+}
+
+// ---------------------------------------------------------------------------
+// 通用小工具
+// ---------------------------------------------------------------------------
+
+const toCount = (value: unknown): number =>
+  typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0
+
+const joinModel = (providerID?: string, modelID?: string): string | null =>
+  providerID && modelID ? `${providerID}/${modelID}` : null
+
+/**
+ * 判断首参是否是 opencode loader 传入的插件输入。
+ * loader 会对本文件所有函数导出各调用一次 `export(ctxInput, options)`。
+ */
+const isPluginInput = (value: unknown): boolean => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false
+  return (
+    "client" in value &&
+    ("project" in value || "worktree" in value || "experimental_workspace" in value || "serverUrl" in value)
+  )
+}
+
+/**
+ * 包装纯辅助导出：被 loader 误当插件工厂调用时返回 `{}`（安全、可被 `V.event?.` 访问），
+ * 正常按签名调用时行为与原函数完全一致。
+ */
+const pluginSafe = <A extends unknown[], R>(fn: (...args: A) => R): ((...args: A) => R) => {
+  return (...args: A): R => {
+    if (isPluginInput(args[0])) return {} as R
+    return fn(...args)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 纯函数：聚合 / 合并 / 载荷 / 队列 / 退避
+// ---------------------------------------------------------------------------
+
+const aggregateSessionImpl = (sessionID: string, messages: readonly UsageMessage[]): SessionSnapshot | null => {
+  let input = 0
+  let output = 0
+  let reasoning = 0
+  let cacheRead = 0
+  let cacheWrite = 0
+  let count = 0
+  let lastActivity: number | null = null
+  let model: string | null = null
+  let agent: string | null = null
+
+  for (const message of messages ?? []) {
+    const info = message?.info
+    if (!info || info.role !== "assistant") continue
+    const completed = info.time?.completed
+    // 只统计已完成（time.completed 已设置）的助手消息，天然去重、不双计
+    if (typeof completed !== "number" || !Number.isFinite(completed)) continue
+    count += 1
+    input += toCount(info.tokens?.input)
+    output += toCount(info.tokens?.output)
+    reasoning += toCount(info.tokens?.reasoning)
+    cacheRead += toCount(info.tokens?.cache?.read)
+    cacheWrite += toCount(info.tokens?.cache?.write)
+    if (lastActivity === null || completed > lastActivity) lastActivity = completed
+    const messageModel = joinModel(info.providerID, info.modelID)
+    if (messageModel) {
+      // 取最后一条已完成助手消息的模型 / agent 作为会话级归属
+      model = messageModel
+      agent = typeof info.mode === "string" ? info.mode : null
+    }
+  }
+
+  if (count === 0) return null
+
+  return {
+    session_id: sessionID,
+    revision: count, // 修订号 = 已完成助手消息数（见文件头说明）
+    model,
+    agent,
+    tokens_input: input,
+    tokens_output: output,
+    tokens_reasoning: reasoning,
+    tokens_cache_read: cacheRead,
+    tokens_cache_write: cacheWrite,
+    message_count: count,
+    session_created_at: null, // 由采集层补充
+    last_activity_at: lastActivity,
+  }
+}
+
+/** 合并同一会话的多个快照：保留修订号最高者；同修订取 last_activity 更新（或后到）者 */
+const mergeSnapshotsImpl = (snapshots: readonly SessionSnapshot[]): SessionSnapshot[] => {
+  const byID = new Map<string, SessionSnapshot>()
+  for (const snapshot of snapshots ?? []) {
+    if (!snapshot || typeof snapshot.session_id !== "string" || !snapshot.session_id) continue
+    const existing = byID.get(snapshot.session_id)
+    if (!existing || snapshot.revision > existing.revision) {
+      byID.set(snapshot.session_id, snapshot)
+      continue
+    }
+    if (snapshot.revision === existing.revision) {
+      const existingAt = existing.last_activity_at ?? 0
+      const incomingAt = snapshot.last_activity_at ?? 0
+      if (incomingAt >= existingAt) byID.set(snapshot.session_id, snapshot)
+    }
+  }
+  return [...byID.values()]
+}
+
+/** 组装上报载荷。绝不包含消费者身份字段 —— 身份由网关注入。 */
+const buildPayloadImpl = (
+  installId: string,
+  reporterVersion: string,
+  snapshots: readonly SessionSnapshot[],
+): ReportPayload => ({
+  schema_version: SCHEMA_VERSION,
+  install_id: installId,
+  reporter: { client: "opencode", version: reporterVersion },
+  sessions: mergeSnapshotsImpl(snapshots),
+})
+
+/** 有界队列：溢出丢最旧；失败批次按原顺序放回队首 */
+const createQueueImpl = (cap: number = QUEUE_CAP): BoundedQueue => {
+  const capacity = typeof cap === "number" && Number.isFinite(cap) && cap >= 1 ? Math.floor(cap) : 1
+  let items: SessionSnapshot[] = []
+  let dropped = 0
+  return {
+    capacity,
+    get size() {
+      return items.length
+    },
+    get dropped() {
+      return dropped
+    },
+    push(item) {
+      if (!item) return
+      if (items.length >= capacity) {
+        items.shift()
+        dropped += 1
+      }
+      items.push(item)
+    },
+    drainAll() {
+      const drained = items
+      items = []
+      return drained
+    },
+    restore(incoming) {
+      const valid = (incoming ?? []).filter((item) => !!item)
+      items = [...valid, ...items]
+      // 极端情况下放回后超容量：保最旧（先产生的数据），裁掉最新
+      if (items.length > capacity) {
+        dropped += items.length - capacity
+        items = items.slice(0, capacity)
+      }
+    },
+  }
+}
+
+/** 指数退避 + 抖动：delay = min(RETRY_MAX_MS, BASE * 2^attempt) * [0.5, 1.5)，结果封顶 RETRY_MAX_MS */
+const computeBackoffMsImpl = (attempt: number, random01: number = Math.random()): number => {
+  const safeAttempt =
+    typeof attempt === "number" && Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0
+  const exponential = Math.min(RETRY_MAX_MS, RETRY_BASE_MS * 2 ** safeAttempt)
+  const safeRandom =
+    typeof random01 === "number" && Number.isFinite(random01) ? Math.min(1, Math.max(0, random01)) : 0.5
+  const jittered = Math.round(exponential * (0.5 + safeRandom))
+  return Math.min(RETRY_MAX_MS, Math.max(0, jittered))
+}
+
+// ---------------------------------------------------------------------------
+// install_id：本地稳定 UUID（生成一次，持久化到用户状态目录）
+// ---------------------------------------------------------------------------
+
+const loadOrCreateInstallIdImpl = async (
+  options: { stateFile?: string; randomUUIDFn?: () => string } = {},
+): Promise<string> => {
+  const stateFile = options.stateFile ?? INSTALL_ID_STATE_FILE()
+  try {
+    const existing = (await readFile(stateFile, "utf8")).trim()
+    if (UUID_PATTERN.test(existing)) return existing
+  } catch {
+    // 首次运行或不可读：走生成流程
+  }
+  const id = options.randomUUIDFn ? options.randomUUIDFn() : randomUUID()
+  try {
+    await mkdir(dirname(stateFile), { recursive: true })
+    await writeFile(stateFile, `${id}\n`, "utf8")
+  } catch {
+    // 只读文件系统等场景：退化为本次进程内的临时 id
+  }
+  return id
+}
+
+// ---------------------------------------------------------------------------
+// 核心：采集 + 非阻塞队列 + 退避重试 + dispose 限时刷新
+// ---------------------------------------------------------------------------
+
+const defaultScheduler: ReporterScheduler = (fn, delayMs) => {
+  const timer = setTimeout(fn, Math.max(0, delayMs))
+  const unref = (timer as unknown as { unref?: () => void }).unref
+  if (typeof unref === "function") unref.call(timer) // 定时器不阻止进程退出
+  return () => clearTimeout(timer)
+}
+
+const createReporterCoreImpl = (options: ReporterCoreOptions): ReporterCore => {
+  const queue = options.queue ?? createQueueImpl(QUEUE_CAP)
+  const fetchFn = options.fetchFn ?? fetch
+  const endpoint = typeof options.endpoint === "string" && options.endpoint.trim() ? options.endpoint.trim() : undefined
+  const reporterVersion = options.reporterVersion ?? PLUGIN_VERSION
+  const requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS
+  const flushDebounceMs = options.flushDebounceMs ?? FLUSH_DEBOUNCE_MS
+  const scheduler = options.scheduler ?? defaultScheduler
+  const random = options.random ?? Math.random
+  const log = options.log ?? (() => {})
+
+  let flushCancel: (() => void) | null = null
+  let retryCancel: (() => void) | null = null
+  let retryAttempt = 0
+  const inFlight = new Set<string>()
+
+  const send = async (snapshots: readonly SessionSnapshot[], timeoutMs: number): Promise<void> => {
+    if (!endpoint) return
+    const payload = buildPayloadImpl(options.installId, reporterVersion, snapshots)
+    const abortTimeout = (AbortSignal as unknown as { timeout?: (ms: number) => AbortSignal } | undefined)?.timeout
+    const signal = typeof abortTimeout === "function" ? abortTimeout(Math.max(1, timeoutMs)) : undefined
+    const headers: Record<string, string> = { "content-type": "application/json" }
+    // 载荷不含身份；上报请求需带网关 Key，由 APIG key-auth 校验后注入消费者身份。
+    if (options.authToken) headers["authorization"] = `Bearer ${options.authToken}`
+    const response = await fetchFn(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      signal,
+    })
+    if (!response.ok) throw new Error(`session-usage endpoint responded ${response.status}`)
+  }
+
+  /** 发送当前全部积压；失败则原样放回队首并调度退避重试。返回是否成功（或无事可做）。 */
+  const flushOnce = async (): Promise<boolean> => {
+    if (!endpoint) return true
+    const batch = queue.drainAll()
+    if (batch.length === 0) return true
+    try {
+      await send(batch, requestTimeoutMs)
+      retryAttempt = 0
+      return true
+    } catch (error) {
+      queue.restore(batch)
+      retryAttempt += 1
+      // 第 1 次失败 → 基础 1s，此后指数翻倍（2s、4s…），封顶 5 分钟，均带抖动
+      const delay = computeBackoffMsImpl(Math.max(0, retryAttempt - 1), random())
+      log(`session-usage: 上报失败，${delay}ms 后重试（队列积压 ${queue.size}）`, error)
+      if (!retryCancel) {
+        retryCancel = scheduler(() => {
+          retryCancel = null
+          void flushOnce()
+        }, delay)
+      }
+      return false
+    }
+  }
+
+  const scheduleFlush = (): void => {
+    if (flushCancel || queue.size === 0) return
+    flushCancel = scheduler(() => {
+      flushCancel = null
+      void flushOnce()
+    }, flushDebounceMs)
+  }
+
+  const query = (): { directory: string } | undefined =>
+    options.directory ? { directory: options.directory } : undefined
+
+  const readMessages = async (sessionID: string): Promise<UsageMessage[]> => {
+    const response = await options.client.session.messages({ path: { id: sessionID }, query: query() })
+    const data = (response as { data?: unknown } | undefined)?.data
+    return Array.isArray(data) ? (data as UsageMessage[]) : []
+  }
+
+  const readChildIDs = async (sessionID: string): Promise<string[]> => {
+    const response = await options.client.session.children({ path: { id: sessionID }, query: query() })
+    const data = (response as { data?: unknown } | undefined)?.data
+    if (!Array.isArray(data)) return []
+    const ids: string[] = []
+    for (const entry of data) {
+      const id = typeof entry === "string" ? entry : (entry as { id?: unknown } | null)?.id
+      if (typeof id === "string" && id) ids.push(id)
+    }
+    return ids
+  }
+
+  const readSessionCreatedAt = async (sessionID: string): Promise<number | null> => {
+    try {
+      const getSession = options.client.session.get
+      if (typeof getSession !== "function") return null
+      const response = await getSession.call(options.client.session, { path: { id: sessionID }, query: query() })
+      const created = (response as { data?: { time?: { created?: unknown } } | undefined } | undefined)?.data?.time
+        ?.created
+      return typeof created === "number" ? created : null
+    } catch {
+      return null
+    }
+  }
+
+  /** 递归聚合会话及其后代；每个会话独立成快照，父快照不含子用量 */
+  const collectRecursive = async (
+    sessionID: string,
+    out: SessionSnapshot[],
+    visited: Set<string>,
+    depth: number,
+  ): Promise<void> => {
+    if (!sessionID || visited.has(sessionID) || depth > MAX_SESSION_DEPTH || visited.size >= QUEUE_CAP) return
+    visited.add(sessionID)
+    const snapshot = aggregateSessionImpl(sessionID, await readMessages(sessionID))
+    if (snapshot) {
+      snapshot.session_created_at = await readSessionCreatedAt(sessionID)
+      out.push(snapshot)
+    }
+    for (const childID of await readChildIDs(sessionID)) {
+      await collectRecursive(childID, out, visited, depth + 1)
+    }
+  }
+
+  const collectSession = async (sessionID: string): Promise<void> => {
+    if (typeof sessionID !== "string" || !sessionID) return
+    if (inFlight.has(sessionID)) return // 同一会话采集中：跳过，下次空闲信号再采
+    inFlight.add(sessionID)
+    try {
+      const out: SessionSnapshot[] = []
+      await collectRecursive(sessionID, out, new Set(), 0)
+      for (const snapshot of out) queue.push(snapshot)
+      if (out.length > 0) scheduleFlush()
+    } catch (error) {
+      log(`session-usage: 采集会话 ${sessionID} 用量失败`, error)
+    } finally {
+      inFlight.delete(sessionID)
+    }
+  }
+
+  /** 统一处理两种空闲信号；绝不抛出 */
+  const handleEvent = async (event?: { type?: unknown; properties?: unknown }): Promise<void> => {
+    try {
+      const type = event?.type
+      const properties = (event?.properties ?? {}) as { sessionID?: unknown; status?: { type?: unknown } }
+      let sessionID: unknown
+      if (type === "session.idle") {
+        sessionID = properties.sessionID
+      } else if (type === "session.status" && properties.status?.type === "idle") {
+        sessionID = properties.sessionID
+      }
+      if (typeof sessionID === "string" && sessionID) await collectSession(sessionID)
+    } catch (error) {
+      log("session-usage: 处理事件失败", error)
+    }
+  }
+
+  /** dispose：限时预算内尽力清空队列；失败立即止损，绝不阻塞退出 */
+  const disposeFlush = async (budgetMs: number = DISPOSE_BUDGET_MS): Promise<void> => {
+    try {
+      flushCancel?.()
+      flushCancel = null
+      retryCancel?.()
+      retryCancel = null
+      if (!endpoint) return
+      const deadline = Date.now() + Math.max(0, budgetMs)
+      while (queue.size > 0) {
+        const remaining = deadline - Date.now()
+        if (remaining <= 0) break
+        const batch = queue.drainAll()
+        if (batch.length === 0) break
+        try {
+          await send(batch, Math.min(requestTimeoutMs, remaining))
+          retryAttempt = 0
+        } catch (error) {
+          queue.restore(batch)
+          log("session-usage: 退出前上报失败，放弃剩余队列", error)
+          break
+        }
+      }
+    } catch (error) {
+      log("session-usage: dispose 刷新失败", error)
+    }
+  }
+
+  return { handleEvent, collectSession, flushOnce, disposeFlush, queue }
+}
+
+// ---------------------------------------------------------------------------
+// 导出：全部是函数（loader 硬约束），纯辅助导出带插件工厂防御
+// ---------------------------------------------------------------------------
+
+export const aggregateSession = pluginSafe(aggregateSessionImpl)
+export const mergeSnapshots = pluginSafe(mergeSnapshotsImpl)
+export const buildPayload = pluginSafe(buildPayloadImpl)
+export const createQueue = pluginSafe(createQueueImpl)
+export const computeBackoffMs = pluginSafe(computeBackoffMsImpl)
+export const loadOrCreateInstallId = pluginSafe(loadOrCreateInstallIdImpl)
+export const createReporterCore = pluginSafe(createReporterCoreImpl)
+
+/**
+ * 插件入口。
+ * 未设置 SESSION_USAGE_ENDPOINT 时返回空 hooks，完全不影响会话。
+ */
+export const SessionUsageReporter: Plugin = async (ctx) => {
+  try {
+    const endpoint = (process.env.SESSION_USAGE_ENDPOINT ?? "").trim() || undefined
+    if (!endpoint) return {}
+
+    const log = (message: string, error?: unknown): void => {
+      try {
+        const detail = error instanceof Error ? `${error.name}: ${error.message}` : error === undefined ? "" : String(error)
+        const client = ctx.client as { app?: { log?: (args: unknown) => unknown } }
+        const result = client.app?.log?.({
+          body: {
+            level: detail ? "error" : "info",
+            service: "session-usage-reporter",
+            message: detail ? `${message}: ${detail}` : message,
+          },
+        })
+        const promise = result as Promise<void> | undefined
+        if (promise && typeof promise.catch === "function") promise.catch(() => {})
+      } catch {
+        // 日志失败绝不影响会话
+      }
+    }
+
+    const installId = await loadOrCreateInstallIdImpl()
+    const core = createReporterCoreImpl({
+      client: ctx.client as unknown as ReporterClient,
+      directory: ctx.directory,
+      endpoint,
+      installId,
+      // 上报请求的网关 Key（APIG key-auth 后注入 X-Forward-Consumer）；未配置则不带鉴权头
+      authToken: (process.env.SESSION_USAGE_API_KEY ?? "").trim() || undefined,
+      log,
+    })
+
+    return {
+      event: async (input: { event?: { type?: unknown; properties?: unknown } }) => {
+        try {
+          // 只触发后台采集，不 await：hook 内禁止等待网络，hooks 串行等待不能被拖慢
+          core.handleEvent(input?.event).catch(() => {})
+        } catch (error) {
+          log("session-usage: hook 执行异常（已忽略）", error)
+        }
+      },
+      dispose: async () => {
+        await core.disposeFlush()
+      },
+    }
+  } catch (error) {
+    try {
+      console.error("[session-usage-reporter] 初始化失败，插件已禁用:", error)
+    } catch {
+      // 连 console 都失败时保持静默
+    }
+    return {}
+  }
+}
+
+export default SessionUsageReporter

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@dijkspicy/opencode-stats-reporter",
+  "version": "0.1.0",
+  "description": "本地一体化 MaaS 用量看板：托管静态面板、反代用量接口、本地存储会话用量",
+  "type": "module",
+  "main": "./contrib/opencode-session-reporter/plugin-server.ts",
+  "exports": {
+    ".": "./contrib/opencode-session-reporter/plugin-server.ts",
+    "./server": "./contrib/opencode-session-reporter/plugin-server.ts",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "opencode-stats-reporter": "bin/opencode-stats-reporter.js"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "panel",
+    "contrib/opencode-session-reporter",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "Apache-2.0"
+}

package/panel/config.example.js

@@ -0,0 +1,35 @@
+/**
+ * BlueRegion Usage 面板配置模板（示例）
+ * ===============================================================
+ * 使用方法：复制本文件为 config.js，按需修改下方配置项。
+ * !! 注意：config.js 会包含你的 API Key，请勿提交 git / 请勿截图分享 !!
+ * 优先级：浏览器 localStorage 中保存的配置 > config.js。
+ */
+
+window.APP_CONFIG = {
+  // 网关地址（必填）：BlueRegion API 网关基础地址，必须是合法 http(s) URL
+  // 示例：'https://gateway.example.com'；本地联调可用 'http://localhost:8765'
+  gatewayBaseUrl: 'http://localhost:8765',
+
+  // API Key（必填）：网关签发的个人 Key，请求时以 Bearer 方式携带
+  apiKey: 'api-key-xxxxxxxx',
+
+  // 趋势图天数（1-15，默认 14）：仅"今日"周期下，趋势图回看的天数
+  trendDays: 14,
+
+  // 主题：auto（跟随系统）| light（浅色）| dark（深色），默认 auto
+  theme: 'auto',
+
+  // 大数字缩写风格：wan（万 / 亿，默认）| intl（K / M / B）
+  numberStyle: 'wan',
+
+  // 每日 Credit 限额（可选）：今日用量超出该值，Credit 卡红字提示「已超出」。
+  // 留空（null）表示不限；可在网页首次登录或「配置限额」中填写，例如 100。
+  dailyCreditLimit: null,
+
+  // 每周 Credit 限额（可选）：本周用量对应额度。
+  weeklyCreditLimit: null,
+
+  // 每月 Credit 限额（可选）：本月用量对应额度，同时用于「本月进度条」的月均 pacing，例如 3000。
+  monthlyCreditLimit: null
+};