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

package/src/db-adapter.ts

@@ -10,7 +10,7 @@
  *   - datetime('now'[, offset])  →  to_char(... AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS')
  *     (timestamps stay TEXT on both backends, RFC-039 §4.1)
  *   - BLOB  →  BYTEA
- *   - INTEGER PRIMARY KEY AUTOINCREMENT  →  SERIAL PRIMARY KEY
+ *   - INTEGER PRIMARY KEY AUTOINCREMENT  →  BIGSERIAL PRIMARY KEY; INTEGER  →  BIGINT
  *   - ON CONFLICT(col) DO UPDATE SET  →  ON CONFLICT(col) DO UPDATE SET  (same syntax)
  */
 
@@ -125,6 +125,9 @@ export function sqliteToPostgres(sql: string): string {
   });
   // datetime('now') → UTC text of NOW()
   s = s.replace(/datetime\s*\(\s*'now'\s*\)/gi, pgUtcText("NOW()"));
+  // strftime('%Y-%m-%d %H:%M:%f', 'now') → the same text with milliseconds
+  s = s.replace(/strftime\s*\(\s*'%Y-%m-%d %H:%M:%f'\s*,\s*'now'\s*\)/gi,
+    "to_char(NOW() AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.MS')");
   // ── Parameter placeholders ──
   // ?1, ?2 → $1, $2  (positional params)
   s = s.replace(/\?(\d+)/g, (_, n) => `$${n}`);
@@ -132,8 +135,11 @@ export function sqliteToPostgres(sql: string): string {
   let idx = 0;
   s = s.replace(/\?(?!\d)/g, () => `$${++idx}`);
   // ── DDL translations ──
-  // INTEGER PRIMARY KEY AUTOINCREMENT → SERIAL PRIMARY KEY
-  s = s.replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, "SERIAL PRIMARY KEY");
+  // INTEGER PRIMARY KEY AUTOINCREMENT → BIGSERIAL PRIMARY KEY
+  s = s.replace(/INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi, "BIGSERIAL PRIMARY KEY");
+  // INTEGER → BIGINT: SQLite integers are 64-bit, and the Hub stores epoch
+  // milliseconds in INTEGER columns (a 32-bit PG integer overflows).
+  s = s.replace(/\bINTEGER\b/gi, "BIGINT");
   // BLOB → BYTEA
   s = s.replace(/\bBLOB\b/gi, "BYTEA");
   return s;
@@ -278,13 +284,19 @@ export class PgAdapter implements DbAdapter {
     return { changes: result.count };
   }
 
+  /** bun:sqlite also accepts get(sql, [a, b]); a lone array argument is the parameter list. */
+  private static bindArgs(params: any[]): any[] | undefined {
+    if (params.length === 1 && Array.isArray(params[0])) return params[0];
+    return params.length > 0 ? params : undefined;
+  }
+
   get<T = any>(sql: string, ...params: any[]): T | null {
-    const result = this.querySync(sql, params.length > 0 ? params : undefined);
+    const result = this.querySync(sql, PgAdapter.bindArgs(params));
     return (result.rows?.[0] as T) ?? null;
   }
 
   all<T = any>(sql: string, ...params: any[]): T[] {
-    const result = this.querySync(sql, params.length > 0 ? params : undefined);
+    const result = this.querySync(sql, PgAdapter.bindArgs(params));
     return (result.rows as T[]) ?? [];
   }
 
@@ -373,7 +385,54 @@ export function assertSafeTestDatabaseEnv(env: NodeJS.ProcessEnv = process.env):
  * explicit COMMHUB_DB (or a reviewed PostgreSQL DATABASE_URL), so forgetting
  * one fails before mkdir/open/write instead of touching the live Hub.
  */
