@sleep2agi/commhub-server 0.9.0-preview.71 → 0.9.0-preview.73

package/src/migrate-sqlite-to-pg.ts

@@ -0,0 +1,263 @@
+/**
+ * RFC-039 S5 — offline copy of a Hub's SQLite database into an EMPTY
+ * PostgreSQL database.
+ *
+ *   commhub-server migrate-to-pg --from <sqlite file> --to <postgres url>
+ *                                [--dry-run] [--i-know-this-is-a-copy]
+ *
+ * Contract:
+ *   - offline: no running process may have the source (or its -wal/-shm)
+ *     open (checked through /proc on Linux). A stopped Hub normally leaves a
+ *     -wal behind — that is expected, and its contents are included: the
+ *     source is opened read-only and read through a `VACUUM INTO` snapshot in
+ *     a private temp dir.
+ *   - never the live Hub's database: a source whose real path is under
+ *     ~/.commhub is refused unless --i-know-this-is-a-copy is given.
+ *   - empty target only: the target's `public` schema must hold no tables,
+ *     views, sequences or functions. The schema is then built by the Hub's
+ *     own module graph (no second copy of the DDL).
+ *   - one transaction: every table is copied and verified — row counts plus
+ *     a SHA-256 over canonicalised rows — before COMMIT; any mismatch or
+ *     error rolls everything back.
+ *   - --dry-run does all of the above, rolls back, and drops what it created,
+ *     leaving the target as it found it.
+ *   - the target URL is printed with credentials removed.
+ */
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { PgAdapter, redactPgUrl, type DbAdapter } from "./db-adapter.js";
+
+export type MigrateOptions = {
+  from: string;
+  to: string;
+  dryRun?: boolean;
+  allowCommhubCopy?: boolean;
+  home?: string;
+  log?: (line: string) => void;
+};
+
+export type TableReport = { table: string; rows: number; sha256: string };
+export type MigrateReport = { ok: true; dryRun: boolean; tables: TableReport[] };
+
+class DryRunRollback extends Error {}
+
+/** Refusals are thrown as MigrateRefused so the CLI can print them without a stack. */
+export class MigrateRefused extends Error {}
+
+function refuse(message: string): never {
+  throw new MigrateRefused(`[migrate-to-pg] REFUSING: ${message}`);
+}
+
+const quoteIdent = (name: string) => `"${name.replace(/"/g, '""')}"`;
+
+/** One canonical text per value, identical for bun:sqlite and PgAdapter output. */
+function canonical(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "bigint") return `i:${value.toString()}`;
+  if (typeof value === "number") return Number.isInteger(value) ? `i:${value}` : `f:${value}`;
+  if (value instanceof Uint8Array) return `b:${Buffer.from(value).toString("hex")}`;
+  if (typeof value === "string" && /^-?\d+$/.test(value) && value.length > 15) return `i:${value}`; // unsafe int8 comes back as text
+  return `s:${String(value)}`;
+}
+
+/** Order-independent digest: hash each row, sort the row hashes, hash the list. */
+function tableDigest(rows: Iterable<Record<string, unknown>>, cols: string[]): { rows: number; sha256: string } {
+  const rowHashes: string[] = [];
+  for (const row of rows) {
+    rowHashes.push(createHash("sha256").update(JSON.stringify(cols.map((c) => canonical(row[c])))).digest("hex"));
+  }
+  rowHashes.sort();
+  return { rows: rowHashes.length, sha256: createHash("sha256").update(rowHashes.join("\n")).digest("hex") };
+}
+
+function bindValue(value: unknown): unknown {
+  if (typeof value === "bigint") {
+    const n = Number(value);
+    return Number.isSafeInteger(n) ? n : value.toString();
+  }
+  return value;
+}
+
+function checkSource(from: string, home: string, allowCommhubCopy: boolean): string {
+  const abs = resolve(from);
+  if (!existsSync(abs)) refuse(`source ${abs} does not exist`);
+  const real = realpathSync(abs);
+  if (!statSync(real).isFile()) refuse(`source ${real} is not a file`);
+  const commhubDir = join(home, ".commhub");
+  const guarded = existsSync(commhubDir) ? realpathSync(commhubDir) : resolve(commhubDir);
+  if ((real === guarded || real.startsWith(guarded + sep)) && !allowCommhubCopy) {
+    refuse(`source ${real} is under ${guarded}, the live Hub's directory. Stop the Hub, copy the database elsewhere, ` +
+      "and migrate the copy — or pass --i-know-this-is-a-copy if this file already is one");
+  }
+  const holders = processesHolding([real, `${real}-wal`, `${real}-shm`]);
+  if (holders === null) {
+    console.warn("[migrate-to-pg] cannot inspect open files on this platform — make sure the Hub using this database is stopped");
+  } else if (holders.length) {
+    refuse(`${real} is open in running process(es) ${holders.join(", ")} — stop the Hub first`);
+  }
+  return real;
+}
+
+/** PIDs (other than ours) with any of `paths` open; null where /proc is unavailable. */
+function processesHolding(paths: string[]): number[] | null {
+  if (!existsSync("/proc/self/fd")) return null;
+  const wanted = new Set(paths);
+  const holders: number[] = [];
+  for (const entry of readdirSync("/proc")) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid) || pid === process.pid) continue;
+    let fds: string[];
+    try { fds = readdirSync(`/proc/${pid}/fd`); } catch { continue; } // gone, or another user's
+    for (const fd of fds) {
+      let target = "";
+      try { target = readlinkSync(`/proc/${pid}/fd/${fd}`); } catch { continue; }
+      if (wanted.has(target.replace(/ \(deleted\)$/, ""))) { holders.push(pid); break; }
+    }
+  }
+  return holders;
+}
+
+function publicObjectCount(pg: PgAdapter): number {
+  const row = pg.get<{ n: number }>(
+    `SELECT (SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.sequences WHERE sequence_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.routines WHERE routine_schema = 'public') AS n`,
+  );
+  return Number(row?.n ?? 0);
+}
+
+function dropEverythingInPublic(pg: DbAdapter) {
+  // Only ever called on a target that was verified empty before we started,
+  // so everything here was created by this run.
+  pg.exec(`DO $$ DECLARE r record; BEGIN
+    FOR r IN SELECT tablename FROM pg_tables WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP TABLE IF EXISTS public.' || quote_ident(r.tablename) || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = 'public' LOOP
+      EXECUTE 'DROP FUNCTION IF EXISTS ' || r.sig || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT sequencename FROM pg_sequences WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP SEQUENCE IF EXISTS public.' || quote_ident(r.sequencename) || ' CASCADE';
+    END LOOP;
+  END $$`);
+}
+
+export async function migrateSqliteToPg(opts: MigrateOptions): Promise<MigrateReport> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const home = opts.home ?? process.env.HOME ?? "";
+  if (!/^postgres(ql)?:\/\//.test(opts.to)) refuse("--to must be a postgres:// or postgresql:// URL");
+  const source = checkSource(opts.from, home, !!opts.allowCommhubCopy);
+  log(`[migrate-to-pg] source ${source}`);
+  log(`[migrate-to-pg] target ${redactPgUrl(opts.to)}${opts.dryRun ? " (dry run)" : ""}`);
+
+  // Empty-target check on a connection of our own, before the schema exists.
+  const probe = new PgAdapter(opts.to);
+  const existing = publicObjectCount(probe);
+  probe.close();
+  if (existing > 0) refuse(`target schema "public" is not empty (${existing} tables/sequences/functions). Migrate only into a new, empty database`);
+
+  // Snapshot the source: a consistent read that cannot touch the original.
+  const snapDir = mkdtempSync(join(tmpdir(), "anet-migrate-"));
+  const snapshot = join(snapDir, "snapshot.db");
+  try {
+    const original = new Database(source, { readonly: true });
+    original.exec(`VACUUM INTO '${snapshot.replace(/'/g, "''")}'`);
+    original.close();
+    const src = new Database(snapshot, { readonly: true, safeIntegers: true });
+
+    // Build the target schema exactly as the Hub does: import its module graph
+    // with DATABASE_URL pointing at the target.
+    delete process.env.COMMHUB_DB;
+    process.env.DATABASE_URL = opts.to;
+    await import("./server.js");
+    const { db } = await import("./db.js");
+    if (db.dialect !== "postgres") throw new Error("schema build did not select PostgreSQL");
+
+    const tables = (src.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all() as { name: string }[])
+      .map((r) => r.name);
+    const report: TableReport[] = [];
+
+    try {
+      db.transaction(() => {
+        for (const table of tables) {
+          const srcCols = (src.query(`PRAGMA table_info(${quoteIdent(table)})`).all() as { name: string }[]).map((c) => c.name);
+          const tgtCols = new Set(db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1", table,
+          ).map((c) => c.column_name));
+          const srcCount = Number((src.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(table)}`).get() as { n: bigint | number }).n);
+          if (tgtCols.size === 0) {
+            if (srcCount > 0) throw new Error(`table ${table} (${srcCount} rows) does not exist in the Hub's PostgreSQL schema`);
+            log(`[migrate-to-pg] skip ${table}: not in the PostgreSQL schema, and empty in the source`);
+            continue;
+          }
+          const missing = srcCols.filter((c) => !tgtCols.has(c));
+          if (missing.length && srcCount > 0) throw new Error(`table ${table}: column(s) ${missing.join(", ")} do not exist in PostgreSQL`);
+          const cols = srcCols.filter((c) => tgtCols.has(c));
+          // SQLite's implicit rowid carries insertion order; PostgreSQL keeps it
+          // in a real `rowid` column on the tables that sort by it (RFC-039 F3).
+          const copyRowid = tgtCols.has("rowid") && !srcCols.includes("rowid");
+          const selectCols = [...(copyRowid ? ["rowid AS rowid"] : []), ...cols.map(quoteIdent)].join(", ");
+          const insertCols = [...(copyRowid ? ["rowid"] : []), ...cols];
+
+          // Triggers are off only while this table is being filled. Re-enabled
+          // in `finally` so no path — including a failed batch — leaves them
+          // off; a rollback also restores them (DDL is transactional in PG).
+          db.exec(`ALTER TABLE ${quoteIdent(table)} DISABLE TRIGGER USER`);
+          try {
+            db.run(`DELETE FROM ${quoteIdent(table)}`); // rows the schema bootstrap seeded; the source is authoritative
+            const perBatch = Math.max(1, Math.floor(30000 / insertCols.length));
+            const stmt = src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)} ORDER BY rowid LIMIT ?1 OFFSET ?2`);
+            for (let offset = 0; offset < srcCount; offset += perBatch) {
+              const rows = stmt.all(perBatch, offset) as Record<string, unknown>[];
+              if (!rows.length) break;
+              const params: unknown[] = [];
+              const tuples = rows.map((row) => `(${insertCols.map((c) => { params.push(bindValue(row[c])); return `?${params.length}`; }).join(", ")})`);
+              db.run(`INSERT INTO ${quoteIdent(table)} (${insertCols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}`, params);
+            }
+          } finally {
+            db.exec(`ALTER TABLE ${quoteIdent(table)} ENABLE TRIGGER USER`);
+          }
+
+          // Sequences behind BIGSERIAL columns continue after the copied ids.
+          for (const seq of db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1 AND column_default LIKE 'nextval(%'", table,
+          )) {
+            db.get(`SELECT setval(pg_get_serial_sequence(?1, ?2), COALESCE((SELECT MAX(${quoteIdent(seq.column_name)}) FROM ${quoteIdent(table)}), 0) + 1, false)`,
+              table, seq.column_name);
+          }
+
+          // Verify before COMMIT.
+          const hashCols = copyRowid ? ["rowid", ...cols] : cols;
+          const srcDigest = tableDigest(src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)}`).all() as Record<string, unknown>[], hashCols);
+          const tgtDigest = tableDigest(db.all(`SELECT ${hashCols.map(quoteIdent).join(", ")} FROM ${quoteIdent(table)}`), hashCols);
+          if (srcDigest.rows !== tgtDigest.rows || srcDigest.sha256 !== tgtDigest.sha256) {
+            throw new Error(`verification failed for ${table}: source ${srcDigest.rows} rows ${srcDigest.sha256.slice(0, 12)}, ` +
+              `target ${tgtDigest.rows} rows ${tgtDigest.sha256.slice(0, 12)}`);
+          }
+          report.push({ table, rows: srcDigest.rows, sha256: srcDigest.sha256 });
+          log(`[migrate-to-pg] ${table}: ${srcDigest.rows} rows, sha256 ${srcDigest.sha256.slice(0, 16)} ✓`);
+        }
+        if (opts.dryRun) throw new DryRunRollback("dry run");
+      });
+    } catch (e) {
+      const rows = report.reduce((n, t) => n + t.rows, 0);
+      dropEverythingInPublic(db);
+      src.close();
+      if (!(e instanceof DryRunRollback)) {
+        const verify = e instanceof Error && e.message.startsWith("verification failed") ? "MISMATCH" : "NOT-REACHED";
+        log(`[migrate-to-pg] SUMMARY result=FAILED tables_verified=${report.length}/${tables.length} rows=${rows} verify=${verify} — rolled back, target left empty`);
+        throw e;
+      }
+      log(`[migrate-to-pg] SUMMARY result=DRY-RUN tables=${report.length} rows=${rows} verify=OK — rolled back, target left empty`);
+      return { ok: true, dryRun: true, tables: report };
+    }
+    src.close();
+    log(`[migrate-to-pg] SUMMARY result=COMMITTED tables=${report.length} rows=${report.reduce((n, t) => n + t.rows, 0)} verify=OK`);
+    return { ok: true, dryRun: false, tables: report };
+  } finally {
+    rmSync(snapDir, { recursive: true, force: true });
+  }
+}

