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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.89",
+  "version": "0.9.0-preview.90",
   "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/agent-access.ts

@@ -480,4 +480,8 @@ export const RESTRICTED_MEMBER_TOOLS: ReadonlySet<string> = new Set([
   "projects_create",
   "projects_update",
   "requirements_events",
+  // #474:评论走同一个 REST 处理 —— 看不见的任务 404、只读角色 403;受限成员的评论和他的其他任务写一样按可见性准入。
+  "requirements_comment",
+  // #473:通讯录同 /api/requirements/people 的可见范围 —— 受限成员看不见的 Agent 不出现(hiddenNodeFilter)。
+  "requirements_people",
 ]);

package/src/requirement-events.ts

@@ -56,11 +56,12 @@ export type EventCard = {
   archived: number | null;
 };
 
-export type EventKind = "created" | "changed" | "deleted";
+export type EventKind = "created" | "changed" | "deleted" | "comment";
 /**
  * field(kind = changed):column / title / priority / due / start / assignee / owner / agent_owner / participants /
  * tags / checklist_item(勾选或取消一项:{id,text,done})/ checklist(增删改条目:{total,done})/
  * description(只记字数,不存正文)/ project / parent / archived。
+ * kind = comment(#474):field 为 null,new = { text }(评论正文,≤ 4000 字),只追加,不对应任何字段的改动。
  */
 export type EventDraft = { kind: EventKind; field: string | null; old: unknown; new: unknown };
 

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

@@ -0,0 +1,165 @@
+// #474(MCP 任务生命周期测试报告问题 5)—— 评论 / 进展:只追加,进「动态」(requirement_events kind=comment),
+// 不改任务本身。钉住:
+//   - Agent(节点令牌)经 MCP、人经 REST 都能评论,署名是调用者;description / updated_at 一个字节都不动;
+//   - requirements_events 里是 kind=comment、new.text 全文,单任务的动态体积可控;
+//   - 看不见这张卡的人评论 = 404(和读一样),只读角色 = 403,空 / 超长 = 400 + 提示;
+//   - 只追加:没有改 / 删评论的路由。
+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";
+import { COMMENT_MAX_CHARS } from "./requirements.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-comment-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqCommentPassw0rd!xyz";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+let card = { id: "", seq: 0 };
+
+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, bytes: text.length };
+}
+async function rpc(token: string, name: string, args: Record<string, unknown>): Promise<{ data: any; raw: any; bytes: number }> {
+  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);
+  const text = out.result?.content?.[0]?.text ?? "";
+  let data: any = null;
+  try { data = JSON.parse(text); } catch { data = text; }
+  return { data, raw: out, bytes: text.length };
+}
+const mcp = async (token: string, name: string, args: Record<string, unknown>) => (await rpc(token, name, args)).data;
+const cardRow = (id: string) => db.get<{ description: string | null; updated_at: string | null; updated_by_json: string | null }>("SELECT description, updated_at, updated_by_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(`cmt_owner_${Date.now()}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const mk = async (username: string, role: string) => {
+    expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
+    const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  U.member = await mk(`cmt_member_${stamp}`, "member");
+  U.viewer = await mk(`cmt_viewer_${stamp}`, "viewer");
+  U.scoped = await mk(`cmt_scoped_${stamp}`, "member");
+  expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.scoped.id}/task-grants`, { task_access: "scoped", project_grants: [] })).status).toBe(200);
+  U.nodeA = { token: createNetworkTokenForNode(U.owner.id, NET, "示例-甲", "node_cmt_a").token!, id: "node_cmt_a" };
+  const created = (await mcp(U.nodeA.token, "requirements_create", { name: "示例任务:评论", description: "## 背景\n原文。" })).requirement;
+  card = { id: created.id, seq: created.seq };
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirements_comment", () => {
+  test("an Agent comments over MCP (#N): one comment event, attributed to the node; the task itself is untouched", async () => {
+    const before = cardRow(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_comment", { id: `#${card.seq}`, text: "进展:示例草稿已写完,等人看。" });
+    expect(r.ok).toBe(true);
+    expect(r.event.kind).toBe("comment");
+    expect(r.event.field).toBeNull();
+    expect(r.event.new).toEqual({ text: "进展:示例草稿已写完,等人看。" });
+    expect(r.event.actor).toEqual({ kind: "node", id: "node_cmt_a" });
+    expect(r.event.requirement_id).toBe(card.id);
+    const after = cardRow(card.id);
+    expect(after).toEqual(before); // description, updated_at, updated_by all unchanged
+  });
+
+  test("a person comments over REST; both show in requirements_events with the full text, newest first", async () => {
+    const r = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "  好的,我下午看。  " });
+    expect(r.status).toBe(201);
+    expect(r.body.event.new.text).toBe("好的,我下午看。"); // trimmed
+    expect(r.body.event.actor).toEqual({ kind: "user", id: U.member.id });
+    const ev = await rpc(U.nodeA.token, "requirements_events", { requirement_id: `#${card.seq}` });
+    const comments = ev.data.events.filter((e: any) => e.kind === "comment");
+    expect(comments.map((e: any) => e.new.text)).toEqual(["好的,我下午看。", "进展:示例草稿已写完,等人看。"]);
+    expect(ev.data.events.at(-1).kind).toBe("created");
+  });
+
+  test("full text up to the cap, and the timeline stays small", async () => {
+    const long = "长".repeat(COMMENT_MAX_CHARS);
+    const r = await mcp(U.nodeA.token, "requirements_comment", { id: card.id, text: long });
+    expect(r.ok).toBe(true);
+    expect(r.event.new.text.length).toBe(COMMENT_MAX_CHARS);
+    const ev = await rpc(U.nodeA.token, "requirements_events", { requirement_id: card.id });
+    // 1 created + 3 comments (one of them 4000 chars): well under 20 KB.
+    expect(ev.bytes).toBeLessThan(20_000);
+    expect(ev.data.events.some((e: any) => e.kind === "comment" && e.new.text === long)).toBe(true);
+  });
+
+  test("bad input: empty → invalid_comment, over the cap → comment_too_long (REST), MCP schema → -32602; both with hints", async () => {
+    const empty = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "   " });
+    expect(empty.status).toBe(400);
+    expect(empty.body.error).toBe("invalid_comment");
+    expect(empty.body.field).toBe("text");
+    const tooLong = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "x".repeat(COMMENT_MAX_CHARS + 1) });
+    expect(tooLong.status).toBe(400);
+    expect(tooLong.body.error).toBe("comment_too_long");
+    expect(tooLong.body.hint).toContain("Split");
+    const viaMcp = await rpc(U.nodeA.token, "requirements_comment", { id: card.id, text: "x".repeat(COMMENT_MAX_CHARS + 1) });
+    expect(String(viaMcp.raw.error?.code ?? viaMcp.raw.result?.content?.[0]?.text)).toMatch(/-32602|too big|Too big/i);
+  });
+
+  test("permissions: a non-reader gets 404 (like reading), a read-only role 403; neither writes anything", async () => {
+    const count = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events WHERE requirement_id = ?1 AND kind = 'comment'", card.id)!.n;
+    const n = count();
+    // scoped member with no grant cannot see the task → cannot read it → cannot comment on it.
+    expect((await rest(U.scoped.token, "GET", `/api/requirements/${card.id}`)).status).toBe(404);
+    const scoped = await rest(U.scoped.token, "POST", `/api/requirements/${card.id}/comments`, { text: "看不见也想评论" });
+    expect(scoped.status).toBe(404);
+    expect(scoped.body.error).toBe("requirement_not_found");
+    const viewer = await rest(U.viewer.token, "POST", `/api/requirements/${card.id}/comments`, { text: "只读角色" });
+    expect(viewer.status).toBe(403);
+    expect(viewer.body.error).toBe("permission_denied");
+    expect(count()).toBe(n);
+    // …and the scoped member does not see the comments in the network timeline either.
+    const ev = await rest(U.scoped.token, "GET", `/api/requirements/events?network_id=${NET}`);
+    expect((ev.body.events ?? []).some((e: any) => e.requirement_id === card.id)).toBe(false);
+  });
+
+  test("append-only: no route edits or deletes a comment; unknown task → requirement_not_found with a hint", async () => {
+    expect((await rest(U.owner.token, "PATCH", `/api/requirements/${card.id}/comments`, { text: "改" })).status).toBe(404);
+    expect((await rest(U.owner.token, "DELETE", `/api/requirements/${card.id}/comments`)).status).toBe(404);
+    const missing = await mcp(U.nodeA.token, "requirements_comment", { id: "#9999", text: "没有这张卡" });
+    expect(missing.error).toBe("requirement_not_found");
+    expect(missing.hint).toContain("requirements_list");
+  });
+
+  test("discoverable: tools/list carries requirements_comment, and requirements_events mentions comments", async () => {
+    const res = await fetch(`${BASE}/mcp`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${U.nodeA.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/list" }),
+    });
+    const raw = await res.text();
+    const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+    const tools = (lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw)).result.tools as any[];
+    const byName = new Map(tools.map(t => [t.name, t]));
+    expect(String(byName.get("requirements_comment")?.description)).toContain("append-only");
+    expect(String(byName.get("requirements_events")?.description)).toContain("kind=comment");
+  });
+});

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