+/**
+ * RFC-039 §9 — the one reviewed way a `bun test` process may use PostgreSQL.
+ *
+ * The inherited-DATABASE_URL guard stays absolute. A test that means to run
+ * on PostgreSQL names a *different* variable, COMMHUB_TEST_PG_URL, which is
+ * honoured only under NODE_ENV=test and only for a literal loopback host and
+ * a database called `anet_…_test`, so it cannot reach a real Hub database by
+ * accident. Error messages never carry credentials.
+ */
+export const TEST_PG_URL_ENV = "COMMHUB_TEST_PG_URL";
+const TEST_PG_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"]);
+const TEST_PG_DB_RE = /^anet_[a-z0-9_]*_test$/;
+const TEST_PG_QUERY_KEYS = new Set(["connect_timeout", "sslmode", "application_name"]);
+
+/** A PostgreSQL URL with user and password replaced, safe to print. */
+export function redactPgUrl(raw: string): string {
+  try {
+    const u = new URL(raw);
+    if (u.username || u.password) { u.username = "***"; u.password = ""; }
+    return u.toString();
+  } catch {
+    return "<unparseable URL>";
+  }
+}
+
+export function validateTestPgUrl(raw: string): string {
+  const refuse = (why: string) => new Error(
+    `[commhub] REFUSING ${TEST_PG_URL_ENV}=${redactPgUrl(raw)}: ${why}.\n` +
+    "  It is test-only: postgres(ql)://<user>:<password>@127.0.0.1|localhost|[::1][:port]/anet_<name>_test",
+  );
+  let u: URL;
+  try { u = new URL(raw); } catch { throw refuse("not a URL"); }
+  if (u.protocol !== "postgres:" && u.protocol !== "postgresql:") throw refuse("scheme must be postgres:// or postgresql://");
+  if (!TEST_PG_HOSTS.has(u.hostname)) throw refuse("host must be literally 127.0.0.1, localhost or ::1");
+  const dbName = decodeURIComponent(u.pathname.replace(/^\//, ""));
+  if (!TEST_PG_DB_RE.test(dbName)) throw refuse("database name must match /^anet_[a-z0-9_]*_test$/");
+  for (const key of u.searchParams.keys()) {
+    if (!TEST_PG_QUERY_KEYS.has(key)) throw refuse(`query parameter "${key}" is not allowed`);
+  }
+  return raw;
+}
+
 function resolveDatabaseTargetAfterGuard(env: NodeJS.ProcessEnv): DbTarget {
+  const testPgUrl = env[TEST_PG_URL_ENV];
+  if (env.NODE_ENV === "test" && testPgUrl) {
+    return { kind: "postgres", url: validateTestPgUrl(testPgUrl) };
+  }
+
   const dbUrl = env.DATABASE_URL;
   if (dbUrl && (dbUrl.startsWith("postgres://") || dbUrl.startsWith("postgresql://"))) {
     return { kind: "postgres", url: dbUrl };

package/src/db.ts

@@ -2007,7 +2007,7 @@ export function syncScheduledRunForTask(taskId: string, expectedNetworkId?: stri
     `SELECT task_id, network_id, status, completed_at
        FROM tasks
       WHERE task_id = ?1
-        AND (?2 IS NULL OR network_id = ?2)`,
+        AND (CAST(?2 AS TEXT) IS NULL OR network_id = ?2)`,
     taskId,
     expectedNetworkId ?? null,
   );
@@ -2073,3 +2073,9 @@ export function logTaskEvent(taskId: string, fromStatus: string | null, toStatus
     );
   } catch {}
 }
+
+// RFC-039 F3: queries break created_at ties with SQLite's implicit rowid
+// (insertion order). PostgreSQL has none, so give these tables a real one.
+if (db.dialect === "postgres") {
+  for (const table of ["nodes", "user_inbox"]) db.exec(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS rowid BIGSERIAL`);
+}

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);
+  });
+});

package/src/requirements-search.test.ts

