@weiping/mbridge-page 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# mbridge's page for magpie
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+magpie 窗口侧栏 Plugins 组里的一个页面：magpie 记下的用量速览。
+
+## 它显示什么
+
+- **周期切换**（今天 / 7 天 / 30 天）与**排序**（Token / 调用 / 费用）
+- 四块：调用、错误（占调用的比例）、Token、费用
+- 模型表：按所选排序，每行一条占比条
+- 每 60 秒刷新一次，周期与排序记在 magpie 的 options 里
+
+## 它不显示什么
+
+**mbridge 自己的状态不在这里。** magpie 的页面插件跑在 `iframe sandbox="allow-scripts"`
+里，CSP 是 `connect-src 'none'`：它连不上 `127.0.0.1:3426`，也读不了 `router.json`。
+所以状态、报表、重启都在 mbridge 自己的状态页：
+
+    http://127.0.0.1:3426/status
+
+页面上把那行地址做成**可选择的文字**而不是链接：沙盒允许导航自己，但那是单程票
+（magpie 的 sidebar 不会把 frame 的 src 重置回来）。
+
+**不做档位归因**：magpie 记下的是最终回答的模型，`usage:summary` 里没有档位。
+
+## 装法
+
+文件夹插件，改了源码在终端重开一个 `magpie` 命令就是新的：
+
+    magpie plugin add ./clients/magpie-page
+
+确认装上了（`plugin list` 这个子命令不存在，用 `--json`）：
+
+    magpie plugin --json
+
+## 这个包必须永远是纯页面插件
+
+`package.json` 里**没有** `main`、**没有** `exports`，这不是偏好：
+magpie 的 `magpie.options.set()` 对纯窗口插件（有 `page`、无 `main`/`exports`）
+不重启插件宿主，而 CLI 写 options 每次都会。一旦给这个包加了 `main` 或 `exports`，
+用户每点一次周期切换就可能把所有插件重启一轮。`page.test.mjs` 里有一条守着。
+
+## 测试
+
+    bun test clients/magpie-page

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@weiping/mbridge-page",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "mbridge's usage at a glance inside magpie: what magpie's ledger recorded, and where mbridge's own status page is.",
+  "license": "MIT",
+  "keywords": [
+    "magpie",
+    "magpie-plugin",
+    "mbridge",
+    "model-router"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weiping/mbridge.git",
+    "directory": "clients/magpie-page"
+  },
+  "bugs": {
+    "url": "https://github.com/weiping/mbridge/issues"
+  },
+  "files": [
+    "page",
+    "README.md"
+  ],
+  "magpie": {
+    "page": {
+      "title": "mbridge",
+      "titles": {
+        "zh": "mbridge",
+        "zh-TW": "mbridge",
+        "ja": "mbridge",
+        "de": "mbridge"
+      },
+      "file": "page/index.html",
+      "icon": "page/icon.svg"
+    },
+    "permissions": [
+      "usage:summary"
+    ],
+    "options": {
+      "period": "7d",
+      "sort": "tokens"
+    }
+  }
+}

package/page/app.js

