@sleep2agi/commhub-server 0.9.0-preview.75 → 0.9.0-preview.77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.75",
+  "version": "0.9.0-preview.77",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/requirement-events-http.test.ts

@@ -0,0 +1,257 @@
+// 任务动态(#429)—— HTTP 集成测试(真实 Bun.serve,临时库;PG 梯子上用 COMMHUB_TEST_PG_URL 原样再跑一遍)。
+//   写路径    —— 新建 / PATCH 的每个字段 / 勾子任务 / 标签改名 / 删项目 / 删卡,各记字段级流水:谁、旧值 → 新值
+//   同一事务  —— 流水写不进去,那次改动也不生效
+//   可见范围  —— 与列表相同:scoped 成员只看到看得见的卡(删掉的按墓碑);Agent 受限成员看不见的节点被隐去
+//   翻页      —— limit / next_cursor / since / requirement_id;参数不合法 400;capability `events`
+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-requirement-events-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "EventsPassw0rd!x";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let admin = { token: "", id: "" };
+let member = { token: "", id: "" };
+let scoped = { token: "", id: "" };
+let restricted = { token: "", id: "" };
+let nodeToken = "";
+let NODE = "";
+
+type R = { status: number; body: any };
+async function send(token: string, method: string, path: string, payload?: unknown): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+const create = async (t: string, card: Record<string, unknown>) => {
+  const r = await send(t, "POST", "/api/requirements", { network_id: NET, ...card });
+  expect(r.status).toBe(201);
+  return r.body.requirement as { id: string; seq: number };
+};
+const patch = (t: string, id: string, p: Record<string, unknown>) => send(t, "PATCH", `/api/requirements/${id}?network_id=${NET}`, p);
+const events = (t: string, qs = "") => send(t, "GET", `/api/requirements/events?network_id=${NET}${qs}`);
+const of = (list: any[], id: string) => list.filter(e => e.requirement_id === id);
+const user = (id: string) => ({ kind: "user", id });
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`ev_admin_${Date.now()}`, PW, undefined, "Admin");
+  expect(a.ok).toBe(true);
+  admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [admin.id]);
+  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}`;
+  const mk = async (username: string) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  member = await mk(`ev_member_${stamp}`);
+  scoped = await mk(`ev_scoped_${stamp}`);
+  restricted = await mk(`ev_restricted_${stamp}`);
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, scoped.id]);
+  // 看全部任务,但一个 Agent 都没授权:所有节点对他隐去
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'granted' WHERE network_id = ?1 AND user_id = ?2", [NET, restricted.id]);
+  NODE = `n_ev_${stamp}`;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id) VALUES (?1, ?2, ?3, ?4)", [NODE, "ev-node", "ev-node", NET]);
+  const ntok = createNetworkTokenForNode(admin.id, NET, "ev-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirement events", () => {
+  test("capability `events` is advertised", async () => {
+    const r = await send(admin.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect(r.body.capabilities).toContain("events");
+  });
+
+  test("create records one `created` event with the actor, title and seq", async () => {
+    const card = await create(member.token, { name: "动态示例一" });
+    const r = await events(admin.token, `&requirement_id=${card.id}`);
+    expect(r.status).toBe(200);
+    expect(r.body.events.length).toBe(1);
+    const [e] = r.body.events;
+    expect(e).toMatchObject({ kind: "created", field: null, actor: user(member.id), title: "动态示例一", seq: card.seq, new: { title: "动态示例一", column: "pool" } });
+    expect(typeof e.id).toBe("string");
+    expect(Date.parse(e.at)).toBeGreaterThan(0);
+  });
+
+  test("a PATCH records one event per changed field, old → new; unchanged fields and no-op PATCHes record nothing", async () => {
+    const card = await create(admin.token, { name: "动态示例二", priority: "normal", tags: ["UI"] });
+    const r1 = await patch(member.token, card.id, {
+      column: "doing", priority: "high", due: "2026-10-03", name: "动态示例二(改)", tags: ["UI", "后端"],
+      agent_owner: { kind: "node", id: NODE }, participants: [user(admin.id)], assignee: "",
+    });
+    expect(r1.status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    const byField = Object.fromEntries(list.filter((e: any) => e.kind === "changed").map((e: any) => [e.field, e]));
+    expect(Object.keys(byField).sort()).toEqual(["agent_owner", "column", "due", "participants", "priority", "tags", "title"]);
+    expect(byField.column).toMatchObject({ old: "pool", new: "doing", actor: user(member.id) });
+    expect(byField.priority).toMatchObject({ old: "normal", new: "high" });
+    expect(byField.due).toMatchObject({ old: null, new: "2026-10-03" });
+    expect(byField.title).toMatchObject({ old: "动态示例二", new: "动态示例二(改)" });
+    expect(byField.tags).toMatchObject({ old: ["UI"], new: ["UI", "后端"] });
+    expect(byField.agent_owner).toMatchObject({ old: null, new: { kind: "node", id: NODE } });
+    expect(byField.participants).toMatchObject({ old: [], new: [user(admin.id)] });
+    // every event of that PATCH carries the card's title after the change
+    expect(new Set(list.filter((e: any) => e.kind === "changed").map((e: any) => e.title))).toEqual(new Set(["动态示例二(改)"]));
+    const before = list.length;
+    expect((await patch(member.token, card.id, { priority: "high", column: "doing" })).status).toBe(200);
+    expect(of((await events(admin.token)).body.events, card.id).length).toBe(before);
+    // archive / unarchive, description (length only, never the text), move to done
+    await patch(member.token, card.id, { description: "一段描述" });
+    await patch(member.token, card.id, { column: "done" });
+    await patch(member.token, card.id, { archived: true });
+    const later = of((await events(admin.token)).body.events, card.id).slice(0, 3);
+    expect(later.map((e: any) => e.field)).toEqual(["archived", "column", "description"]);
+    expect(later[0]).toMatchObject({ old: false, new: true });
+    expect(later[1]).toMatchObject({ old: "doing", new: "done" });
+    expect(later[2]).toMatchObject({ old: { chars: 0 }, new: { chars: 4 } });
+    expect(JSON.stringify(later[2])).not.toContain("一段描述");
+  });
+
+  test("checklist: ticking an item is `checklist_item` (repeat is a no-op); adding items is `checklist`", async () => {
+    const card = await create(admin.token, { name: "动态示例三", checklist: [{ id: "a", text: "第一项" }, { id: "b", text: "第二项" }] });
+    const tick = (done: boolean) => send(member.token, "PATCH", `/api/requirements/${card.id}/checklist/a?network_id=${NET}`, { done });
+    expect((await tick(true)).status).toBe(200);
+    expect((await tick(true)).status).toBe(200);
+    let list = of((await events(admin.token)).body.events, card.id);
+    const ticks = list.filter((e: any) => e.field === "checklist_item");
+    expect(ticks.length).toBe(1);
+    expect(ticks[0]).toMatchObject({ old: { id: "a", text: "第一项", done: false }, new: { id: "a", text: "第一项", done: true }, actor: user(member.id) });
+    // a PATCH that only flips one item's done is also `checklist_item`
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }] });
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }, { id: "c", text: "第三项" }] });
+    list = of((await events(admin.token)).body.events, card.id);
+    expect(list[0]).toMatchObject({ field: "checklist", old: { total: 2, done: 2 }, new: { total: 3, done: 2 } });
+    expect(list[1]).toMatchObject({ field: "checklist_item", new: { id: "b", done: true } });
+  });
+
+  test("the actor of a node token is the node", async () => {
+    const card = await create(admin.token, { name: "动态示例四" });
+    expect((await patch(nodeToken, card.id, { column: "doing" })).status).toBe(200);
+    const [e] = of((await events(nodeToken)).body.events, card.id);
+    expect(e).toMatchObject({ field: "column", actor: { kind: "node", id: NODE } });
+  });
+
+  test("tag rename, project delete and card delete each record per-card events", async () => {
+    const p = await send(admin.token, "POST", `/api/requirements/projects?network_id=${NET}`, { name: `动态项目-${Date.now()}` });
+    expect(p.status).toBe(201);
+    const card = await create(admin.token, { name: "动态示例五", tags: ["旧标签"], project_id: p.body.project.id });
+    expect((await send(admin.token, "POST", `/api/requirements/tags/ops?network_id=${NET}`, { op: "rename", from: "旧标签", to: "新标签" })).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/projects/${p.body.project.id}?network_id=${NET}`)).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/${card.id}?network_id=${NET}`)).status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    expect(list.slice(0, 3).map((e: any) => [e.kind, e.field])).toEqual([["deleted", null], ["changed", "project"], ["changed", "tags"]]);
+    expect(list[0]).toMatchObject({ title: "动态示例五", seq: expect.any(Number), actor: user(admin.id) });
+    expect(list[1]).toMatchObject({ old: p.body.project.id, new: null });
+    expect(list[2]).toMatchObject({ old: ["旧标签"], new: ["新标签"] });
+  });
+
+  test("the write and its events are one transaction: no events table → the PATCH fails and the card is unchanged", async () => {
+    const { db } = await import("./db.js");
+    const card = await create(admin.token, { name: "动态示例六", priority: "low" });
+    db.exec("ALTER TABLE requirement_events RENAME TO requirement_events_away");
+    try {
+      const r = await patch(admin.token, card.id, { priority: "high" });
+      expect(r.status).toBeGreaterThanOrEqual(500);
+    } finally {
+      db.exec("ALTER TABLE requirement_events_away RENAME TO requirement_events");
+    }
+    const now = await send(admin.token, "GET", `/api/requirements/${card.id}?network_id=${NET}`);
+    expect(now.body.requirement.priority).toBe("low");
+  });
+
+  test("a scoped member sees events only for cards they can see — deleted ones by their tombstone", async () => {
+    const mine = await create(scoped.token, { name: "动态示例七(scoped 自己建的)" });
+    const theirs = await create(admin.token, { name: "动态示例八(scoped 看不见)" });
+    const joined = await create(admin.token, { name: "动态示例九(scoped 是参与人)", participants: [user(scoped.id)] });
+    await patch(admin.token, mine.id, { priority: "high" });
+    await patch(admin.token, theirs.id, { priority: "high" });
+    await send(admin.token, "DELETE", `/api/requirements/${joined.id}?network_id=${NET}`);
+    const seen = (await events(scoped.token, "&limit=500")).body.events;
+    expect(of(seen, mine.id).length).toBe(2);
+    expect(of(seen, theirs.id).length).toBe(0);
+    expect(of(seen, joined.id).map((e: any) => e.kind)).toEqual(["deleted", "created"]);
+    // a filter on a card they cannot see answers like a card with no events
+    expect((await events(scoped.token, `&requirement_id=${theirs.id}`)).body.events).toEqual([]);
+  });
+
+  test("an agent-restricted member: hidden nodes are masked, and an event that only differs by a hidden node is dropped", async () => {
+    const card = await create(admin.token, { name: "动态示例十" });
+    await patch(nodeToken, card.id, { priority: "high" });
+    await patch(admin.token, card.id, { agent_owner: { kind: "node", id: NODE } });
+    await patch(admin.token, card.id, { participants: [user(admin.id), { kind: "node", id: NODE }] });
+    const seen = of((await events(restricted.token)).body.events, card.id);
+    const all = of((await events(admin.token)).body.events, card.id);
+    expect(all.map((e: any) => e.field)).toEqual(["participants", "agent_owner", "priority", null]);
+    expect(seen.map((e: any) => e.field)).toEqual(["participants", "priority", null]);
+    expect(seen[0]).toMatchObject({ old: [], new: [user(admin.id)] });
+    expect(seen[1]).toMatchObject({ field: "priority", actor: null });
+    expect(JSON.stringify(seen)).not.toContain(NODE);
+  });
+
+  test("paging: newest first, limit + next_cursor without overlap; since; bad params 400", async () => {
+    const card = await create(admin.token, { name: "动态示例十一" });
+    for (const priority of ["high", "low", "lowest", "normal"]) await patch(admin.token, card.id, { priority });
+    const q = `&requirement_id=${card.id}`;
+    const p1 = await events(admin.token, `${q}&limit=2`);
+    expect(p1.body.events.length).toBe(2);
+    expect(p1.body.has_more).toBe(true);
+    expect(p1.body.events[0].new).toBe("normal");
+    const p2 = await events(admin.token, `${q}&limit=2&cursor=${p1.body.next_cursor}`);
+    const p3 = await events(admin.token, `${q}&limit=2&cursor=${p2.body.next_cursor}`);
+    const ids = [...p1.body.events, ...p2.body.events, ...p3.body.events].map((e: any) => e.id);
+    expect(new Set(ids).size).toBe(5);
+    expect(p3.body.has_more).toBe(false);
+    expect(p3.body.next_cursor).toBe(null);
+    expect(ids.map(Number)).toEqual([...ids.map(Number)].sort((a, b) => b - a));
+    // since = server_time of an earlier read → only what came after
+    const t = p1.body.server_time;
+    await patch(admin.token, card.id, { priority: "high" });
+    const after = await events(admin.token, `${q}&since=${encodeURIComponent(t)}`);
+    // since is inclusive (>=): an event written in the same millisecond as server_time comes back again,
+    // and clients dedupe by id. Only the events not already seen must be exactly the new one.
+    expect(after.body.events.every((e: any) => Date.parse(e.at) >= Date.parse(t))).toBe(true);
+    const seen = new Set(ids);
+    expect(after.body.events.filter((e: any) => !seen.has(e.id)).map((e: any) => e.new)).toEqual(["high"]);
+    for (const bad of ["&limit=0", "&limit=501", "&limit=x", "&since=nope", "&cursor=abc", "&cursor=0"]) {
+      expect((await events(admin.token, bad)).status).toBe(400);
+    }
+  });
+
+  test("migration is idempotent and leaves the rows alone", async () => {
+    const { db } = await import("./db.js");
+    const { ensureRequirementEvents } = await import("./requirement-events.js");
+    const n = Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n);
+    ensureRequirementEvents(db);
+    ensureRequirementEvents(db);
+    expect(Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n)).toBe(n);
+    expect(n).toBeGreaterThan(0);
+  });
+});

package/src/requirement-events.test.ts

@@ -0,0 +1,45 @@
+// diffRequirement 的边角(HTTP 层的写路径在 requirement-events-http.test.ts)。
+import { describe, expect, test } from "bun:test";
+import { diffRequirement, eventPublic, type EventCard } from "./requirement-events.js";
+
+const base: EventCard = {
+  requirement_id: "req_1", network_id: "net_1", seq: 7, title: "示例", column_name: "pool", priority: "normal", due_on: null, start_on: null,
+  assignee: null, owner_json: null, agent_owner_json: null, participants_json: "[]", tags_json: "[]", checklist_json: "[]", description: null,
+  project_id: null, parent_id: null, archived: 0,
+};
+const ck = (items: { id: string; text: string; done?: boolean }[]) => JSON.stringify(items.map(i => ({ done: false, ...i })));
+
+describe("diffRequirement", () => {
+  test("no change → no events; null vs empty string are the same", () => {
+    expect(diffRequirement(base, { ...base })).toEqual([]);
+    expect(diffRequirement(base, { ...base, due_on: "", assignee: "", description: "" })).toEqual([]);
+  });
+  test("created carries title and column only", () => {
+    expect(diffRequirement(null, base)).toEqual([{ kind: "created", field: null, old: null, new: { title: "示例", column: "pool" } }]);
+  });
+  test("checklist: reorder, rename, add or remove is one `checklist` event with counts", () => {
+    const a = { ...base, checklist_json: ck([{ id: "a", text: "一" }, { id: "b", text: "二", done: true }]) };
+    for (const next of [ck([{ id: "b", text: "二", done: true }, { id: "a", text: "一" }]), ck([{ id: "a", text: "一改" }, { id: "b", text: "二", done: true }]), ck([{ id: "a", text: "一" }])]) {
+      const out = diffRequirement(a, { ...a, checklist_json: next });
+      expect(out.length).toBe(1);
+      expect(out[0].field).toBe("checklist");
+    }
+    expect(diffRequirement(a, { ...a, checklist_json: ck([{ id: "a", text: "一" }]) })[0]).toMatchObject({ old: { total: 2, done: 1 }, new: { total: 1, done: 0 } });
+  });
+  test("checklist: two items ticked in one write are two `checklist_item` events", () => {
+    const a = { ...base, checklist_json: ck([{ id: "a", text: "一" }, { id: "b", text: "二" }]) };
+    const out = diffRequirement(a, { ...a, checklist_json: ck([{ id: "a", text: "一", done: true }, { id: "b", text: "二", done: true }]) });
+    expect(out.map(e => [e.field, (e.new as { id: string }).id])).toEqual([["checklist_item", "a"], ["checklist_item", "b"]]);
+  });
+  test("malformed stored JSON reads as empty rather than throwing", () => {
+    expect(() => diffRequirement({ ...base, tags_json: "{nope", participants_json: "x" }, base)).not.toThrow();
+  });
+  test("description records lengths, never text", () => {
+    const [e] = diffRequirement(base, { ...base, description: "secret text" });
+    expect(e).toEqual({ kind: "changed", field: "description", old: { chars: 0 }, new: { chars: 11 } });
+  });
+  test("eventPublic: bigint / string ids from PostgreSQL come out as strings, seq as a number", () => {
+    const row = { id: 12n as unknown as string, network_id: "n", requirement_id: "r", seq: "3", title: "t", actor_json: null, kind: "changed", field: "priority", old_json: "\"low\"", new_json: "\"high\"", created_at: "2026-10-01T00:00:00.000Z" };
+    expect(eventPublic(row)).toMatchObject({ id: "12", seq: 3, old: "low", new: "high", actor: null });
+  });
+});

package/src/requirement-events.ts

@@ -0,0 +1,143 @@
+// 任务动态(#429,Vincent 2026-09-30「任务有新的状态…这完成了,这是有这种动态」)。
+//
+// requirements 表只存「现在是什么」和「最后是谁改的」(updated_by_json),改之前是什么没有任何地方留着 ——
+// 「优先级 P2 → P0」「状态 需求池 → 进行中」画不出来。这里给每一次写入记字段级的流水:谁(用户 / 节点)、
+// 什么时候、哪个字段、旧值 → 新值。写入点在 requirements.ts 的各条写路径里,和那次 UPDATE 在同一个事务里。
+//
+// 表只加不改:旧 Hub(回滚之后)不认识这张表,也不会碰它;再升回来接着记(回滚期间的改动没有流水)。
+// 读:GET /api/requirements/events(requirements.ts,可见范围与列表相同),capability `events`。
+import type { DbAdapter } from "./db-adapter.js";
+
+/** 流水保留多久。更早的在写入时顺手清掉(每 PRUNE_EVERY 次写一次)。 */
+export const EVENTS_RETENTION_MS = 180 * 86_400_000;
+const PRUNE_EVERY = 500;
+
+/** IF NOT EXISTS:重复执行无副作用;SQLite / PostgreSQL 同一段(适配层把 AUTOINCREMENT 译成 BIGSERIAL)。 */
+export function ensureRequirementEvents(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_events (
+      id             INTEGER PRIMARY KEY AUTOINCREMENT,
+      network_id     TEXT NOT NULL,
+      requirement_id TEXT NOT NULL,
+      seq            INTEGER,
+      title          TEXT,
+      actor_json     TEXT,
+      kind           TEXT NOT NULL,
+      field          TEXT,
+      old_json       TEXT,
+      new_json       TEXT,
+      created_at     TEXT NOT NULL
+    );
+  `);
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_network ON requirement_events(network_id, id)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_card ON requirement_events(requirement_id, id)");
+  database.exec("CREATE INDEX IF NOT EXISTS idx_requirement_events_created ON requirement_events(created_at)");
+}
+
+/** 流水要比较的列(requirements.ts 的 Row 的子集)。 */
+export type EventCard = {
+  requirement_id: string;
+  network_id: string;
+  seq: number | null;
+  title: string;
+  column_name: string;
+  priority: string;
+  due_on: string | null;
+  start_on: string | null;
+  assignee: string | null;
+  owner_json: string | null;
+  agent_owner_json: string | null;
+  participants_json: string | null;
+  tags_json: string | null;
+  checklist_json: string | null;
+  description: string | null;
+  project_id: string | null;
+  parent_id: string | null;
+  archived: number | null;
+};
+
+export type EventKind = "created" | "changed" | "deleted";
+/**
+ * field(kind = changed):column / title / priority / due / start / assignee / owner / agent_owner / participants /
+ * tags / checklist_item(勾选或取消一项:{id,text,done})/ checklist(增删改条目:{total,done})/
+ * description(只记字数,不存正文)/ project / parent / archived。
+ */
+export type EventDraft = { kind: EventKind; field: string | null; old: unknown; new: unknown };
+
+const parse = (json: string | null | undefined): unknown => {
+  if (!json) return null;
+  try { return JSON.parse(json); } catch { return null; }
+};
+const list = (json: string | null | undefined): unknown[] => { const v = parse(json); return Array.isArray(v) ? v : []; };
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+type Item = { id: string; text: string; done: boolean };
+const items = (json: string | null | undefined): Item[] =>
+  list(json).filter((x): x is Item => !!x && typeof (x as Item).id === "string" && typeof (x as Item).text === "string").map(x => ({ id: x.id, text: x.text, done: !!x.done }));
+const counts = (xs: Item[]) => ({ total: xs.length, done: xs.filter(x => x.done).length });
+
+/** 一次写入前后的差异。before = null:新建(只记一条 created)。 */
+export function diffRequirement(before: EventCard | null, after: EventCard): EventDraft[] {
+  if (!before) return [{ kind: "created", field: null, old: null, new: { title: after.title, column: after.column_name } }];
+  const out: EventDraft[] = [];
+  const scalar = (field: string, a: unknown, b: unknown) => { if (!same(a, b)) out.push({ kind: "changed", field, old: a, new: b }); };
+  scalar("column", before.column_name, after.column_name);
+  scalar("title", before.title, after.title);
+  scalar("priority", before.priority, after.priority);
+  scalar("due", before.due_on || null, after.due_on || null);
+  scalar("start", before.start_on || null, after.start_on || null);
+  scalar("assignee", before.assignee || null, after.assignee || null);
+  scalar("owner", parse(before.owner_json), parse(after.owner_json));
+  scalar("agent_owner", parse(before.agent_owner_json), parse(after.agent_owner_json));
+  scalar("participants", list(before.participants_json), list(after.participants_json));
+  scalar("tags", list(before.tags_json), list(after.tags_json));
+  // 子任务:同一条(同 id、同文字)只是勾选变了 = 一条 checklist_item;条目增删 / 改字 / 换顺序 = 一条 checklist。
+  const a = items(before.checklist_json), b = items(after.checklist_json);
+  const shape = (xs: Item[]) => xs.map(x => `${x.id}\u0000${x.text}`).join("\u0001");
+  if (shape(a) === shape(b)) {
+    for (let i = 0; i < b.length; i++) if (a[i].done !== b[i].done) out.push({ kind: "changed", field: "checklist_item", old: a[i], new: b[i] });
+  } else {
+    out.push({ kind: "changed", field: "checklist", old: counts(a), new: counts(b) });
+  }
+  if ((before.description || "") !== (after.description || "")) {
+    out.push({ kind: "changed", field: "description", old: { chars: (before.description || "").length }, new: { chars: (after.description || "").length } });
+  }
+  scalar("project", before.project_id || null, after.project_id || null);
+  scalar("parent", before.parent_id || null, after.parent_id || null);
+  scalar("archived", !!before.archived, !!after.archived);
+  return out;
+}
+
+let writes = 0;
+
+/** 记下一张卡的一组流水(调用方负责放进同一个事务)。actorJson = updated_by_json 的那个值。 */
+export function recordRequirementEvents(database: DbAdapter, card: Pick<EventCard, "requirement_id" | "network_id" | "seq" | "title">, actorJson: string | null, drafts: readonly EventDraft[], at: string): void {
+  for (const d of drafts) {
+    database.run(
+      `INSERT INTO requirement_events (network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)`,
+      [card.network_id, card.requirement_id, card.seq ?? null, card.title, actorJson && actorJson !== "null" ? actorJson : null, d.kind, d.field,
+        d.old === null || d.old === undefined ? null : JSON.stringify(d.old), d.new === null || d.new === undefined ? null : JSON.stringify(d.new), at],
+    );
+    writes++;
+  }
+  if (drafts.length && writes >= PRUNE_EVERY) {
+    writes = 0;
+    database.run("DELETE FROM requirement_events WHERE created_at < ?1", [new Date(Date.parse(at) - EVENTS_RETENTION_MS).toISOString()]);
+  }
+}
+
+export type EventRow = { id: number | string; network_id: string; requirement_id: string; seq: number | string | null; title: string | null; actor_json: string | null; kind: string; field: string | null; old_json: string | null; new_json: string | null; created_at: string };
+
+/** 对外的一条(id 转成字符串:PostgreSQL 的 BIGSERIAL 可能回成字符串或 bigint,客户端一律按字符串比较 / 翻页)。 */
+export const eventPublic = (row: EventRow) => ({
+  id: String(row.id),
+  requirement_id: row.requirement_id,
+  seq: row.seq == null ? null : Number(row.seq),
+  title: row.title,
+  actor: parse(row.actor_json),
+  kind: row.kind,
+  field: row.field,
+  old: parse(row.old_json),
+  new: parse(row.new_json),
+  at: row.created_at,
+});

