@sleep2agi/commhub-server 0.9.0-preview.66 → 0.9.0-preview.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.66",
+  "version": "0.9.0-preview.67",
   "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/db.ts

@@ -975,7 +975,7 @@ db.exec(`
 try { db.exec("ALTER TABLE requirements ADD COLUMN client_id TEXT"); } catch {}
 try { db.exec("ALTER TABLE requirements ADD COLUMN issues_json TEXT"); } catch {}
 db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_client ON requirements(network_id, client_id) WHERE client_id IS NOT NULL AND client_id != ''");
-for (const column of ["owner_json TEXT", "participants_json TEXT NOT NULL DEFAULT '[]'", "agent_owner_json TEXT", "description TEXT", "checklist_json TEXT", "project_id TEXT"]) {
+for (const column of ["owner_json TEXT", "participants_json TEXT NOT NULL DEFAULT '[]'", "agent_owner_json TEXT", "description TEXT", "checklist_json TEXT", "project_id TEXT", "external_ref TEXT", "external_url TEXT", "archived INTEGER NOT NULL DEFAULT 0", "created_by_json TEXT", "updated_by_json TEXT", "parent_id TEXT"]) {
   try { db.exec(`ALTER TABLE requirements ADD COLUMN ${column}`); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
 }
 
@@ -1516,6 +1516,10 @@ db.exec(`
     ON scheduled_task_runs(network_id, created_at DESC);
 `);
 try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN misfire_policy TEXT NOT NULL DEFAULT 'catch_up_once'"); } catch {}
+// Skipped runs (overlap_policy=skip) name the open task that blocked them and
+// whether the node had ever picked it up: not_received | in_progress.
+try { db.exec("ALTER TABLE scheduled_task_runs ADD COLUMN blocked_by_task_id TEXT"); } catch {}
+try { db.exec("ALTER TABLE scheduled_task_runs ADD COLUMN blocked_by_state TEXT"); } catch {}
 
 // RFC-036 / B4 — owner-authorized edits of node-host managed schedules.
 // This is intentionally separate from Hub scheduled_tasks: these rows are

package/src/requirements-http.test.ts

@@ -76,7 +76,8 @@ describe("requirements stay on the hub", () => {
     const humanAsAgent = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ agent_owner: user }) });
     expect(humanAsAgent.status).toBe(400);
     expect(humanAsAgent.body.error).toBe('agent_owner_must_be_agent');
-    const agentAsOwner = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: node }) });
+    // 新客户端(带了 agent_owner):节点当负责人严格拒绝
+    const agentAsOwner = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: node, agent_owner: null }) });
     expect(agentAsOwner.status).toBe(400);
     expect(agentAsOwner.body.error).toBe('owner_must_be_human');
     const changed = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ agent_owner: node }) });
@@ -85,9 +86,7 @@ describe("requirements stay on the hub", () => {
     expect(changed.body.requirement.agent_owner).toEqual(node);
     expect(changed.body.requirement.participants).toEqual([user, node]);
     expect(changed.body.requirement.column).toBe('pool');
-    for (const token of [viewerToken, nodeToken]) {
-      expect((await api(token, path, { method: 'PATCH', body: JSON.stringify({ owner: null, participants: [] }) })).status).toBe(403);
-    }
+    expect((await api(viewerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: null, participants: [] }) })).status).toBe(403);
     expect((await api(otherToken, path, { method: 'PATCH', body: JSON.stringify({ owner: null }) })).status).toBe(404);
     for (const invalid of [{ kind: 'node', id: 'foreign-person-node' }, { kind: 'user', id: 'unknown' }, { kind: 'admin', id: ownerId }]) {
       expect((await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ participants: [invalid] }) })).status).toBe(400);
@@ -115,7 +114,7 @@ describe("requirements stay on the hub", () => {
     expect(both.body.requirement.agent_owner).toEqual(agent);
     const plain = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '都不填' }) });
     expect(plain.body.requirement.agent_owner).toBeNull();
-    const wrongOwner = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '节点当负责人', owner: agent }) });
+    const wrongOwner = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '节点当负责人', owner: agent, agent_owner: null }) });
     expect(wrongOwner.status).toBe(400);
     expect(wrongOwner.body.error).toBe('owner_must_be_human');
     const wrongAgent = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '人当负责 Agent', agent_owner: human }) });
@@ -164,7 +163,10 @@ describe("requirements stay on the hub", () => {
     expect((await api(ownerToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: "yes" }) })).status).toBe(400);
     expect((await api(ownerToken, `${path}/checklist/a`, { method: "POST", body: JSON.stringify({ done: true }) })).status).toBe(404);
     expect((await api(viewerToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: false }) })).status).toBe(403);
-    expect((await api(nodeToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: false }) })).body.error).toBe("user_token_required");
+    // Agent(节点令牌)能勾自己网络里的子任务(PR B 放开)
+    const agentTick = await api(nodeToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+    expect(agentTick.status).toBe(200);
+    expect(agentTick.body.requirement.updated_by.kind).toBe("node");
     expect((await api(otherToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: false }) })).status).toBe(404);
 
     // 整个替换:排序 / 增删;只改描述时清单不动;只改清单是有效 PATCH
@@ -193,7 +195,7 @@ describe("requirements stay on the hub", () => {
     expect(row.checklist.length).toBe(100);
     expect(row.description.length).toBe(20_000);
     expect((await api(viewerToken, path, { method: "PATCH", body: JSON.stringify({ description: "越权" }) })).status).toBe(403);
-    expect((await api(nodeToken, path, { method: "PATCH", body: JSON.stringify({ description: "Agent 暂不能写" }) })).body.error).toBe("user_token_required");
+    expect((await api(nodeToken, path, { method: "PATCH", body: JSON.stringify({ description: "Agent 写的描述" }) })).body.requirement.description).toBe("Agent 写的描述");
   });
 
   test("projects: CRUD per network, project_id on cards, delete nulls references, archive keeps them", async () => {
@@ -217,7 +219,9 @@ describe("requirements stay on the hub", () => {
     // 权限:viewer 能读不能写;节点令牌一律拒绝;别的网络看不见、改不了
     expect((await api(viewerToken, `/api/requirements/projects${q}`)).body.projects.length).toBe(2);
     expect((await api(viewerToken, `/api/requirements/projects${q}`, { method: "POST", body: JSON.stringify({ name: "越权" }) })).status).toBe(403);
-    expect((await api(nodeToken, `/api/requirements/projects${q}`)).body.error).toBe("user_token_required");
+    // Agent 能读项目(挂卡片要用),不能建 / 改 / 删项目
+    expect((await api(nodeToken, `/api/requirements/projects${q}`)).body.projects.length).toBe(2);
+    expect((await api(nodeToken, `/api/requirements/projects${q}`, { method: "POST", body: JSON.stringify({ name: "Agent 建的" }) })).body.error).toBe("user_token_required");
     expect((await api(otherToken, "/api/requirements/projects")).body.projects).toEqual([]);
     expect((await api(otherToken, `/api/requirements/projects/${tmai.body.project.id}`, { method: "PATCH", body: JSON.stringify({ name: "抢" }) })).status).toBe(404);
     const foreign = await api(otherToken, "/api/requirements/projects", { method: "POST", body: JSON.stringify({ name: "别人的项目" }) });
@@ -290,7 +294,90 @@ 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"]);
+    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements"]);
+  });
+
+  test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {
+    const mk = async (name: string, extra: Record<string, unknown> = {}) => (await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name, network_id: ownerNetwork, ...extra }) })).body.requirement;
+    const root = await mk("父需求");
+    const a = await mk("子 A", { parent_id: root.id });
+    const b = await mk("子 B", { parent_id: root.id, column: "done" });
+    expect(a.parent_id).toBe(root.id);
+    const parent = (await api(ownerToken, `/api/requirements/${root.id}`)).body.requirement;
+    expect(parent.children).toEqual({ total: 2, done: 1 });
+    expect(parent.parent_id).toBeNull();
+    // 过滤
+    const kids = await api(ownerToken, `/api/requirements?network_id=${ownerNetwork}&parent_id=${root.id}`);
+    expect(kids.body.requirements.map((r: any) => r.id).sort()).toEqual([a.id, b.id].sort());
+    const top = await api(ownerToken, `/api/requirements?network_id=${ownerNetwork}&top_level=1`);
+    expect(top.body.requirements.some((r: any) => r.id === root.id)).toBe(true);
+    expect(top.body.requirements.some((r: any) => r.id === a.id)).toBe(false);
+    // 成环:把父卡挂到自己的子卡下 / 挂到自己
+    expect((await api(ownerToken, `/api/requirements/${root.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: a.id }) })).body.error).toBe("parent_cycle");
+    expect((await api(ownerToken, `/api/requirements/${a.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: a.id }) })).body.error).toBe("parent_cycle");
+    // 深度:第 5 层可以,第 6 层不行;把一棵 2 层的子树挂到第 4 层下面也不行
+    let chain = root;
+    const levels = [root];
+    for (let i = 2; i <= 5; i++) { chain = await mk(`第 ${i} 层`, { parent_id: chain.id }); levels.push(chain); }
+    expect(chain.parent_id).toBe(levels[3].id);
+    expect((await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "第 6 层", network_id: ownerNetwork, parent_id: chain.id }) })).body.error).toBe("parent_too_deep");
+    const subtree = await mk("子树根");
+    await mk("子树叶", { parent_id: subtree.id });
+    expect((await api(ownerToken, `/api/requirements/${subtree.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: levels[3].id }) })).body.error).toBe("parent_too_deep");
+    expect((await api(ownerToken, `/api/requirements/${subtree.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: levels[2].id }) })).status).toBe(200);
+    // 别的网络的卡当父卡:拒绝;坏 id:拒绝
+    const foreign = (await api(otherToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "别的网络的" }) })).body.requirement;
+    expect((await api(ownerToken, `/api/requirements/${a.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: foreign.id }) })).body.error).toBe("parent_not_found");
+    expect((await api(otherToken, `/api/requirements/${foreign.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: root.id }) })).body.error).toBe("parent_not_found");
+    expect((await api(ownerToken, `/api/requirements/${a.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: "bad id!" }) })).body.error).toBe("invalid_parent_id");
+    // 解挂
+    expect((await api(ownerToken, `/api/requirements/${b.id}`, { method: "PATCH", body: JSON.stringify({ parent_id: null }) })).body.requirement.parent_id).toBeNull();
+    // 删父卡:子卡保留、变顶层
+    const before = (await api(ownerToken, `/api/requirements?network_id=${ownerNetwork}`)).body.requirements.length;
+    expect((await api(ownerToken, `/api/requirements/${root.id}`, { method: "DELETE" })).status).toBe(200);
+    const after = (await api(ownerToken, `/api/requirements?network_id=${ownerNetwork}`)).body.requirements;
+    expect(after.length).toBe(before - 1);
+    expect(after.find((r: any) => r.id === a.id).parent_id).toBeNull();
+    expect(after.find((r: any) => r.id === levels[1].id).parent_id).toBeNull();
+    expect(after.find((r: any) => r.id === levels[2].id).parent_id).toBe(levels[1].id);
+  });
+
+  test("old-app compat: owner {kind:'node'} without agent_owner becomes agent_owner (200 + flag); new clients stay strict", async () => {
+    const { db } = await import('./db.js');
+    const ownerId = db.get<{ owner_id: string }>('SELECT owner_id FROM networks WHERE network_id=?1', ownerNetwork)!.owner_id;
+    db.run('INSERT OR IGNORE INTO nodes(node_id,node_name,alias,network_id) VALUES (?1,?2,?2,?3)', ['compat-node', 'compat-node', ownerNetwork]);
+    const node = { kind: 'node', id: 'compat-node' };
+    const human = { kind: 'user', id: ownerId };
+    const card = (await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '旧 App 的卡', owner: human }) })).body.requirement;
+    const path = `/api/requirements/${card.id}`;
+    // 0.2.142 的详情保存:{name?, owner:{node}} —— 不带 agent_owner
+    const old = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: node }) });
+    expect(old.status).toBe(200);
+    expect(old.body.owner_coerced_to_agent_owner).toBe(true);
+    // 回显给旧客户端的 owner 是它设的那个节点(它按这个核对「保存生效」);agent_owner 也在
+    expect(old.body.requirement.owner).toEqual(node);
+    expect(old.body.requirement.agent_owner).toEqual(node);
+    // 实际存储:负责人清空,负责 Agent = 节点;GET 看到的是真实值
+    const stored = (await api(ownerToken, path)).body.requirement;
+    expect(stored.owner).toBeNull();
+    expect(stored.agent_owner).toEqual(node);
+    const row = db.get<{ owner_json: string | null; agent_owner_json: string | null }>('SELECT owner_json, agent_owner_json FROM requirements WHERE requirement_id=?1', card.id)!;
+    expect(row.owner_json).toBeNull();
+    expect(JSON.parse(row.agent_owner_json!)).toEqual(node);
+    // 旧 App 新建时选了节点当负责人:同样改写
+    const created = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '旧 App 新建', owner: node, assignee: '' }) });
+    expect(created.status).toBe(201);
+    expect(created.body.owner_coerced_to_agent_owner).toBe(true);
+    expect((await api(ownerToken, `/api/requirements/${created.body.requirement.id}`)).body.requirement.agent_owner).toEqual(node);
+    // 旧 App 设人类负责人:照常,不带标志
+    const normal = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: human }) });
+    expect(normal.body.owner_coerced_to_agent_owner).toBeUndefined();
+    expect(normal.body.requirement.owner).toEqual(human);
+    expect(normal.body.requirement.agent_owner).toEqual(node);
+    // 新客户端带 agent_owner:严格
+    expect((await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: node, agent_owner: node }) })).body.error).toBe('owner_must_be_human');
+    // 节点不在网络里:仍然 400(不因为兼容放宽成员校验)
+    expect((await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: { kind: 'node', id: 'foreign-person-node' } }) })).status).toBe(400);
   });
 
   test("owner creates a card in the pool", async () => {
@@ -340,9 +427,110 @@ describe("requirements stay on the hub", () => {
     expect(move.status).toBe(403);
   });
 
-  test("a node token cannot use the board", async () => {
-    const denied = await api(nodeToken, "/api/requirements");
-    expect(denied.status).toBe(403);
+  test("agent API: a node token reads / creates / patches in its own network only; cannot delete; who did what is recorded", async () => {
+    const { db } = await import("./db.js");
+    const { createNetworkTokenForNode, register } = await import("./auth.js");
+    const ownerId = db.get<{ owner_id: string }>("SELECT owner_id FROM networks WHERE network_id=?1", ownerNetwork)!.owner_id;
+    const bound = createNetworkTokenForNode(ownerId, ownerNetwork, "sync-bot", "node_sync_bot");
+    expect(bound.ok).toBe(true);
+    const bot = bound.token!;
+    // 读
+    const listed = await api(bot, "/api/requirements");
+    expect(listed.status).toBe(200);
+    expect(listed.body.requirements.length).toBeGreaterThan(0);
+    // 建:记下是哪个节点建的
+    const made = await api(bot, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "Agent 建的任务", column: "doing", checklist: [{ id: "x", text: "第一步" }] }) });
+    expect(made.status).toBe(201);
+    expect(made.body.requirement.created_by).toEqual({ kind: "node", id: "node_sync_bot" });
+    expect(made.body.requirement.updated_by).toEqual({ kind: "node", id: "node_sync_bot" });
+    const path = `/api/requirements/${made.body.requirement.id}`;
+    // 按 id 读、改、勾、归档
+    expect((await api(bot, path)).body.requirement.name).toBe("Agent 建的任务");
+    expect((await api(bot, path, { method: "PATCH", body: JSON.stringify({ column: "done" }) })).body.requirement.column).toBe("done");
+    expect((await api(bot, `${path}/checklist/x`, { method: "PATCH", body: JSON.stringify({ done: true }) })).body.requirement.checklist[0].done).toBe(true);
+    // 人改了之后 updated_by 变成人
+    const human = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ priority: "high" }) });
+    expect(human.body.requirement.updated_by).toEqual({ kind: "user", id: ownerId });
+    expect(human.body.requirement.created_by).toEqual({ kind: "node", id: "node_sync_bot" });
+    // 不能删,只能归档;归档的默认不在列表里
+    const del = await api(bot, path, { method: "DELETE" });
+    expect(del.status).toBe(403);
+    expect(del.body.error).toBe("user_token_required");
+    expect((await api(bot, path, { method: "PATCH", body: JSON.stringify({ archived: true }) })).body.requirement.archived).toBe(true);
+    expect((await api(ownerToken, "/api/requirements")).body.requirements.some((r: any) => r.id === made.body.requirement.id)).toBe(false);
+    expect((await api(ownerToken, "/api/requirements?include_archived=1")).body.requirements.some((r: any) => r.id === made.body.requirement.id)).toBe(true);
+    expect((await api(bot, path, { method: "PATCH", body: JSON.stringify({ archived: "yes" }) })).status).toBe(400);
+    // 别的网络的节点令牌:看不到、改不了、也不能往别的网络里建
+    const outsider = register(`req_outsider_${Date.now()}`, "RequirementsOutsider123!", undefined, "seed");
+    const foreignTok = createNetworkTokenForNode(outsider.user!.user_id, outsider.network_id!, "foreign-bot", "node_foreign_bot");
+    expect(foreignTok.ok).toBe(true);
+    const foreign = foreignTok.token!;
+    expect((await api(foreign, `/api/requirements?include_archived=1`)).body.requirements.some((r: any) => r.id === made.body.requirement.id)).toBe(false);
+    expect((await api(foreign, path)).status).toBe(404);
+    expect((await api(foreign, path, { method: "PATCH", body: JSON.stringify({ name: "越界" }) })).status).toBe(404);
+    expect((await api(foreign, `${path}/checklist/x`, { method: "PATCH", body: JSON.stringify({ done: false }) })).status).toBe(404);
+    const planted = await api(foreign, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "塞进别的网络", network_id: ownerNetwork }) });
+    expect(planted.status).toBe(201);
+    // 写进的是它自己的网络(令牌绑定的网络优先于 body 里的 network_id)。owner 在测试库里是管理员,所以按网络查。
+    expect((await api(ownerToken, `/api/requirements?network_id=${ownerNetwork}`)).body.requirements.some((r: any) => r.id === planted.body.requirement.id)).toBe(false);
+    expect((await api(foreign, `/api/requirements/${planted.body.requirement.id}`)).status).toBe(200);
+    // 人照常能删
+    const humanDel = await api(ownerToken, path, { method: "DELETE" });
+    expect(humanDel.status).toBe(200);
+    expect((await api(ownerToken, path)).status).toBe(404);
+    expect((await api(viewerToken, `/api/requirements/${planted.body.requirement.id}`, { method: "DELETE" })).status).toBe(404);
+  });
+
+  test("external_ref: unique per network, 409 with the existing id, upsert is idempotent, list filters", async () => {
+    const { db } = await import("./db.js");
+    const { createNetworkTokenForNode } = await import("./auth.js");
+    const ownerId = db.get<{ owner_id: string }>("SELECT owner_id FROM networks WHERE network_id=?1", ownerNetwork)!.owner_id;
+    const bot = createNetworkTokenForNode(ownerId, ownerNetwork, "gh-sync", "node_gh_sync").token!;
+    const ref = "github:acme/widgets#123";
+    const first = await api(bot, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ external_ref: ref, external_url: "https://github.com/acme/widgets/issues/123", name: "Issue 标题", description: "issue 正文" }) });
+    expect(first.status).toBe(201);
+    expect(first.body.created).toBe(true);
+    expect(first.body.requirement.external_ref).toBe(ref);
+    expect(first.body.requirement.external_url).toBe("https://github.com/acme/widgets/issues/123");
+    // 同一个 issue 再同步:改,不重复建;省略的字段(状态)保留
+    await api(ownerToken, `/api/requirements/${first.body.requirement.id}`, { method: "PATCH", body: JSON.stringify({ column: "doing" }) });
+    const again = await api(bot, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ external_ref: ref, name: "Issue 改过的标题" }) });
+    expect(again.status).toBe(200);
+    expect(again.body.created).toBe(false);
+    expect(again.body.requirement.id).toBe(first.body.requirement.id);
+    expect(again.body.requirement.name).toBe("Issue 改过的标题");
+    expect(again.body.requirement.column).toBe("doing");
+    const same = await api(bot, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ external_ref: ref }) });
+    expect(same.body.created).toBe(false);
+    expect((await api(ownerToken, `/api/requirements?external_ref=${encodeURIComponent(ref)}`)).body.requirements.length).toBe(1);
+    // 普通 POST 撞同一个 external_ref:409 + 已有 id
+    const dup = await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "重复", external_ref: ref }) });
+    expect(dup.status).toBe(409);
+    expect(dup.body.error).toBe("external_ref_exists");
+    expect(dup.body.existing_id).toBe(first.body.requirement.id);
+    // PATCH 改成别人已有的 external_ref 也 409
+    const other = await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "另一个", external_ref: "github:acme/widgets#124" }) });
+    expect((await api(ownerToken, `/api/requirements/${other.body.requirement.id}`, { method: "PATCH", body: JSON.stringify({ external_ref: ref }) })).status).toBe(409);
+    // 另一个网络可以有同样的 external_ref(唯一只在网络内)
+    const elsewhere = await api(otherToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "别的网络同一个 issue", external_ref: ref }) });
+    expect(elsewhere.status).toBe(201);
+    // 坏值
+    for (const bad of [{ external_ref: "has space" }, { external_ref: "" }, { external_url: "javascript:alert(1)" }]) {
+      expect((await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "坏", ...bad }) })).status).toBe(400);
+    }
+    expect((await api(bot, "/api/requirements/upsert", { method: "POST", body: JSON.stringify({ name: "没有 ref" }) })).body.error).toBe("external_ref_required");
+    // 列表筛选
+    const byStatus = await api(ownerToken, "/api/requirements?status=doing");
+    expect(byStatus.body.requirements.every((r: any) => r.column === "doing")).toBe(true);
+    expect((await api(ownerToken, "/api/requirements?status=nope")).status).toBe(400);
+    const since = new Date(Date.now() - 60_000).toISOString();
+    expect((await api(ownerToken, `/api/requirements?updated_since=${encodeURIComponent(since)}`)).body.requirements.some((r: any) => r.id === first.body.requirement.id)).toBe(true);
+    expect((await api(ownerToken, `/api/requirements?updated_since=${encodeURIComponent(new Date(Date.now() + 60_000).toISOString())}`)).body.requirements.length).toBe(0);
+    expect((await api(ownerToken, "/api/requirements?updated_since=nope")).status).toBe(400);
+    const human = { kind: "user", id: ownerId };
+    await api(ownerToken, `/api/requirements/${other.body.requirement.id}`, { method: "PATCH", body: JSON.stringify({ owner: human }) });
+    expect((await api(ownerToken, `/api/requirements?owner=user:${ownerId}`)).body.requirements.map((r: any) => r.id)).toContain(other.body.requirement.id);
+    expect((await api(ownerToken, "/api/requirements?owner=bad")).status).toBe(400);
   });
 
   test("the same client_id does not create a second card", async () => {

package/src/requirements-mcp.test.ts

@@ -0,0 +1,132 @@
+// 需求池 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);
+    } 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);
+      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.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

