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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.88",
+  "version": "0.9.0-preview.89",
   "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/requirements-errors-mcp-http.test.ts

@@ -0,0 +1,163 @@
+// #472(MCP 任务生命周期测试报告问题 4)—— 任务 / 项目接口的错误带上 field / message / hint,`error` 原样。
+// 每条提示一个测试(经 MCP,以 Agent / 人的身份),外加一道取集门:requirements.ts 里返回 / 抛出的每个错误码都在
+// requirements-errors.ts 的登记表里,新加的错误码没登记 ⇒ 红。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+import { __documentedErrorCodes, errorBody } from "./requirements-errors.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-errors-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqErrorsPassw0rd!xyz";
+let NET = "", ownerToken = "", ownerId = "", nodeToken = "", memberToken = "", cardId = "";
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const out = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(out.result.content[0].text);
+}
+
+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(`reqerr_owner_${Date.now()}`, PW, undefined, "Owner");
+  ownerToken = a.token!; ownerId = a.user!.user_id; NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [ownerId]);
+  nodeToken = createNetworkTokenForNode(ownerId, NET, "示例-甲", "node_reqerr_a").token!;
+  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 = `reqerr_member_${Date.now()}`;
+  expect((await rest(ownerToken, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" })).status).toBe(200);
+  memberToken = (await rest("", "POST", "/api/auth/login", { username, password: PW })).body.token;
+  cardId = (await mcp(nodeToken, "requirements_create", { name: "错误提示测试" })).requirement.id;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("each hint, over MCP", () => {
+  test("invalid_due: field due, the accepted formats", async () => {
+    for (const due of ["下周五", "2026/10/10"]) {
+      const r = await mcp(nodeToken, "requirements_update", { id: cardId, due });
+      expect(r.error).toBe("invalid_due");
+      expect(r.status).toBe(400);
+      expect(r.field).toBe("due");
+      expect(r.hint).toContain("YYYY-MM-DD");
+      expect(r.hint).toContain("ISO 8601");
+    }
+    expect((await mcp(nodeToken, "requirements_update", { id: cardId, start: "明天" })).field).toBe("start");
+  });
+
+  test("person_not_in_network: names the field, explains node_id vs user_id and where to find them", async () => {
+    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");
+    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");
+  });
+
+  test("project_not_in_network: a name is recognised as a name; both point to projects_list", async () => {
+    const byName = await mcp(nodeToken, "requirements_update", { id: cardId, project_id: "示例项目" });
+    expect(byName.error).toBe("project_not_in_network");
+    expect(byName.field).toBe("project_id");
+    expect(byName.message).toContain("looks like a project name");
+    expect(byName.hint).toContain("projects_list");
+    const byId = await mcp(nodeToken, "requirements_update", { id: cardId, project_id: "proj_missing" });
+    expect(byId.error).toBe("project_not_in_network");
+    expect(byId.message).not.toContain("project name");
+    expect(byId.hint).toContain("projects_list");
+  });
+
+  test("empty_patch: lists the writable fields; sending status says to use column", async () => {
+    // The MCP tool schema strips keys it does not know, so `status` arrives as nothing; REST sees the raw body.
+    const viaRest = await rest(nodeToken, "PATCH", `/api/requirements/${cardId}`, { status: "doing" });
+    expect(viaRest.status).toBe(400);
+    expect(viaRest.body.error).toBe("empty_patch");
+    expect(viaRest.body.hint).toContain("use column");
+    expect(viaRest.body.hint).toContain("Writable fields: column");
+    expect(viaRest.body.message).toContain("status");
+    const viaMcp = await mcp(nodeToken, "requirements_update", { id: cardId });
+    expect(viaMcp.error).toBe("empty_patch");
+    expect(viaMcp.hint).toContain("Writable fields:");
+    expect(viaMcp.hint).not.toContain("use column");
+  });
+
+  test("user_token_required: says projects are managed by people and what to do instead", async () => {
+    const r = await mcp(nodeToken, "projects_create", { name: "节点建项目" });
+    expect(r.error).toBe("user_token_required");
+    expect(r.status).toBe(403);
+    expect(r.message).toContain("node token");
+    expect(r.hint).toContain("projects_list");
+  });
+
+  test("network_id_required: field network_id and how to fix it", async () => {
+    const r = await mcp(memberToken, "projects_create", { name: "成员建项目" });
+    expect(r.error).toBe("network_id_required");
+    expect(r.field).toBe("network_id");
+    expect(r.hint).toContain("network_id");
+  });
+
+  test("swept codes carry hints too: checklist_item_not_found, external_ref_exists (existing_id kept), owner_must_be_human, parent_cycle", async () => {
+    const ck = await mcp(nodeToken, "requirements_checklist_toggle", { id: cardId, item_id: "nope", done: true });
+    expect(ck.error).toBe("checklist_item_not_found");
+    expect(ck.hint).toContain("requirements_get");
+    await mcp(nodeToken, "requirements_create", { name: "外部", external_ref: "github:example/repo#472" });
+    const dup = await mcp(nodeToken, "requirements_create", { name: "外部又一次", external_ref: "github:example/repo#472" });
+    expect(dup.error).toBe("external_ref_exists");
+    expect(typeof dup.existing_id).toBe("string");
+    expect(dup.hint).toContain("requirements_upsert_by_external_ref");
+    const own = await mcp(nodeToken, "requirements_update", { id: cardId, owner: { kind: "node", id: "node_reqerr_a" } });
+    expect(own.error).toBe("owner_must_be_human");
+    expect(own.hint).toContain("agent_owner");
+    const cyc = await mcp(nodeToken, "requirements_update", { id: cardId, parent_id: cardId });
+    expect(cyc.error).toBe("parent_cycle");
+    expect(cyc.field).toBe("parent_id");
+  });
+});
+
+describe("compatibility", () => {
+  test("REST keeps the exact error strings the app matches on; the new keys are additive", async () => {
+    const r = await rest(ownerToken, "PATCH", `/api/requirements/${cardId}`, { due: "下周五" });
+    expect(r.status).toBe(400);
+    expect(r.body.ok).toBe(false);
+    expect(r.body.error).toBe("invalid_due");
+    expect(Object.keys(r.body).sort()).toEqual(["error", "field", "hint", "message", "ok"]);
+    // A code without an entry is exactly the old shape.
+    expect(errorBody("some_future_code")).toEqual({ ok: false, error: "some_future_code" });
+  });
+
+  test("every error code requirements.ts returns or throws has an entry (a new code must be documented)", () => {
+    const src = readFileSync(join(import.meta.dir, "requirements.ts"), "utf8");
+    const codes = new Set<string>();
+    for (const m of src.matchAll(/jsonError\(\s*["']([a-z_]+)["']/g)) codes.add(m[1]);
+    for (const m of src.matchAll(/(?:new (?:Error|RequirementFieldError))\(\s*["']([a-z_]+)["']/g)) codes.add(m[1]);
+    for (const m of src.matchAll(/errorBody\(\s*["']([a-z_]+)["']/g)) codes.add(m[1]);
+    for (const m of src.matchAll(/return\s+["'](parent_[a-z_]+)["']/g)) codes.add(m[1]);
+    expect(codes.size).toBeGreaterThan(40); // the scan really found the codes (not an empty pass)
+    const documented = new Set(__documentedErrorCodes());
+    expect([...codes].filter(c => !documented.has(c)).sort()).toEqual([]);
+  });
+});

package/src/requirements-errors.ts

@@ -0,0 +1,129 @@
+// #472(MCP 任务生命周期测试报告问题 4)—— 任务 / 项目接口的错误不再只有一个代码。
+//
+// 以前回 `{ ok:false, error:"invalid_due" }`:app 按代码自己出文案,能用;但 MCP 上的 Agent 拿到的就只有这个词,
+// 不知道哪个字段错了、正确的格式是什么、下一步该调哪个工具。这里给每个代码配上:
+//   field   —— 出错的字段(有的话),
+//   message —— 一句英文说明(MCP 工具描述都是英文,读的是 LLM;app 不显示它),
+//   hint    —— 怎么改 / 下一步调什么。
+// 🔴 `error` 字符串原样不变:app、测试、脚本都按它匹配。新增的三个键旧客户端不认识,直接忽略。
+// 只有一个出口:requirements.ts 的 jsonError() 和抛错转换都走 errorBody(),不在调用点各写各的。
+
+export type ErrorContext = {
+  /** 出错的字段(调用点知道时传;不传就用登记表里的默认字段)。 */
+  field?: string;
+  /** 请求里实际带了哪些键(empty_patch 用来指出「你传了 status,该用 column」)。 */
+  sent?: readonly string[];
+  /** 可写字段(empty_patch 列出来)。 */
+  writable?: readonly string[];
+  /** 出错的那个值(project_not_in_network 用来判断是不是传了项目名)。 */
+  value?: unknown;
+};
+
+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.";
+
+const ENTRIES: Record<string, Entry> = {
+  // ── 定位 / 范围 ──
+  network_id_required: { field: 'network_id', message: 'This token can see more than one network (or is not bound to one), so the network must be named.', hint: 'Pass network_id (the network the task or project belongs to).' },
+  ambiguous_seq: { field: 'id', message: 'That #N exists in more than one network you can see.', hint: 'Pass network_id, or use the req_… id.' },
+  requirement_not_found: { field: 'id', message: 'No task with that id or #N in this network (or you cannot see it).', hint: 'Find it with requirements_list (q= searches titles; include_archived=true also lists archived tasks).' },
+  not_found: { message: 'No such task, project or route.', hint: 'Check the id; requirements_list / projects_list return the ids you can use.' },
+  project_not_found: { field: 'id', message: 'No project with that id in this network.', hint: 'Call projects_list to get project ids (proj_…).' },
+  tag_not_found: { field: 'tag', message: 'No task in this network carries that tag.', hint: 'Tags are free text on tasks; list the ones in use from requirements_list (view=summary shows each task’s tags).' },
+  checklist_item_not_found: { field: 'item_id', message: 'This task has no checklist item with that id.', hint: 'Item ids (ck_…) are in requirements_get → checklist[].id.' },
+  // ── 权限 ──
+  user_token_required: { message: 'This operation is for people only: a node token can read projects and read / create / update tasks, but cannot manage projects or delete tasks.', hint: 'Use an existing project (projects_list), or ask a person to create / change the project in the app (任务 → 管理项目).' },
+  permission_denied: { message: 'Your role in this network cannot do this (read-only, or task-scoped to other projects).', hint: 'Ask a network admin for write access, or work on tasks you can see.' },
+  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 }),
+  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_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.' },
+  project_not_in_network: (ctx) => {
+    const looksLikeName = typeof ctx.value === 'string' && !/^proj_/.test(ctx.value);
+    return {
+      field: ctx.field ?? 'project_id',
+      message: looksLikeName ? `"${String(ctx.value).slice(0, 40)}" is not a project id — it looks like a project name.` : 'No project with that id in this network.',
+      hint: 'Call projects_list and pass the project’s id (proj_…), not its name.',
+    };
+  },
+  project_archived: { field: 'project_id', message: 'That project is archived.', hint: 'Pick an active project from projects_list, or ask a person to unarchive it.' },
+  project_name_taken: { field: 'name', message: 'A project with that name already exists in this network.', hint: 'Use the existing one (projects_list) or choose another name.' },
+  invalid_project_name: { field: 'name', message: 'Project name must be 1–40 characters.' },
+  invalid_project_color: { field: 'color', message: 'color must be #RRGGBB.' },
+  invalid_project_sort: { field: 'sort', message: 'sort must be an integer.' },
+  invalid_project_archived: { field: 'archived', message: 'archived must be true or false.' },
+  too_many_projects: { message: 'This network has reached the project limit (200).', hint: 'Reuse an existing project (projects_list).' },
+  // ── 任务字段 ──
+  empty_patch: (ctx) => {
+    const sent = ctx.sent ?? [];
+    const writable = ctx.writable?.length ? ctx.writable.join(', ') : 'name, column, priority, due, start, description, checklist, tags, owner, agent_owner, participants, project_id, parent_id, external_ref, external_url, archived';
+    const statusHint = sent.includes('status') ? 'To move a task between pool / doing / done, use column (status is the name of the list filter). ' : '';
+    return { message: sent.length ? `None of the keys sent (${sent.join(', ')}) is a writable field.` : 'The patch changes nothing.', hint: `${statusHint}Writable fields: ${writable}.` };
+  },
+  invalid_json: { message: 'The request body must be a JSON object.' },
+  invalid_name: { field: 'name', message: 'name must be 1–80 characters.' },
+  invalid_description: { field: 'description', message: 'description must be a string (markdown) of at most 20 000 characters.' },
+  invalid_column: { field: 'column', message: 'column must be pool, doing or done.' },
+  invalid_status: { field: 'status', message: 'status (list filter) must be pool, doing or done.' },
+  invalid_priority: { field: 'priority', message: 'priority must be high (P0), normal (P1), low (P2) or lowest (P3).' },
+  invalid_due: { field: 'due', message: 'due is not a date this hub understands.', hint: `Use ${DUE_FORMATS}.` },
+  invalid_start: { field: 'start', message: 'start is not a date this hub understands.', hint: `Use ${DUE_FORMATS}.` },
+  invalid_tags: { field: 'tags', message: 'tags must be an array of at most 10 strings, each 1–20 characters.', hint: 'Omit tags to keep them, [] to clear.' },
+  invalid_checklist: { field: 'checklist', message: 'checklist must be an array of up to 100 items {text (1–500 chars), done?, id?}; it replaces the whole list.', hint: 'To tick one item use requirements_checklist_toggle (item ids from requirements_get).' },
+  invalid_done: { field: 'done', message: 'done must be true or false.' },
+  invalid_parent_id: { field: 'parent_id', message: 'parent_id must be a task id in this network (or null to detach).', hint: 'Get the parent’s req_… id from requirements_list / requirements_get.' },
+  parent_cycle: { field: 'parent_id', message: 'That parent would make the task its own ancestor.', hint: 'Pick a parent that is not this task or one of its children.' },
+  parent_too_deep: { field: 'parent_id', message: 'Tasks nest at most 5 levels.', hint: 'Attach it to a higher-level task.' },
+  parent_not_found: { field: 'parent_id', message: 'No task with that parent_id in this network (or you cannot see it).', hint: 'Get the parent’s req_… id from requirements_list / requirements_get.' },
+  invalid_external_ref: { field: 'external_ref', message: 'external_ref must start with a letter or digit and use only letters, digits and _ . : / # @ + - (≤ 200 characters).', hint: 'e.g. github:owner/repo#123' },
+  external_ref_required: { field: 'external_ref', message: 'external_ref is required for upsert.' },
+  external_ref_exists: { field: 'external_ref', message: 'A task with that external_ref already exists in this network (existing_id).', hint: 'Use requirements_upsert_by_external_ref to sync, or requirements_update on existing_id.' },
+  invalid_external_url: { field: 'external_url', message: 'external_url must be an http(s) URL of at most 500 characters, or null.' },
+  invalid_issues: { field: 'issues', message: 'issues must be an array of issue references.' },
+  invalid_archived: { field: 'archived', message: 'archived must be true or false.' },
+  invalid_seq: { field: 'seq', message: 'seq must be a positive integer (the #N shown for a task).' },
+  invalid_client_id: { field: 'client_id', message: 'client_id must be 1–80 characters of letters, digits, ., _ or -.' },
+  client_id_taken: { field: 'client_id', message: 'That client_id was already used for another task.', hint: 'Generate a new client_id for each new task.' },
+  // ── 列表 / 事件 ──
+  invalid_view: { field: 'view', message: 'view must be full or summary.' },
+  invalid_limit: { field: 'limit', message: 'limit is out of range.' },
+  invalid_cursor: { field: 'cursor', message: 'cursor is not one this hub issued.', hint: 'Pass next_cursor from the previous page unchanged, or start again without cursor.' },
+  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.' },
+  insert_failed: { message: 'The hub could not save the task.', hint: 'Retry once; if it fails again, report it.' },
+};
+
+/** 错误响应体:`error` 原样,补上 field / message / hint(登记表里没有的代码就只有 error,和以前一样)。 */
+export function errorBody(error: string, ctx: ErrorContext = {}): { ok: false; error: string; field?: string; message?: string; hint?: string } {
+  const entry = ENTRIES[error];
+  if (!entry) return { ok: false, error };
+  const d = typeof entry === 'function' ? entry(ctx) : entry;
+  const field = ctx.field ?? d.field;
+  return { ok: false, error, ...(field ? { field } : {}), message: d.message, ...(d.hint ? { hint: d.hint } : {}) };
+}
+
+/** 带字段的抛错:assignments / projectRef 里抛,调用点的 catch 用 errorFrom() 转成响应。 */
+export class RequirementFieldError extends Error {
+  constructor(code: string, readonly field?: string, readonly value?: unknown) { super(code); }
+}
+
+export function errorFrom(e: unknown, status = 400): Response {
+  const code = (e as Error)?.message ?? 'invalid_json';
+  const fe = e instanceof RequirementFieldError ? e : null;
+  return Response.json(errorBody(code, { field: fe?.field, value: fe?.value }), { status });
+}
+
+/** Test-only: every code with an entry. */
+export const __documentedErrorCodes = (): string[] => Object.keys(ENTRIES);

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

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

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

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

package/src/requirements-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.ts

@@ -1,5 +1,6 @@
 // 需求池。长期卡片，存在 Hub 上，手机和电脑读同一份。
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
+import { errorBody, errorFrom, RequirementFieldError, type ErrorContext } from "./requirements-errors.js";
 import { createHash } from "node:crypto";
 import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
 import { db, logAudit } from "./db.js";
@@ -37,6 +38,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 +85,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 +269,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,15 +520,15 @@ 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') || typeof row.id !== 'string' || !row.id.trim()) throw new RequirementFieldError('invalid_person', 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 };
 }
 
@@ -529,7 +537,7 @@ function personRef(value: unknown, networkId: string, hidden: HiddenNode = null)
 // 旧客户端兼容(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;
@@ -538,7 +546,7 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
   if ('owner' in body) {
     owner = body.owner === null ? null : personRef(body.owner, networkId, hidden);
     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,13 +555,13 @@ 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()];
@@ -741,7 +749,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 +768,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 +778,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 +798,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);
@@ -805,7 +813,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"];
 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 +864,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 +877,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 +958,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 +1022,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 +1033,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]) : []);
@@ -1436,7 +1446,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);

package/src/tools.ts

@@ -5833,6 +5833,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       isAdmin: false,
       isNodeToken: callerTokenIsNetwork,
       scope,
+      // #470:经 MCP 的写一律严格 —— owner 传节点回 400 owner_must_be_human(+ hint),不走旧 App 的兼容改写。
+      strictOwner: true,
     });
     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) }] };
@@ -5849,7 +5851,7 @@ 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("负责人: must be {kind:'user'}"),
+    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(),
     external_url: z.string().max(500).nullable().optional(),
@@ -5859,31 +5861,49 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   const REQ_WRITE_KEYS = [...Object.keys(reqFields), "external_ref", "archived"];
   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)";
 
-  server.tool(
+  // #471 —— MCP 的列表默认省流:summary 视图 + 50 张一页(REST 的默认 full + 500 不变,App 靠它)。
+  // 生产实测 122 张卡:旧默认(full、500)148 KB,summary 81 KB —— 一次调用就塞满 Agent 的上下文。
+  // 输入 schema 严格:写错 / 不认识的参数(比如以前的 tag)原来会被静默丢掉、回整张表;现在回 -32602 并列出能用的参数。
+  const REQ_LIST_MCP_DEFAULT_LIMIT = 50;
+  const reqListShape = {
+    network_id: z.string().max(200).optional(),
+    seq: z.number().int().positive().optional().describe("short number (#N) of one task in this network"),
+    status: z.enum(["pool", "doing", "done"]).optional(),
+    project_id: z.string().max(200).optional(),
+    owner: z.string().max(210).optional(),
+    agent_owner: z.string().max(210).optional(),
+    tag: z.string().min(1).max(80).optional().describe("only tasks carrying this label (exact, case-sensitive)"),
+    updated_since: z.string().max(40).optional(),
+    external_ref: z.string().max(200).optional(),
+    include_archived: z.boolean().optional(),
+    parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
+    top_level: z.boolean().optional(), q: z.string().max(200).optional(),
+    limit: z.number().int().min(1).max(1000).optional().describe(`page size, default ${REQ_LIST_MCP_DEFAULT_LIMIT}`),
+    cursor: z.string().max(600).optional().describe("next_cursor from the previous page"),
+    view: z.enum(["full", "summary"]).optional().describe("default summary (no description / checklist bodies; has_description, checklist_count instead); full = everything"),
+    changes: z.boolean().optional().describe("with updated_since: only tasks changed since then (archived included) + deleted ids + server_time"),
+  };
+  const reqListKeys = Object.keys(reqListShape);
+  server.registerTool(
     "requirements_list",
-    "List requirement tasks in your network. Filters: seq (the per-network short number shown as #N), status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived; q = search title / description / owner, agent and participant names / project name / tags (space-separated terms are ANDed). Newest first, 500 per page by default (limit ≤ 1000); has_more + next_cursor → pass cursor for the next page. Each task carries children {total, done}. view='summary' drops description and checklist bodies (adds has_description, checklist_count) — much smaller; use requirements_get for one task's full text. changes=true (needs updated_since) returns only tasks changed since then, archived ones included, plus deleted ids and server_time to pass as the next updated_since.",
     {
-      network_id: z.string().max(200).optional(),
-      seq: z.number().int().positive().optional().describe("short number (#N) of one task in this network"),
-      status: z.enum(["pool", "doing", "done"]).optional(),
-      project_id: z.string().max(200).optional(),
-      owner: z.string().max(210).optional(),
-      agent_owner: z.string().max(210).optional(),
-      updated_since: z.string().max(40).optional(),
-      external_ref: z.string().max(200).optional(),
-      include_archived: z.boolean().optional(),
-      parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
-      top_level: z.boolean().optional(), q: z.string().max(200).optional(), limit: z.number().int().min(1).max(1000).optional(), cursor: z.string().max(600).optional(),
-      view: z.enum(["full", "summary"]).optional().describe("summary = no description / checklist bodies (has_description, checklist_count instead)"),
-      changes: z.boolean().optional().describe("with updated_since: only tasks changed since then (archived included) + deleted ids + server_time"),
+      description: `List requirement tasks in your network. Defaults (MCP): view='summary' and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page, newest first — about 0.5 KB per task, so a page stays small. has_more + next_cursor → pass cursor for the next page. Summary rows drop description and checklist bodies (has_description, checklist_count instead); for full text read one task with requirements_get, or pass view='full' (several KB per task — keep limit small). Filters: seq (the per-network short number shown as #N), status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact label), updated_since (ISO), external_ref, parent_id / top_level, include_archived; q = search title / description / owner, agent and participant names / project name / tags (space-separated terms are ANDed). limit ≤ 1000. Each task carries children {total, done}. changes=true (needs updated_since) returns only tasks changed since then, archived ones included, plus deleted ids and server_time to pass as the next updated_since. Unknown parameters are rejected (-32602) with the list of valid ones.`,
+      // Strict: registerTool honours a constructed object's unknownKeys (server.tool() would strip them silently).
+      inputSchema: z.strictObject(reqListShape, {
+        error: (iss: any) => iss.code === "unrecognized_keys"
+          ? `unknown parameter(s): ${(iss.keys ?? []).join(", ")}; valid parameters: ${reqListKeys.join(", ")}`
+          : undefined,
+      }) as any,
     },
-    async (args) => {
+    async (args: any) => {
       const q = new URLSearchParams();
-      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id", "q", "limit", "cursor", "view"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "tag", "updated_since", "external_ref", "parent_id", "q", "limit", "cursor", "view"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      if (!q.has("view")) q.set("view", "summary");
+      if (!q.has("limit")) q.set("limit", String(REQ_LIST_MCP_DEFAULT_LIMIT));
       if (args.include_archived) q.set("include_archived", "1");
       if (args.top_level) q.set("top_level", "1");
       if (args.changes) q.set("changes", "1");
-      return requirementsCall("GET", `/api/requirements${q.size ? `?${q}` : ""}`, args.network_id);
+      return requirementsCall("GET", `/api/requirements?${q}`, args.network_id);
     },
   );