@weiping/mbridge-page 0.0.0-stage → 0.1.0

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,38 @@
 {
   "name": "@weiping/mbridge-page",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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"]
+  }
+}

package/page/app.js

@@ -0,0 +1,161 @@
+/* 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, and the only
+   thing this page needs is what magpie already recorded (SP14 §2). */
+
+import { tiles, rows, periods, sorts, header } from "./view.js";
+
+const REFRESH_MS = 60000; // magpie's ledger moves slowly enough
+const STATUS_URL = "http://127.0.0.1:3426/status";
+const OPTIONS_KEY = "mbridge-page"; // magpie options keep the period and the sort
+
+const state = { period: "7d", sort: "tokens", summary: null, error: null, lang: "en" };
+
+function $(id) {
+  return document.getElementById(id);
+}
+
+function segment(container, items, current, onPick) {
+  container.textContent = "";
+  for (const item of items) {
+    const b = document.createElement("button");
+    b.type = "button";
+    b.className = "seg" + (item.key === current ? " seg-on" : "");
+    b.textContent = item.label;
+    b.addEventListener("click", () => onPick(item.key));
+    container.appendChild(b);
+  }
+}
+
+function render() {
+  const t = header(state.summary, state.lang);
+  $("title").textContent = t.title;
+  $("subtitle").textContent = state.summary ? t.subtitle : "";
+  if (t.since) $("subtitle").textContent += " · " + t.since;
+
+  segment($("periods"), periods(state.lang), state.period, (k) => {
+    if (k === state.period) return;
+    state.period = k;
+    save();
+    load();
+  });
+  segment($("sorts"), sorts(state.lang), state.sort, (k) => {
+    state.sort = k;
+    save();
+    render();
+  });
+
+  const box = $("tiles");
+  box.textContent = "";
+  for (const tile of tiles(state.summary, state.lang)) {
+    const cell = document.createElement("div");
+    cell.className = "tile";
+    const label = document.createElement("div");
+    label.className = "tile-label";
+    label.textContent = tile.label;
+    const value = document.createElement("div");
+    value.className = "tile-value";
+    value.textContent = tile.value;
+    cell.appendChild(label);
+    cell.appendChild(value);
+    if (tile.sub) {
+      const sub = document.createElement("div");
+      sub.className = "tile-sub";
+      sub.textContent = tile.sub;
+      cell.appendChild(sub);
+    }
+    box.appendChild(cell);
+  }
+
+  const r = rows(state.summary, state.sort, state.lang);
+  $("models-label").textContent = r.label;
+  $("models-sort").textContent = r.sortLabel;
+  $("th-model").textContent = viewText("model");
+  $("th-calls").textContent = viewText("calls");
+  $("th-tokens").textContent = viewText("tokens");
+  $("th-cost").textContent = viewText("cost");
+
+  const body = $("rows");
+  body.textContent = "";
+  for (const item of r.items) {
+    const tr = document.createElement("tr");
+    const name = document.createElement("td");
+    name.className = "model";
+    name.textContent = item.model;
+    const bar = document.createElement("span");
+    bar.className = "bar";
+    const fill = document.createElement("i");
+    fill.style.width = Math.round(item.shareValue * 100) + "%";
+    bar.appendChild(fill);
+    name.appendChild(bar);
+    tr.appendChild(name);
+    for (const key of ["calls", "tokens", "cost"]) {
+      const td = document.createElement("td");
+      td.className = "num";
+      td.textContent = item[key];
+      tr.appendChild(td);
+    }
+    body.appendChild(tr);
+  }
+  $("empty").textContent = r.items.length ? "" : t.emptyText;
+
+  $("disclaimer").textContent = t.disclaimer;
+  $("status-label").textContent = t.status + " ";
+  // the address is selectable text, not a link: the sandbox can navigate
+  // itself, but that is a one-way ticket (SP14 §2)
+  $("status-addr").textContent = t.statusWhere + " " + STATUS_URL;
+  $("restart-label").textContent = " · " + t.restart + " ";
+  $("error").textContent = state.error ? state.error + " · " + t.retry : "";
+}
+
+// viewText is one word from the page's vocabulary.
+function viewText(key) {
+  const v = globalThis.MbridgeView;
+  const l = state.lang === "zh" ? "zh" : "en";
+  return v.TEXT[l][key] || key;
+}
+
+async function load() {
+  try {
+    state.summary = await magpie.read("usage:summary", { period: state.period });
+    state.error = null;
+  } catch (err) {
+    state.error = (err && err.message) || String(err);
+  }
+  render();
+}
+
+// save remembers the period and the sort in magpie's own options, so the
+// page comes back the way it was left. magpie takes one write a second.
+async function save() {
+  try {
+    const opts = (await magpie.options.get()) || {};
+    opts[OPTIONS_KEY] = { period: state.period, sort: state.sort };
+    await magpie.options.set(opts);
+  } catch {
+    // not being able to remember is not worth an error on the page
+  }
+}
+
+async function restore() {
+  try {
+    const opts = (await magpie.options.get()) || {};
+    const mine = opts[OPTIONS_KEY];
+    if (mine && mine.period) state.period = mine.period;
+    if (mine && mine.sort) state.sort = mine.sort;
+  } catch {
+    // the defaults stand
+  }
+}
+
+(async function start() {
+  await magpie.ready;
+  const theme = magpie.theme || {};
+  if ((theme.lang || "").toLowerCase().startsWith("zh")) state.lang = "zh";
+  if (magpie.onTheme) magpie.onTheme((t) => {
+    if ((t && t.lang || "").toLowerCase().startsWith("zh")) state.lang = "zh";
+    render();
+  });
+  await restore();
+  await load();
+  setInterval(load, REFRESH_MS);
+})();

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,58 @@
+<!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 id="root" class="root">
+  <header class="head">
+    <h1 id="title" class="title">mbridge</h1>
+    <p id="subtitle" class="subtitle"></p>
+  </header>
+
+  <div class="bar">
+    <div id="periods" class="segmented"></div>
+    <div id="sorts" class="segmented"></div>
+  </div>
+
+  <section id="tiles" class="tiles"></section>
+
+  <section class="models">
+    <div class="models-head">
+      <h2 id="models-label" class="label"></h2>
+      <span id="models-sort" class="muted"></span>
+    </div>
+    <table class="table">
+      <thead>
+        <tr>
+          <th id="th-model"></th>
+          <th class="num" id="th-calls"></th>
+          <th class="num" id="th-tokens"></th>
+          <th class="num" id="th-cost"></th>
+        </tr>
+      </thead>
+      <tbody id="rows"></tbody>
+    </table>
+    <p id="empty" class="muted empty"></p>
+  </section>
+
+  <section class="notes">
+    <p id="disclaimer" class="note"></p>
+    <p class="note">
+      <span id="status-label"></span>
+      <span id="status-addr" class="addr" title="select and copy it"></span>
+      <span id="restart-label"></span>
+      <code class="cmd">mbridge service restart</code>
+    </p>
+  </section>
+
+  <p id="error" class="error"></p>
+</main>
+<script src="app.js" defer></script>
+</body>
+</html>

