dsh-local-telemetry 0.1.0

package/src/store.mjs

@@ -0,0 +1,346 @@
+/**
+ * dsh-local-telemetry — 存储读取层（计划 §8）。
+ *
+ * JSONL 与 SQLite 共享同一读取接口与过滤语义；聚合器只面对事件数组，
+ * 因此两种后端对同一事件集产生一致聚合结果（Phase 5 验收）。
+ * 读取同样 fail-open：坏行 / 不兼容 schema 跳过并计数，绝不中断查询。
+ */
+
+import { readdir, readFile, stat, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { SUPPORTED_SCHEMA_MAJOR, deserializeEvent } from "./schema.mjs";
+import { resolveDataPath } from "./config.mjs";
+import { JsonlSink } from "./sink-jsonl.mjs";
+
+const META_FILE = "meta.json";
+
+export function normalizeFilters(filters = {}) {
+  return {
+    fromMs: filters.fromMs ?? null,
+    toMs: filters.toMs ?? null,
+    profile: filters.profile ?? null,
+    model: filters.model ?? null, // 匹配 model.name 或其末段
+    tool: filters.tool ?? null,
+    plugin: filters.plugin ?? null,
+    event: filters.event ?? null, // 精确事件名或 "request.*" 域通配
+    traceId: filters.traceId ?? null,
+    errorsOnly: Boolean(filters.errorsOnly),
+  };
+}
+
+function modelMatches(modelObj, filterValue) {
+  if (!filterValue) return true;
+  const name = modelObj?.name;
+  if (typeof name !== "string") return false;
+  if (name === filterValue) return true;
+  const tail = name.split("/").pop();
+  return tail === filterValue;
+}
+
+function eventMatches(eventName, filterValue) {
+  if (!filterValue) return true;
+  if (filterValue.endsWith(".*")) return eventName?.startsWith(filterValue.slice(0, -1));
+  return eventName === filterValue;
+}
+
+export function isFailureEvent(event) {
+  const status = event.result?.status;
+  return (
+    event.event === "model.failed" ||
+    event.event === "request.cancelled" ||
+    status === "failed" ||
+    status === "timeout" ||
+    status === "cancelled"
+  );
+}
+
+/** 过滤器应用于单事件。 */
+export function matchesFilters(event, filters) {
+  const f = filters;
+  if (f.fromMs !== null || f.toMs !== null) {
+    const ts = Date.parse(event.timestamp ?? "");
+    if (!Number.isFinite(ts)) return false;
+    if (f.fromMs !== null && ts < f.fromMs) return false;
+    if (f.toMs !== null && ts > f.toMs) return false;
+  }
+  if (f.profile && event.session?.profile !== f.profile) return false;
+  if (!modelMatches(event.model, f.model)) return false;
+  if (f.tool && event.tool?.name !== f.tool) return false;
+  if (f.plugin && event.plugin?.name !== f.plugin) return false;
+  if (f.event && !eventMatches(event.event, f.event)) return false;
+  if (f.traceId && event.trace_id !== f.traceId) return false;
+  if (f.errorsOnly && !isFailureEvent(event)) return false;
+  return true;
+}
+
+/** JSONL 目录读取器。 */
+export function createJsonlStore({ path, now = () => Date.now() } = {}) {
+  const dir = resolveDataPath(path);
+  return {
+    kind: "jsonl",
+    path: dir,
+    async readEvents(filters = {}) {
+      const f = normalizeFilters(filters);
+      const events = [];
+      const skipped = { invalid: 0, schema_incompatible: 0, unreadable_files: 0 };
+      let names = [];
+      try {
+        names = (await readdir(dir)).filter((name) => name.endsWith(".jsonl")).sort();
+      } catch {
+        return { events, skipped };
+      }
+      for (const name of names) {
+        let content;
+        try {
+          content = await readFile(join(dir, name), "utf8");
+        } catch {
+          skipped.unreadable_files += 1;
+          continue;
+        }
+        for (const rawLine of content.split(/\r?\n/)) {
+          const line = rawLine.trim();
+          if (line.length === 0) continue;
+          const parsed = deserializeEvent(line);
+          if (!parsed.ok) {
+            skipped.invalid += 1;
+            continue;
+          }
+          const event = parsed.event;
+          const major = Number.parseInt(String(event?.schema_version ?? "").split(".")[0], 10);
+          if (!Number.isFinite(major) || major !== SUPPORTED_SCHEMA_MAJOR) {
+            skipped.schema_incompatible += 1;
+            continue;
+          }
+          if (matchesFilters(event, f)) events.push(event);
+        }
+      }
+      return { events, skipped };
+    },
+
+    async status() {
+      let files = [];
+      let totalBytes = 0;
+      try {
+        const names = (await readdir(dir)).filter((name) => name.endsWith(".jsonl")).sort();
+        for (const name of names) {
+          const info = await stat(join(dir, name));
+          files.push({ name, bytes: info.size, mtime: info.mtimeMs });
+          totalBytes += info.size;
+        }
+      } catch {
+        files = [];
+      }
+      return {
+        store: "jsonl",
+        path: dir,
+        exists: existsSync(dir),
+        files,
+        total_bytes: totalBytes,
+        counters: await readMetaCounters(dir),
+      };
+    },
+
+    async purge({ olderThanMs = null, beforeMs = null } = {}) {
+      const sink = new JsonlSink({ dir });
+      sink.now = now;
+      return sink.purge({ olderThanMs, beforeMs });
+    },
+  };
+}
+
+/** SQLite 读取器（Node <22.5 时 available=false，readEvents 返回空集与原因）。 */
+export async function createSqliteStore({ path } = {}) {
+  const dir = resolveDataPath(path);
+  const { sqliteAvailable } = await import("./sink-sqlite.mjs");
+  const availability = await sqliteAvailable();
+  if (!availability.available) {
+    return {
+      kind: "sqlite",
+      path: dir,
+      available: false,
+      unavailable_reason: availability.reason,
+      async readEvents() {
+        return { events: [], skipped: { invalid: 0, schema_incompatible: 0, unreadable_files: 0 }, unavailable: availability.reason };
+      },
+      async status() {
+        return { store: "sqlite", path: dir, exists: false, files: [], total_bytes: 0, rows: 0, counters: await readMetaCounters(dir), unavailable: availability.reason };
+      },
+      async purge() {
+        return { removed_files: 0, removed_bytes: 0, removed_rows: 0, unavailable: availability.reason };
+      },
+    };
+  }
+  const { DatabaseSync } = availability.module;
+  const dbPath = join(dir, "telemetry.sqlite3");
+  let db = null;
+  if (existsSync(dbPath)) {
+    try {
+      db = new DatabaseSync(dbPath);
+    } catch {
+      db = null;
+    }
+  }
+
+  function requireDb() {
+    if (!db) throw new Error("sqlite database not initialized");
+    return db;
+  }
+
+  function buildWhere(f) {
+    const clauses = [];
+    const params = [];
+    if (f.fromMs !== null) {
+      clauses.push("ts >= ?");
+      params.push(new Date(f.fromMs).toISOString());
+    }
+    if (f.toMs !== null) {
+      clauses.push("ts <= ?");
+      params.push(new Date(f.toMs).toISOString());
+    }
+    if (f.profile) {
+      clauses.push("profile = ?");
+      params.push(f.profile);
+    }
+    if (f.model) {
+      clauses.push("(model_name = ? OR model_name = ?)");
+      params.push(f.model, f.model.includes("/") ? f.model.split("/").pop() : f.model);
+    }
+    if (f.tool) {
+      clauses.push("tool_name = ?");
+      params.push(f.tool);
+    }
+    if (f.plugin) {
+      clauses.push("plugin_name = ?");
+      params.push(f.plugin);
+    }
+    if (f.event) {
+      if (f.event.endsWith(".*")) {
+        clauses.push("event LIKE ?");
+        params.push(`${f.event.slice(0, -1)}%`);
+      } else {
+        clauses.push("event = ?");
+        params.push(f.event);
+      }
+    }
+    if (f.errorsOnly) {
+      clauses.push("(event IN ('model.failed','request.cancelled') OR status IN ('failed','timeout','cancelled'))");
+    }
+    if (f.traceId) {
+      clauses.push("trace_id = ?");
+      params.push(f.traceId);
+    }
+    return { where: clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "", params };
+  }
+
+  function columnsFromRow(row) {
+    const event = JSON.parse(row.data);
+    // 列值以库内索引列为准回填缺失的冗余字段（JSON 与列不一致时以 JSON 为准）
+    return event;
+  }
+
+  return {
+    kind: "sqlite",
+    path: dir,
+    available: true,
+    async readEvents(filters = {}) {
+      const f = normalizeFilters(filters);
+      const events = [];
+      const skipped = { invalid: 0, schema_incompatible: 0, unreadable_files: 0 };
+      if (!db) return { events, skipped };
+      try {
+        const { where, params } = buildWhere(f);
+        const stmt = db.prepare(`SELECT data FROM events ${where} ORDER BY ts ASC`);
+        for (const row of stmt.all(...params)) {
+          try {
+            events.push(columnsFromRow(row));
+          } catch {
+            skipped.invalid += 1;
+          }
+        }
+      } catch {
+        /* 查询失败按空集处理 */
+      }
+      return { events, skipped };
+    },
+
+    async status() {
+      let bytes = 0;
+      let rows = 0;
+      try {
+        bytes = (await stat(dbPath)).size;
+      } catch {
+        bytes = 0;
+      }
+      if (db) {
+        try {
+          rows = db.prepare("SELECT COUNT(*) AS n FROM events").get().n;
+        } catch {
+          rows = 0;
+        }
+      }
+      return {
+        store: "sqlite",
+        path: dir,
+        exists: existsSync(dbPath),
+        files: existsSync(dbPath) ? [{ name: "telemetry.sqlite3", bytes }] : [],
+        total_bytes: bytes,
+        rows,
+        counters: await readMetaCounters(dir),
+      };
+    },
+
+    async purge({ olderThanMs = null, beforeMs = null } = {}) {
+      const cutoff = beforeMs ?? (olderThanMs !== null ? Date.now() - olderThanMs : null);
+      if (cutoff === null) throw new TypeError("purge requires olderThanMs or beforeMs");
+      const cutoffDate = new Date(cutoff).toISOString().slice(0, 10);
+      if (!db) return { removed_files: 0, removed_bytes: 0, removed_rows: 0 };
+      try {
+        const count = db.prepare("SELECT COUNT(*) AS n FROM events WHERE date < ?").get(cutoffDate).n;
+        db.prepare("DELETE FROM events WHERE date < ?").run(cutoffDate);
+        return { removed_files: 0, removed_bytes: 0, removed_rows: count };
+      } catch {
+        return { removed_files: 0, removed_bytes: 0, removed_rows: 0 };
+      }
+    },
+
+    close() {
+      try {
+        db?.close();
+      } catch {
+        /* ignore */
+      }
+      db = null;
+    },
+  };
+}
+
+/** 按配置打开存储（读取侧）。 */
+export async function openStore({ store = "jsonl", path } = {}) {
+  if (store === "sqlite") return createSqliteStore({ path });
+  return createJsonlStore({ path });
+}
+
+async function readMetaCounters(dir) {
+  try {
+    if (!existsSync(join(dir, META_FILE))) return emptyCounters();
+    const meta = JSON.parse(await readFile(join(dir, META_FILE), "utf8"));
+    return { ...emptyCounters(), ...(meta?.counters ?? {}) };
+  } catch {
+    return emptyCounters();
+  }
+}
+
+function emptyCounters() {
+  return { written: 0, dropped_queue: 0, dropped_oversize: 0, dropped_invalid: 0, dropped_write: 0, sampled_out: 0 };
+}
+
+/** 删除整个数据目录中的过期文件（JSONL）；SQLite 走其 purge。 */
+export async function removeFile(path) {
+  try {
+    await unlink(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/web/app.js

@@ -0,0 +1,337 @@
+/* dsh-local-telemetry Web UI 逻辑 — 零依赖，只调用本地只读 API。 */
+"use strict";
+
+const state = { range: "24h", traceId: null };
+
+const $ = (sel) => document.querySelector(sel);
+const fmtInt = (v) => (v === null || v === undefined ? "n/a" : Number(v).toLocaleString("en-US"));
+const fmtMs = (v) => (v === null || v === undefined ? "n/a" : v >= 10000 ? `${(v / 1000).toFixed(1)}s` : `${v}ms`);
+const fmtPct = (v) => (v === null || v === undefined ? "n/a" : `${(v * 100).toFixed(1)}%`);
+const fmtCost = (v, currency) => {
+  if (v === null || v === undefined) return "n/a";
+  return `${currency === "USD" ? "$" : currency ? currency + " " : ""}${v.toFixed(4)}`;
+};
+const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+async function api(path) {
+  const res = await fetch(path, { cache: "no-store" });
+  if (!res.ok) throw new Error(`${path}: ${res.status}`);
+  return res.json();
+}
+
+function sinceParam() {
+  return state.range === "all" ? null : state.range;
+}
+
+/* ---------- 状态 chips ---------- */
+function renderChips(status, summary) {
+  const dropped = status.counters ?? {};
+  const droppedTotal = dropped.dropped_write + dropped.dropped_queue + dropped.dropped_oversize + dropped.dropped_invalid + dropped.sampled_out;
+  const chips = [
+    `store <b>${esc(status.store)}</b>`,
+    `events <b>${fmtInt(summary.data_completeness.events)}</b>`,
+    droppedTotal > 0 ? `dropped <b>${fmtInt(droppedTotal)}</b>（累计）` : `dropped <b>0</b>`,
+    status.price_catalog?.path ? `价格目录 <b>${esc(status.price_catalog.currency ?? "")}</b> 生效 ${esc(status.price_catalog.effective_at ?? "n/a")}` : `价格目录 <b>未配置</b>`,
+    `<b>127.0.0.1</b> only`,
+  ];
+  $("#chips").innerHTML = chips.map((c) => `<span class="chip">${c}</span>`).join("");
+}
+
+/* ---------- KPI 卡片 ---------- */
+function renderKpis(s) {
+  const cards = [
+    { label: "Requests", value: fmtInt(s.requests.total), note: `成功 ${fmtPct(s.requests.success_rate)} · 取消 ${fmtInt(s.requests.cancelled)}` },
+    { label: "P95 latency", value: fmtMs(s.requests.latency.p95), note: `p50 ${fmtMs(s.requests.latency.p50)} · n=${s.requests.latency.n}` },
+    { label: "TTFT p95", value: fmtMs(s.requests.ttft.p95), note: `排队 p95 ${fmtMs(s.requests.queue.p95)}` },
+    { label: "Tokens in / out", value: fmtInt(s.tokens.input), note: `输出 ${fmtInt(s.tokens.output)} · 缓存 ${fmtInt(s.tokens.cached)}` },
+    { label: "Estimated cost", value: fmtCost(s.cost.amount, s.cost.currency), note: `估算值，非账单 · ${s.cost.priced_events} 事件已计价` },
+    { label: "Tool / Plugin calls", value: fmtInt(s.data_completeness.tool_calls), note: `插件调用 ${fmtInt(s.data_completeness.plugin_calls)} · 重试 ${fmtInt(s.requests.retries)}` },
+  ];
+  $("#kpis").innerHTML = cards
+    .map(
+      (c) => `<div class="kpi"><div class="label">${c.label}</div><div class="value">${c.value}</div><div class="note">${c.note}</div></div>`
+    )
+    .join("");
+}
+
+/* ---------- 趋势图（面积 + 柱） ---------- */
+function renderTrend(rows) {
+  const wrap = $("#trend");
+  if (!rows || rows.length === 0) {
+    wrap.innerHTML = `<div class="empty">该窗口内暂无数据。</div>`;
+    return;
+  }
+  const data = rows.slice(-31);
+  const W = 640, H = 190, padL = 40, padB = 22, padT = 10;
+  const innerW = W - padL - 8, innerH = H - padB - padT;
+  const maxTok = Math.max(...data.map((d) => d.input_tokens + d.output_tokens), 1);
+  const maxReq = Math.max(...data.map((d) => d.requests), 1);
+  const step = innerW / data.length;
+  const x = (i) => padL + i * step + step / 2;
+  const yTok = (v) => padT + innerH - (v / maxTok) * innerH;
+  const barW = Math.min(step * 0.34, 16);
+
+  let area = `M ${x(0)} ${yTok(data[0].input_tokens + data[0].output_tokens)}`;
+  data.forEach((d, i) => { if (i > 0) area += ` L ${x(i)} ${yTok(d.input_tokens + d.output_tokens)}`; });
+  const areaPath = `${area} L ${x(data.length - 1)} ${padT + innerH} L ${x(0)} ${padT + innerH} Z`;
+
+  const bars = data
+    .map((d, i) => `<rect class="bar-row" data-i="${i}" x="${x(i) - barW / 2}" y="${padT + innerH - (d.requests / maxReq) * innerH}" width="${barW}" height="${Math.max((d.requests / maxReq) * innerH, d.requests > 0 ? 2 : 0)}" rx="3" fill="rgba(139,92,246,0.35)"></rect>`)
+    .join("");
+  const labels = data
+    .map((d, i) => (data.length <= 10 || i % Math.ceil(data.length / 10) === 0 ? `<text x="${x(i)}" y="${H - 6}" fill="#71717a" font-size="10" text-anchor="middle">${esc(String(d.group).slice(5))}</text>` : ""))
+    .join("");
+  const gridY = [0.25, 0.5, 0.75, 1]
+    .map((f) => `<line x1="${padL}" y1="${padT + innerH * f}" x2="${W - 8}" y2="${padT + innerH * f}" stroke="#1c1c22" stroke-width="1"></line><text x="${padL - 6}" y="${padT + innerH * f + 3}" fill="#5b5b64" font-size="9.5" text-anchor="end">${compact(maxTok * (1 - f))}</text>`)
+    .join("");
+
+  wrap.innerHTML = `
+  <svg viewBox="0 0 ${W} ${H}" preserveAspectRatio="none" style="height:190px">
+    <defs>
+      <linearGradient id="areaFill" x1="0" y1="0" x2="0" y2="1">
+        <stop offset="0%" stop-color="rgba(6,182,212,0.45)"></stop>
+        <stop offset="100%" stop-color="rgba(6,182,212,0.02)"></stop>
+      </linearGradient>
+      <linearGradient id="lineStroke" x1="0" y1="0" x2="1" y2="0">
+        <stop offset="0%" stop-color="#8b5cf6"></stop><stop offset="100%" stop-color="#06b6d4"></stop>
+      </linearGradient>
+    </defs>
+    ${gridY}
+    ${bars}
+    <path d="${areaPath}" fill="url(#areaFill)"></path>
+    <path d="${area.replace("M", "M")}" fill="none" stroke="url(#lineStroke)" stroke-width="2"></path>
+    ${labels}
+  </svg>`;
+
+  const tip = $("#trend-tip");
+  wrap.querySelectorAll(".bar-row").forEach((el) => {
+    el.addEventListener("mousemove", (ev) => {
+      const d = data[Number(el.dataset.i)];
+      tip.style.display = "block";
+      tip.style.left = `${ev.clientX + 12}px`;
+      tip.style.top = `${ev.clientY + 12}px`;
+      tip.innerHTML = `<div class="t">${esc(d.group)}</div>requests <b>${d.requests}</b> · err <b>${d.failed}</b><br>tokens in <b>${fmtInt(d.input_tokens)}</b> / out <b>${fmtInt(d.output_tokens)}</b><br>cost <b>${fmtCost(d.cost)}</b> · p95 <b>${fmtMs(d.p95_ms)}</b>`;
+    });
+    el.addEventListener("mouseleave", () => { tip.style.display = "none"; });
+  });
+}
+
+function compact(v) {
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1000) return `${(v / 1000).toFixed(1)}k`;
+  return String(Math.round(v));
+}
+
+/* ---------- 错误分类 ---------- */
+function renderErrors(s) {
+  const entries = Object.entries(s.errors.kinds);
+  if (entries.length === 0) {
+    $("#errors").innerHTML = `<div class="empty">窗口内无错误事件。</div>`;
+    return;
+  }
+  const total = entries.reduce((acc, [, n]) => acc + n, 0);
+  $("#errors").innerHTML = entries
+    .sort((a, b) => b[1] - a[1])
+    .map(([kind, n]) => {
+      const pct = total > 0 ? n / total : 0;
+      return `<div style="margin-bottom:10px">
+        <div style="display:flex;justify-content:space-between;font-size:12.5px"><span>${esc(kind)}</span><span style="color:var(--muted)">${n} · ${fmtPct(pct)}</span></div>
+        <div class="lat-bar" style="margin-top:4px"><i style="width:${Math.round(pct * 100)}%"></i></div>
+      </div>`;
+    })
+    .join("");
+}
+
+/* ---------- 表格 ---------- */
+function renderModels(models) {
+  if (!models || models.length === 0) {
+    $("#models").innerHTML = `<div class="empty">窗口内无模型调用。</div>`;
+    return;
+  }
+  const maxP95 = Math.max(...models.map((m) => m.latency.p95 ?? 0), 1);
+  $("#models").innerHTML = `<table><thead><tr>
+    <th>provider / model</th><th>type</th><th class="num">attempts</th><th class="num">成功率</th>
+    <th class="num">p50</th><th class="num">p95</th><th class="num">p99</th><th>延迟分布</th>
+    <th class="num">TTFT p95</th><th class="num">in tok</th><th class="num">out tok</th><th class="num">缓存</th><th class="num">估算成本</th>
+  </tr></thead><tbody>
+    ${models
+      .map(
+        (m) => `<tr>
+      <td class="name">${esc(m.provider ?? "?")} / ${esc(m.name ?? "?")}</td>
+      <td>${esc(m.request_type ?? "?")}</td>
+      <td class="num">${m.attempts}${m.retries > 0 ? ` <span style="color:var(--warn)" title="重试">↻${m.retries}</span>` : ""}</td>
+      <td class="num">${fmtPct(m.success_rate)}</td>
+      <td class="num">${fmtMs(m.latency.p50)}</td>
+      <td class="num">${fmtMs(m.latency.p95)}</td>
+      <td class="num">${fmtMs(m.latency.p99)}</td>
+      <td><div class="lat-bar"><i style="width:${Math.round(((m.latency.p95 ?? 0) / maxP95) * 100)}%"></i></div></td>
+      <td class="num">${fmtMs(m.ttft.p95)}</td>
+      <td class="num">${fmtInt(m.tokens.input)}</td>
+      <td class="num">${fmtInt(m.tokens.output)}</td>
+      <td class="num">${fmtInt(m.tokens.cached)}</td>
+      <td class="num">${fmtCost(m.cost.amount, null)}</td>
+    </tr>`
+      )
+      .join("")}
+  </tbody></table>`;
+}
+
+function renderTools(tools, hints) {
+  if (!tools || tools.length === 0) {
+    $("#tools").innerHTML = `<div class="empty">窗口内无工具调用。</div>`;
+    return;
+  }
+  const hintByTool = {};
+  (hints ?? []).forEach((h) => { hintByTool[h.tool] = h; });
+  const maxP95 = Math.max(...tools.map((t) => t.latency.p95 ?? 0), 1);
+  $("#tools").innerHTML = `<table><thead><tr>
+      <th>工具</th><th class="num">调用</th><th class="num">成功</th><th class="num">失败</th><th class="num">超时</th>
+      <th class="num">p50</th><th class="num">p95</th><th>耗时分布</th><th class="num">需确认</th>
+    </tr></thead><tbody>
+    ${tools
+      .map((t) => {
+        const hint = hintByTool[t.name];
+        const loop = hint ? ` <span style="color:var(--warn)" title="同 trace 内 ${hint.calls} 次调用（疑似循环）">⟲</span>` : "";
+        return `<tr>
+        <td class="name">${esc(t.name)}${loop}</td>
+        <td class="num">${t.calls}</td><td class="num">${t.success}</td><td class="num">${t.failed}</td><td class="num">${t.timeout}</td>
+        <td class="num">${fmtMs(t.latency.p50)}</td><td class="num">${fmtMs(t.latency.p95)}</td>
+        <td><div class="lat-bar"><i style="width:${Math.round(((t.latency.p95 ?? 0) / maxP95) * 100)}%"></i></div></td>
+        <td class="num">${t.confirm_required || ""}</td>
+      </tr>`;
+      })
+      .join("")}
+  </tbody></table>`;
+}
+
+function renderPlugins(plugins) {
+  if (!plugins || plugins.length === 0) {
+    $("#plugins").innerHTML = `<div class="empty">窗口内无插件调用。</div>`;
+    return;
+  }
+  $("#plugins").innerHTML = `<table><thead><tr><th>插件</th><th>hook</th><th class="num">调用</th><th class="num">错误</th><th class="num">p95</th></tr></thead><tbody>
+    ${plugins
+      .map((p) => {
+        const hooks = Object.entries(p.hooks);
+        if (hooks.length === 0) {
+          return `<tr><td class="name">${esc(p.name)}</td><td>-</td><td class="num">-</td><td class="num">${p.errors}</td><td class="num">${fmtMs(p.latency.p95)}</td></tr>`;
+        }
+        return hooks
+          .map(
+            ([hook, data], i) =>
+              `<tr>${i === 0 ? `<td class="name" rowspan="${hooks.length}">${esc(p.name)}</td>` : ""}<td>${esc(hook)}</td><td class="num">${data.calls}</td><td class="num">${data.errors}</td><td class="num">${fmtMs(data.latency.p95)}</td></tr>`
+          )
+          .join("");
+      })
+      .join("")}
+  </tbody></table>`;
+}
+
+/* ---------- 请求时间线 + trace ---------- */
+function renderRequests(requests) {
+  const el = $("#requests");
+  if (!requests || requests.length === 0) {
+    el.innerHTML = `<div class="empty">窗口内无请求。</div>`;
+    return;
+  }
+  el.innerHTML = requests
+    .map(
+      (r) => `<div class="req${r.trace_id === state.traceId ? " active" : ""}" data-trace="${esc(r.trace_id)}">
+      <span class="dot ${esc(r.status)}" title="${esc(r.status)}"></span>
+      <span class="t">${esc((r.started_at ?? "").replace("T", " ").slice(0, 19))}</span>
+      <span class="dur">${fmtMs(r.duration_ms)}</span>
+      <span class="model">${esc(r.model ?? "—")}${r.retries > 0 ? ` <span style="color:var(--warn)">↻${r.retries}</span>` : ""}${r.tool_calls > 0 ? ` <span style="color:var(--muted)">· ${r.tool_calls} tools</span>` : ""}</span>
+      <span class="tok">${fmtInt(r.tokens.input)}/${fmtInt(r.tokens.output)}</span>
+    </div>`
+    )
+    .join("");
+  el.querySelectorAll(".req").forEach((node) => {
+    node.addEventListener("click", () => {
+      state.traceId = node.dataset.trace;
+      el.querySelectorAll(".req").forEach((n) => n.classList.remove("active"));
+      node.classList.add("active");
+      loadTrace(state.traceId);
+    });
+  });
+}
+
+function renderTrace(view) {
+  $("#trace-title").textContent = view.trace_id ? `· ${view.trace_id}` : "";
+  const el = $("#trace");
+  const renderNode = (node, depth) => {
+    const head = node.events[0] ?? {};
+    const who = head.tool ?? head.plugin ?? head.model ?? "";
+    const end = [...node.events].reverse().find((e) => Number.isInteger(e.duration_ms));
+    const status = node.events.map((e) => e.status).find(Boolean);
+    const ms = end ? end.duration_ms : null;
+    const hook = head.hook ? `:${head.hook}` : "";
+    let html = `<div class="span-row" style="margin-left:${depth * 0}px">
+      <span class="ev">${esc(head.event ?? "")}</span>
+      ${who ? `<span class="who">${esc(who)}${esc(hook)}</span>` : ""}
+      ${status ? `<span class="st ${esc(status)}">${esc(status)}</span>` : ""}
+      ${ms !== null && ms !== undefined ? `<span class="ms">${fmtMs(ms)}</span>` : ""}
+    </div>`;
+    if (node.children && node.children.length > 0) {
+      html += `<div class="span-children">${node.children.map((c) => renderNode(c, depth + 1)).join("")}</div>`;
+    }
+    return html;
+  };
+  const treeHtml = view.tree.roots.map((r) => renderNode(r, 0)).join("");
+  const timelineHtml = view.timeline
+    .slice(0, 60)
+    .map(
+      (e) => `<div class="span-row"><span class="ev">${esc(e.event)}</span>
+      ${e.tool ?? e.plugin ?? e.model ? `<span class="who">${esc(e.tool ?? e.plugin ?? e.model ?? "")}</span>` : ""}
+      ${e.status ? `<span class="st ${esc(e.status)}">${esc(e.status)}</span>` : ""}
+      ${e.error ? `<span class="st failed">${esc(e.error)}</span>` : ""}
+      ${e.duration_ms !== null ? `<span class="ms">${fmtMs(e.duration_ms)}</span>` : ""}</div>`
+    )
+    .join("");
+  el.innerHTML = `${treeHtml}<div class="desc" style="margin:12px 0 4px">时间线（最近 ${Math.min(view.timeline.length, 60)} / ${view.timeline.length} 事件）</div>${timelineHtml}`;
+}
+
+async function loadTrace(traceId) {
+  try {
+    const view = await api(`/api/trace/${encodeURIComponent(traceId)}`);
+    renderTrace(view);
+  } catch {
+    $("#trace").innerHTML = `<div class="empty">trace 事件未找到（可能被采样或清理）。</div>`;
+  }
+}
+
+/* ---------- 主刷新 ---------- */
+async function refresh() {
+  const since = sinceParam();
+  const qs = since ? `since=${encodeURIComponent(since)}` : "";
+  const [status, summary, grouped, requests] = await Promise.all([
+    api("/api/status"),
+    api(`/api/summary?${qs}`),
+    api(`/api/grouped?by=day&${qs}`),
+    api(`/api/requests?limit=60&${qs}`),
+  ]);
+  renderChips(status, summary);
+  renderKpis(summary);
+  renderTrend(grouped.rows);
+  renderErrors(summary);
+  renderModels(summary.models);
+  renderTools(summary.tools, summary.tool_loop_hints);
+  renderPlugins(summary.plugins);
+  renderRequests(requests.requests);
+  if (state.traceId) await loadTrace(state.traceId);
+}
+
+document.querySelectorAll("#ranges button").forEach((btn) => {
+  btn.addEventListener("click", () => {
+    document.querySelectorAll("#ranges button").forEach((b) => b.classList.remove("active"));
+    btn.classList.add("active");
+    state.range = btn.dataset.range;
+    refresh().catch(showError);
+  });
+});
+$("#refresh").addEventListener("click", () => refresh().catch(showError));
+
+function showError(error) {
+  $("#chips").innerHTML = `<span class="chip bad">加载失败：${esc(error.message)}（请确认服务运行在本地存储上）</span>`;
+}
+
+refresh().catch(showError);