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

package/package.json

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

@@ -0,0 +1,48 @@
+// Hub 以某个节点的名义发给一个用户的一条通知(#462 登录失效、#464 定时任务卡住)。
+//
+// 走 user_inbox + /events/users/me 的 desktop_message —— 与 send_desktop_message 同一张表、同一条推送,
+// from_session = 节点别名,所以 App 把它显示在**与该节点的会话**里(主动消息)+ 未读角标 + 通知。不新增渠道。
+// 只发给一个人;他不在本网络了就不发。推送在写库之后:收到推送的 App 立刻回读得到这一行。
+
+import { db, uuidv4 } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { pushUserEvent } from "./push.js";
+
+export type AgentNotice = {
+  networkId: string;
+  userId: string;
+  /** 节点别名:通知出现在与它的会话里。 */
+  fromAlias: string;
+  kind: string;
+  title: string;
+  text: string;
+  severity?: "info" | "warning" | "error";
+  meta: Record<string, unknown>;
+  /** 消息 id 前缀(`dm_` 开头,与 App 的去重键同一套)。 */
+  idPrefix: string;
+};
+
+/** 返回 message_id;没发(收件人不在本网络)→ null。 */
+export function sendAgentNotice(n: AgentNotice): string | null {
+  if (!getUserNetworkRole(n.userId, n.networkId)) return null;
+  const messageId = `${n.idPrefix}${uuidv4()}`;
+  const severity = n.severity ?? "warning";
+  db.run(
+    `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+     ON CONFLICT(message_id) DO NOTHING`,
+    [messageId, n.networkId, n.userId, n.fromAlias, n.kind, n.title, n.text, severity, JSON.stringify(n.meta)],
+  );
+  pushUserEvent(n.networkId, n.userId, {
+    type: "desktop_message",
+    message_id: messageId,
+    kind: n.kind,
+    from: n.fromAlias,
+    title: n.title,
+    message: n.text,
+    severity,
+    created_at: new Date().toISOString(),
+    meta: n.meta,
+  });
+  return messageId;
+}

package/src/db.ts

@@ -1,6 +1,6 @@
-import { createAdapter, type DbAdapter } from "./db-adapter";
+import { createAdapter, type DbAdapter } from "./db-adapter"; import { withStatementHook } from "./status-read-cache"; // #431 写 sessions 的语句让 /api/status 缓存失效
 
