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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.74",
+  "version": "0.9.0-preview.76",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/http-gzip.test.ts

@@ -71,3 +71,24 @@ test("trimLightTask keeps a one-line preview under the cap", () => {
   expect([...t].length).toBe(LIGHT_TASK_MAX_CHARS + 1);
   expect(trimLightTask("short")).toBe("short");
 });
+
+test("a response marked reusable is gzipped once per key; unmarked ones every time; different keys never share bytes", async () => {
+  const { markGzipReusable, gzipCacheStats, __resetGzipCacheForTest } = await import("./http-gzip");
+  __resetGzipCacheForTest();
+  const first = await maybeGzipResponse(reqWith("gzip"), markGzipReusable(json(big), "W/\"k1\""));
+  const second = await maybeGzipResponse(reqWith("gzip"), markGzipReusable(json(big), "W/\"k1\""));
+  expect(gzipCacheStats).toEqual({ hits: 1, misses: 1 });
+  const a = new Uint8Array(await first!.arrayBuffer());
+  const b = new Uint8Array(await second!.arrayBuffer());
+  expect(new TextDecoder().decode(Bun.gunzipSync(b))).toBe(big);
+  expect(Buffer.from(b).equals(Buffer.from(a))).toBe(true);
+  expect(Number(second!.headers.get("Content-Length"))).toBe(b.byteLength);
+  const other = big.replace("节点0", "节点X");
+  const third = await maybeGzipResponse(reqWith("gzip"), markGzipReusable(json(other), "W/\"k2\""));
+  expect(new TextDecoder().decode(Bun.gunzipSync(new Uint8Array(await third!.arrayBuffer())))).toBe(other);
+  await maybeGzipResponse(reqWith("gzip"), json(big));
+  expect(gzipCacheStats).toEqual({ hits: 1, misses: 2 });
+  // 没要 gzip 的客户端照旧拿原样正文,不碰缓存
+  const plain = markGzipReusable(json(big), "W/\"k1\"");
+  expect(await maybeGzipResponse(reqWith(), plain)).toBe(plain);
+});

package/src/http-gzip.ts

@@ -29,6 +29,56 @@ export function isCompressibleResponse(res: Response): boolean {
   return COMPRESSIBLE.test(ct);
 }
 