@@ -42,3 +42,10 @@ export function ensureRequirementProjects(database: DbAdapter): void {
     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");
+}

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

@@ -88,7 +88,7 @@ test("an upgraded hub moves node owners to agent_owner and then enforces human o
   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 }) })).body.error).toBe("owner_must_be_human");
+  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

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

@@ -64,6 +64,15 @@ test("startup migration moves node owners to agent_owner, keeps every row, and i
   expect(extra.every(r => r.description === null && r.checklist_json === null)).toBe(true);
   // 项目表:建了、是空的(不预置),重复执行不报错;卡片的 project_id 列只加不改
   expect(cols.includes("project_id")).toBe(true);
+  // PR B:外部引用 / 归档 / 谁做的 —— 只加不改;旧行 archived = 0、其余 NULL;external_ref 的部分唯一索引建了
+  for (const c of ["external_ref", "external_url", "archived", "created_by_json", "updated_by_json", "parent_id"]) expect(cols.includes(c)).toBe(true);
+  expect((db.all("SELECT parent_id FROM requirements WHERE parent_id IS NOT NULL") as any[]).length).toBe(0);
+  expect((db.all("PRAGMA index_list(requirements)") as { name: string }[]).some(i => i.name === "idx_requirements_parent")).toBe(true);
+  expect((db.all("SELECT archived, external_ref FROM requirements") as any[]).every(r => r.archived === 0 && r.external_ref === null)).toBe(true);
+  const idx = (db.all("PRAGMA index_list(requirements)") as { name: string; unique: number }[]).find(i => i.name === "idx_requirements_external_ref");
+  expect(idx?.unique).toBe(1);
+  const { ensureRequirementIndexes } = await import("./requirements-migrate.js");
+  ensureRequirementIndexes(db);
   expect((db.all("SELECT project_id FROM requirements WHERE project_id IS NOT NULL") as any[]).length).toBe(0);
   expect((db.get("SELECT COUNT(*) AS n FROM requirement_projects") as any).n).toBe(0);
   const { ensureRequirementProjects } = await import("./requirements-migrate.js");