package/page/style.css

@@ -0,0 +1,46 @@
+/* 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);
+}
+.title { margin: 0; font-size: 1.05em; font-weight: 600; }
+.subtitle { margin: 2px 0 10px; color: var(--magpie-fg-muted, #6b6b6b); }
+.bar { display: flex; gap: 8px; justify-content: space-between; flex-wrap: wrap; margin-bottom: 10px; }
+.segmented { display: flex; gap: 2px; }
+.seg {
+  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);
+}
+.seg-on { 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-label { color: var(--magpie-fg-muted, #6b6b6b); }
+.tile-value { font-size: 1.15em; font-weight: 600; font-variant-numeric: tabular-nums; }
+.tile-sub { color: var(--magpie-fg-muted, #6b6b6b); }
+.label { margin: 0; font-size: 1em; font-weight: 600; }
+.models-head { display: flex; justify-content: space-between; align-items: baseline; }
+.muted { color: var(--magpie-fg-muted, #6b6b6b); }
+.table { width: 100%; border-collapse: collapse; margin-top: 4px; }
+.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 */
+.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); min-height: 1em; margin: 8px 0 0; }

package/page/view.js

@@ -0,0 +1,178 @@
+// view.js is mbridge's magpie page: the words and the arithmetic, with
+// no DOM in it, so the page and the tests can both use it.
+//
+// The numbers come from magpie's own ledger (`magpie.read("usage:summary")`),
+// never from mbridge: the page runs in a sandbox that cannot reach mbridge
+// at all (SP14 §2). Nothing here knows about tiers — magpie records the
+// model that answered, and mbridge's group is not in there.
+
+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",
+    period: { today: "today", "7d": "7 days", "30d": "30 days" },
+    sort: { tokens: "tokens", calls: "calls", cost: "cost" },
+    empty: "no calls in this period",
+    error: "magpie's usage could not be read",
+    retry: "try again in a minute",
+    since: "since",
+    total: "total",
+    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",
+    statusWhere: "mbridge's status page:",
+    restart: "restart it with",
+  },
+  zh: {
+    title: "mbridge",
+    subtitle: "magpie 记下的全部用量",
+    calls: "调用",
+    errors: "错误",
+    errorShare: "占调用",
+    tokens: "Token",
+    cost: "费用",
+    models: "按模型",
+    model: "模型",
+    period: { today: "今天", "7d": "7 天", "30d": "30 天" },
+    sort: { tokens: "Token", calls: "调用", cost: "费用" },
+    empty: "这个区间没有调用",
+    error: "读不到 magpie 的用量",
+    retry: "一分钟后自动重试",
+    since: "起",
+    total: "合计",
+    disclaimer:
+      "这是 magpie 记下的全部用量。客户端都走 mbridge 时它才等于 mbridge 的用量；你直接用 magpie 的那部分也在里面。",
+    status: "mbridge 自己的状态",
+    statusWhere: "mbridge 的状态页：",
+    restart: "重启用",
+  },
+};
+
+/** count is a number a person reads: 1,234 or 1.23M. */
+export function count(n) {
+  const v = Number(n) || 0;
+  if (Math.abs(v) >= 1e9) return (v / 1e9).toFixed(2) + "B";
+  if (Math.abs(v) >= 1e6) return (v / 1e6).toFixed(2) + "M";
+  if (Math.abs(v) >= 1e3) return v.toLocaleString("en-US");
+  return String(v);
+}
+
+/** money is a price, never NaN, and never "$0.00" for something real. */
+export function money(n) {
+  const v = Number(n);
+  if (!isFinite(v)) return "$0";
+  if (v === 0) return "$0";
+  if (v > 0 && v < 0.01) return "<$0.01";
+  if (v < 10) return "$" + v.toFixed(4).replace(/0+$/, "").replace(/\.$/, "");
+  if (v < 1000) return "$" + v.toFixed(2);
+  return "$" + v.toFixed(0);
+}
+
+/** share is a percentage, and never NaN. */
+export 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() + "%";
+}
+
+function lang(l) {
+  return l === "zh" ? "zh" : "en";
+}
+
+/** tiles are the four numbers at the top: calls, errors, tokens, cost. */
+export function tiles(summary, l = "en") {
+  const t = TEXT[lang(l)];
+  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. */
+export function rows(summary, sort = "tokens", l = "en") {
+  const t = TEXT[lang(l)];
+  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);
+  const labels = t.sort;
+  return {
+    sort: key,
+    label: t.models,
+    sortLabel: labels[key] || key,
+    total,
+    items: 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,
+    })),
+  };
+}
+
+/** period labels, in the order magpie offers them. */
+export function periods(l = "en") {
+  const t = TEXT[lang(l)];
+  return ["today", "7d", "30d"].map((k) => ({ key: k, label: t.period[k] }));
+}
+
+/** sorts, in the order the page offers them. */
+export function sorts(l = "en") {
+  const t = TEXT[lang(l)];
+  return ["tokens", "calls", "cost"].map((k) => ({ key: k, label: t.sort[k] }));
+}
+
+/** header is what the page says above the numbers. */
+export function header(summary, l = "en") {
+  const t = TEXT[lang(l)];
+  const s = summary || {};
+  return {
+    title: t.title,
+    subtitle: t.subtitle,
+    since: s.since ? t.since + " " + s.since : "",
+    empty: !s.calls,
+    emptyText: t.empty,
+    error: t.error,
+    retry: t.retry,
+    disclaimer: t.disclaimer,
+    status: t.status,
+    statusWhere: t.statusWhere,
+    restart: t.restart,
+  };
+}
+
+globalThis.MbridgeView = {
+  TEXT,
+  count,
+  money,
+  pct,
+  tiles,
+  rows,
+  periods,
+  sorts,
+  header,
+};