@@ -0,0 +1,32 @@
+// requirements-search.ts 的纯函数:任务 ID 匹配(与 App 的 task-short-id.ts matchesTaskId 同一规则)。
+import { describe, expect, test } from "bun:test";
+import { matchesTaskId, parseListQuery, taskIdQuery } from "./requirements-search.js";
+
+const row = (id: string, seq: number | null) => ({ requirement_id: id, seq });
+
+describe("matchesTaskId", () => {
+  test("#N / N match seq exactly (#7 does not hit #70)", () => {
+    expect(matchesTaskId(row("req_a", 7), "#7")).toBe(true);
+    expect(matchesTaskId(row("req_a", 7), "7")).toBe(true);
+    expect(matchesTaskId(row("req_a", 70), "#7")).toBe(false);
+    expect(matchesTaskId(row("req_a", null), "#7")).toBe(false);
+  });
+  test("full id and 8+ char prefix, with or without req_; shorter prefixes do not count", () => {
+    const id = "req_0a1b2c3d-4e5f-6789-abcd-ef0123456789";
+    expect(matchesTaskId(row(id, 1), id)).toBe(true);
+    expect(matchesTaskId(row(id, 1), "0a1b2c3d")).toBe(true);
+    expect(matchesTaskId(row(id, 1), "req_0a1b2c3d-4")).toBe(true);
+    expect(matchesTaskId(row(id, 1), "0a1b2c3")).toBe(false);
+    expect(matchesTaskId(row(id, 1), "")).toBe(false);
+  });
+  test("taskIdQuery: trim, NFKC (full-width ＃７ → #7), lowercase", () => {
+    expect(taskIdQuery(" ＃７ ")).toBe("#7");
+    expect(taskIdQuery("REQ_0A1B")).toBe("req_0a1b");
+  });
+  test("parseListQuery: idQuery only when there are terms", () => {
+    const q = (s: string) => parseListQuery(new URLSearchParams(s)) as any;
+    expect(q("q=%EF%BC%83%EF%BC%97").idQuery).toBe("#7");
+    expect(q("q=%20%20").idQuery).toBe("");
+    expect(q("").idQuery).toBe("");
+  });
+});

package/src/requirements-search.ts