@@ -0,0 +1,153 @@
+// app.js reads magpie's ledger and draws it. It never reaches mbridge:
+// the sandbox a magpie page runs in has no network at all (connect-src
+// 'none'), and the only thing this page needs is what magpie already
+// recorded (SP14 §2).
+//
+// A classic script, like the community's usage page: it reads the view
+// from globalThis.
+(async () => {
+  const V = globalThis.MbridgeView;
+  const $ = (id) => document.getElementById(id);
+  const theme = await magpie.ready;
+  let lang = theme.lang;
+
+  // the period and the sort live in this plugin's own options, so the
+  // page opens where it was left
+  let opts = {};
+  try {
+    opts = (await magpie.options.get()) || {};
+  } catch {
+    // no options yet: the defaults in package.json stand
+  }
+  const state = {
+    period: V.PERIODS.includes(opts.period) ? opts.period : "7d",
+    sort: V.SORTS.includes(opts.sort) ? opts.sort : "tokens",
+    summary: null,
+    error: null,
+  };
+
+  function words() {
+    const t = V.text(lang);
+    document.querySelectorAll("[data-t]").forEach((e) => {
+      e.textContent = t[e.dataset.t];
+    });
+    $("status").textContent = t.status;
+    $("restart").textContent = t.restart;
+    $("cmd").textContent = "mbridge service restart";
+  }
+
+  function pick(group, attr, value) {
+    $(group).querySelectorAll("button").forEach((b) => {
+      b.setAttribute("aria-selected", String(b.dataset[attr] === value));
+    });
+  }
+
+  function paint() {
+    pick("periods", "period", state.period);
+    pick("sorts", "sort", state.sort);
+    const s = state.summary;
+    if (!s) return;
+    $("since").textContent = V.since(s, lang);
+
+    $("tiles").replaceChildren(
+      ...V.tiles(s, lang).map((tile) => {
+        const cell = document.createElement("div");
+        cell.className = "tile";
+        for (const [cls, value] of [["k", tile.label], ["v", tile.value], ["s", tile.sub]]) {
+          if (value === undefined) continue;
+          const e = document.createElement("div");
+          e.className = cls;
+          e.textContent = value;
+          cell.append(e);
+        }
+        return cell;
+      })
+    );
+
+    const rows = V.rows(s, state.sort, lang);
+    $("rows").replaceChildren(
+      ...rows.map((r) => {
+        const tr = document.createElement("tr");
+        const name = document.createElement("td");
+        name.className = "model";
+        name.textContent = r.model;
+        const bar = document.createElement("span");
+        bar.className = "bar";
+        const fill = document.createElement("i");
+        fill.style.width = Math.max(2, Math.round(r.shareValue * 100)) + "%";
+        bar.append(fill);
+        name.append(bar);
+        const calls = document.createElement("td");
+        calls.className = "num";
+        calls.textContent = r.calls;
+        const tokens = document.createElement("td");
+        tokens.className = "num";
+        tokens.textContent = r.tokens;
+        const cost = document.createElement("td");
+        cost.className = "num";
+        cost.textContent = r.cost;
+        tr.append(name, calls, tokens, cost);
+        return tr;
+      })
+    );
+    $("empty").hidden = rows.length > 0;
+    $("empty").textContent = V.text(lang).empty;
+    $("error").hidden = !state.error;
+    if (state.error) {
+      $("error").textContent = V.text(lang).failed + ": " + state.error + " · " + V.text(lang).retry;
+    }
+  }
+
+  async function load() {
+    try {
+      state.summary = await magpie.read("usage:summary", { period: state.period });
+      state.error = null;
+    } catch (e) {
+      state.error = (e && e.message) || String(e);
+    }
+    paint();
+  }
+
+  // magpie takes one options write a second: a quick second click is
+  // saved with the next one
+  let saving = null;
+  function save() {
+    if (saving) return;
+    saving = setTimeout(async () => {
+      saving = null;
+      try {
+        opts = (await magpie.options.set({ ...opts, period: state.period, sort: state.sort })) || opts;
+      } catch {
+        // not remembering is not worth an error on the page
+      }
+    }, 1100);
+  }
+
+  $("periods").addEventListener("click", (e) => {
+    const b = e.target.closest("button[data-period]");
+    if (!b || b.dataset.period === state.period) return;
+    state.period = b.dataset.period;
+    save();
+    load();
+  });
+
+  $("sorts").addEventListener("click", (e) => {
+    const b = e.target.closest("button[data-sort]");
+    if (!b || b.dataset.sort === state.sort) return;
+    state.sort = b.dataset.sort;
+    save();
+    paint();
+  });
+
+  // the period and sort buttons carry their own words
+  for (const b of $("periods").querySelectorAll("button[data-period]")) {
+    b.textContent = V.periodLabel(b.dataset.period, lang);
+  }
+  for (const b of $("sorts").querySelectorAll("button[data-sort]")) {
+    b.textContent = V.sortLabel(b.dataset.sort, lang);
+  }
+  $("addr").textContent = V.STATUS_URL;
+  words();
+  await load();
+  setInterval(load, 60000);
+})();