@@ -73,8 +73,9 @@ describe("each hint, over MCP", () => {
     const byAlias = await mcp(nodeToken, "requirements_update", { id: cardId, agent_owner: { kind: "node", id: "示例-甲" } });
     expect(byAlias.error).toBe("person_not_in_network");
     expect(byAlias.field).toBe("agent_owner");
-    expect(byAlias.hint).toContain("get_all_status");
-    expect(byAlias.hint).toContain("Aliases and usernames are not accepted");
+    // #473:人员字段也收名字 —— 提示改为指向 requirements_people,并说明 alias / username 的写法。
+    expect(byAlias.hint).toContain("requirements_people");
+    expect(byAlias.hint).toContain("{kind:'node', alias}");
     expect((await mcp(nodeToken, "requirements_update", { id: cardId, owner: { kind: "user", id: "u_nobody" } })).field).toBe("owner");
     expect((await mcp(nodeToken, "requirements_update", { id: cardId, participants: [{ kind: "node", id: "node_reqerr_a" }, { kind: "user", id: "u_nobody" }] })).field).toBe("participants");
   });

package/src/requirements-errors.ts

@@ -23,7 +23,8 @@ type Detail = { field?: string; message: string; hint?: string };
 type Entry = Detail | ((ctx: ErrorContext) => Detail);
 
 const DUE_FORMATS = 'YYYY-MM-DD (all day) or ISO 8601 with Z / ±HH:MM (e.g. 2026-10-10T18:00:00+08:00); "" clears it';
