dsh-plugin-usage-stats 0.4.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "dsh-plugin-usage-stats",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "DSH (DeepSeek Harness) Web GUI plugin: global model token usage stats as a dedicated \"Token 用量\" page in Settings — incremental session-file scanning with a persistent fold cache, date-range picker with presets, model/provider filters, per-day and per-model breakdowns, cache hit rate, and optional cost via a configurable price table. Per-session stats are built into the host; read-only.",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "dsh-plugin",
+    "usage",
+    "statistics",
+    "tokens",
+    "cache-hit-rate"
+  ],
+  "license": "MIT",
+  "author": "ksxh0524",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ksxh0524/dsh-plugin-usage-stats.git"
+  },
+  "main": "src/cordis.ts",
+  "exports": {
+    ".": "./src/cordis.ts",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "tests",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.2",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@types/node": "^24.2.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.10",
+    "prettier": "^3.8.4",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "test": "node --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "pnpm format:check && pnpm typecheck && pnpm test"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,mjs,cjs,json,jsonc,md,yml,yaml,html}": "prettier --write"
+  },
+  "packageManager": "pnpm@11.5.3"
+}

package/src/aggregate.ts

@@ -0,0 +1,175 @@
+/** 聚合层：增量扫描调度（状态经 store.ts 持久化）+ 全局总计（四路 token / 命中率 / byModel），
+ *  overview 支持 model/provider 过滤（fact 层先过滤再聚合，与时间过滤同构）。
+ *  所有导出结构保持 JSON-safe，直接作为 Remote 返回值。宿主自带会话统计（轮/步/tok·s/缓存），
+ *  本包只做全局视角；v4 起 UI 不再展示消息数/按天/费用，对应 API 字段同步移除（不留死契约）。 */
+import { stat } from "node:fs/promises";
+import { listSessionFiles, type Fold, type UsageFact } from "./scanner.ts";
+import { FoldStore } from "./store.ts";
+
+export interface ScanResult {
+  folds: Fold[];
+  files: number;
+  reloaded: number;
+}
+
+/** 扫描全部会话：未变文件复用持久行（0 解压），追加文件只解新增帧，其余整文件重解；
+ *  每文件之间让出事件循环，避免首扫长时间占用宿主。 */
+export async function scanFolds(root: string, store: FoldStore): Promise<ScanResult> {
+  await store.load();
+  const files = await listSessionFiles(root);
+  let reloaded = 0;
+  const folds: Fold[] = [];
+  const alive = new Set<string>();
+  for (const file of files) {
+    let s;
+    try {
+      s = await stat(file);
+    } catch {
+      continue;
+    }
+    alive.add(file);
+    const before = store.rows.get(file);
+    try {
+      folds.push(await store.foldFor(file, { size: s.size, mtimeMs: s.mtimeMs, ino: s.ino }));
+    } catch {
+      folds.push({ facts: [], meta: null });
+    }
+    const after = store.rows.get(file);
+    if (after && (!before || before.size !== after.size || before.bytes !== after.bytes)) reloaded++;
+    await new Promise((r) => setImmediate(r));
+  }
+  await store.flush(alive);
+  return { folds, files: files.length, reloaded };
+}
+
+export interface Range {
+  from?: string;
+  to?: string;
+  /** 精确模型匹配（"provider/model" 全键或裸 model 键）。 */
+  model?: string;
+  /** 服务商前缀匹配（"provider/" 之前的字段）。 */
+  provider?: string;
+}
+
+export function normalizeRange(raw: unknown): Range {
+  const r = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+  const out: Range = {};
+  const ok = (v: unknown) => typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v);
+  if (ok(r.from)) out.from = String(r.from);
+  if (ok(r.to)) out.to = String(r.to);
+  if (out.from && out.to && out.from > out.to) {
+    const t = out.from;
+    out.from = out.to;
+    out.to = t;
+  }
+  if (typeof r.model === "string" && r.model.trim()) out.model = r.model.trim();
+  if (typeof r.provider === "string" && r.provider.trim()) out.provider = r.provider.trim();
+  return out;
+}
+
+function inRange(date: string, range: Range): boolean {
+  if (range.from && date < range.from) return false;
+  if (range.to && date > range.to) return false;
+  return true;
+}
+
+/** 模型/服务商过滤在 fact 层生效（全键 "prov/model" 精确，裸 model 兜底；provider 全等段匹配）。 */
+function matchesDims(f: UsageFact, range: Range): boolean {
+  if (range.provider && f.provider !== range.provider) return false;
+  if (range.model && f.model !== range.model && `${f.provider}/${f.model}` !== range.model) return false;
+  return true;
+}
+
+function collectFacts(folds: Fold[], range: Range): { facts: UsageFact[]; metaById: Map<string, Fold["meta"]> } {
+  const facts: UsageFact[] = [];
+  const metaById = new Map<string, Fold["meta"]>();
+  const noDim = !range.model && !range.provider;
+  for (const fold of folds) {
+    for (const f of fold.facts) {
+      if (!inRange(f.date, range)) continue;
+      if (noDim) {
+        facts.push(f);
+        if (fold.meta && !metaById.has(f.sessionId)) metaById.set(f.sessionId, fold.meta);
+      } else if (matchesDims(f, range)) {
+        facts.push(f);
+        // 维度过滤后，消息计数只统计「命中维度」的会话（否则口径与过滤后 totals 不一致）。
+        if (fold.meta && !metaById.has(f.sessionId)) metaById.set(f.sessionId, null);
+      }
+    }
+  }
+  return { facts, metaById };
+}
+
+export interface Totals {
+  requests: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+  /** 窗口内是否有任一 usage 样本上报过缓存字段（未上报 → 命中率无口径，显示“—”）。 */
+  reportsCache: boolean;
+}
+
+export function emptyTotals(): Totals {
+  return { requests: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, reportsCache: false };
+}
+
+function add(t: Totals, f: UsageFact): void {
+  t.requests += 1;
+  t.input += f.input;
+  t.output += f.output;
+  t.cacheRead += f.cacheRead;
+  t.cacheWrite += f.cacheWrite;
+  t.total += f.input + f.output + f.cacheRead + f.cacheWrite;
+  if (f.hasCache) t.reportsCache = true;
+}
+
+/** 命中率 = cacheRead / (cacheRead + 未缓存输入)；缓存字段未上报的口径返回 null（UI 显示“—”）。 */
+export function hitRate(t: Totals): number | null {
+  if (!t.reportsCache) return null;
+  const denom = t.cacheRead + t.input;
+  if (denom <= 0) return null;
+  return t.cacheRead / denom;
+}
+
+export interface ModelRow extends Totals {
+  provider: string;
+  model: string;
+  key: string;
+  hitRate: number | null;
+}
+
+export interface Overview {
+  totals: Totals;
+  hitRate: number | null;
+  byModel: ModelRow[];
+  sessionCount: number;
+  scannedFiles: number;
+  generatedAt: number;
+}
+
+export function buildOverview(folds: Fold[], range: Range): Overview {
+  const { facts, metaById } = collectFacts(folds, range);
+  const totals = emptyTotals();
+  const modelRows = new Map<string, ModelRow>();
+  for (const f of facts) {
+    add(totals, f);
+    const key = `${f.provider}/${f.model}`;
+    let m = modelRows.get(key);
+    if (!m) {
+      m = { ...emptyTotals(), provider: f.provider, model: f.model, key, hitRate: null };
+      modelRows.set(key, m);
+    }
+    add(m, f);
+  }
+  const byModel = [...modelRows.values()].map((m) => ({ ...m, hitRate: hitRate(m) })).sort((a, b) => b.total - a.total);
+  return {
+    totals,
+    hitRate: hitRate(totals),
+    byModel,
+    sessionCount: metaById.size || new Set(facts.map((f) => f.sessionId)).size,
+    scannedFiles: folds.length,
+    generatedAt: Date.now(),
+  };
+}

