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

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

@@ -0,0 +1,192 @@
+// 任务短号 seq:新建领号(并发不撞)、按网络各自编号、按 #N 查 / 改、删除和归档不回收号、MCP 工具也收 #N。
+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-seq-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+let server: { port: number; stop?: (force?: boolean) => void };
+let base = "";
+let ownerToken = "", otherToken = "", nodeToken = "";
+let ownerNet = "", otherNet = "", ownerId = "", otherId = "";
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...(init?.headers || {}) } });
+  return { status: res.status, body: await res.json() as any };
+}
+const create = (token: string, body: Record<string, unknown>, query = "") => api(token, `/api/requirements${query}`, { method: "POST", body: JSON.stringify(body) });
+
+beforeAll(async () => {
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  // 第一个注册的用户是 Hub 管理员、作用域是全部网络;让它先占掉,下面两个是普通用户(各自一个网络)。
+  register(`seq_admin_${Date.now()}`, "SeqAdmin123!x", undefined, "seed");
+  const o = register(`seq_owner_${Date.now()}`, "SeqOwner123!x", undefined, "seed");
+  const x = register(`seq_other_${Date.now()}`, "SeqOther123!x", undefined, "seed");
+  ownerToken = o.token!; ownerNet = o.network_id!; ownerId = o.user!.user_id;
+  otherToken = x.token!; otherNet = x.network_id!; otherId = x.user!.user_id;
+  nodeToken = createNetworkTokenForNode(ownerId, ownerNet, "seq-node").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}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirement short numbers (#N)", () => {
+  test("capability is advertised and create returns seq", async () => {
+    const list = await api(ownerToken, "/api/requirements");
+    expect(list.body.capabilities).toContain("requirement_seq");
+    const first = await create(ownerToken, { name: "第一张" });
+    expect(first.status).toBe(201);
+    expect(first.body.requirement.seq).toBe(1);
+    expect(first.body.requirement.id).toMatch(/^req_/);
+    const got = await api(ownerToken, `/api/requirements/${first.body.requirement.id}`);
+    expect(got.body.requirement.seq).toBe(1);
+    expect((await api(ownerToken, "/api/requirements")).body.requirements[0].seq).toBe(1);
+  });
+
+  test("concurrent creates get distinct, gap-free seqs", async () => {
+    const before = (await create(ownerToken, { name: "before" })).body.requirement.seq as number;
+    const results = await Promise.all(Array.from({ length: 40 }, (_, i) => create(i % 2 ? nodeToken : ownerToken, { name: `并发 ${i}` })));
+    expect(results.every(r => r.status === 201)).toBe(true);
+    const seqs = results.map(r => r.body.requirement.seq as number).sort((a, b) => a - b);
+    expect(new Set(seqs).size).toBe(40);
+    expect(seqs).toEqual(Array.from({ length: 40 }, (_, i) => before + 1 + i));
+  });
+
+  test("seq is per network", async () => {
+    const a = await create(otherToken, { name: "别的网络第一张" });
+    expect(a.body.requirement.seq).toBe(1);
+    const b = await create(otherToken, { name: "别的网络第二张" });
+    expect(b.body.requirement.seq).toBe(2);
+    // 同一个 #1 在两个网络各指各的卡
+    expect((await api(ownerToken, "/api/requirements/%231")).body.requirement.name).toBe("第一张");
+    expect((await api(otherToken, "/api/requirements/%231")).body.requirement.name).toBe("别的网络第一张");
+    // 别的网络的号查不到对方的卡
+    expect((await api(otherToken, "/api/requirements/%2310")).status).toBe(404);
+  });
+
+  test("lookup and patch by #N; list filter ?seq=; malformed forms rejected", async () => {
+    const c = (await create(ownerToken, { name: "按号查", checklist: [{ id: "a", text: "一" }] })).body.requirement;
+    const ref = `%23${c.seq}`;
+    const got = await api(ownerToken, `/api/requirements/${ref}`);
+    expect(got.status).toBe(200);
+    expect(got.body.requirement.id).toBe(c.id);
+    const patched = await api(nodeToken, `/api/requirements/${ref}`, { method: "PATCH", body: JSON.stringify({ column: "doing" }) });
+    expect(patched.status).toBe(200);
+    expect(patched.body.requirement.column).toBe("doing");
+    expect(patched.body.requirement.seq).toBe(c.seq); // 改卡不改号
+    const ticked = await api(ownerToken, `/api/requirements/${ref}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+    expect(ticked.body.requirement.checklist[0].done).toBe(true);
+    const listed = await api(ownerToken, `/api/requirements?seq=${c.seq}`);
+    expect(listed.body.requirements.map((r: any) => r.id)).toEqual([c.id]);
+    expect((await api(ownerToken, "/api/requirements?seq=abc")).status).toBe(400);
+    expect((await api(ownerToken, "/api/requirements?seq=0")).status).toBe(400);
+    // 旧 id 照常;裸数字、「#」「#0」「#-1」都不是短号,按 id 查 → 404
+    expect((await api(ownerToken, `/api/requirements/${c.id}`)).body.requirement.seq).toBe(c.seq);
+    for (const bad of [String(c.seq), "%23", "%230", "%23-1", `%23${c.seq}x`]) expect((await api(ownerToken, `/api/requirements/${bad}`)).status).toBe(404);
+  });
+
+  test("deleting or archiving never frees a number", async () => {
+    const top = (await create(ownerToken, { name: "最大号" })).body.requirement;
+    expect((await api(ownerToken, `/api/requirements/%23${top.seq}`, { method: "DELETE" })).status).toBe(200);
+    expect((await api(ownerToken, `/api/requirements/%23${top.seq}`)).status).toBe(404);
+    const next = (await create(ownerToken, { name: "删之后" })).body.requirement;
+    expect(next.seq).toBe(top.seq + 1);
+    await api(ownerToken, `/api/requirements/${next.id}`, { method: "PATCH", body: JSON.stringify({ archived: true }) });
+    expect((await create(ownerToken, { name: "归档之后" })).body.requirement.seq).toBe(next.seq + 1);
+    // 归档的卡按号照样能查到
+    expect((await api(ownerToken, `/api/requirements/%23${next.seq}`)).body.requirement.archived).toBe(true);
+  });
+
+  test("a create that loses on client_id / external_ref does not burn a number", async () => {
+    const a = (await create(ownerToken, { name: "幂等", client_id: "seq-client-1" })).body.requirement;
+    const again = await create(ownerToken, { name: "幂等", client_id: "seq-client-1" });
+    expect(again.body.requirement.seq).toBe(a.seq);
+    await create(ownerToken, { name: "外部", external_ref: "github:acme/seq#1" });
+    expect((await create(ownerToken, { name: "外部", external_ref: "github:acme/seq#1" })).status).toBe(409);
+    const after = (await create(ownerToken, { name: "之后" })).body.requirement;
+    expect(after.seq).toBe(a.seq + 2);
+    // upsert 新建也领号,改的时候号不变
+    const up = await api(ownerToken, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步", external_ref: "github:acme/seq#2" }) });
+    expect(up.body.requirement.seq).toBe(after.seq + 1);
+    const up2 = await api(ownerToken, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步改名", external_ref: "github:acme/seq#2" }) });
+    expect(up2.body.requirement.seq).toBe(after.seq + 1);
+  });
+
+  test("a user whose scope spans two networks gets 409 ambiguous_seq for #N, and network_id resolves it", async () => {
+    const { db } = await import("./db.js");
+    const { addNetworkMember } = await import("./auth.js");
+    addNetworkMember(otherNet, ownerId, "member", otherId);
+    const both = await api(ownerToken, "/api/requirements/%231");
+    expect(both.status).toBe(409);
+    expect(both.body.error).toBe("ambiguous_seq");
+    expect(both.body.networks.sort()).toEqual([ownerNet, otherNet].sort());
+    expect(both.body.message).toContain("pass network_id");
+    // MCP 上用户令牌(跨两个网络)同样:清楚的错误 + 带 network_id 就能查到
+    {
+      const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+      const { InMemoryTransport } = await import("@modelcontextprotocol/sdk/inMemory.js");
+      const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+      const { registerTools } = await import("./tools.js");
+      const mcp = new McpServer({ name: "seq-mcp-user", version: "1" });
+      registerTools(mcp, undefined, null, ownerId, "seq-owner", false, "tok_user");
+      const client = new Client({ name: "seq-mcp-user-client", version: "1" });
+      const [ct, st] = InMemoryTransport.createLinkedPair();
+      await mcp.connect(st); await client.connect(ct);
+      const call = async (name: string, args: Record<string, unknown>) => JSON.parse(((await client.callTool({ name, arguments: args })) as any).content[0].text);
+      try {
+        const amb = await call("requirements_get", { id: "#1" });
+        expect(amb.ok).toBe(false);
+        expect(amb.error).toBe("ambiguous_seq");
+        expect(amb.status).toBe(409);
+        expect(amb.message).toContain("pass network_id");
+        expect((await call("requirements_update", { id: "#1", priority: "low" })).error).toBe("ambiguous_seq");
+        expect((await call("requirements_get", { id: "#1", network_id: otherNet })).requirement.name).toBe("别的网络第一张");
+        expect((await call("requirements_get", { id: "#1", network_id: ownerNet })).requirement.name).toBe("第一张");
+      } finally { await client.close(); await mcp.close(); }
+    }
+    // 旧 id 不受影响
+    const firstId = (await api(ownerToken, `/api/requirements/%231?network_id=${ownerNet}`)).body.requirement.id;
+    expect((await api(ownerToken, `/api/requirements/${firstId}`)).status).toBe(200);
+    const scoped = await api(ownerToken, `/api/requirements/%231?network_id=${otherNet}`);
+    expect(scoped.status).toBe(200);
+    expect(scoped.body.requirement.name).toBe("别的网络第一张");
+    db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [otherNet, ownerId]);
+  });
+
+  test("MCP tools accept #N and expose seq", async () => {
+    const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+    const { InMemoryTransport } = await import("@modelcontextprotocol/sdk/inMemory.js");
+    const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+    const { registerTools } = await import("./tools.js");
+    const { db } = await import("./db.js");
+    const tokenId = db.get<{ token_id: string }>("SELECT token_id FROM api_tokens WHERE network_id = ?1 AND name LIKE 'node:%' LIMIT 1", ownerNet)?.token_id ?? null;
+    const mcp = new McpServer({ name: "seq-mcp", version: "1" });
+    registerTools(mcp, undefined, ownerNet, ownerId, "seq-node", true, tokenId);
+    const client = new Client({ name: "seq-mcp-client", version: "1" });
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    await mcp.connect(st); await client.connect(ct);
+    const call = async (name: string, args: Record<string, unknown>) => {
+      const r: any = await client.callTool({ name, arguments: args });
+      return r.isError ? { mcpError: true } : JSON.parse(r.content[0].text);
+    };
+    try {
+      const made = await call("requirements_create", { name: "MCP 建的", checklist: [{ id: "k", text: "一" }] });
+      expect(Number.isInteger(made.requirement.seq)).toBe(true);
+      const n = `#${made.requirement.seq}`;
+      expect((await call("requirements_get", { id: n })).requirement.id).toBe(made.requirement.id);
+      expect((await call("requirements_update", { id: n, priority: "high" })).requirement.priority).toBe("high");
+      expect((await call("requirements_checklist_toggle", { id: n, item_id: "k", done: true })).requirement.checklist[0].done).toBe(true);
+      const listed = await call("requirements_list", { seq: made.requirement.seq });
+      expect(listed.requirements.map((r: any) => r.id)).toEqual([made.requirement.id]);
+      expect((await call("requirements_list", { seq: 0 })).mcpError).toBe(true);
+      expect((await call("requirements_get", { id: "#1" })).requirement.name).toBe("第一张"); // 节点令牌只看自己网络的 #1
+    } finally { await client.close(); await mcp.close(); }
+  });
+});

