@sleep2agi/commhub-server 0.9.0-preview.8 → 0.9.0-preview.80

package/src/http-gzip.test.ts

@@ -0,0 +1,94 @@
+import { expect, test } from "bun:test";
+import { maybeGzipResponse, wantsGzip, isCompressibleResponse, trimLightTask, GZIP_MIN_BYTES, LIGHT_TASK_MAX_CHARS } from "./http-gzip";
+
+const big = JSON.stringify({ sessions: Array.from({ length: 200 }, (_, i) => ({ alias: `节点${i}`, task: "x".repeat(50) })) });
+const json = (body: string, extra: Record<string, string> = {}) =>
+  new Response(body, { status: 200, headers: { "Content-Type": "application/json; charset=utf-8", ...extra } });
+const reqWith = (ae?: string, method = "GET") =>
+  new Request("http://hub/api/status?light=1", { method, headers: ae === undefined ? {} : { "Accept-Encoding": ae } });
+
+test("wantsGzip reads Accept-Encoding, including q-values", () => {
+  expect(wantsGzip(reqWith("gzip, deflate, br"))).toBe(true);
+  expect(wantsGzip(reqWith("br;q=1.0, gzip;q=0.8"))).toBe(true);
+  expect(wantsGzip(reqWith("identity"))).toBe(false);
+  expect(wantsGzip(reqWith("gzip;q=0"))).toBe(false);
+  expect(wantsGzip(reqWith())).toBe(false);
+});
+
+test("a large JSON body is gzipped only when the client asked, and round-trips", async () => {
+  const out = await maybeGzipResponse(reqWith("gzip"), json(big));
+  expect(out!.headers.get("Content-Encoding")).toBe("gzip");
+  expect(out!.headers.get("Vary")).toContain("Accept-Encoding");
+  const bytes = new Uint8Array(await out!.arrayBuffer());
+  expect(bytes.byteLength).toBeLessThan(big.length / 3);
+  expect(Number(out!.headers.get("Content-Length"))).toBe(bytes.byteLength);
+  expect(new TextDecoder().decode(Bun.gunzipSync(bytes))).toBe(big);
+  expect(out!.headers.get("Content-Type")).toContain("application/json");
+
+  const plain = json(big);
+  expect(await maybeGzipResponse(reqWith(), plain)).toBe(plain); // untouched object
+});
+
+test("small, streamed, already-encoded, SSE, 204 and HEAD responses are left alone", async () => {
+  const small = json("{\"ok\":true}");
+  const outSmall = await maybeGzipResponse(reqWith("gzip"), small);
+  expect(outSmall!.headers.get("Content-Encoding")).toBeNull();
+  expect(await outSmall!.text()).toBe("{\"ok\":true}");
+  expect(GZIP_MIN_BYTES).toBe(1024);
+
+  const sse = new Response(new ReadableStream(), { headers: { "Content-Type": "text/event-stream" } });
+  expect(isCompressibleResponse(sse)).toBe(false);
+  expect(await maybeGzipResponse(reqWith("gzip"), sse)).toBe(sse);
+
+  const encoded = json(big, { "Content-Encoding": "br" });
+  expect(await maybeGzipResponse(reqWith("gzip"), encoded)).toBe(encoded);
+
+  const noContent = new Response(null, { status: 204 });
+  expect(await maybeGzipResponse(reqWith("gzip"), noContent)).toBe(noContent);
+
+  const head = json(big);
+  expect(await maybeGzipResponse(reqWith("gzip", "HEAD"), head)).toBe(head);
+
+  // /api/files downloads: Range replies and attachments keep their exact byte lengths (CI #509/#514 caught this)
+  const partial = new Response("x".repeat(4096), { status: 206, headers: { "Content-Type": "text/plain", "Content-Range": "bytes 0-4095/8192" } });
+  expect(await maybeGzipResponse(reqWith("gzip"), partial)).toBe(partial);
+  const attachment = new Response("y".repeat(4096), { status: 200, headers: { "Content-Type": "text/plain", "Content-Disposition": "attachment; filename=\"a.txt\"" } });
+  expect(await maybeGzipResponse(reqWith("gzip"), attachment)).toBe(attachment);
+
+  const binary = new Response(new Uint8Array(4096), { headers: { "Content-Type": "image/png" } });
+  expect(await maybeGzipResponse(reqWith("gzip"), binary)).toBe(binary);
+
+  expect(await maybeGzipResponse(reqWith("gzip"), undefined)).toBeUndefined();
+});
+
+test("trimLightTask keeps a one-line preview under the cap", () => {
+  expect(trimLightTask(null)).toBeNull();
+  expect(trimLightTask("   ")).toBeNull();
+  expect(trimLightTask("a\n  b")).toBe("a b");
+  const long = "字".repeat(LIGHT_TASK_MAX_CHARS + 40);
+  const t = trimLightTask(long)!;
+  expect(t.endsWith("…")).toBe(true);
+  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

@@ -0,0 +1,110 @@
+// 2026-09-16(Vincent:「发一个消息都要被吞一段时间」「打开窗口历史很久才出来」):
+// 桌面端经 RELAY 连 hub,链路实测只有 ~13 KB/s;/api/status?light=1 128 KB 要 17 s,
+// 一页 20 条任务 41 KB 要 5.6 s,而 hub 从不压缩。gzip 后 128 KB → 31 KB、137 KB → 49 KB。
+// 只在客户端明确 `Accept-Encoding: gzip` 时压;text/event-stream(SSE)与流式 body 一律不碰。
+export const GZIP_MIN_BYTES = 1024;
+
+const COMPRESSIBLE = /^(application\/json|text\/(plain|html|css|javascript)|application\/javascript)\b/i;
+
+export function wantsGzip(req: Request): boolean {
+  const ae = req.headers.get("accept-encoding") || "";
+  for (const part of ae.split(",")) {
+    const [coding, ...params] = part.trim().split(";").map((x) => x.trim());
+    if (coding.toLowerCase() !== "gzip") continue;
+    const q = params.find((x) => /^q=/i.test(x));
+    if (!q) return true;
+    const n = Number(q.slice(2));
+    return Number.isFinite(n) && n > 0;
+  }
+  return false;
+}
+
+export function isCompressibleResponse(res: Response): boolean {
+  // 只压完整的 200:206 Partial Content / Content-Range / 附件下载(Content-Disposition)都有自己的
+  // 字节语义(Range 客户端按 Content-Length 数字节),压了就错 —— CI 的 /api/files Range 测试抓到的。
+  if (res.status !== 200 || !res.body) return false;
+  if (res.headers.get("content-encoding") || res.headers.get("content-range") || res.headers.get("content-disposition")) return false;
+  const ct = res.headers.get("content-type") || "";
+  if (/text\/event-stream/i.test(ct)) return false;
+  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
+ * not compressible is returned untouched (same object).
+ */
+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 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 = got.gz;
+  const headers = new Headers(res.headers);
+  headers.set("Content-Encoding", "gzip");
+  headers.set("Content-Length", String(gz.byteLength));
+  const vary = headers.get("Vary");
+  headers.set("Vary", vary && !/accept-encoding/i.test(vary) ? `${vary}, Accept-Encoding` : (vary || "Accept-Encoding"));
+  return new Response(gz, { status: res.status, statusText: res.statusText, headers });
+}
+
+/** 轻量列表里的 task 只给列表预览用;全文占了 light 载荷的一半以上。 */
+export const LIGHT_TASK_MAX_CHARS = 160;
+export function trimLightTask(task: unknown): string | null {
+  if (typeof task !== "string") return null;
+  const t = task.replace(/\s+/g, " ").trim();
+  if (!t) return null;
+  return t.length > LIGHT_TASK_MAX_CHARS ? `${t.slice(0, LIGHT_TASK_MAX_CHARS)}…` : t;
+}

package/src/hub-timestamp.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { parseHubTimestamp } from "./hub-timestamp";
+
+const RAW = "2026-08-30 21:11:24";                    // sessions.last_seen_at 的真实取值
+const TRUE_UTC = Date.UTC(2026, 7, 30, 21, 11, 24);
+
+describe("parseHubTimestamp (#1650)", () => {
+  test("🔴 非 UTC 时区下也必须解出同一个 UTC 时刻", () => {
+    // `bun test` 把测试进程时区固定成 UTC(getTimezoneOffset() === 0)。
+    // 在 UTC 下,「补 Z」和「不补 Z」解析出**同一个数** —— 这个函数存在的那个
+    // 缺陷在测试进程里**结构上不可见**。所以这一条必须开 TZ≠UTC 的子进程。
+    // 实测:去掉补 Z,本文件其余各条**全绿**。
+    const child = `import { parseHubTimestamp } from ${JSON.stringify(import.meta.dir + "/hub-timestamp.ts")};
+process.stdout.write(new Date().getTimezoneOffset() + "," + parseHubTimestamp(${JSON.stringify(RAW)}));`;
+    const r = Bun.spawnSync(["bun", "-e", child], { env: { ...process.env, TZ: "Asia/Shanghai" } });
+    const [offset, parsed] = r.stdout.toString().trim().split(",");
+    // 🔴 先断言控制生效:子进程真的不在 UTC。否则 TZ 被忽略时这条又变成空测试。
+    expect(Number(offset)).not.toBe(0);
+    expect(parsed).toBe(String(TRUE_UTC));
+  });
+
+  test("已带 Z / ±HH:MM 的串不再追加时区", () => {
+    expect(parseHubTimestamp("2026-08-30T21:11:24Z")).toBe(TRUE_UTC);
+    expect(parseHubTimestamp("2026-08-30T22:11:24+01:00")).toBe(TRUE_UTC);
+  });
+
+  test("拿不到就返回 null,不返回一个看起来合理的数", () => {
+    for (const bad of [undefined, null, "", "  ", 0, 1788124284000, {}, [], "2026-08-30", "垃圾"]) {
+      expect(parseHubTimestamp(bad as unknown)).toBeNull();
+    }
+  });
+
+  test("🔴 INTEGER 列(epoch 毫秒)不归它管 —— 传数字必须返回 null,而不是悄悄接受", () => {
+    // external_schedule_edits.* 是 INTEGER。如果有人把本函数用在那儿,
+    // 应当立刻拿到 null 而不是一个错的时刻。
+    expect(parseHubTimestamp(TRUE_UTC)).toBeNull();
+  });
+});

package/src/hub-timestamp.ts

@@ -0,0 +1,27 @@
+/**
+ * #1650 — hub 的 TEXT 时间戳列是 SQLite `datetime('now')` 写的，
+ * 形如 `2026-08-30 21:11:24`：**UTC，但不带任何时区标记**。
+ *
+ * 🔴 `new Date(raw)` / `Date.parse(raw)` 对这种串按**本地时间**解析（ES 规范：
+ *    带时间的形式无偏移时视为本地时间），误差恰好等于主机时区偏移，**而且不报错**：
+ *
+ *      TZ=UTC                   误差  0h
+ *      TZ=Asia/Shanghai         误差 -8h   （看起来更陈旧）
+ *      TZ=America/Los_Angeles   误差 +7h   （看起来更新鲜 ← 朝好的一侧错）
+ *
+ * 🔴 **只对 TEXT 列用它。** 同一个字段名在不同表里可能是不同类型：
+ *      sessions.last_seen_at / licenses.expires_at   → TEXT（要用本函数）
+ *      external_schedule_edits.expires_at 等 4 列     → INTEGER（epoch 毫秒，直接 new Date 就对）
+ *    按字段名判会判错 —— 见 #1650 里的更正。
+ *
+ * 与 agent-network 侧的同名函数是**有意的重复**：server 包不依赖 agent-network，
+ * 仓里也没有共享 lib。两边各自带测试。
+ */
+export function parseHubTimestamp(raw: unknown): number | null {
+  if (typeof raw !== "string") return null;
+  const t = raw.trim();
+  if (!/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}/.test(t)) return null;
+  const hasZone = /([Zz]|[+-]\d{2}:?\d{2})$/.test(t);
+  const ms = Date.parse(t.replace(" ", "T") + (hasZone ? "" : "Z"));
+  return Number.isFinite(ms) ? ms : null;
+}

package/src/human-dm.ts

@@ -0,0 +1,215 @@
+// 多用户账号:人与人私信(同一网络里的两个用户之间)。
+//
+// 投递复用 user_inbox(与 send_desktop_message 同一张表、同一条 /events/users/me 推送、同一套
+// /api/messages?scope=user 未读与 ack),另外记下 sender_user_id —— 由 Hub 按发信人的用户令牌写入,
+// 不是客户端声称的 from_session。会话记录按 (收件人, sender_user_id) 双向取,所以发信人看得到自己发的。
+//
+// 与 Agent 权限无关:受限成员(看不到任何 Agent 的成员)照样能和网络里的其他人私信。
+
+import { db, uuidv4 } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { isAgentRestricted } from "./agent-access.js";
+import { pushUserEvent, hasUserSubscribers } from "./push.js";
+import { existsSync, readFileSync } from "fs";
+import { DM_FILE_SCOPE, FILE_ID_REGEX, indexEntryPath, validateAttachments, validateIndexEntry, type UploadIndexEntry } from "./uploads.js";
+import { restrictedMemberCanUseFile } from "./restricted-files.js";
+import { redactMessageRow } from "./redact-tokens.js";
+
+export const HUMAN_DM_KIND = "human_dm";
+const MAX_DM_CHARS = 10_000;
+
+export type HumanDmSendInput = {
+  networkId: string;
+  sender: { userId: string; username: string };
+  toUserId?: unknown;
+  toUsername?: unknown;
+  message?: unknown;
+  attachments?: unknown;
+  clientRequestId?: unknown;
+};
+
+export type HumanDmSendResult =
+  | { ok: true; message: Record<string, unknown>; delivered: boolean }
+  | { ok: false; error: string; status: number };
+
+export function sendHumanDm(input: HumanDmSendInput): HumanDmSendResult {
+  const { networkId, sender } = input;
+  if (!getUserNetworkRole(sender.userId, networkId)) return { ok: false, error: "not a member of this network", status: 403 };
+  const text = typeof input.message === "string" ? input.message : "";
+  if (text.length > MAX_DM_CHARS) return { ok: false, error: "message_too_long", status: 400 };
+
+  const byId = typeof input.toUserId === "string" && input.toUserId
+    ? db.get<{ user_id: string; username: string }>("SELECT user_id, username FROM users WHERE user_id = ?1", input.toUserId)
+    : null;
+  const byName = typeof input.toUsername === "string" && input.toUsername
+    ? db.get<{ user_id: string; username: string }>("SELECT user_id, username FROM users WHERE username = ?1", input.toUsername)
+    : null;
+  if (byId && byName && byId.user_id !== byName.user_id) return { ok: false, error: "dm_target_mismatch", status: 400 };
+  const target = byId ?? byName;
+  // 不存在与不在本网络同一个错误,不给用户名探测留差异。
+  if (!target || !getUserNetworkRole(target.user_id, networkId)) return { ok: false, error: "dm_target_not_in_network", status: 404 };
+  if (target.user_id === sender.userId) return { ok: false, error: "dm_to_self", status: 400 };
+
+  const attachments = validateAttachments(input.attachments);
+  if (!attachments.ok) return { ok: false, error: "bad_attachments", status: 400 };
+  if (!text.trim() && attachments.attachments.length === 0) return { ok: false, error: "message_required", status: 400 };
+  const restricted = isAgentRestricted(sender.userId, networkId);
+  for (const a of attachments.attachments) {
+    const fileId = (a as { file_id?: string }).file_id;
+    if (!fileId) continue;
+    const entry = networkFileEntry(networkId, fileId);
+    const usable = restricted
+      ? restrictedMemberCanUseFile(sender.userId, sender.username, networkId, fileId)
+      : !!entry;
+    if (!usable) return { ok: false, error: "attachment_not_accessible", status: 403 };
+    // 私信文件只能由看得见它的人转发:否则任何成员把别人私信里的 file_id 塞进一条自己发出的私信,
+    // 就成了「私信参与者」而解锁它。上传者本人、以及已经在某段私信里收到/发出过它的人可以转。
+    if (entry?.scope === DM_FILE_SCOPE && entry.owner_id !== sender.userId && !dmParticipantSeesFile(sender.userId, networkId, fileId)) {
+      return { ok: false, error: "attachment_not_accessible", status: 403 };
+    }
+  }
+
+  const clientRequestId = typeof input.clientRequestId === "string" && /^[A-Za-z0-9._-]{1,80}$/.test(input.clientRequestId)
+    ? input.clientRequestId : null;
+  // 同一个气泡重试:按 (发信人, client_request_id) 定出同一个 message_id,重投不产生第二条。
+  const messageId = clientRequestId
+    ? `dm_${sender.userId}_${clientRequestId}`.slice(0, 120)
+    : `dm_${uuidv4()}`;
+  const metaJson = attachments.attachments.length ? JSON.stringify({ attachments: attachments.attachments }) : null;
+
+  db.transaction(() => {
+    insertDmRow({ messageId, networkId, targetUserId: target.user_id, sender, title: null, text, metaJson });
+    db.run(
+      `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+       VALUES (?1, ?2, 'human_dm_sent', 'user', ?3, ?4, ?5)`,
+      [sender.userId, sender.username, target.user_id, JSON.stringify({ message_id: messageId, attachments: attachments.attachments.length }), networkId],
+    );
+  });
+  const row = db.get<Record<string, unknown>>(
+    `SELECT message_id, network_id, user_id, sender_user_id, from_session, kind, content, meta_json, acked, created_at
+       FROM user_inbox WHERE message_id = ?1`,
+    messageId,
+  )!;
+  // 推送在提交之后(与 send_desktop_message 同一条规矩:回滚的消息不能先被看见)。
+  const delivered = pushDmEvent({ messageId, networkId, targetUserId: target.user_id, sender, title: null, text, metaJson });
+  return { ok: true, message: redactMessageRow(row), delivered };
+}
+
+type DmRow = { messageId: string; networkId: string; targetUserId: string; sender: { userId: string; username: string }; title: string | null; text: string; metaJson: string | null };
+
+function insertDmRow(m: DmRow): void {
+  db.run(
+    // created_at 带毫秒:同一秒里一来一回的两条私信要能排出先后(秒级的 datetime('now') 排不出)。
+    `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, sender_user_id, created_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'info', ?8, ?9, strftime('%Y-%m-%d %H:%M:%f', 'now'))
+     ON CONFLICT(message_id) DO NOTHING`,
+    [m.messageId, m.networkId, m.targetUserId, m.sender.username, HUMAN_DM_KIND, m.title, m.text, m.metaJson, m.sender.userId],
+  );
+}
+
+/** 推 desktop_message 到收件人的 /events/users/me。返回推送时他有没有在线的订阅。 */
+function pushDmEvent(m: DmRow): boolean {
+  const delivered = hasUserSubscribers(m.networkId, m.targetUserId);
+  pushUserEvent(m.networkId, m.targetUserId, {
+    type: "desktop_message",
+    message_id: m.messageId,
+    kind: HUMAN_DM_KIND,
+    from: m.sender.username,
+    from_user_id: m.sender.userId,
+    title: m.title,
+    message: m.text,
+    severity: "info",
+    created_at: new Date().toISOString(),
+    ...(m.metaJson ? { meta: JSON.parse(m.metaJson) } : {}),
+  });
+  return delivered;
+}
+
+/**
+ * Hub 代某人发的一条私信(参与人改了任务的通知,见 requirement-notify.ts):与人发的私信同一张表、同一条推送,
+ * 所以 App 按私信展示(顶部提示 + 人员列表未读 + 与他的会话里能看到),不用新渠道。
+ * 不校验正文 / 附件(调用方生成),也不记 human_dm_sent 审计(这不是他亲手发的)。
+ * 收件人或发信人已不在网络里 → 不发。返回 false = 没发。
+ */
+export function sendNoticeDm(m: DmRow): boolean {
+  if (m.targetUserId === m.sender.userId) return false;
+  if (!getUserNetworkRole(m.sender.userId, m.networkId) || !getUserNetworkRole(m.targetUserId, m.networkId)) return false;
+  insertDmRow(m);
+  pushDmEvent(m);
+  return true;
+}
+
+/**
+ * 把一条还没读的通知私信改写成合并后的正文(同一段时间里的连续改动并成一条)。
+ * 收件人已经读过(acked)或那行没了 → false,调用方另发一条新的。
+ * 只改库、再推一次同一个 message_id:App 按 message_id 去重,不会第二次弹;会话列表下次拉到的是新正文。
+ */
+export function rewriteUnreadNoticeDm(m: DmRow): boolean {
+  const row = db.get<{ acked: number | boolean | null }>("SELECT acked FROM user_inbox WHERE message_id = ?1 AND user_id = ?2", m.messageId, m.targetUserId);
+  if (!row || row.acked) return false;
+  db.run("UPDATE user_inbox SET content = ?1, meta_json = ?2 WHERE message_id = ?3 AND user_id = ?4", [m.text, m.metaJson, m.messageId, m.targetUserId]);
+  pushDmEvent(m);
+  return true;
+}
+
+/** 带附件:文件必须属于这个网络(防把别的网络的 file_id 塞进来)。返回它的索引条目,不属于 → null。 */
+function networkFileEntry(networkId: string, fileId: string): UploadIndexEntry | null {
+  if (!FILE_ID_REGEX.test(fileId)) return null;
+  const path = indexEntryPath(fileId);
+  if (!path || !existsSync(path)) return null;
+  try {
+    const entry = JSON.parse(readFileSync(path, "utf8"));
+    return validateIndexEntry(entry) && entry.file_id === fileId && entry.network_id === networkId ? entry : null;
+  } catch { return null; }
+}
+
+/**
+ * 这个用户是不是某段带着这个文件的私信里的一方(收到的或发出的)。私信文件(scope=dm)的下载只认它
+ * 和上传者本人(server.ts authorizeFileDownload)。LIKE 只做预筛,真正的判定按 attachments 键解析。
+ */
+export function dmParticipantSeesFile(userId: string, networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const needle = `%"${fileId.replace(/_/g, "\\_")}"%`;
+  const rows = db.all<{ meta_json: string | null }>(
+    `SELECT meta_json FROM user_inbox
+      WHERE network_id = ?1 AND kind = '${HUMAN_DM_KIND}' AND (user_id = ?2 OR sender_user_id = ?2)
+        AND meta_json LIKE ?3 ESCAPE '\\' LIMIT 50`,
+    networkId, userId, needle,
+  );
+  return rows.some((row) => {
+    try {
+      const list = JSON.parse(row.meta_json ?? "null")?.attachments;
+      return Array.isArray(list) && list.some((a: any) => a && typeof a === "object" && a.file_id === fileId);
+    } catch { return false; }
+  });
+}
+
+/** 我和某人的私信记录(双向),新的在前。before = 上一页最后一条的 created_at。 */
+export function listDmThread(networkId: string, meUserId: string, otherUserId: string, limit = 50, before?: string | null) {
+  const params: unknown[] = [networkId, meUserId, otherUserId];
+  let sql = `SELECT message_id, network_id, user_id, sender_user_id, from_session, kind, content, meta_json, acked, created_at
+               FROM user_inbox
+              WHERE network_id = ?1 AND kind = '${HUMAN_DM_KIND}'
+                AND ((user_id = ?2 AND sender_user_id = ?3) OR (user_id = ?3 AND sender_user_id = ?2))`;
+  if (before) { params.push(before); sql += ` AND created_at < ?${params.length}`; }
+  params.push(Math.max(1, Math.min(limit, 200)));
+  sql += ` ORDER BY created_at DESC, rowid DESC LIMIT ?${params.length}`;
+  return db.all<Record<string, unknown>>(sql, ...params).map((row) => ({
+    ...redactMessageRow(row),
+    direction: row.sender_user_id === meUserId ? "out" : "in",
+  }));
+}
+
+/** 我在这个网络里的私信会话:每个对方一行,最后一条时间 + 我这边的未读数。 */
+export function listDmThreads(networkId: string, meUserId: string) {
+  return db.all<{ other_user_id: string; last_at: string; unread: number }>(
+    `SELECT other_user_id, MAX(created_at) AS last_at, SUM(unread) AS unread FROM (
+       SELECT sender_user_id AS other_user_id, created_at, CASE WHEN acked = 0 THEN 1 ELSE 0 END AS unread
+         FROM user_inbox WHERE network_id = ?1 AND user_id = ?2 AND kind = '${HUMAN_DM_KIND}' AND sender_user_id IS NOT NULL
+       UNION ALL
+       SELECT user_id AS other_user_id, created_at, 0 AS unread
+         FROM user_inbox WHERE network_id = ?1 AND sender_user_id = ?2 AND kind = '${HUMAN_DM_KIND}'
+     ) GROUP BY other_user_id ORDER BY last_at DESC`,
+    networkId, meUserId,
+  ).map((r) => ({ other_user_id: r.other_user_id, last_at: r.last_at, unread: Number(r.unread ?? 0) }));
+}