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

package/src/requirements-search.ts

@@ -94,7 +94,7 @@ export function decodeCursor(raw: string): Cursor | null {
   }
 }
 
-export type ListQuery = { limit: number; cursor: Cursor | null; terms: string[]; /** 整句当任务 ID 去对(taskIdQuery);空 = 没有搜索。 */ idQuery: string };
+export type ListQuery = { limit: number; cursor: Cursor | null; terms: string[]; /** 整句当任务 ID 去对(taskIdQuery);空 = 没有搜索。 */ idQuery: string; /** #471 —— 只要带这个标签的卡(精确、区分大小写);null = 不按标签筛。 */ tag: string | null };
 
 /**
  * 任务 ID(同 App 的 task-short-id.ts matchesTaskId):「#42」「42」精确对短号 seq;完整 id,或 8 位以上的
@@ -134,5 +134,12 @@ export function parseListQuery(params: URLSearchParams): ListQuery | { error: st
   const q = params.get("q") ?? "";
   if (q.length > MAX_QUERY_LENGTH) return { error: "invalid_q" };
   const terms = searchTerms(q);
-  return { limit, cursor, terms, idQuery: terms.length ? taskIdQuery(q) : "" };
+  // #471 —— tag=:和卡片标签同一套规范(去首尾空白、1–20 个字符、不含控制字符);不带 = 旧行为。
+  const rawTag = params.get("tag");
+  let tag: string | null = null;
+  if (rawTag !== null) {
+    tag = rawTag.trim();
+    if (!tag || [...tag].length > 20 || /[\u0000-\u001f\u007f]/u.test(tag)) return { error: "invalid_tag" };
+  }
+  return { limit, cursor, terms, idQuery: terms.length ? taskIdQuery(q) : "", tag };
 }

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

@@ -1,6 +1,8 @@
 // 需求池。长期卡片，存在 Hub 上，手机和电脑读同一份。
 // 不是 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";
@@ -37,6 +39,12 @@ export type RequirementsRequestContext = {
   isAdmin: boolean;
   isNodeToken: boolean;
   scope: RestNetworkScope;
+  /**
+   * #470 —— 负责人(owner)只收人,传节点一律 400 owner_must_be_human,不走旧 App 的「节点负责人 → 负责 Agent」兼容。
+   * MCP 工具(Agent 与人经 MCP 的调用)总是严格:那条兼容只为 App ≤ 0.2.142 的 REST 保存存在,Agent 走它会
+   * 静默清空人类负责人(task-lifecycle 测试报告问题 1)。REST 上带 agent_owner 的新客户端也严格(见 assignments)。
+   */
+  strictOwner?: boolean;
 };
 
 const COLUMNS = new Set(["pool", "doing", "done"]);
@@ -78,8 +86,9 @@ type Row = {
   completed_at_approx: number | null;
 };
 
-function jsonError(error: string, status: number): Response {
-  return Response.json({ ok: false, error }, { status });
+// #472:错误码原样,统一补 field / message / hint(requirements-errors.ts,唯一出口)。
+function jsonError(error: string, status: number, ctx?: ErrorContext): Response {
+  return Response.json(errorBody(error, ctx), { status });
 }
 
 // ── 任务的人员权限(RFC-038 §9,判定在 task-access.ts) ──
@@ -261,10 +270,10 @@ function projectNameTaken(networkId: string, name: string, except?: string): boo
 /** 卡片上的 project_id:null 清空;字符串必须是同一网络、未归档的项目。 */
 function projectRef(value: unknown, networkId: string): string | null {
   if (value === null) return null;
-  if (typeof value !== "string" || !value) throw new Error("invalid_project");
+  if (typeof value !== "string" || !value) throw new RequirementFieldError("invalid_project", "project_id", value);
   const row = db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, value);
-  if (!row || row.network_id !== networkId) throw new Error("project_not_in_network");
-  if (row.archived) throw new Error("project_archived");
+  if (!row || row.network_id !== networkId) throw new RequirementFieldError("project_not_in_network", "project_id", value);
+  if (row.archived) throw new RequirementFieldError("project_archived", "project_id", value);
   return row.project_id;
 }
 
@@ -512,33 +521,53 @@ const SELECT = "requirement_id, network_id, title, column_name, priority, due_on
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0 AND c.column_name = 'done') AS children_done";
 
 type PersonRef = { kind: 'user' | 'node'; id: string };
-function personRef(value: unknown, networkId: string, hidden: HiddenNode = null): PersonRef {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid_person');
+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 Error('invalid_person');
+  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);
   // 没授权的节点与不存在的节点同一个错误,不给受限成员留 node_id 探测差异。
