cortico 0.1.0

package/src/web/client/features/usage/strings.ts

@@ -0,0 +1,191 @@
+import { pick } from '../../core/language.ts';
+
+const zh = {
+  // index.ts
+  navLabel: '用量与成本',
+  navGroup: 'Core',
+  pageTitle: '用量与成本',
+  bucketAuto: '自动',
+  bucketMinute: '分',
+  bucketHour: '时',
+  bucketDay: '天',
+  bucketWeek: '周',
+  bucketMonth: '月',
+  presetToday: '今天',
+  preset3: '近 3 天',
+  preset7: '近 7 天',
+  preset30: '近 30 天',
+  preset90: '近 90 天',
+  presetCustom: '自定义',
+  metricCost: '成本',
+  liveRefresh: '自动刷新',
+  liveRefreshTitle: (sec: number) => `每 ${sec} 秒重取一次；离开本页自动停`,
+  refresh: '刷新',
+  granularity: '粒度',
+  autoCurrency: '自动币种',
+  basisMarginal: '边际费用',
+  basisEquivalent: '等价 API 成本',
+  ledger: '账本',
+  compTitle: '成本构成',
+  mainTitle: '用量时间序列',
+  mainDesc: "可组合类型、角色与模型进行拆分。",
+  split: '拆分',
+  dimType: '类型',
+  dimRole: '角色',
+  dimModel: '模型',
+  sortByShare: '占比排序',
+  sortByShareTitle: '按各部分占比从大到小堆叠',
+  callTitle: 'API 调用次数',
+  headCalls: '调用',
+  headInput: '输入 tok',
+  headOutput: '输出 tok',
+  headCache: '缓存命中',
+  headCost: '成本',
+  headAvg: '均价',
+  byRole: '按角色',
+  byModel: '按模型',
+  cardKnownCost: '已知费用小计',
+  unknown: '未知',
+  cardCalls: '调用次数',
+  cardAvgCost: '成功均价 / 次',
+  approxTok: (tok: string) => `≈ ${tok} tok`,
+  cardInput: '输入 token',
+  hitRate: (pct: string) => `命中率 ${pct}`,
+  cardOutput: '输出 token',
+  reasoningShare: (pct: string) => `思维链 ${pct}`,
+  cardCacheRate: '缓存命中率',
+  cardCoverage: '报价覆盖',
+  unpriced: (n: number) => `${n} 次在当前账本未完整计价`,
+  cardPeak: '峰值',
+  cardFailed: '失败流',
+  failedCalls: (n: string) => `${n} 次`,
+  burned: (tok: string) => `消耗 ≈ ${tok} tok`,
+  noCostData: '暂无成本数据',
+  partCacheHit: '命中缓存输入',
+  partCacheMiss: '未命中输入',
+  partOutput: '输出',
+  partOther: '其他费用',
+  noData: '无数据',
+  autoBucket: (label: string) => `自动 → 按${label}`,
+  rangeHint: (from: string, to: string, buckets: number) => `${from} ~ ${to} · ${buckets} 桶`,
+  billingHint: '按请求时的报价快照统计。' +
+    '总量包含失败、抢占与诊断请求；币种和费用口径分别汇总。',
+  unknownUsage: (n: number) => ` ${n} 次请求的用量或缓存分布不完整。`,
+  ledgerError: (pending: number, error: string) => ` 账目存储异常，${pending} 条待写入：${error}`,
+  loadFailed: (msg: string) => '用量加载失败: ' + msg,
+  loading: '加载中…',
+
+  // chart.ts
+  total: '合计',
+  totalPrefix: '合计 ',
+  callsUnit: ' 次',
+  weekShort: (s: string) => s + '周',
+  weekFull: (bucket: string) => bucket + ' 起 · 周',
+  monthFull: (bucket: string) => bucket + ' · 月',
+  restOmitted: '… 其余从略',
+  tipFoot: (calls: number, hitRate: string, reasoning: string) =>
+    `调用 ${calls} · 命中率 ${hitRate} · 思维链 ${reasoning}`,
+  noCalls: '这个范围内没有调用记录',
+
+  // labels.ts
+  typeCacheHit: '命中缓存',
+  typeCacheMiss: '未命中输入',
+  typeOutput: '输出',
+  typeOther: '其他费用 / 未分布输入',
+};
+
+const en: typeof zh = {
+  // index.ts
+  navLabel: 'Usage & cost',
+  navGroup: 'Core',
+  pageTitle: 'Usage & cost',
+  bucketAuto: 'Auto',
+  bucketMinute: 'Minute',
+  bucketHour: 'Hour',
+  bucketDay: 'Day',
+  bucketWeek: 'Week',
+  bucketMonth: 'Month',
+  presetToday: 'Today',
+  preset3: 'Last 3 days',
+  preset7: 'Last 7 days',
+  preset30: 'Last 30 days',
+  preset90: 'Last 90 days',
+  presetCustom: 'Custom',
+  metricCost: 'Cost',
+  liveRefresh: 'Auto refresh',
+  liveRefreshTitle: (sec: number) => `Refetches every ${sec} s; stops when you leave this page`,
+  refresh: 'Refresh',
+  granularity: 'Granularity',
+  autoCurrency: 'Auto currency',
+  basisMarginal: 'Marginal cost',
+  basisEquivalent: 'Equivalent API cost',
+  ledger: 'Ledger',
+  compTitle: 'Cost breakdown',
+  mainTitle: 'Usage time series',
+  mainDesc: "Combine type, role and model dimensions.",
+  split: 'Split',
+  dimType: 'Type',
+  dimRole: 'Role',
+  dimModel: 'Model',
+  sortByShare: 'Sort by share',
+  sortByShareTitle: 'Stack parts from largest share to smallest',
+  callTitle: 'API calls',
+  headCalls: 'Calls',
+  headInput: 'Input tok',
+  headOutput: 'Output tok',
+  headCache: 'Cache hit',
+  headCost: 'Cost',
+  headAvg: 'Avg price',
+  byRole: 'By role',
+  byModel: 'By model',
+  cardKnownCost: 'Known cost subtotal',
+  unknown: 'unknown',
+  cardCalls: 'Calls',
+  cardAvgCost: 'Avg per successful call',
+  approxTok: (tok: string) => `≈ ${tok} tok`,
+  cardInput: 'Input tokens',
+  hitRate: (pct: string) => `hit rate ${pct}`,
+  cardOutput: 'Output tokens',
+  reasoningShare: (pct: string) => `reasoning ${pct}`,
+  cardCacheRate: 'Cache hit rate',
+  cardCoverage: 'Price coverage',
+  unpriced: (n: number) => `${n} calls not fully priced in the current ledger`,
+  cardPeak: 'Peak',
+  cardFailed: 'Failed calls',
+  failedCalls: (n: string) => `${n} calls`,
+  burned: (tok: string) => `used ≈ ${tok} tok`,
+  noCostData: 'No cost data yet',
+  partCacheHit: 'Cached input',
+  partCacheMiss: 'Uncached input',
+  partOutput: 'Output',
+  partOther: 'Other charges',
+  noData: 'No data',
+  autoBucket: (label: string) => `Auto → by ${label}`,
+  rangeHint: (from: string, to: string, buckets: number) => `${from} ~ ${to} · ${buckets} buckets`,
+  billingHint: 'Computed from the price snapshot at request time. ' +
+    'Totals include failed, preempted and diagnostic requests; currencies and cost bases are summed separately.',
+  unknownUsage: (n: number) => ` ${n} requests have an incomplete usage or cache breakdown.`,
+  ledgerError: (pending: number, error: string) => ` Ledger storage error, ${pending} entries pending: ${error}`,
+  loadFailed: (msg: string) => 'Failed to load usage: ' + msg,
+  loading: 'Loading…',
+
+  // chart.ts
+  total: 'Total',
+  totalPrefix: 'Total ',
+  callsUnit: ' calls',
+  weekShort: (s: string) => s + ' wk',
+  weekFull: (bucket: string) => bucket + ' · week',
+  monthFull: (bucket: string) => bucket + ' · month',
+  restOmitted: '… rest omitted',
+  tipFoot: (calls: number, hitRate: string, reasoning: string) =>
+    `calls ${calls} · hit rate ${hitRate} · reasoning ${reasoning}`,
+  noCalls: 'No calls recorded in this range',
+
+  // labels.ts
+  typeCacheHit: 'Cached',
+  typeCacheMiss: 'Uncached input',
+  typeOutput: 'Output',
+  typeOther: 'Other charges / unclassified input',
+};
+
+export const S = pick({ zh, en });