package/page/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none"
+     stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"
+     role="img" aria-label="mbridge">
+  <path d="M2 15c4.5 0 4.5-4 9-4s4.5 4 9 4" />
+  <path d="M2 19c4.5 0 4.5-4 9-4s4.5 4 9 4" opacity=".45" />
+  <path d="M5 15V9m7 6V9m7 6V9" />
+</svg>

package/page/index.html

@@ -0,0 +1,64 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>mbridge</title>
+<link rel="stylesheet" href="style.css">
+<script src="_magpie/bridge.js"></script>
+<script src="view.js"></script>
+</head>
+<body>
+<main class="root">
+  <header class="head">
+    <h1 data-t="title">mbridge</h1>
+    <p class="subtitle" data-t="subtitle"></p>
+    <p class="since" id="since"></p>
+  </header>
+
+  <div class="bar">
+    <div class="segmented" id="periods">
+      <button type="button" data-period="today" aria-selected="false"></button>
+      <button type="button" data-period="7d" aria-selected="false"></button>
+      <button type="button" data-period="30d" aria-selected="false"></button>
+    </div>
+    <div class="segmented" id="sorts">
+      <button type="button" data-sort="tokens" aria-selected="false"></button>
+      <button type="button" data-sort="calls" aria-selected="false"></button>
+      <button type="button" data-sort="cost" aria-selected="false"></button>
+    </div>
+  </div>
+
+  <section class="tiles" id="tiles"></section>
+
+  <section class="models">
+    <h2 data-t="models">by model</h2>
+    <table class="table">
+      <thead>
+        <tr>
+          <th data-t="model">model</th>
+          <th class="num" data-t="calls">calls</th>
+          <th class="num" data-t="tokens">tokens</th>
+          <th class="num" data-t="cost">cost</th>
+        </tr>
+      </thead>
+      <tbody id="rows"></tbody>
+    </table>
+    <p class="muted empty" id="empty" hidden></p>
+  </section>
+
+  <section class="notes">
+    <p class="note" data-t="disclaimer"></p>
+    <p class="note">
+      <span id="status"></span>
+      <span class="addr" id="addr" title="select and copy it"></span>
+      <span id="restart"></span>
+      <code class="cmd" id="cmd"></code>
+    </p>
+  </section>
+
+  <p class="error" id="error" hidden></p>
+</main>
+<script src="app.js" defer></script>
+</body>
+</html>

package/page/style.css