package/src/cordis.ts

@@ -0,0 +1,72 @@
+/** Cordis 入口：注册 `usageStats` 服务（Typert Gateway 只读 Remote：overview 单方法）。
+ *  会话级视图宿主自带（底部计数条 + 会话统计对话框），本包只做全局汇总——不预留下钻接口。
+ *
+ * 设计约束（勿改成 import 官方包）：
+ * - 本包运行在宿主 node 进程里，但被 pnpm 链接在文件目录下，若 import
+ *   `@deepseek-ai/dsh-typert-protocol` / `@deepseek-ai/cordis` 会解析出与宿主不同的第二副本，
+ *   Service 原型链与 instanceof 判定跨副本失效（零依赖铁律）。
+ * - 因此这里按协议文档的形态手工落两件套：
+ *   ① 实例字段 `typertRemote = { service, serviceKey, namespace }`（gateway validateBinding 读它）；
+ *   ② 原型字符串键 `"@deepseek-ai/dsh-typert-protocol/remote-methods"`（remoteMethods() 跨副本可读，
+ *     version 1 校验通过即可被 collectSrcClaims 认领 SRC endpoint）。
+ * - 服务注册走 `ctx.reflect.provide(name, instance)`，与 Service 基类构造函数所做的事等价，
+ *   fiber 卸载时自动注销。
+ * - SRC 模式参数约束：方法参数必须是不带默认值/解构/rest 的单一标识符（gateway 取函数源码切分参数名，
+ *   客户端 contribution descriptor 的 wire 名与之一一对应）。
+ *   实测（dsh-api-gateway methodParameterNames + Node type-strip 行为）：`: unknown` 这类简单类型注解
+ *   strip 后替换为空白、解析时按 trim 保留标识符，可安全携带（tsc strict 需要）；默认值/解构/rest 禁止。
+ */
+import { buildOverview, normalizeRange, scanFolds } from "./aggregate.ts";
+import { sessionsRoot } from "./scanner.ts";
+import { FoldStore } from "./store.ts";
+
+export type CordisConfig = {
+  /** 会话根目录覆盖（默认 $DSH_HOME/sessions 或 ~/.dsh/sessions）。 */
+  sessionsHome?: string;
+};
+
+const REMOTE_METHODS_KEY = "@deepseek-ai/dsh-typert-protocol/remote-methods";
+
+class UsageStatsService {
+  ctx: any;
+  config: CordisConfig;
+  typertRemote: { service: UsageStatsService; serviceKey: string; namespace: string };
+  /** 增量扫描存量（懒初始化：sessions 根要到首次查询才确定）。 */
+  private store: FoldStore | null = null;
+
+  constructor(ctx: any, config: CordisConfig) {
+    this.ctx = ctx;
+    this.config = config || {};
+    this.typertRemote = Object.freeze({ service: this, serviceKey: "usageStats", namespace: "usageStats" });
+  }
+
+  /** 全局汇总视图：`{ from?, to?, model?, provider? }`（日期 YYYY-MM-DD 本地时区），缺省全部。 */
+  async overview(filter: unknown) {
+    const root = sessionsRoot(this.config.sessionsHome);
+    if (!this.store) this.store = new FoldStore(root);
+    const { folds } = await scanFolds(root, this.store);
+    return buildOverview(folds, normalizeRange(filter));
+  }
+}
+
+/** 手写 SRC Remote 标记（形态 = typert-protocol mark() 产物：{version:1, methods:[...]}）。 */
+Object.defineProperty(UsageStatsService.prototype, REMOTE_METHODS_KEY, {
+  configurable: true,
+  value: Object.freeze({
+    version: 1,
+    methods: Object.freeze([Object.freeze({ method: "overview", invocation: Object.freeze({ kind: "direct" }) })]),
+  }),
+});
+
+export const name = "usage-stats";
+export const inject: string[] = [];
+
+export function applyCordis(ctx: any, config?: CordisConfig) {
+  const service = new UsageStatsService(ctx, config || {});
+  ctx.reflect.provide("usageStats", service);
+  ctx.logger?.info?.("[plugin-usage-stats] usageStats remote online");
+  return service;
+}
+
+export default { name, inject, apply: applyCordis };
+export { UsageStatsService };