@dijkspicy/opencode-stats-reporter 0.1.0

package/panel/js/sessions.js

@@ -0,0 +1,412 @@
+/**
+ * 会话视图：客户端上报的会话级 token 用量
+ * 数据源：/v1/sessions*（客户端上报，可能延迟/遗漏，非网关权威数据）
+ * token 口径（已实测验证）：输入总量 = 输入 + 缓存读 + 缓存写；输出总量 = 输出 + 推理（推理单列，不并入输出）
+ * 结构：来源声明 → 用量对账（网关权威总量 − 会话上报合计 = 未归属用量）→ 会话列表（窗口/模型/代理筛选 + 游标分页）→ 会话详情
+ * 由 app.js 初始化：BRU.sessions.init({ getCfg, getPeriod, getModelCatalog, onUnauthorized })，并经 BRU.sessions.load() 触发拉取
+ */
+(function () {
+  'use strict';
+
+  var F = window.BRU.format;
+  var API = window.BRU.api;
+
+  var PAGE_SIZE = 50;
+  var UNAUTH_MSG = 'API Key 无效或已过期，请重新输入';
+
+  var deps = null;
+  var el = {};
+
+  var st = {
+    seq: 0,               // 请求代次：响应到达时核对，过期响应（切窗/切筛选后）直接丢弃
+    period: 'today',
+    rows: [],             // 已加载会话（分页累积）
+    nextCursor: null,     // 下一页游标（null = 没有更多）
+    filters: { model: '', agent: '' },
+    modelSet: {},         // 模型筛选项（模型目录 + 已见会话模型）
+    agentSet: {},         // 代理筛选项（已见会话代理）
+    selectedId: null      // 当前打开详情的会话 ID
+  };
+
+  // ---------- DOM 工具 ----------
+  function $(id) { return document.getElementById(id); }
+  function show(e) { e.classList.remove('hidden'); }
+  function hide(e) { e.classList.add('hidden'); }
+
+  function td(text, cls, title) {
+    var c = document.createElement('td');
+    c.textContent = text;
+    if (cls) c.className = cls;
+    if (title) c.title = title;
+    return c;
+  }
+
+  /** 卡片状态层：与 app.js 的 setCardState 同构（loading/empty/error/ready），空态文案按会话语境定制 */
+  function setCardState(cardEl, name, msg, retryFn, emptyText) {
+    var layer = cardEl.querySelector('.card-state');
+    if (!layer) return;
+    layer.className = 'card-state state-' + name;
+    if (name === 'ready') { layer.innerHTML = ''; hide(layer); return; }
+    show(layer);
+    if (name === 'loading') {
+      layer.innerHTML = '<div class="skeleton"></div><div class="skeleton sk-60"></div><div class="skeleton sk-40"></div>';
+    } else if (name === 'empty') {
+      layer.innerHTML = '<div class="state-text">' + (emptyText || '该窗口暂无会话上报') + '</div>';
+    } else if (name === 'error') {
+      layer.innerHTML = '';
+      var div = document.createElement('div');
+      div.className = 'state-text state-error-text';
+      div.textContent = msg || '加载失败';
+      var btn = document.createElement('button');
+      btn.className = 'btn btn-sm';
+      btn.textContent = '重试';
+      btn.addEventListener('click', retryFn || load);
+      layer.appendChild(div);
+      layer.appendChild(btn);
+    }
+  }
+
+  // ---------- token 口径 ----------
+  /** 输入总量 = 输入 + 缓存读 + 缓存写（面板侧派生，与服务端 tokens_input_total 同口径） */
+  function inputTotal(r) {
+    return (r.tokens_input || 0) + (r.tokens_cache_read || 0) + (r.tokens_cache_write || 0);
+  }
+  /** 输出总量 = 输出 + 推理（推理单独列示，不并入输出） */
+  function outputTotal(r) {
+    return (r.tokens_output || 0) + (r.tokens_reasoning || 0);
+  }
+
+  // ---------- 加载编排 ----------
+  /** 整页加载：列表重置到第一页 + 对账聚合；seq 保证切窗/切筛选后的旧响应不回写 */
+  function load() {
+    var cfg = deps && deps.getCfg();
+    if (!cfg) return Promise.resolve();
+    var seq = ++st.seq;
+    st.period = deps.getPeriod();
+    setCardState(el.coverageCard, 'loading');
+    setCardState(el.listCard, 'loading');
+    st.rows = [];
+    st.nextCursor = null;
+    el.tbody.innerHTML = '';
+    el.count.textContent = '';
+    hide(el.btnMore);
+    closeDetail();
+    var w = st.period;
+    return Promise.all([
+      fetchPage(cfg, w, null, true, seq),
+      fetchCoverage(cfg, w, seq)
+    ]);
+  }
+
+  /** 拉取一页会话：isReset=true 首页（覆盖），false 追加（加载更多）；失败走卡片错误层 + 重试 */
+  function fetchPage(cfg, window_, cursor, isReset, seq) {
+    var params = { window: window_, limit: PAGE_SIZE };
+    if (st.filters.model) params.model = st.filters.model;
+    if (st.filters.agent) params.agent = st.filters.agent;
+    if (cursor) params.cursor = cursor;
+    return API.sessions(cfg, params).then(function (res) {
+      if (seq !== st.seq) return;
+      var rows = (res && res.data) || [];
+      st.rows = isReset ? rows : st.rows.concat(rows);
+      st.nextCursor = (res && res.next_cursor) || null;
+      absorbOptions(rows);
+      renderRows();
+      el.count.textContent = '已加载 ' + st.rows.length + ' 个会话' + (st.nextCursor ? '（还有更多）' : '');
+      if (st.nextCursor) show(el.btnMore); else hide(el.btnMore);
+      if (isReset && !rows.length) {
+        setCardState(el.listCard, 'empty', null, null,
+          (st.filters.model || st.filters.agent) ? '当前筛选条件下暂无会话上报' : null);
+      } else {
+        setCardState(el.listCard, 'ready');
+      }
+      updateStamp(res && res.as_of);
+    }, function (err) {
+      if (seq !== st.seq) return;
+      if (err && err.code === 'unauthorized') { deps.onUnauthorized(UNAUTH_MSG); return; }
+      setCardState(el.listCard, 'error', (err && err.message) || '加载失败', function () {
+        fetchPage(deps.getCfg(), deps.getPeriod(), cursor, isReset, st.seq);
+      });
+    });
+  }
+
+  /** 对账聚合：网关权威总量（/v1/usage/summary）− 会话上报合计（Σ /v1/sessions/summary）= 未归属用量 */
+  function fetchCoverage(cfg, window_, seq) {
+    function settle(p) {
+      return p.then(function (v) { return v; }, function (e) { return { __error: e }; });
+    }
+    return Promise.all([
+      settle(API.summary(cfg, window_)),
+      settle(API.sessionsSummary(cfg, { window: window_, group_by: 'model' }))
+    ]).then(function (rs) {
+      if (seq !== st.seq) return;
+      var gwErr = rs[0].__error, sesErr = rs[1].__error;
+      if ((gwErr && gwErr.code === 'unauthorized') || (sesErr && sesErr.code === 'unauthorized')) {
+        deps.onUnauthorized(UNAUTH_MSG);
+        return;
+      }
+      if (gwErr && sesErr) {
+        setCardState(el.coverageCard, 'error', (gwErr.message || sesErr.message) || '加载失败', function () {
+          fetchCoverage(deps.getCfg(), deps.getPeriod(), st.seq);
+        });
+        return;
+      }
+      var gw = gwErr ? null : ((rs[0].data.req_tokens || 0) + (rs[0].data.rsp_tokens || 0));
+      var ses = 0, cnt = 0;
+      if (!sesErr) {
+        (rs[1].data || []).forEach(function (row) {
+          ses += inputTotal(row) + outputTotal(row);
+          cnt += (row.sessions || 0);
+        });
+      }
+      renderCoverage(gw, ses, cnt, gwErr, sesErr);
+      setCardState(el.coverageCard, 'ready');
+    });
+  }
+
+  // ---------- 对账卡片 ----------
+  function renderCoverage(gw, ses, cnt, gwErr, sesErr) {
+    var cfg = deps.getCfg() || {};
+    function set(node, v, tip) {
+      node.textContent = v === null ? '--' : F.abbrev(v, cfg.numberStyle);
+      node.title = v === null ? '' : tip;
+    }
+    set(el.covGateway, gw,
+      gw === null ? '' : '网关权威口径：/v1/usage/summary 的 req_tokens + rsp_tokens = ' + F.fullNumber(gw));
+    set(el.covReported, sesErr ? null : ses,
+      '会话上报合计：Σ /v1/sessions/summary 各组（输入总量 + 输出总量）= ' + F.fullNumber(ses) +
+      (cnt ? '，共 ' + cnt + ' 个会话' : ''));
+    var diff = (gw === null || sesErr) ? null : (gw - ses);
+    set(el.covDiff, diff,
+      diff === null ? '' : '网关权威总量 − 会话上报合计 = ' + F.fullNumber(diff));
+    el.covRate.textContent = (gw === null || sesErr || gw <= 0) ? '--' : F.hitRate(ses / gw);
+    el.covRate.title = (gw === null || sesErr || gw <= 0) ? '' : '会话上报合计 ÷ 网关权威总量';
+
+    var note = '未归属用量可能来自：标题生成、会话压缩、重试与其他客户端';
+    if (diff !== null && diff < 0) note += '；会话上报合计高于网关总量，可能为口径差异或重复上报';
+    if (gwErr) note = '网关总量获取失败；' + note;
+    if (sesErr) note = '会话汇总获取失败；' + note;
+    if (!sesErr && ses === 0) note = '当前窗口暂无会话上报；' + note;
+    el.covNote.textContent = note;
+  }
+
+  // ---------- 会话列表 ----------
+  function renderRows() {
+    var tbody = el.tbody;
+    tbody.innerHTML = '';
+    st.rows.forEach(function (r) { tbody.appendChild(sessionRow(r)); });
+  }
+
+  function sessionRow(r) {
+    var tr = document.createElement('tr');
+    // 会话 ID：等宽截断展示，完整值放 title，点击查看详情
+    var sidTd = document.createElement('td');
+    var sidBtn = document.createElement('button');
+    sidBtn.type = 'button';
+    sidBtn.className = 'sess-id-btn mono';
+    sidBtn.textContent = r.session_id || '--';
+    sidBtn.title = (r.session_id || '') + '\n点击查看详情';
+    sidBtn.addEventListener('click', function () { openDetail(r.session_id); });
+    sidTd.appendChild(sidBtn);
+    tr.appendChild(sidTd);
+
+    tr.appendChild(td(r.model || '--'));
+    tr.appendChild(td(r.agent || '--'));
+    tr.appendChild(td(F.fullNumber(inputTotal(r)), 'num', '输入总量 = 输入 + 缓存读 + 缓存写'));
+    tr.appendChild(td(F.fullNumber(outputTotal(r)), 'num', '输出总量 = 输出 + 推理'));
+    tr.appendChild(td(F.fullNumber(r.tokens_reasoning), 'num'));
+    tr.appendChild(td(F.fullNumber(r.tokens_cache_read), 'num'));
+    tr.appendChild(td(F.fullNumber(r.tokens_cache_write), 'num'));
+    tr.appendChild(td(F.fullNumber(r.message_count), 'num'));
+    tr.appendChild(td(F.dateTime(r.last_activity_at)));
+    return tr;
+  }
+
+  /** 头部“更新于”时间戳：跟随当前视图数据（as_of 为 ISO 字符串，解析失败回退当前时间） */
+  function updateStamp(asOf) {
+    var target = $('last-updated');
+    if (!target) return;
+    var t = asOf ? Date.parse(asOf) : NaN;
+    if (!isFinite(t)) t = Date.now();
+    target.textContent = '更新于 ' + F.timeOfDay(Math.floor(t / 1000));
+  }
+
+  // ---------- 筛选项 ----------
+  /** 收集筛选项：模型 = 模型目录 ∪ 已见会话；代理 = 已见会话；仅在出现新值时重建下拉 */
+  function absorbOptions(rows) {
+    var modelNew = false, agentNew = false;
+    rows.forEach(function (r) {
+      if (r.model && !st.modelSet[r.model]) { st.modelSet[r.model] = true; modelNew = true; }
+      if (r.agent && !st.agentSet[r.agent]) { st.agentSet[r.agent] = true; agentNew = true; }
+    });
+    (deps.getModelCatalog() || []).forEach(function (m) {
+      if (m && m.id && !st.modelSet[m.id]) { st.modelSet[m.id] = true; modelNew = true; }
+    });
+    if (modelNew) rebuildSelect(el.filterModel, st.modelSet, '全部模型');
+    if (agentNew) rebuildSelect(el.filterAgent, st.agentSet, '全部代理');
+  }
+
+  function rebuildSelect(sel, set, allLabel) {
+    var cur = sel.value;
+    sel.innerHTML = '';
+    var all = document.createElement('option');
+    all.value = '';
+    all.textContent = allLabel;
+    sel.appendChild(all);
+    Object.keys(set).sort().forEach(function (k) {
+      var o = document.createElement('option');
+      o.value = k;
+      o.textContent = k;
+      sel.appendChild(o);
+    });
+    sel.value = set[cur] ? cur : '';  // 保留当前选择
+  }
+
+  // ---------- 会话详情 ----------
+  function openDetail(id) {
+    if (!id) return;
+    var cfg = deps.getCfg();
+    if (!cfg) return;
+    st.selectedId = id;
+    el.detailId.textContent = id;
+    el.detailBody.innerHTML = '';
+    show(el.detailCard);
+    setCardState(el.detailCard, 'loading');
+    if (el.detailCard.scrollIntoView) {
+      try { el.detailCard.scrollIntoView({ behavior: 'smooth', block: 'start' }); }
+      catch (e) { el.detailCard.scrollIntoView(); }
+    }
+    API.sessionDetail(cfg, id).then(function (res) {
+      if (st.selectedId !== id) return;
+      renderDetail((res && res.data) || {});
+      setCardState(el.detailCard, 'ready');
+    }, function (err) {
+      if (st.selectedId !== id) return;
+      if (err && err.code === 'unauthorized') { deps.onUnauthorized(UNAUTH_MSG); return; }
+      var msg = (err && err.status === 404)
+        ? '会话不存在或不在当前消费者名下'
+        : ((err && err.message) || '加载失败');
+      setCardState(el.detailCard, 'error', msg, function () { openDetail(id); });
+    });
+  }
+
+  function closeDetail() {
+    st.selectedId = null;
+    el.detailBody.innerHTML = '';
+    hide(el.detailCard);
+  }
+
+  function renderDetail(d) {
+    el.detailId.textContent = d.session_id || '--';
+    var body = el.detailBody;
+    body.innerHTML = '';
+
+    body.appendChild(group('Token 明细', [
+      item('输入', F.fullNumber(d.tokens_input)),
+      item('缓存读', F.fullNumber(d.tokens_cache_read)),
+      item('缓存写', F.fullNumber(d.tokens_cache_write)),
+      item('输入总量（派生）', F.fullNumber(inputTotal(d)), false, '输入总量 = 输入 + 缓存读 + 缓存写'),
+      item('输出', F.fullNumber(d.tokens_output)),
+      item('推理', F.fullNumber(d.tokens_reasoning)),
+      item('输出总量（派生）', F.fullNumber(outputTotal(d)), false, '输出总量 = 输出 + 推理'),
+      item('消息数', F.fullNumber(d.message_count))
+    ]));
+
+    body.appendChild(group('会话信息', [
+      item('模型', d.model || '--'),
+      item('代理', d.agent || '--'),
+      item('安装标识', d.install_id || '--', true),
+      item('来源', d.source || '--'),
+      item('修订号', F.fullNumber(d.revision)),
+      item('Schema 版本', (d.schema_version === undefined || d.schema_version === null) ? '--' : String(d.schema_version)),
+      item('上报器版本', d.reporter_version || '--')
+    ]));
+
+    body.appendChild(group('时间', [
+      item('会话创建', F.dateTime(d.session_created_at)),
+      item('最后活动', F.dateTime(d.last_activity_at)),
+      item('客户端上报', F.dateTime(d.client_reported_at)),
+      item('首次收录', F.dateTime(d.first_seen_at)),
+      item('最近上报', F.dateTime(d.last_reported_at))
+    ]));
+  }
+
+  function group(title, items) {
+    var g = document.createElement('div');
+    g.className = 'sess-detail-group';
+    var h = document.createElement('div');
+    h.className = 'sess-detail-heading';
+    h.textContent = title;
+    var grid = document.createElement('div');
+    grid.className = 'sess-detail-grid';
+    items.forEach(function (it) { grid.appendChild(it); });
+    g.appendChild(h);
+    g.appendChild(grid);
+    return g;
+  }
+
+  function item(label, value, mono, tip) {
+    var wrap = document.createElement('div');
+    wrap.className = 'sess-detail-item';
+    var l = document.createElement('div');
+    l.className = 'kpi-label';
+    l.textContent = label;
+    var v = document.createElement('div');
+    v.className = 'sess-detail-value' + (mono ? ' mono' : '');
+    v.textContent = value;
+    if (tip) v.title = tip;
+    wrap.appendChild(l);
+    wrap.appendChild(v);
+    return wrap;
+  }
+
+  // ---------- 初始化 ----------
+  function init(d) {
+    deps = d;
+    el = {
+      coverageCard: $('card-session-coverage'),
+      listCard: $('card-session-list'),
+      detailCard: $('card-session-detail'),
+      tbody: $('session-tbody'),
+      btnMore: $('btn-sess-more'),
+      count: $('sess-count'),
+      filterModel: $('sess-filter-model'),
+      filterAgent: $('sess-filter-agent'),
+      detailBody: $('sess-detail-body'),
+      detailId: $('sess-detail-id'),
+      covGateway: $('sess-cov-gateway'),
+      covReported: $('sess-cov-reported'),
+      covDiff: $('sess-cov-diff'),
+      covRate: $('sess-cov-rate'),
+      covNote: $('sess-cov-note')
+    };
+
+    el.btnMore.addEventListener('click', function () {
+      if (!st.nextCursor) return;
+      el.btnMore.disabled = true;
+      el.btnMore.textContent = '加载中…';
+      // fetchPage 内部消化错误，此处仅恢复按钮状态
+      fetchPage(deps.getCfg(), deps.getPeriod(), st.nextCursor, false, st.seq)
+        .then(function () {
+          el.btnMore.disabled = false;
+          el.btnMore.textContent = '加载更多';
+        });
+    });
+
+    el.filterModel.addEventListener('change', function () {
+      st.filters.model = this.value;
+      load();
+    });
+    el.filterAgent.addEventListener('change', function () {
+      st.filters.agent = this.value;
+      load();
+    });
+
+    $('btn-sess-detail-close').addEventListener('click', closeDetail);
+  }
+
+  window.BRU = window.BRU || {};
+  window.BRU.sessions = {
+    init: init,
+    load: load
+  };
+})();

