@sleep2agi/commhub-server 0.9.0-preview.76 → 0.9.0-preview.78

package/src/requirements.ts

@@ -12,6 +12,7 @@ import {
   addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject,
   isTaskScoped, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
+import { diffRequirement, ensureRequirementEvents, eventPublic, recordRequirementEvents, type EventRow } from "./requirement-events.js";
 import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
@@ -24,6 +25,7 @@ ensureRequirementSeq(db);
 ensureRequirementCompletedAt(db);
 ensureNetworkTags(db);
 ensureRequirementTombstones(db);
+ensureRequirementEvents(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -285,8 +287,15 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
   if (req.method === "DELETE") {
     // 先把卡片上的引用置空,再删项目:卡片一张不少。
     // updated_at 跟着动:按 updated_since 增量同步的客户端要看得见「项目被清空」这一改动。
-    db.run("UPDATE requirements SET project_id = NULL, updated_at = ?2 WHERE project_id = ?1", [current.project_id, new Date().toISOString()]);
-    db.run("DELETE FROM requirement_projects WHERE project_id = ?1", [current.project_id]);
+    // 每张被清空项目的卡记一条「项目 X → 无」(与清空同一个事务)。
+    const at = new Date().toISOString();
+    const actor = JSON.stringify(actorOf(ctx));
+    db.transaction(() => {
+      const cards = db.all<{ requirement_id: string; network_id: string; seq: number | null; title: string }>("SELECT requirement_id, network_id, seq, title FROM requirements WHERE project_id = ?1", current.project_id);
+      db.run("UPDATE requirements SET project_id = NULL, updated_at = ?2 WHERE project_id = ?1", [current.project_id, at]);
+      for (const card of cards) recordRequirementEvents(db, card, actor, [{ kind: "changed", field: "project", old: current.project_id, new: null }], at);
+      db.run("DELETE FROM requirement_projects WHERE project_id = ?1", [current.project_id]);
+    });
     deleteTaskGrantsForProject(current.project_id);
     return Response.json({ ok: true });
   }
@@ -335,8 +344,8 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
   const actor = JSON.stringify(actorOf(ctx));
   // 读-改-写整个网络的标签在一个事务里:中途失败一张都不改;颜色表跟着一起挪。
   const result = db.transaction(() => {
-    const cards = db.all<{ requirement_id: string; tags_json: string | null }>(
-      "SELECT requirement_id, tags_json FROM requirements WHERE network_id = ?1 AND tags_json IS NOT NULL AND tags_json <> '[]'", networkId,
+    const cards = db.all<{ requirement_id: string; network_id: string; seq: number | null; title: string; tags_json: string | null }>(
+      "SELECT requirement_id, network_id, seq, title, tags_json FROM requirements WHERE network_id = ?1 AND tags_json IS NOT NULL AND tags_json <> '[]'", networkId,
     );
     const colorOf = (name: string) => db.get<{ color: string }>("SELECT color FROM network_tags WHERE network_id = ?1 AND name = ?2", networkId, name)?.color ?? null;
     const sources = op.op === "rename" ? [op.from] : op.op === "merge" ? op.from : [op.tag];
@@ -352,6 +361,7 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
       const next = applyTagOp(storedTags(card.tags_json), op);
       if (!next) continue;
       db.run("UPDATE requirements SET tags_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(next), now, actor, card.requirement_id]);
+      recordRequirementEvents(db, card, actor, [{ kind: "changed", field: "tags", old: storedTags(card.tags_json), new: next }], now);
       affected++;
     }
     moveTagColors(networkId, op, colorOf, now);
@@ -581,7 +591,8 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
 // search:GET 认 q=(服务端搜索,语义同 App 的任务搜索);paging:认 limit / cursor,响应带 has_more / next_cursor。
 // list_summary:GET 认 view=summary(不带描述正文与子任务条目,见 toSummary);changes:GET 认 changes=1 + updated_since
 // (改过的卡含归档的,加上 deleted 墓碑与 server_time,见 listChanges)。
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes"] as const;
+// events:GET /api/requirements/events —— 字段级的改动流水(谁、何时、旧值 → 新值,requirement-events.ts)。
+export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -738,15 +749,19 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId)); } catch (e) { return jsonError((e as Error).message, 400); }
   const actor = JSON.stringify(actorOf(ctx));
   try {
-    // 领号和插入在同一个事务里:插入被唯一索引挡下时,号一起回滚,不留空洞。
-    db.transaction(() => db.run(
-      `INSERT INTO requirements
-       (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json, start_on, seq, completed_at, completed_by_json, completed_at_approx)
-       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22, ?23, ?24, ?25, ?26, 0)`,
-      [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags), start || null, nextRequirementSeq(db, networkId),
-        // 直接建在「完成」列 = 此刻完成、由建卡的人完成。
-        column === "done" ? createdAt : null, column === "done" ? actor : null],
-    ));
+    // 领号、插入、记「新建」这条动态在同一个事务里:插入被唯一索引挡下时,号和动态一起回滚,不留空洞。
+    db.transaction(() => {
+      const seq = nextRequirementSeq(db, networkId);
+      db.run(
+        `INSERT INTO requirements
+         (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json, start_on, seq, completed_at, completed_by_json, completed_at_approx)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22, ?23, ?24, ?25, ?26, 0)`,
+        [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags), start || null, seq,
+          // 直接建在「完成」列 = 此刻完成、由建卡的人完成。
+          column === "done" ? createdAt : null, column === "done" ? actor : null],
+      );
+      recordRequirementEvents(db, { requirement_id: id, network_id: networkId, seq, title: name }, actor, [{ kind: "created", field: null, old: null, new: { title: name, column } }], createdAt);
+    });
   } catch {
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
     if (ref) {
@@ -857,16 +872,21 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   const completed = column !== "done" ? { at: null, by: null, approx: 0 }
     : row.column_name !== "done" ? { at: updatedAt, by: actor, approx: 0 }
     : { at: row.completed_at, by: row.completed_by_json, approx: row.completed_at_approx ? 1 : 0 };
-  db.run(
-    `UPDATE requirements SET column_name = ?1, updated_at = ?2, title = ?7, priority = ?8, due_on = ?9, assignee = ?10, owner_json = ?4, participants_json = ?5, issues_json = ?6,
-       agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20, start_on = ?21,
-       completed_at = ?22, completed_by_json = ?23, completed_at_approx = ?24
-     WHERE requirement_id = ?3`,
-    [column, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
-      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, actor, parentId, has("tags") ? JSON.stringify(tags) : row.tags_json, start || null,
-      completed.at, completed.by, completed.approx],
-  );
-  const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+  // 改卡和记动态(改前 row → 改后 updated 的字段差异)在同一个事务里:要么都在,要么都不在。
+  const updated = db.transaction(() => {
+    db.run(
+      `UPDATE requirements SET column_name = ?1, updated_at = ?2, title = ?7, priority = ?8, due_on = ?9, assignee = ?10, owner_json = ?4, participants_json = ?5, issues_json = ?6,
+         agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20, start_on = ?21,
+         completed_at = ?22, completed_by_json = ?23, completed_at_approx = ?24
+       WHERE requirement_id = ?3`,
+      [column, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
+        has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, actor, parentId, has("tags") ? JSON.stringify(tags) : row.tags_json, start || null,
+        completed.at, completed.by, completed.approx],
+    );
+    const after = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+    recordRequirementEvents(db, after, actor, diffRequirement(row, after), updatedAt);
+    return after;
+  });
   return Response.json(withLegacyOwner(toPublicFor(ctx, updated), people.coerced));
 }
 
@@ -1046,6 +1066,86 @@ function deletedSince(ctx: RequirementsRequestContext, sinceIso: string): string
   return db.all<TombstoneRow>(sql, ...params).filter(row => canSeeTask(caller, row)).map(row => row.requirement_id);
 }
 
