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

package/src/requirements-mcp.test.ts

@@ -0,0 +1,142 @@
+// 需求池 MCP 工具:走真 MCP in-process transport。Agent(节点令牌)在自己网络里读 / 建 / 改 / 勾 / upsert、
+// 别的网络的节点碰不到、删除不存在于工具里(只有人能在 REST 删)。同步场景:同一个 GitHub issue 同步两次不重复。
+// 跑法:cd server && COMMHUB_DB=/tmp/req-mcp.db bun test src/requirements-mcp.test.ts
+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-mcp-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+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 { db } = await import("./db.js");
+const { register, createNetworkTokenForNode } = await import("./auth.js");
+const { registerTools } = await import("./tools.js");
+
+type Identity = { net: string; user: string; alias: string; isNetworkToken: boolean; tokenId: string };
+let owner: Identity, bot: Identity, foreignBot: Identity;
+let ownerNet = "";
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "req-mcp-test", version: "1" });
+  registerTools(server, undefined, id.isNetworkToken ? id.net : null, id.user, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "req-mcp-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const first = r.content?.[0];
+    if (r.isError) return { mcpError: true, text: first?.text };
+    return JSON.parse(first.text);
+  };
+  return { server, call, close: async () => { await client.close(); await server.close(); } };
+}
+
+beforeAll(() => {
+  const o = register(`reqmcp_owner_${Date.now()}`, "ReqMcpOwner123!", undefined, "seed");
+  const x = register(`reqmcp_other_${Date.now()}`, "ReqMcpOther123!", undefined, "seed");
+  ownerNet = o.network_id!;
+  const t1 = createNetworkTokenForNode(o.user!.user_id, ownerNet, "gh-sync", "node_gh_sync");
+  const t2 = createNetworkTokenForNode(x.user!.user_id, x.network_id!, "foreign", "node_foreign");
+  owner = { net: ownerNet, user: o.user!.user_id, alias: o.user!.username, isNetworkToken: false, tokenId: "tok_user" };
+  bot = { net: ownerNet, user: o.user!.user_id, alias: "gh-sync", isNetworkToken: true, tokenId: t1.token_id! };
+  foreignBot = { net: x.network_id!, user: x.user!.user_id, alias: "foreign", isNetworkToken: true, tokenId: t2.token_id! };
+});
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+describe("requirements MCP tools", () => {
+  test("the seven tools are registered with validated schemas; there is no delete tool", async () => {
+    const s = await connect(owner);
+    try {
+      const reg: Record<string, any> = (s.server as any)._registeredTools;
+      for (const n of ["requirements_list", "requirements_get", "requirements_create", "requirements_update", "requirements_checklist_toggle", "requirements_upsert_by_external_ref", "projects_list"]) expect(reg[n], n).toBeDefined();
+      expect(Object.keys(reg).some(n => /^requirements_delete/.test(n))).toBe(false);
+      // 校验:坏的 status / 负责人种类 / 子任务 id 在协议边界被拒
+      expect((await s.call("requirements_list", { status: "nope" })).mcpError).toBe(true);
+      expect((await s.call("requirements_create", { name: "x", owner: { kind: "robot", id: "a" } })).mcpError).toBe(true);
+      expect((await s.call("requirements_checklist_toggle", { id: "r", item_id: "has space", done: true })).mcpError).toBe(true);
+      expect((await s.call("requirements_create", { name: "" })).mcpError).toBe(true);
+      // P0–P3:lowest(P3 极低)在建 / 改 / upsert 都能写;不认识的值在协议边界被拒
+      expect((await s.call("requirements_create", { name: "x", priority: "urgent" })).mcpError).toBe(true);
+      const low = await s.call("requirements_create", { name: "极低", priority: "lowest" });
+      expect(low.requirement.priority).toBe("lowest");
+      expect((await s.call("requirements_update", { id: low.requirement.id, priority: "high" })).requirement.priority).toBe("high");
+      expect((await s.call("requirements_update", { id: low.requirement.id, priority: "lowest" })).requirement.priority).toBe("lowest");
+      expect((await s.call("requirements_upsert_by_external_ref", { external_ref: "github:acme/p3#1", name: "同步", priority: "lowest" })).requirement.priority).toBe("lowest");
+    } finally { await s.close(); }
+  });
+
+  test("an agent syncs a GitHub issue idempotently, edits it, ticks a checklist item and archives it", async () => {
+    const s = await connect(bot);
+    try {
+      const ref = "github:acme/widgets#42";
+      const first = await s.call("requirements_upsert_by_external_ref", { external_ref: ref, external_url: "https://github.com/acme/widgets/issues/42", name: "修复登录", description: "issue 正文", checklist: [{ id: "c1", text: "复现" }, { id: "c2", text: "修" }] });
+      expect(first.ok).toBe(true);
+      expect(first.created).toBe(true);
+      const tagged = await s.call("requirements_update", { id: first.requirement.id, tags: ["release"] });
+      expect(tagged.requirement.tags).toEqual(["release"]);
+      expect(first.requirement.created_by).toEqual({ kind: "node", id: "node_gh_sync" });
+      const again = await s.call("requirements_upsert_by_external_ref", { external_ref: ref, name: "修复登录(改了标题)" });
+      expect(again.created).toBe(false);
+      expect(again.requirement.tags).toEqual(["release"]);
+      expect(again.requirement.id).toBe(first.requirement.id);
+      const listed = await s.call("requirements_list", { external_ref: ref });
+      expect(listed.requirements.length).toBe(1);
+      expect(listed.requirements[0].name).toBe("修复登录(改了标题)");
+      const dup = await s.call("requirements_create", { name: "重复", external_ref: ref });
+      expect(dup.error).toBe("external_ref_exists");
+      expect(dup.existing_id).toBe(first.requirement.id);
+      expect(dup.status).toBe(409);
+      const id = first.requirement.id;
+      expect((await s.call("requirements_update", { id, column: "doing", agent_owner: { kind: "node", id: "node_gh_sync" } })).requirement.column).toBe("doing");
+      const ticked = await s.call("requirements_checklist_toggle", { id, item_id: "c1", done: true });
+      expect(ticked.requirement.checklist.map((i: any) => i.done)).toEqual([true, false]);
+      expect((await s.call("requirements_get", { id })).requirement.agent_owner).toEqual({ kind: "node", id: "node_gh_sync" });
+      expect((await s.call("requirements_list", { status: "doing", agent_owner: "node:node_gh_sync" })).requirements.map((r: any) => r.id)).toContain(id);
+      expect((await s.call("requirements_update", { id, owner: { kind: "node", id: "node_gh_sync" }, agent_owner: null })).error).toBe("owner_must_be_human");
+      expect((await s.call("requirements_update", { id, archived: true })).requirement.archived).toBe(true);
+      expect((await s.call("requirements_list", {})).requirements.some((r: any) => r.id === id)).toBe(false);
+      expect((await s.call("requirements_list", { include_archived: true })).requirements.some((r: any) => r.id === id)).toBe(true);
+      expect(Array.isArray((await s.call("projects_list", {})).projects)).toBe(true);
+      // 子需求:建子卡、父卡上的进度、按父卡 / 顶层过滤
+      const child = await s.call("requirements_create", { name: "子需求", parent_id: id });
+      expect(child.requirement.parent_id).toBe(id);
+      expect((await s.call("requirements_get", { id })).requirement.children.total).toBe(1);
+      expect((await s.call("requirements_list", { parent_id: id })).requirements.map((r: any) => r.id)).toEqual([child.requirement.id]);
+      expect((await s.call("requirements_list", { top_level: true, include_archived: true })).requirements.some((r: any) => r.id === child.requirement.id)).toBe(false);
+      expect((await s.call("requirements_update", { id, parent_id: child.requirement.id })).error).toBe("parent_cycle");
+    } finally { await s.close(); }
+  });
+
+  test("a node token from another network cannot see or touch these tasks, nor write into this network", async () => {
+    const mine = await connect(bot);
+    const theirs = await connect(foreignBot);
+    try {
+      const made = await mine.call("requirements_create", { name: "只属于本网络" });
+      const id = made.requirement.id;
+      expect((await theirs.call("requirements_get", { id })).error).toBe("requirement_not_found");
+      expect((await theirs.call("requirements_update", { id, name: "越界" })).error).toBe("requirement_not_found");
+      expect((await theirs.call("requirements_checklist_toggle", { id, item_id: "x", done: true })).error).toBe("requirement_not_found");
+      expect((await theirs.call("requirements_list", { network_id: ownerNet })).requirements.some((r: any) => r.id === id)).toBe(false);
+      const planted = await theirs.call("requirements_create", { name: "塞进去", network_id: ownerNet });
+      expect(planted.ok).toBe(true);
+      const row = db.get<{ network_id: string }>("SELECT network_id FROM requirements WHERE requirement_id = ?1", planted.requirement.id)!;
+      expect(row.network_id).toBe(foreignBot.net);
+      expect((await mine.call("requirements_get", { id })).requirement.name).toBe("只属于本网络");
+    } finally { await mine.close(); await theirs.close(); }
+  });
+
+  test("a user token keeps working through the same tools", async () => {
+    const s = await connect(owner);
+    try {
+      const made = await s.call("requirements_create", { name: "人建的", network_id: ownerNet, owner: { kind: "user", id: owner.user } });
+      expect(made.ok).toBe(true);
+      expect(made.requirement.created_by).toEqual({ kind: "user", id: owner.user });
+      expect((await s.call("requirements_list", { network_id: ownerNet, owner: `user:${owner.user}` })).requirements.map((r: any) => r.id)).toContain(made.requirement.id);
+    } finally { await s.close(); }
+  });
+});