@@ -0,0 +1,138 @@
+// GET /api/requirements 的服务端搜索(q=)与分页(limit / cursor)。纯函数,requirements.ts 接线。
+//
+// 为什么要:列表一直是 `ORDER BY created_at DESC LIMIT 500`,App 的任务搜索只在读到的行里搜 ——
+// 生产一个网络已经 ~400 张卡,过了 500 最老的那些就搜不到、也翻不到。
+//
+// 语义与 App 的任务搜索(agent-network-app src/task-search.ts)一致,两边搜同一个词得到同一批卡:
+//   · 字段:标题、描述(去掉 markdown 图片 / 链接的地址,链接文字保留)、负责人 / 负责 Agent / 参与人的显示名、
+//     旧 assignee 文本、项目名、标签
+//   · NFKC(全角 → 半角)+ 小写;中文按子串;空白隔开的词是「且」,每个词可以落在不同字段,但不跨字段拼
+//   · 调用者看不见的节点(受限成员)在卡片上本来就被隐去,它的名字也不参与匹配 —— 否则 q= 就成了
+//     「这张卡是不是某个没授权给我的 Agent 负责」的探测器
+//
+// 分页:按 (created_at DESC, requirement_id DESC) 排,cursor = 上一页最后一行的这两个值(不透明的 base64url)。
+// 不带 limit / cursor / q 的旧请求:同样的 500 行、同样的顺序,响应只多两个字段 has_more / next_cursor。
+
+export const DEFAULT_LIST_LIMIT = 500;
+export const MAX_LIST_LIMIT = 1000;
+export const MAX_QUERY_LENGTH = 200;
+
+const fold = (s: string): string => s.normalize("NFKC").toLocaleLowerCase();
+
+/** 搜索词:归一后按空白切开,去重、去空。 */
+export function searchTerms(q: string): string[] {
+  return [...new Set(fold(q).split(/\s+/).filter(Boolean))];
+}
+
+/** 描述是 markdown:图片 / 链接的地址不参与搜索,链接文字保留;html 标签去掉。 */
+export function descriptionText(md: string | null | undefined): string {
+  if (!md) return "";
+  return md
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, " ");
+}
+
+type Ref = { kind?: unknown; id?: unknown } | null | undefined;
+export type SearchableRow = {
+  name: string;
+  description: string;
+  assignee: string;
+  tags: readonly string[];
+  project_id: string | null;
+  owner: Ref;
+  agent_owner: Ref;
+  participants: readonly Ref[] | unknown;
+};
+export type NameMaps = {
+  /** `user:<id>` / `node:<id>` → 显示名(看不见的节点不在里面)。 */
+  people: ReadonlyMap<string, string>;
+  /** project_id → 项目名。 */
+  projects: ReadonlyMap<string, string>;
+};
+
+const refName = (ref: Ref, maps: NameMaps): string => {
+  if (!ref || typeof ref !== "object" || typeof ref.id !== "string" || (ref.kind !== "user" && ref.kind !== "node")) return "";
+  return maps.people.get(`${ref.kind}:${ref.id}`) ?? "";
+};
+
+/** 一张卡能被搜到的文字,字段之间用换行隔开(一个词不会跨两个字段拼出来)。 */
+export function searchText(row: SearchableRow, maps: NameMaps): string {
+  const participants = Array.isArray(row.participants) ? row.participants as Ref[] : [];
+  return fold([
+    row.name,
+    descriptionText(row.description),
+    refName(row.owner, maps),
+    refName(row.agent_owner, maps),
+    ...participants.map(r => refName(r, maps)),
+    row.assignee,
+    row.project_id ? maps.projects.get(row.project_id) ?? "" : "",
+    ...row.tags,
+  ].filter(Boolean).join("\n"));
+}
+
+export function matchesTerms(row: SearchableRow, terms: readonly string[], maps: NameMaps): boolean {
+  if (!terms.length) return true;
+  const hay = searchText(row, maps);
+  return terms.every(t => hay.includes(t));
+}
+
+export type Cursor = { createdAt: string; id: string };
+
+export function encodeCursor(c: Cursor): string {
+  return Buffer.from(JSON.stringify([c.createdAt, c.id]), "utf8").toString("base64url");
+}
+
+export function decodeCursor(raw: string): Cursor | null {
+  if (!raw || raw.length > 600 || !/^[A-Za-z0-9_-]+$/.test(raw)) return null;
+  try {
+    const v = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+    if (!Array.isArray(v) || v.length !== 2 || typeof v[0] !== "string" || typeof v[1] !== "string" || !v[0] || !v[1]) return null;
+    return { createdAt: v[0], id: v[1] };
+  } catch {
+    return null;
+  }
+}
+
+export type ListQuery = { limit: number; cursor: Cursor | null; terms: string[]; /** 整句当任务 ID 去对(taskIdQuery);空 = 没有搜索。 */ idQuery: string };
+
+/**
+ * 任务 ID(同 App 的 task-short-id.ts matchesTaskId):「#42」「42」精确对短号 seq;完整 id,或 8 位以上的
+ * id 前缀(带不带 req_ 都行)对主键。整句当一个 ID —— 和文字匹配是「或」,不拆成「ID 且文字」。
+ * 全角「＃４２」先 NFKC 归一(ID 本身都是 ASCII)。
+ */
+export const taskIdQuery = (q: string): string => q.trim().normalize("NFKC").toLowerCase();
+export const seqOfQuery = (idQuery: string): number | null => {
+  const m = /^#?(\d{1,15})$/.exec(idQuery);
+  return m ? Number(m[1]) : null;
+};
+export function matchesTaskId(row: { requirement_id: string; seq?: number | null }, idQuery: string): boolean {
+  if (!idQuery) return false;
+  const n = seqOfQuery(idQuery);
+  if (n !== null) return typeof row.seq === "number" && row.seq === n;
+  const id = row.requirement_id.toLowerCase();
+  if (idQuery === id) return true;
+  const bare = idQuery.replace(/^req_/, "");
+  return bare.length >= 8 && id.replace(/^req_/, "").startsWith(bare);
+}
+
+/** 解析 limit / cursor / q。不合法 → 错误码(400)。都没带 = 旧行为(500 行、第一页、不搜)。 */
+export function parseListQuery(params: URLSearchParams): ListQuery | { error: string } {
+  let limit = DEFAULT_LIST_LIMIT;
+  const rawLimit = params.get("limit");
+  if (rawLimit !== null) {
+    if (!/^\d{1,5}$/.test(rawLimit)) return { error: "invalid_limit" };
+    limit = Number(rawLimit);
+    if (limit < 1 || limit > MAX_LIST_LIMIT) return { error: "invalid_limit" };
+  }
+  let cursor: Cursor | null = null;
+  const rawCursor = params.get("cursor");
+  if (rawCursor !== null && rawCursor !== "") {
+    cursor = decodeCursor(rawCursor);
+    if (!cursor) return { error: "invalid_cursor" };
+  }
+  const q = params.get("q") ?? "";
+  if (q.length > MAX_QUERY_LENGTH) return { error: "invalid_q" };
+  const terms = searchTerms(q);
+  return { limit, cursor, terms, idQuery: terms.length ? taskIdQuery(q) : "" };
+}