package/src/requirements-seq-migration.test.ts

@@ -0,0 +1,63 @@
+// 任务短号 seq 的启动迁移:用没有 seq 列的旧表建库、塞行,再走真实启动路径(import db.ts + requirements.ts)。
+// 补号按网络各自从 1 开始,按 created_at(新旧两种时间格式混在一起)排,同一时刻按 requirement_id。
+import { afterAll, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-req-seq-migrate-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`CREATE TABLE requirements (
+  requirement_id TEXT PRIMARY KEY, network_id TEXT NOT NULL, title TEXT NOT NULL,
+  column_name TEXT NOT NULL DEFAULT 'pool', priority TEXT NOT NULL DEFAULT 'normal', due_on TEXT, assignee TEXT,
+  client_id TEXT, issues_json TEXT, created_by TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')), updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  owner_json TEXT, participants_json TEXT NOT NULL DEFAULT '[]')`);
+// 插入顺序故意打乱;期望的号写在第三列。
+const rows: [string, string, string, number][] = [
+  ["req_c", "net_a", "2026-09-02T00:00:00.000Z", 5],
+  ["req_a", "net_a", "2026-09-01 08:00:00", 1],        // 旧默认格式(UTC,空格分隔)
+  ["req_z", "net_b", "2026-08-01T00:00:00.000Z", 1],
+  ["req_b2", "net_a", "2026-09-01T09:00:00.000Z", 3],  // 与 req_b1 同一时刻 → 按 id
+  ["req_b1", "net_a", "2026-09-01T09:00:00.000Z", 2],
+  ["req_y", "net_b", "2026-08-02 00:00:00", 2],
+  ["req_d", "net_a", "2026-09-01 23:59:59", 4],        // 旧格式,晚于 09:00 的 ISO、早于 09-02
+];
+for (const [id, net, at] of rows) legacy.run("INSERT INTO requirements (requirement_id, network_id, title, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?4)", [id, net, `卡 ${id}`, at]);
+legacy.close();
+
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+test("startup backfills seq per network in created_at order, then id; counters and unique index follow", async () => {
+  const { db } = await import("./db.js");
+  await import("./requirements.js"); // 真实启动路径
+  const got = Object.fromEntries((db.all("SELECT requirement_id, network_id, seq FROM requirements") as any[]).map(r => [r.requirement_id, r.seq]));
+  // net_a 按时间:req_a 09-01 08:00 → req_b1 / req_b2 09-01 09:00(按 id)→ req_d 09-01 23:59:59 → req_c 09-02
+  expect(got).toEqual({ req_a: 1, req_b1: 2, req_b2: 3, req_d: 4, req_c: 5, req_z: 1, req_y: 2 });
+  // 按字符串排会把「2026-09-01 23:59:59」排到所有 ISO 的 09-01 前面 —— 证明排序真的按时刻,不按字面
+  expect("2026-09-01 23:59:59" < "2026-09-01T09:00:00.000Z").toBe(true);
+  const counters = Object.fromEntries((db.all("SELECT network_id, last_seq FROM requirement_seq_counters") as any[]).map(r => [r.network_id, r.last_seq]));
+  expect(counters).toEqual({ net_a: 5, net_b: 2 });
+  const idx = (db.all("PRAGMA index_list(requirements)") as { name: string; unique: number }[]).find(i => i.name === "idx_requirements_network_seq");
+  expect(idx?.unique).toBe(1);
+  expect(() => db.run("UPDATE requirements SET seq = 1 WHERE requirement_id = 'req_c'")).toThrow();
+
+  // 重复执行:已有号的行一个不动;回滚到旧 Hub 期间建的卡(seq 为空)接在后面补号
+  const { ensureRequirementSeq, nextRequirementSeq } = await import("./requirements-migrate.js");
+  expect(ensureRequirementSeq(db).backfilled).toBe(0);
+  db.run("INSERT INTO requirements (requirement_id, network_id, title, created_at, updated_at) VALUES ('req_old_hub', 'net_a', 'x', '2020-01-01T00:00:00Z', '2020-01-01T00:00:00Z')");
+  expect(ensureRequirementSeq(db).backfilled).toBe(1);
+  expect((db.get("SELECT seq FROM requirements WHERE requirement_id = 'req_old_hub'") as any).seq).toBe(6);
+  expect(got.req_a).toBe((db.get("SELECT seq FROM requirements WHERE requirement_id = 'req_a'") as any).seq);
+  // 删掉最大号的卡,下一个号也不回收
+  db.run("DELETE FROM requirements WHERE requirement_id = 'req_old_hub'");
+  ensureRequirementSeq(db);
+  expect(nextRequirementSeq(db, "net_a")).toBe(7);
+  // 从没建过卡的网络从 1 开始
+  expect(nextRequirementSeq(db, "net_new")).toBe(1);
+  expect(nextRequirementSeq(db, "net_new")).toBe(2);
+});