+// 2026-09-30(连接较慢横幅):任务页每 15 s 轮询 ~1 MB 的需求表,每次都在事件循环上同步 gzip 一遍,
+// 而两次轮询之间表多半没变。带内容哈希 ETag 的响应(conditionalJson)标一个键,同一份正文只压一次。
+// 键就是正文的哈希,所以不同调用者拿到同一份压缩字节是安全的:字节相同 ⇔ 正文相同。
+export const GZIP_CACHE_MAX_BYTES = 16 * 1024 * 1024;
+const gzipKeys = new WeakMap<Response, string>();
+const gzipCache = new Map<string, Uint8Array>();
+let gzipCacheBytes = 0;
+export const gzipCacheStats = { hits: 0, misses: 0 };
+
+/** 标记这个响应的正文由 `key`(正文的内容哈希)唯一决定:压缩结果可以按键复用。 */
+export function markGzipReusable(res: Response, key: string): Response {
+  gzipKeys.set(res, key);
+  return res;
+}
+
+function gzipCached(key: string | undefined, raw: () => Promise<Uint8Array>): Promise<{ raw: Uint8Array | null; gz: Uint8Array | null }> | { raw: null; gz: Uint8Array } {
+  if (key) {
+    const hit = gzipCache.get(key);
+    if (hit) {
+      gzipCacheStats.hits++;
+      gzipCache.delete(key);
+      gzipCache.set(key, hit); // 最近用过的挪到队尾(LRU)
+      return { raw: null, gz: hit };
+    }
+  }
+  return raw().then(bytes => {
+    if (bytes.byteLength < GZIP_MIN_BYTES) return { raw: bytes, gz: null };
+    const gz = Bun.gzipSync(bytes);
+    if (key) gzipCacheStats.misses++;
+    if (key && gz.byteLength <= GZIP_CACHE_MAX_BYTES / 4) {
+      gzipCache.set(key, gz);
+      gzipCacheBytes += gz.byteLength;
+      for (const [k, v] of gzipCache) {
+        if (gzipCacheBytes <= GZIP_CACHE_MAX_BYTES) break;
+        gzipCache.delete(k);
+        gzipCacheBytes -= v.byteLength;
+      }
+    }
+    return { raw: bytes, gz };
+  });
+}
+
+/** Test-only. */
+export function __resetGzipCacheForTest(): void {
+  gzipCache.clear();
+  gzipCacheBytes = 0;
+  gzipCacheStats.hits = 0;
+  gzipCacheStats.misses = 0;
+}
+
 /**
  * Gzip a finished response when the client asked for it and the body is worth it.
  * Reads the body once; callers must not have consumed it. Anything streamed or
@@ -37,11 +87,11 @@ export function isCompressibleResponse(res: Response): boolean {
 export async function maybeGzipResponse(req: Request, res: Response | undefined | void): Promise<Response | undefined> {
   if (!res) return res as undefined;
   if (req.method === "HEAD" || !wantsGzip(req) || !isCompressibleResponse(res)) return res;
-  const raw = new Uint8Array(await res.arrayBuffer());
-  if (raw.byteLength < GZIP_MIN_BYTES) {
-    return new Response(raw, { status: res.status, statusText: res.statusText, headers: res.headers });
+  const got = await gzipCached(gzipKeys.get(res), async () => new Uint8Array(await res.arrayBuffer()));
+  if (!got.gz) {
+    return new Response(got.raw, { status: res.status, statusText: res.statusText, headers: res.headers });
   }
-  const gz = Bun.gzipSync(raw);
+  const gz = got.gz;
   const headers = new Headers(res.headers);
   headers.set("Content-Encoding", "gzip");
   headers.set("Content-Length", String(gz.byteLength));

package/src/requirements-http.test.ts

@@ -373,7 +373,7 @@ describe("requirements stay on the hub", () => {
     expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "" }) })).body.requirement.due).toBe("");
     const listed = await api(ownerToken, "/api/requirements");
     expect(listed.body.capabilities).toContain("due_datetime");
-    expect(listed.body.capabilities).toEqual(["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"]);
+    expect(listed.body.capabilities).toEqual(["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"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {

package/src/requirements-list-slim-http.test.ts

@@ -0,0 +1,315 @@
+// GET /api/requirements 省流(2026-09-30,App「连接较慢 · 数据可能稍有延迟」)—— HTTP 集成测试(真实 Bun.serve,临时库)。
+//   view=summary      —— 不带 description / checklist,换成 has_description / checklist_count;不带 view = 与原来逐字相同。
+//   changes=1         —— updated_since 之后改过的卡(含归档的)+ deleted 墓碑 + server_time;受限成员只收到他看得见的卡的删除。
+//   列表缓存          —— 表没变时复用上一次的正文 / ETag;任何写入(REST、MCP、项目删除)之后都不会拿旧的。
+//   /api/stats/routes —— 每个路由的耗时汇总,只给管理员。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gunzipSync } from "node:zlib";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-requirements-slim-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "SlimListPassw0rd!x";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let admin = { token: "", id: "" };
+let member = { token: "", id: "" };
+let scoped = { token: "", id: "" };
+let cache: { size: () => number; clear: () => void; generation: () => number };
+let gzipStats: { hits: number; misses: number };
+
+type R = { status: number; body: any; text: string; headers: Headers };
+async function send(token: string, method: string, path: string, payload?: unknown, headers: Record<string, string> = {}): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json", ...headers },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body, text, headers: res.headers };
+}
+const list = (t: string, qs = "", headers: Record<string, string> = {}) => send(t, "GET", `/api/requirements?network_id=${NET}${qs}`, undefined, headers);
+const create = async (t: string, card: Record<string, unknown>) => {
+  const r = await send(t, "POST", "/api/requirements", { network_id: NET, ...card });
+  expect(r.status).toBe(201);
+  return r.body.requirement as { id: string; updatedAt: string };
+};
+const patch = (t: string, id: string, p: Record<string, unknown>) => send(t, "PATCH", `/api/requirements/${id}?network_id=${NET}`, p);
+const del = (t: string, id: string) => send(t, "DELETE", `/api/requirements/${id}?network_id=${NET}`);
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const payload = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(payload.result.content[0].text);
+}
+const tick = () => new Promise(r => setTimeout(r, 5));
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`slim_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(a.ok).toBe(true);
+  admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [admin.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const mk = async (username: string) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  member = await mk(`slim_member_${stamp}`);
+  scoped = await mk(`slim_scoped_${stamp}`);
+  // member:看全部任务、全部 Agent(可缓存);scoped:只看相关任务(不缓存,且只收到看得见的卡的删除)。
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, scoped.id]);
+  cache = (await import("./requirements.js")).__requirementsListCacheForTest();
+  gzipStats = (await import("./http-gzip.js")).gzipCacheStats;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("view=summary", () => {
+  test("drops description and checklist bodies, keeps everything else, adds has_description / checklist_count", async () => {
+    const card = await create(admin.token, {
+      name: "slim-summary",
+      description: "一段很长的描述 ".repeat(200),
+      checklist: [{ text: "第一项", done: true }, { text: "第二项", done: false }, { text: "第三项", done: true }],
+    });
+    await create(admin.token, { name: "slim-empty" });
+    const full = await list(admin.token);
+    const summary = await list(admin.token, "&view=summary");
+    expect(full.status).toBe(200);
+    expect(summary.status).toBe(200);
+    expect(summary.body.view).toBe("summary");
+    expect(full.body.view).toBeUndefined();
+    expect(summary.body.capabilities).toContain("list_summary");
+    expect(summary.body.capabilities).toContain("changes");
+    const f = full.body.requirements.find((r: any) => r.id === card.id);
+    const s = summary.body.requirements.find((r: any) => r.id === card.id);
+    expect(f.description.length).toBeGreaterThan(1000);
+    expect(f.checklist).toHaveLength(3);
+    expect("description" in s).toBe(false);
+    expect("checklist" in s).toBe(false);
+    expect(s.has_description).toBe(true);
+    expect(s.checklist_count).toEqual({ total: 3, done: 2 });
+    const { description: _d, checklist: _c, ...rest } = f;
+    const { has_description: _h, checklist_count: _cc, ...sRest } = s;
+    expect(sRest).toEqual(rest);
+    const empty = summary.body.requirements.find((r: any) => r.name === "slim-empty");
+    expect(empty.has_description).toBe(false);
+    expect(empty.checklist_count).toEqual({ total: 0, done: 0 });
+    // 同样的卡、同样的顺序;全文在单卡接口上照旧拿得到
+    expect(summary.body.requirements.map((r: any) => r.id)).toEqual(full.body.requirements.map((r: any) => r.id));
+    const one = await send(admin.token, "GET", `/api/requirements/${card.id}?network_id=${NET}`);
+    expect(one.body.requirement.description).toBe(f.description);
+    expect(summary.text.length).toBeLessThan(full.text.length / 2);
+  });
+
+  test("view=full is the plain list; an unknown view is a 400", async () => {
+    const plain = await list(admin.token);
+    const explicit = await list(admin.token, "&view=full");
+    expect(explicit.body.requirements).toEqual(plain.body.requirements);
+    expect((await list(admin.token, "&view=tiny")).status).toBe(400);
+    expect((await list(admin.token, "&view=tiny")).body.error).toBe("invalid_view");
+  });
+});
+
+describe("changes=1", () => {
+  test("requires updated_since", async () => {
+    const r = await list(admin.token, "&changes=1");
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("updated_since_required");
+  });
+
+  test("returns only cards changed since, archived ones included, plus deleted ids and a server_time to continue from", async () => {
+    const keep = await create(admin.token, { name: "slim-keep" });
+    const edit = await create(admin.token, { name: "slim-edit" });
+    const arch = await create(admin.token, { name: "slim-arch" });
+    const gone = await create(admin.token, { name: "slim-gone" });
+    const first = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(new Date(Date.now() - 60_000).toISOString())}`);
+    expect(first.status).toBe(200);
+    const t0 = first.body.server_time as string;
+    expect(Date.parse(t0)).toBeGreaterThan(0);
+    expect(first.body.deleted).toEqual([]);
+    await tick();
+
+    expect((await patch(admin.token, edit.id, { name: "slim-edit-2" })).status).toBe(200);
+    expect((await patch(admin.token, arch.id, { archived: true })).status).toBe(200);
+    expect((await del(admin.token, gone.id)).status).toBe(200);
+
+    const delta = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    expect(delta.status).toBe(200);
+    const ids = delta.body.requirements.map((r: any) => r.id).sort();
+    expect(ids).toEqual([edit.id, arch.id].sort());
+    expect(delta.body.requirements.find((r: any) => r.id === arch.id).archived).toBe(true);
+    expect(delta.body.requirements.find((r: any) => r.id === edit.id).name).toBe("slim-edit-2");
+    expect(delta.body.deleted).toEqual([gone.id]);
+    expect(ids).not.toContain(keep.id);
+    expect(Date.parse(delta.body.tombstones_since)).toBeLessThan(Date.parse(t0));
+
+    // 接着读:什么都没变就是空的
+    const again = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(delta.body.server_time)}`);
+    expect(again.body.requirements).toEqual([]);
+    expect(again.body.deleted).toEqual([]);
+
+    // 与 view=summary 组合
+    const slim = await list(admin.token, `&changes=1&view=summary&updated_since=${encodeURIComponent(t0)}`);
+    expect(slim.body.requirements.every((r: any) => !("description" in r) && "checklist_count" in r)).toBe(true);
+
+    // 不带 changes 的 updated_since 与原来一样:归档的不回、没有 deleted
+    const legacy = await list(admin.token, `&updated_since=${encodeURIComponent(t0)}`);
+    expect(legacy.body.requirements.map((r: any) => r.id)).toEqual([edit.id]);
+    expect(legacy.body.deleted).toBeUndefined();
+    expect(legacy.body.server_time).toBeUndefined();
+  });
+
+  test("side effects that used to leave updated_at alone now show up: orphaned children, cleared project", async () => {
+    const parent = await create(admin.token, { name: "slim-parent" });
+    const child = await create(admin.token, { name: "slim-child", parent_id: parent.id });
+    const proj = await send(admin.token, "POST", "/api/requirements/projects", { network_id: NET, name: "slim-proj" });
+    expect(proj.status).toBe(201);
+    const inProj = await create(admin.token, { name: "slim-in-proj", project_id: proj.body.project.id });
+    await tick();
+    const t0 = new Date().toISOString();
+    await tick();
+    expect((await del(admin.token, parent.id)).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/projects/${proj.body.project.id}?network_id=${NET}`)).status).toBe(200);
+    const delta = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    const byId = new Map(delta.body.requirements.map((r: any) => [r.id, r]));
+    expect((byId.get(child.id) as any)?.parent_id).toBeNull();
+    expect((byId.get(inProj.id) as any)?.project_id).toBeNull();
+    expect(delta.body.deleted).toEqual([parent.id]);
+  });
+
+  test("a scoped member only hears about deletions of cards they could see", async () => {
+    const theirs = await create(admin.token, { name: "slim-theirs", owner: { kind: "user", id: scoped.id } });
+    const hidden = await create(admin.token, { name: "slim-hidden" });
+    const seen = await list(scoped.token);
+    expect(seen.body.requirements.map((r: any) => r.id)).toContain(theirs.id);
+    expect(seen.body.requirements.map((r: any) => r.id)).not.toContain(hidden.id);
+    await tick();
+    const t0 = new Date().toISOString();
+    await tick();
+    expect((await del(admin.token, theirs.id)).status).toBe(200);
+    expect((await del(admin.token, hidden.id)).status).toBe(200);
+    const mine = await list(scoped.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    expect(mine.body.deleted).toEqual([theirs.id]);
+    const all = await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(t0)}`);
+    expect(all.body.deleted.sort()).toEqual([theirs.id, hidden.id].sort());
+  });
+});
+
+describe("list cache", () => {
+  test("an unchanged table is served from the cache: same ETag, and If-None-Match still 304s", async () => {
+    cache.clear();
+    const a = await list(admin.token);
+    expect(cache.size()).toBe(1);
+    const b = await list(admin.token);
+    expect(b.headers.get("etag")).toBe(a.headers.get("etag"));
+    expect(b.text).toBe(a.text);
+    expect((await list(admin.token, "", { "If-None-Match": a.headers.get("etag")! })).status).toBe(304);
+  });
+
+  test("every kind of write invalidates it: REST patch, MCP update, checklist tick, delete", async () => {
+    const card = await create(admin.token, { name: "slim-cache", checklist: [{ text: "x", done: false }] });
+    const seen = async () => (await list(admin.token)).body.requirements.find((r: any) => r.id === card.id);
+    expect((await seen()).name).toBe("slim-cache");
+    await patch(admin.token, card.id, { name: "slim-cache-rest" });
+    expect((await seen()).name).toBe("slim-cache-rest");
+    const viaMcp = await mcp(admin.token, "requirements_update", { id: card.id, network_id: NET, name: "slim-cache-mcp" });
+    expect(viaMcp.ok).toBe(true);
+    expect((await seen()).name).toBe("slim-cache-mcp");
+    const item = (await seen()).checklist[0];
+    expect((await send(admin.token, "PATCH", `/api/requirements/${card.id}/checklist/${item.id}?network_id=${NET}`, { done: true })).status).toBe(200);
+    expect((await seen()).checklist[0].done).toBe(true);
+    await del(admin.token, card.id);
+    expect(await seen()).toBeUndefined();
+  });
+
+  test("a failed write still invalidates (the handler may have written before failing)", async () => {
+    const g = cache.generation();
+    await send(admin.token, "PATCH", `/api/requirements/does-not-exist?network_id=${NET}`, { name: "x" });
+    expect(cache.generation()).toBe(g + 1);
+    // 不是需求接口的写入不动代数
+    await send(admin.token, "POST", "/api/task", { alias: "nobody", task: "x" });
+    expect(cache.generation()).toBe(g + 1);
+  });
+
+  test("callers are cached separately; a member's access change is seen at once; scoped / agent-restricted members are never cached", async () => {
+    cache.clear();
+    await list(admin.token);
+    await list(member.token);
+    expect(cache.size()).toBe(2);
+    await list(scoped.token);
+    expect(cache.size()).toBe(2);
+    const { db } = await import("./db.js");
+    const before = await list(member.token);
+    db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+    const after = await list(member.token);
+    expect(after.body.requirements.length).toBeLessThan(before.body.requirements.length);
+    db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+    expect((await list(member.token)).body.requirements.length).toBe(before.body.requirements.length);
+    // Agent 受限(看得见哪些 Agent 取决于节点表)→ 不缓存
+    cache.clear();
+    db.run("UPDATE network_members SET agent_access = 'granted' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+    await list(member.token);
+    expect(cache.size()).toBe(0);
+    db.run("UPDATE network_members SET agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  });
+
+  test("changes=1 and search are not cached", async () => {
+    cache.clear();
+    await list(admin.token, `&changes=1&updated_since=${encodeURIComponent(new Date(0).toISOString())}`);
+    await list(admin.token, "&q=slim");
+    expect(cache.size()).toBe(0);
+  });
+
+  test("gzip of an unchanged list is computed once", async () => {
+    const before = { ...gzipStats };
+    const a = await fetch(`${BASE}/api/requirements?network_id=${NET}`, { headers: { Authorization: `Bearer ${admin.token}`, "Accept-Encoding": "gzip" }, decompress: false } as any);
+    const b = await fetch(`${BASE}/api/requirements?network_id=${NET}`, { headers: { Authorization: `Bearer ${admin.token}`, "Accept-Encoding": "gzip" }, decompress: false } as any);
+    expect(a.headers.get("content-encoding")).toBe("gzip");
+    const ga = new Uint8Array(await a.arrayBuffer());
+    const gb = new Uint8Array(await b.arrayBuffer());
+    expect(Buffer.from(gunzipSync(gb)).toString()).toBe(Buffer.from(gunzipSync(ga)).toString());
+    expect(gzipStats.hits).toBeGreaterThanOrEqual(before.hits + 1);
+    expect(JSON.parse(Buffer.from(gunzipSync(gb)).toString()).ok).toBe(true);
+  });
+});
+
+describe("GET /api/stats/routes", () => {
+  test("admin sees per-route timings with ids collapsed; a member gets 403", async () => {
+    await list(admin.token, "&view=summary");
+    const r = await send(admin.token, "GET", "/api/stats/routes?minutes=5");
+    expect(r.status).toBe(200);
+    const routes = r.body.routes.map((x: any) => x.route);
+    expect(routes).toContain("GET /api/requirements?view=summary");
+    expect(routes.some((x: string) => x.startsWith("PATCH /api/requirements/:id"))).toBe(true);
+    const row = r.body.routes.find((x: any) => x.route === "GET /api/requirements");
+    expect(row.count).toBeGreaterThan(0);
+    expect(row.max_ms).toBeGreaterThanOrEqual(row.avg_ms);
+    expect((await send(member.token, "GET", "/api/stats/routes")).status).toBe(403);
+  });
+});

package/src/requirements-mcp.test.ts

@@ -115,6 +115,21 @@ describe("requirements MCP tools", () => {
       expect(page.requirements.length).toBe(1);
       expect(page.has_more).toBe(true);
       expect((await s.call("requirements_list", { limit: 1, include_archived: true, cursor: page.next_cursor })).requirements[0].id).not.toBe(page.requirements[0].id);
+      // view / changes 透传(Hub capability list_summary / changes):精简行没有正文;增量带 deleted 与 server_time
+      const slim = await s.call("requirements_list", { view: "summary", include_archived: true });
+      const slimRow = slim.requirements.find((r: any) => r.id === id);
+      expect(slim.view).toBe("summary");
+      expect("description" in slimRow).toBe(false);
+      expect(typeof slimRow.checklist_count.total).toBe("number");
+      expect(typeof slimRow.has_description).toBe("boolean");
+      expect((await s.call("requirements_list", { view: "tiny" })).mcpError).toBe(true);
+      expect((await s.call("requirements_list", { changes: true })).error).toBe("updated_since_required");
+      const since = new Date(Date.now() - 1000).toISOString();
+      await s.call("requirements_update", { id: child.requirement.id, name: "子需求改名" });
+      const delta = await s.call("requirements_list", { changes: true, updated_since: since, view: "summary" });
+      expect(delta.requirements.map((r: any) => r.id)).toContain(child.requirement.id);
+      expect(Array.isArray(delta.deleted)).toBe(true);
+      expect(typeof delta.server_time).toBe("string");
     } finally { await s.close(); }
   });
 

package/src/requirements-migrate.ts

@@ -59,6 +59,27 @@ export function ensureNetworkTags(database: DbAdapter): void {
   `);
 }
 
+/**
+ * 删掉的卡留一条墓碑,给 GET /api/requirements?changes=1 报「这些 id 没了」(按 updated_since 增量同步的客户端
+ * 否则永远不知道一张卡被删了)。连同判断可见性要用的列一起存:受限成员只收到他本来看得见的卡的删除。
+ * 保留 30 天(requirements.ts TOMBSTONE_RETENTION_MS,写入时顺手清)。IF NOT EXISTS:重复执行无副作用。
+ */
+export function ensureRequirementTombstones(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_tombstones (
+      requirement_id    TEXT PRIMARY KEY,
+      network_id        TEXT NOT NULL,
+      deleted_at        TEXT NOT NULL,
+      project_id        TEXT,
+      owner_json        TEXT,
+      participants_json TEXT,
+      created_by        TEXT,
+      created_by_json   TEXT
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_tombstones_network ON requirement_tombstones(network_id, deleted_at)");
+}
+
 /** external_ref 在同一网络里唯一(只管有值的行)。IF NOT EXISTS:重复执行无副作用。 */
 export function ensureRequirementIndexes(database: DbAdapter): void {
   database.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_external_ref ON requirements(network_id, external_ref) WHERE external_ref IS NOT NULL");

package/src/requirements-people-http.test.ts

@@ -0,0 +1,114 @@
+// GET /api/requirements/people 的 display_name 字段 —— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+// test2123 在真实 PostgreSQL 上原样再跑一遍(COMMHUB_TEST_PG_URL)。
+//
+// name 保持原样:成员 = display_name,没设回落到用户名;节点 = display_name → alias → node_name(旧 app 只读它)。
+// display_name 另给一份,没设就是 "" —— 分享图等对外场景据此不把 admin 之类的账号名印出去。
+// 成员的 display_name 等于用户名也返回 "":register() 没给显示名时存的就是 username。
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-people-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+process.env.HOST = "127.0.0.1";
+const PW = "ReqPeoplePassw0rd!x";
+
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let owner = { token: "", id: "", username: "" };
+let named = { id: "" };
+let plain = { id: "", username: "" };
+let same = { id: "", username: "" };
+
+async function people(token: string) {
+  const res = await fetch(`${BASE}/api/requirements/people?network_id=${NET}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+beforeAll(async () => {
+  const { db } = await import("./db.js");
+  const { addNetworkMember, register } = await import("./auth.js");
+  const stamp = Date.now();
+  const o = register(`rp_owner_${stamp}`, PW, undefined, "");
+  expect(o.ok).toBe(true);
+  owner = { token: o.token!, id: o.user!.user_id, username: o.user!.username };
+  NET = o.network_id!;
+  const m = register(`rp_member_${stamp}`, PW, undefined, "");
+  expect(m.ok).toBe(true);
+  named = { id: m.user!.user_id };
+  addNetworkMember(NET, named.id, "member", owner.id, { taskAccess: "all" });
+  // owner:没有显示名(= 只有用户名);member:有显示名。
+  db.run("UPDATE users SET display_name = NULL WHERE user_id = ?1", [owner.id]);
+  db.run("UPDATE users SET display_name = ?1 WHERE user_id = ?2", ["Placeholder Person", named.id]);
+  // plain:注册时没给显示名 —— register() 存的是 display_name = username,不改。
+  const pl = register(`rp_plain_${stamp}`, PW);
+  expect(pl.ok).toBe(true);
+  plain = { id: pl.user!.user_id, username: pl.user!.username };
+  addNetworkMember(NET, plain.id, "member", owner.id, { taskAccess: "all" });
+  // same:显示名被显式设成和用户名一模一样。
+  const sm = register(`rp_same_${stamp}`, PW, undefined, "Placeholder Other");
+  expect(sm.ok).toBe(true);
+  same = { id: sm.user!.user_id, username: sm.user!.username };
+  addNetworkMember(NET, same.id, "member", owner.id, { taskAccess: "all" });
+  db.run("UPDATE users SET display_name = username WHERE user_id = ?1", [same.id]);
+  db.run("INSERT INTO nodes(node_id,node_name,alias,display_name,network_id) VALUES (?1,?2,?3,?4,?5)", ["rp-node-alias", "rp-node-name", "placeholder-alias", "", NET]);
+  db.run("INSERT INTO nodes(node_id,node_name,alias,display_name,network_id) VALUES (?1,?2,?3,?4,?5)", ["rp-node-named", "rp-node-name-2", "placeholder-alias-2", "Placeholder Agent", NET]);
+  db.run("INSERT INTO nodes(node_id,node_name,network_id) VALUES (?1,?2,?3)", ["rp-node-bare", "rp-node-bare-name", NET]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/requirements/people display_name", () => {
+  test("display_name is its own field, empty when unset; name keeps the username / alias fallback", async () => {
+    const r = await people(owner.token);
+    expect(r.status).toBe(200);
+    const find = (kind: string, id: string) => r.body.people.find((p: any) => p.kind === kind && p.id === id);
+    expect(find("user", owner.id)).toMatchObject({ name: owner.username, display_name: "", networkId: NET });
+    expect(find("user", named.id)).toMatchObject({ name: "Placeholder Person", display_name: "Placeholder Person" });
+    expect(find("node", "rp-node-alias")).toMatchObject({ name: "placeholder-alias", display_name: "" });
+    expect(find("node", "rp-node-named")).toMatchObject({ name: "Placeholder Agent", display_name: "Placeholder Agent" });
+    expect(find("node", "rp-node-bare")).toMatchObject({ name: "rp-node-bare-name", display_name: "" });
+    expect(r.body.people.every((p: any) => typeof p.display_name === "string")).toBe(true);
+  });
+
+  test("a member whose display_name is just the username gets display_name \"\" (name still the username)", async () => {
+    const { db } = await import("./db.js");
+    // 前提是真的:register() 没给显示名时存的就是用户名。
+    expect(db.get<{ display_name: string }>("SELECT display_name FROM users WHERE user_id = ?1", plain.id)!.display_name).toBe(plain.username);
+    const r = await people(owner.token);
+    const find = (id: string) => r.body.people.find((p: any) => p.kind === "user" && p.id === id);
+    expect(find(plain.id)).toMatchObject({ name: plain.username, display_name: "" });
+    expect(find(same.id)).toMatchObject({ name: same.username, display_name: "" });
+    // 显示名只是「包含」用户名、不等于它:照常返回。
+    db.run("UPDATE users SET display_name = ?1 WHERE user_id = ?2", [`${same.username} (placeholder)`, same.id]);
+    const r2 = await people(owner.token);
+    expect(r2.body.people.find((p: any) => p.kind === "user" && p.id === same.id)).toMatchObject({ display_name: `${same.username} (placeholder)` });
+    db.run("UPDATE users SET display_name = username WHERE user_id = ?1", [same.id]);
+  });
+
+  test("sort order is still by name, then id", async () => {
+    const r = await people(owner.token);
+    const users = r.body.people.filter((p: any) => p.kind === "user");
+    const sorted = [...users].sort((a: any, b: any) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : 1));
+    expect(users.map((p: any) => p.id)).toEqual(sorted.map((p: any) => p.id));
+  });
+
+  test("the existing fields keep their shape for old apps", async () => {
+    const r = await people(owner.token);
+    for (const p of r.body.people) {
+      expect(Object.keys(p).sort()).toEqual(["display_name", "id", "kind", "name", "networkId"]);
+      expect(typeof p.name).toBe("string");
+      expect(p.name.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/requirements.ts

@@ -3,15 +3,16 @@
 import { createHash } from "node:crypto";
 import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
 import { db, logAudit } from "./db.js";
+import { markGzipReusable } from "./http-gzip.js";
 import { applyTagOp, normalizeTags, parseTagOp, storedTags, type TagOp } from "./requirement-tags.js";
 import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-stats.js";
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
-import { isAgentRestricted, visibleAgents } from "./agent-access.js";
+import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
 import {
   addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject,
   isTaskScoped, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
-import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
+import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
 // 放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次。
@@ -22,6 +23,7 @@ ensureRequirementIndexes(db);
 ensureRequirementSeq(db);
 ensureRequirementCompletedAt(db);
 ensureNetworkTags(db);
+ensureRequirementTombstones(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -282,7 +284,8 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
   if (!current || current.network_id !== networkId) return jsonError("project_not_found", 404);
   if (req.method === "DELETE") {
     // 先把卡片上的引用置空,再删项目:卡片一张不少。
-    db.run("UPDATE requirements SET project_id = NULL WHERE project_id = ?1", [current.project_id]);
+    // 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]);
     deleteTaskGrantsForProject(current.project_id);
     return Response.json({ ok: true });
@@ -553,11 +556,19 @@ function operationOf(req: Request, url: URL): string {
  */
 export function conditionalJson(req: Request, payload: unknown): Response {
   const body = JSON.stringify(payload);
-  const etag = `W/"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
+  return conditionalBody(req, body, bodyEtag(body));
+}
+
+function bodyEtag(body: string): string {
+  return `W/"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
+}
+
+function conditionalBody(req: Request, body: string, etag: string): Response {
   // private:按用户可见范围生成,不能被共享缓存复用;no-cache:每次都要回来验证,不会拿旧表当新的。
   const headers = { ETag: etag, "Cache-Control": "private, no-cache" };
   if (ifNoneMatchHits(req.headers.get("if-none-match"), etag)) return new Response(null, { status: 304, headers });
-  return new Response(body, { headers: { ...headers, "Content-Type": "application/json;charset=utf-8" } });
+  // ETag 就是正文的哈希:同一份正文的 gzip 结果可以复用(http-gzip.ts)。
+  return markGzipReusable(new Response(body, { headers: { ...headers, "Content-Type": "application/json;charset=utf-8" } }), etag);
 }
 
 function ifNoneMatchHits(header: string | null, etag: string): boolean {
@@ -568,7 +579,9 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
 
 // tag_ops:有 POST /api/requirements/tags/ops(标签改名 / 合并 / 删除 / 颜色),GET /api/requirements/tags 带 counts / colors / can_manage。
 // search:GET 认 q=(服务端搜索,语义同 App 的任务搜索);paging:认 limit / cursor,响应带 has_more / next_cursor。
-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"] as const;
+// 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;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -929,8 +942,9 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   if (parent !== null) sql += parent === "none" ? " AND parent_id IS NULL" : ` AND parent_id = ?${params.push(parent)}`;
   if (q.get("top_level") === "1") sql += " AND parent_id IS NULL";
   // Explicit archived-only wins over the legacy include-all switch.
+  // changes=1 看得见「被归档」这一改动:默认连归档的一起回(行上 archived: true),客户端据此把它移出看板。
   if (q.get("archived") === "true") sql += " AND COALESCE(archived, 0) = 1";
-  else if (q.get("include_archived") !== "1") sql += " AND COALESCE(archived, 0) = 0";
+  else if (q.get("include_archived") !== "1" && q.get("changes") !== "1") sql += " AND COALESCE(archived, 0) = 0";
   return sql;
 }
 
@@ -993,9 +1007,106 @@ function hiddenFilterForScope(ctx: RequirementsRequestContext, nodeId: string):
   return false;
 }
 
+// ── 列表省流(2026-09-30,App「连接较慢 · 数据可能稍有延迟」)──
+// 生产:425 张卡、1447 条子任务,整张表 1 MB(gzip 240 KB),任务页每 15 s 读一次;中国经 RELAY 的链路上
+// 一次要好几秒。三件事,都是加法,旧 App 不带新参数就与原来逐字相同:
+//   1. view=summary:不带描述正文和子任务条目(打开一张卡再 GET /api/requirements/:id 读全文);
+//   2. changes=1 + updated_since:只回这之后改过的卡(含归档的),加上删掉的卡的 id 和下次用的 server_time;
+//   3. 表没变时不重算:按「调用者 + 查询」缓存上一次的正文和 ETag,需求表一有写入就作废(见 requirementsGeneration)。
+
+/** view=summary 的一行:去掉 description / checklist,换成 has_description 和 checklist_count。 */
+function toSummary<T extends { description: string; checklist: ChecklistItem[] }>(pub: T): Omit<T, "description" | "checklist"> & { has_description: boolean; checklist_count: { total: number; done: number } } {
+  const { description, checklist, ...rest } = pub;
+  return { ...rest, has_description: !!description, checklist_count: { total: checklist.length, done: checklist.filter(item => item.done).length } };
+}
+
+/** 墓碑保留多久。changes 的 updated_since 早于这之前,删除就可能漏报 —— 响应里的 tombstones_since 告诉客户端这个下限。 */
+export const TOMBSTONE_RETENTION_MS = 30 * 86_400_000;
+
+/** 删卡时留一条墓碑(连同判断「谁看得见」要用的列,受限成员只收到他本来看得见的卡的删除)。 */
+function recordTombstone(row: Row, deletedAt: string): void {
+  db.run(
+    `INSERT INTO requirement_tombstones (requirement_id, network_id, deleted_at, project_id, owner_json, participants_json, created_by, created_by_json)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+     ON CONFLICT(requirement_id) DO UPDATE SET deleted_at = excluded.deleted_at`,
+    [row.requirement_id, row.network_id, deletedAt, row.project_id || null, row.owner_json || null, row.participants_json || null, row.created_by || null, row.created_by_json || null],
+  );
+  db.run("DELETE FROM requirement_tombstones WHERE deleted_at < ?1", [new Date(Date.parse(deletedAt) - TOMBSTONE_RETENTION_MS).toISOString()]);
+}
+
+type TombstoneRow = { requirement_id: string; network_id: string; deleted_at: string; project_id: string | null; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null };
+
+/** updated_since 之后删掉的、调用者看得见的卡。同 id 又出现在表里的(不该有)不算删除。 */
+function deletedSince(ctx: RequirementsRequestContext, sinceIso: string): string[] {
+  const params: unknown[] = [sinceIso];
+  let sql = "SELECT requirement_id, network_id, deleted_at, project_id, owner_json, participants_json, created_by, created_by_json FROM requirement_tombstones WHERE deleted_at >= ?1";
+  sql = addHumanNetworkScope(sql, params, ctx.scope);
+  sql += " AND requirement_id NOT IN (SELECT requirement_id FROM requirements) ORDER BY deleted_at, requirement_id";
+  const caller = taskCaller(ctx);
+  return db.all<TombstoneRow>(sql, ...params).filter(row => canSeeTask(caller, row)).map(row => row.requirement_id);
+}
+
+/**
+ * 需求表的写入代数:每个经过 handleRequirementsRequest 的非 GET 请求处理完就 +1(REST 和 MCP 的写入都走它,
+ * tools.ts 调的是同一个处理函数)。列表缓存只在代数没变时复用。进程重启 = 缓存清空。
+ */
+let requirementsGeneration = 0;
+/** 缓存条目最长信任这么久:兜住不经过处理函数的改动(启动迁移、运维脚本直接改库)。 */
+export const LIST_CACHE_MAX_AGE_MS = 60_000;
+/** 只缓存不带搜索词的列表(搜索每打一个字就是一个新键),总共最多这么多字符(条目按最近使用淘汰)。 */
+const LIST_CACHE_MAX_CHARS = 16 * 1024 * 1024;
+type ListCacheEntry = { generation: number; acl: string; at: number; body: string; etag: string };
+const listCache = new Map<string, ListCacheEntry>();
+let listCacheChars = 0;
+function rememberList(key: string, entry: ListCacheEntry): void {
+  const old = listCache.get(key);
+  if (old) { listCache.delete(key); listCacheChars -= old.body.length; }
+  if (entry.body.length > LIST_CACHE_MAX_CHARS / 4) return;
+  listCache.set(key, entry);
+  listCacheChars += entry.body.length;
+  for (const [k, v] of listCache) {
+    if (listCacheChars <= LIST_CACHE_MAX_CHARS) break;
+    listCache.delete(k);
+    listCacheChars -= v.body.length;
+  }
+}
+
+/**
+ * 缓存能不能用、以及调用者权限的指纹。null = 这个调用者不缓存:受限成员(看得见哪些 Agent 取决于节点表)
+ * 和「只看相关任务」的成员(看得见哪些卡取决于项目授权)每次照旧现算。
+ * 其余调用者的输出只取决于需求表本身 + 他的角色 / 成员行:这些都放进指纹,变了就不命中。
+ */
+function listCacheAcl(ctx: RequirementsRequestContext): string | null {
+  const caller = taskCaller(ctx);
+  if (!caller) return `open:${ctx.isAdmin ? 1 : 0}:${ctx.isNodeToken ? 1 : 0}`;
+  if (restrictedNetworkIds(caller.userId).length > 0) return null;
+  const members = db.all<Record<string, unknown>>("SELECT * FROM network_members WHERE user_id = ?1 ORDER BY network_id", caller.userId);
+  const networks = members.map(m => String(m.network_id));
+  if (networks.some(networkId => isTaskScoped(caller.userId, networkId))) return null;
+  const role = db.get<{ role: string | null }>("SELECT role FROM users WHERE user_id = ?1", caller.userId)?.role ?? null;
+  return JSON.stringify({ role, members });
+}
+
+function listCacheKey(ctx: RequirementsRequestContext): string {
+  const sorted = [...ctx.url.searchParams.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return JSON.stringify({ u: ctx.auth?.userId ?? null, n: ctx.auth?.networkId ?? null, a: ctx.isAdmin, t: ctx.isNodeToken, s: ctx.scope, q: sorted });
+}
+
+/** Test-only. */
+export function __requirementsListCacheForTest() {
+  return { size: () => listCache.size, clear: () => { listCache.clear(); listCacheChars = 0; }, generation: () => requirementsGeneration };
+}
+
 export async function handleRequirementsRequest(ctx: RequirementsRequestContext): Promise<Response | null> {
-  const { req, url } = ctx;
+  const { url } = ctx;
   if (url.pathname !== "/api/requirements" && !url.pathname.startsWith("/api/requirements/")) return null;
+  if (ctx.req.method === "GET") return handleRequirementsRequestInner(ctx);
+  // 写完(成功与否)才 +1:之后的 GET 一定看得见这次写入。
+  try { return await handleRequirementsRequestInner(ctx); } finally { requirementsGeneration++; }
+}
+
+async function handleRequirementsRequestInner(ctx: RequirementsRequestContext): Promise<Response | null> {
+  const { req, url } = ctx;
   // 节点令牌只能做 NODE_TOKEN_OPERATIONS 里的事(读 / 建 / 改 / 勾子任务 / upsert / 读项目),
   // 而且只在它绑定的网络里 —— 范围由 scope 强制,写入再由 canWrite 核一次。
   if (ctx.isNodeToken && !NODE_TOKEN_OPERATIONS.has(operationOf(req, url))) return jsonError("user_token_required", 403);
@@ -1044,12 +1155,16 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   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);
-    const users = db.all<{ id: string; name: string }>(
-      "SELECT u.user_id AS id, COALESCE(NULLIF(u.display_name,''), u.username) AS name FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 ORDER BY name, id", networkId,
+    // name = 显示用的名字(没设 display_name 时回落到用户名 / alias,旧 app 只读它);display_name 单独给出、没设为 ""
+    // —— 分享图等对外场景据此判断「只有用户名」,不把 admin 之类的账号名印出去。
+    // 成员的 display_name 等于用户名也算「没设」:register() 在没给显示名时存的就是 username(auth.ts),
+    // 否则没设过显示名的账号(比如 admin)照样把账号名当显示名送出去。
+    const users = db.all<{ id: string; name: string; display_name: string }>(
+      "SELECT u.user_id AS id, COALESCE(NULLIF(u.display_name,''), u.username) AS name, CASE WHEN u.display_name IS NULL OR u.display_name = '' OR u.display_name = u.username THEN '' ELSE u.display_name END AS display_name FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 ORDER BY name, id", networkId,
     );
     const hidden = hiddenNodeFilter(ctx, networkId);
-    const nodes = db.all<{ id: string; name: string }>(
-      "SELECT node_id AS id, COALESCE(NULLIF(display_name,''), NULLIF(alias,''), node_name) AS name FROM nodes WHERE network_id=?1 ORDER BY name, id", networkId,
+    const nodes = db.all<{ id: string; name: string; display_name: string }>(
+      "SELECT node_id AS id, COALESCE(NULLIF(display_name,''), NULLIF(alias,''), node_name) AS name, COALESCE(display_name,'') AS display_name FROM nodes WHERE network_id=?1 ORDER BY name, id", networkId,
     ).filter(row => !hidden?.(row.id));
     return Response.json({ ok: true, people: [...users.map(row => ({ ...row, kind: 'user', networkId })), ...nodes.map(row => ({ ...row, kind: 'node', networkId }))] });
   }
@@ -1065,10 +1180,37 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     // q= / limit / cursor(requirements-search.ts)。都不带 = 旧行为:最新 500 张、同样的顺序。
     const lq = parseListQuery(url.searchParams);
     if ("error" in lq) return jsonError(lq.error, 400);
+    const view = url.searchParams.get("view");
+    if (view !== null && view !== "full" && view !== "summary") return jsonError("invalid_view", 400);
+    const changes = url.searchParams.get("changes") === "1";
+    if (changes && url.searchParams.get("updated_since") === null) return jsonError("updated_since_required", 400);
+    // changes 模式:server_time 取在读表之前,下次拿它当 updated_since,读表期间的写入不会漏(>= 会重复回一次,客户端按 id 覆盖)。
+    const serverTime = new Date().toISOString();
+    const cacheKey = changes || url.searchParams.get("q") ? null : listCacheKey(ctx);
+    const acl = cacheKey ? listCacheAcl(ctx) : null;
+    const generation = requirementsGeneration;
+    const cached = cacheKey && acl !== null ? listCache.get(cacheKey) : undefined;
+    if (cached && cached.generation === generation && cached.acl === acl && Date.now() - cached.at < LIST_CACHE_MAX_AGE_MS) {
+      listCache.delete(cacheKey!);
+      listCache.set(cacheKey!, cached);
+      return conditionalBody(ctx.req, cached.body, cached.etag);
+    }
     const page = listPage(ctx, filtered, params, lq);
+    const rows = page.rows.map(row => toPublicFor(ctx, row));
     // capabilities:客户端按这个决定显示哪些功能(预计完成能不能带时刻、有没有项目…),不用靠猜字段。
     // has_more / next_cursor:后面还有没有(带 cursor=next_cursor 再读一页)。旧客户端不认识,忽略即可。
-    return conditionalJson(ctx.req, { ok: true, requirements: page.rows.map(row => toPublicFor(ctx, row)), capabilities: REQUIREMENT_CAPABILITIES, has_more: page.hasMore, next_cursor: page.nextCursor });
+    const payload: Record<string, unknown> = { ok: true, requirements: view === "summary" ? rows.map(toSummary) : rows, capabilities: REQUIREMENT_CAPABILITIES, has_more: page.hasMore, next_cursor: page.nextCursor };
+    if (view === "summary") payload.view = "summary";
+    if (changes) {
+      const since = new Date(Date.parse(url.searchParams.get("updated_since")!)).toISOString();
+      payload.deleted = deletedSince(ctx, since);
+      payload.server_time = serverTime;
+      payload.tombstones_since = new Date(Date.parse(serverTime) - TOMBSTONE_RETENTION_MS).toISOString();
+    }
+    const body = JSON.stringify(payload);
+    const etag = bodyEtag(body);
+    if (cacheKey && acl !== null) rememberList(cacheKey, { generation, acl, at: Date.now(), body, etag });
+    return conditionalBody(ctx.req, body, etag);
   }
 
   if (url.pathname === "/api/requirements" && req.method === "POST") {
@@ -1139,8 +1281,10 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
     if (!canDeleteTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_delete_denied");
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
-    db.run("UPDATE requirements SET parent_id = NULL WHERE parent_id = ?1", [row.requirement_id]);
+    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);
     // 硬删除以前不留痕(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

@@ -0,0 +1,40 @@
+import { expect, test } from "bun:test";
+import { __resetRouteTimingForTest, recordRouteTiming, routeKey, routeStats, ROUTE_RING_SIZE } from "./route-timing";
+
+const u = (s: string) => new URL(`http://hub${s}`);
+
+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");
+  expect(routeKey("GET", u("/api/requirements?view=summary&network_id=n"))).toBe("GET /api/requirements?view=summary");
+  expect(routeKey("PATCH", u("/api/requirements/req_3f9a/checklist/c1"))).toBe("PATCH /api/requirements/:id/checklist/:id");
+  expect(routeKey("GET", u("/api/requirements/stats"))).toBe("GET /api/requirements/stats");
+  expect(routeKey("GET", u("/api/status?light=1"))).toBe("GET /api/status?light=1");
+  expect(routeKey("GET", u(`/api/nodes/${encodeURIComponent("通信牛")}/config`))).toBe("GET /api/nodes/:id/config");
+  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", () => {
+  __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;
+  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);
+  recordRouteTiming(req("/api/status?light=1"), at(100), res(), now - 10 * 60_000); // 窗口外
+  expect(recordRouteTiming(req("/ws"), 0, undefined, now)).toBeUndefined();
+  const stats = routeStats(60_000, now);
+  expect(stats.samples).toBe(3);
+  expect(stats.routes.map(r => r.route)).toEqual(["GET /api/requirements", "GET /api/status?light=1"]);
+  const r0 = stats.routes[0];
+  expect(r0.count).toBe(2);
+  expect(r0.bytes).toBe(1500);
+  expect(r0.max_ms).toBeGreaterThanOrEqual(29);
+  expect(r0.total_ms).toBeGreaterThanOrEqual(39);
+  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);
+  const after = routeStats(60_000, now);
+  expect(after.samples).toBe(ROUTE_RING_SIZE);
+  expect(after.routes.map(r => r.route)).toEqual(["GET /api/tasks"]);
+});