+// ── 任务动态(requirement-events.ts)──
+// GET /api/requirements/events?network_id&since&limit&cursor&requirement_id:一个网络的改动流水,按 id 从新到旧。
+// 可见范围与列表相同:卡还在 → 按当前这张卡判断调用者看不看得见;删掉了 → 按墓碑(过了墓碑保留期的删除,
+// 只有不受任务范围限制的调用者看得到)。受限成员看不见的节点:操作者隐去,负责人 / 负责 Agent / 参与人里的隐去,
+// 隐去之后前后一样的那条整条不回(否则是「这张卡的 Agent 换过」的探测器)。
+// 按可见性过滤是在读出来之后做的:一页最多扫 EVENTS_SCAN_MAX 条,扫满还没凑够就带 next_cursor 回去,客户端接着翻。
+const EVENTS_PAGE_DEFAULT = 200;
+const EVENTS_PAGE_MAX = 500;
+const EVENTS_SCAN_MAX = 5000;
+type VisibilityRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null };
+
+function listEvents(ctx: RequirementsRequestContext): Response {
+  const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+  if (!networkId) return jsonError("network_id_required", 400);
+  const q = ctx.url.searchParams;
+  const limit = q.get("limit") === null ? EVENTS_PAGE_DEFAULT : Number(q.get("limit"));
+  if (!Number.isInteger(limit) || limit < 1 || limit > EVENTS_PAGE_MAX) return jsonError("invalid_limit", 400);
+  let since: string | null = null;
+  if (q.get("since") !== null) {
+    const ms = Date.parse(q.get("since")!);
+    if (!Number.isFinite(ms)) return jsonError("invalid_since", 400);
+    since = new Date(ms).toISOString();
+  }
+  const cursor = q.get("cursor");
+  if (cursor !== null && !/^[1-9]\d{0,17}$/.test(cursor)) return jsonError("invalid_cursor", 400);
+  const card = q.get("requirement_id");
+  // server_time 取在读表之前:下次拿它当 since,读的期间写进来的不会漏(>= 会重复回,客户端按 id 去重)。
+  const serverTime = new Date().toISOString();
+  const caller = taskCaller(ctx);
+  const hidden = hiddenNodeFilter(ctx, networkId);
+  const seen = new Map<string, boolean>();
+  const canSee = (id: string): boolean => {
+    if (!caller) return true;
+    let ok = seen.get(id);
+    if (ok === undefined) {
+      const cols = "network_id, owner_json, participants_json, created_by, created_by_json, project_id";
+      const row = db.get<VisibilityRow>(`SELECT ${cols} FROM requirements WHERE requirement_id = ?1`, id)
+        ?? db.get<VisibilityRow>(`SELECT ${cols} FROM requirement_tombstones WHERE requirement_id = ?1`, id);
+      seen.set(id, ok = !!row && row.network_id === networkId && canSeeTask(caller, row));
+    }
+    return ok;
+  };
+  const shown = (row: EventRow) => {
+    if (!canSee(row.requirement_id)) return null;
+    const ev = eventPublic(row);
+    if (!hidden) return ev;
+    const mask = (ref: unknown) => (isHiddenRef(ref, hidden) ? null : ref);
+    const masked = { ...ev, actor: mask(ev.actor) };
+    if (ev.field === "owner" || ev.field === "agent_owner") { masked.old = mask(ev.old); masked.new = mask(ev.new); }
+    if (ev.field === "participants") {
+      masked.old = Array.isArray(ev.old) ? ev.old.filter(ref => !isHiddenRef(ref, hidden)) : ev.old;
+      masked.new = Array.isArray(ev.new) ? ev.new.filter(ref => !isHiddenRef(ref, hidden)) : ev.new;
+    }
+    return ev.field && JSON.stringify(masked.old) === JSON.stringify(masked.new) ? null : masked;
+  };
+  const events: ReturnType<typeof eventPublic>[] = [];
+  let before = cursor === null ? null : Number(cursor);
+  let scanned = 0;
+  let nextCursor: string | null = null;
+  scan: for (;;) {
+    const params: unknown[] = [networkId];
+    let sql = "SELECT id, network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at FROM requirement_events WHERE network_id = ?1";
+    if (since) sql += ` AND created_at >= ?${params.push(since)}`;
+    if (card) sql += ` AND requirement_id = ?${params.push(card)}`;
+    if (before !== null) sql += ` AND id < ?${params.push(before)}`;
+    const batch = db.all<EventRow>(`${sql} ORDER BY id DESC LIMIT ${limit + 1}`, ...params);
+    for (const row of batch) {
+      const ev = shown(row);
+      if (ev && events.length === limit) { nextCursor = events[events.length - 1].id; break scan; }
+      scanned++;
+      before = Number(row.id);
+      if (ev) events.push(ev);
+    }
+    if (batch.length < limit + 1) break;
+    // 扫满了(调用者看不见的太多):从扫到的地方接着翻。
+    if (scanned >= EVENTS_SCAN_MAX) { nextCursor = String(before); break; }
+  }
+  return Response.json({ ok: true, network_id: networkId, events, has_more: nextCursor !== null, next_cursor: nextCursor, server_time: serverTime });
+}
+
 /**
  * 需求表的写入代数:每个经过 handleRequirementsRequest 的非 GET 请求处理完就 +1(REST 和 MCP 的写入都走它,
  * tools.ts 调的是同一个处理函数)。列表缓存只在代数没变时复用。进程重启 = 缓存清空。
@@ -1152,6 +1252,8 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     return conditionalJson(ctx.req, { ok: true, networkId, ...aggregateStats(rows, sq, hiddenNodeFilter(ctx, networkId)) });
   }
 
+  if (url.pathname === "/api/requirements/events" && req.method === "GET") return listEvents(ctx);
+
   if (url.pathname === '/api/requirements/people' && req.method === 'GET') {
     const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
     if (!networkId) return jsonError('network_id_required', 400);
@@ -1261,9 +1363,16 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const itemId = decodeURIComponent(itemMatch[2]);
     const item = items.find(entry => entry.id === itemId);
     if (!item) return jsonError("checklist_item_not_found", 404);
+    const was = item.done;
     item.done = body.done;
-    db.run("UPDATE requirements SET checklist_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(items), new Date().toISOString(), JSON.stringify(actorOf(ctx)), row.requirement_id]);
-    const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+    const at = new Date().toISOString();
+    const actor = JSON.stringify(actorOf(ctx));
+    const updated = db.transaction(() => {
+      db.run("UPDATE requirements SET checklist_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(items), at, actor, row.requirement_id]);
+      // 重复勾同一个值(done 是显式值,幂等)不算一次改动,不记。
+      if (was !== item.done) recordRequirementEvents(db, row, actor, [{ kind: "changed", field: "checklist_item", old: { ...item, done: was }, new: { ...item } }], at);
+      return db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+    });
     return Response.json({ ok: true, requirement: toPublicFor(ctx, updated) });
   }
 
@@ -1282,9 +1391,13 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     if (!canDeleteTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_delete_denied");
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
     const deletedAt = new Date().toISOString();
-    db.run("UPDATE requirements SET parent_id = NULL, updated_at = ?2 WHERE parent_id = ?1", [row.requirement_id, deletedAt]);
-    db.run("DELETE FROM requirements WHERE requirement_id = ?1", [row.requirement_id]);
-    recordTombstone(row, deletedAt);
+    db.transaction(() => {
+      db.run("UPDATE requirements SET parent_id = NULL, updated_at = ?2 WHERE parent_id = ?1", [row.requirement_id, deletedAt]);
+      db.run("DELETE FROM requirements WHERE requirement_id = ?1", [row.requirement_id]);
+      recordTombstone(row, deletedAt);
+      // 卡没了,动态里还要画得出「谁删了 #N 标题」:标题 / 短号随行存(seq、title 列)。
+      recordRequirementEvents(db, row, JSON.stringify(actorOf(ctx)), [{ kind: "deleted", field: null, old: null, new: null }], deletedAt);
+    });
     // 硬删除以前不留痕(RFC-038 §9.1):记下是谁删了哪张(标题 + 短号),卡本身已经没了。
     if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_deleted", "requirement", row.requirement_id, JSON.stringify({ title: row.title, seq: row.seq ?? null }).slice(0, 1000), undefined, row.network_id);
     return Response.json({ ok: true, deleted: row.requirement_id });

package/src/route-timing.test.ts

@@ -1,7 +1,13 @@
 import { expect, test } from "bun:test";
-import { __resetRouteTimingForTest, recordRouteTiming, routeKey, routeStats, ROUTE_RING_SIZE } from "./route-timing";
+import {
+  __resetRouteTimingForTest, labelRoute, mcpRouteLabel, recordRouteTiming, routeKey, routeStats,
+  ROUTE_BUCKET_MS, ROUTE_BUCKET_RETENTION, ROUTE_MAX_KEYS_PER_BUCKET, ROUTE_OVERFLOW_KEY,
+} from "./route-timing";
 
 const u = (s: string) => new URL(`http://hub${s}`);
+const req = (path: string, method = "GET") => new Request(`http://hub${path}`, { method });
+const res = (status = 200, len?: number) => new Response("x", { status, headers: len === undefined ? {} : { "Content-Length": String(len) } });
+const at = (ms: number) => performance.now() - ms;
 
 test("routeKey collapses ids, aliases and file names, keeps payload-shaping params", () => {
   expect(routeKey("GET", u("/api/requirements?network_id=net_1&limit=500"))).toBe("GET /api/requirements");
@@ -13,12 +19,9 @@ test("routeKey collapses ids, aliases and file names, keeps payload-shaping para
   expect(routeKey("GET", u("/api/messages?scope=user&limit=50"))).toBe("GET /api/messages?scope=user");
 });
 
-test("routeStats groups the window, sorts by total time, and the ring keeps only the newest samples", () => {
+test("routeStats groups the window, sorts by total time, and counts every request (no sample cap)", () => {
   __resetRouteTimingForTest();
-  const now = 1_000_000;
-  const req = (path: string) => new Request(`http://hub${path}`);
-  const res = (status = 200, len?: number) => new Response("x", { status, headers: len === undefined ? {} : { "Content-Length": String(len) } });
-  const at = (ms: number) => performance.now() - ms;
+  const now = 1_000_000_000;
   recordRouteTiming(req("/api/requirements"), at(30), res(200, 1000), now);
   recordRouteTiming(req("/api/requirements"), at(10), res(200, 500), now);
   recordRouteTiming(req("/api/status?light=1"), at(5), res(503), now);
@@ -32,9 +35,103 @@ test("routeStats groups the window, sorts by total time, and the ring keeps only
   expect(r0.bytes).toBe(1500);
   expect(r0.max_ms).toBeGreaterThanOrEqual(29);
   expect(r0.total_ms).toBeGreaterThanOrEqual(39);
+  expect(r0.p95_ms).toBeLessThanOrEqual(r0.max_ms);
   expect(stats.routes[1].errors).toBe(1);
-  for (let i = 0; i < ROUTE_RING_SIZE + 10; i++) recordRouteTiming(req("/api/tasks"), at(1), res(), now);
+  // The old 4096-sample ring dropped everything past its size; the buckets count all of it.
+  for (let i = 0; i < 10_000; i++) recordRouteTiming(req("/api/tasks"), at(1), res(), now);
   const after = routeStats(60_000, now);
-  expect(after.samples).toBe(ROUTE_RING_SIZE);
-  expect(after.routes.map(r => r.route)).toEqual(["GET /api/tasks"]);
+  expect(after.routes.find(r => r.route === "GET /api/tasks")!.count).toBe(10_000);
+  expect(after.samples).toBe(10_003);
+});
+
+test("?minutes=10 really covers 10 minutes: a steady 15 req/s stream is fully counted, older traffic is not", () => {
+  __resetRouteTimingForTest();
+  const t0 = 2_000_000_000 - (2_000_000_000 % ROUTE_BUCKET_MS); // bucket-aligned
+  // 20 minutes at 15 req/s — the old ring filled in ~4.5 minutes of this.
+  for (let s = 0; s < 20 * 60; s++) {
+    for (let k = 0; k < 15; k++) recordRouteTiming(req("/mcp", "POST"), at(1), res(), t0 + s * 1000);
+  }
+  const now = t0 + 20 * 60_000;
+  const ten = routeStats(10 * 60_000, now);
+  // window starts at t0+10min → the ten minute buckets t0+10 … t0+19
+  expect(ten.samples).toBe(10 * 60 * 15);
+  expect(ten.oldest_at).toBe(new Date(t0 + 10 * 60_000).toISOString());
+  expect(routeStats(20 * 60_000, now).samples).toBe(20 * 60 * 15);
+  expect(routeStats(60 * 60_000, now).samples).toBe(20 * 60 * 15);
+});
+
+test("buckets older than the retention are dropped", () => {
+  __resetRouteTimingForTest();
+  const now = 3_000_000_000;
+  const old = now - (ROUTE_BUCKET_RETENTION + 5) * ROUTE_BUCKET_MS;
+  recordRouteTiming(req("/api/old"), at(1), res(), old);
+  expect(routeStats(ROUTE_BUCKET_RETENTION * 2 * ROUTE_BUCKET_MS, old).samples).toBe(1);
+  recordRouteTiming(req("/api/new"), at(1), res(), now);
+  const s = routeStats(ROUTE_BUCKET_RETENTION * 2 * ROUTE_BUCKET_MS, now);
+  expect(s.routes.map(r => r.route)).toEqual(["GET /api/new"]);
+});
+
+test("p95 comes from the histogram: close to the true value and never above max", () => {
+  __resetRouteTimingForTest();
+  const now = 4_000_000_000;
+  // 96 fast (~1 ms) and 4 slow (~200 ms): p95 (the 96th of 100, same rank as the old ring's
+  // sorted[floor(n·0.95)]) must be in the fast band, max in the slow band.
+  for (let i = 0; i < 96; i++) recordRouteTiming(req("/api/p"), at(1), res(), now);
+  for (let i = 0; i < 4; i++) recordRouteTiming(req("/api/p"), at(200), res(), now);
+  const r = routeStats(60_000, now).routes[0];
+  expect(r.p95_ms).toBeGreaterThanOrEqual(1);
+  expect(r.p95_ms).toBeLessThan(5);
+  expect(r.max_ms).toBeGreaterThanOrEqual(200);
+  __resetRouteTimingForTest();
+  recordRouteTiming(req("/api/q"), at(3), res(), now);
+  const one = routeStats(60_000, now).routes[0];
+  expect(one.p95_ms).toBe(one.max_ms);
+});
+
+test("distinct routes per bucket are capped; the rest land in the overflow key", () => {
+  __resetRouteTimingForTest();
+  const now = 5_000_000_000;
+  for (let i = 0; i < ROUTE_MAX_KEYS_PER_BUCKET + 50; i++) {
+    const r = req("/mcp", "POST");
+    labelRoute(r, `tools/call t${String.fromCharCode(97 + (i % 26))}${Math.floor(i / 26)}x`);
+    recordRouteTiming(r, at(1), res(), now);
+  }
+  const s = routeStats(60_000, now);
+  expect(s.routes.length).toBe(ROUTE_MAX_KEYS_PER_BUCKET + 1);
+  expect(s.routes.find(r => r.route === ROUTE_OVERFLOW_KEY)!.count).toBe(50);
+  expect(s.samples).toBe(ROUTE_MAX_KEYS_PER_BUCKET + 50);
+});
+
+test("a label is appended to the route shape of that request only", () => {
+  __resetRouteTimingForTest();
+  const now = 6_000_000_000;
+  const a = req("/mcp", "POST");
+  labelRoute(a, "tools/call report_status");
+  recordRouteTiming(a, at(1), res(), now);
+  recordRouteTiming(req("/mcp", "POST"), at(1), res(), now);
+  expect(routeStats(60_000, now).routes.map(r => r.route).sort()).toEqual(["POST /mcp", "POST /mcp tools/call report_status"]);
+});
+
+test("mcpRouteLabel: method, tool name, and nothing else", () => {
+  expect(mcpRouteLabel({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "report_status", arguments: { task: "secret" } } })).toBe("tools/call report_status");
+  expect(mcpRouteLabel({ jsonrpc: "2.0", id: 1, method: "tools/list" })).toBe("tools/list");
+  expect(mcpRouteLabel({ jsonrpc: "2.0", method: "notifications/initialized" })).toBe("notifications/initialized");
+  expect(mcpRouteLabel({ jsonrpc: "2.0", id: 1, method: "initialize", params: { name: "x" } })).toBe("initialize");
+  // odd shapes collapse to "?"
+  expect(mcpRouteLabel([{ method: "tools/list" }])).toBe("batch");
+  expect(mcpRouteLabel(null)).toBe("?");
+  expect(mcpRouteLabel("tools/list")).toBe("?");
+  expect(mcpRouteLabel(42)).toBe("?");
+  expect(mcpRouteLabel({})).toBe("?");
+  expect(mcpRouteLabel({ method: 7 })).toBe("?");
+  expect(mcpRouteLabel({ method: "x".repeat(65) })).toBe("?");
+  expect(mcpRouteLabel({ method: "tools/call x" })).toBe("?");
+  expect(mcpRouteLabel({ method: "通信" })).toBe("?");
+  expect(mcpRouteLabel({ method: "tools/call" })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: "report_status" })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: { toString: () => "x" } } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "a b" } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "../../etc/passwd" } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "n".repeat(65) } })).toBe("tools/call ?");
+  expect(mcpRouteLabel({ method: "tools/call", params: { name: "" } })).toBe("tools/call ?");
 });

package/src/route-timing.ts

@@ -1,11 +1,29 @@
-// 每个路由的耗时环(2026-09-30):生产 hub 平均 ~24% CPU,但没有任何按路由的计时,也没有访问日志,
-// 说不清是谁在吃 CPU。这里在 fetch 入口记最近 ROUTE_RING_SIZE 个请求(路由形状、耗时、状态、字节),
-// GET /api/stats/routes(管理员 / master)按时间窗汇总。只在内存里,重启清空;不记 query 值、不记调用者。
-export const ROUTE_RING_SIZE = 4096;
+// 每个路由的耗时统计(2026-09-30):生产 hub 平均 ~24% CPU,但没有任何按路由的计时,也没有访问日志,
+// 说不清是谁在吃 CPU。这里在 fetch 入口按路由形状累计次数、耗时、状态、字节,
+// GET /api/stats/routes(管理员 / master)按时间窗汇总。只在内存里,重启清空;不记 query 值、不记调用者、不记请求体。
+//
+// 2026-10-01 —— 原来是 4096 条样本的环:生产上 212 s 就写满,?minutes=10 实际只覆盖三分半钟。
+// 改成按分钟分桶的累计器:每个桶里每个路由一行(次数 / 总耗时 / 最大值 / 字节 / 5xx / 耗时直方图),
+// 保留 ROUTE_BUCKET_RETENTION 个桶(24 小时),窗口多长就真覆盖多长。p95 从直方图取(桶上沿,不超过 max)。
+export const ROUTE_BUCKET_MS = 60_000;
+export const ROUTE_BUCKET_RETENTION = 1440;
+/** 每个分钟桶里最多这么多个不同的路由;再多的记到 ROUTE_OVERFLOW_KEY,防止怪路径 / 怪工具名把内存撑大。 */
+export const ROUTE_MAX_KEYS_PER_BUCKET = 256;
+export const ROUTE_OVERFLOW_KEY = "(other)";
 