package/src/requirements.ts

@@ -1,11 +1,12 @@
 // 需求池。长期卡片，存在 Hub 上，手机和电脑读同一份。
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
 import { createHash } from "node:crypto";
+import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
 import { db } from "./db.js";
 import { normalizeTags, storedTags } from "./requirement-tags.js";
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, visibleAgents } from "./agent-access.js";
-import { ensureRequirementIndexes, ensureRequirementProjects, migrateRequirementAgentOwners, migrateRequirementPriorityCheck } from "./requirements-migrate.js";
+import { ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
 // 放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次。
@@ -13,6 +14,7 @@ migrateRequirementPriorityCheck(db);
 migrateRequirementAgentOwners(db);
 ensureRequirementProjects(db);
 ensureRequirementIndexes(db);
+ensureRequirementSeq(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -58,6 +60,7 @@ type Row = {
   issues_json: string | null;
   tags_json: string | null;
   created_at: string;
+  seq: number | null;
 };
 
 function jsonError(error: string, status: number): Response {
@@ -283,6 +286,8 @@ function toPublic(row: Row) {
     project_id: row.project_id || null,
     participants: JSON.parse(row.participants_json || '[]'),
     id: row.requirement_id,
+    // 短号:每个网络自己的 #1、#2…(不回收)。界面显示 #N;GET / PATCH / MCP 的 id 也收「#N」。旧 App 忽略它。
+    seq: row.seq == null ? null : Number(row.seq),
     name: row.title,
     priority: row.priority,
     assignee: row.assignee || "",
@@ -357,7 +362,7 @@ function toPublicFor(ctx: RequirementsRequestContext, row: Row) {
   };
 }
 
-const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, tags_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, start_on, " +
+const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, tags_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, start_on, seq, " +
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0) AS children_total, " +
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0 AND c.column_name = 'done') AS children_done";
 
@@ -452,7 +457,8 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
   return header.split(",").some(tag => tag.trim() === "*" || bare(tag) === bare(etag));
 }
 
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date"] as const;
+// 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"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -602,12 +608,13 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId)); } catch (e) { return jsonError((e as Error).message, 400); }
   const actor = JSON.stringify(actorOf(ctx));
   try {
-    db.run(
+    // 领号和插入在同一个事务里:插入被唯一索引挡下时,号一起回滚,不留空洞。
+    db.transaction(() => db.run(
       `INSERT INTO requirements
-       (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json, start_on)
-       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22, ?23)`,
-      [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags), start || null],
-    );
+       (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json, start_on, seq)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22, ?23, ?24)`,
+      [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags), start || null, nextRequirementSeq(db, networkId)],
+    ));
   } catch {
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
     if (ref) {
@@ -726,14 +733,30 @@ function withLegacyOwner(requirement: ReturnType<typeof toPublic>, coerced: Pers
   return { ok: true, requirement: { ...requirement, owner: coerced }, owner_coerced_to_agent_owner: true };
 }
 
-function scopedRow(ctx: RequirementsRequestContext, id: string): Row | undefined {
-  const params: unknown[] = [id];
-  let sql = `SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`;
+/** 「#123」→ 123;别的形状(包括裸数字)→ null,仍按 requirement_id 查。 */
+export function seqFromId(id: string): number | null {
+  const m = /^#([1-9]\d{0,14})$/.exec(id.trim());
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * 按 id 或「#N」找调用者作用域里的那张卡。短号只在一个网络里唯一:作用域跨多个网络、又各有一张 #N 时
+ * 不猜,回 409 ambiguous_seq(带 ?network_id= 再查)。
+ */
+function scopedRow(ctx: RequirementsRequestContext, id: string): Row | Response {
+  const seq = seqFromId(id);
+  const params: unknown[] = [seq ?? id];
+  let sql = `SELECT ${SELECT} FROM requirements WHERE ${seq === null ? "requirement_id" : "seq"} = ?1`;
   sql = addHumanNetworkScope(sql, params, ctx.scope);
-  return db.get<Row>(sql, ...params) ?? undefined;
+  const rows = db.all<Row>(`${sql} LIMIT 2`, ...params);
+  if (rows.length > 1) {
+    const networks = rows.map(r => r.network_id);
+    return Response.json({ ok: false, error: "ambiguous_seq", networks, message: `#${seq} exists in more than one network you can see (${networks.join(", ")}); pass network_id to pick one` }, { status: 409 });
+  }
+  return rows[0] ?? jsonError("requirement_not_found", 404);
 }
 