package/src/push.ts

@@ -158,6 +158,10 @@ function closeClient(client: SSEClient, reason: string): void {
     // we're done with it.
   }
   console.log(`[${ts()}] SSE ✕ ${printableKey(client.key)} closed (reason=${reason})`);
+  if (isUserStreamClient(client)) {
+    touchUserSeen(client.subscriberUserId!);
+    if (!isUserOnline(client.subscriberUserId!)) notifyPresence(client.subscriberUserId!, false);
+  }
 }
 
 /** Best-effort enqueue with backpressure guard. Returns:
@@ -308,8 +312,11 @@ function createStreamForKey(
         ...(opts.eventFilter ? { eventFilter: opts.eventFilter } : {}),
       };
 
+      const presenceUser = isUserStreamClient(client) ? client.subscriberUserId! : null;
+      const wasOnline = presenceUser ? isUserOnline(presenceUser) : true;
       if (!clients.has(key)) clients.set(key, []);
       clients.get(key)!.push(client);
+      if (presenceUser) touchUserSeen(presenceUser);
       console.log(`[${ts()}] SSE ← ${printableKey(key)} connected (${clients.get(key)!.length} clients)`);
 
       // Send initial connected frame through the backpressure guard so
@@ -328,6 +335,7 @@ function createStreamForKey(
           return;
         }
         const result = tryEnqueueBytes(client, encoder.encode(`: keepalive\n\n`));
+        if (result === "ok" && isUserStreamClient(client)) touchUserSeen(client.subscriberUserId!);
         if (result === "dead") {
           // closeClient already cleared the timer; just make sure we
           // also prune from the map.
@@ -337,6 +345,8 @@ function createStreamForKey(
       (client.keepaliveTimer as any)?.unref?.();
 
       ensureLivenessSweep();
+      // 在线状态的广播放在 connected 帧之后:订阅方先拿到自己的 connected,再看到别人的变化。
+      if (presenceUser && !wasOnline) notifyPresence(presenceUser, true);
     },
     cancel() {
       // Consumer side hangup — straightforward path, mark closed and
@@ -523,6 +533,75 @@ export function pushUserEvent(
   if (needPrune) pruneClosed(key);
 }
 
+// ── 人类成员在线状态(人员列表的在线点)──────────────────────────────────
+// 判据就是上面这张用户流(/events/users/me)注册表:此刻有活着的用户流 = 在线。按**用户**算,
+// 不按网络 —— 桌面端同一时刻只连当前网络的用户流,按网络算会把正在别的网络里的人画成离线。
+// last_seen 只在内存:连上、每次 keepalive 成功、断开时刷新。Hub 重启后清空(未知 = null,
+// 调用方不要把 null 画成「很久以前」)。
+
+const userLastSeen = new Map<string, number>();
+let presenceListener: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null = null;
+
+function isUserStreamClient(client: SSEClient): boolean {
+  return !!client.subscriberUserId && client.key.startsWith(USER_KEY_PREFIX);
+}
+
+function touchUserSeen(userId: string): void {
+  userLastSeen.set(userId, Date.now());
+}
+
+function isUserOnline(userId: string): boolean {
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    if (arr.some((c) => !c.closed && c.subscriberUserId === userId)) return true;
+  }
+  return false;
+}
+
+function lastSeenIso(userId: string): string | null {
+  const ms = userLastSeen.get(userId);
+  return ms === undefined ? null : new Date(ms).toISOString();
+}
+
+function notifyPresence(userId: string, online: boolean): void {
+  if (!presenceListener) return;
+  try {
+    presenceListener(userId, online, lastSeenIso(userId));
+  } catch (e: any) {
+    console.log(`[${ts()}] presence listener failed: ${e?.message || e}`);
+  }
+}
+
+/** 用户的第一条用户流连上 / 最后一条断开时回调(server.ts 用它向同网络成员推 member_presence)。 */
+export function onUserPresenceChange(cb: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null): void {
+  presenceListener = cb;
+}
+
+/** 一批用户此刻的在线状态。鉴权由调用方负责。 */
+export function getUserPresence(userIds: readonly string[]): Map<string, { online: boolean; last_seen_at: string | null }> {
+  const online = new Set<string>();
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    for (const c of arr) if (!c.closed && c.subscriberUserId) online.add(c.subscriberUserId);
+  }
+  const out = new Map<string, { online: boolean; last_seen_at: string | null }>();
+  for (const uid of userIds) out.set(uid, { online: online.has(uid), last_seen_at: lastSeenIso(uid) });
+  return out;
+}
+
+/** 推给某网络里所有连着用户流的人(可排除一个)。鉴权由调用方负责。 */
+export function pushUserEventToNetwork(networkId: string, event: Record<string, unknown>, exceptUserId?: string): number {
+  const prefix = `${USER_KEY_PREFIX}${networkId}:`;
+  const recipients: string[] = [];
+  for (const key of clients.keys()) {
+    if (!key.startsWith(prefix)) continue;
+    const uid = key.slice(prefix.length);
+    if (uid && uid !== exceptUserId) recipients.push(uid);
+  }
+  for (const uid of recipients) pushUserEvent(networkId, uid, event);
+  return recipients.length;
+}
+
 /**
  * 多用户 Agent 权限:某用户在某网络的授权 / 成员资格变了,断开他在这个网络里**订阅时带了身份**
  * 的流(网络观察流、用户流),客户端重连时按新权限重新鉴权。返回断开的条数。
@@ -549,6 +628,7 @@ export function __resetSSEClientsForTest(): void {
     for (const c of arr) closeClient(c, "reset-for-test");
   }
   clients.clear();
+  userLastSeen.clear();
   if (livenessSweepTimer) {
     clearInterval(livenessSweepTimer);
     livenessSweepTimer = null;

package/src/requirements-http.test.ts

@@ -372,7 +372,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"]);
+    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"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {

package/src/requirements-mcp.test.ts

@@ -109,6 +109,12 @@ describe("requirements MCP tools", () => {
       expect((await s.call("requirements_list", { parent_id: id })).requirements.map((r: any) => r.id)).toEqual([child.requirement.id]);
       expect((await s.call("requirements_list", { top_level: true, include_archived: true })).requirements.some((r: any) => r.id === child.requirement.id)).toBe(false);
       expect((await s.call("requirements_update", { id, parent_id: child.requirement.id })).error).toBe("parent_cycle");
+      // q= / limit / cursor 透传到 GET /api/requirements
+      expect((await s.call("requirements_list", { q: "子需求" })).requirements.map((r: any) => r.id)).toEqual([child.requirement.id]);
+      const page = await s.call("requirements_list", { limit: 1, include_archived: true });
+      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);
     } finally { await s.close(); }
   });
 

package/src/requirements-migrate.ts

@@ -81,3 +81,64 @@ export function migrateRequirementPriorityCheck(database: DbAdapter): { rebuilt:
   });
   return { rebuilt: true };
 }
+
+/**
+ * 任务短号 seq:每个网络自己的 #1、#2…,界面显示和按 #N 查都用它。主键 requirement_id 不变。
+ * - 加可空列 seq;没有号的旧行按 created_at(再按 requirement_id)补号,接在该网络已有的最大号后面。
+ * - requirement_seq_counters 记每个网络发到过的最大号:删掉 / 归档的卡,号也不回收。
+ * - (network_id, seq) 唯一。重复执行只补还没号的行(回滚到旧 Hub 期间新建的卡)。
+ */
+export function ensureRequirementSeq(database: DbAdapter): { backfilled: number } {
+  try { database.exec("ALTER TABLE requirements ADD COLUMN seq INTEGER"); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
+  database.exec("CREATE TABLE IF NOT EXISTS requirement_seq_counters (network_id TEXT PRIMARY KEY, last_seq INTEGER NOT NULL DEFAULT 0)");
+  const pending = database.all<{ requirement_id: string; network_id: string; created_at: string | null }>(
+    "SELECT requirement_id, network_id, created_at FROM requirements WHERE seq IS NULL",
+  );
+  if (pending.length) {
+    // datetime('now') 的旧默认值「YYYY-MM-DD HH:MM:SS」是 UTC,和 ISO 混在一起时按字符串排会错位,换成毫秒再排。
+    const at = (v: string | null) => {
+      const s = v ?? "";
+      const ms = Date.parse(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(s) ? `${s.replace(" ", "T")}Z` : s);
+      return Number.isFinite(ms) ? ms : 0;
+    };
+    pending.sort((a, b) => a.network_id.localeCompare(b.network_id) || at(a.created_at) - at(b.created_at) || (a.requirement_id < b.requirement_id ? -1 : a.requirement_id > b.requirement_id ? 1 : 0));
+    database.transaction(() => {
+      const next = new Map<string, number>();
+      for (const row of pending) {
+        if (!next.has(row.network_id)) {
+          const max = database.get<{ m: number | null }>("SELECT MAX(seq) AS m FROM requirements WHERE network_id = ?1", row.network_id)?.m ?? 0;
+          const counter = database.get<{ last_seq: number }>("SELECT last_seq FROM requirement_seq_counters WHERE network_id = ?1", row.network_id)?.last_seq ?? 0;
+          next.set(row.network_id, Math.max(Number(max), Number(counter)));
+        }
+        const seq = next.get(row.network_id)! + 1;
+        next.set(row.network_id, seq);
+        database.run("UPDATE requirements SET seq = ?1 WHERE requirement_id = ?2 AND seq IS NULL", [seq, row.requirement_id]);
+      }
+    });
+  }
+  // 计数器不低于库里的最大号(补号之后、或计数器表是新建的)。
+  for (const row of database.all<{ network_id: string; m: number }>("SELECT network_id, MAX(seq) AS m FROM requirements WHERE seq IS NOT NULL GROUP BY network_id")) {
+    database.run(
+      `INSERT INTO requirement_seq_counters (network_id, last_seq) VALUES (?1, ?2)
+       ON CONFLICT(network_id) DO UPDATE SET last_seq = CASE WHEN excluded.last_seq > requirement_seq_counters.last_seq THEN excluded.last_seq ELSE requirement_seq_counters.last_seq END`,
+      [row.network_id, Number(row.m)],
+    );
+  }
+  database.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_network_seq ON requirements(network_id, seq) WHERE seq IS NOT NULL");
+  return { backfilled: pending.length };
+}
+
+/**
+ * 给新卡领下一个号。调用方把它和 INSERT 放在同一个事务里:插入失败(client_id / external_ref 撞了)号也一起回滚。
+ * 一条语句完成「读 + 加一 + 写回」,两个并发的新建拿不到同一个号;(network_id, seq) 唯一索引兜底。
+ */
+export function nextRequirementSeq(database: DbAdapter, networkId: string): number {
+  const row = database.get<{ last_seq: number }>(
+    `INSERT INTO requirement_seq_counters (network_id, last_seq)
+     VALUES (?1, COALESCE((SELECT MAX(seq) FROM requirements WHERE network_id = ?1), 0) + 1)
+     ON CONFLICT(network_id) DO UPDATE SET last_seq = requirement_seq_counters.last_seq + 1
+     RETURNING last_seq`,
+    networkId,
+  );
+  return Number(row!.last_seq);
+}

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

@@ -0,0 +1,182 @@
+// GET /api/requirements 的 q= 服务端搜索与 limit / cursor 分页(requirements-search.ts)。一次性 hub:临时 DB、端口 0。
+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-search-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+let server: { port: number; stop?: (force?: boolean) => void };
+let base = "";
+let token = "";
+let otherToken = "";
+let net = "";
+let db: any;
+
+async function api(tok: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${tok}`, "Content-Type": "application/json", ...(init?.headers || {}) } });
+  return { status: res.status, body: await res.json() as any };
+}
+const list = (query: string, tok = token) => api(tok, `/api/requirements?network_id=${net}${query ? `&${query}` : ""}`);
+const ids = async (query: string, tok = token) => {
+  const r = await list(query, tok);
+  expect(r.status).toBe(200);
+  return (r.body.requirements as any[]).map(x => x.name);
+};
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const owner = register(`search_owner_${Date.now()}`, "SearchOwner123!", undefined, "seed");
+  token = owner.token!;
+  net = owner.network_id!;
+  const other = register(`search_other_${Date.now()}`, "SearchOther123!", undefined, "seed");
+  otherToken = other.token!;
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+  db.run("INSERT INTO nodes(node_id,node_name,alias,display_name,network_id) VALUES (?1,?2,?2,?3,?4)", ["n_search_a", "portal-cow", "示例-门户牛", net]);
+  const project = await api(token, "/api/requirements/projects", { method: "POST", body: JSON.stringify({ name: "示例门户项目", network_id: net }) });
+  const pid = project.body.project.id;
+  const mk = (name: string, extra: Record<string, unknown> = {}) => api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name, network_id: net, ...extra }) });
+  await mk("企业组织树权限设置");
+  await mk("Portal Token 管理 | 估算成本卡布局", { agent_owner: { kind: "node", id: "n_search_a" }, tags: ["前端"] });
+  await mk("Space 网络策略 | 历史 receipt 误报", { description: "看 ![截图](/api/files/abc123) 和 [链接文字](https://example.com/x),重启导致 binding 丢失" });
+  await mk("子项目的卡", { project_id: pid });
+  const arch = await mk("已归档的组织树旧方案");
+  await api(token, `/api/requirements/${arch.body.requirement.id}`, { method: "PATCH", body: JSON.stringify({ archived: true }) });
+  await api(otherToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "别的网络的组织树" }) });
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("q= server-side search (same semantics as the app's task search)", () => {
+  test("title substring, CJK, case-insensitive, full-width input", async () => {
+    expect(await ids("q=" + encodeURIComponent("组织树"))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=portal")).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("ＰＯＲＴＡＬ"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+  });
+  test("agent owner display name, tags, project name, description text (not URLs)", async () => {
+    expect(await ids("q=" + encodeURIComponent("门户牛"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("前端"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("示例门户项目"))).toEqual(["子项目的卡"]);
+    expect(await ids("q=binding")).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    expect(await ids("q=" + encodeURIComponent("链接文字"))).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    expect(await ids("q=abc123")).toEqual([]);
+    expect(await ids("q=example.com")).toEqual([]);
+  });
+  test("space-separated terms are ANDed across fields", async () => {
+    expect(await ids("q=" + encodeURIComponent("成本 门户牛"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+    expect(await ids("q=" + encodeURIComponent("成本 receipt"))).toEqual([]);
+  });
+  test("archived only with archived=true / include_archived=1; other networks never", async () => {
+    expect(await ids("q=" + encodeURIComponent("组织树"))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("archived=true&q=" + encodeURIComponent("组织树"))).toEqual(["已归档的组织树旧方案"]);
+    expect((await ids("include_archived=1&q=" + encodeURIComponent("组织树"))).sort()).toEqual(["企业组织树权限设置", "已归档的组织树旧方案"].sort());
+  });
+  test("combines with the other filters", async () => {
+    expect(await ids("status=done&q=portal")).toEqual([]);
+    expect(await ids("agent_owner=node:n_search_a&q=" + encodeURIComponent("成本"))).toEqual(["Portal Token 管理 | 估算成本卡布局"]);
+  });
+  test("empty / whitespace q = no search; too long q = 400", async () => {
+    expect((await ids("q=")).length).toBe(4);
+    expect((await ids("q=%20%20")).length).toBe(4);
+    const r = await list("q=" + "x".repeat(201));
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("invalid_q");
+  });
+});
+
+describe("q= also matches task ids: #N / N on seq (#2139), full id and 8+ char prefix", () => {
+  const idOf = async (name: string) => (await list("limit=1000&include_archived=1")).body.requirements.find((r: any) => r.name === name).id as string;
+  test("full id and id prefix (with or without req_), not shorter prefixes", async () => {
+    const id = await idOf("企业组织树权限设置");
+    const bare = id.replace(/^req_/, "");
+    expect(await ids("q=" + encodeURIComponent(id))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=" + encodeURIComponent(id.toUpperCase()))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=" + encodeURIComponent(bare.slice(0, 10)))).toEqual(["企业组织树权限设置"]);
+    expect(await ids("q=" + encodeURIComponent(`req_${bare.slice(0, 9)}`))).toEqual(["企业组织树权限设置"]);
+    // 7 位以下的前缀不算 ID(否则输入几个字母就搜出一堆)
+    expect(await ids("q=" + encodeURIComponent(`req_${bare.slice(0, 5)}`))).toEqual([]);
+  });
+  test("#N / full-width ＃Ｎ / padded #N match the task's seq (#2139); #N plus text is plain text; filters still apply", async () => {
+    const target = await idOf("Space 网络策略 | 历史 receipt 误报");
+    const n = db.get("SELECT seq FROM requirements WHERE requirement_id = ?1", target).seq as number;
+    expect(typeof n).toBe("number");
+    expect(await ids(`q=%23${n}`)).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    const fullWidth = `＃${String(n).replace(/\d/g, d => String.fromCharCode(0xff10 + Number(d)))}`;
+    expect(await ids("q=" + encodeURIComponent(fullWidth))).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    expect(await ids("q=" + encodeURIComponent(` #${n} `))).toEqual(["Space 网络策略 | 历史 receipt 误报"]);
+    // 「#N receipt」整句不是 ID,只按文字「且」:没有卡同时含「#N」和「receipt」
+    expect(await ids("q=" + encodeURIComponent(`#${n} receipt`))).toEqual([]);
+    // ID 命中也受筛选管
+    expect(await ids(`status=done&q=%23${n}`)).toEqual([]);
+  });
+});
+
+describe("paging: limit / cursor / has_more / next_cursor", () => {
+  test("no params: legacy shape plus has_more=false, next_cursor=null, capabilities advertise search + paging", async () => {
+    const r = await list("");
+    expect(r.body.requirements.length).toBe(4);
+    expect(r.body.has_more).toBe(false);
+    expect(r.body.next_cursor).toBeNull();
+    expect(r.body.capabilities).toContain("search");
+    expect(r.body.capabilities).toContain("paging");
+  });
+  test("walking pages returns every row exactly once, newest first, including same-timestamp ties", async () => {
+    // 25 张,其中 10 张同一个 created_at(翻页边界落在并列上也不能漏 / 重)
+    const same = new Date(Date.now() + 60_000).toISOString();
+    for (let i = 0; i < 25; i++) {
+      const c = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: `页-${String(i).padStart(2, "0")}`, network_id: net }) });
+      if (i >= 10 && i < 20) db.run("UPDATE requirements SET created_at = ?1 WHERE requirement_id = ?2", [same, c.body.requirement.id]);
+    }
+    const full = await ids("limit=1000");
+    expect(full.length).toBe(29);
+    const seen: string[] = [];
+    let cursor = "";
+    let pages = 0;
+    for (;;) {
+      const r = await list(`limit=7${cursor ? `&cursor=${cursor}` : ""}`);
+      expect(r.status).toBe(200);
+      seen.push(...r.body.requirements.map((x: any) => x.name));
+      pages++;
+      if (!r.body.has_more) { expect(r.body.next_cursor).toBeNull(); break; }
+      expect(typeof r.body.next_cursor).toBe("string");
+      cursor = r.body.next_cursor;
+      expect(pages).toBeLessThan(10);
+    }
+    expect(pages).toBe(5);
+    expect(seen).toEqual(full);
+    expect(new Set(seen).size).toBe(29);
+  });
+  test("q= pages too", async () => {
+    const first = await list("limit=4&q=" + encodeURIComponent("页-"));
+    expect(first.body.requirements.length).toBe(4);
+    expect(first.body.has_more).toBe(true);
+    const rest = await list(`limit=100&q=${encodeURIComponent("页-")}&cursor=${first.body.next_cursor}`);
+    expect(rest.body.requirements.length).toBe(21);
+    expect(rest.body.has_more).toBe(false);
+  });
+  test("default limit stays 500 (legacy clients see the same cap)", async () => {
+    const { DEFAULT_LIST_LIMIT } = await import("./requirements-search.js");
+    expect(DEFAULT_LIST_LIMIT).toBe(500);
+  });
+  test("bad limit / cursor → 400", async () => {
+    for (const q of ["limit=0", "limit=1001", "limit=abc", "limit=-1", "cursor=%%%", "cursor=bm9wZQ"]) {
+      const r = await list(q);
+      expect(r.status).toBe(400);
+      expect(["invalid_limit", "invalid_cursor"]).toContain(r.body.error);
+    }
+  });
+  test("ETag still works with the new fields", async () => {
+    const first = await fetch(`${base}/api/requirements?network_id=${net}&limit=5`, { headers: { Authorization: `Bearer ${token}` } });
+    const etag = first.headers.get("etag")!;
+    await first.text();
+    const again = await fetch(`${base}/api/requirements?network_id=${net}&limit=5`, { headers: { Authorization: `Bearer ${token}`, "If-None-Match": etag } });
+    expect(again.status).toBe(304);
+  });
+});