-  if (!exists || (row.kind === 'node' && hidden?.(row.id as string))) throw new Error('person_not_in_network');
+  if (!exists || (row.kind === 'node' && hidden?.(row.id as string))) throw new RequirementFieldError('person_not_in_network', field);
   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
 // → 当成设置负责 Agent,负责人清空,照常 200,并回 owner_coerced_to_agent_owner: true。
 // 带了 agent_owner 的就是新客户端,保持严格:owner 是节点 → 400 owner_must_be_human。
-function assignments(body: Record<string, unknown>, networkId: string, current?: Row, hidden: HiddenNode = null) {
+function assignments(body: Record<string, unknown>, networkId: string, current?: Row, hidden: HiddenNode = null, strictOwner = false) {
   let owner = current?.owner_json ? JSON.parse(current.owner_json) : null;
   let agentOwner = current?.agent_owner_json ? JSON.parse(current.agent_owner_json) : null;
   let coerced: PersonRef | null = null;
   // 受限成员看不见的负责 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 ('agent_owner' in body) throw new Error('owner_must_be_human');
+      if (strictOwner || 'agent_owner' in body) throw new Error('owner_must_be_human');
       coerced = owner;
       agentOwner = owner;
       owner = null;
@@ -547,17 +576,37 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
   if (coerced && agentOwnerLocked) throw new Error('agent_owner_not_granted');
   if ('agent_owner' in body) {
     if (agentOwnerLocked) throw new Error('agent_owner_not_granted');
-    agentOwner = body.agent_owner === null ? null : personRef(body.agent_owner, networkId, hidden);
+    agentOwner = body.agent_owner === null ? null : personRef(body.agent_owner, networkId, hidden, 'agent_owner');
     if (agentOwner && agentOwner.kind !== 'node') throw new Error('agent_owner_must_be_agent');
   }
   let participants = current ? JSON.parse(current.participants_json || '[]') : [];
   if ('participants' in body) {
     if (!Array.isArray(body.participants) || body.participants.length > 100) throw new Error('invalid_participants');
-    const refs = body.participants.map(value => personRef(value, networkId, hidden));
+    const refs = body.participants.map(value => personRef(value, networkId, hidden, 'participants'));
     // 参与人是整体替换:把受限成员看不见的那些节点原样留下,别让他「保存」时静默删掉。
     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),
@@ -570,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";
@@ -741,7 +794,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   const scoped = !!caller && isTaskScoped(caller.userId, networkId);
   let projectId: string | null = null;
   if (body.project_id !== undefined) {
-    try { projectId = projectRef(body.project_id, networkId); } catch (e) { return jsonError((e as Error).message, 400); }
+    try { projectId = projectRef(body.project_id, networkId); } catch (e) { return errorFrom(e); }
     // scoped 成员只能建进自己 can_edit 的项目;没授权的项目与不存在的项目同一个错误。
     if (!canUseProject(caller, networkId, projectId)) return jsonError("project_not_in_network", 400);
   }
@@ -760,7 +813,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   if (ref) {
     const existing = rowByExternalRef(networkId, ref);
     // 同一个外部条目再建一次 = 冲突,回已有的 id(同步方改用 upsert,或按这个 id PATCH)。
-    if (existing) return Response.json({ ok: false, error: "external_ref_exists", existing_id: existing.requirement_id }, { status: 409 });
+    if (existing) return Response.json({ ...errorBody("external_ref_exists"), existing_id: existing.requirement_id }, { status: 409 });
   }
   if (clientId) {
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
@@ -770,7 +823,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   const id = `req_${crypto.randomUUID()}`;
   const createdAt = new Date().toISOString();
   let people;
-  try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId)); } catch (e) { return jsonError((e as Error).message, 400); }
+  try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
   const actor = JSON.stringify(actorOf(ctx));
   try {
     // 领号、插入、记「新建」这条动态在同一个事务里:插入被唯一索引挡下时,号和动态一起回滚,不留空洞。
@@ -790,7 +843,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
     if (ref) {
       const existing = rowByExternalRef(networkId, ref);
-      if (existing) return Response.json({ ok: false, error: "external_ref_exists", existing_id: existing.requirement_id }, { status: 409 });
+      if (existing) return Response.json({ ...errorBody("external_ref_exists"), existing_id: existing.requirement_id }, { status: 409 });
     }
     if (!clientId) return jsonError("insert_failed", 500);
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
@@ -803,9 +856,9 @@ 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);
+  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);
   if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
   const caller = taskCaller(ctx);