-/** GET 的筛选(同步方 / MCP 用):status、project_id、owner / agent_owner(kind:id)、updated_since、external_ref、parent_id / top_level、include_archived。 */
+/** GET 的筛选(同步方 / MCP 用):seq(短号)、status、project_id、owner / agent_owner(kind:id)、updated_since、external_ref、parent_id / top_level、include_archived。 */
 function listFilters(url: URL, sql: string, params: unknown[], ctx?: RequirementsRequestContext): string | Response {
   const q = url.searchParams;
   const status = q.get("status");
@@ -759,6 +782,11 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
     if (!Number.isFinite(ms)) return jsonError("invalid_updated_since", 400);
     sql += ` AND updated_at >= ?${params.push(new Date(ms).toISOString())}`;
   }
+  const seq = q.get("seq");
+  if (seq !== null) {
+    if (!/^[1-9]\d{0,14}$/.test(seq)) return jsonError("invalid_seq", 400);
+    sql += ` AND seq = ?${params.push(Number(seq))}`;
+  }
   const ref = q.get("external_ref");
   if (ref !== null) sql += ` AND external_ref = ?${params.push(ref)}`;
   const parent = q.get("parent_id");
@@ -770,6 +798,55 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   return sql;
 }
 
+const LIST_ORDER = " ORDER BY created_at DESC, requirement_id DESC";
+type LightRow = { requirement_id: string; seq?: number | null; network_id: string; created_at: string; title: string; description: string | null; assignee: string | null; tags_json: string | null; project_id: string | null; owner_json: string | null; agent_owner_json: string | null; participants_json: string | null };
+const parseRef = (json: string | null) => { try { return json ? JSON.parse(json) : null; } catch { return null; } };
+
+/**
+ * 列表的一页(from = listFilters 拼好的「FROM requirements WHERE …」)。没有搜索词:SQL 直接 LIMIT。有搜索词:先按同样的筛选 + 顺序读轻量列(不算子需求计数),
+ * 在这里逐行匹配,凑够 limit + 1 张就停,再按 id 读这一页的完整行。
+ */
+function listPage(ctx: RequirementsRequestContext, from: string, baseParams: unknown[], lq: ListQuery): { rows: Row[]; hasMore: boolean; nextCursor: string | null } {
+  const params = [...baseParams];
+  let where = from;
+  if (lq.cursor) {
+    const a = params.push(lq.cursor.createdAt), b = params.push(lq.cursor.id);
+    where += ` AND (created_at < ?${a} OR (created_at = ?${a} AND requirement_id < ?${b}))`;
+  }
+  let rows: Row[];
+  if (!lq.terms.length) {
+    rows = db.all<Row>(`SELECT ${SELECT} ${where}${LIST_ORDER} LIMIT ${lq.limit + 1}`, ...params);
+  } else {
+    // seq(任务短号,#2139):启动迁移 ensureRequirementSeq 在 SQLite / PostgreSQL 上都加这一列,SELECT 本来就带它。
+    const light = db.all<LightRow>(`SELECT requirement_id, seq, network_id, created_at, title, description, assignee, tags_json, project_id, owner_json, agent_owner_json, participants_json ${where}${LIST_ORDER}`, ...params);
+    const maps = new Map<string, NameMaps>();
+    const hits: string[] = [];
+    for (const r of light) {
+      let m = maps.get(r.network_id);
+      if (!m) maps.set(r.network_id, m = searchNameMaps(ctx, r.network_id));
+      const row = { name: r.title, description: r.description || "", assignee: r.assignee || "", tags: storedTags(r.tags_json), project_id: r.project_id, owner: parseRef(r.owner_json), agent_owner: parseRef(r.agent_owner_json), participants: parseRef(r.participants_json) ?? [] };
+      if (matchesTaskId(r, lq.idQuery) || matchesTerms(row, lq.terms, m)) hits.push(r.requirement_id);
+      if (hits.length > lq.limit) break;
+    }
+    const byId = new Map(hits.length ? db.all<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id IN (${hits.map((_, i) => `?${i + 1}`).join(",")})`, ...hits).map(r => [r.requirement_id, r]) : []);
+    rows = hits.map(id => byId.get(id)).filter((r): r is Row => !!r);
+  }
+  const hasMore = rows.length > lq.limit;
+  if (hasMore) rows = rows.slice(0, lq.limit);
+  const last = rows[rows.length - 1];
+  return { rows, hasMore, nextCursor: hasMore && last ? encodeCursor({ createdAt: last.created_at, id: last.requirement_id }) : null };
+}
+
+/** 搜索用的名字表(与 GET /api/requirements/people 同一个显示名规则);调用者看不见的节点不放进来。 */
+function searchNameMaps(ctx: RequirementsRequestContext, networkId: string): NameMaps {
+  const hidden = hiddenNodeFilter(ctx, networkId);
+  const people = new Map<string, string>();
+  for (const u of 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", networkId)) people.set(`user:${u.id}`, u.name);
+  for (const n of 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", networkId)) if (!hidden?.(n.id)) people.set(`node:${n.id}`, n.name);
+  const projects = new Map(db.all<{ project_id: string; name: string }>("SELECT project_id, name FROM requirement_projects WHERE network_id=?1", networkId).map(p => [p.project_id, p.name] as const));
+  return { people, projects };
+}
+
 /** 这个节点对调用者在他作用域内的某个受限网络里是否隐藏。 */
 function hiddenFilterForScope(ctx: RequirementsRequestContext, nodeId: string): boolean {
   const restricted = ctx.scope.agentRestriction?.networkIds ?? [];
@@ -812,13 +889,18 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
 
   if (url.pathname === "/api/requirements" && req.method === "GET") {
     const params: unknown[] = [];
-    let sql = `SELECT ${SELECT} FROM requirements WHERE 1=1`;
+    // 只拼 FROM … WHERE:同一组条件既用来读整行,也用来(搜索时)先读轻量列。
+    let sql = "FROM requirements WHERE 1=1";
     sql = addHumanNetworkScope(sql, params, ctx.scope);
     const filtered = listFilters(url, sql, params, ctx);
     if (typeof filtered !== "string") return filtered;
-    const rows = db.all<Row>(`${filtered} ORDER BY created_at DESC LIMIT 500`, ...params).map(row => toPublicFor(ctx, row));
+    // q= / limit / cursor(requirements-search.ts)。都不带 = 旧行为:最新 500 张、同样的顺序。
+    const lq = parseListQuery(url.searchParams);
+    if ("error" in lq) return jsonError(lq.error, 400);
+    const page = listPage(ctx, filtered, params, lq);
     // capabilities:客户端按这个决定显示哪些功能(预计完成能不能带时刻、有没有项目…),不用靠猜字段。
-    return conditionalJson(ctx.req, { ok: true, requirements: rows, capabilities: REQUIREMENT_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 });
   }
 
   if (url.pathname === "/api/requirements" && req.method === "POST") {
@@ -859,7 +941,7 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
     if (typeof body.done !== "boolean") return jsonError("invalid_done", 400);
     const row = scopedRow(ctx, decodeURIComponent(itemMatch[1]));
-    if (!row) return jsonError("requirement_not_found", 404);
+    if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
     // 读-改-写在同一个同步段里完成(中间没有 await),同一进程里的两次勾选不会交错。
     const items = storedChecklist(row.checklist_json);
@@ -877,12 +959,12 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   const id = decodeURIComponent(match[1]);
   if (req.method === "GET") {
     const row = scopedRow(ctx, id);
-    return row ? Response.json({ ok: true, requirement: toPublicFor(ctx, row) }) : jsonError("requirement_not_found", 404);
+    return row instanceof Response ? row : Response.json({ ok: true, requirement: toPublicFor(ctx, row) });
   }
   if (req.method === "DELETE") {
     // 删除只给人(节点令牌在入口已被拒):Agent 用 archived 归档。
     const row = scopedRow(ctx, id);
-    if (!row) return jsonError("requirement_not_found", 404);
+    if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
     db.run("UPDATE requirements SET parent_id = NULL WHERE parent_id = ?1", [row.requirement_id]);
@@ -894,6 +976,6 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
   if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400);
   const row = scopedRow(ctx, id);
-  if (!row) return jsonError("requirement_not_found", 404);
+  if (row instanceof Response) return row;
   return patchRequirement(ctx, row, body);
 }

package/src/retention.ts

@@ -197,10 +197,13 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
   //     DBs must run a one-time blocking `VACUUM` themselves (out of
   //     scope for the sweeper, which deliberately stays non-
   //     blocking).
+  //   Both are SQLite PRAGMAs; on PostgreSQL autovacuum does this job and
+  //   the two counters stay null (RFC-039 S3).
   let walCheckpointPagesMoved: number | null = null;
   let incrementalFreedPages: number | null = null;
   let errored = false;
-  try {
+  const sqliteVacuum = db.dialect === "sqlite";
+  if (sqliteVacuum) try {
     // wal_checkpoint(TRUNCATE) returns a row { busy, log, checkpointed }.
     // We expose `log` (page count moved into the main DB) for ops visibility.
     const checkpoint = db.get<{ busy: number; log: number; checkpointed: number }>(
@@ -211,7 +214,7 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
     console.log(`[commhub retention] wal_checkpoint failed: ${e?.message ?? e}`);
     errored = true;
   }
-  try {
+  if (sqliteVacuum) try {
     // incremental_vacuum is a no-op on databases not created with
     // PRAGMA auto_vacuum = INCREMENTAL. For existing prod DBs that
     // weren't, the operator would have to run a full one-time VACUUM

package/src/scheduled-tasks-http.test.ts

@@ -8,8 +8,8 @@ import { db } from "./db.js";
 import { assertScheduledTaskBackendSupported, nextOccurrence, runDueScheduledTasks } from "./scheduled-tasks.js";
 
 const dir = mkdtempSync(join(tmpdir(), "anet-scheduler-"));
-const activeDbPath = process.env.COMMHUB_DB;
-if (!activeDbPath) throw new Error("test601 requires COMMHUB_DB before module import");
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("test601 requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
 let server: any;
 let base = "";
 let ownerToken = "";
@@ -128,8 +128,13 @@ describe("Hub scheduled task API and dispatcher", () => {
       (db as any).atomicTransactions = original;
     }
     expect(() => assertScheduledTaskBackendSupported()).not.toThrow();
-    const misfireColumn = db.all<any>("PRAGMA table_info(scheduled_tasks)").find((column: any) => column.name === "misfire_policy");
-    expect(misfireColumn?.dflt_value).toBe("'catch_up_once'");
+    if (db.dialect === "sqlite") {
+      const misfireColumn = db.all<any>("PRAGMA table_info(scheduled_tasks)").find((column: any) => column.name === "misfire_policy");
+      expect(misfireColumn?.dflt_value).toBe("'catch_up_once'");
+    } else {
+      const misfireColumn = db.get<any>("SELECT column_default FROM information_schema.columns WHERE table_name = 'scheduled_tasks' AND column_name = 'misfire_policy'");
+      expect(misfireColumn?.column_default).toBe("'catch_up_once'::text");
+    }
   });
 
   test("owner creates; viewer and node token cannot mutate", async () => {
@@ -283,10 +288,17 @@ describe("Hub scheduled task API and dispatcher", () => {
     // Test-only fault injection at the second durable write. The inbox row has
     // already been attempted when this aborts, so any missing transaction
     // boundary leaves an observable half-state.
-    db.run(`CREATE TRIGGER test601_abort_scheduled_task_insert
-      BEFORE INSERT ON tasks
-      WHEN NEW.meta_json LIKE '%${atomicScheduleId}%'
-      BEGIN SELECT RAISE(ABORT, 'test601_injected_task_failure'); END`);
+    if (db.dialect === "sqlite") {
+      db.run(`CREATE TRIGGER test601_abort_scheduled_task_insert
+        BEFORE INSERT ON tasks
+        WHEN NEW.meta_json LIKE '%${atomicScheduleId}%'
+        BEGIN SELECT RAISE(ABORT, 'test601_injected_task_failure'); END`);
+    } else {
+      db.exec(`CREATE FUNCTION test601_abort_scheduled_task_insert() RETURNS trigger AS $$
+        BEGIN RAISE EXCEPTION 'test601_injected_task_failure'; END; $$ LANGUAGE plpgsql;
+        CREATE TRIGGER test601_abort_scheduled_task_insert BEFORE INSERT ON tasks FOR EACH ROW
+        WHEN (NEW.meta_json LIKE '%${atomicScheduleId}%') EXECUTE FUNCTION test601_abort_scheduled_task_insert()`);
+    }
     const failed = runDueScheduledTasks();
     expect(failed.failed).toBe(1);
     expect(db.get("SELECT run_id FROM scheduled_task_runs WHERE schedule_id = ?1", atomicScheduleId)).toBeNull();
@@ -294,7 +306,8 @@ describe("Hub scheduled task API and dispatcher", () => {
     expect(db.get("SELECT task_id FROM tasks WHERE meta_json LIKE '%' || ?1 || '%'", atomicScheduleId)).toBeNull();
     expect(db.get<{ next_run_at: string }>("SELECT next_run_at FROM scheduled_tasks WHERE schedule_id = ?1", atomicScheduleId)!.next_run_at).toBe(due);
 
-    db.run("DROP TRIGGER test601_abort_scheduled_task_insert");
+    if (db.dialect === "sqlite") db.run("DROP TRIGGER test601_abort_scheduled_task_insert");
+    else db.exec("DROP TRIGGER test601_abort_scheduled_task_insert ON tasks; DROP FUNCTION test601_abort_scheduled_task_insert()");
     expect(runDueScheduledTasks().processed).toBe(1);
     expect(db.get("SELECT task_id FROM scheduled_task_runs WHERE schedule_id = ?1", atomicScheduleId)).toBeTruthy();
   });

package/src/server.ts

@@ -3459,7 +3459,7 @@ return Bun.serve({
         db.run("DELETE FROM nodes WHERE node_id = ?1", [node.node_id]);
         if (node.alias) {
           db.run(
-            "DELETE FROM sessions WHERE alias = ?1 AND (network_id = ?2 OR (?2 IS NULL AND network_id IS NULL))",
+            "DELETE FROM sessions WHERE alias = ?1 AND (network_id = ?2 OR (CAST(?2 AS TEXT) IS NULL AND network_id IS NULL))",
             [node.alias, node.network_id ?? null]
           );
         }

package/src/side-thread-command-transport.test.ts

@@ -1,12 +1,22 @@
 import { describe, expect, test } from "bun:test";
 import { Database } from "bun:sqlite";
-import { SQLiteAdapter } from "./db-adapter";
+import { PgAdapter, SQLiteAdapter, resolveDatabaseTarget, type DbAdapter } from "./db-adapter";
 import { DurableSideThreadCommandPort, SideThreadCommandStore, handleSideThreadCommandRequest } from "./side-thread-command-transport";
 import { SideThreadCoordinator, SideThreadStore } from "./side-thread";
 
 function actor(tokenId = "tok-node") { return { tokenId, networkId: "net-1", nodeId: "node-1" }; }
+// RFC-039 S4: with COMMHUB_TEST_PG_URL (validated by the adapter guard) the
+// same tests run on PostgreSQL, each fixture on an emptied schema.
+function freshDb(): DbAdapter {
+  if (!process.env.COMMHUB_TEST_PG_URL) return new SQLiteAdapter(new Database(":memory:"));
+  const target = resolveDatabaseTarget();
+  if (target.kind !== "postgres") throw new Error("COMMHUB_TEST_PG_URL did not select PostgreSQL");
+  const pg = new PgAdapter(target.url);
+  pg.exec("DROP SCHEMA public CASCADE; CREATE SCHEMA public");
+  return pg;
+}
 function fixture() {
-  const db = new SQLiteAdapter(new Database(":memory:"));
+  const db = freshDb();
   db.exec("CREATE TABLE inbox(id TEXT PRIMARY KEY, content TEXT)");
   const store = new SideThreadCommandStore(db, () => 123);
   const port = new DurableSideThreadCommandPort({ store, networkForNode: (id) => id === "node-1" ? "net-1" : null,

package/src/side-thread.ts

@@ -450,6 +450,10 @@ export function installSideThreadSchema(database: DbAdapter): void {
     if (!/duplicate column|already exists/i.test(error?.message ?? ""))
       throw error;
   }
+  // RFC-039 F3: operations are listed in insertion order via SQLite's
+  // implicit rowid; PostgreSQL needs a real column for that.
+  if (database.dialect === "postgres")
+    database.exec("ALTER TABLE side_chat_operations ADD COLUMN IF NOT EXISTS rowid BIGSERIAL");
 }
 
 type SideChatRow = {