-type Sample = { at: number; route: string; ms: number; status: number; bytes: number | null };
-const ring: Sample[] = [];
-let next = 0;
+// 耗时直方图:第 i 格的上沿 = HIST_BASE_MS · 2^(i/2),0.05 ms … ~52 s;最后一格收下更慢的。
+const HIST_BASE_MS = 0.05;
+const HIST_BINS = 41;
+function histBin(ms: number): number {
+  if (!(ms > HIST_BASE_MS)) return 0;
+  return Math.min(HIST_BINS - 1, Math.ceil(2 * Math.log2(ms / HIST_BASE_MS)));
+}
+const histUpper = (bin: number) => HIST_BASE_MS * 2 ** (bin / 2);
+
+type Agg = { count: number; totalMs: number; maxMs: number; bytes: number; errors: number; hist: Uint32Array };
+type Bucket = { minute: number; routes: Map<string, Agg> };
+// 按 minute 升序;新的一分钟追加在尾部,超出保留期从头部丢。
+const buckets: Bucket[] = [];
 
 /** 路由的形状:id / 别名 / 文件名这类段换成 :id,几个会改变载荷形状的参数保留(light / view / scope / changes)。 */
 const SHAPE_PARAMS = ["changes", "light", "scope", "view"];
@@ -18,46 +36,112 @@ export function routeKey(method: string, url: URL): string {
   return `${method} ${segments.join("/")}${shape ? `?${shape}` : ""}`;
 }
 