package/src/requirements-migrate.ts

@@ -0,0 +1,83 @@
+// 需求卡的启动迁移。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);
+  `);
+}
+
+/** 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 };
+}

package/src/requirements-priority-lowest.test.ts

@@ -0,0 +1,114 @@
+// P0–P3 优先级:lowest(P3 极低)。生产库的 requirements 表建于旧 db.ts,带 CHECK(priority IN ('high', 'normal', 'low')),
+// 光放开校验集合写进去也会被 SQLite 拒掉。这里先用旧建表语句建库、塞行,再走真实启动路径(db.ts + server.ts),
+// 看:表重建一次、存量行 / 索引原样、lowest 在 POST / PATCH / upsert 都能写、坏值仍被拒、再启动不再重建。
+import { afterAll, beforeAll, describe, 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-priority-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`
+  CREATE TABLE IF NOT EXISTS requirements (
+    requirement_id TEXT PRIMARY KEY,
+    network_id     TEXT NOT NULL,
+    title          TEXT NOT NULL,
+    column_name    TEXT NOT NULL DEFAULT 'pool' CHECK(column_name IN ('pool', 'doing', 'done')),
+    priority       TEXT NOT NULL DEFAULT 'normal' CHECK(priority IN ('high', 'normal', 'low')),
+    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'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_requirements_network ON requirements(network_id, created_at DESC);
+`);
+legacy.exec("ALTER TABLE requirements ADD COLUMN tags_json TEXT NOT NULL DEFAULT '[]'");
+legacy.exec("ALTER TABLE requirements ADD COLUMN description TEXT");
+const seeded = [["r_high", "high"], ["r_normal", "normal"], ["r_low", "low"]] as const;
+for (const [id, p] of seeded) {
+  legacy.run("INSERT INTO requirements (requirement_id, network_id, title, priority, client_id, description, tags_json) VALUES (?1, 'net_legacy', ?2, ?3, ?4, ?5, '[\"旧\"]')", [id, `卡 ${id}`, p, `c_${id}`, `desc ${id}`]);
+}
+// 旧库确实拒 lowest:这就是光改 PRIORITIES 不够的原因
+expect(() => legacy.run("INSERT INTO requirements (requirement_id, network_id, title, priority) VALUES ('x', 'n', 't', 'lowest')")).toThrow(/CHECK/);
+legacy.close();
+
+let base = "";
+let token = "";
+let server: { port: number; stop?: (force?: boolean) => void };
+let db: any;
+
+async function api(path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const owner = register(`prio_owner_${Date.now()}`, "PriorityOwner123!", undefined, "seed");
+  token = owner.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("P3 lowest priority", () => {
+  test("startup rebuilds the legacy CHECK once and keeps every row and index", async () => {
+    const sql = db.get("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'requirements'").sql as string;
+    expect(sql).toContain("'lowest'");
+    expect(sql).toContain("CHECK(column_name IN ('pool', 'doing', 'done'))");
+    const rows = db.all("SELECT requirement_id, network_id, title, priority, client_id, description, tags_json FROM requirements WHERE network_id = 'net_legacy' ORDER BY requirement_id") as any[];
+    expect(rows.map(r => [r.requirement_id, r.priority])).toEqual([["r_high", "high"], ["r_low", "low"], ["r_normal", "normal"]]);
+    for (const r of rows) {
+      expect(r.title).toBe(`卡 ${r.requirement_id}`);
+      expect(r.client_id).toBe(`c_${r.requirement_id}`);
+      expect(r.description).toBe(`desc ${r.requirement_id}`);
+      expect(r.tags_json).toBe('["旧"]');
+    }
+    const indexes = (db.all("PRAGMA index_list(requirements)") as { name: string; unique: number }[]).map(i => i.name);
+    for (const name of ["idx_requirements_network", "idx_requirements_client", "idx_requirements_external_ref", "idx_requirements_network_updated", "idx_requirements_parent"]) expect(indexes).toContain(name);
+    expect(db.get("SELECT name FROM sqlite_master WHERE name = 'requirements_migrated'")).toBeNull();
+    // 坏值仍被数据库拒
+    expect(() => db.run("INSERT INTO requirements (requirement_id, network_id, title, priority) VALUES ('bad', 'n', 't', 'urgent')")).toThrow(/CHECK/);
+    // 下次启动:已经放开,不再重建
+    const { migrateRequirementPriorityCheck } = await import("./requirements-migrate.js");
+    expect(migrateRequirementPriorityCheck(db).rebuilt).toBe(false);
+  });
+
+  test("lowest is accepted on create, PATCH and upsert; unknown values stay 400", async () => {
+    const created = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "极低的活", priority: "lowest" }) });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.priority).toBe("lowest");
+    const id = created.body.requirement.id;
+    const patched = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ priority: "low" }) });
+    expect(patched.body.requirement.priority).toBe("low");
+    const back = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ priority: "lowest" }) });
+    expect(back.status).toBe(200);
+    expect(back.body.requirement.priority).toBe("lowest");
+    const up = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步来的", external_ref: "github:t/p#1", priority: "lowest" }) });
+    expect(up.status).toBe(201);
+    expect(up.body.requirement.priority).toBe("lowest");
+    const upAgain = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ external_ref: "github:t/p#1", priority: "high" }) });
+    expect(upAgain.body.requirement.priority).toBe("high");
+    for (const [path, method] of [["/api/requirements", "POST"], [`/api/requirements/${id}`, "PATCH"]] as const) {
+      const bad = await api(path, { method, body: JSON.stringify({ name: "x", priority: "urgent" }) });
+      expect(bad.status).toBe(400);
+      expect(bad.body.error).toBe("invalid_priority");
+    }
+    const listed = await api("/api/requirements");
+    expect(listed.body.capabilities).toContain("priority_lowest");
+    expect(listed.body.requirements.find((r: any) => r.id === id).priority).toBe("lowest");
+  });
+});

package/src/requirements-start-date.test.ts

@@ -0,0 +1,125 @@
+// 需求的可选开始字段(start,存 start_on):App 甘特图用。
+// 先用「没有 start_on 列」的旧库形状建库、塞行,再走真实启动路径(db.ts + server.ts),看:
+// 列被加上、存量行读出来 start = "" 且别的列原样;POST / PATCH / upsert 都能写;只 PATCH due 不动 start 和描述;
+// 旧客户端(不带 start)的 PATCH 不清掉已有的 start;坏值 400 invalid_start;capabilities 带 start_date。
+import { afterAll, beforeAll, describe, 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-start-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`
+  CREATE TABLE IF NOT EXISTS requirements (
+    requirement_id TEXT PRIMARY KEY,
+    network_id     TEXT NOT NULL,
+    title          TEXT NOT NULL,
+    column_name    TEXT NOT NULL DEFAULT 'pool' CHECK(column_name IN ('pool', 'doing', 'done')),
+    priority       TEXT NOT NULL DEFAULT 'normal' CHECK(priority IN ('high', 'normal', 'low', 'lowest')),
+    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'))
+  );
+`);
+legacy.exec("ALTER TABLE requirements ADD COLUMN description TEXT");
+legacy.run("INSERT INTO requirements (requirement_id, network_id, title, due_on, description) VALUES ('r_old', 'net_legacy', '旧卡', '2026-10-01', '旧描述')");
+expect(legacy.query("SELECT name FROM pragma_table_info('requirements') WHERE name = 'start_on'").all()).toEqual([]);
+legacy.close();
+
+let base = "";
+let token = "";
+let server: { port: number; stop?: (force?: boolean) => void };
+let db: any;
+
+async function api(path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const owner = register(`start_owner_${Date.now()}`, "StartOwner123!", undefined, "seed");
+  token = owner.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("optional requirement start date", () => {
+  test("startup adds start_on to an old table; existing rows keep every value and read start = ''", () => {
+    const cols = (db.all("PRAGMA table_info(requirements)") as { name: string }[]).map(c => c.name);
+    expect(cols).toContain("start_on");
+    const row = db.get("SELECT title, due_on, description, start_on FROM requirements WHERE requirement_id = 'r_old'") as any;
+    expect(row).toEqual({ title: "旧卡", due_on: "2026-10-01", description: "旧描述", start_on: null });
+  });
+
+  test("create / PATCH / upsert write start; due-only PATCH and start-less PATCH keep it", async () => {
+    const created = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "有开始的", start: "2026-09-20", due: "2026-10-01", description: "别动我" }) });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.start).toBe("2026-09-20");
+    const id = created.body.requirement.id;
+
+    // 甘特图拖动只发 due:start 和描述原样
+    const dueOnly = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ due: "2026-10-05" }) });
+    expect(dueOnly.status).toBe(200);
+    expect(dueOnly.body.requirement.due).toBe("2026-10-05");
+    expect(dueOnly.body.requirement.start).toBe("2026-09-20");
+    expect(dueOnly.body.requirement.description).toBe("别动我");
+
+    // 旧客户端不认识 start:它的 PATCH 不带这个字段,不能清掉
+    const old = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ name: "改名了" }) });
+    expect(old.body.requirement.start).toBe("2026-09-20");
+
+    const instant = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: "2026-09-21T09:30:00+08:00" }) });
+    expect(instant.body.requirement.start).toBe("2026-09-21T01:30:00Z");
+    const cleared = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: "" }) });
+    expect(cleared.status).toBe(200);
+    expect(cleared.body.requirement.start).toBe("");
+    // 只带 start 的 PATCH 不是 empty_patch
+    const onlyStart = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: "2026-09-22" }) });
+    expect(onlyStart.status).toBe(200);
+
+    const up = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "同步来的", external_ref: "github:t/p#9", start: "2026-09-01" }) });
+    expect(up.status).toBe(201);
+    expect(up.body.requirement.start).toBe("2026-09-01");
+    const upAgain = await api("/api/requirements/upsert", { method: "POST", body: JSON.stringify({ external_ref: "github:t/p#9", start: "2026-09-02" }) });
+    expect(upAgain.body.requirement.start).toBe("2026-09-02");
+
+    const noStart = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "没开始字段" }) });
+    expect(noStart.body.requirement.start).toBe("");
+  });
+
+  test("bad start values are 400 invalid_start and change nothing", async () => {
+    const created = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "坏值", start: "2026-09-20" }) });
+    const id = created.body.requirement.id;
+    for (const bad of ["2026-02-30", "tomorrow", "2026-09-20T10:00:00", 20260920]) {
+      const post = await api("/api/requirements", { method: "POST", body: JSON.stringify({ name: "x", start: bad }) });
+      const patch = await api(`/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ start: bad }) });
+      expect(patch.status).toBe(400);
+      expect(patch.body.error).toBe("invalid_start");
+      if (typeof bad === "string") {
+        expect(post.status).toBe(400);
+        expect(post.body.error).toBe("invalid_start");
+      }
+    }
+    const listed = await api("/api/requirements");
+    expect(listed.body.requirements.find((r: any) => r.id === id).start).toBe("2026-09-20");
+    expect(listed.body.capabilities).toContain("start_date");
+    // 旧卡在列表里 start = ""(不是缺字段:新 App 按 capabilities 判断支持与否)
+    expect(listed.body.requirements.every((r: any) => typeof r.start === "string")).toBe(true);
+  });
+});