package/src/requirements-http.test.ts

@@ -373,7 +373,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", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes"]);
+    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", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {

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

package/src/requirements.ts

@@ -12,6 +12,7 @@ import {
   addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject,
   isTaskScoped, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
+import { diffRequirement, ensureRequirementEvents, eventPublic, recordRequirementEvents, type EventRow } from "./requirement-events.js";
 import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
@@ -24,6 +25,7 @@ ensureRequirementSeq(db);
 ensureRequirementCompletedAt(db);
 ensureNetworkTags(db);
 ensureRequirementTombstones(db);
+ensureRequirementEvents(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -285,8 +287,15 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
   if (req.method === "DELETE") {
     // 先把卡片上的引用置空,再删项目:卡片一张不少。
     // updated_at 跟着动:按 updated_since 增量同步的客户端要看得见「项目被清空」这一改动。
-    db.run("UPDATE requirements SET project_id = NULL, updated_at = ?2 WHERE project_id = ?1", [current.project_id, new Date().toISOString()]);
-    db.run("DELETE FROM requirement_projects WHERE project_id = ?1", [current.project_id]);
+    // 每张被清空项目的卡记一条「项目 X → 无」(与清空同一个事务)。
+    const at = new Date().toISOString();
+    const actor = JSON.stringify(actorOf(ctx));
+    db.transaction(() => {
+      const cards = db.all<{ requirement_id: string; network_id: string; seq: number | null; title: string }>("SELECT requirement_id, network_id, seq, title FROM requirements WHERE project_id = ?1", current.project_id);
+      db.run("UPDATE requirements SET project_id = NULL, updated_at = ?2 WHERE project_id = ?1", [current.project_id, at]);
+      for (const card of cards) recordRequirementEvents(db, card, actor, [{ kind: "changed", field: "project", old: current.project_id, new: null }], at);
+      db.run("DELETE FROM requirement_projects WHERE project_id = ?1", [current.project_id]);
+    });
     deleteTaskGrantsForProject(current.project_id);
     return Response.json({ ok: true });
   }
@@ -335,8 +344,8 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
   const actor = JSON.stringify(actorOf(ctx));
   // 读-改-写整个网络的标签在一个事务里:中途失败一张都不改;颜色表跟着一起挪。
   const result = db.transaction(() => {
-    const cards = db.all<{ requirement_id: string; tags_json: string | null }>(
-      "SELECT requirement_id, tags_json FROM requirements WHERE network_id = ?1 AND tags_json IS NOT NULL AND tags_json <> '[]'", networkId,
+    const cards = db.all<{ requirement_id: string; network_id: string; seq: number | null; title: string; tags_json: string | null }>(
+      "SELECT requirement_id, network_id, seq, title, tags_json FROM requirements WHERE network_id = ?1 AND tags_json IS NOT NULL AND tags_json <> '[]'", networkId,
     );
     const colorOf = (name: string) => db.get<{ color: string }>("SELECT color FROM network_tags WHERE network_id = ?1 AND name = ?2", networkId, name)?.color ?? null;
     const sources = op.op === "rename" ? [op.from] : op.op === "merge" ? op.from : [op.tag];
@@ -352,6 +361,7 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
       const next = applyTagOp(storedTags(card.tags_json), op);
       if (!next) continue;
       db.run("UPDATE requirements SET tags_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(next), now, actor, card.requirement_id]);
+      recordRequirementEvents(db, card, actor, [{ kind: "changed", field: "tags", old: storedTags(card.tags_json), new: next }], now);
       affected++;
     }
     moveTagColors(networkId, op, colorOf, now);
@@ -581,7 +591,8 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
 // search:GET 认 q=(服务端搜索,语义同 App 的任务搜索);paging:认 limit / cursor,响应带 has_more / next_cursor。
 // list_summary:GET 认 view=summary(不带描述正文与子任务条目,见 toSummary);changes:GET 认 changes=1 + updated_since
 // (改过的卡含归档的,加上 deleted 墓碑与 server_time,见 listChanges)。
-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", "completed_at", "stats", "tag_ops", "list_summary", "changes"] as const;
+// events:GET /api/requirements/events —— 字段级的改动流水(谁、何时、旧值 → 新值,requirement-events.ts)。
+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", "completed_at", "stats", "tag_ops", "list_summary", "changes", "events"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -738,15 +749,19 @@ 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.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, seq, completed_at, completed_by_json, completed_at_approx)
-       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, ?25, ?26, 0)`,
-      [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),
-        // 直接建在「完成」列 = 此刻完成、由建卡的人完成。
-        column === "done" ? createdAt : null, column === "done" ? actor : null],
-    ));
+    // 领号、插入、记「新建」这条动态在同一个事务里:插入被唯一索引挡下时,号和动态一起回滚,不留空洞。
+    db.transaction(() => {
+      const seq = nextRequirementSeq(db, networkId);
+      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, seq, completed_at, completed_by_json, completed_at_approx)
+         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, ?25, ?26, 0)`,
+        [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, seq,
+          // 直接建在「完成」列 = 此刻完成、由建卡的人完成。
+          column === "done" ? createdAt : null, column === "done" ? actor : null],
+      );
+      recordRequirementEvents(db, { requirement_id: id, network_id: networkId, seq, title: name }, actor, [{ kind: "created", field: null, old: null, new: { title: name, column } }], createdAt);
+    });
   } catch {
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
     if (ref) {
@@ -857,16 +872,21 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   const completed = column !== "done" ? { at: null, by: null, approx: 0 }
     : row.column_name !== "done" ? { at: updatedAt, by: actor, approx: 0 }
     : { at: row.completed_at, by: row.completed_by_json, approx: row.completed_at_approx ? 1 : 0 };
-  db.run(
-    `UPDATE requirements SET column_name = ?1, updated_at = ?2, title = ?7, priority = ?8, due_on = ?9, assignee = ?10, owner_json = ?4, participants_json = ?5, issues_json = ?6,
-       agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20, start_on = ?21,
-       completed_at = ?22, completed_by_json = ?23, completed_at_approx = ?24
-     WHERE requirement_id = ?3`,
-    [column, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
-      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, actor, parentId, has("tags") ? JSON.stringify(tags) : row.tags_json, start || null,
-      completed.at, completed.by, completed.approx],
-  );
-  const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+  // 改卡和记动态(改前 row → 改后 updated 的字段差异)在同一个事务里:要么都在,要么都不在。
+  const updated = db.transaction(() => {
+    db.run(
+      `UPDATE requirements SET column_name = ?1, updated_at = ?2, title = ?7, priority = ?8, due_on = ?9, assignee = ?10, owner_json = ?4, participants_json = ?5, issues_json = ?6,
+         agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20, start_on = ?21,
+         completed_at = ?22, completed_by_json = ?23, completed_at_approx = ?24
+       WHERE requirement_id = ?3`,
+      [column, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
+        has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, actor, parentId, has("tags") ? JSON.stringify(tags) : row.tags_json, start || null,
+        completed.at, completed.by, completed.approx],
+    );
+    const after = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+    recordRequirementEvents(db, after, actor, diffRequirement(row, after), updatedAt);
+    return after;
+  });
   return Response.json(withLegacyOwner(toPublicFor(ctx, updated), people.coerced));
 }
 
@@ -1046,6 +1066,86 @@ function deletedSince(ctx: RequirementsRequestContext, sinceIso: string): string
   return db.all<TombstoneRow>(sql, ...params).filter(row => canSeeTask(caller, row)).map(row => row.requirement_id);
 }
 