+// 处理器给某个请求补一段标签(比如 POST /mcp 的 JSON-RPC 方法名),recordRouteTiming 拼到路由形状后面。
+const labels = new WeakMap<Request, string>();
+export function labelRoute(req: Request, label: string): void {
+  labels.set(req, label);
+}
+
+const MCP_METHOD_RE = /^[A-Za-z][A-Za-z0-9_./-]{0,63}$/;
+const MCP_TOOL_RE = /^[A-Za-z0-9_.-]{1,64}$/;
+/**
+ * POST /mcp 的标签:JSON-RPC 方法名,tools/call 再带工具名,如 "tools/call report_status"。
+ * 只读 method 和 params.name 两个字段,别的(尤其 arguments)一概不碰;形状不对的一律折成 "?",
+ * 批量请求记 "batch"。名字只放行短的 ASCII 标识符,防止拿请求体造出任意多、任意长的路由键。
+ */
+export function mcpRouteLabel(body: unknown): string {
+  if (Array.isArray(body)) return "batch";
+  if (!body || typeof body !== "object") return "?";
+  const method = (body as { method?: unknown }).method;
+  if (typeof method !== "string" || !MCP_METHOD_RE.test(method)) return "?";
+  if (method !== "tools/call") return method;
+  const params = (body as { params?: unknown }).params;
+  const name = params && typeof params === "object" ? (params as { name?: unknown }).name : undefined;
+  return `tools/call ${typeof name === "string" && MCP_TOOL_RE.test(name) ? name : "?"}`;
+}
+
 /** 记一次请求;原样返回 res,方便套在 fetch 处理器的 return 上。WebSocket 升级(res 为空)不记。 */
 export function recordRouteTiming<T extends Response | undefined>(req: Request, started: number, res: T, now: number = Date.now()): T {
   if (!res) return res;
   let url: URL;
   try { url = new URL(req.url); } catch { return res; }
+  const label = labels.get(req);
+  const route = label ? `${routeKey(req.method, url)} ${label}` : routeKey(req.method, url);
   const length = Number(res.headers.get("content-length"));
-  const sample: Sample = { at: now, route: routeKey(req.method, url), ms: performance.now() - started, status: res.status, bytes: Number.isFinite(length) && res.headers.has("content-length") ? length : null };
-  if (ring.length < ROUTE_RING_SIZE) ring.push(sample);
-  else ring[next] = sample;
-  next = (next + 1) % ROUTE_RING_SIZE;
+  const bytes = Number.isFinite(length) && res.headers.has("content-length") ? length : 0;
+  addSample(route, performance.now() - started, res.status, bytes, now);
   return res;
 }
 