-const PERSON_IDS = "node ids (kind:'node') come from get_all_status (node_id) or a task's agent_owner / participants; user ids (kind:'user') from a task's owner / created_by / participants. Aliases and usernames are not accepted.";
+// #473 —— 人员字段也收名字({kind:'user', username} / {kind:'node', alias}),只在任务所在的网络里解析;查人用 requirements_people。
+const PERSON_IDS = "Look people up with requirements_people (q= filters by name): it returns each member's user_id and username and the node_id and alias of their Agents. Pass {kind:'user', id} or {kind:'user', username}, {kind:'node', id} or {kind:'node', alias}; names resolve only in the task's own network.";
 
 const ENTRIES: Record<string, Entry> = {
   // ── 定位 / 范围 ──
@@ -40,12 +41,18 @@ const ENTRIES: Record<string, Entry> = {
   upsert_not_allowed: { message: 'Task-scoped members cannot upsert by external_ref.', hint: 'Use requirements_create / requirements_update on tasks you can see.' },
   external_ref_not_allowed: { field: 'external_ref', message: 'Task-scoped members cannot set external_ref.', hint: 'Leave external_ref out.' },
   // ── 人员 ──
-  invalid_person: (ctx) => ({ field: ctx.field ?? 'owner', message: 'A person must be an object {kind:"user"|"node", id}.', hint: PERSON_IDS }),
-  person_not_in_network: (ctx) => ({ field: ctx.field ?? 'owner', message: `${ctx.field ?? 'owner'} names nobody in this network (unknown id, wrong kind, or a node you cannot see).`, hint: PERSON_IDS }),
+  invalid_person: (ctx) => ({ field: ctx.field ?? 'owner', message: 'A person must be an object {kind:"user", id | username} or {kind:"node", id | alias}.', hint: PERSON_IDS }),
+  person_not_in_network: (ctx) => ({ field: ctx.field ?? 'owner', message: `${ctx.field ?? 'owner'} names nobody in this network (unknown id / username / alias, wrong kind, or a node you cannot see).`, hint: PERSON_IDS }),
+  person_ambiguous: (ctx) => ({ field: ctx.field ?? 'agent_owner', message: 'More than one Agent in this network has that alias.', hint: 'Call requirements_people (q=<alias>) and pass the node_id instead.' }),
   owner_must_be_human: { field: 'owner', message: 'owner (负责人) must be a person.', hint: "Use owner: {kind:'user', id}. To assign a node / Agent, use agent_owner: {kind:'node', id}." },
   agent_owner_must_be_agent: { field: 'agent_owner', message: 'agent_owner (负责 Agent) must be a node.', hint: "Use agent_owner: {kind:'node', id}. To assign a person, use owner: {kind:'user', id}." },
   agent_owner_not_granted: { field: 'agent_owner', message: 'The current responsible Agent is one you are not granted, so you cannot replace or clear it.', hint: 'Leave agent_owner out of the patch.' },
   invalid_participants: { field: 'participants', message: 'participants must be an array of up to 100 persons {kind, id}; it replaces the whole list.', hint: 'Send the full list you want (read it first with requirements_get).' },
+  invalid_participants_delta: { field: 'participants_add', message: 'participants_add / participants_remove must each be an array of up to 100 persons ({kind, id}, {kind:"user", username} or {kind:"node", alias}).', hint: PERSON_IDS },
+  participants_conflict: { field: 'participants', message: 'participants (replace the whole list) cannot be combined with participants_add / participants_remove.', hint: 'Use participants_add / participants_remove to change a few people, or participants alone to replace the list.' },
+  participants_add_remove_overlap: { field: 'participants_remove', message: 'The same person is in both participants_add and participants_remove.', hint: 'Send each person in only one of the two lists.' },
+  too_many_participants: { field: 'participants_add', message: 'A task can have at most 100 participants.', hint: 'Remove some with participants_remove first.' },
+  status_conflicts_with_column: { field: 'status', message: 'status is an alias of column, and the two values sent differ.', hint: 'Send only one of them (pool, doing or done).' },
   invalid_assignee: { field: 'assignee', message: 'assignee must be a string (legacy free-text field).', hint: 'Prefer owner / agent_owner.' },
   // ── 项目 ──
   invalid_project: { field: 'project_id', message: 'project_id must be a project id string or null.', hint: 'Call projects_list to get project ids (proj_…); null removes the task from its project.' },
@@ -102,6 +109,8 @@ const ENTRIES: Record<string, Entry> = {
   invalid_updated_since: { field: 'updated_since', message: 'updated_since must be an ISO 8601 time.', hint: 'Use server_time from the previous changes=true response.' },
   updated_since_required: { field: 'updated_since', message: 'changes=true needs updated_since.', hint: 'Pass updated_since (ISO time; server_time from the last call).' },
   invalid_since: { field: 'since', message: 'since must be an ISO 8601 time.', hint: 'Use server_time from the previous requirements_events response.' },
+  invalid_comment: { field: 'text', message: 'A comment needs non-empty text.', hint: 'Pass text (markdown), e.g. a progress note or a conclusion.' },
+  comment_too_long: { field: 'text', message: 'A comment can be at most 4000 characters.', hint: 'Split it into several comments, or put the long part in the description.' },
   insert_failed: { message: 'The hub could not save the task.', hint: 'Retry once; if it fails again, report it.' },
 };
 

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

package/src/requirements-status-participants-http.test.ts

@@ -0,0 +1,216 @@
+// #475(MCP 任务生命周期测试报告问题 6)—— Agent 写任务时两处常见的坑:
+//   - status 当 column 用(列表的筛选参数就叫 status):MCP 的 create / update / upsert 把 status 当 column 的别名,
+//     两个都给且不同 → 400 status_conflicts_with_column;REST 不变(仍是 empty_patch + 提示用 column)。
+//   - participants 是整体替换,Agent 想「加一个人」时把别人全删了:新增 participants_add / participants_remove,
+//     在当前列表上加减、同一次同步读改写里完成;加已有 = 不变,减不在的 = 不变。
+// 外加 #476 第 1 部分:项目工具的描述写明节点令牌只能读项目(行为本来就是 403 user_token_required)。
+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-req-status-part-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqStatusPartPassw0rd!xyz";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+
+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 rpc(token: string, method: string, params: Record<string, unknown>) {
+  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, params }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const out = await rpc(token, "tools/call", { name, arguments: args });
+  const text = out.result?.content?.[0]?.text ?? "";
+  try { return JSON.parse(text); } catch { return { raw: out, text }; }
+}
+const keys = (refs: { kind: string; id: string }[]) => refs.map(r => `${r.kind}:${r.id}`).sort();
+const row = (id: string) => db.get<{ column_name: string; participants_json: string; updated_at: string }>("SELECT column_name, participants_json, updated_at FROM requirements WHERE requirement_id = ?1", id)!;
+const participantEvents = (id: string) => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events WHERE requirement_id = ?1 AND field = 'participants'", id)!.n;
+
+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(`sp_owner_${Date.now()}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  const username = `sp_member_${Date.now()}`;
+  expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" })).status).toBe(200);
+  const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+  U.member = { token: login.body.token, id: login.body.user.user_id };
+  for (const [k, alias] of [["nodeA", "示例-甲"], ["nodeB", "示例-乙"], ["nodeC", "示例-丙"]] as const) {
+    const nodeId = `node_sp_${k}`;
+    U[k] = { token: createNetworkTokenForNode(U.owner.id, NET, alias, nodeId).token!, id: nodeId };
+  }
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("status is an alias of column (MCP)", () => {
+  test("create / update / upsert with status land exactly where column would", async () => {
+    const viaStatus = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:status 建", status: "doing" })).requirement;
+    const viaColumn = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:column 建", column: "doing" })).requirement;
+    expect(viaStatus.column).toBe("doing");
+    expect(viaStatus.column).toBe(viaColumn.column);
+
+    const done = await mcp(U.nodeA.token, "requirements_update", { id: `#${viaStatus.seq}`, status: "done" });
+    expect(done.requirement.column).toBe("done");
+    expect(done.requirement.completedAt).toBeTruthy(); // same side effects as column=done
+    expect(row(viaStatus.id).column_name).toBe("done");
+
+    const same = await mcp(U.nodeA.token, "requirements_update", { id: viaColumn.id, status: "pool", column: "pool" });
+    expect(same.requirement.column).toBe("pool");
+
+    const up = await mcp(U.nodeA.token, "requirements_upsert_by_external_ref", { external_ref: "demo:status-alias-1", name: "示例:upsert", status: "doing" });
+    expect(up.created).toBe(true);
+    expect(up.requirement.column).toBe("doing");
+  });
+
+  test("status and column both sent and different → 400 status_conflicts_with_column with a hint; nothing written", async () => {
+    const card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:冲突", column: "pool" })).requirement;
+    const before = row(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, status: "doing", column: "done" });
+    expect(r.ok).toBe(false);
+    expect(r.status).toBe(400);
+    expect(r.error).toBe("status_conflicts_with_column");
+    expect(r.field).toBe("status");
+    expect(r.hint).toContain("only one");
+    expect(row(card.id)).toEqual(before);
+    const c = await mcp(U.nodeA.token, "requirements_create", { name: "示例:冲突建", status: "doing", column: "done" });
+    expect(c.error).toBe("status_conflicts_with_column");
+  });
+
+  test("a bad status value is a schema error (-32602), like a bad column", async () => {
+    const out = await rpc(U.nodeA.token, "tools/call", { name: "requirements_update", arguments: { id: "#1", status: "finished" } });
+    expect(String(out.error?.code ?? out.result?.content?.[0]?.text)).toMatch(/-32602|invalid/i);
+  });
+
+  test("REST is unchanged: status on PATCH is still not a writable field", async () => {
+    const card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:REST", column: "pool" })).requirement;
+    const r = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { status: "doing" });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("empty_patch");
+    expect(row(card.id).column_name).toBe("pool");
+  });
+});
+
+describe("participants_add / participants_remove", () => {
+  let card = { id: "", seq: 0 };
+  const node = (k: string) => ({ kind: "node", id: U[k].id });
+  const user = (k: string) => ({ kind: "user", id: U[k].id });
+
+  test("add keeps the people already there", async () => {
+    card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:参与人", participants: [user("member"), node("nodeA")] })).requirement;
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: `#${card.seq}`, participants_add: [node("nodeB")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+  });
+
+  test("add is idempotent: someone already there → same list, no participants event", async () => {
+    const events = participantEvents(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeB"), node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+    expect(participantEvents(card.id)).toBe(events);
+  });
+
+  test("remove drops only those people; removing someone absent (or no longer in the network) is a no-op", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_remove: [user("member"), { kind: "user", id: "u_left_the_network" }] });
+    expect(r.ok).toBe(true);
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB")]));
+  });
+
+  test("add and remove in one call are applied together", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeC"), user("member")], participants_remove: [node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeB"), node("nodeC"), user("member")]));
+  });
+
+  test("concurrent adds from two Agents both stick (no lost update)", async () => {
+    const fresh = (await mcp(U.owner.token, "requirements_create", { name: "示例:并发", participants: [user("owner")], network_id: NET })).requirement;
+    await Promise.all([
+      mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeA")] }),
+      mcp(U.nodeB.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeB")] }),
+      mcp(U.nodeC.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeC")] }),
+    ]);
+    expect(keys(JSON.parse(row(fresh.id).participants_json))).toEqual(keys([user("owner"), node("nodeA"), node("nodeB"), node("nodeC")]));
+  });
+
+  test("name forms (#473): add by alias / username, remove by username", async () => {
+    const fresh = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:按名字", participants: [node("nodeA")] })).requirement;
+    const memberName = db.get<{ username: string }>("SELECT username FROM users WHERE user_id = ?1", U.member.id)!.username;
+    const added = await mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_add: [{ kind: "node", alias: "示例-乙" }, { kind: "user", username: memberName }] });
+    expect(keys(added.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB"), user("member")]));
+    const removed = await mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_remove: [{ kind: "user", username: memberName }] });
+    expect(keys(removed.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB")]));
+  });
+
+  test("participants is still a full replace", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants: [node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeA")]));
+  });
+
+  test("bad combinations → 400 with hints, nothing written", async () => {
+    const before = row(card.id);
+    const both = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants: [], participants_add: [node("nodeB")] });
+    expect(both.status).toBe(400);
+    expect(both.error).toBe("participants_conflict");
+    expect(both.hint).toContain("participants_add");
+    const overlap = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeB")], participants_remove: [node("nodeB")] });
+    expect(overlap.error).toBe("participants_add_remove_overlap");
+    const stranger = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [{ kind: "node", id: "node_not_here" }] });
+    expect(stranger.error).toBe("person_not_in_network");
+    expect(stranger.field).toBe("participants_add");
+    expect(row(card.id)).toEqual(before);
+  });
+
+  test("REST accepts the same keys (additive; old clients never send them)", async () => {
+    const r = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { participants_add: [user("member")] });
+    expect(r.status).toBe(200);
+    // the member has no grant on nodeA, so the response leaves it out — but the stored list keeps it
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([node("nodeA"), user("member")]));
+    expect(keys(r.body.requirement.participants)).toEqual(keys([user("member")]));
+    // …and the member cannot remove an Agent they cannot see (same error as a node that does not exist)
+    const hidden = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { participants_remove: [node("nodeA")] });
+    expect(hidden.status).toBe(400);
+    expect(hidden.body.error).toBe("person_not_in_network");
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([node("nodeA"), user("member")]));
+  });
+});
+
+describe("tool descriptions", () => {
+  test("participants says it replaces; projects tools say node tokens only read; node token project write → 403", async () => {
+    const tools = (await rpc(U.nodeA.token, "tools/list", {})).result.tools as any[];
+    const byName = new Map(tools.map(t => [t.name, t]));
+    const update = byName.get("requirements_update");
+    expect(update.description).toContain("REPLACES the whole list");
+    expect(update.inputSchema.properties.participants.description).toContain("REPLACES");
+    expect(Object.keys(update.inputSchema.properties)).toEqual(expect.arrayContaining(["status", "participants_add", "participants_remove"]));
+    for (const name of ["projects_list", "projects_create", "projects_update"]) expect(byName.get(name).description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    const denied = await mcp(U.nodeA.token, "projects_create", { name: "示例项目" });
+    expect(denied.status).toBe(403);
+    expect(denied.error).toBe("user_token_required");
+  });
+});

package/src/requirements.ts

@@ -2,6 +2,7 @@
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
 import { errorBody, errorFrom, RequirementFieldError, type ErrorContext } from "./requirements-errors.js";
 import { createHash } from "node:crypto";
+import { parsePeopleQuery, peopleDirectory, resolvePersonName } from "./requirements-people.js";
 import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
 import { db, logAudit } from "./db.js";
 import { markGzipReusable } from "./http-gzip.js";
@@ -523,7 +524,15 @@ type PersonRef = { kind: 'user' | 'node'; id: string };
 function personRef(value: unknown, networkId: string, hidden: HiddenNode = null, field = 'owner'): PersonRef {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new RequirementFieldError('invalid_person', field);
   const row = value as Record<string, unknown>;
-  if ((row.kind !== 'user' && row.kind !== 'node') || typeof row.id !== 'string' || !row.id.trim()) throw new RequirementFieldError('invalid_person', field);
+  if (row.kind !== 'user' && row.kind !== 'node') throw new RequirementFieldError('invalid_person', field);
+  // #473 —— 没给 id 时可以按名字:人 {kind:'user', username},Agent {kind:'node', alias}。
+  // 只在 networkId(任务所在的网络)里找,绝不跨网络;存下来的仍是 {kind, id}。给了 id 就只看 id(与以前逐字相同)。
+  if (typeof row.id !== 'string' || !row.id.trim()) {
+    const name = row.kind === 'user' ? row.username : row.alias;
+    if (row.id !== undefined || typeof name !== 'string' || !name.trim()) throw new RequirementFieldError('invalid_person', field);
+    try { return { kind: row.kind, id: resolvePersonName(row.kind, name.trim(), networkId, hidden) }; }
+    catch (e) { throw new RequirementFieldError((e as Error).message, field); }
+  }
   const exists = row.kind === 'user'
     ? db.get("SELECT 1 FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 AND m.user_id=?2", networkId, row.id)
     : db.get("SELECT 1 FROM nodes WHERE network_id=?1 AND node_id=?2", networkId, row.id);
@@ -532,6 +541,18 @@ function personRef(value: unknown, networkId: string, hidden: HiddenNode = null,
   return { kind: row.kind, id: row.id };
 }
 
+// participants_remove 的一项 → "kind:id"。给了 id 就直接按 id 比(已经离开网络的人也能从列表里减掉,不查在不在网络里);
+// 没给 id 的形状交给 personRef 解析。受限成员看不见的节点与不存在同一个错误(不给他留探测差异)。
+function participantKey(value: unknown, networkId: string, hidden: HiddenNode, field: string): string {
+  const row = value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+  if (row && (row.kind === 'user' || row.kind === 'node') && typeof row.id === 'string' && row.id.trim()) {
+    if (row.kind === 'node' && hidden?.(row.id)) throw new RequirementFieldError('person_not_in_network', field);
+    return `${row.kind}:${row.id}`;
+  }
+  const ref = personRef(value, networkId, hidden, field);
+  return `${ref.kind}:${ref.id}`;
+}
+
 // 负责人只能是人类,负责 Agent 只能是节点;参与人两种都行。库里旧的节点负责人照样读出来(启动迁移会挪走),
 // 只有这次请求显式写了 owner / agent_owner 才校验种类。
 // 旧客户端兼容(App ≤ 0.2.142 只有一个「负责人」,可以选节点):请求里 owner 是节点、又**没带** agent_owner
@@ -544,7 +565,7 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
   // 受限成员看不见的负责 Agent,他也不能换掉或清空(他读到的是 null,写回 null 不该抹掉别人的指派)。
   const agentOwnerLocked = isHiddenRef(agentOwner, hidden);
   if ('owner' in body) {
-    owner = body.owner === null ? null : personRef(body.owner, networkId, hidden);
+    owner = body.owner === null ? null : personRef(body.owner, networkId, hidden, 'owner');
     if (owner && owner.kind !== 'user') {
       if (strictOwner || 'agent_owner' in body) throw new Error('owner_must_be_human');
       coerced = owner;
@@ -566,6 +587,26 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
     const keptHidden = hidden ? participants.filter((ref: unknown) => isHiddenRef(ref, hidden)) : [];
     participants = [...new Map([...keptHidden, ...refs].map((ref: PersonRef) => [`${ref.kind}:${ref.id}`, ref])).values()];
   }
+  // #475 —— 增量改参与人:participants_add / participants_remove 在当前列表上加 / 减(同步读改写,中间不让出,
+  // 并发的另一个请求插不进来),不碰别的参与人。加已有的人 = 不变;减不在列表里的人 = 不变。
+  // 和整体替换的 participants 不能同时用;同一个人既加又减 = 400,不猜先后。
+  if ('participants_add' in body || 'participants_remove' in body) {
+    if ('participants' in body) throw new RequirementFieldError('participants_conflict', 'participants');
+    const list = (key: string): unknown[] => {
+      const value = body[key];
+      if (value === undefined) return [];
+      if (!Array.isArray(value) || value.length > 100) throw new RequirementFieldError('invalid_participants_delta', key);
+      return value;
+    };
+    const add: PersonRef[] = list('participants_add').map(value => personRef(value, networkId, hidden, 'participants_add'));
+    const remove = new Set(list('participants_remove').map(value => participantKey(value, networkId, hidden, 'participants_remove')));
+    if (add.some(ref => remove.has(`${ref.kind}:${ref.id}`))) throw new RequirementFieldError('participants_add_remove_overlap', 'participants_remove');
+    const next = new Map<string, PersonRef>(participants.map((ref: PersonRef) => [`${ref.kind}:${ref.id}`, ref]));
+    for (const ref of add) if (!next.has(`${ref.kind}:${ref.id}`)) next.set(`${ref.kind}:${ref.id}`, ref);
+    for (const key of remove) next.delete(key);
+    if (next.size > 100) throw new RequirementFieldError('too_many_participants', 'participants_add');
+    participants = [...next.values()];
+  }
   return {
     coerced,
     ownerJson: owner === null ? null : JSON.stringify(owner),
@@ -578,12 +619,16 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
  * 节点令牌(Agent,比如把 GitHub issue 同步进任务的 TM 节点)可用的操作 —— 只在它自己的网络里
  * (令牌绑定的网络,范围由 resolveRestNetworkScope 强制)。删除卡片、管理项目仍然只给人。
  */
-const NODE_TOKEN_OPERATIONS: ReadonlySet<string> = new Set<string>(["read", "create", "patch", "checklist_item", "upsert", "projects_read"]);
+/** 一条评论最多这么多字(去掉首尾空白后);进展 / 结论写得下,又不至于让动态列表里一条撑爆。 */
+export const COMMENT_MAX_CHARS = 4000;
+
+const NODE_TOKEN_OPERATIONS: ReadonlySet<string> = new Set<string>(["read", "create", "patch", "checklist_item", "comment", "upsert", "projects_read"]);
 function operationOf(req: Request, url: URL): string {
   if (/^\/api\/requirements\/projects(\/|$)/.test(url.pathname)) return req.method === "GET" ? "projects_read" : "projects_write";
   if (url.pathname === "/api/requirements/tags/ops") return "tags_write";
   if (req.method === "GET") return "read";
   if (/^\/api\/requirements\/[^/]+\/checklist\/[^/]+$/.test(url.pathname)) return "checklist_item";
+  if (/^\/api\/requirements\/[^/]+\/comments$/.test(url.pathname)) return "comment";
   if (url.pathname === "/api/requirements/upsert") return "upsert";
   if (req.method === "DELETE") return "delete";
   if (req.method === "PATCH") return "patch";
@@ -811,7 +856,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
 }
 
 // ── 修改(省略的字段保留原值) ──
-const PATCH_FIELDS = ["column", "issues", "tags", "name", "priority", "due", "assignee", "owner", "agent_owner", "participants", "description", "checklist", "project_id", "external_ref", "external_url", "archived", "parent_id", "start"];
+const PATCH_FIELDS = ["column", "issues", "tags", "name", "priority", "due", "assignee", "owner", "agent_owner", "participants", "participants_add", "participants_remove", "description", "checklist", "project_id", "external_ref", "external_url", "archived", "parent_id", "start"];
 function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Record<string, unknown>): Response {
   if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400, { sent: Object.keys(body), writable: PATCH_FIELDS });
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
@@ -1294,6 +1339,15 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
 
   if (url.pathname === "/api/requirements/events" && req.method === "GET") return listEvents(ctx);
 
+  // #473 —— MCP requirements_people:紧凑通讯录(用户名、角色、部门、名下 Agent),q / limit / offset。
+  if (url.pathname === '/api/requirements/people/directory' && req.method === 'GET') {
+    const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+    if (!networkId) return jsonError('network_id_required', 400);
+    const pq = parsePeopleQuery(url.searchParams);
+    if ('error' in pq) return jsonError(pq.error, 400);
+    return Response.json(peopleDirectory(networkId, hiddenNodeFilter(ctx, networkId), pq));
+  }
+
   if (url.pathname === '/api/requirements/people' && req.method === 'GET') {
     const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
     if (!networkId) return jsonError('network_id_required', 400);
@@ -1388,6 +1442,28 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     return Response.json({ ...data, created: false });
   }
 
+  // #474 评论 / 进展(MCP 任务生命周期测试报告问题 5):以前 Agent 只能读全文再整段改写 description,两次调用、
+  // 并发会覆盖别人刚写的。评论是一条只追加的动态(requirement_events kind=comment,正文存在 new.text),
+  // 不碰 requirements 表的任何一列;谁能看见这张卡谁就能读到,能写这个网络(非只读角色)又看得见它的人能发。
+  const commentMatch = url.pathname.match(/^\/api\/requirements\/([^/]+)\/comments$/);
+  if (commentMatch) {
+    if (req.method !== "POST") return jsonError("not_found", 404);
+    let body: Record<string, unknown>;
+    try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
+    const text = typeof body.text === "string" ? body.text.trim() : "";
+    if (!text) return jsonError("invalid_comment", 400);
+    if (text.length > COMMENT_MAX_CHARS) return jsonError("comment_too_long", 400);
+    const row = scopedRow(ctx, decodeURIComponent(commentMatch[1]));
+    if (row instanceof Response) return row;
+    if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    const at = new Date().toISOString();
+    const event = db.transaction(() => {
+      recordRequirementEvents(db, row, JSON.stringify(actorOf(ctx)), [{ kind: "comment", field: null, old: null, new: { text } }], at);
+      return db.get<EventRow>("SELECT id, network_id, requirement_id, seq, title, actor_json, kind, field, old_json, new_json, created_at FROM requirement_events WHERE requirement_id = ?1 AND kind = 'comment' ORDER BY id DESC LIMIT 1", row.requirement_id)!;
+    });
+    return Response.json({ ok: true, event: eventPublic(event) }, { status: 201 });
+  }
+
   const itemMatch = url.pathname.match(/^\/api\/requirements\/([^/]+)\/checklist\/([^/]+)$/);
   if (itemMatch) {
     if (req.method !== "PATCH") return jsonError("not_found", 404);

package/src/tools.ts

@@ -14,6 +14,7 @@ import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
 import { addAgentNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { canMessageAgent, restrictedNetworkIds, RESTRICTED_MEMBER_TOOLS } from "./agent-access.js";
 import { restrictedMemberAttachmentsDenied } from "./restricted-files.js";
+import { errorBody } from "./requirements-errors.js";
 import { handleRequirementsRequest } from "./requirements.js";
 import {
   buildAnetArgs as _unused_buildAnetArgs,           // ensure module is loaded
@@ -5839,7 +5840,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     const data = res ? await res.json() : { ok: false, error: "not_found" };
     return { content: [{ type: "text" as const, text: JSON.stringify(res && !res.ok && data && typeof data === "object" ? { ...data, status: res.status } : data) }] };
   };
-  const reqPerson = z.object({ kind: z.enum(["user", "node"]), id: z.string().min(1).max(200) });
+  // #473 —— 人员字段除了 id,也可以按名字:{kind:'user', username} / {kind:'node', alias},在任务所在的网络里解析
+  // (requirements.ts personRef;找不到 / 别名对上多个 → 400 + hint)。给了 id 就只看 id。
+  const reqPerson = z.object({
+    kind: z.enum(["user", "node"]),
+    id: z.string().min(1).max(200).optional().describe("user_id / node_id (from requirements_people)"),
+    username: z.string().min(1).max(100).optional().describe("kind 'user' only: the member's username, resolved in the task's network"),
+    alias: z.string().min(1).max(200).optional().describe("kind 'node' only: the Agent's alias, resolved in the task's network"),
+  });
   const reqChecklistItem = z.object({ id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/).optional(), text: z.string().min(1).max(500), done: z.boolean().optional() });
   const reqFields = {
     tags: z.array(z.string()).max(10).optional().describe("Task labels; each 1–20 Unicode characters. Omit to preserve, [] to clear."),
@@ -5851,14 +5859,23 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     description: z.string().max(20_000).optional().describe("markdown"),
     checklist: z.array(reqChecklistItem).max(100).optional().describe("replaces the whole list"),
     project_id: z.string().max(200).nullable().optional(),
-    owner: reqPerson.nullable().optional().describe("负责人 (a person): must be {kind:'user', id}; a node here is rejected with 400 owner_must_be_human — use agent_owner for nodes"),
-    agent_owner: reqPerson.nullable().optional().describe("负责 Agent: must be {kind:'node'}"),
-    participants: z.array(reqPerson).max(100).optional(),
+    owner: reqPerson.nullable().optional().describe("负责人 (a person): {kind:'user', id} or {kind:'user', username}; a node here is rejected with 400 owner_must_be_human — use agent_owner for nodes"),
+    agent_owner: reqPerson.nullable().optional().describe("负责 Agent: {kind:'node', id} or {kind:'node', alias}"),
+    participants: z.array(reqPerson).max(100).optional().describe("REPLACES the whole participant list ({kind, id}, {kind:'user', username} or {kind:'node', alias}) (omitted people are removed; [] clears it). To add or remove a few people without touching the others, use participants_add / participants_remove on requirements_update."),
     external_url: z.string().max(500).nullable().optional(),
     parent_id: z.string().regex(/^[A-Za-z0-9_-]{1,200}$/).nullable().optional().describe("parent requirement (same network, no cycles, ≤ 5 levels); null detaches"),
   };
   const pick = (args: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter(k => args[k] !== undefined).map(k => [k, args[k]]));
   const REQ_WRITE_KEYS = [...Object.keys(reqFields), "external_ref", "archived"];
+  // #475 —— status 是 column 的别名(列表的筛选参数就叫 status,Agent 写任务时也常这么写)。只在 MCP 这层换名,REST 不变;
+  // 两个都给且不同 → 400 status_conflicts_with_column,不替调用方挑一个。
+  const reqStatus = z.enum(["pool", "doing", "done"]).optional().describe("alias of column (same values); if both are sent they must match");
+  const withColumn = (args: Record<string, unknown>, call: (args: Record<string, unknown>) => Promise<{ content: { type: "text"; text: string }[] }>) => {
+    if (args.status === undefined) return call(args);
+    if (args.column !== undefined && args.column !== args.status) return Promise.resolve({ content: [{ type: "text" as const, text: JSON.stringify({ ...errorBody("status_conflicts_with_column"), status: 400 }) }] });
+    return call({ ...args, column: args.status });
+  };
+  const reqPeopleDelta = (verb: string) => z.array(reqPerson).max(100).optional().describe(`${verb} these people ${verb === "add" ? "to" : "from"} the participant list, keeping everyone else (atomic; ${verb === "add" ? "already present = no change" : "not present = no change"}). Cannot be combined with participants.`);
   const REQ_ID_DESC = "requirement id (req_…) or its short number \"#N\" (e.g. \"#42\", per network; a user token that sees several networks must also pass network_id, else 409 ambiguous_seq)";
 
   // #471 —— MCP 的列表默认省流:summary 视图 + 50 张一页(REST 的默认 full + 500 不变,App 靠它)。
@@ -5907,6 +5924,31 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     },
   );
 
+  // #473 —— Agent 查人:紧凑通讯录(requirements-people.ts)。严格参数,同 requirements_list(#471)。
+  const reqPeopleShape = {
+    network_id: z.string().max(200).optional(),
+    q: z.string().min(1).max(100).optional().describe("case-insensitive substring of username, display name, department or Agent alias"),
+    limit: z.number().int().min(1).max(200).optional().describe("people per page, default 50"),
+    offset: z.number().int().min(0).optional().describe("next_offset from the previous page"),
+  };
+  const reqPeopleKeys = Object.keys(reqPeopleShape);
+  server.registerTool(
+    "requirements_people",
+    {
+      description: "Look up the people in your network and the Agents they own, to fill task person fields. Each row: user_id, username, display_name (\"\" if not set), role, department {id, name} or null, agents [{node_id, alias}]; Agents with no owner in this network are listed in agents_without_owner (first page only). q filters by username / display name / department / Agent alias (case-insensitive substring). 50 people per page (limit ≤ 200); has_more + next_offset → pass offset. Agents you are not granted are left out. Person fields on requirements_create / requirements_update / requirements_upsert_by_external_ref accept {kind:'user', id} or {kind:'user', username} (owner, participants) and {kind:'node', id} or {kind:'node', alias} (agent_owner, participants), resolved in the task's own network only.",
+      inputSchema: z.strictObject(reqPeopleShape, {
+        error: (iss: any) => iss.code === "unrecognized_keys"
+          ? `unknown parameter(s): ${(iss.keys ?? []).join(", ")}; valid parameters: ${reqPeopleKeys.join(", ")}`
+          : undefined,
+      }) as any,
+    },
+    async (args: any) => {
+      const q = new URLSearchParams();
+      for (const k of ["q", "limit", "offset"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      return requirementsCall("GET", `/api/requirements/people/directory${q.size ? `?${q}` : ""}`, args.network_id);
+    },
+  );
+
   server.tool(
     "requirements_get",
     "Get one requirement task by id or by its short number \"#N\" (with description, checklist, owners, project, external_ref, seq).",
@@ -5916,16 +5958,16 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_create",
-    "Create a requirement task. name is required. A duplicate external_ref in the network returns 409 external_ref_exists with existing_id — use requirements_upsert_by_external_ref for syncing.",
-    { network_id: z.string().max(200).optional(), ...reqFields, name: z.string().min(1).max(80), external_ref: z.string().max(200).optional() },
-    async (args) => requirementsCall("POST", "/api/requirements", args.network_id, pick(args, REQ_WRITE_KEYS)),
+    "Create a requirement task. name is required. column (or its alias status) = pool / doing / done. A duplicate external_ref in the network returns 409 external_ref_exists with existing_id — use requirements_upsert_by_external_ref for syncing.",
+    { network_id: z.string().max(200).optional(), ...reqFields, status: reqStatus, name: z.string().min(1).max(80), external_ref: z.string().max(200).optional() },
+    async (args) => withColumn(args, a => requirementsCall("POST", "/api/requirements", args.network_id, pick(a, REQ_WRITE_KEYS))),
   );
 
   server.tool(
     "requirements_update",
-    "Patch a requirement task (id or \"#N\"); omitted fields keep their value. archived=true hides it from the default list (agents cannot delete).",
-    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional(), ...reqFields, external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
-    async (args) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(args.id)}`, args.network_id, pick(args, REQ_WRITE_KEYS)),
+    "Patch a requirement task (id or \"#N\"); omitted fields keep their value. column (or its alias status) moves it between pool / doing / done. participants REPLACES the whole list; to add or remove people without dropping the others use participants_add / participants_remove. archived=true hides it from the default list (agents cannot delete).",
+    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional(), ...reqFields, status: reqStatus, participants_add: reqPeopleDelta("add"), participants_remove: reqPeopleDelta("remove"), external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
+    async (args) => withColumn(args, a => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(args.id)}`, args.network_id, pick(a, [...REQ_WRITE_KEYS, "participants_add", "participants_remove"]))),
   );
 
   server.tool(
@@ -5937,14 +5979,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_upsert_by_external_ref",
-    "Idempotent sync: create the task for external_ref (e.g. github:owner/repo#123) or, if it already exists in the network, patch it (omitted fields — including status — are kept). Returns { requirement, created }.",
-    { network_id: z.string().max(200).optional(), external_ref: z.string().min(1).max(200), ...reqFields, archived: z.boolean().optional() },
-    async (args) => requirementsCall("POST", "/api/requirements/upsert", args.network_id, pick(args, REQ_WRITE_KEYS)),
+    "Idempotent sync: create the task for external_ref (e.g. github:owner/repo#123) or, if it already exists in the network, patch it (omitted fields — including column / status — are kept). Returns { requirement, created }.",
+    { network_id: z.string().max(200).optional(), external_ref: z.string().min(1).max(200), ...reqFields, status: reqStatus, archived: z.boolean().optional() },
+    async (args) => withColumn(args, a => requirementsCall("POST", "/api/requirements/upsert", args.network_id, pick(a, REQ_WRITE_KEYS))),
   );
 
   server.tool(
     "projects_list",
-    "List requirement projects in your network (id, name, color, sort, archived). Manage them with projects_create / projects_update.",
+    "List requirement projects in your network (id, name, color, sort, archived). Node (Agent) tokens can only read projects; creating / changing them (projects_create / projects_update) needs a person's token.",
     { network_id: z.string().max(200).optional() },
     async ({ network_id }) => requirementsCall("GET", "/api/requirements/projects", network_id),
   );
@@ -5954,7 +5996,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // write access and is refused to 「仅相关任务」(task-scoped) members; events use the task list's visibility.
   server.tool(
     "projects_create",
-    "Create a requirement project in your network (same as 管理项目 → 新建 in the app). name 1–40 characters, unique in the network; color #RRGGBB (default: next palette colour); sort integer. Returns { project }. Refused (403) for task-scoped members and read-only roles.",
+    "Create a requirement project in your network (same as 管理项目 → 新建 in the app). name 1–40 characters, unique in the network; color #RRGGBB (default: next palette colour); sort integer. Returns { project }. Needs a person's token: node (Agent) tokens can only read projects (403 user_token_required). Also refused (403) for task-scoped members and read-only roles.",
     {
       network_id: z.string().max(200).optional(),
       name: z.string().min(1).max(40),
@@ -5966,7 +6008,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "projects_update",
-    "Rename, recolour, reorder, archive or unarchive a requirement project (same as 管理项目 in the app). Only the fields you pass change. archived=true hides it from pickers (its tasks keep project_id); archived=false brings it back. Returns { project }. Refused (403) for task-scoped members and read-only roles.",
+    "Rename, recolour, reorder, archive or unarchive a requirement project (same as 管理项目 in the app). Only the fields you pass change. archived=true hides it from pickers (its tasks keep project_id); archived=false brings it back. Returns { project }. Needs a person's token: node (Agent) tokens can only read projects (403 user_token_required). Also refused (403) for task-scoped members and read-only roles.",
     {
       network_id: z.string().max(200).optional(),
       id: z.string().min(1).max(200).describe("project id (proj_…), from projects_list"),
@@ -5980,7 +6022,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_events",
-    "Read the task activity timeline (the app's 动态): field-level changes — who, when, old → new — newest first. Pass requirement_id (req_… or \"#N\") for one task, or omit it for the whole network. since (ISO) = only changes after it; limit 1–500 (default 200); next_cursor → pass as cursor for the next page; server_time → use as the next since. Same visibility as requirements_list: tasks you can't see (and hidden Agents) are left out.",
+    "Read the task activity timeline (the app's 动态): field-level changes — who, when, old → new — and comments (kind=comment, text in new.text; add one with requirements_comment), newest first. Pass requirement_id (req_… or \"#N\") for one task, or omit it for the whole network. since (ISO) = only changes after it; limit 1–500 (default 200); next_cursor → pass as cursor for the next page; server_time → use as the next since. Same visibility as requirements_list: tasks you can't see (and hidden Agents) are left out.",
     {
       network_id: z.string().max(200).optional(),
       requirement_id: z.string().min(1).max(200).optional(),
@@ -6005,6 +6047,19 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       return requirementsCall("GET", `/api/requirements/events${q.size ? `?${q}` : ""}`, args.network_id);
     },
   );
+
+  // #474(MCP 任务生命周期测试报告问题 5):评论 / 进展。以前只能 requirements_get 读全文、再整段改写 description ——
+  // 两次调用,并发时覆盖别人刚写的描述。这条只追加,进「动态」(requirements_events kind=comment),不改任务本身。
+  server.tool(
+    "requirements_comment",
+    "Add a comment / progress note to a task (append-only; never rewrites the description). It shows in the task's activity timeline (the app's 动态, requirements_events kind=comment, text in new.text) under your name. text: markdown, 1–4000 characters. Anyone who can see the task and can write in the network (not read-only) may comment. Returns { event }.",
+    {
+      id: z.string().min(1).max(200).describe(REQ_ID_DESC),
+      text: z.string().min(1).max(4000).describe("the comment (markdown), 1–4000 characters"),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ id, text, network_id }) => requirementsCall("POST", `/api/requirements/${encodeURIComponent(id)}/comments`, network_id, { text }),
+  );
 }
 
 // ────────────────────────────────────────────────────────────────────