@@ -856,10 +909,10 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     assignee = body.assignee.trim().slice(0, 80);
   }
   let people;
-  try { people = assignments(body, row.network_id, row, hiddenNodeFilter(ctx, row.network_id)); } catch (e) { return jsonError((e as Error).message, 400); }
+  try { people = assignments(body, row.network_id, row, hiddenNodeFilter(ctx, row.network_id), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
   let projectId = row.project_id;
   if (has("project_id")) {
-    try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return jsonError((e as Error).message, 400); }
+    try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return errorFrom(e); }
     // scoped 成员只能挪进自己 can_edit 的项目;没授权的项目与不存在的项目同一个错误。
     if (projectId !== row.project_id && !canUseProject(caller, row.network_id, projectId)) return jsonError("project_not_in_network", 400);
   }
@@ -869,7 +922,7 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     if (next === undefined) return jsonError("invalid_external_ref", 400);
     if (next && next !== row.external_ref) {
       const taken = rowByExternalRef(row.network_id, next);
-      if (taken) return Response.json({ ok: false, error: "external_ref_exists", existing_id: taken.requirement_id }, { status: 409 });
+      if (taken) return Response.json({ ...errorBody("external_ref_exists"), existing_id: taken.requirement_id }, { status: 409 });
     }
     ref = next;
   }
@@ -950,7 +1003,7 @@ function scopedRow(ctx: RequirementsRequestContext, id: string): Row | Response
   const rows = db.all<Row>(`${sql} LIMIT 2`, ...params);
   if (rows.length > 1) {
     const networks = rows.map(r => r.network_id);
-    return Response.json({ ok: false, error: "ambiguous_seq", networks, message: `#${seq} exists in more than one network you can see (${networks.join(", ")}); pass network_id to pick one` }, { status: 409 });
+    return Response.json({ ...errorBody("ambiguous_seq"), networks, message: `#${seq} exists in more than one network you can see (${networks.join(", ")}); pass network_id to pick one` }, { status: 409 });
   }
   return rows[0] ?? jsonError("requirement_not_found", 404);
 }
@@ -1014,7 +1067,7 @@ function listPage(ctx: RequirementsRequestContext, from: string, baseParams: unk
     where += ` AND (created_at < ?${a} OR (created_at = ?${a} AND requirement_id < ?${b}))`;
   }
   let rows: Row[];
-  if (!lq.terms.length) {
+  if (!lq.terms.length && lq.tag === null) {
     rows = db.all<Row>(`SELECT ${SELECT} ${where}${LIST_ORDER} LIMIT ${lq.limit + 1}`, ...params);
   } else {
     // seq(任务短号,#2139):启动迁移 ensureRequirementSeq 在 SQLite / PostgreSQL 上都加这一列,SELECT 本来就带它。
@@ -1025,7 +1078,9 @@ function listPage(ctx: RequirementsRequestContext, from: string, baseParams: unk
       let m = maps.get(r.network_id);
       if (!m) maps.set(r.network_id, m = searchNameMaps(ctx, r.network_id));
       const row = { name: r.title, description: r.description || "", assignee: r.assignee || "", tags: storedTags(r.tags_json), project_id: r.project_id, owner: parseRef(r.owner_json), agent_owner: parseRef(r.agent_owner_json), participants: parseRef(r.participants_json) ?? [] };
-      if (matchesTaskId(r, lq.idQuery) || matchesTerms(row, lq.terms, m)) hits.push(r.requirement_id);
+      // #471 —— tag= 在这里按存好的标签数组精确比(JSON 列,SQLite / PostgreSQL 写法不同,所以不进 SQL)。
+      if (lq.tag !== null && !row.tags.includes(lq.tag)) continue;
+      if (!lq.terms.length || matchesTaskId(r, lq.idQuery) || matchesTerms(row, lq.terms, m)) hits.push(r.requirement_id);
       if (hits.length > lq.limit) break;
     }
     const byId = new Map(hits.length ? db.all<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id IN (${hits.map((_, i) => `?${i + 1}`).join(",")})`, ...hits).map(r => [r.requirement_id, r]) : []);
@@ -1284,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);
@@ -1378,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);
@@ -1436,7 +1522,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
   if (req.method !== "PATCH") return jsonError("not_found", 404);
   let body: Record<string, unknown>;
   try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
-  if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400);
+  if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400, { sent: Object.keys(body), writable: PATCH_FIELDS });
   const row = scopedRow(ctx, id);
   if (row instanceof Response) return row;
   return patchRequirement(ctx, row, body);