+function addSample(route: string, ms: number, status: number, bytes: number, now: number): void {
+  const minute = Math.floor(now / ROUTE_BUCKET_MS);
+  let bucket = buckets[buckets.length - 1];
+  if (!bucket || minute > bucket.minute) {
+    buckets.push(bucket = { minute, routes: new Map() });
+    const oldest = minute - ROUTE_BUCKET_RETENTION + 1;
+    let drop = 0;
+    while (drop < buckets.length && buckets[drop].minute < oldest) drop++;
+    if (drop) buckets.splice(0, drop);
+  } else if (minute < bucket.minute) {
+    // 时间戳比最新的桶早(时钟回拨,或测试里乱序记):放回它自己的那一分钟;比保留期还早的丢掉。
+    if (minute < bucket.minute - ROUTE_BUCKET_RETENTION + 1) return;
+    let i = buckets.length - 1;
+    while (i > 0 && buckets[i - 1].minute >= minute) i--;
+    if (buckets[i].minute !== minute) buckets.splice(i, 0, { minute, routes: new Map() });
+    bucket = buckets[i];
+  }
+  let agg = bucket.routes.get(route);
+  if (!agg) {
+    if (bucket.routes.size >= ROUTE_MAX_KEYS_PER_BUCKET) route = ROUTE_OVERFLOW_KEY;
+    agg = bucket.routes.get(route);
+    if (!agg) bucket.routes.set(route, agg = { count: 0, totalMs: 0, maxMs: 0, bytes: 0, errors: 0, hist: new Uint32Array(HIST_BINS) });
+  }
+  agg.count++;
+  agg.totalMs += ms;
+  if (ms > agg.maxMs) agg.maxMs = ms;
+  agg.bytes += bytes;
+  if (status >= 500) agg.errors++;
+  agg.hist[histBin(ms)]++;
+}
+
 export type RouteStat = { route: string; count: number; total_ms: number; avg_ms: number; p95_ms: number; max_ms: number; bytes: number; errors: number };
 
