@sleep2agi/commhub-server 0.9.0-preview.88 → 0.9.0-preview.90

package/src/requirements-list-mcp-slim-http.test.ts

@@ -0,0 +1,155 @@
+// #471(#469 问题 3)—— MCP requirements_list 默认省流 + 严格参数。
+//
+// 钉住:
+//   1. MCP 默认 = summary 视图 + 50 张一页:120 张有正文 / 检查项 / 标签 / 参与人的卡,第一页 50 张、has_more、
+//      next_cursor 接着翻,两页不重叠;一页的线上字节有上限(见 SUMMARY_PAGE_MAX_BYTES)。
+//   2. view='full' 照旧给全文(description / checklist);limit 可显式放大。
+//   3. 不认识的参数(以前的 tag 写错成 tags / 任何拼错)→ -32602,错误里列出能用的参数;不会回整张表。
+//   4. tag= 精确筛(区分大小写),和 limit / cursor 一起翻页。
+//   5. REST GET /api/requirements 不变:不带参数仍是 full + 最多 500 张(App 靠它)。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/requirements-list-mcp-slim-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { register } from "./auth.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("requirements-list-mcp-slim requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const TASKS = 120;
+/**
+ * 一页 summary(50 张;每张中文标题、3 个标签、负责人 + 参与人、8 条检查项、1.5 KB 正文)的字节上限。
+ * 这批数据实测 39.7 KB(≈ 795 B / 张,中文 3 字节 / 字);生产 122 张 summary 81 KB ≈ 670 B / 张 → 50 张约 33 KB。
+ * 上限 45 KB。同一批数据走旧默认(full、500 张)是整张表 120 张全文。
+ */
+const SUMMARY_PAGE_MAX_BYTES = 45_000;
+
+let server: any;
+let base = "";
+let token = "", userId = "", netId = "";
+let call: (args: Record<string, unknown>) => Promise<{ isError: boolean; text: string }>;
+let closeMcp: () => Promise<void>;
+
+const DESCRIPTION = "背景:".padEnd(1500, "这是一段很长的任务描述,用来模拟真实看板上的正文。");
+const checklist = Array.from({ length: 8 }, (_, i) => ({ text: `检查项 ${i + 1}:确认这一步已经完成并且有记录` }));
+
+beforeAll(async () => {
+  const stamp = Date.now();
+  const u = register(`slim_${stamp}`, "SlimList123!", undefined, "seed");
+  expect(u.ok).toBe(true);
+  token = u.token!; userId = u.user!.user_id; netId = u.network_id!;
+  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}`;
+
+  const s = new McpServer({ name: "slim", version: "1" });
+  registerTools(s, undefined, null, userId, u.user!.username, false, "tok_user");
+  const client = new Client({ name: "slim-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await s.connect(st);
+  await client.connect(ct);
+  const raw = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    return { isError: r.isError === true, text: String(r.content?.[0]?.text ?? "") };
+  };
+  call = (args) => raw("requirements_list", { network_id: netId, ...args });
+  closeMcp = async () => { await client.close(); await s.close(); };
+
+  for (let i = 0; i < TASKS; i++) {
+    const tags = ["bug", "后端", `批次${i % 4}`];
+    if (i % 3 === 0) tags[0] = "Bug"; // 大小写不同的另一个标签
+    const r = await raw("requirements_create", {
+      network_id: netId, name: `任务 ${i}:修复列表接口返回过大的问题`, description: DESCRIPTION, checklist, tags,
+      owner: { kind: "user", id: userId }, participants: [{ kind: "user", id: userId }],
+      priority: "normal", column: i % 2 ? "doing" : "pool",
+    });
+    expect(r.isError).toBe(false);
+  }
+}, 120_000);
+
+afterAll(async () => { await closeMcp?.(); server?.stop?.(true); });
+
+describe("#471 MCP requirements_list defaults", () => {
+  test("default = summary, 50 per page, under the byte bound; cursor pages without overlap", async () => {
+    const first = await call({});
+    expect(first.isError).toBe(false);
+    const bytes = Buffer.byteLength(first.text, "utf8");
+    const body = JSON.parse(first.text);
+    expect(body.view).toBe("summary");
+    expect(body.requirements.length).toBe(50);
+    expect(body.has_more).toBe(true);
+    expect(typeof body.next_cursor).toBe("string");
+    for (const r of body.requirements) {
+      expect(r.description).toBeUndefined();
+      expect(r.checklist).toBeUndefined();
+      expect(r.has_description).toBe(true);
+      expect(r.checklist_count).toEqual({ total: 8, done: 0 });
+    }
+    console.log(`summary page of 50: ${bytes} B`);
+    expect(bytes).toBeLessThan(SUMMARY_PAGE_MAX_BYTES);
+
+    const second = JSON.parse((await call({ cursor: body.next_cursor })).text);
+    expect(second.requirements.length).toBe(50);
+    const third = JSON.parse((await call({ cursor: second.next_cursor })).text);
+    expect(third.requirements.length).toBe(TASKS - 100);
+    expect(third.has_more).toBe(false);
+    const ids = [...body.requirements, ...second.requirements, ...third.requirements].map((r: any) => r.id);
+    expect(new Set(ids).size).toBe(TASKS);
+  });
+
+  test("view='full' still returns description and checklist; limit is honoured", async () => {
+    const r = JSON.parse((await call({ view: "full", limit: 3 })).text);
+    expect(r.view).toBeUndefined();
+    expect(r.requirements.length).toBe(3);
+    expect(r.requirements[0].description).toBe(DESCRIPTION);
+    expect(r.requirements[0].checklist.length).toBe(8);
+  });
+
+  test("unknown parameters → -32602 listing the valid ones; never the whole table", async () => {
+    for (const bad of [{ tags: "bug" }, { lable: "x" }, { status: "doing", foo: 1 }]) {
+      const r = await call(bad);
+      expect(r.isError).toBe(true);
+      expect(r.text).toContain("-32602");
+      expect(r.text).toContain(`unknown parameter(s): ${Object.keys(bad).filter(k => k !== "status").join(", ")}`);
+      expect(r.text).toContain("valid parameters: network_id, seq, status, project_id, owner, agent_owner, tag,");
+      expect(r.text).not.toContain('"requirements":[');
+    }
+  });
+
+  test("tag = exact label match (case-sensitive), pages with limit/cursor", async () => {
+    const lower = JSON.parse((await call({ tag: "bug", limit: 100 })).text);
+    expect(lower.requirements.length).toBe(TASKS - TASKS / 3);
+    expect(lower.requirements.every((r: any) => r.tags.includes("bug"))).toBe(true);
+    const upper = JSON.parse((await call({ tag: "Bug", limit: 100 })).text);
+    expect(upper.requirements.length).toBe(TASKS / 3);
+    expect(upper.requirements.every((r: any) => r.tags.includes("Bug") && !r.tags.includes("bug"))).toBe(true);
+    const p1 = JSON.parse((await call({ tag: "批次1", limit: 20 })).text);
+    expect(p1.requirements.length).toBe(20);
+    expect(p1.has_more).toBe(true);
+    const p2 = JSON.parse((await call({ tag: "批次1", limit: 20, cursor: p1.next_cursor })).text);
+    expect(p2.requirements.length).toBe(TASKS / 4 - 20);
+    expect(p2.has_more).toBe(false);
+    expect((await call({ tag: "nope" })).text).toContain('"requirements":[]');
+    // tag + q 组合:两个条件都要满足
+    const both = JSON.parse((await call({ tag: "批次2", q: "任务 10", limit: 100 })).text);
+    expect(both.requirements.map((r: any) => r.name)).toContain("任务 10:修复列表接口返回过大的问题");
+    expect(both.requirements.every((r: any) => r.tags.includes("批次2") && /任务 \d*10/.test(r.name))).toBe(true);
+  });
+
+  test("REST GET /api/requirements is unchanged: no params = full view, up to 500", async () => {
+    const res = await fetch(`${base}/api/requirements?network_id=${netId}`, { headers: { Authorization: `Bearer ${token}` } });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.view).toBeUndefined();
+    expect(body.requirements.length).toBe(TASKS);
+    expect(body.requirements[0].description).toBe(DESCRIPTION);
+    // REST 的 tag= 是新增的可选参数:不合法 → 400,与其它筛选参数同一形状
+    const bad = await fetch(`${base}/api/requirements?network_id=${netId}&tag=${"x".repeat(21)}`, { headers: { Authorization: `Bearer ${token}` } });
+    expect(bad.status).toBe(400);
+    expect(((await bad.json()) as any).error).toBe("invalid_tag");
+  });
+});

package/src/requirements-owner-strict-mcp-http.test.ts

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

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

@@ -0,0 +1,225 @@
+// #473(#469 问题 2)—— Agent 查人 + 人员字段按名字写。
+//
+// 钉住:
+//   1. MCP requirements_people:紧凑行(user_id / username / display_name / role / department / agents),
+//      没主人的 Agent 单列;q 按用户名 / 显示名 / 部门 / Agent 别名筛;50 人一页、offset 翻页;一页有字节上限。
+//   2. 严格参数:不认识的参数 → -32602,列出能用的参数。
+//   3. requirements_create / update / upsert 的 owner / agent_owner / participants 收 {kind:'user', username} 与
+//      {kind:'node', alias},在任务所在的网络里解析,存下来仍是 {kind, id}。
+//   4. 别名对上多个 Agent → person_ambiguous;找不到 → person_not_in_network;都带 field 和指向 requirements_people 的 hint。
+//   5. 绝不跨网络:别的网络的用户名 / 别名都是「找不到」。受限成员看不见的 Agent:通讯录里没有,按别名写也是「找不到」。
+//   6. REST GET /api/requirements/people 的形状不变。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/requirements-people-mcp-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { addNetworkMember, register } from "./auth.js";
+import { db } from "./db.js";
+import { createDepartment, setMemberDepartment } from "./departments.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("requirements-people-mcp requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const PW = "PeopleLookup123!";
+/** 一页 50 人(每人带部门、1 个 Agent)的字节上限。实测约 12.6 KB(≈ 250 B / 人);上限 16 KB。 */
+const PAGE_MAX_BYTES = 16_000;
+const EXTRA_MEMBERS = 60;
+
+let server: any;
+let base = "";
+let netA = "", netB = "";
+let boss: { id: string; token: string; username: string };
+let alice: { id: string; username: string };
+let bob: { id: string; username: string };
+let carol: { id: string; username: string };
+let ruth: { id: string; username: string };
+let deptId = "";
+const node = (suffix: string) => `n_pl_${suffix}_${stamp}`;
+const ALIAS = { alice: `alice-bot-${stamp}`, dup: `dup-bot-${stamp}`, free: `free-bot-${stamp}`, far: `far-bot-${stamp}` };
+
+type Mcp = { call: (name: string, args: Record<string, unknown>) => Promise<any>; close: () => Promise<void> };
+async function connect(userId: string, username: string): Promise<Mcp> {
+  const s = new McpServer({ name: "people", version: "1" });
+  registerTools(s, undefined, null, userId, username, false, "tok_user");
+  const client = new Client({ name: "people-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await s.connect(st);
+  await client.connect(ct);
+  return {
+    call: async (name, args) => {
+      const r: any = await client.callTool({ name, arguments: args });
+      const text = String(r.content?.[0]?.text ?? "");
+      if (r.isError) return { mcpError: true, text };
+      return { ...JSON.parse(text), _bytes: Buffer.byteLength(text, "utf8") };
+    },
+    close: async () => { await client.close(); await s.close(); },
+  };
+}
+let asBoss: Mcp, asRuth: Mcp;
+
+function mk(name: string) {
+  const r = register(`${name}_${stamp}`, PW, undefined, name === "alice" ? "爱丽丝" : undefined);
+  expect(r.ok).toBe(true);
+  return { id: r.user!.user_id, token: r.token!, username: r.user!.username, net: r.network_id! };
+}
+const insertNode = (id: string, alias: string, net: string, owner: string | null) =>
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)", [id, alias, net, owner]);
+
+beforeAll(async () => {
+  const b = mk("boss"); boss = { id: b.id, token: b.token, username: b.username }; netA = b.net;
+  const a = mk("alice"); alice = { id: a.id, username: a.username };
+  const o = mk("bob"); bob = { id: o.id, username: o.username };
+  const c = mk("carol"); carol = { id: c.id, username: c.username }; netB = c.net;
+  const r = mk("ruth"); ruth = { id: r.id, username: r.username };
+  expect(addNetworkMember(netA, alice.id, "member", boss.id, { agentAccess: "all" }).ok).toBe(true);
+  expect(addNetworkMember(netA, bob.id, "member", boss.id, { agentAccess: "all" }).ok).toBe(true);
+  // ruth:受限成员(只看授权的 Agent),一个都没授权
+  expect(addNetworkMember(netA, ruth.id, "member", boss.id, { agentAccess: "granted" }).ok).toBe(true);
+  const dept = createDepartment(netA, boss.id, { name: `研发部${stamp % 1000}` });
+  expect(dept.ok).toBe(true);
+  deptId = (dept as any).department.id;
+  expect(setMemberDepartment(netA, alice.id, deptId).ok).toBe(true);
+  insertNode(node("alice"), ALIAS.alice, netA, alice.id);
+  insertNode(node("dup1"), ALIAS.dup, netA, null);
+  insertNode(node("dup2"), ALIAS.dup, netA, null);
+  insertNode(node("free"), ALIAS.free, netA, null);
+  insertNode(node("far"), ALIAS.far, netB, carol.id);
+  for (let i = 0; i < EXTRA_MEMBERS; i++) {
+    const m = register(`pl_m${String(i).padStart(2, "0")}_${stamp}`, PW, undefined, `成员${i}`);
+    expect(addNetworkMember(netA, m.user!.user_id, "member", boss.id, { agentAccess: "all" }).ok).toBe(true);
+    setMemberDepartment(netA, m.user!.user_id, deptId);
+    insertNode(node(`m${i}`), `m${i}-bot-${stamp}`, netA, m.user!.user_id);
+  }
+  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}`;
+  asBoss = await connect(boss.id, boss.username);
+  asRuth = await connect(ruth.id, ruth.username);
+}, 120_000);
+afterAll(async () => { await asBoss?.close(); await asRuth?.close(); server?.stop?.(true); });
+
+describe("#473 requirements_people", () => {
+  test("compact rows: username, display_name, role, department, owned agents; unowned agents listed once", async () => {
+    const r = await asBoss.call("requirements_people", { network_id: netA, q: "alice" });
+    expect(r.ok).toBe(true);
+    expect(r.people).toEqual([{
+      user_id: alice.id, username: alice.username, display_name: "爱丽丝", role: "member",
+      department: { id: deptId, name: `研发部${stamp % 1000}` }, agents: [{ node_id: node("alice"), alias: ALIAS.alice }],
+    }]);
+    const all = await asBoss.call("requirements_people", { network_id: netA, q: String(stamp) });
+    expect(all.agents_without_owner.map((a: any) => a.alias).sort()).toEqual([ALIAS.dup, ALIAS.dup, ALIAS.free].sort());
+    const bossRow = (await asBoss.call("requirements_people", { network_id: netA, q: boss.username })).people[0];
+    expect(bossRow.role).toBe("owner");
+    expect(bossRow.display_name).toBe("");
+    expect(bossRow.department).toBeNull();
+  });
+
+  test("q matches username, display name, department and Agent alias", async () => {
+    expect((await asBoss.call("requirements_people", { network_id: netA, q: "爱丽" })).people.map((p: any) => p.user_id)).toEqual([alice.id]);
+    expect((await asBoss.call("requirements_people", { network_id: netA, q: ALIAS.alice.toUpperCase() })).people.map((p: any) => p.user_id)).toEqual([alice.id]);
+    const dept = await asBoss.call("requirements_people", { network_id: netA, q: `研发部${stamp % 1000}`, limit: 200 });
+    expect(dept.total).toBe(EXTRA_MEMBERS + 1);
+  });
+
+  test("default page = 50 people under the byte bound; offset pages the rest", async () => {
+    const p1 = await asBoss.call("requirements_people", { network_id: netA });
+    expect(p1.people.length).toBe(50);
+    expect(p1.has_more).toBe(true);
+    console.log(`people page of 50: ${p1._bytes} B`);
+    expect(p1._bytes).toBeLessThan(PAGE_MAX_BYTES);
+    const p2 = await asBoss.call("requirements_people", { network_id: netA, offset: p1.next_offset });
+    expect(p2.people.length).toBe(p1.total - 50);
+    expect(p2.agents_without_owner).toBeUndefined();
+    expect(new Set([...p1.people, ...p2.people].map((p: any) => p.user_id)).size).toBe(p1.total);
+  });
+
+  test("strict params: unknown key → -32602 listing the valid ones", async () => {
+    const r = await asBoss.call("requirements_people", { network_id: netA, name: "alice" });
+    expect(r.mcpError).toBe(true);
+    expect(r.text).toContain("-32602");
+    expect(r.text).toContain("unknown parameter(s): name; valid parameters: network_id, q, limit, offset");
+  });
+
+  test("another network is not readable; a restricted member sees no ungranted Agents", async () => {
+    const other = await asBoss.call("requirements_people", { network_id: netB });
+    expect(other.ok).toBe(false);
+    const r = await asRuth.call("requirements_people", { network_id: netA, q: String(stamp), limit: 200 });
+    expect(r.people.every((p: any) => p.agents.length === 0)).toBe(true);
+    expect(r.agents_without_owner).toEqual([]);
+  });
+});
+
+describe("#473 person fields by name", () => {
+  test("create / update / upsert accept username and alias; stored as ids in this network", async () => {
+    const made = await asBoss.call("requirements_create", {
+      network_id: netA, name: `by name ${stamp}`,
+      owner: { kind: "user", username: alice.username },
+      agent_owner: { kind: "node", alias: ALIAS.alice },
+      participants: [{ kind: "user", username: bob.username }, { kind: "node", alias: ALIAS.free }],
+    });
+    expect(made.ok).toBe(true);
+    const req = made.requirement;
+    expect(req.owner).toEqual({ kind: "user", id: alice.id });
+    expect(req.agent_owner).toEqual({ kind: "node", id: node("alice") });
+    expect(req.participants).toEqual([{ kind: "user", id: bob.id }, { kind: "node", id: node("free") }]);
+
+    const upd = await asBoss.call("requirements_update", { id: req.id, network_id: netA, owner: { kind: "user", username: bob.username } });
+    expect(upd.requirement.owner).toEqual({ kind: "user", id: bob.id });
+
+    const ups = await asBoss.call("requirements_upsert_by_external_ref", {
+      network_id: netA, external_ref: `test:people#${stamp}`, name: "upserted", agent_owner: { kind: "node", alias: ALIAS.alice },
+    });
+    expect(ups.requirement.agent_owner).toEqual({ kind: "node", id: node("alice") });
+    // id 照旧可用,且优先于名字
+    const byId = await asBoss.call("requirements_update", { id: req.id, network_id: netA, owner: { kind: "user", id: alice.id, username: bob.username } });
+    expect(byId.requirement.owner).toEqual({ kind: "user", id: alice.id });
+  });
+
+  test("ambiguous alias → person_ambiguous with field and a requirements_people hint", async () => {
+    const r = await asBoss.call("requirements_create", { network_id: netA, name: "amb", agent_owner: { kind: "node", alias: ALIAS.dup } });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("person_ambiguous");
+    expect(r.field).toBe("agent_owner");
+    expect(r.hint).toContain("requirements_people");
+    expect(r.hint).toContain("node_id");
+  });
+
+  test("unknown name → person_not_in_network naming the field and requirements_people", async () => {
+    const r = await asBoss.call("requirements_create", { network_id: netA, name: "nope", participants: [{ kind: "user", username: `ghost_${stamp}` }] });
+    expect(r.error).toBe("person_not_in_network");
+    expect(r.field).toBe("participants");
+    expect(r.hint).toContain("requirements_people");
+  });
+
+  test("never across networks: another network's username / alias is not found", async () => {
+    const u = await asBoss.call("requirements_create", { network_id: netA, name: "x", owner: { kind: "user", username: carol.username } });
+    expect(u.error).toBe("person_not_in_network");
+    const n = await asBoss.call("requirements_create", { network_id: netA, name: "x", agent_owner: { kind: "node", alias: ALIAS.far } });
+    expect(n.error).toBe("person_not_in_network");
+  });
+
+  test("wrong-kind or missing identifier → invalid_person", async () => {
+    for (const bad of [{ kind: "user", alias: ALIAS.alice }, { kind: "node", username: alice.username }, { kind: "user" }]) {
+      const r = await asBoss.call("requirements_create", { network_id: netA, name: "bad", participants: [bad] });
+      expect(r.error).toBe("invalid_person");
+      expect(r.hint).toContain("requirements_people");
+    }
+  });
+
+  test("a restricted member cannot resolve an Agent alias they are not granted", async () => {
+    const r = await asRuth.call("requirements_create", { network_id: netA, name: "hidden", agent_owner: { kind: "node", alias: ALIAS.alice } });
+    expect(r.error).toBe("person_not_in_network");
+  });
+
+  test("REST GET /api/requirements/people keeps its shape", async () => {
+    const res = await fetch(`${base}/api/requirements/people?network_id=${netA}`, { headers: { Authorization: `Bearer ${boss.token}` } });
+    const body = await res.json() as any;
+    expect(res.status).toBe(200);
+    for (const p of body.people) expect(Object.keys(p).sort()).toEqual(["display_name", "id", "kind", "name", "networkId"]);
+  });
+});