package/src/requirements-upgrade-e2e.test.ts

@@ -0,0 +1,126 @@
+// 负责人 / 负责 Agent 拆分:一次性 Hub 进程的升级端到端。
+// 真起两次 `bun run src/index.ts`(HOME=临时目录、随机端口、绝不是 9200、独立库):
+//   第一次:注册、建节点、建一张「旧式」卡(owner 是节点 —— 用 SQL 写进去,因为新 Hub 已不接受);
+//          再把 agent_owner_json 列删掉,库回到 #2065 时代的样子。
+//   第二次:同一个库启动 = 升级。启动迁移把节点挪到 agent_owner,HTTP 读回;然后走一遍新规则。
+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, resolve } from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+
+const home = mkdtempSync(join(tmpdir(), "anet-req-agent-owner-e2e-"));
+const dbFile = join(home, "hub.db");
+const port = 20000 + Math.floor(Math.random() * 20000);
+if (port === 9200) throw new Error("9200 is the production hub port");
+const base = `http://127.0.0.1:${port}`;
+const serverDir = resolve(import.meta.dir, "..");
+let proc: ChildProcess | null = null;
+
+async function startHub() {
+  proc = spawn("bun", ["run", "src/index.ts"], {
+    cwd: serverDir,
+    env: { PATH: process.env.PATH || "", HOME: home, COMMHUB_DB: dbFile, COMMHUB_SERVER: "1", PORT: String(port), HOST: "127.0.0.1" },
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  let err = "";
+  proc.stderr?.on("data", d => { err += String(d); });
+  for (let i = 0; i < 100; i++) {
+    try { if ((await fetch(`${base}/health`)).ok) return; } catch {}
+    await new Promise(r => setTimeout(r, 150));
+  }
+  throw new Error(`hub did not start on ${port}: ${err.slice(-600)}`);
+}
+async function stopHub() {
+  if (!proc) return;
+  const p = proc;
+  proc = null;
+  await new Promise<void>(res => { p.once("exit", () => res()); p.kill("SIGTERM"); setTimeout(() => { p.kill("SIGKILL"); res(); }, 5000); });
+}
+afterAll(async () => { await stopHub(); try { rmSync(home, { recursive: true, force: true }); } catch {} });
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+test("an upgraded hub moves node owners to agent_owner and then enforces human owner / agent executor", async () => {
+  await startHub();
+  const reg = await (await fetch(`${base}/api/auth/register`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ username: "e2e_owner", password: "E2eOwner123!pass" }) })).json() as any;
+  expect(reg.ok).toBe(true);
+  const token = reg.token as string, net = reg.network_id as string, uid = reg.user.user_id as string;
+  const human = { kind: "user", id: uid }, agent = { kind: "node", id: "node_e2e_exec" };
+  {
+    const db = new Database(dbFile);
+    db.run("INSERT INTO nodes (node_id,node_name,alias,network_id) VALUES (?1,'e2e-exec','e2e-exec',?2)", [agent.id, net]);
+    db.close();
+  }
+  const card = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "旧式卡", network_id: net, participants: [human] }) });
+  expect(card.status).toBe(201);
+  const keep = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "人类负责人卡", network_id: net, owner: human }) });
+  expect(keep.status).toBe(201);
+  await stopHub();
+  {
+    // 退回旧库:节点当负责人,且没有 agent_owner_json 列
+    const db = new Database(dbFile);
+    db.run("UPDATE requirements SET owner_json = ?1 WHERE requirement_id = ?2", [JSON.stringify(agent), card.body.requirement.id]);
+    db.exec("ALTER TABLE requirements DROP COLUMN agent_owner_json");
+    const cols = (db.query("PRAGMA table_info(requirements)").all() as { name: string }[]).map(c => c.name);
+    expect(cols.includes("agent_owner_json")).toBe(false);
+    db.close();
+  }
+  await startHub();
+  const listed = await api(token, `/api/requirements?network_id=${net}`);
+  expect(listed.status).toBe(200);
+  expect(listed.body.requirements.length).toBe(2);
+  const upgraded = listed.body.requirements.find((r: any) => r.id === card.body.requirement.id);
+  expect(upgraded.owner).toBeNull();
+  expect(upgraded.agent_owner).toEqual(agent);
+  expect(upgraded.participants).toEqual([human]);
+  expect(upgraded.name).toBe("旧式卡");
+  const untouched = listed.body.requirements.find((r: any) => r.id === keep.body.requirement.id);
+  expect(untouched.owner).toEqual(human);
+  expect(untouched.agent_owner).toBeNull();
+
+  const path = `/api/requirements/${upgraded.id}?network_id=${net}`;
+  const both = await api(token, path, { method: "PATCH", body: JSON.stringify({ owner: human }) });
+  expect(both.status).toBe(200);
+  expect(both.body.requirement.owner).toEqual(human);
+  expect(both.body.requirement.agent_owner).toEqual(agent);
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ owner: agent, agent_owner: agent }) })).body.error).toBe("owner_must_be_human");
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ agent_owner: human }) })).body.error).toBe("agent_owner_must_be_agent");
+
+  // 预计完成:旧卡的全天值(升级前写的)原样读回;改成带时刻的,存 UTC
+  const dated = await api(token, path, { method: "PATCH", body: JSON.stringify({ due: "2026-10-01" }) });
+  expect(dated.body.requirement.due).toBe("2026-10-01");
+  // 描述 / 子任务:升级后的旧卡可写,单项勾选只动那一项
+  expect(upgraded.description).toBe("");
+  expect(upgraded.checklist).toEqual([]);
+  const withList = await api(token, path, { method: "PATCH", body: JSON.stringify({ description: "# 验收\n- 能用", checklist: [{ id: "one", text: "第一步" }, { id: "two", text: "第二步" }] }) });
+  expect(withList.status).toBe(200);
+  const ticked = await api(token, `/api/requirements/${upgraded.id}/checklist/two?network_id=${net}`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+  expect(ticked.body.requirement.checklist).toEqual([{ id: "one", text: "第一步", done: false }, { id: "two", text: "第二步", done: true }]);
+
+  // 项目:升级后没有任何项目(不预置),建一个、给旧卡挂上
+  expect((await api(token, `/api/requirements/projects?network_id=${net}`)).body.projects).toEqual([]);
+  const proj = await api(token, `/api/requirements/projects?network_id=${net}`, { method: "POST", body: JSON.stringify({ name: "军团项目" }) });
+  expect(proj.status).toBe(201);
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ project_id: proj.body.project.id }) })).body.requirement.project_id).toBe(proj.body.project.id);
+
+  // 第三次启动(同一个库):迁移不再改任何东西
+  await stopHub();
+  await startHub();
+  const again = (await api(token, `/api/requirements?network_id=${net}`)).body.requirements;
+  expect(again.length).toBe(2);
+  const same = again.find((r: any) => r.id === upgraded.id);
+  expect(same.owner).toEqual(human);
+  expect(same.agent_owner).toEqual(agent);
+  expect(same.description).toBe("# 验收\n- 能用");
+  expect(same.checklist.map((i: any) => i.done)).toEqual([false, true]);
+  expect(same.project_id).toBe(proj.body.project.id);
+  expect(same.due).toBe("2026-10-01");
+  const timed = await api(token, `/api/requirements/${upgraded.id}?network_id=${net}`, { method: "PATCH", body: JSON.stringify({ due: "2026-10-01T18:30:45+08:00" }) });
+  expect(timed.body.requirement.due).toBe("2026-10-01T10:30:45Z");
+  expect((await api(token, `/api/requirements/projects?network_id=${net}`)).body.projects.map((p: any) => p.name)).toEqual(["军团项目"]);
+}, 60_000);