package/src/route-timing.ts

@@ -0,0 +1,70 @@
+// 每个路由的耗时环(2026-09-30):生产 hub 平均 ~24% CPU,但没有任何按路由的计时,也没有访问日志,
+// 说不清是谁在吃 CPU。这里在 fetch 入口记最近 ROUTE_RING_SIZE 个请求(路由形状、耗时、状态、字节),
+// GET /api/stats/routes(管理员 / master)按时间窗汇总。只在内存里,重启清空;不记 query 值、不记调用者。
+export const ROUTE_RING_SIZE = 4096;
+
+type Sample = { at: number; route: string; ms: number; status: number; bytes: number | null };
+const ring: Sample[] = [];
+let next = 0;
+
+/** 路由的形状:id / 别名 / 文件名这类段换成 :id,几个会改变载荷形状的参数保留(light / view / scope / changes)。 */
+const SHAPE_PARAMS = ["changes", "light", "scope", "view"];
+export function routeKey(method: string, url: URL): string {
+  const segments = url.pathname.split("/").map((seg, i) => {
+    if (i < 2 || !seg) return seg;
+    return /[0-9%]/.test(seg) || /[^\x20-\x7e]/.test(seg) || seg.length > 24 ? ":id" : seg;
+  });
+  const shape = SHAPE_PARAMS.filter(k => url.searchParams.has(k)).map(k => `${k}=${url.searchParams.get(k)}`).join("&");
+  return `${method} ${segments.join("/")}${shape ? `?${shape}` : ""}`;
+}
+
+/** 记一次请求;原样返回 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 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;
+  return res;
+}
+
+export type RouteStat = { route: string; count: number; total_ms: number; avg_ms: number; p95_ms: number; max_ms: number; bytes: number; errors: number };
+
+/** 最近 windowMs 内的样本按路由汇总,按总耗时降序。 */
+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[]>();
+  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);
+  }
+  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);
+    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,
+    };
+  }).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 };
+}
+
+/** Test-only. */
+export function __resetRouteTimingForTest(): void {
+  ring.length = 0;
+  next = 0;
+}