-export const db: DbAdapter = createAdapter();
+export const db: DbAdapter = withStatementHook(createAdapter());
 
 // Schema
 db.exec(`

package/src/http-gzip.ts

@@ -56,7 +56,9 @@ function gzipCached(key: string | undefined, raw: () => Promise<Uint8Array>): Pr
   }
   return raw().then(bytes => {
     if (bytes.byteLength < GZIP_MIN_BYTES) return { raw: bytes, gz: null };
-    const gz = Bun.gzipSync(bytes);
+    // 可复用的正文(带键)压一次、存起来、反复发:压缩级别拉到 9 —— 多花的那点 CPU 只花一次,
+    // 而线上每次都少发 ~3%(#431 实测:旧节点别名解析读 29.6 KB → 28.6 KB)。不带键的照旧默认级别。
+    const gz = key ? Bun.gzipSync(bytes, { level: 9 }) : Bun.gzipSync(bytes);
     if (key) gzipCacheStats.misses++;
     if (key && gz.byteLength <= GZIP_CACHE_MAX_BYTES / 4) {
       gzipCache.set(key, gz);

package/src/model-auth-notify.ts

@@ -15,12 +15,11 @@
 //
 // 收件人 = 节点主人:上报令牌绑定的 nodes.owner_user_id(RFC-036,建节点时定死),没有绑定(老令牌)就取
 //   铸这个节点令牌的用户(api_tokens.user_id —— 新令牌里两者相同)。只发给这一个人;不在本网络了就不发。
-// 怎么送:user_inbox(与 send_desktop_message 同一张表、同一条 /events/users/me 推送),from_session = 节点别名,
-//   所以 App 把它显示在**与该节点的会话**里(主动消息)+ 未读角标 + 通知。不新增渠道。
+// 怎么送:agent-notice.ts(user_inbox + /events/users/me,from_session = 节点别名)。
 
-import { db, uuidv4 } from "./db.js";
+import { db } from "./db.js";
 import { getUserNetworkRole } from "./auth.js";
-import { pushUserEvent } from "./push.js";
+import { sendAgentNotice } from "./agent-notice.js";
 import { degradedLayers } from "./node-health-guard.js";
 import type { NodeHealth } from "./node-health-store.js";
 
@@ -104,26 +103,11 @@ export function noteModelAuthHealth(input: { networkId: string; alias: string; t
     if (prev === undefined && hasUnreadNotice(owner, networkId, alias)) return [];
 
     const { title, text } = modelAuthNoticeText(alias, state);
-    const messageId = `dm_auth_${uuidv4()}`;
-    const meta = { model_auth_notice: { alias, state } };
-    db.run(
-      `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json)
-       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'warning', ?8)
-       ON CONFLICT(message_id) DO NOTHING`,
-      [messageId, networkId, owner, alias, MODEL_AUTH_NOTICE_KIND, title, text, JSON.stringify(meta)],
-    );
-    // 推送在写库之后:收到推送的 App 立刻回读得到这一行。
-    pushUserEvent(networkId, owner, {
-      type: "desktop_message",
-      message_id: messageId,
-      kind: MODEL_AUTH_NOTICE_KIND,
-      from: alias,
-      title,
-      message: text,
-      severity: "warning",
-      created_at: new Date().toISOString(),
-      meta,
+    const sent = sendAgentNotice({
+      networkId, userId: owner, fromAlias: alias, kind: MODEL_AUTH_NOTICE_KIND, title, text,
+      meta: { model_auth_notice: { alias, state } }, idPrefix: "dm_auth_",
     });
+    if (!sent) return [];
     return [owner];
   } catch (e: any) {
     console.error(`[model-auth-notify] ${input.alias}: ${e?.message ?? e}`);

package/src/node-health-store.ts

@@ -34,7 +34,22 @@ export type NodeHealth = NonNullable<z.infer<typeof nodeHealthSchema>>;
 const store = new Map<string, { health: NodeHealth; at: number }>();
 const keyOf = (networkId: string | null | undefined, alias: string) => `${networkId ?? "default"}\0${alias}`;
 
+// #431 —— /api/status 的记忆化(status-read-cache.ts)按这两样判断正文还对不对:任何一次上报 → 版本 +1;
+// 任何一份报告过 TTL 的那一刻(degraded / health 字段会消失)→ 由 nodeHealthNextExpiryAt 给出的时刻失效。
+let version = 0;
+export function nodeHealthVersion(): number { return version; }
+/** 最早一份还没过期的报告的过期时刻(ms);一份都没有 → Infinity。 */
+export function nodeHealthNextExpiryAt(now = Date.now()): number {
+  let next = Infinity;
+  for (const v of store.values()) {
+    const at = v.at + NODE_HEALTH_TTL_MS;
+    if (at >= now && at < next) next = at;
+  }
+  return next;
+}
+
 export function recordNodeHealth(networkId: string | null | undefined, alias: string, health: NodeHealth, now = Date.now()): void {
+  version++;
   store.set(keyOf(networkId, alias), { health, at: now });
   // 有界:按 TTL 顺手清掉过期的,别让改过名/删掉的节点在内存里攒着。
   if (store.size > 256) {
@@ -54,4 +69,4 @@ export function readNodeHealth(
 }
 
 /** 测试用。 */
-export function clearNodeHealthStore(): void { store.clear(); }
+export function clearNodeHealthStore(): void { store.clear(); version++; }

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