package/src/web/client/features/usage/tooltip.ts

@@ -0,0 +1,86 @@
+/**
+ * 随鼠标移动的 tooltip 与当前色块高亮。tooltip 位于本页 root，使用 fixed 定位并随卸载移除。
+ * 移出色块、重画图表与卸载统一通过 setHi/clearHi 更新高亮，避免残留描边。
+ */
+
+import type { Disposable } from '../../../shared/client-panel.ts';
+
+/** 鼠标与浮层之间留的空隙，也是碰到视口边缘时翻转的余量。 */
+const TIP_PAD = 14;
+/** 贴边时离视口边缘至少留这么多。 */
+const TIP_EDGE = 8;
+
+export interface UsageTip extends Disposable {
+  /** 浮层节点本身（`.u-tip`）。 */
+  readonly el: HTMLElement;
+  /**
+   * 显示一段正文。`key` 相同就**不重写 innerHTML**——鼠标在同一个段里移动会每帧
+   * 触发一次，重写等于每帧重建一棵子树（也会打断文本选取）。
+   */
+  show(html: string, key: string): void;
+  /** 跟着鼠标走，碰到视口边缘翻到另一侧。 */
+  move(ev: { clientX: number; clientY: number }): void;
+  /** 收起，并顺手清掉高亮。 */
+  hide(): void;
+  setHi(rect: Element): void;
+  clearHi(): void;
+}
+
+/** host 通常为 feature 的 root。HTML 来自 uTipHtml，所有外部文本必须经过 escaping。 */
+export function createUsageTip(doc: Document, host: HTMLElement): UsageTip {
+  const el = doc.createElement('div');
+  el.className = 'u-tip viewport-overlay hidden';
+  host.appendChild(el);
+  let hi: Element | null = null;
+  let curKey: string | undefined;
+  let disposed = false;
+
+  const clearHi = (): void => {
+    if (hi) {
+      hi.classList.remove('seghi');
+      hi = null;
+    }
+  };
+
+  return {
+    el,
+    show(html, key) {
+      if (disposed) return;
+      if (curKey !== key) {
+        el.innerHTML = html;
+        curKey = key;
+      }
+      el.classList.remove('hidden');
+    },
+    move(ev) {
+      if (disposed) return;
+      const view = doc.defaultView;
+      const r = el.getBoundingClientRect();
+      let x = ev.clientX + TIP_PAD;
+      let y = ev.clientY + TIP_PAD;
+      const vw = view?.innerWidth ?? 0;
+      const vh = view?.innerHeight ?? 0;
+      if (vw && x + r.width > vw - TIP_EDGE) x = ev.clientX - r.width - TIP_PAD;
+      if (vh && y + r.height > vh - TIP_EDGE) y = ev.clientY - r.height - TIP_PAD;
+      el.style.left = Math.max(4, x) + 'px';
+      el.style.top = Math.max(4, y) + 'px';
+    },
+    hide() {
+      el.classList.add('hidden');
+      clearHi();
+    },
+    setHi(rect) {
+      if (hi === rect) return;
+      clearHi();
+      rect.classList.add('seghi');
+      hi = rect;
+    },
+    clearHi,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearHi();
+      el.remove();
+    },
+  };
+}