package/src/requirements-people.ts

@@ -0,0 +1,127 @@
+// #473(#469 问题 2)—— Agent 查人。
+//
+// 现场:Agent 想把任务派给「张三」或者某个节点,手里只有用户名 / 别名,而任务的人员字段只收 id;
+// GET /api/requirements/people 只给显示名,没有用户名、角色、部门,也看不出哪个 Agent 是谁的。
+// 这里给 MCP requirements_people 一份紧凑的通讯录:每个成员一行(user_id、username、display_name、网络角色、
+// 部门),带上他名下的 Agent(node_id、alias);没有主人(或主人不在本网络)的 Agent 单列。
+// 只在一个网络里查,受限成员看不见的 Agent 一律不出现(与 /people 同一个 hidden 判据)。
+//
+// 人员字段按名字写(owner {kind:'user', username} / agent_owner {kind:'node', alias})的解析在
+// requirements.ts personRef():同样只在任务所在的那个网络里找,看不见的节点等同不存在。
+
+import { db } from "./db.js";
+import "./departments.js"; // network_departments 表 + network_members.department_id 列(导入即建,只增)
+
+type HiddenNode = ((nodeId: string) => boolean) | null;
+
+export const PEOPLE_DEFAULT_LIMIT = 50;
+export const PEOPLE_MAX_LIMIT = 200;
+
+export type DirectoryAgent = { node_id: string; alias: string };
+export type DirectoryPerson = {
+  user_id: string;
+  username: string;
+  /** 没设(或等于用户名)为 ""(与 /people 同一规则)。 */
+  display_name: string;
+  role: string;
+  department: { id: string; name: string } | null;
+  agents: DirectoryAgent[];
+};
+
+/** q / limit / offset 解析;不合法 → 错误码(400)。 */
+export function parsePeopleQuery(params: URLSearchParams): { q: string; limit: number; offset: number } | { error: string } {
+  const q = (params.get("q") ?? "").trim();
+  if (q.length > 100) return { error: "invalid_q" };
+  let limit = PEOPLE_DEFAULT_LIMIT;
+  const rawLimit = params.get("limit");
+  if (rawLimit !== null) {
+    if (!/^\d{1,4}$/.test(rawLimit)) return { error: "invalid_limit" };
+    limit = Number(rawLimit);
+    if (limit < 1 || limit > PEOPLE_MAX_LIMIT) return { error: "invalid_limit" };
+  }
+  let offset = 0;
+  const rawOffset = params.get("offset");
+  if (rawOffset !== null) {
+    if (!/^\d{1,6}$/.test(rawOffset)) return { error: "invalid_offset" };
+    offset = Number(rawOffset);
+  }
+  return { q, limit, offset };
+}
+
+/**
+ * 一个网络的通讯录。q = 不区分大小写的子串,匹配用户名 / 显示名 / 部门名 / 名下 Agent 的别名;
+ * 成员按 username 排序、offset 翻页;没主人的 Agent 只在第一页给(按 q 过滤)。
+ */
+export function peopleDirectory(networkId: string, hidden: HiddenNode, query: { q: string; limit: number; offset: number }) {
+  const members = db.all<{ user_id: string; username: string; display_name: string | null; role: string | null; department_id: string | null; department_name: string | null }>(
+    `SELECT u.user_id, u.username, u.display_name, m.role, d.department_id, d.name AS department_name
+       FROM network_members m
+       JOIN users u ON u.user_id = m.user_id
+       LEFT JOIN network_departments d ON d.network_id = m.network_id AND d.department_id = m.department_id
+      WHERE m.network_id = ?1
+      ORDER BY u.username, u.user_id`,
+    networkId,
+  );
+  const nodes = db.all<{ node_id: string; alias: string | null; node_name: string; owner_user_id: string | null }>(
+    "SELECT node_id, alias, node_name, owner_user_id FROM nodes WHERE network_id = ?1 ORDER BY COALESCE(alias, node_name), node_id",
+    networkId,
+  ).filter(n => !hidden?.(n.node_id));
+  const memberIds = new Set(members.map(m => m.user_id));
+  const byOwner = new Map<string, DirectoryAgent[]>();
+  const unowned: DirectoryAgent[] = [];
+  for (const n of nodes) {
+    const agent = { node_id: n.node_id, alias: n.alias || n.node_name };
+    if (n.owner_user_id && memberIds.has(n.owner_user_id)) {
+      const list = byOwner.get(n.owner_user_id) ?? [];
+      list.push(agent);
+      byOwner.set(n.owner_user_id, list);
+    } else unowned.push(agent);
+  }
+  const needle = query.q.toLowerCase();
+  const hit = (s: string | null | undefined) => !needle || (s ?? "").toLowerCase().includes(needle);
+  const people: DirectoryPerson[] = [];
+  for (const m of members) {
+    const displayName = !m.display_name || m.display_name === m.username ? "" : m.display_name;
+    const agents = byOwner.get(m.user_id) ?? [];
+    if (!(hit(m.username) || (displayName && hit(displayName)) || (m.department_name && hit(m.department_name)) || agents.some(a => hit(a.alias)))) continue;
+    people.push({
+      user_id: m.user_id,
+      username: m.username,
+      display_name: displayName,
+      role: m.role ?? "member",
+      department: m.department_id && m.department_name ? { id: m.department_id, name: m.department_name } : null,
+      agents,
+    });
+  }
+  const page = people.slice(query.offset, query.offset + query.limit);
+  const hasMore = query.offset + query.limit < people.length;
+  return {
+    ok: true,
+    network_id: networkId,
+    total: people.length,
+    people: page,
+    ...(query.offset === 0 ? { agents_without_owner: unowned.filter(a => hit(a.alias)) } : {}),
+    has_more: hasMore,
+    next_offset: hasMore ? query.offset + query.limit : null,
+  };
+}
+
+/**
+ * 按名字找人(personRef 用):只在 networkId 里找,hidden 的节点等同不存在。
+ * 返回 id;找不到 → person_not_in_network;同一个别名对上多个节点 → person_ambiguous。
+ */
+export function resolvePersonName(kind: "user" | "node", name: string, networkId: string, hidden: HiddenNode): string {
+  if (kind === "user") {
+    const row = db.get<{ user_id: string }>(
+      "SELECT u.user_id FROM network_members m JOIN users u ON u.user_id = m.user_id WHERE m.network_id = ?1 AND u.username = ?2",
+      networkId, name,
+    );
+    if (!row) throw new Error("person_not_in_network");
+    return row.user_id;
+  }
+  const rows = db.all<{ node_id: string }>("SELECT node_id FROM nodes WHERE network_id = ?1 AND alias = ?2", networkId, name)
+    .filter(r => !hidden?.(r.node_id));
+  if (rows.length === 0) throw new Error("person_not_in_network");
+  if (rows.length > 1) throw new Error("person_ambiguous");
+  return rows[0].node_id;
+}