package/src/server.ts

@@ -61,6 +61,7 @@ import { stampTaskAuthOrigin, type TaskAuthOrigin } from "./task-auth-origin.js"
 import { diagnoseTask } from "./task-diagnostic.js";
 import { assertScheduledTaskBackendSupported, handleScheduledTaskRequest, startScheduledTaskScheduler } from "./scheduled-tasks.js";
 import { handleRequirementsRequest } from "./requirements.js";
+import { recordRouteTiming, routeStats } from "./route-timing.js";
 import { handleExternalScheduleEditRequest } from "./external-schedule-edits.js";
 import { recordDeliveredStaleEvents } from "./task-lifecycle-watcher.js";
 import { SIDE_THREAD_FEATURE_FLAG, SideThreadCoordinator, SideThreadPortRegistry, SideThreadStore, type SideThreadActor, type SideThreadAttachmentRef, type SideThreadExecutionPort } from "./side-thread.js";
@@ -903,7 +904,8 @@ return Bun.serve({
 
   async fetch(req, server) {
     // 2026-09-16 —— 所有 JSON/文本响应在客户端要求时 gzip(见 http-gzip.ts);SSE/流式/二进制原样。
-    return maybeGzipResponse(req, explainExpiredSession(req, await (async (): Promise<Response | undefined> => {
+    // 2026-09-30 —— 每个请求的路由形状 + 耗时进内存环(route-timing.ts),GET /api/stats/routes 看谁在吃 CPU。
+    return recordRouteTiming(req, performance.now(), await maybeGzipResponse(req, explainExpiredSession(req, await (async (): Promise<Response | undefined> => {
     const url = new URL(req.url, `http://localhost:${PORT}`);
 
     // ── CORS preflight ──
@@ -2126,6 +2128,16 @@ return Bun.serve({
     });
     if (requirementsResponse) return withCors(req, requirementsResponse);
 
+    // ── REST: per-route timing (ops-only, same gate as /api/stats/sse) ──
+    // ?minutes=N(默认 15,最多 1440):最近 N 分钟里每个路由的次数、总耗时、p95、最大、字节。
+    if (url.pathname === "/api/stats/routes" && req.method === "GET") {
+      if (restAuth && !isAdmin) {
+        return withCors(req, Response.json({ ok: false, error: "admin or master token required" }, { status: 403 }));
+      }
+      const minutes = Math.min(Math.max(Number(url.searchParams.get("minutes")) || 15, 1), 1440);
+      return withCors(req, Response.json({ ok: true, ...routeStats(minutes * 60_000) }));
+    }
+
     // ── #473 REST: SSE connection detail (ops-only) ──
     // The per-key breakdown /health used to expose anonymously: keys are
     // `{networkId}:{alias}` (+ `\0netobs:{networkId}` observer keys via
@@ -4235,7 +4247,7 @@ Security: ${SECURITY_LABEL}
 `,
       { status: 200, headers: { "Content-Type": "text/plain; charset=utf-8" } }   // #426
     ));
-    })()));
+    })())));
   },
 
   // ── WebSocket handler for tmux terminal streaming ──

package/src/tools.ts

@@ -5825,7 +5825,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_list",
-    "List requirement tasks in your network. Filters: seq (the per-network short number shown as #N), status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived; q = search title / description / owner, agent and participant names / project name / tags (space-separated terms are ANDed). Newest first, 500 per page by default (limit ≤ 1000); has_more + next_cursor → pass cursor for the next page. Each task carries children {total, done}.",
+    "List requirement tasks in your network. Filters: seq (the per-network short number shown as #N), status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived; q = search title / description / owner, agent and participant names / project name / tags (space-separated terms are ANDed). Newest first, 500 per page by default (limit ≤ 1000); has_more + next_cursor → pass cursor for the next page. Each task carries children {total, done}. view='summary' drops description and checklist bodies (adds has_description, checklist_count) — much smaller; use requirements_get for one task's full text. changes=true (needs updated_since) returns only tasks changed since then, archived ones included, plus deleted ids and server_time to pass as the next updated_since.",
     {
       network_id: z.string().max(200).optional(),
       seq: z.number().int().positive().optional().describe("short number (#N) of one task in this network"),
@@ -5838,12 +5838,15 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       include_archived: z.boolean().optional(),
       parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
       top_level: z.boolean().optional(), q: z.string().max(200).optional(), limit: z.number().int().min(1).max(1000).optional(), cursor: z.string().max(600).optional(),
+      view: z.enum(["full", "summary"]).optional().describe("summary = no description / checklist bodies (has_description, checklist_count instead)"),
+      changes: z.boolean().optional().describe("with updated_since: only tasks changed since then (archived included) + deleted ids + server_time"),
     },
     async (args) => {
       const q = new URLSearchParams();
-      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id", "q", "limit", "cursor"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id", "q", "limit", "cursor", "view"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
       if (args.include_archived) q.set("include_archived", "1");
       if (args.top_level) q.set("top_level", "1");
+      if (args.changes) q.set("changes", "1");
       return requirementsCall("GET", `/api/requirements${q.size ? `?${q}` : ""}`, args.network_id);
     },
   );