package/src/cli.js

@@ -0,0 +1,164 @@
+import fs from "node:fs"
+import path from "node:path"
+import { spawn } from "node:child_process"
+import { readConfig, setConfig, maskKey } from "./config.js"
+import { dbFile, panelDir, pluginSource, opencodePluginsDir, PKG_ROOT } from "./paths.js"
+import { Store } from "./store.js"
+import { createServer } from "./server.js"
+
+const DEFAULT_PORT = 8787
+const DEFAULT_HOST = "127.0.0.1"
+
+function version() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8")).version
+  } catch {
+    return "0.0.0"
+  }
+}
+
+function parseFlags(argv) {
+  const flags = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=")
+      if (eq > -1) flags[a.slice(2, eq)] = a.slice(eq + 1)
+      else {
+        const next = argv[i + 1]
+        if (next !== undefined && !next.startsWith("--")) {
+          flags[a.slice(2)] = next
+          i++
+        } else flags[a.slice(2)] = true
+      }
+    } else if (a === "-h") flags.help = true
+    else if (a === "-v") flags.version = true
+    else flags._.push(a)
+  }
+  return flags
+}
+
+const HELP = `opencode-stats-reporter — 本地一体化 MaaS 用量看板
+
+用法:
+  opencode-stats-reporter config set --gateway <url> --key <key>   配置上游网关与 Key
+  opencode-stats-reporter config get                              查看配置（Key 脱敏）
+  opencode-stats-reporter web start [--port 8787] [--host 127.0.0.1] [--open]
+                                                              启动本地服务并托管面板
+  opencode-stats-reporter plugin install [--port 8787]            安装 opencode 上报插件
+
+选项:
+  -h, --help       显示帮助
+  -v, --version    显示版本
+`
+
+function cmdConfig(argv) {
+  const sub = argv[0]
+  const flags = parseFlags(argv.slice(1))
+  if (sub === "set") {
+    const cfg = setConfig({ gateway: flags.gateway, key: flags.key })
+    console.log("已写入配置: " + (cfg.gatewayBaseUrl || "(未设置)"))
+    console.log("API Key: " + maskKey(cfg.apiKey))
+    return
+  }
+  if (sub === "get") {
+    const cfg = readConfig()
+    console.log("gatewayBaseUrl: " + (cfg.gatewayBaseUrl || "(未设置)"))
+    console.log("apiKey: " + maskKey(cfg.apiKey))
+    return
+  }
+  throw new Error("用法: opencode-stats-reporter config set|get")
+}
+
+async function cmdWeb(argv) {
+  const sub = argv[0]
+  if (sub !== "start") throw new Error("用法: opencode-stats-reporter web start")
+  const flags = parseFlags(argv.slice(1))
+  const cfg = readConfig()
+  if (!cfg.gatewayBaseUrl || !cfg.apiKey) {
+    throw new Error("尚未配置上游网关，请先运行: opencode-stats-reporter config set --gateway <url> --key <key>")
+  }
+  const port = Number(flags.port || DEFAULT_PORT)
+  const host = String(flags.host || DEFAULT_HOST)
+  const mode = String(flags.mode || process.env.SESSION_USAGE_MODE || "local")
+  if (mode !== "local" && mode !== "gateway") throw new Error("--mode 必须是 local 或 gateway")
+  const loopback = host === "127.0.0.1" || host === "localhost" || host === "::1"
+
+  const store = new Store(dbFile())
+  store.migrate()
+  const server = createServer({ config: cfg, store, panelDir: panelDir(), mode, consumerHeader: flags["consumer-header"] || null })
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(port, host, resolve)
+  })
+
+  const url = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`
+  console.log("本地看板已启动: " + url)
+  console.log("上游网关: " + cfg.gatewayBaseUrl)
+  console.log("数据文件: " + dbFile())
+  if (!loopback) console.warn("警告: 正在监听非回环地址 " + host + "，本机网络内可访问，请自行确认风险")
+  if (flags.open) openBrowser(url)
+
+  process.on("SIGINT", () => {
+    console.log("\n正在关闭…")
+    store.close()
+    server.close(() => process.exit(0))
+    setTimeout(() => process.exit(0), 1000).unref()
+  })
+}
+
+function cmdPlugin(argv) {
+  const sub = argv[0]
+  if (sub !== "install") throw new Error("用法: opencode-stats-reporter plugin install")
+  const flags = parseFlags(argv.slice(1))
+  const port = Number(flags.port || DEFAULT_PORT)
+  const src = pluginSource()
+  if (!fs.existsSync(src)) throw new Error("包内未找到上报插件: " + src)
+  const dir = opencodePluginsDir()
+  fs.mkdirSync(dir, { recursive: true })
+  const dest = path.join(dir, "session-usage-reporter.ts")
+  const content = fs.readFileSync(src)
+  const same = fs.existsSync(dest) && Buffer.compare(fs.readFileSync(dest), content) === 0
+  if (same) {
+    console.log("插件已是最新: " + dest)
+  } else {
+    fs.writeFileSync(dest, content)
+    console.log("已安装插件: " + dest)
+  }
+  console.log("")
+  console.log("推荐用 npm 方式安装（可随 npm 更新、支持 -f 覆盖）:")
+  console.log("  opencode plugin @dijkspicy/opencode-stats-reporter -g")
+  console.log("")
+  console.log("以上为离线/本地文件安装方式。之后在 opencode 进程环境中设置:")
+  console.log("  SESSION_USAGE_ENDPOINT=http://127.0.0.1:" + port + "/v1/session-usage/report")
+  console.log("（本地模式无需 SESSION_USAGE_API_KEY；请勿使用 --pure 启动 opencode）")
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open"
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url]
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref()
+  } catch {
+    /* 打不开就算了 */
+  }
+}
+
+export async function main(argv) {
+  const flags = parseFlags(argv)
+  if (flags.version) {
+    console.log(version())
+    return
+  }
+  if (flags.help || argv.length === 0) {
+    console.log(HELP)
+    return
+  }
+  const [cmd, ...rest] = argv
+  if (cmd === "config") return cmdConfig(rest)
+  if (cmd === "web") return cmdWeb(rest)
+  if (cmd === "plugin") return cmdPlugin(rest)
+  console.log(HELP)
+  throw new Error("未知命令: " + cmd)
+}

package/src/config.js

@@ -0,0 +1,57 @@
+import fs from "node:fs"
+import { configDir, configFile } from "./paths.js"
+
+export function readConfig() {
+  try {
+    const raw = fs.readFileSync(configFile(), "utf8")
+    const obj = JSON.parse(raw)
+    return obj && typeof obj === "object" ? obj : {}
+  } catch {
+    return {}
+  }
+}
+
+/** 原子写入，权限 600 */
+export function writeConfig(cfg) {
+  fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 })
+  const tmp = configFile() + ".tmp"
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 })
+  fs.renameSync(tmp, configFile())
+  try {
+    fs.chmodSync(configFile(), 0o600)
+  } catch {
+    /* 平台不支持时忽略 */
+  }
+  return cfg
+}
+
+function validUrl(url) {
+  try {
+    const u = new URL(url)
+    return u.protocol === "http:" || u.protocol === "https:"
+  } catch {
+    return false
+  }
+}
+
+export function setConfig({ gateway, key }) {
+  const cfg = readConfig()
+  if (gateway !== undefined) {
+    const g = String(gateway).trim().replace(/\/+$/, "")
+    if (!validUrl(g)) throw new Error("gateway 必须是合法的 http(s) URL")
+    cfg.gatewayBaseUrl = g
+  }
+  if (key !== undefined) {
+    const k = String(key).trim()
+    if (!k) throw new Error("key 不能为空")
+    cfg.apiKey = k
+  }
+  return writeConfig(cfg)
+}
+
+export function maskKey(key) {
+  const k = String(key || "")
+  if (!k) return "(未设置)"
+  if (k.length <= 8) return "****"
+  return k.slice(0, 4) + "****" + k.slice(-4)
+}

package/src/identity.js

@@ -0,0 +1,34 @@
+import { LOCAL_CONSUMER } from "./store.js"
+
+// 与网关侧一致的消费者 ID 形态；不匹配者一律不认
+export const CONSUMER_PATTERN = /^api-key-[A-Za-z0-9]{6,32}$/
+
+export function normalizeConsumer(raw) {
+  if (!raw) return null
+  let c = String(raw).trim().split(",")[0].trim()
+  if (c.toLowerCase().startsWith("bearer ")) c = c.slice(7).trim()
+  return CONSUMER_PATTERN.test(c) ? c : null
+}
+
+/**
+ * 身份解析：
+ * - mode=gateway（网关托管）：只认网关注入的身份头，取不到即 fail-closed 返回 null → 401
+ * - mode=local（本地单用户）：取不到身份时归入单一本地用户
+ * - SESSION_USAGE_CONSUMER_HEADER 显式指定头名时，只认该头且 fail-closed（与 Python 版行为一致）
+ */
+export function createIdentityResolver({ mode = "local", headerName = null } = {}) {
+  return function resolveConsumer(req) {
+    const forced = (headerName || process.env.SESSION_USAGE_CONSUMER_HEADER || "").trim()
+    if (forced) {
+      return normalizeConsumer(req.headers[forced.toLowerCase()])
+    }
+    for (const header of ["x-forward-consumer"]) {
+      const c = normalizeConsumer(req.headers[header])
+      if (c) return c
+    }
+    // 本地开发回退：Authorization: Bearer api-key-xxx（网关上的 Key 是 UUID，过不了白名单，不会误认）
+    const c = normalizeConsumer(req.headers["authorization"])
+    if (c) return c
+    return mode === "local" ? LOCAL_CONSUMER : null
+  }
+}