-/** 最近 windowMs 内的样本按路由汇总,按总耗时降序。 */
+/**
+ * 最近 windowMs 内的请求按路由汇总,按总耗时降序。粒度是分钟桶:窗口起点落在哪个桶,就从那个桶算起。
+ * oldest_at 是窗口里最早一个有数据的桶的起点 —— 它比 now - window_ms 晚很多,说明 hub 是那之后才起来的。
+ */
 export function routeStats(windowMs: number, now: number = Date.now()): { window_ms: number; samples: number; oldest_at: string | null; routes: RouteStat[] } {
-  const since = now - windowMs;
-  const groups = new Map<string, Sample[]>();
+  const fromMinute = Math.floor((now - windowMs) / ROUTE_BUCKET_MS);
+  const merged = new Map<string, Agg>();
   let oldest: number | null = null;
-  for (const s of ring) {
-    if (s.at < since) continue;
-    if (oldest === null || s.at < oldest) oldest = s.at;
-    let g = groups.get(s.route);
-    if (!g) groups.set(s.route, g = []);
-    g.push(s);
+  for (const bucket of buckets) {
+    if (bucket.minute < fromMinute) continue;
+    if (oldest === null) oldest = bucket.minute * ROUTE_BUCKET_MS;
+    for (const [route, a] of bucket.routes) {
+      let m = merged.get(route);
+      if (!m) merged.set(route, m = { count: 0, totalMs: 0, maxMs: 0, bytes: 0, errors: 0, hist: new Uint32Array(HIST_BINS) });
+      m.count += a.count;
+      m.totalMs += a.totalMs;
+      if (a.maxMs > m.maxMs) m.maxMs = a.maxMs;
+      m.bytes += a.bytes;
+      m.errors += a.errors;
+      for (let i = 0; i < HIST_BINS; i++) m.hist[i] += a.hist[i];
+    }
   }
   const round = (n: number) => Math.round(n * 10) / 10;
-  const routes = [...groups].map(([route, samples]): RouteStat => {
-    const ms = samples.map(s => s.ms).sort((a, b) => a - b);
-    const total = ms.reduce((a, b) => a + b, 0);
+  const routes = [...merged].map(([route, a]): RouteStat => {
+    const rank = Math.min(a.count, Math.floor(a.count * 0.95) + 1);
+    let seen = 0, bin = 0;
+    for (; bin < HIST_BINS - 1; bin++) { seen += a.hist[bin]; if (seen >= rank) break; }
     return {
       route,
-      count: samples.length,
-      total_ms: round(total),
-      avg_ms: round(total / samples.length),
-      p95_ms: round(ms[Math.min(ms.length - 1, Math.floor(ms.length * 0.95))]),
-      max_ms: round(ms[ms.length - 1]),
-      bytes: samples.reduce((n, s) => n + (s.bytes ?? 0), 0),
-      errors: samples.filter(s => s.status >= 500).length,
+      count: a.count,
+      total_ms: round(a.totalMs),
+      avg_ms: round(a.totalMs / a.count),
+      p95_ms: round(Math.min(histUpper(bin), a.maxMs)),
+      max_ms: round(a.maxMs),
+      bytes: a.bytes,
+      errors: a.errors,
     };
   }).sort((a, b) => b.total_ms - a.total_ms);
   return { window_ms: windowMs, samples: routes.reduce((n, r) => n + r.count, 0), oldest_at: oldest === null ? null : new Date(oldest).toISOString(), routes };
@@ -65,6 +149,5 @@ export function routeStats(windowMs: number, now: number = Date.now()): { window
 
 /** Test-only. */
 export function __resetRouteTimingForTest(): void {
-  ring.length = 0;
-  next = 0;
+  buckets.length = 0;
 }