@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.130

package/src/requirements-migrate.ts

@@ -0,0 +1,259 @@
+// 需求卡的启动迁移。requirements.ts 载入时调用一次(列由 db.ts 的加列循环加上)。
+import type { DbAdapter } from "./db-adapter";
+
+/**
+ * 负责人 = 人类(owner, kind user);负责 Agent = 节点(agent_owner, kind node)。
+ * 之前 owner 可以是节点:这些卡把节点挪到 agent_owner、owner 置空。只动 agent_owner 还空着的行,
+ * 所以重复执行不会再改任何东西;不删行,不碰别的列。在 JS 里判 kind(不依赖 SQLite 的 json_extract)。
+ */
+export function migrateRequirementAgentOwners(database: DbAdapter): { moved: number } {
+  const rows = database.all<{ requirement_id: string; owner_json: string | null }>(
+    "SELECT requirement_id, owner_json FROM requirements WHERE owner_json IS NOT NULL AND agent_owner_json IS NULL",
+  );
+  let moved = 0;
+  for (const row of rows) {
+    let owner: { kind?: unknown; id?: unknown } | null = null;
+    try { owner = JSON.parse(row.owner_json || "null"); } catch { continue; }
+    if (!owner || owner.kind !== "node" || typeof owner.id !== "string" || !owner.id) continue;
+    database.run(
+      "UPDATE requirements SET agent_owner_json = ?1, owner_json = NULL WHERE requirement_id = ?2 AND agent_owner_json IS NULL",
+      [JSON.stringify({ kind: "node", id: owner.id }), row.requirement_id],
+    );
+    moved += 1;
+  }
+  return { moved };
+}
+
+/**
+ * 项目表(需求卡的「项目」)。只建表、建索引,不塞任何项目 —— 军团项目 / TMAI 由 owner 在界面里建。
+ * CREATE ... IF NOT EXISTS:重复执行无副作用。放在这里而不是 db.ts,db.ts 的行号被文档钉着。
+ */
+export function ensureRequirementProjects(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_projects (
+      project_id  TEXT PRIMARY KEY,
+      network_id  TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      color       TEXT NOT NULL,
+      sort        INTEGER NOT NULL DEFAULT 0,
+      archived    INTEGER NOT NULL DEFAULT 0,
+      created_at  TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_requirement_projects_network ON requirement_projects(network_id, sort);
+  `);
+}
+
+/**
+ * 标签颜色(可选)。标签本身仍只是卡片 tags 数组里的字符串;这里只存「这个网络里这个名字用什么颜色」。
+ * 没有行 = 默认色。改名 / 合并 / 删除时跟着挪或删(见 requirements.ts 的标签管理)。IF NOT EXISTS:重复执行无副作用。
+ */
+export function ensureNetworkTags(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS network_tags (
+      network_id  TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      color       TEXT NOT NULL,
+      updated_at  TEXT NOT NULL,
+      PRIMARY KEY (network_id, name)
+    );
+  `);
+}
+
+/**
+ * 删掉的卡留一条墓碑,给 GET /api/requirements?changes=1 报「这些 id 没了」(按 updated_since 增量同步的客户端
+ * 否则永远不知道一张卡被删了)。连同判断可见性要用的列一起存:受限成员只收到他本来看得见的卡的删除。
+ * 保留 30 天(requirements.ts TOMBSTONE_RETENTION_MS,写入时顺手清)。IF NOT EXISTS:重复执行无副作用。
+ */
+export function ensureRequirementTombstones(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_tombstones (
+      requirement_id    TEXT PRIMARY KEY,
+      network_id        TEXT NOT NULL,
+      deleted_at        TEXT NOT NULL,
+      project_id        TEXT,
+      owner_json        TEXT,
+      participants_json TEXT,
+      created_by        TEXT,
+      created_by_json   TEXT
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_tombstones_network ON requirement_tombstones(network_id, deleted_at)");
+}
+
+/** external_ref 在同一网络里唯一(只管有值的行)。IF NOT EXISTS:重复执行无副作用。 */
+export function ensureRequirementIndexes(database: DbAdapter): void {
+  database.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_external_ref ON requirements(network_id, external_ref) WHERE external_ref IS NOT NULL");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_network_updated ON requirements(network_id, updated_at)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_parent ON requirements(parent_id) WHERE parent_id IS NOT NULL");
+}
+
+/**
+ * 优先级加 lowest(P3 极低)。旧库建表时带 CHECK(priority IN ('high', 'normal', 'low')),SQLite 不能就地改
+ * CHECK,只能重建一次:拿 sqlite_master 里的原建表语句(含历次加的列)只换掉那个 CHECK,整表拷过去,
+ * 再按原样重建这张表的索引。已经放开的库什么都不做。存量值不改。
+ */
+const OLD_PRIORITY_CHECK = /CHECK\s*\(\s*priority\s+IN\s*\(\s*'high'\s*,\s*'normal'\s*,\s*'low'\s*\)\s*\)/i;
+export const PRIORITY_CHECK = "CHECK(priority IN ('high', 'normal', 'low', 'lowest'))";
+export function migrateRequirementPriorityCheck(database: DbAdapter): { rebuilt: boolean } {
+  if (database.dialect === "postgres") {
+    try {
+      database.exec("ALTER TABLE requirements DROP CONSTRAINT IF EXISTS requirements_priority_check");
+      database.exec(`ALTER TABLE requirements ADD CONSTRAINT requirements_priority_check ${PRIORITY_CHECK}`);
+    } catch {}
+    return { rebuilt: false };
+  }
+  const table = database.get<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'requirements'");
+  if (!table?.sql || !OLD_PRIORITY_CHECK.test(table.sql)) return { rebuilt: false };
+  const indexes = database.all<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'index' AND tbl_name = 'requirements' AND sql IS NOT NULL");
+  const createSql = table.sql
+    .replace(/^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?requirements["`]?/i, "CREATE TABLE requirements_migrated")
+    .replace(OLD_PRIORITY_CHECK, PRIORITY_CHECK);
+  database.transaction(() => {
+    database.exec("DROP TABLE IF EXISTS requirements_migrated");
+    database.exec(createSql);
+    database.exec("INSERT INTO requirements_migrated SELECT * FROM requirements");
+    database.exec("DROP TABLE requirements");
+    database.exec("ALTER TABLE requirements_migrated RENAME TO requirements");
+    for (const index of indexes) database.exec(index.sql);
+  });
+  return { rebuilt: true };
+}
+
+/**
+ * 状态加 abandoned(废弃)。同 migrateRequirementPriorityCheck:旧库的 CHECK(column_name IN ('pool', 'doing', 'done'))
+ * SQLite 不能就地改,只重建一次;PostgreSQL 换掉默认名的列约束。已经放开的库什么都不做。存量值不改。
+ */
+const OLD_COLUMN_CHECK = /CHECK\s*\(\s*column_name\s+IN\s*\(\s*'pool'\s*,\s*'doing'\s*,\s*'done'\s*\)\s*\)/i;
+export const COLUMN_CHECK = "CHECK(column_name IN ('pool', 'doing', 'done', 'abandoned'))";
+export function migrateRequirementColumnCheck(database: DbAdapter): { rebuilt: boolean } {
+  if (database.dialect === "postgres") {
+    // 只在约束还不认识 abandoned(或不存在)时动;一条 ALTER TABLE 里先删后加 = 一个语句,原子,
+    // 失败(比如存量里有不合法的值)整条回滚、旧约束原样留着,并且直接抛出 —— 不吞错,启动就该停下来。
+    const def = database.get<{ def: string }>(
+      "SELECT pg_get_constraintdef(c.oid) AS def FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid WHERE t.relname = 'requirements' AND c.conname = 'requirements_column_name_check'",
+    )?.def ?? "";
+    if (def.includes("'abandoned'")) return { rebuilt: false };
+    database.exec(`ALTER TABLE requirements DROP CONSTRAINT IF EXISTS requirements_column_name_check, ADD CONSTRAINT requirements_column_name_check ${COLUMN_CHECK}`);
+    return { rebuilt: true };
+  }
+  const table = database.get<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'requirements'");
+  if (!table?.sql || !OLD_COLUMN_CHECK.test(table.sql)) return { rebuilt: false };
+  const indexes = database.all<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'index' AND tbl_name = 'requirements' AND sql IS NOT NULL");
+  const createSql = table.sql
+    .replace(/^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?requirements["`]?/i, "CREATE TABLE requirements_migrated")
+    .replace(OLD_COLUMN_CHECK, COLUMN_CHECK);
+  database.transaction(() => {
+    database.exec("DROP TABLE IF EXISTS requirements_migrated");
+    database.exec(createSql);
+    database.exec("INSERT INTO requirements_migrated SELECT * FROM requirements");
+    database.exec("DROP TABLE requirements");
+    database.exec("ALTER TABLE requirements_migrated RENAME TO requirements");
+    for (const index of indexes) database.exec(index.sql);
+  });
+  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 };
+}
+
+/**
+ * 完成时间(仪表盘「今天 / 本周完成了多少」用)。三列只加不改:
+ * - completed_at:进入「完成」列的时刻(ISO,UTC)。移出「完成」列清空;在「完成」列里改别的字段不动它。
+ * - completed_by_json:谁把它移进「完成」的({kind,id},同 updated_by)。
+ * - completed_at_approx:1 = 这个时刻是补出来的近似值(见下),界面可以标「近似」。
+ * 补值:已经在「完成」列、还没有 completed_at 的卡,按 updated_at(没有就 created_at)补,approx = 1,completed_by 留空
+ * —— updated_at 是「最后一次改」,不是「完成那一刻」,只能当近似。旧库里 datetime('now') 的「YYYY-MM-DD HH:MM:SS」(UTC)
+ * 统一换成 ISO,按时间范围比较时不和 ISO 值错位。
+ * 每次启动都跑,重复执行只处理需要处理的行:回滚到旧 Hub 期间移进「完成」的卡补近似值,移出「完成」的卡清掉残留。
+ */
+export function ensureRequirementCompletedAt(database: DbAdapter): { backfilled: number; cleared: number } {
+  for (const column of ["completed_at TEXT", "completed_by_json TEXT", "completed_at_approx INTEGER NOT NULL DEFAULT 0"]) {
+    try { database.exec(`ALTER TABLE requirements ADD COLUMN ${column}`); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
+  }
+  const pending = database.all<{ requirement_id: string; updated_at: string | null; created_at: string | null }>(
+    "SELECT requirement_id, updated_at, created_at FROM requirements WHERE column_name = 'done' AND completed_at IS NULL",
+  );
+  const stale = database.all<{ requirement_id: string }>(
+    "SELECT requirement_id FROM requirements WHERE column_name <> 'done' AND (completed_at IS NOT NULL OR completed_by_json IS NOT NULL OR completed_at_approx <> 0)",
+  );
+  if (pending.length || stale.length) {
+    database.transaction(() => {
+      for (const row of pending) {
+        database.run(
+          "UPDATE requirements SET completed_at = ?1, completed_by_json = NULL, completed_at_approx = 1 WHERE requirement_id = ?2 AND completed_at IS NULL",
+          [isoInstant(row.updated_at) ?? isoInstant(row.created_at) ?? new Date().toISOString(), row.requirement_id],
+        );
+      }
+      for (const row of stale) {
+        database.run("UPDATE requirements SET completed_at = NULL, completed_by_json = NULL, completed_at_approx = 0 WHERE requirement_id = ?1", [row.requirement_id]);
+      }
+    });
+  }
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirements_network_completed ON requirements(network_id, completed_at) WHERE completed_at IS NOT NULL");
+  return { backfilled: pending.length, cleared: stale.length };
+}
+
+/** 库里的时间 → ISO(UTC)。认 ISO 和旧默认值「YYYY-MM-DD HH:MM:SS」(SQLite datetime('now'),UTC);读不懂 → null。 */
+export function isoInstant(value: string | null | undefined): string | null {
+  const s = value ?? "";
+  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) ? new Date(ms).toISOString() : null;
+}
+
+/**
+ * 给新卡领下一个号。调用方把它和 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-owner-strict-mcp-http.test.ts

@@ -0,0 +1,145 @@
+// #470(MCP 任务生命周期测试报告问题 1)—— Agent 经 MCP 把负责人设成节点:以前走旧 App 的兼容改写,
+// 人类负责人被静默清空、负责 Agent 被换掉,响应还显示 owner=节点。现在:
+//   - MCP 上 owner 传节点(建 / 改 / upsert,节点令牌和用户令牌都一样)→ 400 owner_must_be_human + hint,什么都不写;
+//   - MCP 写入的响应就是落库的那一行(和紧接着的 requirements_get 一字不差);
+//   - REST 上旧 App ≤ 0.2.142 的兼容路径不变(requirements-http.test.ts「old-app compat」那条钉着)。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-owner-strict-mcp-"));
+let BASE = "";
+let hub: any = null;
+const PW = "OwnerStrictMcpPassw0rd!x";
+let NET = "", ownerToken = "", ownerId = "", nodeToken = "";
+const human = () => ({ kind: "user", id: ownerId });
+const nodeA = { kind: "node", id: "node_strict_a" };
+const nodeB = { kind: "node", id: "node_strict_b" };
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const out = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(out.result.content[0].text);
+}
+const stored = (id: string) => db.get<{ owner_json: string | null; agent_owner_json: string | null }>("SELECT owner_json, agent_owner_json FROM requirements WHERE requirement_id = ?1", id)!;
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`strict_owner_${Date.now()}`, PW, undefined, "Owner");
+  ownerToken = a.token!; ownerId = a.user!.user_id; NET = a.network_id!;
+  nodeToken = createNetworkTokenForNode(ownerId, NET, "strict-a", "node_strict_a").token!;
+  createNetworkTokenForNode(ownerId, NET, "strict-b", "node_strict_b");
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("MCP: owner must be a person", () => {
+  test("update owner=node → 400 owner_must_be_human + hint; the human owner and the agent owner are untouched", async () => {
+    const card = (await mcp(nodeToken, "requirements_create", { name: "负责人保护", owner: human(), agent_owner: nodeB })).requirement;
+    expect(card.owner).toEqual(human());
+    const r = await mcp(nodeToken, "requirements_update", { id: card.id, owner: nodeA });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("owner_must_be_human");
+    expect(r.status).toBe(400);
+    expect(r.hint).toContain("agent_owner");
+    expect(r.owner_coerced_to_agent_owner).toBeUndefined();
+    const row = stored(card.id);
+    expect(JSON.parse(row.owner_json!)).toEqual(human());
+    expect(JSON.parse(row.agent_owner_json!)).toEqual(nodeB);
+    const got = (await mcp(nodeToken, "requirements_get", { id: card.id })).requirement;
+    expect(got.owner).toEqual(human());
+    expect(got.agent_owner).toEqual(nodeB);
+  });
+
+  test("…the same for a user token over MCP, for create (nothing is written) and for upsert", async () => {
+    const r = await mcp(ownerToken, "requirements_update", { network_id: NET, id: (await mcp(ownerToken, "requirements_create", { network_id: NET, name: "用户令牌", owner: human() })).requirement.id, owner: nodeA });
+    expect(r.error).toBe("owner_must_be_human");
+    const before = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET)!.n;
+    const c = await mcp(nodeToken, "requirements_create", { name: "建时就传节点", owner: nodeA });
+    expect(c.error).toBe("owner_must_be_human");
+    expect(c.hint).toContain("agent_owner");
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET)!.n).toBe(before);
+    const u = await mcp(nodeToken, "requirements_upsert_by_external_ref", { external_ref: "github:example/repo#470", name: "upsert", owner: nodeA });
+    expect(u.error).toBe("owner_must_be_human");
+    expect(db.get("SELECT 1 FROM requirements WHERE external_ref = 'github:example/repo#470'")).toBeNull();
+  });
+
+  test("the right way still works: agent_owner = node, owner = person, owner = null", async () => {
+    const card = (await mcp(nodeToken, "requirements_create", { name: "正确的写法", owner: human() })).requirement;
+    const r = await mcp(nodeToken, "requirements_update", { id: card.id, agent_owner: nodeA });
+    expect(r.ok).toBe(true);
+    expect(r.requirement.owner).toEqual(human());
+    expect(r.requirement.agent_owner).toEqual(nodeA);
+    const cleared = await mcp(nodeToken, "requirements_update", { id: card.id, owner: null });
+    expect(cleared.requirement.owner).toBeNull();
+    // agent_owner given a person is refused the other way round, with its own hint.
+    const wrong = await mcp(nodeToken, "requirements_update", { id: card.id, agent_owner: human() });
+    expect(wrong.error).toBe("agent_owner_must_be_agent");
+    expect(wrong.hint).toContain("owner");
+  });
+
+  test("every MCP write's response equals a fresh requirements_get", async () => {
+    const card = (await mcp(nodeToken, "requirements_create", { name: "响应即落库", owner: human(), checklist: [{ text: "一" }] })).requirement;
+    expect((await mcp(nodeToken, "requirements_get", { id: card.id })).requirement).toEqual(card);
+    const patches: Record<string, unknown>[] = [
+      { column: "doing" }, { agent_owner: nodeA }, { participants: [nodeB, human()] }, { owner: null }, { owner: human(), priority: "high" },
+      { agent_owner: null }, { due: "2026-10-10" }, { archived: true }, { archived: false },
+    ];
+    for (const p of patches) {
+      const r = await mcp(nodeToken, "requirements_update", { id: card.id, ...p });
+      expect(r.ok).toBe(true);
+      expect(r.owner_coerced_to_agent_owner).toBeUndefined();
+      expect(r.requirement).toEqual((await mcp(nodeToken, "requirements_get", { id: card.id })).requirement);
+    }
+  });
+});
+
+describe("REST", () => {
+  test("new clients' responses equal a fresh GET (the old-app compat echo is the only exception, pinned in requirements-http.test.ts)", async () => {
+    const card = (await rest(ownerToken, "POST", "/api/requirements", { network_id: NET, name: "REST 响应", owner: human() })).body.requirement;
+    for (const p of [{ agent_owner: nodeA }, { owner: human(), agent_owner: nodeB }, { participants: [nodeA] }]) {
+      const r = await rest(ownerToken, "PATCH", `/api/requirements/${card.id}`, p);
+      expect(r.status).toBe(200);
+      expect(r.body.requirement).toEqual((await rest(ownerToken, "GET", `/api/requirements/${card.id}`)).body.requirement);
+    }
+    // A new client (sends agent_owner) passing a node as owner: still strict, now with the hint.
+    const strict = await rest(ownerToken, "PATCH", `/api/requirements/${card.id}`, { owner: nodeA, agent_owner: nodeB });
+    expect(strict.status).toBe(400);
+    expect(strict.body.error).toBe("owner_must_be_human");
+    expect(strict.body.hint).toContain("agent_owner");
+  });
+
+  test("old-app compat on REST is unchanged: owner=node without agent_owner is still coerced (200 + flag)", async () => {
+    const card = (await rest(ownerToken, "POST", "/api/requirements", { network_id: NET, name: "旧 App", owner: human() })).body.requirement;
+    const old = await rest(ownerToken, "PATCH", `/api/requirements/${card.id}`, { owner: nodeA });
+    expect(old.status).toBe(200);
+    expect(old.body.owner_coerced_to_agent_owner).toBe(true);
+    const row = stored(card.id);
+    expect(row.owner_json).toBeNull();
+    expect(JSON.parse(row.agent_owner_json!)).toEqual(nodeA);
+  });
+});

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

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