+// ── 任务动态(requirement-events.ts)──
+// GET /api/requirements/events?network_id&since&limit&cursor&requirement_id:一个网络的改动流水,按 id 从新到旧。
+// 可见范围与列表相同:卡还在 → 按当前这张卡判断调用者看不看得见;删掉了 → 按墓碑(过了墓碑保留期的删除,
+// 只有不受任务范围限制的调用者看得到)。受限成员看不见的节点:操作者隐去,负责人 / 负责 Agent / 参与人里的隐去,
+// 隐去之后前后一样的那条整条不回(否则是「这张卡的 Agent 换过」的探测器)。
+// 按可见性过滤是在读出来之后做的:一页最多扫 EVENTS_SCAN_MAX 条,扫满还没凑够就带 next_cursor 回去,客户端接着翻。
+const EVENTS_PAGE_DEFAULT = 200;
+const EVENTS_PAGE_MAX = 500;
+const EVENTS_SCAN_MAX = 5000;
+type VisibilityRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null };
+
+function listEvents(ctx: RequirementsRequestContext): Response {
+  const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+  if (!networkId) return jsonError("network_id_required", 400);
+  const q = ctx.url.searchParams;
+  const limit = q.get("limit") === null ? EVENTS_PAGE_DEFAULT : Number(q.get("limit"));
+  if (!Number.isInteger(limit) || limit < 1 || limit > EVENTS_PAGE_MAX) return jsonError("invalid_limit", 400);
+  let since: string | null = null;
+  if (q.get("since") !== null) {
+    const ms = Date.parse(q.get("since")!);
+    if (!Number.isFinite(ms)) return jsonError("invalid_since", 400);
+    since = new Date(ms).toISOString();
+  }
+  const cursor = q.get("cursor");
+  if (cursor !== null && !/^[1-9]\d{0,17}$/.test(cursor)) return jsonError("invalid_cursor", 400);
+  const card = q.get("requirement_id");
+  // server_time 取在读表之前:下次拿它当 since,读的期间写进来的不会漏(>= 会重复回,客户端按 id 去重)。
+  const serverTime = new Date().toISOString();
+  const caller = taskCaller(ctx);
+  const hidden = hiddenNodeFilter(ctx, networkId);
+  const seen = new Map<string, boolean>();
+  const canSee = (id: string): boolean => {
+    if (!caller) return true;
+    let ok = seen.get(id);
+    if (ok === undefined) {
+      const cols = "network_id, owner_json, participants_json, created_by, created_by_json, project_id";
+      const row = db.get<VisibilityRow>(`SELECT ${cols} FROM requirements WHERE requirement_id = ?1`, id)
+        ?? db.get<VisibilityRow>(`SELECT ${cols} FROM requirement_tombstones WHERE requirement_id = ?1`, id);
+      seen.set(id, ok = !!row && row.network_id === networkId && canSeeTask(caller, row));
+    }
+    return ok;
+  };
+  const shown = (row: EventRow) => {
+    if (!canSee(row.requirement_id)) return null;
+    const ev = eventPublic(row);
+    if (!hidden) return ev;
+    const mask = (ref: unknown) => (isHiddenRef(ref, hidden) ? null : ref);
+    const masked = { ...ev, actor: mask(ev.actor) };
+    if (ev.field === "owner" || ev.field === "agent_owner") { masked.old = mask(ev.old); masked.new = mask(ev.new); }
+    if (ev.field === "participants") {
+      masked.old = Array.isArray(ev.old) ? ev.old.filter(ref => !isHiddenRef(ref, hidden)) : ev.old;
+      masked.new = Array.isArray(ev.new) ? ev.new.filter(ref => !isHiddenRef(ref, hidden)) : ev.new;
+    }
+    return ev.field && JSON.stringify(masked.old) === JSON.stringify(masked.new) ? null : masked;
+  };
+  const events: ReturnType<typeof eventPublic>[] = [];
+  let before = cursor === null ? null : Number(cursor);
+  let scanned = 0;
+  let nextCursor: string | null = null;
+  scan: for (;;) {
+    const params: unknown[] = [networkId];
+    let sql = "SELECT id, network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at FROM requirement_events WHERE network_id = ?1";
+    if (since) sql += ` AND created_at >= ?${params.push(since)}`;
+    if (card) sql += ` AND requirement_id = ?${params.push(card)}`;
+    if (before !== null) sql += ` AND id < ?${params.push(before)}`;
+    const batch = db.all<EventRow>(`${sql} ORDER BY id DESC LIMIT ${limit + 1}`, ...params);
+    for (const row of batch) {
+      const ev = shown(row);
+      if (ev && events.length === limit) { nextCursor = events[events.length - 1].id; break scan; }
+      scanned++;
+      before = Number(row.id);
+      if (ev) events.push(ev);
+    }
+    if (batch.length < limit + 1) break;
+    // 扫满了(调用者看不见的太多):从扫到的地方接着翻。
+    if (scanned >= EVENTS_SCAN_MAX) { nextCursor = String(before); break; }
+  }
+  return Response.json({ ok: true, network_id: networkId, events, has_more: nextCursor !== null, next_cursor: nextCursor, server_time: serverTime });
+}
+
 /**
  * 需求表的写入代数:每个经过 handleRequirementsRequest 的非 GET 请求处理完就 +1(REST 和 MCP 的写入都走它,
  * tools.ts 调的是同一个处理函数)。列表缓存只在代数没变时复用。进程重启 = 缓存清空。
@@ -1152,15 +1252,21 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     return conditionalJson(ctx.req, { ok: true, networkId, ...aggregateStats(rows, sq, hiddenNodeFilter(ctx, networkId)) });
   }
 
+  if (url.pathname === "/api/requirements/events" && req.method === "GET") return listEvents(ctx);
+
   if (url.pathname === '/api/requirements/people' && req.method === 'GET') {
     const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
     if (!networkId) return jsonError('network_id_required', 400);
-    const users = 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 ORDER BY name, id", networkId,
+    // name = 显示用的名字(没设 display_name 时回落到用户名 / alias,旧 app 只读它);display_name 单独给出、没设为 ""
+    // —— 分享图等对外场景据此判断「只有用户名」,不把 admin 之类的账号名印出去。
+    // 成员的 display_name 等于用户名也算「没设」:register() 在没给显示名时存的就是 username(auth.ts),
+    // 否则没设过显示名的账号(比如 admin)照样把账号名当显示名送出去。
+    const users = db.all<{ id: string; name: string; display_name: string }>(
+      "SELECT u.user_id AS id, COALESCE(NULLIF(u.display_name,''), u.username) AS name, CASE WHEN u.display_name IS NULL OR u.display_name = '' OR u.display_name = u.username THEN '' ELSE u.display_name END AS display_name FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 ORDER BY name, id", networkId,
     );
     const hidden = hiddenNodeFilter(ctx, networkId);
-    const nodes = 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 ORDER BY name, id", networkId,
+    const nodes = db.all<{ id: string; name: string; display_name: string }>(
+      "SELECT node_id AS id, COALESCE(NULLIF(display_name,''), NULLIF(alias,''), node_name) AS name, COALESCE(display_name,'') AS display_name FROM nodes WHERE network_id=?1 ORDER BY name, id", networkId,
     ).filter(row => !hidden?.(row.id));
     return Response.json({ ok: true, people: [...users.map(row => ({ ...row, kind: 'user', networkId })), ...nodes.map(row => ({ ...row, kind: 'node', networkId }))] });
   }
@@ -1257,9 +1363,16 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const itemId = decodeURIComponent(itemMatch[2]);
     const item = items.find(entry => entry.id === itemId);
     if (!item) return jsonError("checklist_item_not_found", 404);
+    const was = item.done;
     item.done = body.done;
-    db.run("UPDATE requirements SET checklist_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(items), new Date().toISOString(), JSON.stringify(actorOf(ctx)), row.requirement_id]);
-    const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+    const at = new Date().toISOString();
+    const actor = JSON.stringify(actorOf(ctx));
+    const updated = db.transaction(() => {
+      db.run("UPDATE requirements SET checklist_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(items), at, actor, row.requirement_id]);
+      // 重复勾同一个值(done 是显式值,幂等)不算一次改动,不记。
+      if (was !== item.done) recordRequirementEvents(db, row, actor, [{ kind: "changed", field: "checklist_item", old: { ...item, done: was }, new: { ...item } }], at);
+      return db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+    });
     return Response.json({ ok: true, requirement: toPublicFor(ctx, updated) });
   }
 
@@ -1278,9 +1391,13 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     if (!canDeleteTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_delete_denied");
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
     const deletedAt = new Date().toISOString();
-    db.run("UPDATE requirements SET parent_id = NULL, updated_at = ?2 WHERE parent_id = ?1", [row.requirement_id, deletedAt]);
-    db.run("DELETE FROM requirements WHERE requirement_id = ?1", [row.requirement_id]);
-    recordTombstone(row, deletedAt);
+    db.transaction(() => {
+      db.run("UPDATE requirements SET parent_id = NULL, updated_at = ?2 WHERE parent_id = ?1", [row.requirement_id, deletedAt]);
+      db.run("DELETE FROM requirements WHERE requirement_id = ?1", [row.requirement_id]);
+      recordTombstone(row, deletedAt);
+      // 卡没了,动态里还要画得出「谁删了 #N 标题」:标题 / 短号随行存(seq、title 列)。
+      recordRequirementEvents(db, row, JSON.stringify(actorOf(ctx)), [{ kind: "deleted", field: null, old: null, new: null }], deletedAt);
+    });
     // 硬删除以前不留痕(RFC-038 §9.1):记下是谁删了哪张(标题 + 短号),卡本身已经没了。
     if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_deleted", "requirement", row.requirement_id, JSON.stringify({ title: row.title, seq: row.seq ?? null }).slice(0, 1000), undefined, row.network_id);
     return Response.json({ ok: true, deleted: row.requirement_id });