package/src/web/client/features/usage/types.ts

@@ -0,0 +1,96 @@
+/**
+ * /api/usage 的线上 JSON 形状。usage 未挂载时允许空 series、null totals 和缺失字段，因此与服务端聚合器内部必填类型分开定义；数值由 uMetricVal/uTypeVal 集中归一。
+ */
+
+/** 一个累计单元：总量 + 成本三档拆分。桶点、子拆分、分组合计共用此形。 */
+export interface UsageAccum {
+  calls?: number;
+  promptTokens?: number;
+  completionTokens?: number;
+  cacheHitTokens?: number;
+  cacheMissTokens?: number;
+  reasoningTokens?: number;
+  cost?: number;
+  costCacheHit?: number;
+  costCacheMiss?: number;
+  costOutput?: number;
+  costOther?: number;
+  unclassifiedInputTokens?: number;
+  pricedCalls?: number;
+  unpricedCalls?: number;
+  unknownUsageCalls?: number;
+}
+
+/** 时间序列上的一个桶。三张子拆分表是"任意维度交叉堆叠"的寻址面。 */
+export interface UsagePoint extends UsageAccum {
+  /** 本地时区前缀，如 `2026-07-19T14:30` / `2026-07-19` / `2026-07` */
+  bucket: string;
+  byRole?: Record<string, UsageAccum>;
+  byModel?: Record<string, UsageAccum>;
+  /** `byRoleModel[role][model]`：角色×模型的交叉格 */
+  byRoleModel?: Record<string, Record<string, UsageAccum>>;
+}
+
+/**
+ * 按 role / model 分组的合计。
+ *
+ * `key` 是不透明 id（角色 id 由Persona定义，模型名由供应商定义），
+ * `label` 是**声明方随数据给的人话名**。控制台不为任何一个 id 备一张中文名表——
+ * 备了就等于把某个具体 bot 的角色集写进了框架。给不出 label 时原样显示 `key`。
+ */
+export interface UsageGroupStat extends UsageAccum {
+  key: string;
+  /** 声明方给的显示名；缺省时用 `key`。 */
+  label?: string;
+  cacheHitRate?: number | null;
+}
+
+/** 已解析的具体粒度。 */
+export type UsageBucketUnit = 'minute' | 'hour' | 'day' | 'week' | 'month';
+/** 请求粒度：具体粒度或 `auto`（按跨度自适应）。 */
+export type UsageBucketOption = UsageBucketUnit | 'auto';
+
+export interface UsageAggregate {
+  ledger?: { pending: number; error: string | null };
+  currency?: string;
+  basis?: 'marginal' | 'equivalent';
+  balances?: Array<{ currency: string; basis: 'marginal' | 'equivalent'; knownAmount: number; pricedCalls: number; partialCalls: number }>;
+  successful?: UsageAccum;
+  bucket?: UsageBucketUnit;
+  from?: string | null;
+  to?: string | null;
+  series?: UsagePoint[];
+  /** `usage` 未挂载时为 null。 */
+  totals?: UsageGroupStat | null;
+  byRole?: UsageGroupStat[];
+  byModel?: UsageGroupStat[];
+  /** 失败、丢弃和中断均计入 totals；此字段用于核对失败消耗。 */
+  failed?: UsageAccum;
+}
+
+/** 图上纵轴画的是什么。`calls` 只出现在下面那张调用图。 */
+export type UsageMetric = 'cost' | 'tokens' | 'calls';
+
+/** 可拆分的三个维度。优先级（嵌套序）恒为 类型 > 角色 > 模型。 */
+export type UsageDim = 'type' | 'role' | 'model';
+
+/** 成本/token 的三档分量。与 `U_TYPES` 的 key 对应。 */
+export type UsageTypeKey = 'cacheHit' | 'cacheMiss' | 'output' | 'other';
+
+/** 一段组合里的一格：某个维度取了某个键。 */
+export interface UsageCompPart {
+  dim: UsageDim;
+  key: string;
+}
+
+/**
+ * 一个堆叠段的身份 = 各维度取值的笛卡尔积中的一项。
+ * 空数组表示"不拆分"（整根柱子就是合计）。
+ */
+export type UsageComposite = UsageCompPart[];
+
+/** 拆分维度的勾选状态。调用图没有 `type` 档，所以逐个可选。 */
+export type UsageDimFlags = Partial<Record<UsageDim, boolean>>;
+
+/** 颜色解析器：把主题 token（`chart-1` / `chart-hit`）解析成一个具体颜色。 */
+export type ColorResolver = (token: string) => string;