@@ -0,0 +1,48 @@
+/* Only magpie's own variables, so the page follows the window's theme in
+   both light and dark without knowing either. */
+.root {
+  --pad: 12px;
+  padding: var(--pad);
+  font: 12px/1.5 var(--magpie-font, system-ui, -apple-system, "Segoe UI", sans-serif);
+  color: var(--magpie-fg, #1a1a1a);
+  background: var(--magpie-bg, transparent);
+}
+h1 { margin: 0; font-size: 1.05em; font-weight: 600; }
+.subtitle { margin: 2px 0 0; color: var(--magpie-fg-muted, #6b6b6b); }
+.since { margin: 0 0 8px; color: var(--magpie-fg-muted, #6b6b6b); font-size: .9em; }
+.bar { display: flex; gap: 8px; justify-content: space-between; flex-wrap: wrap; margin-bottom: 10px; }
+.segmented { display: flex; gap: 2px; }
+.segmented button {
+  font: inherit; color: inherit; cursor: pointer; padding: 2px 8px; border-radius: 5px;
+  border: 1px solid var(--magpie-border, #d8d8d8);
+  background: var(--magpie-bg-subtle, transparent);
+}
+.segmented button[aria-selected="true"] {
+  background: var(--magpie-accent, #2f6feb); border-color: transparent; color: #fff;
+}
+.tiles { display: grid; grid-template-columns: repeat(4, 1fr); gap: 6px; margin-bottom: 14px; }
+.tile {
+  padding: 6px 8px; border-radius: 6px;
+  border: 1px solid var(--magpie-border, #e3e3e3);
+  background: var(--magpie-bg-subtle, transparent);
+}
+.tile .k { color: var(--magpie-fg-muted, #6b6b6b); }
+.tile .v { font-size: 1.15em; font-weight: 600; font-variant-numeric: tabular-nums; }
+.tile .s { color: var(--magpie-fg-muted, #6b6b6b); }
+.models h2 { margin: 0 0 4px; font-size: 1em; font-weight: 600; }
+.muted { color: var(--magpie-fg-muted, #6b6b6b); }
+.table { width: 100%; border-collapse: collapse; }
+.table th, .table td { text-align: left; padding: 3px 4px; border-bottom: 1px solid var(--magpie-border, #e3e3e3); }
+.table .num { text-align: right; font-variant-numeric: tabular-nums; }
+.table th.num { text-align: right; color: var(--magpie-fg-muted, #6b6b6b); font-weight: 500; }
+.model { width: 55%; overflow-wrap: anywhere; }
+.bar { display: block; height: 2px; margin-top: 2px; background: var(--magpie-border, #e3e3e3); border-radius: 1px; overflow: hidden; }
+.bar > i { display: block; height: 100%; background: var(--magpie-accent, #2f6feb); }
+.empty { margin: 6px 0; }
+.notes { margin-top: 14px; }
+.note { margin: 4px 0; color: var(--magpie-fg-muted, #6b6b6b); }
+/* the address is selectable text, not a link: the sandbox may navigate
+   itself, but that is a one-way ticket (SP14 §2) */
+.addr { user-select: all; color: var(--magpie-fg, inherit); }
+.cmd { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--magpie-fg, inherit); }
+.error { color: var(--magpie-danger, #b42318); margin: 8px 0 0; }

package/page/view.js

@@ -0,0 +1,173 @@
+// view.js is what the page shows, worked out from usage:summary without
+// the DOM, so a test can check it.
+//
+// It is a classic script, not a module: a magpie page runs in a sandbox
+// whose CSP serves the plugin's own files, and the community's usage
+// page does it this way too (globalThis.UsageView). A module script
+// would be a different thing to load, and the test below loads this file
+// the same way the page does.
+
+(() => {
+  const TEXT = {
+    en: {
+      title: "mbridge",
+      subtitle: "what magpie's ledger recorded",
+      calls: "calls",
+      errors: "errors",
+      errorShare: "of the calls",
+      tokens: "tokens",
+      cost: "cost",
+      models: "by model",
+      model: "model",
+      today: "today",
+      "7d": "7 days",
+      "30d": "30 days",
+      sortTokens: "tokens",
+      sortCalls: "calls",
+      sortCost: "cost",
+      empty: "no calls in this period",
+      failed: "couldn't read usage",
+      retry: "try again in a minute",
+      since: "since",
+      disclaimer:
+        "This is everything magpie recorded. It is mbridge's usage only when every client goes through mbridge; whatever you use magpie for directly is in here too.",
+      status: "mbridge's own status:",
+      restart: "restart it with",
+    },
+    zh: {
+      title: "mbridge",
+      subtitle: "magpie 记下的全部用量",
+      calls: "调用",
+      errors: "错误",
+      errorShare: "占调用",
+      tokens: "Token",
+      cost: "费用",
+      models: "按模型",
+      model: "模型",
+      today: "今天",
+      "7d": "7 天",
+      "30d": "30 天",
+      sortTokens: "Token",
+      sortCalls: "调用",
+      sortCost: "费用",
+      empty: "这个区间没有调用",
+      failed: "读不到 magpie 的用量",
+      retry: "一分钟后自动重试",
+      since: "起",
+      disclaimer:
+        "这是 magpie 记下的全部用量。客户端都走 mbridge 时它才等于 mbridge 的用量；你直接用 magpie 的那部分也在里面。",
+      status: "mbridge 自己的状态：",
+      restart: "重启用",
+    },
+  };
+
+  const PERIODS = ["today", "7d", "30d"];
+  const SORTS = ["tokens", "calls", "cost"];
+  const STATUS_URL = "http://127.0.0.1:3426/status";
+
+  // text is the words for a language: zh for anything that starts with zh.
+  function text(lang) {
+    return String(lang || "").toLowerCase().startsWith("zh") ? TEXT.zh : TEXT.en;
+  }
+
+  // count is a number a person reads: 1,234 or 1.23M.
+  function count(n) {
+    n = Number(n) || 0;
+    const a = Math.abs(n);
+    if (a >= 1e9) return (n / 1e9).toFixed(2) + "B";
+    if (a >= 1e6) return (n / 1e6).toFixed(2) + "M";
+    if (a >= 1e3) return n.toLocaleString("en-US");
+    return String(n);
+  }
+
+  // money is a price, never NaN, and never "$0.00" for something real.
+  function money(n) {
+    n = Number(n);
+    if (!isFinite(n)) return "$0";
+    if (n === 0) return "$0";
+    if (n > 0 && n < 0.01) return "<$0.01";
+    if (n < 10) return "$" + n.toFixed(4).replace(/0+$/, "").replace(/\.$/, "");
+    if (n < 1000) return "$" + n.toFixed(2);
+    return "$" + n.toFixed(0);
+  }
+
+  // share is a percentage, and never NaN.
+  function pct(part, whole) {
+    const p = Number(part) || 0;
+    const w = Number(whole) || 0;
+    if (w <= 0) return "0%";
+    const v = (100 * p) / w;
+    if (!isFinite(v)) return "0%";
+    return (Math.round(v * 10) / 10).toString() + "%";
+  }
+
+  // tiles are the four numbers at the top: calls, errors, tokens, cost.
+  function tiles(summary, lang) {
+    const t = text(lang);
+    const s = summary || {};
+    return [
+      { key: "calls", label: t.calls, value: count(s.calls) },
+      {
+        key: "errors",
+        label: t.errors,
+        value: count(s.errors),
+        sub: t.errorShare + " " + pct(s.errors, s.calls),
+      },
+      { key: "tokens", label: t.tokens, value: count((s.input || 0) + (s.output || 0)) },
+      { key: "cost", label: t.cost, value: money(s.cost) },
+    ];
+  }
+
+  // rows are the model table, sorted by tokens, calls or cost, with each
+  // model's share of the total.
+  function rows(summary, sort, lang) {
+    const s = summary || {};
+    const models = Array.isArray(s.models) ? s.models : [];
+    const key = sort === "calls" ? "calls" : sort === "cost" ? "cost" : "tokens";
+    const value = (m) => (key === "tokens" ? (m.input || 0) + (m.output || 0) : m[key] || 0);
+    const sorted = models.slice().sort((a, b) => value(b) - value(a));
+    const total = sorted.reduce((a, m) => a + value(m), 0);
+    return sorted.map((m) => ({
+      model: m.model || "?",
+      calls: count(m.calls),
+      tokens: count((m.input || 0) + (m.output || 0)),
+      cost: money(m.cost),
+      share: pct(value(m), total),
+      shareValue: total > 0 ? value(m) / total : 0,
+    }));
+  }
+
+  // since is when the period started.
+  function since(summary, lang) {
+    const t = text(lang);
+    const s = summary || {};
+    return s.since ? t.since + " " + s.since : "";
+  }
+
+  // periodLabel is the name of a period.
+  function periodLabel(period, lang) {
+    return text(lang)[period] || period;
+  }
+
+  // sortLabel is the name of a sort.
+  function sortLabel(sort, lang) {
+    const t = text(lang);
+    return t["sort" + sort.charAt(0).toUpperCase() + sort.slice(1)] || sort;
+  }
+
+  globalThis.MbridgeView = {
+    TEXT,
+    PERIODS,
+    SORTS,
+    STATUS_URL,
+    text,
+    count,
+    money,
+    pct,
+    tiles,
+    rows,
+    since,
+    periodLabel,
+    sortLabel,
+  };
+})();